-<!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>
-<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 >
-<!--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>
-
-<P>
-<H1 ALIGN="CENTER">SDCC Compiler User Guide</H1>
-<BR>
-
-<H2><A NAME="SECTION00010000000000000000">
-Contents</A>
-</H2>
-<!--Table of Contents-->
-
-<UL>
-<LI><A NAME="tex2html120"
- HREF="SDCCUdoc.html">1 Introduction</A>
-<UL>
-<LI><A NAME="tex2html121"
- HREF="#SECTION00021000000000000000">1.1 About SDCC</A>
-<LI><A NAME="tex2html122"
- HREF="#SECTION00022000000000000000">1.2 Open Source</A>
-<LI><A NAME="tex2html123"
- HREF="#SECTION00023000000000000000">1.3 System Requirements</A>
-<LI><A NAME="tex2html124"
- HREF="#SECTION00024000000000000000">1.4 Other Resources</A>
-</UL>
-<BR>
-<LI><A NAME="tex2html125"
- HREF="#SECTION00030000000000000000">2 Installation</A>
-<UL>
-<LI><A NAME="tex2html126"
- HREF="#SECTION00031000000000000000">2.1 Linux/Unix Installation</A>
-<LI><A NAME="tex2html127"
- HREF="#SECTION00032000000000000000">2.2 Windows Installation</A>
-<LI><A NAME="tex2html128"
- HREF="#SECTION00033000000000000000">2.3 Testing out the SDCC Compiler</A>
-<LI><A NAME="tex2html129"
- HREF="#SECTION00034000000000000000">2.4 Install Trouble-shooting</A>
-<LI><A NAME="tex2html130"
- HREF="#SECTION00035000000000000000">2.5 Additional Information for Windows Users</A>
-<LI><A NAME="tex2html131"
- HREF="#SECTION00036000000000000000">2.6 SDCC on Other Platforms</A>
-<LI><A NAME="tex2html132"
- HREF="#SECTION00037000000000000000">2.7 Advanced Install Options</A>
-<LI><A NAME="tex2html133"
- HREF="#SECTION00038000000000000000">2.8 Components of SDCC</A>
-</UL>
-<BR>
-<LI><A NAME="tex2html134"
- HREF="#SECTION00040000000000000000">3 Using SDCC</A>
-<UL>
-<LI><A NAME="tex2html135"
- HREF="#SECTION00041000000000000000">3.1 Compiling</A>
-<LI><A NAME="tex2html136"
- HREF="#SECTION00042000000000000000">3.2 Command Line Options</A>
-<LI><A NAME="tex2html137"
- HREF="#SECTION00043000000000000000">3.3 MCS51/DS390 Storage Class Language Extensions</A>
-<LI><A NAME="tex2html138"
- HREF="#SECTION00044000000000000000">3.4 Pointers</A>
-<LI><A NAME="tex2html139"
- HREF="#SECTION00045000000000000000">3.5 Parameters & Local Variables</A>
-<LI><A NAME="tex2html140"
- HREF="#SECTION00046000000000000000">3.6 Overlaying</A>
-<LI><A NAME="tex2html141"
- HREF="#SECTION00047000000000000000">3.7 Interrupt Service Routines</A>
-<LI><A NAME="tex2html142"
- HREF="#SECTION00048000000000000000">3.8 Critical Functions</A>
-<LI><A NAME="tex2html143"
- HREF="#SECTION00049000000000000000">3.9 Naked Functions</A>
-<LI><A NAME="tex2html144"
- HREF="#SECTION000410000000000000000">3.10 Functions using private banks</A>
-<LI><A NAME="tex2html145"
- HREF="#SECTION000411000000000000000">3.11 Absolute Addressing</A>
-<LI><A NAME="tex2html146"
- HREF="#SECTION000412000000000000000">3.12 Startup Code</A>
-<LI><A NAME="tex2html147"
- HREF="#SECTION000413000000000000000">3.13 Inline Assembler Code</A>
-<LI><A NAME="tex2html148"
- HREF="#SECTION000414000000000000000">3.14 int(16 bit) and long (32 bit ) Support</A>
-<LI><A NAME="tex2html149"
- HREF="#SECTION000415000000000000000">3.15 Floating Point Support</A>
-<LI><A NAME="tex2html150"
- HREF="#SECTION000416000000000000000">3.16 MCS51 Memory Models</A>
-<LI><A NAME="tex2html151"
- HREF="#SECTION000417000000000000000">3.17 Flat 24 bit Addressing Model</A>
-<LI><A NAME="tex2html152"
- HREF="#SECTION000418000000000000000">3.18 Defines Created by the Compiler</A>
-</UL>
-<BR>
-<LI><A NAME="tex2html153"
- HREF="#SECTION00050000000000000000">4 SDCC Technical Data</A>
-<UL>
-<LI><A NAME="tex2html154"
- HREF="#SECTION00051000000000000000">4.1 Optimizations</A>
-<LI><A NAME="tex2html155"
- HREF="#SECTION00052000000000000000">4.2 Pragmas</A>
-<LI><A NAME="tex2html156"
- HREF="#SECTION00053000000000000000">4.3 Library Routines</A>
-<LI><A NAME="tex2html157"
- HREF="#SECTION00054000000000000000">4.4 Interfacing with Assembly Routines</A>
-<LI><A NAME="tex2html158"
- HREF="#SECTION00055000000000000000">4.5 Global Registers used for Parameter Passing</A>
-<LI><A NAME="tex2html159"
- HREF="#SECTION00056000000000000000">4.6 External Stack</A>
-<LI><A NAME="tex2html160"
- HREF="#SECTION00057000000000000000">4.7 ANSI-Compliance</A>
-<LI><A NAME="tex2html161"
- HREF="#SECTION00058000000000000000">4.8 Cyclomatic Complexity</A>
-</UL>
-<BR>
-<LI><A NAME="tex2html162"
- HREF="#SECTION00060000000000000000">5 TIPS</A>
-<LI><A NAME="tex2html163"
- HREF="#SECTION00070000000000000000">6 Retargetting for other MCUs.</A>
-<LI><A NAME="tex2html164"
- HREF="#SECTION00080000000000000000">7 SDCDB - Source Level Debugger</A>
-<UL>
-<LI><A NAME="tex2html165"
- HREF="#SECTION00081000000000000000">7.1 Compiling for Debugging</A>
-<LI><A NAME="tex2html166"
- HREF="#SECTION00082000000000000000">7.2 How the Debugger Works</A>
-<LI><A NAME="tex2html167"
- HREF="#SECTION00083000000000000000">7.3 Starting the Debugger</A>
-<LI><A NAME="tex2html168"
- HREF="#SECTION00084000000000000000">7.4 Command Line Options.</A>
-<LI><A NAME="tex2html169"
- HREF="#SECTION00085000000000000000">7.5 Debugger Commands.</A>
-<LI><A NAME="tex2html170"
- HREF="#SECTION00086000000000000000">7.6 Interfacing with XEmacs.</A>
-</UL>
-<BR>
-<LI><A NAME="tex2html171"
- HREF="#SECTION00090000000000000000">8 Other Processors</A>
-<UL>
-<LI><A NAME="tex2html172"
- HREF="#SECTION00091000000000000000">8.1 The Z80 and gbz80 port</A>
-</UL>
-<BR>
-<LI><A NAME="tex2html173"
- HREF="#SECTION000100000000000000000">9 Support</A>
-<UL>
-<LI><A NAME="tex2html174"
- HREF="#SECTION000101000000000000000">9.1 Reporting Bugs</A>
-<LI><A NAME="tex2html175"
- HREF="#SECTION000102000000000000000">9.2 Acknowledgments</A>
-</UL>
-<BR>
-<LI><A NAME="tex2html176"
- HREF="#SECTION000110000000000000000">About this document ...</A>
-</UL>
-<!--End of Table of Contents-->
-
-<P>
-
-<H1><A NAME="SECTION00020000000000000000">
-1 Introduction</A>
-</H1>
-
-<P>
-
-<H2><A NAME="SECTION00021000000000000000">
-1.1 About SDCC</A>
-</H2>
-
-<P>
-<B>SDCC</B> is a Free ware, retargettable, optimizing ANSI-C compiler
-by <B>Sandeep Dutta</B> designed for 8 bit Microprocessors. The
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
+ "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<meta name="GENERATOR" content="TtH 3.01">
+ <style type="text/css"><!--
+ td div.comp { margin-top: -0.6ex; margin-bottom: -1ex;}
+ td div.comb { margin-top: -0.6ex; margin-bottom: -.6ex;}
+ td div.hrcomp { line-height: 0.9; margin-top: -0.8ex; margin-bottom: -1ex;}
+ td div.norm {line-height:normal;}
+ span.roman {font-family: serif; font-style: normal; font-weight: normal;}
+ span.overacc2 {position: relative; left: .8em; top: -1.2ex;}
+ span.overacc1 {position: relative; left: .6em; top: -1.2ex;} --></style>
+
+
+<title> lSDCC Compiler User Guide</title>
+
+<h1 align="center">lSDCC Compiler User Guide </h1>
+
+<p>
+ <h2><a name="tth_sEc1">
+1</a> Introduction</h2>
+
+<p>
+ <h3><a name="tth_sEc1.1">
+1.1</a> About SDCC</h3>
+
+<p>
+<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
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
+does a host of standard optimizations like <em>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
+statements.</em> 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
-dependent. Supported data-types are <I>char (8 bits, 1 byte), short
-and int (16 bits, 2 bytes ), long (32 bit, 4 bytes)</I> and <I>float
-(4 byte IEEE).</I> The compiler also allows <I>inline assembler code</I>
+dependent. Supported data-types are <em>char (8 bits, 1 byte), short
+and int (16 bits, 2 bytes), long (32 bit, 4 bytes)</em> and <em>float
+(4 byte IEEE).</em> The compiler also allows <em>inline assembler code</em>
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 needed. 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>
+The latest version can be downloaded from <b><a href="http://sdcc.sourceforge.net/"><tt>http://sdcc.sourceforge.net/</tt></a>
+.</b>
-<P>
+<p>
+ <h3><a name="tth_sEc1.2">
+1.2</a> Open Source</h3>
-<H2><A NAME="SECTION00022000000000000000">
-1.2 Open Source</A>
-</H2>
-
-<P>
-All packages used in this compiler system are <I>opensource</I>(freeware);
+<p>
+All packages used in this compiler system are <em>opensource</em> (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).
+using a freeware word processor (LY<!--hbox-->X).
-<P>
+<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)
else to use, share and improve what you give them. Help stamp out
software-hoarding!
-<P>
+<p>
+ <h3><a name="tth_sEc1.3">
+1.3</a> Typographic conventions</h3>
+
+<p>
+Throughout this manual, we will use the following convention. Commands
+you have to type in are printed in <font face="helvetica"><b>"sans
+serif"</b></font><font face="helvetica">.</font> Code samples are printed in <tt>typewriter
+font.</tt> Interesting items and new terms are printed in <em>italicised
+type.</em>
-<H2><A NAME="SECTION00023000000000000000">
-1.3 System Requirements</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc1.4">
+1.4</a> System Requirements</h3>
-<P>
+<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
You should have some experience with command line tools and compiler
use.
-<P>
-
-<H2><A NAME="SECTION00024000000000000000">
-1.4 Other Resources</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc1.5">
+1.5</a> Other Resources</h3>
-<P>
-The SDCC home page at http://sdcc.sourceforge.net/ is a great
+<p>
+The SDCC home page at <a href="http://sdcc.sourceforge.net/"><tt>http://sdcc.sourceforge.net/</tt></a> 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
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>
+on cvs.sdcc.sourceforge.net.
+
+<p>
+ <h2><a name="tth_sEc2">
+2</a> Installation</h2>
+
+<p>
+ <h3><a name="tth_sEc2.1">
+2.1</a> Linux/Unix Installation</h3>
+
+<p>
+
+<ol type="1"><p>
+<li> Download the source package, it will be named something like sdcc-2.x.x.tgz.</li>
+<p>
+<li> Bring up a command line terminal, such as xterm.</li>
+<p>
+<li> Unpack the file using a command like: <font face="helvetica"><b>"tar
+-xzf sdcc-2.x.x.tgz"</b></font>, this will create a sub-directory
+called sdcc with all of the sources.</li>
+<p>
+<li> Change directory into the main SDCC directory, for example type: <font face="helvetica"><b>"cd
+sdcc"</b></font><font face="helvetica">.</font></li>
+<p>
+<li> Type <font face="helvetica"><b>"./configure"</b></font>. This configures
+the package for compilation on your system.</li>
+<p>
+<li> Type <font face="helvetica"><b>"make"</b></font>. All of the source
+packages will compile, this can take a while.</li>
+<p>
+<li> Type <font face="helvetica"><b>"make install"</b></font> as root. This
+copies the binary executables to the install directories.</li>
+</ol>
+
+<p>
+ <h3><a name="tth_sEc2.2">
+2.2</a> Windows Installation</h3>
+
+<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
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>.
+<p>
+ <h4><a name="tth_sEc2.2.1">
+2.2.1</a> Windows Install Using a Binary Package</h4>
+
+<p>
+
+<ol type="1"><p>
+<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:usrlocalbin
+for the executables, c:usrlocalsharesdccinclude
+and c:usrlocalsharesdcclib
+for the include and libraries.</li>
+<p>
+<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:usrlocalbin;%PATH%</li>
+<p>
+<li> When you compile with sdcc, you may need to specify the location of
+the lib and include folders. For example, sdcc -I c:usrlocalsharesdccinclude
+-L c:usrlocalsharesdcclibsmall
+test.c</li>
+</ol>
+
+<p>
+ <h4><a name="tth_sEc2.2.2">
+2.2.2</a> Windows Install Using Cygwin</h4>
+
+<p>
+
+<ol type="1"><p>
+<li> Download and install the cygwin package from the redhat site<a href="http://sources.redhat.com/cygwin/"><tt>http://sources.redhat.com/cygwin/</tt></a>.
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>
+then automates downloading and installing selected parts of the package
+(a large 80M byte sized dowload for the whole thing).</li>
+<p>
+<li> Bring up a Unix/Bash command line terminal from the Cygwin menu.</li>
+<p>
+<li> Follow the instructions in the preceding Linux/Unix installation section.</li>
+</ol>
+
+<p>
+ <h3><a name="tth_sEc2.3">
+2.3</a> Testing out the SDCC Compiler</h3>
+
+<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>
+is to see if it runs. Type <font face="helvetica"><b>"sdcc -version"</b></font>
+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.<br />
+<br />
SDCC binaries are commonly installed in a directory arrangement like
-this:
-<BR>
-<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>
-<BR>
-<BR>
+this:<br />
+
+<p>
+
+<table border="1">
+<tr><td>/usr/local/bin</td><td>Holds executables(sdcc, s51, aslink, ...)</td></tr><tr><td>
+<tr><td>/usr/local/share/sdcc/lib </td><td>Holds common C libraries</td></tr>
+<tr><td>/usr/local/share/sdcc/include</td><td>Holds common C header files</td></tr></table>
+<br />
+<br />
Make sure the compiler works on a very simple example. Type in the
-following test.c program using your favorite editor:
-<BR>
-<BR><TT>main()</TT>
-<BR><TT>{ </TT>
-
-<P>
-<TT>int i;</TT>
-
-<P>
-<TT>i = 0;</TT>
-
-<P>
-<TT>i += 10;</TT>
-<BR><TT>}</TT>
-<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 directory (see the Install trouble-shooting
-section for suggestions).
-
-<P>
+following test.c program using your favorite editor:<br />
+<em></em><br />
+Compile this using the following command: <font face="helvetica"><b>"sdcc
+-c test.c"</b></font> 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.<br />
+<br />
+The next step is to try it with the linker. Type in <font face="helvetica"><b>"sdcc
+test.c"</b></font>. 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 directory
+(see the Install trouble-shooting section for suggestions).<br />
+<br />
The final test is to ensure sdcc can use the standard header files
-and libraries. Edit test.c and change it to the following:
-<BR>
-<BR><TT>#include <string.h></TT>
-<BR><TT>main()</TT>
-<BR><TT>{ </TT>
-
-<P>
-<TT>char str1[10];</TT>
-
-<P>
-<TT>strcpy(str1, ``testing'');</TT>
-<BR>
-<BR><TT>}</TT>
-<BR>
-<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
+and libraries. Edit test.c and change it to the following:<br />
+<br />
+#include <string.h><br />
+main() {<br />
+<tt>char str1[10];</tt> <br />
+<tt> strcpy(str1, "testing");</tt> <br />
+<tt>}</tt> <br />
+<tt></tt> <br />
+Compile this by typing <font face="helvetica"><b>"sdcc test.c"</b></font>.
+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="tth_sEc2.4">
+2.4</a> Install Trouble-shooting</h3>
-<P>
+<p>
+ <h4><a name="tth_sEc2.4.1">
+2.4.1</a> SDCC cannot find libraries or header files.</h4>
-<H3><A NAME="SECTION00034100000000000000">
-2.4.1 SDCC cannot find libraries or header files.</A>
-</H3>
-
-<P>
+<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>
+this: <font face="helvetica"><b>"sdcc -L /usr/local/sdcc/lib/small
+-I /usr/local/sdcc/include test.c"</b></font>.
-<H3><A NAME="SECTION00034200000000000000">
-2.4.2 SDCC does not compile correctly.</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc2.4.2">
+2.4.2</a> SDCC does not compile correctly.</h4>
-<P>
+<p>
A thing to try is starting from scratch by unpacking the .tgz source
-package again in an empty directory. Confure it again and build like:
-
-<P>
-``make 2SPMamp;>1 | tee make.log''
-
-<P>
+package again in an empty directory. Confure it again and build like:<br />
+<br />
+<font face="helvetica"><b>make 2&>1 | tee make.log</b></font><br />
+<br />
After this you can review the make.log file to locate the problem.
Or a relevant part of this 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>
+ <h4><a name="tth_sEc2.4.3">
+2.4.3</a> What the ''./configure'' does</h4>
-<P>
-The ``./configure'' command is a script that analyzes your system
+<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>
+ <h4><a name="tth_sEc2.4.4">
+2.4.4</a> What the ''make'' does.</h4>
-<P>
+<p>
This runs the GNU make tool, which automatically compiles all the
source packages into the final installed binary executables.
-<P>
+<p>
+ <h4><a name="tth_sEc2.4.5">
+2.4.5</a> What the ''make install'' command does.</h4>
-<H3><A NAME="SECTION00034500000000000000">
-2.4.5 What the ``make install'' command does.</A>
-</H3>
-
-<P>
+<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>
+ <h3><a name="tth_sEc2.5">
+2.5</a> Additional Information for Windows Users</h3>
-<P>
+<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
a pre-compiled Windows binary package. There are various trade-offs
between each of these methods.
-<P>
+<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
+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>
+ <h4><a name="tth_sEc2.5.1">
+2.5.1</a> Getting started with Cygwin</h4>
-<P>
-SDCC is typically distributed as a tarred/gzipped file(.tgz). This
+<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
+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''.
+commands and so on. The change directory command is <font face="helvetica"><b>``cd''</b></font>,
+the move command is <font face="helvetica"><b>``mv''</b></font>. To print the current
+working directory, type <font face="helvetica"><b>``pwd''</b></font>. To make a directory,
+use <font face="helvetica"><b>``mkdir''</b></font>.
-<P>
+<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.
+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>
+<p>
+ <h4><a name="tth_sEc2.5.2">
+2.5.2</a> Running SDCC as Native Compiled Executables</h4>
-<H3><A NAME="SECTION00035200000000000000">
-2.5.2 Running SDCC as Native Compiled Executables</A>
-</H3>
-
-<P>
+<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.
+command line like this: <font face="helvetica"><b>"sdcc -L c:usrlocalsdcclibsmall
+-I c:usrlocalsdccinclude
+test.c"</b></font> if you are running outside of a Unix bash shell.
-<P>
+<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>
+the Borland 32-bit compiler you would run <font face="helvetica"><b>"make
+-f Makefile.bcc"</b></font>. A command line version of the Borland
+32-bit compiler can be downloaded from the Inprise web site.
-<H2><A NAME="SECTION00036000000000000000">
-2.6 SDCC on Other Platforms</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc2.6">
+2.6</a> SDCC on Other Platforms</h3>
-<P>
+<p>
-<UL>
-<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
+<ul><p>
+<li> <b>FreeBSD and other non-GNU Unixes</b> - Make sure the GNU make
+is installed as the default make tool.</li>
+<p>
+<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>
+can be compiled and run on your system.</li>
+</ul>
-<H2><A NAME="SECTION00037000000000000000">
-2.7 Advanced Install Options</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc2.7">
+2.7</a> Advanced Install Options</h3>
-<P>
+<p>
The ``configure'' command has several options. The most commonly
-used option is -prefix=<directory name>, where <directory name> is
+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>
+following directory structure under the <directory name> specified
+(if they do not already exist). <br />
+<br />
+bin/ - binary exectables (add to PATH environment variable)<br />
+bin/share/<br />
+bin/share/sdcc/include/ - include header files<br />
+bin/share/sdcc/lib/<br />
+bin/share/sdcc/lib/small/ - Object & library files for small model
+library<br />
+bin/share/sdcc/lib/large/ - Object & library files for large model
+library<br />
+bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390 library<br />
+<br />
+The command <font face="helvetica"><b>''./configure -prefix=/usr/local''</b></font>
will configure the compiler to be installed in directory /usr/local/bin.
-<P>
+<p>
+ <h3><a name="tth_sEc2.8">
+2.8</a> Components of SDCC</h3>
-<H2><A NAME="SECTION00038000000000000000">
-2.8 Components of SDCC</A>
-</H2>
-
-<P>
+<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
from various developers are included and may have their own sets of
documentation.
-<P>
+<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>
+programs:<br />
+<br />
+<b>sdcc</b> - The compiler.<br />
+<b>sdcpp</b> - The C preprocessor.<br />
+<b>asx8051</b> - The assembler for 8051 type processors.<br />
+<b>as-z80, as-gbz80</b> - The Z80 and GameBoy Z80 assemblers.<br />
+<b>aslink</b> -The linker for 8051 type processors.<br />
+<b>link-z80, link-gbz80</b> - The Z80 and GameBoy Z80 linkers.<br />
+<b>s51</b> - The ucSim 8051 simulator.<br />
+<b>sdcdb</b> - The source debugger.<br />
+<b>packihx</b> - A tool to pack Intel hex files.<br />
+<br />
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>
+ <h4><a name="tth_sEc2.8.1">
+2.8.1</a> sdcc - The Compiler</h4>
-<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>
-
-<H3><A NAME="SECTION00038300000000000000">
-2.8.3 SDCC - The compiler</A>
-</H3>
-
-<P>
+<p>
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>
-
-<H3><A NAME="SECTION00038400000000000000">
-2.8.4 S51 - Simulator</A>
-</H3>
+invokes the assembler and linkage editor.
-<P>
-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>
+ <h4><a name="tth_sEc2.8.2">
+2.8.2</a> sdcpp (C-Preprocessor)</h4>
-<P>
+<p>
+The preprocessor 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.
-<H3><A NAME="SECTION00038500000000000000">
-2.8.5 SDCDB - Source Level Debugger</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc2.8.3">
+2.8.3</a> asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 (The Assemblers
+and Linkage Editors)</h4>
-<P>
-SDCDB is the companion source level debugger. The current version
+<p>
+This is retargettable assembler & linkage editor, it was developed
+by Alan Baldwin. John Hartman created the version for 8051, and I
+(Sandeep) have made some enhancements and bug fixes for it to work
+properly with the SDCC.
+
+<p>
+ <h4><a name="tth_sEc2.8.4">
+2.8.4</a> s51 - Simulator</h4>
+
+<p>
+S51 is a freeware, opensource simulator developed by Daniel Drotos
+(<a href="mailto:drdani@mazsola.iit.uni-miskolc.hu"><tt>mailto:drdani@mazsola.iit.uni-miskolc.hu</tt></a>). The simulator is
+built as part of the build process. For more information visit Daniel's
+website at: <a href="http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51"><tt>http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51</tt></a>
+.
+
+<p>
+ <h4><a name="tth_sEc2.8.5">
+2.8.5</a> sdcdb - Source Level Debugger</h4>
+
+<p>
+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>
-
-<H1><A NAME="SECTION00040000000000000000">
-3 Using SDCC</A>
-</H1>
+<p>
+ <h2><a name="tth_sEc3">
+3</a> Using SDCC</h2>
-<P>
+<p>
+ <h3><a name="tth_sEc3.1">
+3.1</a> Compiling</h3>
-<H2><A NAME="SECTION00041000000000000000">
-3.1 Compiling</A>
-</H2>
+<p>
+ <h4><a name="tth_sEc3.1.1">
+3.1.1</a> Single Source File Projects</h4>
-<P>
-
-<H3><A NAME="SECTION00041100000000000000">
-3.1.1 Single Source File Projects</A>
-</H3>
-
-<P>
+<p>
For single source file 8051 projects the process is very simple. Compile
-your programs with the following command
-
-<P>
-<FONT SIZE="-1">sdcc sourcefile.c</FONT>
-<P>
-
-
-<P>
-The above command will compile ,assemble and link your source file.
-Output files are as follows.
-
-<P>
+your programs with the following command <font face="helvetica"><b>"sdcc
+sourcefile.c".</b></font> This will compile, assemble and link your
+source file. Output files are as follows<br />
-<UL>
-<LI><FONT SIZE="-1">sourcefile.asm - Assembler source file created by the
-compiler</FONT>
-<P>
+<p>
+sourcefile.asm - Assembler source file created by the compiler
-</LI>
-<LI><FONT SIZE="-1">sourcefile.lst - Assembler listing file created by
-the Assembler</FONT>
-<P>
+<p>
+sourcefile.lst - Assembler listing file created by the Assembler
-</LI>
-<LI><FONT SIZE="-1">sourcefile.rst - Assembler listing file updated with
-linkedit information , created by linkage editor</FONT>
-<P>
+<p>
+sourcefile.rst - Assembler listing file updated with linkedit information,
+created by linkage editor
-</LI>
-<LI><FONT SIZE="-1">sourcefile.sym - symbol listing for the sourcefile,
-created by the assembler.</FONT>
-<P>
+<p>
+sourcefile.sym - symbol listing for the sourcefile, created by the
+assembler.
-</LI>
-<LI><FONT SIZE="-1">sourcefile.rel - Object file created by the assembler,
-input to Linkage editor.</FONT>
-<P>
+<p>
+sourcefile.rel - Object file created by the assembler, input to Linkage
+editor.
-</LI>
-<LI><FONT SIZE="-1">sourcefile.map - The memory map for the load module,
-created by the Linker.</FONT>
-<P>
+<p>
+sourcefile.map - The memory map for the load module, created by the
+Linker.
-</LI>
-<LI><FONT SIZE="-1">sourcefile.ihx - The load module in Intel hex format
-(you can select the Motorola S19 format with -out-fmt-s19)</FONT>
-<P>
+<p>
+sourcefile.ihx - The load module in Intel hex format (you can select
+the Motorola S19 format with -out-fmt-s19)
-</LI>
-<LI>sourcefile.cdb - An optional file (with -debug) containing debug
+<p>
+sourcefile.cdb - An optional file (with -debug) containing debug
information.
-</LI>
-</UL>
-<P>
+<p>
+ <h4><a name="tth_sEc3.1.2">
+3.1.2</a> Projects with Multiple Source Files</h4>
-<H3><A NAME="SECTION00041200000000000000">
-3.1.2 Projects with Multiple Source Files</A>
-</H3>
-
-<P>
+<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>
-
-
-<P>
-<FONT SIZE="-1">foo2.c (contains some more functions)</FONT>
-<P>
-
-
-<P>
-<FONT SIZE="-1">foomain.c (contains more functions and the function
-main)</FONT>
-<P>
-
-
-<P>
-The first two files will need to be compiled separately with the commands
-
-<P>
-<FONT SIZE="-1">sdcc -c foo1.c</FONT>
-<P>
-
-
-<P>
-<FONT SIZE="-1">sdcc -c foo2.c</FONT>
-<P>
-
-
-<P>
-Then compile the source file containing main and link the other files
-together with the following command.
-
-<P>
-<FONT SIZE="-1">sdcc foomain.c foo1.rel foo2.rel</FONT>
-<P>
-
-
-<P>
-Alternatively <I>foomain.c</I> can be separately compiled as well
-
-<P>
-<FONT SIZE="-1">sdcc -c foomain.c </FONT>
-<P>
-
-
-<P>
-<FONT SIZE="-1">sdcc foomain.rel foo1.rel foo2.rel</FONT>
-<P>
-
+that you have a project containing the following files:<br />
+<br />
+foo1.c (contains some functions)<br />
+foo2.c (contains some more functions)<br />
+foomain.c (contains more functions and the function main)<br />
+<font size="-2"></font><br />
+The first two files will need to be compiled separately with the commands:
+<font size="-2"></font><br />
+<br />
+<font face="helvetica"><b>sdcc -c foo1.c</b></font><font size="-2"></font><br />
+<font face="helvetica"><b>sdcc -c foo2.c</b></font><br />
+<br />
+Then compile the source file containing the <em>main()</em> function
+and link the files together with the following command: <br />
+<br />
+<font face="helvetica"><b>sdcc foomain.c foo1.rel foo2.rel</b></font><br />
+<br />
+Alternatively, <em>foomain.c</em> can be separately compiled as well:
+<font face="helvetica"><b></b></font><br />
+<font face="helvetica"><b></b></font><br />
+<font face="helvetica"><b>sdcc -c foomain.c</b></font><br />
+<font face="helvetica"><b>sdcc foomain.rel foo1.rel foo2.rel</b></font><br />
+<font face="helvetica"><b></b></font><br />
+The file containing the <em>main()</em> function <em></em> <font size="-2">MUST</font>
+be the <font size="-2">FIRST</font> file specified in the command line, since the
+linkage editor processes file in the order they are presented to it.
+
+<p>
+ <h4><a name="tth_sEc3.1.3">
+3.1.3</a> Projects with Additional Libraries</h4>
+
+<p>
+Some reusable routines may be compiled into a library, see the documentation
+for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
+for how to create a <em>.lib</em> library file. Libraries created in
+this manner can be included in the command line. Make sure you include
+the -L <library-path> option to tell the linker where to look for
+these files if they are not in the current directory. Here is an example,
+assuming you have the source file <em>foomain.c</em> and a library <em>foolib.lib</em>
+in the directory <em>mylib</em> (if that is not the same as your current
+project):<br />
+<br />
+<font face="helvetica"><b>sdcc foomain.c foolib.lib -L mylib</b></font><br />
+<font face="helvetica"><b></b></font><br />
+Note here that <em>mylib</em> must be an absolute path name.<br />
+<br />
+The most efficient way to use libraries is to keep seperate modules
+in seperate source files. The lib file now should name all the modules.rel
+files. For an example see the standard library file <em>libsdcc.lib</em>
+in the directory <installdir>/share/lib/small.
+
+<p>
+ <h3><a name="tth_sEc3.2">
+3.2</a> Command Line Options</h3>
+
+<p>
+ <h4><a name="tth_sEc3.2.1">
+3.2.1</a> Processor Selection Options</h4>
+
+<p>
+
+<dl compact="compact">
+
+
+
+
+ <dt><b><b>-mmcs51</b></b></dt>
+ <dd>Generate code for the MCS51 (8051) family of processors.
+This is the default processor target.</dd>
+ <dt><b><b>-mds390</b></b></dt>
+ <dd>Generate code for the DS80C390 processor.</dd>
+ <dt><b><b>-mz80</b></b></dt>
+ <dd>Generate code for the Z80 family of processors.</dd>
+ <dt><b><b>-mgbz80</b></b></dt>
+ <dd>Generate code for the GameBoy Z80 processor.</dd>
+ <dt><b><b>-mavr</b></b></dt>
+ <dd>Generate code for the Atmel AVR processor(In development,
+not complete).</dd>
+ <dt><b><b>-mpic14</b></b></dt>
+ <dd>Generate code for the PIC 14-bit processors(In development,
+not complete).</dd>
+ <dt><b><b>-mtlcs900h</b></b></dt>
+ <dd>Generate code for the Toshiba TLCS-900H processor(In
+development, not complete).
+</dd>
+</dl>
+
+<p>
+ <h4><a name="tth_sEc3.2.2">
+3.2.2</a> Preprocessor Options</h4>
+
+<p>
+
+<dl compact="compact">
+
+
+
+
+ <dt><b><b>-I<path></b></b></dt>
+ <dd>The additional location where the pre processor
+will look for <..h> or ``..h'' files.</dd>
+ <dt><b><b>-D<macro[=value]></b></b></dt>
+ <dd>Command line definition of macros.
+Passed to the pre processor.</dd>
+ <dt><b><b>-M</b></b></dt>
+ <dd>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'.</dd>
+ <dt><b><b>-C</b></b></dt>
+ <dd>Tell the preprocessor not to discard comments. Used with
+the `-E' option.</dd>
+ <dt><b><b>-MM</b></b></dt>
+ <dd>Like `-M' but the output mentions only the user header
+files included with `#include ``file"'. System header
+files included with `#include <file>' are omitted.</dd>
+ <dt><b><b>-Aquestion(answer)</b></b></dt>
+ <dd>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.</dd>
+ <dt><b><b>-Aquestion</b></b></dt>
+ <dd>(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.</dd>
+ <dt><b><b>-Umacro</b></b></dt>
+ <dd>Undefine macro macro. `-U' options are evaluated
+after all `-D' options, but before any `-include' and `-imacros' options.</dd>
+ <dt><b><b>-dM</b></b></dt>
+ <dd>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.</dd>
+ <dt><b><b>-dD</b></b></dt>
+ <dd>Tell the preprocessor to pass all macro definitions
+into the output, in their proper sequence in the rest of the output.</dd>
+ <dt><b><b>-dN</b></b></dt>
+ <dd>Like `-dD' except that the macro arguments and contents
+are omitted. Only `#define name' is included in the output.
+</dd>
+</dl>
-<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>
+ <h4><a name="tth_sEc3.2.3">
+3.2.3</a> Linker Options</h4>
-<P>
+<p>
-<H3><A NAME="SECTION00041300000000000000">
-3.1.3 Projects with Additional Libraries</A>
-</H3>
+<dl compact="compact">
-<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>' (if that is not the same as your current
-project).
-
-<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 Preprocessor Options</A>
-</H3>
-
-<P>
-
-<UL>
-<LI>[<B>-I<path></B>]The additional location where the pre processor
-will look for <..h> or ``..h'' files.
-</LI>
-<LI>[<B>-D<macro[=value]></B>]Command line definition of macros.
-Passed to the pre processor.
-</LI>
-<LI>[<B>-compile-only(-c)</B>] will compile and assemble the source,
-but will not call the linkage editor.
-</LI>
-</UL>
-<P>
-
-<H3><A NAME="SECTION00042300000000000000">
-3.2.3 Linker Options</A>
-</H3>
-
-<P>
-<B>-lib-path(-L)</B> <absolute path to additional libraries> This
+
+
+
+ <dt><b><b>-L -lib-path</b></b></dt>
+ <dd><absolute path to additional libraries> This
option is passed to the linkage editor's 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.
-
-<P>
-<B>-xram-loc</B><Value> The start location of the external ram,
+more details.</dd>
+ <dt><b><b>-xram-loc</b><Value></b></dt>
+ <dd>The start location of the external ram,
default value is 0. The value entered can be in Hexadecimal or Decimal
-format, e.g.: -xram-loc 0x8000 or -xram-loc 32768.
-
-<P>
-
-<UL>
-<LI>[<B>-code-loc</B><Value>]The start location of the code segment
-, default value 0. Note when this option is used the interrupt vector
+format, e.g.: -xram-loc 0x8000 or -xram-loc 32768.</dd>
+ <dt><b><b>-code-loc</b><Value></b></dt>
+ <dd>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, e.g.: -code-loc 0x8000 or -code-loc
-32768.
-</LI>
-<LI>[<B>-stack-loc</B><Value>]The initial value of the stack pointer.
+32768.</dd>
+ <dt><b><b>-stack-loc</b><Value></b></dt>
+ <dd>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.
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>-stack-after-data</B>]This option will cause the stack to be
-located in the internal ram after the data segment.
-</LI>
-<LI>[<B>-data-loc</B><Value>]The start location of the internal ram
+to -stack-after-data)</dd>
+ <dt><b><b>-stack-after-data</b></b></dt>
+ <dd>This option will cause the stack to be
+located in the internal ram after the data segment.</dd>
+ <dt><b><b>-data-loc</b><Value></b></dt>
+ <dd>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>-idata-loc</B><Value>]The start location of the indirectly
+Hexadecimal or Decimal format, eg. -data-loc 0x20 or -data-loc 32.</dd>
+ <dt><b><b>-idata-loc</b><Value></b></dt>
+ <dd>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>
-</UL>
-<P>
+136.</dd>
+ <dt><b><b>-out-fmt-ihx</b></b></dt>
+ <dd>The linker output (final object code) is in
+Intel Hex format. (This is the default option).</dd>
+ <dt><b><b>-out-fmt-s19</b></b></dt>
+ <dd>The linker output (final object code) is in
+Motorola S19 format.
+</dd>
+</dl>
+
+<p>
+ <h4><a name="tth_sEc3.2.4">
+3.2.4</a> MCS51 Options</h4>
-<H3><A NAME="SECTION00042400000000000000">
-3.2.4 MCS51 Options</A>
-</H3>
+<p>
-<P>
+<dl compact="compact">
-<UL>
-<LI>[<B>-model-large</B>]Generate code for Large model programs see
+
+
+
+ <dt><b><b>-model-large</b></b></dt>
+ <dd>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>-model-small</B>]Generate code for Small Model programs see
+addition the standard library routines are compiled with small model,
+they will need to be recompiled.</dd>
+ <dt><b><b>-model-small</b></b></dt>
+ <dd>Generate code for Small Model programs see
section Memory Models for more details. This is the default model.
-</LI>
-<LI>[<B>-stack-auto</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>-xstack</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="SECTION00042500000000000000">
-3.2.5 Optimization Options</A>
-</H3>
-
-<P>
-
-<UL>
-<LI>[<B>-nogcse</B>]Will not do global subexpression elimination, this
+</dd>
+</dl>
+
+<p>
+ <h4><a name="tth_sEc3.2.5">
+3.2.5</a> DS390 Options</h4>
+
+<p>
+
+<dl compact="compact">
+
+
+
+
+ <dt><b><b>-model-flat24</b></b></dt>
+ <dd>Generate 24-bit flat mode code. This is the
+one and only that the ds390 code generator supports right now and
+is default when using <em>-mds390</em>. See section Memory Models for
+more details.</dd>
+ <dt><b><b>-stack-10bit</b></b></dt>
+ <dd>Generate code for the 10 bit stack mode of
+the Dallas DS80C390 part. This is the one and only that the ds390
+code generator supports right now and is default when using <em>-mds390</em>.
+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 will
+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 <em>-stack-auto</em> option,
+but that has not been tested. It is incompatible with the <em>-xstack</em>
+option. It also only makes sense if the processor is in 24 bit contiguous
+addressing mode (see the <em>-model-flat24 option</em>).
+</dd>
+</dl>
+
+<p>
+ <h4><a name="tth_sEc3.2.6">
+3.2.6</a> Optimization Options</h4>
+
+<p>
+
+<dl compact="compact">
+
+
+
+
+ <dt><b><b>-nogcse</b></b></dt>
+ <dd>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>-noinvariant</B>]Will not do loop invariant optimizations,
+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.</dd>
+ <dt><b><b>-noinvariant</b></b></dt>
+ <dd>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>-noinduction</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>-nojtbound</B>] Will not generate boundary condition check
+Invariants.It recommended that this option NOT be used, #pragma NOINVARIANT
+can be used to turn off invariant optimizations for a given function
+only.</dd>
+ <dt><b><b>-noinduction</b></b></dt>
+ <dd>Will not do loop induction optimizations,
+see section strength reduction for more details.It is recommended
+that this option is NOT used, #pragma NOINDUCTION can be used to
+turn off induction optimizations for a given function only.</dd>
+ <dt><b><b>-nojtbound</b></b></dt>
+ <dd> 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>-noloopreverse</B>]Will not do loop reversal optimization
-</LI>
-</UL>
-<P>
-
-<H3><A NAME="SECTION00042600000000000000">
-3.2.6 DS390 Options</A>
-</H3>
-
-<P>
-
-<UL>
-<LI>[<B>-stack-auto</B>]See MCS51 section for description.
-</LI>
-<LI>[-<B>model</B>-<B>flat24</B>]Generate 24-bit flat mode code.
-This is the one and only that the ds390 code generator supports right
-now and is default when using -mds390. See section Memory Models for
-more details.
-</LI>
-<LI>[<B>-stack-10bit</B>]This option generates code for the 10 bit
-stack mode of the Dallas DS80C390 part. This is the one and only that
-the ds390 code generator supports right now and is default when using
--mds390. 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 will 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="SECTION00042700000000000000">
-3.2.7 Other Options</A>
-</H3>
-
-<P>
-
-<UL>
-<LI>[<B>-callee-saves</B>]<B>function1[,function2][,function3]....</B>
+Switch Statements for more details. It is recommended that this option
+is NOT used, #pragma NOJTBOUND can be used to turn off boundary checking
+for jump tables for a given function only.</dd>
+ <dt><b><b>-noloopreverse</b></b></dt>
+ <dd>Will not do loop reversal optimization.
+</dd>
+</dl>
+
+<p>
+ <h4><a name="tth_sEc3.2.7">
+3.2.7</a> Other Options</h4>
+
+<p>
+
+<dl compact="compact">
+
+
+
+
+ <dt><b><b>-c -compile-only</b></b></dt>
+ <dd>will compile and assemble the source,
+but will not call the linkage editor.</dd>
+ <dt><b><b>-E</b></b></dt>
+ <dd>Run only the C preprocessor. Preprocess all the C source
+files specified and output the results to standard output.</dd>
+ <dt><b><b>-stack-auto</b></b></dt>
+ <dd>All functions in the source file will be compiled
+as <em>reentrant</em>, 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.</dd>
+ <dt><b><b>-xstack</b></b></dt>
+ <dd>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.</dd>
+ <dt><b><b>-callee-saves</b></b></dt>
+ <dd><b>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
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>-debug</B>]When this option is used the compiler will generate
-debug information , that can be used with the SDCDB. The debug information
+option string. Also see Pragma Directive CALLEE-SAVES.</dd>
+ <dt><b><b>-debug</b></b></dt>
+ <dd>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>-regextend</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>-peep-file</B><filename>]This option can be used to use additional
+documentation for SDCDB.</dd>
+ <dt><b><b><em>-regextend</em></b></b></dt>
+ <dd> <em>This option is obsolete and isn't
+supported anymore.</em></dd>
+ <dt><b><b><em>-noregparms</em></b></b></dt>
+ <dd><em>This option is obsolete and isn't
+supported anymore.</em></dd>
+ <dt><b><b>-peep-file</b><filename></b></dt>
+ <dd>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>-E</B>]Run only the C preprocessor. Preprocess all the C source
-files specified and output the results to standard output.
-</LI>
-<LI>[<B>-M</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>-C</B>]Tell the preprocessor not to discard comments. Used with
-the `-E' option.
-</LI>
-<LI>[<B>-MM</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>-Aquestion(answer)</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>-Aquestion</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>-Umacro</B>]Undefine macro macro. `-U' options are evaluated
-after all `-D' options, but before any `-include' and `-imacros' options.
-</LI>
-<LI>[<B>-dM</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>-dD</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>-dN</B>]Like `-dD' except that the macro arguments and contents
-are omitted. Only `#define name' is included in the output.
-</LI>
-<LI>[<B>-S</B>]Stop after the stage of compilation proper; do not assemble.
-The output is an assembler code file for the input file specified.
-</LI>
-<LI>[<B>-Wa_asmOption[,asmOption]</B>...]Pass the asmOption to
-the assembler.
-</LI>
-<LI>[<B>-Wl_linkOption[,linkOption]</B>...]Pass the linkOption
-to the linker.
-</LI>
-<LI>[<B>-int-long-reent</B>] Integer (16 bit) and long (32 bit) libraries
+optimizations for details on how to write these rules.</dd>
+ <dt><b><b>-S</b></b></dt>
+ <dd>Stop after the stage of compilation proper; do not assemble.
+The output is an assembler code file for the input file specified.</dd>
+ <dt><b><b>-Wa_asmOption[,asmOption]</b>...</b></dt>
+ <dd>Pass the asmOption to
+the assembler.</dd>
+ <dt><b><b>-Wl_linkOption[,linkOption]</b>...</b></dt>
+ <dd>Pass the linkOption
+to the linker.</dd>
+ <dt><b><b>-int-long-reent</b></b></dt>
+ <dd> 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>-cyclomatic</B>]This option will cause the compiler to generate
+compiled as non-reentrant. See section Installation for more details.</dd>
+ <dt><b><b>-cyclomatic</b></b></dt>
+ <dd>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
+contains some <em>important</em> 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>-float-reent</B>] Floating point library is compiled as reentrant.See
-section Installation for more details.
-</LI>
-<LI>[<B>-out-fmt-ihx</B>]The linker output (final object code) is in
-Intel Hex format. (This is the default option).
-</LI>
-<LI>[<B>-out-fmt-s19</B>]The linker output (final object code) is in
-Motorola S19 format.
-</LI>
-<LI>[<B>-nooverlay</B>] The compiler will not overlay parameters and
+graph of the function, and most importantly the <em>cyclomatic complexity</em>
+see section on Cyclomatic Complexity for more details.</dd>
+ <dt><b><b>-float-reent</b></b></dt>
+ <dd> Floating point library is compiled as reentrant.See
+section Installation for more details.</dd>
+ <dt><b><b>-nooverlay</b></b></dt>
+ <dd> The compiler will not overlay parameters and
local variables of any function, see section Parameters and local
-variables for more details.
-</LI>
-<LI>[<B>-main-return</B>]This option can be used when the code generated
+variables for more details.</dd>
+ <dt><b><b>-main-return</b></b></dt>
+ <dd>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>-no-peep</B>] Disable peep-hole optimization.
-</LI>
-<LI>[<B>-peep-asm</B>] Pass the inline assembler code through the peep
+up i.e. generate a 'ljmp '.</dd>
+ <dt><b><b>-no-peep</b></b></dt>
+ <dd> Disable peep-hole optimization.</dd>
+ <dt><b><b>-peep-asm</b></b></dt>
+ <dd> Pass the inline assembler code through the peep
hole optimizer. This can cause unexpected changes to inline assembler
code, please go through the peephole optimizer rules defined in the
-source file tree '<target>/peeph.def' before using this option.
-</LI>
-<LI>[<B>-iram-size</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="SECTION00042800000000000000">
-3.2.8 Intermediate Dump Options</A>
-</H3>
-
-<P>
+source file tree '<target>/peeph.def' before using this option.</dd>
+ <dt><b><b>-iram-size</b><Value></b></dt>
+ <dd>Causes the linker to check if the interal
+ram usage is within limits of the given value.</dd>
+ <dt><b><b>-nostdincl</b></b></dt>
+ <dd>This will prevent the compiler from passing
+on the default include path to the preprocessor.</dd>
+ <dt><b><b>-nostdlib</b></b></dt>
+ <dd>This will prevent the compiler from passing on
+the default library path to the linker.</dd>
+ <dt><b><b>-verbose</b></b></dt>
+ <dd>Shows the various actions the compiler is performing.</dd>
+ <dt><b><b>-V</b></b></dt>
+ <dd>Shows the actual commands the compiler is executing.
+</dd>
+</dl>
+
+<p>
+ <h4><a name="tth_sEc3.2.8">
+3.2.8</a> Intermediate Dump Options</h4>
+
+<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>
+<p>
-<UL>
-<LI>[<B>-dumpraw</B>]This option will cause the compiler to dump the
-intermediate code into a file of named <I><source filename>.dumpraw</I>
+<dl compact="compact">
+
+
+
+
+ <dt><b><b>-dumpraw</b></b></dt>
+ <dd>This option will cause the compiler to dump the
+intermediate code into a file of named <em><source filename>.dumpraw</em>
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>-dumpgcse</B>]Will create a dump of iCode's, after global subexpression
-elimination, into a file named <I><source filename>.dumpgcse.</I>
-</LI>
-<LI>[<B>-dumpdeadcode</B>]Will create a dump of iCode's, after deadcode
-elimination, into a file named <I><source filename>.dumpdeadcode.</I>
-</LI>
-<LI>[<B>-dumploop</B>]Will create a dump of iCode's, after loop optimizations,
-into a file named <I><source filename>.dumploop.</I>
-</LI>
-<LI>[<B>-dumprange</B>]Will create a dump of iCode's, after live range
-analysis, into a file named <I><source filename>.dumprange.</I>
-</LI>
-<LI>[<B>-dumlrange</B>]Will dump the life ranges for all symbols
-</LI>
-<LI>[<B>-dumpregassign</B>]Will create a dump of iCode's, after register
-assignment , into a file named <I><source filename>.dumprassgn.</I>
-</LI>
-<LI>[<B>-dumplrange</B>]Will create a dump of the live ranges of iTemp's
-</LI>
-<LI>[<B>-dumpall</B>]Will cause all the above mentioned dumps to be
+of execution.</dd>
+ <dt><b><b>-dumpgcse</b></b></dt>
+ <dd>Will create a dump of iCode's, after global subexpression
+elimination, into a file named <em><source filename>.dumpgcse.</em></dd>
+ <dt><b><b>-dumpdeadcode</b></b></dt>
+ <dd>Will create a dump of iCode's, after deadcode
+elimination, into a file named <em><source filename>.dumpdeadcode.</em></dd>
+ <dt><b><b>-dumploop</b></b></dt>
+ <dd>Will create a dump of iCode's, after loop optimizations,
+into a file named <em><source filename>.dumploop.</em></dd>
+ <dt><b><b>-dumprange</b></b></dt>
+ <dd>Will create a dump of iCode's, after live range
+analysis, into a file named <em><source filename>.dumprange.</em></dd>
+ <dt><b><b>-dumlrange</b></b></dt>
+ <dd>Will dump the life ranges for all symbols.</dd>
+ <dt><b><b>-dumpregassign</b></b></dt>
+ <dd>Will create a dump of iCode's, after register
+assignment, into a file named <em><source filename>.dumprassgn.</em></dd>
+ <dt><b><b>-dumplrange</b></b></dt>
+ <dd>Will create a dump of the live ranges of iTemp's</dd>
+ <dt><b><b>-dumpall</b></b></dt>
+ <dd>Will cause all the above mentioned dumps to be
created.
-</LI>
-</UL>
-<P>
+</dd>
+</dl>
-<H2><A NAME="SECTION00043000000000000000">
-3.3 MCS51/DS390 Storage Class Language Extensions</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc3.3">
+3.3</a> MCS51/DS390 Storage Class Language Extensions</h3>
-<P>
+<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>
+ <h4><a name="tth_sEc3.3.1">
+3.3.1</a> xdata</h4>
-<P>
+<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,
-e.g.:
-<BR>
-<BR><TT>xdata unsigned char xduc;</TT>
+RAM. This is the <b>default</b> storage class for Large Memory model,
+e.g.:<br />
+<br />
+<tt>xdata unsigned char xduc;</tt>
-<P>
+<p>
+ <h4><a name="tth_sEc3.3.2">
+3.3.2</a> data</h4>
-<H3><A NAME="SECTION00043200000000000000">
-3.3.2 data</A>
-</H3>
-
-<P>
-This is the <B>default</B> storage class for Small Memory model.
+<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, e.g.:
-<BR>
-<BR><TT>data int iramdata;</TT>
-
-<P>
+internal RAM, e.g.:<br />
+<br />
+<tt>data int iramdata;</tt>
-<H3><A NAME="SECTION00043300000000000000">
-3.3.3 idata</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc3.3.3">
+3.3.3</a> idata</h4>
-<P>
+<p>
Variables declared with this storage class will be allocated into
the indirectly addressable portion of the internal ram of a 8051,
-e.g.:
-<BR>
-<BR><TT>idata int idi;</TT>
-
-<P>
+e.g.:<br />
+<br />
+<tt>idata int idi;</tt>
-<H3><A NAME="SECTION00043400000000000000">
-3.3.4 bit</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc3.3.4">
+3.3.4</a> bit</h4>
-<P>
+<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, e.g.:
-<BR>
-<BR><TT>bit iFlag;</TT>
+is declared as a bit, it is allocated into the bit addressable memory
+of 8051, e.g.:<br />
+<br />
+<tt>bit iFlag;</tt>
-<P>
+<p>
+ <h4><a name="tth_sEc3.3.5">
+3.3.5</a> sfr / sbit</h4>
-<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
+<p>
+Like the bit keyword, <em>sfr / sbit</em> signifies both a data-type
and storage class, they are used to describe the special function
-registers and special bit variables of a 8051, eg:
-<BR>
-<BR><TT>sfr at 0x80 P0; /* special function register P0 at location
-0x80 */</TT>
-<BR><TT>sbit at 0xd7 CY; /* CY (Carry Flag) */</TT>
-
-<P>
+registers and special bit variables of a 8051, eg:<br />
+<br />
+<tt>sfr at 0x80 P0; /* special function register P0 at location
+0x80 */</tt> <br />
+<tt>sbit at 0xd7 CY; /* CY (Carry Flag) */</tt>
-<H2><A NAME="SECTION00044000000000000000">
-3.4 Pointers</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc3.4">
+3.4</a> Pointers</h3>
-<P>
+<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.
-<BR>
-<BR>
-Pointer declaration examples.
-<BR>
-<BR><TT>/* pointer physically in xternal ram pointing to object
-in internal ram */ </TT>
-<BR><TT>data unsigned char * xdata p;</TT>
-<BR>
-<BR><TT>/* pointer physically in code rom pointing to data in xdata
-space */ </TT>
-<BR><TT>xdata unsigned char * code p;</TT>
-<BR>
-<BR><TT>/* pointer physically in code space pointing to data in
-code space */ </TT>
-<BR><TT>code unsigned char * code p;</TT>
-<BR>
-<BR><TT>/* the folowing is a generic pointer physically located
-in xdata space */</TT>
-<BR><TT>char * xdata p;</TT>
-<BR>
-<BR>
-Well you get the idea. For compatibility with the previous version
-of the compiler, the following syntax for pointer declaration is still
-supported but will disappear int the near future.
-<BR>
-<BR><TT>unsigned char _xdata *ucxdp; /* pointer to data in external
-ram */ </TT>
-<BR><TT>unsigned char _data *ucdp ; /* pointer to data in internal
-ram */ </TT>
-<BR><TT>unsigned char _code *uccp ; /* pointer to data in R/O
-code space */</TT>
-<BR><TT>unsigned char _idata *uccp; /* pointer to upper 128
-bytes of ram */</TT>
-<BR>
-<BR>
+pointers, the compiler also allows a <em>_generic</em> class of pointers
+which can be used to point to any of the memory spaces.<br />
+<br />
+Pointer declaration examples:<br />
+<font size="-1"></font><br />
+<tt>/* pointer physically in xternal ram pointing to object
+in internal ram */ </tt> <br />
+<tt>data unsigned char * xdata p;</tt> <br />
+<tt></tt> <br />
+<tt>/* pointer physically in code rom pointing to data in xdata
+space */ </tt> <br />
+<tt>xdata unsigned char * code p;</tt> <br />
+<tt></tt> <br />
+<tt>/* pointer physically in code space pointing to data in
+code space */ </tt> <br />
+<tt>code unsigned char * code p;</tt> <br />
+<tt></tt> <br />
+<tt>/* the folowing is a generic pointer physically located
+in xdata space */</tt> <br />
+<tt>char * xdata p;</tt><font size="-1"></font><br />
+<font size="-1"></font><br />
+Well you get the idea. <br />
+<br />
+<em>For compatibility with the previous version of the compiler,
+the following syntax for pointer declaration is still supported but
+will disappear int the near future. </em><br />
+<em></em><br />
+<tt><em>unsigned char _xdata *ucxdp; /* pointer to data
+in external ram */ </em></tt> <br />
+<tt><em>unsigned char _data *ucdp ; /* pointer to data
+in internal ram */ </em></tt> <br />
+<tt><em>unsigned char _code *uccp ; /* pointer to data
+in R/O code space */</em></tt> <br />
+<tt><em>unsigned char _idata *uccp; /* pointer to upper
+128 bytes of ram */</em></tt><font size="-1"></font><br />
+<font size="-1"></font><br />
All unqualified pointers are treated as 3-byte (4-byte for the ds390)
-'_generic' pointers. These type of pointers can also to be explicitly
-declared.
-<BR>
-<BR><TT>unsigned char _generic *ucgp;</TT>
-<BR>
-<BR>
-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>
+<em>generic</em> pointers. These type of pointers can also to be explicitly
+declared.<br />
+<br />
+<tt>unsigned char _generic *ucgp;</tt><font size="-1"></font><br />
+<font size="-1"></font><br />
+The highest order byte of the <em>generic</em> pointers contains the
+data space information. Assembler support routines are called whenever
+data is stored or retrieved using <em>generic</em> 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 and NEW style could have unpredictable results.
+
+<p>
+ <h3><a name="tth_sEc3.5">
+3.5</a> Parameters & Local Variables</h3>
+
+<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, e.g.:
-<BR>
-<BR><TT>unsigned char foo( char i) reentrant </TT>
-<BR><TT>{ </TT>
-<BR><TT>... </TT>
-<BR><TT>}</TT>
-<BR>
-<BR>
-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,
-e.g.: (jwk: pending: this is obsolete and need a rewrite)
-<BR>
-<BR><TT>unsigned char foo() {</TT>
-
-<P>
-<TT>xdata unsigned char i;</TT>
-
-<P>
-<TT>bit bvar;</TT>
-
-<P>
-<TT>data at 0x31 unsiged char j;</TT>
-
-<P>
-<TT>... </TT>
-<BR><TT>}</TT>
-
-<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>
+compiler is to place these variables in the internal RAM (for small
+model) or external RAM (for Large model). This in fact makes them
+<em>static</em> so by default functions are non-reentrant.
+
+<p>
+They can be placed on the stack either by using the <em>-stack-auto</em>
+compiler option or by using the <em>reentrant</em> keyword in the function
+declaration, e.g.:<br />
+<font size="-1"></font><br />
+<tt>unsigned char foo(char i) reentrant </tt> <br />
+<tt>{ </tt> <br />
+<tt>... </tt> <br />
+<tt>}</tt> <br />
+<br />
+Since stack space on 8051 is limited, the <em>reentrant</em> keyword
+or the <em>-stack-auto</em> option should be used sparingly. Note that
+the reentrant keyword just means that the parameters & local variables
+will be allocated to the stack, it <em>does not</em> mean that the function
+is register bank independent.<br />
+<br />
+Local variables can be assigned storage classes and absolute addresses,
+e.g.: <br />
+<br />
+<tt>unsigned char foo() {</tt> <br />
+<tt> xdata unsigned char i;</tt> <br />
+<tt> bit bvar;</tt> <br />
+<tt> data at 0x31 unsiged char j;</tt> <br />
+<tt> ... </tt> <br />
+<tt>}</tt> <br />
+<tt></tt> <br />
+In the above example the variable <em>i</em> will be allocated in the
+external ram, <em>bvar</em> in bit addressable space and <em>j</em> in
+internal ram. When compiled with <em>-stack-auto</em> or when a function
+is declared as <em>reentrant</em> this can only be done for static variables.
+
+<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>
+memory model in use, and the reentrancy options.
-<H2><A NAME="SECTION00046000000000000000">
-3.6 Overlaying</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc3.6">
+3.6</a> Overlaying</h3>
-<P>
+<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.
+to an overlayable segment if the function has <em>no other function
+calls and the function is non-reentrant and the memory model is small.</em>
+If an explicit storage class is specified for a local variable, it
+will NOT be overlayed.
-<P>
+<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>
+are not reentrant.
+
+<p>
+Also note that the compiler does not do any processing of inline assembler
+code, so the compiler might incorrectly assign local variables and
+parameters of a function into the overlay segment if the inline assembler
+code calls other c-functions that might use the overlay. In that case
+the #pragma NOOVERLAY should be used.
+
+<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, e.g.:
-<BR>
-<BR><TT>#pragma SAVE </TT>
-<BR><TT>#pragma NOOVERLAY </TT>
-<BR><TT>void set_error( unsigned char errcd) </TT>
-<BR><TT>{</TT>
-
-<P>
-<TT>P3 = errcd;</TT>
-<BR><TT>} </TT>
-<BR><TT>#pragma RESTORE </TT>
-<BR><TT>void some_isr () interrupt 2 using 1 </TT>
-<BR><TT>{</TT>
-
-<P>
-<TT>...</TT>
-
-<P>
-<TT>set_error(10);</TT>
-
-<P>
-<TT>... </TT>
-<BR><TT>}</TT>
-
-<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
-when called from an ISR. The pragma NOOVERLAY ensures that the parameters
+implemented using external functions, e.g.:<br />
+<br />
+<tt>#pragma SAVE </tt> <br />
+<tt>#pragma NOOVERLAY </tt> <br />
+<tt>void set_error(unsigned char errcd) </tt> <br />
+<tt>{</tt> <br />
+<tt> P3 = errcd;</tt> <br />
+<tt>} </tt> <br />
+<tt>#pragma RESTORE </tt> <br />
+<tt></tt> <br />
+<tt>void some_isr () interrupt 2 using 1 </tt> <br />
+<tt>{</tt> <br />
+<tt> ...</tt> <br />
+<tt> set_error(10);</tt> <br />
+<tt> ... </tt> <br />
+<tt>}</tt> <br />
+<tt></tt> <br />
+In the above example the parameter <em>errcd</em> for the function <em>set_error</em>
+would be assigned to the overlayable segment if the #pragma NOOVERLAY
+was not present, this could cause unpredictable runtime behavior when
+called from an ISR. The #pragma NOOVERLAY ensures that the parameters
and local variables for the function are NOT overlayed.
-<P>
-
-<H2><A NAME="SECTION00047000000000000000">
-3.7 Interrupt Service Routines</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc3.7">
+3.7</a> Interrupt Service Routines</h3>
-<P>
+<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>
+extended keywords.<br />
+<br />
+<tt>void timer_isr (void) interrupt 2 using 1 </tt> <br />
+<tt>{ </tt> <br />
+<tt>.. </tt> <br />
+<tt>}</tt> <br />
+<tt></tt> <br />
+The number following the <em>interrupt</em> 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 <em>using</em> 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 <em>#pragma
+NOOVERLAY</em> 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 be recompiled using the <em>-stack-auto</em> option and the
+source file will need to be compiled using the <em>-int-long-ren</em>t
+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>.
+MUST be present or included in the file that contains the function
+<em>main</em>.
-<P>
+<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.
-<BR>
-<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>
-<BR>
-<P>
-If the interrupt service routine is defined without <I>'using'</I>
-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>
+the interrupt vector table to the maximum interrupt number specified.<br />
+
+<p>
+
+<table border="1">
+<tr><td align="center">Interrupt #</td><td align="center">Description</td><td align="center">Vector Address</td></tr><tr><td>
+<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>
+<br />
+<br />
+If the interrupt service routine is defined without <em>using</em> 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="SECTION00048000000000000000">
-3.8 Critical Functions</A>
-</H2>
-
-<P>
+register bank then only <em>a, b & dptr</em> 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.<br />
+<br />
+Also see the _naked modifier.
+
+<p>
+ <h3><a name="tth_sEc3.8">
+3.8</a> Critical Functions</h3>
+
+<p>
A special keyword may be associated with a function declaring it as
-'<I>critical</I>'. SDCC will generate code to disable all interrupts
+<em>critical</em>. 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.
-<BR>
-<BR>
-eg:
-<BR>
-<BR><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>
-<BR>
-<BR>
-The critical attribute maybe used with other attributes like <I>reentrant.</I>
-
-<P>
-
-<H2><A NAME="SECTION00049000000000000000">
-3.9 Naked Functions</A>
-</H2>
-
-<P>
+Note that nesting critical functions may cause unpredictable results.<br />
+<font size="-1"></font><br />
+<tt>int foo () critical </tt> <br />
+<tt>{ </tt> <br />
+<tt>... </tt> <br />
+<tt>... </tt> <br />
+<tt>}</tt> <br />
+<br />
+The critical attribute maybe used with other attributes like <em>reentrant.</em>
+
+<p>
+ <h3><a name="tth_sEc3.9">
+3.9</a> Naked Functions</h3>
+
+<p>
A special keyword may be associated with a function declaring it as
-<I>'_naked'.</I> The <I>'_naked'</I> function modifier attribute
-prevents the compiler from generating prologue and epilogue code for
-that function. This means that the user is entirely responsible for
-such things as saving any registers that may need to be preserved,
-selecting the proper register bank, generating the <I>'return'</I>
-instruction at the end, etc. Practically, this means that the contents
-of the function must be written in inline assembler. This is particularly
-useful for interrupt functions, which can have a large (and often
-unnecessary) prologue/epilogue. For example, compare the code generated
-by these two functions:
-<BR>
-<BR>
-data unsigned char counter;
-<BR>
-void simpleIterrupt(void) interrupt 1
-<BR>{
-
-<P>
-counter++;
-<BR>}
-<BR>
-<BR>
-void nakedInterrupt(void) interrupt 2 _naked
-<BR>{
-
-<P>
-_asm
-
-<P>
- inc _counter
-
-<P>
- reti ; MUST explicitly include ret in _naked
-function.
-
-<P>
-_endasm;
-<BR>}
-<BR>
-<BR>
-For an 8051 target, the generated simpleInterrupt looks like:
-<BR>
-<BR>
-_simpleIterrupt:
-
-<P>
-push acc
-
-<P>
-push b
-
-<P>
-push dpl
-
-<P>
-push dph
-
-<P>
-push psw
-
-<P>
-mov psw,#0x00
-
-<P>
-inc _counter
-
-<P>
-pop psw
-
-<P>
-pop dph
-
-<P>
-pop dpl
-
-<P>
-pop b
-
-<P>
-pop acc
-
-<P>
-reti
-<BR>
-<BR>
-whereas nakedInterrupt looks like:
-<BR>
-<BR>
-_nakedInterrupt:
-
-<P>
-inc _counter
-
-<P>
-reti ; MUST explicitly include ret(i) in _naked function.
-<BR>
-<BR>
+<em>_naked.</em> The <em>_naked</em> function modifier attribute prevents
+the compiler from generating prologue and epilogue code for that function.
+This means that the user is entirely responsible for such things as
+saving any registers that may need to be preserved, selecting the
+proper register bank, generating the <em>return</em> instruction at
+the end, etc. Practically, this means that the contents of the function
+must be written in inline assembler. This is particularly useful for
+interrupt functions, which can have a large (and often unnecessary)
+prologue/epilogue. For example, compare the code generated by these
+two functions:<br />
+<br />
+<tt>data unsigned char counter;</tt> <br />
+<tt>void simpleInterrupt(void) interrupt 1</tt> <br />
+<tt>{</tt> <br />
+<tt> counter++;</tt> <br />
+<tt>}</tt> <br />
+<tt></tt> <br />
+<tt>void nakedInterrupt(void) interrupt 2 _naked</tt> <br />
+<tt>{</tt> <br />
+<tt> _asm</tt> <br />
+<tt> inc _counter</tt> <br />
+<tt> reti ; MUST explicitly include ret in _naked
+function.</tt> <br />
+<tt> _endasm;</tt> <br />
+<tt>}</tt><br />
+<br />
+For an 8051 target, the generated simpleInterrupt looks like:<br />
+<br />
+<tt>_simpleIterrupt:</tt> <br />
+<tt> push acc</tt> <br />
+<tt> push b</tt> <br />
+<tt> push dpl</tt> <br />
+<tt> push dph</tt> <br />
+<tt> push psw</tt> <br />
+<tt> mov psw,#0x00</tt> <br />
+<tt> inc _counter</tt> <br />
+<tt> pop psw</tt> <br />
+<tt> pop dph</tt> <br />
+<tt> pop dpl</tt> <br />
+<tt> pop b</tt> <br />
+<tt> pop acc</tt> <br />
+<tt> reti</tt><br />
+<br />
+whereas nakedInterrupt looks like:<br />
+<br />
+<tt>_nakedInterrupt:</tt> <br />
+<tt> inc _counter</tt> <br />
+<tt> reti ; MUST explicitly include ret(i) in _naked
+function.</tt><br />
+<br />
While there is nothing preventing you from writing C code inside a
_naked function, there are many ways to shoot yourself in the foot
doing this, and is is recommended that you stick to inline assembler.
-<P>
-
-<H2><A NAME="SECTION000410000000000000000">
-3.10 Functions using private banks</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc3.10">
+3.10</a> Functions using private banks</h3>
-<P>
-The <I>'using'</I> attribute (which tells the compiler to use a register
-bank other than the default bank zero) should only be applied to 'interrupt'
-functions (see note A below). This will in most circumstances make
+<p>
+The <em>using</em> attribute (which tells the compiler to use a register
+bank other than the default bank zero) should only be applied to <em>interrupt</em>
+functions (see note 1 below). This will in most circumstances make
the generated ISR code more efficient since it will not have to save
registers on the stack.
-<P>
-The <I>'using'</I> attribute will have no effect on the generated
-code for a <I>non-'interrupt'</I> function (but may occasionally be
-useful anyway<A NAME="tex2html1"
- HREF="#foot456"><SUP>1</SUP></A>).
-<BR>(jwk: todo: I don't think this has been done yet)
+<p>
+The <em>using</em> attribute will have no effect on the generated code
+for a <em>non-interrupt</em> function (but may occasionally be useful
+anyway<a href="#tthFtNtAAB" name="tthFrefAAB"><sup>1</sup></a>).<br />
+<em>(pending: I don't think this has been done yet)</em>
-<P>
-An 'interrupt' function using a non-zero bank will assume that it
-can trash that register bank, and will not save it. Since high-priority
+<p>
+An <em>interrupt</em> function using a non-zero bank will assume that
+it can trash that register bank, and will not save it. Since high-priority
interrupts can interrupt low-priority ones on the 8051 and friends,
-this means that if a high-priority ISR 'using' a particular bank occurs
-while processing a low-priority ISR 'using' the same bank, terrible
-and bad things can happen. To prevent this, no single register bank
-should be 'used' by both a high priority and a low priority ISR. This
-is probably most easily done by having all high priority ISRs use
-one bank and all low priority ISRs use another. If you have an ISR
-which can change priority at runtime, you're on your own: I suggest
-using the default bank zero and taking the small performance hit.
-
-<P>
+this means that if a high-priority ISR <em>using</em> a particular bank
+occurs while processing a low-priority ISR <em>using</em> the same bank,
+terrible and bad things can happen. To prevent this, no single register
+bank should be <em>used</em> by both a high priority and a low priority
+ISR. This is probably most easily done by having all high priority
+ISRs use one bank and all low priority ISRs use another. If you have
+an ISR which can change priority at runtime, you're on your own: I
+suggest using the default bank zero and taking the small performance
+hit.
+
+<p>
It is most efficient if your ISR calls no other functions. If your
ISR must call other functions, it is most efficient if those functions
-use the same bank as the ISR (see note A below); the next best is
+use the same bank as the ISR (see note 1 below); the next best is
if the called functions use bank zero. It is very inefficient to call
a function using a different, non-zero bank from an ISR.
-<P>
-
-<H2><A NAME="SECTION000411000000000000000">
-3.11 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>
+<p>
+ <h3><a name="tth_sEc3.11">
+3.11</a> Absolute Addressing</h3>
+
+<p>
+Data items can be assigned an absolute address with the <em>at <address></em>
+keyword, in addition to a storage class, e.g.:<br />
+<br />
+<tt>xdata at 0x8000 unsigned char PORTA_8255 ;</tt> <br />
+<br />
+In the above example the PORTA_8255 will be allocated to the location
+0x8000 of the external ram. Note that this feature is provided to
+give the programmer access to <em>memory mapped</em> 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 (.rst) and (.map) are a good places to look for such
+overlaps.<br />
+<br />
+Absolute address can be specified for variables in all storage classes,
+e.g.:<br />
+<br />
+<tt>bit at 0x02 bvar;</tt> <br />
+<tt></tt> <br />
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
+addresses to variables in this manner, unless you want strict control
over all the variables allocated.
-<P>
-
-<H2><A NAME="SECTION000412000000000000000">
-3.12 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="SECTION000413000000000000000">
-3.13 Inline Assembler Code</A>
-</H2>
-
-<P>
+<p>
+ <h3><a name="tth_sEc3.12">
+3.12</a> Startup Code</h3>
+
+<p>
+The compiler inserts a call to the C routine <em>_sdcc__external__startup()</em>
+at the start of the CODE area. This routine is in the runtime library.
+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 <em>_sdcc__external__startup()</em> routine to
+your program to override the default if you need to setup hardware
+or perform some other critical operation prior to static & global
+variable initialization.
+
+<p>
+ <h3><a name="tth_sEc3.13">
+3.13</a> Inline Assembler Code</h3>
+
+<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>
+regards labels. All labels defined within inline assembler code <em>has
+to be</em> of the form <em>nnnnn$</em> where nnnn is a number less than
+100 (which implies a limit of utmost 100 inline assembler labels <em>per
+function</em> ). It is strongly recommended that each assembly
+instruction (including labels) be placed in a separate line (as the
+example shows). When the <em>-peep-asm</em> 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 <em>SDCCpeeph.def</em> carefully before using this option.<br />
+<br />
+<tt>_asm </tt> <br />
+<tt> mov b,#10 </tt> <br />
+<tt>00001$: </tt> <br />
+<tt> djnz b,00001$ </tt> <br />
+<tt>_endasm ;</tt><font size="-1"></font><br />
+<font size="-1"></font><br />
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>
+the assembler, this includes any assembler directives and comment
+lines. The compiler does not do any validation of the code within
+the <tt>_asm ... _endasm;</tt> keyword pair. <br />
+<br />
+Inline assembler code cannot reference any C-Labels, however it can
+reference labels defined by the inline assembler, e.g.:<br />
+<br />
+<tt>foo() { </tt> <br />
+<tt> /* some c code */ </tt> <br />
+<tt> _asm </tt> <br />
+<tt> ; some assembler code </tt> <br />
+<tt> ljmp $0003 </tt> <br />
+<tt> _endasm; </tt> <br />
+<tt> /* some more c code */ </tt> <br />
+<tt>clabel: /* inline assembler cannot reference this label
+*/ </tt> <br />
+<tt> _asm</tt> <br />
+<tt> $0003: ;label (can be reference by inline assembler
+only) </tt> <br />
+<tt> _endasm ; </tt> <br />
+<tt> /* some more c code */</tt> <br />
+<tt>}</tt> <br />
+<tt></tt> <br />
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.
+assembly within the scope of the funtion.
-<P>
+<p>
+The same goes the other way, ie. labels defines in inline assembly
+CANNOT be accessed by C statements.
-<H2><A NAME="SECTION000414000000000000000">
-3.14 int(16 bit) and long (32 bit ) Support</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc3.14">
+3.14</a> int(16 bit) and long (32 bit) Support</h3>
-<P>
+<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
+to other MCUs, although some model specific assembler optimations
+are used. The following files contain the described routine, all of
+them can be found in <installdir>/share/sdcc/lib.<br />
+<br />
+_mulsint.c - signed 16 bit multiplication (calls _muluint)<br />
+_muluint.c - unsigned 16 bit multiplication<br />
+_divsint.c - signed 16 bit division (calls _divuint)<br />
+_divuint.c - unsigned 16 bit division<br />
+_modsint.c - signed 16 bit modulus (call _moduint)<br />
+_moduint.c - unsigned 16 bit modulus<br />
+_mulslong.c - signed 32 bit multiplication (calls _mululong)<br />
+_mululong.c - unsigned32 bit multiplication<br />
+_divslong.c - signed 32 division (calls _divulong)<br />
+_divulong.c - unsigned 32 division<br />
+_modslong.c - signed 32 bit modulus (calls _modulong)<br />
+_modulong.c - unsigned 32 bit modulus <font size="-2"></font><br />
+<font size="-2"></font><br />
+Since they are compiled as <em>non-reentrant</em>, interrupt service
+routines should not do any of the above operations. If this is unavoidable
+then the above routines will need to be compiled with the <em>-stack-auto</em>
option, after which the source program will have to be compiled with
--int-long-rent option.
+<em>-int-long-rent</em> option.
-<P>
+<p>
+ <h3><a name="tth_sEc3.15">
+3.15</a> Floating Point Support</h3>
-<H2><A NAME="SECTION000415000000000000000">
-3.15 Floating Point Support</A>
-</H2>
-
-<P>
+<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>
+and consists of the following routines:<br />
+<br />
+_fsadd.c - add floating point numbers<br />
+_fssub.c - subtract floating point numbers<br />
+_fsdiv.c - divide floating point numbers<br />
+_fsmul.c - multiply floating point numbers<br />
+_fs2uchar.c - convert floating point to unsigned char<br />
+_fs2char.c - convert floating point to signed char<br />
+_fs2uint.c - convert floating point to unsigned int<br />
+_fs2int.c - convert floating point to signed int<br />
+_fs2ulong.c - convert floating point to unsigned long<br />
+_fs2long.c - convert floating point to signed long<br />
+_uchar2fs.c - convert unsigned char to floating point<br />
+_char2fs.c - convert char to floating point number<br />
+_uint2fs.c - convert unsigned int to floating point<br />
+_int2fs.c - convert int to floating point numbers<br />
+_ulong2fs.c - convert unsigned long to floating point number<br />
+_long2fs.c - convert long to floating point number<font size="-2"></font><br />
+<font size="-2"></font><br />
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>
+that the large model be used.
-<H2><A NAME="SECTION000416000000000000000">
-3.16 MCS51 Memory Models</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc3.16">
+3.16</a> MCS51 Memory Models</h3>
-<P>
+<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>
+compiled with different memory models should <em>never</em> 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.
+
+<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>
+<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
+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="SECTION000417000000000000000">
-3.17 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>
+<p>
+ <h3><a name="tth_sEc3.17">
+3.17</a> DS390 Memory Models</h3>
+
+<p>
+The only model supported is Flat 24. This 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.<br />
+<br />
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>
+code generator (<em>-mmcs51</em>). Now, however, the '390 has it's own
+code generator, selected by the <em>-mds390</em> switch. <br />
+<br />
Note that the compiler does not generate any code to place the processor
-into24 bitmode (it defaults to 8051 compatible mode). Boot loader
+into 24 bitmode (although <em>tinibios</em> in the ds390 libraries will
+do that for you). If you don't use <em>tinibios</em>, the 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>
+addressing mode before calling the SDCC startup code.<br />
+<br />
+Like the <em>-model-large</em> option, variables will by default be
+placed into the XDATA segment. <br />
+<br />
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.
+The -r flag can be passed to the linker by using the option <em>-Wl-r</em>
+on the sdcc command line. However, currently the linker can not handle
+code segments > 64k.
-<P>
+<p>
+ <h3><a name="tth_sEc3.18">
+3.18</a> Defines Created by the Compiler</h3>
-<H2><A NAME="SECTION000418000000000000000">
-3.18 Defines Created by the Compiler</A>
-</H2>
-
-<P>
+<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
+<p>
+
+<ul><p>
+<li> SDCC - this Symbol is always defined.</li>
+<p>
+<li> SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model
+used (e.g.: -mds390)</li>
+<p>
+<li> __mcs51 or __ds390 or __z80, etc - depending on the model used
+(e.g. -mz80)</li>
+<p>
+<li> SDCC_STACK_AUTO - this symbol is defined when <em>-stack-auto</em>
+option is used.</li>
+<p>
+<li> SDCC_MODEL_SMALL - when <em>-model-small</em> is used.</li>
+<p>
+<li> SDCC_MODEL_LARGE - when <em>-model-large</em> is used.</li>
+<p>
+<li> SDCC_USE_XSTACK - when <em>-xstack</em> option is used.</li>
+<p>
+<li> SDCC_STACK_TENBIT - when <em>-mds390</em> is used</li>
+<p>
+<li> SDCC_MODEL_FLAT24 - when <em>-mds390</em> is used</li>
+</ul>
+
+<p>
+ <h2><a name="tth_sEc4">
+4</a> SDCC Technical Data</h2>
+
+<p>
+ <h3><a name="tth_sEc4.1">
+4.1</a> Optimizations</h3>
+
+<p>
+SDCC performs 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>
+<p>
+ <h4><a name="tth_sEc4.1.1">
+4.1.1</a> Sub-expression Elimination</h4>
+
+<p>
+The compiler does local and global common subexpression elimination,
+e.g.: <br />
+<br />
+<tt>i = x + y + 1; </tt> <br />
+<tt>j = x + y;</tt><br />
+<br />
+will be translated to<br />
+<br />
+<tt>iTemp = x + y </tt> <br />
+<tt>i = iTemp + 1 </tt> <br />
+<tt>j = iTemp</tt> <br />
+<br />
+Some subexpressions are not as obvious as the above example, e.g.:<br />
+<br />
+<tt>a->b[i].c = 10; </tt> <br />
+<tt>a->b[i].d = 11;</tt><br />
+<br />
+In this case the address arithmetic a->b[i] will be computed only
+once; the equivalent code in C would be.<br />
+<br />
+<tt>iTemp = a->b[i]; </tt> <br />
+<tt>iTemp.c = 10; </tt> <br />
+<tt>iTemp.d = 11;</tt><br />
+<br />
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>
+<p>
+ <h4><a name="tth_sEc4.1.2">
+4.1.2</a> Dead-Code Elimination</h4>
+
+<p>
+<tt>int global; </tt> <br />
+<tt>void f () { </tt> <br />
+<tt> int i; </tt> <br />
+<tt> i = 1; /* dead store */ </tt> <br />
+<tt> global = 1; /* dead store */ </tt> <br />
+<tt> global = 2; </tt> <br />
+<tt> return; </tt> <br />
+<tt> global = 3; /* unreachable */ </tt> <br />
+<tt>}</tt><br />
+<br />
+will be changed to<br />
+<br />
+<tt>int global; void f () </tt> <br />
+<tt>{</tt> <br />
+<tt> global = 2; </tt> <br />
+<tt> return; </tt> <br />
+<tt>}</tt>
+
+<p>
+ <h4><a name="tth_sEc4.1.3">
+4.1.3</a> Copy-Propagation</h4>
+
+<p>
+<tt>int f() { </tt> <br />
+<tt> int i, j; </tt> <br />
+<tt> i = 10; </tt> <br />
+<tt> j = i; </tt> <br />
+<tt> return j; </tt> <br />
+<tt>}</tt><br />
+<br />
+will be changed to <br />
+<br />
+<tt>int f() { </tt> <br />
+<tt> int i,j; </tt> <br />
+<tt> i = 10; </tt> <br />
+<tt> j = 10; </tt> <br />
+<tt> return 10; </tt> <br />
+<tt>}</tt> <br />
+<tt></tt> <br />
Note: the dead stores created by this copy propagation will be eliminated
by dead-code elimination.
-<P>
+<p>
+ <h4><a name="tth_sEc4.1.4">
+4.1.4</a> Loop Optimizations</h4>
-<H3><A NAME="SECTION00051400000000000000">
-4.1.4 Loop Optimizations</A>
-</H3>
-
-<P>
+<p>
Two types of loop optimizations are done by SDCC loop invariant lifting
-and strength reduction of loop induction variables.In addition to
+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>
+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).<br />
+<br />
+Loop Invariant:<br />
+<br />
+<tt>for (i = 0 ; i < 100 ; i ++) </tt> <br />
+ <tt> f += k + l;</tt><br />
+<br />
+changed to<br />
+<br />
+<tt>itemp = k + l; </tt> <br />
+<tt>for (i = 0; i < 100; i++) </tt> <br />
+<tt> f += itemp;</tt><br />
+<br />
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>
+all static address computations are also moved out of the loop.<br />
+<br />
+Strength Reduction, this optimization substitutes an expression by
+a cheaper expression:<br />
+<br />
+<tt>for (i=0;i < 100; i++)</tt> <br />
+<tt> ar[i*5] = i*3;</tt><br />
+<br />
+changed to<br />
+<br />
+<tt>itemp1 = 0; </tt> <br />
+<tt>itemp2 = 0; </tt> <br />
+<tt>for (i=0;i< 100;i++) { </tt> <br />
+ <tt> ar[itemp1] = itemp2; </tt> <br />
+ <tt> itemp1 += 5; </tt> <br />
+ <tt> itemp2 += 3; </tt> <br />
+<tt>}</tt><br />
+<br />
The more expensive multiplication is changed to a less expensive addition.
-<P>
+<p>
+ <h4><a name="tth_sEc4.1.5">
+4.1.5</a> Loop Reversing</h4>
-<H3><A NAME="SECTION00051500000000000000">
-4.1.5 Loop Reversing:</A>
-</H3>
-
-<P>
+<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
+reversible (note: more sophisticated compilers 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',
-ofcourse this may not be possible on all situations.
-
-<P>
-
-<H3><A NAME="SECTION00051600000000000000">
-4.1.6 Algebraic Simplifications</A>
-</H3>
-
-<P>
+<p>
+
+<ul><p>
+<li> The 'for' loop is of the form <br />
+<br />
+<tt>for (<symbol> = <expression> ; <sym> [< | <=] <expression>
+; [<sym>++ | <sym> += 1])</tt> <br />
+<tt> <for body></tt></li>
+<p>
+<li> The <for body> does not contain ``continue'' or 'break''.</li>
+<p>
+<li> All goto's are contained within the loop.</li>
+<p>
+<li> No function calls within the loop.</li>
+<p>
+<li> The loop control variable <sym> is not assigned any value within the
+loop</li>
+<p>
+<li> The loop control variable does NOT participate in any arithmetic operation
+within the loop.</li>
+<p>
+<li> There are NO switch statements in the loop.</li>
+</ul>
+Note djnz instruction can be used for 8-bit values <em>only</em>, therefore
+it is advantageous to declare loop control symbols as <em>char</em>.
+Ofcourse this may not be possible on all situations.
+
+<p>
+ <h4><a name="tth_sEc4.1.6">
+4.1.6</a> Algebraic Simplifications</h4>
+
+<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>
+sub-set of these optimizations.<br />
+<br />
+<tt>i = j + 0 ; /* changed to */ i = j; </tt> <br />
+<tt>i /= 2; /* changed to */ i > >= 1; </tt> <br />
+<tt>i = j - j ; /* changed to */ i = 0; </tt> <br />
+<tt>i = j / 1 ; /* changed to */ i = j;</tt><br />
+<br />
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>
+ <h4><a name="tth_sEc4.1.7">
+4.1.7</a> 'switch' Statements</h4>
-<P>
+<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>
+<p>
+
+<ul><p>
+<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>
+<tt>switch(i) { switch (i)
+{ </tt> <br />
+<tt>case 4:... case 1: ... </tt> <br />
+<tt>case 5:... case 2: ... </tt> <br />
+<tt>case 3:... case 3: ... </tt> <br />
+<tt>case 6:... case 4: ... </tt> <br />
+<tt>} }</tt> <br />
+<tt></tt> <br />
Both the above switch statements will be implemented using a jump-table.
-<P>
+<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>
+<ul><p>
+<li> The number of case labels is at least three, since it takes two conditional
+statements to handle the boundary conditions.</li>
+<p>
+<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>
+switch statement for efficient code generation, e.g.:<br />
+<br />
+<tt>switch (i) { </tt> <br />
+<tt>case 1: ... </tt> <br />
+<tt>case 2: ... </tt> <br />
+<tt>case 3: ... </tt> <br />
+<tt>case 4: ... </tt> <br />
+<tt>case 9: ... </tt> <br />
+<tt>case 10: ... </tt> <br />
+<tt>case 11: ... </tt> <br />
+<tt>case 12: ... </tt> <br />
+<tt>}</tt><br />
+<br />
+If the above switch statement is broken down into two switch statements<br />
+<br />
+<tt>switch (i) { </tt> <br />
+<tt>case 1: ... </tt> <br />
+<tt>case 2: ... </tt> <br />
+<tt>case 3: ... </tt> <br />
+<tt>case 4: ... </tt> <br />
+<tt>}</tt> <br />
+<tt></tt> <br />
+and<tt></tt> <br />
+<tt></tt> <br />
+<tt>switch (i) { </tt> <br />
+<tt>case 9: ... </tt> <br />
+<tt>case 10: ... </tt> <br />
+<tt>case 11: ... </tt> <br />
+<tt>case 12: ... </tt> <br />
+<tt>}</tt> <br />
+<tt></tt> <br />
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>
+ <h4><a name="tth_sEc4.1.8">
+4.1.8</a> Bit-shifting Operations.</h4>
-<P>
+<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 char 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>
+efficient way possible, e.g.:<br />
+<br />
+unsigned char i;<br />
+... <br />
+i> >= 4; <br />
+...<br />
+<br />
+generates the following code:<br />
+<br />
+mov a,_i <br />
+swap a <br />
+anl a,#0x0f <br />
+mov _i,a<br />
+<br />
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>
+Another example:<br />
+<br />
+<tt>unsigned int i; </tt> <br />
+<tt>... </tt> <br />
+<tt>i > >= 9; </tt> <br />
+<tt>...</tt><br />
+<br />
+will generate:<br />
+<br />
+<tt>mov a,(_i + 1) </tt> <br />
+<tt>mov (_i + 1),#0x00 </tt> <br />
+<tt>clr c </tt> <br />
+<tt>rrc a </tt> <br />
+<tt>mov _i,a</tt><br />
+<br />
+Note that SDCC stores numbers in little-endian format (i.e. lowest
+order first).
+
+<p>
+ <h4><a name="tth_sEc4.1.9">
+4.1.9</a> Bit-rotation</h4>
+
+<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>
+the following expression to be a left bit-rotation:<br />
+<br />
+<tt>unsigned char i; </tt> <br />
+<tt>... </tt> <br />
+<tt>i = ((i < < 1) | (i > >
+7));</tt> <br />
+...<br />
+<br />
+will generate the following code:<br />
+<br />
+<tt>mov a,_i </tt> <br />
+<tt>rl a </tt> <br />
+<tt>mov _i,a</tt><br />
+<br />
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>
+of this case will also be recognized as bit-rotation, i.e.: <br />
+<br />
+<tt>i = ((i > > 7) | (i < <
+1)); /* left-bit rotation */</tt>
-<H3><A NAME="SECTION000511000000000000000">
-4.1.10 Highest Order Bit</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc4.1.10">
+4.1.10</a> Highest Order Bit</h4>
-<P>
+<p>
It is frequently required to obtain the highest order bit of an integral
type (long, int, 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>
+code for it, e.g.:<br />
+<br />
+ <tt>unsigned int gint; </tt> <br />
+<tt></tt> <br />
+<tt>foo () { </tt> <br />
+<tt>unsigned char hob; </tt> <br />
+<tt> ... </tt> <br />
+<tt> hob = (gint > > 15) & 1; </tt> <br />
+<tt> .. </tt> <br />
+<tt>}</tt><br />
+<br />
+will generate the following code:<br />
+<tt></tt> <br />
+<tt> 61
+; hob.c 7 </tt> <br />
+<tt> 000A E5*01 62
+mov a,(_gint + 1) </tt> <br />
+<tt> 000C 33 63
+rlc a </tt> <br />
+<tt> 000D E4 64
+clr a </tt> <br />
+<tt> 000E 13 65
+rrc a </tt> <br />
+<tt> 000F F5*02 66
+mov _foo_hob_1_1,a</tt> <br />
+<tt></tt> <br />
+Variations of this case however will <em>not</em> 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, e.g.:<br />
+<br />
+<tt>xyz = gint + ((gint > > 15) & 1);</tt><br />
+<br />
will still be recognized.
-<P>
-
-<H3><A NAME="SECTION000511100000000000000">
-4.1.11 Peep-hole Optimizer</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc4.1.11">
+4.1.11</a> Peep-hole Optimizer</h4>
-<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
+<p>
+The compiler uses a rule based, pattern matching and re-writing mechanism
+for peep-hole optimization. It is inspired by <em>copt</em> 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>
+be added with the <em>-peep-file <filename></em> option. The rule language
+is best illustrated with examples.<br />
+<br />
+<tt>replace { </tt> <br />
+<tt> mov %1,a </tt> <br />
+<tt> mov a,%1</tt> <br />
+<tt>} by {</tt> <br />
+<tt> mov %1,a</tt> <br />
+<tt>}</tt><br />
+<br />
+The above rule will change the following assembly sequence:<br />
+<br />
+<tt> mov r1,a </tt> <br />
+<tt> mov a,r1</tt><br />
+<br />
+to<br />
+<br />
+<tt>mov r1,a</tt><br />
+<br />
+Note: All occurrences of a <em>%n</em> (pattern variable) must denote
+the same string. With the above rule, the assembly sequence:<br />
+<br />
+<tt> mov r1,a </tt> <br />
+<tt> mov a,r2</tt><br />
+<br />
+will remain unmodified.<br />
+<br />
+Other special case optimizations may be added by the user (via <em>-peep-file
+option</em>). E.g. some variants of the 8051 MCU allow only <tt>ajmp</tt>
+and <tt>acall</tt>. The following two rules will change all <tt>ljmp</tt>
+and <tt>lcall</tt> to <tt>ajmp</tt> and <tt>acall</tt><br />
+<br />
+<tt>replace { lcall %1 } by { acall %1 } </tt> <br />
+<tt>replace { ljmp %1 } by { ajmp %1 }</tt><br />
+<br />
+The <em>inline-assembler code</em> 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.<br />
+<br />
+The syntax for a rule is as follows:<br />
+<br />
+<tt>rule := replace [ restart ] '{' <assembly sequence> 'n'
+</tt> <br />
+<tt> '}' by '{' 'n'
+</tt> <br />
+<tt> <assembly
+sequence> 'n' </tt> <br />
+<tt> '}' [if <functionName>
+] 'n' </tt> <br />
+<br />
+<assembly sequence> := assembly instruction (each instruction including
+labels must be on a separate line).<br />
+<br />
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
+exhausted. If the 'restart' 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>
+of this the following rule:<br />
+<br />
+replace restart { <br />
+ pop %1 <br />
+ push %1 } by { <br />
+ ; nop <br />
+}<br />
+<br />
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>
+line. Without the 'restart' option only the inner most 'pop' 'push'
+pair would be eliminated, i.e.:<br />
+<br />
+<tt> pop ar1 </tt> <br />
+<tt> pop ar2 </tt> <br />
+<tt> push ar2 </tt> <br />
+<tt> push ar1</tt><br />
+<br />
+would result in:<br />
+<br />
+<tt>pop ar1 </tt> <br />
+<tt>; nop </tt> <br />
+<tt>push ar1</tt><br />
+<br />
+<em>with</em> the restart option the rule will be applied again to the
+resulting code and then all the pop-push pairs will be eliminated
+to yield:<br />
+<br />
+<tt>; nop </tt> <br />
+<tt>; nop</tt><br />
+<br />
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>
+are somewhat more involved, let me illustrate this with an example.<br />
+<br />
+<tt>replace { </tt> <br />
+<tt> ljmp %5 </tt> <br />
+<tt>%2:} by { </tt> <br />
+<tt> sjmp %5 </tt> <br />
+<tt>%2:} if labelInRange</tt><br />
+<br />
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
+<em>callFuncByName</em> in the source file SDCCpeeph.c, with the name
+<em>labelInRange</em>. 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 <em>%5</em> is crucial, since the function
+<em>labelInRange</em> 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 labelInRange and the calling mechanism in source file SDCCpeeph.c.
+I know this whole thing is a little kludgey, but maybe 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 add your own rules in the default set there if you get tired
+of specifying the -peep-file option.
+
+<p>
+ <h3><a name="tth_sEc4.2">
+4.2</a> Pragmas</h3>
+
+<p>
+SDCC supports the following #pragma directives. This directives are
+applicable only at a function level.
+
+<p>
+
+<ul><p>
+<li> SAVE - this will save all the current options.</li>
+<p>
+<li> RESTORE - 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>
+<p>
+<li> NOGCSE - will stop global subexpression elimination.</li>
+<p>
+<li> NOINDUCTION - will stop loop induction optimizations.</li>
+<p>
+<li> NOJTBOUND - will not generate code for boundary value checking, when
+switch statements are turned into jump-tables.</li>
+<p>
+<li> NOOVERLAY - the compiler will not overlay the parameters and local
+variables of a function.</li>
+<p>
+<li> NOLOOPREVERSE - Will not do loop reversal optimization</li>
+<p>
+<li> EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - 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>
+<p>
+<li> CALLEE-SAVES function1[,function2[,function3...]] - 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>
+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>
+for a given function; pragmas should be placed before and/or after
+a function, placing pragma's inside a function body could have unpredictable
+results.
+
+<p>
+eg
+
+<p>
+#pragma SAVE /* save the current settings */ <br />
+#pragma NOGCSE /* turnoff global subexpression elimination */
+<br />
+#pragma NOINDUCTION /* turn off induction optimizations */ <br />
+int foo () <br />
+{ <br />
+ ... <br />
+ /* large code */ <br />
+ ... <br />
+} <br />
+#pragma RESTORE /* turn the optimizations back on */
+
+<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>
+<p>
+ <h3><a name="tth_sEc4.3">
+4.3</a> Library Routines</h3>
-<H2><A NAME="SECTION00053000000000000000">
-4.3 Library Routines</A>
-</H2>
-
-<P>
+<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 short/int </FONT>
-<BR><FONT SIZE="-2">%ld decimal long </FONT>
-<BR><FONT SIZE="-2">%hd decimal char </FONT>
-<BR><FONT SIZE="-2">%x hexadecimal short/int </FONT>
-<BR><FONT SIZE="-2">%lx hexadecimal long </FONT>
-<BR><FONT SIZE="-2">%hx hexadecimal char </FONT>
-<BR><FONT SIZE="-2">%o octal short/int
-</FONT>
-<BR><FONT SIZE="-2">%lo octal long </FONT>
-<BR><FONT SIZE="-2">%ho octal char </FONT>
-<BR><FONT SIZE="-2">%c character char </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">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>
+<p>
+stdio.h - Contains the following functions printf & sprintf these
+routines are developed by Martijn van Balen <balen@natlab.research.philips.com>.
+
+<p>
+%[flags][width][b|B|l|L]type
+
+<p>
+ flags: - left justify output in
+specified field width <br />
+ + prefix output with
++/- sign if output is signed type <br />
+ space prefix output with a
+blank if it's a signed positive value <br />
+ width: specifies minimum number
+of characters outputted for numbers <br />
+ or strings. <br />
+ - For numbers,
+spaces are added on the left when needed. <br />
+ If width starts
+with a zero character, zeroes and used <br />
+ instead of
+spaces. <br />
+ - For strings,
+spaces are are added on the left or right (when <br />
+ flag '-' is
+used) when needed. <br />
+ <br />
+ b/B: byte argument (used
+by d, u, o, x, X) <br />
+ l/L: long argument (used
+by d, u, o, x, X)<br />
+ type: d decimal number <br />
+ u unsigned decimal
+number <br />
+ o unsigned octal number
+<br />
+ x unsigned hexadecimal
+number (0-9, a-f) <br />
+ X unsigned hexadecimal
+number (0-9, A-F) <br />
+ c character <br />
+ s string (generic pointer)
+<br />
+ p generic pointer (I:data/idata,
+C:code, X:xdata, P:paged) <br />
+ f float (still to be
+implemented)
+
+<p>
+Also contains a very simple version of printf (printf_small). This
+simplified version of printf supports only the following formats.
+
+<p>
+format output type argument-type <br />
+%d decimal short/int <br />
+%ld decimal long <br />
+%hd decimal char <br />
+%x hexadecimal short/int <br />
+%lx hexadecimal long <br />
+%hx hexadecimal char <br />
+%o octal short/int <br />
+%lo octal long <br />
+%ho octal char <br />
+%c character char <br />
+%s character _generic pointer
+
+<p>
+The routine is very stack intesive, -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 putchar(char)
+to be present (this can be changed). When using the %s format the
+string / pointer should be cast to a generic pointer. eg.
+
+<p>
+printf_small(``my str %s, my int %dn'',(char
+_generic *)mystr,myint);
+
+<p>
+
+<ul><p>
+<li> stdarg.h - 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>
+<p>
+<li> setjmp.h - contains defintion for ANSI setjmp & longjmp 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>
+<p>
+<li> stdlib.h - contains the following functions.
+
+<p>
+atoi, atol.</li>
+<p>
+<li> string.h - contains the following functions.
+
+<p>
+strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr,
+strspn, strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp,
+memset.</li>
+<p>
+<li> ctype.h - contains the following routines.
+
+<p>
+iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
+isxdigit, isalnum, isalpha.</li>
+<p>
+<li> malloc.h - 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>
+//Example: <br />
+ // #define DYNAMIC_MEMORY_SIZE 0x2000 <br />
+ // ..... <br />
+ // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
+<br />
+ // unsigned char xdata * current_buffer; <br />
+ // ..... <br />
+ // void main(void) <br />
+ // { <br />
+ // ... <br />
+ // init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
+<br />
+ // //Now it's possible to use malloc. <br />
+ // ... <br />
+ // current_buffer = malloc(0x100); <br />
+ //</li>
+<p>
+<li> serial.h - 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>
+<p>
+<li> ser.h - 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>
+<p>
+<li> ser_ir.h - Another alternate set of serial routines provided by Josef
+Wolf <jw@raven.inka.de>, these routines do not use the external ram.</li>
+<p>
+<li> reg51.h - contains register definitions for a standard 8051</li>
+<p>
+<li> float.h - 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>
+<p>
+ <h3><a name="tth_sEc4.4">
+4.4</a> Interfacing with Assembly Routines</h3>
-<H2><A NAME="SECTION00055000000000000000">
-4.5 Global Registers used for Parameter Passing</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc4.5">
+4.5</a> Global Registers used for Parameter Passing</h3>
-<P>
+<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 char, unsigned char);</FONT>
-<P>
-
-
-<P>
-<FONT SIZE="-1"> </FONT>
-<BR><FONT SIZE="-1">int c_func (unsigned char i, unsigned char 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>
+<p>
+ <h4><a name="tth_sEc4.5.1">
+4.5.1</a> Assembler Routine(non-reentrant)</h4>
+
+<p>
+In the following example the function cfunc calls an assembler routine
+asm_func, which takes two parameters.
+
+<p>
+extern int asm_func(unsigned char, unsigned char);
+
+<p>
+ <br />
+int c_func (unsigned char i, unsigned char j) <br />
+{ <br />
+ return asm_func(i,j); <br />
+} <br />
+int main() <br />
+{ <br />
+ return c_func(10,9); <br />
+}
+
+<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>
+<p>
+ .globl _asm_func_PARM_2 <br />
+ .globl _asm_func <br />
+ .area OSEG <br />
+_asm_func_PARM_2: .ds 1 <br />
+ .area CSEG <br />
+_asm_func: <br />
+ mov a,dpl <br />
+ add a,_asm_func_PARM_2 <br />
+ mov dpl,a <br />
+ mov dpl,#0x00 <br />
+ ret
+
+<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>
+<p>
+The parameter naming convention is _<function_name>_PARM_<n>,
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>
-
+and ``acc,b,dptr'' for four bytes, the varaible name for the second
+parameter will be _<function_name>_PARM_2.
-<P>
+<p>
Assemble the assembler routine with the following command.
-<P>
+<p>
asx8051 -losg asmfunc.asm
-<P>
+<p>
Then compile and link the assembler routine to the C source file with
the following command,
-<P>
+<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 char, unsigned char);</FONT>
-<P>
+<p>
+ <h4><a name="tth_sEc4.5.2">
+4.5.2</a> Assembler Routine(reentrant)</h4>
+<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"> </FONT>
-<P>
-
-
-<P>
-<FONT SIZE="-1">int c_func (unsigned char i, unsigned char 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>
+extern int asm_func(unsigned char, unsigned char);
+<p>
+
-<P>
+<p>
+int c_func (unsigned char i, unsigned char j) reentrant <br />
+{ <br />
+ return asm_func(i,j); <br />
+} <br />
+int main() <br />
+{ <br />
+ return c_func(10,9); <br />
+}
+
+<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>
+<p>
+ .globl _asm_func <br />
+_asm_func: <br />
+ push _bp <br />
+ mov _bp,sp <br />
+ mov r2,dpl<br />
+ mov a,_bp <br />
+ clr c <br />
+ add a,#0xfd <br />
+ mov r0,a <br />
+ add a,#0xfc<br />
+ mov r1,a <br />
+ mov a,@r0 <br />
+ add a,r2<br />
+ mov dpl,a <br />
+ mov dph,#0x00 <br />
+ mov sp,_bp <br />
+ pop _bp <br />
+ ret
+
+<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>
+<p>
+ <h3><a name="tth_sEc4.6">
+4.6</a> External Stack</h3>
-<H2><A NAME="SECTION00056000000000000000">
-4.6 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
+<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>
+<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="SECTION00057000000000000000">
-4.7 ANSI-Compliance</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc4.7">
+4.7</a> ANSI-Compliance</h3>
-<P>
+<p>
Deviations from the compliancy.
-<P>
+<p>
-<OL>
-<LI>functions are not always reentrant.
-</LI>
-<LI>structures cannot be assigned values directly, cannot be passed as
+<ol type="1"><p>
+<li> functions are not always reentrant.</li>
+<p>
+<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
+<p>
+eg</li>
+</ol>
+struct s { ... }; <br />
+struct s s1, s2; <br />
+foo() <br />
+{ <br />
+... <br />
+s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ <br />
+... <br />
+}
+
+<p>
+struct s foo1 (struct s parms) /* is invalid in SDCC although allowed
+in ANSI */ <br />
+{ <br />
+struct s rets; <br />
+... <br />
+return rets;/* is invalid in SDCC although allowed in ANSI */
+<br />
+}
+
+<p>
+
+<ol type="1"><p>
+<li> 'long long' (64 bit integers) not supported.</li>
+<p>
+<li> 'double' precision floating point not supported.</li>
+<p>
+<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="SECTION00058000000000000000">
-4.8 Cyclomatic Complexity</A>
-</H2>
-
-<P>
+integer, exception is an assignment or parameter passing.</li>
+<p>
+<li> No support for setjmp and longjmp (for now).</li>
+<p>
+<li> Old K&R style function declarations are NOT allowed.</li>
+</ol>
+foo(i,j) /* this old style of function declarations */ <br />
+int i,j; /* are valid in ANSI .. not valid in SDCC */ <br />
+{ <br />
+... <br />
+}
+
+<p>
+
+<ol type="1"><p>
+<li> functions declared as pointers must be dereferenced during the call.
+
+<p>
+int (*foo)();</li>
+</ol>
+ ... <br />
+ /* has to be called like this */ <br />
+ (*foo)();/* ansi standard allows calls to be made like 'foo()'
+*/
+
+<p>
+ <h3><a name="tth_sEc4.8">
+4.8</a> Cyclomatic Complexity</h3>
+
+<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
by SDCC exceeds 10 you should think about simplification of the function
logic.
-<P>
+<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>
+complexity = (number of edges in control flow graph) - <br />
+ (number of nodes in control flow graph) + 2;
-<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
complexity of the function, it does however provide a good starting
point for which functions you might look at for further optimization.
-<P>
+<p>
+ <h2><a name="tth_sEc5">
+5</a> TIPS</h2>
-<H1><A NAME="SECTION00060000000000000000">
-5 TIPS</A>
-</H1>
-
-<P>
+<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>
+<p>
-<UL>
-<LI>Use the smallest data type to represent your data-value. If it is
+<ul><p>
+<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 'char' instead of a 'short' or 'int'.
-</LI>
-<LI>Use unsigned when it is known in advance that the value is not going
+use a 'char' instead of a 'short' or 'int'.</li>
+<p>
+<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
+multiplication.</li>
+<p>
+<li> NEVER jump into a LOOP.</li>
+<p>
+<li> Declare the variables to be local whenever possible, especially loop
+control variables (induction).</li>
+<p>
+<li> Since the compiler does not do implicit integral promotion, the programmer
+should do an explicit cast when integral promotion is required.</li>
+<p>
+<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>
+foobar(unsigned int p1, unsigned char ch)<br />
+{<br />
+ unsigned char ch1 = p1 % ch ;<br />
+ .... <br />
+}
-<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>
+foobar(unsigned int p1, unsigned char ch)<br />
+{<br />
+ unsigned char ch1 = (unsigned char)p1 % ch ;<br />
+ .... <br />
+}
-<P>
+<p>
It would substantially reduce the code generated (future versions
-of the compiler will be smart enough to detect such optimization oppurtunities).
+of the compiler will be smart enough to detect such optimization oppurtunities).</li>
+</ul>
+Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
-<P>
-</LI>
-</UL>
-<B>Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)</B>
-
-<P>
+<p>
The 8051 family of micro controller have a minimum of 128 bytes of
internal memory which is structured as follows
-<P>
+<p>
- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7
to R7
-<P>
+<p>
- Bytes 20-2F - 16 bytes to hold 128 bit variables and
-<P>
+<p>
- Bytes 30-7F - 60 bytes for general purpose use.
-<P>
+<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
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>
+<p>
By default, the compiler uses the 60 general purpose bytes to hold
-"near data". The compiler/optimiser may also declare
+"near data". The compiler/optimiser may also declare
some Local Variables in this area to hold local data.
-<P>
+<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
+"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,
+<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>
+<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>
+<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
+size of the "near data" increases, it may creep
into the bottom of the stack.
-<P>
+<p>
-stack-after-data, similar to the -stack-loc, but it automatically
-places the stack after the end of the "near data".
+places the stack after the end of the "near data".
Again this could waste any spare register space.
-<P>
+<p>
-data-loc allows you to specify the start address of the near data.
-This could be used to move the "near data" further
+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>
+<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
+<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>
+<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>
+ <h2><a name="tth_sEc6">
+6</a> Retargetting for other MCUs.</h2>
-<P>
+<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>
+<p>
-<OL>
-<LI>Parsing the source and building the annotated parse tree. This phase
+<ol type="1"><p>
+<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
+& 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
+like bit-rotation etc.</li>
+<p>
+<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
+form of the code generated by using the -dumpraw option.</li>
+<p>
+<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
+<p>
+
+<ul><p>
+<li> Break down intermediate code (iCode) into basic blocks.</li>
+<p>
+<li> Do control flow & data flow analysis on the basic blocks.</li>
+<p>
+<li> Do local common subexpression elimination, then global subexpression
+elimination</li>
+<p>
+<li> dead code elimination</li>
+<p>
+<li> loop optimizations</li>
+<p>
+<li> if loop optimizations caused any changes then do 'global subexpression
+elimination' and 'dead code elimination' again.</li>
+</ul></li>
+<p>
+<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.
+to registers, and for how long.</li>
+<p>
+<li> Phase five is register allocation. There are two parts to this process.
-<P>
+<p>
-<OL>
-<LI>The first part I call 'register packing' (for lack of a better term).
+<ol type="a"><p>
+<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
+register pressure.</li>
+<p>
+<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
+registers available in the 8051.</li>
+</ol></li>
+<p>
+<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>
+for each iCode operand may be reused.</li>
+<p>
+<li> As mentioned in the optimization section the peep-hole optimizer is
+rule based system, which can reprogrammed for other MCUs.</li>
+</ol>
-<H1><A NAME="SECTION00080000000000000000">
-7 SDCDB - Source Level Debugger</A>
-</H1>
+<p>
+ <h2><a name="tth_sEc7">
+7</a> SDCDB - Source Level Debugger</h2>
-<P>
+<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
+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>
+<p>
+ <h3><a name="tth_sEc7.1">
+7.1</a> Compiling for Debugging</h3>
+
+<p>
+The -debug option must be specified for all files for which debug
+information is to be generated. The complier generates a .cdb file
+for each of these files. The linker updates the .cdb file with the
+address information. This .cdb is used by the debugger.
+
+<p>
+ <h3><a name="tth_sEc7.2">
+7.2</a> How the Debugger Works</h3>
+
+<p>
+When the -debug 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>
+ <h3><a name="tth_sEc7.3">
+7.3</a> Starting the Debugger</h3>
+
+<p>
The debugger can be started using the following command line. (Assume
the file you are debugging has
-<P>
+<p>
the file name foo).
-<P>
->sdcdb foo
+<p>
+>sdcdb foo
-<P>
+<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>
-<P>
+<ol type="1"><p>
+<li> foo.c - the source file.</li>
+<p>
+<li> foo.cdb - the debugger symbol information file.</li>
+<p>
+<li> foo.ihx - the intel hex format object file.</li>
+</ol>
-<H2><A NAME="SECTION00084000000000000000">
-7.4 Command Line Options.</A>
-</H2>
+<p>
+ <h3><a name="tth_sEc7.4">
+7.4</a> Command Line Options.</h3>
-<P>
+<p>
-<UL>
-<LI>-directory=<source file directory> this option can used to specify
+<ul><p>
+<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
+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>
+spaces in the option.</li>
+<p>
+<li> -cd <directory> - change to the <directory>.</li>
+<p>
+<li> -fullname - used by GUI front ends.</li>
+<p>
+<li> -cpu <cpu-type> - this argument is passed to the simulator please
+see the simulator docs for details.</li>
+<p>
+<li> -X <Clock frequency > this options is passed to the simulator please
+see simulator docs for details.</li>
+<p>
+<li> -s <serial port file> passed to simulator see simulator docs for details.</li>
+<p>
+<li> -S <serial in,out> passed to simulator see simulator docs for details.</li>
+</ul>
+
+<p>
+ <h3><a name="tth_sEc7.5">
+7.5</a> Debugger Commands.</h3>
+
+<p>
As mention earlier the command interface for the debugger has been
-deliberately kept as close the GNU debugger gdb , as possible, this
+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>
+<p>
+ <h4><a name="tth_sEc7.5.1">
+7.5.1</a> break [line | file:line | function | file:function]</h4>
-<H3><A NAME="SECTION00085100000000000000">
-7.5.1 break [line | file:line | function | file:function]</A>
-</H3>
-
-<P>
+<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>
+<p>
+sdcdb>break 100 <br />
+sdcdb>break foo.c:100<br />
+sdcdb>break funcfoo<br />
+sdcdb>break foo.c:funcfoo
-<H3><A NAME="SECTION00085200000000000000">
-7.5.2 clear [line | file:line | function | file:function ]</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc7.5.2">
+7.5.2</a> clear [line | file:line | function | file:function ]</h4>
-<P>
+<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>
+sdcdb>clear 100<br />
+sdcdb>clear foo.c:100<br />
+sdcdb>clear funcfoo<br />
+sdcdb>clear foo.c:funcfoo
-<P>
+<p>
+ <h4><a name="tth_sEc7.5.3">
+7.5.3</a> continue</h4>
-<H3><A NAME="SECTION00085300000000000000">
-7.5.3 continue</A>
-</H3>
-
-<P>
+<p>
Continue program being debugged, after breakpoint.
-<P>
-
-<H3><A NAME="SECTION00085400000000000000">
-7.5.4 finish</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc7.5.4">
+7.5.4</a> finish</h4>
-<P>
+<p>
Execute till the end of the current function.
-<P>
-
-<H3><A NAME="SECTION00085500000000000000">
-7.5.5 delete [n]</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc7.5.5">
+7.5.5</a> delete [n]</h4>
-<P>
+<p>
Delete breakpoint number 'n'. If used without any option clear ALL
user defined break points.
-<P>
+<p>
+ <h4><a name="tth_sEc7.5.6">
+7.5.6</a> info [break | stack | frame | registers ]</h4>
-<H3><A NAME="SECTION00085600000000000000">
-7.5.6 info [break | stack | frame | registers ]</A>
-</H3>
+<p>
-<P>
+<ul><p>
+<li> info break - list all breakpoints</li>
+<p>
+<li> info stack - show the function call stack.</li>
+<p>
+<li> info frame - show information about the current execution frame.</li>
+<p>
+<li> info registers - show content of all registers.</li>
+</ul>
-<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>
+ <h4><a name="tth_sEc7.5.7">
+7.5.7</a> step</h4>
-<P>
-
-<H3><A NAME="SECTION00085700000000000000">
-7.5.7 step</A>
-</H3>
-
-<P>
+<p>
Step program until it reaches a different source line.
-<P>
-
-<H3><A NAME="SECTION00085800000000000000">
-7.5.8 next</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc7.5.8">
+7.5.8</a> next</h4>
-<P>
+<p>
Step program, proceeding through subroutine calls.
-<P>
+<p>
+ <h4><a name="tth_sEc7.5.9">
+7.5.9</a> run</h4>
-<H3><A NAME="SECTION00085900000000000000">
-7.5.9 run</A>
-</H3>
-
-<P>
+<p>
Start debugged program.
-<P>
-
-<H3><A NAME="SECTION000851000000000000000">
-7.5.10 ptype variable </A>
-</H3>
+<p>
+ <h4><a name="tth_sEc7.5.10">
+7.5.10</a> ptype variable </h4>
-<P>
+<p>
Print type information of the variable.
-<P>
-
-<H3><A NAME="SECTION000851100000000000000">
-7.5.11 print variable</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc7.5.11">
+7.5.11</a> print variable</h4>
-<P>
+<p>
print value of variable.
-<P>
+<p>
+ <h4><a name="tth_sEc7.5.12">
+7.5.12</a> file filename</h4>
-<H3><A NAME="SECTION000851200000000000000">
-7.5.12 file filename</A>
-</H3>
-
-<P>
+<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>
+ <h4><a name="tth_sEc7.5.13">
+7.5.13</a> frame</h4>
-<P>
+<p>
print information about current frame.
-<P>
+<p>
+ <h4><a name="tth_sEc7.5.14">
+7.5.14</a> set srcmode</h4>
-<H3><A NAME="SECTION000851400000000000000">
-7.5.14 set srcmode</A>
-</H3>
-
-<P>
+<p>
Toggle between C source & assembly source.
-<P>
-
-<H3><A NAME="SECTION000851500000000000000">
-7.5.15 ! simulator command</A>
-</H3>
+<p>
+ <h4><a name="tth_sEc7.5.15">
+7.5.15</a> ! simulator command</h4>
-<P>
+<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>
+ <h4><a name="tth_sEc7.5.16">
+7.5.16</a> quit.</h4>
-<P>
-"Watch me now. Iam going Down. My name is Bobby Brown"
+<p>
+"Watch me now. Iam going Down. My name is Bobby Brown"
-<P>
+<p>
+ <h3><a name="tth_sEc7.6">
+7.6</a> Interfacing with XEmacs.</h3>
-<H2><A NAME="SECTION00086000000000000000">
-7.6 Interfacing with XEmacs.</A>
-</H2>
-
-<P>
+<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
+XEmacs, sdcdb.el and sdcdbsrc.el. 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 '.xemacs' file (which can be found in your HOME directory) (load-file
+sdcdbsrc.el) [ .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 'EMACSLOADPATH' to the installation
+bin directory [$(prefix)/bin], then enter the following command
+ESC-x load-file sdcdbsrc. To start the interface enter the following
+command ESC-x sdcdbsrc, you will prompted to enter the file name to
be debugged.
-<P>
+<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 bound to default values in the file sdcdbsrc.el the variables
are listed below these values maybe changed as required.
-<P>
+<p>
-<UL>
-<LI>sdcdbsrc-cpu-type '51
-</LI>
-<LI>sdcdbsrc-frequency '11059200
-</LI>
-<LI>sdcdbsrc-serial nil
-</LI>
-</UL>
+<ul><p>
+<li> sdcdbsrc-cpu-type '51</li>
+<p>
+<li> sdcdbsrc-frequency '11059200</li>
+<p>
+<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>
+<p>
+ <br />
+;; Current Listing :: <br />
+;;key binding Comment
+<br />
+;;- --- ---
+<br />
+;; <br />
+;; n sdcdb-next-from-src SDCDB
+next command <br />
+;; b sdcdb-back-from-src SDCDB
+back command <br />
+;; c sdcdb-cont-from-src SDCDB
+continue command<br />
+;; s sdcdb-step-from-src SDCDB
+step command <br />
+;; ? sdcdb-whatis-c-sexp SDCDB
+ptypecommand for data at <br />
+;;
+buffer point <br />
+;; x sdcdbsrc-delete SDCDB
+Delete all breakpoints if no arg <br />
+;; given
+or delete arg (C-u arg x) <br />
+;; m sdcdbsrc-frame SDCDB
+Display current frame if no arg, <br />
+;; given
+or display frame arg <br />
+;; buffer
+point <br />
+;; ! sdcdbsrc-goto-sdcdb Goto
+the SDCDB output buffer <br />
+;; p sdcdb-print-c-sexp SDCDB
+print command for data at <br />
+;;
+buffer point <br />
+;; g sdcdbsrc-goto-sdcdb Goto
+the SDCDB output buffer <br />
+;; t sdcdbsrc-mode Toggles
+Sdcdbsrc mode (turns it off) <br />
+;; <br />
+;; C-c C-f sdcdb-finish-from-src SDCDB
+finish command <br />
+;; <br />
+;; C-x SPC sdcdb-break Set
+break for line with point <br />
+;; ESC t sdcdbsrc-mode Toggle
+Sdcdbsrc mode <br />
+;; ESC m sdcdbsrc-srcmode
+Toggle list mode <br />
+;; <br />
+
+<p>
+ <h2><a name="tth_sEc8">
+8</a> Other Processors</h2>
+
+<p>
+ <h3><a name="tth_sEc8.1">
+8.1</a> The Z80 and gbz80 port</h3>
+
+<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>
+<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
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>
+ <h2><a name="tth_sEc9">
+9</a> Support</h2>
-<P>
+<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
SDCC users. There are lots of ways to contribute, and we encourage
you to take part in making SDCC a great software package.
-<P>
+<p>
+ <h3><a name="tth_sEc9.1">
+9.1</a> Reporting Bugs</h3>
-<H2><A NAME="SECTION000101000000000000000">
-9.1 Reporting Bugs</A>
-</H2>
-
-<P>
+<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
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>
+ <h3><a name="tth_sEc9.2">
+9.2</a> Acknowledgments</h3>
-<P>
+<p>
Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code
-generator, Debugger, AVR port
-<BR>
+generator, Debugger, AVR port<br />
Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX
-& ASLINK.
-<BR>
+& 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>
+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
+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>
+who you are :-)<br />
+
+<p>
This document initially written by Sandeep Dutta
-<P>
+<p>
All product names mentioned herein may be trademarks of their respective
companies.
-<P>
-<A NAME="1227"></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_tmpdir14474Rxoof/lyx_tmpbuf1447IsYCoR/SDCCUdoc.tex</TT>
-<P>
-The translation was initiated by Karl Bongers on 2001-07-04
-<BR><HR><H4>Footnotes</H4>
-<DL>
-<DT><A NAME="foot456">... anyway</A><A NAME="foot456"
- HREF="SDCCUdoc.html#tex2html1"><SUP>1</SUP></A>
-<DD>possible exception: if a function is called ONLY from 'interrupt'
+<p>
+<hr /><h3>Footnotes:</h3>
+
+<p>
+<a name="tthFtNtAAB"></a><a href="#tthFrefAAB"><sup>1</sup></a>possible exception: if a function is called ONLY from 'interrupt'
functions using a particular bank, it can be declared with the same
'using' attribute as the calling 'interrupt' functions. For instance,
if you have several ISRs using bank one, and all of them call memcpy(),
1', since this would prevent the ISR from having to save bank zero
to the stack on entry and switch to bank zero before calling the function
-
-</DL><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-04
-</ADDRESS>
-</BODY>
-</HTML>
+<br /><br /><hr /><small>File translated from
+T<sub><font size="-1">E</font></sub>X
+by <a href="http://hutchinson.belmont.ma.us/tth/">
+T<sub><font size="-1">T</font></sub>H</a>,
+version 3.01.<br />On 5 Jul 2001, 17:34.</small>
+</html>
\layout Standard
+\emph on
+<pending: tabularise these features, this is unreadeble>
+\newline
+
+\newline
+
\series bold
+\emph default
SDCC
\series default
is a Free ware, retargettable, optimizing ANSI-C compiler by
is MCU dependent.
Supported data-types are
\emph on
-char (8 bits, 1 byte), short and int (16 bits, 2 bytes ), long (32 bit,
- 4 bytes)
+char (8 bits, 1 byte), short and int (16 bits, 2 bytes), long (32 bit, 4
+ bytes)
\emph default
and
\emph on
\emph on
opensource
\emph default
- (freeware); source code for all the sub-packages (asxxxx assembler/linker,
- pre-processor) are distributed with the package.
+ and
+\emph on
+freeware
+\emph default
+; source code for all the sub-packages (asxxxx assembler/linker, pre-processor)
+ is distributed with the package.
This documentation is maintained using a freeware word processor (LyX).
\layout Standard
You are forbidden to forbid anyone else to use, share and improve what
you give them.
Help stamp out software-hoarding!
+\newline
+
+\newline
+
+\emph on
+<pending: add a link to gnu>
\layout Subsection
Typographic conventions
italicised type.
\layout Subsection
+Pending: compatibilaty with previous versions
+\layout Standard
+
+This version has numerous bug fixes comperated with the previous version.
+ But we also introduced some incompatibilaties with older versions.
+ Not just for the fun of it, but to make the compiler more stable, efficient
+ and ANSI compliant.
+
+\newline
+
+\newline
+short char
+\newline
+directory structure (2.7)
+\newline
+vararg pars expl int unless casted
+\newline
+never had a regextend
+\newline
+no --noreparms anymore
+\newline
+
+\newline
+more?
+\layout Subsection
+
System Requirements
\layout Standard
Windows Installation
\layout Standard
+
+\emph on
+<pending: is this complete? where is borland, mingw>
+\newline
+
+\newline
+
+\emph default
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.
\series medium
Download and install the cygwin package from the redhat site
\series default
-\emph on
\begin_inset LatexCommand \htmlurl{http://sources.redhat.com/cygwin/}
\series medium
-\emph default
.
Currently, this involved downloading a small install program which then
automates downloading and installing
\series medium
header files and libraries.
Edit test.c and change it to the following:
-\layout LyX-Code
+\series default
-#include <string.h>
-\layout LyX-Code
+\newline
+\newline
+#include <string.h>
+\newline
main() {
-\layout LyX-Code
+\newline
-
\family typewriter
char str1[10];
-\layout LyX-Code
-
-
-\family typewriter
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
strcpy(str1, "testing");
-\layout LyX-Code
-
-
-\family typewriter
+\newline
}
-\layout LyX-Code
-
-\layout Standard
+\newline
+\newline
+\family default
\series medium
Compile this by typing
\family sans
\family sans
\series bold
-"sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include test.c"
+"sdcc\SpecialChar ~
+-L\SpecialChar ~
+/usr/local/sdcc/lib/small\SpecialChar ~
+-I\SpecialChar ~
+/usr/local/sdcc/include\SpecialChar ~
+test.c"
\family default
\series default
.
Additional Information for Windows Users
\layout Standard
+
+\emph on
+<pending: is this up to date?>
+\newline
+
+\newline
+
+\emph default
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
\newline
-\layout Standard
-
+\newline
bin/ - binary exectables (add to PATH environment variable)
-\layout Standard
-
+\newline
bin/share/
-\layout Standard
-
+\newline
bin/share/sdcc/include/ - include header files
-\layout Standard
-
+\newline
bin/share/sdcc/lib/
-\layout Standard
-
+\newline
bin/share/sdcc/lib/small/ - Object & library files for small model library
-\layout Standard
-
+\newline
bin/share/sdcc/lib/large/ - Object & library files for large model library
-\layout Standard
-
+\newline
bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390 library
\newline
At the time of this writing, we find the following programs:
\newline
-\layout Standard
+\newline
+
+\emph on
+<pending: tabularize this>
+\emph default
+\newline
+
+\newline
\series bold
sdcc
\series default
- The compiler.
-\layout Standard
-
+\newline
\series bold
-aslink
+sdcpp
\series default
- -The linker for 8051 type processors.
-\layout Standard
-
+ - The C preprocessor.
+\newline
\series bold
asx8051
\series default
- The assembler for 8051 type processors.
-\layout Standard
-
-
-\series bold
-sdcpp
-\series default
- - The C preprocessor.
-\layout Standard
-
+\newline
\series bold
-sdcdb
+as-z80, as-gbz80
\series default
- - The source debugger.
-\layout Standard
-
+ - The Z80 and GameBoy Z80 assemblers.
+\newline
\series bold
-s51
+aslink
\series default
- - The ucSim 8051 simulator.
-\layout Standard
-
+ -The linker for 8051 type processors.
+\newline
\series bold
link-z80, link-gbz80
\series default
- The Z80 and GameBoy Z80 linkers.
-\layout Standard
-
+\newline
\series bold
-as-z80, as-gbz80
+s51
\series default
- - The Z80 and GameBoy Z80 assemblers.
-\layout Standard
+ - The ucSim 8051 simulator.
+\newline
+\series bold
+sdcdb
+\series default
+ - The source debugger.
+\newline
\series bold
packihx
executables to support processors like AVR, PIC, etc.
\layout Subsubsection
-cpp ( C-Preprocessor)
+sdcc - The Compiler
+\layout Standard
+
+This is the actual compiler, it in turn uses the c-preprocessor and invokes
+ the assembler and linkage editor.
+\layout Subsubsection
+
+sdcpp (C-Preprocessor)
\layout Standard
The preprocessor is a modified version of the GNU preprocessor.
statements, #defines and so on.
\layout Subsubsection
-asxxxx & aslink ( The Assembler and Linkage Editor)
+asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 (The Assemblers
+ and Linkage Editors)
\layout Standard
This is retargettable assembler & linkage editor, it was developed by Alan
enhancements and bug fixes for it to work properly with the SDCC.
\layout Subsubsection
-sdcc - The Compiler
-\layout Standard
-
-This is the actual compiler, it in turn uses the c-preprocessor and invokes
- the assembler and linkage editor.
-\layout Subsubsection
-
s51 - Simulator
\layout Standard
-S51 is a freeware, opensource simulator developed by Daniel Drotos
+S51 is a freeware, opensource simulator developed by Daniel Drotos (
\begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
\end_inset
-.
- The executable is built as part of the build process.
- For more information visit Daniel's website at
+).
+ The simulator is built as part of the build process.
+ For more information visit Daniel's website at:
\begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
\end_inset
-.
+ .
\layout Subsubsection
sdcdb - Source Level Debugger
\family default
\series default
This will compile, assemble and link your source file.
- Output files are as follows.
-\layout Itemize
-
+ Output files are as follows
+\newline
-\size footnotesize
+\newline
sourcefile.asm - Assembler source file created by the compiler
-\layout Itemize
-
-
-\size footnotesize
+\newline
sourcefile.lst - Assembler listing file created by the Assembler
-\layout Itemize
-
-
-\size footnotesize
-sourcefile.rst - Assembler listing file updated with linkedit information
- , created by linkage editor
-\layout Itemize
-
-
-\size footnotesize
-sourcefile.sym - symbol listing for the sourcefile, created by the assembler.
-\layout Itemize
-
-
-\size footnotesize
-sourcefile.rel - Object file created by the assembler, input to Linkage editor.
-\layout Itemize
-
-
-\size footnotesize
-sourcefile.map - The memory map for the load module, created by the Linker.
-\layout Itemize
-
-
-\size footnotesize
+\newline
+sourcefile.rst - Assembler listing file updated with linkedit information,
+ created by linkage editor
+\newline
+sourcefile.sym - symbol listing for the sourcefile, created by the assembler
+\newline
+sourcefile.rel - Object file created by the assembler, input to Linkage editor
+\newline
+sourcefile.map - The memory map for the load module, created by the Linker
+\newline
sourcefile.ihx - The load module in Intel hex format (you can select the
Motorola S19 format with --out-fmt-s19)
-\layout Itemize
+\newline
+sourcefile.cdb - An optional file (with --debug) containing debug information
+\newline
-sourcefile.cdb - An optional file (with --debug) containing debug information.
\layout Subsubsection
Projects with Multiple Source Files
SDCC can compile only ONE file at a time.
Let us for example assume that you have a project containing the following
- files.
+ files:
\newline
-\layout Standard
-
+\newline
+foo1.c (contains some functions)
+\newline
+foo2.c (contains some more functions)
+\newline
+foomain.c (contains more functions and the function main)
+\newline
\size footnotesize
-foo1.c ( contains some functions )
-\layout Standard
+\newline
+\size default
+The first two files will need to be compiled separately with the commands:
\size footnotesize
-foo2.c (contains some more functions)
-\layout Standard
-
+
+\size default
-\size footnotesize
-foomain.c (contains more functions and the function main)
\newline
\newline
-\size default
-The first two files will need to be compiled separately with the commands
-\size footnotesize
-
\family sans
\series bold
-\size default
-"sdcc\SpecialChar ~
+sdcc\SpecialChar ~
-c\SpecialChar ~
-foo1.c"
+foo1.c
\family default
\series default
\size footnotesize
- and
+
+\newline
+
\family sans
\series bold
\size default
-"sdcc\SpecialChar ~
+sdcc\SpecialChar ~
-c\SpecialChar ~
-foo2.c"
+foo2.c
\family default
\series default
-\size footnotesize
-.
-
-\size default
-Then compile the source file containing the main() function and link the
- files together with the following command:
+
+\newline
+
+\newline
+Then compile the source file containing the
+\emph on
+main()
+\emph default
+ function and link the files together with the following command:
+\newline
+
+\newline
+
\family sans
\series bold
-"sdcc\SpecialChar ~
+sdcc\SpecialChar ~
foomain.c\SpecialChar ~
foo1.rel\SpecialChar ~
-foo2.rel"
+foo2.rel
\family default
\series default
-.
- Alternatively, foomain.c
+
+\newline
+
+\newline
+Alternatively,
\emph on
-
+foomain.c
\emph default
can be separately compiled as well:
\family sans
\series bold
-"sdcc\SpecialChar ~
--c\SpecialChar ~
-foomain.c"
-\family default
-\series default
-\size footnotesize
- and
-\family sans
-\series bold
-\size default
-\begin_inset Quotes sld
-\end_inset
+\newline
-sdcc foomain.rel foo1.rel foo2.rel"
+\newline
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foomain.c
+\newline
+sdcc foomain.rel foo1.rel foo2.rel
\newline
\newline
\family default
\series default
-The file containing the main function
+The file containing the
\emph on
-must
+main()
\emph default
- be the
+ function
\emph on
-first
+
\emph default
+\noun on
+must
+\noun default
+ be the
+\noun on
+first
+\noun default
file specified in the command line, since the linkage editor processes
file in the order they are presented to it.
\layout Subsubsection
\layout Standard
Some reusable routines may be compiled into a library, see the documentation
- for the assembler and linkage editor in the directory
-\emph on
-SDCCDIR/asxxxx/asxhtm.htm
-\emph default
-this describes how to create a
+ for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
+ for how to create a
\emph on
.lib
\emph default
- 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.
+ library file.
+ Libraries created in this manner can be included in the command line.
+ Make sure you include the -L <library-path> option to tell the linker where
+ to look for these files if they are not in the current directory.
Here is an example, assuming you have the source file
\emph on
-'foomain.c
+foomain.c
\emph default
-' and a library
+ and a library
\emph on
- 'foolib.lib'
+ foolib.lib
\emph default
in the directory
\emph on
-'mylib
+mylib
\emph default
-' (if that is not the same as your current project).
-\layout Standard
+ (if that is not the same as your current project):
+\newline
+\newline
-\size footnotesize
+\family sans
+\series bold
sdcc foomain.c foolib.lib -L mylib
-\layout Standard
+\newline
+
+\newline
-Note here that
+\family default
+\series default
+Note here that
\emph on
-'mylib
+ mylib
\emph default
-' must be an absolute path name.
-\layout Standard
+ must be an absolute path name.
+\newline
-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.
+\newline
+The most efficient way to use libraries is to keep seperate modules in seperate
+ source files.
+ The lib file now should name all the modules.rel files.
+ For an example see the standard library file
+\emph on
+libsdcc.lib
+\emph default
+ in the directory <installdir>/share/lib/small.
\layout Subsection
Command Line Options
\series bold
--code-loc
\series default
-<Value> The start location of the code segment , default value 0.
+<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, e.g.: --code-loc
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.
+ In addition the standard library routines are compiled with small model,
+ they will need to be recompiled.
\layout List
\labelwidthstring 00.00.0000
Generate code for Small Model programs see section Memory Models for more
details.
This is the default model.
+\layout Subsubsection
+
+DS390 Options
\layout List
\labelwidthstring 00.00.0000
\series bold
---xstack
+--model-flat24
\series default
- 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.
+\size large
+\emph on
+
+\size default
+\emph default
+Generate 24-bit flat mode code.
+ This is the one and only that the ds390 code generator supports right now
+ and is default when using
+\emph on
+-mds390
+\emph default
+.
+ See section Memory Models for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+--stack-10bit
+\series default
+ Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
+ This is the one and only that the ds390 code generator supports right now
+ and is default when using
+\emph on
+-mds390
+\emph default
+.
+ 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
+ will 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
+\emph on
+--stack-auto
+\emph default
+ option, but that has not been tested.
+ It is incompatible with the
+\emph on
+--xstack
+\emph default
+ option.
+ It also only makes sense if the processor is in 24 bit contiguous addressing
+ mode (see the
+\emph on
+--model-flat24 option
+\emph default
+).
\layout Subsubsection
Optimization Options
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
+ It recommended that this option NOT be used, #pragma\SpecialChar ~
+NOGCSE can be used
to turn off global subexpression elimination for a given function only.
\layout List
\labelwidthstring 00.00.0000
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
+ recommended that this option NOT be used, #pragma\SpecialChar ~
+NOINVARIANT can be used
to turn off invariant optimizations for a given function only.
\layout List
\labelwidthstring 00.00.0000
\series bold
--noinduction
\series default
- Will not do loop induction optimizations, see section Strength reduction
- for more details.It recommended that this option NOT be used , #pragma NOINDUCTI
-ON can be used to turn off induction optimizations for given function only.
+ Will not do loop induction optimizations, see section strength reduction
+ for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
+NOINDUCT
+ION can be used to turn off induction optimizations for a given function
+ only.
\layout List
\labelwidthstring 00.00.0000
\bar default
Will not generate boundary condition check when switch statements are implement
ed 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.
+ See section Switch Statements for more details.
+ It is recommended that this option is NOT used, #pragma\SpecialChar ~
+NOJTBOUND can be
+ used to turn off boundary checking for jump tables for a given function
+ only.
\layout List
\labelwidthstring 00.00.0000
\size large
\size default
-Will not do loop reversal optimization
-\layout Subsubsection
-
-DS390 Options
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
---model-flat24
-\series default
-\size large
-\emph on
-
-\size default
-\emph default
-Generate 24-bit flat mode code.
- This is the one and only that the ds390 code generator supports right now
- and is default when using -mds390.
- See section Memory Models for more details.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
---stack-10bit
-\series default
- Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
- This is the one and only that the ds390 code generator supports right now
- and is default when using -mds390.
- 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
- will 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).
+Will not do loop reversal optimization.
\layout Subsubsection
Other Options
\labelwidthstring 00.00.0000
+\series bold
+--xstack
+\series default
+ 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.
+\layout List
+\labelwidthstring 00.00.0000
+
+
\series bold
--callee-saves function1[,function2][,function3]....
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.
+ Also see #pragma\SpecialChar ~
+CALLEE-SAVES.
\layout List
\labelwidthstring 00.00.0000
\series default
\bar default
-When this option is used the compiler will generate debug information ,
- that can be used with the SDCDB.
+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.
\layout List
\series default
\bar default
-Will create a dump of iCode's, after register assignment , into a file named
+Will create a dump of iCode's, after register assignment, into a file named
\emph on
<source filename>.dumprassgn.
\layout Standard
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
+ When a variable is declared as a bit, it is allocated into the bit addressable
memory of 8051, e.g.:
\newline
\newline
\newline
-Pointer declaration examples.
+Pointer declaration examples:
\newline
\size small
\size default
Well you get the idea.
- For compatibility with the previous version of the compiler, the following
+
+\newline
+
+\newline
+
+\emph on
+For compatibility with the previous version of the compiler, the following
syntax for pointer declaration is still supported but will disappear int
the near future.
/* pointer to upper 128 bytes of ram */
\family default
\size small
+\emph default
\newline
\newline
\size default
-All unqualified pointers are treated as 3-byte (4-byte for the ds390) '_generic'
+All unqualified pointers are treated as 3-byte (4-byte for the ds390)
+\emph on
+generic
+\emph default
pointers.
These type of pointers can also to be explicitly declared.
\newline
\newline
\size default
-The highest order byte of the generic pointers contains the data space informati
-on.
+The highest order byte of the
+\emph on
+generic
+\emph default
+ pointers contains the data space information.
Assembler support routines are called whenever data is stored or retrieved
- using _generic pointers.
+ using
+\emph on
+generic
+\emph default
+ 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
+ Pointers declared using a mixture of OLD and NEW style could have unpredictable
results.
\layout Subsection
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
+ RAM (for small model) or external RAM (for Large model).
+ This in fact makes them
+\emph on
+static
+\emph default
+ so by default functions are non-reentrant.
+\layout Standard
+
+They can be placed on the stack either by using the
\emph on
--stack-auto
\emph default
- compiler option or by using the 'reentrant' keyword in the function declaration
-, e.g.:
+ compiler option or by using the
+\emph on
+reentrant
+\emph default
+ keyword in the function declaration, e.g.:
\newline
\size small
\family typewriter
\size default
-unsigned char foo( char i) reentrant
+unsigned char foo(char i) reentrant
\newline
{
\newline
\family default
\newline
-Note that when the parameters & local variables are declared in the internal/ext
-ernal ram the functions are non-reentrant.
- Since stack space on 8051 is limited the
+Since stack space on 8051 is limited, the
\emph on
-'reentrant'
+reentrant
\emph default
keyword or the
\emph on
--stack-auto
\emph default
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.
-\layout Standard
+ Note that the reentrant keyword just means that the parameters & local
+ variables will be allocated to the stack, it
+\emph on
+does not
+\emph default
+ mean that the function is register bank independent.
+\newline
-When compiled with the default option (i.e.
- non-reentrant ), local variables can be assigned storage classes and absolute
- addresses, e.g.: (jwk: pending: this is obsolete and need a rewrite)
+\newline
+Local variables can be assigned storage classes and absolute addresses,
+ e.g.:
\newline
\newline
\family typewriter
unsigned char foo() {
-\layout Standard
-
-
-\family typewriter
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
xdata unsigned char i;
-\layout Standard
-
-
-\family typewriter
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
bit bvar;
-\layout Standard
-
-
-\family typewriter
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
data at 0x31 unsiged char j;
-\layout Standard
-
-
-\family typewriter
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
...
\newline
}
-\layout Standard
+\newline
+\newline
+
+\family default
In the above example the variable
\emph on
i
j
\emph default
in internal ram.
- When compiled with the
+ When compiled with
\emph on
--stack-auto
\emph default
or when a function is declared as
\emph on
-'reentrant'
+reentrant
\emph default
- local variables cannot be assigned storage classes or absolute addresses.
+ this can only be done for static variables.
\layout Standard
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.
+ model in use, and the reentrancy options.
\layout Subsection
Overlaying
model is small.
\emph default
- If an explicit storage class is specified for a local variable , it will
- NOT be overplayed.
+ If an explicit storage class is specified for a local variable, it will
+ NOT be overlayed.
\layout Standard
Note that the compiler (not the linkage editor) makes the decision for overlayin
g 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.
+ by a #pragma\SpecialChar ~
+NOOVERLAY if they are not reentrant.
+\layout Standard
+
+Also note that the compiler does not do any processing of inline assembler
+ code, so the compiler might incorrectly assign local variables and parameters
+ of a function into the overlay segment if the inline assembler code calls
+ other c-functions that might use the overlay.
+ In that case the #pragma\SpecialChar ~
+NOOVERLAY should be used.
\layout Standard
Parameters and Local variables of functions that contain 16 or 32 bit multiplica
\newline
#pragma NOOVERLAY
\newline
-void set_error( unsigned char errcd)
+void set_error(unsigned char errcd)
\newline
{
\newline
\newline
}
-\layout Standard
+\newline
+\newline
+
+\family default
In the above example the parameter
\emph on
errcd
\emph on
set_error
\emph default
- would be assigned to the overlayable segment (if the #pragma NOOVERLAY
- was not present) , this could cause unpredictable runtime behavior when
- called from an ISR.
- The pragma NOOVERLAY ensures that the parameters and local variables for
+ would be assigned to the overlayable segment if the #pragma\SpecialChar ~
+NOOVERLAY was
+ not present, this could cause unpredictable runtime behavior when called
+ from an ISR.
+ The #pragma\SpecialChar ~
+NOOVERLAY ensures that the parameters and local variables for
the function are NOT overlayed.
\layout Subsection
\newline
\family default
-The number following the 'interrupt' keyword is the interrupt number this
- routine will service.
+The number following the
+\emph on
+interrupt
+\emph default
+ 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.
+ The
+\emph on
+using
+\emph default
+ 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).
+ it should be preceded by a #pragma\SpecialChar ~
+NOOVERLAY if it is not reentrant.
A special note here, int (16 bit) and long (32 bit) integer division, multiplic
ation & 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.
+ section) will have to be recompiled using the
+\emph on
+ --stack-auto
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+--int-long-ren
+\emph default
+t compiler option.
\layout Standard
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
+ or included in the file that contains the function
\emph on
-'main'
+main
\emph default
.
\layout Standard
\newline
-\layout Standard
-
+\newline
If the interrupt service routine is defined without
\emph on
-'using'
+using
\emph default
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
+ 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.
If the interrupt service routine is defined to be using a specific register
bank then only
-\begin_inset Quotes eld
-\end_inset
+\emph on
+a, b & dptr
+\emph default
+ 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.
+\layout Standard
-a
-\begin_inset Quotes erd
-\end_inset
+Calling other functions from an interrupt service routine is not recommended,
+ avoid it if possible.
+\newline
-,
-\begin_inset Quotes erd
-\end_inset
-
-b
-\begin_inset Quotes erd
-\end_inset
-
- &
-\begin_inset Quotes eld
-\end_inset
-
-dptr
-\begin_inset Quotes erd
-\end_inset
-
- 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.
-\layout Standard
-
-Calling other functions from an interrupt service routine is not recommended
- avoid it if possible.
-\layout Subsection
+\newline
+Also see the _naked modifier.
+\layout Subsection
Critical Functions
\layout Standard
-A special keyword may be associated with a function declaring it as '
+A special keyword may be associated with a function declaring it as
\emph on
critical
\emph default
-'.
+.
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.
-
\newline
\size small
A special keyword may be associated with a function declaring it as
\emph on
-'_naked'.
+_naked.
\emph default
The
\emph on
-'_naked'
+_naked
\emph default
function modifier attribute prevents the compiler from generating prologue
and epilogue code for that function.
any registers that may need to be preserved, selecting the proper register
bank, generating the
\emph on
-'return'
+return
\emph default
instruction at the end, etc.
Practically, this means that the contents of the function must be written
\family typewriter
data unsigned char counter;
\newline
-void simpleIterrupt(void) interrupt 1
+void simpleInterrupt(void) interrupt 1
\newline
{
\newline
The
\emph on
-'using'
+using
\emph default
attribute (which tells the compiler to use a register bank other than the
- default bank zero) should only be applied to 'interrupt' functions (see
- note A below).
+ default bank zero) should only be applied to
+\emph on
+interrupt
+\emph default
+ functions (see note 1 below).
This will in most circumstances make the generated ISR code more efficient
since it will not have to save registers on the stack.
\layout Standard
The
\emph on
-'using'
+using
\emph default
attribute will have no effect on the generated code for a
\emph on
-non-'interrupt'
+non-interrupt
\emph default
function (but may occasionally be useful anyway
\begin_float footnote
\end_float
).
\newline
-(jwk: todo: I don't think this has been done yet)
+
+\emph on
+(pending: I don't think this has been done yet)
\layout Standard
-An 'interrupt' function using a non-zero bank will assume that it can trash
- that register bank, and will not save it.
+An
+\emph on
+interrupt
+\emph default
+ function using a non-zero bank will assume that it can trash that register
+ bank, and will not save it.
Since high-priority interrupts can interrupt low-priority ones on the 8051
- and friends, this means that if a high-priority ISR 'using' a particular
- bank occurs while processing a low-priority ISR 'using' the same bank,
- terrible and bad things can happen.
- To prevent this, no single register bank should be 'used' by both a high
- priority and a low priority ISR.
+ and friends, this means that if a high-priority ISR
+\emph on
+using
+\emph default
+ a particular bank occurs while processing a low-priority ISR
+\emph on
+using
+\emph default
+ the same bank, terrible and bad things can happen.
+ To prevent this, no single register bank should be
+\emph on
+used
+\emph default
+ by both a high priority and a low priority ISR.
This is probably most easily done by having all high priority ISRs use
one bank and all low priority ISRs use another.
If you have an ISR which can change priority at runtime, you're on your
It is most efficient if your ISR calls no other functions.
If your ISR must call other functions, it is most efficient if those functions
- use the same bank as the ISR (see note A below); the next best is if the
+ use the same bank as the ISR (see note 1 below); the next best is if the
called functions use bank zero.
It is very inefficient to call a function using a different, non-zero bank
from an ISR.
\family default
\newline
-In the above example the
-\emph on
-PORTA_8255
-\emph default
- will be allocated to the location 0x8000 of the external ram.
+In the above example the PORTA_8255 will be allocated to the location 0x8000
+ of the external ram.
Note that this feature is provided to give the programmer access to
\emph on
memory mapped
\emph default
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>.m
-ap) are a good places to look for such overlaps.
+ 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 (.rst) and
+ (.map) are a good places to look for such overlaps.
\newline
\newline
The above example will allocate the variable at offset 0x02 in the bit-addressab
le 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.
+ in this manner, unless you want strict control over all the variables allocated.
\layout Subsection
Startup Code
\layout Standard
-The compiler inserts a jump to the C routine
+The compiler inserts a call to the C routine
+\emph on
+_sdcc__external__startup()
\series bold
-_sdcc__external__startup()
+\emph default
+
\series default
at the start of the CODE area.
- This routine can be found in the file
-\series bold
-SDCCDIR/sdcc51lib/_startup.c
-\series default
-, 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.
+ This routine is in the runtime library.
+ 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
-\series bold
+\emph on
_sdcc__external__startup()
-\series default
- 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.
+\emph default
+ routine to your program to override the default if you need to setup hardware
+ or perform some other critical operation prior to static & global variable
+ initialization.
\layout Subsection
Inline Assembler Code
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 form
+ All labels defined within inline assembler code
+\emph on
+has to be
+\emph default
+ of the form
\emph on
nnnnn$
\emph default
where nnnn is a number less than 100 (which implies a limit of utmost 100
inline assembler labels
+\emph on
+per function
+\emph default
\noun on
-per function)
+)
\noun default
.
It is strongly recommended that each assembly instruction (including labels)
be placed in a separate line (as the example shows).
When the
-\series bold
+\emph on
--peep-asm
-\series default
+\emph default
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'
+ the peephole optimizer.
+ This might cause some unexpected changes in the inline assembler code.
+ Please go throught the peephole optimizer rules defined in file
+\emph on
+SDCCpeeph.def
+\emph default
carefully before using this option.
\newline
_asm
\newline
\SpecialChar ~
- \SpecialChar ~
- mov b,#10
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b,#10
\newline
00001$:
\newline
\SpecialChar ~
- \SpecialChar ~
- djnz b,00001$
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+djnz\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b,00001$
\newline
_endasm ;
\family default
\size default
The inline assembler code can contain any valid code understood by the assembler
- (this includes any assembler directives and comment lines).
+, this includes any assembler directives and comment lines.
The compiler does not do any validation of the code within the
\family typewriter
_asm ...
\family default
In other words inline assembly code can access labels defined in inline
- assembly.
- The same goes the other way, ie.
+ assembly within the scope of the funtion.
+
+\layout Standard
+
+The same goes the other way, ie.
labels defines in inline assembly CANNOT be accessed by C statements.
\layout Subsection
-int(16 bit) and long (32 bit ) Support
+int(16 bit) and long (32 bit) Support
\layout Standard
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.
+ to other MCUs, although some model specific assembler optimations are used.
The following files contain the described routine, all of them can be found
- in the directory default SDCC library path.
-\layout Itemize
+ in <installdir>/share/sdcc/lib.
+\newline
+\newline
-\size footnotesize
-_mulsint.c - signed 16 bit multiplication (calls _muluint)
-\layout Itemize
+\emph on
+<pending: tabularise this>
+\emph default
+\newline
-\size footnotesize
+\newline
+_mulsint.c - signed 16 bit multiplication (calls _muluint)
+\newline
_muluint.c - unsigned 16 bit multiplication
-\layout Itemize
-
-
-\size footnotesize
+\newline
_divsint.c - signed 16 bit division (calls _divuint)
-\layout Itemize
-
-
-\size footnotesize
-_divuint.c - unsigned 16 bit division.
-\layout Itemize
-
-
-\size footnotesize
+\newline
+_divuint.c - unsigned 16 bit division
+\newline
_modsint.c - signed 16 bit modulus (call _moduint)
-\layout Itemize
-
-
-\size footnotesize
-_moduint.c - unsigned 16 bit modulus.
-\layout Itemize
-
-
-\size footnotesize
+\newline
+_moduint.c - unsigned 16 bit modulus
+\newline
_mulslong.c - signed 32 bit multiplication (calls _mululong)
-\layout Itemize
-
-
-\size footnotesize
-_mululong.c - unsigned32 bit multiplication.
-\layout Itemize
-
-
-\size footnotesize
+\newline
+_mululong.c - unsigned32 bit multiplication
+\newline
_divslong.c - signed 32 division (calls _divulong)
-\layout Itemize
-
-
-\size footnotesize
-_divulong.c - unsigned 32 division.
-\layout Itemize
-
-
+\newline
+_divulong.c - unsigned 32 division
+\newline
+_modslong.c - signed 32 bit modulus (calls _modulong)
+\newline
+_modulong.c - unsigned 32 bit modulus
\size footnotesize
-_modslong.c - signed 32 bit modulus (calls _modulong).
-\layout Itemize
+\newline
-\size footnotesize
-_modulong.c - unsigned 32 bit modulus.
-\layout Standard
+\newline
-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 be compiled with
- the --stack-auto option, after which the source program will have to be
- compiled with --int-long-rent option.
+\size default
+Since they are compiled as
+\emph on
+non-reentrant
+\emph default
+, interrupt service routines should not do any of the above operations.
+ If this is unavoidable then the above routines will need to be compiled
+ with the
+\emph on
+--stack-auto
+\emph default
+ option, after which the source program will have to be compiled with
+\emph on
+--int-long-rent
+\emph default
+ option.
\layout Subsection
Floating Point Support
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.
-
-\layout Itemize
+ the following routines:
+\newline
+\newline
-\size footnotesize
-_fsadd.c - add floating point numbers.
-\layout Itemize
+\emph on
+<pending: tabularise this>
+\emph default
+\newline
-\size footnotesize
+\newline
+_fsadd.c - add floating point numbers
+\newline
_fssub.c - subtract floating point numbers
-\layout Itemize
-
-
-\size footnotesize
+\newline
_fsdiv.c - divide floating point numbers
-\layout Itemize
-
-
-\size footnotesize
+\newline
_fsmul.c - multiply floating point numbers
-\layout Itemize
-
-
-\size footnotesize
+\newline
_fs2uchar.c - convert floating point to unsigned char
-\layout Itemize
-
-
-\size footnotesize
-_fs2char.c - convert floating point to signed char.
-\layout Itemize
-
-
-\size footnotesize
-_fs2uint.c - convert floating point to unsigned int.
-\layout Itemize
-
-
-\size footnotesize
-_fs2int.c - convert floating point to signed int.
-\layout Itemize
-
-
-\size footnotesize
-_fs2ulong.c - convert floating point to unsigned long.
-\layout Itemize
-
-
-\size footnotesize
-_fs2long.c - convert floating point to signed long.
-\layout Itemize
-
-
-\size footnotesize
+\newline
+_fs2char.c - convert floating point to signed char
+\newline
+_fs2uint.c - convert floating point to unsigned int
+\newline
+_fs2int.c - convert floating point to signed int
+\newline
+_fs2ulong.c - convert floating point to unsigned long
+\newline
+_fs2long.c - convert floating point to signed long
+\newline
_uchar2fs.c - convert unsigned char to floating point
-\layout Itemize
-
-
-\size footnotesize
+\newline
_char2fs.c - convert char to floating point number
-\layout Itemize
-
-
-\size footnotesize
+\newline
_uint2fs.c - convert unsigned int to floating point
-\layout Itemize
-
-
-\size footnotesize
+\newline
_int2fs.c - convert int to floating point numbers
-\layout Itemize
-
-
-\size footnotesize
+\newline
_ulong2fs.c - convert unsigned long to floating point number
-\layout Itemize
+\newline
+_long2fs.c - convert long to floating point number
+\size footnotesize
+\newline
-\size footnotesize
-_long2fs.c - convert long to floating point number.
-\layout Standard
+\newline
+\size default
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)
+ For serious floating point usage it is strongly recommended that the large
+ model be used.
\layout Subsection
MCS51 Memory Models
\newline
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
+ generator (
+\emph on
+-mmcs51
+\emph default
+).
+ Now, however, the '390 has it's own code generator, selected by the
+\emph on
+-mds390
+\emph default
switch.
\newline
\newline
Note that the compiler does not generate any code to place the processor
- into 24 bitmode (although the tinibios in the ds390 libraries will do that
- for you).
- If you don't use tinibios, the boot loader or similar code must ensure
- that the processor is in 24 bit contiguous addressing mode before calling
- the SDCC startup code.
+ into 24 bitmode (although
+\emph on
+tinibios
+\emph default
+ in the ds390 libraries will do that for you).
+ If you don't use
+\emph on
+tinibios
+\emph default
+, the boot loader or similar code must ensure that the processor is in 24
+ bit contiguous addressing mode before calling the SDCC startup code.
\newline
\newline
-Like the --model-large option, variables will by default be placed into
- the XDATA segment.
+Like the
+\emph on
+--model-large
+\emph default
+ option, variables will by default be placed into the XDATA segment.
\newline
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.
+ The -r flag can be passed to the linker by using the option
+\emph on
+-Wl-r
+\emph default
+ on the sdcc command line.
However, currently the linker can not handle code segments > 64k.
\layout Subsection
-mz80)
\layout Itemize
-SDCC_STACK_AUTO - this symbol is defined when --stack-auto option is used.
-\layout Itemize
-
-SDCC_MODEL_SMALL - when small model is used.
+SDCC_STACK_AUTO - this symbol is defined when
+\emph on
+--stack-auto
+\emph default
+ option is used.
\layout Itemize
-SDCC_MODEL_LARGE - when --model-large is used.
+SDCC_MODEL_SMALL - when
+\emph on
+--model-small
+\emph default
+ is used.
\layout Itemize
-SDCC_USE_XSTACK - when --xstack option is used.
+SDCC_MODEL_LARGE - when
+\emph on
+--model-large
+\emph default
+ is used.
+\layout Itemize
+
+SDCC_USE_XSTACK - when
+\emph on
+--xstack
+\emph default
+ option is used.
\layout Itemize
-SDCC_STACK_TENBIT - when -mds390 is used
+SDCC_STACK_TENBIT - when
+\emph on
+-mds390
+\emph default
+ is used
\layout Itemize
-SDCC_MODEL_FLAT24 - when -mds390 is used
+SDCC_MODEL_FLAT24 - when
+\emph on
+-mds390
+\emph default
+ is used
\layout Section
SDCC Technical Data
Optimizations
\layout Standard
-SDCC performs a a host of standard optimizations in addition to some MCU
- specific optimizations.
+SDCC performs a host of standard optimizations in addition to some MCU specific
+ optimizations.
\layout Subsubsection
Sub-expression Elimination
\layout Standard
-The compiler does
-\emph on
-local and global
-\emph default
-common subexpression elimination.
-\layout Standard
-
-
-\family typewriter
-\size scriptsize
-eg.
+The compiler does local and global common subexpression elimination, e.g.:
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
i = x + y + 1;
-\size default
+\newline
+j = x + y;
+\family default
\newline
-j
-\size small
-= x + y;
-\layout Standard
+\newline
will be translated to
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
iTemp = x + y
\newline
i = iTemp + 1
\newline
j = iTemp
-\layout Standard
+\newline
-Some subexpressions are not as obvious as the above example.
-\layout Standard
+\family default
-eg.
-\layout Standard
+\newline
+Some subexpressions are not as obvious as the above example, e.g.:
+\newline
+\newline
-\size small
+\family typewriter
a->b[i].c = 10;
\newline
a->b[i].d = 11;
-\layout Standard
+\family default
-In this case the address arithmetic
-\emph on
-a->b[i]
-\emph default
-will be computed only once; the equivalent code in C would be.
-\layout Standard
+\newline
+\newline
+In this case the address arithmetic a->b[i] will be computed only once;
+ the equivalent code in C would be.
+\newline
-\size small
+\newline
+
+\family typewriter
iTemp = a->b[i];
\newline
iTemp.c = 10;
\newline
iTemp.d = 11;
-\layout Standard
+\family default
+\newline
+
+\newline
The compiler will try to keep these temporary variables in registers.
\layout Subsubsection
Dead-Code Elimination
\layout Standard
-eg.
-\layout Standard
-
-\size small
+\family typewriter
int global;
\newline
void f () {
\SpecialChar ~
\SpecialChar ~
i = 1; \SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
/* dead store */
\newline
\SpecialChar ~
\SpecialChar ~
-global = 1; /* dead store */
+global = 1;\SpecialChar ~
+/* dead store */
\newline
\SpecialChar ~
\SpecialChar ~
\newline
\SpecialChar ~
\SpecialChar ~
-global = 3; /* unreachable */
+global = 3;\SpecialChar ~
+/* unreachable */
\newline
}
-\layout Standard
+\family default
+\newline
+
+\newline
will be changed to
-\layout Standard
+\newline
+\newline
-\size footnotesize
+\family typewriter
int global; void f ()
\newline
-{ \SpecialChar ~
- \SpecialChar ~
-
+{
\newline
\SpecialChar ~
-global = 2; \SpecialChar ~
- \SpecialChar ~
-
+\SpecialChar ~
+global = 2;
\newline
\SpecialChar ~
+\SpecialChar ~
return;
\newline
}
Copy-Propagation
\layout Standard
-eg.
-\layout Standard
-
-\size footnotesize
+\family typewriter
int f() {
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
int i, j;
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
i = 10;
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
j = i;
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
return j;
\newline
}
-\layout Standard
+\family default
+
+\newline
+\newline
will be changed to
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
int f() {
\newline
\SpecialChar ~
return 10;
\newline
}
-\layout Standard
+\newline
+\newline
+
+\family default
Note: the dead stores created by this copy propagation will be eliminated
by dead-code elimination.
\layout Subsubsection
\layout Standard
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 optimizat
-ion causes an increase in register pressure, which may cause unwanted spilling
+ 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 optimizati
+on 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).
-\layout Itemize
-
+ can be eliminated either for the entire source file (with --noinduction
+ option) or for a given function only using #pragma\SpecialChar ~
+NOINDUCTION.
+\newline
-\series bold
+\newline
Loop Invariant:
-\layout Standard
-
-eg
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
for (i = 0 ; i < 100 ; i ++)
\newline
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
f += k + l;
-\layout Standard
+\family default
+
+\newline
+\newline
changed to
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
itemp = k + l;
\newline
-for ( i = 0; i < 100; i++ ) f += itemp;
-\layout Standard
+for (i = 0; i < 100; i++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+f += itemp;
+\family default
+\newline
+
+\newline
As mentioned previously some loop invariants are not as apparent, all static
address computations are also moved out of the loop.
-\layout Itemize
-
-
-\series bold
-Strength Reduction :
-\layout Standard
+\newline
-This optimization substitutes an expression by a cheaper expression.
-\layout Standard
+\newline
+Strength Reduction, this optimization substitutes an expression by a cheaper
+ expression:
+\newline
-eg.
-\layout Standard
+\newline
+\family typewriter
+for (i=0;i < 100; i++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ar[i*5] = i*3;
+\family default
-\size small
-for (i=0;i < 100; i++) ar[i*5] = i*3;
-\layout Standard
+\newline
+\newline
changed to
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
itemp1 = 0;
\newline
itemp2 = 0;
\newline
for (i=0;i< 100;i++) {
\newline
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
ar[itemp1] = itemp2;
\newline
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
itemp1 += 5;
\newline
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
itemp2 += 3;
\newline
}
-\layout Standard
+\family default
+
+\newline
+\newline
The more expensive multiplication is changed to a less expensive addition.
\layout Subsubsection
-Loop Reversing:
+Loop Reversing
\layout Standard
This optimization is done to reduce the overhead of checking loop boundaries
instruction.
SDCC checks for the following criterion to determine if a loop is reversible
- (note: more sophisticated compiers use data-dependency analysis to make
+ (note: more sophisticated compilers use data-dependency analysis to make
this determination, SDCC uses a more simple minded analysis).
\layout Itemize
The 'for' loop is of the form
\newline
-\begin_inset Quotes eld
-\end_inset
+\newline
-for ( <symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
+\family typewriter
+for (<symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
<sym> += 1])
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
<for body>
-\begin_inset Quotes erd
-\end_inset
-
-
\layout Itemize
The <for body> does not contain
There are NO switch statements in the loop.
\layout Standard
-Note djnz instruction can be used for 8-bit values ONLY, therefore it is
- advantageous to declare loop control symbols as either 'char', ofcourse
- this may not be possible on all situations.
+Note djnz instruction can be used for 8-bit values
+\emph on
+only
+\emph default
+, therefore it is advantageous to declare loop control symbols as
+\emph on
+char
+\emph default
+.
+ Ofcourse this may not be possible on all situations.
\layout Subsubsection
Algebraic Simplifications
SDCC does numerous algebraic simplifications, the following is a small sub-set
of these optimizations.
-\layout Standard
-
-
-\size small
-eg
-\emph on
-
-\emph default
+\newline
\newline
+
+\family typewriter
i = j + 0 ; /* changed to */ i = j;
\newline
i /= 2; /* changed to */ i >>= 1;
i = j - j ; /* changed to */ i = 0;
\newline
i = j / 1 ; /* changed to */ i = j;
-\layout Standard
+\family default
+
+\newline
+\newline
Note the subexpressions given above are generally introduced by macro expansions
or as a result of copy/constant propagation.
\layout Subsubsection
\layout Itemize
-The case labels are in numerical sequence , the labels need not be in order,
+The case labels are in numerical sequence, the labels need not be in order,
and the starting number need not be one or zero.
\layout Standard
-eg
-\layout Standard
-
-\size small
+\family typewriter
switch(i) {\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
}
-\layout Standard
+\newline
+
+\newline
+\family default
Both the above switch statements will be implemented using a jump-table.
\layout Itemize
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.
-\layout Standard
-
-eg
-\layout Standard
+ for efficient code generation, e.g.:
+\newline
+\newline
-\size small
+\family typewriter
switch (i) {
\newline
case 1: ...
\newline
}
-\layout Standard
+\family default
+
+\newline
+\newline
If the above switch statement is broken down into two switch statements
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
switch (i) {
\newline
case 1: ...
\newline
}
-\layout Standard
+\newline
+\newline
-\size small
+\family default
+and
+\family typewriter
+
+\newline
+
+\newline
switch (i) {
\newline
-case 9: ...
+case 9: \SpecialChar ~
+...
\newline
case 10: ...
case 11: ...
\newline
-case 12:...
+case 12:\SpecialChar ~
+...
\newline
}
-\layout Standard
+\newline
+
+\newline
+\family default
then both the switch statements will be implemented using jump-tables whereas
the unmodified switch statement will not be.
\layout Subsubsection
Bit shifting is one of the most frequently used operation in embedded programmin
g.
SDCC tries to implement bit-shift operations in the most efficient way
- possible.
-\layout Standard
+ possible, e.g.:
+\newline
-eg.
-\layout Standard
-
-
-\size small
+\newline
unsigned char i;
-\layout Standard
-
-
-\size small
+\newline
...
\newline
i>>= 4;
\newline
-..
-\layout Standard
-
-generates the following code.
-\layout Standard
+...
+\newline
+\newline
+generates the following code:
+\newline
-\size small
+\newline
mov a,_i
\newline
swap a
anl a,#0x0f
\newline
mov _i,a
-\layout Standard
+\newline
+\newline
In general SDCC will never setup a loop if the shift count is known.
- Another example
-\layout Standard
+ Another example:
+\newline
+\newline
-\size small
+\family typewriter
unsigned int i;
\newline
...
i >>= 9;
\newline
...
-\layout Standard
+\family default
-will generate
-\layout Standard
+\newline
+\newline
+will generate:
+\newline
-\size small
+\newline
+
+\family typewriter
mov a,(_i + 1)
\newline
mov (_i + 1),#0x00
rrc a
\newline
mov _i,a
-\layout Standard
+\family default
-Note that SDCC stores numbers in
-\noun on
-little-endian
-\noun default
-format (i.e.
- lowest order first)
+\newline
+
+\newline
+Note that SDCC stores numbers in little-endian format (i.e.
+ lowest order first).
\layout Subsubsection
Bit-rotation
\layout Standard
A special case of the bit-shift operation is bit rotation, SDCC recognizes
- the following expression to be a left bit-rotation.
-\layout Standard
+ the following expression to be a left bit-rotation:
+\newline
+\newline
-\size small
+\family typewriter
unsigned char i;
\newline
...
\newline
-i = ( ( i << 1) | ( i >> 7));
+i = ((i << 1) | (i >> 7));
+\family default
+
\newline
...
-\layout Standard
+\newline
-will generate the following code.
-\layout Standard
+\newline
+will generate the following code:
+\newline
+\newline
-\size small
+\family typewriter
mov a,_i
\newline
rl a
\newline
mov _i,a
-\layout Standard
+\family default
+
+\newline
+\newline
SDCC uses pattern matching on the parse tree to determine this operation.Variatio
-ns of this case will also be recognized as bit-rotation i.e
-\emph on
- i = ((i >> 7) | (i << 1));
-\emph default
-/* left-bit rotation */
+ns of this case will also be recognized as bit-rotation, i.e.:
+\newline
+
+\newline
+
+\family typewriter
+i = ((i >> 7) | (i << 1)); /* left-bit rotation */
\layout Subsubsection
Highest Order Bit
It is frequently required to obtain the highest order bit of an integral
type (long, int, short or char types).
SDCC recognizes the following expression to yield the highest order bit
- and generates optimized code for it.
-\layout Standard
-
+ and generates optimized code for it, e.g.:
+\newline
-\size small
-eg
\newline
+
+\family typewriter
unsigned int gint;
+\newline
+
\newline
foo () {
\newline
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
...
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
hob = (gint >> 15) & 1;
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
..
\newline
}
-\layout Standard
+\family default
-Will generate the following code.
-\layout Standard
+\newline
+\newline
+will generate the following code:
+\newline
-\size small
+\family typewriter
+
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov\SpecialChar ~
_foo_hob_1_1,a
-\layout Standard
-
-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.
-\layout Standard
+\newline
+\newline
-\size small
-eg.
-\layout Standard
+\family default
+Variations of this case however will
+\emph on
+not
+\emph default
+ 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,
+ e.g.:
+\newline
+\newline
-\size small
+\family typewriter
xyz = gint + ((gint >> 15) & 1);
-\layout Standard
+\family default
+\newline
+
+\newline
will still be recognized.
\layout Subsubsection
Peep-hole Optimizer
\layout Standard
-The compiler uses a rule based , pattern matching and re-writing mechanism
+The compiler uses a rule based, pattern matching and re-writing mechanism
for peep-hole optimization.
- It is inspired by '
+ It is inspired by
\emph on
-copt'
+copt
\emph default
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.
+ may be added with the
+\emph on
+--peep-file <filename>
+\emph default
+ option.
The rule language is best illustrated with examples.
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
replace {
\newline
+\SpecialChar ~
+\SpecialChar ~
mov %1,a
\newline
-mov a,%1 } by { mov %1,a }
-\layout Standard
+\SpecialChar ~
+\SpecialChar ~
+mov a,%1
+\newline
+} by {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+mov %1,a
+\newline
+}
+\family default
-The above rule will the following assembly sequence
-\layout Standard
+\newline
+\newline
+The above rule will change the following assembly sequence:
+\newline
-\size small
+\newline
+
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
mov r1,a
\newline
+\SpecialChar ~
+\SpecialChar ~
mov a,r1
-\layout Standard
+\family default
+
+\newline
+\newline
to
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
mov r1,a
-\layout Standard
+\family default
-Note: All occurrences of a '%n' ( pattern variable ) must denote the same
- string.
- With the above rule, the assembly sequence
-\layout Standard
+\newline
+\newline
+Note: All occurrences of a
+\emph on
+%n
+\emph default
+ (pattern variable) must denote the same string.
+ With the above rule, the assembly sequence:
+\newline
-\size small
+\newline
+
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
mov r1,a
\newline
+\SpecialChar ~
+\SpecialChar ~
mov a,r2
-\layout Standard
+\family default
+
+\newline
+\newline
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'.
-\layout Standard
+\newline
+\newline
+Other special case optimizations may be added by the user (via
+\emph on
+--peep-file option
+\emph default
+).
+ E.g.
+ some variants of the 8051 MCU allow only
+\family typewriter
+ajmp
+\family default
+ and
+\family typewriter
+acall
+\family default
+.
+ The following two rules will change all
+\family typewriter
+ljmp
+\family default
+ and
+\family typewriter
+lcall
+\family default
+ to
+\family typewriter
+ajmp
+\family default
+ and
+\family typewriter
+acall
+\family default
-\size small
+\newline
+
+\newline
+
+\family typewriter
replace { lcall %1 } by { acall %1 }
\newline
replace { ljmp %1 } by { ajmp %1 }
-\layout Standard
+\family default
+
+\newline
-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.
+\newline
+The
+\emph on
+inline-assembler code
+\emph default
+ 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-structur
e is MCU independent.
Peephole optimization rules for other MCU can be easily programmed using
the rule language.
-\layout Standard
+\newline
-The syntax for a rule is as follows ,
-\layout Standard
+\newline
+The syntax for a rule is as follows:
+\newline
+\newline
-\size small
+\family typewriter
rule := replace [ restart ] '{' <assembly sequence> '
\backslash
n'
\backslash
n'
\newline
-<assembly sequence> := assembly instruction (each instruction including
- labels must be on a separate line).\SpecialChar ~
- \SpecialChar ~
-\layout Standard
+\family default
+
+\newline
+<assembly sequence> := assembly instruction (each instruction including
+ labels must be on a separate line).
+\newline
+\newline
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 '
-\emph on
-restart
-\emph default
-' 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
+ If the 'restart' 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.
-\layout Standard
-
+ A good example of this the following rule:
+\newline
-\size small
+\newline
replace restart {
\newline
+\SpecialChar ~
+\SpecialChar ~
pop %1
\newline
+\SpecialChar ~
+\SpecialChar ~
push %1 } by {
\newline
+\SpecialChar ~
+\SpecialChar ~
; nop
\newline
}
-\layout Standard
+\newline
+\newline
Note that the replace pattern cannot be a blank, but can be a comment line.
- Without the '
-\emph on
-restart
-\emph default
-' option only the inner most 'pop' 'push' pair would be eliminated.
- i.e.
-\layout Standard
+ Without the 'restart' option only the inner most 'pop' 'push' pair would
+ be eliminated, i.e.:
+\newline
+\newline
-\size small
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
pop ar1
\newline
+\SpecialChar ~
+\SpecialChar ~
pop ar2
\newline
+\SpecialChar ~
+\SpecialChar ~
push ar2
\newline
+\SpecialChar ~
+\SpecialChar ~
push ar1
-\layout Standard
+\family default
-would result in
-\layout Standard
+\newline
+\newline
+would result in:
+\newline
-\size small
+\newline
+
+\family typewriter
pop ar1
\newline
; nop
\newline
push ar1
-\layout Standard
+\family default
+
+\newline
+
+\newline
-with the '
-\emph on
-restart
-\emph default
-' option the rule will be applied again to the resulting code and the all
- the '
\emph on
-pop' 'push'
+with
\emph default
- pairs will be eliminated to yield
-\layout Standard
+ the restart option the rule will be applied again to the resulting code
+ and then all the pop-push pairs will be eliminated to yield:
+\newline
+\newline
-\size small
+\family typewriter
; nop
\newline
; nop
-\layout Standard
+\family default
+\newline
+
+\newline
A conditional function can be attached to a rule.
Attaching rules are somewhat more involved, let me illustrate this with
an example.
-\layout Standard
+\newline
+\newline
-\size small
+\family typewriter
replace {
\newline
\SpecialChar ~
sjmp %5
\newline
%2:} if labelInRange
-\layout Standard
+\family default
+
+\newline
+\newline
The optimizer does a look-up of a function name table defined in function
- '
-\emph on
-callFuncByName'
-\emph default
- in the source file
+
\emph on
-SDCCpeeph.c
+callFuncByName
\emph default
- , with the name
+ in the source file SDCCpeeph.c, with the name
\emph on
-'labelInRange
+labelInRange
\emph default
-', if it finds a corresponding entry the function is called.
+.
+ 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
\emph on
-'%5
+%5
\emph default
-' is crucial, since the function
+ is crucial, since the function
\emph on
labelInRange
\emph default
expects to find the label in that particular variable (the hash table containin
g the variable bindings is passed as a parameter).
- If you want to code more such functions , take a close look at the function
-
-\emph on
-labelInRange
-\emph default
- and the calling mechanism in source file
-\emph on
-SDCCpeeph.c
-\emph default
-.
- I know this whole thing is a little kludgey , may be some day we will have
- some better means.
+ If you want to code more such functions, take a close look at the function
+ labelInRange and the calling mechanism in source file SDCCpeeph.c.
+ I know this whole thing is a little kludgey, but maybe 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
+ are compiled into the compiler, you can add your own rules in the default
+ set there if you get tired of specifying the --peep-file option.
+\newline
+
+\newline
+
\emph on
---peep-file
-\emph default
- option.
+<pending: this is as far as I got>
\layout Subsection
Pragmas
\layout Standard
-SDCC supports the following
-\emph on
-#pragma
-\emph default
-directives.
+SDCC supports the following #pragma directives.
This directives are applicable only at a function level.
\layout Itemize
-
-\series bold
-SAVE
-\series default
- - this will save all the current options.
+SAVE - this will save all the current options.
\layout Itemize
-
-\series bold
-RESTORE
-\series default
-- will restore the saved options from the last save.
+RESTORE - 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.
\layout Itemize
-
-\series bold
-NOGCSE
-\series default
- - will stop global subexpression elimination.
+NOGCSE - will stop global subexpression elimination.
\layout Itemize
-
-\series bold
-NOINDUCTION
-\series default
- - will stop loop induction optimizations.
+NOINDUCTION - will stop loop induction optimizations.
\layout Itemize
-
-\series bold
-NOJTBOUND
-\series default
- - will not generate code for boundary value checking , when switch statements
- are turned into jump-tables.
+NOJTBOUND - will not generate code for boundary value checking, when switch
+ statements are turned into jump-tables.
\layout Itemize
-
-\series bold
-NOOVERLAY
-\series default
-- the compiler will not overlay the parameters and local variables of a
- function.
+NOOVERLAY - the compiler will not overlay the parameters and local variables
+ of a function.
\layout Itemize
-
-\series bold
-NOLOOPREVERSE
-\series default
- - Will not do loop reversal optimization
+NOLOOPREVERSE - Will not do loop reversal optimization
\layout Itemize
-
-\series bold
-EXCLUDE NONE | {acc[,b[,dpl[,dph]]]
-\series default
- - The exclude pragma disables generation of pair of push/pop instruction
- in ISR function (using interrupt keyword).
+EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - 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
-\begin_inset Quotes eld
-\end_inset
-
-#pragma EXCLUDE none
-\begin_inset Quotes erd
-\end_inset
-
-
+ To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
+EXCLUDE\SpecialChar ~
+none.
\layout Itemize
-
-\series bold
-CALLEE-SAVES function1[,function2[,function3...]]
-\series default
- - 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.
+CALLEE-SAVES function1[,function2[,function3...]] - 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
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.
+ in #pragma\SpecialChar ~
+CALLEE-SAVES is appended to the list of functions specified inthe
+ command line.
\layout Standard
The pragma's are intended to be used to turn-off certain optimizations which
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
-\noun on
-before
-\noun default
- and/or
-\noun on
-after
-\noun default
- a function, placing pragma's inside a function body could have unpredictable
- results.
+ should be placed before and/or after a function, placing pragma's inside
+ a function body could have unpredictable results.
\layout Standard
-
-\size scriptsize
eg
\layout Standard
-
-\size scriptsize
#pragma SAVE \SpecialChar ~
/* save the current settings */
\newline
The following library routines are provided for your convenience.
\layout Standard
-
-\series bold
-\size large
-stdio.h
-\series default
-\size default
-- Contains the following functions printf & sprintf these routines are developed
- by
-\emph on
-Martijn van Balen <balen@natlab.research.philips.com>.
+stdio.h - Contains the following functions printf & sprintf these routines
+ are developed by Martijn van Balen <balen@natlab.research.philips.com>.
\layout Standard
-
-\size scriptsize
%[flags][width][b|B|l|L]type
\layout Standard
-
-\size scriptsize
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
float (still to be implemented)
\layout Standard
-Also contains a very simple version of printf (
-\series bold
-printf_small
-\series default
-).
+Also contains a very simple version of printf (printf_small).
This simplified version of printf supports only the following formats.
\layout Standard
-
-\size scriptsize
-\bar under
format\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-argument-type
-\bar default
-
-\series bold
-\size default
-
+argument-type
\newline
-
-\series default
-\size scriptsize
%d \SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_generic pointer
\layout Standard
-The routine is
-\series bold
-very stack intesive
-\series default
-, --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
-\emph on
-putchar(char )
-\emph default
- to be present (this can be changed).
+The routine is very stack intesive, --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 putchar(char) to be present
+ (this can be changed).
When using the %s format the string / pointer should be cast to a generic
pointer.
eg.
\layout Standard
-
-\size scriptsize
printf_small(
\begin_inset Quotes eld
\end_inset
,(char _generic *)mystr,myint);
\layout Itemize
-
-\series bold
-\size large
-stdarg.h
-\series default
-\size default
-- 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'
+stdarg.h - 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'
\begin_deeper
\layout Standard
-
-\size small
va_list, va_start, va_arg, va_end.
\end_deeper
\layout Itemize
-
-\series bold
-\size large
-setjmp.h
-\series default
-\size default
-- contains defintion for ANSI
-\series bold
- setjmp
-\series default
-&
-\series bold
-longjmp
-\series default
- routines.
+setjmp.h - contains defintion for ANSI setjmp & longjmp 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
return address), and can be placed in any address space.
\layout Itemize
-
-\series bold
-\size large
-stdlib.h
-\series default
-\size default
- - contains the following functions.
+stdlib.h - contains the following functions.
\begin_deeper
\layout Standard
-
-\size footnotesize
atoi, atol.
\end_deeper
\layout Itemize
-
-\series bold
-\size large
-string.h
-\series default
-\size default
-- contains the following functions.
+string.h - contains the following functions.
\begin_deeper
\layout Standard
-
-\size footnotesize
strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn,
strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.
\end_deeper
\layout Itemize
-
-\series bold
-\size large
-ctype.h
-\series default
-\size default
- - contains the following routines.
+ctype.h - contains the following routines.
\begin_deeper
\layout Standard
-
-\size footnotesize
iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
isxdigit, isalnum, isalpha.
\end_deeper
\layout Itemize
-
-\series bold
-\size large
-malloc.h
-\series default
-\size default
- - The malloc routines are developed by Dmitry S.
+malloc.h - 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).
\begin_deeper
\layout Standard
-
-\size scriptsize
//Example:
\newline
\SpecialChar ~
\end_deeper
\layout Itemize
-
-\series bold
-\size large
-serial.h
-\series default
-\size default
- - Serial IO routines are also developed by Dmitry S.
+serial.h - 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.
MUST be included in the file containing the 'main' function.
\layout Itemize
-
-\series bold
-\size large
-ser.h
-\series default
-\size default
-- Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.co
-m> these routines are more compact and faster.
+ser.h - Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMi
+nds.com> these routines are more compact and faster.
Please see documentation in file SDCCDIR/sdcc51lib/ser.c
\layout Itemize
-
-\series bold
-\size large
-ser_ir.h
-\series default
-\size default
-- Another alternate set of serial routines provided by Josef Wolf <jw@raven.inka.d
-e> , these routines do not use the external ram.
+ser_ir.h - Another alternate set of serial routines provided by Josef Wolf
+ <jw@raven.inka.de>, these routines do not use the external ram.
\layout Itemize
-
-\series bold
-\size large
-reg51.h
-\series default
-\size default
- - contains register definitions for a standard 8051
+reg51.h - contains register definitions for a standard 8051
\layout Itemize
-
-\series bold
-\size large
-float.h
-\series default
-\size default
- - contains min, max and other floating point related stuff.
+float.h - contains min, max and other floating point related stuff.
\layout Standard
-All library routines are compiled as --model-small , they are all non-reentrant,
+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.
\layout Standard
Assembler Routine(non-reentrant)
\layout Standard
-In the following example the function
-\series bold
- cfunc
-\series default
- calls an assembler routine
-\series bold
-asm_func
-\series default
-, which takes two parameters.
+In the following example the function cfunc calls an assembler routine asm_func,
+ which takes two parameters.
\layout Standard
-
-\size footnotesize
-extern int asm_func( unsigned char, unsigned char);
+extern int asm_func(unsigned char, unsigned char);
\layout Standard
-
-\size footnotesize
\SpecialChar ~
\newline
\SpecialChar ~
return asm_func(i,j);
\newline
-}
-\size default
-
-\size scriptsize
-
+}
\newline
int main()
\newline
The corresponding assembler function is:-
\layout Standard
-
-\size scriptsize
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
b' & 'acc' for four byte values.
\layout Standard
-The parameter naming convention is
-\series bold
-_<function_name>_PARM_<n>,
-\series default
- where n is the parameter number starting from 1, and counting from the
- left.
+The parameter naming convention is _<function_name>_PARM_<n>, where n is
+ the parameter number starting from 1, and counting from the left.
The first parameter is passed in
\begin_inset Quotes eld
\end_inset
\begin_inset Quotes erd
\end_inset
- for four bytes, the
-\family typewriter
-\series bold
-\size footnotesize
-varaible name for the second parameter will be _<function_name>_PARM_2.
+ for four bytes, the varaible name for the second parameter will be _<function_n
+ame>_PARM_2.
\layout Standard
Assemble the assembler routine with the following command.
Assembler Routine(reentrant)
\layout Standard
-In this case the second parameter onwards will be passed on the stack ,
- the parameters are pushed from right to left i.e.
+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.
\layout Standard
-
-\size footnotesize
-extern int asm_func( unsigned char, unsigned char);
+extern int asm_func(unsigned char, unsigned char);
\layout Standard
-
-\size footnotesize
\SpecialChar ~
\layout Standard
-
-\size footnotesize
int c_func (unsigned char i, unsigned char j) reentrant
\newline
{
\SpecialChar ~
return asm_func(i,j);
\newline
-}
-\size default
-
-\size scriptsize
-
+}
\newline
int main()
\newline
The corresponding assembler routine is.
\layout Standard
-
-\size scriptsize
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
External Stack
\layout Standard
-The external stack is located at the start of the external ram segment ,
+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.
\begin_deeper
\layout Standard
-
-\size small
eg
\end_deeper
\layout Standard
-
-\size small
struct s { ...
};
\newline
}
\layout Standard
-
-\size small
struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
ANSI */
\newline
\layout Enumerate
-No support for
-\emph on
-setjmp
-\emph default
- and
-\emph on
-longjmp
-\emph default
- (for now).
+No support for setjmp and longjmp (for now).
\layout Enumerate
Old K&R style function declarations are NOT allowed.
\layout Standard
-
-\size footnotesize
-foo( i,j) /* this old style of function declarations */
+foo(i,j) /* this old style of function declarations */
\newline
int i,j; /* are valid in ANSI ..
not valid in SDCC */
\begin_deeper
\layout Standard
-
-\size small
int (*foo)();
\end_deeper
\layout Standard
-
-\size small
\SpecialChar ~
\SpecialChar ~
...
SDCC uses the following formula to compute the complexity.
\layout Standard
-
-\size small
complexity = (number of edges in control flow graph) -
\newline
\SpecialChar ~
should do an explicit cast when integral promotion is required.
\layout Itemize
-Reducing the size of division , multiplication & modulus operations can
- reduce code size substantially.
+Reducing the size of division, multiplication & modulus operations can reduce
+ code size substantially.
Take the following code for example.
\begin_deeper
\layout Standard
-
-\size footnotesize
-foobar( unsigned int p1, unsigned char ch)
+foobar(unsigned int p1, unsigned char ch)
\newline
{
\newline
If the code is changed to
\layout Standard
-
-\size footnotesize
-foobar( unsigned int p1, unsigned char ch)
+foobar(unsigned int p1, unsigned char ch)
\newline
{
\newline
\end_deeper
\layout Standard
-
-\series bold
Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
\layout Standard
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.
+ 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.
\layout Enumerate
The second phase involves generating an intermediate code which can be easy
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.
+ debugger has been kept as close to gdb (the GNU debugger) as possible.
The configuration and build process is part of the standard compiler installati
on, which also builds and installs the debugger in the target directory
specified during configuration.
Compiling for Debugging
\layout Standard
-The
-\emph on
---debug
-\emph default
- option must be specified for all files for which debug information is to
- be generated.
- The complier generates a
-\emph on
-.cdb
-\emph default
- file for each of these files.
- The linker updates the
-\emph on
-.cdb
-\emph default
- file with the address information.
+The --debug option must be specified for all files for which debug information
+ is to be generated.
+ The complier generates a .cdb file for each of these files.
+ The linker updates the .cdb file with the address information.
This .cdb is used by the debugger.
\layout Subsection
How the Debugger Works
\layout Standard
-When the
-\emph on
---debug
-\emph default
- 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.
+When the --debug 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
--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
+ 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.
+ 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.
\layout Standard
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 integratio
-n with existing graphical user interfaces (like ddd, xxgdb or xemacs) existing
+ 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.
\layout Subsubsection
\layout Standard
Two files are (in emacs lisp) are provided for the interfacing with XEmacs,
-\emph on
- sdcdb.el
-\emph default
- and
-\emph on
-sdcdbsrc.el
-\emph default
-.
+ sdcdb.el and sdcdbsrc.el.
These two files can be found in the $(prefix)/bin directory after the installat
ion 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
-
-\emph on
-'.xemacs'
-\emph default
- file (which can be found in your HOME directory)
-\emph on
-(load-file sdcdbsrc.el)
-\emph default
-[ .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
-\emph on
-'EMACSLOADPATH'
-\emph default
-to the installation bin directory [$(prefix)/bin], then enter the following
- command
-\emph on
-ESC-x load-file sdcdbsrc.
-
-\emph default
-To start the interface enter the following command
-\emph on
-ESC-x sdcdbsrc
-\emph default
- , you will prompted to enter the file name to be debugged.
+ '.xemacs' file (which can be found in your HOME directory) (load-file sdcdbsrc.el
+) [ .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 environme
+nt variable 'EMACSLOADPATH' to the installation bin directory [$(prefix)/bin],
+ then enter the following command ESC-x load-file sdcdbsrc.
+ To start the interface enter the following command ESC-x sdcdbsrc, you
+ will prompted to enter the file name to be debugged.
\layout Standard
The command line options that are passed to the simulator directly are bound
- to default values in the file
-\emph on
-sdcdbsrc.el
-\emph default
-the variables are listed below these values maybe changed as required.
+ to default values in the file sdcdbsrc.el the variables are listed below
+ these values maybe changed as required.
\layout Itemize
sdcdbsrc-cpu-type '51
\SpecialChar ~
-\size scriptsize
-
\newline
;; Current Listing ::
\newline
-SDCC Compiler User Guide
+lSDCC Compiler User Guide
Table of Contents
1 Introduction
1.1 About SDCC
1.2 Open Source
- 1.3 System Requirements
- 1.4 Other Resources
+ 1.3 Typographic conventions
+ 1.4 Pending: compatibilaty with previous versions
+ 1.5 System Requirements
+ 1.6 Other Resources
2 Installation
2.1 Linux/Unix Installation
2.2 Windows Installation
2.6 SDCC on Other Platforms
2.7 Advanced Install Options
2.8 Components of SDCC
- 2.8.1 cpp ( C-Preprocessor)
- 2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)
- 2.8.3 SDCC - The compiler
- 2.8.4 S51 - Simulator
- 2.8.5 SDCDB - Source Level Debugger
+ 2.8.1 sdcc - The Compiler
+ 2.8.2 sdcpp (C-Preprocessor)
+ 2.8.3 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 (The Assemblers and Linkage Editors)
+ 2.8.4 s51 - Simulator
+ 2.8.5 sdcdb - Source Level Debugger
3 Using SDCC
3.1 Compiling
3.1.1 Single Source File Projects
3.2.2 Preprocessor Options
3.2.3 Linker Options
3.2.4 MCS51 Options
- 3.2.5 Optimization Options
- 3.2.6 DS390 Options
+ 3.2.5 DS390 Options
+ 3.2.6 Optimization Options
3.2.7 Other Options
3.2.8 Intermediate Dump Options
3.3 MCS51/DS390 Storage Class Language Extensions
3.11 Absolute Addressing
3.12 Startup Code
3.13 Inline Assembler Code
- 3.14 int(16 bit) and long (32 bit ) Support
+ 3.14 int(16 bit) and long (32 bit) Support
3.15 Floating Point Support
3.16 MCS51 Memory Models
- 3.17 Flat 24 bit Addressing Model
+ 3.17 DS390 Memory Models
3.18 Defines Created by the Compiler
4 SDCC Technical Data
4.1 Optimizations
4.1.2 Dead-Code Elimination
4.1.3 Copy-Propagation
4.1.4 Loop Optimizations
- 4.1.5 Loop Reversing:
+ 4.1.5 Loop Reversing
4.1.6 Algebraic Simplifications
4.1.7 'switch' Statements
4.1.8 Bit-shifting Operations.
1.1 About SDCC
+<pending: tabularise these features, this is unreadeble>
+
SDCC is a Free ware, retargettable, optimizing ANSI-C compiler
by Sandeep Dutta designed for 8 bit Microprocessors. The
current version targets Intel MCS51 based Microprocessors(8051,8052,
which should be well suited for other 8 bit MCUs. The peep
hole optimizer uses a rule based substitution mechanism
which is MCU dependent. Supported data-types are char (8
-bits, 1 byte), short and int (16 bits, 2 bytes ), long (32
+bits, 1 byte), short and int (16 bits, 2 bytes), long (32
bit, 4 bytes) and float (4 byte IEEE). The compiler also
allows inline assembler code to be embedded anywhere in
a function. In addition routines developed in assembly can
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 [http://sdcc.sourceforge.net/].
+be downloaded from [http://sdcc.sourceforge.net/] .
1.2 Open Source
-All packages used in this compiler system are opensource(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).
+All packages used in this compiler system are opensource
+and freeware; source code for all the sub-packages (asxxxx
+assembler/linker, pre-processor) is distributed with the
+package. This documentation is maintained using a freeware
+word processor (LyX).
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
use, share and improve what you give them. Help stamp out
software-hoarding!
-1.3 System Requirements
+<pending: add a link to gnu>
+
+1.3 Typographic conventions
+
+Throughout this manual, we will use the following convention.
+Commands you have to type in are printed in "sans serif".
+Code samples are printed in typewriter font. Interesting
+items and new terms are printed in italicised type.
+
+1.4 Pending: compatibilaty with previous versions
+
+This version has numerous bug fixes comperated with the previous
+version. But we also introduced some incompatibilaties with
+older versions. Not just for the fun of it, but to make
+the compiler more stable, efficient and ANSI compliant.
+
+
+short char
+directory structure (2.7)
+vararg pars expl int unless casted
+never had a regextend
+no --noreparms anymore
+
+more?
+
+1.5 System Requirements
What do you need before you start installation of SDCC? A
computer, and a desire to compute. The preferred method
are available for your convenience. You should have some
experience with command line tools and compiler use.
-1.4 Other Resources
+1.6 Other Resources
The SDCC home page at [http://sdcc.sourceforge.net/]
is a great place to find distribution sets. You can also
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.
+is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
2 Installation
2. Bring up a command line terminal, such as xterm.
-3. Unpack the file using a command like: tar -xzf sdcc-2.x.x.tgz,
+3. 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.
4. Change directory into the main SDCC directory, for example
type: "cd sdcc".
-5. Type "./configure". This configures
- the package for compilation on your system.
+5. Type "./configure". This configures the package for compilation
+ on your system.
-6. Type "make". All of the source packages
- will compile, this can take a while.
+6. Type "make". All of the source packages will compile, this
+ can take a while.
-7. Type "make install" as root.
- This copies the binary executables to the install directories.
+7. Type "make install" as root. This copies the binary executables
+ to the install directories.
2.2 Windows Installation
+<pending: is this complete? where is borland, mingw>
+
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
2.2.1 Windows Install Using a Binary Package
1. Download the binary package and unpack it using your favorite
- unpacking tool(gunzip, WinZip, etc). This should unpack
+ 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
site[http://sources.redhat.com/cygwin/]. 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
+ of the package (a large 80M byte sized dowload for the
whole thing).
2. Bring up a Unix/Bash command line terminal from the Cygwin
2.3 Testing out the SDCC Compiler
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.
+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.
SDCC binaries are commonly installed in a directory arrangement
like this:
Make sure the compiler works on a very simple example. Type
in the following test.c program using your favorite editor:
-main()
-{
-
-int i;
-
-i = 0;
-
-i += 10;
-}
-
-
-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.
+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.
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),
+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 directory (see the Install trouble-shooting
section for suggestions).
files and libraries. Edit test.c and change it to the following:
#include <string.h>
-main()
-{
-
+main() {
char str1[10];
-
-strcpy(str1, "testing");
-
+ strcpy(str1, "testing");
}
-
-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).
+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).
2.4 Install Trouble-shooting
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
+options like this: "sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include test.c".
2.4.2 SDCC does not compile correctly.
.tgz source package again in an empty directory. Confure
it again and build like:
-"make 2&>1 | tee make.log"
+make 2&>1 | tee make.log
After this you can review the make.log file to locate the
problem. Or a relevant part of this be attached to an email
2.5 Additional Information for Windows Users
+<pending: is this up to date?>
+
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.
each of these methods.
The Cygwin package allows a Windows user to run a Unix command
-line interface(bash shell) and also implements a Unix like
+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
2.5.1 Getting started with Cygwin
-SDCC is typically distributed as a tarred/gzipped file(.tgz).
+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
+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,
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
+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.
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
+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.
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.
+structure under the <directory name> specified (if they
+do not already exist).
bin/ - binary exectables (add to PATH environment variable)
-
- share/
- sdcc/include/ - include
-header files
- sdcc/lib/ -
- small/
-- Object & library files for small model library
- large/
-- Object & library files for large model library
- ds390/
-- Object & library files forDS80C390 library
-
-The command
-
-'./configure --prefix=/usr/local"
-
+bin/share/
+bin/share/sdcc/include/ - include header files
+bin/share/sdcc/lib/
+bin/share/sdcc/lib/small/ - Object & library files for small
+model library
+bin/share/sdcc/lib/large/ - Object & library files for large
+model library
+bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390
+library
+
+The command "./configure --prefix=/usr/local"
will configure the compiler to be installed in directory
/usr/local/bin.
installed in the bin directory. At the time of this writing,
we find the following programs:
-sdcc - The compiler.
-
-aslink -The linker for 8051 type processors.
-
-asx8051 - The assembler for 8051 type processors.
+<pending: tabularize this>
+sdcc - The compiler.
sdcpp - The C preprocessor.
-
-sdcpd - The source debugger.
-
-s51 - The ucSim 8051 simulator.
-
-linkz80, linkgbz80 - The Z80 and GameBoy Z80 linkers.
-
+asx8051 - The assembler for 8051 type processors.
as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers.
-
+aslink -The linker for 8051 type processors.
+link-z80, link-gbz80 - The Z80 and GameBoy Z80 linkers.
+s51 - The ucSim 8051 simulator.
+sdcdb - The source debugger.
packihx - A tool to pack Intel hex files.
As development for other processors proceeds, this list will
expand to include executables to support processors like
AVR, PIC, etc.
-2.8.1 cpp ( C-Preprocessor)
+2.8.1 sdcc - The Compiler
-The preprocessor is extracted into the directory SDCCDIR/cpp,
-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.
+This is the actual compiler, it in turn uses the c-preprocessor
+and invokes the assembler and linkage editor.
-2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)
+2.8.2 sdcpp (C-Preprocessor)
-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 SDCCDIR/asxxxx.
+The preprocessor 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.
-2.8.3 SDCC - The compiler
+2.8.3 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80
+ (The Assemblers and Linkage Editors)
-This is the actual compiler, it in turn uses the c-preprocessor
-and invokes the assembler and linkage editors. All files
-with the prefix SDCC are part of the compiler and are extracted
-into the the directory SDCCDIR.
+This is retargettable assembler & linkage editor, it was
+developed by Alan Baldwin. John Hartman created the version
+for 8051, and I (Sandeep) have made some enhancements and
+bug fixes for it to work properly with the SDCC.
-2.8.4 S51 - Simulator
+2.8.4 s51 - Simulator
-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/>.
+S51 is a freeware, opensource simulator developed by Daniel
+Drotos ([mailto:drdani@mazsola.iit.uni-miskolc.hu]).
+The simulator 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] .
-2.8.5 SDCDB - Source Level Debugger
+2.8.5 sdcdb - Source Level Debugger
-SDCDB is the companion source level debugger. The current
+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.
For single source file 8051 projects the process is very
simple. Compile your programs with the following command
+"sdcc sourcefile.c". This will compile, assemble and link
+your source file. Output files are as follows
+
+sourcefile.asm - Assembler source file created by the compiler
+sourcefile.lst - Assembler listing file created by the Assembler
+sourcefile.rst - Assembler listing file updated with linkedit
+information, created by linkage editor
+sourcefile.sym - symbol listing for the sourcefile, created
+by the assembler
+sourcefile.rel - Object file created by the assembler, input
+to Linkage editor
+sourcefile.map - The memory map for the load module, created
+by the Linker
+sourcefile.ihx - The load module in Intel hex format (you
+can select the Motorola S19 format with --out-fmt-s19)
+sourcefile.cdb - An optional file (with --debug) containing
+debug information
-sdcc sourcefile.c
-
-The above command will compile ,assemble and link your source
-file. Output files are as follows.
-
-* sourcefile.asm - Assembler source file created by the compiler
-
-* sourcefile.lst - Assembler listing file created by the
- Assembler
-
-* sourcefile.rst - Assembler listing file updated with linkedit
- information , created by linkage editor
-
-* sourcefile.sym - symbol listing for the sourcefile, created
- by the assembler.
-
-* sourcefile.rel - Object file created by the assembler,
- input to Linkage editor.
-
-* sourcefile.map - The memory map for the load module, created
- by the Linker.
-
-* sourcefile.ihx - The load module in Intel hex format (you
- can select the Motorola S19 format with --out-fmt-s19)
-
-* sourcefile.cdb - An optional file (with --debug) containing
- debug information.
3.1.2 Projects with Multiple Source Files
SDCC can compile only ONE file at a time. Let us for example
assume that you have a project containing the following
-files.
-
-foo1.c ( contains some functions )
+files:
+foo1.c (contains some functions)
foo2.c (contains some more functions)
-
foomain.c (contains more functions and the function main)
The first two files will need to be compiled separately with
-the commands
+the commands:
sdcc -c foo1.c
-
sdcc -c foo2.c
-Then compile the source file containing main and link the
-other files together with the following command.
+Then compile the source file containing the main() function
+and link the files together with the following command:
+
sdcc foomain.c foo1.rel foo2.rel
-Alternatively foomain.c can be separately compiled as well
+Alternatively, foomain.c can be separately compiled as well:
-sdcc -c foomain.c
+sdcc -c foomain.c
sdcc foomain.rel foo1.rel foo2.rel
-The file containing the main function MUST be the FIRST file
-specified in the command line , since the linkage editor
+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.
3.1.3 Projects with Additional Libraries
Some reusable routines may be compiled into a library, see
-the documentation for the assembler and linkage editor in
-the directory SDCCDIR/asxxxx/asxhtm.htm this describes how
-to create a .lib 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 'foomain.c' and a library
-'foolib.lib' in the directory 'mylib' (if that is not the
-same as your current project).
+the documentation for the assembler and linkage editor (which
+are in <installdir>/share/sdcc/doc) for how to create a
+.lib library file. Libraries created in this manner can
+be included in the command line. Make sure you include the
+-L <library-path> option to tell the linker where to look
+for these files if they are not in the current directory.
+Here is an example, assuming you have the source file foomain.c
+and a library foolib.lib in the directory mylib (if that
+is not the same as your current project):
sdcc foomain.c foolib.lib -L mylib
-Note here that 'mylib' must be an absolute path name.
+Note here that mylib must be an absolute path name.
-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.
+The most efficient way to use libraries is to keep seperate
+modules in seperate source files. The lib file now should
+name all the modules.rel files. For an example see the standard
+library file libsdcc.lib in the directory <installdir>/share/lib/small.
3.2 Command Line Options
-D<macro[=value]> Command line definition of macros. Passed
to the pre processor.
---compile-only(-c) will compile and assemble the source,
-but will not call the linkage editor.
+-M 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'.
+
+-C Tell the preprocessor not to discard comments. Used with
+the `-E' option.
+
+-MM Like `-M' but the output mentions only the user header
+files included with `#include "file"'.
+System header files included with `#include <file>' are
+omitted.
+
+-Aquestion(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.
+
+-Aquestion (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.
+
+-Umacro Undefine macro macro. `-U' options are evaluated
+after all `-D' options, but before any `-include' and `-imacros'
+options.
+
+-dM 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.
+
+-dD Tell the preprocessor to pass all macro definitions into
+the output, in their proper sequence in the rest of the
+output.
+
+-dN Like `-dD' except that the macro arguments and contents
+are omitted. Only `#define name' is included in the output.
3.2.3 Linker Options
--
-lib-path(-L) <absolute path to additional libraries> This
+-
L --lib-path <absolute path to additional libraries> This
option is passed to the linkage editor's additional libraries
search path. The path name must be absolute. Additional
library files may be specified in the command line. See
or Decimal format, e.g.: --xram-loc 0x8000 or --xram-loc
32768.
---code-loc<Value> The start location of the code segment
-, default value 0. Note when this option is used the interrupt
+--code-loc<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, e.g.:
--code-loc 0x8000 or --code-loc 32768.
be in Hexadecimal or Decimal format, eg. --idata-loc 0x88
or --idata-loc 136.
+--out-fmt-ihx The linker output (final object code) is in
+Intel Hex format. (This is the default option).
+
+--out-fmt-s19 The linker output (final object code) is in
+Motorola S19 format.
+
3.2.4 MCS51 Options
--model-large 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.
+are compiled with small model, they will need to be recompiled.
--model-small Generate code for Small Model programs see
section Memory Models for more details. This is the default
model.
---stack-auto All functions in the source file will be compiled
-as reentrant, 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.
+3.2.5 DS390 Options
---xstack 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.
+--model-flat24 Generate 24-bit flat mode code. This is the
+one and only that the ds390 code generator supports right
+now and is default when using -mds390. See section Memory
+Models for more details.
-3.2.5 Optimization Options
+--stack-10bit Generate code for the 10 bit stack mode of
+the Dallas DS80C390 part. This is the one and only that
+the ds390 code generator supports right now and is default
+when using -mds390. 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 will
+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).
+
+3.2.6 Optimization Options
--nogcse 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 ,
+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.
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.
+NOT be used, #pragma NOINVARIANT can
+be used to turn off invariant optimizations for a given
+function only.
--noinduction 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.
+section strength reduction for more details.It is recommended
+that this option is NOT used, #pragma NOINDUCTION
+can be used to turn off induction optimizations for a given
+function only.
--nojtbound 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.
+section Switch Statements for more details. It is recommended
+that this option is NOT used, #pragma NOJTBOUND
+can be used to turn off boundary checking for jump tables
+for a given function only.
---noloopreverse Will not do loop reversal optimization
+--noloopreverse Will not do loop reversal optimization.
-3.2.6 DS390 Options
+3.2.7 Other Options
---stack-auto See MCS51 section for description.
+-c --compile-only will compile and assemble the source,
+but will not call the linkage editor.
---model-flat24 Generate 24-bit flat mode code. This is the
-one and only that the ds390 code generator supports right
-now and is default when using -mds390. See section Memory
-Models for more details.
+-E Run only the C preprocessor. Preprocess all the C source
+files specified and output the results to standard output.
---stack-10bit This option generates code for the 10 bit stack
-mode of the Dallas DS80C390 part. This is the one and only
-that the ds390 code generator supports right now and is
-default when using -mds390. 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 will 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).
+--stack-auto All functions in the source file will be compiled
+as reentrant, 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.
-3.2.7 Other Options
+--xstack 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.
--callee-saves function1[,function2][,function3].... The
compiler by default uses a caller saves convention for register
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.
+Also see #pragma CALLEE-SAVES.
--debug When this option is used the compiler will generate
-debug information , that can be used with the SDCDB. The
+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.
---regextend 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.
+--regextend This option is obsolete and isn't supported
+anymore.
+
+--noregparms This option is obsolete and isn't supported
+anymore.
--peep-file<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.
--E Run only the C preprocessor. Preprocess all the C source
-files specified and output the results to standard output.
-
--M 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'.
-
--C Tell the preprocessor not to discard comments. Used with
-the `-E' option.
-
--MM Like `-M' but the output mentions only the user header
-files included with `#include "file"'.
-System header files included with `#include <file>' are
-omitted.
-
--Aquestion(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.
-
--Aquestion (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.
-
--Umacro Undefine macro macro. `-U' options are evaluated
-after all `-D' options, but before any `-include' and `-imacros'
-options.
-
--dM 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.
-
--dD Tell the preprocessor to pass all macro definitions into
-the output, in their proper sequence in the rest of the
-output.
-
--dN Like `-dD' except that the macro arguments and contents
-are omitted. Only `#define name' is included in the output.
-
-S Stop after the stage of compilation proper; do not assemble.
The output is an assembler code file for the input file
specified.
--float-reent Floating point library is compiled as reentrant.See
section Installation for more details.
---out-fmt-ihx The linker output (final object code) is in
-Intel Hex format. (This is the default option).
-
---out-fmt-s19 The linker output (final object code) is in
-Motorola S19 format.
-
--nooverlay The compiler will not overlay parameters and
local variables of any function, see section Parameters
and local variables for more details.
--iram-size<Value> Causes the linker to check if the interal
ram usage is within limits of the given value.
+--nostdincl This will prevent the compiler from passing on
+the default include path to the preprocessor.
+
+--nostdlib This will prevent the compiler from passing on
+the default library path to the linker.
+
+--verbose Shows the various actions the compiler is performing.
+
+-V Shows the actual commands the compiler is executing.
+
3.2.8 Intermediate Dump Options
The following options are provided for the purpose of retargetting
--dumprange Will create a dump of iCode's, after live range
analysis, into a file named <source filename>.dumprange.
---dumlrange Will dump the life ranges for all symbols
+--dumlrange Will dump the life ranges for all symbols.
--dumpregassign Will create a dump of iCode's, after register
-assignment , into a file named <source filename>.dumprassgn.
+assignment, into a file named <source filename>.dumprassgn.
--dumplrange Will create a dump of the live ranges of iTemp's
3.3.4 bit
This is a data-type and a storage class specifier. When a
-variable is declared as a bit , it is allocated into the
+variable is declared as a bit, it is allocated into the
bit addressable memory of 8051, e.g.:
bit iFlag;
class of pointers which can be used to point to any of the
memory spaces.
-Pointer declaration examples.
+Pointer declaration examples:
/* pointer physically in xternal ram pointing to object in
internal ram */
xdata space */
char * xdata p;
-Well you get the idea. For compatibility with the previous
-version of the compiler, the following syntax for pointer
-declaration is still supported but will disappear int the
-near future.
+Well you get the idea.
+
+For compatibility with the previous version of the compiler,
+the following syntax for pointer declaration is still supported
+but will disappear int the near future.
unsigned char _xdata *ucxdp; /* pointer to data in external
ram */
pointer to upper 128 bytes of ram */
All unqualified pointers are treated as 3-byte (4-byte for
-the ds390) '_generic' pointers. These type of pointers can
+the ds390) generic pointers. These type of pointers can
also to be explicitly declared.
unsigned char _generic *ucgp;
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.
+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.
+OLD and NEW style could have unpredictable results.
3.5 Parameters & Local Variables
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 --stack-auto compiler option or by using the 'reentrant'
-keyword in the function declaration, e.g.:
+internal RAM (for small model) or external RAM (for Large
+model). This in fact makes them static so by default functions
+are non-reentrant.
-unsigned char foo( char i) reentrant
+They can be placed on the stack either by using the --stack-auto
+compiler option or by using the reentrant keyword in the
+function declaration, e.g.:
+
+unsigned char foo(char i) reentrant
{
...
}
-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 'reentrant' keyword
+Since stack space on 8051 is limited, the reentrant keyword
or the --stack-auto 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.
+that 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.
-When compiled with the default option (i.e. non-reentrant
-), local variables can be assigned storage classes and absolute
-addresses, e.g.: (jwk: pending: this is obsolete and need
-a rewrite)
+Local variables can be assigned storage classes and absolute
+addresses, e.g.:
unsigned char foo() {
-
-xdata unsigned char i;
-
-bit bvar;
-
-data at 0x31 unsiged char j;
-
-...
+ xdata unsigned char i;
+ bit bvar;
+ data at 0x31 unsiged char j;
+ ...
}
In the above example the variable i will be allocated in
the external ram, bvar in bit addressable space and j in
-internal ram. When compiled with the --stack-auto or when
-a function is declared as 'reentrant' local variables cannot
-be assigned storage classes or absolute addresses.
+internal ram. When compiled with --stack-auto or when a
+function is declared as reentrant this can only be done
+for static variables.
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
+is governed by the memory model in use, and the reentrancy
options.
3.6 Overlaying
of a function will be allocated to an overlayable segment
if the function has no other function calls and the function
is non-reentrant and the memory model is small. If an explicit
-storage class is specified for a local variable , it will
-NOT be overplayed.
+storage class is specified for a local variable, it will
+NOT be overlayed.
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
+by a #pragma NOOVERLAY if they are not reentrant.
+
+Also note that the compiler does not do any processing of
+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.
+the overlay segment if the inline assembler code calls other
+c-functions that might use the overlay. In that case the
+#pragma NOOVERLAY should be used.
Parameters and Local variables of functions that contain
16 or 32 bit multiplication or division will NOT be overlayed
#pragma SAVE
#pragma NOOVERLAY
-void set_error( unsigned char errcd)
+void set_error(unsigned char errcd)
{
-
-P3 = errcd;
+ P3 = errcd;
}
#pragma RESTORE
+
void some_isr () interrupt 2 using 1
{
-
-...
-
-set_error(10);
-
-...
+ ...
+ set_error(10);
+ ...
}
In the above example the parameter errcd for the function
-set_error would be assigned to the overlayable segment (if
-the #pragma NOOVERLAY was not present) , this could cause
-unpredictable runtime behavior when called from an ISR.
-The pragma NOOVERLAY ensures that the parameters and local
-variables for the function are NOT overlayed.
+set_error would be assigned to the overlayable segment if
+the #pragma NOOVERLAY was not present, this could
+cause unpredictable runtime behavior when called from an
+ISR. The #pragma NOOVERLAY ensures that
+the parameters and local variables for the function are
+NOT overlayed.
3.7 Interrupt Service Routines
..
}
-The number following the 'interrupt' keyword is the interrupt
+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
+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)
+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
+(as mentioned in a following section) will have to be recompiled
using the --stack-auto option and the source file will need
to be compiled using the --int-long-rent compiler option.
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 'main'.
+of the isr MUST be present or included in the file that
+contains the function main.
Interrupt Numbers and the corresponding address & descriptions
for the Standard 8051 are listed below. SDCC will automatically
+--------------+--------------+----------------+
-
-If the interrupt service routine is defined without 'using'
+If the interrupt service routine is defined without using
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
+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.
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.
+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.
Calling other functions from an interrupt service routine
-is not recommended avoid it if possible.
+is not recommended, avoid it if possible.
+
+Also see the _naked modifier.
3.8 Critical Functions
A special keyword may be associated with a function declaring
-it as 'critical'. 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.
-
-eg:
+it as critical. 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.
int foo () critical
{
3.9 Naked Functions
A special keyword may be associated with a function declaring
-it as '_naked'. The '_naked' function modifier attribute
-prevents the compiler from generating prologue and epilogue
-code for that function. This means that the user is entirely
+it as _naked. The _naked function modifier attribute prevents
+the compiler from generating prologue and epilogue code
+for that function. This means that the user is entirely
responsible for such things as saving any registers that
may need to be preserved, selecting the proper register
-bank, generating the 'return' instruction at the end, etc.
+bank, generating the return instruction at the end, etc.
Practically, this means that the contents of the function
must be written in inline assembler. This is particularly
useful for interrupt functions, which can have a large (and
the code generated by these two functions:
data unsigned char counter;
-void simpleIterrupt(void) interrupt 1
+void simpleInterrupt(void) interrupt 1
{
-
-counter++;
+ counter++;
}
void nakedInterrupt(void) interrupt 2 _naked
{
-
-_asm
-
- inc _counter
-
- reti
-; MUST explicitly include ret in _naked function.
-
-_endasm;
+ _asm
+ inc _counter
+ reti ;
+MUST explicitly include ret in _naked function.
+ _endasm;
}
For an 8051 target, the generated simpleInterrupt looks like:
_simpleIterrupt:
-
-push acc
-
-push b
-
-push dpl
-
-push dph
-
-push psw
-
-mov psw,#0x00
-
-inc _counter
-
-pop psw
-
-pop dph
-
-pop dpl
-
-pop b
-
-pop acc
-
-reti
+ push acc
+ push b
+ push dpl
+ push dph
+ push psw
+ mov psw,#0x00
+ inc _counter
+ pop psw
+ pop dph
+ pop dpl
+ pop b
+ pop acc
+ reti
whereas nakedInterrupt looks like:
_nakedInterrupt:
-
-inc _counter
-
-reti
-; MUST explicitly include ret(i) in _naked function.
+ inc _counter
+ reti ; MUST explicitly
+include ret(i) in _naked function.
While there is nothing preventing you from writing C code
inside a _naked function, there are many ways to shoot yourself
3.10 Functions using private banks
-The 'using' attribute (which tells the compiler to use a
-register bank other than the default bank zero) should only
-be applied to 'interrupt' functions (see note A below).
-This will in most circumstances make the generated ISR code
-more efficient since it will not have to save registers
-on the stack.
+The using attribute (which tells the compiler to use a register
+bank other than the default bank zero) should only be applied
+to interrupt functions (see note 1 below). This will in
+most circumstances make the generated ISR code more efficient
+since it will not have to save registers on the stack.
-The 'using' attribute will have no effect on the generated
-code for a non-'interrupt' function (but may occasionally
+The using attribute will have no effect on the generated
+code for a non-interrupt function (but may occasionally
be useful anyway([footnote] possible exception: if a function is called ONLY
from 'interrupt' functions using a particular bank, it can
be declared with the same 'using' attribute as the calling
1', since this would prevent the ISR from having to save
bank zero to the stack on entry and switch to bank zero
before calling the function) ).
-(jwk: todo: I don't think this has been done yet)
-
-An 'interrupt' function using a non-zero bank will assume
-that it can trash that register bank, and will not save
-it. Since high-priority interrupts can interrupt low-priority
-ones on the 8051 and friends, this means that if a high-priority
-ISR 'using' a particular bank occurs while processing a
-low-priority ISR 'using' the same bank, terrible and bad
-things can happen. To prevent this, no single register bank
-should be 'used' by both a high priority and a low priority
-ISR. This is probably most easily done by having all high
-priority ISRs use one bank and all low priority ISRs use
-another. If you have an ISR which can change priority at
-runtime, you're on your own: I suggest using the default
-bank zero and taking the small performance hit.
+(pending: I don't think this has been done yet)
+
+An interrupt function using a non-zero bank will assume that
+it can trash that register bank, and will not save it. Since
+high-priority interrupts can interrupt low-priority ones
+on the 8051 and friends, this means that if a high-priority
+ISR using a particular bank occurs while processing a low-priority
+ISR using the same bank, terrible and bad things can happen.
+To prevent this, no single register bank should be used
+by both a high priority and a low priority ISR. This is
+probably most easily done by having all high priority ISRs
+use one bank and all low priority ISRs use another. If you
+have an ISR which can change priority at runtime, you're
+on your own: I suggest using the default bank zero and taking
+the small performance hit.
It is most efficient if your ISR calls no other functions.
If your ISR must call other functions, it is most efficient
if those functions use the same bank as the ISR (see note
-A below); the next best is if the called functions use bank
+1 below); the next best is if the called functions use bank
zero. It is very inefficient to call a function using a
different, non-zero bank from an ISR.
3.11 Absolute Addressing
Data items can be assigned an absolute address with the at
-<address> keyword, in addition to a storage class.
-
-eg.
+<address> keyword, in addition to a storage class, e.g.:
xdata at 0x8000 unsigned char PORTA_8255 ;
In the above example the PORTA_8255 will be allocated to
-the location 0x8000 of the external ram.
-
-Note that is this feature is provided to give the programmer
-access to memory mapped 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.
+the location 0x8000 of the external ram. Note that this
+feature is provided to give the programmer access to memory
+mapped 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 (.rst) and (.map) are
+a good places to look for such overlaps.
Absolute address can be specified for variables in all storage
-classes.
-
-eg.
+classes, e.g.:
bit at 0x02 bvar;
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.
+to assigning absolute addresses to variables in this manner,
+unless you want strict control over all the variables allocated.
3.12 Startup Code
-The compiler inserts a jump to the C routine _sdcc__external__startup()
-at the start of the CODE area. This routine can be found
-in the file SDCCDIR/sdcc51lib/_startup.c, 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 _sdcc__external__startup()
-routine to your program to override the default if you needed
+The compiler inserts a call to the C routine _sdcc__external__startup()
+at the start of the CODE area. This routine is in the runtime
+library. 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 _sdcc__external__startup()
+routine to your program to override the default if you need
to setup hardware or perform some other critical operation
prior to static & global variable initialization.
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 form nnnnn$ where nnnn is a number
+code has to be of the form nnnnn$ where nnnn is a number
less than 100 (which implies a limit of utmost 100 inline
assembler labels per function). It is strongly recommended
that each assembly instruction (including labels) be placed
-in a separate line ( as the example shows). When the --peep-asm
+in a separate line (as the example shows). When the --peep-asm
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
+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.
-
-eg
+SDCCpeeph.def carefully before using this option.
_asm
- mov b,#10
+ mov b,#10
+
00001$:
- djnz b,00001$
+ djnz b,00001$
+
_endasm ;
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
+by the assembler, this includes any assembler directives
+and comment lines. The compiler does not do any validation
of the code within the _asm ... _endasm; keyword pair.
-Inline assembler code cannot reference any C-Labels however
-it can reference labels defined by the inline assembler.
-
-eg
+Inline assembler code cannot reference any C-Labels, however
+it can reference labels defined by the inline assembler,
+e.g.:
foo() {
-... /* some c code */
-_asm
- ; some assembler code
- ljmp $0003
-_endasm ;
-... /* some more c code */
-clabel: /* inline assembler cannot reference this
-label */
-_asm
- $0003: ;label (can be reference by inline assembler
+ /* some c code */
+ _asm
+ ; some assembler code
+ ljmp $0003
+ _endasm;
+ /* some more c code */
+clabel: /* inline assembler cannot reference
+this label */
+ _asm
+ $0003: ;label (can be reference by inline assembler
only)
-_endasm ;
-...
+ _endasm ;
+ /* some more c code */
}
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.
+in inline assembly within the scope of the funtion.
-3.14 int(16 bit) and long (32 bit ) Support
+The same goes the other way, ie. labels defines in inline
+assembly CANNOT be accessed by C statements.
+
+3.14 int(16 bit) and long (32 bit) Support
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
-
-* _mulsint.c - signed 16 bit multiplication (calls _muluint)
-
-* _muluint.c - unsigned 16 bit multiplication
-
-* _divsint.c - signed 16 bit division (calls _divuint)
-
-* _divuint.c - unsigned 16 bit division.
-
-* _modsint.c - signed 16 bit modulus (call _moduint)
-
-* _moduint.c - unsigned 16 bit modulus.
-
-* _mulslong.c - signed 32 bit multiplication (calls _mululong)
-
-* _mululong.c - unsigned32 bit multiplication.
-
-* _divslong.c - signed 32 division (calls _divulong)
-
-* _divulong.c - unsigned 32 division.
-
-* _modslong.c - signed 32 bit modulus (calls _modulong).
-
-* _modulong.c - unsigned 32 bit modulus.
-
-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.
+in ANSI-C to facilitate porting to other MCUs, although
+some model specific assembler optimations are used. The
+following files contain the described routine, all of them
+can be found in <installdir>/share/sdcc/lib.
+
+<pending: tabularise this>
+
+_mulsint.c - signed 16 bit multiplication (calls _muluint)
+_muluint.c - unsigned 16 bit multiplication
+_divsint.c - signed 16 bit division (calls _divuint)
+_divuint.c - unsigned 16 bit division
+_modsint.c - signed 16 bit modulus (call _moduint)
+_moduint.c - unsigned 16 bit modulus
+_mulslong.c - signed 32 bit multiplication (calls _mululong)
+_mululong.c - unsigned32 bit multiplication
+_divslong.c - signed 32 division (calls _divulong)
+_divulong.c - unsigned 32 division
+_modslong.c - signed 32 bit modulus (calls _modulong)
+_modulong.c - unsigned 32 bit modulus
+
+Since they are compiled as non-reentrant, interrupt service
+routines should not do any of the above operations. If this
+is unavoidable then the above routines will need to be compiled
+with the --stack-auto option, after which the source program
+will have to be compiled with --int-long-rent option.
3.15 Floating Point Support
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.
-
-* _fsadd.c - add floating point numbers.
-
-* _fssub.c - subtract floating point numbers
-
-* _fsdiv.c - divide floating point numbers
-
-* _fsmul.c - multiply floating point numbers
-
-* _fs2uchar.c - convert floating point to unsigned char
-
-* _fs2char.c - convert floating point to signed char.
-
-* _fs2uint.c - convert floating point to unsigned int.
-
-* _fs2int.c - convert floating point to signed int.
-
-* _fs2ulong.c - convert floating point to unsigned long.
-
-* _fs2long.c - convert floating point to signed long.
-
-* _uchar2fs.c - convert unsigned char to floating point
-
-* _char2fs.c - convert char to floating point number
-
-* _uint2fs.c - convert unsigned int to floating point
-
-* _int2fs.c - convert int to floating point numbers
-
-* _ulong2fs.c - convert unsigned long to floating point number
-
-* _long2fs.c - convert long to floating point number.
+from gcc's floatlib.c and consists of the following routines:
+
+<pending: tabularise this>
+
+_fsadd.c - add floating point numbers
+_fssub.c - subtract floating point numbers
+_fsdiv.c - divide floating point numbers
+_fsmul.c - multiply floating point numbers
+_fs2uchar.c - convert floating point to unsigned char
+_fs2char.c - convert floating point to signed char
+_fs2uint.c - convert floating point to unsigned int
+_fs2int.c - convert floating point to signed int
+_fs2ulong.c - convert floating point to unsigned long
+_fs2long.c - convert floating point to signed long
+_uchar2fs.c - convert unsigned char to floating point
+_char2fs.c - convert char to floating point number
+_uint2fs.c - convert unsigned int to floating point
+_int2fs.c - convert int to floating point numbers
+_ulong2fs.c - convert unsigned long to floating point number
+_long2fs.c - convert long to floating point number
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)
+is strongly recommended that the large model be used.
3.16 MCS51 Memory Models
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.
+that you can link to either set.
When the large model is used all variables declared without
a storage class will be allocated into the external ram,
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
+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.
-3.17 Flat 24 bit Addressing Model
+3.17 DS390 Memory Models
-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.
+The only model supported is Flat 24. This 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.
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.
+
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
+the processor into 24 bitmode (although tinibios in the
+ds390 libraries will do that for you). If you don't use
+tinibios, the boot loader or similar code must ensure that
+the processor is in 24 bit contiguous addressing mode before
calling the SDCC startup code.
Like the --model-large option, variables will by default
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.
+command line. However, currently the linker can not handle
+code segments > 64k.
3.18 Defines Created by the Compiler
* SDCC - this Symbol is always defined.
+* SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on
+ the model used (e.g.: -mds390)
+
+* __mcs51 or __ds390 or __z80, etc - depending on the model
+ used (e.g. -mz80)
+
* SDCC_STACK_AUTO - this symbol is defined when --stack-auto
option is used.
-* SDCC_MODEL_SMALL - when small model is used.
+* SDCC_MODEL_SMALL - when --model-small is used.
* SDCC_MODEL_LARGE - when --model-large is used.
* SDCC_USE_XSTACK - when --xstack option is used.
+* SDCC_STACK_TENBIT - when -mds390 is used
+
+* SDCC_MODEL_FLAT24 - when -mds390 is used
+
4 SDCC Technical Data
4.1 Optimizations
-SDCC performs a a host of standard optimizations in addition
+SDCC performs a host of standard optimizations in addition
to some MCU specific optimizations.
4.1.1 Sub-expression Elimination
-The compiler does local and global common subexpression elimination.
-
-eg.
+The compiler does local and global common subexpression elimination,
+e.g.:
i = x + y + 1;
j = x + y;
i = iTemp + 1
j = iTemp
-Some subexpressions are not as obvious as the above example.
-
-eg.
+Some subexpressions are not as obvious as the above example,
+e.g.:
a->b[i].c = 10;
a->b[i].d = 11;
4.1.2 Dead-Code Elimination
-eg.
-
int global;
void f () {
int i;
- i = 1; /* dead store
-*/
+ i = 1; /* dead store */
global = 1; /* dead store */
global = 2;
return;
will be changed to
int global; void f ()
-{
- global = 2;
- return;
+{
+ global = 2;
+ return;
}
4.1.3 Copy-Propagation
-eg.
-
int f() {
- int i, j;
- i = 10;
- j = i;
- return j;
+ int i, j;
+ i = 10;
+ j = i;
+ return j;
}
will be changed to
4.1.4 Loop Optimizations
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
+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
+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).
+entire source file (with --noinduction option) or for a
+given function only using #pragma NOINDUCTION.
-* Loop Invariant:
-
-eg
+Loop Invariant:
for (i = 0 ; i < 100 ; i ++)
- f += k + l;
+ f += k + l;
changed to
itemp = k + l;
-for ( i = 0; i < 100; i++ ) f += itemp;
+for (i = 0; i < 100; i++)
+ f += itemp;
As mentioned previously some loop invariants are not as apparent,
all static address computations are also moved out of the
loop.
-* Strength Reduction :
+Strength Reduction, this optimization substitutes an expression
+by a cheaper expression:
-This optimization substitutes an expression by a cheaper
-expression.
-
-eg.
-
-for (i=0;i < 100; i++) ar[i*5] = i*3;
+for (i=0;i < 100; i++)
+ ar[i*5] = i*3;
changed to
itemp1 = 0;
itemp2 = 0;
for (i=0;i< 100;i++) {
- ar[itemp1] = itemp2;
- itemp1 += 5;
- itemp2 += 3;
+ ar[itemp1] = itemp2;
+ itemp1 += 5;
+ itemp2 += 3;
}
The more expensive multiplication is changed to a less expensive
addition.
-4.1.5 Loop Reversing:
+4.1.5 Loop Reversing
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
+is reversible (note: more sophisticated compilers use data-dependency
analysis to make this determination, SDCC uses a more simple
minded analysis).
* The 'for' loop is of the form
- "for ( <symbol> = <expression> ; <sym> [< | <=] <expression>
+
+ for (<symbol> = <expression> ; <sym> [< | <=] <expression>
; [<sym>++ | <sym> += 1])
- <for body>"
+ <for body>
* The <for body> does not contain "continue"
or 'break".
* There are NO switch statements in the loop.
-Note djnz instruction can be used for 8-bit values ONLY,
+Note djnz instruction can be used for 8-bit values only,
therefore it is advantageous to declare loop control symbols
-as either 'char', ofcourse this may not be possible on all
-situations.
+as char. Ofcourse this may not be possible on all situations.
4.1.6 Algebraic Simplifications
SDCC does numerous algebraic simplifications, the following
is a small sub-set of these optimizations.
-eg
i = j + 0 ; /* changed to */ i = j;
i /= 2; /* changed to */ i >>= 1;
i = j - j ; /* changed to */ i = 0;
SDCC changes switch statements to jump tables when the following
conditions are true.
-* The case labels are in numerical sequence , the labels
- need not be in order, and the starting number need not
- be one or zero.
-
-eg
+* The case labels are in numerical sequence, the labels need
+ not be in order, and the starting number need not be one
+ or zero.
switch(i) {
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.
-
-eg
+into more than one switch statement for efficient code generation,
+e.g.:
switch (i) {
case 1: ...
case 4: ...
}
+and
+
switch (i) {
-case 9: ...
+case 9: ...
case 10: ...
case 11: ...
-case 12:...
+case 12: ...
}
then both the switch statements will be implemented using
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.
-
-eg.
+operations in the most efficient way possible, e.g.:
unsigned char i;
-
...
i>>= 4;
-..
+...
-generates the following code.
+generates the following code:
mov a,_i
swap a
mov _i,a
In general SDCC will never setup a loop if the shift count
-is known. Another example
+is known. Another example:
unsigned int i;
...
i >>= 9;
...
-will generate
+will generate:
mov a,(_i + 1)
mov (_i + 1),#0x00
mov _i,a
Note that SDCC stores numbers in little-endian format (i.e.
-lowest order first)
+lowest order first).
4.1.9 Bit-rotation
A special case of the bit-shift operation is bit rotation,
-SDCC recognizes the following expression to be a left bit-rotation.
+SDCC recognizes the following expression to be a left bit-rotation:
unsigned char i;
...
-i = ( ( i << 1) | ( i >> 7));
+i = ((i << 1) | (i >> 7));
...
-will generate the following code.
+will generate the following code:
mov a,_i
rl a
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 >> 7) | (i << 1)); /* left-bit
-rotation */
+as bit-rotation, i.e.:
+
+i = ((i >> 7) | (i << 1)); /* left-bit rotation */
4.1.10 Highest Order Bit
It is frequently required to obtain the highest order bit
of an integral type (long, int, short or char types). SDCC
recognizes the following expression to yield the highest
-order bit and generates optimized code for it.
+order bit and generates optimized code for it, e.g.:
+
+ unsigned int gint;
-eg
-unsigned int gint;
foo () {
unsigned char hob;
- ...
- hob = (gint >> 15) & 1;
- ..
+ ...
+ hob = (gint >> 15) & 1;
+ ..
}
-Will generate the following code.
+will generate the following code:
61 ; hob.c 7
66 mov
_foo_hob_1_1,a
-Variations of this case however will NOT be recognized. It
-is a standard C expression , so I heartily recommend this
+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.
-
-eg.
+other expressions, e.g.:
xyz = gint + ((gint >> 15) & 1);
4.1.11 Peep-hole Optimizer
-The compiler uses a rule based , pattern matching and re-writing
+The compiler uses a rule based, pattern matching and re-writing
mechanism for peep-hole optimization. It is inspired by
-'copt' a peep-hole optimizer by Christopher W. Fraser (cwfraser@microsoft.com).
+copt 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.
replace {
-mov %1,a
-mov a,%1 } by { mov %1,a }
+ mov %1,a
+ mov a,%1
+} by {
+ mov %1,a
+}
-The above rule will the following assembly sequence
+The above rule will change the following assembly sequence:
-mov r1,a
-mov a,r1
+ mov r1,a
+ mov a,r1
to
mov r1,a
-Note: All occurrences of a '%n' ( pattern variable ) must
-denote the same string. With the above rule, the assembly
-sequence
+Note: All occurrences of a %n (pattern variable) must denote
+the same string. With the above rule, the assembly sequence:
-mov r1,a
-mov a,r2
+ mov r1,a
+ mov a,r2
-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'.
+will remain unmodified.
+
+Other special case optimizations may be added by the user
+(via --peep-file option). E.g. some variants of the 8051
+MCU allow only ajmp and acall. The following two rules will
+change all ljmp and lcall to ajmp and acall
replace { lcall %1 } by { acall %1 }
replace { ljmp %1 } by { ajmp %1 }
-The inline-assembler' code is also passed through the peep
+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.
-The syntax for a rule is as follows ,
+The syntax for a rule is as follows:
rule := replace [ restart ] '{' <assembly sequence> '\n'
'}' [if <functionName>
] '\n'
+
<assembly sequence> := assembly instruction (each instruction
-including labels must be on a separate line).
+including labels must be on a separate line).
The optimizer will apply to the rules one by one from the
top in the sequence of their appearance, it will terminate
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.
+example of this the following rule:
replace restart {
-pop %1
-push %1 } by {
-; nop
+ pop %1
+ push %1 } by {
+ ; nop
}
Note that the replace pattern cannot be a blank, but can
be a comment line. Without the 'restart' option only the
-inner most 'pop' 'push' pair would be eliminated. i.e.
+inner most 'pop' 'push' pair would be eliminated, i.e.:
-pop ar1
-pop ar2
-push ar2
-push ar1
+ pop ar1
+ pop ar2
+ push ar2
+ push ar1
-would result in
+would result in:
pop ar1
; nop
push ar1
-with the 'restart' option the rule will be applied again
-to the resulting code and the all the 'pop' 'push' pairs
-will be eliminated to yield
+with the restart option the rule will be applied again to
+the resulting code and then all the pop-push pairs will
+be eliminated to yield:
; nop
; nop
%2:} if labelInRange
The optimizer does a look-up of a function name table defined
-in function 'callFuncByName' in the source file SDCCpeeph.c
-, with the name 'labelInRange', if it finds a corresponding
+in function callFuncByName in the source file SDCCpeeph.c,
+with the name labelInRange. 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 '%5'
+specified for these functions, in this case the use of %5
is crucial, since the function labelInRange 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 labelInRange and the calling mechanism in source
-file SDCCpeeph.c. I know this whole thing is a little kludgey
-, may be some day we will have some better means. If you
+want to code more such functions, take a close look at the
+function labelInRange and the calling mechanism in source
+file SDCCpeeph.c. I know this whole thing is a little kludgey,
+but maybe 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
+rules that are compiled into the compiler, you can add your
own rules in the default set there if you get tired of specifying
the --peep-file option.
+<pending: this is as far as I got>
+
4.2 Pragmas
SDCC supports the following #pragma directives. This directives
* NOINDUCTION - will stop loop induction optimizations.
-* NOJTBOUND - will not generate code for boundary value checking
- , when switch statements are turned into jump-tables.
+* NOJTBOUND - will not generate code for boundary value checking,
+ when switch statements are turned into jump-tables.
* NOOVERLAY - the compiler will not overlay the parameters
and local variables of a function.
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"
+ the normal register saving for ISR functions use #pragma EXCLUDE none.
* CALLEE-SAVES function1[,function2[,function3...]] - The
compiler by default uses a caller saves convention for
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.
+ option is used, the function names specified in #pragma CALLEE-SAVES
+ is appended to the list of functions specified inthe command
+ line.
The pragma's are intended to be used to turn-off certain
optimizations which might cause the compiler to generate
%s character _generic
pointer
-The routine is very stack intesive , --stack-after-data parameter
+The routine is very stack intesive, --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 putchar(char ) to be present (this can be
+function named putchar(char) to be present (this can be
changed). When using the %s format the string / pointer
should be cast to a generic pointer. eg.
and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
* ser_ir.h - Another alternate set of serial routines provided
- by Josef Wolf <jw@raven.inka.de> , these routines do not
+ by Josef Wolf <jw@raven.inka.de>, these routines do not
use the external ram.
* reg51.h - contains register definitions for a standard
* float.h - contains min, max and other floating point related
stuff.
-All library routines are compiled as --model-small , they
+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.
In the following example the function cfunc calls an assembler
routine asm_func, which takes two parameters.
-extern int asm_func( unsigned char, unsigned char);
+extern int asm_func(unsigned char, unsigned char);
int c_func (unsigned char i, unsigned char j)
4.5.2 Assembler Routine(reentrant)
In this case the second parameter onwards will be passed
-on the stack , the parameters are pushed from right to left
+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.
-extern int asm_func( unsigned char, unsigned char);
+extern int asm_func(unsigned char, unsigned char);
4.6 External Stack
The external stack is located at the start of the external
-ram segment , and is 256 bytes in size. When --xstack option
+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
5. Old K&R style function declarations are NOT allowed.
-foo( i,j) /* this old style of function declarations */
+foo(i,j) /* this old style of function declarations */
int i,j; /* are valid in ANSI .. not valid in SDCC */
{
...
the programmer should do an explicit cast when integral
promotion is required.
-* Reducing the size of division , multiplication & modulus
+* Reducing the size of division, multiplication & modulus
operations can reduce code size substantially. Take the
following code for example.
- foobar( unsigned int p1, unsigned char ch)
+ foobar(unsigned int p1, unsigned char ch)
{
unsigned char ch1 = p1 % ch ;
....
be performed (this will lead to a call to a support routine).
If the code is changed to
- foobar( unsigned int p1, unsigned char ch)
+ foobar(unsigned int p1, unsigned char ch)
{
unsigned char ch1 = (unsigned char)p1
% ch ;
1. 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
+ done in this phase, along with some initial optimizations
like back patching labels and the pattern matching optimizations
like bit-rotation etc.
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)
+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
* --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
+ 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
+ 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.
7.5 Debugger Commands.
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
+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.
XEmacs is running, set the environment variable 'EMACSLOADPATH'
to the installation bin directory [$(prefix)/bin], then
enter the following command ESC-x load-file sdcdbsrc. To
-start the interface enter the following command ESC-x sdcdbsrc
-, you will prompted to enter the file name to be debugged.
+start the interface enter the following command ESC-x sdcdbsrc,
+you will prompted to enter the file name to be debugged.
The command line options that are passed to the simulator
directly are bound to default values in the file sdcdbsrc.el
projects / fw / sdcc / commitdiff