Section install and search path fixed

[fw/sdcc] / doc / sdccman.lyx

#LyX 1.2 created this file. For more info see http://www.lyx.org/
\lyxformat 220
\textclass article
\language english
\inputencoding default
\fontscheme pslatex
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language swedish
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle fancy

\layout Comment

Please note: double dashed longoptions (e.g.
 --version) need three dashes in this document to be visable in html and
 pdf output.
\layout Title

SDCC Compiler User Guide
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Section

Introduction
\layout Subsection

About SDCC
\layout Standard


\series bold 
SDCC
\series default 
 is a Freeware, 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 DS80C390 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 microcont
rollers and underlying hardware effectively.
 
\newline 

\newline 
In addition to the MCU specific optimizations SDCC also does a host of standard
 optimizations like:
\layout Itemize

global sub expression elimination, 
\layout Itemize

loop optimizations (loop invariant, strength reduction of induction variables
 and loop reversing), 
\layout Itemize

constant folding & propagation, 
\layout Itemize

copy propagation, 
\layout Itemize

dead code elimination 
\layout Itemize

jumptables for 
\emph on 
switch
\emph default 
 statements.
\layout Standard

For the back-end SDCC uses a global register allocation scheme which should
 be well suited for other 8 bit MCUs.
 
\newline 

\newline 
The peep hole optimizer uses a rule based substitution mechanism which is
 MCU independent.
 
\newline 

\newline 
Supported data-types are:
\layout Itemize

char (8 bits, 1 byte), 
\layout Itemize

short and int (16 bits, 2 bytes), 
\layout Itemize

long (32 bit, 4 bytes)
\layout Itemize

float (4 byte IEEE).
 
\layout Standard

The compiler also allows 
\emph on 
inline assembler code
\emph default 
 to be embedded anywhere in a function.
 In addition, routines developed in assembly can also be called.
\newline 

\newline 
SDCC also provides an option (--cyclomatic) to report the relative complexity
 of a function.
 These functions can then be further optimized, or hand coded in assembly
 if needed.
 
\newline 

\newline 
SDCC also comes with a companion source level debugger SDCDB, the debugger
 currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 
\newline 

\newline 
The latest version can be downloaded from 
\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}

\end_inset 


\series bold 
.
\layout Subsection

Open Source
\layout Standard

All packages used in this compiler system are 
\emph on 
opensource
\emph default 
 and 
\emph on 
freeware
\emph default 
; source code for all the sub-packages (pre-processor, assemblers, linkers
 etc) is distributed with the package.
 This documentation is maintained using a freeware word processor (LyX).
\newline 
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! 
\layout Subsection

Typographic conventions
\layout Standard

Throughout this manual, we will use the following convention.
 Commands you have to type in are printed in 
\family sans 
\series bold 
"sans serif"
\series default 
.

\family default 
 Code samples are printed in 
\family typewriter 
typewriter font.

\family default 
 Interesting items and new terms are printed in 
\emph on 
italic.
\layout Subsection

Compatibility with previous versions
\layout Standard

This version has numerous bug fixes compared with the previous version.
 But we also introduced some incompatibilities with older versions.
 Not just for the fun of it, but to make the compiler more stable, efficient
 and ANSI compliant.
 
\newline 

\layout Itemize

short is now equivalent to int (16 bits), it used to be equivalent to char
 (8 bits) which is not ANSI compliant
\layout Itemize

the default directory for gcc-builds where include, library and documention
 files are stored is now in /usr/local/share
\layout Itemize

char type parameters to vararg functions are casted to int unless explicitly
 casted, e.g.: 
\newline 

\family typewriter 
\SpecialChar ~
\SpecialChar ~
char a=3;
\newline 
\SpecialChar ~
\SpecialChar ~
printf ("%d %c
\backslash 
n", a, (char)a);
\family default 

\newline 
 will push a as an int and as a char resp.
\layout Itemize

option ---regextend has been removed
\layout Itemize

option ---noregparms has been removed
\layout Itemize

option ---stack-after-data has been removed
\layout Standard


\emph on 
<pending: more incompatibilities?>
\layout Subsection

System Requirements
\layout Standard

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

Other Resources
\layout Standard

The SDCC home page at 
\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}

\end_inset 

 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 cvs.sdcc.sourceforge.net.
\layout Subsection

Wishes for the future
\layout Standard

There are (and always will be) some things that could be done.
 Here are some I can think of:
\newline 

\layout Standard


\family typewriter 
char KernelFunction3(char p) at 0x340;
\newline 

\newline 

\family default 
If you can think of some more, please send them to the list.
\newline 

\newline 

\emph on 
<pending: And then of course a proper index-table
\begin_inset LatexCommand \index{index}

\end_inset 

>
\layout Section

Installation
\layout Subsection

Install paths
\layout Standard

The install paths and default search paths are defined when running 'configure'.
 The defaults can be overriden by
\layout Standard

...
 TBA
\newline 

\newline 
These configure variables are compiled into the binaries, and can only be
 changed by rerunning 'configure' and recompiling SDCC.
 The configure variables are written in 
\emph on 
italics
\emph default 
 to distinguish them from run time variables (see next section).
\newline 

\newline 
The defaults are:
\newline 

\newline 

\begin_inset  Tabular
<lyxtabular version="3" rows="7" columns="3">
<features>
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Variable
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

*nix default
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Win32 default
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
PREFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

/usr/local
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
sdcc
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
DATADIR
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
$PREFIX
\emph default 
/share/sdcc
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
$PREFIX
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
BIN_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

bin
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

bin
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
SEARCH_SUFFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

share/sdcc
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
INCLUDE_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

include
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

include
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
LIB_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

lib
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

lib
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\newline 

\newline 
Cygwin is handled like a *nix, Mingw32 however belongs to the Win32 builds.
 The SDCC team uses Mingw32 to build the official Windows binaries, because
 it's
\layout Enumerate

open source, 
\layout Enumerate

a gcc compiler and last but not least
\layout Enumerate

the binaries can be built by cross compiling on Sourceforge's compile farm.
\layout Standard

The other Win32 builds using Borland, VC or whatever don't use 'configure',
 but they (hopefully) use the default Win32 paths.
\newline 

\newline 
1.
 Binary files (preprocessor, assembler and linker)
\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="2" columns="3">
<features>
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Path
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

*nix default
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Win32 default
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
$PREFIX/$BIN_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

/usr/local/bin
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
sdcc
\backslash 
bin
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 

 
\newline 

\newline 
2.
 Include files
\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="2" columns="3">
<features>
<column alignment="left" valignment="top" leftline="true" width="1.6in">
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Path
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

*nix default
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Win32 default
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
$DATADIR/
\newline 
$INCLUDE_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

/usr/local/share/sdcc/include
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
sdcc
\backslash 
include
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\newline 

\newline 
3.
 Library files (the 
\shape italic 
model
\shape default 
 is auto-appended by the compiler, e.g.
 small, large, z80, ds390 etc.)
\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="2" columns="3">
<features>
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Path
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

*nix default
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Win32 default
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
$DATADIR/$LIB_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

/usr/local/share/sdcc/lib
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
sdcc
\backslash 
lib
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\newline 

\newline 
4.
 Documentation
\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="2" columns="3">
<features>
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Path
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

*nix default
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Win32 default
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
$DATADIR/
\emph default 
doc
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

/usr/local/share/sdcc/doc
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
sdcc
\backslash 
doc
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\layout Subsection

Search paths
\layout Standard

Some search paths or parts of them are determined by configure variables
 (in 
\emph on 
italics
\emph default 
, see section above).
 Other search paths are determined by environment variables during runtime.
 
\newline 
The paths searched when running the compiler are as follows (the first catch
 wins):
\newline 

\newline 
1.
 Binary files (preprocessor, assembler and linker)
\newline 
 
\begin_inset  Tabular
<lyxtabular version="3" rows="4" columns="3">
<features>
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Search path
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

*nix default
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Win32 default
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_HOME/
\emph on 
$BIN_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_HOME/bin
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_HOME
\backslash 
bin
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Path of argv[0] (if available)
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Path of argv[0]
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Path of argv[0]
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$PATH
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$PATH
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

$PATH
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 

 
\newline 

\newline 
2.
 Include files
\newline 
 
\begin_inset  Tabular
<lyxtabular version="3" rows="6" columns="3">
<features>
<column alignment="left" valignment="top" leftline="true" width="1.5in">
<column alignment="left" valignment="top" leftline="true" width="1.5in">
<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Search path
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

*nix default
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Win32 default
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

---I dir
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

---I dir
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

---I dir
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_INCLUDE_PATH
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_INCLUDE_PATH
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_INCLUDE_PATH
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_HOME/
\newline 

\emph on 
$SEARCH_SUFFIX/
\newline 
$INCLUDE_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_HOME/
\newline 
share/sdcc/
\newline 
include
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_HOME
\backslash 
include
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

path(argv[0])/../
\newline 

\emph on 
$SEARCH_SUFFIX/
\emph default 

\newline 

\emph on 
$INCLUDE_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

(not on *nix)
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

path(argv[0])
\backslash 
..
\backslash 
include
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
$DATADIR/
\emph default 

\newline 

\emph on 
$INCLUDE_DIR_SUFFIX
\end_inset 
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

/usr/local/share/sdcc/
\newline 
include
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

(not on Win32)
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 

 
\newline 

\newline 
 The option ---nostdinc disables the last two search paths.
\newline 

\newline 
3.
 Library files 
\newline 
With the exception of 
\begin_inset Quotes sld
\end_inset 

---L dir
\begin_inset Quotes srd
\end_inset 

 the 
\shape italic 
model
\shape default 
 is auto-appended by the compiler (e.g.
 small, large, z80, ds390 etc.).
 
\newline 

\begin_inset  Tabular
<lyxtabular version="3" rows="6" columns="3">
<features>
<column alignment="left" valignment="top" leftline="true" width="1.7in">
<column alignment="left" valignment="top" leftline="true" width="1.2in">
<column alignment="left" valignment="top" leftline="true" rightline="true" width="1.2in">
<row topline="true" bottomline="true">
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Search path
\end_inset 
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

*nix default
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Win32 default
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

---L dir
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

---L dir
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

---L dir
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_LIB_PATH/
\newline 

\emph on 
<model>
\end_inset 
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_LIB_PATH/
\newline 

\emph on 
<model>
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_LIB_PATH
\backslash 

\newline 

\emph on 
<model>
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_HOME/
\newline 

\emph on 
$SEARCH_SUFFIX/
\newline 
$LIB_DIR_SUFFIX/<model>
\end_inset 
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_HOME/
\newline 
share/sdcc/
\newline 
lib/
\emph on 
<model>
\end_inset 
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

$SDCC_HOME
\backslash 
lib
\backslash 

\emph on 

\newline 
<model>
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

path(argv[0]/../
\newline 

\emph on 
$SEARCH_SUFFIX/
\newline 
$LIB_DIR_SUFFIX/<model>
\end_inset 
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

(not on *nix)
\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 ~

\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

path(argv[0]
\backslash 
..
\backslash 
lib
\backslash 

\emph on 

\newline 
<model>
\newline 

\emph default 
\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 ~

\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\emph on 
$DATADIR/
\newline 
$LIB_DIR_SUFFIX/<model>
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

/usr/local/share/sdcc/
\newline 
lib/
\emph on 
<model>
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

(not on Win32)
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\layout Comment

Don't delete any of the stray spaces in the table line 5 without checking
 the HTML output (last line)!
\layout Standard

\SpecialChar ~

\newline 
The option ---nostdlib disables the last two search paths.
\layout Subsection

Linux and other gcc-based systems (cygwin, mingw32, osx)
\layout Enumerate


\series medium 
Download the source package
\series default 
 either from the SDCC CVS repository or from the 
\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}

\end_inset 


\series medium 
, it will be named something like sdcc
\series default 
.src
\series medium 
.t
\series default 
ar.
\series medium 
gz.
\layout Enumerate


\series medium 
Bring up a command line terminal, such as xterm.
\layout Enumerate


\series medium 
Unpack the file using a command like: 
\family sans 
\series bold 
"tar -xzf sdcc.src.tar.gz
\family default 
\series default 
"
\series medium 
, this will create a sub-directory called sdcc with all of the sources.
\layout Enumerate

Change directory into the main SDCC directory, for example type: 
\family sans 
\series bold 
"cd sdcc
\series default 
".
\layout Enumerate


\series medium 
Type 
\family sans 
\series bold 
"./configure
\family default 
\series default 
".
 This configures the package for compilation on your system.
\layout Enumerate


\series medium 
Type 
\family sans 
\series bold 
"make
\family default 
\series default 
"
\series medium 
.

\series default 
 All of the source packages will compile, this can take a while.
\layout Enumerate


\series medium 
Type 
\family sans 
\series bold 
"make install"
\family default 
\series default 
 as root
\series medium 
.

\series default 
 This copies the binary executables, the include files, the libraries and
 the documentation to the install directories.
\layout Subsection

Windows 
\layout Subsubsection

Windows Install Using a Binary Package
\layout Enumerate

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 the mingw32 package 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

Adjust your environment variable PATH to include the location of the bin
 directory or start sdcc using the full path.
\layout Subsubsection

Windows Install Using Cygwin and Mingw32
\layout Standard

Follow the instruction in 
\series bold 
Linux and other gcc-based systems
\series default 
.
\layout Subsubsection

Windows Install Using Microsoft Visual C++ 6.0/NET
\layout Standard


\series medium 
Download the source package
\series default 
 either from the SDCC CVS repository or from the 
\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}

\end_inset 


\series medium 
, it will be named something like sdcc
\series default 
.src
\series medium 
.tgz.

\series default 
 SDCC is distributed with all the projects, workspaces, and files you need
 to build it using Visual C++ 6.0/NET.
 The workspace name is 'sdcc.dsw'.
 Please note that as it is now, all the executables are created in a folder
 called sdcc
\backslash 
bin_vc.
 Once built you need to copy the executables from sdcc
\backslash 
bin_vc to sdcc
\backslash 
bin before runnng SDCC.
 
\newline 

\newline 
In order to build SDCC with Visual C++ 6.0/NET you need win32 executables
 of bison.exe, flex.exe, and gawk.exe.
 One good place to get them is 
\begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}

\end_inset 


\newline 

\newline 
Download the file UnxUtils.zip.
 Now you have to install the utilities and setup Visual C++ so it can locate
 the required programs.
 Here there are two alternatives (choose one!):
\layout Enumerate

The easy way:
\newline 

\newline 
a) Extract UnxUtils.zip to your C:
\backslash 
 hard disk PRESERVING the original paths, otherwise bison won't work.
 (If you are using WinZip make certain that 'Use folder names' is selected)
\newline 

\newline 
b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
 in 'Show directories for:' select 'Executable files', and in the directories
 window add a new path: 'C:
\backslash 
user
\backslash 
local
\backslash 
wbin', click ok.
\newline 

\newline 
(As a side effect, you get a bunch of Unix utilities that could be useful,
 such as diff and patch.)
\layout Enumerate

A more compact way:
\newline 

\newline 
This one avoids extracting a bunch of files you may not use, but requires
 some extra work:
\newline 

\newline 
a) Create a directory were to put the tools needed, or use a directory already
 present.
 Say for example 'C:
\backslash 
util'.
\newline 

\newline 
b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
 to such directory WITHOUT preserving the original paths.
 (If you are using WinZip make certain that 'Use folder names' is not selected)
\newline 

\newline 
c) Rename bison.exe to '_bison.exe'.
\newline 

\newline 
d) Create a batch file 'bison.bat' in 'C:
\backslash 
util
\backslash 
' and add these lines: 
\newline 
\SpecialChar ~
\SpecialChar ~
set BISON_SIMPLE=C:
\backslash 
util
\backslash 
bison.simple 
\newline 
\SpecialChar ~
\SpecialChar ~
set BISON_HAIRY=C:
\backslash 
util
\backslash 
bison.hairy
\newline 
\SpecialChar ~
\SpecialChar ~
_bison %1 %2 %3 %4 %5 %6 %7 %8 %9
\newline 

\newline 
Steps 'c' and 'd' are needed because bison requires by default that the
 files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
 '/usr/local/share/' I think.
 So it is necessary to tell bison where those files are located if they
 are not in such directory.
 That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
\newline 

\newline 
e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
 in 'Show directories for:' select 'Executable files', and in the directories
 window add a new path: 'c:
\backslash 
util', click ok.
 Note that you can use any other path instead of 'c:
\backslash 
util', even the path where the Visual C++ tools are, probably: 'C:
\backslash 
Program Files
\backslash 
Microsoft Visual Studio
\backslash 
Common
\backslash 
Tools'.
 So you don't have to execute step 'e' :)
\layout Standard

That is it.
 Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
 the executables from sdcc
\backslash 
bin_vc to sdcc
\backslash 
bin, and you can compile using sdcc.
\layout Subsubsection

Windows Install Using Borland
\layout Enumerate

From the sdcc directory, run the command "make -f Makefile.bcc".
 This should regenerate all the .exe files in the bin directory except for
 sdcdb.exe (which currently doesn't build under Borland C++).
\layout Enumerate

If you modify any source files and need to rebuild, be aware that the dependanci
es may not be correctly calculated.
 The safest option is to delete all .obj files and run the build again.
 From a Cygwin BASH prompt, this can easily be done with the commmand:
\newline 

\newline 

\family sans 
\series bold 
find .
 
\backslash 
( -name '*.obj' -o -name '*.lib' -o -name '*.rul' 
\backslash 
) -print -exec rm {} 
\backslash 
;
\family default 
\series default 

\newline 

\newline 
or on Windows NT/2000/XP from the command prompt with the commmand:
\newline 

\family sans 
\series bold 

\newline 
del /s *.obj *.lib *.rul
\family default 
\series default 
 from the sdcc directory.
\layout Subsection

Testing out the SDCC Compiler
\layout Standard

The first thing you should do after installing your SDCC compiler is to
 see if it runs.
 Type 
\family sans 
\series bold 
"sdcc ---version"
\family default 
\series default 
 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.
\newline 

\newline 

\series medium 
SDCC 
\series default 
is commonly installed as described in section 
\begin_inset Quotes sld
\end_inset 

Install and search paths
\begin_inset Quotes srd
\end_inset 


\newline 

\newline 

\series medium 
Make sure the compiler works on a very simple example.
 Type in the following test.c program using your favorite 
\series default 
ascii 
\series medium 
editor:
\series default 

\newline 

\family typewriter 

\newline 
char test;
\newline 

\newline 
void main(void) {
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
test=0;
\newline 
}
\family default 

\newline 

\emph on 

\newline 

\series medium 
\emph default 
Compile this using the following command: 
\family sans 
\series bold 
"sdcc -c test.c".

\family default 
\series default 
 
\series medium 
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.
\series default 

\newline 

\newline 

\series medium 
The next step is to try it with the linker.
 Type in 
\family sans 
\series bold 
"sdcc test.c
\family default 
\series default 
"
\series medium 
.
 If all goes well the compiler will link with the libraries and produce
 a test.ihx output file.
 If this step fails
\series default 
 
\series medium 
(no test.ihx, and the linker generates warnings), then the problem is most
 likely that sdcc cannot find the 
\series default 
/
\series medium 
usr/local/share/sdcc/lib directory
\series default 
 
\series medium 
(see the Install trouble-shooting section for suggestions).
\series default 

\newline 

\newline 

\series medium 
The final test is to ensure sdcc can use the 
\series default 
standard
\series medium 
 header files and libraries.
 Edit test.c and change it to the following:
\series default 

\newline 

\newline 

\family typewriter 
#include <string.h>
\newline 

\newline 
char str1[10];
\newline 

\newline 
void main(void) {
\newline 
\SpecialChar ~
\SpecialChar ~
strcpy(str1, "testing");
\newline 
}
\newline 

\newline 

\family default 
\series medium 
Compile this by typing 
\family sans 
\series bold 
"sdcc test.c"
\family default 
\series medium 
.
 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
\series default 
 
\series medium 
(see the Install trouble-shooting section for suggestions).
\layout Subsection

Install Trouble-shooting
\layout Subsubsection

SDCC does not build correctly.
\layout Standard

A thing to try is starting from scratch by unpacking the .tgz source package
 again in an empty directory.
 Confure it like:
\newline 

\newline 

\family sans 
\series bold 
./configure 2>&1 | tee configure.log
\family default 
\series default 

\newline 

\newline 
and build it like:
\newline 

\newline 

\family sans 
\series bold 
make 2>&1 | tee make.log
\family default 
\series default 

\newline 

\newline 
If anything goes wrong, you can review the log files to locate the problem.
 Or a relevant part of this can be attached to an email that could be helpful
 when requesting help from the mailing list.
\layout Subsubsection

What the 
\begin_inset Quotes sld
\end_inset 

./configure
\begin_inset Quotes srd
\end_inset 

 does
\layout Standard

The 
\begin_inset Quotes sld
\end_inset 

./configure
\begin_inset Quotes srd
\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

What the 
\begin_inset Quotes sld
\end_inset 

make
\begin_inset Quotes srd
\end_inset 

 does.
\layout Standard

This runs the GNU make tool, which automatically compiles all the source
 packages into the final installed binary executables.
\layout Subsubsection

What the 
\begin_inset Quotes sld
\end_inset 

make install
\begin_inset Quotes erd
\end_inset 

 command does.
\layout Standard

This will install the compiler, other executables libraries and include
 files in to the appropriate directories.
 See section 
\begin_inset Quotes sld
\end_inset 

Install and Search PATHS
\begin_inset Quotes srd
\end_inset 

.
\newline 
On most systems you will need super-user privilages to do this.
\layout Subsection

Components of SDCC
\layout Standard

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.
\newline 

\newline 
You might want to look at the files which are installed in <installdir>.
 At the time of this writing, we find the following programs for gcc-builds:
\newline 
 
\newline 
In <installdir>/bin:
\layout Itemize

sdcc - The compiler.
\layout Itemize

sdcpp - The C preprocessor.
\layout Itemize

asx8051 - The assembler for 8051 type processors.
\layout Itemize

as-z80
\series bold 
, 
\series default 
as-gbz80 - The Z80 and GameBoy Z80 assemblers.
\layout Itemize

aslink -The linker for 8051 type processors.
\layout Itemize

link-z80
\series bold 
, 
\series default 
link-gbz80 - The Z80 and GameBoy Z80 linkers.
\layout Itemize

s51 - The ucSim 8051 simulator.
\layout Itemize

sdcdb - The source debugger.
\layout Itemize

packihx - A tool to pack (compress) Intel hex files.
\layout Standard

In <installdir>/share/sdcc/include
\layout Itemize

the include files
\layout Standard

In <installdir>/share/sdcc/lib
\layout Itemize

the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
 relocatables.
\layout Standard

In <installdir>/share/sdcc/doc
\layout Itemize

the documentation
\layout Standard

As development for other processors proceeds, this list will expand to include
 executables to support processors like AVR, PIC, etc.
\layout Subsubsection

sdcc - The Compiler
\layout Standard

This is the actual compiler, it in turn uses the c-preprocessor and invokes
 the assembler and linkage editor.
\layout Subsubsection

sdcpp - The C-Preprocessor
\layout Standard

The preprocessor is a modified version of the GNU preprocessor.
 The C preprocessor is used to pull in #include sources, process #ifdef
 statements, #defines and so on.
\layout Subsubsection

asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 - The Assemblers
 and Linkage Editors
\layout Standard

This is retargettable assembler & linkage editor, it was developed by Alan
 Baldwin.
 John Hartman created the version for 8051, and I (Sandeep) have made some
 enhancements and bug fixes for it to work properly with the SDCC.
\layout Subsubsection

s51 - The Simulator
\layout Standard

S51 is a freeware, opensource simulator developed by Daniel Drotos (
\begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}

\end_inset 

).
 The simulator is built as part of the build process.
 For more information visit Daniel's website at: 
\begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}

\end_inset 

.
 It currently support the core mcs51, the Dallas DS80C390 and the Philips
 XA51 family.
\layout Subsubsection

sdcdb - Source Level Debugger
\layout Standard


\family typewriter 
\shape italic 
<todo: is this thing still alive?>
\newline 

\newline 

\family default 
\shape default 
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

Using SDCC
\layout Subsection

Compiling
\layout Subsubsection

Single Source File Projects
\layout Standard

For single source file 8051 projects the process is very simple.
 Compile your programs with the following command 
\family sans 
\series bold 
"sdcc sourcefile.c".

\family default 
\series default 
 This will compile, assemble and link your source file.
 Output files are as follows
\newline 

\newline 
sourcefile.asm - Assembler source file created by the compiler
\newline 
sourcefile.lst - Assembler listing file created by the Assembler
\newline 
sourcefile.rst - Assembler listing file updated with linkedit information,
 created by linkage editor
\newline 
sourcefile.sym - symbol listing for the sourcefile, created by the assembler
\newline 
sourcefile.rel - Object file created by the assembler, input to Linkage editor
\newline 
sourcefile.map - The memory map for the load module, created by the Linker
\newline 
sourcefile.ihx - The load module in Intel hex format (you can select the
 Motorola S19 format with ---out-fmt-s19)
\newline 
sourcefile.cdb - An optional file (with ---debug) containing debug information
\newline 
sourcefile.dump* - Dump file to debug the compiler it self (with ---dumpall)
 (see section 
\begin_inset Quotes sld
\end_inset 

Anatomy of the compiler
\begin_inset Quotes srd
\end_inset 

).
\layout Subsubsection

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:
\newline 

\newline 
foo1.c (contains some functions)
\newline 
foo2.c (contains some more functions)
\newline 
foomain.c (contains more functions and the function main)
\newline 

\size footnotesize 

\newline 

\size default 
The first two files will need to be compiled separately with the commands:
\size footnotesize 
 
\size default 

\newline 

\newline 

\family sans 
\series bold 
sdcc\SpecialChar ~
-c\SpecialChar ~
foo1.c
\family default 
\series default 
\size footnotesize 

\newline 

\family sans 
\series bold 
\size default 
sdcc\SpecialChar ~
-c\SpecialChar ~
foo2.c
\family default 
\series default 

\newline 

\newline 
Then compile the source file containing the 
\emph on 
main()
\emph default 
 function and link the files together with the following command: 
\newline 

\newline 

\family sans 
\series bold 
sdcc\SpecialChar ~
foomain.c\SpecialChar ~
foo1.rel\SpecialChar ~
foo2.rel
\family default 
\series default 

\newline 

\newline 
Alternatively, 
\emph on 
foomain.c 
\emph default 
can be separately compiled as well: 
\family sans 
\series bold 

\newline 

\newline 
sdcc\SpecialChar ~
-c\SpecialChar ~
foomain.c
\newline 
sdcc foomain.rel foo1.rel foo2.rel
\newline 

\newline 

\family default 
\series default 
The file containing the 
\emph on 
main()
\emph default 
 function
\emph on 
 
\emph default 
\noun on 
must
\noun default 
 be the 
\noun on 
first
\noun default 
 file specified in the command line, since the linkage editor processes
 file in the order they are presented to it.
\layout Subsubsection

Projects with Additional Libraries
\layout Standard

Some reusable routines may be compiled into a library, see the documentation
 for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
 for how to create a 
\emph on 
.lib
\emph default 
 library file.
 Libraries created in this manner can be included in the command line.
 Make sure you include the -L <library-path> option to tell the linker where
 to look for these files if they are not in the current directory.
 Here is an example, assuming you have the source file 
\emph on 
foomain.c
\emph default 
 and a library
\emph on 
 foolib.lib
\emph default 
 in the directory 
\emph on 
mylib
\emph default 
 (if that is not the same as your current project):
\newline 

\newline 

\family sans 
\series bold 
sdcc foomain.c foolib.lib -L mylib
\newline 

\newline 

\family default 
\series default 
Note here that
\emph on 
 mylib
\emph default 
 must be an absolute path name.
\newline 

\newline 
The most efficient way to use libraries is to keep seperate modules in seperate
 source files.
 The lib file now should name all the modules.rel files.
 For an example see the standard library file 
\emph on 
libsdcc.lib
\emph default 
 in the directory <installdir>/share/lib/small.
\layout Subsection

Command Line Options
\layout Subsubsection

Processor Selection Options
\layout List
\labelwidthstring 00.00.0000


\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


\series bold 
-mds390
\series default 
 Generate code for the DS80C390 processor.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-mz80
\series default 
 Generate code for the Z80 family of processors.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-mgbz80
\series default 
 Generate code for the GameBoy Z80 processor.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-mavr
\series default 
 Generate code for the Atmel AVR processor (In development, not complete).
\layout List
\labelwidthstring 00.00.0000


\series bold 
-mpic14
\series default 
 Generate code for the PIC 14-bit processors (In development, not complete).
\layout List
\labelwidthstring 00.00.0000


\series bold 
-mtlcs900h
\series default 
 Generate code for the Toshiba TLCS-900H processor (In development, not
 complete).
\layout List
\labelwidthstring 00.00.0000


\series bold 
-mxa51
\series default 
 Generate code for the Philips XA51 processor (In development, not complete).
\layout Subsubsection

Preprocessor Options
\layout List
\labelwidthstring 00.00.0000


\series bold 
-I<path>
\series 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 List
\labelwidthstring 00.00.0000


\series bold 
-D<macro[=value]>
\series default 
 Command line definition of macros.
 Passed to the pre processor.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-M
\series 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


\series bold 
-C
\series default 
 Tell the preprocessor not to discard comments.
 Used with the `-E' option.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-MM
\size large 
\bar under 
 
\series default 
\size default 
\bar default 
Like `-M' but the output mentions only the user header files included with
 `#include 
\begin_inset Quotes eld
\end_inset 

file"'.
 System header files included with `#include <file>' are omitted.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-Aquestion(answer)
\series 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


\series bold 
-Aquestion
\series 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


\series bold 
-Umacro
\series 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


\series bold 
-dM
\series 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


\series bold 
-dD
\series 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


\series bold 
-dN
\size large 
\bar under 
 
\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 Subsubsection

Linker Options
\layout List
\labelwidthstring 00.00.0000


\series bold 
-L\SpecialChar ~
---lib-path
\bar under 
 
\series default 
\bar default 
<absolute path to additional libraries> This option is passed to the linkage
 editor's additional libraries search path.
 The path name must be absolute.
 Additional library files may be specified in the command line.
 See section Compiling programs for more details.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---xram-loc
\series default 
<Value> The start location of the external ram, default value is 0.
 The value entered can be in Hexadecimal or Decimal format, e.g.: ---xram-loc
 0x8000 or ---xram-loc 32768.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---code-loc
\series 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, e.g.: ---code-loc
 0x8000 or ---code-loc 32768.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---stack-loc
\series default 
<Value> By default the stack is placed after the data segment.
 Using this option the stack can be placed anywhere in the internal memory
 space of the 8051.
 The value entered can be in Hexadecimal or Decimal format, e.g.
 ---stack-loc 0x20 or ---stack-loc 32.
 Since the sp register is incremented before a push or call, the initial
 sp will be set to one byte prior the provided value.
 The provided value should not overlap any other memory areas such as used
 register banks or the data segment and with enough space for the current
 application.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---data-loc
\series default 
<Value> The start location of the internal ram data segment.
 The value entered can be in Hexadecimal or Decimal format, eg.
 ---data-loc 0x20 or ---data-loc 32.
 (By default, the start location of the internal ram data segment  is set
 as low as possible in memory, taking into account the used register banks
 and the bit segment at address 0x20.
 For example if register banks 0 and 1 are used without bit variables, the
 data segment will be set, if ---data-loc is not used, to location 0x10.)
\layout List
\labelwidthstring 00.00.0000


\series bold 
---idata-loc
\series 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


\series bold 
---out-fmt-ihx
\bar under 
 
\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


\series bold 
---out-fmt-s19
\bar under 
 
\series default 
\bar default 
The linker output (final object code) is in Motorola S19 format.
\layout Subsubsection

MCS51 Options
\layout List
\labelwidthstring 00.00.0000


\series bold 
---model-large
\series 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


\series bold 
---model-small
\series default 
\size large 
\emph on 
 
\size default 
\emph default 
Generate code for Small Model programs see section Memory Models for more
 details.
 This is the default model.
\layout Subsubsection

DS390 Options
\layout List
\labelwidthstring 00.00.0000


\series bold 
---model-flat24
\series default 
\size large 
\emph on 
 
\size default 
\emph default 
Generate 24-bit flat mode code.
 This is the one and only that the ds390 code generator supports right now
 and is default when using 
\emph on 
-mds390
\emph default 
.
 See section Memory Models for more details.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---stack-10bit
\series default 
 Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
 This is the one and only that the ds390 code generator supports right now
 and is default when using 
\emph on 
-mds390
\emph default 
.
 In this mode, the stack is located in the lower 1K of the internal RAM,
 which is mapped to 0x400000.
 Note that the support is incomplete, since it still uses a single byte
 as the stack pointer.
 This means that only the lower 256 bytes of the potential 1K stack space
 will actually be used.
 However, this does allow you to reclaim the precious 256 bytes of low RAM
 for use for the DATA and IDATA segments.
 The compiler will not generate any code to put the processor into 10 bit
 stack mode.
 It is important to ensure that the processor is in this mode before calling
 any re-entrant functions compiled with this option.
 In principle, this should work with the 
\emph on 
---stack-auto
\emph default 
 option, but that has not been tested.
 It is incompatible with the 
\emph on 
---xstack
\emph default 
 option.
 It also only makes sense if the processor is in 24 bit contiguous addressing
 mode (see the 
\emph on 
---model-flat24 option
\emph default 
).
\layout Subsubsection

Optimization Options
\layout List
\labelwidthstring 00.00.0000


\series bold 
---nogcse
\series 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\SpecialChar ~
NOGCSE can be used
 to turn off global subexpression elimination for a given function only.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---noinvariant
\series 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\SpecialChar ~
NOINVARIANT can be used
 to turn off invariant optimizations for a given function only.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---noinduction
\series default 
 Will not do loop induction optimizations, see section strength reduction
 for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
NOINDUCT
ION can be used to turn off induction optimizations for a given function
 only.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---nojtbound
\size large 
\bar under 
 
\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 is recommended that this option is NOT used, #pragma\SpecialChar ~
NOJTBOUND can be
 used to turn off boundary checking for jump tables for a given function
 only.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---noloopreverse
\series default 
\size large 
 
\size default 
Will not do loop reversal optimization.
\layout List
\labelwidthstring 00.00.0000

---
\series bold 
nolabelopt
\series default 
 Will not optimize labels (makes the dumpfiles more readable).
\layout List
\labelwidthstring 00.00.0000


\series bold 
---no-xinit-opt
\series default 
 Will not memcpy initialized data in far space from code space.
 This saves a few bytes in code space if you don't have initialized data.
\layout Subsubsection

Other Options
\layout List
\labelwidthstring 00.00.0000


\series bold 
-c\SpecialChar ~
---compile-only
\series default 
 will compile and assemble the source, but will not call the linkage editor.
\layout List
\labelwidthstring 00.00.0000


\series bold 
--c1mode
\series default 
 reads the preprocessed source from standard input and compiles it.
 The file name for the assembler output must be specified using the -o option.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-E
\series 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


\series bold 
-o\SpecialChar ~
<path/file> 
\series default 
The output path resp.
 file where everything will be placed.
 If the parameter is a path, it must have a trailing slash (or backslash
 for the Windows binaries) to be recognized as a path.
 
\layout List
\labelwidthstring 00.00.0000


\series bold 
---stack-auto
\series default 
\size large 
\emph on 
 
\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


\series bold 
---xstack
\series default 
 Uses a pseudo stack in the first 256 bytes in the external ram for allocating
 variables and passing parameters.
 See section on external stack for more details.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---callee-saves function1[,function2][,function3]....

\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, no 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 the 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\SpecialChar ~
CALLEE-SAVES.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---debug
\bar under 
 
\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


\series bold 
---peep-file
\series 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


\series bold 
-S
\size large 
\bar under 
 
\series default 
\size default 
\bar default 
Stop after the stage of compilation proper; do not assemble.
 The output is an assembler code file for the input file specified.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-Wa_asmOption[,asmOption]
\series default 
...
 Pass the asmOption to the assembler.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-Wl_linkOption[,linkOption]
\series default 
...
 Pass the linkOption to the linker.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---int-long-reent
\series default 
\size large 
 
\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


\series bold 
---cyclomatic
\bar under 
 
\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 
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 List
\labelwidthstring 00.00.0000


\series bold 
---float-reent
\bar under 
 
\series default 
\bar default 
 Floating point library is compiled as reentrant.See section Installation
 for more details.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---nooverlay
\series 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


\series bold 
---main-return
\series 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


\series bold 
---no-peep
\series default 
  Disable peep-hole optimization.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---peep-asm
\series default 
  Pass the inline assembler code through the peep hole optimizer.
 This can cause unexpected changes to inline assembler code, please go through
 the peephole optimizer rules defined in the source file tree '<target>/peeph.def
' before using this option.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---iram-size
\series default 
<Value> Causes the linker to check if the internal ram usage is within limits
 of the given value.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---xram-size
\series default 
<Value> Causes the linker to check if the external ram usage is within limits
 of the given value.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---code-size
\series default 
<Value> Causes the linker to check if the code usage is within limits of
 the given value.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---nostdincl
\series default 
 This will prevent the compiler from passing on the default include path
 to the preprocessor.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---nostdlib
\series default 
 This will prevent the compiler from passing on the default library path
 to the linker.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---verbose
\series default 
 Shows the various actions the compiler is performing.
\layout List
\labelwidthstring 00.00.0000


\series bold 
-V
\series default 
 Shows the actual commands the compiler is executing.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---no-c-code-in-asm
\series default 
 Hides your ugly and inefficient c-code from the asm file, so you can always
 blame the compiler :).
\layout List
\labelwidthstring 00.00.0000


\series bold 
---i-code-in-asm
\series default 
 Include i-codes in the asm file.
 Looks like noise but is most helpfull for debugging the compiler itself.
\layout Subsubsection

Intermediate Dump Options
\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 List
\labelwidthstring 00.00.0000


\series bold 
---dumpraw
\series 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


\series bold 
---dumpgcse
\series default 
 Will create a dump of iCode's, after global subexpression elimination,
 into a file named 
\emph on 
<source filename>.dumpgcse.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---dumpdeadcode
\series default 
 Will create a dump of iCode's, after deadcode elimination, into a file
 named 
\emph on 
<source filename>.dumpdeadcode.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---dumploop
\series default 
\size large 
 
\size default 
Will create a dump of iCode's, after loop optimizations, into a file named
 
\emph on 
<source filename>.dumploop.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---dumprange
\series default 
\size large 
 
\size default 
Will create a dump of iCode's, after live range analysis, into a file named
 
\emph on 
<source filename>.dumprange.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---dumlrange
\series default 
 Will dump the life ranges for all symbols.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---dumpregassign
\bar under 
 
\series default 
\bar default 
Will create a dump of iCode's, after register assignment, into a file named
 
\emph on 
<source filename>.dumprassgn.
\layout List
\labelwidthstring 00.00.0000


\series bold 
---dumplrange
\series default 
 Will create a dump of the live ranges of iTemp's
\layout List
\labelwidthstring 00.00.0000


\series bold 
---dumpall
\size large 
\bar under 
 
\series default 
\size default 
\bar default 
Will cause all the above mentioned dumps to be created.
\layout Subsection

Environment variables
\layout Standard

SDCC recognizes the following environment variables:
\layout List
\labelwidthstring 00.00.0000


\series bold 
SDCC_LEAVE_SIGNALS
\series default 
 SDCC installs a signal handler to be able to delete temporary files after
 an user break (^C) or an exception.
 If this environment variable is set, SDCC won't install the signal handler
 in order to be able to debug SDCC.
\layout List
\labelwidthstring 00.00.0000


\series bold 
TMP,\SpecialChar ~
TEMP,\SpecialChar ~
TMPDIR
\series default 
 Path, where temporary files will be created.
 The order of the variables is the search order.
 In a standard *nix environment these variables are not set, and there's
 no need to set them.
 On Windows it's recommended to set one of them.
\layout List
\labelwidthstring 00.00.0000


\series bold 
(coming\SpecialChar ~
soon:\SpecialChar ~
SDCC_BIN_PATH)
\series default 
 Path, see 
\begin_inset Quotes sld
\end_inset 

2.1 Install and search paths
\begin_inset Quotes srd
\end_inset 

.
\layout List
\labelwidthstring 00.00.0000


\series bold 
(coming\SpecialChar ~
soon:\SpecialChar ~
SDCC_INCLUDE_PATH)
\series default 
 Path, see 
\begin_inset Quotes sld
\end_inset 

2.1 Install and search paths
\begin_inset Quotes srd
\end_inset 

.
\layout List
\labelwidthstring 00.00.0000


\series bold 
(coming\SpecialChar ~
soon:\SpecialChar ~
SDCC_LIB_PATH)
\series default 
 Path, see 
\begin_inset Quotes sld
\end_inset 

2.1 Install and search paths
\begin_inset Quotes srd
\end_inset 

.
\layout List
\labelwidthstring 00.00.0000


\series bold 
SDCCDIR\SpecialChar ~
(soon\SpecialChar ~
replaced\SpecialChar ~
by:\SpecialChar ~
SDCCPATH)
\series default 
 Path, see 
\begin_inset Quotes sld
\end_inset 

2.1 Install and search paths
\begin_inset Quotes srd
\end_inset 

.
\layout Standard

There are some more environment variables recognized by SDCC, but these
 are solely used for debugging purposes.
 They can change or disappear very quickly, and will never be documentated.
\layout Subsection

MCS51/DS390 Storage Class Language Extensions
\layout Standard

In addition to the ANSI storage classes SDCC allows the following MCS51
 specific storage classes.
\layout Subsubsection

xdata
\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, e.g.:
\newline 

\newline 

\family typewriter 
xdata unsigned char xduc;
\layout Subsubsection

data
\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, e.g.:
\newline 

\newline 

\family typewriter 
data int iramdata;
\layout Subsubsection

idata
\layout Standard

Variables declared with this storage class will be allocated into the indirectly
 addressable portion of the internal ram of a 8051, e.g.:
\newline 

\newline 

\family typewriter 
idata int idi;
\layout Subsubsection

bit
\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, e.g.:
\newline 

\newline 

\family typewriter 
bit iFlag;
\layout Subsubsection

sfr / sbit
\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, eg:
\newline 

\newline 

\family typewriter 
sfr at 0x80 P0; /* special function register P0 at location 0x80 */
\newline 
sbit at 0xd7 CY; /* CY (Carry Flag) */
\layout Subsection

Pointers
\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 uses (by default) generic
 pointers which can be used to point to any of the memory spaces.
\newline 

\newline 
Pointer declaration examples:
\newline 

\size small 

\newline 

\family typewriter 
\size default 
/* pointer physically in xternal ram pointing to object in internal ram
 */ 
\newline 
data unsigned char * xdata p;
\newline 

\newline 
/* pointer physically in code rom pointing to data in xdata space */ 
\newline 
xdata unsigned char * code p;
\newline 

\newline 
/* 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;
\family default 
\size small 

\newline 

\newline 

\size default 
Well you get the idea.
 
\newline 

\newline 
All unqualified pointers are treated as 3-byte (4-byte for the ds390) 
\emph on 
generic
\emph default 
 pointers.
 
\size small 

\newline 

\newline 

\size default 
The highest order byte of the 
\emph on 
generic
\emph default 
 pointers contains the data space information.
 Assembler support routines are called whenever data is stored or retrieved
 using 
\emph on 
generic
\emph default 
 pointers.
 These are useful for developing reusable library routines.
 Explicitly specifying the pointer type will generate the most efficient
 code.
\layout Subsection

Parameters & Local Variables
\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).
 This in fact makes them 
\emph on 
static
\emph default 
 so by default functions are non-reentrant.
\newline 

\newline 
They can be placed on the stack either by using the
\emph on 
 ---stack-auto
\emph default 
 option or by using the 
\emph on 
reentrant
\emph default 
 keyword in the function declaration, e.g.:
\newline 

\size small 

\newline 

\family typewriter 
\size default 
unsigned char foo(char i) reentrant 
\newline 
{ 
\newline 
...
 
\newline 
}
\newline 

\family default 

\newline 
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 that the reentrant keyword just means that the parameters & local
 variables will be allocated to the stack, it 
\emph on 
does not
\emph default 
 mean that the function is register bank independent.
\newline 

\newline 
Local variables can be assigned storage classes and absolute addresses,
 e.g.: 
\newline 

\newline 

\family typewriter 
unsigned char foo() {
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
xdata unsigned char i;
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
bit bvar;
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
data at 0x31 unsiged char j;
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
...
 
\newline 
}
\newline 

\newline 

\family default 
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 
\emph on 
---stack-auto
\emph default 
 or when a function is declared as 
\emph on 
reentrant
\emph default 
 this should only be done for static variables.
\layout Standard

Parameters however are not allowed any storage class, (storage classes for
 parameters will be ignored), their allocation is governed by the memory
 model in use, and the reentrancy options.
\layout Subsection

Overlaying
\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 overlayed.
\layout Standard

Note that the compiler (not the linkage editor) makes the decision for overlayin
g the data items.
 Functions that are called from an interrupt service routine should be preceded
 by a #pragma\SpecialChar ~
NOOVERLAY if they are not reentrant.
\layout Standard

Also note that the compiler does not do any processing of inline assembler
 code, so the compiler might incorrectly assign local variables and parameters
 of a function into the overlay segment if the inline assembler code calls
 other c-functions that might use the overlay.
 In that case the #pragma\SpecialChar ~
NOOVERLAY should be used.
\layout Standard

Parameters and Local variables of functions that contain 16 or 32 bit multiplica
tion or division will NOT be overlayed since these are implemented using
 external functions, e.g.:
\newline 

\newline 

\family typewriter 
#pragma SAVE 
\newline 
#pragma NOOVERLAY 
\newline 
void set_error(unsigned char errcd) 
\newline 
{
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
P3 = errcd;
\newline 
} 
\newline 
#pragma RESTORE 
\newline 

\newline 
void some_isr () interrupt 2 using 1 
\newline 
{
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
...
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
set_error(10);
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
...
 
\newline 
}
\newline 

\newline 

\family default 
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\SpecialChar ~
NOOVERLAY was
 not present, this could cause unpredictable runtime behavior when called
 from an ISR.
 The #pragma\SpecialChar ~
NOOVERLAY ensures that the parameters and local variables for
 the function are NOT overlayed.
\layout Subsection

Interrupt Service Routines
\layout Standard

SDCC allows interrupt service routines to be coded in C, with some extended
 keywords.
\newline 

\newline 

\family typewriter 
void timer_isr (void) interrupt 2 using 1 
\newline 
{ 
\newline 
..
 
\newline 
}
\newline 

\newline 

\family default 
The number following the 
\emph on 
interrupt
\emph default 
 keyword is the interrupt number this routine will service.
 The compiler will insert a call to this routine in the interrupt vector
 table for the interrupt number specified.
 The 
\emph on 
using
\emph default 
 keyword is used to tell the compiler to use the specified register bank
 (8051 specific) when generating code for this function.
 Note that when some function is called from an interrupt service routine
 it should be preceded by a #pragma\SpecialChar ~
NOOVERLAY if it is not reentrant.
 A special note here, int (16 bit) and long (32 bit) integer division, multiplic
ation & modulus operations are implemented using external support routines
 developed in ANSI-C, if an interrupt service routine needs to do any of
 these operations then the support routines (as mentioned in a following
 section) will have to be recompiled using the
\emph on 
 ---stack-auto
\emph default 
 option and the source file will need to be compiled using the 
\emph on 
---int-long-ren
\emph default 
t compiler option.
\layout Standard

If you have multiple source files in your project, interrupt service routines
 can be present in any of them, but a prototype of the isr MUST be present
 or included 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.
\newline 

\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="6" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Interrupt #
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Description
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Vector Address
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

0
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

External 0
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

0x0003
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

1
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Timer 0
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

0x000B
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

2
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

External 1
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

0x0013
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

3
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Timer 1
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

0x001B
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

4
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Serial
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

0x0023
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\newline 

\newline 
If the interrupt service routine is defined without 
\emph on 
using
\emph default 
 a register bank or with register bank 0 (using 0), the compiler will save
 the registers used by itself on the stack upon entry and restore them at
 exit, however if such an interrupt service routine calls another function
 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 
\emph on 
a, b & dptr
\emph default 
 are save and restored, if such an interrupt service routine calls another
 function (using another register bank) then the entire register bank of
 the called function will be saved on the stack.
 This scheme is recommended for larger interrupt service routines.
\layout Standard

Calling other functions from an interrupt service routine is not recommended,
 avoid it if possible.
\newline 

\newline 
Also see the _naked modifier.
\layout Subsection

Critical Functions
\layout Standard


\shape italic 
<TODO: this isn't implemented at all!>
\shape default 

\newline 

\newline 
A special keyword may be associated with a function declaring it as 
\emph on 
critical
\emph default 
.
 SDCC will generate code to disable all interrupts upon entry to a critical
 function and enable them back before returning.
 Note that nesting critical functions may cause unpredictable results.
\newline 

\size small 

\newline 

\family typewriter 
\size default 
int foo () critical 
\newline 
{ 
\newline 
...
 
\newline 
...
 
\newline 
}
\newline 

\family default 

\newline 
The critical attribute maybe used with other attributes like 
\emph on 
reentrant.
\layout Subsection

Naked Functions
\layout Standard

A special keyword may be associated with a function declaring it as 
\emph on 
_naked.
 
\emph default 
The 
\emph on 
_naked
\emph default 
 function modifier attribute prevents the compiler from generating prologue
 and epilogue code for that function.
 This means that the user is entirely responsible for such things as saving
 any registers that may need to be preserved, selecting the proper register
 bank, generating the 
\emph on 
return
\emph default 
 instruction at the end, etc.
 Practically, this means that the contents of the function must be written
 in inline assembler.
 This is particularly useful for interrupt functions, which can have a large
 (and often unnecessary) prologue/epilogue.
 For example, compare the code generated by these two functions:
\newline 

\newline 

\family typewriter 
data unsigned char counter;
\newline 
void simpleInterrupt(void) interrupt 1
\newline 
{
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
counter++;
\newline 
}
\newline 

\newline 
void nakedInterrupt(void) interrupt 2 _naked
\newline 
{
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_asm
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
inc\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_counter
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
reti\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
; MUST explicitly include ret in _naked function.
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_endasm;
\newline 
}
\family default 

\newline 

\newline 
For an 8051 target, the generated simpleInterrupt looks like:
\newline 

\newline 

\family typewriter 
_simpleIterrupt:
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
push\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
acc
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
push\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
b
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
push\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
dpl
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
push\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
dph
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
push\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
psw
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
psw,#0x00
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
inc\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_counter
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
pop\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
psw
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
pop\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
dph
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
pop\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
dpl
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
pop\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
b
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
pop\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
acc
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
reti
\family default 

\newline 

\newline 
whereas nakedInterrupt looks like:
\newline 

\newline 

\family typewriter 
_nakedInterrupt:
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
inc\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_counter
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
reti\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
; MUST explicitly include ret(i) in _naked function.
\family default 

\newline 

\newline 
While there is nothing preventing you from writing C code inside a _naked
 function, there are many ways to shoot yourself in the foot doing this,
 and it is recommended that you stick to inline assembler.
\layout Subsection

Functions using private banks
\layout Standard

The 
\emph on 
using
\emph default 
 attribute (which tells the compiler to use a register bank other than the
 default bank zero) should only be applied to 
\emph on 
interrupt
\emph default 
 functions (see note 1 below).
 This will in most circumstances make the generated ISR code more efficient
 since it will not have to save registers on the stack.
\layout Standard

The 
\emph on 
using
\emph default 
 attribute will have no effect on the generated code for a 
\emph on 
non-interrupt
\emph default 
 function (but may occasionally be useful anyway
\begin_inset Foot
collapsed true

\layout Standard

possible exception: if a function is called ONLY from 'interrupt' functions
 using a particular bank, it can be declared with the same 'using' attribute
 as the calling 'interrupt' functions.
 For instance, if you have several ISRs using bank one, and all of them
 call memcpy(), it might make sense to create a specialized version of memcpy()
 'using 1', since this would prevent the ISR from having to save bank zero
 to the stack on entry and switch to bank zero before calling the function
\end_inset 

).
\newline 

\emph on 
(pending: I don't think this has been done yet)
\layout Standard

An 
\emph on 
interrupt
\emph default 
 function using a non-zero bank will assume that it can trash that register
 bank, and will not save it.
 Since high-priority interrupts can interrupt low-priority ones on the 8051
 and friends, this means that if a high-priority ISR 
\emph on 
using
\emph default 
 a particular bank occurs while processing a low-priority ISR 
\emph on 
using
\emph default 
 the same bank, terrible and bad things can happen.
 To prevent this, no single register bank should be 
\emph on 
used
\emph default 
 by both a high priority and a low priority ISR.
 This is probably most easily done by having all high priority ISRs use
 one bank and all low priority ISRs use another.
 If you have an ISR which can change priority at runtime, you're on your
 own: I suggest using the default bank zero and taking the small performance
 hit.
\layout Standard

It is most efficient if your ISR calls no other functions.
 If your ISR must call other functions, it is most efficient if those functions
 use the same bank as the ISR (see note 1 below); the next best is if the
 called functions use bank zero.
 It is very inefficient to call a function using a different, non-zero bank
 from an ISR.
 
\layout Subsection

Absolute Addressing
\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, e.g.:
\newline 

\newline 

\family typewriter 
xdata at 0x8000 unsigned char PORTA_8255 ;
\newline 

\family default 

\newline 
In the above example the PORTA_8255 will be allocated to the location 0x8000
 of the external ram.
 Note that this feature is provided to give the programmer access to 
\emph on 
memory mapped
\emph default 
 devices attached to the controller.
 The compiler does not actually reserve any space for variables declared
 in this way (they are implemented with an equate in the assembler).
 Thus it is left to the programmer to make sure there are no overlaps with
 other variables that are declared without the absolute address.
 The assembler listing file (.lst) and the linker output files (.rst) and
 (.map) are a good places to look for such overlaps.
\newline 

\newline 
Absolute address can be specified for variables in all storage classes,
 e.g.:
\newline 

\newline 

\family typewriter 
bit at 0x02 bvar;
\newline 

\newline 

\family default 
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

Startup Code
\layout Standard

The compiler inserts a call to the C routine 
\emph on 
_sdcc__external__startup()
\series bold 
\emph default 
 
\series default 
at the start of the CODE area.
 This routine is in the runtime library.
 By default this routine returns 0, if this routine returns a non-zero value,
 the static & global variable initialization will be skipped and the function
 main will be invoked Other wise static & global variables will be initialized
 before the function main is invoked.
 You could add a 
\emph on 
_sdcc__external__startup()
\emph default 
 routine to your program to override the default if you need to setup hardware
 or perform some other critical operation prior to static & global variable
 initialization.
\layout Subsection

Inline Assembler Code
\layout Standard

SDCC allows the use of in-line assembler with a few restriction as regards
 labels.
 All labels defined within inline assembler code 
\emph on 
has to be
\emph default 
 of the form 
\emph on 
nnnnn$
\emph default 
 where nnnn is a number less than 100 (which implies a limit of utmost 100
 inline assembler labels 
\emph on 
per function
\emph default 
\noun on 
)
\noun default 
.
 It is strongly recommended that each assembly instruction (including labels)
 be placed in a separate line (as the example shows).
 When the 
\emph on 
---peep-asm
\emph default 
 command line option is used, the inline assembler code will be passed through
 the peephole optimizer.
 This might cause some unexpected changes in the inline assembler code.
 Please go throught the peephole optimizer rules defined in file 
\emph on 
SDCCpeeph.def
\emph default 
 carefully before using this option.
\newline 

\newline 

\family typewriter 
_asm 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
b,#10 
\newline 
00001$: 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
djnz\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
b,00001$ 
\newline 
_endasm ;
\family default 
\size small 

\newline 

\newline 

\size default 
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 
\family typewriter 
_asm ...
 _endasm;
\family default 
 keyword pair.
 
\newline 

\newline 
Inline assembler code cannot reference any C-Labels, however it can reference
 labels defined by the inline assembler, e.g.:
\newline 

\newline 

\family typewriter 
foo() { 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* some c code */ 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_asm 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
; some assembler code 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
ljmp $0003 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_endasm; 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* some more c code */ 
\newline 
clabel:\SpecialChar ~
\SpecialChar ~
/* inline assembler cannot reference this label */ 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_asm
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
$0003: ;label (can be reference by inline assembler only) 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
_endasm ; 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* some more c code */
\newline 
}
\newline 

\newline 

\family default 
In other words inline assembly code can access labels defined in inline
 assembly within the scope of the funtion.
 
\layout Standard

The same goes the other way, ie.
 labels defines in inline assembly CANNOT be accessed by C statements.
\layout Subsection

int (16 bit) and long (32 bit) Support
\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, although some model specific assembler optimations are used.
 The following files contain the described routine, all of them can be found
 in <installdir>/share/sdcc/lib.
\newline 

\newline 

\emph on 
<pending: tabularise this>
\emph default 

\newline 

\newline 
_mulsint.c - signed 16 bit multiplication (calls _muluint)
\newline 
_muluint.c - unsigned 16 bit multiplication
\newline 
_divsint.c - signed 16 bit division (calls _divuint)
\newline 
_divuint.c - unsigned 16 bit division
\newline 
_modsint.c - signed 16 bit modulus (call _moduint)
\newline 
_moduint.c - unsigned 16 bit modulus
\newline 
_mulslong.c - signed 32 bit multiplication (calls _mululong)
\newline 
_mululong.c - unsigned32 bit multiplication
\newline 
_divslong.c - signed 32 division (calls _divulong)
\newline 
_divulong.c - unsigned 32 division
\newline 
_modslong.c - signed 32 bit modulus (calls _modulong)
\newline 
_modulong.c - unsigned 32 bit modulus 
\size footnotesize 

\newline 

\newline 

\size default 
Since they are compiled as 
\emph on 
non-reentrant
\emph default 
, interrupt service routines should not do any of the above operations.
 If this is unavoidable then the above routines will need to be compiled
 with the 
\emph on 
---stack-auto
\emph default 
 option, after which the source program will have to be compiled with 
\emph on 
---int-long-rent
\emph default 
 option.
\layout Subsection

Floating Point Support
\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:
\newline 

\newline 

\emph on 
<pending: tabularise this>
\emph default 

\newline 

\newline 
_fsadd.c - add floating point numbers
\newline 
_fssub.c - subtract floating point numbers
\newline 
_fsdiv.c - divide floating point numbers
\newline 
_fsmul.c - multiply floating point numbers
\newline 
_fs2uchar.c - convert floating point to unsigned char
\newline 
_fs2char.c - convert floating point to signed char
\newline 
_fs2uint.c - convert floating point to unsigned int
\newline 
_fs2int.c - convert floating point to signed int
\newline 
_fs2ulong.c - convert floating point to unsigned long
\newline 
_fs2long.c - convert floating point to signed long
\newline 
_uchar2fs.c - convert unsigned char to floating point
\newline 
_char2fs.c - convert char to floating point number
\newline 
_uint2fs.c - convert unsigned int to floating point
\newline 
_int2fs.c - convert int to floating point numbers
\newline 
_ulong2fs.c - convert unsigned long to floating point number
\newline 
_long2fs.c - convert long to floating point number
\size footnotesize 

\newline 

\newline 

\size default 
Note if all these routines are used simultaneously the data space might
 overflow.
 For serious floating point usage it is strongly recommended that the large
 model be used.
\layout Subsection

MCS51 Memory Models
\layout Standard

SDCC allows two memory models for MCS51 code, small and large.
 Modules compiled with different memory models should 
\emph on 
never
\emph default 
 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.
 
\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 Subsection

DS390 Memory Models
\layout Standard

The only model supported is Flat 24.
 This generates code for the 24 bit contiguous addressing mode of the Dallas
 DS80C390 part.
 In this mode, up to four meg of external RAM or code space can be directly
 addressed.
 See the data sheets at www.dalsemi.com for further information on this part.
\newline 

\newline 
In older versions of the compiler, this option was used with the MCS51 code
 generator (
\emph on 
-mmcs51
\emph default 
).
 Now, however, the '390 has it's own code generator, selected by the 
\emph on 
-mds390
\emph default 
 switch.
 
\newline 

\newline 
Note that the compiler does not generate any code to place the processor
 into 24 bitmode (although 
\emph on 
tinibios
\emph default 
 in the ds390 libraries will do that for you).
 If you don't use 
\emph on 
tinibios
\emph default 
, the boot loader or similar code must ensure that the processor is in 24
 bit contiguous addressing mode before calling the SDCC startup code.
\newline 

\newline 
Like the 
\emph on 
---model-large
\emph default 
 option, variables will by default be placed into the XDATA segment.
 
\newline 

\newline 
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 
\emph on 
-Wl-r
\emph default 
 on the sdcc command line.
 However, currently the linker can not handle code segments > 64k.
\layout Subsection

Defines Created by the Compiler
\layout Standard

The compiler creates the following #defines.
\layout Itemize

SDCC - this Symbol is always defined.
\layout Itemize

SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model used
 (e.g.: -mds390)
\layout Itemize

__mcs51 or __ds390 or __z80, etc - depending on the model used (e.g.
 -mz80)
\layout Itemize

SDCC_STACK_AUTO - this symbol is defined when 
\emph on 
---stack-auto
\emph default 
 option is used.
\layout Itemize

SDCC_MODEL_SMALL - when 
\emph on 
---model-small
\emph default 
 is used.
\layout Itemize

SDCC_MODEL_LARGE - when 
\emph on 
---model-large
\emph default 
 is used.
\layout Itemize

SDCC_USE_XSTACK - when 
\emph on 
---xstack
\emph default 
 option is used.
\layout Itemize

SDCC_STACK_TENBIT - when 
\emph on 
-mds390
\emph default 
 is used
\layout Itemize

SDCC_MODEL_FLAT24 - when 
\emph on 
-mds390
\emph default 
 is used
\layout Section

SDCC Technical Data
\layout Subsection

Optimizations
\layout Standard

SDCC performs a host of standard optimizations in addition to some MCU specific
 optimizations.
 
\layout Subsubsection

Sub-expression Elimination
\layout Standard

The compiler does local and global common subexpression elimination, e.g.:
 
\newline 

\newline 

\family typewriter 
i = x + y + 1; 
\newline 
j = x + y;
\family default 

\newline 

\newline 
will be translated to
\newline 

\newline 

\family typewriter 
iTemp = x + y 
\newline 
i = iTemp + 1 
\newline 
j = iTemp
\newline 

\family default 

\newline 
Some subexpressions are not as obvious as the above example, e.g.:
\newline 

\newline 

\family typewriter 
a->b[i].c = 10; 
\newline 
a->b[i].d = 11;
\family default 

\newline 

\newline 
In this case the address arithmetic a->b[i] will be computed only once;
 the equivalent code in C would be.
\newline 

\newline 

\family typewriter 
iTemp = a->b[i]; 
\newline 
iTemp.c = 10; 
\newline 
iTemp.d = 11;
\family default 

\newline 

\newline 
The compiler will try to keep these temporary variables in registers.
\layout Subsubsection

Dead-Code Elimination
\layout Standard


\family typewriter 
int global; 
\newline 
void f () { 
\newline 
\SpecialChar ~
\SpecialChar ~
int i; 
\newline 
\SpecialChar ~
\SpecialChar ~
i = 1; \SpecialChar ~
/* dead store */ 
\newline 
\SpecialChar ~
\SpecialChar ~
global = 1;\SpecialChar ~
/* dead store */ 
\newline 
\SpecialChar ~
\SpecialChar ~
global = 2; 
\newline 
\SpecialChar ~
\SpecialChar ~
return; 
\newline 
\SpecialChar ~
\SpecialChar ~
global = 3;\SpecialChar ~
/* unreachable */ 
\newline 
}
\family default 

\newline 

\newline 
will be changed to
\newline 

\newline 

\family typewriter 
int global; void f () 
\newline 
{
\newline 
\SpecialChar ~
\SpecialChar ~
global = 2; 
\newline 
\SpecialChar ~
\SpecialChar ~
return; 
\newline 
}
\layout Subsubsection

Copy-Propagation
\layout Standard


\family typewriter 
int f() { 
\newline 
\SpecialChar ~
\SpecialChar ~
int i, j; 
\newline 
\SpecialChar ~
\SpecialChar ~
i = 10; 
\newline 
\SpecialChar ~
\SpecialChar ~
j = i; 
\newline 
\SpecialChar ~
\SpecialChar ~
return j; 
\newline 
}
\family default 

\newline 

\newline 
will be changed to 
\newline 

\newline 

\family typewriter 
int f() { 
\newline 
\SpecialChar ~
 \SpecialChar ~
 int i,j; 
\newline 
\SpecialChar ~
 \SpecialChar ~
 i = 10; 
\newline 
\SpecialChar ~
 \SpecialChar ~
 j = 10; 
\newline 
\SpecialChar ~
 \SpecialChar ~
 return 10; 
\newline 
}
\newline 

\newline 

\family default 
Note: the dead stores created by this copy propagation will be eliminated
 by dead-code elimination.
\layout Subsubsection

Loop Optimizations
\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 optimizati
on causes an increase in register pressure, which may cause unwanted spilling
 of other temporary variables into the stack / data space.
 The compiler will generate a warning message when it is forced to allocate
 extra space either on the stack or data space.
 If this extra space allocation is undesirable then induction optimization
 can be eliminated either for the entire source file (with ---noinduction
 option) or for a given function only using #pragma\SpecialChar ~
NOINDUCTION.
\newline 

\newline 
Loop Invariant:
\newline 

\newline 

\family typewriter 
for (i = 0 ; i < 100 ; i ++) 
\newline 
 \SpecialChar ~
 \SpecialChar ~
f += k + l;
\family default 

\newline 

\newline 
changed to
\newline 

\newline 

\family typewriter 
itemp = k + l; 
\newline 
for (i = 0; i < 100; i++) 
\newline 
\SpecialChar ~
\SpecialChar ~
f += itemp;
\family default 

\newline 

\newline 
As mentioned previously some loop invariants are not as apparent, all static
 address computations are also moved out of the loop.
\newline 

\newline 
Strength Reduction, this optimization substitutes an expression by a cheaper
 expression:
\newline 

\newline 

\family typewriter 
for (i=0;i < 100; i++)
\newline 
\SpecialChar ~
\SpecialChar ~
ar[i*5] = i*3;
\family default 

\newline 

\newline 
changed to
\newline 

\newline 

\family typewriter 
itemp1 = 0; 
\newline 
itemp2 = 0; 
\newline 
for (i=0;i< 100;i++) { 
\newline 
 \SpecialChar ~
 \SpecialChar ~
ar[itemp1] = itemp2; 
\newline 
 \SpecialChar ~
 \SpecialChar ~
itemp1 += 5; 
\newline 
 \SpecialChar ~
 \SpecialChar ~
itemp2 += 3; 
\newline 
}
\family default 

\newline 

\newline 
The more expensive multiplication is changed to a less expensive addition.
\layout Subsubsection

Loop Reversing
\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 compilers use data-dependency analysis to make
 this determination, SDCC uses a more simple minded analysis).
\layout Itemize

The 'for' loop is of the form 
\newline 

\newline 

\family typewriter 
for (<symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
 <sym> += 1])
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
<for body>
\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 Subsubsection

Algebraic Simplifications
\layout Standard

SDCC does numerous algebraic simplifications, the following is a small sub-set
 of these optimizations.
\newline 

\newline 

\family typewriter 
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;
\family default 

\newline 

\newline 
Note the subexpressions given above are generally introduced by macro expansions
 or as a result of copy/constant propagation.
\layout Subsubsection

'switch' Statements
\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.
\newline 

\newline 

\family typewriter 
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 ~
}
\newline 

\newline 

\family default 
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, e.g.:
\newline 

\newline 

\family typewriter 
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 
}
\family default 

\newline 

\newline 
If the above switch statement is broken down into two switch statements
\newline 

\newline 

\family typewriter 
switch (i) { 
\newline 
case 1: ...
 
\newline 
case 2: ...
 
\newline 
case 3: ...
 
\newline 
case 4: ...
 
\newline 
}
\newline 

\newline 

\family default 
and
\family typewriter 

\newline 

\newline 
switch (i) { 
\newline 
case 9: \SpecialChar ~
...
 
\newline 
case 10: ...
 
\newline 
case 11: ...
 
\newline 
case 12:\SpecialChar ~
...
 
\newline 
}
\newline 

\newline 

\family default 
then both the switch statements will be implemented using jump-tables whereas
 the unmodified switch statement will not be.
\layout Subsubsection

Bit-shifting Operations.
\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, e.g.:
\newline 

\family typewriter 

\newline 
unsigned char i;
\newline 
...
 
\newline 
i>>= 4; 
\newline 
...
\newline 

\family default 

\newline 
generates the following code:
\newline 

\family typewriter 

\newline 
mov a,_i 
\newline 
swap a 
\newline 
anl a,#0x0f 
\newline 
mov _i,a
\family default 

\newline 

\newline 
In general SDCC will never setup a loop if the shift count is known.
 Another example:
\newline 

\newline 

\family typewriter 
unsigned int i; 
\newline 
...
 
\newline 
i >>= 9; 
\newline 
...
\family default 

\newline 

\newline 
will generate:
\newline 

\newline 

\family typewriter 
mov a,(_i + 1) 
\newline 
mov (_i + 1),#0x00 
\newline 
clr c 
\newline 
rrc a 
\newline 
mov _i,a
\family default 

\newline 

\newline 
Note that SDCC stores numbers in little-endian format (i.e.
 lowest order first).
\layout Subsubsection

Bit-rotation
\layout Standard

A special case of the bit-shift operation is bit rotation, SDCC recognizes
 the following expression to be a left bit-rotation:
\newline 

\newline 

\family typewriter 
unsigned char i; 
\newline 
...
 
\newline 
i = ((i << 1) | (i >> 7)); 
\family default 

\newline 
...
\newline 

\newline 
will generate the following code:
\newline 

\newline 

\family typewriter 
mov a,_i 
\newline 
rl a 
\newline 
mov _i,a
\family default 

\newline 

\newline 
SDCC uses pattern matching on the parse tree to determine this operation.Variatio
ns of this case will also be recognized as bit-rotation, i.e.: 
\newline 

\newline 

\family typewriter 
i = ((i >> 7) | (i << 1)); /* left-bit rotation */
\layout Subsubsection

Highest Order Bit
\layout Standard

It is frequently required to obtain the highest order bit of an integral
 type (long, int, short or char types).
 SDCC recognizes the following expression to yield the highest order bit
 and generates optimized code for it, e.g.:
\newline 

\newline 
 
\family typewriter 
unsigned int gint; 
\newline 

\newline 
foo () { 
\newline 
unsigned char hob; 
\newline 
\SpecialChar ~
\SpecialChar ~
...
 
\newline 
\SpecialChar ~
\SpecialChar ~
hob = (gint >> 15) & 1; 
\newline 
\SpecialChar ~
\SpecialChar ~
..
 
\newline 
}
\family default 

\newline 

\newline 
will generate the following code:
\newline 

\family typewriter 

\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 ~
 61 ;\SpecialChar ~
 hob.c 7 
\newline 
\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
\newline 

\newline 

\family default 
Variations of this case however will 
\emph on 
not
\emph default 
 be recognized.
 It is a standard C expression, so I heartily recommend this be the only
 way to get the highest order bit, (it is portable).
 Of course it will be recognized even if it is embedded in other expressions,
 e.g.:
\newline 

\newline 

\family typewriter 
xyz = gint + ((gint >> 15) & 1);
\family default 

\newline 

\newline 
will still be recognized.
\layout Subsubsection

Peep-hole Optimizer
\layout Standard

The compiler uses a rule based, pattern matching and re-writing mechanism
 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 
\emph on 
---peep-file <filename>
\emph default 
 option.
 The rule language is best illustrated with examples.
\newline 

\newline 

\family typewriter 
replace { 
\newline 
\SpecialChar ~
\SpecialChar ~
mov %1,a 
\newline 
\SpecialChar ~
\SpecialChar ~
mov a,%1
\newline 
} by {
\newline 
\SpecialChar ~
\SpecialChar ~
mov %1,a
\newline 
}
\family default 

\newline 

\newline 
The above rule will change the following assembly sequence:
\newline 

\newline 

\family typewriter 
\SpecialChar ~
\SpecialChar ~
mov r1,a 
\newline 
\SpecialChar ~
\SpecialChar ~
mov a,r1
\family default 

\newline 

\newline 
to
\newline 

\newline 

\family typewriter 
mov r1,a
\family default 

\newline 

\newline 
Note: All occurrences of a 
\emph on 
%n
\emph default 
 (pattern variable) must denote the same string.
 With the above rule, the assembly sequence:
\newline 

\newline 

\family typewriter 
\SpecialChar ~
\SpecialChar ~
mov r1,a 
\newline 
\SpecialChar ~
\SpecialChar ~
mov a,r2
\family default 

\newline 

\newline 
will remain unmodified.
\newline 

\newline 
Other special case optimizations may be added by the user (via 
\emph on 
---peep-file option
\emph default 
).
 E.g.
 some variants of the 8051 MCU allow only 
\family typewriter 
ajmp
\family default 
 and 
\family typewriter 
acall
\family default 
.
 The following two rules will change all 
\family typewriter 
ljmp
\family default 
 and 
\family typewriter 
lcall
\family default 
 to 
\family typewriter 
ajmp
\family default 
 and 
\family typewriter 
acall
\family default 

\newline 

\newline 

\family typewriter 
replace { lcall %1 } by { acall %1 } 
\newline 
replace { ljmp %1 } by { ajmp %1 }
\family default 

\newline 

\newline 
The 
\emph on 
inline-assembler code
\emph default 
 is also passed through the peep hole optimizer, thus the peephole optimizer
 can also be used as an assembly level macro expander.
 The rules themselves are MCU dependent whereas the rule language infra-structur
e is MCU independent.
 Peephole optimization rules for other MCU can be easily programmed using
 the rule language.
\newline 

\newline 
The syntax for a rule is as follows:
\newline 

\newline 

\family typewriter 
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 

\family default 

\newline 
<assembly sequence> := assembly instruction (each instruction including
 labels must be on a separate line).
\newline 

\newline 
The optimizer will apply to the rules one by one from the top in the sequence
 of their appearance, it will terminate when all rules are exhausted.
 If the '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.
 An example of this (not a good one, it has side effects) is the following
 rule:
\newline 

\newline 

\family typewriter 
replace restart { 
\newline 
\SpecialChar ~
\SpecialChar ~
pop %1 
\newline 
\SpecialChar ~
\SpecialChar ~
push %1 } by { 
\newline 
\SpecialChar ~
\SpecialChar ~
; nop 
\newline 
}
\family default 

\newline 

\newline 
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.:
\newline 

\newline 

\family typewriter 
\SpecialChar ~
\SpecialChar ~
pop ar1 
\newline 
\SpecialChar ~
\SpecialChar ~
pop ar2 
\newline 
\SpecialChar ~
\SpecialChar ~
push ar2 
\newline 
\SpecialChar ~
\SpecialChar ~
push ar1
\family default 

\newline 

\newline 
would result in:
\newline 

\newline 

\family typewriter 
\SpecialChar ~
\SpecialChar ~
pop ar1 
\newline 
\SpecialChar ~
\SpecialChar ~
; nop 
\newline 
\SpecialChar ~
\SpecialChar ~
push ar1
\family default 

\newline 

\newline 

\emph on 
with
\emph default 
 the restart option the rule will be applied again to the resulting code
 and then all the pop-push pairs will be eliminated to yield:
\newline 

\newline 

\family typewriter 
\SpecialChar ~
\SpecialChar ~
; nop 
\newline 
\SpecialChar ~
\SpecialChar ~
; nop
\family default 

\newline 

\newline 
A conditional function can be attached to a rule.
 Attaching rules are somewhat more involved, let me illustrate this with
 an example.
\newline 

\newline 

\family typewriter 
replace { 
\newline 
\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
ljmp %5 
\newline 
%2:
\newline 
} by { 
\newline 
\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
sjmp %5 
\newline 
%2:
\newline 
} if labelInRange
\family default 

\newline 

\newline 
The optimizer does a look-up of a function name table defined in function
 
\emph on 
callFuncByName
\emph default 
 in the source file SDCCpeeph.c, 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
 labelInRange and the calling mechanism in source file SDCCpeeph.c.
 I know this whole thing is a little kludgey, but maybe some day we will
 have some better means.
 If you are looking at this file, you will also see the default rules that
 are compiled into the compiler, you can add your own rules in the default
 set there if you get tired of specifying the ---peep-file option.
\layout Subsection

Pragmas
\layout Standard

SDCC supports the following #pragma directives.
 This directives are applicable only at a function level.
\layout Itemize

SAVE - this will save all the current options.
\layout Itemize

RESTORE - will restore the saved options from the last save.
 Note that SAVES & RESTOREs cannot be nested.
 SDCC uses the same buffer to save the options each time a SAVE is called.
\layout Itemize

NOGCSE - will stop global subexpression elimination.
\layout Itemize

NOINDUCTION - will stop loop induction optimizations.
\layout Itemize

NOJTBOUND - will not generate code for boundary value checking, when switch
 statements are turned into jump-tables.
\layout Itemize

NOOVERLAY - the compiler will not overlay the parameters and local variables
 of a function.
\layout Itemize

NOLOOPREVERSE - Will not do loop reversal optimization
\layout Itemize

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\SpecialChar ~
EXCLUDE\SpecialChar ~
none.
\layout Itemize

NOIV - Do not generate interrupt vector table entries for all ISR functions
 defined after the pragma.
 This is useful in cases where the interrupt vector table must be defined
 manually, or when there is a secondary, manually defined interrupt vector
 table (e.g.
 for the autovector feature of the Cypress EZ-USB FX2).
\layout Itemize

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\SpecialChar ~
CALLEE-SAVES is appended to the list of functions specified inthe
 command line.
\layout Standard

The pragma's are intended to be used to turn-off certain optimizations which
 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.
\newline 

\newline 

\family typewriter 
#pragma SAVE /* save the current settings */ 
\newline 
#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 */
\family default 

\newline 

\newline 
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


\emph on 
<pending: this is messy and incomplete>
\emph default 
 Library Routines
\layout Enumerate

Compiler support routines (_gptrget, _mulint etc)
\layout Enumerate

Stdclib functions (puts, printf, strcat etc)
\layout Enumerate

Math functions (sin, pow, sqrt etc)
\layout Subsection

Interfacing with Assembly Routines
\layout Subsubsection

Global Registers used for Parameter Passing
\layout Standard

The compiler always uses the global registers 
\emph on 
DPL,DPH,B 
\emph default 
and
\emph on 
 ACC
\emph default 
 to pass the first parameter to a routine.
 The second parameter onwards is either allocated on the stack (for reentrant
 routines or if ---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 cfunc calls an assembler routine asm_func,
 which takes two parameters.
\newline 

\newline 

\family typewriter 
extern int asm_func(unsigned char, unsigned char);
\newline 

\newline 
int c_func (unsigned char i, unsigned char j)
\newline 
{
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
return asm_func(i,j);
\newline 
}
\newline 

\newline 
int main()
\newline 
{
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
return c_func(10,9);
\newline 
}
\newline 

\newline 

\family default 
The corresponding assembler function is:
\newline 

\newline 

\family typewriter 
.globl _asm_func_PARM_2 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
.globl _asm_func 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
.area OSEG 
\newline 
_asm_func_PARM_2:
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
.ds      1 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
.area CSEG 
\newline 
_asm_func: 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov     a,dpl 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
add     a,_asm_func_PARM_2 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov     dpl,a 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov     dpl,#0x00 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
ret
\newline 

\newline 

\family default 
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 _<function_name>_PARM_<n>, where n is
 the parameter number starting from 1, and counting from the left.
 The first parameter is passed in 
\begin_inset Quotes eld
\end_inset 

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 varible name for the second parameter will be _<function_na
me>_PARM_2.
\newline 

\newline 
Assemble the assembler routine with the following command:
\newline 

\newline 

\family sans 
\series bold 
asx8051 -losg asmfunc.asm
\newline 

\newline 

\family default 
\series default 
Then compile and link the assembler routine to the C source file with the
 following command:
\newline 

\newline 

\family sans 
\series bold 
sdcc cfunc.c asmfunc.rel
\layout Subsubsection

Assembler Routine(reentrant)
\layout Standard

In this case the second parameter onwards will be passed on the stack, the
 parameters are pushed from right to left i.e.
 after the call the left most parameter will be on the top of the stack.
 Here is an example:
\newline 

\newline 

\family typewriter 
extern int asm_func(unsigned char, unsigned char);
\newline 

\newline 
int c_func (unsigned char i, unsigned char j) reentrant 
\newline 
{ 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
return asm_func(i,j); 
\newline 
} 
\newline 

\newline 
int main() 
\newline 
{ 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
return c_func(10,9); 
\newline 
}
\newline 

\family default 

\newline 
The corresponding assembler routine is:
\newline 

\newline 

\family typewriter 
.globl _asm_func 
\newline 
_asm_func: 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
push  _bp 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov  _bp,sp 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov  r2,dpl
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov  a,_bp 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
clr  c 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
add  a,#0xfd 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov  r0,a 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
add  a,#0xfc
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov  r1,a 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov  a,@r0 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
add  a,r2
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov  dpl,a 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov  dph,#0x00 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov  sp,_bp 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
pop  _bp 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
ret
\newline 

\newline 

\family default 
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

External Stack
\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

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

ANSI-Compliance
\layout Standard

Deviations from the compliancy.
\layout Itemize

functions are not always reentrant.
\layout Itemize

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, e.g.:
\family typewriter 

\newline 

\newline 
struct s { ...
 }; 
\newline 
struct s s1, s2; 
\newline 
foo() 
\newline 
{ 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
...
 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
...
 
\newline 
}
\newline 
struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
 ANSI */ 
\newline 
{ 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
struct s rets; 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
...
 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
return rets;/* is invalid in SDCC although allowed in ANSI */ 
\newline 
}
\layout Itemize

'long long' (64 bit integers) not supported.
\layout Itemize

'double' precision floating point not supported.
\layout Itemize

No support for setjmp and longjmp (for now).
\layout Itemize

Old K&R style function declarations are NOT allowed.
\newline 

\family typewriter 

\newline 
foo(i,j) /* this old style of function declarations */ 
\newline 
int i,j; /* are valid in ANSI but not valid in SDCC */ 
\newline 
{ 
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
...
 
\newline 
}
\layout Itemize

functions declared as pointers must be dereferenced during the call.
\newline 

\family typewriter 

\newline 
int (*foo)();
\newline 
...
 
\newline 
/* has to be called like this */ 
\newline 
(*foo)(); /* ansi standard allows calls to be made like 'foo()' */
\layout Subsection

Cyclomatic Complexity
\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.
 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.
 
\newline 

\newline 
SDCC uses the following formula to compute the complexity:
\newline 

\layout Standard

complexity = (number of edges in control flow graph) - (number of nodes
 in control flow graph) + 2;
\newline 

\newline 
Having said that the industry standard is 10, you should be aware that in
 some cases it be 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
\layout Standard

Here are a few guidelines 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

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 an 'unsigned char' instead of a 'short' or 'int'.
\layout Itemize

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

NEVER jump into a LOOP.
\layout Itemize

Declare the variables to be local whenever possible, especially loop control
 variables (induction).
\layout Itemize

Since the compiler does not always do implicit integral promotion, the programme
r 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.
\family typewriter 

\newline 

\newline 
foobar(unsigned int p1, unsigned char ch)
\newline 
{
\newline 
    unsigned char ch1 = p1 % ch ;
\newline 
    ....
    
\newline 
}
\newline 

\family default 

\newline 
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 support routine _moduint()), and the result will be casted to a
 char.
 If the code is changed to 
\newline 

\family typewriter 

\newline 
foobar(unsigned int p1, unsigned char ch)
\newline 
{
\newline 
    unsigned char ch1 = (unsigned char)p1 % ch ;
\newline 
    ....
    
\newline 
}
\newline 

\family default 

\newline 
It would substantially reduce the code generated (future versions of the
 compiler will be smart enough to detect such optimization oppurtunities).
\layout Subsection

Notes on MCS51 memory layout
\layout Standard

The 8051 family of micro controller have a minimum of 128 bytes of internal
 memory which is structured as follows
\newline 

\newline 
- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
 
\newline 
- Bytes 20-2F - 16 bytes to hold 128 bit variables and 
\newline 
- Bytes 30-7F - 60 bytes for general purpose use.
\newline 

\newline 
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

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

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) and 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 code which will be slower to execute.
 
\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

---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.
\newline 

\newline 
Conclusion.
\newline 

\newline 
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 bit variables, ---data-loc
 16, and use the ---stack-after-data option.
\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.
\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 Itemize

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 Itemize

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 Itemize

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:
\newline 

\newline 
Break down intermediate code (iCode) into basic blocks.
\newline 
Do control flow & data flow analysis on the basic blocks.
\newline 
Do local common subexpression elimination, then global subexpression elimination
\newline 
Dead code elimination
\newline 
Loop optimizations
\newline 
If loop optimizations caused any changes then do 'global subexpression eliminati
on' and 'dead code elimination' again.
\layout Itemize

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 Itemize

Phase five is register allocation.
 There are two parts to this process.
\newline 

\newline 
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.
\newline 

\newline 
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.
\layout Itemize

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 Itemize

As mentioned in the optimization section the peep-hole optimizer is rule
 based system, which can reprogrammed for other MCUs.
\layout Section

SDCDB - Source Level Debugger
\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 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

Compiling for Debugging
\layout Standard

The \SpecialChar \-
\SpecialChar \-
debug option must be specified for all files for which debug information
 is to be generated.
 The complier generates a .cdb file for each of these files.
 The linker updates the .cdb file with the address information.
 This .cdb is used by the debugger.
\layout Subsection

How the Debugger Works
\layout Standard

When the ---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.
\layout Subsection

Starting the Debugger
\layout Standard

The debugger can be started using the following command line.
 (Assume the file you are debugging has the file name foo).
\newline 

\newline 

\family sans 
\series bold 
sdcdb foo
\newline 

\family default 
\series default 

\newline 
The debugger will look for the following files.
\layout Itemize

foo.c - the source file.
\layout Itemize

foo.cdb - the debugger symbol information file.
\layout Itemize

foo.ihx - the intel hex format object file.
\layout Subsection

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.
 
\layout Itemize

-cd <directory> - change to the <directory>.
\layout Itemize

-fullname - used by GUI front ends.
\layout Itemize

-cpu <cpu-type> - this argument is passed to the simulator please see the
 simulator docs for details.
\layout Itemize

-X <Clock frequency > this options is passed to the simulator please see
 the simulator docs for details.
\layout Itemize

-s <serial port file> passed to simulator see the simulator docs for details.
\layout Itemize

-S <serial in,out> passed to simulator see the simulator docs for details.
\layout Subsection

Debugger Commands.
\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 the integration with existing graphical user interfaces
 (like ddd, xxgdb or xemacs) existing for the GNU debugger.
\layout Subsubsection

break [line | file:line | function | file:function]
\layout Standard

Set breakpoint at specified line or function:
\newline 

\newline 

\family sans 
\series bold 
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 ]
\layout Standard

Clear breakpoint at specified line or function:
\newline 

\newline 

\family sans 
\series bold 
sdcdb>clear 100
\newline 
sdcdb>clear foo.c:100
\newline 
sdcdb>clear funcfoo
\newline 
sdcdb>clear foo.c:funcfoo
\layout Subsubsection

continue
\layout Standard

Continue program being debugged, after breakpoint.
\layout Subsubsection

finish
\layout Standard

Execute till the end of the current function.
\layout Subsubsection

delete [n]
\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

info break - list all breakpoints
\layout Itemize

info stack - show the function call stack.
\layout Itemize

info frame - show information about the current execution frame.
\layout Itemize

info registers - show content of all registers.
\layout Subsubsection

step
\layout Standard

Step program until it reaches a different source line.
\layout Subsubsection

next
\layout Standard

Step program, proceeding through subroutine calls.
\layout Subsubsection

run
\layout Standard

Start debugged program.
\layout Subsubsection

ptype variable 
\layout Standard

Print type information of the variable.
\layout Subsubsection

print variable
\layout Standard

print value of variable.
\layout Subsubsection

file filename
\layout Standard

load the given file name.
 Note this is an alternate method of loading file for debugging.
\layout Subsubsection

frame
\layout Standard

print information about current frame.
\layout Subsubsection

set srcmode
\layout Standard

Toggle between C source & assembly source.
\layout Subsubsection

! 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

quit.
\layout Standard

"Watch me now.
 Iam going Down.
 My name is Bobby Brown"
\layout Subsection

Interfacing with XEmacs.
\layout Standard

Two files (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 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 '.xemacs' file (which can be found in your HOME directory): 
\newline 

\newline 

\family typewriter 
(load-file sdcdbsrc.el) 
\family default 

\newline 

\newline 
.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
 (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
 To start the interface enter the following command: 
\newline 

\newline 

\family sans 
\series bold 
ESC-x sdcdbsrc
\family default 
\series default 

\newline 

\newline 
You will prompted to enter the file name to be debugged.
 
\newline 

\newline 
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.
\layout Itemize

sdcdbsrc-cpu-type '51
\layout Itemize

sdcdbsrc-frequency '11059200
\layout Itemize

sdcdbsrc-serial nil
\layout Standard

The following is a list of key mapping for the debugger interface.
\layout Standard

\SpecialChar ~

\family typewriter 

\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 ~
\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 ~
\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 ~
\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 ~
\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 
;; 
\family default 

\newline 

\layout Section

Other Processors
\layout Subsection

The Z80 and gbz80 port
\layout Standard

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.
 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.
\layout Section

Support
\layout Standard

SDCC has grown to be a large project.
 The compiler alone (without the preprocessor, assembler and linker) 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 Section

Compiler internals
\layout Subsection

The anatomy of the compiler
\layout Standard


\shape italic 
This is an excerpt from an atricle published in Circuit Cellar MagaZine
 in august 2000.
 It's a little outdated (the compiler is much more efficient now and user/devell
oper friendly), but pretty well exposes the guts of it all.
\shape default 

\newline 

\newline 
The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
 It is fairly easy to retarget for other 8-bit MCU.
 Here we take a look at some of the internals of the compiler.
 
\layout Paragraph*

Parsing 
\layout Standard

Parsing the input source file and creating an AST (Annotated Syntax Tree).
 This phase also involves propagating types (annotating each node of the
 parse tree with type information) and semantic analysis.
 There are some MCU specific parsing rules.
 For example the storage classes, the extended storage classes are MCU specific
 while there may be a xdata storage class for 8051 there is no such storage
 class for z80 or Atmel AVR.
 SDCC allows MCU specific storage class extensions, i.e.
 xdata will be treated as a storage class specifier when parsing 8051 C
 code but will be treated as a C identifier when parsing z80 or ATMEL AVR
 C code.
\layout Paragraph*

Generating iCode
\layout Standard

Intermediate code generation.
 In this phase the AST is broken down into three-operand form (iCode).
 These three operand forms are represented as doubly linked lists.
 ICode is the term given to the intermediate form generated by the compiler.
 ICode example section shows some examples of iCode generated for some simple
 C source functions.
\layout Paragraph*

Optimizations.
\layout Standard

Bulk of the target independent optimizations is performed in this phase.
 The optimizations include constant propagation, common sub-expression eliminati
on, loop invariant code movement, strength reduction of loop induction variables
 and dead-code elimination.
\layout Paragraph*

Live range analysis
\layout Standard

During intermediate code generation phase, the compiler assumes the target
 machine has infinite number of registers and generates a lot of temporary
 variables.
 The live range computation determines the lifetime of each of these compiler-ge
nerated temporaries.
 A picture speaks a thousand words.
 ICode example sections show the live range annotations for each of the
 operand.
 It is important to note here, each iCode is assigned a number in the order
 of its execution in the function.
 The live ranges are computed in terms of these numbers.
 The from number is the number of the iCode which first defines the operand
 and the to number signifies the iCode which uses this operand last.
\layout Paragraph*

Register Allocation
\layout Standard

The register allocation determines the type and number of registers needed
 by each operand.
 In most MCUs only a few registers can be used for indirect addressing.
 In case of 8051 for example the registers R0 & R1 can be used to indirectly
 address the internal ram and DPTR to indirectly address the external ram.
 The compiler will try to allocate the appropriate register to pointer variables
 if it can.
 ICode example section shows the operands annotated with the registers assigned
 to them.
 The compiler will try to keep operands in registers as much as possible;
 there are several schemes the compiler uses to do achieve this.
 When the compiler runs out of registers the compiler will check to see
 if there are any live operands which is not used or defined in the current
 basic block being processed, if there are any found then it will push that
 operand and use the registers in this block, the operand will then be popped
 at the end of the basic block.
 
\layout Standard

There are other MCU specific considerations in this phase.
 Some MCUs have an accumulator; very short-lived operands could be assigned
 to the accumulator instead of general-purpose register.
\layout Paragraph*

Code generation
\layout Standard

Figure II gives a table of iCode operations supported by the compiler.
 The code generation involves translating these operations into corresponding
 assembly code for the processor.
 This sounds overly simple but that is the essence of code generation.
 Some of the iCode operations are generated on a MCU specific manner for
 example, the z80 port does not use registers to pass parameters so the
 SEND and RECV iCode operations will not be generated, and it also does
 not support JUMPTABLES.
 
\newline 

\series bold 
\shape italic 
\color red
<Where is Figure II ?>
\layout Paragraph*

ICode Example
\layout Standard

This section shows some details of iCode.
 The example C code does not do anything useful; it is used as an example
 to illustrate the intermediate code generated by the compiler.
\newline 

\newline 

\family typewriter 
1.\SpecialChar ~
xdata int * p;
\newline 
2.\SpecialChar ~
int gint;
\newline 
3.\SpecialChar ~
/* This function does nothing useful.
 It is used
\newline 
4.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
for the purpose of explaining iCode */
\newline 
5.\SpecialChar ~
short function (data int *x)
\newline 
6.\SpecialChar ~
{
\newline 
7.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
short i=10; /* dead initialization eliminated */
\newline 
8.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
short sum=10; /* dead initialization eliminated */
\newline 
9.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
short mul;
\newline 
10.\SpecialChar ~
\SpecialChar ~
int j ;
\newline 
11.\SpecialChar ~
\SpecialChar ~
while (*x) *x++ = *p++; 
\newline 
12.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
sum = 0 ; 
\newline 
13.\SpecialChar ~
\SpecialChar ~
mul = 0;
\newline 
14.\SpecialChar ~
\SpecialChar ~
/* compiler detects i,j to be induction variables */
\newline 
15.\SpecialChar ~
\SpecialChar ~
for (i = 0, j = 10 ; i < 10 ; i++, j---) {
\newline 
16.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
sum += i;
\newline 
17.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mul += i * 3; /* this multiplication remains */
\newline 
18.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
gint += j * 3;/* this multiplication changed to addition */
\newline 
19.\SpecialChar ~
\SpecialChar ~
}
\newline 
20.\SpecialChar ~
\SpecialChar ~
return sum+mul;
\newline 
21.\SpecialChar ~
}
\newline 

\newline 

\family default 
In addition to the operands each iCode contains information about the filename
 and line it corresponds to in the source file.
 The first field in the listing should be interpreted as follows:
\newline 

\shape italic 
\size footnotesize 
Filename(linenumber: iCode Execution sequence number : ICode hash table
 key : loop depth of the iCode).
\shape default 
\size default 

\newline 
Then follows the human readable form of the ICode operation.
 Each operand of this triplet form can be of three basic types a) compiler
 generated temporary b) user defined variable c) a constant value.
 Note that local variables and parameters are replaced by compiler generated
 temporaries.
 Live ranges are computed only for temporaries (i.e.
 live ranges are not computed for global variables).
 Registers are allocated for temporaries only.
 Operands are formatted in the following manner:
\newline 

\shape italic 
\size footnotesize 
Operand Name [lr live-from : live-to ] { type information } [ registers
 allocated ].
\shape default 
\size default 

\newline 
As mentioned earlier the live ranges are computed in terms of the execution
 sequence number of the iCodes, for example 
\newline 
the iTemp0 is live from (i.e.
 first defined in iCode with execution sequence number 3, and is last used
 in the iCode with sequence number 5).
 For induction variables such as iTemp21 the live range computation extends
 the lifetime from the start to the end of the loop.
\newline 
The register allocator used the live range information to allocate registers,
 the same registers may be used for different temporaries if their live
 ranges do not overlap, for example r0 is allocated to both iTemp6 and to
 iTemp17 since their live ranges do not overlap.
 In addition the allocator also takes into consideration the type and usage
 of a temporary, for example itemp6 is a pointer to near space and is used
 as to fetch data from (i.e.
 used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
 Some short lived temporaries are allocated to special registers which have
 meaning to the code generator e.g.
 iTemp13 is allocated to a pseudo register CC which tells the back end that
 the temporary is used only for a conditional jump the code generation makes
 use of this information to optimize a compare and jump ICode.
\newline 
There are several loop optimizations performed by the compiler.
 It can detect induction variables iTemp21(i) and iTemp23(j).
 Also note the compiler does selective strength reduction, i.e.
 the multiplication of an induction variable in line 18 (gint = j * 3) is
 changed to addition, a new temporary iTemp17 is allocated and assigned
 a initial value, a constant 3 is then added for each iteration of the loop.
 The compiler does not change the multiplication in line 17 however since
 the processor does support an 8 * 8 bit multiplication.
\newline 
Note the dead code elimination optimization eliminated the dead assignments
 in line 7 & 8 to I and sum respectively.
\newline 

\layout Standard


\size footnotesize 
Sample.c (5:1:0:0) _entry($9) :
\layout Standard


\size footnotesize 
Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
\layout Standard


\size footnotesize 
Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv 
\layout Standard


\size footnotesize 
Sample.c(11:4:53:0) preHeaderLbl0($11) :
\layout Standard


\size footnotesize 
Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
 * int}[r2]
\layout Standard


\size footnotesize 
Sample.c(11:6:5:1) _whilecontinue_0($1) :
\layout Standard


\size footnotesize 
Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
 int}[r0]]
\layout Standard


\size footnotesize 
Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
\layout Standard


\size footnotesize 
Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
 * int}
\layout Standard


\size footnotesize 
Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
 {short}
\layout Standard


\size footnotesize 
Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
 * int}[DPTR]]
\layout Standard


\size footnotesize 
Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
}[r2 r3]
\layout Standard


\size footnotesize 
Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
 * int}[r0] + 0x2 {short}
\layout Standard


\size footnotesize 
Sample.c(11:16:20:1) goto _whilecontinue_0($1)
\layout Standard


\size footnotesize 
Sample.c(11:17:21:0)_whilebreak_0($3) :
\layout Standard


\size footnotesize 
Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
\layout Standard


\size footnotesize 
Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
\layout Standard


\size footnotesize 
Sample.c(15:20:54:0)preHeaderLbl1($13) :
\layout Standard


\size footnotesize 
Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
\layout Standard


\size footnotesize 
Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
\layout Standard


\size footnotesize 
Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
\layout Standard


\size footnotesize 
Sample.c(15:24:26:1)_forcond_0($4) :
\layout Standard


\size footnotesize 
Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
 < 0xa {short}
\layout Standard


\size footnotesize 
Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
\layout Standard


\size footnotesize 
Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
 + ITemp21 [lr21:38]{short}[r4]
\layout Standard


\size footnotesize 
Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
 * 0x3 {short}
\layout Standard


\size footnotesize 
Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
 + iTemp15 [lr29:30]{short}[r1]
\layout Standard


\size footnotesize 
Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
 r0]- 0x3 {short}
\layout Standard


\size footnotesize 
Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
int}[r7 r0]
\layout Standard


\size footnotesize 
Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
 + 0x1 {short}
\layout Standard


\size footnotesize 
Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
 r6]- 0x1 {short}
\layout Standard


\size footnotesize 
Sample.c(19:38:47:1) goto _forcond_0($4)
\layout Standard


\size footnotesize 
Sample.c(19:39:48:0)_forbreak_0($7) :
\layout Standard


\size footnotesize 
Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
 + ITemp11 [lr19:40]{short}[r3]
\layout Standard


\size footnotesize 
Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
\layout Standard


\size footnotesize 
Sample.c(20:42:51:0)_return($8) :
\layout Standard


\size footnotesize 
Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
\size default 

\newline 

\newline 
Finally the code generated for this function:
\newline 

\layout Standard


\size footnotesize 
.area DSEG (DATA)
\layout Standard


\size footnotesize 
_p::
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
.ds 2
\layout Standard


\size footnotesize 
_gint::
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
.ds 2
\layout Standard


\size footnotesize 
; sample.c 5
\layout Standard


\size footnotesize 
; ----------------------------------------------
\layout Standard


\size footnotesize 
; function function
\layout Standard


\size footnotesize 
; ----------------------------------------------
\layout Standard


\size footnotesize 
_function:
\layout Standard


\size footnotesize 
; iTemp0 [lr3:5]{_near * int}[r2] = recv 
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r2,dpl
\layout Standard


\size footnotesize 
; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov ar0,r2
\layout Standard


\size footnotesize 
;_whilecontinue_0($1) :
\layout Standard


\size footnotesize 
00101$:
\layout Standard


\size footnotesize 
; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
\layout Standard


\size footnotesize 
; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov ar2,@r0
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
inc r0
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov ar3,@r0
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
dec r0
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,r2
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
orl a,r3
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
jz 00103$
\layout Standard


\size footnotesize 
00114$:
\layout Standard


\size footnotesize 
; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov dpl,_p
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov dph,(_p + 1)
\layout Standard


\size footnotesize 
; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,#0x02
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
add a,_p
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov _p,a
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
clr a
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
addc a,(_p + 1)
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov (_p + 1),a
\layout Standard


\size footnotesize 
; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
movx a,@dptr
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r2,a
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
inc dptr
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
movx a,@dptr
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r3,a
\layout Standard


\size footnotesize 
; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov @r0,ar2
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
inc r0
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov @r0,ar3
\layout Standard


\size footnotesize 
; iTemp6 [lr5:16]{_near * int}[r0] = 
\layout Standard


\size footnotesize 
; iTemp6 [lr5:16]{_near * int}[r0] + 
\layout Standard


\size footnotesize 
; 0x2 {short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
inc r0
\layout Standard


\size footnotesize 
; goto _whilecontinue_0($1)
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
sjmp 00101$
\layout Standard


\size footnotesize 
; _whilebreak_0($3) :
\layout Standard


\size footnotesize 
00103$:
\layout Standard


\size footnotesize 
; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r2,#0x00
\layout Standard


\size footnotesize 
; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r3,#0x00
\layout Standard


\size footnotesize 
; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r4,#0x00
\layout Standard


\size footnotesize 
; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r5,#0x0A
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r6,#0x00
\layout Standard


\size footnotesize 
; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r7,#0x1E
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r0,#0x00
\layout Standard


\size footnotesize 
; _forcond_0($4) :
\layout Standard


\size footnotesize 
00104$:
\layout Standard


\size footnotesize 
; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
\layout Standard


\size footnotesize 
; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
clr c
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,r4
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
xrl a,#0x80
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
subb a,#0x8a
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
jnc 00107$
\layout Standard


\size footnotesize 
00115$:
\layout Standard


\size footnotesize 
; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] + 
\layout Standard


\size footnotesize 
; iTemp21 [lr21:38]{short}[r4]
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,r4
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
add a,r2
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r2,a
\layout Standard


\size footnotesize 
; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov b,#0x03
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,r4
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mul ab
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r1,a
\layout Standard


\size footnotesize 
; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] + 
\layout Standard


\size footnotesize 
; iTemp15 [lr29:30]{short}[r1]
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
add a,r3
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r3,a
\layout Standard


\size footnotesize 
; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,r7
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
add a,#0xfd
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r7,a
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,r0
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
addc a,#0xff
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov r0,a
\layout Standard


\size footnotesize 
; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,r7
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
add a,_gint
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov _gint,a
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,r0
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
addc a,(_gint + 1)
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov (_gint + 1),a
\layout Standard


\size footnotesize 
; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
inc r4
\layout Standard


\size footnotesize 
; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
dec r5
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
cjne r5,#0xff,00104$
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
dec r6
\layout Standard


\size footnotesize 
; goto _forcond_0($4)
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
sjmp 00104$
\layout Standard


\size footnotesize 
; _forbreak_0($7) :
\layout Standard


\size footnotesize 
00107$:
\layout Standard


\size footnotesize 
; ret iTemp24 [lr40:41]{short}
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov a,r3
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
add a,r2
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
mov dpl,a
\layout Standard


\size footnotesize 
; _return($8) :
\layout Standard


\size footnotesize 
00108$:
\layout Standard


\size footnotesize 
\SpecialChar ~
\SpecialChar ~
ret
\newline 

\layout Subsection

A few words about basic block successors, predecessors and dominators
\layout Standard

Successors are basic blocks that might execute after this basic block.
\newline 
Predecessors are basic blocks that might execute before reaching this basic
 block.
\newline 
Dominators are basic blocks that WILL execute before reaching this basic
 block.
\newline 

\layout Standard

[basic block 1]
\layout Standard

if (something)
\layout Standard

[basic block 2]
\layout Standard

else
\layout Standard

[basic block 3]
\layout Standard

[basic block 4]
\newline 

\layout Standard

a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
\layout Standard

b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
\layout Standard

c) domVect of [BB4] = BB1 ...
 here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
 was executed.
\layout Section

Acknowledgments
\layout Standard


\begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}

\end_inset 


\newline 

\newline 

\emph on 
Thanks to all the other volunteer developers who have helped with coding,
 testing, web-page creation, distribution sets, etc.
 You know who you are :-)
\emph default 

\newline 

\layout Standard

This document was initially written by Sandeep Dutta
\layout Standard

All product names mentioned herein may be trademarks of their respective
 companies.
 
\layout Standard


\begin_inset LatexCommand \printindex{}

\end_inset 


\the_end