<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+
+<!--Converted with LaTeX2HTML 2K.1beta (1.47)
+original version by: Nikos Drakos, CBLU, University of Leeds
+* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
+* with significant contributions from:
+ Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7">
- <TITLE>SDCC Compiler User Guide</TITLE>
- <LINK HREF="SDCCUdoc-1.html" REL=next>
+<TITLE>SDCC Compiler User Guide</TITLE>
+<META NAME="description" CONTENT="SDCC Compiler User Guide">
+<META NAME="keywords" CONTENT="SDCCUdoc">
+<META NAME="resource-type" CONTENT="document">
+<META NAME="distribution" CONTENT="global">
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+<META NAME="Generator" CONTENT="LaTeX2HTML v2K.1beta">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+<LINK REL="STYLESHEET" HREF="SDCCUdoc.css">
</HEAD>
-<BODY>
-<A HREF="SDCCUdoc-1.html">Next</A>
-Previous
-Contents
-<HR>
-<H1>SDCC Compiler User Guide</H1>
-<H2>Sandeep Dutta (sandeep.dutta@usa.net)</H2>
+<BODY >
+<!--Navigation Panel-->
+<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
+ SRC="file:/usr/share/latex2html/icons/nx_grp_g.png">
+<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
+ SRC="file:/usr/share/latex2html/icons/up_g.png">
+<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
+ SRC="file:/usr/share/latex2html/icons/prev_g.png">
+<BR>
+<BR>
+<BR>
+<!--End of Navigation Panel-->
+
<P>
-<H2><A NAME="toc1">1.</A> <A HREF="SDCCUdoc-1.html">Introduction</A></H2>
<P>
-<H2><A NAME="toc2">2.</A> <A HREF="SDCCUdoc-2.html">Installation </A></H2>
+<H1 ALIGN="CENTER">SDCC Compiler User Guide</H1>
+<BR>
+
+<H2><A NAME="SECTION00010000000000000000">
+Contents</A>
+</H2>
+<!--Table of Contents-->
<UL>
-<LI><A HREF="SDCCUdoc-2.html#ss2.1">2.1 Components of SDCC</A>
-<LI><A HREF="SDCCUdoc-2.html#ss2.2">2.2 Installation for Version <= 2.1.7</A>
-<LI><A HREF="SDCCUdoc-2.html#ss2.3">2.3 Installation for Version >= 2.1.8a</A>
+<LI><A NAME="tex2html119"
+ HREF="SDCCUdoc.html">1 Introduction</A>
+<UL>
+<LI><A NAME="tex2html120"
+ HREF="#SECTION00021000000000000000">1.1 About SDCC</A>
+<LI><A NAME="tex2html121"
+ HREF="#SECTION00022000000000000000">1.2 Open Source</A>
+<LI><A NAME="tex2html122"
+ HREF="#SECTION00023000000000000000">1.3 System Requirements</A>
+<LI><A NAME="tex2html123"
+ HREF="#SECTION00024000000000000000">1.4 Other Resources</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html124"
+ HREF="#SECTION00030000000000000000">2 Installation</A>
+<UL>
+<LI><A NAME="tex2html125"
+ HREF="#SECTION00031000000000000000">2.1 Linux/Unix Installation</A>
+<LI><A NAME="tex2html126"
+ HREF="#SECTION00032000000000000000">2.2 Windows Installation</A>
+<LI><A NAME="tex2html127"
+ HREF="#SECTION00033000000000000000">2.3 Testing out the SDCC Compiler</A>
+<LI><A NAME="tex2html128"
+ HREF="#SECTION00034000000000000000">2.4 Install Trouble-shooting</A>
+<LI><A NAME="tex2html129"
+ HREF="#SECTION00035000000000000000">2.5 Additional Information for Windows Users</A>
+<LI><A NAME="tex2html130"
+ HREF="#SECTION00036000000000000000">2.6 SDCC on Other Platforms</A>
+<LI><A NAME="tex2html131"
+ HREF="#SECTION00037000000000000000">2.7 Advanced Install Options</A>
+<LI><A NAME="tex2html132"
+ HREF="#SECTION00038000000000000000">2.8 Components of SDCC</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html133"
+ HREF="#SECTION00040000000000000000">3 Using SDCC</A>
+<UL>
+<LI><A NAME="tex2html134"
+ HREF="#SECTION00041000000000000000">3.1 Compiling</A>
+<LI><A NAME="tex2html135"
+ HREF="#SECTION00042000000000000000">3.2 Command Line Options</A>
+<LI><A NAME="tex2html136"
+ HREF="#SECTION00043000000000000000">3.3 MCS51 Storage Class Language Extensions</A>
+<LI><A NAME="tex2html137"
+ HREF="#SECTION00044000000000000000">3.4 Pointers</A>
+<LI><A NAME="tex2html138"
+ HREF="#SECTION00045000000000000000">3.5 Parameters & Local Variables</A>
+<LI><A NAME="tex2html139"
+ HREF="#SECTION00046000000000000000">3.6 Overlaying</A>
+<LI><A NAME="tex2html140"
+ HREF="#SECTION00047000000000000000">3.7 Critical Functions</A>
+<LI><A NAME="tex2html141"
+ HREF="#SECTION00048000000000000000">3.8 Absolute Addressing</A>
+<LI><A NAME="tex2html142"
+ HREF="#SECTION00049000000000000000">3.9 Interrupt Service Routines</A>
+<LI><A NAME="tex2html143"
+ HREF="#SECTION000410000000000000000">3.10 Startup Code</A>
+<LI><A NAME="tex2html144"
+ HREF="#SECTION000411000000000000000">3.11 Inline Assembler Code</A>
+<LI><A NAME="tex2html145"
+ HREF="#SECTION000412000000000000000">3.12 int(16 bit) and long (32 bit ) Support</A>
+<LI><A NAME="tex2html146"
+ HREF="#SECTION000413000000000000000">3.13 Floating Point Support</A>
+<LI><A NAME="tex2html147"
+ HREF="#SECTION000414000000000000000">3.14 MCS51 Memory Models</A>
+<LI><A NAME="tex2html148"
+ HREF="#SECTION000415000000000000000">3.15 Flat 24 bit Addressing Model</A>
+<LI><A NAME="tex2html149"
+ HREF="#SECTION000416000000000000000">3.16 Defines Created by the Compiler</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html150"
+ HREF="#SECTION00050000000000000000">4 SDCC Technical Data</A>
+<UL>
+<LI><A NAME="tex2html151"
+ HREF="#SECTION00051000000000000000">4.1 Optimizations</A>
+<LI><A NAME="tex2html152"
+ HREF="#SECTION00052000000000000000">4.2 Pragmas</A>
+<LI><A NAME="tex2html153"
+ HREF="#SECTION00053000000000000000">4.3 Library Routines</A>
+<LI><A NAME="tex2html154"
+ HREF="#SECTION00054000000000000000">4.4 Interfacing with Assembly Routines</A>
+<LI><A NAME="tex2html155"
+ HREF="#SECTION00055000000000000000">4.5 Global Registers used for Parameter Passing</A>
+<LI><A NAME="tex2html156"
+ HREF="#SECTION00056000000000000000">4.6 With -noregparms Option</A>
+<LI><A NAME="tex2html157"
+ HREF="#SECTION00057000000000000000">4.7 External Stack</A>
+<LI><A NAME="tex2html158"
+ HREF="#SECTION00058000000000000000">4.8 ANSI-Compliance</A>
+<LI><A NAME="tex2html159"
+ HREF="#SECTION00059000000000000000">4.9 Cyclomatic Complexity</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html160"
+ HREF="#SECTION00060000000000000000">5 TIPS</A>
+<LI><A NAME="tex2html161"
+ HREF="#SECTION00070000000000000000">6 Retargetting for other MCUs.</A>
+<LI><A NAME="tex2html162"
+ HREF="#SECTION00080000000000000000">7 SDCDB - Source Level Debugger</A>
+<UL>
+<LI><A NAME="tex2html163"
+ HREF="#SECTION00081000000000000000">7.1 Compiling for Debugging</A>
+<LI><A NAME="tex2html164"
+ HREF="#SECTION00082000000000000000">7.2 How the Debugger Works</A>
+<LI><A NAME="tex2html165"
+ HREF="#SECTION00083000000000000000">7.3 Starting the Debugger</A>
+<LI><A NAME="tex2html166"
+ HREF="#SECTION00084000000000000000">7.4 Command Line Options.</A>
+<LI><A NAME="tex2html167"
+ HREF="#SECTION00085000000000000000">7.5 Debugger Commands.</A>
+<LI><A NAME="tex2html168"
+ HREF="#SECTION00086000000000000000">7.6 Interfacing with XEmacs.</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html169"
+ HREF="#SECTION00090000000000000000">8 Other Processors</A>
+<UL>
+<LI><A NAME="tex2html170"
+ HREF="#SECTION00091000000000000000">8.1 The Z80 and gbz80 port</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html171"
+ HREF="#SECTION000100000000000000000">9 Support</A>
+<UL>
+<LI><A NAME="tex2html172"
+ HREF="#SECTION000101000000000000000">9.1 Reporting Bugs</A>
+<LI><A NAME="tex2html173"
+ HREF="#SECTION000102000000000000000">9.2 Acknowledgments</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html174"
+ HREF="#SECTION000110000000000000000">About this document ...</A>
+</UL>
+<!--End of Table of Contents-->
+
<P>
-<H2><A NAME="toc3">3.</A> <A HREF="SDCCUdoc-3.html">Compiling.</A></H2>
-<UL>
-<LI><A HREF="SDCCUdoc-3.html#ss3.1">3.1 Single Source file projects.</A>
-<LI><A HREF="SDCCUdoc-3.html#ss3.2">3.2 Projects with multiple source files.</A>
-<LI><A HREF="SDCCUdoc-3.html#ss3.3">3.3 Projects with additional libraries.</A>
+<H1><A NAME="SECTION00020000000000000000">
+1 Introduction</A>
+</H1>
+
<P>
-<H2><A NAME="toc4">4.</A> <A HREF="SDCCUdoc-4.html">Command Line options</A></H2>
+
+<H2><A NAME="SECTION00021000000000000000">
+1.1 About SDCC</A>
+</H2>
<P>
-<H2><A NAME="toc5">5.</A> <A HREF="SDCCUdoc-5.html">Language Extensions</A></H2>
+<B>SDCC</B> is a Free ware, retargettable, optimizing ANSI-C compiler
+by <B>Sandeep Dutta</B> designed for 8 bit Microprocessors. The
+current version targets Intel MCS51 based Microprocessors(8051,8052,
+etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51 variant. It
+can be retargetted for other microprocessors, support for PIC, AVR
+and 186 is under development. The entire source code for the compiler
+is distributed under GPL. SDCC uses ASXXXX & ASLINK, a Freeware,
+retargettable assembler & linker. SDCC has extensive language extensions
+suitable for utilizing various microcontrollers underlying hardware
+effectively. In addition to the MCU specific optimizations SDCC also
+does a host of standard optimizations like <I>global sub expression
+elimination, loop optimizations (loop invariant, strength reduction
+of induction variables and loop reversing), constant folding & propagation,
+copy propagation, dead code elimination and jumptables for 'switch'
+statements.</I> For the back-end SDCC uses a global register allocation
+scheme which should be well suited for other 8 bit MCUs. The peep
+hole optimizer uses a rule based substitution mechanism which is MCU
+independent. Supported data-types are <I>short (8 bits, 1 byte),
+char (8 bits, 1 byte), int (16 bits, 2 bytes ), long (32 bit, 4 bytes)
+& float (4 byte IEEE).</I> The compiler also allows <I>inline assembler
+code</I> to be embedded anywhere in a function. In addition routines
+developed in assembly can also be called. SDCC also provides an option
+to report the relative complexity of a function, these functions can
+then be further optimized, or hand coded in assembly if need be. SDCC
+also comes with a companion source level debugger SDCDB, the debugger
+currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
+The latest version can be downloaded from <B>http://sdcc.sourceforge.net/.</B>
-<UL>
-<LI><A HREF="SDCCUdoc-5.html#ss5.1">5.1 Storage Classes.</A>
<P>
-<H2><A NAME="toc6">6.</A> <A HREF="SDCCUdoc-6.html">Optimizations</A></H2>
-<UL>
-<LI><A HREF="SDCCUdoc-6.html#ss6.1">6.1 Sub-expression elimination</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.2">6.2 Dead-Code elimination.</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.3">6.3 Copy-Propagation:</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.4">6.4 Loop optimizations</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.5">6.5 Algebraic simplifications:</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.6">6.6 'switch' statements.</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.7">6.7 bit-shifting operations.</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.8">6.8 Highest Order Bit.</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.9">6.9 Peep-hole optimizer.</A>
+<H2><A NAME="SECTION00022000000000000000">
+1.2 Open Source</A>
+</H2>
+
+<P>
+All packages used in this compiler system are <I>opensource</I>(freeware);
+source code for all the sub-packages (asxxxx assembler/linker, pre-processor)
+are distributed with the package. This documentation is maintained
+using a freeware word processor (LYX).
+
+<P>
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published
+by the Free Software Foundation; either version 2, or (at your option)
+any later version. This program is distributed in the hope that it
+will be useful, but WITHOUT ANY WARRANTY; without even the implied
+warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
+the GNU General Public License for more details. You should have received
+a copy of the GNU General Public License along with this program;
+if not, write to the Free Software Foundation, 59 Temple Place - Suite
+330, Boston, MA 02111-1307, USA. In other words, you are welcome to
+use, share and improve this program. You are forbidden to forbid anyone
+else to use, share and improve what you give them. Help stamp out
+software-hoarding!
+
+<P>
+
+<H2><A NAME="SECTION00023000000000000000">
+1.3 System Requirements</A>
+</H2>
+
+<P>
+What do you need before you start installation of SDCC? A computer,
+and a desire to compute. The preferred method of installation is to
+compile SDCC from source using GNU GCC and make. For Windows some
+pre-compiled binary distributions are available for your convenience.
+You should have some experience with command line tools and compiler
+use.
+
+<P>
+
+<H2><A NAME="SECTION00024000000000000000">
+1.4 Other Resources</A>
+</H2>
+
+<P>
+The SDCC home page at http://sdcc.sourceforge.net/ is a great
+place to find distribution sets. You can also find links to the user
+mailing lists that offer help or discuss SDCC with other SDCC users.
+Web links to other SDCC related sites can also be found here. This
+document can be found in the DOC directory of the source package as
+a text or HTML file. Some of the other tools(simulator and assembler)
+included with SDCC contain their own documentation and can be found
+in the source distribution. If you want the latest unreleased software,
+the complete source package is available directly by anonymous CVS
+on www.sourceforge.net.
+
+<P>
+
+<H1><A NAME="SECTION00030000000000000000">
+2 Installation</A>
+</H1>
+
+<P>
+
+<H2><A NAME="SECTION00031000000000000000">
+2.1 Linux/Unix Installation</A>
+</H2>
+
+<P>
+
+<OL>
+<LI>Download the source package, it will be named something like sdcc-2.x.x.tgz.
+</LI>
+<LI>Bring up a command line terminal, such as xterm.
+</LI>
+<LI>Unpack the file using a command like: tar -xzf sdcc-2.x.x.tgz, this
+will create a sub-directory called sdcc with all of the sources.
+</LI>
+<LI>Change directory into the main SDCC directory, for example type: ``cd
+sdcc''.
+</LI>
+<LI>Type ``./configure''. This configures the package for compilation
+on your system.
+</LI>
+<LI>Type ``make''. All of the source packages will compile, this can
+take a while.
+</LI>
+<LI>Type ``make install'' as root. This copies the binary executables
+to the install directories.
+</LI>
+</OL>
+
+<P>
+
+<H2><A NAME="SECTION00032000000000000000">
+2.2 Windows Installation</A>
+</H2>
+
+<P>
+For installation under Windows you first need to pick between a pre-compiled
+binary package, or installing the source package along with the Cygwin
+package. The binary package is the quickest to install, while the
+Cygwin package includes all of the open source power tools used to
+compile the complete SDCC source package in the Windows environment.
+If you are not familiar with the Unix command line environment, you
+may want to read the section on additional information for Windows
+users prior to your initial installation.
+
+<P>
+
+<H3><A NAME="SECTION00032100000000000000">
+2.2.1 Windows Install Using a Binary Package</A>
+</H3>
+
+<P>
+
+<OL>
+<LI>Download the binary package and unpack it using your favorite unpacking
+tool(gunzip, WinZip, etc). This should unpack to a group of sub-directories.
+An example directory structure after unpacking is: c:\usr\local\bin
+for the executables, c:\usr\local\share\sdcc\include
+and c:\usr\local\share\sdcc\lib
+for the include and libraries.
+</LI>
+<LI>Adjust your environment PATH to include the location of the bin directory.
+For example, make a setsdcc.bat file with the following: set PATH=c:\usr\local\bin;%PATH%
+</LI>
+<LI>When you compile with sdcc, you may need to specify the location of
+the lib and include folders. For example, sdcc -I c:\usr\local\share\sdcc\include
+-L c:\usr\local\share\sdcc\lib\small
+test.c
+</LI>
+</OL>
+
+<P>
+
+<H3><A NAME="SECTION00032200000000000000">
+2.2.2 Windows Install Using Cygwin</A>
+</H3>
+
+<P>
+
+<OL>
+<LI>Download and install the cygwin package from the redhat site<I>http://sources.redhat.com/cygwin/</I>.
+Currently, this involved downloading a small install program which
+then automates downloading and installing selected parts of the package(a
+large 80M byte sized dowload for the whole thing).
+</LI>
+<LI>Bring up a Unix/Bash command line terminal from the Cygwin menu.
+</LI>
+<LI>Follow the instructions in the preceding Linux/Unix installation section.
+</LI>
+</OL>
+
+<P>
+
+<H2><A NAME="SECTION00033000000000000000">
+2.3 Testing out the SDCC Compiler</A>
+</H2>
+
+<P>
+The first thing you should do after installing your SDCC compiler
+is to see if it runs. Type ``sdcc -version'' at the prompt, and
+the program should run and tell you the version. If it doesn't run,
+or gives a message about not finding sdcc program, then you need to
+check over your installation. Make sure that the sdcc bin directory
+is in your executable search path defined by the PATH environment
+setting(see the Trouble-shooting section for suggestions). Make sure
+that the sdcc program is in the bin folder, if not perhaps something
+did not install correctly.
+
+<P>
+SDCC binaries are commonly installed in a directory arrangement like
+this:
+
+<P>
+<TABLE CELLPADDING=3 BORDER="1">
+<TR><TD ALIGN="LEFT">/usr/local/bin</TD>
+<TD ALIGN="LEFT">Holds executables(sdcc, s51, aslink, ...)</TD>
+</TR>
+<TR><TD ALIGN="LEFT">/usr/local/share/sdcc/lib</TD>
+<TD ALIGN="LEFT">Holds common C libraries</TD>
+</TR>
+<TR><TD ALIGN="LEFT">/usr/local/share/sdcc/include</TD>
+<TD ALIGN="LEFT">Holds common C header files</TD>
+</TR>
+</TABLE>
+
+<P>
+Make sure the compiler works on a very simple example. Type in the
+following test.c program using your favorite editor:
+
+<P>
+<I>main()</I>
+<BR><I>{ int i;</I>
+<BR><I>i = 0;</I>
+<BR><I>i += 10;</I>
+<BR><I>}</I>
+<BR>
+<P>
+Compile this using the following command: ``sdcc -c test.c''.
+If all goes well, the compiler will generate a test.asm and test.rel
+file. Congratulations, you've just compiled your first program with
+SDCC. We used the -c option to tell SDCC not to link the generated
+code, just to keep things simple for this step.
+
+<P>
+The next step is to try it with the linker. Type in ``sdcc test.c''.
+If all goes well the compiler will link with the libraries and produce
+a test.ihx output file. If this step fails(no test.ihx, and the linker
+generates warnings), then the problem is most likely that sdcc cannot
+find the usr/local/share/sdcc/lib/small directory(see the Install
+trouble-shooting section for suggestions).
+
+<P>
+The final test is to ensure sdcc can use the standard header files
+and libraries. Edit test.c and change it to the following:
+
+<P>
+<I>#include <string.h></I>
+<BR><I>main()</I>
+<BR><I>{ char str1[10];</I>
+<BR><I>strcpy(str1, ``testing'');</I>
+<BR><I>}</I>
+
+<P>
+Compile this by typing: ``sdcc test.c''. This should generate
+a test.ihx output file, and it should give no warnings such as not
+finding the string.h file. If it cannot find the string.h file, then
+the problem is that sdcc cannot find the /usr/local/share/sdcc/include
+directory(see the Install trouble-shooting section for suggestions).
+
+<P>
+
+<H2><A NAME="SECTION00034000000000000000">
+2.4 Install Trouble-shooting</A>
+</H2>
+
+<P>
+
+<H3><A NAME="SECTION00034100000000000000">
+2.4.1 SDCC cannot find libraries or header files.</A>
+</H3>
+
+<P>
+The default installation assumes the libraries and header files are
+located at ``/usr/local/share/sdcc/lib'' and ``/usr/local/share/sdcc/include''.
+An alternative is to specify these locations as compiler options like
+this: sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include
+test.c
+
+<P>
+
+<H3><A NAME="SECTION00034200000000000000">
+2.4.2 SDCC does not compile correctly.</A>
+</H3>
+
+<P>
+A few things to try include starting from scratch by unpacking the
+.tgz source package again in an empty directory. If this doesn't work,
+you could try downloading a different version. If this doesn't work,
+you can re-direct the install messages by doing the following:
+
+<P>
+$./make > dump.txt 2>&1
+
+<P>
+After this you can examine the dump.txt files to locate the problem.
+Or these messages can be attached to an email that could be helpful
+when requesting help from the mailing list.
+
+<P>
+
+<H3><A NAME="SECTION00034300000000000000">
+2.4.3 What the ``./configure'' does</A>
+</H3>
+
+<P>
+The ``./configure'' command is a script that analyzes your system
+and performs some configuration to ensure the source package compiles
+on your system. It will take a few minutes to run, and will compile
+a few tests to determine what compiler features are installed.
+
+<P>
+
+<H3><A NAME="SECTION00034400000000000000">
+2.4.4 What the ``make'' does.</A>
+</H3>
+
+<P>
+This runs the GNU make tool, which automatically compiles all the
+source packages into the final installed binary executables.
+
<P>
-<H2><A NAME="toc7">7.</A> <A HREF="SDCCUdoc-7.html">Pointers</A></H2>
+
+<H3><A NAME="SECTION00034500000000000000">
+2.4.5 What the ``make install'' command does.</A>
+</H3>
+
+<P>
+This will install the compiler, other executables and libraries in
+to the appropriate system directories. The default is to copy the
+executables to /usr/local/bin and the libraries and header files to
+/usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
+
+<P>
+
+<H2><A NAME="SECTION00035000000000000000">
+2.5 Additional Information for Windows Users</A>
+</H2>
+
+<P>
+The standard method of installing on a Unix system involves compiling
+the source package. This is easily done under Unix, but under Windows
+it can be a more difficult process. The Cygwin is a large package
+to download, and the compilation runs considerably slower under Windows
+due to the overhead of the Cygwin tool set. An alternative is to install
+a pre-compiled Windows binary package. There are various trade-offs
+between each of these methods.
+
+<P>
+The Cygwin package allows a Windows user to run a Unix command line
+interface(bash shell) and also implements a Unix like file system
+on top of Windows. Included are many of the famous GNU software development
+tools which can augment the SDCC compiler.This is great if you have
+some experience with Unix command line tools and file system conventions,
+if not you may find it easier to start by installing a binary Windows
+package. The binary packages work with the Windows file system conventions.
+
+<P>
+
+<H3><A NAME="SECTION00035100000000000000">
+2.5.1 Getting started with Cygwin</A>
+</H3>
+
+<P>
+SDCC is typically distributed as a tarred/gzipped file(.tgz). This
+is a packed file similar to a .zip file. Cygwin includes the tools
+you will need to unpack the SDCC distribution(tar and gzip). To unpack
+it, simply follow the instructions under the Linux/Unix install section.
+Before you do this you need to learn how to start a cygwin shell and
+some of the basic commands used to move files, change directory, run
+commands and so on. The change directory command is ``cd'', the
+move command is ``mv''. To print the current working directory,
+type ``pwd''. To make a directory, use ``mkdir''.
+
+<P>
+There are some basic differences between Unix and Windows file systems
+you should understand. When you type in directory paths, Unix and
+the Cygwin bash prompt uses forward slashes '/' between directories
+while Windows traditionally uses '\' backward slashes.
+So when you work at the Cygwin bash prompt, you will need to use the
+forward '/' slashes. Unix does not have a concept of drive letters,
+such as ``c:``, instead all files systems attach and appear
+as directories.
+
+<P>
+
+<H3><A NAME="SECTION00035200000000000000">
+2.5.2 Running SDCC as Native Compiled Executables</A>
+</H3>
+
+<P>
+If you use the pre-compiled binaries, the install directories for
+the libraries and header files may need to be specified on the sdcc
+command line like this: sdcc -L c:\usr\local\sdcc\lib\small
+-I c:\usr\local\sdcc\include
+test.c if you are running outside of a Unix bash shell.
+
+<P>
+If you have successfully installed and compiled SDCC with the Cygwin
+package, it is possible to compile into native .exe files by using
+the additional makefiles included for this purpose. For example, with
+the Borland 32-bit compiler you would run make -f Makefile.bcc. A
+command line version of the Borland 32-bit compiler can be downloaded
+from the Inprise web site.
+
+<P>
+
+<H2><A NAME="SECTION00036000000000000000">
+2.6 SDCC on Other Platforms</A>
+</H2>
<P>
-<H2><A NAME="toc8">8.</A> <A HREF="SDCCUdoc-8.html">Parameters & Local Variables</A></H2>
<UL>
-<LI><A HREF="SDCCUdoc-8.html#ss8.1">8.1 Overlaying</A>
+<LI><B>FreeBSD and other non-GNU Unixes</B> - Make sure the GNU make
+is installed as the default make tool.
+</LI>
+<LI>SDCC has been ported to run under a variety of operating systems and
+processors. If you can run GNU GCC/make then chances are good SDCC
+can be compiled and run on your system.
+</LI>
+</UL>
+
+<P>
+
+<H2><A NAME="SECTION00037000000000000000">
+2.7 Advanced Install Options</A>
+</H2>
+
+<P>
+The ``configure'' command has several options. The most commonly
+used option is -prefix=<directory name>, where <directory name> is
+the final location for the sdcc executables and libraries, (default
+location is /usr/local). The installation process will create the
+following directory structure under the <directory name> specified.
+
+<P>
+bin/ - binary exectables (add to PATH environment variable)
+<BR> share/
+<BR> sdcc/include/ - include header files
+<BR> sdcc/lib/ -
+<BR> small/ - Object & library files for small
+model library
+<BR> large/ - Object & library files for large
+model library
+<BR> ds390/ - Object & library files forDS80C390
+library
+
+<P>
+The command
+
+<P>
+<B><U><FONT SIZE="+1">'./configure -prefix=/usr/local'' </FONT></U></B>
+<P>
+
+
+<P>
+will configure the compiler to be installed in directory /usr/local/bin.
+
+<P>
+
+<H2><A NAME="SECTION00038000000000000000">
+2.8 Components of SDCC</A>
+</H2>
+
+<P>
+SDCC is not just a compiler, but a collection of tools by various
+developers. These include linkers, assemblers, simulators and other
+components. Here is a summary of some of the components. Note that
+the included simulator and assembler have separate documentation which
+you can find in the source package in their respective directories.
+As SDCC grows to include support for other processors, other packages
+from various developers are included and may have their own sets of
+documentation.
+
+<P>
+You might want to look at the various executables which are installed
+in the bin directory. At the time of this writing, we find the following
+programs:
+
+<P>
+<B>sdcc</B> - The compiler.
+
+<P>
+<B>aslink</B> -The linker for 8051 type processors.
+
+<P>
+<B>asx8051</B> - The assembler for 8051 type processors.
+
+<P>
+<B>sdcpp</B> - The C preprocessor.
+
+<P>
+<B>sdcpd</B> - The source debugger.
+
+<P>
+<B>s51</B> - The ucSim 8051 simulator.
+
+<P>
+<B>linkz80, linkgbz80</B> - The Z80 and GameBoy Z80 linkers.
+
+<P>
+<B>as-z80, as-gbz80</B> - The Z80 and GameBoy Z80 assemblers.
+
+<P>
+<B>packihx</B> - A tool to pack Intel hex files.
+
+<P>
+As development for other processors proceeds, this list will expand
+to include executables to support processors like AVR, PIC, etc.
+
+<P>
+
+<H3><A NAME="SECTION00038100000000000000">
+2.8.1 cpp ( C-Preprocessor)</A>
+</H3>
+
+<P>
+The preprocessor is extracted into the directory <I>SDCCDIR/cpp</I>,
+it is a modified version of the GNU preprocessor. The C preprocessor
+is used to pull in #include sources, process #ifdef statements,
+#defines and so on.
+
+<P>
+
+<H3><A NAME="SECTION00038200000000000000">
+2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)</A>
+</H3>
+
<P>
-<H2><A NAME="toc9">9.</A> <A HREF="SDCCUdoc-9.html">critical Functions.</A></H2>
+This is retargettable assembler & linkage editor, it was developed
+by Alan Baldwin, John Hartman created the version for 8051, and I
+(Sandeep) have some enhancements and bug fixes for it to work properly
+with the SDCC. This component is extracted into the directory <I>SDCCDIR/asxxxx.</I>
<P>
-<H2><A NAME="toc10">10.</A> <A HREF="SDCCUdoc-10.html">Absolute addressing.</A></H2>
+
+<H3><A NAME="SECTION00038300000000000000">
+2.8.3 SDCC - The compiler</A>
+</H3>
<P>
-<H2><A NAME="toc11">11.</A> <A HREF="SDCCUdoc-11.html">Interrupt Service Routines</A></H2>
+This is the actual compiler, it in turn uses the c-preprocessor and
+invokes the assembler and linkage editors. All files with the prefix
+<I>SDCC</I> are part of the compiler and are extracted into the the
+directory <I>SDCCDIR.</I>
<P>
-<H2><A NAME="toc12">12.</A> <A HREF="SDCCUdoc-12.html">Startup Code</A></H2>
+
+<H3><A NAME="SECTION00038400000000000000">
+2.8.4 S51 - Simulator</A>
+</H3>
<P>
-<H2><A NAME="toc13">13.</A> <A HREF="SDCCUdoc-13.html">Inline assembler code.</A></H2>
+s51 is a freeware, opensource simulator developed by Daniel Drotos
+<drdani@mazsola.iit.uni-miskolc.hu>. The executable is built as part
+of the build process, for more information visit Daniel's website
+at <http://mazsola.iit.uni-miskolc.hu/drdani/embedded/s51/>.
<P>
-<H2><A NAME="toc14">14.</A> <A HREF="SDCCUdoc-14.html">int (16 bit) and long (32 bit ) support.</A></H2>
+
+<H3><A NAME="SECTION00038500000000000000">
+2.8.5 SDCDB - Source Level Debugger</A>
+</H3>
<P>
-<H2><A NAME="toc15">15.</A> <A HREF="SDCCUdoc-15.html">Floating point support</A></H2>
+SDCDB is the companion source level debugger . The current version
+of the debugger uses Daniel's Simulator S51, but can be easily changed
+to use other simulators.
<P>
-<H2><A NAME="toc16">16.</A> <A HREF="SDCCUdoc-16.html">Memory Models</A></H2>
+
+<H1><A NAME="SECTION00040000000000000000">
+3 Using SDCC</A>
+</H1>
<P>
-<H2><A NAME="toc17">17.</A> <A HREF="SDCCUdoc-17.html">Flat 24 bit addressing model.</A></H2>
+
+<H2><A NAME="SECTION00041000000000000000">
+3.1 Compiling</A>
+</H2>
<P>
-<H2><A NAME="toc18">18.</A> <A HREF="SDCCUdoc-18.html">Defines created by the compiler.</A></H2>
+
+<H3><A NAME="SECTION00041100000000000000">
+3.1.1 Single Source File Projects</A>
+</H3>
<P>
-<H2><A NAME="toc19">19.</A> <A HREF="SDCCUdoc-19.html">Pragmas</A></H2>
+For single source file 8051 projects the process is very simple. Compile
+your programs with the following command
<P>
-<H2><A NAME="toc20">20.</A> <A HREF="SDCCUdoc-20.html">Library routines.</A></H2>
+<FONT SIZE="-1">sdcc sourcefile.c</FONT>
+<P>
+
<P>
-<PRE>
-printf_small("my str %s, my int %d\n",(char _generic *)mystr,myint);
-
-</PRE>
+The above command will compile ,assemble and link your source file.
+Output files are as follows.
<P>
+
<UL>
-<LI><B>stdarg.h </B>- contains definition for the following macros to be used for
-variable parameter list, note that a function can have a variable parameter
-list if and only if it is 'reentrant'
-<P>va_list, va_start, va_arg, va_end.
+<LI><FONT SIZE="-1">sourcefile.asm - Assembler source file created by the
+compiler</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">sourcefile.lst - Assembler listing file created by
+the Assembler</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">sourcefile.rst - Assembler listing file updated with
+linkedit information , created by linkage editor</FONT>
+<P>
+
</LI>
-<LI><B>setjmp.h </B>- contains defintion for ANSI<B> setjmp </B>& <B>longjmp</B> routines. Note
-in this case setjmp & longjmp can be used between functions executing within
-the same register bank, if long jmp is executed from a function that is using
-a different register bank from the function issuing the setjmp function, the
-results may be unpredictable. The jump buffer requires 3 bytes of data (the
-stack pointer & a 16 byte return address), and can be placed in any address
-space.</LI>
-<LI><B>stdlib.h</B> - contains the following functions.
-<P>atoi, atol.
+<LI><FONT SIZE="-1">sourcefile.sym - symbol listing for the sourcefile,
+created by the assembler.</FONT>
+<P>
+
</LI>
-<LI><B>string.h </B>- contains the following functions.
-<P>strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn,
-strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.
+<LI><FONT SIZE="-1">sourcefile.rel - Object file created by the assembler,
+input to Linkage editor.</FONT>
+<P>
+
</LI>
-<LI><B>ctype.h</B> - contains the following routines.
-<P>iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
-isxdigit, isalnum, isalpha.
+<LI><FONT SIZE="-1">sourcefile.map - The memory map for the load module,
+created by the Linker.</FONT>
+<P>
+
</LI>
-<LI><B>malloc.h</B> - The malloc routines are developed by Dmitry S. Obukhov (dso@usa.net).
-These routines will allocate memory from the external ram. Here is a description
-on how to use them (as described by the author).
-<PRE>
-//Example:
- // #define DYNAMIC_MEMORY_SIZE 0x2000
- //
- .....
- // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
-
- // unsigned char xdata * current_buffer;
- // .....
-
- // void main(void)
- // {
- // ...
- //
- init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
- //
- //Now it's possible to use malloc.
- // ...
- // current_buffer
- = malloc(0x100);
- //
-
-</PRE>
+<LI><FONT SIZE="-1">sourcefile.<ihx | s19> - The load module : ihx - Intel
+hex format (default ), s19 - Motorola S19 format when compiler option
+-out-fmt-s19 is used.</FONT>
+<P>
+
</LI>
-<LI><B>serial.h</B> - Serial IO routines are also developed by Dmitry S. Obukhov (dso@usa.net).
-These routines are interrupt driven with a 256 byte circular buffer, they also
-expect external ram to be present. Please see documentation in file SDCCDIR/sdcc51lib/serial.c
-. Note the header file "serial.h" MUST be included in the file containing the
-'main' function.</LI>
-<LI><B>ser.h </B>- Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.com>
-these routines are more compact and faster. Please see documentation in file
-SDCCDIR/sdcc51lib/ser.c</LI>
-<LI><B>ser_ir.h </B>- Another alternate set of serial routines provided by Josef Wolf
-<jw@raven.inka.de> , these routines do not use the external ram.</LI>
-<LI><B>reg51.h</B> - contains register definitions for a standard 8051</LI>
-<LI><B>reg552.h </B>- contains register definitions for 80C552.</LI>
-<LI><B>float.h</B> - contains min, max and other floating point related stuff.</LI>
</UL>
-<P>All library routines are compiled as --model-small , they are all non-reentrant,
-if you plan to use the large model or want to make these routines reentrant,
-then they will have to be recompiled with the appropriate compiler option.
-<P>Have not had time to do the more involved routines like printf, will get
-to them shortly.
+
<P>
-<H2><A NAME="toc21">21.</A> <A HREF="SDCCUdoc-21.html">Interfacing with assembly routines.</A></H2>
-<UL>
-<LI><A HREF="SDCCUdoc-21.html#ss21.1">21.1 Global registers used for parameter passing.</A>
-<LI><A HREF="SDCCUdoc-21.html#ss21.2">21.2 With --noregparms option.</A>
+<H3><A NAME="SECTION00041200000000000000">
+3.1.2 Projects with Multiple Source Files</A>
+</H3>
+
+<P>
+SDCC can compile only ONE file at a time. Let us for example assume
+that you have a project containing the following files.
+
+<P>
+<FONT SIZE="-1">foo1.c ( contains some functions )</FONT>
<P>
-<H2><A NAME="toc22">22.</A> <A HREF="SDCCUdoc-22.html">External Stack.</A></H2>
+
+<P>
+<FONT SIZE="-1">foo2.c (contains some more functions)</FONT>
<P>
-<H2><A NAME="toc23">23.</A> <A HREF="SDCCUdoc-23.html">ANSI-Compliance.</A></H2>
+
+<P>
+<FONT SIZE="-1">foomain.c (contains more functions and the function
+main)</FONT>
<P>
-<H2><A NAME="toc24">24.</A> <A HREF="SDCCUdoc-24.html">Cyclomatic Complexity</A></H2>
+
<P>
-<H2><A NAME="toc25">25.</A> <A HREF="SDCCUdoc-25.html">TIPS</A></H2>
+The first two files will need to be compiled separately with the commands
<P>
-<H2><A NAME="toc26">26.</A> <A HREF="SDCCUdoc-26.html">Retargetting for other MCUs.</A></H2>
+<FONT SIZE="-1">sdcc -c foo1.c</FONT>
+<P>
+
+<P>
+<FONT SIZE="-1">sdcc -c foo2.c</FONT>
<P>
-<H2><A NAME="toc27">27.</A> <A HREF="SDCCUdoc-27.html">Reporting Bugs</A></H2>
+
<P>
-<H2><A NAME="toc28">28.</A> <A HREF="SDCCUdoc-28.html">SDCDB - Source level debugger.</A></H2>
+Then compile the source file containing main and link the other files
+together with the following command.
-<UL>
-<LI><A HREF="SDCCUdoc-28.html#ss28.1">28.1 Compiling for debugging.</A>
-<LI><A HREF="SDCCUdoc-28.html#ss28.2">28.2 How the debugger works.</A>
-<LI><A HREF="SDCCUdoc-28.html#ss28.3">28.3 Starting the debugger.</A>
-<LI><A HREF="SDCCUdoc-28.html#ss28.4">28.4 Command line options.</A>
-<LI><A HREF="SDCCUdoc-28.html#ss28.5">28.5 Debugger Commands.</A>
-<LI><A HREF="SDCCUdoc-28.html#ss28.6">28.6 Interfacing with XEmacs.</A>
<P>
-<H2><A NAME="toc29">29.</A> <A HREF="SDCCUdoc-29.html">Conclusion</A></H2>
+<FONT SIZE="-1">sdcc foomain.c foo1.rel foo2.rel</FONT>
+<P>
+
<P>
-<H2><A NAME="toc30">30.</A> <A HREF="SDCCUdoc-30.html">Acknowledgments</A></H2>
+Alternatively <I>foomain.c</I> can be separately compiled as well
<P>
-<H2><A NAME="toc31">31.</A> <A HREF="SDCCUdoc-31.html">Appendix A: The Z80 and gbz80 port</A></H2>
+<FONT SIZE="-1">sdcc -c foomain.c </FONT>
+<P>
+
-<HR>
-<A HREF="SDCCUdoc-1.html">Next</A>
-Previous
-Contents
+<P>
+<FONT SIZE="-1">sdcc foomain.rel foo1.rel foo2.rel</FONT>
+<P>
+
+
+<P>
+The file containing the main function MUST be the FIRST file specified
+in the command line , since the linkage editor processes file in the
+order they are presented to it.
+
+<P>
+
+<H3><A NAME="SECTION00041300000000000000">
+3.1.3 Projects with Additional Libraries</A>
+</H3>
+
+<P>
+Some reusable routines may be compiled into a library, see the documentation
+for the assembler and linkage editor in the directory <I>SDCCDIR/asxxxx/asxhtm.htm</I>
+this describes how to create a <I>.lib</I> library file, the libraries
+created in this manner may be included using the command line, make
+sure you include the -L <library-path> option to tell the linker where
+to look for these files. Here is an example, assuming you have the
+source file <I>'foomain.c</I>' and a library <I>'foolib.lib'</I> in
+the directory <I>'mylib'</I>.
+
+<P>
+<FONT SIZE="-1">sdcc foomain.c foolib.lib -L mylib</FONT>
+<P>
+
+
+<P>
+Note here that <I>'mylib</I>' must be an absolute path name.
+
+<P>
+The view of the way the linkage editor processes the library files,
+it is recommended that you put each source routine in a separate file
+and combine them using the .lib file. For an example see the standard
+library file 'libsdcc.lib' in the directory SDCCDIR/sdcc51lib.
+
+<P>
+
+<H2><A NAME="SECTION00042000000000000000">
+3.2 Command Line Options</A>
+</H2>
+
+<P>
+
+<H3><A NAME="SECTION00042100000000000000">
+3.2.1 Processor Selection Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B>-mmcs51</B>]Generate code for the MCS51 (8051) family of processors.
+This is the default processor target.
+</LI>
+<LI>[<B>-mds390</B>]Generate code for the DS80C390 processor.
+</LI>
+<LI>[<B>-mz80</B>]Generate code for the Z80 family of processors.
+</LI>
+<LI>[<B>-mgbz80</B>]Generate code for the GameBoy Z80 processor.
+</LI>
+<LI>[<B>-mavr</B>]Generate code for the Atmel AVR processor(In development,
+not complete).
+</LI>
+<LI>[<B>-mpic14</B>]Generate code for the PIC 14-bit processors(In development,
+not complete).
+</LI>
+<LI>[<B>-mtlcs900h</B>]Generate code for the Toshiba TLCS-900H processor(In
+development, not complete).
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042200000000000000">
+3.2.2 Path, Lib and Define Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B><U>-I<path></U></B>] The additional location where the pre
+processor will look for <..h> or ``..h'' files.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-D<macro[=value]></FONT></U></B>]Command line definition
+of macros. Passed to the pre processor.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-lib-path(-L)</FONT></U></B>]<absolute path to additional
+libraries> This option is passed to the linkage editor, additional
+libraries search path. The path name must be absolute. Additional
+library files may be specified in the command line . See section Compiling
+programs for more details.
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042300000000000000">
+3.2.3 MCS51 Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B><FONT SIZE="+1">-model-large</FONT></B>]Generate code for Large model programs
+see section Memory Models for more details. If this option is used
+all source files in the project should be compiled with this option.
+In addition the standard library routines are compiled with small
+model , they will need to be recompiled.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-model-small</FONT></U></B>]Generate code for Small
+Model programs see section Memory Models for more details. This is
+the default model.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-model-flat24</FONT></U></B>]Generate code forDS80C390
+24-bit flat mode. See section Memory Models for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-stack-</FONT></U></B><B><I><U><FONT SIZE="+1">auto</FONT></U></I></B>]All
+functions in the source file will be compiled as <I>reentrant</I>,
+i.e. the parameters and local variables will be allocated on the stack.
+see section Parameters and Local Variables for more details. If this
+option is used all source files in the project should be compiled
+with this option.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-xstack</FONT></U></B>]Uses a pseudo stack in the first
+256 bytes in the external ram for allocating variables and passing
+parameters. See section on external stack for more details.
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042400000000000000">
+3.2.4 Optimization Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B><U><FONT SIZE="+1">-nogcse</FONT></U></B>]Will not do global subexpression
+elimination, this option may be used when the compiler creates undesirably
+large stack/data spaces to store compiler temporaries. A warning message
+will be generated when this happens and the compiler will indicate
+the number of extra bytes it allocated. It recommended that this option
+NOT be used , #pragma NOGCSE can be used to turn off global subexpression
+elimination for a given function only.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-noinvariant</FONT></U></B>]Will not do loop invariant
+optimizations, this may be turned off for reasons explained for the
+previous option . For more details of loop optimizations performed
+see section Loop Invariants.It recommended that this option NOT be
+used , #pragma NOINVARIANT can be used to turn off invariant optimizations
+for a given function only.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-noinduction</FONT></U></B>]Will not do loop induction
+optimizations, see section Strength reduction for more details.It
+recommended that this option NOT be used , #pragma NOINDUCTION can
+be used to turn off induction optimizations for given function only.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-nojtbound</FONT></U></B>] Will not generate boundary
+condition check when switch statements are implemented using jump-tables.
+See section Switch Statements for more details.It recommended that
+this option NOT be used , #pragma NOJTBOUND can be used to turn off
+boundary checking for jump tables for a given function only.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-noloopreverse</FONT></U></B>]Will not do loop reversal
+optimization
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-noregparms</FONT></U></B>]By default the first parameter
+is passed using global registers (DPL,DPH,B,ACC). This option will
+disable parameter passing using registers. NOTE: if your program uses
+the 16/32 bit support routines (for multiplication/division) these
+library routines will need to be recompiled with the -noregparms
+option as well.
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042500000000000000">
+3.2.5 DS390 Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B>-stack-auto</B>]See MCS51 section for description.
+</LI>
+<LI>[<B>-stack-10bit</B>]This option generates code for the 10 bit
+stack mode of the Dallas DS80C390 part. In this mode, the stack is
+located in the lower 1K of the internal RAM, which is mapped to 0x400000.
+Note that the support is incomplete, since it still uses a single
+byte as the stack pointer. This means that only the lower 256 bytes
+of the potential 1K stack space can actually be used. However, this
+does allow you to reclaim the precious 256 bytes of low RAM for use
+for the DATA and IDATA segments. The compiler will not generate any
+code to put the processor into 10 bit stack mode. It is important
+to ensure that the processor is in this mode before calling any re-entrant
+functions compiled with this option. In principle, this should work
+with the -stack-auto option, but that has not been tested. It is
+incompatible with the -xstack option. It also only makes sense if
+the processor is in 24 bit contiguous addressing mode (see the -model-flat24
+option).
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042600000000000000">
+3.2.6 Other Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B><U><FONT SIZE="+1">-callee-saves</FONT></U></B>]<B><U><FONT SIZE="+1">function1[,function2][,function3]....</FONT></U></B>
+The compiler by default uses a caller saves convention for register
+saving across function calls, however this can cause unneccessary
+register pushing & popping when calling small functions from larger
+functions. This option can be used to switch the register saving convention
+for the function names specified. The compiler will not save registers
+when calling these functions, extra code will be generated at the
+entry & exit for these functions to save & restore the registers
+used by these functions, this can SUBSTANTIALLY reduce code & improve
+run time performance of the generated code. In future the compiler
+(with interprocedural analysis) will be able to determine the appropriate
+scheme to use for each function call. DO NOT use this option for built-in
+functions such as _muluint..., if this option is used for a library
+function the appropriate library function needs to be recompiled with
+the same option. If the project consists of multiple source files
+then all the source file should be compiled with the same -callee-saves
+option string. Also see Pragma Directive CALLEE-SAVES. .
+</LI>
+<LI>[<B><U>-debug</U></B>]When this option is used the compiler
+will generate debug information , that can be used with the SDCDB.
+The debug information is collected in a file with .cdb extension.
+For more information see documentation for SDCDB.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-regextend</FONT></U></B>] This option will cause the
+compiler to define pseudo registers , if this option is used, all
+source files in the project should be compiled with this option. See
+section Register Extension for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-compile-only</FONT></U></B><FONT SIZE="+1">(-c)</FONT>] will compile
+and assemble the source only, will not call the linkage editor.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-xram-loc</FONT></U></B><Value>]The start location of
+the external ram, default value is 0. The value entered can be in
+Hexadecimal or Decimal format .eg. -xram-loc 0x8000 or -xram-loc
+32768.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-code-loc</FONT></U></B><Value>]The start location of
+the code segment , default value 0. Note when this option is used
+the interrupt vector table is also relocated to the given address.
+The value entered can be in Hexadecimal or Decimal format .eg. -code-loc
+0x8000 or -code-loc 32768.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-stack-loc</FONT></U></B><Value>]The initial value of
+the stack pointer. The default value of the stack pointer is 0x07
+if only register bank 0 is used, if other register banks are used
+then the stack pointer is initialized to the location above the highest
+register bank used. eg. if register banks 1 & 2 are used the stack
+pointer will default to location 0x18. The value entered can be in
+Hexadecimal or Decimal format .eg. -stack-loc 0x20 or -stack-loc
+32. If all four register banks are used the stack will be placed after
+the data segment (equivalent to -stack-after-data)
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-stack-after-data</FONT></U></B>]This option will cause
+the stack to be located in the internal ram after the data segment.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-data-loc</FONT></U></B><Value>]The start location of
+the internal ram data segment, the default value is 0x30.The value
+entered can be in Hexadecimal or Decimal format .eg. -data-loc 0x20
+or -data-loc 32.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-idata-loc</FONT></U></B><Value>]The start location
+of the indirectly addressable internal ram, default value is 0x80.
+The value entered can be in Hexadecimal or Decimal format .eg. -idata-loc
+0x88 or -idata-loc 136.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-peep-file</FONT></U></B><filename>]This option can
+be used to use additional rules to be used by the peep hole optimizer.
+See section Peep Hole optimizations for details on how to write these
+rules.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-E</FONT></U></B>]Run only the C preprocessor. Preprocess
+all the C source files specified and output the results to standard
+output.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-M</FONT></U></B>]Tell the preprocessor to output a rule
+suitable for make describing the dependencies of each object file.
+For each source file, the preprocessor outputs one make-rule whose
+target is the object file name for that source file and whose dependencies
+are all the files `#include'd in it. This rule may be a single line
+or may be continued with `\'-newline if it is long.
+The list of rules is printed on standard output instead of the preprocessed
+C program. `-M' implies `-E'.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-C</FONT></U></B>]Tell the preprocessor not to discard
+comments. Used with the `-E' option.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-MM</FONT></U></B>]Like `-M' but the output mentions
+only the user header files included with `#include file"'.
+System header files included with `#include <file>' are omitted.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-Aquestion(answer)</FONT></U></B>]Assert the answer answer
+for question, in case it is tested with a preprocessor conditional
+such as `#if #question(answer)'. `-A-' disables the standard assertions
+that normally describe the target machine.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-Aquestion</FONT></U></B>](answer) Assert the answer
+answer for question, in case it is tested with a preprocessor conditional
+such as `#if #question(answer)'. `-A-' disables the standard assertions
+that normally describe the target machine.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-Umacro</FONT></U></B>]Undefine macro macro. `-U' options
+are evaluated after all `-D' options, but before any `-include' and
+`-imacros' options.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dM</FONT></U></B>]Tell the preprocessor to output only
+a list of the macro definitions that are in effect at the end of preprocessing.
+Used with the `-E' option.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dD</FONT></U></B>]Tell the preprocessor to pass all
+macro definitions into the output, in their proper sequence in the
+rest of the output.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dN</FONT></U></B>]Like `-dD' except that the macro arguments
+and contents are omitted. Only `#define name' is included in the
+output.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-S</FONT></U></B>]Stop after the stage of compilation
+proper; do not as- semble. The output is an assembler code file for
+the input file specified.
+</LI>
+<LI>[<B><U>-Wa_asmOption[,asmOption]</U></B>...]Pass the asmOption
+to the assembler.
+</LI>
+<LI>[<B><U>-Wl_linkOption[,linkOption]</U></B>].. Pass the
+linkOption to the linker.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-int-long-reent</FONT></U></B>] Integer (16 bit) and
+long (32 bit) libraries have been compiled as reentrant. Note by default
+these libraries are compiled as non-reentrant. See section Installation
+for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-cyclomatic</FONT></U></B>]This option will cause the
+compiler to generate an information message for each function in the
+source file. The message contains some <I>important</I> information
+about the function. The number of edges and nodes the compiler detected
+in the control flow graph of the function, and most importantly the
+<I>cyclomatic complexity</I> see section on Cyclomatic Complexity
+for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-float-reent</FONT></U></B>] Floating point library
+is compiled as reentrant.See section Installation for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-out-fmt-ihx</FONT></U></B>]The linker output (final
+object code) is in Intel Hex format. (This is the default option).
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-out-fmt-s19</FONT></U></B>]The linker output (final
+object code) is in Motorola S19 format.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-nooverlay</FONT></U></B>] The compiler will not overlay
+parameters and local variables of any function, see section Parameters
+and local variables for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-main-return</FONT></U></B>]This option can be used
+when the code generated is called by a monitor program. The compiler
+will generate a 'ret' upon return from the 'main' function. The default
+option is to lock up i.e. generate a 'ljmp .' .
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-no-peep</FONT></U></B>] Disable peep-hole optimization.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-peep-asm</FONT></U></B>] Pass the inline assembler
+code through the peep hole optimizer. Can cause unexpected changes
+to inline assembler code , please go through the peephole optimizer
+rules defnied in file 'SDCCpeeph.def' before using this option.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-iram-size</FONT></U></B><Value>]Causes the linker to
+check if the interal ram usage is within limits of the given value.
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042700000000000000">
+3.2.7 Intermediate Dump Options</A>
+</H3>
+
+<P>
+The following options are provided for the purpose of retargetting
+and debugging the compiler . These provided a means to dump the intermediate
+code (iCode) generated by the compiler in human readable form at various
+stages of the compilation process.
+
+<P>
+
+<UL>
+<LI>[<B><U><FONT SIZE="+1">-dumpraw</FONT></U></B>]. This option will cause the
+compiler to dump the intermediate code into a file of named <I><source
+filename>.dumpraw</I> just after the intermediate code has been generated
+for a function , i.e. before any optimizations are done. The basic
+blocks at this stage ordered in the depth first number, so they may
+not be in sequence of execution.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumpgcse</FONT></U></B><FONT SIZE="+1">.</FONT>]Will create a dump
+if iCode, after global subexpression elimination, into a file named
+<I><source filename>.dumpgcse.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumpdeadcode</FONT></U></B>].Will create a dump if
+iCode, after deadcode elimination, into a file named <I><source
+filename>.dumpdeadcode.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumploop.</FONT></U></B>]Will create a dump if iCode,
+after loop optimizations, into a file named <I><source filename>.dumploop.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumprange.</FONT></U></B>]Will create a dump if iCode,
+after live range analysis, into a file named <I><source filename>.dumprange.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumpregassign.</FONT></U></B>]Will create a dump if
+iCode, after register assignment , into a file named <I><source
+filename>.dumprassgn.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumpall.</FONT></U></B>]Will cause all the above mentioned
+dumps to be created.
+</LI>
+</UL>Note that the files created for the dump are appended to each time.
+So the files should be deleted manually , before each dump is created.
+
+<P>
+When reporting bugs, it can be helpful to include these dumps along
+with the portion of the code that is causing the problem.
+
+<P>
+
+<H2><A NAME="SECTION00043000000000000000">
+3.3 MCS51 Storage Class Language Extensions</A>
+</H2>
+
+<P>
+In addition to the ANSI storage classes SDCC allows the following
+MCS51 specific storage classes.
+
+<P>
+
+<H3><A NAME="SECTION00043100000000000000">
+3.3.1 xdata</A>
+</H3>
+
+<P>
+Variables declared with this storage class will be placed in the extern
+RAM. This is the <B>default</B> storage class for Large Memory model
+.
+
+<P>
+<FONT SIZE="-1">eg.</FONT> <I><FONT SIZE="-1">xdata unsigned char xduc;</FONT></I>
+<P>
+
+
+<P>
+
+<H3><A NAME="SECTION00043200000000000000">
+3.3.2 data</A>
+</H3>
+
+<P>
+This is the <B>default</B> storage class for Small Memory model.
+Variables declared with this storage class will be allocated in the
+internal RAM.
+
+<P>
+<FONT SIZE="-1">eg.</FONT> <I><FONT SIZE="-1">data int iramdata;</FONT></I>
+<P>
+
+
+<P>
+
+<H3><A NAME="SECTION00043300000000000000">
+3.3.3 idata</A>
+</H3>
+
+<P>
+Variables declared with this storage class will be allocated into
+the indirectly addressable portion of the internal ram of a 8051 .
+
+<P>
+<FONT SIZE="-1">eg.</FONT><I><FONT SIZE="-1">idata int idi;</FONT></I>
+<P>
+
+
+<P>
+
+<H3><A NAME="SECTION00043400000000000000">
+3.3.4 bit</A>
+</H3>
+
+<P>
+This is a data-type and a storage class specifier. When a variable
+is declared as a bit , it is allocated into the bit addressable memory
+of 8051.
+
+<P>
+eg.<I>bit iFlag;</I>
+
+<P>
+
+<H3><A NAME="SECTION00043500000000000000">
+3.3.5 sfr / sbit</A>
+</H3>
+
+<P>
+Like the bit keyword, <I>sfr / sbit</I> signifies both a data-type
+and storage class, they are used to describe the special function
+registers and special bit variables of a 8051.
+
+<P>
+eg.
+
+<P>
+<I>sfr at 0x80 P0;</I> /* <SMALL>SPECIAL FUNCTION REGISTER </SMALL>P0 <SMALL>AT
+LOCATION 0X80 </SMALL>*/
+
+<P>
+<I>sbit at 0xd7 CY; /*</I> <I>CY (C<SMALL>ARRY </SMALL>F<SMALL>LAG) </SMALL>*/</I>
+
+<P>
+
+<H2><A NAME="SECTION00044000000000000000">
+3.4 Pointers</A>
+</H2>
+
+<P>
+SDCC allows (via language extensions) pointers to explicitly point
+to any of the memory spaces of the 8051. In addition to the explicit
+pointers, the compiler also allows a <I>_generic</I> class of pointers
+which can be used to point to any of the memory spaces.
+
+<P>
+Pointer declaration examples.
+
+<P>
+<FONT SIZE="-1">/* pointer physically in xternal ram pointing to object
+in internal ram */ </FONT>
+<BR><FONT SIZE="-1">data unsigned char * xdata p;</FONT>
+<BR>
+<P>
+
+
+<P>
+<FONT SIZE="-1">/* pointer physically in code rom pointing to data in xdata
+space */ </FONT>
+<BR><FONT SIZE="-1">xdata unsigned char * code p;</FONT>
+<BR>
+<P>
+
+
+<P>
+<FONT SIZE="-1">/* pointer physically in code space pointing to data in
+code space */ </FONT>
+<BR><FONT SIZE="-1">code unsigned char * code p;</FONT>
+<BR>
+<BR><FONT SIZE="-1">/* the folowing is a generic pointer physically located
+in xdata space */</FONT>
+<BR><FONT SIZE="-1">char * xdata p;</FONT>
+<P>
+
+
+<P>
+Well you get the idea. For compatibility with the previous version
+of the compiler, the following syntax for pointer declaration is also
+supported. Note the above examples will be portable to other commercially
+available compilers.
+
+<P>
+<FONT SIZE="-1">unsigned char _xdata *ucxdp; /* pointer to data in external
+ram */ </FONT>
+<BR><FONT SIZE="-1">unsigned char _data *ucdp ; /* pointer to data in internal
+ram */ </FONT>
+<BR><FONT SIZE="-1">unsigned char _code *uccp ; /* pointer to data in R/O
+code space */</FONT>
+<BR><FONT SIZE="-1">unsigned char _idata *uccp; /* pointer to upper 128
+bytes of ram */</FONT>
+<P>
+
+
+<P>
+All unqualified pointers are treated as 3 - byte '_generic' pointers.
+These type of pointers can also to be explicitly declared.
+
+<P>
+<FONT SIZE="-1">unsigned char _generic *ucgp;</FONT>
+<P>
+
+
+<P>
+The highest order byte of the generic pointers contains the data space
+information. Assembler support routines are called whenever data is
+stored or retrieved using _generic pointers. These are useful for
+developing reusable library routines. Explicitly specifying the pointer
+type will generate the most efficient code. Pointers declared using
+a mixture of OLD/NEW style could have unpredictable results.
+
+<P>
+
+<H2><A NAME="SECTION00045000000000000000">
+3.5 Parameters & Local Variables</A>
+</H2>
+
+<P>
+Automatic (local) variables and parameters to functions can either
+be placed on the stack or in data-space. The default action of the
+compiler is to place these variables in the internal RAM ( for small
+model) or external RAM (for Large model). They can be placed on the
+stack either by using the <I>-stack-auto</I> compiler option or by
+using the 'reentrant' keyword in the function declaration.
+
+<P>
+<TT><FONT SIZE="-2">eg</FONT></TT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">unsigned short foo( short i) reentrant { </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+Note that when the parameters & local variables are declared in the
+internal/external ram the functions are non-reentrant. Since stack
+space on 8051 is limited the <I>'reentrant'</I> keyword or the <I>-stack-auto</I>
+option should be used sparingly. Note the reentrant keyword just means
+that the parameters & local variables will be allocated to the stack,
+it DOES NOT mean that the function is register bank independent.
+
+<P>
+When compiled with the default option (i.e. non-reentrant ), local
+variables can be assigned storage classes and absolute addresses.
+
+<P>
+<TT><FONT SIZE="-2">eg</FONT></TT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">unsigned short foo() { </FONT>
+<BR><FONT SIZE="-1"> xdata unsigned short i; </FONT>
+<BR><FONT SIZE="-1"> bit bvar; </FONT>
+<BR><FONT SIZE="-1"> data at 0x31 unsiged short j; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+In the above example the variable <I>i</I> will be allocated in the
+external ram, <I>bvar</I> in bit addressable space and <I>j</I> in
+internal ram. When compiled with the <I>-stack-auto</I> or when a
+function is declared as <I>'reentrant'</I> local variables cannot
+be assigned storage classes or absolute addresses.
+
+<P>
+Parameters however are not allowed any storage class, (storage classes
+for parameters will be ignored), their allocation is governed by the
+memory model in use , and the reentrancy options.
+
+<P>
+
+<H2><A NAME="SECTION00046000000000000000">
+3.6 Overlaying</A>
+</H2>
+
+<P>
+For non-reentrant functions SDCC will try to reduce internal ram space
+usage by overlaying parameters and local variables of a function (if
+possible). Parameters and local variables of a function will be allocated
+to an overlayable segment if the function has <I>no other function
+calls and the function is non-reentrant and the memory model is small.</I>
+If an explicit storage class is specified for a local variable , it
+will NOT be overplayed.
+
+<P>
+Note that the compiler (not the linkage editor) makes the decision
+for overlaying the data items. Functions that are called from an interrupt
+service routine should be preceded by a #pragma NOOVERLAY if they
+are not reentrant Along the same lines the compiler does not do any
+processing with the inline assembler code so the compiler might incorrectly
+assign local variables and parameters of a function into the overlay
+segment if the only function call from a function is from inline assembler
+code, it is safe to use the #pragma NOOVERLAY for functions which
+call other functions using inline assembler code.
+
+<P>
+Parameters and Local variables of functions that contain 16 or 32
+bit multiplication or division will NOT be overlayed since these are
+implemented using external functions.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">#pragma SAVE </FONT>
+<BR><FONT SIZE="-1">#pragma NOOVERLAY </FONT>
+<BR><FONT SIZE="-1">void set_error( unsigned short errcd) </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> P3 = errcd; </FONT>
+<BR><FONT SIZE="-1">} </FONT>
+<BR><FONT SIZE="-1">#pragma RESTORE </FONT>
+<BR><FONT SIZE="-1">void some_isr () interrupt 2 using 1 </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> ... </FONT>
+<BR><FONT SIZE="-1"> set_error(10); </FONT>
+<BR><FONT SIZE="-1"> ... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+In the above example the parameter <I>errcd</I> for the function <I>set_error</I>
+would be assigned to the overlayable segment (if the #pragma NOOVERLAY
+was not present) , this could cause unpredictable runtime behavior.
+The pragma NOOVERLAY ensures that the parameters and local variables
+for the function are NOT overlayed.
+
+<P>
+
+<H2><A NAME="SECTION00047000000000000000">
+3.7 Critical Functions</A>
+</H2>
+
+<P>
+A special keyword may be associated with a function declaring it as
+'<I>critical</I>'. SDCC will generate code to disable all interrupts
+upon entry to a critical function and enable them back before returning
+. Note that nesting critical functions may cause unpredictable results.
+
+<P>
+eg
+
+<P>
+<FONT SIZE="-1">int foo () critical </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+The critical attribute maybe used with other attributes like <I>reentrant.</I>
+
+<P>
+
+<H2><A NAME="SECTION00048000000000000000">
+3.8 Absolute Addressing</A>
+</H2>
+
+<P>
+Data items can be assigned an absolute address with the <I>at <address></I>
+keyword, in addition to a storage class.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">xdata at 0x8000 unsigned char PORTA_8255 ;</FONT>
+<P>
+
+
+<P>
+In the above example the <I>PORTA_8255</I> will be allocated to the
+location 0x8000 of the external ram.
+
+<P>
+Note that is this feature is provided to give the programmer access
+to <I>memory mapped</I> devices attached to the controller. The compiler
+does not actually reserve any space for variables declared in this
+way (they are implemented with an equate in the assembler), thus it
+is left to the programmer to make sure there are no overlaps with
+other variables that are declared without the absolute address, the
+assembler listing file (.lst) and the linker output files (<filename>.rst)
+and (<filename>.map) are a good places to look for such overlaps.
+
+<P>
+Absolute address can be specified for variables in all storage classes.
+
+<P>
+<FONT SIZE="-1">eg.</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">bit at 0x02 bvar;</FONT>
+<P>
+
+
+<P>
+The above example will allocate the variable at offset 0x02 in the
+bit-addressable space. There is no real advantage to assigning absolute
+addresses to variables in this manner , unless you want strict control
+over all the variables allocated.
+
+<P>
+
+<H2><A NAME="SECTION00049000000000000000">
+3.9 Interrupt Service Routines</A>
+</H2>
+
+<P>
+SDCC allows interrupt service routines to be coded in C, with some
+extended keywords.
+
+<P>
+<FONT SIZE="-1">void timer_isr (void) interrupt 2 using 1 </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">.. </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+The number following the 'interrupt' keyword is the interrupt number
+this routine will service. The compiler will insert a call to this
+routine in the interrupt vector table for the interrupt number specified.
+The 'using' keyword is used to tell the compiler to use the specified
+register bank (8051 specific) when generating code for this function.
+Note that when some function is called from an interrupt service routine
+it should be preceded by a #pragma NOOVERLAY (if it is not reentrant)
+. A special note here, int (16 bit) and long (32 bit) integer division,
+multiplication & modulus operations are implemented using external
+support routines developed in ANSI-C, if an interrupt service routine
+needs to do any of these operations then the support routines (as
+mentioned in a following section) will have to recompiled using the
+-stack-auto option and the source file will need to be compiled using
+the -int-long-rent compiler option.
+
+<P>
+If you have multiple source files in your project, interrupt service
+routines can be present in any of them, but a prototype of the isr
+MUST be present in the file that contains the function <I>'main'</I>.
+
+<P>
+Interrupt Numbers and the corresponding address & descriptions for
+the Standard 8051 are listed below. SDCC will automatically adjust
+the interrupt vector table to the maximum interrupt number specified.
+
+<P>
+<TABLE CELLPADDING=3 BORDER="1">
+<TR><TD ALIGN="CENTER">Interrupt #</TD>
+<TD ALIGN="CENTER">Description</TD>
+<TD ALIGN="CENTER">Vector Address</TD>
+</TR>
+<TR><TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">External 0</TD>
+<TD ALIGN="CENTER">0x0003</TD>
+</TR>
+<TR><TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">Timer 0</TD>
+<TD ALIGN="CENTER">0x000B</TD>
+</TR>
+<TR><TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">External 1</TD>
+<TD ALIGN="CENTER">0x0013</TD>
+</TR>
+<TR><TD ALIGN="CENTER">3</TD>
+<TD ALIGN="CENTER">Timer 1</TD>
+<TD ALIGN="CENTER">0x001B</TD>
+</TR>
+<TR><TD ALIGN="CENTER">4</TD>
+<TD ALIGN="CENTER">Serial</TD>
+<TD ALIGN="CENTER">0x0023</TD>
+</TR>
+</TABLE>
+
+<P>
+If the interrupt service routine is defined without a register bank
+or with register bank 0 (using 0), the compiler will save the registers
+used by itself on the stack (upon entry and restore them at exit),
+however if such an interrupt service routine calls another function
+then the entire register bank will be saved on the stack. This scheme
+may be advantageous for small interrupt service routines which have
+low register usage.
+
+<P>
+If the interrupt service routine is defined to be using a specific
+register bank then only ``a'',''b'' & ``dptr'' are save
+and restored, if such an interrupt service routine calls another function
+(using another register bank) then the entire register bank of the
+called function will be saved on the stack. This scheme is recommended
+for larger interrupt service routines.
+
+<P>
+Calling other functions from an interrupt service routine is not recommended
+avoid it if possible.
+
+<P>
+
+<H2><A NAME="SECTION000410000000000000000">
+3.10 Startup Code</A>
+</H2>
+
+<P>
+The compiler inserts a jump to the C routine <B>_sdcc__external__startup()</B>
+at the start of the CODE area. This routine can be found in the file
+<B>SDCCDIR/sdcc51lib/_startup.c</B>, by default this routine returns
+0, if this routine returns a non-zero value , the static & global
+variable initialization will be skipped and the function main will
+be invoked, other wise static & global variables will be initialized
+before the function main is invoked. You could add a <B>_sdcc__external__startup()</B>
+routine to your program to override the default if you needed to setup
+hardware or perform some other critical operation prior to static
+& global variable initialization.
+
+<P>
+
+<H2><A NAME="SECTION000411000000000000000">
+3.11 Inline Assembler Code</A>
+</H2>
+
+<P>
+SDCC allows the use of in-line assembler with a few restriction as
+regards labels. All labels defined within inline assembler code HAS
+TO BE of the <I>form nnnnn$</I> where nnnn is a number less than
+100 (which implies a limit of utmost 100 inline assembler labels <SMALL>PER
+FUNCTION)</SMALL>. It is strongly recommended that each assembly instruction
+(including labels) be placed in a separate line ( as the example shows).
+When the <B><U>-peep-asm</U></B> command line option is used,
+the inline assembler code will be passed through the peephole optimizer,
+this might cause some unexpected changes in the inline assembler code,
+please go throught the peephole optimizer rules defined in file 'SDCCpeeph.def'
+carefully before using this option.
+
+<P>
+<FONT SIZE="-1">eg</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">_asm </FONT>
+<BR><FONT SIZE="-1"> mov b,#10 </FONT>
+<BR><FONT SIZE="-1">00001$: </FONT>
+<BR><FONT SIZE="-1"> djnz b,00001$ </FONT>
+<BR><FONT SIZE="-1">_endasm ;</FONT>
+<P>
+
+
+<P>
+The inline assembler code can contain any valid code understood by
+the assembler (this includes any assembler directives and comment
+lines ) . The compiler does not do any validation of the code within
+the <I>_asm ... _endasm;</I> keyword pair.
+
+<P>
+Inline assembler code cannot reference any C-Labels however it can
+reference labels defined by the inline assembler.
+
+<P>
+<FONT SIZE="-1">eg</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">foo() { </FONT>
+<BR><FONT SIZE="-1">... /* some c code */ </FONT>
+<BR><FONT SIZE="-1">_asm </FONT>
+<BR><FONT SIZE="-1"> ; some assembler code </FONT>
+<BR><FONT SIZE="-1"> ljmp $0003 </FONT>
+<BR><FONT SIZE="-1">_endasm ; </FONT>
+<BR><FONT SIZE="-1">... /* some more c code */ </FONT>
+<BR><FONT SIZE="-1">clabel: /* inline assembler cannot reference this label
+*/ </FONT>
+<BR><FONT SIZE="-1">_asm </FONT>
+<BR><FONT SIZE="-1"> $0003: ;label (can be reference by inline assembler
+only) </FONT>
+<BR><FONT SIZE="-1">_endasm ; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+In other words inline assembly code can access labels defined in inline
+assembly. The same goes the other way, ie. labels defines in inline
+assembly CANNOT be accessed by C statements.
+
+<P>
+
+<H2><A NAME="SECTION000412000000000000000">
+3.12 int(16 bit) and long (32 bit ) Support</A>
+</H2>
+
+<P>
+For signed & unsigned int (16 bit) and long (32 bit) variables, division,
+multiplication and modulus operations are implemented by support routines.
+These support routines are all developed in ANSI-C to facilitate porting
+to other MCUs. The following files contain the described routine,
+all of them can be found in the directory SDCCDIR/sdcc51lib
+
+<P>
+
+<UL>
+<LI><FONT SIZE="-1">_mulsint.c - signed 16 bit multiplication (calls _muluint)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_muluint.c - unsigned 16 bit multiplication</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_divsint.c - signed 16 bit division (calls _divuint)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_divuint.c - unsigned 16 bit division.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_modsint.c - signed 16 bit modulus (call _moduint)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_moduint.c - unsigned 16 bit modulus.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_mulslong.c - signed 32 bit multiplication (calls
+_mululong)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_mululong.c - unsigned32 bit multiplication.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_divslong.c - signed 32 division (calls _divulong)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_divulong.c - unsigned 32 division.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_modslong.c - signed 32 bit modulus (calls _modulong).</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_modulong.c - unsigned 32 bit modulus.</FONT>
+<P>
+
+</LI>
+</UL>
+All these routines are compiled as non-reentrant and small model.
+Since they are compiled as non-reentrant, interrupt service routines
+should not do any of the above operations, if this unavoidable then
+the above routines will need to ne compiled with the -stack-auto
+option, after which the source program will have to be compiled with
+-int-long-rent option.
+
+<P>
+
+<H2><A NAME="SECTION000413000000000000000">
+3.13 Floating Point Support</A>
+</H2>
+
+<P>
+SDCC supports IEEE (single precision 4bytes) floating point numbers.The
+floating point support routines are derived from gcc's floatlib.c
+and consists of the following routines.
+
+<P>
+
+<UL>
+<LI><FONT SIZE="-1">_fsadd.c - add floating point numbers.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fssub.c - subtract floating point numbers</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fsdiv.c - divide floating point numbers</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fsmul.c - multiply floating point numbers</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2uchar.c - convert floating point to unsigned char</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2char.c - convert floating point to signed char.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2uint.c - convert floating point to unsigned int.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2int.c - convert floating point to signed int.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2ulong.c - convert floating point to unsigned long.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2long.c - convert floating point to signed long.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_uchar2fs.c - convert unsigned char to floating point</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_char2fs.c - convert char to floating point number</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_uint2fs.c - convert unsigned int to floating point</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_int2fs.c - convert int to floating point numbers</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_ulong2fs.c - convert unsigned long to floating point
+number</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_long2fs.c - convert long to floating point number.</FONT>
+<P>
+
+</LI>
+</UL>
+Note if all these routines are used simultaneously the data space
+might overflow. For serious floating point usage it is strongly recommended
+that the Large model be used (in which case the floating point routines
+mentioned above will need to recompiled with the -model-Large option)
+
+<P>
+
+<H2><A NAME="SECTION000414000000000000000">
+3.14 MCS51 Memory Models</A>
+</H2>
+
+<P>
+SDCC allows two memory models for MCS51 code, small and large. Modules
+compiled with different memory models should never be combined together
+or the results would be unpredictable. The library routines supplied
+with the compiler are compiled as both small and large. The compiled
+library modules are contained in seperate directories as small and
+large so that you can link to either set. In general the use of the
+large model is discouraged.
+
+<P>
+When the large model is used all variables declared without a storage
+class will be allocated into the external ram, this includes all parameters
+and local variables (for non-reentrant functions). When the small
+model is used variables without storage class are allocated in the
+internal ram.
+
+<P>
+Judicious usage of the processor specific storage classes and the
+'reentrant' function type will yield much more efficient code, than
+using the large-model. Several optimizations are disabled when the
+program is compiled using the large model, it is therefore strongly
+recommdended that the small model be used unless absolutely required.
+
+<P>
+
+<H2><A NAME="SECTION000415000000000000000">
+3.15 Flat 24 bit Addressing Model</A>
+</H2>
+
+<P>
+This option generates code for the 24 bit contiguous addressing mode
+of the Dallas DS80C390 part. In this mode, up to four meg of external
+RAM or code space can be directly addressed. See the data sheets at
+www.dalsemi.com for further information on this part.
+
+<P>
+In older versions of the compiler, this option was used with the MCS51
+code generator (-mmcs51). Now, however, the '390 has it's own code
+generator, selected by the -mds390 switch. This code generator currently
+supports only the flat24 model, but the -model-flat24 switch is still
+required, in case later versions of the code generator support other
+models (such as the paged mode of the '390). The combination of -mmcs51
+and -model-flat24 is now depracated.
+
+<P>
+Note that the compiler does not generate any code to place the processor
+into24 bitmode (it defaults to 8051 compatible mode). Boot loader
+or similar code must ensure that the processor is in 24 bit contiguous
+addressing mode before calling the SDCC startup code.
+
+<P>
+Like the -model-large option, variables will by default be placed
+into the XDATA segment.
+
+<P>
+Segments may be placed anywhere in the 4 meg address space using the
+usual -*-loc options. Note that if any segments are located above
+64K, the -r flag must be passed to the linker to generate the proper
+segment relocations, and the Intel HEX output format must be used.
+The -r flag can be passed to the linker by using the option -Wl-r
+on the sdcc command line.
+
+<P>
+
+<H2><A NAME="SECTION000416000000000000000">
+3.16 Defines Created by the Compiler</A>
+</H2>
+
+<P>
+The compiler creates the following #defines .
+
+<P>
+
+<UL>
+<LI>SDCC - this Symbol is always defined.
+</LI>
+<LI>SDCC_STACK_AUTO - this symbol is defined when -stack-auto option
+is used.
+</LI>
+<LI>SDCC_MODEL_SMALL - when small model is used.
+</LI>
+<LI>SDCC_MODEL_LARGE - when -model-large is used.
+</LI>
+<LI>SDCC_USE_XSTACK - when -xstack option is used.
+</LI>
+</UL>
+
+<P>
+
+<H1><A NAME="SECTION00050000000000000000">
+4 SDCC Technical Data</A>
+</H1>
+
+<P>
+
+<H2><A NAME="SECTION00051000000000000000">
+4.1 Optimizations</A>
+</H2>
+
+<P>
+SDCC performs a a host of standard optimizations in addition to some
+MCU specific optimizations.
+
+<P>
+
+<H3><A NAME="SECTION00051100000000000000">
+4.1.1 Sub-expression Elimination</A>
+</H3>
+
+<P>
+The compiler does <I>local and global</I> common subexpression elimination.
+
+<P>
+<TT><FONT SIZE="-2">eg. </FONT></TT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">i = x + y + 1;</FONT>
+<BR>
+j <FONT SIZE="-1">= x + y;</FONT>
+<P>
+
+
+<P>
+will be translated to
+
+<P>
+<FONT SIZE="-1">iTemp = x + y </FONT>
+<BR><FONT SIZE="-1">i = iTemp + 1 </FONT>
+<BR><FONT SIZE="-1">j = iTemp</FONT>
+<P>
+
+
+<P>
+Some subexpressions are not as obvious as the above example.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">a->b[i].c = 10; </FONT>
+<BR><FONT SIZE="-1">a->b[i].d = 11;</FONT>
+<P>
+
+
+<P>
+In this case the address arithmetic <I>a->b[i]</I> will be computed
+only once; the equivalent code in C would be.
+
+<P>
+<FONT SIZE="-1">iTemp = a->b[i]; </FONT>
+<BR><FONT SIZE="-1">iTemp.c = 10; </FONT>
+<BR><FONT SIZE="-1">iTemp.d = 11;</FONT>
+<P>
+
+
+<P>
+The compiler will try to keep these temporary variables in registers.
+
+<P>
+
+<H3><A NAME="SECTION00051200000000000000">
+4.1.2 Dead-Code Elimination</A>
+</H3>
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">int global; </FONT>
+<BR><FONT SIZE="-1">void f () { </FONT>
+<BR><FONT SIZE="-1"> int i; </FONT>
+<BR><FONT SIZE="-1"> i = 1; /* dead store */ </FONT>
+<BR><FONT SIZE="-1"> global = 1; /* dead store */ </FONT>
+<BR><FONT SIZE="-1"> global = 2; </FONT>
+<BR><FONT SIZE="-1"> return; </FONT>
+<BR><FONT SIZE="-1"> global = 3; /* unreachable */ </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+will be changed to
+
+<P>
+<FONT SIZE="-1">int global; void f () </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> global = 2; </FONT>
+<BR><FONT SIZE="-1"> return; </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+
+<H3><A NAME="SECTION00051300000000000000">
+4.1.3 Copy-Propagation</A>
+</H3>
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">int f() { </FONT>
+<BR><FONT SIZE="-1"> int i, j; </FONT>
+<BR><FONT SIZE="-1"> i = 10; </FONT>
+<BR><FONT SIZE="-1"> j = i; </FONT>
+<BR><FONT SIZE="-1"> return j; </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+will be changed to
+
+<P>
+<FONT SIZE="-1">int f() { </FONT>
+<BR><FONT SIZE="-1"> int i,j; </FONT>
+<BR><FONT SIZE="-1"> i = 10; </FONT>
+<BR><FONT SIZE="-1"> j = 10; </FONT>
+<BR><FONT SIZE="-1"> return 10; </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+Note: the dead stores created by this copy propagation will be eliminated
+by dead-code elimination .
+
+<P>
+
+<H3><A NAME="SECTION00051400000000000000">
+4.1.4 Loop Optimizations</A>
+</H3>
+
+<P>
+Two types of loop optimizations are done by SDCC loop invariant lifting
+and strength reduction of loop induction variables.In addition to
+the strength reduction the optimizer marks the induction variables
+and the register allocator tries to keep the induction variables in
+registers for the duration of the loop. Because of this preference
+of the register allocator , loop induction optimization causes an
+increase in register pressure, which may cause unwanted spilling of
+other temporary variables into the stack / data space . The compiler
+will generate a warning message when it is forced to allocate extra
+space either on the stack or data space. If this extra space allocation
+is undesirable then induction optimization can be eliminated either
+for the entire source file ( with -noinduction option) or for a given
+function only (#pragma NOINDUCTION).
+
+<P>
+
+<UL>
+<LI><B>Loop Invariant:</B>
+</LI>
+</UL>
+eg
+
+<P>
+<FONT SIZE="-1">for (i = 0 ; i < 100 ; i ++) </FONT>
+<BR><FONT SIZE="-1"> f += k + l;</FONT>
+<P>
+
+
+<P>
+changed to
+
+<P>
+<FONT SIZE="-1">itemp = k + l; </FONT>
+<BR><FONT SIZE="-1">for ( i = 0; i < 100; i++ ) f += itemp;</FONT>
+<P>
+
+
+<P>
+As mentioned previously some loop invariants are not as apparent,
+all static address computations are also moved out of the loop.
+
+<P>
+
+<UL>
+<LI><B>Strength Reduction :</B>
+</LI>
+</UL>
+This optimization substitutes an expression by a cheaper expression.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">for (i=0;i < 100; i++) ar[i*5] = i*3;</FONT>
+<P>
+
+
+<P>
+changed to
+
+<P>
+<FONT SIZE="-1">itemp1 = 0; </FONT>
+<BR><FONT SIZE="-1">itemp2 = 0; </FONT>
+<BR><FONT SIZE="-1">for (i=0;i< 100;i++) { </FONT>
+<BR><FONT SIZE="-1"> ar[itemp1] = itemp2; </FONT>
+<BR><FONT SIZE="-1"> itemp1 += 5; </FONT>
+<BR><FONT SIZE="-1"> itemp2 += 3; </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+The more expensive multiplication is changed to a less expensive addition.
+
+<P>
+
+<H3><A NAME="SECTION00051500000000000000">
+4.1.5 Loop Reversing:</A>
+</H3>
+
+<P>
+This optimization is done to reduce the overhead of checking loop
+boundaries for every iteration. Some simple loops can be reversed
+and implemented using a ``decrement and jump if not zero'' instruction.
+SDCC checks for the following criterion to determine if a loop is
+reversible (note: more sophisticated compiers use data-dependency
+analysis to make this determination, SDCC uses a more simple minded
+analysis).
+
+<P>
+
+<UL>
+<LI>The 'for' loop is of the form
+<BR>``for ( <symbol> = <expression> ; <sym> [< | <=] <expression>
+; [<sym>++ | <sym> += 1])
+<BR> <for body>''
+</LI>
+<LI>The <for body> does not contain ``continue'' or 'break''.
+</LI>
+<LI>All goto's are contained within the loop.
+</LI>
+<LI>No function calls within the loop.
+</LI>
+<LI>The loop control variable <sym> is not assigned any value within the
+loop
+</LI>
+<LI>The loop control variable does NOT participate in any arithmetic operation
+within the loop.
+</LI>
+<LI>There are NO switch statements in the loop.
+</LI>
+</UL>
+Note djnz instruction can be used for 8-bit values ONLY, therefore
+it is advantageous to declare loop control symbols as either 'char'
+or 'short', ofcourse this may not be possible on all situations.
+
+<P>
+
+<H3><A NAME="SECTION00051600000000000000">
+4.1.6 Algebraic Simplifications</A>
+</H3>
+
+<P>
+SDCC does numerous algebraic simplifications, the following is a small
+sub-set of these optimizations.
+
+<P>
+<FONT SIZE="-1">eg</FONT> <I></I>
+<BR><FONT SIZE="-1">i = j + 0 ; /* changed to */ i = j; </FONT>
+<BR><FONT SIZE="-1">i /= 2; /* changed to */ i >>= 1; </FONT>
+<BR><FONT SIZE="-1">i = j - j ; /* changed to */ i = 0; </FONT>
+<BR><FONT SIZE="-1">i = j / 1 ; /* changed to */ i = j;</FONT>
+<P>
+
+
+<P>
+Note the subexpressions given above are generally introduced by macro
+expansions or as a result of copy/constant propagation.
+
+<P>
+
+<H3><A NAME="SECTION00051700000000000000">
+4.1.7 'switch' Statements</A>
+</H3>
+
+<P>
+SDCC changes switch statements to jump tables when the following conditions
+are true.
+
+<P>
+
+<UL>
+<LI>The case labels are in numerical sequence , the labels need not be
+in order, and the starting number need not be one or zero.
+</LI>
+</UL>
+eg
+
+<P>
+<FONT SIZE="-1">switch(i) { switch (i)
+{ </FONT>
+<BR><FONT SIZE="-1">case 4:... case 1: ...
+</FONT>
+<BR><FONT SIZE="-1">case 5:... case 2: ...
+</FONT>
+<BR><FONT SIZE="-1">case 3:... case 3: ...
+</FONT>
+<BR><FONT SIZE="-1">case 6:... case 4: ...
+</FONT>
+<BR><FONT SIZE="-1">} }</FONT>
+<P>
+
+
+<P>
+Both the above switch statements will be implemented using a jump-table.
+
+<P>
+
+<UL>
+<LI>The number of case labels is at least three, since it takes two conditional
+statements to handle the boundary conditions.
+</LI>
+<LI>The number of case labels is less than 84, since each label takes
+3 bytes and a jump-table can be utmost 256 bytes long.
+</LI>
+</UL>
+Switch statements which have gaps in the numeric sequence or those
+that have more that 84 case labels can be split into more than one
+switch statement for efficient code generation.
+
+<P>
+eg
+
+<P>
+<FONT SIZE="-1">switch (i) { </FONT>
+<BR><FONT SIZE="-1">case 1: ... </FONT>
+<BR><FONT SIZE="-1">case 2: ... </FONT>
+<BR><FONT SIZE="-1">case 3: ... </FONT>
+<BR><FONT SIZE="-1">case 4: ... </FONT>
+<BR><FONT SIZE="-1">case 9: ... </FONT>
+<BR><FONT SIZE="-1">case 10: ... </FONT>
+<BR><FONT SIZE="-1">case 11: ... </FONT>
+<BR><FONT SIZE="-1">case 12: ... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+If the above switch statement is broken down into two switch statements
+
+<P>
+<FONT SIZE="-1">switch (i) { </FONT>
+<BR><FONT SIZE="-1">case 1: ... </FONT>
+<BR><FONT SIZE="-1">case 2: ... </FONT>
+<BR><FONT SIZE="-1">case 3: ... </FONT>
+<BR><FONT SIZE="-1">case 4: ... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">switch (i) { </FONT>
+<BR><FONT SIZE="-1">case 9: ... </FONT>
+<BR><FONT SIZE="-1">case 10: ... </FONT>
+<BR><FONT SIZE="-1">case 11: ... </FONT>
+<BR><FONT SIZE="-1">case 12:... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+then both the switch statements will be implemented using jump-tables
+whereas the unmodified switch statement will not be .
+
+<P>
+
+<H3><A NAME="SECTION00051800000000000000">
+4.1.8 Bit-shifting Operations.</A>
+</H3>
+
+<P>
+Bit shifting is one of the most frequently used operation in embedded
+programming . SDCC tries to implement bit-shift operations in the
+most efficient way possible.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">unsigned short i;</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">i>>= 4; </FONT>
+<BR><FONT SIZE="-1">..</FONT>
+<P>
+
+
+<P>
+generates the following code.
+
+<P>
+<FONT SIZE="-1">mov a,_i </FONT>
+<BR><FONT SIZE="-1">swap a </FONT>
+<BR><FONT SIZE="-1">anl a,#0x0f </FONT>
+<BR><FONT SIZE="-1">mov _i,a</FONT>
+<P>
+
+
+<P>
+In general SDCC will never setup a loop if the shift count is known.
+Another example
+
+<P>
+<FONT SIZE="-1">unsigned int i; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">i >>= 9; </FONT>
+<BR><FONT SIZE="-1">...</FONT>
+<P>
+
+
+<P>
+will generate
+
+<P>
+<FONT SIZE="-1">mov a,(_i + 1) </FONT>
+<BR><FONT SIZE="-1">mov (_i + 1),#0x00 </FONT>
+<BR><FONT SIZE="-1">clr c </FONT>
+<BR><FONT SIZE="-1">rrc a </FONT>
+<BR><FONT SIZE="-1">mov _i,a</FONT>
+<P>
+
+
+<P>
+Note that SDCC stores numbers in <SMALL>LITTLE-ENDIAN</SMALL> format (i.e.
+lowest order first)
+
+<P>
+
+<H3><A NAME="SECTION00051900000000000000">
+4.1.9 Bit-rotation</A>
+</H3>
+
+<P>
+A special case of the bit-shift operation is bit rotation, SDCC recognizes
+the following expression to be a left bit-rotation.
+
+<P>
+<FONT SIZE="-1">unsigned char i; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">i = ( ( i << 1) | ( i >>
+7)); </FONT>
+<BR><FONT SIZE="-1">...</FONT>
+<P>
+
+
+<P>
+will generate the following code.
+
+<P>
+<FONT SIZE="-1">mov a,_i </FONT>
+<BR><FONT SIZE="-1">rl a </FONT>
+<BR><FONT SIZE="-1">mov _i,a</FONT>
+<P>
+
+
+<P>
+SDCC uses pattern matching on the parse tree to determine this operation
+.Variations of this case will also be recognized as bit-rotation i.e
+<I>i = ((i >> 7) | (i <<
+1));</I> /* left-bit rotation */
+
+<P>
+
+<H3><A NAME="SECTION000511000000000000000">
+4.1.10 Highest Order Bit</A>
+</H3>
+
+<P>
+It is frequently required to obtain the highest order bit of an integral
+type (int,long,short or char types). SDCC recognizes the following
+expression to yield the highest order bit and generates optimized
+code for it.
+
+<P>
+<FONT SIZE="-1">eg </FONT>
+<BR><FONT SIZE="-1">unsigned int gint; </FONT>
+<BR><FONT SIZE="-1">foo () { </FONT>
+<BR><FONT SIZE="-1">unsigned char hob; </FONT>
+<BR><FONT SIZE="-1"> ... </FONT>
+<BR><FONT SIZE="-1"> hob = (gint >> 15) & 1; </FONT>
+<BR><FONT SIZE="-1"> .. </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+Will generate the following code.
+
+<P>
+<FONT SIZE="-1"> 61
+; hob.c 7 </FONT>
+<BR><FONT SIZE="-1"> 000A E5*01 62
+mov a,(_gint + 1) </FONT>
+<BR><FONT SIZE="-1"> 000C 33 63
+rlc a </FONT>
+<BR><FONT SIZE="-1"> 000D E4 64
+clr a </FONT>
+<BR><FONT SIZE="-1"> 000E 13 65
+rrc a </FONT>
+<BR><FONT SIZE="-1"> 000F F5*02 66
+mov _foo_hob_1_1,a</FONT>
+<P>
+
+
+<P>
+Variations of this case however will NOT be recognized . It is a standard
+C expression , so I heartily recommend this be the only way to get
+the highest order bit, (it is portable). Of course it will be recognized
+even if it is embedded in other expressions.
+
+<P>
+<FONT SIZE="-1">eg.</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">xyz = gint + ((gint >> 15) & 1);</FONT>
+<P>
+
+
+<P>
+will still be recognized.
+
+<P>
+
+<H3><A NAME="SECTION000511100000000000000">
+4.1.11 Peep-hole Optimizer</A>
+</H3>
+
+<P>
+The compiler uses a rule based , pattern matching and re-writing mechanism
+for peep-hole optimization . It is inspired by '<I>copt'</I> a peep-hole
+optimizer by Christopher W. Fraser (cwfraser@microsoft.com). A default
+set of rules are compiled into the compiler, additional rules may
+be added with the -peep-file <filename> option. The rule language
+is best illustrated with examples.
+
+<P>
+<FONT SIZE="-1">replace { </FONT>
+<BR><FONT SIZE="-1">mov %1,a </FONT>
+<BR><FONT SIZE="-1">mov a,%1 } by { mov %1,a }</FONT>
+<P>
+
+
+<P>
+The above rule will the following assembly sequence
+
+<P>
+<FONT SIZE="-1">mov r1,a </FONT>
+<BR><FONT SIZE="-1">mov a,r1</FONT>
+<P>
+
+
+<P>
+to
+
+<P>
+<FONT SIZE="-1">mov r1,a</FONT>
+<P>
+
+
+<P>
+Note: All occurrences of a '%n' ( pattern variable ) must denote
+the same string. With the above rule, the assembly sequence
+
+<P>
+<FONT SIZE="-1">mov r1,a </FONT>
+<BR><FONT SIZE="-1">mov a,r2</FONT>
+<P>
+
+
+<P>
+will remain unmodified. Other special case optimizations may be added
+by the user (via -peep-file option), eg. some variants of the 8051
+MCU allow only 'AJMP' and 'ACALL' , the following two rules will change
+all 'LJMP' & 'LCALL' to 'AJMP' & 'ACALL'.
+
+<P>
+<FONT SIZE="-1">replace { lcall %1 } by { acall %1 } </FONT>
+<BR><FONT SIZE="-1">replace { ljmp %1 } by { ajmp %1 }</FONT>
+<P>
+
+
+<P>
+The inline-assembler' code is also passed through the peep hole optimizer,
+thus the peephole optimizer can also be used as an assembly level
+macro expander. The rules themselves are MCU dependent whereas the
+rule language infra-structure is MCU independent. Peephole optimization
+rules for other MCU can be easily programmed using the rule language.
+
+<P>
+The syntax for a rule is as follows ,
+
+<P>
+<FONT SIZE="-1">rule := replace [ restart ] '{' <assembly sequence> '\n'
+</FONT>
+<BR><FONT SIZE="-1"> '}' by '{' '\n'
+</FONT>
+<BR><FONT SIZE="-1"> <assembly
+sequence> '\n' </FONT>
+<BR><FONT SIZE="-1"> '}' [if <functionName>
+] '\n' </FONT>
+<BR><FONT SIZE="-1"><assembly sequence> := assembly instruction (each instruction
+including labels must be on a separate line). </FONT>
+<P>
+
+
+<P>
+The optimizer will apply to the rules one by one from the top in the
+sequence of their appearance, it will terminate when all rules are
+exhausted. If the '<I>restart</I>' option is specified, then the optimizer
+will start matching the rules again from the top, this option for
+a rule is expensive (performance), it is intended to be used in situations
+where a transformation will trigger the same rule again. A good example
+of this the following rule.
+
+<P>
+<FONT SIZE="-1">replace restart { </FONT>
+<BR><FONT SIZE="-1">pop %1 </FONT>
+<BR><FONT SIZE="-1">push %1 } by { </FONT>
+<BR><FONT SIZE="-1">; nop </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+Note that the replace pattern cannot be a blank, but can be a comment
+line. Without the '<I>restart</I>' option only the inner most 'pop'
+'push' pair would be eliminated. i.e.
+
+<P>
+<FONT SIZE="-1">pop ar1 </FONT>
+<BR><FONT SIZE="-1">pop ar2 </FONT>
+<BR><FONT SIZE="-1">push ar2 </FONT>
+<BR><FONT SIZE="-1">push ar1</FONT>
+<P>
+
+
+<P>
+would result in
+
+<P>
+<FONT SIZE="-1">pop ar1 </FONT>
+<BR><FONT SIZE="-1">; nop </FONT>
+<BR><FONT SIZE="-1">push ar1</FONT>
+<P>
+
+
+<P>
+with the '<I>restart</I>' option the rule will be applied again to
+the resulting code and the all the '<I>pop' 'push'</I> pairs will
+be eliminated to yield
+
+<P>
+<FONT SIZE="-1">; nop </FONT>
+<BR><FONT SIZE="-1">; nop</FONT>
+<P>
+
+
+<P>
+A conditional function can be attached to a rule. Attaching rules
+are somewhat more involved, let me illustrate this with an example.
+
+<P>
+<FONT SIZE="-1">replace { </FONT>
+<BR><FONT SIZE="-1"> ljmp %5 </FONT>
+<BR><FONT SIZE="-1">%2:} by { </FONT>
+<BR><FONT SIZE="-1"> sjmp %5 </FONT>
+<BR><FONT SIZE="-1">%2:} if labelInRange</FONT>
+<P>
+
+
+<P>
+The optimizer does a look-up of a function name table defined in function
+'<I>callFuncByName'</I> in the source file <I>SDCCpeeph.c</I> , with
+the name <I>'labelInRange</I>', if it finds a corresponding entry
+the function is called. Note there can be no parameters specified
+for these functions, in this case the use of <I>'%5</I>' is crucial,
+since the function <I>labelInRange</I> expects to find the label in
+that particular variable (the hash table containing the variable bindings
+is passed as a parameter). If you want to code more such functions
+, take a close look at the function <I>labelInRange</I> and the calling
+mechanism in source file <I>SDCCpeeph.c</I>. I know this whole thing
+is a little kludgey , may be some day we will have some better means.
+If you are looking at this file, you will also see the default rules
+that are compiled into the compiler, you can your own rules in the
+default set there if you get tired of specifying the <I>-peep-file</I>
+option.
+
+<P>
+
+<H2><A NAME="SECTION00052000000000000000">
+4.2 Pragmas</A>
+</H2>
+
+<P>
+SDCC supports the following <I>#pragma</I> directives. This directives
+are applicable only at a function level.
+
+<P>
+
+<UL>
+<LI><B>SAVE</B> - this will save all the current options .
+</LI>
+<LI><B>RESTORE</B> - will restore the saved options from the last save.
+Note that SAVES & RESTOREs cannot be nested. SDCC uses the same buffer
+to save the options each time a SAVE is called.
+</LI>
+<LI><B>NOGCSE</B> - will stop global subexpression elimination.
+</LI>
+<LI><B>NOINDUCTION</B> - will stop loop induction optimizations .
+</LI>
+<LI><B>NOJTBOUND</B> - will not generate code for boundary value checking
+, when switch statements are turned into jump-tables.
+</LI>
+<LI><B>NOOVERLAY</B> - the compiler will not overlay the parameters
+and local variables of a function.
+</LI>
+<LI><B>NOLOOPREVERSE</B> - Will not do loop reversal optimization
+</LI>
+<LI><B>EXCLUDE NONE | {acc[,b[,dpl[,dph]]]</B> - The exclude
+pragma disables generation of pair of push/pop instruction in ISR
+function (using interrupt keyword). The directive should be placed
+immediately before the ISR function definition and it affects ALL
+ISR functions following it. To enable the normal register saving for
+ISR functions use ``#pragma EXCLUDE none''
+</LI>
+<LI><B>CALLEE-SAVES function1[,function2[,function3...]]</B>
+- The compiler by default uses a caller saves convention for register
+saving across function calls, however this can cause unneccessary
+register pushing & popping when calling small functions from larger
+functions. This option can be used to switch the register saving convention
+for the function names specified. The compiler will not save registers
+when calling these functions, extra code will be generated at the
+entry & exit for these functions to save & restore the registers
+used by these functions, this can SUBSTANTIALLY reduce code & improve
+run time performance of the generated code. In future the compiler
+(with interprocedural analysis) will be able to determine the appropriate
+scheme to use for each function call. If -callee-saves command line
+option is used, the function names specified in #pragma CALLEE-SAVES
+is appended to the list of functions specified inthe command line.
+</LI>
+</UL>
+The pragma's are intended to be used to turn-off certain optimizations
+which might cause the compiler to generate extra stack / data space
+to store compiler generated temporary variables. This usually happens
+in large functions. Pragma directives should be used as shown in the
+following example, they are used to control options & optimizations
+for a given function; pragmas should be placed <SMALL>BEFORE</SMALL> and/or
+<SMALL>AFTER</SMALL> a function, placing pragma's inside a function body
+could have unpredictable results.
+
+<P>
+<FONT SIZE="-2">eg</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-2">#pragma SAVE /* save the current settings */
+</FONT>
+<BR><FONT SIZE="-2">#pragma NOGCSE /* turnoff global subexpression elimination
+*/ </FONT>
+<BR><FONT SIZE="-2">#pragma NOINDUCTION /* turn off induction optimizations
+*/ </FONT>
+<BR><FONT SIZE="-2">int foo () </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> ... </FONT>
+<BR><FONT SIZE="-2"> /* large code */ </FONT>
+<BR><FONT SIZE="-2"> ... </FONT>
+<BR><FONT SIZE="-2">} </FONT>
+<BR><FONT SIZE="-2">#pragma RESTORE /* turn the optimizations back on
+*/</FONT>
+<P>
+
+
+<P>
+The compiler will generate a warning message when extra space is allocated.
+It is strongly recommended that the SAVE and RESTORE pragma's be used
+when changing options for a function.
+
+<P>
+
+<H2><A NAME="SECTION00053000000000000000">
+4.3 Library Routines</A>
+</H2>
+
+<P>
+The following library routines are provided for your convenience.
+
+<P>
+<B><FONT SIZE="+1">stdio.h</FONT></B> - Contains the following functions printf
+& sprintf these routines are developed by <I>Martijn van Balen
+<balen@natlab.research.philips.com>. </I>
+
+<P>
+<FONT SIZE="-2">%[flags][width][b|B|l|L]type</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-2"> flags: - left justify
+output in specified field width </FONT>
+<BR><FONT SIZE="-2"> + prefix
+output with +/- sign if output is signed type </FONT>
+<BR><FONT SIZE="-2"> space prefix output
+with a blank if it's a signed positive value </FONT>
+<BR><FONT SIZE="-2"> width: specifies
+minimum number of characters outputted for numbers </FONT>
+<BR><FONT SIZE="-2"> or
+strings. </FONT>
+<BR><FONT SIZE="-2"> -
+For numbers, spaces are added on the left when needed. </FONT>
+<BR><FONT SIZE="-2">
+If width starts with a zero character, zeroes and used </FONT>
+<BR><FONT SIZE="-2">
+instead of spaces. </FONT>
+<BR><FONT SIZE="-2"> -
+For strings, spaces are are added on the left or right (when </FONT>
+<BR><FONT SIZE="-2">
+flag '-' is used) when needed. </FONT>
+<BR><FONT SIZE="-2"> </FONT>
+<BR><FONT SIZE="-2"> b/B: byte argument
+(used by d, u, o, x, X) </FONT>
+<BR><FONT SIZE="-2"> l/L: long argument
+(used by d, u, o, x, X)</FONT>
+<BR><FONT SIZE="-2"> type: d decimal number
+</FONT>
+<BR><FONT SIZE="-2"> u unsigned
+decimal number </FONT>
+<BR><FONT SIZE="-2"> o unsigned
+octal number </FONT>
+<BR><FONT SIZE="-2"> x unsigned
+hexadecimal number (0-9, a-f) </FONT>
+<BR><FONT SIZE="-2"> X unsigned
+hexadecimal number (0-9, A-F) </FONT>
+<BR><FONT SIZE="-2"> c character
+</FONT>
+<BR><FONT SIZE="-2"> s string
+(generic pointer) </FONT>
+<BR><FONT SIZE="-2"> p generic
+pointer (I:data/idata, C:code, X:xdata, P:paged) </FONT>
+<BR><FONT SIZE="-2"> f float
+(still to be implemented)</FONT>
+<P>
+
+
+<P>
+Also contains a very simple version of printf (<B>printf_small</B>).
+This simplified version of printf supports only the following formats.
+
+<P>
+<U><FONT SIZE="-2">format output type argument-type</FONT></U>
+<BR><FONT SIZE="-2">%d decimal int </FONT>
+<BR><FONT SIZE="-2">%ld decimal long </FONT>
+<BR><FONT SIZE="-2">%hd decimal short/char </FONT>
+<BR><FONT SIZE="-2">%x hexadecimal int </FONT>
+<BR><FONT SIZE="-2">%lx hexadecimal long </FONT>
+<BR><FONT SIZE="-2">%hx hexadecimal short/char </FONT>
+<BR><FONT SIZE="-2">%o octal int </FONT>
+<BR><FONT SIZE="-2">%lo octal long </FONT>
+<BR><FONT SIZE="-2">%ho octal short/char
+</FONT>
+<BR><FONT SIZE="-2">%c character char/short </FONT>
+<BR><FONT SIZE="-2">%s character _generic pointer</FONT>
+<P>
+
+
+<P>
+The routine is <B>very stack intesive</B> , -stack-after-data parameter
+should be used when using this routine, the routine also takes about
+1K of code space .It also expects an external function named <I>putchar(char
+)</I> to be present (this can be changed). When using the %s format
+the string / pointer should be cast to a generic pointer. eg.
+
+<P>
+<FONT SIZE="-2">printf_small(``my str %s, my int %d\n'',(char
+_generic *)mystr,myint);</FONT>
+<P>
+
+
+<P>
+
+<UL>
+<LI><B><FONT SIZE="+1">stdarg.h</FONT></B> - contains definition for the following macros
+to be used for variable parameter list, note that a function can have
+a variable parameter list if and only if it is 'reentrant'
+
+<P>
+<FONT SIZE="-1">va_list, va_start, va_arg, va_end.</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">setjmp.h</FONT></B> - contains defintion for ANSI <B>setjmp</B>
+& <B>longjmp</B> routines. Note in this case setjmp & longjmp
+can be used between functions executing within the same register bank,
+if long jmp is executed from a function that is using a different
+register bank from the function issuing the setjmp function, the results
+may be unpredictable. The jump buffer requires 3 bytes of data (the
+stack pointer & a 16 byte return address), and can be placed in any
+address space.
+</LI>
+<LI><B><FONT SIZE="+1">stdlib.h</FONT></B> - contains the following functions.
+
+<P>
+<FONT SIZE="-1">atoi, atol.</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">string.h</FONT></B> - contains the following functions.
+
+<P>
+<FONT SIZE="-1">strcpy, strncpy, strcat, strncat, strcmp, strncmp,
+strchr, strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok,
+memcpy, memcmp, memset.</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">ctype.h</FONT></B> - contains the following routines.
+
+<P>
+<FONT SIZE="-1">iscntrl, isdigit, isgraph, islower, isupper, isprint,
+ispunct, isspace, isxdigit, isalnum, isalpha.</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">malloc.h</FONT></B> - The malloc routines are developed by Dmitry
+S. Obukhov (dso@usa.net). These routines will allocate memory from
+the external ram. Here is a description on how to use them (as described
+by the author).
+
+<P>
+<FONT SIZE="-2">//Example: </FONT>
+<BR><FONT SIZE="-2"> // #define DYNAMIC_MEMORY_SIZE 0x2000
+</FONT>
+<BR><FONT SIZE="-2"> // ..... </FONT>
+<BR><FONT SIZE="-2"> // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
+</FONT>
+<BR><FONT SIZE="-2"> // unsigned char xdata * current_buffer;
+</FONT>
+<BR><FONT SIZE="-2"> // ..... </FONT>
+<BR><FONT SIZE="-2"> // void main(void) </FONT>
+<BR><FONT SIZE="-2"> // { </FONT>
+<BR><FONT SIZE="-2"> // ... </FONT>
+<BR><FONT SIZE="-2"> // init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
+</FONT>
+<BR><FONT SIZE="-2"> // //Now it's possible to use
+malloc. </FONT>
+<BR><FONT SIZE="-2"> // ... </FONT>
+<BR><FONT SIZE="-2"> // current_buffer = malloc(0x100);
+</FONT>
+<BR><FONT SIZE="-2"> //</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">serial.h</FONT></B> - Serial IO routines are also developed by
+Dmitry S. Obukhov (dso@usa.net). These routines are interrupt driven
+with a 256 byte circular buffer, they also expect external ram to
+be present. Please see documentation in file SDCCDIR/sdcc51lib/serial.c
+. Note the header file ``serial.h'' MUST be included in the file
+containing the 'main' function.
+</LI>
+<LI><B><FONT SIZE="+1">ser.h</FONT></B> - Alternate serial routine provided by Wolfgang
+Esslinger <wolfgang@WiredMinds.com> these routines are more compact
+and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
+</LI>
+<LI><B><FONT SIZE="+1">ser_ir.h</FONT></B> - Another alternate set of serial routines
+provided by Josef Wolf <jw@raven.inka.de> , these routines do not
+use the external ram.
+</LI>
+<LI><B><FONT SIZE="+1">reg51.h</FONT></B> - contains register definitions for a standard
+8051
+</LI>
+<LI><B><FONT SIZE="+1">reg552.h</FONT></B> - contains register definitions for 80C552.
+</LI>
+<LI><B><FONT SIZE="+1">float.h</FONT></B> - contains min, max and other floating point
+related stuff.
+</LI>
+</UL>
+All library routines are compiled as -model-small , they are all
+non-reentrant, if you plan to use the large model or want to make
+these routines reentrant, then they will have to be recompiled with
+the appropriate compiler option.
+
+<P>
+Have not had time to do the more involved routines like printf, will
+get to them shortly.
+
+<P>
+
+<H2><A NAME="SECTION00054000000000000000">
+4.4 Interfacing with Assembly Routines</A>
+</H2>
+
+<P>
+
+<H2><A NAME="SECTION00055000000000000000">
+4.5 Global Registers used for Parameter Passing</A>
+</H2>
+
+<P>
+By default the compiler uses the global registers ``DPL,DPH,B,ACC''
+to pass the first parameter to a routine, the second parameter onwards
+is either allocated on the stack (for reentrant routines or -stack-auto
+is used) or in the internal / external ram (depending on the memory
+model).
+
+<P>
+
+<H3><A NAME="SECTION00055100000000000000">
+4.5.1 Assembler Routine(non-reentrant)</A>
+</H3>
+
+<P>
+In the following example the function <B>cfunc</B> calls an assembler
+routine <B>asm_func</B>, which takes two parameters.
+
+<P>
+<FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1"> </FONT>
+<BR><FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<BR><FONT SIZE="-2">int main() </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
+<BR><FONT SIZE="-2">}</FONT>
+<P>
+
+
+<P>
+The corresponding assembler function is:-
+
+<P>
+<FONT SIZE="-2"> .globl _asm_func_PARM_2 </FONT>
+<BR><FONT SIZE="-2"> .globl _asm_func </FONT>
+<BR><FONT SIZE="-2"> .area OSEG </FONT>
+<BR><FONT SIZE="-2">_asm_func_PARM_2: .ds 1 </FONT>
+<BR><FONT SIZE="-2"> .area CSEG </FONT>
+<BR><FONT SIZE="-2">_asm_func: </FONT>
+<BR><FONT SIZE="-2"> mov a,dpl </FONT>
+<BR><FONT SIZE="-2"> add a,_asm_func_PARM_2 </FONT>
+<BR><FONT SIZE="-2"> mov dpl,a </FONT>
+<BR><FONT SIZE="-2"> mov dpl,#0x00 </FONT>
+<BR><FONT SIZE="-2"> ret</FONT>
+<P>
+
+
+<P>
+Note here that the return values are placed in 'dpl' - One byte return
+value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and
+'b' for three byte values (generic pointers) and 'dpl','dph','b' &
+'acc' for four byte values.
+
+<P>
+The parameter naming convention is <B>_<function_name>_PARM_<n>,</B>
+where n is the parameter number starting from 1, and counting from
+the left. The first parameter is passed in ``dpl'' for One bye
+parameter, ``dptr'' if two bytes, ``b,dptr'' for three bytes
+and ``acc,b,dptr'' for four bytes, the <TT><B><FONT SIZE="-1">varaible
+name for the second parameter will be _<function_name>_PARM_2.</FONT></B></TT>
+<P>
+
+
+<P>
+Assemble the assembler routine with the following command.
+
+<P>
+asx8051 -losg asmfunc.asm
+
+<P>
+Then compile and link the assembler routine to the C source file with
+the following command,
+
+<P>
+sdcc cfunc.c asmfunc.rel
+
+<P>
+
+<H3><A NAME="SECTION00055200000000000000">
+4.5.2 Assembler Routine(reentrant)</A>
+</H3>
+
+<P>
+In this case the second parameter onwards will be passed on the stack
+, the parameters are pushed from right to left i.e. after the call
+the left most parameter will be on the top of the stack. Here is an
+example.
+
+<P>
+<FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1"> </FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) reentrant
+</FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<BR><FONT SIZE="-2">int main() </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
+<BR><FONT SIZE="-2">}</FONT>
+<P>
+
+
+<P>
+The corresponding assembler routine is.
+
+<P>
+<FONT SIZE="-2"> .globl _asm_func </FONT>
+<BR><FONT SIZE="-2">_asm_func: </FONT>
+<BR><FONT SIZE="-2"> push _bp </FONT>
+<BR><FONT SIZE="-2"> mov _bp,sp </FONT>
+<BR><FONT SIZE="-2"> mov r2,dpl</FONT>
+<BR><FONT SIZE="-2"> mov a,_bp </FONT>
+<BR><FONT SIZE="-2"> clr c </FONT>
+<BR><FONT SIZE="-2"> add a,#0xfd </FONT>
+<BR><FONT SIZE="-2"> mov r0,a </FONT>
+<BR><FONT SIZE="-2"> add a,#0xfc</FONT>
+<BR><FONT SIZE="-2"> mov r1,a </FONT>
+<BR><FONT SIZE="-2"> mov a,@r0 </FONT>
+<BR><FONT SIZE="-2"> add a,r2</FONT>
+<BR><FONT SIZE="-2"> mov dpl,a </FONT>
+<BR><FONT SIZE="-2"> mov dph,#0x00 </FONT>
+<BR><FONT SIZE="-2"> mov sp,_bp </FONT>
+<BR><FONT SIZE="-2"> pop _bp </FONT>
+<BR><FONT SIZE="-2"> ret</FONT>
+<P>
+
+
+<P>
+The compiling and linking procedure remains the same, however note
+the extra entry & exit linkage required for the assembler code, _bp
+is the stack frame pointer and is used to compute the offset into
+the stack for parameters and local variables.
+
+<P>
+
+<H2><A NAME="SECTION00056000000000000000">
+4.6 With -noregparms Option</A>
+</H2>
+
+<P>
+When the source is compiled with -noregparms option , space is allocated
+for each of the parameters passed to a routine.
+
+<P>
+
+<H3><A NAME="SECTION00056100000000000000">
+4.6.1 Assembler Routine Non-reentrant</A>
+</H3>
+
+<P>
+In the following example the function <B>cfunc</B> calls an assembler
+routine <B>asm_func</B>, which takes two parameters.
+
+<P>
+<FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1"> </FONT>
+<BR><FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<BR><FONT SIZE="-2">int main() </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
+<BR><FONT SIZE="-2">}</FONT>
+<P>
+
+
+<P>
+The corresponding assembler function is:-
+
+<P>
+<FONT SIZE="-2"> .globl _asm_func_PARM_1 </FONT>
+<BR><FONT SIZE="-2"> .globl _asm_func_PARM_2 </FONT>
+<BR><FONT SIZE="-2"> .globl _asm_func </FONT>
+<BR><FONT SIZE="-2"> .area OSEG </FONT>
+<BR><FONT SIZE="-2">_asm_func_PARM_1: .ds 1 </FONT>
+<BR><FONT SIZE="-2">_asm_func_PARM_2: .ds 1 </FONT>
+<BR><FONT SIZE="-2"> .area CSEG </FONT>
+<BR><FONT SIZE="-2">_asm_func: </FONT>
+<BR><FONT SIZE="-2"> mov a,_asm_func_PARM_1 </FONT>
+<BR><FONT SIZE="-2"> add a,_asm_func_PARM_2 </FONT>
+<BR><FONT SIZE="-2"> mov dpl,a </FONT>
+<BR><FONT SIZE="-2"> mov dpl,#0x00 </FONT>
+<BR><FONT SIZE="-2"> ret</FONT>
+<P>
+
+
+<P>
+Note here that the return values are placed in 'dpl' - One byte return
+value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and
+'b' for three byte values (generic pointers) and 'dpl','dph','b' &
+'acc' for four byte values.
+
+<P>
+The parameter naming convention is <B>_<function_name>_PARM_<n>,</B>
+where n is the parameter number starting from 1, and counting from
+the left. i.e. the <TT><B><FONT SIZE="-1">left-most parameter
+name will be _<function_name>_PARM_1.</FONT></B></TT>
+<P>
+
+
+<P>
+Assemble the assembler routine with the following command.
+
+<P>
+asx8051 -losg asmfunc.asm
+
+<P>
+Then compile and link the assembler routine to the C source file with
+the following command,
+
+<P>
+sdcc cfunc.c asmfunc.rel
+
+<P>
+
+<H3><A NAME="SECTION00056200000000000000">
+4.6.2 Assembler Routine(reentrant)</A>
+</H3>
+
+<P>
+In this case the parameters will be passed on the stack , the parameters
+are pushed from right to left i.e. after the call the left most parameter
+will be on the top of the stack. Here is an example.
+
+<P>
+<FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1"> </FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) reentrant
+</FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<BR><FONT SIZE="-2">int main() </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
+<BR><FONT SIZE="-2">}</FONT>
+<P>
+
+
+<P>
+The corresponding assembler routine is.
+
+<P>
+<FONT SIZE="-2"> .globl _asm_func </FONT>
+<BR><FONT SIZE="-2">_asm_func: </FONT>
+<BR><FONT SIZE="-2"> push _bp </FONT>
+<BR><FONT SIZE="-2"> mov _bp,sp </FONT>
+<BR><FONT SIZE="-2"> mov a,_bp </FONT>
+<BR><FONT SIZE="-2"> clr c </FONT>
+<BR><FONT SIZE="-2"> add a,#0xfd </FONT>
+<BR><FONT SIZE="-2"> mov r0,a </FONT>
+<BR><FONT SIZE="-2"> mov a,_bp </FONT>
+<BR><FONT SIZE="-2"> clr c </FONT>
+<BR><FONT SIZE="-2"> add a,#0xfc </FONT>
+<BR><FONT SIZE="-2"> mov r1,a </FONT>
+<BR><FONT SIZE="-2"> mov a,@r0 </FONT>
+<BR><FONT SIZE="-2"> add a,@r1 </FONT>
+<BR><FONT SIZE="-2"> mov dpl,a </FONT>
+<BR><FONT SIZE="-2"> mov dph,#0x00 </FONT>
+<BR><FONT SIZE="-2"> mov sp,_bp </FONT>
+<BR><FONT SIZE="-2"> pop _bp </FONT>
+<BR><FONT SIZE="-2"> ret</FONT>
+<P>
+
+
+<P>
+The compiling and linking procedure remains the same, however note
+the extra entry & exit linkage required for the assembler code, _bp
+is the stack frame pointer and is used to compute the offset into
+the stack for parameters and local variables.
+
+<P>
+
+<H2><A NAME="SECTION00057000000000000000">
+4.7 External Stack</A>
+</H2>
+
+<P>
+The external stack is located at the start of the external ram segment
+, and is 256 bytes in size. When -xstack option is used to compile
+the program, the parameters and local variables of all reentrant functions
+are allocated in this area. This option is provided for programs with
+large stack space requirements. When used with the -stack-auto option,
+all parameters and local variables are allocated on the external stack
+(note support libraries will need to be recompiled with the same options).
+
+<P>
+The compiler outputs the higher order address byte of the external
+ram segment into PORT P2, therefore when using the External Stack
+option, this port MAY NOT be used by the application program.
+
+<P>
+
+<H2><A NAME="SECTION00058000000000000000">
+4.8 ANSI-Compliance</A>
+</H2>
+
+<P>
+Deviations from the compliancy.
+
+<P>
+
+<OL>
+<LI>functions are not always reentrant.
+</LI>
+<LI>structures cannot be assigned values directly, cannot be passed as
+function parameters or assigned to each other and cannot be a return
+value from a function.
+
+<P>
+<FONT SIZE="-1">eg</FONT>
+<P>
+
+
+<P>
+</LI>
+</OL>
+<FONT SIZE="-1">struct s { ... }; </FONT>
+<BR><FONT SIZE="-1">struct s s1, s2; </FONT>
+<BR><FONT SIZE="-1">foo() </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">s1 = s2 ; /* is invalid in SDCC although allowed in ANSI
+*/ </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">struct s foo1 (struct s parms) /* is invalid in SDCC although
+allowed in ANSI */ </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">struct s rets; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">return rets;/* is invalid in SDCC although allowed in ANSI
+*/ </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+
+<OL>
+<LI>'long long' (64 bit integers) not supported.
+</LI>
+<LI>'double' precision floating point not supported.
+</LI>
+<LI>integral promotions are suppressed. What does this mean ? The compiler
+will not implicitly promote an integer expression to a higher order
+integer, exception is an assignment or parameter passing.
+</LI>
+<LI>No support for <I>setjmp</I> and <I>longjmp</I> (for now).
+</LI>
+<LI>Old K&R style function declarations are NOT allowed.
+</LI>
+</OL>
+<FONT SIZE="-1">foo( i,j) /* this old style of function declarations
+*/ </FONT>
+<BR><FONT SIZE="-1">int i,j; /* are valid in ANSI .. not valid in SDCC
+*/ </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+
+<OL>
+<LI>functions declared as pointers must be dereferenced during the call.
+
+<P>
+<FONT SIZE="-1">int (*foo)();</FONT>
+<P>
+
+
+<P>
+</LI>
+</OL>
+<FONT SIZE="-1"> ... </FONT>
+<BR><FONT SIZE="-1"> /* has to be called like this */ </FONT>
+<BR><FONT SIZE="-1"> (*foo)();/* ansi standard allows calls to be made
+like 'foo()' */</FONT>
+<P>
+
+
+<P>
+
+<H2><A NAME="SECTION00059000000000000000">
+4.9 Cyclomatic Complexity</A>
+</H2>
+
+<P>
+Cyclomatic complexity of a function is defined as the number of independent
+paths the program can take during execution of the function. This
+is an important number since it defines the number test cases you
+have to generate to validate the function . The accepted industry
+standard for complexity number is 10, if the cyclomatic complexity
+reported by SDCC exceeds 10 you should think about simplification
+of the function logic.
+
+<P>
+Note that the complexity level is not related to the number of lines
+of code in a function. Large functions can have low complexity, and
+small functions can have large complexity levels. SDCC uses the following
+formula to compute the complexity.
+
+<P>
+<FONT SIZE="-1">complexity = (number of edges in control flow graph) - </FONT>
+<BR><FONT SIZE="-1"> (number of nodes in control flow graph)
++ 2;</FONT>
+<P>
+
+
+<P>
+Having said that the industry standard is 10, you should be aware
+that in some cases it may unavoidable to have a complexity level of
+less than 10. For example if you have switch statement with more than
+10 case labels, each case label adds one to the complexity level.
+The complexity level is by no means an absolute measure of the algorithmic
+complexity of the function, it does however provide a good starting
+point for which functions you might look at for further optimization.
+
+<P>
+
+<H1><A NAME="SECTION00060000000000000000">
+5 TIPS</A>
+</H1>
+
+<P>
+Here are a few guide-lines that will help the compiler generate more
+efficient code, some of the tips are specific to this compiler others
+are generally good programming practice.
+
+<P>
+
+<UL>
+<LI>Use the smallest data type to represent your data-value. If it is
+known in advance that the value is going to be less than 256 then
+use a 'short' or 'char' instead of an 'int'.
+</LI>
+<LI>Use unsigned when it is known in advance that the value is not going
+to be negative. This helps especially if you are doing division or
+multiplication.
+</LI>
+<LI>NEVER jump into a LOOP.
+</LI>
+<LI>Declare the variables to be local whenever possible, especially loop
+control variables (induction).
+</LI>
+<LI>Since the compiler does not do implicit integral promotion, the programmer
+should do an explicit cast when integral promotion is required.
+</LI>
+<LI>Reducing the size of division , multiplication & modulus operations
+can reduce code size substantially. Take the following code for example.
+
+<P>
+<FONT SIZE="-1">foobar( unsigned int p1, unsigned char ch)</FONT>
+<BR><FONT SIZE="-1">{</FONT>
+<BR><FONT SIZE="-1"> unsigned char ch1 = p1 % ch ;</FONT>
+<BR><FONT SIZE="-1"> .... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+For the modulus operation the variable ch will be promoted to unsigned
+int first then the modulus operation will be performed (this will
+lead to a call to a support routine). If the code is changed to
+
+<P>
+<FONT SIZE="-1">foobar( unsigned int p1, unsigned char ch)</FONT>
+<BR><FONT SIZE="-1">{</FONT>
+<BR><FONT SIZE="-1"> unsigned char ch1 = (unsigned char)p1 % ch
+;</FONT>
+<BR><FONT SIZE="-1"> .... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+It would substantially reduce the code generated (future versions
+of the compiler will be smart enough to detect such optimization oppurtunities).
+
+<P>
+</LI>
+</UL>
+<B>Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)</B>
+
+<P>
+The 8051 family of micro controller have a minimum of 128 bytes of
+internal memory which is structured as follows
+
+<P>
+- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7
+to R7
+
+<P>
+- Bytes 20-2F - 16 bytes to hold 128 bit variables and
+
+<P>
+- Bytes 30-7F - 60 bytes for general purpose use.
+
+<P>
+Normally the SDCC compiler will only utilise the first bank of registers,
+but it is possible to specify that other banks of registers should
+be used in interrupt routines. By default, the compiler will place
+the stack after the last bank of used registers, i.e. if the first
+2 banks of registers are used, it will position the base of the internal
+stack at address 16 (0X10). This implies that as the stack grows,
+it will use up the remaining register banks, and the 16 bytes used
+by the 128 bit variables, and 60 bytes for general purpose use.
+
+<P>
+By default, the compiler uses the 60 general purpose bytes to hold
+"near data". The compiler/optimiser may also declare
+some Local Variables in this area to hold local data.
+
+<P>
+If any of the 128 bit variables are used, or near data is being used
+then care needs to be taken to ensure that the stack does not grow
+so much that it starts to over write either your bit variables or
+"near data". There is no runtime checking to prevent
+this from happening.
+
+<P>
+The amount of stack being used is affected by the use of the "internal
+stack" to save registers before a subroutine call is made,
+- -stack-auto will declare parameters and local variables on the
+stack - the number of nested subroutines.
+
+<P>
+If you detect that the stack is over writing you data, then the following
+can be done. -xstack will cause an external stack to be used for
+saving registers and (if -stack-auto is being used) storing parameters
+and local variables. However this will produce more and code which
+will be slower to execute.
+
+<P>
+-stack-loc will allow you specify the start of the stack, i.e. you
+could start it after any data in the general purpose area. However
+this may waste the memory not used by the register banks and if the
+size of the "near data" increases, it may creep
+into the bottom of the stack.
+
+<P>
+-stack-after-data, similar to the -stack-loc, but it automatically
+places the stack after the end of the "near data".
+Again this could waste any spare register space.
+
+<P>
+-data-loc allows you to specify the start address of the near data.
+This could be used to move the "near data" further
+away from the stack giving it more room to grow. This will only work
+if no bit variables are being used and the stack can grow to use the
+bit variable space.
+
+<P>
+Conclusion.
+
+<P>
+If you find that the stack is over writing your bit variables or "near
+data" then the approach which best utilised the internal
+memory is to position the "near data" after the
+last bank of used registers or, if you use bit variables, after the
+last bit variable by using the -data-loc, e.g. if two register banks
+are being used and no data variables, -data-loc 16, and - use the
+-stack-after-data option.
+
+<P>
+If bit variables are being used, another method would be to try and
+squeeze the data area in the unused register banks if it will fit,
+and start the stack after the last bit variable.
+
+<P>
+
+<H1><A NAME="SECTION00070000000000000000">
+6 Retargetting for other MCUs.</A>
+</H1>
+
+<P>
+The issues for retargetting the compiler are far too numerous to be
+covered by this document. What follows is a brief description of each
+of the seven phases of the compiler and its MCU dependency.
+
+<P>
+
+<OL>
+<LI>Parsing the source and building the annotated parse tree. This phase
+is largely MCU independent (except for the language extensions). Syntax
+& semantic checks are also done in this phase , along with some initial
+optimizations like back patching labels and the pattern matching optimizations
+like bit-rotation etc.
+</LI>
+<LI>The second phase involves generating an intermediate code which can
+be easy manipulated during the later phases. This phase is entirely
+MCU independent. The intermediate code generation assumes the target
+machine has unlimited number of registers, and designates them with
+the name iTemp. The compiler can be made to dump a human readable
+form of the code generated by using the -dumpraw option.
+</LI>
+<LI>This phase does the bulk of the standard optimizations and is also
+MCU independent. This phase can be broken down into several sub-phases.
+
+<P>
+
+<UL>
+<LI>Break down intermediate code (iCode) into basic blocks.
+</LI>
+<LI>Do control flow & data flow analysis on the basic blocks.
+</LI>
+<LI>Do local common subexpression elimination, then global subexpression
+elimination
+</LI>
+<LI>dead code elimination
+</LI>
+<LI>loop optimizations
+</LI>
+<LI>if loop optimizations caused any changes then do 'global subexpression
+elimination' and 'dead code elimination' again.
+</LI>
+</UL>
+</LI>
+<LI>This phase determines the live-ranges; by live range I mean those
+iTemp variables defined by the compiler that still survive after all
+the optimizations. Live range analysis is essential for register allocation,
+since these computation determines which of these iTemps will be assigned
+to registers, and for how long.
+</LI>
+<LI>Phase five is register allocation. There are two parts to this process
+.
+
+<P>
+
+<OL>
+<LI>The first part I call 'register packing' (for lack of a better term)
+. In this case several MCU specific expression folding is done to
+reduce register pressure.
+</LI>
+<LI>The second part is more MCU independent and deals with allocating
+registers to the remaining live ranges. A lot of MCU specific code
+does creep into this phase because of the limited number of index
+registers available in the 8051.
+</LI>
+</OL>
+</LI>
+<LI>The Code generation phase is (unhappily), entirely MCU dependent and
+very little (if any at all) of this code can be reused for other MCU.
+However the scheme for allocating a homogenized assembler operand
+for each iCode operand may be reused.
+</LI>
+<LI>As mentioned in the optimization section the peep-hole optimizer is
+rule based system, which can reprogrammed for other MCUs.
+</LI>
+</OL>
+
+<P>
+
+<H1><A NAME="SECTION00080000000000000000">
+7 SDCDB - Source Level Debugger</A>
+</H1>
+
+<P>
+SDCC is distributed with a source level debugger. The debugger uses
+a command line interface, the command repertoire of the debugger has
+been kept as close to gdb ( the GNU debugger) as possible. The configuration
+and build process is part of the standard compiler installation, which
+also builds and installs the debugger in the target directory specified
+during configuration. The debugger allows you debug BOTH at the C
+source and at the ASM source level.
+
+<P>
+
+<H2><A NAME="SECTION00081000000000000000">
+7.1 Compiling for Debugging</A>
+</H2>
+
+<P>
+The <I>-debug</I> option must be specified for all files for which
+debug information is to be generated. The complier generates a <I>.cdb</I>
+file for each of these files. The linker updates the <I>.cdb</I> file
+with the address information. This .cdb is used by the debugger .
+
+<P>
+
+<H2><A NAME="SECTION00082000000000000000">
+7.2 How the Debugger Works</A>
+</H2>
+
+<P>
+When the <I>-debug</I> option is specified the compiler generates
+extra symbol information some of which are put into the the assembler
+source and some are put into the .cdb file, the linker updates the
+.cdb file with the address information for the symbols. The debugger
+reads the symbolic information generated by the compiler & the address
+information generated by the linker. It uses the SIMULATOR (Daniel's
+S51) to execute the program, the program execution is controlled by
+the debugger. When a command is issued for the debugger, it translates
+it into appropriate commands for the simulator .
+
+<P>
+
+<H2><A NAME="SECTION00083000000000000000">
+7.3 Starting the Debugger</A>
+</H2>
+
+<P>
+The debugger can be started using the following command line. (Assume
+the file you are debugging has
+
+<P>
+the file name foo).
+
+<P>
+>sdcdb foo
+
+<P>
+The debugger will look for the following files.
+
+<P>
+
+<OL>
+<LI>foo.c - the source file.
+</LI>
+<LI>foo.cdb - the debugger symbol information file.
+</LI>
+<LI>foo.ihx - the intel hex format object file.
+</LI>
+</OL>
+
+<P>
+
+<H2><A NAME="SECTION00084000000000000000">
+7.4 Command Line Options.</A>
+</H2>
+
+<P>
+
+<UL>
+<LI>-directory=<source file directory> this option can used to specify
+the directory search list. The debugger will look into the directory
+list specified for source , cdb & ihx files. The items in the directory
+list must be separated by ':' , e.g. if the source files can be in
+the directories /home/src1 and /home/src2, the -directory option
+should be -directory=/home/src1:/home/src2 . Note there can be no
+spaces in the option.
+</LI>
+<LI>-cd <directory> - change to the <directory>.
+</LI>
+<LI>-fullname - used by GUI front ends.
+</LI>
+<LI>-cpu <cpu-type> - this argument is passed to the simulator please
+see the simulator docs for details.
+</LI>
+<LI>-X <Clock frequency > this options is passed to the simulator please
+see simulator docs for details.
+</LI>
+<LI>-s <serial port file> passed to simulator see simulator docs for details.
+</LI>
+<LI>-S <serial in,out> passed to simulator see simulator docs for details.
+</LI>
+</UL>
+
+<P>
+
+<H2><A NAME="SECTION00085000000000000000">
+7.5 Debugger Commands.</A>
+</H2>
+
+<P>
+As mention earlier the command interface for the debugger has been
+deliberately kept as close the GNU debugger gdb , as possible, this
+will help int integration with existing graphical user interfaces
+(like ddd, xxgdb or xemacs) existing for the GNU debugger.
+
+<P>
+
+<H3><A NAME="SECTION00085100000000000000">
+7.5.1 break [line | file:line | function | file:function]</A>
+</H3>
+
+<P>
+Set breakpoint at specified line or function.
+
+<P>
+sdcdb>break 100
+<BR>
+sdcdb>break foo.c:100
+<BR>
+sdcdb>break funcfoo
+<BR>
+sdcdb>break foo.c:funcfoo
+
+<P>
+
+<H3><A NAME="SECTION00085200000000000000">
+7.5.2 clear [line | file:line | function | file:function ]</A>
+</H3>
+
+<P>
+Clear breakpoint at specified line or function.
+
+<P>
+sdcdb>clear 100
+<BR>
+sdcdb>clear foo.c:100
+<BR>
+sdcdb>clear funcfoo
+<BR>
+sdcdb>clear foo.c:funcfoo
+
+<P>
+
+<H3><A NAME="SECTION00085300000000000000">
+7.5.3 continue</A>
+</H3>
+
+<P>
+Continue program being debugged, after breakpoint.
+
+<P>
+
+<H3><A NAME="SECTION00085400000000000000">
+7.5.4 finish</A>
+</H3>
+
+<P>
+Execute till the end of the current function.
+
+<P>
+
+<H3><A NAME="SECTION00085500000000000000">
+7.5.5 delete [n]</A>
+</H3>
+
+<P>
+Delete breakpoint number 'n'. If used without any option clear ALL
+user defined break points.
+
+<P>
+
+<H3><A NAME="SECTION00085600000000000000">
+7.5.6 info [break | stack | frame | registers ]</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>info break - list all breakpoints
+</LI>
+<LI>info stack - show the function call stack.
+</LI>
+<LI>info frame - show information about the current execution frame.
+</LI>
+<LI>info registers - show content of all registers.
+</LI>
+</UL>
+
+<P>
+
+<H3><A NAME="SECTION00085700000000000000">
+7.5.7 step</A>
+</H3>
+
+<P>
+Step program until it reaches a different source line.
+
+<P>
+
+<H3><A NAME="SECTION00085800000000000000">
+7.5.8 next</A>
+</H3>
+
+<P>
+Step program, proceeding through subroutine calls.
+
+<P>
+
+<H3><A NAME="SECTION00085900000000000000">
+7.5.9 run</A>
+</H3>
+
+<P>
+Start debugged program.
+
+<P>
+
+<H3><A NAME="SECTION000851000000000000000">
+7.5.10 ptype variable </A>
+</H3>
+
+<P>
+Print type information of the variable.
+
+<P>
+
+<H3><A NAME="SECTION000851100000000000000">
+7.5.11 print variable</A>
+</H3>
+
+<P>
+print value of variable.
+
+<P>
+
+<H3><A NAME="SECTION000851200000000000000">
+7.5.12 file filename</A>
+</H3>
+
+<P>
+load the given file name. Note this is an alternate method of loading
+file for debugging.
+
+<P>
+
+<H3><A NAME="SECTION000851300000000000000">
+7.5.13 frame</A>
+</H3>
+
+<P>
+print information about current frame.
+
+<P>
+
+<H3><A NAME="SECTION000851400000000000000">
+7.5.14 set srcmode</A>
+</H3>
+
+<P>
+Toggle between C source & assembly source.
+
+<P>
+
+<H3><A NAME="SECTION000851500000000000000">
+7.5.15 ! simulator command</A>
+</H3>
+
+<P>
+Send the string following '!' to the simulator, the simulator response
+is displayed. Note the debugger does not interpret the command being
+sent to the simulator, so if a command like 'go' is sent the debugger
+can loose its execution context and may display incorrect values.
+
+<P>
+
+<H3><A NAME="SECTION000851600000000000000">
+7.5.16 quit.</A>
+</H3>
+
+<P>
+"Watch me now. Iam going Down. My name is Bobby Brown"
+
+<P>
+
+<H2><A NAME="SECTION00086000000000000000">
+7.6 Interfacing with XEmacs.</A>
+</H2>
+
+<P>
+Two files are (in emacs lisp) are provided for the interfacing with
+XEmacs, <I>sdcdb.el</I> and <I>sdcdbsrc.el</I>. These two files can
+be found in the $(prefix)/bin directory after the installation is
+complete. These files need to be loaded into XEmacs for the interface
+to work, this can be done at XEmacs startup time by inserting the
+following into your <I>'.xemacs'</I> file (which can be found in your
+HOME directory) <I>(load-file sdcdbsrc.el)</I> [ .xemacs is a lisp
+file so the () around the command is REQUIRED), the files can also
+be loaded dynamically while XEmacs is running, set the environment
+variable <I>'EMACSLOADPATH'</I> to the installation bin directory
+[$(prefix)/bin], then enter the following command <I>ESC-x
+load-file sdcdbsrc .</I> To start the interface enter the following command
+<I>ESC-x sdcdbsrc</I> , you will prompted to enter the file name to
+be debugged.
+
+<P>
+The command line options that are passed to the simulator directly
+are bound to default values in the file <I>sdcdbsrc.el</I> the variables
+are listed below these values maybe changed as required.
+
+<P>
+
+<UL>
+<LI>sdcdbsrc-cpu-type '51
+</LI>
+<LI>sdcdbsrc-frequency '11059200
+</LI>
+<LI>sdcdbsrc-serial nil
+</LI>
+</UL>
+The following is a list of key mapping for the debugger interface.
+
+<P>
+
+<BR><FONT SIZE="-2">;; Current Listing :: </FONT>
+<BR><FONT SIZE="-2">;;key binding Comment
+</FONT>
+<BR><FONT SIZE="-2">;;-- ---- ----
+</FONT>
+<BR><FONT SIZE="-2">;; </FONT>
+<BR><FONT SIZE="-2">;; n sdcdb-next-from-src SDCDB
+next command </FONT>
+<BR><FONT SIZE="-2">;; b sdcdb-back-from-src SDCDB
+back command </FONT>
+<BR><FONT SIZE="-2">;; c sdcdb-cont-from-src SDCDB
+continue command</FONT>
+<BR><FONT SIZE="-2">;; s sdcdb-step-from-src SDCDB
+step command </FONT>
+<BR><FONT SIZE="-2">;; ? sdcdb-whatis-c-sexp SDCDB
+ptypecommand for data at </FONT>
+<BR><FONT SIZE="-2">;;
+buffer point </FONT>
+<BR><FONT SIZE="-2">;; x sdcdbsrc-delete SDCDB
+Delete all breakpoints if no arg </FONT>
+<BR><FONT SIZE="-2">;; given
+or delete arg (C-u arg x) </FONT>
+<BR><FONT SIZE="-2">;; m sdcdbsrc-frame SDCDB
+Display current frame if no arg, </FONT>
+<BR><FONT SIZE="-2">;; given
+or display frame arg </FONT>
+<BR><FONT SIZE="-2">;; buffer
+point </FONT>
+<BR><FONT SIZE="-2">;; ! sdcdbsrc-goto-sdcdb Goto
+the SDCDB output buffer </FONT>
+<BR><FONT SIZE="-2">;; p sdcdb-print-c-sexp SDCDB
+print command for data at </FONT>
+<BR><FONT SIZE="-2">;;
+buffer point </FONT>
+<BR><FONT SIZE="-2">;; g sdcdbsrc-goto-sdcdb Goto
+the SDCDB output buffer </FONT>
+<BR><FONT SIZE="-2">;; t sdcdbsrc-mode Toggles
+Sdcdbsrc mode (turns it off) </FONT>
+<BR><FONT SIZE="-2">;; </FONT>
+<BR><FONT SIZE="-2">;; C-c C-f sdcdb-finish-from-src SDCDB
+finish command </FONT>
+<BR><FONT SIZE="-2">;; </FONT>
+<BR><FONT SIZE="-2">;; C-x SPC sdcdb-break Set
+break for line with point </FONT>
+<BR><FONT SIZE="-2">;; ESC t sdcdbsrc-mode Toggle
+Sdcdbsrc mode </FONT>
+<BR><FONT SIZE="-2">;; ESC m sdcdbsrc-srcmode
+Toggle list mode </FONT>
+<BR><FONT SIZE="-2">;; </FONT>
+<BR>
+<P>
+
+
+<P>
+
+<H1><A NAME="SECTION00090000000000000000">
+8 Other Processors</A>
+</H1>
+
+<P>
+
+<H2><A NAME="SECTION00091000000000000000">
+8.1 The Z80 and gbz80 port</A>
+</H2>
+
+<P>
+SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like
+gbz80. The port is incomplete - long support is incomplete (mul, div
+and mod are unimplimented), and both float and bitfield support is
+missing, but apart from that the code generated is correct.
+
+<P>
+As always, the code is the authoritave reference - see z80/ralloc.c
+and z80/gen.c. The stack frame is similar to that generated by the
+IAR Z80 compiler. IX is used as the base pointer, HL is used as a
+temporary register, and BC and DE are available for holding varibles.
+IY is currently unusued. Return values are stored in HL. One bad side
+effect of using IX as the base pointer is that a functions stack frame
+is limited to 127 bytes - this will be fixed in a later version.
+
+<P>
+
+<H1><A NAME="SECTION000100000000000000000">
+9 Support</A>
+</H1>
+
+<P>
+SDCC has grown to be large project, the compiler alone (without the
+Assembler Package, Preprocessor) is about 40,000 lines of code (blank
+stripped). The open source nature of this project is a key to its
+continued growth and support. You gain the benefit and support of
+many active software developers and end users. Is SDCC perfect? No,
+that's why we need your help. The developers take pride in fixing
+reported bugs. You can help by reporting the bugs and helping other
+SDCC users. There are lots of ways to contribute, and we encourage
+you to take part in making SDCC a great software package.
+
+<P>
+
+<H2><A NAME="SECTION000101000000000000000">
+9.1 Reporting Bugs</A>
+</H2>
+
+<P>
+Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
+or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed ASAP. When
+reporting a bug, it is very useful to include a small test program
+which reproduces the problem. If you can isolate the problem by looking
+at the generated assembly code, this can be very helpful. Compiling
+your program with the -dumpall option can sometimes be useful in
+locating optimization problems.
+
+<P>
+
+<H2><A NAME="SECTION000102000000000000000">
+9.2 Acknowledgments</A>
+</H2>
+
+<P>
+Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code
+generator, Debugger, AVR port
+<BR>
+Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX
+& ASLINK.
+<BR>
+John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for
+8051
+<BR>
+Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
+<BR>
+Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware
+simulator
+<BR>
+Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience
+and support.
+<BR>
+Unknown - for the GNU C - preprocessor.
+<BR>
+Michael Hope - The Z80 and Z80GB port, 186 development
+<BR>
+Kevin Vigor - The DS390 port.
+<BR>
+Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
+<BR>
+Scott Datallo - PIC port.
+<BR>(Thanks to all the other volunteer developers who have helped with
+coding, testing, web-page creation, distribution sets, etc. You know
+who you are :-)
+<BR>
+<P>
+This document initially written by Sandeep Dutta
+
+<P>
+All product names mentioned herein may be trademarks of their respective
+companies.
+
+<P>
+<A NAME="1284"></A>
+
+<H1><A NAME="SECTION000110000000000000000">
+About this document ...</A>
+</H1>
+ <STRONG>SDCC Compiler User Guide</STRONG><P>
+This document was generated using the
+<A HREF="http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2K.1beta (1.47)
+<P>
+Copyright © 1993, 1994, 1995, 1996,
+<A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>,
+Computer Based Learning Unit, University of Leeds.
+<BR>
+Copyright © 1997, 1998, 1999,
+<A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>,
+Mathematics Department, Macquarie University, Sydney.
+<P>
+The command line arguments were: <BR>
+ <STRONG>latex2html</STRONG> <TT>-no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir72816uWRHo/lyx_tmpbuf7281E6F6dg/SDCCUdoc.tex</TT>
+<P>
+The translation was initiated by Karl Bongers on 2001-07-02<HR>
+<!--Navigation Panel-->
+<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
+ SRC="file:/usr/share/latex2html/icons/nx_grp_g.png">
+<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
+ SRC="file:/usr/share/latex2html/icons/up_g.png">
+<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
+ SRC="file:/usr/share/latex2html/icons/prev_g.png">
+<BR>
+<!--End of Navigation Panel-->
+<ADDRESS>
+Karl Bongers
+2001-07-02
+</ADDRESS>
</BODY>
</HTML>
-#This file was created by <kvigor> Wed Oct 4 16:57:26 2000
-#LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team
-\lyxformat 2.15
+#LyX 1.1 created this file. For more info see http://www.lyx.org/
+\lyxformat 218
\textclass article
\language english
\inputencoding default
\layout Title
SDCC Compiler User Guide
-\layout Author
+\layout Standard
+
+
+\begin_inset LatexCommand \tableofcontents{}
+
+\end_inset
+
-Sandeep Dutta (sandeep.dutta@usa.net)
\layout Section
Introduction
+\layout Subsection
+
+About SDCC
\layout Standard
-SDCC is a Free ware , retargettable, optimizing ANSI-C compiler.
- The current version targets Intel 8051 based MCUs, including the Dallas
- 80C390 variant, as well as the Zilog Z80 family.
- It can be retargetted for other 8 bit MCUs or PICs.
+
+\series bold
+SDCC
+\series default
+ is a Free ware, retargettable, optimizing ANSI-C compiler by
+\series bold
+Sandeep Dutta
+\series default
+ designed for 8 bit Microprocessors.
+ The current version targets Intel MCS51 based Microprocessors(8051,8052,
+ etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51 variant.
+ It can be retargetted for other microprocessors, support for PIC, AVR and
+ 186 is under development.
The entire source code for the compiler is distributed under GPL.
SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
- SDCC has extensive MCU (8051) specific language extensions, which lets
- it utilize the underlying hardware effectively.
- The front-end (parser) will be enhanced to handle language extensions for
- other MCUs as and when they are targetted.
- In addition to the MCU Specific optimizations SDCC also does a host of
+ SDCC has extensive language extensions suitable for utilizing various microcont
+rollers underlying hardware effectively.
+ In addition to the MCU specific optimizations SDCC also does a host of
standard optimizations like
\emph on
global sub expression elimination, loop optimizations (loop invariant,
\emph default
For the back-end SDCC uses a global register allocation scheme which should
- be well suited for other 8 bit MCUs , the peep hole optimizer uses a rule
- based substitution mechanism which is MCU independent.
+ be well suited for other 8 bit MCUs.
+ The peep hole optimizer uses a rule based substitution mechanism which
+ is MCU independent.
Supported data-types are
\emph on
short (8 bits, 1 byte), char (8 bits, 1 byte), int (16 bits, 2 bytes ),
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
+ these functions can then be further optimized, or hand coded in assembly
if need be.
SDCC also comes with a companion source level debugger SDCDB, the debugger
- currently uses S51 a freeware simulator for 8051, it can be easily modified
- to use other simulators.
+ currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
The latest version can be downloaded from
\series bold
-http://sdcc.sourceforge.net
+
+\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
+
+\end_inset
+
+.
+\layout Subsection
+
+Open Source
\layout Standard
All packages used in this compiler system are
\emph on
opensource
\emph default
- (freeware); source code for all the sub-packages ( asxxxx assembler/linker
- , pre-processor and
-\emph on
- gc
-\emph default
- a conservative garbage collector) are distributed with the package.
- Documentation was created using a freeware word processor (LyX).
+(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).
\layout Standard
You are forbidden to forbid anyone else to use, share and improve what
you give them.
Help stamp out software-hoarding!
-\layout Section
-
-Installation
-\begin_inset LatexCommand \label{Installation}
-
-\end_inset
-
-
-\layout Standard
-
-What you need before you start installation of SDCC ? A C Compiler, not
- just any C Compiler, gcc to be exact, you can get adventurous and try another
- compiler , I HAVEN'T tried it.
- GCC is free , and is available for almost all major platforms.
- If you are using
-\emph on
-linux
-\emph default
- you probably already have it, if you are using
-\emph on
-Windows 9x/NT
-\emph default
- go to
-\emph on
-http://sources.redhat.com/
-\emph default
- and download
-\emph on
-Cygwin.
+\layout Subsection
-\emph default
-
+System Requirements
\layout Standard
-After you have installed
-\emph on
-gcc
-\emph default
- you are ready to build the compiler (sorry no binary distributions yet).
- SDCC is native to Linux but can be ported to any platform on which GCC
- is available .
- Extract the source file package (
-\emph on
-.zip
-\emph default
- or
-\emph on
-.tar.gz
-\emph default
-) into some directory , which we shall refer to as
-\emph on
-SDCCDIR
-\emph default
- from now on.
+What do you need before you start installation of SDCC? A computer, and
+ a desire to compute.
+ The preferred method of installation is to compile SDCC from source using
+ GNU GCC and make.
+ For Windows some pre-compiled binary distributions are available for your
+ convenience.
+ You should have some experience with command line tools and compiler use.
\layout Subsection
-Components of SDCC
-\begin_inset LatexCommand \label{Components}
-
-\end_inset
-
-
-\layout Subsubsection
-
-gc ( a conservative garbage collector)
+Other Resources
\layout Standard
-SDCC relies on this component to do all the memory management, this excellent
- package is copyrighted by
-\emph on
-Jans J Boehm(boehm@sgi.com) and Alan J Demers
-\emph default
- but can be used with minimum restrictions.
- The GC source will be extracted into the directory
-\emph on
-SDCCDIR/gc.
-
-\emph default
-
-\layout Subsubsection
-
-cpp ( C-Preprocessor)
-\layout Standard
+The SDCC home page at
+\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
-The preprocessor is extracted into the directory
-\emph on
-SDCCDIR/cpp
-\emph default
-, it is a modified version of the GNU preprocessor.
-\layout Subsubsection
+\end_inset
-asxxxx & aslink ( The assembler and Linkage Editor)
-\layout Standard
+ is a great place to find distribution sets.
+ You can also find links to the user mailing lists that offer help or discuss
+ SDCC with other SDCC users.
+ Web links to other SDCC related sites can also be found here.
+ This document can be found in the DOC directory of the source package as
+ a text or HTML file.
+ Some of the other tools(simulator and assembler) included with SDCC contain
+ their own documentation and can be found in the source distribution.
+ If you want the latest unreleased software, the complete source package
+ is available directly by anonymous CVS on www.sourceforge.net.
+\layout Section
-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
-\emph on
-SDCCDIR/asxxxx.
-\layout Subsubsection
+Installation
+\layout Subsection
-SDCC - The compiler.
-\layout Standard
+Linux/Unix Installation
+\layout Enumerate
-This is the actual compiler, it uses
-\emph on
-gc
-\emph default
- and invokes the assembler and linkage editor.
- All files with the prefix
-\emph on
-SDCC
-\emph default
-are part of the compiler and is extracted into the the directory
-\emph on
-SDCCDIR.
-\layout Subsubsection
-S51 - Simulator
-\layout Standard
+\series medium
+Download the source package, it will be named something like sdcc-2.x.x.tgz.
+\layout Enumerate
-Version 2.1.8 onwards contains s51 a freeware , opensource simulator developed
- by Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu>.
- The executable is built as part of build process, for more information
- visit Daniel's website at <http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51/
->.
-\layout Subsubsection
-SDCDB - Source level Debugger.
-\layout Standard
+\series medium
+Bring up a command line terminal, such as xterm.
+\layout Enumerate
-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.
-\layout Subsection
-Installation for Version <= 2.1.7
-\layout Standard
+\series medium
+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.
+\layout Enumerate
-After the package is extracted (
-\emph on
-Windows 95/NT
-\emph default
- users start
-\emph on
-CYGWIN shell)
-\emph default
-, change to the directory where you extracted the package and give the command.
-\layout Standard
+Change directory into the main SDCC directory, for example type:
+\begin_inset Quotes eld
+\end_inset
-./sdccbuild.sh
-\layout Standard
+cd sdcc
+\begin_inset Quotes erd
+\end_inset
-This is a
-\emph on
-bash
-\emph default
- shell script, it will compile all the above mentioned components and install
- the executables into the directory
-\emph on
-SDCCDIR/bin
-\emph default
- make sure you add this directory to your
-\emph on
-PATH
-\emph default
- environment variable.
- This script will also compile all the support routines ( library routines
- ) using SDCC.
- The support routines are all developed in C and need to be compiled.
-\layout Subsection
+.
+\layout Enumerate
-Installation for Version >= 2.1.8a
-\layout Standard
-The distribution method from Version 2.1.8a has been changed to be conforment
- with the
+\series medium
+Type
\begin_inset Quotes eld
\end_inset
-autoconf
+./configure
\begin_inset Quotes erd
\end_inset
- utility.
- The source is now distributed as
-\series bold
-\size large
-\emph on
-sdcc-<version number>.tar.gz format
+
\series default
-\size default
-\emph default
- , instead of the older .zip format.
- The steps for installation are as follows.
-\layout Subsubsection
+.
+ This configures the package for compilation on your system.
+\layout Enumerate
-Unpack the sources.
-\layout Standard
-This is usually done by the following command
+\series medium
+Type
\begin_inset Quotes eld
\end_inset
+make
+\begin_inset Quotes erd
+\end_inset
+
+.
-\series bold
-\size large
-\emph on
-gunzip -c sdcc-<version number>.tar.gz | tar -xv -
\series default
-\size default
-\emph default
+ All of the source packages will compile, this can take a while.
+\layout Enumerate
+
+\series medium
+Type
\begin_inset Quotes eld
\end_inset
+make install
+\begin_inset Quotes erd
+\end_inset
-\layout Subsubsection
-Change to the main source directory (usually sdcc or sdcc-<version number>)
-\layout Subsubsection
+\series default
+ as root
+\series medium
+.
-Issue command to configure your system
-\layout Standard
+\series default
+ This copies the binary executables to the install directories.
+\layout Subsection
-The configure command has several options the most commonly used option
- is --prefix=<directory name>, where <directory name> is the final location
- for the sdcc executables and libraries, (default location is /usr/local).
- The installation process will create the following directory structure
- under the <directory name> specified.
-
+Windows Installation
\layout Standard
-bin/ - binary exectables (add to PATH environment variable)
-\newline
-share/
-\newline
+For installation under Windows you first need to pick between a pre-compiled
+ binary package, or installing the source package along with the Cygwin
+ package.
+ The binary package is the quickest to install, while the Cygwin package
+ includes all of the open source power tools used to compile the complete
+ SDCC source package in the Windows environment.
+ If you are not familiar with the Unix command line environment, you may
+ want to read the section on additional information for Windows users prior
+ to your initial installation.
+\layout Subsubsection
-\protected_separator
+Windows Install Using a Binary Package
+\layout Enumerate
-\protected_separator
+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:
+\backslash
+usr
+\backslash
+local
+\backslash
+bin for the executables, c:
+\backslash
+usr
+\backslash
+local
+\backslash
+share
+\backslash
+sdcc
+\backslash
+include and c:
+\backslash
+usr
+\backslash
+local
+\backslash
+share
+\backslash
+sdcc
+\backslash
+lib for the include and libraries.
+\layout Enumerate
-\protected_separator
+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:
+\backslash
+usr
+\backslash
+local
+\backslash
+bin;%PATH%
+\layout Enumerate
-\protected_separator
+When you compile with sdcc, you may need to specify the location of the
+ lib and include folders.
+ For example, sdcc -I c:
+\backslash
+usr
+\backslash
+local
+\backslash
+share
+\backslash
+sdcc
+\backslash
+include -L c:
+\backslash
+usr
+\backslash
+local
+\backslash
+share
+\backslash
+sdcc
+\backslash
+lib
+\backslash
+small test.c
+\layout Subsubsection
-\protected_separator
+Windows Install Using Cygwin
+\layout Enumerate
-\protected_separator
-sdcc51inc/ - include header files
-\newline
-\protected_separator
+\series medium
+Download and install the cygwin package from the redhat site
+\series default
+\emph on
-\protected_separator
+\begin_inset LatexCommand \htmlurl{http://sources.redhat.com/cygwin/}
-\protected_separator
+\end_inset
-\protected_separator
-\protected_separator
+\series medium
+\emph default
+.
+ Currently, this involved downloading a small install program which then
+ automates downloading and installing
+\series default
+selected parts of
+\series medium
+ the package
+\series default
+(a large 80M byte sized dowload for the whole thing)
+\series medium
+.
-\protected_separator
-sdcc51lib/ -
-\newline
+\series default
+
+\layout Enumerate
-\protected_separator
-\protected_separator
+\series medium
+Bring up a
+\series default
+Unix/Bash
+\series medium
+command line terminal from the Cygwin menu.
+\layout Enumerate
-\protected_separator
-\protected_separator
+\series medium
+Follow the instructions in the preceding Linux/Unix installation section.
+\layout Subsection
-\protected_separator
+Testing out the SDCC Compiler
+\layout Standard
-\protected_separator
+The first thing you should do after installing your SDCC compiler is to
+ see if it runs.
+ Type
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+sdcc --version
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ 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.
+\layout Standard
-\protected_separator
-\protected_separator
+\series medium
+SDCC binaries are commonly installed in a directory arrangement like this:
+\layout Standard
-\protected_separator
-\protected_separator
+\begin_inset Tabular
+<lyxtabular version="2" rows="3" columns="2">
+<features rotate="false" islongtable="false" endhead="0" endfirsthead="0" endfoot="0" endlastfoot="0">
+<column alignment="left" valignment="top" leftline="true" rightline="false" width="" special="">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="" special="">
+<row topline="true" bottomline="true" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\protected_separator
-small/ - Object & Library files for small model library
-\newline
+\layout Standard
-\protected_separator
+/
+\series medium
+usr/local/bin
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\protected_separator
+\layout Standard
-\protected_separator
-\protected_separator
+\series medium
+Holds executables(sdcc, s51, aslink,
+\series default
+...
+\series medium
+)
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\protected_separator
+\layout Standard
-\protected_separator
+/
+\series medium
+usr/local/share/sdcc/lib
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\protected_separator
+\layout Standard
-\protected_separator
-\protected_separator
+\series medium
+Holds common C
+\series default
+libraries
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\protected_separator
+\layout Standard
-\protected_separator
+/
+\series medium
+usr/local/share/sdcc/include
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\protected_separator
+\layout Standard
-\protected_separator
-large/ - Object & library files for large model library
-\newline
-\protected_separator
+\series medium
+Holds common C header files
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-\protected_separator
+\end_inset
-\protected_separator
-\protected_separator
+\layout Standard
-\protected_separator
-\protected_separator
+\series medium
+Make sure the compiler works on a very simple example.
+ Type in the following test.c program using your favorite editor:
+\layout Standard
-\protected_separator
-\protected_separator
+\emph on
+main()
+\newline
+{ int i;
+\newline
+i = 0;
+\newline
+i += 10;
+\newline
+}
+\series medium
+\emph default
-\protected_separator
+\newline
-\protected_separator
+\layout Standard
-\protected_separator
-\protected_separator
+\series medium
+Compile this using the following command:
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
-ds390/ - Object & library files forDS80C390 library
-\newline
+sdcc -c test.c
+\begin_inset Quotes erd
+\end_inset
+.
+ 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.
\layout Standard
-The command
-\layout Standard
+\series medium
+The next step is to try it with the linker.
+ Type in
+\begin_inset Quotes eld
+\end_inset
-\series bold
-\size large
-\bar under
-'./configure --prefix=/usr/local
+sdcc test.c
\begin_inset Quotes erd
\end_inset
-
+.
+ 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
+\series default
+/small
+\series medium
+ directory(see the Install trouble-shooting section for suggestions).
\layout Standard
-will create configure the compiler to be installed in directory /usr/local/bin.
-\layout Subsubsection
-
-make
-\layout Standard
-After configuration step issue the command
+\series medium
+The final test is to ensure sdcc can use the standard header files and libraries.
+ Edit test.c and change it to the following:
\layout Standard
-\series bold
-\size large
-\bar under
-
+\emph on
+#include <string.h>
+\newline
+main()
+\newline
+{ char str1[10];
+\newline
+strcpy(str1,
\begin_inset Quotes eld
\end_inset
-make
+testing
\begin_inset Quotes erd
\end_inset
-
+);
+\newline
+}
\layout Standard
-This will compile the compiler
-\layout Subsubsection
-
+\series medium
+Compile this by typing:
\begin_inset Quotes eld
\end_inset
-make install
+sdcc test.c
\begin_inset Quotes erd
\end_inset
+.
+ 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-shooti
+ng section for suggestions).
+\layout Subsection
-\layout Standard
-
-Will install the compiler and libraries in the appropriate directories.
+Install Trouble-shooting
\layout Subsubsection
-Special Notes for Windows Users.
- Provided by Michael Jamet[ mjamet@computer.org]
+SDCC cannot find libraries or header files.
\layout Standard
-Please note: these instructions are valid for Cygwin versions prior to 1.0.
- If you have Cygwin 1.0 or later, the generic
+The default installation assumes the libraries and header files are located
+ at
\begin_inset Quotes eld
\end_inset
-configure/make/make install
+/usr/local/share/sdcc/lib
\begin_inset Quotes erd
\end_inset
- procedure described above should work as expected from the Cygwin shell.
- If you have an earlier version of Cygwin, I strongly recommend upgrading.
- If, however, you insist on using an earlier version, the following instructions
- should prove helpful.
-\layout Standard
+ and
+\begin_inset Quotes eld
+\end_inset
+/usr/local/share/sdcc/include
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+.
+ 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
+\layout Subsubsection
+SDCC does not compile correctly.
\layout Standard
+A few things to try include starting from scratch by unpacking the .tgz source
+ package again in an empty directory.
+ If this doesn't work, you could try downloading a different version.
+ If this doesn't work, you can re-direct the install messages by doing the
+ following:
+\layout Standard
-\protected_separator
- How to install SDCC from source on a Windows 95 or Windows NT 4 system
-
+$./make > dump.txt 2>&1
\layout Standard
+After this you can examine the dump.txt files to locate the problem.
+ Or these messages can be attached to an email that could be helpful when
+ requesting help from the mailing list.
+\layout Subsubsection
+
+What the
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+./configure
+\begin_inset Quotes erd
+\end_inset
+ does
\layout Standard
+The
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
- This document describes how to install SDCC on a Win 95 or Win NT 4 system.
-
-\layout Standard
+./configure
+\begin_inset Quotes erd
+\end_inset
+ 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.
+\layout Subsubsection
-\protected_separator
- These instructions probably work for Win 98 as well, but have not been
-
-\layout Standard
+What the
+\begin_inset Quotes eld
+\end_inset
+make
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
- tested on that platform.
-
+ does.
\layout Standard
+This runs the GNU make tool, which automatically compiles all the source
+ packages into the final installed binary executables.
+\layout Subsubsection
-\protected_separator
-
-\layout Standard
+What the
+\begin_inset Quotes eld
+\end_inset
+make install
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
- There are lots of little differences between UNIX and the Win32 Cygnus
-
+ command does.
\layout Standard
+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.
+\layout Subsection
-\protected_separator
- environment which make porting more difficult than it should be.
-\protected_separator
- If
+Additional Information for Windows Users
\layout Standard
-
-\protected_separator
- you want the details, please contact me.
-\protected_separator
- Otherwise just follow these
+The standard method of installing on a Unix system involves compiling the
+ source package.
+ This is easily done under Unix, but under Windows it can be a more difficult
+ process.
+ The Cygwin is a large package to download, and the compilation runs considerabl
+y slower under Windows due to the overhead of the Cygwin tool set.
+ An alternative is to install a pre-compiled Windows binary package.
+ There are various trade-offs between each of these methods.
+
\layout Standard
+The Cygwin package allows a Windows user to run a Unix command line interface(ba
+sh 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.
+\layout Subsubsection
-\protected_separator
- instructions.
-
+Getting started with Cygwin
\layout Standard
+SDCC is typically distributed as a tarred/gzipped file(.tgz).
+ This is a packed file similar to a .zip file.
+ Cygwin includes the tools you will need to unpack the SDCC distribution(tar
+ and gzip).
+ To unpack it, simply follow the instructions under the Linux/Unix install
+ section.
+ Before you do this you need to learn how to start a cygwin shell and some
+ of the basic commands used to move files, change directory, run commands
+ and so on.
+ The change directory command is
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+cd
+\begin_inset Quotes erd
+\end_inset
-\layout Standard
+, the move command is
+\begin_inset Quotes eld
+\end_inset
+mv
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
- 1.
- Install the Cygnus Software
-\layout Standard
+.
+ To print the current working directory, type
+\begin_inset Quotes eld
+\end_inset
+pwd
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
- Go to http://sourceware.cygnus.com/cygwin.
-\protected_separator
- Cygnus provides a UNIX like
-\layout Standard
+.
+ To make a directory, use
+\begin_inset Quotes eld
+\end_inset
+mkdir
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
- environment for Win 32 systems.
-\protected_separator
- Download "full.exe" and install.
-\protected_separator
- You
+.
\layout Standard
+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
+ '
+\backslash
+' 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
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
- MUST install it on your C drive.
-\protected_separator
- "full.exe" contains a shell AND many
-\layout Standard
+c:
+\begin_inset Quotes eld
+\end_inset
+, instead all files systems attach and appear as directories.
+\layout Subsubsection
-\protected_separator
- common UNIX utilities.
-
+Running SDCC as Native Compiled Executables
\layout Standard
+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:
+\backslash
+usr
+\backslash
+local
+\backslash
+sdcc
+\backslash
+lib
+\backslash
+small -I c:
+\backslash
+usr
+\backslash
+local
+\backslash
+sdcc
+\backslash
+include test.c if you are running outside of a Unix bash shell.
+\layout Standard
-\protected_separator
+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.
+\layout Subsection
-\layout Standard
+SDCC on Other Platforms
+\layout Itemize
-\protected_separator
- 2.
- Download and Extract the Latest SDCC
-\layout Standard
+\series bold
+FreeBSD and other non-GNU Unixes
+\series default
+- Make sure the GNU make is installed as the default make tool.
+\layout Itemize
+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.
+\layout Subsection
-\protected_separator
- The latest version can be found at
+Advanced Install Options
\layout Standard
+The
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+configure
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
- www.geocities.com/ResearchTriange/Forum/1353.
+ command has several options.
+ The most commonly used option is --prefix=<directory name>, where <directory
+ name> is the final location for the sdcc executables and libraries, (default
+ location is /usr/local).
+ The installation process will create the following directory structure
+ under the <directory name> specified.
\layout Standard
+bin/ - binary exectables (add to PATH environment variable)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+share/
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcc/include/ - include header files
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcc/lib/ -
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+small/ - Object & library files for small model library
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+large/ - Object & library files for large model library
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ds390/ - Object & library files forDS80C390 library
+\layout Standard
-\protected_separator
- It can be uncompressed with winzip.
-
+The command
\layout Standard
-\protected_separator
+\series bold
+\size large
+\bar under
+'./configure --prefix=/usr/local
+\begin_inset Quotes erd
+\end_inset
+
\layout Standard
+will configure the compiler to be installed in directory /usr/local/bin.
+\layout Subsection
-\protected_separator
- 3.
-\protected_separator
- Start a Cygnus Shell
+Components of SDCC
\layout Standard
-
-\protected_separator
- There should be an entry in the Start Menu for Cygnus.
-\protected_separator
- Invoke the shell.
-
+SDCC is not just a compiler, but a collection of tools by various developers.
+ These include linkers, assemblers, simulators and other components.
+ Here is a summary of some of the components.
+ Note that the included simulator and assembler have separate documentation
+ which you can find in the source package in their respective directories.
+ As SDCC grows to include support for other processors, other packages from
+ various developers are included and may have their own sets of documentation.
\layout Standard
-
-\protected_separator
- This gives you a UNIX like environment.
-\protected_separator
- FROM THIS POINT ON, DIRECTORIES
+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:
\layout Standard
-\protected_separator
- MUST BE SPECIFIED WITH FORWARD SLASHES (/) NOT THE DOS STYLE BACK
+\series bold
+sdcc
+\series default
+ - The compiler.
\layout Standard
-\protected_separator
- SLASHES (
-\backslash
-) BECAUSE THIS IS WHAT UNIX EXPECTS.
-\protected_separator
- -
+\series bold
+aslink
+\series default
+ -The linker for 8051 type processors.
\layout Standard
-\protected_separator
-
-\protected_separator
- ex.
- "
-\backslash
-winnt" would be "/winnt" under the shell.
-
+\series bold
+asx8051
+\series default
+ - The assembler for 8051 type processors.
\layout Standard
-\protected_separator
-
+\series bold
+sdcpp
+\series default
+ - The C preprocessor.
\layout Standard
-\protected_separator
- 4.
- Change Directory to Where SDCC was extracted (referred to as INSTALLDIR)
-
+\series bold
+sdcpd
+\series default
+ - The source debugger.
\layout Standard
-\protected_separator
-
+\series bold
+s51
+\series default
+ - The ucSim 8051 simulator.
\layout Standard
-\protected_separator
- ex.
- cd /sdcc218Da.
-\protected_separator
- If you extracted to a drive OTHER THAN C, the drive
+\series bold
+linkz80, linkgbz80
+\series default
+ - The Z80 and GameBoy Z80 linkers.
\layout Standard
-\protected_separator
- must be specified as part of the path.
- For example, if you extracted to
+\series bold
+as-z80, as-gbz80
+\series default
+ - The Z80 and GameBoy Z80 assemblers.
\layout Standard
-\protected_separator
- your "g drive", type the following: "cd //g/mydir".
-\protected_separator
- You must use "//"
+\series bold
+packihx
+\series default
+ - A tool to pack Intel hex files.
\layout Standard
+As development for other processors proceeds, this list will expand to include
+ executables to support processors like AVR, PIC, etc.
+\layout Subsubsection
-\protected_separator
- to specify the drive.
-
+cpp ( C-Preprocessor)
\layout Standard
+The preprocessor is extracted into the directory
+\emph on
+SDCCDIR/cpp
+\emph default
+, 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.
+\layout Subsubsection
-\protected_separator
-
+asxxxx & aslink ( The assembler and Linkage Editor)
\layout Standard
+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
+\emph on
+SDCCDIR/asxxxx.
+\layout Subsubsection
-\protected_separator
- 5.
- Make Dirs Which are Automatically Made During the UNIX Installation
+SDCC - The compiler
\layout Standard
+This is the actual compiler, it in turn uses the c-preprocessor and invokes
+ the assembler and linkage editors.
+ All files with the prefix
+\emph on
+SDCC
+\emph default
+are part of the compiler and are extracted into the the directory
+\emph on
+SDCCDIR.
+\layout Subsubsection
-\protected_separator
- From the INSTALLDIR,
+S51 - Simulator
\layout Standard
+s51 is a freeware, opensource simulator developed by Daniel Drotos <drdani@mazso
+la.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/
+>.
+\layout Subsubsection
-\protected_separator
-
+SDCDB - Source Level Debugger
\layout Standard
+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.
+\layout Section
-\protected_separator
+Using SDCC
+\layout Subsection
-\protected_separator
- mkdir -p bin
-\protected_separator
+Compiling
+\layout Subsubsection
-\protected_separator
- (not a typo, just "bin")
+Single Source File Projects
\layout Standard
-
-\protected_separator
-
-\protected_separator
- mkdir -p /bin
+For single source file 8051 projects the process is very simple.
+ Compile your programs with the following command
\layout Standard
-\protected_separator
-
-\protected_separator
- mkdir -p /usr/local/bin
+\size footnotesize
+sdcc sourcefile.c
\layout Standard
+The above command will compile ,assemble and link your source file.
+ Output files are as follows.
+\layout Itemize
-\protected_separator
-\protected_separator
- mkdir -p /usr/local/share
-\layout Standard
+\size footnotesize
+sourcefile.asm - Assembler source file created by the compiler
+\layout Itemize
-\protected_separator
-
-\protected_separator
- mkdir -p /usr/local/share/sdcc51lib
-\layout Standard
+\size footnotesize
+sourcefile.lst - Assembler listing file created by the Assembler
+\layout Itemize
-\protected_separator
+\size footnotesize
+sourcefile.rst - Assembler listing file updated with linkedit information
+ , created by linkage editor
+\layout Itemize
-\protected_separator
- mkdir -p /usr/local/share/sdcc51inc
-\layout Standard
+\size footnotesize
+sourcefile.sym - symbol listing for the sourcefile, created by the assembler.
+\layout Itemize
-\protected_separator
-\protected_separator
- mkdir -p /tmp
-\layout Standard
+\size footnotesize
+sourcefile.rel - Object file created by the assembler, input to Linkage editor.
+\layout Itemize
-\protected_separator
+\size footnotesize
+sourcefile.map - The memory map for the load module, created by the Linker.
+\layout Itemize
-\layout Standard
+\size footnotesize
+sourcefile.<ihx | s19> - The load module : ihx - Intel hex format (default
+ ), s19 - Motorola S19 format when compiler option --out-fmt-s19 is used.
+\layout Subsubsection
-\protected_separator
- (When a path from the root directory is specified WITHOUT a drive, the
-
+Projects with Multiple Source Files
\layout Standard
-
-\protected_separator
- drive defaults to c.
-\protected_separator
- For example /michael/newuser => c:
-\backslash
-michael
-\backslash
-newuser)
+SDCC can compile only ONE file at a time.
+ Let us for example assume that you have a project containing the following
+ files.
\layout Standard
-\protected_separator
-
+\size footnotesize
+foo1.c ( contains some functions )
\layout Standard
-\protected_separator
- 6.
-\protected_separator
- Add Programs to /bin Expected by the Installation Process
+\size footnotesize
+foo2.c (contains some more functions)
\layout Standard
-\protected_separator
-
-\protected_separator
- - Look at your path: echo $PATH
+\size footnotesize
+foomain.c (contains more functions and the function main)
\layout Standard
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- One of the fields is the diretory with the CYGNUS programs.
-
+The first two files will need to be compiled separately with the commands
\layout Standard
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- ex.
- /CYGNUS/CYGWIN~1/H-I586/BIN
+\size footnotesize
+sdcc -c foo1.c
\layout Standard
-\protected_separator
-
+\size footnotesize
+sdcc -c foo2.c
\layout Standard
-
-\protected_separator
-
-\protected_separator
- - cd to the directory found above.
-\protected_separator
- You may have to fiddle with the
+Then compile the source file containing main and link the other files together
+ with the following command.
\layout Standard
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- case (upper or lower) here because the PATH is SHOWN as all upper
+\size footnotesize
+sdcc foomain.c foo1.rel foo2.rel
\layout Standard
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- case, but is actually mixed.
-\protected_separator
- To help you along, you may type
+Alternatively
+\emph on
+foomain.c
+\emph default
+ can be separately compiled as well
\layout Standard
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- a letter or 2 followed by the escape key.
-\protected_separator
- The shell will fill
+\size footnotesize
+sdcc -c foomain.c
\layout Standard
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- out the remaining letters IF THEY describe a unique directory.
-
+\size footnotesize
+sdcc foomain.rel foo1.rel foo2.rel
\layout Standard
+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.
+\layout Subsubsection
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- If you have problems here, cd one directory and type "ls".
-\protected_separator
- "ls"
+Projects with Additional Libraries
\layout Standard
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- is the equivalent of "dir/w".
-
+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
+\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.
+ Here is an example, assuming you have the source file
+\emph on
+'foomain.c
+\emph default
+' and a library
+\emph on
+ 'foolib.lib'
+\emph default
+ in the directory
+\emph on
+'mylib'
+\emph default
+.
\layout Standard
-\protected_separator
-
+\size footnotesize
+sdcc foomain.c foolib.lib -L mylib
\layout Standard
-
-\protected_separator
-
-\protected_separator
- - Copy the following:
+Note here that
+\emph on
+'mylib
+\emph default
+' must be an absolute path name.
\layout Standard
+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.
+\layout Subsection
-\protected_separator
-
-\protected_separator
+Command Line Options
+\layout Subsubsection
-\protected_separator
- cp sh.exe /bin
-\layout Standard
+Processor Selection Options
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
+\series bold
+-mmcs51
+\series default
+ Generate code for the MCS51 (8051) family of processors.
+ This is the default processor target.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\protected_separator
- cp pwd.exe /bin
-\layout Standard
+\series bold
+-mds390
+\series default
+ Generate code for the DS80C390 processor.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
+\series bold
+-mz80
+\series default
+ Generate code for the Z80 family of processors.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\protected_separator
- cp echo.exe /bin
-\layout Standard
+\series bold
+-mgbz80
+\series default
+ Generate code for the GameBoy Z80 processor.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
+\series bold
+-mavr
+\series default
+ Generate code for the Atmel AVR processor(In development, not complete).
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
+\series bold
+-mpic14
+\series default
+ Generate code for the PIC 14-bit processors(In development, not complete).
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- 7.
- Go back to the INSTALLDIR
-\layout Standard
+\series bold
+-mtlcs900h
+\series default
+ Generate code for the Toshiba TLCS-900H processor(In development, not complete).
+\layout Subsubsection
-\protected_separator
+Path, Lib and Define Options
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- cd INSTALLDIR
-\layout Standard
+\series bold
+\bar under
+-I<path>
+\series default
+\bar default
+ The additional location where the pre processor will look for <..h> or
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
- ex.
- cd //d/sdcc218Da
-\layout Standard
+..h
+\begin_inset Quotes erd
+\end_inset
+ files.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\layout Standard
+\series bold
+\size large
+\bar under
+-D<macro[=value]>
+\series default
+\size default
+\bar default
+ Command line definition of macros.
+ Passed to the pre processor.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- 8.
- Run the configure Program
-\layout Standard
+\series bold
+\size large
+\bar under
+--lib-path(-L)
+\size default
+
+\series default
+\bar default
+<absolute path to additional libraries> This option is passed to the linkage
+ editor, additional libraries search path.
+ The path name must be absolute.
+ Additional library files may be specified in the command line .
+ See section Compiling programs for more details.
+\layout Subsubsection
+MCS51 Options
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\protected_separator
- ./configure
-\layout Standard
+\series bold
+\size large
+--model-large
+\series default
+\size default
+ 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.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- The "./" is important because your current directory is NOT in your path.
+\series bold
+\size large
+\bar under
+--model-small
+\series default
+\emph on
+\bar default
-\layout Standard
+\size default
+\emph default
+Generate code for Small Model programs see section Memory Models for more
+ details.
+ This is the default model.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- Under DOS, your current directory was implicitly always the first entry
+\series bold
+\size large
+\bar under
+--model-flat24
+\series default
+\emph on
+\bar default
-\layout Standard
+\size default
+\emph default
+Generate code forDS80C390 24-bit flat mode.
+ See section Memory Models for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- in your path.
+\series bold
+\size large
+\bar under
+--stack-
+\emph on
+auto
+\series default
+\bar default
-\layout Standard
-
-
-\protected_separator
-
-\layout Standard
+\size default
+\emph default
+All functions in the source file will be compiled as
+\emph on
+reentrant
+\emph default
+, 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.
+
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- 9.
- Run make
-\layout Standard
+\series bold
+\size large
+\bar under
+--xstack
+\series default
+\size default
+\bar 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 Subsubsection
+Optimization Options
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\protected_separator
- make
-\layout Standard
+\series bold
+\size large
+\bar under
+--nogcse
+\series default
+\size default
+\bar default
+ 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.
+\layout List
+\labelwidthstring 00.00.0000
+
+\series bold
+\size large
+\bar under
+--noinvariant
+\series default
+\size default
+\bar default
+ 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.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\layout Standard
+\series bold
+\size large
+\bar under
+--noinduction
+\series default
+\size default
+\bar 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.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- This process takes quite some time under Win 32.
-
-\layout Standard
+\series bold
+\size large
+\bar under
+--nojtbound
+\series default
+\size default
+\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.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
+\series bold
+\size large
+\bar under
+--noloopreverse
+\series default
+\bar default
+
+\size default
+Will not do loop reversal optimization
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
+\series bold
+\size large
+\bar under
+--noregparms
+\series default
+\size default
+\bar default
+ By default the first parameter is passed using global registers (DPL,DPH,B,ACC).
+ This option will disable parameter passing using registers.
+ NOTE: if your program uses the 16/32 bit support routines (for multiplication/d
+ivision) these library routines will need to be recompiled with the --noregparms
+ option as well.
+\layout Subsubsection
-\protected_separator
- 10.
- Install the Newly Built Software
-\layout Standard
+DS390 Options
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
+\series bold
+--stack-auto
+\series default
+ See MCS51 section for description.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- make install
-\layout Standard
+\series bold
+--stack-10bit
+\series default
+ This option generates code for the 10 bit stack mode of the Dallas DS80C390
+ part.
+ In this mode, the stack is located in the lower 1K of the internal RAM,
+ which is mapped to 0x400000.
+ Note that the support is incomplete, since it still uses a single byte
+ as the stack pointer.
+ This means that only the lower 256 bytes of the potential 1K stack space
+ can actually be used.
+ However, this does allow you to reclaim the precious 256 bytes of low RAM
+ for use for the DATA and IDATA segments.
+ The compiler will not generate any code to put the processor into 10 bit
+ stack mode.
+ It is important to ensure that the processor is in this mode before calling
+ any re-entrant functions compiled with this option.
+ In principle, this should work with the --stack-auto option, but that has
+ not been tested.
+ It is incompatible with the --xstack option.
+ It also only makes sense if the processor is in 24 bit contiguous addressing
+ mode (see the --model-flat24 option).
+\layout Subsubsection
-\protected_separator
+Other Options
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
+\series bold
+\size large
+\bar under
+--callee-saves function1[,function2][,function3]....
-\protected_separator
- This will partially install the software into the /usr/local directories
-
-\layout Standard
+\series default
+\size default
+\bar 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.
+ This option can be used to switch the register saving convention for the
+ function names specified.
+ The compiler will not save registers when calling these functions, extra
+ code will be generated at the entry & exit for these functions to save
+ & restore the registers used by these functions, this can SUBSTANTIALLY
+ reduce code & improve run time performance of the generated code.
+ In future the compiler (with interprocedural analysis) will be able to
+ determine the appropriate scheme to use for each function call.
+ DO NOT use this option for built-in functions such as _muluint..., if this
+ option is used for a library function the appropriate library function
+ needs to be recompiled with the same option.
+ If the project consists of multiple source files then all the source file
+ should be compiled with the same --callee-saves option string.
+ Also see Pragma Directive CALLEE-SAVES.
+ .
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- created in step 5.
-\protected_separator
- What it actually doing is copying the .c, .h and
-\layout Standard
+\series bold
+\bar under
+--debug
+\series default
+\bar default
+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
+\labelwidthstring 00.00.0000
-\protected_separator
- library files to directories under /usr/local/share.
+\series bold
+\size large
+\bar under
+--regextend
+\size default
-\layout Standard
+\series default
+\bar default
+ 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.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
+\series bold
+\size large
+\bar under
+--compile-only
+\series default
+\bar default
+(-c)
+\size default
+ will compile and assemble the source only, will not call the linkage editor.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
+\series bold
+\size large
+\bar under
+--xram-loc
+\series default
+\size default
+\bar default
+<Value> The start location of the external ram, default value is 0.
+ The value entered can be in Hexadecimal or Decimal format .eg.
+ --xram-loc 0x8000 or --xram-loc 32768.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- It will NOT be able to install the actual programs (binaries) because
-\layout Standard
+\series bold
+\size large
+\bar under
+--code-loc
+\series default
+\size default
+\bar default
+<Value> The start location of the code segment , default value 0.
+ Note when this option is used the interrupt vector table is also relocated
+ to the given address.
+ The value entered can be in Hexadecimal or Decimal format .eg.
+ --code-loc 0x8000 or --code-loc 32768.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- it does not know programs on Win32 systems have ".exe" extensions.
-
-\layout Standard
+\series bold
+\size large
+\bar under
+--stack-loc
+\series default
+\size default
+\bar default
+<Value> The initial value of the stack pointer.
+ The default value of the stack pointer is 0x07 if only register bank 0
+ is used, if other register banks are used then the stack pointer is initialized
+ to the location above the highest register bank used.
+ eg.
+ if register banks 1 & 2 are used the stack pointer will default to location
+ 0x18.
+ The value entered can be in Hexadecimal or Decimal format .eg.
+ --stack-loc 0x20 or --stack-loc 32.
+ If all four register banks are used the stack will be placed after the
+ data segment (equivalent to --stack-after-data)
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- For example, it tries to install sdcc instead of sdcc.exe.
-
-\layout Standard
+\series bold
+\size large
+\bar under
+--stack-after-data
+\series default
+\size default
+\bar default
+ This option will cause the stack to be located in the internal ram after
+ the data segment.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\layout Standard
+\series bold
+\size large
+\bar under
+--data-loc
+\series default
+\size default
+\bar default
+<Value> The start location of the internal ram data segment, the default
+ value is 0x30.The value entered can be in Hexadecimal or Decimal format
+ .eg.
+ --data-loc 0x20 or --data-loc 32.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- After the automated part is finished, you must manually copy the binaries:
-
-\layout Standard
+\series bold
+\size large
+\bar under
+--idata-loc
+\series default
+\size default
+\bar default
+<Value> The start location of the indirectly addressable internal ram, default
+ value is 0x80.
+ The value entered can be in Hexadecimal or Decimal format .eg.
+ --idata-loc 0x88 or --idata-loc 136.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
+\series bold
+\size large
+\bar under
+--peep-file
+\series default
+\size default
+\bar default
+<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.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
- cd bin
-\protected_separator
- (This is the bin directory in your INSTALLDIR)
-\layout Standard
-
-\protected_separator
-
-\protected_separator
- cp * /usr/local/bin
-\layout Standard
-
-
-\protected_separator
-
-\layout Standard
-
-
-\protected_separator
- 11.
- Make sure /usr/local/bin is in Your PATH
-\layout Standard
-
-
-\protected_separator
- You may add c:
-\backslash
-usr
-\backslash
-local
-\backslash
-bin to your path however your Win32 system allows.
-\protected_separator
- For
-\layout Standard
-
-
-\protected_separator
- example you may add it to the PATH statement in autoexec.bat.
-
-\layout Standard
-
-
-\protected_separator
-
-\layout Standard
-
-
-\protected_separator
- Good luck.
-\protected_separator
- If you have any questions send them to me or post them
-\layout Standard
-
-
-\protected_separator
- to the list.
-\layout Subsubsection
-
-FreeBSD and other non-GNU unixes
-\layout Standard
-
-Note that the SDCC build environment uses Gnu make.
- If this is not the default 'make' on your system, you may need to install
- it.
- On many systems, Gnu make is installed as 'gmake'.
-\layout Section
-
-Compiling.
-\begin_inset LatexCommand \label{Compiling}
-
-\end_inset
-
-
-\layout Subsection
-
-Single Source file projects.
-\begin_inset LatexCommand \label{One Source File}
-
-\end_inset
-
-
-\layout Standard
-
-For single source file projects the process is very simple.
- Compile your programs with the following command
-\layout Standard
-
-
-\size footnotesize
-sdcc sourcefile.c
-\layout Standard
-
-The above command will compile ,assemble and link your source file.
- Output files are as follows.
-\layout Itemize
-
-
-\size footnotesize
-sourcefile.asm - Assembler source file created by the compiler
-\layout Itemize
-
-
-\size footnotesize
-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
-sourcefile.<ihx | s19> - The load module : ihx - Intel hex format (default
- ), s19 - Motorola S19 format when compiler option --out-fmt-s19 is used.
-\layout Subsection
-
-Projects with multiple source files.
-\layout Standard
-
-SDCC can compile only ONE file at a time.
- Let us for example assume that you have a project containing the following
- files.
-\layout Standard
-
-
-\size footnotesize
-foo1.c ( contains some functions )
-\layout Standard
-
-
-\size footnotesize
-foo2.c (contains some more functions)
-\layout Standard
-
-
-\size footnotesize
-foomain.c (contains more functions and the function main)
-\layout Standard
-
-The first two files will need to be compiled separately with the commands
-\layout Standard
-
-
-\size footnotesize
-sdcc -c foo1.c
-\layout Standard
-
-
-\size footnotesize
-sdcc -c foo2.c
-\layout Standard
-
-Then compile the source file containing main and link the other files together
- with the following command.
-\layout Standard
-
-
-\size footnotesize
-sdcc foomain.c foo1.rel foo2.rel
-\layout Standard
-
-Alternatively
-\emph on
-foomain.c
-\emph default
- can be separately compiled as well
-\layout Standard
-
-
-\size footnotesize
-sdcc -c foomain.c
-\layout Standard
-
-
-\size footnotesize
-sdcc foomain.rel foo1.rel foo2.rel
-\layout Standard
-
-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.
-\layout Subsection
-
-Projects with additional libraries.
-\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
-\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.
- Here is an example, assuming you have the source file
-\emph on
-'foomain.c
-\emph default
-' and a library
-\emph on
- 'foolib.lib'
-\emph default
- in the directory
-\emph on
-'mylib'
-\emph default
-.
-\layout Standard
-
-
-\size footnotesize
-sdcc foomain.c foolib.lib -L mylib
-\layout Standard
-
-Note here that
-\emph on
-'mylib
-\emph default
-' must be an absolute path name.
-\layout Standard
-
-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.
-\layout Section
-
-Command Line options
-\begin_inset LatexCommand \label{Command Line Options}
-
-\end_inset
-
-
-\layout Itemize
-
--mmcs51
-\begin_inset LatexCommand \label{-mmcs51}
-
-\end_inset
-
-Generate code for the MCS51 (8051) family of processors.
- This is the default processor target.
-\layout Itemize
-
--mz80
-\begin_inset LatexCommand \label{-mz80}
-
-\end_inset
-
-Generate code for the Z80 family of processors.
- Various other options may not be applicable in this mode.
-
-\layout Itemize
-
-
-\series bold
--mds390
-\series default
-
-\begin_inset LatexCommand \label{-mds390}
-
-\end_inset
-
-Generate code for the DS80C390 processor.
- Various other options may not be applicable in this mode.
-\layout Itemize
-
-
-\series bold
-\size large
---model-large
-\emph on
-
-\begin_inset LatexCommand \label{--model-large}
-
-\end_inset
-
-
-\series default
-\size default
-\emph default
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---model-small
-\series default
-\emph on
-\bar default
-
-\size default
-\emph default
-
-\begin_inset LatexCommand \label{--model-small}
-
-\end_inset
-
-Generate code for Small Model programs see section Memory Models for more
- details.
- This is the default model.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---model-flat24
-\series default
-\emph on
-\bar default
-
-\size default
-\emph default
-
-\begin_inset LatexCommand \ref[--model-flat24]{--model-flat24}
-
-\end_inset
-
-Generate code forDS80C390 24-bit flat mode.
- See section Memory Models for more details.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---stack-
-\emph on
-auto
-\series default
-\bar default
-
-\size default
-\emph default
-
-\begin_inset LatexCommand \label{--stack-auto}
-
-\end_inset
-
-All functions in the source file will be compiled as
-\emph on
-reentrant
-\emph default
-, 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.
-
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---xstack
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--xstack}
-
-\end_inset
-
- 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 Itemize
-
-
-\series bold
-\size large
-\bar under
---nogcse
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--nogcse}
-
-\end_inset
-
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---noinvariant
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--noinvariant}
-
-\end_inset
-
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---noinduction
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--noinduction}
-
-\end_inset
-
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---nojtbound
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--nojtbound}
-
-\end_inset
-
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---noloopreverse
-\series default
-\bar default
-
-\size default
-
-\begin_inset LatexCommand \label{--noloopreverse}
-
-\end_inset
-
-Will not do loop reversal optimization
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---noregparms
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--noregparms}
-
-\end_inset
-
- By default the first parameter is passed using global registers (DPL,DPH,B,ACC).
- This option will disable parameter passing using registers.
- NOTE: if your program uses the 16/32 bit support routines (for multiplication/d
-ivision) these library routines will need to be recompiled with the --noregparms
- option as well.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---callee-saves function1[,function2][,function3]....
-
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--callee-saves}
-
-\end_inset
-
-The compiler by default uses a caller saves convention for register saving
- across function calls, however this can cause unneccessary register pushing
- & popping when calling small functions from larger functions.
- This option can be used to switch the register saving convention for the
- function names specified.
- The compiler will not save registers when calling these functions, extra
- code will be generated at the entry & exit for these functions to save
- & restore the registers used by these functions, this can SUBSTANTIALLY
- reduce code & improve run time performance of the generated code.
- In future the compiler (with interprocedural analysis) will be able to
- determine the appropriate scheme to use for each function call.
- DO NOT use this option for built-in functions such as _muluint..., if this
- option is used for a library function the appropriate library function
- needs to be recompiled with the same option.
- If the project consists of multiple source files then all the source file
- should be compiled with the same --callee-saves option string.
- Also see Pragma Directive
-\begin_inset LatexCommand \ref{Pragmaa}
-
-\end_inset
-
- CALLEE-SAVES.
-\begin_inset LatexCommand \ref{pragma callee-saves}
-
-\end_inset
-
- .
-\layout Itemize
-
-
-\series bold
-\bar under
---debug
-\series default
-\bar default
-
-\begin_inset LatexCommand \label{--debug}
-
-\end_inset
-
-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 Itemize
-
-
-\series bold
-\size large
-\bar under
---regextend
-\size default
-
-\series default
-\bar default
-
-\begin_inset LatexCommand \label{--regextend}
-
-\end_inset
-
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---compile-only
-\series default
-\bar default
-(-c)
-\size default
-
-\begin_inset LatexCommand \label{--compile-only}
-
-\end_inset
-
- will compile and assemble the source only, will not call the linkage editor.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---xram-loc
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--xram-loc}
-
-\end_inset
-
-<Value> The start location of the external ram, default value is 0.
- The value entered can be in Hexadecimal or Decimal format .eg.
- --xram-loc 0x8000 or --xram-loc 32768.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---code-loc
-\size default
-
-\series default
-\bar default
-
-\begin_inset LatexCommand \label{--code-loc}
-
-\end_inset
-
-<Value> The start location of the code segment , default value 0.
- Note when this option is used the interrupt vector table is also relocated
- to the given address.
- The value entered can be in Hexadecimal or Decimal format .eg.
- --code-loc 0x8000 or --code-loc 32768.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---stack-loc
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--stack-loc}
-
-\end_inset
-
-<Value> The initial value of the stack pointer.
- The default value of the stack pointer is 0x07 if only register bank 0
- is used, if other register banks are used then the stack pointer is initialized
- to the location above the highest register bank used.
- eg.
- if register banks 1 & 2 are used the stack pointer will default to location
- 0x18.
- The value entered can be in Hexadecimal or Decimal format .eg.
- --stack-loc 0x20 or --stack-loc 32.
- If all four register banks are used the stack will be placed after the
- data segment (equivalent to --stack-after-data)
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---stack-after-data
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--stack-after-data}
-
-\end_inset
-
-This option will cause the stack to be located in the internal ram after
- the data segment.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---data-loc
-\series default
-\bar default
-
-\size default
-
-\begin_inset LatexCommand \label{--data-loc}
-
-\end_inset
-
-<Value> The start location of the internal ram data segment, the default
- value is 0x30.The value entered can be in Hexadecimal or Decimal format
- .eg.
- --data-loc 0x20 or --data-loc 32.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---idata-loc
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--idata-loc}
-
-\end_inset
-
-<Value> The start location of the indirectly addressable internal ram, default
- value is 0x80.
- The value entered can be in Hexadecimal or Decimal format .eg.
- --idata-loc 0x88 or --idata-loc 136.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---peep-file
-\size default
-
-\begin_inset LatexCommand \label{--peep-file}
-
-\end_inset
-
-
-\series default
-\bar default
-<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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---lib-path (-L)
-\size default
-
-\series default
-\bar default
-
-\begin_inset LatexCommand \label{--lib-path}
-
-\end_inset
-
-<absolute path to additional libraries> This option is passed to the linkage
- editor, additional libraries search path.
- The path name must be absolute.
- Additional library files may be specified in the command line .
- See section Compiling programs for more details.
-\layout Itemize
-
-
-\series bold
-\bar under
--I <path>
-\begin_inset LatexCommand \label{-I}
-
-\end_inset
-
-
-\series default
-\bar default
- The additional location where the pre processor will look for <..h> or
-\begin_inset Quotes eld
-\end_inset
-
-..h
-\begin_inset Quotes erd
-\end_inset
-
- files.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--D<macro[=value]>
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-D}
-
-\end_inset
-
-Command line definition of macros.
- Passed to the pre processor.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--E
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-E}
-
-\end_inset
-
- Run only the C preprocessor.
- Preprocess all the C source files specified and output the results to standard
- output.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--M
-\bar default
-
-\begin_inset LatexCommand \label{-M}
-
-\end_inset
-
-
-\series default
-\size default
- 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 `
-\backslash
-'-newline if it is long.
- The list of rules is printed on standard output instead of the preprocessed
- C program.
- `-M' implies `-E'.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--C
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-C}
-
-\end_inset
-
-Tell the preprocessor not to discard comments.
- Used with the `-E' option.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--MM
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-MM}
-
-\end_inset
-
-Like `-M' but the output mentions only the user header files included with
- `#include file"'.
- System header files included with `#include <file>' are omitted.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--Aquestion(answer)
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-Aquestion(answer)}
-
-\end_inset
-
- Assert the answer answer for question, in case it is tested with a preprocessor
- conditional such as `#if #question(answer)'.
- `-A-' disables the standard asser- tions that normally describe the target
- machine.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--Aquestion
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-Aquestion}
-
-\end_inset
-
- (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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--Umacro
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-Umacro}
-
-\end_inset
-
- Undefine macro macro.
- `-U' options are evaluated after all `-D' options, but before any `-include'
- and `-imac- ros' options.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--dM
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-dM}
-
-\end_inset
-
- Tell the preprocessor to output only a list of the mac- ro definitions
- that are in effect at the end of prepro- cessing.
- Used with the `-E' option.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--dD
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-dD}
-
-\end_inset
-
-Tell the preprocessor to pass all macro definitions into the output, in
- their proper sequence in the rest of the output.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--dN
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-dN}
-
-\end_inset
-
-Like `-dD' except that the macro arguments and contents are omitted.
- Only `#define name' is included in the output.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
--S
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{-S}
-
-\end_inset
-
-Stop after the stage of compilation proper; do not as- semble.
- The output is an assembler code file for the input file specified.
-\layout Itemize
-
-
-\series bold
-\bar under
--Wa asmOption[,asmOption]
-\series default
-\bar default
-...
- Pass the asmOption to the assembler
-\layout Itemize
-
-
-\series bold
-\bar under
--Wl linkOption[,linkOption]
-\series default
-\bar default
- ..
- Pass the linkOption to the linker.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---int-long-reent
-\series default
-\bar default
-
-\size default
-
-\begin_inset LatexCommand \label{--int-long-rent}
-
-\end_inset
-
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---cyclomatic
-\size default
-
-\series default
-\bar default
-
-\begin_inset LatexCommand \label{--cyclomatic}
-
-\end_inset
-
-This option will cause the compiler to generate an information message for
- each function in the source file.
- The message contains some
-\emph on
-important
-\emph default
- 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
-\emph on
-cyclomatic complexity
-\emph default
- see section on Cyclomatic Complexity for more details.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---float-reent
-\size default
-
-\series default
-\bar default
-
-\begin_inset LatexCommand \label{--float-reent}
-
-\end_inset
-
- Floating point library is compiled as reentrant.See section Installation
- for more details.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---out-fmt-ihx
-\size default
-
-\begin_inset LatexCommand \label{--out-fmt-ihx}
-
-\end_inset
-
-
-\series default
-\bar default
-The linker output (final object code) is in Intel Hex format.
- (This is the default option).
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---out-fmt-s19
-\size default
-
-\series default
-\bar default
-
-\begin_inset LatexCommand \label{--out-fmt-s19}
-
-\end_inset
-
-The linker output (final object code) is in Motorola S19 format.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---nooverlay
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--nooverlay}
-
-\end_inset
-
- The compiler will not overlay parameters and local variables of any function,
- see section Parameters and local variables for more details.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---main-return
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--main-return}
-
-\end_inset
-
- 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 .' .
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---no-peep
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--no-peep}
-
-\end_inset
-
- Disable peep-hole optimization.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---peep-asm
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--peep-asm}
-
-\end_inset
-
- Pass the inline assembler code through the peep hole optimizer.
- Can cause unexpected changes to inline assembler code , please go through
- the peephole optimizer rules defnied in file 'SDCCpeeph.def' before using
- this option.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---iram-size
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--iram-size}
-
-\end_inset
-
- <Value> Causes the linker to check if the interal ram usage is within limits
- of the given value.
-\layout Standard
-
-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.
-
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---dumpraw
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--dumpraw}
-
-\end_inset
-
-.
- This option will cause the compiler to dump the intermediate code into
- a file of named
-\emph on
-<source filename>.dumpraw
-\emph default
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---dumpgcse
-\series default
-\bar default
-.
-\size default
-
-\begin_inset LatexCommand \label{--dumpgcse}
-
-\end_inset
-
- Will create a dump if iCode, after global subexpression elimination, into
- a file named
-\emph on
-<source filename>.dumpgcse.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---dumpdeadcode
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--dumpdeadcode}
-
-\end_inset
-
-.Will create a dump if iCode, after deadcode elimination, into a file named
-
-\emph on
-<source filename>.dumpdeadcode.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---dumploop.
-
-\series default
-\bar default
-
-\size default
-
-\begin_inset LatexCommand \label{--dumploop}
-
-\end_inset
-
-Will create a dump if iCode, after loop optimizations, into a file named
-
-\emph on
-<source filename>.dumploop.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---dumprange.
-
-\series default
-\bar default
-
-\size default
-
-\begin_inset LatexCommand \label{--dump-range}
-
-\end_inset
-
-Will create a dump if iCode, after live range analysis, into a file named
-
-\emph on
-<source filename>.dumprange.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---dumpregassign.
-
-\size default
-
-\series default
-\bar default
-
-\begin_inset LatexCommand \label{--dumpregassign}
-
-\end_inset
-
-Will create a dump if iCode, after register assignment , into a file named
-
-\emph on
-<source filename>.dumprassgn.
-\layout Itemize
-
-
-\series bold
-\size large
-\bar under
---dumpall.
-
-\series default
-\size default
-\bar default
-
-\begin_inset LatexCommand \label{--dumpall}
-
-\end_inset
-
-Will cause all the above mentioned dumps to be created.
-\layout Standard
-
-Note that the files created for the dump are appended to each time.
- So the files should be deleted manually , before each dump is created.
-
-\layout Standard
-
-When reporting bugs, it will be very helpful if you could include these
- dumps along with the portion of the code that is causing the problem.
-\layout Section
-
-Language Extensions
-\begin_inset LatexCommand \label{Language Extension}
-
-\end_inset
-
-
-\layout Subsection
-
-Storage Classes.
-\begin_inset LatexCommand \label{Storage Classes}
-
-\end_inset
-
-
-\layout Standard
-
-In addition to the ANSI storage classes SDCC allows the following 8051 specific
- storage classes.
-\layout Subsubsection
-
-xdata.
-\begin_inset LatexCommand \label{xdata}
-
-\end_inset
-
-
-\layout Standard
-
-Variables declared with this storage class will be placed in the extern
- RAM.
- This is the
-\series bold
-default
-\series default
- storage class for Large Memory model .
-\layout Standard
-
-
-\size footnotesize
-eg.
-
-\emph on
-xdata unsigned char xduc;
-\layout Subsubsection
-
-data
-\begin_inset LatexCommand \label{data}
-
-\end_inset
-
-
-\layout Standard
-
-This is the
-\series bold
-default
-\series default
- storage class for Small Memory model.
- Variables declared with this storage class will be allocated in the internal
- RAM.
-\layout Standard
-
-
-\size footnotesize
-eg.
-
-\emph on
- data int iramdata;
-\layout Subsubsection
-
-idata
-\begin_inset LatexCommand \label{idata}
-
-\end_inset
-
-
-\layout Standard
-
-Variables declared with this storage class will be allocated into the indirectly
- addressable portion of the internal ram of a 8051 .
-\layout Standard
-
-
-\size footnotesize
-eg.
-\emph on
-idata int idi;
-\layout Subsubsection
-
-bit
-\begin_inset LatexCommand \label{bit}
-
-\end_inset
-
-
-\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
- memory of 8051.
-\layout Standard
-
-eg.
-\emph on
-bit iFlag;
-\layout Subsubsection
-
-sfr / sbit
-\begin_inset LatexCommand \label{sfr / sbit}
-
-\end_inset
-
-
-\layout Standard
-
-Like the bit keyword,
-\emph on
-sfr / sbit
-\emph default
-signifies both a data-type and storage class, they are used to describe
- the special function registers and special bit variables of a 8051.
-
-\layout Standard
-
-eg.
-
-\emph on
-
-\layout Standard
-
-
-\emph on
-sfr at 0x80 P0;
-\emph default
-\noun on
-/* special function register P0 at location 0x80 */
-\layout Standard
-
-
-\emph on
-sbit at 0xd7 CY; /*
-\noun on
-CY (Carry Flag) */
-\layout Section
-
-Optimizations
-\begin_inset LatexCommand \label{Optimizations}
-
-\end_inset
-
-
-\layout Standard
-
-SDCC performs a a host of standard optimizations in addition to some MCU
- specific optimizations.
-
-\layout Subsection
-
-Sub-expression elimination
-\begin_inset LatexCommand \label{Sub-expression Elimination}
-
-\end_inset
-
-
-\layout Standard
-
-The compiler does
-\emph on
-local and global
-\emph default
-common subexpression elimination.
-\layout Standard
-
-
-\family typewriter
-\size scriptsize
-eg.
-
-\layout Standard
-
-
-\size small
-i = x + y + 1;
-\size default
-
-\newline
-j
-\size small
-= x + y;
-\layout Standard
-
-will be translated to
-\layout Standard
-
-
-\size small
-iTemp = x + y
-\newline
-i = iTemp + 1
-\newline
-j = iTemp
-\layout Standard
-
-Some subexpressions are not as obvious as the above example.
-\layout Standard
-
-eg.
-\layout Standard
-
-
-\size small
-a->b[i].c = 10;
-\newline
-a->b[i].d = 11;
-\layout Standard
-
-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
-
-
-\size small
-iTemp = a->b[i];
-\newline
-iTemp.c = 10;
-\newline
-iTemp.d = 11;
-\layout Standard
-
-The compiler will try to keep these temporary variables in registers.
-\layout Subsection
-
-Dead-Code elimination.
-\begin_inset LatexCommand \label{Dead-code elimination}
-
-\end_inset
-
-
-\layout Standard
-
-eg.
-\layout Standard
-
-
-\size small
-int global;
-\newline
-void f () {
-\newline
-
-\protected_separator
-
-\protected_separator
-int i;
-\newline
-
-\protected_separator
-
-\protected_separator
-i = 1;
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-/* dead store */
-\newline
-
-\protected_separator
-
-\protected_separator
-global = 1; /* dead store */
-\newline
-
-\protected_separator
-
-\protected_separator
-global = 2;
-\newline
-
-\protected_separator
-
-\protected_separator
-return;
-\newline
-
-\protected_separator
-
-\protected_separator
-global = 3; /* unreachable */
-\newline
-}
-\layout Standard
-
-will be changed to
-\layout Standard
-
-
-\size footnotesize
-int global; void f ()
-\newline
-{
-\protected_separator
-
-\protected_separator
-
-\newline
-
-\protected_separator
-global = 2;
-\protected_separator
-
-\protected_separator
-
-\newline
-
-\protected_separator
-return;
-\newline
-}
-\layout Subsection
-
-Copy-Propagation:
-\begin_inset LatexCommand \label{Copy-Propagation}
-
-\end_inset
-
-
-\layout Standard
-
-eg.
-\layout Standard
-
-
-\size footnotesize
-int f() {
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-int i, j;
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-i = 10;
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-j = i;
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-return j;
-\newline
-}
-\layout Standard
-
-will be changed to
-\layout Standard
-
-
-\size small
-int f() {
-\newline
-
-\protected_separator
-
-\protected_separator
- int i,j;
-\newline
-
-\protected_separator
-
-\protected_separator
- i = 10;
-\newline
-
-\protected_separator
-
-\protected_separator
- j = 10;
-\newline
-
-\protected_separator
-
-\protected_separator
- return 10;
-\newline
-}
-\layout Standard
-
-Note: the dead stores created by this copy propagation will be eliminated
- by dead-code elimination .
-\layout Subsection
-
-Loop optimizations
-\begin_inset LatexCommand \label{Loop Optimizations}
-
-\end_inset
-
-
-\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
- 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 Subsubsection
-
-Loop Invariant:
-\begin_inset LatexCommand \label{Loop Invariant}
-
-\end_inset
-
-
-\layout Standard
-
-eg
-\layout Standard
-
-
-\size small
-for (i = 0 ; i < 100 ; i ++)
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-f += k + l;
-\layout Standard
-
-changed to
-\layout Standard
-
-
-\size small
-itemp = k + l;
-\newline
-for ( i = 0; i < 100; i++ ) f += itemp;
-\layout Standard
-
-As mentioned previously some loop invariants are not as apparent, all static
- address computations are also moved out of the loop.
-\layout Subsubsection
-
-Strength reduction :
-\begin_inset LatexCommand \label{Strength Reduction}
-
-\end_inset
-
-
-\layout Standard
-
-This optimization substitutes an expression by a cheaper expression.
-\layout Standard
-
-eg.
-\layout Standard
-
-
-\size small
-for (i=0;i < 100; i++) ar[i*5] = i*3;
-\layout Standard
-
-changed to
-\layout Standard
-
-
-\size small
-itemp1 = 0;
-\newline
-itemp2 = 0;
-\newline
-for (i=0;i< 100;i++) {
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-ar[itemp1] = itemp2;
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-itemp1 += 5;
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-itemp2 += 3;
-\newline
-}
-\layout Standard
-
-The more expensive multiplication is changed to a less expensive addition.
-\layout Subsubsection
-
-Loop reversing:
-\begin_inset LatexCommand \label{Loop reversing}
-
-\end_inset
-
-
-\layout Standard
-
-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
-\begin_inset Quotes eld
-\end_inset
-
-decrement and jump if not zero
-\begin_inset Quotes erd
-\end_inset
-
- instruction.
- SDCC checks for the following criterion to determine if a loop is reversible
- (note: more sophisticated compiers use data-dependency analysis to make
- this determination, SDCC uses a more simple minded analysis).
-\layout Itemize
-
-The 'for' loop is of the form
-\newline
-
-\begin_inset Quotes eld
-\end_inset
-
-for ( <symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
- <sym> += 1])
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-<for body>
-\begin_inset Quotes erd
-\end_inset
-
-
-\layout Itemize
-
-The <for body> does not contain
-\begin_inset Quotes eld
-\end_inset
-
-continue
-\begin_inset Quotes erd
-\end_inset
-
- or 'break
-\begin_inset Quotes erd
-\end_inset
-
-.
-\layout Itemize
-
-All goto's are contained within the loop.
-\layout Itemize
-
-No function calls within the loop.
-\layout Itemize
-
-The loop control variable <sym> is not assigned any value within the loop
-\layout Itemize
-
-The loop control variable does NOT participate in any arithmetic operation
- within the loop.
-\layout Itemize
-
-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' or 'short',
- ofcourse this may not be possible on all situations.
-\layout Subsection
-
-Algebraic simplifications:
-\begin_inset LatexCommand \label{Algebraic Simplifications}
-
-\end_inset
-
-
-\layout Standard
-
-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
-i = j + 0 ; /* changed to */ i = j;
-\newline
-i /= 2; /* changed to */ i >>= 1;
-\newline
-i = j - j ; /* changed to */ i = 0;
-\newline
-i = j / 1 ; /* changed to */ i = j;
-\layout Standard
-
-Note the subexpressions given above are generally introduced by macro expansions
- or as a result of copy/constant propagation.
-\layout Subsection
-
-'switch' statements.
-\begin_inset LatexCommand \label{Switch Statement}
-
-\end_inset
-
-
-\layout Standard
-
-SDCC changes switch statements to jump tables when the following conditions
- are true.
-
-\layout Itemize
-
-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
-switch(i) {
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-switch (i) {
-\newline
-case 4:...
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-case 1: ...
-
-\newline
-case 5:...
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-case 2: ...
-
-\newline
-case 3:...
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-case 3: ...
-
-\newline
-case 6:...
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-case 4: ...
-
-\newline
-}
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-}
-\layout Standard
-
-Both the above switch statements will be implemented using a jump-table.
-\layout Itemize
-
-The number of case labels is at least three, since it takes two conditional
- statements to handle the boundary conditions.
-\layout Itemize
-
-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.
-
-\layout Standard
-
-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
-
-
-\size small
-switch (i) {
-\newline
-case 1: ...
-
-\newline
-case 2: ...
-
-\newline
-case 3: ...
-
-\newline
-case 4: ...
-
-\newline
-case 9: ...
-
-\newline
-case 10: ...
-
-\newline
-case 11: ...
-
-\newline
-case 12: ...
-
-\newline
-}
-\layout Standard
-
-If the above switch statement is broken down into two switch statements
-\layout Standard
-
-
-\size small
-switch (i) {
-\newline
-case 1: ...
-
-\newline
-case 2: ...
-
-\newline
-case 3: ...
-
-\newline
-case 4: ...
-
-\newline
-}
-\layout Standard
-
-
-\size small
-switch (i) {
-\newline
-case 9: ...
-
-\newline
-case 10: ...
-
-\newline
-case 11: ...
-
-\newline
-case 12:...
-
-\newline
-}
-\layout Standard
-
-then both the switch statements will be implemented using jump-tables whereas
- the unmodified switch statement will not be .
-\layout Subsection
-
-bit-shifting operations.
-\begin_inset LatexCommand \label{bit shifting}
-
-\end_inset
-
-
-\layout Standard
-
-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
-
-eg.
-\layout Standard
-
-
-\size small
-unsigned short i;
-\layout Standard
-
-
-\size small
-...
-
-\newline
-i>>= 4;
-\newline
-..
-\layout Standard
-
-generates the following code.
-\layout Standard
-
-
-\size small
-mov a,_i
-\newline
-swap a
-\newline
-anl a,#0x0f
-\newline
-mov _i,a
-\layout Standard
-
-In general SDCC will never setup a loop if the shift count is known.
- Another example
-\layout Standard
-
-
-\size small
-unsigned int i;
-\newline
-...
-
-\newline
-i >>= 9;
-\newline
-...
-\layout Standard
-
-will generate
-\layout Standard
-
-
-\size small
-mov a,(_i + 1)
-\newline
-mov (_i + 1),#0x00
-\newline
-clr c
-\newline
-rrc a
-\newline
-mov _i,a
-\layout Standard
-
-Note that SDCC stores numbers in
-\noun on
-little-endian
-\noun default
-format (i.e.
- lowest order first)
-\layout Subsubsection
-
-Bit-rotation:
-\begin_inset LatexCommand \label{bit rotation}
-
-\end_inset
-
-
-\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
-
-
-\size small
-unsigned char i;
-\newline
-...
-
-\newline
-i = ( ( i << 1) | ( i >> 7));
-\newline
-...
-\layout Standard
-
-will generate the following code.
-\layout Standard
-
-
-\size small
-mov a,_i
-\newline
-rl a
-\newline
-mov _i,a
-\layout Standard
-
-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
-\emph on
- i = ((i >> 7) | (i << 1));
-\emph default
-/* left-bit rotation */
-\layout Subsection
-
-Highest Order Bit.
-\begin_inset LatexCommand \label{Highest Order Bit}
-
-\end_inset
-
-
-\layout Standard
-
-It is frequently required to obtain the highest order bit of an integral
- type (int,long,short or char types).
- SDCC recognizes the following expression to yield the highest order bit
- and generates optimized code for it.
-\layout Standard
-
-
-\size small
-eg
-\newline
-unsigned int gint;
-\newline
-foo () {
-\newline
-unsigned char hob;
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-...
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-hob = (gint >> 15) & 1;
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-..
-
-\newline
-}
-\layout Standard
-
-Will generate the following code.
-\layout Standard
-
-
-\size small
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- 61 ;
-\protected_separator
- hob.c 7
-\newline
-
-\protected_separator
-
-\protected_separator
- 000A E5*01
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- 62
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- a,(_gint + 1)
-\newline
-
-\protected_separator
-
-\protected_separator
- 000C 33
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- 63
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- rlc
-\protected_separator
- a
-\newline
-
-\protected_separator
-
-\protected_separator
- 000D E4
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- 64
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- clr
-\protected_separator
- a
-\newline
-
-\protected_separator
-
-\protected_separator
- 000E 13
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- 65
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- rrc
-\protected_separator
- a
-\newline
-
-\protected_separator
-
-\protected_separator
- 000F F5*02
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- 66
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- _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
-
-
-\size small
-eg.
-\layout Standard
-
-
-\size small
-xyz = gint + ((gint >> 15) & 1);
-\layout Standard
-
-will still be recognized.
-\layout Subsection
-
-Peep-hole optimizer.
-\begin_inset LatexCommand \label{Peep-Hole}
-
-\end_inset
-
-
-\layout Standard
-
-The compiler uses a rule based , pattern matching and re-writing mechanism
- for peep-hole optimization .
- It is inspired by '
-\emph on
-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.
- The rule language is best illustrated with examples.
-\layout Standard
-
-
-\size small
-replace {
-\newline
-mov %1,a
-\newline
-mov a,%1 } by { mov %1,a }
-\layout Standard
-
-The above rule will the following assembly sequence
-\layout Standard
-
-
-\size small
-mov r1,a
-\newline
-mov a,r1
-\layout Standard
-
-to
-\layout Standard
-
-
-\size small
-mov r1,a
-\layout Standard
-
-Note: All occurrences of a '%n' ( pattern variable ) must denote the same
- string.
- With the above rule, the assembly sequence
-\layout Standard
-
-
-\size small
-mov r1,a
-\newline
-mov a,r2
-\layout Standard
-
-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
-
-
-\size small
-replace { lcall %1 } by { acall %1 }
-\newline
-replace { ljmp %1 } by { ajmp %1 }
-\layout Standard
-
-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-structur
-e is MCU independent.
- Peephole optimization rules for other MCU can be easily programmed using
- the rule language.
-\layout Standard
-
-The syntax for a rule is as follows ,
-\layout Standard
-
-
-\size small
-rule := replace [ restart ] '{' <assembly sequence> '
-\backslash
-n'
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- '}' by '{' '
-\backslash
-n'
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- <assembly sequence> '
-\backslash
-n'
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- '}' [if <functionName> ] '
-\backslash
-n'
-\newline
-<assembly sequence> := assembly instruction (each instruction including
- labels must be on a separate line).
-\protected_separator
-
-\protected_separator
-
-\layout Standard
-
-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
- the same rule again.
- A good example of this the following rule.
-\layout Standard
-
-
-\size small
-replace restart {
-\newline
-pop %1
-\newline
-push %1 } by {
-\newline
-; nop
-\newline
-}
-\layout Standard
-
-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
-
-
-\size small
-pop ar1
-\newline
-pop ar2
-\newline
-push ar2
-\newline
-push ar1
-\layout Standard
-
-would result in
-\layout Standard
-
-
-\size small
-pop ar1
-\newline
-; nop
-\newline
-push ar1
-\layout Standard
-
-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'
-\emph default
- pairs will be eliminated to yield
-\layout Standard
-
-
-\size small
-; nop
-\newline
-; nop
-\layout Standard
-
-A conditional function can be attached to a rule.
- Attaching rules are somewhat more involved, let me illustrate this with
- an example.
-\layout Standard
-
-
-\size small
-replace {
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-ljmp %5
-\newline
-%2:} by {
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-sjmp %5
-\newline
-%2:} if labelInRange
-\layout Standard
-
-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
-\emph default
- , with the name
-\emph on
-'labelInRange
-\emph default
-', 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
-\emph default
-' 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 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
-\emph on
---peep-file
-\emph default
- option.
-\layout Section
-
-Pointers
-\begin_inset LatexCommand \label{Pointers}
-
-\end_inset
-
-
-\layout Standard
-
-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
-\emph on
-_generic
-\emph default
- class of pointers which can be used to point to any of the memory spaces.
-
-\layout Standard
-
-Pointer declaration examples.
-\layout Standard
-
-
-\size small
-/* pointer physically in xternal ram pointing to object in internal ram
- */
-\newline
-data unsigned char * xdata p;
-\newline
-
-\layout Standard
-
-
-\size small
-/* pointer physically in code rom pointing to data in xdata space */
-\newline
-xdata unsigned char * code p;
-\newline
-
-\layout Standard
-
-
-\size small
-/* pointer physically in code space pointing to data in code space */
-\newline
-code unsigned char * code p;
-\newline
-
-\newline
-/* the folowing is a generic pointer physically located in xdata space */
-\newline
-char * xdata p;
-\layout Standard
-
-Well you get the idea.
- For compatibility with the previous version of the compiler, the following
- syntax for pointer declaration is also supported.
- Note the above examples will be portable to other commercially available
- compilers.
-\layout Standard
-
-
-\size small
-unsigned char _xdata *ucxdp; /* pointer to data in external ram */
-\newline
-unsigned char _data
-\protected_separator
-*ucdp ; /* pointer to data in internal ram */
-\newline
-unsigned char _code
-\protected_separator
-*uccp ; /* pointer to data in R/O code space */
-\newline
-unsigned char _idata *uccp;
-\protected_separator
-/* pointer to upper 128 bytes of ram */
-\layout Standard
-
-All unqualified pointers are treated as 3 - byte '_generic' pointers.
- These type of pointers can also to be explicitly declared.
-\layout Standard
-
-
-\size small
-unsigned char _generic *ucgp;
-\layout Standard
-
-The highest order byte of the generic pointers contains the data space informati
-on.
- 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.
-\layout Section
-
-Parameters & Local Variables
-\begin_inset LatexCommand \label{Auto Variables}
-
-\end_inset
-
-
-\layout Standard
-
-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
-\emph on
- --stack-auto
-\emph default
- compiler option or by using the 'reentrant' keyword in the function declaration.
-\layout Standard
-
-
-\family typewriter
-\size scriptsize
-eg
-\layout Standard
-
-
-\size small
-unsigned short foo( short i) reentrant {
-\newline
-...
-
-\newline
-}
-\layout Standard
-
-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
-\emph on
-'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
-
-When compiled with the default option (i.e.
- non-reentrant ), local variables can be assigned storage classes and absolute
- addresses.
-
-\layout Standard
-
-
-\family typewriter
-\size scriptsize
-eg
-\layout Standard
-
-
-\size small
-unsigned short foo() {
-\newline
-
-\protected_separator
-
-\protected_separator
-xdata unsigned short i;
-\newline
-
-\protected_separator
-
-\protected_separator
-bit bvar;
-\newline
-
-\protected_separator
-
-\protected_separator
-data at 0x31 unsiged short j;
-\newline
-...
-
-\newline
-}
-\layout Standard
-
-In the above example the variable
-\emph on
-i
-\emph default
- will be allocated in the external ram,
-\emph on
-bvar
-\emph default
- in bit addressable space and
-\emph on
- j
-\emph default
- in internal ram.
- When compiled with the
-\emph on
---stack-auto
-\emph default
- or when a function is declared as
-\emph on
-'reentrant'
-\emph default
- local variables cannot be assigned storage classes or absolute addresses.
-\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.
-\layout Subsection
-
-Overlaying
-\begin_inset LatexCommand \label{Overlaying}
-
-\end_inset
-
-
-\layout Standard
-
-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 overlayabl
-e segment if the function has
-\emph on
-no other function calls and the function is non-reentrant and the memory
- model is small.
-
-\emph default
- If an explicit storage class is specified for a local variable , it will
- NOT be overplayed.
-\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.
-\layout Standard
-
-Parameters and Local variables of functions that contain 16 or 32 bit multiplica
-tion or division will NOT be overlayed since these are implemented using
- external functions.
-\layout Standard
-
-eg.
-\layout Standard
-
-
-\size small
-#pragma SAVE
-\newline
-#pragma NOOVERLAY
-\newline
-void set_error( unsigned short errcd)
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
- P3 = errcd;
-\newline
-}
-\newline
-#pragma RESTORE
-\newline
-void some_isr () interrupt 2 using 1
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
- ...
-
-\newline
-
-\protected_separator
-
-\protected_separator
- set_error(10);
-\newline
-
-\protected_separator
-
-\protected_separator
- ...
-
-\newline
-}
-\layout Standard
-
-In the above example the parameter
-\emph on
-errcd
-\emph default
- for the function
-\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.
- The pragma NOOVERLAY ensures that the parameters and local variables for
- the function are NOT overlayed.
-\layout Section
-
-critical Functions.
-\begin_inset LatexCommand \label{Critical}
-
-\end_inset
-
-
-\layout Standard
-
-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.
-\layout Standard
-
-eg
-\layout Standard
-
-
-\size small
-int foo () critical
-\newline
-{
-\newline
-...
-
-\newline
-...
-
-\newline
-}
-\layout Standard
-
-The critical attribute maybe used with other attributes like
-\emph on
-reentrant.
-\layout Section
-
-Absolute addressing.
-\begin_inset LatexCommand \label{Absolute Addressing}
-
-\end_inset
-
-
-\layout Standard
-
-Data items can be assigned an absolute address with the
-\emph on
-at <address>
-\emph default
- keyword, in addition to a storage class.
-\layout Standard
-
-eg.
-
-\layout Standard
-
-
-\size small
-xdata at 0x8000 unsigned char PORTA_8255 ;
-\layout Standard
-
-In the above example the
-\emph on
-PORTA_8255
-\emph default
- will be allocated to the location 0x8000 of the external ram.
-
-\layout Standard
-
-Note that is 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.
-\layout Standard
-
-Absolute address can be specified for variables in all storage classes.
-\layout Standard
-
-
-\size small
-eg.
-\layout Standard
-
-
-\size small
-bit at 0x02 bvar;
-\layout Standard
-
-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.
-\layout Section
-
-Interrupt Service Routines
-\begin_inset LatexCommand \label{Interrupt Service Rouines}
-
-\end_inset
-
-
-\layout Standard
-
-SDCC allows interrupt service routines to be coded in C, with some extended
- keywords.
-\layout Standard
-
-
-\size small
-void timer_isr (void) interrupt 2 using 1
-\newline
-{
-\newline
-..
-
-\newline
-}
-\layout Standard
-
-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, 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.
-\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
-\emph on
-'main'
-\emph default
-.
-\layout Standard
-
-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.
-\layout Standard
-
-Interrupt #
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-Description
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-Vector Address
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-0
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-External 0
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-0x0003
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-1
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-Timer 0
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-0x000B
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-2
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-External 1
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-0x0013
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-3
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-Timer 1
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-0x001B
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-4
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-Serial
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-0x0023
-\layout Standard
-
-If the interrupt service routine is defined without a register bank or with
- register bank 0 (using 0), the compiler will save the registers used by
- itself on the stack (upon entry and restore them at exit), however if such
- an interrupt service routine calls another function then the entire register
- bank will be saved on the stack.
- This scheme may be advantageous for small interrupt service routines which
- have low register usage.
-\layout Standard
-
-If the interrupt service routine is defined to be using a specific register
- bank then only
-\begin_inset Quotes eld
-\end_inset
-
-a
-\begin_inset Quotes erd
-\end_inset
-
-,
-\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 Section
-
-Startup Code
-\begin_inset LatexCommand \label{Startup}
-
-\end_inset
-
-
-\layout Standard
-
-The compiler inserts a jump to the C routine
-\series bold
-_sdcc__external__startup()
-\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.
-\layout Section
-
-Inline assembler code.
-\begin_inset LatexCommand \label{Inline}
-
-\end_inset
-
-
-\layout Standard
-
-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
-\emph on
-form nnnnn$
-\emph default
- where nnnn is a number less than 100 (which implies a limit of utmost 100
- inline assembler labels
-\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
-\bar under
---peep-asm
-\series default
-\bar 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' carefully before using this option.
-\layout Standard
-
-
-\size small
-eg
-\layout Standard
-
-
-\size small
-_asm
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-mov b,#10
-\newline
-00001$:
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-djnz b,00001$
-\newline
-_endasm ;
-\layout Standard
-
-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
-\emph on
-_asm ...
- _endasm;
-\emph default
- keyword pair.
-
-\layout Standard
-
-Inline assembler code cannot reference any C-Labels however it can reference
- labels defined by the inline assembler.
-\layout Standard
-
-
-\size small
-eg
-\layout Standard
-
-
-\size small
-foo() {
-\newline
-...
- /* some c code */
-\newline
-_asm
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-; some assembler code
-\newline
-
-\protected_separator
-
-\protected_separator
- ljmp $0003
-\newline
-_endasm ;
-\newline
-...
- /* some more c code */
-\newline
-clabel:
-\protected_separator
- /* inline assembler cannot reference this label */
-\newline
-_asm
-\newline
-
-\protected_separator
-
-\protected_separator
-$0003: ;label (can be reference by inline assembler only)
-\newline
-_endasm ;
-\newline
-...
-
-\newline
-}
-\layout Standard
-
-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.
-\layout Section
-
-int (16 bit) and long (32 bit ) support.
-\begin_inset LatexCommand \label{int and long}
-
-\end_inset
-
-
-\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.
- The following files contain the described routine, all of them can be found
- in the directory SDCCDIR/sdcc51lib
-\layout Itemize
-
-
-\size footnotesize
-_mulsint.c - signed 16 bit multiplication (calls _muluint)
-\layout Itemize
-
-
-\size footnotesize
-_muluint.c - unsigned 16 bit multiplication
-\layout Itemize
-
-
-\size footnotesize
-_divsint.c - signed 16 bit division (calls _divuint)
-\layout Itemize
-
-
-\size footnotesize
-_divuint.c - unsigned 16 bit division.
-\layout Itemize
-
-
-\size footnotesize
-_modsint.c - signed 16 bit modulus (call _moduint)
-\layout Itemize
-
-
-\size footnotesize
-_moduint.c - unsigned 16 bit modulus.
-\layout Itemize
-
-
-\size footnotesize
-_mulslong.c - signed 32 bit multiplication (calls _mululong)
-\layout Itemize
-
-
-\size footnotesize
-_mululong.c - unsigned32 bit multiplication.
-\layout Itemize
-
-
-\size footnotesize
-_divslong.c - signed 32 division (calls _divulong)
-\layout Itemize
-
-
-\size footnotesize
-_divulong.c - unsigned 32 division.
-\layout Itemize
-
-
-\size footnotesize
-_modslong.c - signed 32 bit modulus (calls _modulong).
-\layout Itemize
-
-
-\size footnotesize
-_modulong.c - unsigned 32 bit modulus.
-\layout Standard
-
-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.
-\layout Section
-
-Floating point support
-\begin_inset LatexCommand \label{Float}
-
-\end_inset
-
-
-\layout Standard
-
-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
-
-
-\size footnotesize
-_fsadd.c - add floating point numbers.
-\layout Itemize
-
-
-\size footnotesize
-_fssub.c - subtract floating point numbers
-\layout Itemize
-
-
-\size footnotesize
-_fsdiv.c - divide floating point numbers
-\layout Itemize
-
-
-\size footnotesize
-_fsmul.c - multiply floating point numbers
-\layout Itemize
-
-
-\size footnotesize
-_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
-_uchar2fs.c - convert unsigned char to floating point
-\layout Itemize
-
-
-\size footnotesize
-_char2fs.c - convert char to floating point number
-\layout Itemize
-
-
-\size footnotesize
-_uint2fs.c - convert unsigned int to floating point
-\layout Itemize
-
-
-\size footnotesize
-_int2fs.c - convert int to floating point numbers
-\layout Itemize
-
-
-\size footnotesize
-_ulong2fs.c - convert unsigned long to floating point number
-\layout Itemize
-
-
-\size footnotesize
-_long2fs.c - convert long to floating point number.
-\layout Standard
-
-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)
-\layout Section
-
-Memory Models
-\begin_inset LatexCommand \label{Memory Models}
-
-\end_inset
-
-
-\layout Standard
-
-SDCC allows two memory models for MCS51 code.
- Modules compiled with different memory models should be combined together,
- the results would be unpredictable.
- The support routines supplied with the compiler are compiled in small-model
- by default, and will need to be recompiled using the large model if the
- large model is used.
- In general the use of the large model is discouraged.
-\layout Standard
-
-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.
-\layout Standard
-
-Judicious usage of the processor specific storage classes and the 'reentrant'
- function type will yield much more efficient code, than using the large-model.
- Several optimizations are disabled when the program is compiled using the
- large model, it is therefore strongly recommdended that the small model
- be used unless absolutely required.
-\layout Section
-
-Flat 24 bit addressing model.
-\begin_inset LatexCommand \label{--model-flat24}
-
-\end_inset
-
-
-\layout Standard
-
-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.
-\layout Standard
-
-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-f
-lat24 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.
-\layout Standard
-
-Note that the compiler does not generate any code to place the processor
- into24 bitmode (it defaults to 8051 compatible mode).
- Boot loader or similar code must ensure that the processor is in 24 bit
- contiguous addressing mode before calling the SDCC startup code.
-\layout Standard
-
-Like the --model-large option, variables will by default be placed into
- the XDATA segment.
-
-\layout Standard
-
-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.
-\layout Standard
-
---stack-10bit:
-\layout Standard
-
-This option generates code for the 10 bit stack mode of the Dallas DS80C390
- part.
- In this mode, the stack is located in the lower 1K of the internal RAM,
- which is mapped to 0x400000.
-\layout Standard
-
-With this option, sdcc will generate the proper addressing for stack variables.
-\layout Standard
-
-Note that the support is incomplete, since it still uses a single byte as
- the stack pointer.
- This means that only the lower 256 bytes of the potential 1K stack space
- can actually be used.
- However, this does allow you to reclaim the precious 256 bytes of low RAM
- for use for the DATA and IDATA segments.
-\layout Standard
-
-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.
-\layout Standard
-
-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).
-\layout Section
-
-Defines created by the compiler.
-\begin_inset LatexCommand \label{Defines.}
-
-\end_inset
-
-
-\layout Standard
-
-The compiler creates the following #defines .
-\layout Itemize
-
-SDCC - this Symbol is always defined.
-\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.
-\layout Itemize
-
-SDCC_MODEL_LARGE - when --model-large is used.
-\layout Itemize
-
-SDCC_USE_XSTACK - when --xstack option is used.
-\layout Section
-
-Pragmas
-\begin_inset LatexCommand \label{Pragmaa}
-
-\end_inset
-
-
-\layout Standard
-
-SDCC supports the following
-\emph on
-#pragma
-\emph default
-directives.
- This directives are applicable only at a function level.
-\layout Itemize
-
-
-\series bold
-SAVE
-\series default
-
-\begin_inset LatexCommand \label{pragma save}
-
-\end_inset
-
- - this will save all the current options .
-\layout Itemize
-
-
-\series bold
-RESTORE
-\series default
-
-\begin_inset LatexCommand \label{pragma restore}
-
-\end_inset
-
-- 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
-
-\begin_inset LatexCommand \label{pragma nogcse}
-
-\end_inset
-
- - will stop global subexpression elimination.
-\layout Itemize
-
-
-\series bold
-NOINDUCTION
-\series default
-
-\begin_inset LatexCommand \label{pragma noinduction}
-
-\end_inset
-
-- will stop loop induction optimizations .
-\layout Itemize
-
-
-\series bold
-NOJTBOUND
-\series default
-
-\begin_inset LatexCommand \label{pragma nojtbound}
-
-\end_inset
-
-- will not generate code for boundary value checking , when switch statements
- are turned into jump-tables.
-\layout Itemize
-
-
-\series bold
-NOOVERLAY
-\series default
-
-\begin_inset LatexCommand \label{pragma nooverlay}
-
-\end_inset
-
-- the compiler will not overlay the parameters and local variables of a
- function.
-\layout Itemize
-
-
-\series bold
-NOLOOPREVERSE
-\series default
-
-\begin_inset LatexCommand \label{pragma noloopreverse}
-
-\end_inset
-
-- Will not do loop reversal optimization
-\layout Itemize
-
-
-\series bold
-EXCLUDE NONE | {acc[,b[,dpl[,dph]]]
-\series default
-
-\begin_inset LatexCommand \label{pragma exclude}
-
-\end_inset
-
- - 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
-
-
-\layout Itemize
-
-
-\series bold
-CALLEE-SAVES function1[,function2[,function3...]]
-\series default
-
-\begin_inset LatexCommand \label{pragma callee-saves}
-
-\end_inset
-
- - 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
-\begin_inset LatexCommand \ref{--callee-saves}
-
-\end_inset
-
- command line option is used, the function names specified in #pragma CALLEE-SAV
-ES 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
- 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
-\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.
-\layout Standard
-
-
-\size scriptsize
-eg
-\layout Standard
-
-
-\size scriptsize
-#pragma SAVE
-\protected_separator
- /* save the current settings */
-\newline
-#pragma NOGCSE /* turnoff global subexpression elimination */
-\newline
-#pragma NOINDUCTION /* turn off induction optimizations */
-\newline
-int foo ()
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
- ...
-
-\newline
-
-\protected_separator
-
-\protected_separator
- /* large code */
-\newline
-
-\protected_separator
-
-\protected_separator
- ...
-
-\newline
-}
-\newline
-#pragma RESTORE /* turn the optimizations back on */
-\layout Standard
-
-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.
-\layout Section
-
-Library routines.
-\begin_inset LatexCommand \label{Library}
-
-\end_inset
-
-
-\layout Standard
-
-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>.
-
-\layout Standard
-
-
-\size scriptsize
-%[flags][width][b|B|l|L]type
-\layout Standard
-
-
-\size scriptsize
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- flags: -
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- left justify output in specified field width
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- +
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- prefix output with +/- sign if output is signed type
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- space
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- prefix output with a blank if it's a signed positive value
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- width:
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- specifies minimum number of characters outputted for numbers
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- or strings.
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- - For numbers, spaces are added on the left when needed.
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- If width starts with a zero character, zeroes and used
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- instead of spaces.
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- - For strings, spaces are are added on the left or right (when
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- flag '-' is used) when needed.
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- b/B:
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- byte argument (used by d, u, o, x, X)
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- l/L:
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- long argument (used by d, u, o, x, X)
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- type:
-\protected_separator
- d
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- decimal number
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- u
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- unsigned decimal number
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- o
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- unsigned octal number
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- x
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- unsigned hexadecimal number (0-9, a-f)
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- X
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- unsigned hexadecimal number (0-9, A-F)
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- c
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- character
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- s
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- string (generic pointer)
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- p
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- generic pointer (I:data/idata, C:code, X:xdata, P:paged)
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- f
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- float (still to be implemented)
-\layout Standard
-
-Also contains a very simple version of printf (
-\series bold
-printf_small
-\series default
-).
- This simplified version of printf supports only the following formats.
-\layout Standard
-
-
-\size scriptsize
-\bar under
-format
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-output
-\protected_separator
-type
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-argument-type
-\bar default
-
-\series bold
-\size default
-
-\newline
-
-\series default
-\size scriptsize
-%d
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-decimal
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- int
-\newline
-%ld
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-decimal
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-long
-\newline
-%hd
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-decimal
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-short/char
-\newline
-%x
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-hexadecimal
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-int
-\newline
-%lx
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-hexadecimal
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-long
-\newline
-%hx
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-hexadecimal
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-short/char
-\newline
-%o
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-octal
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-int
-\newline
-%lo
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-octal
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-long
-\newline
-%ho
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-octal
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-short/char
-\newline
-%c
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-character
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-char/short
-\newline
-%s
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-character
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-_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).
- 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
-
-my str %s, my int %d
-\backslash
-n
-\begin_inset Quotes erd
-\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'
-\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.
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-stdlib.h
-\series default
-\size default
- - 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.
-\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.
-\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.
- 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
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- #define DYNAMIC_MEMORY_SIZE 0x2000
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .....
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- unsigned char xdata * current_buffer;
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .....
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- void main(void)
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- {
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- ...
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-//
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //Now it's possible to use malloc.
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- ...
-
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- current_buffer = malloc(0x100);
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- //
-\end_deeper
-\layout Itemize
-
-
-\series bold
-\size large
-serial.h
-\series default
-\size default
- - 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
-\begin_inset Quotes eld
-\end_inset
-
-serial.h
-\begin_inset Quotes erd
-\end_inset
-
- 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.
- 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.
-\layout Itemize
-
-
-\series bold
-\size large
-reg51.h
-\series default
-\size default
- - contains register definitions for a standard 8051
-\layout Itemize
-
-
-\series bold
-\size large
-reg552.h
-\series default
-\size default
-- contains register definitions for 80C552.
-\layout Itemize
-
-
-\series bold
-\size large
-float.h
-\series default
-\size default
- - contains min, max and other floating point related stuff.
-\layout Standard
-
-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
-
-Have not had time to do the more involved routines like printf, will get
- to them shortly.
-\layout Section
-
-Interfacing with assembly routines.
-\begin_inset LatexCommand \label{Interface_asm}
-
-\end_inset
-
-
-\layout Subsection
-
-Global registers used for parameter passing.
-\layout Standard
-
-By default the compiler uses the global registers
-\begin_inset Quotes eld
-\end_inset
-
-DPL,DPH,B,ACC
-\begin_inset Quotes erd
-\end_inset
-
- 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).
-
-\layout Subsubsection
-
-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.
-\layout Standard
-
-
-\size footnotesize
-extern int asm_func( unsigned short, unsigned short);
-\layout Standard
-
-
-\size footnotesize
-
-\protected_separator
-
-\newline
-int c_func (unsigned short i, unsigned short j)
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- return asm_func(i,j);
-\newline
-}
-\size default
-
-\size scriptsize
-
-\newline
-int main()
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-return c_func(10,9);
-\newline
-}
-\layout Standard
-
-The corresponding assembler function is:-
-\layout Standard
-
-
-\size scriptsize
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .globl _asm_func_PARM_2
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .globl _asm_func
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .area OSEG
-\newline
-_asm_func_PARM_2:
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .ds
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- 1
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .area CSEG
-\newline
-_asm_func:
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- a,dpl
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- add
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- a,_asm_func_PARM_2
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- dpl,a
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- dpl,#0x00
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- ret
-\layout Standard
-
-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.
-\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 first parameter is passed in
-\begin_inset Quotes eld
-\end_inset
-
-dpl
-\begin_inset Quotes erd
-\end_inset
-
- for One bye parameter,
-\begin_inset Quotes eld
-\end_inset
-
-dptr
-\begin_inset Quotes erd
-\end_inset
-
- if two bytes,
-\begin_inset Quotes eld
-\end_inset
-
-b,dptr
-\begin_inset Quotes erd
-\end_inset
-
- for three bytes and
-\begin_inset Quotes eld
-\end_inset
-
-acc,b,dptr
-\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.
-\layout Standard
-
-Assemble the assembler routine with the following command.
-\layout Standard
-
-asx8051 -losg asmfunc.asm
-\layout Standard
-
-Then compile and link the assembler routine to the C source file with the
- following command,
-\layout Standard
-
-sdcc cfunc.c asmfunc.rel
-\layout Subsubsection
-
-Assembler routine is 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.
- 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 short, unsigned short);
-\layout Standard
-
-
-\size footnotesize
-
-\protected_separator
-
-\layout Standard
-
-
-\size footnotesize
-int c_func (unsigned short i, unsigned short j) reentrant
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- return asm_func(i,j);
-\newline
-}
-\size default
-
-\size scriptsize
-
-\newline
-int main()
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-return c_func(10,9);
-\newline
-}
-\layout Standard
-
-The corresponding assembler routine is.
-\layout Standard
-
-
-\size scriptsize
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .globl _asm_func
-\newline
-_asm_func:
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- push
-\protected_separator
- _bp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- _bp,sp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-mov
-\protected_separator
- r2,dpl
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- a,_bp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- clr
-\protected_separator
- c
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- add
-\protected_separator
- a,#0xfd
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- r0,a
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- add
-\protected_separator
- a,#0xfc
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- r1,a
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- a,@r0
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- add
-\protected_separator
- a,r2
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- dpl,a
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- dph,#0x00
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- sp,_bp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- pop
-\protected_separator
- _bp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- ret
-\layout Standard
-
-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.
-\layout Subsection
-
-With --noregparms option.
-\layout Standard
-
-When the source is compiled with --noregparms option , space is allocated
- for each of the parameters passed to a routine.
-\layout Subsubsection
-
-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.
-\layout Standard
-
-
-\size footnotesize
-extern int asm_func( unsigned short, unsigned short);
-\layout Standard
-
-
-\size footnotesize
-
-\protected_separator
-
-\newline
-int c_func (unsigned short i, unsigned short j)
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- return asm_func(i,j);
-\newline
-}
-\size default
-
-\size scriptsize
-
-\newline
-int main()
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-return c_func(10,9);
-\newline
-}
-\layout Standard
-
-The corresponding assembler function is:-
-\layout Standard
-
-
-\size scriptsize
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .globl _asm_func_PARM_1
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .globl _asm_func_PARM_2
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .globl _asm_func
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .area OSEG
-\newline
-_asm_func_PARM_1:
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .ds
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- 1
-\newline
-_asm_func_PARM_2:
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .ds
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- 1
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .area CSEG
-\newline
-_asm_func:
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- a,_asm_func_PARM_1
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- add
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- a,_asm_func_PARM_2
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- dpl,a
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- dpl,#0x00
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- ret
-\layout Standard
-
-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.
-\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.
- i.e.
- the
-\family typewriter
-\series bold
-\size footnotesize
-left-most parameter name will be _<function_name>_PARM_1.
-\layout Standard
-
-Assemble the assembler routine with the following command.
-\layout Standard
-
-asx8051 -losg asmfunc.asm
-\layout Standard
-
-Then compile and link the assembler routine to the C source file with the
- following command,
-\layout Standard
-
-sdcc cfunc.c asmfunc.rel
-\layout Subsubsection
-
-Assembler routine is reentrant.
-\layout Standard
-
-In this case the parameters will be passed on the stack , the parameters
- are pushed from right to left i.e.
- after the call the left most parameter will be on the top of the stack.
- Here is an example.
-\layout Standard
-
-
-\size footnotesize
-extern int asm_func( unsigned short, unsigned short);
-\layout Standard
-
-
-\size footnotesize
-
-\protected_separator
-
-\layout Standard
-
-
-\size footnotesize
-int c_func (unsigned short i, unsigned short j) reentrant
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- return asm_func(i,j);
-\newline
-}
+\series bold
+\size large
+\bar under
+-E
+\series default
\size default
-
-\size scriptsize
-
-\newline
-int main()
-\newline
-{
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-return c_func(10,9);
-\newline
-}
-\layout Standard
-
-The corresponding assembler routine is.
-\layout Standard
-
-
-\size scriptsize
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- .globl _asm_func
-\newline
-_asm_func:
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- push
-\protected_separator
- _bp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- _bp,sp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- a,_bp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- clr
-\protected_separator
- c
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- add
-\protected_separator
- a,#0xfd
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- r0,a
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- a,_bp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- clr
-\protected_separator
- c
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- add
-\protected_separator
- a,#0xfc
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- r1,a
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- a,@r0
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- add
-\protected_separator
- a,@r1
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- dpl,a
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- dph,#0x00
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- mov
-\protected_separator
- sp,_bp
-\newline
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
- pop
-\protected_separator
- _bp
-\newline
-
-\protected_separator
+\bar default
+ Run only the C preprocessor.
+ Preprocess all the C source files specified and output the results to standard
+ output.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\protected_separator
+\series bold
+\size large
+\bar under
+-M
+\series default
+\size default
+\bar default
+ 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 `
+\backslash
+'-newline if it is long.
+ The list of rules is printed on standard output instead of the preprocessed
+ C program.
+ `-M' implies `-E'.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\protected_separator
+\series bold
+\size large
+\bar under
+-C
+\series default
+\size default
+\bar default
+ Tell the preprocessor not to discard comments.
+ Used with the `-E' option.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\protected_separator
- ret
-\layout Standard
+\series bold
+\size large
+\bar under
+-MM
+\series default
+\size default
+\bar default
+Like `-M' but the output mentions only the user header files included with
+ `#include file"'.
+ System header files included with `#include <file>' are omitted.
+\layout List
+\labelwidthstring 00.00.0000
-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.
-\layout Section
-External Stack.
-\begin_inset LatexCommand \label{xstack}
+\series bold
+\size large
+\bar under
+-Aquestion(answer)
+\series default
+\size default
+\bar default
+ 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.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+\size large
+\bar under
+-Aquestion
+\series default
+\size default
+\bar default
+ (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.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-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).
-\layout Standard
+\series bold
+\size large
+\bar under
+-Umacro
+\series default
+\size default
+\bar default
+ Undefine macro macro.
+ `-U' options are evaluated after all `-D' options, but before any `-include'
+ and `-imacros' options.
+\layout List
+\labelwidthstring 00.00.0000
-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.
-\layout Section
-ANSI-Compliance.
-\begin_inset LatexCommand \label{ANSI_Compliance}
+\series bold
+\size large
+\bar under
+-dM
+\series default
+\size default
+\bar default
+ 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.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+\size large
+\bar under
+-dD
+\series default
+\size default
+\bar default
+ Tell the preprocessor to pass all macro definitions into the output, in
+ their proper sequence in the rest of the output.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-Deviations from the compliancy.
-\layout Enumerate
+\series bold
+\size large
+\bar under
+-dN
+\series default
+\size default
+\bar default
+Like `-dD' except that the macro arguments and contents are omitted.
+ Only `#define name' is included in the output.
+\layout List
+\labelwidthstring 00.00.0000
-functions are not always reentrant.
-\layout Enumerate
-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.
-\begin_deeper
-\layout Standard
+\series bold
+\size large
+\bar under
+-S
+\series default
+\size default
+\bar default
+Stop after the stage of compilation proper; do not as- semble.
+ The output is an assembler code file for the input file specified.
+\layout List
+\labelwidthstring 00.00.0000
-\size small
-eg
-\end_deeper
-\layout Standard
+\series bold
+\bar under
+-Wa_asmOption[,asmOption]
+\series default
+\bar default
+...
+ Pass the asmOption to the assembler.
+\layout List
+\labelwidthstring 00.00.0000
-\size small
-struct s { ...
- };
-\newline
-struct s s1, s2;
-\newline
-foo()
-\newline
-{
-\newline
-...
-
-\newline
-s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
-\newline
-...
-
-\newline
-}
-\layout Standard
+\series bold
+\bar under
+-Wl_linkOption[,linkOption]
+\series default
+\bar default
+ ..
+ Pass the linkOption to the linker.
+\layout List
+\labelwidthstring 00.00.0000
-\size small
-struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
- ANSI */
-\newline
-{
-\newline
-struct s rets;
-\newline
-...
+\series bold
+\size large
+\bar under
+--int-long-reent
+\series default
+\bar default
-\newline
-return rets;/* is invalid in SDCC although allowed in ANSI */
-\newline
-}
-\layout Enumerate
-
-'long long' (64 bit integers) not supported.
-\layout Enumerate
+\size default
+ 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.
+\layout List
+\labelwidthstring 00.00.0000
-'double' precision floating point not supported.
-\layout Enumerate
-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.
+\series bold
+\size large
+\bar under
+--cyclomatic
+\size default
-\layout Enumerate
-
-No support for
+\series default
+\bar default
+This option will cause the compiler to generate an information message for
+ each function in the source file.
+ The message contains some
\emph on
-setjmp
+important
\emph default
- and
+ 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
\emph on
-longjmp
+cyclomatic complexity
\emph default
- (for now).
-\layout Enumerate
-
-Old K&R style function declarations are NOT allowed.
-\layout Standard
+ see section on Cyclomatic Complexity for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\size footnotesize
-foo( i,j) /* this old style of function declarations */
-\newline
-int i,j; /* are valid in ANSI ..
- not valid in SDCC */
-\newline
-{
-\newline
-...
+\series bold
+\size large
+\bar under
+--float-reent
+\size default
-\newline
-}
-\layout Enumerate
-
-functions declared as pointers must be dereferenced during the call.
-\begin_deeper
-\layout Standard
-
-
-\size small
-int (*foo)();
-\end_deeper
-\layout Standard
-
+\series default
+\bar default
+ Floating point library is compiled as reentrant.See section Installation
+ for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\size small
-\protected_separator
-
-\protected_separator
-...
+\series bold
+\size large
+\bar under
+--out-fmt-ihx
+\size default
-\newline
+\series default
+\bar default
+The linker output (final object code) is in Intel Hex format.
+ (This is the default option).
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-
-\protected_separator
-/* has to be called like this */
-\newline
-\protected_separator
+\series bold
+\size large
+\bar under
+--out-fmt-s19
+\size default
-\protected_separator
-(*foo)();/* ansi standard allows calls to be made like 'foo()' */
-\layout Section
-
-Cyclomatic Complexity
-\begin_inset LatexCommand \label{Cyclomatic}
-
-\end_inset
-
-
-\layout Standard
-
-Cyclomatic complexity of a function is defined as the number of independent
- paths the program can take during execution of the function.
- This is an important number since it defines the number test cases you
- have to generate to validate the function .
- The accepted industry standard for complexity number is 10, if the cyclomatic
- complexity reported by SDCC exceeds 10 you should think about simplification
- of the function logic.
-\layout Standard
+\series default
+\bar default
+The linker output (final object code) is in Motorola S19 format.
+\layout List
+\labelwidthstring 00.00.0000
-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.
-\layout Standard
+\series bold
+\size large
+\bar under
+--nooverlay
+\series default
+\size default
+\bar default
+ The compiler will not overlay parameters and local variables of any function,
+ see section Parameters and local variables for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\size small
-complexity = (number of edges in control flow graph) -
-\newline
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-(number of nodes in control flow graph) + 2;
-\layout Standard
+\series bold
+\size large
+\bar under
+--main-return
+\series default
+\size default
+\bar default
+ 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 .' .
+\layout List
+\labelwidthstring 00.00.0000
-Having said that the industry standard is 10, you should be aware that in
- some cases it may unavoidable to have a complexity level of less than 10.
- For example if you have switch statement with more than 10 case labels,
- each case label adds one to the complexity level.
- The complexity level is by no means an absolute measure of the algorithmic
- complexity of the function, it does however provide a good starting point
- for which functions you might look at for further optimization.
-\layout Section
-TIPS
-\begin_inset LatexCommand \label{Tips}
+\series bold
+\size large
+\bar under
+--no-peep
+\series default
+\size default
+\bar default
+ Disable peep-hole optimization.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+\size large
+\bar under
+--peep-asm
+\series default
+\size default
+\bar default
+ Pass the inline assembler code through the peep hole optimizer.
+ Can cause unexpected changes to inline assembler code , please go through
+ the peephole optimizer rules defnied in file 'SDCCpeeph.def' before using
+ this option.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-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.
-\layout Itemize
+\series bold
+\size large
+\bar under
+--iram-size
+\series default
+\size default
+\bar default
+<Value> Causes the linker to check if the interal ram usage is within limits
+ of the given value.
+\layout Subsubsection
-Use the smallest data type to represent your data-value.
- If it is known in advance that the value is going to be less than 256 then
- use a 'short' or 'char' instead of an 'int'.
-\layout Itemize
+Intermediate Dump Options
+\layout Standard
-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.
-\layout Itemize
+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.
+
+\layout List
+\labelwidthstring 00.00.0000
-NEVER jump into a LOOP.
-\layout Itemize
-Declare the variables to be local whenever possible, especially loop control
- variables (induction).
-\layout Itemize
+\series bold
+\size large
+\bar under
+--dumpraw
+\series default
+\size default
+\bar default
+.
+ This option will cause the compiler to dump the intermediate code into
+ a file of named
+\emph on
+<source filename>.dumpraw
+\emph default
+ 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.
+\layout List
+\labelwidthstring 00.00.0000
-Since the compiler does not do implicit integral promotion, the programmer
- 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.
- Take the following code for example.
-\begin_deeper
-\layout Standard
+\series bold
+\size large
+\bar under
+--dumpgcse
+\series default
+\bar default
+.
+\size default
+ Will create a dump if iCode, after global subexpression elimination, into
+ a file named
+\emph on
+<source filename>.dumpgcse.
+\layout List
+\labelwidthstring 00.00.0000
-\size footnotesize
-foobar( unsigned int p1, unsigned char ch)
-\newline
-{
-\newline
-\protected_separator
+\series bold
+\size large
+\bar under
+--dumpdeadcode
+\series default
+\size default
+\bar default
+.Will create a dump if iCode, after deadcode elimination, into a file named
+
+\emph on
+<source filename>.dumpdeadcode.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\protected_separator
+\series bold
+\size large
+\bar under
+--dumploop.
-\protected_separator
-unsigned char ch1 = p1 % ch ;
-\newline
+\series default
+\bar default
+
+\size default
+Will create a dump if iCode, after loop optimizations, into a file named
+
+\emph on
+<source filename>.dumploop.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\protected_separator
+\series bold
+\size large
+\bar under
+--dumprange.
-\protected_separator
+\series default
+\bar default
+
+\size default
+Will create a dump if iCode, after live range analysis, into a file named
+
+\emph on
+<source filename>.dumprange.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-....
-\protected_separator
-\protected_separator
+\series bold
+\size large
+\bar under
+--dumpregassign.
-\protected_separator
+\size default
+
+\series default
+\bar default
+Will create a dump if iCode, after register assignment , into a file named
+
+\emph on
+<source filename>.dumprassgn.
+\layout List
+\labelwidthstring 00.00.0000
-\protected_separator
-\newline
-}
+\series bold
+\size large
+\bar under
+--dumpall.
+
+\series default
+\size default
+\bar default
+Will cause all the above mentioned dumps to be created.
\layout Standard
-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
+Note that the files created for the dump are appended to each time.
+ So the files should be deleted manually , before each dump is created.
+
\layout Standard
+When reporting bugs, it can be helpful to include these dumps along with
+ the portion of the code that is causing the problem.
+\layout Subsection
-\size footnotesize
-foobar( unsigned int p1, unsigned char ch)
-\newline
-{
-\newline
-
-\protected_separator
+MCS51 Storage Class Language Extensions
+\layout Standard
-\protected_separator
+In addition to the ANSI storage classes SDCC allows the following MCS51
+ specific storage classes.
+\layout Subsubsection
-\protected_separator
+xdata
+\layout Standard
-\protected_separator
-unsigned char ch1 = (unsigned char)p1 % ch ;
-\newline
+Variables declared with this storage class will be placed in the extern
+ RAM.
+ This is the
+\series bold
+default
+\series default
+ storage class for Large Memory model .
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+eg.
+
+\emph on
+xdata unsigned char xduc;
+\layout Subsubsection
-\protected_separator
+data
+\layout Standard
-\protected_separator
-....
-\protected_separator
+This is the
+\series bold
+default
+\series default
+ storage class for Small Memory model.
+ Variables declared with this storage class will be allocated in the internal
+ RAM.
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+eg.
-\protected_separator
+\emph on
+ data int iramdata;
+\layout Subsubsection
-\newline
-}
+idata
\layout Standard
-It would substantially reduce the code generated (future versions of the
- compiler will be smart enough to detect such optimization oppurtunities).
-\end_deeper
+Variables declared with this storage class will be allocated into the indirectly
+ addressable portion of the internal ram of a 8051 .
\layout Standard
-\series bold
-Notes from an USER ( Trefor@magera.freeserve.co.uk )
+\size footnotesize
+eg.
+\emph on
+idata int idi;
+\layout Subsubsection
+
+bit
\layout Standard
-The 8051 family of micro controller have a minimum of 128 bytes of internal
- memory which is structured as follows
+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.
\layout Standard
-- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
-
-\layout Standard
+eg.
+\emph on
+bit iFlag;
+\layout Subsubsection
-- Bytes 20-2F - 16 bytes to hold 128 bit variables and
+sfr / sbit
\layout Standard
-- Bytes 30-7F - 60 bytes for general purpose use.
+Like the bit keyword,
+\emph on
+sfr / sbit
+\emph default
+signifies both a data-type and storage class, they are used to describe
+ the special function registers and special bit variables of a 8051.
+
\layout Standard
-Normally the SDCC compiler will only utilise the first bank of registers,
- but it is possible to specify that other banks of registers should be used
- in interrupt routines.
- By default, the compiler will place the stack after the last bank of used
- registers, i.e.
- if the first 2 banks of registers are used, it will position the base of
- the internal stack at address 16 (0X10).
- This implies that as the stack grows, it will use up the remaining register
- banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
- general purpose use.
-\layout Standard
+eg.
-By default, the compiler uses the 60 general purpose bytes to hold "near
- data".
- The compiler/optimiser may also declare some Local Variables in this area
- to hold local data.
+\emph on
\layout Standard
-If any of the 128 bit variables are used, or near data is being used then
- care needs to be taken to ensure that the stack does not grow so much that
- it starts to over write either your bit variables or "near data".
- There is no runtime checking to prevent this from happening.
-\layout Standard
-
-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.
-\layout Standard
-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.
-
+\emph on
+sfr at 0x80 P0;
+\emph default
+\noun on
+/* special function register P0 at location 0x80 */
\layout Standard
---stack-loc will allow you specify the start of the stack, i.e.
- you could start it after any data in the general purpose area.
- However this may waste the memory not used by the register banks and if
- the size of the "near data" increases, it may creep into the bottom of
- the stack.
-\layout Standard
---stack-after-data, similar to the --stack-loc, but it automatically places
- the stack after the end of the "near data".
- Again this could waste any spare register space.
-\layout Standard
+\emph on
+sbit at 0xd7 CY; /*
+\noun on
+CY (Carry Flag) */
+\layout Subsection
---data-loc allows you to specify the start address of the near data.
- This could be used to move the "near data" further away from the stack
- giving it more room to grow.
- This will only work if no bit variables are being used and the stack can
- grow to use the bit variable space.
+Pointers
\layout Standard
-Conclusion.
+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
+\emph on
+_generic
+\emph default
+ class of pointers which can be used to point to any of the memory spaces.
+
\layout Standard
-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.
+Pointer declaration examples.
\layout Standard
-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.
-\layout Section
-
-Retargetting for other MCUs.
-\begin_inset LatexCommand \label{Retargetting}
-
-\end_inset
+\size small
+/* pointer physically in xternal ram pointing to object in internal ram
+ */
+\newline
+data unsigned char * xdata p;
+\newline
\layout Standard
-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.
-\layout Enumerate
-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.
-\layout Enumerate
+\size small
+/* pointer physically in code rom pointing to data in xdata space */
+\newline
+xdata unsigned char * code p;
+\newline
-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.
-\layout Enumerate
+\layout Standard
-This phase does the bulk of the standard optimizations and is also MCU independe
-nt.
- This phase can be broken down into several sub-phases.
-\begin_deeper
-\layout Itemize
-Break down intermediate code (iCode) into basic blocks.
-\layout Itemize
+\size small
+/* pointer physically in code space pointing to data in code space */
+\newline
+code unsigned char * code p;
+\newline
-Do control flow & data flow analysis on the basic blocks.
-\layout Itemize
+\newline
+/* the folowing is a generic pointer physically located in xdata space */
+\newline
+char * xdata p;
+\layout Standard
-Do local common subexpression elimination, then global subexpression elimination
-\layout Itemize
+Well you get the idea.
+ For compatibility with the previous version of the compiler, the following
+ syntax for pointer declaration is also supported.
+ Note the above examples will be portable to other commercially available
+ compilers.
+\layout Standard
-dead code elimination
-\layout Itemize
-loop optimizations
-\layout Itemize
+\size small
+unsigned char _xdata *ucxdp; /* pointer to data in external ram */
+\newline
+unsigned char _data \SpecialChar ~
+*ucdp ; /* pointer to data in internal ram */
+\newline
+unsigned char _code \SpecialChar ~
+*uccp ; /* pointer to data in R/O code space */
+\newline
+unsigned char _idata *uccp; \SpecialChar ~
+/* pointer to upper 128 bytes of ram */
+\layout Standard
-if loop optimizations caused any changes then do 'global subexpression eliminati
-on' and 'dead code elimination' again.
-\end_deeper
-\layout Enumerate
+All unqualified pointers are treated as 3 - byte '_generic' pointers.
+ These type of pointers can also to be explicitly declared.
+\layout Standard
-This phase determines the live-ranges; by live range I mean those iTemp
- variables defined by the compiler that still survive after all the optimization
-s.
- Live range analysis is essential for register allocation, since these computati
-on determines which of these iTemps will be assigned to registers, and for
- how long.
-\layout Enumerate
-Phase five is register allocation.
- There are two parts to this process .
-\begin_deeper
-\layout Enumerate
+\size small
+unsigned char _generic *ucgp;
+\layout Standard
-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.
-\layout Enumerate
+The highest order byte of the generic pointers contains the data space informati
+on.
+ 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.
+\layout Subsection
-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.
-\end_deeper
-\layout Enumerate
+Parameters & Local Variables
+\layout Standard
-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.
-\layout Enumerate
+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
+\emph on
+ --stack-auto
+\emph default
+ compiler option or by using the 'reentrant' keyword in the function declaration.
+\layout Standard
-As mentioned in the optimization section the peep-hole optimizer is rule
- based system, which can reprogrammed for other MCUs.
-\layout Section
-Reporting Bugs
-\begin_inset LatexCommand \label{Bugs}
+\family typewriter
+\size scriptsize
+eg
+\layout Standard
-\end_inset
+\size small
+unsigned short foo( short i) reentrant {
+\newline
+...
+
+\newline
+}
+\layout Standard
+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
+\emph on
+'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
-Shoot of an email to 'sandeep.dutta@usa.net', as a matter of principle I always
- reply to all email's sent to me.
- Bugs will be fixed ASAP.
- When reporting a bug , it is useful to include a small snippet of code
- that is causing the problem, if possible compile your program with the
- --dumpall option and send the dump files along with the bug report.
-\layout Section
-
-SDCDB - Source level debugger.
+When compiled with the default option (i.e.
+ non-reentrant ), local variables can be assigned storage classes and absolute
+ addresses.
+
\layout Standard
-SDCC is distributed with a source level debugger.
- The debugger uses a command line interface, the command repertoire of the
- debugger has been kept as close to gdb ( the GNU debugger) as possible.
- The configuration and build process of the compiler see Installation
-\begin_inset LatexCommand \ref{Installation}
-\end_inset
+\family typewriter
+\size scriptsize
+eg
+\layout Standard
- 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.
-\layout Subsection
-Compiling for debugging.
+\size small
+unsigned short foo() {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+xdata unsigned short i;
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+bit bvar;
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+data at 0x31 unsiged short j;
+\newline
+...
+
+\newline
+}
\layout Standard
-The
+In the above example the variable
\emph on
---debug
+i
\emph default
- option must be specified for all files for which debug information is to
- be generated.
- The complier generates a
+ will be allocated in the external ram,
\emph on
-.cdb
+bvar
\emph default
- file for each of these files.
- The linker updates the
+ in bit addressable space and
\emph on
-.cdb
+ j
\emph default
- file with the address information.
- This .cdb is used by the debugger .
+ in internal ram.
+ When compiled with the
+\emph on
+--stack-auto
+\emph default
+ or when a function is declared as
+\emph on
+'reentrant'
+\emph default
+ local variables cannot be assigned storage classes or absolute addresses.
+\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.
\layout Subsection
-How the debugger works.
+Overlaying
\layout Standard
-When the
+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 overlayabl
+e segment if the function has
\emph on
---debug
+no other function calls and the function is non-reentrant and the memory
+ model is small.
+
\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.
- 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 .
-\layout Subsection
+ If an explicit storage class is specified for a local variable , it will
+ NOT be overplayed.
+\layout Standard
-Starting the debugger.
+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.
\layout Standard
-The debugger can be started using the following command line.
- (Assume the file you are debugging has
+Parameters and Local variables of functions that contain 16 or 32 bit multiplica
+tion or division will NOT be overlayed since these are implemented using
+ external functions.
\layout Standard
-the file name foo).
+eg.
\layout Standard
->sdcdb foo
+
+\size small
+#pragma SAVE
+\newline
+#pragma NOOVERLAY
+\newline
+void set_error( unsigned short errcd)
+\newline
+{
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ P3 = errcd;
+\newline
+}
+\newline
+#pragma RESTORE
+\newline
+void some_isr () interrupt 2 using 1
+\newline
+{
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ set_error(10);
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+}
\layout Standard
-The debugger will look for the following files.
-\layout Enumerate
+In the above example the parameter
+\emph on
+errcd
+\emph default
+ for the function
+\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.
+ The pragma NOOVERLAY ensures that the parameters and local variables for
+ the function are NOT overlayed.
+\layout Subsection
-foo.c - the source file.
-\layout Enumerate
+Critical Functions
+\layout Standard
-foo.cdb - the debugger symbol information file.
-\layout Enumerate
+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.
+\layout Standard
-foo.ihx - the intel hex format object file.
-\layout Subsection
+eg
+\layout Standard
-Command line options.
-\layout Itemize
---directory=<source file directory> this option can used to specify the
- directory search list.
- The debugger will look into the directory list specified for source , cdb
- & ihx files.
- The items in the directory list must be separated by ':' , e.g.
- if the source files can be in the directories /home/src1 and /home/src2,
- the --directory option should be --directory=/home/src1:/home/src2 .
- Note there can be no spaces in the option.
+\size small
+int foo () critical
+\newline
+{
+\newline
+...
-\layout Itemize
-
--cd <directory> - change to the <directory>.
-\layout Itemize
+\newline
+...
+
+\newline
+}
+\layout Standard
--fullname - used by GUI front ends.
-\layout Itemize
+The critical attribute maybe used with other attributes like
+\emph on
+reentrant.
+\layout Subsection
--cpu <cpu-type> - this argument is passed to the simulator please see the
- simulator docs for details.
-\layout Itemize
+Absolute Addressing
+\layout Standard
--X <Clock frequency > this options is passed to the simulator please see
- simulator docs for details.
-\layout Itemize
+Data items can be assigned an absolute address with the
+\emph on
+at <address>
+\emph default
+ keyword, in addition to a storage class.
+\layout Standard
--s <serial port file> passed to simulator see simulator docs for details.
-\layout Itemize
+eg.
+
+\layout Standard
--S <serial in,out> passed to simulator see simulator docs for details.
-\layout Subsection
-Debugger Commands.
+\size small
+xdata at 0x8000 unsigned char PORTA_8255 ;
\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
- for the GNU debugger.
-\layout Subsubsection
+In the above example the
+\emph on
+PORTA_8255
+\emph default
+ will be allocated to the location 0x8000 of the external ram.
+
+\layout Standard
-break [line | file:line | function | file:function]
+Note that is 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.
\layout Standard
-Set breakpoint at specified line or function.
+Absolute address can be specified for variables in all storage classes.
\layout Standard
-sdcdb>break 100
-\newline
-sdcdb>break foo.c:100
-\newline
-sdcdb>break funcfoo
-\newline
-sdcdb>break foo.c:funcfoo
-\layout Subsubsection
-clear [line | file:line | function | file:function ]
+\size small
+eg.
\layout Standard
-Clear breakpoint at specified line or function.
+
+\size small
+bit at 0x02 bvar;
\layout Standard
-sdcdb>clear 100
-\newline
-sdcdb>clear foo.c:100
-\newline
-sdcdb>clear funcfoo
-\newline
-sdcdb>clear foo.c:funcfoo
-\layout Subsubsection
+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.
+\layout Subsection
-continue
+Interrupt Service Routines
\layout Standard
-Continue program being debugged, after breakpoint.
-\layout Subsubsection
-
-finish
+SDCC allows interrupt service routines to be coded in C, with some extended
+ keywords.
\layout Standard
-Execute till the end of the current function.
-\layout Subsubsection
-delete [n]
+\size small
+void timer_isr (void) interrupt 2 using 1
+\newline
+{
+\newline
+..
+
+\newline
+}
\layout Standard
-Delete breakpoint number 'n'.
- If used without any option clear ALL user defined break points.
-\layout Subsubsection
-
-info [break | stack | frame | registers ]
-\layout Itemize
+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, 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.
+\layout Standard
-info break - list all breakpoints
-\layout Itemize
+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
+\emph on
+'main'
+\emph default
+.
+\layout Standard
-info stack - show the function call stack.
-\layout Itemize
+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.
+\layout Standard
-info frame - show information about the current execution frame.
-\layout Itemize
-info registers - show content of all registers.
-\layout Subsubsection
+\begin_inset Tabular
+<lyxtabular version="2" rows="6" columns="3">
+<features rotate="false" islongtable="false" endhead="0" endfirsthead="0" endfoot="0" endlastfoot="0">
+<column alignment="center" valignment="top" leftline="true" rightline="false" width="" special="">
+<column alignment="center" valignment="top" leftline="true" rightline="false" width="" special="">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="" special="">
+<row topline="true" bottomline="true" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-step
\layout Standard
-Step program until it reaches a different source line.
-\layout Subsubsection
+Interrupt #
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-next
\layout Standard
-Step program, proceeding through subroutine calls.
-\layout Subsubsection
+Description
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-run
\layout Standard
-Start debugged program.
-\layout Subsubsection
+Vector Address
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-ptype variable
\layout Standard
-Print type information of the variable.
-\layout Subsubsection
+0
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-print variable
\layout Standard
-print value of variable.
-\layout Subsubsection
+External 0
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-file filename
\layout Standard
-load the given file name.
- Note this is an alternate method of loading file for debugging.
-\layout Subsubsection
+0x0003
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-frame
\layout Standard
-print information about current frame.
-\layout Subsubsection
+1
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-set srcmode
\layout Standard
-Toggle between C source & assembly source.
-\layout Subsubsection
+Timer 0
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-! simulator command
\layout Standard
-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.
-\layout Subsubsection
+0x000B
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-quit.
\layout Standard
-"Watch me now.
- Iam going Down.
- My name is Bobby Brown"
-\layout Subsection
-
-Interfacing with XEmacs.
-\layout Standard
+2
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-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
-.
- 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.
-
\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.
-\layout Itemize
+External 1
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-sdcdbsrc-cpu-type '51
-\layout Itemize
+\layout Standard
-sdcdbsrc-frequency '11059200
-\layout Itemize
+0x0013
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-sdcdbsrc-serial nil
\layout Standard
-The following is a list of key mapping for the debugger interface.
+3
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
+
\layout Standard
+Timer 1
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\protected_separator
+\layout Standard
-\size scriptsize
+0x001B
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\newline
-;; Current Listing ::
-\newline
-;;key
-\protected_separator
+\layout Standard
-\protected_separator
+4
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\protected_separator
+\layout Standard
-\protected_separator
+Serial
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
+\begin_inset Text
-\protected_separator
+\layout Standard
-\protected_separator
+0x0023
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-\protected_separator
+\end_inset
-\protected_separator
-\protected_separator
+\layout Standard
-\protected_separator
+If the interrupt service routine is defined without a register bank or with
+ register bank 0 (using 0), the compiler will save the registers used by
+ itself on the stack (upon entry and restore them at exit), however if such
+ an interrupt service routine calls another function then the entire register
+ bank will be saved on the stack.
+ This scheme may be advantageous for small interrupt service routines which
+ have low register usage.
+\layout Standard
-\protected_separator
+If the interrupt service routine is defined to be using a specific register
+ bank then only
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+a
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+,
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+b
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
-binding
-\protected_separator
+ &
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+dptr
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ 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
-\protected_separator
+Calling other functions from an interrupt service routine is not recommended
+ avoid it if possible.
+\layout Subsection
-\protected_separator
+Startup Code
+\layout Standard
-\protected_separator
+The compiler inserts a jump to the C routine
+\series bold
+_sdcc__external__startup()
+\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.
+ You could add a
+\series bold
+_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.
+\layout Subsection
-\protected_separator
+Inline Assembler Code
+\layout Standard
-\protected_separator
+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
+\emph on
+form nnnnn$
+\emph default
+ where nnnn is a number less than 100 (which implies a limit of utmost 100
+ inline assembler labels
+\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
+\bar under
+--peep-asm
+\series default
+\bar 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' carefully before using this option.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+eg
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+_asm
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+mov b,#10
+\newline
+00001$:
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+djnz b,00001$
+\newline
+_endasm ;
+\layout Standard
-\protected_separator
+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
+\emph on
+_asm ...
+ _endasm;
+\emph default
+ keyword pair.
+
+\layout Standard
-\protected_separator
+Inline assembler code cannot reference any C-Labels however it can reference
+ labels defined by the inline assembler.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+eg
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+foo() {
+\newline
+...
+ /* some c code */
+\newline
+_asm
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+; some assembler code
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ljmp $0003
+\newline
+_endasm ;
+\newline
+...
+ /* some more c code */
+\newline
+clabel: \SpecialChar ~
+ /* inline assembler cannot reference this label */
+\newline
+_asm
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+$0003: ;label (can be reference by inline assembler only)
+\newline
+_endasm ;
+\newline
+...
+
+\newline
+}
+\layout Standard
-\protected_separator
+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.
+\layout Subsection
-\protected_separator
+int(16 bit) and long (32 bit ) Support
+\layout Standard
-\protected_separator
+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
+\layout Itemize
-\protected_separator
-Comment
-\newline
-;;---
-\protected_separator
-\protected_separator
+\size footnotesize
+_mulsint.c - signed 16 bit multiplication (calls _muluint)
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_muluint.c - unsigned 16 bit multiplication
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_divsint.c - signed 16 bit division (calls _divuint)
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_divuint.c - unsigned 16 bit division.
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_modsint.c - signed 16 bit modulus (call _moduint)
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_moduint.c - unsigned 16 bit modulus.
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_mulslong.c - signed 32 bit multiplication (calls _mululong)
+\layout Itemize
-\protected_separator
--------
-\protected_separator
-\protected_separator
+\size footnotesize
+_mululong.c - unsigned32 bit multiplication.
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_divslong.c - signed 32 division (calls _divulong)
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_divulong.c - unsigned 32 division.
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_modslong.c - signed 32 bit modulus (calls _modulong).
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_modulong.c - unsigned 32 bit modulus.
+\layout Standard
-\protected_separator
+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.
+\layout Subsection
-\protected_separator
+Floating Point Support
+\layout Standard
-\protected_separator
+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
-\protected_separator
-\protected_separator
+\size footnotesize
+_fsadd.c - add floating point numbers.
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_fssub.c - subtract floating point numbers
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_fsdiv.c - divide floating point numbers
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_fsmul.c - multiply floating point numbers
+\layout Itemize
-\protected_separator
--------
-\newline
-;;
-\newline
-;; n
-\protected_separator
-\protected_separator
+\size footnotesize
+_fs2uchar.c - convert floating point to unsigned char
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_fs2char.c - convert floating point to signed char.
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_fs2uint.c - convert floating point to unsigned int.
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_fs2int.c - convert floating point to signed int.
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_fs2ulong.c - convert floating point to unsigned long.
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_fs2long.c - convert floating point to signed long.
+\layout Itemize
-\protected_separator
-\protected_separator
- sdcdb-next-from-src
-\protected_separator
+\size footnotesize
+_uchar2fs.c - convert unsigned char to floating point
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_char2fs.c - convert char to floating point number
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_uint2fs.c - convert unsigned int to floating point
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_int2fs.c - convert int to floating point numbers
+\layout Itemize
-\protected_separator
-\protected_separator
+\size footnotesize
+_ulong2fs.c - convert unsigned long to floating point number
+\layout Itemize
-\protected_separator
-SDCDB next command
-\newline
-;; b
-\protected_separator
-\protected_separator
+\size footnotesize
+_long2fs.c - convert long to floating point number.
+\layout Standard
-\protected_separator
+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)
+\layout Subsection
-\protected_separator
+MCS51 Memory Models
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
+Judicious usage of the processor specific storage classes and the 'reentrant'
+ function type will yield much more efficient code, than using the large-model.
+ Several optimizations are disabled when the program is compiled using the
+ large model, it is therefore strongly recommdended that the small model
+ be used unless absolutely required.
+\layout Subsection
-\protected_separator
+Flat 24 bit Addressing Model
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
+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-f
+lat24 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.
+\layout Standard
-\protected_separator
+Note that the compiler does not generate any code to place the processor
+ into24 bitmode (it defaults to 8051 compatible mode).
+ Boot loader or similar code must ensure that the processor is in 24 bit
+ contiguous addressing mode before calling the SDCC startup code.
+\layout Standard
-\protected_separator
+Like the --model-large option, variables will by default be placed into
+ the XDATA segment.
+
+\layout Standard
-\protected_separator
+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.
+\layout Subsection
-\protected_separator
- sdcdb-back-from-src
-\protected_separator
+Defines Created by the Compiler
+\layout Standard
-\protected_separator
+The compiler creates the following #defines .
+\layout Itemize
-\protected_separator
+SDCC - this Symbol is always defined.
+\layout Itemize
-\protected_separator
+SDCC_STACK_AUTO - this symbol is defined when --stack-auto option is used.
+\layout Itemize
-\protected_separator
+SDCC_MODEL_SMALL - when small model is used.
+\layout Itemize
-\protected_separator
+SDCC_MODEL_LARGE - when --model-large is used.
+\layout Itemize
-\protected_separator
+SDCC_USE_XSTACK - when --xstack option is used.
+\layout Section
-\protected_separator
+SDCC Technical Data
+\layout Subsection
-\protected_separator
+Optimizations
+\layout Standard
-\protected_separator
-SDCDB back command
-\newline
-;; c
-\protected_separator
+SDCC performs a a host of standard optimizations in addition to some MCU
+ specific optimizations.
+
+\layout Subsubsection
-\protected_separator
+Sub-expression Elimination
+\layout Standard
-\protected_separator
+The compiler does
+\emph on
+local and global
+\emph default
+common subexpression elimination.
+\layout Standard
-\protected_separator
-\protected_separator
+\family typewriter
+\size scriptsize
+eg.
+
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+i = x + y + 1;
+\size default
-\protected_separator
+\newline
+j
+\size small
+= x + y;
+\layout Standard
-\protected_separator
+will be translated to
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+iTemp = x + y
+\newline
+i = iTemp + 1
+\newline
+j = iTemp
+\layout Standard
-\protected_separator
+Some subexpressions are not as obvious as the above example.
+\layout Standard
-\protected_separator
+eg.
+\layout Standard
-\protected_separator
- sdcdb-cont-from-src
-\protected_separator
-\protected_separator
+\size small
+a->b[i].c = 10;
+\newline
+a->b[i].d = 11;
+\layout Standard
-\protected_separator
+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
-\protected_separator
-\protected_separator
+\size small
+iTemp = a->b[i];
+\newline
+iTemp.c = 10;
+\newline
+iTemp.d = 11;
+\layout Standard
-\protected_separator
+The compiler will try to keep these temporary variables in registers.
+\layout Subsubsection
-\protected_separator
+Dead-Code Elimination
+\layout Standard
-\protected_separator
+eg.
+\layout Standard
-\protected_separator
-\protected_separator
-SDCDB continue command
+\size small
+int global;
\newline
-;; s
-\protected_separator
-
-\protected_separator
+void f () {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+int i;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+i = 1; \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* dead store */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+global = 1; /* dead store */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+global = 2;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+return;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+global = 3; /* unreachable */
+\newline
+}
+\layout Standard
-\protected_separator
+will be changed to
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+int global; void f ()
+\newline
+{ \SpecialChar ~
+ \SpecialChar ~
+
+\newline
+\SpecialChar ~
+global = 2; \SpecialChar ~
+ \SpecialChar ~
+
+\newline
+\SpecialChar ~
+return;
+\newline
+}
+\layout Subsubsection
-\protected_separator
+Copy-Propagation
+\layout Standard
-\protected_separator
+eg.
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+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
-\protected_separator
+will be changed to
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+int f() {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ int i,j;
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ i = 10;
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ j = 10;
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ return 10;
+\newline
+}
+\layout Standard
-\protected_separator
+Note: the dead stores created by this copy propagation will be eliminated
+ by dead-code elimination .
+\layout Subsubsection
-\protected_separator
- sdcdb-step-from-src
-\protected_separator
+Loop Optimizations
+\layout Standard
-\protected_separator
+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
+ 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
-\protected_separator
-\protected_separator
+\series bold
+Loop Invariant:
+\layout Standard
-\protected_separator
+eg
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+for (i = 0 ; i < 100 ; i ++)
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+f += k + l;
+\layout Standard
-\protected_separator
+changed to
+\layout Standard
-\protected_separator
-\protected_separator
-SDCDB step command
+\size small
+itemp = k + l;
\newline
-;; ?
-\protected_separator
-
-\protected_separator
+for ( i = 0; i < 100; i++ ) f += itemp;
+\layout Standard
-\protected_separator
+As mentioned previously some loop invariants are not as apparent, all static
+ address computations are also moved out of the loop.
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+Strength Reduction :
+\layout Standard
-\protected_separator
+This optimization substitutes an expression by a cheaper expression.
+\layout Standard
-\protected_separator
+eg.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+for (i=0;i < 100; i++) ar[i*5] = i*3;
+\layout Standard
-\protected_separator
+changed to
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+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
-\protected_separator
+The more expensive multiplication is changed to a less expensive addition.
+\layout Subsubsection
-\protected_separator
- sdcdb-whatis-c-sexp
-\protected_separator
+Loop Reversing:
+\layout Standard
-\protected_separator
+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
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+decrement and jump if not zero
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ instruction.
+ SDCC checks for the following criterion to determine if a loop is reversible
+ (note: more sophisticated compiers use data-dependency analysis to make
+ this determination, SDCC uses a more simple minded analysis).
+\layout Itemize
-\protected_separator
+The 'for' loop is of the form
+\newline
-\protected_separator
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+for ( <symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
+ <sym> += 1])
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+<for body>
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
-\protected_separator
+\layout Itemize
-\protected_separator
-SDCDB ptypecommand for data at
-\newline
-;;
-\protected_separator
+The <for body> does not contain
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+continue
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ or 'break
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+.
+\layout Itemize
-\protected_separator
+All goto's are contained within the loop.
+\layout Itemize
-\protected_separator
+No function calls within the loop.
+\layout Itemize
-\protected_separator
+The loop control variable <sym> is not assigned any value within the loop
+\layout Itemize
-\protected_separator
+The loop control variable does NOT participate in any arithmetic operation
+ within the loop.
+\layout Itemize
-\protected_separator
+There are NO switch statements in the loop.
+\layout Standard
-\protected_separator
+Note djnz instruction can be used for 8-bit values ONLY, therefore it is
+ advantageous to declare loop control symbols as either 'char' or 'short',
+ ofcourse this may not be possible on all situations.
+\layout Subsubsection
-\protected_separator
+Algebraic Simplifications
+\layout Standard
-\protected_separator
+SDCC does numerous algebraic simplifications, the following is a small sub-set
+ of these optimizations.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+eg
+\emph on
+
+\emph default
-\protected_separator
+\newline
+i = j + 0 ; /* changed to */ i = j;
+\newline
+i /= 2; /* changed to */ i >>= 1;
+\newline
+i = j - j ; /* changed to */ i = 0;
+\newline
+i = j / 1 ; /* changed to */ i = j;
+\layout Standard
-\protected_separator
+Note the subexpressions given above are generally introduced by macro expansions
+ or as a result of copy/constant propagation.
+\layout Subsubsection
-\protected_separator
+'switch' Statements
+\layout Standard
-\protected_separator
+SDCC changes switch statements to jump tables when the following conditions
+ are true.
+
+\layout Itemize
-\protected_separator
+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
-\protected_separator
+eg
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+switch(i) {\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+switch (i) {
+\newline
+case 4:...
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+case 1: ...
+
+\newline
+case 5:...
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+case 2: ...
+
+\newline
+case 3:...
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+case 3: ...
+
+\newline
+case 6:...
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+case 4: ...
+
+\newline
+}\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+}
+\layout Standard
-\protected_separator
+Both the above switch statements will be implemented using a jump-table.
+\layout Itemize
-\protected_separator
+The number of case labels is at least three, since it takes two conditional
+ statements to handle the boundary conditions.
+\layout Itemize
-\protected_separator
+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.
+
+\layout Standard
-\protected_separator
+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
-\protected_separator
+eg
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+switch (i) {
+\newline
+case 1: ...
+
+\newline
+case 2: ...
+
+\newline
+case 3: ...
+
+\newline
+case 4: ...
+
+\newline
+case 9: ...
+
+\newline
+case 10: ...
+
+\newline
+case 11: ...
+
+\newline
+case 12: ...
+
+\newline
+}
+\layout Standard
-\protected_separator
+If the above switch statement is broken down into two switch statements
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+switch (i) {
+\newline
+case 1: ...
+
+\newline
+case 2: ...
+
+\newline
+case 3: ...
+
+\newline
+case 4: ...
+
+\newline
+}
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+switch (i) {
+\newline
+case 9: ...
+
+\newline
+case 10: ...
+
+\newline
+case 11: ...
+
+\newline
+case 12:...
+
+\newline
+}
+\layout Standard
-\protected_separator
+then both the switch statements will be implemented using jump-tables whereas
+ the unmodified switch statement will not be .
+\layout Subsubsection
-\protected_separator
+Bit-shifting Operations.
+\layout Standard
-\protected_separator
+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
-\protected_separator
+eg.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+unsigned short i;
+\layout Standard
-\protected_separator
-\protected_separator
- buffer point
+\size small
+...
+
\newline
-;; x
-\protected_separator
-
-\protected_separator
+i>>= 4;
+\newline
+..
+\layout Standard
-\protected_separator
+generates the following code.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+mov a,_i
+\newline
+swap a
+\newline
+anl a,#0x0f
+\newline
+mov _i,a
+\layout Standard
-\protected_separator
+In general SDCC will never setup a loop if the shift count is known.
+ Another example
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+unsigned int i;
+\newline
+...
+
+\newline
+i >>= 9;
+\newline
+...
+\layout Standard
-\protected_separator
+will generate
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+mov a,(_i + 1)
+\newline
+mov (_i + 1),#0x00
+\newline
+clr c
+\newline
+rrc a
+\newline
+mov _i,a
+\layout Standard
-\protected_separator
+Note that SDCC stores numbers in
+\noun on
+little-endian
+\noun default
+format (i.e.
+ lowest order first)
+\layout Subsubsection
-\protected_separator
+Bit-rotation
+\layout Standard
-\protected_separator
- sdcdbsrc-delete
-\protected_separator
+A special case of the bit-shift operation is bit rotation, SDCC recognizes
+ the following expression to be a left bit-rotation.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+unsigned char i;
+\newline
+...
+
+\newline
+i = ( ( i << 1) | ( i >> 7));
+\newline
+...
+\layout Standard
-\protected_separator
+will generate the following code.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+mov a,_i
+\newline
+rl a
+\newline
+mov _i,a
+\layout Standard
-\protected_separator
+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
+\emph on
+ i = ((i >> 7) | (i << 1));
+\emph default
+/* left-bit rotation */
+\layout Subsubsection
-\protected_separator
+Highest Order Bit
+\layout Standard
-\protected_separator
+It is frequently required to obtain the highest order bit of an integral
+ type (int,long,short or char types).
+ SDCC recognizes the following expression to yield the highest order bit
+ and generates optimized code for it.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+eg
+\newline
+unsigned int gint;
+\newline
+foo () {
+\newline
+unsigned char hob;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+hob = (gint >> 15) & 1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+..
+
+\newline
+}
+\layout Standard
-\protected_separator
+Will generate the following code.
+\layout Standard
-\protected_separator
-\protected_separator
-SDCDB Delete all breakpoints if no arg
+\size small
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 61 ;\SpecialChar ~
+ hob.c 7
\newline
-;;
-\protected_separator
-
-\protected_separator
+\SpecialChar ~
+\SpecialChar ~
+ 000A E5*01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 62\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ a,(_gint + 1)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ 000C 33\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 63\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ rlc\SpecialChar ~
+ a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ 000D E4\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 64\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ clr\SpecialChar ~
+ a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ 000E 13\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 65\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ rrc\SpecialChar ~
+ a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ 000F F5*02\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 66\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ _foo_hob_1_1,a
+\layout Standard
-\protected_separator
+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
-\protected_separator
-\protected_separator
+\size small
+eg.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+xyz = gint + ((gint >> 15) & 1);
+\layout Standard
-\protected_separator
+will still be recognized.
+\layout Subsubsection
-\protected_separator
+Peep-hole Optimizer
+\layout Standard
-\protected_separator
+The compiler uses a rule based , pattern matching and re-writing mechanism
+ for peep-hole optimization .
+ It is inspired by '
+\emph on
+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.
+ The rule language is best illustrated with examples.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+replace {
+\newline
+mov %1,a
+\newline
+mov a,%1 } by { mov %1,a }
+\layout Standard
-\protected_separator
+The above rule will the following assembly sequence
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+mov r1,a
+\newline
+mov a,r1
+\layout Standard
-\protected_separator
+to
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+mov r1,a
+\layout Standard
-\protected_separator
+Note: All occurrences of a '%n' ( pattern variable ) must denote the same
+ string.
+ With the above rule, the assembly sequence
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+mov r1,a
+\newline
+mov a,r2
+\layout Standard
-\protected_separator
+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
-\protected_separator
-\protected_separator
+\size small
+replace { lcall %1 } by { acall %1 }
+\newline
+replace { ljmp %1 } by { ajmp %1 }
+\layout Standard
-\protected_separator
+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-structur
+e is MCU independent.
+ Peephole optimization rules for other MCU can be easily programmed using
+ the rule language.
+\layout Standard
-\protected_separator
+The syntax for a rule is as follows ,
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+rule := replace [ restart ] '{' <assembly sequence> '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' by '{' '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ <assembly sequence> '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' [if <functionName> ] '
+\backslash
+n'
+\newline
+<assembly sequence> := assembly instruction (each instruction including
+ labels must be on a separate line).\SpecialChar ~
+ \SpecialChar ~
-\protected_separator
+\layout Standard
-\protected_separator
+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
+ the same rule again.
+ A good example of this the following rule.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+replace restart {
+\newline
+pop %1
+\newline
+push %1 } by {
+\newline
+; nop
+\newline
+}
+\layout Standard
-\protected_separator
+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
-\protected_separator
-\protected_separator
+\size small
+pop ar1
+\newline
+pop ar2
+\newline
+push ar2
+\newline
+push ar1
+\layout Standard
-\protected_separator
+would result in
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+pop ar1
+\newline
+; nop
+\newline
+push ar1
+\layout Standard
-\protected_separator
+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'
+\emph default
+ pairs will be eliminated to yield
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+; nop
+\newline
+; nop
+\layout Standard
-\protected_separator
+A conditional function can be attached to a rule.
+ Attaching rules are somewhat more involved, let me illustrate this with
+ an example.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+replace {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ljmp %5
+\newline
+%2:} by {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+sjmp %5
+\newline
+%2:} if labelInRange
+\layout Standard
-\protected_separator
+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
+\emph default
+ , with the name
+\emph on
+'labelInRange
+\emph default
+', 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
+\emph default
+' 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 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
+\emph on
+--peep-file
+\emph default
+ option.
+\layout Subsection
-\protected_separator
-given or delete arg (C-u arg x)
-\newline
-;; m
-\protected_separator
+Pragmas
+\layout Standard
-\protected_separator
+SDCC supports the following
+\emph on
+#pragma
+\emph default
+directives.
+ This directives are applicable only at a function level.
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+SAVE
+\series default
+ - this will save all the current options .
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+RESTORE
+\series default
+- 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
-\protected_separator
-\protected_separator
+\series bold
+NOGCSE
+\series default
+ - will stop global subexpression elimination.
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+NOINDUCTION
+\series default
+ - will stop loop induction optimizations .
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+NOJTBOUND
+\series default
+ - will not generate code for boundary value checking , when switch statements
+ are turned into jump-tables.
+\layout Itemize
-\protected_separator
-\protected_separator
- sdcdbsrc-frame
-\protected_separator
+\series bold
+NOOVERLAY
+\series default
+- the compiler will not overlay the parameters and local variables of a
+ function.
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+NOLOOPREVERSE
+\series default
+ - Will not do loop reversal optimization
+\layout Itemize
-\protected_separator
-\protected_separator
+\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).
+ 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
-\protected_separator
+#pragma EXCLUDE none
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
-\protected_separator
+\layout Itemize
-\protected_separator
-\protected_separator
+\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.
+ 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.
+\layout Standard
-\protected_separator
+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
+\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.
+\layout Standard
-\protected_separator
-\protected_separator
+\size scriptsize
+eg
+\layout Standard
-\protected_separator
-\protected_separator
-SDCDB Display current frame if no arg,
+\size scriptsize
+#pragma SAVE \SpecialChar ~
+ /* save the current settings */
\newline
-;;
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
+#pragma NOGCSE /* turnoff global subexpression elimination */
+\newline
+#pragma NOINDUCTION /* turn off induction optimizations */
+\newline
+int foo ()
+\newline
+{
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ /* large code */
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+}
+\newline
+#pragma RESTORE /* turn the optimizations back on */
+\layout Standard
-\protected_separator
+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.
+\layout Subsection
-\protected_separator
+Library Routines
+\layout Standard
-\protected_separator
+The following library routines are provided for your convenience.
+\layout Standard
-\protected_separator
-\protected_separator
+\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>.
+
+\layout Standard
-\protected_separator
-\protected_separator
+\size scriptsize
+%[flags][width][b|B|l|L]type
+\layout Standard
-\protected_separator
-\protected_separator
+\size scriptsize
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ flags: -\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ left justify output in specified field width
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ +\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ prefix output with +/- sign if output is signed type
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ space\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ prefix output with a blank if it's a signed positive value
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ width:\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ specifies minimum number of characters outputted for numbers
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ or strings.
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ - For numbers, spaces are added on the left when needed.
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ If width starts with a zero character, zeroes and used
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ instead of spaces.
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ - For strings, spaces are are added on the left or right (when
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ flag '-' is used) when needed.
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ b/B:\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ byte argument (used by d, u, o, x, X)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ l/L:\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ long argument (used by d, u, o, x, X)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ type:\SpecialChar ~
+ d\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ decimal number
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ u\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ unsigned decimal number
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ o\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ unsigned octal number
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ x\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ unsigned hexadecimal number (0-9, a-f)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ X\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ unsigned hexadecimal number (0-9, A-F)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ c\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ character
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ s\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ string (generic pointer)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ p\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ generic pointer (I:data/idata, C:code, X:xdata, P:paged)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ f\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ float (still to be implemented)
+\layout Standard
-\protected_separator
+Also contains a very simple version of printf (
+\series bold
+printf_small
+\series default
+).
+ This simplified version of printf supports only the following formats.
+\layout Standard
-\protected_separator
-\protected_separator
+\size scriptsize
+\bar under
+format\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+output\SpecialChar ~
+type\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+argument-type
+\bar default
+
+\series bold
+\size default
-\protected_separator
+\newline
-\protected_separator
+\series default
+\size scriptsize
+%d \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+decimal \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ int
+\newline
+%ld\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+decimal\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+long
+\newline
+%hd\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+decimal\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+short/char
+\newline
+%x\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+hexadecimal\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+int
+\newline
+%lx\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+hexadecimal\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+long
+\newline
+%hx\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+hexadecimal\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+short/char
+\newline
+%o\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+octal\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+int
+\newline
+%lo\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+octal\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+long
+\newline
+%ho\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+octal\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+short/char
+\newline
+%c\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+character\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+char/short
+\newline
+%s\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+character\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_generic pointer
+\layout Standard
-\protected_separator
+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).
+ When using the %s format the string / pointer should be cast to a generic
+ pointer.
+ eg.
+\layout Standard
-\protected_separator
-\protected_separator
+\size scriptsize
+printf_small(
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+my str %s, my int %d
+\backslash
+n
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+,(char _generic *)mystr,myint);
+\layout Itemize
-\protected_separator
-\protected_separator
+\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'
+\begin_deeper
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+va_list, va_start, va_arg, va_end.
+\end_deeper
+\layout Itemize
-\protected_separator
-\protected_separator
+\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.
+ 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.
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+\size large
+stdlib.h
+\series default
+\size default
+ - contains the following functions.
+\begin_deeper
+\layout Standard
-\protected_separator
-\protected_separator
-given or display frame arg
-\newline
-;;
-\protected_separator
+\size footnotesize
+atoi, atol.
+\end_deeper
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+\size large
+string.h
+\series default
+\size default
+- contains the following functions.
+\begin_deeper
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn,
+ strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.
+\end_deeper
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+\size large
+ctype.h
+\series default
+\size default
+ - contains the following routines.
+\begin_deeper
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
+ isxdigit, isalnum, isalpha.
+\end_deeper
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+\size large
+malloc.h
+\series default
+\size default
+ - 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
-\protected_separator
-\protected_separator
+\size scriptsize
+//Example:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ #define DYNAMIC_MEMORY_SIZE 0x2000
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .....
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ unsigned char xdata * current_buffer;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .....
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ void main(void)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+//\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //Now it's possible to use malloc.
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ current_buffer = malloc(0x100);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ //
+\end_deeper
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+\size large
+serial.h
+\series default
+\size default
+ - 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
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+serial.h
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ MUST be included in the file containing the 'main' function.
+\layout Itemize
-\protected_separator
-\protected_separator
+\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.
+ Please see documentation in file SDCCDIR/sdcc51lib/ser.c
+\layout Itemize
-\protected_separator
-\protected_separator
+\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.
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+\size large
+reg51.h
+\series default
+\size default
+ - contains register definitions for a standard 8051
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+\size large
+reg552.h
+\series default
+\size default
+- contains register definitions for 80C552.
+\layout Itemize
-\protected_separator
-\protected_separator
+\series bold
+\size large
+float.h
+\series default
+\size default
+ - contains min, max and other floating point related stuff.
+\layout Standard
-\protected_separator
+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
-\protected_separator
+Have not had time to do the more involved routines like printf, will get
+ to them shortly.
+\layout Subsection
-\protected_separator
+Interfacing with Assembly Routines
+\layout Subsection
-\protected_separator
+Global Registers used for Parameter Passing
+\layout Standard
-\protected_separator
+By default the compiler uses the global registers
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+DPL,DPH,B,ACC
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ 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).
+
+\layout Subsubsection
-\protected_separator
+Assembler Routine(non-reentrant)
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+extern int asm_func( unsigned short, unsigned short);
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+\SpecialChar ~
-\protected_separator
+\newline
+int c_func (unsigned short i, unsigned short j)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ return asm_func(i,j);
+\newline
+}
+\size default
+
+\size scriptsize
-\protected_separator
+\newline
+int main()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c_func(10,9);
+\newline
+}
+\layout Standard
-\protected_separator
+The corresponding assembler function is:-
+\layout Standard
-\protected_separator
-\protected_separator
-buffer point
+\size scriptsize
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .globl _asm_func_PARM_2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .globl _asm_func
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .area OSEG
+\newline
+_asm_func_PARM_2:\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .ds\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .area CSEG
\newline
-;; !
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
-
-\protected_separator
+_asm_func:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ a,dpl
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ add\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ a,_asm_func_PARM_2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ dpl,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ret
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
+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 first parameter is passed in
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+dpl
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ for One bye parameter,
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+dptr
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ if two bytes,
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
+b,dptr
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ for three bytes and
+\begin_inset Quotes eld
+\end_inset
-\protected_separator
- sdcdbsrc-goto-sdcdb
-\protected_separator
+acc,b,dptr
+\begin_inset Quotes erd
+\end_inset
-\protected_separator
+ for four bytes, the
+\family typewriter
+\series bold
+\size footnotesize
+varaible name for the second parameter will be _<function_name>_PARM_2.
+\layout Standard
-\protected_separator
+Assemble the assembler routine with the following command.
+\layout Standard
-\protected_separator
+asx8051 -losg asmfunc.asm
+\layout Standard
-\protected_separator
+Then compile and link the assembler routine to the C source file with the
+ following command,
+\layout Standard
-\protected_separator
+sdcc cfunc.c asmfunc.rel
+\layout Subsubsection
-\protected_separator
+Assembler Routine(reentrant)
+\layout Standard
-\protected_separator
+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
-\protected_separator
-\protected_separator
-Goto the SDCDB output buffer
-\newline
-;; p
-\protected_separator
+\size footnotesize
+extern int asm_func( unsigned short, unsigned short);
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+\SpecialChar ~
-\protected_separator
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+int c_func (unsigned short i, unsigned short j) reentrant
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ return asm_func(i,j);
+\newline
+}
+\size default
+
+\size scriptsize
-\protected_separator
+\newline
+int main()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c_func(10,9);
+\newline
+}
+\layout Standard
-\protected_separator
+The corresponding assembler routine is.
+\layout Standard
-\protected_separator
-\protected_separator
+\size scriptsize
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .globl _asm_func
+\newline
+_asm_func:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ push\SpecialChar ~
+ _bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ _bp,sp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+ r2,dpl
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ a,_bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ clr\SpecialChar ~
+ c
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ add\SpecialChar ~
+ a,#0xfd
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ r0,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ add\SpecialChar ~
+ a,#0xfc
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ r1,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ a,@r0
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ add\SpecialChar ~
+ a,r2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ dph,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ sp,_bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ pop\SpecialChar ~
+ _bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ret
+\layout Standard
-\protected_separator
+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.
+\layout Subsection
-\protected_separator
+With --noregparms Option
+\layout Standard
-\protected_separator
+When the source is compiled with --noregparms option , space is allocated
+ for each of the parameters passed to a routine.
+\layout Subsubsection
-\protected_separator
- sdcdb-print-c-sexp
-\protected_separator
+Assembler Routine Non-reentrant
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+extern int asm_func( unsigned short, unsigned short);
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+\SpecialChar ~
-\protected_separator
+\newline
+int c_func (unsigned short i, unsigned short j)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ return asm_func(i,j);
+\newline
+}
+\size default
+
+\size scriptsize
-\protected_separator
+\newline
+int main()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c_func(10,9);
+\newline
+}
+\layout Standard
-\protected_separator
+The corresponding assembler function is:-
+\layout Standard
-\protected_separator
-\protected_separator
-SDCDB print command for data at
+\size scriptsize
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .globl _asm_func_PARM_1
\newline
-;;
-\protected_separator
-
-\protected_separator
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .globl _asm_func_PARM_2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .globl _asm_func
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .area OSEG
+\newline
+_asm_func_PARM_1:\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .ds\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 1
+\newline
+_asm_func_PARM_2:\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .ds\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .area CSEG
+\newline
+_asm_func:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ a,_asm_func_PARM_1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ add\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ a,_asm_func_PARM_2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ dpl,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ret
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
+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.
+ i.e.
+ the
+\family typewriter
+\series bold
+\size footnotesize
+left-most parameter name will be _<function_name>_PARM_1.
+\layout Standard
-\protected_separator
+Assemble the assembler routine with the following command.
+\layout Standard
-\protected_separator
+asx8051 -losg asmfunc.asm
+\layout Standard
-\protected_separator
+Then compile and link the assembler routine to the C source file with the
+ following command,
+\layout Standard
-\protected_separator
+sdcc cfunc.c asmfunc.rel
+\layout Subsubsection
-\protected_separator
+Assembler Routine(reentrant)
+\layout Standard
-\protected_separator
+In this case the parameters will be passed on the stack , the parameters
+ are pushed from right to left i.e.
+ after the call the left most parameter will be on the top of the stack.
+ Here is an example.
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+extern int asm_func( unsigned short, unsigned short);
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+\SpecialChar ~
-\protected_separator
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+int c_func (unsigned short i, unsigned short j) reentrant
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ return asm_func(i,j);
+\newline
+}
+\size default
+
+\size scriptsize
-\protected_separator
+\newline
+int main()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c_func(10,9);
+\newline
+}
+\layout Standard
-\protected_separator
+The corresponding assembler routine is.
+\layout Standard
-\protected_separator
-\protected_separator
+\size scriptsize
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ .globl _asm_func
+\newline
+_asm_func:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ push\SpecialChar ~
+ _bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ _bp,sp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ a,_bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ clr\SpecialChar ~
+ c
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ add\SpecialChar ~
+ a,#0xfd
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ r0,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ a,_bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ clr\SpecialChar ~
+ c
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ add\SpecialChar ~
+ a,#0xfc
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ r1,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ a,@r0
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ add\SpecialChar ~
+ a,@r1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ dph,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ sp,_bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ pop\SpecialChar ~
+ _bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ret
+\layout Standard
-\protected_separator
+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.
+\layout Subsection
-\protected_separator
+External Stack
+\layout Standard
-\protected_separator
+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).
+\layout Standard
-\protected_separator
+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.
+\layout Subsection
-\protected_separator
+ANSI-Compliance
+\layout Standard
-\protected_separator
+Deviations from the compliancy.
+\layout Enumerate
-\protected_separator
+functions are not always reentrant.
+\layout Enumerate
-\protected_separator
+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.
+\begin_deeper
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+eg
+\end_deeper
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+struct s { ...
+ };
+\newline
+struct s s1, s2;
+\newline
+foo()
+\newline
+{
+\newline
+...
+
+\newline
+s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
+\newline
+...
+
+\newline
+}
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
+ ANSI */
+\newline
+{
+\newline
+struct s rets;
+\newline
+...
+
+\newline
+return rets;/* is invalid in SDCC although allowed in ANSI */
+\newline
+}
+\layout Enumerate
-\protected_separator
+'long long' (64 bit integers) not supported.
+\layout Enumerate
-\protected_separator
+'double' precision floating point not supported.
+\layout Enumerate
-\protected_separator
+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.
+
+\layout Enumerate
-\protected_separator
+No support for
+\emph on
+setjmp
+\emph default
+ and
+\emph on
+longjmp
+\emph default
+ (for now).
+\layout Enumerate
-\protected_separator
+Old K&R style function declarations are NOT allowed.
+\layout Standard
-\protected_separator
-\protected_separator
- buffer point
+\size footnotesize
+foo( i,j) /* this old style of function declarations */
+\newline
+int i,j; /* are valid in ANSI ..
+ not valid in SDCC */
+\newline
+{
+\newline
+...
+
\newline
-;; g
-\protected_separator
+}
+\layout Enumerate
-\protected_separator
+functions declared as pointers must be dereferenced during the call.
+\begin_deeper
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+int (*foo)();
+\end_deeper
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+\SpecialChar ~
+ \SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+/* has to be called like this */
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+(*foo)();/* ansi standard allows calls to be made like 'foo()' */
+\layout Subsection
-\protected_separator
+Cyclomatic Complexity
+\layout Standard
-\protected_separator
+Cyclomatic complexity of a function is defined as the number of independent
+ paths the program can take during execution of the function.
+ This is an important number since it defines the number test cases you
+ have to generate to validate the function .
+ The accepted industry standard for complexity number is 10, if the cyclomatic
+ complexity reported by SDCC exceeds 10 you should think about simplification
+ of the function logic.
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
-\protected_separator
+\size small
+complexity = (number of edges in control flow graph) -
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+(number of nodes in control flow graph) + 2;
+\layout Standard
-\protected_separator
+Having said that the industry standard is 10, you should be aware that in
+ some cases it may unavoidable to have a complexity level of less than 10.
+ For example if you have switch statement with more than 10 case labels,
+ each case label adds one to the complexity level.
+ The complexity level is by no means an absolute measure of the algorithmic
+ complexity of the function, it does however provide a good starting point
+ for which functions you might look at for further optimization.
+\layout Section
-\protected_separator
+TIPS
+\layout Standard
-\protected_separator
- sdcdbsrc-goto-sdcdb
-\protected_separator
+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.
+\layout Itemize
-\protected_separator
+Use the smallest data type to represent your data-value.
+ If it is known in advance that the value is going to be less than 256 then
+ use a 'short' or 'char' instead of an 'int'.
+\layout Itemize
-\protected_separator
+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.
+\layout Itemize
-\protected_separator
+NEVER jump into a LOOP.
+\layout Itemize
-\protected_separator
+Declare the variables to be local whenever possible, especially loop control
+ variables (induction).
+\layout Itemize
-\protected_separator
+Since the compiler does not do implicit integral promotion, the programmer
+ should do an explicit cast when integral promotion is required.
+\layout Itemize
-\protected_separator
+Reducing the size of division , multiplication & modulus operations can
+ reduce code size substantially.
+ Take the following code for example.
+\begin_deeper
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+foobar( unsigned int p1, unsigned char ch)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+unsigned char ch1 = p1 % ch ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
-\protected_separator
-Goto the SDCDB output buffer
\newline
-;; t
-\protected_separator
+}
+\layout Standard
-\protected_separator
+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
+\layout Standard
-\protected_separator
-\protected_separator
+\size footnotesize
+foobar( unsigned int p1, unsigned char ch)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+unsigned char ch1 = (unsigned char)p1 % ch ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
-\protected_separator
+\newline
+}
+\layout Standard
-\protected_separator
+It would substantially reduce the code generated (future versions of the
+ compiler will be smart enough to detect such optimization oppurtunities).
+\end_deeper
+\layout Standard
-\protected_separator
-\protected_separator
+\series bold
+Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
+\layout Standard
-\protected_separator
+The 8051 family of micro controller have a minimum of 128 bytes of internal
+ memory which is structured as follows
+\layout Standard
-\protected_separator
+- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
+
+\layout Standard
-\protected_separator
+- Bytes 20-2F - 16 bytes to hold 128 bit variables and
+\layout Standard
-\protected_separator
+- Bytes 30-7F - 60 bytes for general purpose use.
+\layout Standard
-\protected_separator
+Normally the SDCC compiler will only utilise the first bank of registers,
+ but it is possible to specify that other banks of registers should be used
+ in interrupt routines.
+ By default, the compiler will place the stack after the last bank of used
+ registers, i.e.
+ if the first 2 banks of registers are used, it will position the base of
+ the internal stack at address 16 (0X10).
+ This implies that as the stack grows, it will use up the remaining register
+ banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
+ general purpose use.
+\layout Standard
-\protected_separator
- sdcdbsrc-mode
-\protected_separator
+By default, the compiler uses the 60 general purpose bytes to hold "near
+ data".
+ The compiler/optimiser may also declare some Local Variables in this area
+ to hold local data.
+
+\layout Standard
-\protected_separator
+If any of the 128 bit variables are used, or near data is being used then
+ care needs to be taken to ensure that the stack does not grow so much that
+ it starts to over write either your bit variables or "near data".
+ There is no runtime checking to prevent this from happening.
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
+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.
+
+\layout Standard
-\protected_separator
+--stack-loc will allow you specify the start of the stack, i.e.
+ you could start it after any data in the general purpose area.
+ However this may waste the memory not used by the register banks and if
+ the size of the "near data" increases, it may creep into the bottom of
+ the stack.
+\layout Standard
-\protected_separator
+--stack-after-data, similar to the --stack-loc, but it automatically places
+ the stack after the end of the "near data".
+ Again this could waste any spare register space.
+\layout Standard
-\protected_separator
+--data-loc allows you to specify the start address of the near data.
+ This could be used to move the "near data" further away from the stack
+ giving it more room to grow.
+ This will only work if no bit variables are being used and the stack can
+ grow to use the bit variable space.
+\layout Standard
-\protected_separator
+Conclusion.
+\layout Standard
-\protected_separator
+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.
+\layout Standard
-\protected_separator
+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.
+\layout Section
-\protected_separator
+Retargetting for other MCUs.
+\layout Standard
-\protected_separator
+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.
+\layout Enumerate
-\protected_separator
+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.
+\layout Enumerate
-\protected_separator
+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.
+\layout Enumerate
-\protected_separator
+This phase does the bulk of the standard optimizations and is also MCU independe
+nt.
+ This phase can be broken down into several sub-phases.
+\begin_deeper
+\layout Itemize
-\protected_separator
-Toggles Sdcdbsrc mode (turns it off)
-\newline
-;;
-\newline
-;; C-c C-f
-\protected_separator
+Break down intermediate code (iCode) into basic blocks.
+\layout Itemize
-\protected_separator
+Do control flow & data flow analysis on the basic blocks.
+\layout Itemize
-\protected_separator
+Do local common subexpression elimination, then global subexpression elimination
+\layout Itemize
-\protected_separator
+dead code elimination
+\layout Itemize
-\protected_separator
+loop optimizations
+\layout Itemize
-\protected_separator
+if loop optimizations caused any changes then do 'global subexpression eliminati
+on' and 'dead code elimination' again.
+\end_deeper
+\layout Enumerate
-\protected_separator
+This phase determines the live-ranges; by live range I mean those iTemp
+ variables defined by the compiler that still survive after all the optimization
+s.
+ Live range analysis is essential for register allocation, since these computati
+on determines which of these iTemps will be assigned to registers, and for
+ how long.
+\layout Enumerate
-\protected_separator
- sdcdb-finish-from-src
-\protected_separator
+Phase five is register allocation.
+ There are two parts to this process .
+\begin_deeper
+\layout Enumerate
-\protected_separator
+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.
+\layout Enumerate
-\protected_separator
+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.
+\end_deeper
+\layout Enumerate
-\protected_separator
+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.
+\layout Enumerate
-\protected_separator
+As mentioned in the optimization section the peep-hole optimizer is rule
+ based system, which can reprogrammed for other MCUs.
+\layout Section
-\protected_separator
+SDCDB - Source Level Debugger
+\layout Standard
-\protected_separator
+SDCC is distributed with a source level debugger.
+ The debugger uses a command line interface, the command repertoire of the
+ debugger has been kept as close to gdb ( the GNU debugger) as possible.
+ The configuration and build process is part of the standard compiler installati
+on, 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.
+\layout Subsection
-\protected_separator
-SDCDB finish command
-\newline
-;;
-\newline
-;; C-x SPC
-\protected_separator
+Compiling for Debugging
+\layout Standard
-\protected_separator
+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.
+ This .cdb is used by the debugger .
+\layout Subsection
-\protected_separator
+How the Debugger Works
+\layout Standard
-\protected_separator
+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.
+ 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 .
+\layout Subsection
-\protected_separator
+Starting the Debugger
+\layout Standard
-\protected_separator
+The debugger can be started using the following command line.
+ (Assume the file you are debugging has
+\layout Standard
-\protected_separator
+the file name foo).
+\layout Standard
-\protected_separator
- sdcdb-break
-\protected_separator
+>sdcdb foo
+\layout Standard
-\protected_separator
+The debugger will look for the following files.
+\layout Enumerate
-\protected_separator
+foo.c - the source file.
+\layout Enumerate
-\protected_separator
+foo.cdb - the debugger symbol information file.
+\layout Enumerate
-\protected_separator
+foo.ihx - the intel hex format object file.
+\layout Subsection
-\protected_separator
+Command Line Options.
+\layout Itemize
-\protected_separator
+--directory=<source file directory> this option can used to specify the
+ directory search list.
+ The debugger will look into the directory list specified for source , cdb
+ & ihx files.
+ The items in the directory list must be separated by ':' , e.g.
+ if the source files can be in the directories /home/src1 and /home/src2,
+ the --directory option should be --directory=/home/src1:/home/src2 .
+ Note there can be no spaces in the option.
+
+\layout Itemize
-\protected_separator
+-cd <directory> - change to the <directory>.
+\layout Itemize
-\protected_separator
+-fullname - used by GUI front ends.
+\layout Itemize
-\protected_separator
+-cpu <cpu-type> - this argument is passed to the simulator please see the
+ simulator docs for details.
+\layout Itemize
-\protected_separator
+-X <Clock frequency > this options is passed to the simulator please see
+ simulator docs for details.
+\layout Itemize
-\protected_separator
+-s <serial port file> passed to simulator see simulator docs for details.
+\layout Itemize
-\protected_separator
+-S <serial in,out> passed to simulator see simulator docs for details.
+\layout Subsection
-\protected_separator
+Debugger Commands.
+\layout Standard
-\protected_separator
+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
+ for the GNU debugger.
+\layout Subsubsection
-\protected_separator
+break [line | file:line | function | file:function]
+\layout Standard
-\protected_separator
+Set breakpoint at specified line or function.
+\layout Standard
-\protected_separator
-Set break for line with point
+sdcdb>break 100
+\newline
+sdcdb>break foo.c:100
\newline
-;; ESC t
-\protected_separator
+sdcdb>break funcfoo
+\newline
+sdcdb>break foo.c:funcfoo
+\layout Subsubsection
-\protected_separator
+clear [line | file:line | function | file:function ]
+\layout Standard
-\protected_separator
+Clear breakpoint at specified line or function.
+\layout Standard
-\protected_separator
+sdcdb>clear 100
+\newline
+sdcdb>clear foo.c:100
+\newline
+sdcdb>clear funcfoo
+\newline
+sdcdb>clear foo.c:funcfoo
+\layout Subsubsection
-\protected_separator
+continue
+\layout Standard
-\protected_separator
+Continue program being debugged, after breakpoint.
+\layout Subsubsection
-\protected_separator
+finish
+\layout Standard
-\protected_separator
+Execute till the end of the current function.
+\layout Subsubsection
-\protected_separator
+delete [n]
+\layout Standard
-\protected_separator
- sdcdbsrc-mode
-\protected_separator
+Delete breakpoint number 'n'.
+ If used without any option clear ALL user defined break points.
+\layout Subsubsection
-\protected_separator
+info [break | stack | frame | registers ]
+\layout Itemize
-\protected_separator
+info break - list all breakpoints
+\layout Itemize
-\protected_separator
+info stack - show the function call stack.
+\layout Itemize
-\protected_separator
+info frame - show information about the current execution frame.
+\layout Itemize
-\protected_separator
+info registers - show content of all registers.
+\layout Subsubsection
-\protected_separator
+step
+\layout Standard
-\protected_separator
+Step program until it reaches a different source line.
+\layout Subsubsection
-\protected_separator
+next
+\layout Standard
-\protected_separator
+Step program, proceeding through subroutine calls.
+\layout Subsubsection
-\protected_separator
+run
+\layout Standard
-\protected_separator
+Start debugged program.
+\layout Subsubsection
-\protected_separator
+ptype variable
+\layout Standard
-\protected_separator
+Print type information of the variable.
+\layout Subsubsection
-\protected_separator
+print variable
+\layout Standard
-\protected_separator
-Toggle Sdcdbsrc mode
-\newline
-;; ESC m
-\protected_separator
+print value of variable.
+\layout Subsubsection
-\protected_separator
+file filename
+\layout Standard
-\protected_separator
+load the given file name.
+ Note this is an alternate method of loading file for debugging.
+\layout Subsubsection
-\protected_separator
+frame
+\layout Standard
-\protected_separator
+print information about current frame.
+\layout Subsubsection
-\protected_separator
+set srcmode
+\layout Standard
-\protected_separator
+Toggle between C source & assembly source.
+\layout Subsubsection
-\protected_separator
+! simulator command
+\layout Standard
-\protected_separator
+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.
+\layout Subsubsection
-\protected_separator
- sdcdbsrc-srcmode
-\protected_separator
+quit.
+\layout Standard
-\protected_separator
+"Watch me now.
+ Iam going Down.
+ My name is Bobby Brown"
+\layout Subsection
-\protected_separator
+Interfacing with XEmacs.
+\layout Standard
-\protected_separator
+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
+.
+ 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.
+
+\layout Standard
-\protected_separator
+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.
+\layout Itemize
-\protected_separator
+sdcdbsrc-cpu-type '51
+\layout Itemize
-\protected_separator
+sdcdbsrc-frequency '11059200
+\layout Itemize
-\protected_separator
+sdcdbsrc-serial nil
+\layout Standard
-\protected_separator
+The following is a list of key mapping for the debugger interface.
+\layout Standard
-\protected_separator
+\SpecialChar ~
-\protected_separator
+\size scriptsize
-\protected_separator
+\newline
+;; Current Listing ::
+\newline
+;;key\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+binding\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Comment
+\newline
+;;---\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+-------\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+-------
+\newline
+;;
+\newline
+;; n\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-next-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB next command
+\newline
+;; b\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-back-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB back command
+\newline
+;; c\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-cont-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB continue command
+\newline
+;; s\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-step-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB step command
+\newline
+;; ?\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-whatis-c-sexp\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB ptypecommand for data at
+\newline
+;;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ buffer point
+\newline
+;; x\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-delete\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB Delete all breakpoints if no arg
+\newline
+;;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+given or delete arg (C-u arg x)
+\newline
+;; m\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-frame\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB Display current frame if no arg,
+\newline
+;;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+given or display frame arg
+\newline
+;;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+buffer point
+\newline
+;; !\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-goto-sdcdb\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Goto the SDCDB output buffer
+\newline
+;; p\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-print-c-sexp\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB print command for data at
+\newline
+;;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ buffer point
+\newline
+;; g\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-goto-sdcdb\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Goto the SDCDB output buffer
+\newline
+;; t\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-mode\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Toggles Sdcdbsrc mode (turns it off)
+\newline
+;;
+\newline
+;; C-c C-f\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-finish-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB finish command
+\newline
+;;
+\newline
+;; C-x SPC\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-break\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Set break for line with point
+\newline
+;; ESC t\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-mode\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Toggle Sdcdbsrc mode
+\newline
+;; ESC m\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-srcmode\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
Toggle list mode
\newline
;;
\layout Section
-Conclusion
-\begin_inset LatexCommand \label{Conclusion}
-
-\end_inset
-
+Other Processors
+\layout Subsection
+The Z80 and gbz80 port
\layout Standard
-SDCC is a large project , the compiler alone (without the Assembler Package
- , Preprocessor & garbage collector) is about 40,000 lines of code (blank
- stripped).
- As with any project of this size there are bound to be bugs, I am more
- than willing to work to fix these bugs , of course all the source code
- is included with the package.
-
+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.
\layout Standard
-Where does it go from here ? I am planning to target the Atmel AVR 8-bit
- MCUs which seems to have a lot of users.
- I am also planning to include an alias analysis system with this compiler
- (it does not currently have one).
+As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
+ The stack frame is similar to that generated by the IAR Z80 compiler.
+ IX is used as the base pointer, HL is used as a temporary register, and
+ BC and DE are available for holding varibles.
+ IY is currently unusued.
+ Return values are stored in HL.
+ One bad side effect of using IX as the base pointer is that a functions
+ stack frame is limited to 127 bytes - this will be fixed in a later version.
\layout Section
-Acknowledgments
-\begin_inset LatexCommand \label{Acknowledgements}
+Support
+\layout Standard
-\end_inset
+SDCC has grown to be large project, the compiler alone (without the Assembler
+ Package, Preprocessor) is about 40,000 lines of code (blank stripped).
+ The open source nature of this project is a key to its continued growth
+ and support.
+ You gain the benefit and support of many active software developers and
+ end users.
+ Is SDCC perfect? No, that's why we need your help.
+ The developers take pride in fixing reported bugs.
+ You can help by reporting the bugs and helping other SDCC users.
+ There are lots of ways to contribute, and we encourage you to take part
+ in making SDCC a great software package.
+\layout Subsection
+Reporting Bugs
+\layout Standard
+
+Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd
+cc@sdcc.sourceforge.net'.
+ Bugs will be fixed ASAP.
+ When reporting a bug, it is very useful to include a small test program
+ which reproduces the problem.
+ If you can isolate the problem by looking at the generated assembly code,
+ this can be very helpful.
+ Compiling your program with the --dumpall option can sometimes be useful
+ in locating optimization problems.
+\layout Subsection
+Acknowledgments
\layout Standard
+Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code generator,
+ Debugger, AVR port
+\newline
Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX & ASLINK.
-\layout Standard
-
+\newline
John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for 8051
-\layout Standard
-
+\newline
Dmitry S.
Obukhov (dso@usa.net) - malloc & serial i/o routines.
-\layout Standard
-
+\newline
Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware simulator
-\layout Standard
-
-Jans J Boehm(boehm@sgi.com) and Alan J Demers - Conservative garbage collector
- for C & C++.
-\layout Standard
-
+\newline
Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience and support.
-\layout Standard
-
+\newline
Unknown - for the GNU C - preprocessor.
-\layout Section
-
-Appendix A: The Z80 and gbz80 port
-\layout Standard
+\newline
+Michael Hope - The Z80 and Z80GB port, 186 development
+\newline
+Kevin Vigor - The DS390 port.
+\newline
+Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
+\newline
+Scott Datallo - PIC port.
+\newline
+(Thanks to all the other volunteer developers who have helped with coding,
+ testing, web-page creation, distribution sets, etc.
+ You know who you are :-)
+\newline
-2.2.0 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.
\layout Standard
-As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
- The stack frame is similar to that generated by the IAR Z80 compiler.
- IX is used as the base pointer, HL is used as a temporary register, and
- BC and DE are available for holding varibles.
- IY is currently unusued.
- Return values are stored in HL.
- One bad side effect of using IX as the base pointer is that a functions
- stack frame is limited to 127 bytes - this will be fixed in a later version.bc
+This document initially written by Sandeep Dutta
\layout Standard
-9
+All product names mentioned herein may be trademarks of their respective
+ companies.
+
\layout Standard
SDCC Compiler User Guide
-Sandeep Dutta (sandeep.dutta@usa.net)
+Table of Contents
1 Introduction
+ 1.1 About SDCC
+ 1.2 Open Source
+ 1.3 System Requirements
+ 1.4 Other Resources
+2 Installation
+ 2.1 Linux/Unix Installation
+ 2.2 Windows Installation
+ 2.2.1 Windows Install Using a Binary Package
+ 2.2.2 Windows Install Using Cygwin
+ 2.3 Testing out the SDCC Compiler
+ 2.4 Install Trouble-shooting
+ 2.4.1 SDCC cannot find libraries or header files.
+ 2.4.2 SDCC does not compile correctly.
+ 2.4.3 What the ./configure does
+ 2.4.4 What the make does.
+ 2.4.5 What the make install command does.
+ 2.5 Additional Information for Windows Users
+ 2.5.1 Getting started with Cygwin
+ 2.5.2 Running SDCC as Native Compiled Executables
+ 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
+3 Using SDCC
+ 3.1 Compiling
+ 3.1.1 Single Source File Projects
+ 3.1.2 Projects with Multiple Source Files
+ 3.1.3 Projects with Additional Libraries
+ 3.2 Command Line Options
+ 3.2.1 Processor Selection Options
+ 3.2.2 Path, Lib and Define Options
+ 3.2.3 MCS51 Options
+ 3.2.4 Optimization Options
+ 3.2.5 DS390 Options
+ 3.2.6 Other Options
+ 3.2.7 Intermediate Dump Options
+ 3.3 MCS51 Storage Class Language Extensions
+ 3.3.1 xdata
+ 3.3.2 data
+ 3.3.3 idata
+ 3.3.4 bit
+ 3.3.5 sfr / sbit
+ 3.4 Pointers
+ 3.5 Parameters & Local Variables
+ 3.6 Overlaying
+ 3.7 Critical Functions
+ 3.8 Absolute Addressing
+ 3.9 Interrupt Service Routines
+ 3.10 Startup Code
+ 3.11 Inline Assembler Code
+ 3.12 int(16 bit) and long (32 bit ) Support
+ 3.13 Floating Point Support
+ 3.14 MCS51 Memory Models
+ 3.15 Flat 24 bit Addressing Model
+ 3.16 Defines Created by the Compiler
+4 SDCC Technical Data
+ 4.1 Optimizations
+ 4.1.1 Sub-expression Elimination
+ 4.1.2 Dead-Code Elimination
+ 4.1.3 Copy-Propagation
+ 4.1.4 Loop Optimizations
+ 4.1.5 Loop Reversing:
+ 4.1.6 Algebraic Simplifications
+ 4.1.7 'switch' Statements
+ 4.1.8 Bit-shifting Operations.
+ 4.1.9 Bit-rotation
+ 4.1.10 Highest Order Bit
+ 4.1.11 Peep-hole Optimizer
+ 4.2 Pragmas
+ 4.3 Library Routines
+ 4.4 Interfacing with Assembly Routines
+ 4.5 Global Registers used for Parameter Passing
+ 4.5.1 Assembler Routine(non-reentrant)
+ 4.5.2 Assembler Routine(reentrant)
+ 4.6 With --noregparms Option
+ 4.6.1 Assembler Routine Non-reentrant
+ 4.6.2 Assembler Routine(reentrant)
+ 4.7 External Stack
+ 4.8 ANSI-Compliance
+ 4.9 Cyclomatic Complexity
+5 TIPS
+6 Retargetting for other MCUs.
+7 SDCDB - Source Level Debugger
+ 7.1 Compiling for Debugging
+ 7.2 How the Debugger Works
+ 7.3 Starting the Debugger
+ 7.4 Command Line Options.
+ 7.5 Debugger Commands.
+ 7.5.1 break [line | file:line | function | file:function]
+ 7.5.2 clear [line | file:line | function | file:function ]
+ 7.5.3 continue
+ 7.5.4 finish
+ 7.5.5 delete [n]
+ 7.5.6 info [break | stack | frame | registers ]
+ 7.5.7 step
+ 7.5.8 next
+ 7.5.9 run
+ 7.5.10 ptype variable
+ 7.5.11 print variable
+ 7.5.12 file filename
+ 7.5.13 frame
+ 7.5.14 set srcmode
+ 7.5.15 ! simulator command
+ 7.5.16 quit.
+ 7.6 Interfacing with XEmacs.
+8 Other Processors
+ 8.1 The Z80 and gbz80 port
+9 Support
+ 9.1 Reporting Bugs
+ 9.2 Acknowledgments
-SDCC is a Free ware , retargettable, optimizing ANSI-C compiler. The
-current version targets Intel 8051 based MCUs, it can be retargetted
-for other 8 bit MCUs or PICs. The entire source code for the compiler
-is distributed under GPL. SDCC used ASXXXX & ASLINK a Free ware, retargettable
-assembler & linker. SDCC has extensive MCU (8051) specific language
-extensions, which lets it utilize the underlying hardware effectively.
-The front-end (parser) will be enhanced to handle language extensions
-for other MCUs as and when they are targetted. In addition to the
-MCU Specific optimizations SDCC also does a host of standard optimizations
-like 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. For the back-end SDCC uses a global
-register allocation scheme which should be well suited for other 8
-bit MCUs , the peep hole optimizer uses a rule based substitution
-mechanism which is MCU independent. Supported data-types are short
-(8 bits, 1 byte), char (8 bits, 1 byte), int (16 bits, 2 bytes ),
-long (32 bit, 4 bytes) & 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 also be called. SDCC also provides
-an option to report the relative complexity of a function, these functions
-can then be further optimized , or hand coded in assembly if need
-be. SDCC also comes with a companion source level debugger SDCDB,
-the debugger currently uses S51 a freeware simulator for 8051, it
-can be easily modified to use other simulators. The latest version
-can be downloaded from http://www.geocities.com/ResearchTriangle/Forum/1353
-
-All packages used in this compiler system are opensource (freeware);
-source code for all the sub-packages ( asxxxx assembler/linker , pre-processor
-and gc a conservative garbage collector) are distributed with the
-package. Documentation was created 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 as published
-by the Free Software Foundation; either version 2, or (at your option)
-any later version. This program is distributed in the hope that it
-will be useful, but WITHOUT ANY WARRANTY; without even the implied
-warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
-the GNU General Public License for more details. You should have received
-a copy of the GNU General Public License along with this program;
-if not, write to the Free Software Foundation, 59 Temple Place - Suite
-330, Boston, MA 02111-1307, USA. In other words, you are welcome to
-use, share and improve this program. You are forbidden to forbid anyone
-else to use, share and improve what you give them. Help stamp out
-software-hoarding!
-
-2 Installation \label{Installation}
-
-What you need before you start installation of SDCC ? A C Compiler,
-not just any C Compiler, gcc to be exact, you can get adventurous
-and try another compiler , I HAVEN'T tried it. GCC is free , and is
-available for almost all major platforms, if you are using linux you
-probably already have it, if you are using Windows 95/NT go to www.cygnus.com
-and download CYGWIN32 you will need the full development version of
-their tool (full.exe), follow their instructions for installation
-(this is also free and is very easy to install), Windows 95/NT users
-be aware that the compiler runs substantially slower on the Windows
-platform, I am not sure why.
-
-After you have installed gcc you are ready to build the compiler (sorry
-no binary distributions yet). SDCC is native to Linux but can be ported
-to any platform on which GCC is available . Extract the source file
-package (.zip or .tar.gz) into some directory , which we shall refer
-to as SDCCDIR from now on.
-2.1 Components of SDCC\label{Components}
-2.1.1 gc ( a conservative garbage collector)
+1 Introduction
-SDCC relies on this component to do all the memory management, this
-excellent package is copyrighted by Jans J Boehm(boehm@sgi.com) and
-Alan J Demers but can be used with minimum restrictions. The GC source
-will be extracted into the directory SDCCDIR/gc.
+1.1 About SDCC
+
+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,
+etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51
+variant. It can be retargetted for other microprocessors,
+support for PIC, AVR and 186 is under development. The entire
+source code for the compiler is distributed under GPL. SDCC
+uses ASXXXX & ASLINK, a Freeware, retargettable assembler
+& linker. SDCC has extensive language extensions suitable
+for utilizing various microcontrollers underlying hardware
+effectively. In addition to the MCU specific optimizations
+SDCC also does a host of standard optimizations like 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. For
+the back-end SDCC uses a global register allocation scheme
+which should be well suited for other 8 bit MCUs. The peep
+hole optimizer uses a rule based substitution mechanism
+which is MCU independent. Supported data-types are short
+(8 bits, 1 byte), char (8 bits, 1 byte), int (16 bits, 2
+bytes ), long (32 bit, 4 bytes) & 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 also be called. SDCC also provides an option
+to report the relative complexity of a function, these functions
+can then be further optimized, or hand coded in assembly
+if need be. SDCC also comes with a companion source level
+debugger SDCDB, the debugger currently uses ucSim a freeware
+simulator for 8051 and other micro-controllers. The latest
+version can be downloaded from [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).
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version
+2, or (at your option) any later version. This program is
+distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+Public License for more details. You should have received
+a copy of the GNU General Public License along with this
+program; if not, write to the Free Software Foundation,
+59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+In other words, you are welcome to use, share and improve
+this program. You are forbidden to forbid anyone else to
+use, share and improve what you give them. Help stamp out
+software-hoarding!
-2.1.2 cpp ( C-Preprocessor)
+1.3 System Requirements
-The preprocessor is extracted into the directory SDCCDIR/cpp, it is
-a modified version of the GNU preprocessor.
+What do you need before you start installation of SDCC? A
+computer, and a desire to compute. The preferred method
+of installation is to compile SDCC from source using GNU
+GCC and make. For Windows some pre-compiled binary distributions
+are available for your convenience. You should have some
+experience with command line tools and compiler use.
+
+1.4 Other Resources
+
+The SDCC home page at [http://sdcc.sourceforge.net/]
+is a great place to find distribution sets. You can also
+find links to the user mailing lists that offer help or
+discuss SDCC with other SDCC users. Web links to other SDCC
+related sites can also be found here. This document can
+be found in the DOC directory of the source package as a
+text or HTML file. Some of the other tools(simulator and
+assembler) included with SDCC contain their own documentation
+and can be found in the source distribution. If you want
+the latest unreleased software, the complete source package
+is available directly by anonymous CVS on www.sourceforge.net.
+
+2 Installation
+
+2.1 Linux/Unix Installation
+
+1. Download the source package, it will be named something
+ like sdcc-2.x.x.tgz.
+
+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,
+ 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.
+
+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.
+
+2.2 Windows Installation
+
+For installation under Windows you first need to pick between
+a pre-compiled binary package, or installing the source
+package along with the Cygwin package. The binary package
+is the quickest to install, while the Cygwin package includes
+all of the open source power tools used to compile the complete
+SDCC source package in the Windows environment. If you are
+not familiar with the Unix command line environment, you
+may want to read the section on additional information for
+Windows users prior to your initial installation.
+
+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
+ 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.
+
+2. 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%
+
+3. 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
+
+2.2.2 Windows Install Using Cygwin
+
+1. Download and install the cygwin package from the redhat
+ 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
+ whole thing).
+
+2. Bring up a Unix/Bash command line terminal from the Cygwin
+ menu.
+
+3. Follow the instructions in the preceding Linux/Unix installation
+ section.
+
+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.
+
+SDCC binaries are commonly installed in a directory arrangement
+like this:
+
++--------------------------------+-------------------------------------------+
+| /usr/local/bin | Holds executables(sdcc, s51, aslink, ...) |
++--------------------------------+-------------------------------------------+
++--------------------------------+-------------------------------------------+
+| /usr/local/share/sdcc/lib | Holds common C libraries |
++--------------------------------+-------------------------------------------+
+| /usr/local/share/sdcc/include | Holds common C header files |
++--------------------------------+-------------------------------------------+
+
+
+Make sure the compiler works on a very simple example. Type
+in the following test.c program using your favorite editor:
-2.1.3 asxxxx & aslink ( The assembler and Linkage Editor)
+main()
+{ int i;
+i = 0;
+i += 10;
+}
-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.
-2.1.4 SDCC - The compiler.
+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),
+then the problem is most likely that sdcc cannot find the
+usr/local/share/sdcc/lib/small directory(see the Install
+trouble-shooting section for suggestions).
+
+The final test is to ensure sdcc can use the standard header
+files and libraries. Edit test.c and change it to the following:
+
+#include <string.h>
+main()
+{ char str1[10];
+strcpy(str1, "testing");
+}
-This is the actual compiler, it uses gc and invokes the assembler and
-linkage editor. All files with the prefix SDCC are part of the compiler
-and is extracted into the the directory SDCCDIR.
+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
+
+2.4.1 SDCC cannot find libraries or header files.
+
+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
+
+2.4.2 SDCC does not compile correctly.
+
+A few things to try include starting from scratch by unpacking
+the .tgz source package again in an empty directory. If
+this doesn't work, you could try downloading a different
+version. If this doesn't work, you can re-direct the install
+messages by doing the following:
+
+$./make > dump.txt 2>&1
+
+After this you can examine the dump.txt files to locate the
+problem. Or these messages can be attached to an email that
+could be helpful when requesting help from the mailing list.
+
+2.4.3 What the "./configure"
+ does
+
+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.
+
+2.4.4 What the "make" does.
+
+This runs the GNU make tool, which automatically compiles
+all the source packages into the final installed binary
+executables.
+
+2.4.5 What the "make install"
+ command does.
+
+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.
+
+2.5 Additional Information for Windows Users
+
+The standard method of installing on a Unix system involves
+compiling the source package. This is easily done under
+Unix, but under Windows it can be a more difficult process.
+The Cygwin is a large package to download, and the compilation
+runs considerably slower under Windows due to the overhead
+of the Cygwin tool set. An alternative is to install a pre-compiled
+Windows binary package. There are various trade-offs between
+each of these methods.
+
+The Cygwin package allows a Windows user to run a Unix command
+line interface(bash shell) and also implements a Unix like
+file system on top of Windows. Included are many of the
+famous GNU software development tools which can augment
+the SDCC compiler.This is great if you have some experience
+with Unix command line tools and file system conventions,
+if not you may find it easier to start by installing a binary
+Windows package. The binary packages work with the Windows
+file system conventions.
+
+2.5.1 Getting started with Cygwin
+
+SDCC is typically distributed as a tarred/gzipped file(.tgz).
+This is a packed file similar to a .zip file. Cygwin includes
+the tools you will need to unpack the SDCC distribution(tar
+and gzip). To unpack it, simply follow the instructions
+under the Linux/Unix install section. Before you do this
+you need to learn how to start a cygwin shell and some of
+the basic commands used to move files, change directory,
+run commands and so on. The change directory command is
+"cd", the move command is "mv".
+To print the current working directory, type "pwd".
+To make a directory, use "mkdir".
+
+There are some basic differences between Unix and Windows
+file systems you should understand. When you type in directory
+paths, Unix and the Cygwin bash prompt uses forward slashes
+'/' between directories while Windows traditionally uses
+'\' backward slashes. So when you work at the Cygwin bash
+prompt, you will need to use the forward '/' slashes. Unix
+does not have a concept of drive letters, such as "c:",
+instead all files systems attach and appear as directories.
+
+2.5.2 Running SDCC as Native Compiled Executables
+
+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.
+
+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.
+
+2.6 SDCC on Other Platforms
+
+* FreeBSD and other non-GNU Unixes - Make sure the GNU make
+ is installed as the default make tool.
+
+* 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.
+
+2.7 Advanced Install Options
+
+The "configure" command has several options.
+The most commonly used option is --prefix=<directory name>,
+where <directory name> is the final location for the sdcc
+executables and libraries, (default location is /usr/local).
+The installation process will create the following directory
+structure under the <directory name> specified.
+
+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
-2.1.5 S51 - Simulator
+The command
-Version 2.1.8 onwards contains s51 a freeware , opensource simulator
-developed by Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu>. The
-executable is built as part of build process, for more information
-visit Daniel's website at <http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51/>.
+'./configure --prefix=/usr/local"
-2.1.6 SDCDB - Source level Debugger.
+will configure the compiler to be installed in directory
+/usr/local/bin.
-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.
+2.8 Components of SDCC
-2.2 Installation for Version <= 2.1.7
+SDCC is not just a compiler, but a collection of tools by
+various developers. These include linkers, assemblers, simulators
+and other components. Here is a summary of some of the components.
+Note that the included simulator and assembler have separate
+documentation which you can find in the source package in
+their respective directories. As SDCC grows to include support
+for other processors, other packages from various developers
+are included and may have their own sets of documentation.
-After the package is extracted (Windows 95/NT users start CYGWIN shell),
-change to the directory where you extracted the package and give the
-command.
+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:
-./sdccbuild.sh
+sdcc - The compiler.
-This is a bash shell script, it will compile all the above mentioned
-components and install the executables into the directory SDCCDIR/bin
-make sure you add this directory to your PATH environment variable.
-This script will also compile all the support routines ( library routines
-) using SDCC. The support routines are all developed in C and need
-to be compiled.
+aslink -The linker for 8051 type processors.
-2.3 Installation for Version >= 2.1.8a
+asx8051 - The assembler for 8051 type processors.
-The distribution method from Version 2.1.8a has been changed to be
-conforment with the ``autoconf'' utility. The source is now distributed
-as sdcc-<version number>.tar.gz format , instead of the older .zip
-format. The steps for installation are as follows.
+sdcpp - The C preprocessor.
-2.3.1 Unpack the sources.
+sdcpd - The source debugger.
-This is usually done by the following command ``gunzip -c sdcc-<version
-number>.tar.gz | tar -xv -``
+s51 - The ucSim 8051 simulator.
-2.3.2 Change to the main source directory (usually sdcc or sdcc-<version
- number>)
+linkz80, linkgbz80 - The Z80 and GameBoy Z80 linkers.
-2.3.3 Issue command to configure your system
+as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers.
-The configure command has several options the most commonly used option
-is --prefix=<directory name>, where <directory name> is the final
-location for the sdcc executables and libraries, (default location
-is /usr/local). The installation process will create the following
-directory structure under the <directory name> specified.
+packihx - A tool to pack Intel hex files.
-bin/ - binary exectables (add to PATH environment variable)
-share/
- sdcc51inc/ - include header files
- sdcc51lib/ -
- small/ - Object & Library files for small model library
- large/ - Object & library files for large model library
+As development for other processors proceeds, this list will
+expand to include executables to support processors like
+AVR, PIC, etc.
-The command
+2.8.1 cpp ( C-Preprocessor)
-'./configure --prefix=/usr/local''
+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.
-will create configure the compiler to be installed in directory /usr/local/bin.
+2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)
-2.3.4 make
+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.
-After configuration step issue the command
+2.8.3 SDCC - The compiler
-``make''
+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 will compile the compiler
+2.8.4 S51 - Simulator
-2.3.5 ``make install''
+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/>.
-Will install the compiler and libraries in the appropriate directories.
+2.8.5 SDCDB - Source Level Debugger
-2.3.6 Special Notes for Windows Users. Provided by Michael Jamet[ mjamet@computer.org]
+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.
-
+3 Using SDCC
- How to install SDCC from source on a Windows 95 or Windows NT 4 system
+3.1 Compiling
-
+3.1.1 Single Source File Projects
- This document describes how to install SDCC on a Win 95 or Win NT
-4 system.
+For single source file 8051 projects the process is very
+simple. Compile your programs with the following command
- These instructions probably work for Win 98 as well, but have not
-been
-
- tested on that platform.
-
-
+sdcc sourcefile.c
- There are lots of little differences between UNIX and the Win32 Cygnus
+The above command will compile ,assemble and link your source
+file. Output files are as follows.
- environment which make porting more difficult than it should be. If
+* sourcefile.asm - Assembler source file created by the compiler
- you want the details, please contact me. Otherwise just follow these
+* sourcefile.lst - Assembler listing file created by the
+ Assembler
- instructions.
+* sourcefile.rst - Assembler listing file updated with linkedit
+ information , created by linkage editor
-
+* sourcefile.sym - symbol listing for the sourcefile, created
+ by the assembler.
- 1. Install the Cygnus Software
+* sourcefile.rel - Object file created by the assembler,
+ input to Linkage editor.
- Go to http://sourceware.cygnus.com/cygwin. Cygnus provides a UNIX
-like
+* sourcefile.map - The memory map for the load module, created
+ by the Linker.
- environment for Win 32 systems. Download "full.exe" and install. You
+* sourcefile.<ihx | s19> - The load module : ihx - Intel
+ hex format (default ), s19 - Motorola S19 format when
+ compiler option --out-fmt-s19 is used.
- MUST install it on your C drive. "full.exe" contains a shell AND many
+3.1.2 Projects with Multiple Source Files
- common UNIX utilities.
+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 )
- 2. Download and Extract the Latest SDCC
+foo2.c (contains some more functions)
- The latest version can be found at
+foomain.c (contains more functions and the function main)
- www.geocities.com/ResearchTriange/Forum/1353.
+The first two files will need to be compiled separately with
+the commands
- It can be uncompressed with winzip.
+sdcc -c foo1.c
-
+sdcc -c foo2.c
- 3. Start a Cygnus Shell
+Then compile the source file containing main and link the
+other files together with the following command.
- There should be an entry in the Start Menu for Cygnus. Invoke the
-shell.
+sdcc foomain.c foo1.rel foo2.rel
- This gives you a UNIX like environment. FROM THIS POINT ON, DIRECTORIES
+Alternatively foomain.c can be separately compiled as well
- MUST BE SPECIFIED WITH FORWARD SLASHES (/) NOT THE DOS STYLE BACK
+sdcc -c foomain.c
- SLASHES (\) BECAUSE THIS IS WHAT UNIX EXPECTS. -
+sdcc foomain.rel foo1.rel foo2.rel
- ex. "\winnt" would be "/winnt" under the shell.
+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
- 4. Change Directory to Where SDCC was extracted (referred to as INSTALLDIR)
+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'.
-
+sdcc foomain.c foolib.lib -L mylib
- ex. cd /sdcc218Da. If you extracted to a drive OTHER THAN C, the drive
+Note here that 'mylib' must be an absolute path name.
- must be specified as part of the path. For example, if you extracted
-to
+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.
- your "g drive", type the following: "cd //g/mydir". You must use "//"
+3.2 Command Line Options
- to specify the drive.
+3.2.1 Processor Selection Options
-
+-mmcs51 Generate code for the MCS51 (8051) family of processors.
+This is the default processor target.
- 5. Make Dirs Which are Automatically Made During the UNIX Installation
+-mds390 Generate code for the DS80C390 processor.
- From the INSTALLDIR,
+-mz80 Generate code for the Z80 family of processors.
-
+-mgbz80 Generate code for the GameBoy Z80 processor.
- mkdir -p bin (not a typo, just "bin")
+-mavr Generate code for the Atmel AVR processor(In development,
+not complete).
- mkdir -p /bin
+-mpic14 Generate code for the PIC 14-bit processors(In development,
+not complete).
+
+-mtlcs900h Generate code for the Toshiba TLCS-900H processor(In
+development, not complete).
+
+3.2.2 Path, Lib and Define Options
+
+-I<path> The additional location where the pre processor
+will look for <..h> or "..h"
+files.
+
+-D<macro[=value]> Command line definition of macros. Passed
+to the pre processor.
+
+--lib-path(-L) <absolute path to additional libraries> This
+option is passed to the linkage editor, additional libraries
+search path. The path name must be absolute. Additional
+library files may be specified in the command line . See
+section Compiling programs for more details.
+
+3.2.3 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.
+
+--model-small Generate code for Small Model programs see
+section Memory Models for more details. This is the default
+model.
+
+--model-flat24 Generate code forDS80C390 24-bit flat mode.
+See section Memory Models for more details.
+
+--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.
+
+--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.
+
+3.2.4 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 ,
+#pragma NOGCSE can be used to turn off global subexpression
+elimination for a given function only.
+
+--noinvariant 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.
+
+--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.
+
+--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.
+
+--noloopreverse Will not do loop reversal optimization
+
+--noregparms By default the first parameter is passed using
+global registers (DPL,DPH,B,ACC). This option will disable
+parameter passing using registers. NOTE: if your program
+uses the 16/32 bit support routines (for multiplication/division)
+these library routines will need to be recompiled with the
+--noregparms option as well.
+
+3.2.5 DS390 Options
+
+--stack-auto See MCS51 section for description.
+
+--stack-10bit This option generates code for the 10 bit stack
+mode of the Dallas DS80C390 part. In this mode, the stack
+is located in the lower 1K of the internal RAM, which is
+mapped to 0x400000. Note that the support is incomplete,
+since it still uses a single byte as the stack pointer.
+This means that only the lower 256 bytes of the potential
+1K stack space can actually be used. However, this does
+allow you to reclaim the precious 256 bytes of low RAM for
+use for the DATA and IDATA segments. The compiler will not
+generate any code to put the processor into 10 bit stack
+mode. It is important to ensure that the processor is in
+this mode before calling any re-entrant functions compiled
+with this option. In principle, this should work with the
+--stack-auto option, but that has not been tested. It is
+incompatible with the --xstack option. It also only makes
+sense if the processor is in 24 bit contiguous addressing
+mode (see the --model-flat24 option).
+
+3.2.6 Other Options
+
+--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. DO NOT use this option for built-in functions such
+as _muluint..., if this option is used for a library function
+the appropriate library function needs to be recompiled
+with the same option. If the project consists of multiple
+source files then all the source file should be compiled
+with the same --callee-saves option string. Also see Pragma
+Directive CALLEE-SAVES. .
+
+--debug 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.
+
+--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.
+
+--compile-only(-c) will compile and assemble the source
+only, will not call the linkage editor.
+
+--xram-loc<Value> The start location of the external ram,
+default value is 0. The value entered can be in Hexadecimal
+or Decimal format .eg. --xram-loc 0x8000 or --xram-loc 32768.
+
+--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 .eg.
+--code-loc 0x8000 or --code-loc 32768.
+
+--stack-loc<Value> The initial value of the stack pointer.
+The default value of the stack pointer is 0x07 if only register
+bank 0 is used, if other register banks are used then the
+stack pointer is initialized to the location above the highest
+register bank used. eg. if register banks 1 & 2 are used
+the stack pointer will default to location 0x18. The value
+entered can be in Hexadecimal or Decimal format .eg. --stack-loc
+0x20 or --stack-loc 32. If all four register banks are used
+the stack will be placed after the data segment (equivalent
+to --stack-after-data)
+
+--stack-after-data This option will cause the stack to be
+located in the internal ram after the data segment.
+
+--data-loc<Value> The start location of the internal ram
+data segment, the default value is 0x30.The value entered
+can be in Hexadecimal or Decimal format .eg. --data-loc
+0x20 or --data-loc 32.
+
+--idata-loc<Value> The start location of the indirectly addressable
+internal ram, default value is 0x80. The value entered can
+be in Hexadecimal or Decimal format .eg. --idata-loc 0x88
+or --idata-loc 136.
+
+--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 as-
+semble. The output is an assembler code file for the input
+file specified.
+
+-Wa_asmOption[,asmOption]... Pass the asmOption to the assembler.
+
+-Wl_linkOption[,linkOption] .. Pass the linkOption to the
+linker.
+
+--int-long-reent 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.
+
+--cyclomatic This option will cause the compiler to generate
+an information message for each function in the source file.
+The message contains some important 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 cyclomatic complexity see section on Cyclomatic Complexity
+for more details.
+
+--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.
- mkdir -p /usr/local/bin
+--main-return 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 .' .
- mkdir -p /usr/local/share
+--no-peep Disable peep-hole optimization.
- mkdir -p /usr/local/share/sdcc51lib
+--peep-asm Pass the inline assembler code through the peep
+hole optimizer. Can cause unexpected changes to inline assembler
+code , please go through the peephole optimizer rules defnied
+in file 'SDCCpeeph.def' before using this option.
- mkdir -p /usr/local/share/sdcc51inc
+--iram-size<Value> Causes the linker to check if the interal
+ram usage is within limits of the given value.
- mkdir -p /tmp
+3.2.7 Intermediate Dump Options
-
+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.
- (When a path from the root directory is specified WITHOUT a drive,
-the
+--dumpraw . This option will cause the compiler to dump the
+intermediate code into a file of named <source filename>.dumpraw
+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.
- drive defaults to c. For example /michael/newuser => c:\michael\newuser)
+--dumpgcse. Will create a dump if iCode, after global subexpression
+elimination, into a file named <source filename>.dumpgcse.
-
+--dumpdeadcode .Will create a dump if iCode, after deadcode
+elimination, into a file named <source filename>.dumpdeadcode.
- 6. Add Programs to /bin Expected by the Installation Process
+--dumploop. Will create a dump if iCode, after loop optimizations,
+into a file named <source filename>.dumploop.
- - Look at your path: echo $PATH
+--dumprange. Will create a dump if iCode, after live range
+analysis, into a file named <source filename>.dumprange.
- One of the fields is the diretory with the CYGNUS programs.
+--dumpregassign. Will create a dump if iCode, after register
+assignment , into a file named <source filename>.dumprassgn.
- ex. /CYGNUS/CYGWIN~1/H-I586/BIN
+--dumpall. Will cause all the above mentioned dumps to be
+created.
-
+Note that the files created for the dump are appended to
+each time. So the files should be deleted manually , before
+each dump is created.
- - cd to the directory found above. You may have to fiddle with the
+When reporting bugs, it can be helpful to include these dumps
+along with the portion of the code that is causing the problem.
- case (upper or lower) here because the PATH is SHOWN as all upper
+3.3 MCS51 Storage Class Language Extensions
- case, but is actually mixed. To help you along, you may type
+In addition to the ANSI storage classes SDCC allows the following
+MCS51 specific storage classes.
- a letter or 2 followed by the escape key. The shell will fill
+3.3.1 xdata
- out the remaining letters IF THEY describe a unique directory.
+Variables declared with this storage class will be placed
+in the extern RAM. This is the default storage class for
+Large Memory model .
- If you have problems here, cd one directory and type "ls". "ls"
+eg. xdata unsigned char xduc;
- is the equivalent of "dir/w".
+3.3.2 data
-
+This is the default storage class for Small Memory model.
+Variables declared with this storage class will be allocated
+in the internal RAM.
- - Copy the following:
+eg. data int iramdata;
- cp sh.exe /bin
+3.3.3 idata
- cp pwd.exe /bin
+Variables declared with this storage class will be allocated
+into the indirectly addressable portion of the internal
+ram of a 8051 .
- cp echo.exe /bin
+eg.idata int idi;
-
+3.3.4 bit
- 7. Go back to the INSTALLDIR
+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.
- cd INSTALLDIR
+eg.bit iFlag;
- ex. cd //d/sdcc218Da
+3.3.5 sfr / sbit
-
+Like the bit keyword, sfr / sbit signifies both a data-type
+and storage class, they are used to describe the special
+function registers and special bit variables of a 8051.
- 8. Run the configure Program
+eg.
- ./configure
+sfr at 0x80 P0; /* special function register P0 at location
+0x80 */
- The "./" is important because your current directory is NOT in your
-path.
+sbit at 0xd7 CY; /* CY (Carry Flag) */
- Under DOS, your current directory was implicitly always the first
-entry
+3.4 Pointers
- in your path.
+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 _generic
+class of pointers which can be used to point to any of the
+memory spaces.
-
+Pointer declaration examples.
- 9. Run make
+/* pointer physically in xternal ram pointing to object in
+internal ram */
+data unsigned char * xdata p;
- make
-
+/* pointer physically in code rom pointing to data in xdata
+space */
+xdata unsigned char * code p;
- This process takes quite some time under Win 32.
-
+/* pointer physically in code space pointing to data in code
+space */
+code unsigned char * code p;
- 10. Install the Newly Built Software
+/* the folowing is a generic pointer physically located in
+xdata space */
+char * xdata p;
- make install
+Well you get the idea. For compatibility with the previous
+version of the compiler, the following syntax for pointer
+declaration is also supported. Note the above examples will
+be portable to other commercially available compilers.
-
+unsigned char _xdata *ucxdp; /* pointer to data in external
+ram */
+unsigned char _data *ucdp ; /* pointer
+to data in internal ram */
+unsigned char _code *uccp ; /* pointer
+to data in R/O code space */
+unsigned char _idata *uccp; /*
+pointer to upper 128 bytes of ram */
- This will partially install the software into the /usr/local directories
+All unqualified pointers are treated as 3 - byte '_generic'
+pointers. These type of pointers can also to be explicitly
+declared.
- created in step 5. What it actually doing is copying the .c, .h and
+unsigned char _generic *ucgp;
- library files to directories under /usr/local/share.
+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.
-
+3.5 Parameters & Local Variables
- It will NOT be able to install the actual programs (binaries) because
+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.
- it does not know programs on Win32 systems have ".exe" extensions.
+eg
- For example, it tries to install sdcc instead of sdcc.exe.
+unsigned short foo( short 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
+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.
- After the automated part is finished, you must manually copy the binaries:
+When compiled with the default option (i.e. non-reentrant
+), local variables can be assigned storage classes and absolute
+addresses.
- cd bin (This is the bin directory in your INSTALLDIR)
+eg
- cp * /usr/local/bin
+unsigned short foo() {
+ xdata unsigned short i;
+ bit bvar;
+ data at 0x31 unsiged short 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.
+
+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.
+
+3.6 Overlaying
+
+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 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.
- 11. Make sure /usr/local/bin is in Your PATH
+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.
+
+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.
- You may add c:\usr\local\bin to your path however your Win32 system allows.
-For
+eg.
- example you may add it to the PATH statement in autoexec.bat.
+#pragma SAVE
+#pragma NOOVERLAY
+void set_error( unsigned short errcd)
+{
+ P3 = errcd;
+}
+#pragma RESTORE
+void some_isr () interrupt 2 using 1
+{
+ ...
+ 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. The pragma NOOVERLAY ensures
+that the parameters and local variables for the function
+are NOT overlayed.
- Good luck. If you have any questions send them to me or post them
+3.7 Critical Functions
- to the list.
+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.
-3 Compiling.\label{Compiling}
+eg
-3.1 Single Source file projects.\label{One Source File}
+int foo () critical
+{
+...
+...
+}
-For single source file projects the process is very simple. Compile
-your programs with the following command
+The critical attribute maybe used with other attributes like
+reentrant.
-sdcc sourcefile.c
+3.8 Absolute Addressing
-The above command will compile ,assemble and link your source file.
-Output files are as follows.
+Data items can be assigned an absolute address with the at
+<address> keyword, in addition to a storage class.
-* sourcefile.asm - Assembler source file created by the compiler
+eg.
-* sourcefile.lst - Assembler listing file created by the Assembler
+xdata at 0x8000 unsigned char PORTA_8255 ;
-* sourcefile.rst - Assembler listing file updated with linkedit information
- , created by linkage editor
+In the above example the PORTA_8255 will be allocated to
+the location 0x8000 of the external ram.
-* sourcefile.sym - symbol listing for the sourcefile, created by the
- assembler.
+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.
-* sourcefile.rel - Object file created by the assembler, input to Linkage
- editor.
+Absolute address can be specified for variables in all storage
+classes.
-* sourcefile.map - The memory map for the load module, created by the
- Linker.
+eg.
-* sourcefile.<ihx | s19> - The load module : ihx - Intel hex format
- (default ), s19 - Motorola S19 format when compiler option --out-fmt-s19
- is used.
+bit at 0x02 bvar;
-3.2 Projects with multiple source files.
+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.
-SDCC can compile only ONE file at a time. Let us for example assume
-that you have a project containing the following files.
+3.9 Interrupt Service Routines
-foo1.c ( contains some functions )
+SDCC allows interrupt service routines to be coded in C,
+with some extended keywords.
-foo2.c (contains some more functions)
+void timer_isr (void) interrupt 2 using 1
+{
+..
+}
-foomain.c (contains more functions and the function main)
+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.
+
+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'.
+
+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.
+
++--------------+--------------+----------------+
+| Interrupt # | Description | Vector Address |
++--------------+--------------+----------------+
++--------------+--------------+----------------+
+| 0 | External 0 | 0x0003 |
++--------------+--------------+----------------+
+| 1 | Timer 0 | 0x000B |
++--------------+--------------+----------------+
+| 2 | External 1 | 0x0013 |
++--------------+--------------+----------------+
+| 3 | Timer 1 | 0x001B |
++--------------+--------------+----------------+
+| 4 | Serial | 0x0023 |
++--------------+--------------+----------------+
+
+
+If the interrupt service routine is defined without a register
+bank or with register bank 0 (using 0), the compiler will
+save the registers used by itself on the stack (upon entry
+and restore them at exit), however if such an interrupt
+service routine calls another function then the entire register
+bank will be saved on the stack. This scheme may be advantageous
+for small interrupt service routines which have low register
+usage.
+
+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.
-The first two files will need to be compiled separately with the commands
+Calling other functions from an interrupt service routine
+is not recommended avoid it if possible.
-sdcc -c foo1.c
+3.10 Startup Code
-sdcc -c foo2.c
+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
+to setup hardware or perform some other critical operation
+prior to static & global variable initialization.
+
+3.11 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 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
+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.
-Then compile the source file containing main and link the other files
-together with the following command.
+eg
-sdcc foomain.c foo1.rel foo2.rel
+_asm
+ mov b,#10
+00001$:
+ djnz b,00001$
+_endasm ;
-Alternatively foomain.c can be separately compiled as well
+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 _asm ... _endasm; keyword pair.
-sdcc -c foomain.c
+Inline assembler code cannot reference any C-Labels however
+it can reference labels defined by the inline assembler.
-sdcc foomain.rel foo1.rel foo2.rel
+eg
-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.
+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
+only)
+_endasm ;
+...
+}
-3.3 Projects with additional libraries.
+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.
-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'.
+3.12 int(16 bit) and long (32 bit ) Support
-sdcc foomain.c foolib.lib -L mylib
+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
-Note here that 'mylib' must be an absolute path name.
+* _mulsint.c - signed 16 bit multiplication (calls _muluint)
-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.
-
-4 Command Line options\label{Command Line Options}
-
-* --model-large\label{--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.
-
-* --model-small \label{--model-small}Generate code for Small Model
- programs see section Memory Models for more details. This is the
- default model.
-
-* --stack-auto \label{--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.
-
-* --xstack\label{--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.
-
-* --nogcse\label{--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 , #pragma NOGCSE can be used to turn off global
- subexpression elimination for a given function only.
-
-* --noinvariant\label{--noinvariant} 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.
-
-* --noinduction\label{--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.
-
-* --nojtbound \label{--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.
-
-* --noloopreverse \label{--noloopreverse}Will not do loop reversal
- optimization
-
-* --noregparms\label{--noregparms} By default the first parameter is
- passed using global registers (DPL,DPH,B,ACC). This option will
- disable parameter passing using registers. NOTE: if your program
- uses the 16/32 bit support routines (for multiplication/division)
- these library routines will need to be recompiled with the --noregparms
- option as well.
-
-* --callee-saves function1[,function2][,function3].... \label{--callee-saves}The
- compiler by default uses a caller saves convention for register
- saving across function calls, however this can cause unneccessary
- register pushing & popping when calling small functions from larger
- functions. This option can be used to switch the register saving
- convention for the function names specified. The compiler will not
- save registers when calling these functions, extra code will be
- generated at the entry & exit for these functions to save & restore
- the registers used by these functions, this can SUBSTANTIALLY reduce
- code & improve run time performance of the generated code. In future
- the compiler (with interprocedural analysis) will be able to determine
- the appropriate scheme to use for each function call. DO NOT use
- this option for built-in functions such as _muluint..., if this
- option is used for a library function the appropriate library function
- needs to be recompiled with the same option. If the project consists
- of multiple source files then all the source file should be compiled
- with the same --callee-saves option string. Also see Pragma Directive\ref{Pragmaa}
- CALLEE-SAVES.\ref{pragma callee-saves} .
-
-* --debug \label{--debug}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.
-
-* --regextend \label{--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.
-
-* --compile-only(-c) \label{--compile-only} will compile and assemble
- the source only, will not call the linkage editor.
-
-* --xram-loc \label{--xram-loc}<Value> The start location of the external
- ram, default value is 0. The value entered can be in Hexadecimal
- or Decimal format .eg. --xram-loc 0x8000 or --xram-loc 32768.
-
-* --code-loc \label{--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 .eg. --code-loc 0x8000 or
- --code-loc 32768.
-
-* --stack-loc\label{--stack-loc}<Value> The initial value of the stack
- pointer. The default value of the stack pointer is 0x07 if only
- register bank 0 is used, if other register banks are used then the
- stack pointer is initialized to the location above the highest register
- bank used. eg. if register banks 1 & 2 are used the stack pointer
- will default to location 0x18. The value entered can be in Hexadecimal
- or Decimal format .eg. --stack-loc 0x20 or --stack-loc 32. If all
- four register banks are used the stack will be placed after the
- data segment (equivalent to --stack-after-data)
-
-* --stack-after-data\label{--stack-after-data}This option will cause
- the stack to be located in the internal ram after the data segment.
-
-* --data-loc \label{--data-loc}<Value> The start location of the internal
- ram data segment, the default value is 0x30.The value entered can
- be in Hexadecimal or Decimal format .eg. --data-loc 0x20 or --data-loc
- 32.
-
-* --idata-loc\label{--idata-loc}<Value> The start location of the indirectly
- addressable internal ram, default value is 0x80. The value entered
- can be in Hexadecimal or Decimal format .eg. --idata-loc 0x88 or
- --idata-loc 136.
-
-* --peep-file\label{--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.
-
-* --lib-path (-L) \label{--lib-path}<absolute path to additional libraries>
- This option is passed to the linkage editor, additional libraries
- search path. The path name must be absolute. Additional library
- files may be specified in the command line . See section Compiling
- programs for more details.
-
-* -I <path>\label{-I} The additional location where the pre processor
- will look for <..h> or ``..h'' files.
-
-* -D<macro[=value]> \label{-D}Command line definition of macros. Passed
- to the pre processor.
-
-* -E\label{-E} Run only the C preprocessor. Preprocess all the C source
- files specified and output the results to standard output.
-
-* -M\label{-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 \label{-C}Tell the preprocessor not to discard comments. Used
- with the `-E' option.
-
-* -MM \label{-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)\label{-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 asser-
- tions that normally describe the target machine.
-
-* -Aquestion\label{-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\label{-Umacro} Undefine macro macro. `-U' options are evaluated
- after all `-D' options, but before any `-include' and `-imac- ros'
- options.
-
-* -dM\label{-dM} Tell the preprocessor to output only a list of the
- mac- ro definitions that are in effect at the end of prepro- cessing.
- Used with the `-E' option.
-
-* -dD \label{-dD}Tell the preprocessor to pass all macro definitions
- into the output, in their proper sequence in the rest of the output.
-
-* -dN \label{-dN}Like `-dD' except that the macro arguments and contents
- are omitted. Only `#define name' is included in the output.
-
-* -S \label{-S}Stop after the stage of compilation proper; do not as-
- semble. The output is an assembler code file for the input file
- specified.
-
-* -Wa asmOption[,asmOption]... Pass the asmOption to the assembler
-
-* -Wl linkOption[,linkOption] .. Pass the linkOption to the linker.
-
-* --int-long-reent \label{--int-long-rent} 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.
-
-* --cyclomatic \label{--cyclomatic}This option will cause the compiler
- to generate an information message for each function in the source
- file. The message contains some important 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
- cyclomatic complexity see section on Cyclomatic Complexity for more
- details.
-
-* --float-reent \label{--float-reent} Floating point library is compiled
- as reentrant.See section Installation for more details.
+* _muluint.c - unsigned 16 bit multiplication
-* --out-fmt-ihx\label{--out-fmt-ihx} The linker output (final object
- code) is in Intel Hex format. (This is the default option).
+* _divsint.c - signed 16 bit division (calls _divuint)
-* --out-fmt-s19 \label{--out-fmt-s19}The linker output (final object
- code) is in Motorola S19 format.
+* _divuint.c - unsigned 16 bit division.
-* --nooverlay \label{--nooverlay} The compiler will not overlay parameters
- and local variables of any function, see section Parameters and
- local variables for more details.
+* _modsint.c - signed 16 bit modulus (call _moduint)
-* --main-return\label{--main-return} 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 .' .
+* _moduint.c - unsigned 16 bit modulus.
-* --no-peep \label{--no-peep} Disable peep-hole optimization.
+* _mulslong.c - signed 32 bit multiplication (calls _mululong)
-* --peep-asm \label{--peep-asm} Pass the inline assembler code through
- the peep hole optimizer. Can cause unexpected changes to inline
- assembler code , please go through the peephole optimizer rules
- defnied in file 'SDCCpeeph.def' before using this option.
+* _mululong.c - unsigned32 bit multiplication.
-* --iram-size\label{--iram-size} <Value> Causes the linker to check
- if the interal ram usage is within limits of the given value.
+* _divslong.c - signed 32 division (calls _divulong)
-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.
+* _divulong.c - unsigned 32 division.
-* --dumpraw \label{--dumpraw}. This option will cause the compiler
- to dump the intermediate code into a file of named <source filename>.dumpraw
- 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.
+* _modslong.c - signed 32 bit modulus (calls _modulong).
-* --dumpgcse.\label{--dumpgcse} Will create a dump if iCode, after
- global subexpression elimination, into a file named <source filename>.dumpgcse.
+* _modulong.c - unsigned 32 bit modulus.
-* --dumpdeadcode \label{--dumpdeadcode}.Will create a dump if iCode,
- after deadcode elimination, into a file named <source filename>.dumpdeadcode.
+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.
-* --dumploop. \label{--dumploop}Will create a dump if iCode, after
- loop optimizations, into a file named <source filename>.dumploop.
+3.13 Floating Point Support
-* --dumprange. \label{--dump-range}Will create a dump if iCode, after
- live range analysis, into a file named <source filename>.dumprange.
+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.
-* --dumpregassign. \label{--dumpregassign}Will create a dump if iCode,
- after register assignment , into a file named <source filename>.dumprassgn.
+* _fsadd.c - add floating point numbers.
-* --dumpall. \label{--dumpall}Will cause all the above mentioned dumps
- to be created.
+* _fssub.c - subtract floating point numbers
-Note that the files created for the dump are appended to each time.
-So the files should be deleted manually , before each dump is created.
+* _fsdiv.c - divide floating point numbers
-When reporting bugs, it will be very helpful if you could include these
-dumps along with the portion of the code that is causing the problem.
+* _fsmul.c - multiply floating point numbers
-5 Language Extensions\label{Language Extension}
+* _fs2uchar.c - convert floating point to unsigned char
-5.1 Storage Classes.\label{Storage Classes}
+* _fs2char.c - convert floating point to signed char.
-In addition to the ANSI storage classes SDCC allows the following 8051
-specific storage classes.
+* _fs2uint.c - convert floating point to unsigned int.
-5.1.1 xdata.\label{xdata}
+* _fs2int.c - convert floating point to signed int.
-Variables declared with this storage class will be placed in the extern
-RAM. This is the default storage class for Large Memory model .
+* _fs2ulong.c - convert floating point to unsigned long.
-eg. xdata unsigned char xduc;
+* _fs2long.c - convert floating point to signed long.
-5.1.2 data\label{data}
+* _uchar2fs.c - convert unsigned char to floating point
-This is the default storage class for Small Memory model. Variables
-declared with this storage class will be allocated in the internal
-RAM.
+* _char2fs.c - convert char to floating point number
-eg. data int iramdata;
+* _uint2fs.c - convert unsigned int to floating point
-5.1.3 idata\label{idata}
+* _int2fs.c - convert int to floating point numbers
-Variables declared with this storage class will be allocated into the
-indirectly addressable portion of the internal ram of a 8051 .
+* _ulong2fs.c - convert unsigned long to floating point number
-eg.idata int idi;
+* _long2fs.c - convert long to floating point number.
-5.1.4 bit\label{bit}
+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)
+
+3.14 MCS51 Memory Models
+
+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.
+
+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.
+
+Judicious usage of the processor specific storage classes
+and the 'reentrant' function type will yield much more efficient
+code, than using the large-model. Several optimizations
+are disabled when the program is compiled using the large
+model, it is therefore strongly recommdended that the small
+model be used unless absolutely required.
+
+3.15 Flat 24 bit Addressing Model
+
+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.
+
+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
+calling the SDCC startup code.
+
+Like the --model-large option, variables will by default
+be placed into the XDATA segment.
+
+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.
+
+3.16 Defines Created by the Compiler
-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.
+The compiler creates the following #defines .
-eg.bit iFlag;
+* SDCC - this Symbol is always defined.
-5.1.5 sfr / sbit\label{sfr / sbit}
+* SDCC_STACK_AUTO - this symbol is defined when --stack-auto
+ option is used.
-Like the bit keyword, sfr / sbit signifies both a data-type and storage
-class, they are used to describe the special function registers and
-special bit variables of a 8051.
+* SDCC_MODEL_SMALL - when small model is used.
-eg.
+* SDCC_MODEL_LARGE - when --model-large is used.
-sfr at 0x80 P0; /* special function register P0 at location 0x80 */
+* SDCC_USE_XSTACK - when --xstack option is used.
-sbit at 0xd7 CY; /* CY (Carry Flag) */
+4 SDCC Technical Data
-6 Optimizations\label{Optimizations}
+4.1 Optimizations
-SDCC performs a a host of standard optimizations in addition to some
-MCU specific optimizations.
+SDCC performs a a host of standard optimizations in addition
+to some MCU specific optimizations.
-6.1 Sub-expression elimination\label{Sub-expression Elimination}
+4.1.1 Sub-expression Elimination
The compiler does local and global common subexpression elimination.
a->b[i].c = 10;
a->b[i].d = 11;
-In this case the address arithmetic a->b[i] will be computed only once;
-the equivalent code in C would be.
+In this case the address arithmetic a->b[i] will be computed
+only once; the equivalent code in C would be.
iTemp = a->b[i];
iTemp.c = 10;
iTemp.d = 11;
-The compiler will try to keep these temporary variables in registers.
+The compiler will try to keep these temporary variables in
+registers.
-6.2 Dead-Code elimination.\label{Dead-code elimination}
+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;
return;
}
-6.3 Copy-Propagation:\label{Copy-Propagation}
+4.1.3 Copy-Propagation
eg.
return 10;
}
-Note: the dead stores created by this copy propagation will be eliminated
-by dead-code elimination .
-
-6.4 Loop optimizations\label{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 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).
-
-6.4.1 Loop Invariant:\label{Loop Invariant}
+Note: the dead stores created by this copy propagation will
+be eliminated by dead-code elimination .
+
+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
+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).
+
+* Loop Invariant:
eg
itemp = k + l;
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.
+As mentioned previously some loop invariants are not as apparent,
+all static address computations are also moved out of the
+loop.
-6.4.2 Strength reduction :\label{Strength Reduction}
+* Strength Reduction :
-This optimization substitutes an expression by a cheaper expression.
+This optimization substitutes an expression by a cheaper
+expression.
eg.
itemp2 += 3;
}
-The more expensive multiplication is changed to a less expensive addition.
+The more expensive multiplication is changed to a less expensive
+addition.
-6.4.3 Loop reversing:\label{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 analysis to make this
-determination, SDCC uses a more simple minded analysis).
+This optimization is done to reduce the overhead of checking
+loop boundaries for every iteration. Some simple loops can
+be reversed and implemented using a "decrement
+and jump if not zero" instruction. SDCC
+checks for the following criterion to determine if a loop
+is reversible (note: more sophisticated compiers use data-dependency
+analysis to make this determination, SDCC uses a more simple
+minded analysis).
* The 'for' loop is of the form
- ``for ( <symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++
- | <sym> += 1])
- <for body>''
+ "for ( <symbol> = <expression> ; <sym> [< | <=] <expression>
+ ; [<sym>++ | <sym> += 1])
+ <for body>"
-* The <for body> does not contain ``continue'' or 'break''.
+* The <for body> does not contain "continue"
+ or 'break".
* All goto's are contained within the loop.
* No function calls within the loop.
-* The loop control variable <sym> is not assigned any value within
- the loop
+* The loop control variable <sym> is not assigned any value
+ within the loop
* The loop control variable does NOT participate in any arithmetic
operation within the loop.
* There are NO switch statements in the loop.
-Note djnz instruction can be used for 8-bit values ONLY, therefore
-it is advantageous to declare loop control symbols as either 'char'
-or 'short', ofcourse this may not be possible on all situations.
+Note djnz instruction can be used for 8-bit values ONLY,
+therefore it is advantageous to declare loop control symbols
+as either 'char' or 'short', ofcourse this may not be possible
+on all situations.
-6.5 Algebraic simplifications:\label{Algebraic Simplifications}
+4.1.6 Algebraic Simplifications
-SDCC does numerous algebraic simplifications, the following is a small
-sub-set of these optimizations.
+SDCC does numerous algebraic simplifications, the following
+is a small sub-set of these optimizations.
eg
i = j + 0 ; /* changed to */ i = j;
i = j - j ; /* changed to */ i = 0;
i = j / 1 ; /* changed to */ i = j;
-Note the subexpressions given above are generally introduced by macro
-expansions or as a result of copy/constant propagation.
+Note the subexpressions given above are generally introduced
+by macro expansions or as a result of copy/constant propagation.
-6.6 'switch' statements.\label{Switch Statement}
+4.1.7 'switch' Statements
-SDCC changes switch statements to jump tables when the following conditions
-are true.
+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.
+* 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
-switch(i) { switch (i) {
-case 4:... case 1: ...
-case 5:... case 2: ...
-case 3:... case 3: ...
-case 6:... case 4: ...
-} }
-
-Both the above switch statements will be implemented using a jump-table.
-
-* The number of case labels is at least three, since it takes two conditional
- statements to handle the boundary conditions.
-
-* 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.
-
-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.
+switch(i) {
+
+ switch (i) {
+case 4:...
+
+ case 1: ...
+case 5:...
+
+ case 2: ...
+case 3:...
+
+ case 3: ...
+case 6:...
+
+ case 4: ...
+}
+
+ }
+
+Both the above switch statements will be implemented using
+a jump-table.
+
+* The number of case labels is at least three, since it takes
+ two conditional statements to handle the boundary conditions.
+
+* 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.
+
+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
case 12: ...
}
-If the above switch statement is broken down into two switch statements
+If the above switch statement is broken down into two switch
+statements
switch (i) {
case 1: ...
case 12:...
}
-then both the switch statements will be implemented using jump-tables
-whereas the unmodified switch statement will not be .
+then both the switch statements will be implemented using
+jump-tables whereas the unmodified switch statement will
+not be .
-6.7 bit-shifting operations.\label{bit shifting}
+4.1.8 Bit-shifting Operations.
-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.
+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.
anl a,#0x0f
mov _i,a
-In general SDCC will never setup a loop if the shift count is known.
-Another example
+In general SDCC will never setup a loop if the shift count
+is known. Another example
unsigned int i;
...
rrc a
mov _i,a
-Note that SDCC stores numbers in little-endian format (i.e. lowest
-order first)
+Note that SDCC stores numbers in little-endian format (i.e.
+lowest order first)
-6.7.1 Bit-rotation:\label{bit rotation}
+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.
+A special case of the bit-shift operation is bit rotation,
+SDCC recognizes the following expression to be a left bit-rotation.
unsigned char i;
...
rl a
mov _i,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 */
+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 */
-6.8 Highest Order Bit.\label{Highest Order Bit}
+4.1.10 Highest Order Bit
-It is frequently required to obtain the highest order bit of an integral
-type (int,long,short or char types). SDCC recognizes the following
-expression to yield the highest order bit and generates optimized
-code for it.
+It is frequently required to obtain the highest order bit
+of an integral type (int,long,short or char types). SDCC
+recognizes the following expression to yield the highest
+order bit and generates optimized code for it.
eg
unsigned int gint;
Will generate the following code.
- 61 ; hob.c 7
- 000A E5*01 62 mov a,(_gint + 1)
- 000C 33 63 rlc a
- 000D E4 64 clr a
- 000E 13 65 rrc a
- 000F F5*02 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 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.
+
+61 ; hob.c 7
+ 000A E5*01
+62 mov
+a,(_gint + 1)
+ 000C 33
+63 rlc
+a
+ 000D E4
+64 clr
+a
+ 000E 13
+65 rrc
+a
+ 000F F5*02
+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 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.
will still be recognized.
-6.9 Peep-hole optimizer.\label{Peep-Hole}
+4.1.11 Peep-hole Optimizer
-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). 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.
+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).
+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 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
-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), eg. some
+variants of the 8051 MCU allow only 'AJMP' and 'ACALL' ,
+the following two rules will change all 'LJMP' & 'LCALL'
+to 'AJMP' & 'ACALL'.
replace { lcall %1 } by { acall %1 }
replace { ljmp %1 } by { ajmp %1 }
-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 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 ,
rule := replace [ restart ] '{' <assembly sequence> '\n'
- '}' by '{' '\n'
- <assembly sequence> '\n'
- '}' [if <functionName> ] '\n'
-<assembly sequence> := assembly instruction (each instruction 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 when all rules are
-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.
+
+ '}' by '{' '\n'
+
+
+
+ <assembly sequence> '\n'
+
+ '}' [if <functionName>
+] '\n'
+<assembly sequence> := assembly instruction (each instruction
+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
+when all rules are 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.
replace restart {
pop %1
; 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.
+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.
pop ar1
pop ar2
; 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 the all the 'pop' 'push' pairs
+will be eliminated to yield
; nop
; nop
-A conditional function can be attached to a rule. Attaching rules are
-somewhat more involved, let me illustrate this with an example.
+A conditional function can be attached to a rule. Attaching
+rules are somewhat more involved, let me illustrate this
+with an example.
replace {
ljmp %5
sjmp %5
%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 entry the function is called. Note there
-can be no parameters 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 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
---peep-file option.
-
-7 Pointers\label{Pointers}
-
-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 _generic class of pointers which
-can be used to point to any of the memory spaces.
-
-Pointer declaration examples.
-
-/* pointer physically in xternal ram pointing to object in internal
-ram */
-data unsigned char * xdata p;
-
-
-/* pointer physically in code rom pointing to data in xdata space */
-
-xdata unsigned char * code p;
-
-
-/* pointer physically in code space pointing to data in code space
-*/
-code unsigned char * code p;
-
-/* the folowing is a generic pointer physically located in 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 also
-supported. Note the above examples will be portable to other commercially
-available compilers.
-
-unsigned char _xdata *ucxdp; /* pointer to data in external ram */
-
-unsigned char _data *ucdp ; /* pointer to data in internal ram */
-unsigned char _code *uccp ; /* pointer to data in R/O code space */
-unsigned char _idata *uccp; /* pointer to upper 128 bytes of ram */
-
-All unqualified pointers are treated as 3 - byte '_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. 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.
-
-8 Parameters & Local Variables\label{Auto 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.
-
-eg
-
-unsigned short foo( short 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 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.
-
-When compiled with the default option (i.e. non-reentrant ), local
-variables can be assigned storage classes and absolute addresses.
-
-eg
-
-unsigned short foo() {
- xdata unsigned short i;
- bit bvar;
- data at 0x31 unsiged short 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.
-
-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.
-
-8.1 Overlaying\label{Overlaying}
-
-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 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.
-
-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.
-
-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.
-
-eg.
-
-#pragma SAVE
-#pragma NOOVERLAY
-void set_error( unsigned short errcd)
-{
- P3 = errcd;
-}
-#pragma RESTORE
-void some_isr () interrupt 2 using 1
-{
- ...
- 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.
-The pragma NOOVERLAY ensures that the parameters and local variables
-for the function are NOT overlayed.
-
-9 critical Functions.\label{Critical}
-
-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
-
-int foo () critical
-{
-...
-...
-}
-
-The critical attribute maybe used with other attributes like reentrant.
-
-10 Absolute addressing.\label{Absolute Addressing}
-
-Data items can be assigned an absolute address with the at <address>
-keyword, in addition to a storage class.
-
-eg.
-
-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.
-
-Absolute address can be specified for variables in all storage classes.
-
-eg.
-
-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.
-
-11 Interrupt Service Routines\label{Interrupt Service Rouines}
-
-SDCC allows interrupt service routines to be coded in C, with some
-extended keywords.
-
-void timer_isr (void) interrupt 2 using 1
-{
-..
-}
-
-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.
-
-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'.
-
-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.
-
-Interrupt # Description Vector Address
- 0 External 0 0x0003
- 1 Timer 0 0x000B
- 2 External 1 0x0013
- 3 Timer 1 0x001B
- 4 Serial 0x0023
-
-If the interrupt service routine is defined without a register bank
-or with register bank 0 (using 0), the compiler will save the registers
-used by itself on the stack (upon entry and restore them at exit),
-however if such an interrupt service routine calls another function
-then the entire register bank will be saved on the stack. This scheme
-may be advantageous for small interrupt service routines which have
-low register usage.
-
-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.
-
-Calling other functions from an interrupt service routine is not recommended
-avoid it if possible.
-
-12 Startup Code\label{Startup}
-
-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.
-
-13 Inline assembler code.\label{Inline}
-
-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 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 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.
-
-eg
-
-_asm
- mov b,#10
-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 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.
+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
+entry the function is called. Note there can be no parameters
+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
+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 --peep-file option.
+
+4.2 Pragmas
+
+SDCC supports the following #pragma directives. This directives
+are applicable only at a function level.
+
+* SAVE - this will save all the current options .
+
+* 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.
+
+* NOGCSE - will stop global subexpression elimination.
+
+* NOINDUCTION - will stop loop induction optimizations .
+
+* 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.
+
+* NOLOOPREVERSE - Will not do loop reversal optimization
+
+* 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"
+
+* 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.
+
+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 before and/or after a
+function, placing pragma's inside a function body could
+have unpredictable results.
eg
-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 only)
-_endasm ;
-...
-}
-
-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.
-
-14 int (16 bit) and long (32 bit ) support.\label{int and long}
-
-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.
-
-15 Floating point support\label{Float}
-
-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.
-
-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).
-
-16 Memory Models\label{Memory Models}
-
-SDCC allows two memory models, modules compiled with different memory
-models should be combined together, the results would be unpredictable.
-The support routines supplied with the compiler are compiled in small-model
-by default, and will need to be recompiled using the large model if
-the large model is used. In general the use of the large model is
-discouraged.
-
-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.
-
-Judicious usage of the processor specific storage classes and the 'reentrant'
-function type will yield much more efficient code, than using the
-large-model.
-
-17 Defines created by the compiler.\label{Defines.}
-
-The compiler creates the following #defines .
-
-* SDCC - this Symbol is always defined.
-
-* SDCC_STACK_AUTO - this symbol is defined when --stack-auto option
- is used.
-
-* SDCC_MODEL_SMALL - when small model is used.
-
-* SDCC_MODEL_LARGE - when --model-large is used.
-
-* SDCC_USE_XSTACK - when --xstack option is used.
-
-18 Pragmas\label{Pragmaa}
-
-SDCC supports the following #pragma directives. This directives are
-applicable only at a function level.
-
-* SAVE\label{pragma save} - this will save all the current options .
-
-* RESTORE \label{pragma 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.
-
-* NOGCSE\label{pragma nogcse} - will stop global subexpression elimination.
-
-* NOINDUCTION \label{pragma noinduction}- will stop loop induction
- optimizations .
-
-* NOJTBOUND \label{pragma nojtbound}- will not generate code for boundary
- value checking , when switch statements are turned into jump-tables.
-
-* NOOVERLAY \label{pragma nooverlay}- the compiler will not overlay
- the parameters and local variables of a function.
-
-* NOLOOPREVERSE \label{pragma noloopreverse}- Will not do loop reversal
- optimization
-
-* EXCLUDE NONE | {acc[,b[,dpl[,dph]]]\label{pragma exclude} - 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''
-
-* CALLEE-SAVES function1[,function2[,function3...]]\label{pragma callee-saves}
- - 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\ref{--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.
-
-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 before and/or after
-a function, placing pragma's inside a function body could have unpredictable
-results.
-
-eg
+#pragma SAVE /* save the current settings
+*/
+#pragma NOGCSE /* turnoff global subexpression elimination
+*/
+#pragma NOINDUCTION /* turn off induction optimizations */
-#pragma SAVE /* save the current settings */
-#pragma NOGCSE /* turnoff global subexpression elimination */
-#pragma NOINDUCTION /* turn off induction optimizations */
int foo ()
{
...
}
#pragma RESTORE /* turn the optimizations back on */
-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.
+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.
-19 Library routines.\label{Library}
+4.3 Library Routines
The following library routines are provided for your convenience.
-stdio.h - Contains the following functions printf & sprintf these routines
-are developed by 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>.
%[flags][width][b|B|l|L]type
- flags: - left justify output in specified field width
- + prefix output with +/- sign if output is signed type
- space prefix output with a blank if it's a signed positive value
- width: specifies minimum number of characters outputted for numbers
-
- or strings.
- - For numbers, spaces are added on the left when needed.
- If width starts with a zero character, zeroes and used
- instead of spaces.
- - For strings, spaces are are added on the left or right (when
- flag '-' is used) when needed.
-
- b/B: byte argument (used by d, u, o, x, X)
- l/L: long argument (used by d, u, o, x, X)
- type: d decimal number
- u unsigned decimal number
- o unsigned octal number
- x unsigned hexadecimal number (0-9, a-f)
- X unsigned hexadecimal number (0-9, A-F)
- c character
- s string (generic pointer)
- p generic pointer (I:data/idata, C:code, X:xdata, P:paged)
- f float (still to be implemented)
-
-Also contains a very simple version of printf (printf_small). This
-simplified version of printf supports only the following formats.
-
-format output type argument-type
-%d decimal int
-%ld decimal long
-%hd decimal short/char
-%x hexadecimal int
-%lx hexadecimal long
-%hx hexadecimal short/char
-%o octal int
-%lo octal long
-%ho octal short/char
-%c character char/short
-%s character _generic pointer
-
- 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.
-
- printf_small(``my str %s, my int %d\n'',(char _generic *)mystr,myint);
-
-* 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'
+ flags:
+- left justify output
+in specified field width
+
++ prefix output with
++/- sign if output is signed type
+
+space prefix output with a blank if
+it's a signed positive value
+ width:
+specifies minimum number of characters outputted for numbers
+
+
+or strings.
+
+- For numbers, spaces are added on the left when needed.
+
+
+If width starts with a zero character, zeroes and used
+
+instead of spaces.
+
+- For strings, spaces are are added on the left or right
+(when
+
+flag '-' is used) when needed.
+
+
+ b/B:
+byte argument (used by d, u, o, x, X)
+ l/L:
+long argument (used by d, u, o, x, X)
+ type:
+d decimal number
+
+u unsigned decimal number
+
+
+o unsigned octal number
+
+
+x unsigned hexadecimal
+number (0-9, a-f)
+
+X unsigned hexadecimal
+number (0-9, A-F)
+
+c character
+
+s string (generic pointer)
+
+
+p generic pointer (I:data/idata,
+C:code, X:xdata, P:paged)
+
+f float (still to be
+implemented)
+
+Also contains a very simple version of printf (printf_small).
+This simplified version of printf supports only the following
+formats.
+
+format output type argument-type
+
+%d decimal
+ int
+%ld decimal long
+
+%hd decimal short/char
+
+%x hexadecimal int
+
+%lx hexadecimal long
+
+%hx hexadecimal short/char
+
+%o octal int
+
+%lo octal long
+
+%ho octal short/char
+
+%c character char/short
+
+%s character _generic
+pointer
+
+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.
+
+printf_small("my str %s, my int %d\n",(char
+_generic *)mystr,myint);
+
+* 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'
va_list, va_start, va_arg, va_end.
-* 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.
+* 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.
* stdlib.h - contains the following functions.
* string.h - contains the following functions.
- strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr,
- strspn, strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp,
- memset.
+ strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr,
+ strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok,
+ memcpy, memcmp, memset.
* ctype.h - contains the following routines.
- iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
- isxdigit, isalnum, isalpha.
+ iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct,
+ isspace, isxdigit, isalnum, isalpha.
-* 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).
+* 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).
//Example:
- // #define DYNAMIC_MEMORY_SIZE 0x2000
- // .....
- // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
+ //
+ #define DYNAMIC_MEMORY_SIZE 0x2000
+ //
+ .....
+ //
+ unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
- // unsigned char xdata * current_buffer;
- // .....
- // void main(void)
- // {
- // ...
- // init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
+ //
+ unsigned char xdata * current_buffer;
+ //
+ .....
+ //
+ void main(void)
+ //
+ {
+ //
+ ...
+ //
+ init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
- // //Now it's possible to use malloc.
- // ...
- // current_buffer = malloc(0x100);
+ //
+ //Now it's possible to use malloc.
+ //
+ ...
+ //
+ current_buffer = malloc(0x100);
//
-* 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
+* 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.
-* 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
+* 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
-* 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.
+* 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.
-* reg51.h - contains register definitions for a standard 8051
+* reg51.h - contains register definitions for a standard
+ 8051
* reg552.h - contains register definitions for 80C552.
-* float.h - contains min, max and other floating point related stuff.
+* float.h - contains min, max and other floating point related
+ stuff.
-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.
+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.
-Have not had time to do the more involved routines like printf, will
-get to them shortly.
+Have not had time to do the more involved routines like printf,
+will get to them shortly.
-20 Interfacing with assembly routines.\label{Interface_asm}
+4.4 Interfacing with Assembly Routines
-20.1 Global registers used for parameter passing.
+4.5 Global Registers used for Parameter Passing
-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).
+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).
-20.1.1 Assembler routine non-reentrant
+4.5.1 Assembler Routine(non-reentrant)
-In the following example the function cfunc calls an assembler routine
-asm_func, which takes two parameters.
+In the following example the function cfunc calls an assembler
+routine asm_func, which takes two parameters.
extern int asm_func( unsigned short, unsigned short);
.globl _asm_func_PARM_2
.globl _asm_func
.area OSEG
-_asm_func_PARM_2: .ds 1
+_asm_func_PARM_2:
+.ds 1
.area CSEG
_asm_func:
- mov a,dpl
- add a,_asm_func_PARM_2
- mov dpl,a
- mov dpl,#0x00
+ mov
+a,dpl
+ add
+a,_asm_func_PARM_2
+ mov
+dpl,a
+ mov
+dpl,#0x00
ret
-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.
+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.
-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 varaible name for the second parameter will be _<function_name>_PARM_2.
+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 varaible name for the second parameter
+will be _<function_name>_PARM_2.
Assemble the assembler routine with the following command.
asx8051 -losg asmfunc.asm
-Then compile and link the assembler routine to the C source file with
-the following command,
+Then compile and link the assembler routine to the C source
+file with the following command,
sdcc cfunc.c asmfunc.rel
-20.1.2 Assembler routine is reentrant
+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 i.e. after the call
-the left most parameter will be on the top of the stack. Here is an
-example.
+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.
extern int asm_func( unsigned short, unsigned short);
-int c_func (unsigned short i, unsigned short j) reentrant
+int c_func (unsigned short i, unsigned short j) reentrant
+
{
return asm_func(i,j);
}
pop _bp
ret
-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.
+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.
-20.2 With --noregparms option.
+4.6 With --noregparms Option
-When the source is compiled with --noregparms option , space is allocated
-for each of the parameters passed to a routine.
+When the source is compiled with --noregparms option , space
+is allocated for each of the parameters passed to a routine.
-20.2.1 Assembler routine non-reentrant.
+4.6.1 Assembler Routine Non-reentrant
-In the following example the function cfunc calls an assembler routine
-asm_func, which takes two parameters.
+In the following example the function cfunc calls an assembler
+routine asm_func, which takes two parameters.
extern int asm_func( unsigned short, unsigned short);
.globl _asm_func_PARM_2
.globl _asm_func
.area OSEG
-_asm_func_PARM_1: .ds 1
-_asm_func_PARM_2: .ds 1
+_asm_func_PARM_1:
+.ds 1
+_asm_func_PARM_2:
+.ds 1
.area CSEG
_asm_func:
- mov a,_asm_func_PARM_1
- add a,_asm_func_PARM_2
- mov dpl,a
- mov dpl,#0x00
+ mov
+a,_asm_func_PARM_1
+ add
+a,_asm_func_PARM_2
+ mov
+dpl,a
+ mov
+dpl,#0x00
ret
-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.
+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.
-The parameter naming convention is _<function_name>_PARM_<n>, where
-n is the parameter number starting from 1, and counting from the left.
-i.e. the left-most parameter name will be _<function_name>_PARM_1.
+The parameter naming convention is _<function_name>_PARM_<n>,
+where n is the parameter number starting from 1, and counting
+from the left. i.e. the left-most parameter name will be
+_<function_name>_PARM_1.
Assemble the assembler routine with the following command.
asx8051 -losg asmfunc.asm
-Then compile and link the assembler routine to the C source file with
-the following command,
+Then compile and link the assembler routine to the C source
+file with the following command,
sdcc cfunc.c asmfunc.rel
-20.2.2 Assembler routine is reentrant.
+4.6.2 Assembler Routine(reentrant)
-In this case the parameters will be passed on the stack , the parameters
-are pushed from right to left i.e. after the call the left most parameter
-will be on the top of the stack. Here is an example.
+In this case the parameters will be passed on the stack ,
+the parameters are pushed from right to left i.e. after
+the call the left most parameter will be on the top of the
+stack. Here is an example.
extern int asm_func( unsigned short, unsigned short);
-int c_func (unsigned short i, unsigned short j) reentrant
+int c_func (unsigned short i, unsigned short j) reentrant
+
{
return asm_func(i,j);
}
pop _bp
ret
-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.
+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.
-21 External Stack.\label{xstack}
+4.7 External Stack
-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).
+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).
-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.
+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.
-22 ANSI-Compliance.\label{ANSI_Compliance}
+4.8 ANSI-Compliance
Deviations from the compliancy.
1. functions are not always reentrant.
-2. 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.
+2. 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.
eg
foo()
{
...
-s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
+s1 = s2 ; /* is invalid in SDCC although allowed in ANSI
+*/
...
}
-struct s foo1 (struct s parms) /* is invalid in SDCC although allowed
-in ANSI */
+struct s foo1 (struct s parms) /* is invalid in SDCC although
+allowed in ANSI */
{
struct s rets;
...
-return rets;/* is invalid in SDCC although allowed in ANSI */
+return rets;/* is invalid in SDCC although allowed in ANSI
+*/
}
1. 'long long' (64 bit integers) not supported.
2. 'double' precision floating point not supported.
-3. 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.
+3. 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.
4. No support for setjmp and longjmp (for now).
...
}
-1. functions declared as pointers must be dereferenced during the call.
+1. functions declared as pointers must be dereferenced during
+ the call.
int (*foo)();
...
/* has to be called like this */
- (*foo)();/* ansi standard allows calls to be made like 'foo()' */
+ (*foo)();/* ansi standard allows calls to be made like
+'foo()' */
-23 Cyclomatic Complexity\label{Cyclomatic}
+4.9 Cyclomatic Complexity
-Cyclomatic complexity of a function is defined as the number of independent
-paths the program can take during execution of the function. This
-is an important number since it defines the number test cases you
-have to generate to validate the function . The accepted industry
-standard for complexity number is 10, if the cyclomatic complexity
-reported by SDCC exceeds 10 you should think about simplification
-of the function logic.
+Cyclomatic complexity of a function is defined as the number
+of independent paths the program can take during execution
+of the function. This is an important number since it defines
+the number test cases you have to generate to validate the
+function . The accepted industry standard for complexity
+number is 10, if the cyclomatic complexity reported by SDCC
+exceeds 10 you should think about simplification of the
+function logic.
-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.
+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.
complexity = (number of edges in control flow graph) -
- (number of nodes in control flow graph) + 2;
-
-Having said that the industry standard is 10, you should be aware that
-in some cases it may unavoidable to have a complexity level of less
-than 10. For example if you have switch statement with more than 10
-case labels, each case label adds one to the complexity level. The
-complexity level is by no means an absolute measure of the algorithmic
-complexity of the function, it does however provide a good starting
-point for which functions you might look at for further optimization.
-
-24 TIPS\label{Tips}
-
-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.
-
-* Use the smallest data type to represent your data-value. If it is
- known in advance that the value is going to be less than 256 then
- use a 'short' or 'char' instead of an 'int'.
-
-* 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.
+ (number
+of nodes in control flow graph) + 2;
+
+Having said that the industry standard is 10, you should
+be aware that in some cases it may unavoidable to have a
+complexity level of less than 10. For example if you have
+switch statement with more than 10 case labels, each case
+label adds one to the complexity level. The complexity level
+is by no means an absolute measure of the algorithmic complexity
+of the function, it does however provide a good starting
+point for which functions you might look at for further
+optimization.
+
+5 TIPS
+
+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.
+
+* Use the smallest data type to represent your data-value.
+ If it is known in advance that the value is going to be
+ less than 256 then use a 'short' or 'char' instead of
+ an 'int'.
+
+* 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.
* NEVER jump into a LOOP.
-* Declare the variables to be local whenever possible, especially loop
- control variables (induction).
+* Declare the variables to be local whenever possible, especially
+ loop control variables (induction).
-* Since the compiler does not do implicit integral promotion, the programmer
- should do an explicit cast when integral promotion is required.
+* Since the compiler does not do implicit integral promotion,
+ the programmer should do an explicit cast when integral
+ promotion is required.
-* Reducing the size of division , multiplication & modulus operations
- can reduce code size substantially. Take the following code for
- example.
+* 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)
{
....
}
- 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
+ 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
foobar( unsigned int p1, unsigned char ch)
{
- unsigned char ch1 = (unsigned char)p1 % ch ;
+ unsigned char ch1 = (unsigned char)p1
+ % ch ;
....
}
- It would substantially reduce the code generated (future versions
- of the compiler will be smart enough to detect such optimization
- oppurtunities).
+ It would substantially reduce the code generated (future
+ versions of the compiler will be smart enough to detect
+ such optimization oppurtunities).
-Notes from an USER ( Trefor@magera.freeserve.co.uk )
+Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
-The 8051 family of micro controller have a minimum of 128 bytes of
-internal memory which is structured as follows
+The 8051 family of micro controller have a minimum of 128
+bytes of internal memory which is structured as follows
-- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7
-to R7
+- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers
+R7 to R7
- Bytes 20-2F - 16 bytes to hold 128 bit variables and
- Bytes 30-7F - 60 bytes for general purpose use.
-Normally the SDCC compiler will only utilise the first bank of registers,
-but it is possible to specify that other banks of registers should
-be used in interrupt routines. By default, the compiler will place
-the stack after the last bank of used registers, i.e. if the first
-2 banks of registers are used, it will position the base of the internal
-stack at address 16 (0X10). This implies that as the stack grows,
-it will use up the remaining register banks, and the 16 bytes used
-by the 128 bit variables, and 60 bytes for general purpose use.
-
-By default, the compiler uses the 60 general purpose bytes to hold
-"near data". The compiler/optimiser may also declare some Local Variables
-in this area to hold local data.
-
-If any of the 128 bit variables are used, or near data is being used
-then care needs to be taken to ensure that the stack does not grow
-so much that it starts to over write either your bit variables or
-"near data". There is no runtime checking to prevent this from happening.
-
-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.
-
-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.
-
---stack-loc will allow you specify the start of the stack, i.e. you
-could start it after any data in the general purpose area. However
-this may waste the memory not used by the register banks and if the
-size of the "near data" increases, it may creep into the bottom of
-the stack.
+Normally the SDCC compiler will only utilise the first bank
+of registers, but it is possible to specify that other banks
+of registers should be used in interrupt routines. By default,
+the compiler will place the stack after the last bank of
+used registers, i.e. if the first 2 banks of registers are
+used, it will position the base of the internal stack at
+address 16 (0X10). This implies that as the stack grows,
+it will use up the remaining register banks, and the 16
+bytes used by the 128 bit variables, and 60 bytes for general
+purpose use.
+
+By default, the compiler uses the 60 general purpose bytes
+to hold "near data". The compiler/optimiser may also declare
+some Local Variables in this area to hold local data.
+
+If any of the 128 bit variables are used, or near data is
+being used then care needs to be taken to ensure that the
+stack does not grow so much that it starts to over write
+either your bit variables or "near data". There is no runtime
+checking to prevent this from happening.
+
+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.
+
+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.
+
+--stack-loc will allow you specify the start of the stack,
+i.e. you could start it after any data in the general purpose
+area. However this may waste the memory not used by the
+register banks and if the size of the "near data" increases,
+it may creep into the bottom of the stack.
--stack-after-data, similar to the --stack-loc, but it automatically
-places the stack after the end of the "near data". Again this could
-waste any spare register space.
+places the stack after the end of the "near data". Again
+this could waste any spare register space.
---data-loc allows you to specify the start address of the near data.
-This could be used to move the "near data" further away from the stack
-giving it more room to grow. This will only work if no bit variables
-are being used and the stack can grow to use the bit variable space.
+--data-loc allows you to specify the start address of the
+near data. This could be used to move the "near data" further
+away from the stack giving it more room to grow. This will
+only work if no bit variables are being used and the stack
+can grow to use the bit variable space.
Conclusion.
-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.
-
-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.
-
-25 Retargetting for other MCUs.\label{Retargetting}
-
-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.
-
-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 like back patching labels and the pattern
- matching optimizations like bit-rotation etc.
-
-2. 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
+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.
+
+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.
+
+6 Retargetting for other MCUs.
+
+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.
+
+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
+ like back patching labels and the pattern matching optimizations
+ like bit-rotation etc.
+
+2. 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.
-3. This phase does the bulk of the standard optimizations and is also
- MCU independent. This phase can be broken down into several sub-phases.
+3. This phase does the bulk of the standard optimizations
+ and is also MCU independent. This phase can be broken
+ down into several sub-phases.
* Break down intermediate code (iCode) into basic blocks.
* Do control flow & data flow analysis on the basic blocks.
- * Do local common subexpression elimination, then global subexpression
- elimination
+ * Do local common subexpression elimination, then global
+ subexpression elimination
* dead code elimination
* loop optimizations
- * if loop optimizations caused any changes then do 'global subexpression
- elimination' and 'dead code elimination' again.
-
-4. 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.
-
-5. Phase five is register allocation. There are two parts to this process .
-
- (a) 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.
-
- (b) 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.
-
-6. 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.
-
-7. As mentioned in the optimization section the peep-hole optimizer
- is rule based system, which can reprogrammed for other MCUs.
-
-26 Reporting Bugs\label{Bugs}
-
-Shoot of an email to 'sandeep.dutta@usa.net', as a matter of principle
-I always reply to all email's sent to me. Bugs will be fixed ASAP.
-When reporting a bug , it is useful to include a small snippet of
-code that is causing the problem, if possible compile your program
-with the --dumpall option and send the dump files along with the bug
-report.
-
-27 SDCDB - Source level debugger.
-
-SDCC is distributed with a source level debugger. The debugger uses
-a command line interface, the command repertoire of the debugger has
-been kept as close to gdb ( the GNU debugger) as possible. The configuration
-and build process of the compiler see Installation \ref{Installation}
-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.
-
-27.1 Compiling for debugging.
-
-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 .
-
-27.2 How the debugger works.
-
-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 .
-
-27.3 Starting the debugger.
-
-The debugger can be started using the following command line. (Assume
-the file you are debugging has
+ * if loop optimizations caused any changes then do 'global
+ subexpression elimination' and 'dead code elimination'
+ again.
+
+4. 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.
+
+5. Phase five is register allocation. There are two parts
+ to this process .
+
+ (a) 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.
+
+ (b) 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.
+
+6. 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.
+
+7. As mentioned in the optimization section the peep-hole
+ optimizer is rule based system, which can reprogrammed
+ for other MCUs.
+
+7 SDCDB - Source Level Debugger
+
+SDCC is distributed with a source level debugger. The debugger
+uses a command line interface, the command repertoire of
+the debugger has been kept as close to gdb ( the GNU debugger)
+as possible. The configuration and build process is part
+of the standard compiler installation, which also builds
+and installs the debugger in the target directory specified
+during configuration. The debugger allows you debug BOTH
+at the C source and at the ASM source level.
+
+7.1 Compiling for Debugging
+
+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 .
+
+7.2 How the Debugger Works
+
+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 .
+
+7.3 Starting the Debugger
+
+The debugger can be started using the following command line.
+(Assume the file you are debugging has
the file name foo).
3. foo.ihx - the intel hex format object file.
-27.4 Command line options.
+7.4 Command Line Options.
-* --directory=<source file directory> this option can used to specify
- the directory search list. The debugger will look into the directory
- list specified for source , cdb & ihx files. The items in the directory
- list must be separated by ':' , e.g. if the source files can be
- in the directories /home/src1 and /home/src2, the --directory option
- should be --directory=/home/src1:/home/src2 . Note there can be
- no spaces in the option.
+* --directory=<source file directory> this option can used
+ to specify the directory search list. The debugger will
+ look into the directory list specified for source , cdb
+ & ihx files. The items in the directory list must be separated
+ by ':' , e.g. if the source files can be in the directories
+ /home/src1 and /home/src2, the --directory option should
+ be --directory=/home/src1:/home/src2 . Note there can
+ be no spaces in the option.
* -cd <directory> - change to the <directory>.
* -fullname - used by GUI front ends.
-* -cpu <cpu-type> - this argument is passed to the simulator please
- see the simulator docs for details.
+* -cpu <cpu-type> - this argument is passed to the simulator
+ please see the simulator docs for details.
-* -X <Clock frequency > this options is passed to the simulator please
- see simulator docs for details.
+* -X <Clock frequency > this options is passed to the simulator
+ please see simulator docs for details.
-* -s <serial port file> passed to simulator see simulator docs for
- details.
+* -s <serial port file> passed to simulator see simulator
+ docs for details.
-* -S <serial in,out> passed to simulator see simulator docs for details.
+* -S <serial in,out> passed to simulator see simulator docs
+ for details.
-27.5 Debugger Commands.
+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 graphical user interfaces
-(like ddd, xxgdb or xemacs) existing for the GNU debugger.
+As mention earlier the command interface for the debugger
+has been deliberately kept as close the GNU debugger gdb
+, as possible, this will help int integration with existing
+graphical user interfaces (like ddd, xxgdb or xemacs) existing
+for the GNU debugger.
-27.5.1 break [line | file:line | function | file:function]
+7.5.1 break [line | file:line | function | file:function]
Set breakpoint at specified line or function.
sdcdb>break funcfoo
sdcdb>break foo.c:funcfoo
-27.5.2 clear [line | file:line | function | file:function ]
+7.5.2 clear [line | file:line | function | file:function ]
Clear breakpoint at specified line or function.
sdcdb>clear funcfoo
sdcdb>clear foo.c:funcfoo
-27.5.3 continue
+7.5.3 continue
Continue program being debugged, after breakpoint.
-27.5.4 finish
+7.5.4 finish
Execute till the end of the current function.
-27.5.5 delete [n]
+7.5.5 delete [n]
-Delete breakpoint number 'n'. If used without any option clear ALL
-user defined break points.
+Delete breakpoint number 'n'. If used without any option
+clear ALL user defined break points.
-27.5.6 info [break | stack | frame | registers ]
+7.5.6 info [break | stack | frame | registers ]
* info break - list all breakpoints
* info stack - show the function call stack.
-* info frame - show information about the current execution frame.
+* info frame - show information about the current execution
+ frame.
* info registers - show content of all registers.
-27.5.7 step
+7.5.7 step
Step program until it reaches a different source line.
-27.5.8 next
+7.5.8 next
Step program, proceeding through subroutine calls.
-27.5.9 run
+7.5.9 run
Start debugged program.
-27.5.10 ptype variable
+7.5.10 ptype variable
Print type information of the variable.
-27.5.11 print variable
+7.5.11 print variable
print value of variable.
-27.5.12 file filename
+7.5.12 file filename
-load the given file name. Note this is an alternate method of loading
-file for debugging.
+load the given file name. Note this is an alternate method
+of loading file for debugging.
-27.5.13 frame
+7.5.13 frame
print information about current frame.
-27.5.14 set srcmode
+7.5.14 set srcmode
Toggle between C source & assembly source.
-27.5.15 ! simulator command
+7.5.15 ! simulator command
-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.
+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.
-27.5.16 quit.
+7.5.16 quit.
"Watch me now. Iam going Down. My name is Bobby Brown"
-27.6 Interfacing with XEmacs.
-
-Two files are (in emacs lisp) are provided for the interfacing with
-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.
-
-The command line options that are passed to the simulator directly
-are bound to default values in the file sdcdbsrc.el the variables
-are listed below these values maybe changed as required.
+7.6 Interfacing with XEmacs.
+
+Two files are (in emacs lisp) are provided for the interfacing
+with 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.
+
+The command line options that are passed to the simulator
+directly are bound to default values in the file sdcdbsrc.el
+the variables are listed below these values maybe changed
+as required.
* sdcdbsrc-cpu-type '51
;; Current Listing ::
-;;key binding Comment
-;;--- ------- -------
+;;key binding Comment
+
+;;--- ------- -------
+
;;
-;; n sdcdb-next-from-src SDCDB next command
-;; b sdcdb-back-from-src SDCDB back command
-;; c sdcdb-cont-from-src SDCDB continue command
-;; s sdcdb-step-from-src SDCDB step command
-;; ? sdcdb-whatis-c-sexp SDCDB ptypecommand for data at
-;; buffer point
-;; x sdcdbsrc-delete SDCDB Delete all breakpoints if no arg
-;; given or delete arg (C-u arg x)
-;; m sdcdbsrc-frame SDCDB Display current frame if no arg,
-;; given or display frame arg
-;; buffer point
-;; ! sdcdbsrc-goto-sdcdb Goto the SDCDB output buffer
-;; p sdcdb-print-c-sexp SDCDB print command for data at
-;; buffer point
-;; g sdcdbsrc-goto-sdcdb Goto the SDCDB output buffer
-;; t sdcdbsrc-mode Toggles Sdcdbsrc mode (turns it off)
+;; n
+sdcdb-next-from-src SDCDB
+next command
+;; b
+sdcdb-back-from-src SDCDB
+back command
+;; c
+sdcdb-cont-from-src SDCDB
+continue command
+;; s
+sdcdb-step-from-src SDCDB
+step command
+;; ?
+sdcdb-whatis-c-sexp SDCDB
+ptypecommand for data at
+;;
+buffer point
+;; x
+sdcdbsrc-delete SDCDB
+Delete all breakpoints if no arg
+;; given
+or delete arg (C-u arg x)
+;; m
+sdcdbsrc-frame SDCDB
+Display current frame if no arg,
+;; given
+or display frame arg
+;; buffer
+point
+;; !
+sdcdbsrc-goto-sdcdb Goto
+the SDCDB output buffer
+;; p
+sdcdb-print-c-sexp SDCDB
+print command for data at
+;;
+buffer point
+;; g
+sdcdbsrc-goto-sdcdb Goto
+the SDCDB output buffer
+;; t
+sdcdbsrc-mode Toggles
+Sdcdbsrc mode (turns it off)
;;
-;; C-c C-f sdcdb-finish-from-src SDCDB finish command
+;; C-c C-f
+sdcdb-finish-from-src SDCDB
+finish command
;;
-;; C-x SPC sdcdb-break Set break for line with point
-;; ESC t sdcdbsrc-mode Toggle Sdcdbsrc mode
-;; ESC m sdcdbsrc-srcmode Toggle list mode
+;; C-x SPC
+sdcdb-break Set
+break for line with point
+;; ESC t
+sdcdbsrc-mode Toggle
+Sdcdbsrc mode
+;; ESC m
+sdcdbsrc-srcmode
+Toggle list mode
;;
-28 Conclusion\label{Conclusion}
-
-SDCC is a large project , the compiler alone (without the Assembler
-Package , Preprocessor & garbage collector) is about 40,000 lines
-of code (blank stripped). As with any project of this size there are
-bound to be bugs, I am more than willing to work to fix these bugs
-, of course all the source code is included with the package.
-
-Where does it go from here ? I am planning to target the Atmel AVR
-8-bit MCUs which seems to have a lot of users. I am also planning
-to include an alias analysis system with this compiler (it does not
-currently have one).
-
-29 Acknowledgments\label{Acknowledgements}
-
-Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX
-& ASLINK.
-
-John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for
-8051
-
-Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
+8 Other Processors
+
+8.1 The Z80 and gbz80 port
+
+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.
+
+As always, the code is the authoritave reference - see z80/ralloc.c
+and z80/gen.c. The stack frame is similar to that generated
+by the IAR Z80 compiler. IX is used as the base pointer,
+HL is used as a temporary register, and BC and DE are available
+for holding varibles. IY is currently unusued. Return values
+are stored in HL. One bad side effect of using IX as the
+base pointer is that a functions stack frame is limited
+to 127 bytes - this will be fixed in a later version.
+
+9 Support
+
+SDCC has grown to be large project, the compiler alone (without
+the Assembler Package, Preprocessor) is about 40,000 lines
+of code (blank stripped). The open source nature of this
+project is a key to its continued growth and support. You
+gain the benefit and support of many active software developers
+and end users. Is SDCC perfect? No, that's why we need your
+help. The developers take pride in fixing reported bugs.
+You can help by reporting the bugs and helping other SDCC
+users. There are lots of ways to contribute, and we encourage
+you to take part in making SDCC a great software package.
+
+9.1 Reporting Bugs
+
+Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
+or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed
+ASAP. When reporting a bug, it is very useful to include
+a small test program which reproduces the problem. If you
+can isolate the problem by looking at the generated assembly
+code, this can be very helpful. Compiling your program with
+the --dumpall option can sometimes be useful in locating
+optimization problems.
+
+9.2 Acknowledgments
+
+Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler,
+MCS51 code generator, Debugger, AVR port
+Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version
+of ASXXXX & ASLINK.
+John Hartman (jhartman@compuserve.com) - Porting ASXXX &
+ASLINK for 8051
+Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
+
+Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his
+Freeware simulator
+Malini Dutta(malini_dutta@hotmail.com) - my wife for her
+patience and support.
+Unknown - for the GNU C - preprocessor.
+Michael Hope - The Z80 and Z80GB port, 186 development
+Kevin Vigor - The DS390 port.
+Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
+Scott Datallo - PIC port.
+(Thanks to all the other volunteer developers who have helped
+with coding, testing, web-page creation, distribution sets,
+etc. You know who you are :-)
-Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware
-simulator
-Jans J Boehm(boehm@sgi.com) and Alan J Demers - Conservative garbage
-collector for C & C++.
+This document initially written by Sandeep Dutta
-Malini Dutta(malini@mediaone.net) - my wife for her patience and support.
+All product names mentioned herein may be trademarks of their
+respective companies.
-Unknown - for the GNU C - preprocessor.
-\index
projects / fw / sdcc / commitdiff