#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
-\textclass article
+\textclass book
\begin_preamble
+\pdfoptionpdfminorversion=3
\usepackage[
pdftitle={SDCC Compiler User Guide},
pdfauthor={SDCC development team},
pdfsubject={installation, user manual},
- pdfkeywords={8032, 8051, ansi, c, compiler, CPU, DS390,
- embedded, GPL, manual, mcs51, PIC, small, Z80},
+ pdfkeywords={68hc08 8032 8051 ansi c compiler CPU DS390 embedded free Freescale GPL HC08 Intel manual Maxim mcs51 Microchip microcontroller open source PIC Z80 Zilog},
+ pdfpagemode=UseOutlines,
colorlinks=true,
linkcolor=blue] {hyperref}
+%
+\sloppy
+\tolerance=500
+\emergencystretch=30pt
+%
\date{}
\end_preamble
\language english
\graphics default
\paperfontsize default
\spacing single
-\papersize Default
+\papersize letterpaper
\paperpackage a4
\use_geometry 1
\use_amsmath 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 30mm
-\topmargin 10mm
+\topmargin 20mm
\rightmargin 25mm
-\bottommargin 15mm
+\bottommargin 20mm
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
extra long dash.
\layout Comment
-This document would need some rework: The Installation section is much to
-
-\layout Comment
-
-intimidating (as is the section about sdcdb).
-\layout Comment
-
Architecture specific stuff (like memory models, code examples) should maybe
- go
+ later go
\layout Comment
into seperate sections/chapters/appendices (it is hard to document PIC or
Z80 in
\layout Comment
-a 8051 centered document)
+a 8051 centered document) - for now simply add.
\layout Title
SDCC Compiler User Guide
-\layout Comment
+\layout Date
-The strings enclosed in $ are automatically updated by cvs:
-\layout Standard
-\align center
+\size normal
+SDCC 2.5.6
\size footnotesize
-$Date$
-\layout Standard
-\align center
-\size footnotesize
+\newline
+$Date$
+\newline
$Revision$
+\layout Comment
+
+The above strings enclosed in $ are automatically updated by Subversion
\layout Standard
\end_inset
-\layout Section
-\pagebreak_top
+\layout Chapter
+
Introduction
-\layout Subsection
+\layout Section
About SDCC
\layout Standard
\series bold
SDCC
\series default
- is a Freeware, retargettable, optimizing ANSI-C compiler by
+ (
+\emph on
+S
+\emph default
+mall
+\emph on
+D
+\emph default
+evice
+\emph on
+C
+\emph default
+
+\emph on
+C
+\emph default
+ompiler) is an open source, 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 (8031, 8032,
8051, 8052
-\begin_inset LatexCommand \index{8031, 8032, 8051, 8052 CPU}
+\begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
\end_inset
-, etc), Zilog Z80 based MCUs, and the Dallas DS80C390 variant.
- It can be retargetted for other microprocessors, support for PIC, AVR is
- under development.
+, etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
+ Zilog Z80 based MCUs.
+ It can be retargetted for other microprocessors, support for Microchip
+ PIC, Atmel AVR is under development.
The entire source code for the compiler is distributed under GPL.
- SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
+ SDCC uses ASXXXX
+\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
+
+\end_inset
+
+ & ASLINK
+\begin_inset LatexCommand \index{aslink}
+
+\end_inset
+
+, an open source retargettable assembler & linker.
SDCC has extensive language extensions suitable for utilizing various microcont
rollers and underlying hardware effectively.
\newline
Supported data-types are:
-\layout Itemize
-
-char (8 bits, 1 byte),
-\layout Itemize
+\layout Standard
-short and int (16 bits, 2 bytes),
-\layout Itemize
-long (32 bit, 4 bytes)
-\layout Itemize
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" columns="5">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-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 (-
-\begin_inset ERT
-status Collapsed
+type
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+width
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--cyclomatic) to report the relative complexity of a function.
- These functions can then be further optimized, or hand coded in assembly
- if needed.
-
-\newline
+\layout Standard
-\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
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-The latest version can be downloaded from
-\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
+\layout Standard
+signed range
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-.
+\layout Standard
-\series bold
-
-\series default
-\emph on
-Please note: the compiler will probably always be some steps ahead of this
- documentation
-\series bold
-\emph default
+unsigned range
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\begin_inset LatexCommand \index{Status of documentation}
+\layout Standard
+bool
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset Foot
-collapsed false
+1 bit
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-Obviously this has pros and cons
+unsigned
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-\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
-\begin_inset LatexCommand \index{GNU General Public License, GPL}
-
+-
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- 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
-\begin_inset LatexCommand \index{warranty}
+\layout Standard
+0, 1
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- 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
+\layout Standard
-Typographic conventions
-\begin_inset LatexCommand \index{Typographic conventions}
+char
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+8 bits, 1 byte
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+signed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\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
-.
+-128, +127
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\family default
- Code samples are printed in
-\family typewriter
-typewriter font.
+\layout Standard
-\family default
- Interesting items and new terms are printed in
-\emph on
-italic.
-\layout Subsection
+0, +255
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-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
-\begin_inset LatexCommand \index{ANSI-compliance}
+short
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+
+16 bits, 2 bytes
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-
-\newline
+\layout Standard
-\layout Itemize
+signed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-short is now equivalent to int (16 bits), it used to be equivalent to char
- (8 bits) which is not ANSI compliant
-\layout Itemize
+\layout Standard
-the default directory for gcc-builds where include, library and documentation
- files are stored is now in /usr/local/share
-\layout Itemize
+-32.768, +32.767
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-char type parameters to vararg functions are casted to int unless explicitly
- casted, e.g.:
-\newline
+\layout Standard
-\family typewriter
-\SpecialChar ~
-\SpecialChar ~
-char a=3;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-printf ("%d %c
-\backslash
-n", a, (char)a);
-\family default
+0, +65.535
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
- will push a as an int and as a char resp.
-\layout Itemize
+\layout Standard
-option -
-\begin_inset ERT
-status Collapsed
+int
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+16 bits, 2 bytes
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--regextend has been removed
-\layout Itemize
+\layout Standard
-option -
-\begin_inset ERT
-status Collapsed
+signed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+-32.768, +32.767
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--noregparms has been removed
-\layout Itemize
+\layout Standard
-option -
-\begin_inset ERT
-status Collapsed
+0, +65.535
+\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
-\backslash
-/
+long
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--stack-after-data has been removed
\layout Standard
+32 bits, 4 bytes
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\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
+signed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Other Resources
\layout Standard
-The SDCC home page at
-\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
-
+-2.147.483.648, +2.147.483.647
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- 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
+0, +4.294.967.296
+\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
-
-\family typewriter
-char KernelFunction3(char p) at 0x340;
-\newline
+float
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
+4 bytes IEEE 754
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family typewriter
-code banking
-\begin_inset LatexCommand \index{code banking (not supported)}
+\layout Standard
+signed
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- support for mcs51
-\newline
-
-\family default
-If you can think of some more, please see the chapter 9 about filing feature
- requests
-\begin_inset LatexCommand \index{Requesting features}
+\layout Standard
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{Feature request}
+\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
+pointer
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-\newline
+\layout Standard
-\layout Section
-\pagebreak_top
-Installation
-\begin_inset LatexCommand \index{Installation}
+1, 2, 3 or 4 bytes
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+
+generic
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\layout Subsection
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-Configure Options
-\begin_inset LatexCommand \index{Options SDCC configuration}
+\layout Standard
\end_inset
+</cell>
+</row>
+</lyxtabular>
+\end_inset
-\layout Standard
-The install paths, search paths and other options are defined when running
- 'configure'.
- The defaults can be overridden by:
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+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 (-
\begin_inset ERT
status Collapsed
/
\end_inset
--prefix see table below
-\layout List
-\labelwidthstring 00.00.0000
+-cyclomatic) to report the relative complexity of a function.
+ These functions can then be further optimized, or hand coded in assembly
+ if needed.
+
+\newline
--
-\begin_inset ERT
-status Collapsed
+\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.
+ SDCDB and ucSim are currently not available on Win32 platforms.
+
+\newline
-\layout Standard
+\newline
+The latest version can be downloaded from
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
-\backslash
-/
\end_inset
--exec_prefix see table below
-\layout List
-\labelwidthstring 00.00.0000
+.
--
-\begin_inset ERT
-status Collapsed
+\series bold
+
+\series default
+\emph on
+Please note: the compiler will probably always be some steps ahead of this
+ documentation
+\series bold
+\emph default
-\layout Standard
+\begin_inset LatexCommand \index{Status of documentation}
-\backslash
-/
\end_inset
--bindir see table below
-\layout List
-\labelwidthstring 00.00.0000
--
-\begin_inset ERT
-status Collapsed
+\begin_inset Foot
+collapsed false
\layout Standard
-\backslash
-/
+Obviously this has pros and cons
\end_inset
--datadir see table below
-\layout List
-\labelwidthstring 00.00.0000
+.
+\layout Section
-docdir environment variable, see table below
-\layout List
-\labelwidthstring 00.00.0000
+Open Source
+\layout Standard
-include_dir_suffix environment variable, see table below
-\layout List
-\labelwidthstring 00.00.0000
+All packages used in this compiler system are
+\emph on
+open source
+\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
+\begin_inset LatexCommand \index{GNU General Public License, GPL}
-lib_dir_suffix environment variable, see table below
-\layout List
-\labelwidthstring 00.00.0000
+\end_inset
-sdccconf_h_dir_separator environment variable, either / or
-\backslash
+ 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
+\begin_inset LatexCommand \index{warranty}
-\backslash
- makes sense here.
- This character will only be used in sdccconf.h; don't forget it's a C-header,
- therefore a double-backslash is needed there.
-\layout List
-\labelwidthstring 00.00.0000
+\end_inset
--
-\begin_inset ERT
-status Collapsed
+ 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 Section
-\layout Standard
+Typographic conventions
+\begin_inset LatexCommand \index{Typographic conventions}
-\backslash
-/
\end_inset
--disable-mcs51-port Excludes the Intel mcs51 port
-\layout List
-\labelwidthstring 00.00.0000
-
--
-\begin_inset ERT
-status Collapsed
\layout Standard
-\backslash
-/
-\end_inset
+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
+.
--disable-gbz80-port Excludes the Gameboy gbz80 port
-\layout List
-\labelwidthstring 00.00.0000
+\family default
+ Code samples are printed in
+\family typewriter
+typewriter font.
--
-\begin_inset ERT
-status Collapsed
+\family default
+ Interesting items and new terms are printed in
+\emph on
+italic.
+\layout Section
-\layout Standard
+Compatibility
+\begin_inset LatexCommand \label{sec:Compatibility-with-previous}
-\backslash
-/
\end_inset
--z80-port Excludes the z80 port
-\layout List
-\labelwidthstring 00.00.0000
+ with previous versions
+\begin_inset LatexCommand \index{Compatibility with previous versions}
+
+\end_inset
--
-\begin_inset ERT
-status Collapsed
\layout Standard
-\backslash
-/
+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
+\begin_inset LatexCommand \index{ANSI-compliance}
+
\end_inset
--disable-avr-port Excludes the AVR port
-\layout List
-\labelwidthstring 00.00.0000
+ (see section
+\begin_inset LatexCommand \ref{sub:ANSI-Compliance}
--
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
+ for ANSI-Compliance).
+
+\newline
-\backslash
-/
-\end_inset
+\layout Itemize
--disable-ds390-port Excludes the DS390 port
-\layout List
-\labelwidthstring 00.00.0000
+short is now equivalent to int (16 bits), it used to be equivalent to char
+ (8 bits) which is not ANSI compliant.
+\layout Itemize
--
-\begin_inset ERT
-status Collapsed
+the default directory for gcc-builds where include, library and documentation
+ files are stored is now in /usr/local/share.
+\layout Itemize
-\layout Standard
+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
-/
-\end_inset
+n", a, (char)a);
+\family default
--disable-pic-port Excludes the PIC port
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+ will push a as an int and as a char resp.
+\layout Itemize
--
+option -
\begin_inset ERT
status Collapsed
/
\end_inset
--disable-xa51-port Excludes the XA51 port
-\layout List
-\labelwidthstring 00.00.0000
+-regextend has been removed.
+\layout Itemize
--
+option -
\begin_inset ERT
status Collapsed
/
\end_inset
--disable-ucsim Disables configuring and building of ucsim
-\layout List
-\labelwidthstring 00.00.0000
+-noregparms has been removed.
+\layout Itemize
--
+option -
\begin_inset ERT
status Collapsed
/
\end_inset
--disable-device-lib-build Disables automatically building device libraries
-\layout List
-\labelwidthstring 00.00.0000
-
--
-\begin_inset ERT
-status Collapsed
+-stack-after-data has been removed.
+\layout Itemize
-\layout Standard
+bit
+\begin_inset LatexCommand \index{bit}
-\backslash
-/
\end_inset
--disable-packihx Disables building packihx
-\layout List
-\labelwidthstring 00.00.0000
+ and sbit
+\begin_inset LatexCommand \index{sbit}
--
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
-\backslash
-/
+\begin_inset LatexCommand \index{\_\_sbit}
+
\end_inset
--enable-libgc Use the Bohem memory allocator.
- Lower runtime footprint.
-\layout Standard
+ types now consistently behave like the C99 _Bool type with respect to type
+ conversion
+\begin_inset LatexCommand \index{type conversion}
-Furthermore the environment variables CC, CFLAGS, ...
- the tools and their arguments can be influenced.
- Please see `configure -
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
-\backslash
-/
+\begin_inset LatexCommand \index{type promotion}
+
\end_inset
--help` and the man/info pages of `configure` for details.
-\newline
+.
+ The most common incompatibility resulting from this change is related to
+ bit toggling
+\begin_inset LatexCommand \index{Bit toggling}
-\newline
-The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
- STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
-NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
- At the moment it's not possible to change the default settings (it was
- simply never required.
-\newline
+\end_inset
-\newline
-These configure options are compiled into the binaries, and can only be
- changed by rerunning 'configure' and recompiling SDCC.
- The configure options are written in
-\emph on
-italics
-\emph default
- to distinguish them from run time environment variables (see section search
- paths).
+ idioms, e.g.:
\newline
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
+bit b;
\newline
-The settings for
-\begin_inset Quotes sld
-\end_inset
-
-Win32 builds
-\begin_inset Quotes srd
-\end_inset
-
- are used by the SDCC team to build the official Win32 binaries.
- The SDCC team uses Mingw32 to build the official Windows binaries, because
- it's
-\layout Enumerate
+\SpecialChar ~
+\SpecialChar ~
+b = ~b; /* equivalent to b=1 instead of toggling b */
+\begin_inset Marginal
+collapsed true
-open source,
-\layout Enumerate
+\layout Standard
-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
+\series bold
+!
+\end_inset
-See the examples, how to pass the Win32 settings to 'configure'.
- The other Win32 builds using Borland, VC or whatever don't use 'configure',
- but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
- for Win32.
-\newline
\newline
-These defaults are:
+\SpecialChar ~
+\SpecialChar ~
+b = !b; /* toggles b */
\newline
+\family default
+In previous versions, both forms would have toggled the bit.
\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="8" columns="3">
-<features>
-<column alignment="block" valignment="top" leftline="true" width="0in">
-<column alignment="block" valignment="top" leftline="true" width="0in">
-<column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
-<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
-default
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\emph on
+<pending: more incompatibilities?>
+\layout Section
+System Requirements
\layout Standard
-Win32 builds
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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 Section
+Other Resources
\layout Standard
+The SDCC home page at
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
-\emph on
-PREFIX
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ is a great place to find distribution sets.
+ You can also find links to the user mailing lists that offer help or discuss
+ SDCC with other SDCC users.
+ Web links to other SDCC related sites can also be found here.
+ This document can be found in the DOC directory of the source package as
+ a text or HTML file.
+ A pdf version of this document is available at
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
-/usr/local
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+ 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 from Subversion on https://svn.sourceforge.net/svnroot/sdcc
+/trunk/sdcc.
+\layout Section
+Wishes for the future
+\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
+There are (and always will be) some things that could be done.
+ Here are some I can think of:
+\newline
\layout Standard
-\emph on
-EXEC_PREFIX
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+char KernelFunction3(char p) at 0x340;
+\newline
\layout Standard
-\emph on
-$PREFIX
+\family typewriter
+better code banking
+\begin_inset LatexCommand \index{code banking (limited support)}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ support for mcs51
+\newline
+\newline
-\emph on
-$PREFIX
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family default
+If you can think of some more, please see the section
+\begin_inset LatexCommand \ref{sub:Requesting-Features}
-\layout Standard
+\end_inset
+ about filing feature requests
+\begin_inset LatexCommand \index{Requesting features}
-\emph on
-BINDIR
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{Feature request}
-\emph on
-$EXECPREFIX
-\emph default
-/bin
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+\newline
+\layout Chapter
-\emph on
-$EXECPREFIX
-\emph default
+Installing SDCC
+\begin_inset LatexCommand \index{Installation}
-\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
+For most users it is sufficient to skip to either section
+\begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
-\emph on
-DATADIR
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+ or section
+\begin_inset LatexCommand \ref{sub:Windows-Install}
-\emph on
-$PREFIX
-\emph default
-/share
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+ More detailled instructions follow below.
+\layout Section
+Configure Options
+\begin_inset LatexCommand \index{Options SDCC configuration}
-\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
+The install paths, search paths and other options are defined when running
+ 'configure'.
+ The defaults can be overridden by:
+\layout List
+\labelwidthstring 00.00.0000
-\emph on
-DOCDIR
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\emph on
-$DATADIR
-\emph default
-/sdcc/doc
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-prefix see table below
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
-\emph on
-$DATADIR
-\emph default
+\layout Standard
\backslash
-doc
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+-exec_prefix see table below
+\layout List
+\labelwidthstring 00.00.0000
-\emph on
-INCLUDE_DIR_SUFFIX
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-sdcc/include
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-bindir see table below
+\layout List
+\labelwidthstring 00.00.0000
-include
-\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\emph on
-LIB_DIR_SUFFIX
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-sdcc/lib
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+-datadir see table below
+\layout List
+\labelwidthstring 00.00.0000
-lib
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+docdir environment variable, see table below
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+include_dir_suffix environment variable, see table below
+\layout List
+\labelwidthstring 00.00.0000
+lib_dir_suffix environment variable, see table below
+\layout List
+\labelwidthstring 00.00.0000
-\newline
+sdccconf_h_dir_separator environment variable, either / or
+\backslash
-\layout Standard
-\noindent
-'configure' also computes relative paths.
- This is needed for full relocatability of a binary package and to complete
- search paths (see section search paths below):
-\newline
-
-\layout Standard
-\align center
+\backslash
+ makes sense here.
+ This character will only be used in sdccconf.h; don't forget it's a C-header,
+ therefore a double-backslash is needed there.
+\layout List
+\labelwidthstring 00.00.0000
-\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="3">
-<features>
-<column alignment="block" valignment="top" leftline="true" width="0in">
-<column alignment="block" valignment="top" leftline="true" width="0in">
-<column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Variable (computed)
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-disable-mcs51-port Excludes the Intel mcs51 port
+\layout List
+\labelwidthstring 00.00.0000
-default
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Win32 builds
+\backslash
+/
\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
+-disable-gbz80-port Excludes the Gameboy gbz80 port
+\layout List
+\labelwidthstring 00.00.0000
-\emph on
-BIN2DATA_DIR
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-../share
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+-disable-z80-port Excludes the z80 port
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-..
\backslash
-
+/
\end_inset
-</cell>
-</row>
-<row bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+-disable-avr-port Excludes the AVR port
+\layout List
+\labelwidthstring 00.00.0000
-\emph on
-PREFIX2BIN_DIR
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-bin
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-disable-ds390-port Excludes the DS390 port
+\layout List
+\labelwidthstring 00.00.0000
-bin
-\end_inset
-</cell>
-</row>
-<row bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\emph on
-PREFIX2DATA_DIR
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-disable-hc08-port Excludes the HC08 port
+\layout List
+\labelwidthstring 00.00.0000
-share/sdcc
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
+\backslash
+/
\end_inset
+-disable-pic-port Excludes the PIC port
+\layout List
+\labelwidthstring 00.00.0000
-\newline
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-\noindent
-Examples:
-\layout LyX-Code
-./configure
-\newline
-./configure -
+\backslash
+/
+\end_inset
+
+-disable-xa51-port Excludes the XA51 port
+\layout List
+\labelwidthstring 00.00.0000
+
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--prefix=
-\begin_inset Quotes srd
-\end_inset
-
-/usr/bin
-\begin_inset Quotes srd
-\end_inset
+-disable-ucsim Disables configuring and building of ucsim
+\layout List
+\labelwidthstring 00.00.0000
- -
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--datadir=
-\begin_inset Quotes srd
-\end_inset
+-disable-device-lib Disables automatically building device libraries
+\layout List
+\labelwidthstring 00.00.0000
-/usr/share
-\begin_inset Quotes srd
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
\end_inset
+-disable-packihx Disables building packihx
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-./configure -
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--disable-avr-port -
+-enable-doc Build pdf, html and txt files from the lyx sources
+\layout List
+\labelwidthstring 00.00.0000
+
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--disable-xa51-port
+-enable-libgc Use the Bohem memory allocator.
+ Lower runtime footprint.
\layout Standard
-To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
-32'):
-\layout LyX-Code
+Furthermore the environment variables CC, CFLAGS, ...
+ the tools and their arguments can be influenced.
+ Please see `configure -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
-./configure
\backslash
+/
+\end_inset
+-help` and the man/info pages of `configure` for details.
\newline
-CC=
-\begin_inset Quotes srd
-\end_inset
-i586-mingw32msvc-gcc
-\begin_inset Quotes srd
-\end_inset
-
- CXX=
-\begin_inset Quotes srd
-\end_inset
+\newline
+The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
+ STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
+NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
+ At the moment it's not possible to change the default settings (it was
+ simply never required).
+\newline
-i586-mingw32msvc-g++
-\begin_inset Quotes srd
-\end_inset
+\newline
+These configure options are compiled into the binaries, and can only be
+ changed by rerunning 'configure' and recompiling SDCC.
+ The configure options are written in
+\emph on
+italics
+\emph default
+ to distinguish them from run time environment variables (see section search
+ paths).
+\newline
-
-\backslash
-
\newline
-RANLIB=
-\begin_inset Quotes srd
+The settings for
+\begin_inset Quotes sld
\end_inset
-i586-mingw32msvc-ranlib
+Win32 builds
\begin_inset Quotes srd
\end_inset
-
-\backslash
+ are used by the SDCC team to build the official Win32 binaries.
+ The SDCC team uses Mingw32 to build the official Windows binaries, because
+ it's
+\layout Enumerate
-\newline
-STRIP=
-\begin_inset Quotes srd
-\end_inset
+open source,
+\layout Enumerate
-i586-mingw32msvc-strip
-\begin_inset Quotes srd
-\end_inset
+a gcc compiler and last but not least
+\layout Enumerate
-
-\backslash
+the binaries can be built by cross compiling on Sourceforge's compile farm.
+\layout Standard
+See the examples, how to pass the Win32 settings to 'configure'.
+ The other Win32 builds using Borland, VC or whatever don't use 'configure',
+ but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
+ for Win32.
+\newline
+
+\newline
+These defaults are:
\newline
--
-\begin_inset ERT
-status Collapsed
\layout Standard
+\align center
-\backslash
-/
-\end_inset
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="0in">
+<column alignment="block" valignment="top" leftline="true" width="0in">
+<column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--prefix=
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-/sdcc
-\begin_inset Quotes srd
+Variable
\end_inset
-
-
-\backslash
-
-\newline
--
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+default
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--datadir=
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-/sdcc
-\begin_inset Quotes srd
+Win32 builds
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\backslash
+\layout Standard
-\newline
-docdir=
-\begin_inset Quotes srd
-\end_inset
-/sdcc/doc
-\begin_inset Quotes srd
+\emph on
+PREFIX
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\backslash
+\layout Standard
-\newline
-include_dir_suffix=
-\begin_inset Quotes srd
+/usr/local
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-include
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-
-\backslash
-\newline
-lib_dir_suffix=
-\begin_inset Quotes srd
+\backslash
+sdcc
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-lib
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-
-\backslash
-\newline
-sdccconf_h_dir_separator=
-\begin_inset Quotes srd
+\emph on
+EXEC_PREFIX
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\backslash
-\backslash
+\emph on
+$PREFIX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\backslash
+\layout Standard
-\backslash
-\begin_inset Quotes srd
+\emph on
+$PREFIX
\end_inset
-
-
-\backslash
-
-\newline
--
-\begin_inset ERT
-status Collapsed
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
-
--disable-device-lib-build
-\backslash
-\newline
--
-\begin_inset ERT
-status Collapsed
+\emph on
+BINDIR
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+
+\emph on
+$EXECPREFIX
+\emph default
+/bin
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--disable-ucsim
-\backslash
+\layout Standard
-\newline
--
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\emph on
+$EXECPREFIX
+\emph default
\backslash
-/
+bin
\end_inset
-
--host=i586-mingw32msvc -
-\begin_inset ERT
-status Collapsed
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+
+\emph on
+DATADIR
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--build=unknown-unknown-linux-gnu
\layout Standard
-To
-\begin_inset Quotes sld
-\end_inset
-cross
-\begin_inset Quotes srd
+\emph on
+$PREFIX
+\emph default
+/share
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-compile on Cygwin for Mingw32(see also sdcc/support/scripts/sdcc_cygwin_mingw32)
-:
-\layout LyX-Code
-
-./configure -C
-\backslash
+\layout Standard
-\newline
-CFLAGS=
-\begin_inset Quotes srd
-\end_inset
--mno-cygwin -O2
-\begin_inset Quotes srd
+\emph on
+$PREFIX
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\backslash
+\layout Standard
-\newline
-LDFLAGS=
-\begin_inset Quotes srd
-\end_inset
--mno-cygwin
-\begin_inset Quotes srd
+\emph on
+DOCDIR
\end_inset
-
-
-\backslash
-
-\newline
--
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
-
--prefix=
-\begin_inset Quotes srd
-\end_inset
-/sdcc
-\begin_inset Quotes srd
+\emph on
+$DATADIR
+\emph default
+/sdcc/doc
\end_inset
-
-
-\backslash
-
-\newline
--
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
-
--datadir=
-\begin_inset Quotes srd
-\end_inset
-/sdcc
-\begin_inset Quotes srd
-\end_inset
+\emph on
+$DATADIR
+\emph default
-
\backslash
-
-\newline
-docdir=
-\begin_inset Quotes srd
+doc
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-/sdcc/doc
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-
-\backslash
-
-\newline
-include_dir_suffix=
-\begin_inset Quotes srd
-\end_inset
-include
-\begin_inset Quotes srd
+\emph on
+INCLUDE_DIR_SUFFIX
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\backslash
-
-\newline
-lib_dir_suffix=
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-lib
-\begin_inset Quotes srd
+sdcc/include
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-
-\backslash
+\layout Standard
-\newline
-sdccconf_h_dir_separator=
-\begin_inset Quotes srd
+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
-\backslash
-
-\backslash
-
-\backslash
-
-\backslash
-\begin_inset Quotes srd
+\emph on
+LIB_DIR_SUFFIX
\end_inset
-
-
-\backslash
-
-\newline
--
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+sdcc/lib
\end_inset
-
--disable-ucsim
-\layout Standard
-
-'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
- The option '-
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+lib
\end_inset
-
--C' turns on caching, which gives a little bit extra speed.
- However if options are changed, it can be necessary to delete the config.cache
- file.
-\layout Subsection
-
-Install paths
-\begin_inset LatexCommand \index{Install paths}
+</cell>
+</row>
+</lyxtabular>
\end_inset
+\newline
+
\layout Standard
-\added_space_top medskip \align center
+\noindent
+'configure' also computes relative paths.
+ This is needed for full relocatability of a binary package and to complete
+ search paths (see section search paths below):
+\newline
+
+\layout Standard
+\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="5" columns="4">
+<lyxtabular version="3" rows="4" columns="3">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="block" valignment="top" leftline="true" width="0in">
+<column alignment="block" valignment="top" leftline="true" width="0in">
+<column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-
-\series bold
-Description
+Variable (computed)
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
-Path
+\layout Standard
+
+Win32 builds
\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
-\series bold
-Default
+\emph on
+BIN2DATA_DIR
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-
-\series bold
-Win32 builds
+../share
\end_inset
</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-Binary files*
+..
\end_inset
</cell>
+</row>
+<row bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\emph on
-$EXEC_PREFIX
+PREFIX2BIN_DIR
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-/usr/local/bin
+bin
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\backslash
-sdcc
-\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
-
-Include files
-\end_inset
-</cell>
+<row bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\emph on
-$DATADIR/ $INCLUDE_DIR_SUFFIX
+PREFIX2DATA_DIR
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-/usr/local/share/sdcc/include
+share/sdcc
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\backslash
-sdcc
-\backslash
-include
\end_inset
</cell>
</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+</lyxtabular>
-Library file**
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+
+\newline
\layout Standard
+\noindent
+Examples:
+\layout LyX-Code
+./configure
+\newline
+./configure -
+\begin_inset ERT
+status Collapsed
-\emph on
-$DATADIR/$LIB_DIR_SUFFIX
+\layout Standard
+
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-prefix=
+\begin_inset Quotes srd
+\end_inset
-/usr/local/share/sdcc/lib
+/usr/bin
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ -
+\begin_inset ERT
+status Collapsed
+\layout Standard
\backslash
-sdcc
-\backslash
-lib
+/
\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
+-datadir=
+\begin_inset Quotes srd
+\end_inset
-Documentation
+/usr/share
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\newline
+./configure -
+\begin_inset ERT
+status Collapsed
-\emph on
-$DOCDIR
+\layout Standard
+
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+-disable-avr-port -
+\begin_inset ERT
+status Collapsed
\layout Standard
-/usr/local/share/sdcc/doc
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+-disable-xa51-port
\layout Standard
+To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
+32'):
+\layout LyX-Code
+./configure
\backslash
-sdcc
-\backslash
-doc
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+\newline
+CC=
+\begin_inset Quotes srd
\end_inset
+i586-mingw32msvc-gcc
+\begin_inset Quotes srd
+\end_inset
-\layout Verse
+ CXX=
+\begin_inset Quotes srd
+\end_inset
+i586-mingw32msvc-g++
+\begin_inset Quotes srd
+\end_inset
-\size footnotesize
-*compiler, preprocessor, assembler, and linker
+
+\backslash
+
\newline
-**the
-\shape italic
-model
-\shape default
- is auto-appended by the compiler, e.g.
- small, large, z80, ds390 etc
-\layout Standard
-\noindent
-The install paths can still be changed during `make install` with e.g.:
-\layout LyX-Code
-
-make install prefix=$(HOME)/local/sdcc
-\layout Standard
+RANLIB=
+\begin_inset Quotes srd
+\end_inset
-Of course this doesn't change the search paths compiled into the binaries.
-\layout Subsection
+i586-mingw32msvc-ranlib
+\begin_inset Quotes srd
+\end_inset
-Search Paths
-\begin_inset LatexCommand \index{Search path}
+
+\backslash
+\newline
+STRIP=
+\begin_inset Quotes srd
\end_inset
+i586-mingw32msvc-strip
+\begin_inset Quotes srd
+\end_inset
-\layout Standard
-
-Some search paths or parts of them are determined by configure variables
- (in
-\emph on
-italics
-\emph default
-, see section above).
- Further 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
+\backslash
\newline
-1.
- Binary files (preprocessor, assembler and linker)
-\newline
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="3">
-<features>
-<column alignment="block" valignment="top" leftline="true" width="0in">
-<column alignment="block" valignment="top" leftline="true" width="0in">
-<column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\backslash
+/
+\end_inset
-\layout Standard
+-prefix=
+\begin_inset Quotes srd
+\end_inset
-Search path
+/sdcc
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+
+\backslash
-default
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\newline
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Win32 builds
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-datadir=
+\begin_inset Quotes srd
+\end_inset
-$SDCC_HOME/
-\emph on
-$PPREFIX2BIN_DIR
+/sdcc
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+
+\backslash
-$SDCC_HOME/bin
+\newline
+docdir=
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+/sdcc/doc
+\begin_inset Quotes srd
+\end_inset
-$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
+\newline
+include_dir_suffix=
+\begin_inset Quotes srd
+\end_inset
-Path of argv[0] (if available)
+include
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+
+\backslash
-Path of argv[0]
+\newline
+lib_dir_suffix=
+\begin_inset Quotes srd
\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]
+lib
+\begin_inset Quotes srd
\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
+
+\backslash
-$PATH
+\newline
+sdccconf_h_dir_separator=
+\begin_inset Quotes srd
\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
+\backslash
-\layout Standard
+\backslash
-$PATH
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+\backslash
+
+\backslash
+\begin_inset Quotes srd
\end_inset
+\backslash
+
\newline
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-\noindent
-2.
- Include files
+
+\backslash
+/
+\end_inset
+
+-disable-device-lib
+\backslash
+
\newline
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
-<features>
-<column alignment="block" valignment="top" leftline="true" width="1.5in">
-<column alignment="block" valignment="top" leftline="true" width="1.5in">
-<column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\backslash
+/
+\end_inset
+
+-disable-ucsim
+\backslash
+
+\newline
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Search path
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+-host=i586-mingw32msvc -
+\begin_inset ERT
+status Collapsed
\layout Standard
-default
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+-build=unknown-unknown-linux-gnu
\layout Standard
-Win32 builds
+To
+\begin_inset Quotes sld
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+cross
+\begin_inset Quotes srd
+\end_inset
--
-\begin_inset ERT
-status Collapsed
+compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
+):
+\layout LyX-Code
-\layout Standard
+./configure -C
+\backslash
+
+\newline
+CFLAGS=
+\begin_inset Quotes srd
+\end_inset
+
+-mno-cygwin -O2
+\begin_inset Quotes srd
+\end_inset
+
\backslash
-/
+
+\newline
+LDFLAGS=
+\begin_inset Quotes srd
\end_inset
--I dir
+-mno-cygwin
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+
+\backslash
+\newline
-
\begin_inset ERT
status Collapsed
/
\end_inset
--I dir
+-prefix=
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+/sdcc
+\begin_inset Quotes srd
+\end_inset
+
+
+\backslash
+\newline
-
\begin_inset ERT
status Collapsed
/
\end_inset
--I dir
+-datadir=
+\begin_inset Quotes srd
\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
+/sdcc
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+
+\backslash
-$SDCC_INCLUDE
+\newline
+docdir=
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-
-$SDCC_INCLUDE
+/sdcc/doc
+\begin_inset Quotes srd
\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/
+
+\backslash
+
\newline
+include_dir_suffix=
+\begin_inset Quotes srd
+\end_inset
-\emph on
-$PREFIX2DATA_DIR/
-\newline
-$INCLUDE_DIR_SUFFIX
+include
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+
+\backslash
-$SDCC_ HOME/
\newline
-share/sdcc/
-\newline
-include
+lib_dir_suffix=
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+lib
+\begin_inset Quotes srd
+\end_inset
-$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
-$BIN2DATADIR/
-\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
-
-path(argv[0])/
-\newline
-../sdcc/include
\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 ~
-
+sdccconf_h_dir_separator=
+\begin_inset Quotes srd
\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
+\backslash
-\emph on
-$DATADIR/
-\emph default
+\backslash
-\newline
+\backslash
-\emph on
-$INCLUDE_DIR_SUFFIX
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+
+\backslash
-/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
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-(not on Win32)
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
+\backslash
+/
\end_inset
-
-\newline
-
+-disable-ucsim
\layout Standard
-\noindent
-The option -
+
+'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
+ The option '-
\begin_inset ERT
status Collapsed
/
\end_inset
--nostdinc disables the last two search paths.
-\newline
-
-\newline
-3.
- Library files
-\newline
+-C' turns on caching, which gives a little bit extra speed.
+ However if options are changed, it can be necessary to delete the config.cache
+ file.
+\layout Section
-\layout Standard
+Install paths
+\begin_inset LatexCommand \label{sub:Install-paths}
-With the exception of
-\begin_inset Quotes sld
\end_inset
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-\backslash
-/
-\end_inset
+\begin_inset LatexCommand \index{Install paths}
--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
\layout Standard
-\align center
+\added_space_top medskip \align center
\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
+<lyxtabular version="3" rows="5" columns="4">
<features>
-<column alignment="block" valignment="top" leftline="true" width="1.7in">
-<column alignment="block" valignment="top" leftline="true" width="1.2in">
-<column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Search path
+
+\series bold
+Description
\end_inset
</cell>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-default
+
+\series bold
+Path
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Default
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
+
+\series bold
Win32 builds
\end_inset
</cell>
</row>
<row topline="true">
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
--
-\begin_inset ERT
-status Collapsed
+Binary files*
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
--L dir
+\emph on
+$EXEC_PREFIX
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--L dir
+/usr/local/bin
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
\backslash
-/
-\end_inset
-
--L dir
+sdcc
+\backslash
+bin
\end_inset
</cell>
</row>
\layout Standard
-$SDCC_LIB/
-\newline
-
-\emph on
-<model>
+Include files
\end_inset
</cell>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-$SDCC_LIB/
-\newline
\emph on
-<model>
+$DATADIR/ $INCLUDE_DIR_SUFFIX
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-$SDCC_LIB
-\backslash
-
-\newline
-
-\emph on
-<model>
+/usr/local/share/sdcc/include
\end_inset
</cell>
-</row>
-<row topline="true">
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-$SDCC_HOME/
-\newline
-\emph on
-$PREFIX2DATA_DIR/
-\newline
-$LIB_DIR_SUFFIX/<model>
+\backslash
+sdcc
+\backslash
+include
\end_inset
</cell>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-$SDCC_HOME/
-\newline
-share/sdcc/
-\newline
-lib/
-\emph on
-<model>
+Library file**
\end_inset
</cell>
-<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-$SDCC_HOME
-\backslash
-lib
-\backslash
\emph on
-
-\newline
-<model>
+$DATADIR/$LIB_DIR_SUFFIX
\end_inset
</cell>
-</row>
-<row topline="true">
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-path(argv[0])/
-\newline
-
-\emph on
-$BIN2DATADIR/
-\emph default
-
-\newline
-
-\emph on
-$LIB_DIR_SUFFIX/<model>
+/usr/local/share/sdcc/lib
\end_inset
</cell>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-path(argv[0])/
-\newline
-../sdcc/lib/
-\emph on
-<model>
-\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 ~
+\backslash
+sdcc
+\backslash
+lib
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-path(argv[0])
-\backslash
-
-\newline
-..
-\backslash
-lib
-\backslash
-
-\emph on
-<model>
-\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 ~
-
+Documentation
\end_inset
</cell>
-</row>
-<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\emph on
-$DATADIR/
-\newline
-$LIB_DIR_SUFFIX/<model>
+$DOCDIR
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-/usr/local/share/sdcc/
-\newline
-lib/
-\emph on
-<model>
+/usr/local/share/sdcc/doc
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-(not on Win32)
+
+\backslash
+sdcc
+\backslash
+doc
\end_inset
</cell>
</row>
\end_inset
-\newline
+\layout Verse
-\layout Comment
-Don't delete any of the stray spaces in the table above without checking
- the HTML output (last line)!
+\size footnotesize
+*compiler, preprocessor, assembler, and linker
+\newline
+**the
+\shape italic
+model
+\shape default
+ is auto-appended by the compiler, e.g.
+ small, large, z80, ds390 etc
\layout Standard
+\noindent
+The install paths can still be changed during `make install` with e.g.:
+\layout LyX-Code
-\SpecialChar ~
+make install prefix=$(HOME)/local/sdcc
+\layout Standard
+Of course this doesn't change the search paths compiled into the binaries.
\newline
-The option -
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\newline
+Moreover the install path can be changed by defining DESTDIR
+\begin_inset LatexCommand \index{DESTDIR}
-\backslash
-/
\end_inset
--nostdlib disables the last two search paths.
-\layout Subsection
-
-Building SDCC
-\begin_inset LatexCommand \index{Building SDCC}
+:
+\layout LyX-Code
-\end_inset
+make install DESTDIR=$(HOME)/sdcc.rpm/
+\layout Standard
+Please note that DESTDIR must have a trailing slash!
+\layout Section
-\layout Subsubsection
+Search Paths
+\begin_inset LatexCommand \label{sub:Search-Paths}
-Building SDCC on Linux
-\layout Enumerate
+\end_inset
-\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}
+\begin_inset LatexCommand \index{Search path}
\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
+\layout Standard
+Some search paths or parts of them are determined by configure variables
+ (in
+\emph on
+italics
+\emph default
+, see section above).
+ Further 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
-\series medium
-Bring up a command line terminal, such as xterm.
-\layout Enumerate
+\newline
+1.
+ Binary files (preprocessor, assembler and linker)
+\newline
+\layout Standard
+\align center
-\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
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="0in">
+<column alignment="block" valignment="top" leftline="true" width="0in">
+<column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series medium
-Type
-\family sans
-\series bold
-"./configure
-\family default
-\series default
-".
- This configures the package for compilation on your system.
-\layout Enumerate
+Search path
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series medium
-Type
-\family sans
-\series bold
-"make
-\family default
-\series default
-"
-\series medium
-.
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series default
- All of the source packages will compile, this can take a while.
-\layout Enumerate
+\layout Standard
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series medium
-Type
-\family sans
-\series bold
-"make install"
-\family default
-\series default
- as root
-\series medium
-.
+\layout Standard
-\series default
- This copies the binary executables, the include files, the libraries and
- the documentation to the install directories.
-\layout Subsubsection
+$SDCC_HOME/
+\emph on
+$PPREFIX2BIN_DIR
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Building SDCC on OSX 2.x
\layout Standard
-Follow the instruction for Linux.
-\newline
+$SDCC_HOME/bin
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
-On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
-)) fails to compile SDCC.
- Fortunately there's also gcc 2.9.x installed, which works fine.
- This compiler can be selected by running 'configure' with:
-\layout LyX-Code
+\layout Standard
-./configure CC=gcc2 CXX=g++2
-\layout Subsubsection
+$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
-Cross compiling SDCC on Linux for Windows
\layout Standard
-With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
- See section 'Configure Options'.
-\layout Subsubsection
+Path of argv[0] (if available)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Building SDCC on Windows
\layout Standard
-With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
- built on Windows.
- They use Unix-sockets, which are not available on Win32.
-\layout Subsubsection
+Path of argv[0]
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-Windows Install Using a Binary Package
-\layout Enumerate
+\layout Standard
-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
-sdcc
-\backslash
-bin for the executables, c:
-\backslash
-sdcc
-\backslash
-include and c:
-\backslash
-sdcc
-\backslash
-lib for the include and libraries.
-\layout Enumerate
+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
-Adjust your environment variable PATH to include the location of the bin
- directory or start sdcc using the full path.
-\layout Subsubsection
+\layout Standard
+
+$PATH
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Building SDCC using Cygwin and Mingw32
\layout Standard
-For building and installing a Cygwin executable follow the instructions
- for Linux.
-\newline
+$PATH
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
-On Cygwin a
-\begin_inset Quotes sld
+\layout Standard
+
+$PATH
\end_inset
+</cell>
+</row>
+</lyxtabular>
-native
-\begin_inset Quotes srd
\end_inset
- Win32-binary can be built, which will not need the Cygwin-DLL.
- For the necessary 'configure' options see section 'configure options' or
- the script 'sdcc/support/scripts/sdcc_cygwinmingw32'.
+
\newline
+\layout Standard
+\noindent
+2.
+ Include files
\newline
-In order to install Cygwin on Windows download setup.exe from
-\begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
-\end_inset
+\layout Standard
+\align center
-.
- Run it, set the
-\begin_inset Quotes sld
-\end_inset
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="1.5in">
+<column alignment="block" valignment="top" leftline="true" width="1.5in">
+<column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-default text file type
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
- to
-\begin_inset Quotes sld
+Search path
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-unix
-\begin_inset Quotes srd
+\layout Standard
+
+default
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- and download/install at least the following packages.
- Some packages are selected by default, others will be automatically selected
- because of dependencies with the manually selected packages.
- Never deselect these packages!
-\layout Itemize
+\layout Standard
-flex
-\layout Itemize
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-bison
-\layout Itemize
+\layout Standard
-gcc ; version 3.x is fine, no need to use the old 2.9x
-\layout Itemize
+-
+\begin_inset ERT
+status Collapsed
-binutils ; selected with gcc
-\layout Itemize
-
-make
-\layout Itemize
-
-rxvt ; a nice console, which makes life much easier under windoze (see below)
-\layout Itemize
-
-man ; not really needed for building SDCC, but you'll miss it sooner or
- later
-\layout Itemize
-
-less ; not really needed for building SDCC, but you'll miss it sooner or
- later
-\layout Itemize
-
-cvs ; only if you use CVS access
\layout Standard
-If you want to develop something you'll need:
-\layout Itemize
-
-python ; for the regression tests
-\layout Itemize
-
-gdb ; the gnu debugger, together with the nice GUI
-\begin_inset Quotes sld
+\backslash
+/
\end_inset
-insight
-\begin_inset Quotes srd
+-I dir
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\layout Itemize
-
-openssh ; to access the CF or commit changes
-\layout Itemize
-
-autoconf and autoconf-devel ; if you want to fight with 'configure', don't
- use autoconf-stable!
\layout Standard
-rxvt is a nice console with history.
- Replace in your cygwin.bat the line
-\layout LyX-Code
-
-bash -
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--login -i
-\layout Standard
-
-with (one line):
-\layout LyX-Code
+-I dir
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
-\layout LyX-Code
+\layout Standard
- -bg black -fg white -geometry 100x65 -e bash -
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--login
-\layout Standard
-
-Text selected with the mouse is automatically copied to the clipboard, pasting
- works with shift-insert.
-\newline
-
-\newline
-The other good tip is to make sure you have no //c/-style paths anywhere,
- use /cygdrive/c/ instead.
- Using // invokes a network lookup which is very slow.
- If you think
-\begin_inset Quotes sld
-\end_inset
-
-cygdrive
-\begin_inset Quotes srd
+-I dir
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- is too long, you can change it with e.g.
-\layout LyX-Code
-
-mount -s -u -c /mnt
\layout Standard
-SDCC sources use the unix line ending LF.
- Life is much easier, if you store the source tree on a drive, which is
- mount in binary mode.
- And use an editor which can handle LF-only line endings.
- Make sure not to commit files with windows line endings.
-\layout Subsubsection
+$SDCC_INCLUDE
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
\layout Standard
+$SDCC_INCLUDE
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\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}
+\layout Standard
+$SDCC_INCLUDE
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\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 (except for sdcdb.exe which currently
- doesn't build under MSVC).
- 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 running SDCC.
-
+$SDCC_HOME/
\newline
+\emph on
+$PREFIX2DATA_DIR/
\newline
-In order to build SDCC with MSVC 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}
-
+$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
-Download the file UnxUtils
-\begin_inset LatexCommand \index{UnxUtils}
-
+include
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-.zip.
- Now you have to install the utilities and setup MSVC 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
+\layout Standard
-\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
+$SDCC_HOME
\backslash
-wbin', click ok.
-\newline
+include
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-(As a side effect, you get a bunch of Unix utilities that could be useful,
- such as diff and patch.)
-\layout Enumerate
+\layout Standard
-A more compact way:
+path(argv[0])/
\newline
-\newline
-This one avoids extracting a bunch of files you may not use, but requires
- some extra work:
-\newline
+\emph on
+$BIN2DATADIR/
+\emph default
-\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
+\emph on
+$INCLUDE_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-c) Rename bison.exe to '_bison.exe'.
-\newline
+\layout Standard
+path(argv[0])/
\newline
-d) Create a batch file 'bison.bat' in 'C:
-\backslash
-util
-\backslash
-' and add these lines:
+../sdcc/include
\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
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\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
-\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
+path(argv[0])
\backslash
-bin_vc to sdcc
+..
\backslash
-bin, and you can compile using sdcc.
-\layout Subsubsection
+include
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Building SDCC Using Borland
-\layout Enumerate
+\layout Standard
-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 dependenci
-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 command:
-\newline
+\emph on
+$DATADIR/
+\emph default
\newline
-\family sans
-\series bold
-find .
-
-\backslash
-( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
-\backslash
-) -print -exec rm {}
-\backslash
-;
-\family default
-\series default
+\emph on
+$INCLUDE_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
+/usr/local/share/sdcc/
\newline
-or on Windows NT/2000/XP from the command prompt with the command:
-\newline
+include
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\family sans
-\series bold
+\layout Standard
-\newline
-del /s *.obj *.lib *.rul
-\family default
-\series default
- from the sdcc directory.
-\layout Subsection
+(not on Win32)
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-Building the Documentation
-\layout Standard
+\end_inset
-...
- coming soon
-\layout Subsection
+
+\newline
-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 -
+\noindent
+The option -
\begin_inset ERT
status Collapsed
/
\end_inset
--version"
-\begin_inset LatexCommand \index{version}
-
-\end_inset
-
-
-\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.
+-nostdinc disables the last two search paths.
\newline
\newline
+3.
+ Library files
+\newline
-\series medium
-SDCC
-\series default
-is commonly installed as described in section
+\layout Standard
+
+With the exception of
\begin_inset Quotes sld
\end_inset
-Install and search paths
-\begin_inset Quotes srd
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
\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
-\newline
+\layout Standard
+\align center
-\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:
-\layout Verse
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="1.7in">
+<column alignment="block" valignment="top" leftline="true" width="1.2in">
+<column alignment="block" 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
-\family typewriter
-char test;
-\newline
+Search path
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-void main(void) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-test=0;
-\newline
-}
\layout Standard
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series medium
-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
+\layout Standard
-\newline
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\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:
-\layout Verse
+-
+\begin_inset ERT
+status Collapsed
+\layout Standard
-\family typewriter
-#include <string.h>
-\newline
+\backslash
+/
+\end_inset
-\newline
-char str1[10];
-\newline
+-L dir
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-void main(void) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-strcpy(str1, "testing");
-\newline
-}
\layout Standard
-
-\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).
-
-\series default
- Use option
-\series bold
-
\begin_inset ERT
status Collapsed
/
\end_inset
--print-search-dirs
-\series default
-
-\begin_inset LatexCommand \index{-\/-print-search-dirs}
-
+-L dir
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- to find exactly where SDCC is looking for the include and lib files.
-\layout Subsection
+\layout Standard
-Install Trouble-shooting
-\begin_inset LatexCommand \index{Install trouble-shooting}
+-
+\begin_inset ERT
+status Collapsed
-\end_inset
+\layout Standard
+\backslash
+/
+\end_inset
-\layout Subsubsection
+-L dir
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-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.
- Configure it like:
-\newline
-
+$SDCC_LIB/
\newline
-\family sans
-\series bold
-./configure 2>&1 | tee configure.log
-\family default
-\series default
+\emph on
+<model>
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\newline
-and build it like:
+$SDCC_LIB/
\newline
-\newline
+\emph on
+<model>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\family sans
-\series bold
-make 2>&1 | tee make.log
-\family default
-\series default
+\layout Standard
-\newline
+$SDCC_LIB
+\backslash
\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
+\emph on
+<model>
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- does
\layout Standard
-The
-\begin_inset Quotes sld
-\end_inset
+$SDCC_HOME/
+\newline
-./configure
-\begin_inset Quotes srd
+\emph on
+$PREFIX2DATA_DIR/
+\newline
+$LIB_DIR_SUFFIX/<model>
\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- 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
+\layout Standard
-make
-\begin_inset Quotes srd
+$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
- does.
\layout Standard
-This runs the GNU make tool, which automatically compiles all the source
- packages into the final installed binary executables.
-\layout Subsubsection
+$SDCC_HOME
+\backslash
+lib
+\backslash
-What the
-\begin_inset Quotes sld
-\end_inset
+\emph on
-make install
-\begin_inset Quotes erd
+\newline
+<model>
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- 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
+path(argv[0])/
+\newline
-Install and Search PATHS
-\begin_inset Quotes srd
-\end_inset
+\emph on
+$BIN2DATADIR/
+\emph default
-.
\newline
-On most systems you will need super-user privileges to do this.
-\layout Subsection
-Components of SDCC
+\emph on
+$LIB_DIR_SUFFIX/<model>
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
\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.
+path(argv[0])/
\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
-
+../sdcc/lib/
+\emph on
+<model>
\newline
-In <installdir>/bin:
-\layout Itemize
-
-sdcc - The compiler.
-\layout Itemize
-
-sdcpp - The C preprocessor.
-\layout Itemize
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
-asx8051 - The assembler for 8051 type processors.
-\layout Itemize
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-as-z80
-\series bold
-,
-\series default
-as-gbz80 - The Z80 and GameBoy Z80 assemblers.
-\layout Itemize
+\layout Standard
-aslink -The linker for 8051 type processors.
-\layout Itemize
+path(argv[0])
+\backslash
-link-z80
-\series bold
-,
-\series default
-link-gbz80 - The Z80 and GameBoy Z80 linkers.
-\layout Itemize
+\newline
+..
+\backslash
+lib
+\backslash
-s51 - The ucSim 8051 simulator.
-\layout Itemize
+\emph on
+<model>
+\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 ~
-sdcdb - The source debugger.
-\layout Itemize
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-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
+\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
-the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
- relocatables.
\layout Standard
-In <installdir>/share/sdcc/doc
-\layout Itemize
+/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
-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
+(not on Win32)
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-sdcc - The Compiler
-\layout Standard
+\end_inset
-This is the actual compiler, it in turn uses the c-preprocessor and invokes
- the assembler and linkage editor.
-\layout Subsubsection
-sdcpp
-\begin_inset LatexCommand \index{sdcpp}
+\newline
-\end_inset
+\layout Comment
- - The C-Preprocessor
+Don't delete any of the stray spaces in the table above without checking
+ the HTML output (last line)!
\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
+\SpecialChar ~
+
+\newline
+The option -
+\begin_inset ERT
+status Collapsed
-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
+\backslash
+/
+\end_inset
-s51 - The Simulator
-\begin_inset LatexCommand \index{s51}
+-nostdlib disables the last two search paths.
+\layout Section
+
+Building SDCC
+\begin_inset LatexCommand \index{Building SDCC}
\end_inset
-\layout Standard
+\layout Subsection
-S51 is a freeware, opensource simulator developed by Daniel Drotos (
-\begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
+Building SDCC on Linux
+\begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
\end_inset
-).
- The simulator is built as part of the build process.
- For more information visit Daniel's web site at:
-\begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
-\end_inset
+\layout Enumerate
-.
- It currently support the core mcs51, the Dallas DS80C390 and the Phillips
- XA51 family.
-\layout Subsubsection
-sdcdb
-\begin_inset LatexCommand \index{sdcdb}
+\series medium
+Download the source package
+\series default
+ either from the SDCC Subversion repository or from the nightly snapshots
+\series medium
+, it will be named something like sdcc
+\series default
+.src
+\series medium
+.t
+\series default
+ar.
+\series medium
+gz
+\series default
+
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
\end_inset
- - Source Level Debugger
-\layout Standard
-
-Sdcdb is the companion source level debugger.
- The current version of the debugger uses Daniel's Simulator S51
-\begin_inset LatexCommand \index{s51}
-
-\end_inset
+.
+\layout Enumerate
-, but can be easily changed to use other simulators.
-\layout Section
-\pagebreak_top
-Using SDCC
-\layout Subsection
-Compiling
-\layout Subsubsection
+\series medium
+Bring up a command line terminal, such as xterm.
+\layout Enumerate
-Single Source File Projects
-\layout Standard
-For single source file 8051 projects the process is very simple.
- Compile your programs with the following command
+\series medium
+Unpack the file using a command like:
\family sans
\series bold
-"sdcc sourcefile.c".
-
+"tar -xvzf sdcc.src.tar.gz
\family default
\series default
- This will compile, assemble and link your source file.
- Output files are as follows
-\layout Itemize
+"
+\series medium
+, this will create a sub-directory called sdcc with all of the sources.
+\layout Enumerate
-sourcefile.asm
-\begin_inset LatexCommand \index{.asm}
+Change directory into the main SDCC directory, for example type:
+\family sans
+\series bold
+"cd sdcc
+\series default
+".
+\layout Enumerate
-\end_inset
- - Assembler source
-\begin_inset LatexCommand \index{Assembler source}
+\series medium
+Type
+\family sans
+\series bold
+"./configure
+\family default
+\series default
+".
+ This configures the package for compilation on your system.
+\layout Enumerate
-\end_inset
- file created by the compiler
-\layout Itemize
+\series medium
+Type
+\family sans
+\series bold
+"make
+\family default
+\series default
+"
+\series medium
+.
-sourcefile.lst
-\begin_inset LatexCommand \index{.lst}
+\series default
+ All of the source packages will compile, this can take a while.
+\layout Enumerate
-\end_inset
- - Assembler listing
-\begin_inset LatexCommand \index{Assembler listing}
+\series medium
+Type
+\family sans
+\series bold
+"make install"
+\family default
+\series default
+ as root
+\series medium
+.
-\end_inset
+\series default
+ This copies the binary executables, the include files, the libraries and
+ the documentation to the install directories.
+ Proceed with section
+\begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
- file created by the Assembler
-\layout Itemize
+\end_inset
-sourcefile.rst
-\begin_inset LatexCommand \index{.rst}
+.
+\layout Subsection
-\end_inset
+Building SDCC on OSX 2.x
+\layout Standard
- - Assembler listing
-\begin_inset LatexCommand \index{Assembler listing}
+Follow the instruction for Linux.
+\newline
-\end_inset
+\newline
+On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
+)) fails to compile SDCC.
+ Fortunately there's also gcc 2.9.x installed, which works fine.
+ This compiler can be selected by running 'configure' with:
+\layout LyX-Code
- file updated with linkedit information, created by linkage editor
-\layout Itemize
+./configure CC=gcc2 CXX=g++2
+\layout Subsection
-sourcefile.sym
-\begin_inset LatexCommand \index{.sym}
+Cross compiling SDCC on Linux for Windows
+\layout Standard
-\end_inset
+With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
+ See section 'Configure Options'.
+\layout Subsection
- - symbol listing
-\begin_inset LatexCommand \index{Symbol listing}
+Building SDCC on Windows
+\layout Standard
-\end_inset
+With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
+ built on Windows.
+ They use Unix-sockets, which are not available on Win32.
+\layout Subsection
- for the sourcefile, created by the assembler
-\layout Itemize
+Building SDCC using Cygwin and Mingw32
+\layout Standard
-sourcefile.rel
-\begin_inset LatexCommand \index{.rel}
+For building and installing a Cygwin executable follow the instructions
+ for Linux.
+\newline
+\newline
+On Cygwin a
+\begin_inset Quotes sld
\end_inset
- - Object file
-\begin_inset LatexCommand \index{Object file}
-
+native
+\begin_inset Quotes srd
\end_inset
- created by the assembler, input to Linkage editor
-\layout Itemize
+ Win32-binary can be built, which will not need the Cygwin-DLL.
+ For the necessary 'configure' options see section 'configure options' or
+ the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
+\newline
-sourcefile.map
-\begin_inset LatexCommand \index{.map}
+\newline
+In order to install Cygwin on Windows download setup.exe from
+\begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
\end_inset
- - The memory map
-\begin_inset LatexCommand \index{Memory map}
-
+.
+ Run it, set the
+\begin_inset Quotes sld
\end_inset
- for the load module, created by the Linker
-\layout Itemize
+default text file type
+\begin_inset Quotes srd
+\end_inset
-sourcefile.mem
-\begin_inset LatexCommand \index{.mem}
+ to
+\begin_inset Quotes sld
+\end_inset
+unix
+\begin_inset Quotes srd
\end_inset
- - A file with a summary of the memory usage
+ and download/install at least the following packages.
+ Some packages are selected by default, others will be automatically selected
+ because of dependencies with the manually selected packages.
+ Never deselect these packages!
\layout Itemize
-sourcefile.ihx
-\begin_inset LatexCommand \index{.ihx}
+flex
+\layout Itemize
-\end_inset
+bison
+\layout Itemize
- - The load module in Intel hex format
-\begin_inset LatexCommand \index{Intel hex format}
+gcc ; version 3.x is fine, no need to use the old 2.9x
+\layout Itemize
-\end_inset
+binutils ; selected with gcc
+\layout Itemize
- (you can select the Motorola S19 format
-\begin_inset LatexCommand \index{Motorola S19 format}
+make
+\layout Itemize
-\end_inset
+rxvt ; a nice console, which makes life much easier under windoze (see below)
+\layout Itemize
- with -
-\begin_inset ERT
-status Collapsed
+man ; not really needed for building SDCC, but you'll miss it sooner or
+ later
+\layout Itemize
+less ; not really needed for building SDCC, but you'll miss it sooner or
+ later
+\layout Itemize
+
+svn ; only if you use Subversion access
\layout Standard
-\backslash
-/
-\end_inset
+If you want to develop something you'll need:
+\layout Itemize
--out-fmt-s19
-\begin_inset LatexCommand \index{-\/-out-fmt-s19}
+python ; for the regression tests
+\layout Itemize
+gdb ; the gnu debugger, together with the nice GUI
+\begin_inset Quotes sld
\end_inset
-.
- If you need another format you might want to use objdump
-\begin_inset LatexCommand \index{objdump}
-
+insight
+\begin_inset Quotes srd
\end_inset
- or srecord
-\begin_inset LatexCommand \index{srecord}
-\end_inset
+\layout Itemize
-)
+openssh ; to access the CF or commit changes
\layout Itemize
-sourcefile.adb
-\begin_inset LatexCommand \index{.adb}
+autoconf and autoconf-devel ; if you want to fight with 'configure', don't
+ use autoconf-stable!
+\layout Standard
-\end_inset
+rxvt is a nice console with history.
+ Replace in your cygwin.bat the line
+\layout LyX-Code
- - An intermediate file containing debug information needed to create the
- .cdb file (with -
+bash -
\begin_inset ERT
status Collapsed
/
\end_inset
--debug
-\begin_inset LatexCommand \index{-\/-debug}
-
-\end_inset
-
-)
-\layout Itemize
+-login -i
+\layout Standard
-sourcefile.cdb
-\begin_inset LatexCommand \index{.cdb}
+with (one line):
+\layout LyX-Code
-\end_inset
+rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
+\layout LyX-Code
- - An optional file (with -
+ -bg black -fg white -geometry 100x65 -e bash -
\begin_inset ERT
status Collapsed
/
\end_inset
--debug) containing debug information
-\layout Itemize
+-login
+\layout Standard
-sourcefile.
- - (no extension)
-\begin_inset LatexCommand \index{. (no extension)}
+Text selected with the mouse is automatically copied to the clipboard, pasting
+ works with shift-insert.
+\newline
+
+\newline
+The other good tip is to make sure you have no //c/-style paths anywhere,
+ use /cygdrive/c/ instead.
+ Using // invokes a network lookup which is very slow.
+ If you think
+\begin_inset Quotes sld
+\end_inset
+cygdrive
+\begin_inset Quotes srd
\end_inset
- An optional AOMF51 file containing debug information (with -
-\begin_inset ERT
-status Collapsed
+ is too long, you can change it with e.g.
+\layout LyX-Code
+mount -s -u -c /mnt
\layout Standard
-\backslash
-/
+SDCC sources use the unix line ending LF.
+ Life is much easier, if you store the source tree on a drive which is mounted
+ in binary mode.
+ And use an editor which can handle LF-only line endings.
+ Make sure not to commit files with windows line endings.
+ The tabulator spacing
+\begin_inset LatexCommand \index{tabulator spacing (8 columns)}
+
\end_inset
--debug)
-\layout Itemize
+ used in the project is 8.
+ Although a tabulator spacing of 8 is a sensible choice for programmers
+ (it's a power of 2 and allows to display 8/16 bit signed variables without
+ loosing columns) the plan is to move towards using only spaces in the source.
+\layout Subsection
-sourcefile.dump*
-\begin_inset LatexCommand \index{.dump*}
+Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
+\layout Standard
+
+
+\series medium
+Download the source package
+\series default
+ either from the SDCC Subversion repository or from the
+\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
\end_inset
- - Dump file to debug the compiler it self (with -
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\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 (except for sdcdb.exe which currently
+ doesn't build under MSVC).
+ 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 running SDCC.
+
+\newline
+
+\newline
+WARNING: Visual studio is very picky with line terminations; it expects
+ the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
+ When using the Subversion repository it's easiest to configure the svn
+ client to convert automatically for you.
+ If however you are getting a message such as "This makefile was not generated
+ by Developer Studio etc.
+ etc.
+\begin_inset Quotes srd
\end_inset
--dumpall) (see section
+ when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
+ need to convert the Unix style line endings to DOS style line endings.
+ To do so you can use the
\begin_inset Quotes sld
\end_inset
-Anatomy of the compiler
+unix2dos
\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:
+ utility freely available on the internet.
+ Doug Hawkins reported in the sdcc-user list that this works:
\newline
\newline
-foo1.c (contains some functions)
+C:
+\backslash
+Programming
+\backslash
+SDCC> unix2dos sdcc.dsw
\newline
-foo2.c (contains some more functions)
+C:
+\backslash
+Programming
+\backslash
+SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
\newline
-foomain.c (contains more functions and the function main)
+
\newline
+In order to build SDCC with MSVC 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
-\size footnotesize
\newline
-\size default
-The first two files will need to be compiled separately with the commands:
-\size footnotesize
-
-\size default
+\newline
+Download the file UnxUtils
+\begin_inset LatexCommand \index{UnxUtils}
+
+\end_inset
+
+.zip.
+ Now you have to install the utilities and setup MSVC 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
-\family sans
-\series bold
-sdcc\SpecialChar ~
--c\SpecialChar ~
-foo1.c
-\family default
-\series default
-\size footnotesize
+\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
-\family sans
-\series bold
-\size default
-sdcc\SpecialChar ~
--c\SpecialChar ~
-foo2.c
-\family default
-\series default
+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
-Then compile the source file containing the
-\emph on
-main()
-\emph default
- function and link
-\begin_inset LatexCommand \index{Linker}
+a) Create a directory were to put the tools needed, or use a directory already
+ present.
+ Say for example 'C:
+\backslash
+util'.
+\newline
-\end_inset
+\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
- the files together with the following command:
+\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
-\family sans
-\series bold
-sdcc\SpecialChar ~
-foomain.c\SpecialChar ~
-foo1.rel\SpecialChar ~
-foo2.rel
-\family default
-\series default
+\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
-\begin_inset LatexCommand \index{.rel}
+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 Subsection
-\end_inset
+Building SDCC 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 dependenci
+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 command (be
+ sure you are in the sdcc directory):
\newline
\newline
-Alternatively,
-\emph on
-foomain.c
-\emph default
-can be separately compiled as well:
+
\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
-sdcc\SpecialChar ~
--c\SpecialChar ~
-foomain.c
-\newline
-sdcc foomain.rel foo1.rel foo2.rel
+or on Windows NT/2000/XP from the command prompt with the command:
\newline
-\newline
+\family sans
+\series bold
+\newline
+del /s *.obj *.lib *.rul
\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.
- The linker is invoked from sdcc using a script file with extension .lnk
-\begin_inset LatexCommand \index{.lnk}
-
-\end_inset
+ from the sdcc directory.
+\layout Subsection
-.
- You can view this file to troubleshoot linking problems such as those arising
- from missing libraries.
-\layout Subsubsection
+Windows Install Using a ZIP Package
+\layout Enumerate
-Projects with Additional Libraries
-\begin_inset LatexCommand \index{Libraries}
+Download the binary zip package from
+\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
\end_inset
+ 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
+sdcc
+\backslash
+bin for the executables, c:
+\backslash
+sdcc
+\backslash
+include and c:
+\backslash
+sdcc
+\backslash
+lib for the include and libraries.
+\layout Enumerate
-\layout Standard
+Adjust your environment variable PATH to include the location of the bin
+ directory or start sdcc using the full path.
+\layout Subsection
-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
-\begin_inset LatexCommand \index{.lib}
+Windows Install Using the Setup Program
+\begin_inset LatexCommand \label{sub:Windows-Install}
\end_inset
-\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
+\layout Standard
-\family default
-\series default
-Note here that
+Download the setup program
\emph on
- mylib
+sdcc-x.y.z-setup.exe
\emph default
- must be an absolute path name.
+ for an official release from
\newline
-\newline
-The most efficient way to use libraries is to keep separate modules in separate
- source files.
- The lib file now should name all the modules.rel
-\begin_inset LatexCommand \index{rel}
+\begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
\end_inset
- files.
- For an example see the standard library file
+ or a setup program for one of the snapshots
\emph on
-libsdcc.lib
+sdcc-yyyymmdd-xxxx-setup.exe
\emph default
- in the directory <installdir>/share/lib/small.
-\layout Subsection
-
-Command Line Options
-\begin_inset LatexCommand \index{Command Line Options}
+ from
+\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
\end_inset
+ and execute it.
+ A windows typical installer will guide you through the installation process.
+\layout Subsection
-\layout Subsubsection
-
-Processor Selection Options
-\begin_inset LatexCommand \index{Options processor selection}
+VPATH
+\begin_inset LatexCommand \index{VPATH}
\end_inset
+ feature
+\layout Standard
-\begin_inset LatexCommand \index{Processor selection options}
+SDCC supports the VPATH feature provided by configure and make.
+ It allows to separate the source and build trees.
+ Here's an example:
+\layout Standard
-\end_inset
+\family typewriter
+cd ~\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+# cd $HOME
+\layout Standard
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+tar -xzf sdcc.src.tar.gz\SpecialChar ~
+# extract source to directory sdcc
+\layout Standard
-\series bold
--mmcs51
-\begin_inset LatexCommand \index{-mmcs51}
-\end_inset
+\family typewriter
+mkdir sdcc.build\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+# put output in sdcc.build
+\layout Standard
-\series default
- Generate code for the MCS51
-\begin_inset LatexCommand \index{MCS51}
+\family typewriter
+cd sdcc.build
+\layout Standard
-\end_inset
- family of processors.
- This is the default processor target.
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+../sdcc/configure\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+# configure is doing all the magic!
+\layout Standard
+\family typewriter
+make
+\layout Standard
+\noindent
+That's it!
\series bold
--mds390
-\begin_inset LatexCommand \index{-mds390}
+configure
+\series default
+ will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
+ It automagically computes the variables srcdir, top_srcdir and top_buildir
+ for each directory.
+ After running
+\series bold
+make
+\series default
+ the generated files will be in ~/sdcc.build, while the source files stay
+ in ~/sdcc.
+\newline
+This is not only usefull for building different binaries, e.g.
+ when cross compiling.
+ It also gives you a much better overview in the source tree when all the
+ generated files are not scattered between the source files.
+ And the best thing is: if you want to change a file you can leave the original
+ file untouched in the source directory.
+ Simply copy it to the build directory, edit it, enter `make clean`, `rm
+ Makefile.dep` and `make`.
+
+\series bold
+make
+\series default
+ will do the rest for you!
+\layout Section
-\end_inset
+Building the Documentation
+\layout Standard
+Add -
+\begin_inset ERT
+status Collapsed
-\series default
- Generate code for the DS80C390
-\begin_inset LatexCommand \index{DS80C390}
+\layout Standard
+\backslash
+/
\end_inset
- processor.
-\layout List
-\labelwidthstring 00.00.0000
-
-
+-enable-doc to the configure arguments to build the documentation together
+ with all the other stuff.
+ You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
+ dvips and makeindex) to get the job done.
+ Another possibility is to change to the doc directory and to type
+\family sans
\series bold
--mds400
-\begin_inset LatexCommand \index{-mds400}
+\begin_inset Quotes srd
+\end_inset
+
+make
+\begin_inset Quotes srd
\end_inset
+\family default
\series default
- Generate code for the DS80C400
-\begin_inset LatexCommand \index{DS80C400}
+ there.
+ You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
+x).
+ Using LyX
+\begin_inset LatexCommand \url{http://www.lyx.org}
\end_inset
- processor.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--mz80
-\begin_inset LatexCommand \index{-mz80}
+ as editor is straightforward.
+ Prebuilt documentation in html and pdf format is available from
+\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
\end_inset
+.
+\layout Section
-\series default
- Generate code for the Z80
-\begin_inset LatexCommand \index{Z80}
+Reading the Documentation
+\layout Standard
-\end_inset
+Currently reading the document in pdf format is recommended, as for unknown
+ reason the hyperlinks are working there whereas in the html version they
+ are not
+\begin_inset Foot
+collapsed false
- family of processors.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+If you should know why please drop us a note
+\end_inset
-\series bold
--mgbz80
-\begin_inset LatexCommand \index{-mgbz80}
+.
+
+\newline
+You'll find the pdf version
+\begin_inset LatexCommand \index{PDF version of this document}
\end_inset
-
-\series default
- Generate code for the GameBoy Z80
-\begin_inset LatexCommand \index{GameBoy Z80}
+ at
+\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
\end_inset
- processor.
-\layout List
-\labelwidthstring 00.00.0000
+.
+
+\newline
+A html version
+\begin_inset LatexCommand \index{HTML version of this document}
+\end_inset
-\series bold
--mavr
-\begin_inset LatexCommand \index{-mavr}
+ should be online at
+\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
\end_inset
+.
+\newline
+This documentation is in some aspects different from a commercial documentation:
+
+\layout Itemize
-\series default
- Generate code for the Atmel AVR
-\begin_inset LatexCommand \index{AVR}
+It tries to document SDCC for several processor architectures in one document
+ (commercially these probably would be separate documents/products).
+ This document
+\begin_inset LatexCommand \index{Status of documentation}
\end_inset
- processor (In development, not complete).
- AVR users should probably have a look at avr-gcc
-\begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
+ currently matches SDCC for mcs51 and DS390 best and does give too few informati
+on about f.e.
+ Z80, PIC14, PIC16 and HC08.
+\layout Itemize
+
+There are many references pointing away from this documentation.
+ Don't let this distract you.
+ If there f.e.
+ was a reference like
+\begin_inset LatexCommand \url{http://www.opencores.org}
\end_inset
-.
-\layout Comment
+ together with a statement
+\begin_inset Quotes sld
+\end_inset
-I think it is fair to direct users there for now.
- Open source is also about avoiding unnecessary work .
- But I didn't find the 'official' link.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--mpic14
-\begin_inset LatexCommand \index{-mpic14}
-
-\end_inset
-
-
-\series default
- Generate code for the PIC 14
-\begin_inset LatexCommand \index{PIC14}
+some processors which are targetted by SDCC can be implemented in a
+\emph on
+f
+\emph default
+ield
+\emph on
+p
+\emph default
+rogrammable
+\emph on
+g
+\emph default
+ate
+\emph on
+a
+\emph default
+rray
+\begin_inset LatexCommand \index{FPGA (field programmable gate array)}
\end_inset
--bit processors (Microchip p16f84 and variants).
-\layout Comment
-
-p16f627 p16f628 p16f84 p16f873 p16f877?
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--mpic16
-\begin_inset LatexCommand \index{-mpic16}
+\begin_inset Quotes srd
\end_inset
-
-\series default
- Generate code for the PIC 16
-\begin_inset LatexCommand \index{PIC16}
+ or
+\begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
\end_inset
--bit processors (Microchip p18f452 and variants).
-\layout List
-\labelwidthstring 00.00.0000
-
-\series bold
--mtlcs900h
-\series default
- Generate code for the Toshiba TLCS-900H
-\begin_inset LatexCommand \index{TLCS-900H}
+\begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
\end_inset
- processor (In development, not complete).
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--mxa51
-\begin_inset LatexCommand \index{-mxa51}
-
+
+\begin_inset Quotes sld
\end_inset
-
-\series default
- Generate code for the Phillips XA51
-\begin_inset LatexCommand \index{XA51}
-
+have you ever heard of an open source compiler that compiles a subset of
+ C for an FPGA?
+\begin_inset Quotes srd
\end_inset
- processor (In development, not complete).
-\layout Subsubsection
+ we expect you to have a quick look there and come back.
+ If you read this you are on the right track.
+\layout Itemize
-Preprocessor Options
-\begin_inset LatexCommand \index{Options preprocessor}
+Some sections attribute more space to problems, restrictions and warnings
+ than to the solution.
+\layout Itemize
-\end_inset
+The installation section and the section about the debugger is intimidating.
+\layout Itemize
+There are still lots of typos and there are more different writing styles
+ than pictures.
+\layout Section
-\begin_inset LatexCommand \index{Preprocessor options}
+Testing the SDCC Compiler
+\begin_inset LatexCommand \label{sec:Testing-the-SDCC}
\end_inset
-\layout List
-\labelwidthstring 00.00.0000
-
+\layout Standard
+The first thing you should do after installing your SDCC compiler is to
+ see if it runs.
+ Type
+\family sans
\series bold
--I<path>
-\begin_inset LatexCommand \index{-I<path>}
-
-\end_inset
-
+"sdcc -
+\begin_inset ERT
+status Collapsed
-\series default
- The additional location where the pre processor will look for <..h> or
-\begin_inset Quotes eld
-\end_inset
+\layout Standard
-..h
-\begin_inset Quotes erd
+\backslash
+/
\end_inset
- files.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--D<macro[=value]>
-\begin_inset LatexCommand \index{-D<macro[=value]>}
+-version"
+\begin_inset LatexCommand \index{version}
\end_inset
+\family default
\series default
- Command line definition of macros.
- Passed to the pre processor.
-\layout List
-\labelwidthstring 00.00.0000
+ at the prompt, and the program should run and output its version like:
+
+\newline
+\family typewriter
+SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
+ (UNIX)
+\layout Standard
-\series bold
--M
-\begin_inset LatexCommand \index{-M}
+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 (
+\series medium
+see
+\series default
+section
+\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
\end_inset
+\SpecialChar ~
+\series medium
+Install trouble-shooting for suggestions
\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
+).
+ Make sure that the sdcc program is in the bin folder, if not perhaps something
+ did not install correctly.
+\newline
+\newline
-\series bold
--C
-\begin_inset LatexCommand \index{-C}
+\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
- Tell the preprocessor not to discard comments.
- Used with the `-E' option.
-\layout List
-\labelwidthstring 00.00.0000
+ASCII
+\series medium
+editor:
+\layout Verse
-\series bold
--MM
-\begin_inset LatexCommand \index{-MM}
+\family typewriter
+char test;
+\newline
-\end_inset
+\newline
+void main(void) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+test=0;
+\newline
+}
+\layout Standard
-\size large
-\bar under
+\series medium
+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
-\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
+\newline
+\newline
+\series medium
+The next step is to try it with the linker.
+ Type in
+\family sans
\series bold
--Aquestion(answer)
-\begin_inset LatexCommand \index{-Aquestion(answer)}
+"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
+\series default
+SDCC
+\series medium
+ cannot find the
+\series default
+/
+\series medium
+usr/local/share/sdcc/lib directory
+\series default
+
+\series medium
+(see
+\series default
+section
+\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
\end_inset
+\SpecialChar ~
+\series medium
+Install trouble-shooting for suggestions).
\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
+\newline
+
+\newline
-\series bold
--Aquestion
+\series medium
+The final test is to ensure
\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
-\begin_inset LatexCommand \index{-Umacro}
-
-\end_inset
-
-
+SDCC
+\series medium
+ can use the
\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
-
+standard
+\series medium
+ header files and libraries.
+ Edit test.c and change it to the following:
+\layout Verse
-\series bold
--dM
-\begin_inset LatexCommand \index{-dM}
-\end_inset
+\family typewriter
+#include <string.h>
+\newline
+\newline
+char str1[10];
+\newline
-\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
+\newline
+void main(void) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+strcpy(str1, "testing");
+\newline
+}
+\layout Standard
+\series medium
+Compile this by typing
+\family sans
\series bold
--dD
-\begin_inset LatexCommand \index{-dD}
-
-\end_inset
-
-
+"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
+\series default
+SDCC
+\series medium
+ cannot find the /usr/local/share/sdcc/include directory
\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
-\begin_inset LatexCommand \index{-dN}
-
-\end_inset
-
-
-\size large
-\bar under
+\series medium
+(see the
\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
-\begin_inset LatexCommand \index{Options linker}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{Linker options}
+section
+\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
\end_inset
+\SpecialChar ~
-\layout List
-\labelwidthstring 00.00.0000
-
+\series medium
+Install trouble-shooting section for suggestions).
+\series default
+ Use option
\series bold
--L\SpecialChar ~
-
-\series default
-
\begin_inset ERT
status Collapsed
/
\end_inset
+-print-search-dirs
+\series default
-\series bold
--lib-path
-\begin_inset LatexCommand \index{-\/-lib-path}
+\begin_inset LatexCommand \index{-\/-print-search-dirs}
\end_inset
+ to find exactly where SDCC is looking for the include and lib files.
+\layout Section
-\begin_inset LatexCommand \index{-L -\/-lib-path}
+Install Trouble-shooting
+\begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
\end_inset
-\bar under
-
-\series default
-\bar default
-<absolute path to additional libraries> This option is passed to the linkage
- editor's additional libraries
-\begin_inset LatexCommand \index{Libraries}
+\begin_inset LatexCommand \index{Install trouble-shooting}
\end_inset
- 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
--
-\begin_inset ERT
-status Collapsed
+\layout Subsection
+If SDCC does not build correctly
\layout Standard
-\backslash
-/
-\end_inset
+A thing to try is starting from scratch by unpacking the .tgz source package
+ again in an empty directory.
+ Configure it like:
+\newline
--xram-loc
+\newline
+
+\family sans
+\series bold
+./configure 2>&1 | tee configure.log
+\family default
\series default
-\begin_inset LatexCommand \index{-\/-xram-loc}
+\newline
-\end_inset
+\newline
+and build it like:
+\newline
-<Value> The start location of the external ram
-\begin_inset LatexCommand \index{xdata}
+\newline
-\end_inset
+\family sans
+\series bold
+make 2>&1 | tee make.log
+\family default
+\series default
-, default value is 0.
- The value entered can be in Hexadecimal or Decimal format, e.g.: -
-\begin_inset ERT
-status Collapsed
+\newline
-\layout Standard
+\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 Subsection
-\backslash
-/
+What the
+\begin_inset Quotes sld
\end_inset
--xram-loc 0x8000 or -
-\begin_inset ERT
-status Collapsed
+./configure
+\begin_inset Quotes srd
+\end_inset
+ does
\layout Standard
-\backslash
-/
+The
+\begin_inset Quotes sld
\end_inset
--xram-loc 32768.
-\layout List
-\labelwidthstring 00.00.0000
-
+./configure
+\begin_inset Quotes srd
+\end_inset
-\series bold
--
-\begin_inset ERT
-status Collapsed
+ 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 Subsection
-\layout Standard
+What the
+\begin_inset Quotes sld
+\end_inset
-\backslash
-/
+make
+\begin_inset Quotes srd
\end_inset
--code-loc
-\series default
+ does
+\layout Standard
-\begin_inset LatexCommand \index{-\/-code-loc}
+This runs the GNU make tool, which automatically compiles all the source
+ packages into the final installed binary executables.
+\layout Subsection
+What the
+\begin_inset Quotes sld
\end_inset
-<Value> The start location of the code
-\begin_inset LatexCommand \index{code}
-
+make install
+\begin_inset Quotes erd
\end_inset
- 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.: -
-\begin_inset ERT
-status Collapsed
-
+ command does.
\layout Standard
-\backslash
-/
+This will install the compiler, other executables libraries and include
+ files into the appropriate directories.
+ See sections
+\begin_inset LatexCommand \ref{sub:Install-paths}
+
\end_inset
--code-loc 0x8000 or -
-\begin_inset ERT
-status Collapsed
+,\SpecialChar ~
-\layout Standard
+\begin_inset LatexCommand \ref{sub:Search-Paths}
-\backslash
-/
\end_inset
--code-loc 32768.
-\layout List
-\labelwidthstring 00.00.0000
+\SpecialChar ~
+about install and search paths.
+\newline
+On most systems you will need super-user privileges to do this.
+\layout Section
+Components of SDCC
+\layout Standard
-\series bold
--
-\begin_inset ERT
-status Collapsed
+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
-\layout Standard
+\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
-\backslash
-/
-\end_inset
+sdcc - The compiler.
+\layout Itemize
--stack-loc
-\series default
+sdcpp - The C preprocessor.
+\layout Itemize
-\begin_inset LatexCommand \index{-\/-stack-loc}
+asx8051 - The assembler for 8051 type processors.
+\layout Itemize
-\end_inset
+as-z80
+\series bold
+,
+\series default
+as-gbz80 - The Z80 and GameBoy Z80 assemblers.
+\layout Itemize
-<Value> By default the stack
-\begin_inset LatexCommand \index{stack}
+aslink -The linker for 8051 type processors.
+\layout Itemize
-\end_inset
+link-z80
+\series bold
+,
+\series default
+link-gbz80 - The Z80 and GameBoy Z80 linkers.
+\layout Itemize
- 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.
- -
-\begin_inset ERT
-status Collapsed
+s51 - The ucSim 8051 simulator.
+ Not available on Win32 platforms.
+\layout Itemize
-\layout Standard
+sdcdb - The source debugger.
+ Not available on Win32 platforms.
+\layout Itemize
-\backslash
-/
-\end_inset
+packihx - A tool to pack (compress) Intel hex files.
+\layout Standard
--stack-loc 0x20 or -
-\begin_inset ERT
-status Collapsed
+In <installdir>/share/sdcc/include
+\layout Itemize
+the include files
\layout Standard
-\backslash
-/
-\end_inset
+In <installdir>/share/sdcc/lib
+\layout Itemize
--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
+the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
+ relocatables.
+\layout Standard
+In <installdir>/share/sdcc/doc
+\layout Itemize
-\series bold
--
-\begin_inset ERT
-status Collapsed
+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 Subsection
+sdcc - The Compiler
\layout Standard
-\backslash
-/
-\end_inset
+This is the actual compiler, it in turn uses the c-preprocessor and invokes
+ the assembler and linkage editor.
+\layout Subsection
--data-loc
-\series default
+sdcpp - The C-Preprocessor
+\layout Standard
-\begin_inset LatexCommand \index{-\/-data-loc}
+The preprocessor
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
\end_inset
-<Value> The start location of the internal ram data
-\begin_inset LatexCommand \index{data}
+ 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 Subsection
-\end_inset
+as
+\emph on
+xxxx
+\emph default
+, aslink, link-
+\emph on
+xxx
+\emph default
+ - The Assemblers and Linkage Editors
+\layout Standard
- segment.
- The value entered can be in Hexadecimal or Decimal format, eg.
- -
-\begin_inset ERT
-status Collapsed
+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 SDCC.
+\layout Subsection
+s51 - The Simulator
\layout Standard
-\backslash
-/
+S51
+\begin_inset LatexCommand \index{s51}
+
\end_inset
--data-loc 0x20 or -
-\begin_inset ERT
-status Collapsed
+ is a freeware, opensource simulator developed by Daniel Drotos.
+ The simulator is built as part of the build process.
+ For more information visit Daniel's web site at:
+\begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
+
+\end_inset
+
+.
+ It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
+ XA51 family.
+ S51 is currently not available on Win32 platfors.
+\layout Subsection
+sdcdb - Source Level Debugger
\layout Standard
-\backslash
-/
+Sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
\end_inset
--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 -
-\begin_inset ERT
-status Collapsed
+ is the companion source level debugger.
+ More about sdcdb in section
+\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
-\layout Standard
+\end_inset
+
+.
+ The current version of the debugger uses Daniel's Simulator S51
+\begin_inset LatexCommand \index{s51}
-\backslash
-/
\end_inset
--data-loc is not used, to location 0x10.)
-\layout List
-\labelwidthstring 00.00.0000
+, but can be easily changed to use other simulators.
+ Sdcdb is currently not available on Win32 platfors.
+\layout Chapter
+Using SDCC
+\layout Section
-\series bold
--
-\begin_inset ERT
-status Collapsed
+Compiling
+\layout Subsection
+Single Source File Projects
\layout Standard
-\backslash
-/
-\end_inset
+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".
--idata-loc
+\family default
\series default
+ This will compile, assemble and link your source file.
+ Output files are as follows:
+\layout Itemize
-\begin_inset LatexCommand \index{-\/-idata-loc}
+sourcefile.asm
+\begin_inset LatexCommand \index{<file>.asm}
\end_inset
-<Value> The start location of the indirectly addressable internal ram
-\begin_inset LatexCommand \index{idata}
+ - Assembler source
+\begin_inset LatexCommand \index{Assembler source}
\end_inset
-, default value is 0x80.
- The value entered can be in Hexadecimal or Decimal format, eg.
- -
-\begin_inset ERT
-status Collapsed
+ file created by the compiler
+\layout Itemize
-\layout Standard
+sourcefile.lst
+\begin_inset LatexCommand \index{<file>.lst}
-\backslash
-/
\end_inset
--idata-loc 0x88 or -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+ - Assembler listing
+\begin_inset LatexCommand \index{Assembler listing}
-\backslash
-/
\end_inset
--idata-loc 136.
-\layout List
-\labelwidthstring 00.00.0000
+ file created by the Assembler
+\layout Itemize
+sourcefile.rst
+\begin_inset LatexCommand \index{<file>.rst}
-\series bold
--
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
+ - Assembler listing
+\begin_inset LatexCommand \index{Assembler listing}
-\backslash
-/
\end_inset
--out-fmt-ihx
-\begin_inset LatexCommand \index{-\/-out-fmt-ihx}
+ file updated with linkedit information, created by linkage editor
+\layout Itemize
-\end_inset
+sourcefile.sym
+\begin_inset LatexCommand \index{<file>.sym}
+\end_inset
-\bar under
-
-\series default
-\bar default
-The linker output (final object code) is in Intel Hex format.
-\begin_inset LatexCommand \index{Intel hex format}
+ - symbol listing
+\begin_inset LatexCommand \index{Symbol listing}
\end_inset
- (This is the default option).
-\layout List
-\labelwidthstring 00.00.0000
+ for the sourcefile, created by the assembler
+\layout Itemize
+sourcefile.rel
+\begin_inset LatexCommand \index{<file>.rel}
-\series bold
--
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
+ or sourcefile.o
+\begin_inset LatexCommand \index{<file>.o}
-\backslash
-/
\end_inset
--out-fmt-s19
-\begin_inset LatexCommand \index{-\/-out-fmt-s19}
+ - Object file
+\begin_inset LatexCommand \index{Object file}
\end_inset
+ created by the assembler, input to Linkage editor
+\layout Itemize
-\bar under
-
-\series default
-\bar default
-The linker output (final object code) is in Motorola S19 format
-\begin_inset LatexCommand \index{Motorola S19 format}
+sourcefile.map
+\begin_inset LatexCommand \index{<file>.map}
\end_inset
-.
-\layout Subsubsection
-
-MCS51 Options
-\begin_inset LatexCommand \index{Options MCS51}
+ - The memory map
+\begin_inset LatexCommand \index{Memory map}
\end_inset
+ for the load module, created by the Linker
+\layout Itemize
-\begin_inset LatexCommand \index{MCS51 options}
+sourcefile.mem
+\begin_inset LatexCommand \index{<file>.mem}
\end_inset
+ - A file with a summary of the memory usage
+\layout Itemize
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+sourcefile.ihx
+\begin_inset LatexCommand \index{<file>.ihx}
-\backslash
-/
\end_inset
--model-large
-\begin_inset LatexCommand \index{-\/-model-large}
+ - The load module in Intel hex format
+\begin_inset LatexCommand \index{Intel hex format}
\end_inset
+ (you can select the Motorola S19 format
+\begin_inset LatexCommand \index{Motorola S19 format}
-\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
-
+\end_inset
-\series bold
--
+ with -
\begin_inset ERT
status Collapsed
/
\end_inset
--model-small
-\begin_inset LatexCommand \index{-\/-model-small}
+-out-fmt-s19
+\begin_inset LatexCommand \index{-\/-out-fmt-s19}
\end_inset
+.
+ If you need another format you might want to use
+\family sans
+\shape italic
+objdump
+\family default
+\shape default
-\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
-\begin_inset LatexCommand \index{Options DS390}
+\begin_inset LatexCommand \index{objdump (tool)}
\end_inset
+ or
+\family sans
+\shape italic
+ srecord
+\family default
+\shape default
+
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
-\begin_inset LatexCommand \index{DS390 options}
+\end_inset
+
+).
+ Both formats are documented in the documentation of srecord
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
\end_inset
-\layout List
-\labelwidthstring 00.00.0000
+\layout Itemize
+
+sourcefile.adb
+\begin_inset LatexCommand \index{<file>.adb}
+\end_inset
-\series bold
--
+ - An intermediate file containing debug information needed to create the
+ .cdb file (with -
\begin_inset ERT
-status Collapsed
+status Open
\layout Standard
/
\end_inset
--model-flat24
-\series default
-
-\begin_inset LatexCommand \index{-\/-model-flat24}
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
\end_inset
+)
+\layout Itemize
-\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
+sourcefile.cdb
+\begin_inset LatexCommand \index{<file>.cdb}
+\end_inset
-\series bold
--
+ - An optional file (with -
\begin_inset ERT
status Collapsed
/
\end_inset
--stack-10bit
-\series default
+-debug) containing debug information.
+ The format is documented in cdbfileformat.pdf
+\layout Itemize
-\begin_inset LatexCommand \index{-\/-stack-10bit}
+sourcefile.
+ - (no extension)
+\begin_inset LatexCommand \index{<file> (no extension)}
\end_inset
- 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
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+ An optional AOMF or AOMF51
+\begin_inset LatexCommand \index{AOMF, AOMF51}
-\backslash
-/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\begin_inset LatexCommand \label{OMF file}
\end_inset
-
-\emph default
- option, but that has not been tested.
- It is incompatible with the
-\emph on
--
+file containing debug information (generated with option -
\begin_inset ERT
status Collapsed
/
\end_inset
--xstack
-\begin_inset LatexCommand \index{-\/-xstack}
+-debug).
+ The (Intel)
+\emph on
+ a
+\emph default
+bsolute
+\emph on
+o
+\emph default
+bject
+\emph on
+m
+\emph default
+odule
+\emph on
+f
+\emph default
+ormat is commonly used by third party tools (debuggers
+\begin_inset LatexCommand \index{Debugger}
\end_inset
+, simulators, emulators)
+\layout Itemize
-\emph default
- option.
- It also only makes sense if the processor is in 24 bit contiguous addressing
- mode (see the
-\emph on
--
+sourcefile.dump*
+\begin_inset LatexCommand \index{<file>.dump*}
+
+\end_inset
+
+ - Dump file to debug the compiler it self (generated with option -
\begin_inset ERT
status Collapsed
/
\end_inset
--model-flat24 option
-\emph default
-).
-\layout Subsubsection
-
-Z80 Options
-\begin_inset LatexCommand \index{Options Z80}
+-dumpall) (see section
+\begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
\end_inset
-
-\begin_inset LatexCommand \index{Z80 options}
+\SpecialChar ~
+ and section
+\begin_inset LatexCommand \ref{sub:The-anatomy-of}
\end_inset
+\SpecialChar ~
-\layout List
-\labelwidthstring 00.00.0000
+\begin_inset Quotes sld
+\end_inset
+Anatomy of the compiler
+\begin_inset Quotes srd
+\end_inset
-\series bold
--
-\begin_inset ERT
-status Collapsed
+).
+\layout Subsection
+Projects with Multiple Source Files
\layout Standard
-\backslash
-/
-\end_inset
-
--callee-saves-bc
-\series default
+SDCC can compile only ONE file at a time.
+ Let us for example assume that you have a project containing the following
+ files:
+\newline
-\begin_inset LatexCommand \index{-\/-callee-saves-bc}
+\newline
+foo1.c (contains some functions)
+\newline
+foo2.c (contains some more functions)
+\newline
+foomain.c (contains more functions and the function main)
+\newline
-\end_inset
+\size footnotesize
+\newline
-\size large
-\emph on
+\size default
+The first two files will need to be compiled separately with the commands:
+\size footnotesize
\size default
-\emph default
-Force a called function to always save BC.
-\layout List
-\labelwidthstring 00.00.0000
+\newline
-\series bold
--
-\begin_inset ERT
-status Collapsed
+\newline
-\layout Standard
+\family sans
+\series bold
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foo1.c
+\family default
+\series default
+\size footnotesize
-\backslash
-/
-\end_inset
+\newline
--no-std-crt0
+\family sans
+\series bold
+\size default
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foo2.c
+\family default
\series default
-\begin_inset LatexCommand \index{-\/-no-std-crt0}
+\newline
-\end_inset
+\newline
+Then compile the source file containing the
+\emph on
+main()
+\emph default
+ function and link
+\begin_inset LatexCommand \index{Linker}
- When linking, skip the standard crt0.o object file.
- You must provide your own crt0.o for your system when linking.
-
-\layout Subsubsection
+\end_inset
-Optimization Options
-\begin_inset LatexCommand \index{Options optimization}
+ the files together with the following command:
+\newline
-\end_inset
+\newline
+\family sans
+\series bold
+sdcc\SpecialChar ~
+foomain.c\SpecialChar ~
+foo1.rel\SpecialChar ~
+foo2.rel
+\family default
+\series default
-\begin_inset LatexCommand \index{Optimization options}
+\begin_inset LatexCommand \index{<file>.rel}
\end_inset
-\layout List
-\labelwidthstring 00.00.0000
-
+\newline
+\newline
+Alternatively,
+\emph on
+foomain.c
+\emph default
+can be separately compiled as well:
+\family sans
\series bold
--
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\newline
-\backslash
-/
-\end_inset
+\newline
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foomain.c
+\newline
+sdcc foomain.rel foo1.rel foo2.rel
+\newline
--nogcse
-\begin_inset LatexCommand \index{-\/-nogcse}
+\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.
+ The linker is invoked from SDCC using a script file with extension .lnk
+\begin_inset LatexCommand \index{<file>.lnk}
\end_inset
+.
+ You can view this file to troubleshoot linking problems such as those arising
+ from missing libraries.
+\layout Subsection
-\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
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+Projects with Additional Libraries
+\begin_inset LatexCommand \index{Libraries}
\end_inset
- can be used to turn off global subexpression elimination
-\begin_inset LatexCommand \index{Subexpression elimination}
+
+\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
+\begin_inset LatexCommand \index{<file>.lib}
\end_inset
- for a given function only.
-\layout List
-\labelwidthstring 00.00.0000
+\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
--
-\begin_inset ERT
-status Collapsed
+sdcc foomain.c foolib.lib -L mylib
+\newline
-\layout Standard
+\newline
-\backslash
-/
-\end_inset
+\family default
+\series default
+Note here that
+\emph on
+ mylib
+\emph default
+ must be an absolute path name.
+\newline
--noinvariant
-\begin_inset LatexCommand \index{-\/-noinvariant}
+\newline
+The most efficient way to use libraries is to keep separate modules in separate
+ source files.
+ The lib file now should name all the modules.rel
+\begin_inset LatexCommand \index{<file>.rel}
\end_inset
+ files.
+ For an example see the standard library file
+\emph on
+libsdcc.lib
+\emph default
+ in the directory <installdir>/share/lib/small.
+\layout Subsection
-\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
-\begin_inset LatexCommand \index{\#pragma NOINVARIANT}
+Using sdcclib to Create and Manage Libraries
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
- can be used to turn off invariant optimizations for a given function only.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
-\series bold
--
-\begin_inset ERT
-status Collapsed
+Alternatively, instead of having a .rel file for each entry on the library
+ file as described in the preceding section, sdcclib can be used to embed
+ all the modules belonging to such library in the library file itself.
+ This results in a larger library file, but it greatly reduces the number
+ of disk files accessed by the linker.
+ Additionally, the packed library file contains an index of all include
+ modules and symbols that significantly speeds up the linking process.
+ To display a list of options supported by sdcclib type:
+\newline
\layout Standard
-\backslash
-/
-\end_inset
--noinduction
-\begin_inset LatexCommand \index{-\/-noinduction}
+\family sans
+\series bold
+sdcclib -?
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\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
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+\newline
-\end_inset
+\newline
- can be used to turn off induction optimizations for a given function only.
-\layout List
-\labelwidthstring 00.00.0000
+\family default
+\series default
+To create a new library file, start by compiling all the required modules.
+ For example:
+\newline
+
+\layout Standard
+\family sans
\series bold
--
-\begin_inset ERT
-status Collapsed
+sdcc -c _divsint.c
+\layout Standard
+
+\family sans
+\series bold
+sdcc -c _divuint.c
\layout Standard
-\backslash
-/
-\end_inset
--nojtbound
-\begin_inset LatexCommand \index{-\/-nojtbound}
+\family sans
+\series bold
+sdcc -c _modsint.c
+\layout Standard
-\end_inset
+\family sans
+\series bold
+sdcc -c _moduint.c
+\layout Standard
-\size large
-\bar under
-
-\series default
-\size default
-\bar default
- Will not generate boundary condition check when switch statements
-\begin_inset LatexCommand \index{switch statement}
-\end_inset
+\family sans
+\series bold
+sdcc -c _mulint.c
+\newline
- are implemented using jump-tables.
- See section Switch Statements for more details.
- It is recommended that this option is NOT used, #pragma\SpecialChar ~
-NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+\layout Standard
-\end_inset
+This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
+ and _mulint.rel.
+ The next step is to add the .rel files to the library file:
+\newline
- can be used to turn off boundary checking for jump tables for a given function
- only.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+\family sans
\series bold
--
-\begin_inset ERT
-status Collapsed
+sdcclib libint.lib _divsint.rel
+\family default
-\layout Standard
+\begin_inset LatexCommand \index{sdcclib}
-\backslash
-/
\end_inset
--noloopreverse
-\begin_inset LatexCommand \index{-\/-noloopreverse}
-\end_inset
+\layout Standard
-\series default
-\size large
-
-\size default
-Will not do loop reversal
-\begin_inset LatexCommand \index{Loop reversing}
+\family sans
+\series bold
+sdcclib libint.lib _divuint.rel
+\layout Standard
-\end_inset
-optimization.
-\layout List
-\labelwidthstring 00.00.0000
+\family sans
+\series bold
+sdcclib libint.lib _modsint.rel
+\layout Standard
--
-\begin_inset ERT
-status Collapsed
+\family sans
+\series bold
+sdcclib libint.lib _moduint.rel
\layout Standard
-\backslash
-/
-\end_inset
--
+\family sans
\series bold
-nolabelopt
+sdcclib libint.lib _mulint.rel
\series default
-
-\begin_inset LatexCommand \index{-\/-nolabelopt }
-\end_inset
+\newline
-Will not optimize labels (makes the dumpfiles more readable).
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+
+If the file already exists in the library, it will be replaced.
+ To see what modules and symbols are included in the library, options -s
+ and -m are available.
+ For example:
+\newline
+\newline
+\family sans
\series bold
--
-\begin_inset ERT
-status Collapsed
+sdcclib -s libint.lib
+\family default
-\layout Standard
+\begin_inset LatexCommand \index{sdcclib}
-\backslash
-/
\end_inset
--no-xinit-opt
-\begin_inset LatexCommand \index{-\/-no-xinit-opt}
-
-\end_inset
+\newline
+\family typewriter
\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
+_divsint.rel:
+\layout Standard
-Other Options
-\begin_inset LatexCommand \index{Options other}
-\end_inset
+\family typewriter
+__divsint_a_1_1
+\layout Standard
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__divsint_PARM_2
+\layout Standard
-\series bold
--c\SpecialChar ~
--
-\begin_inset ERT
-status Collapsed
+\family typewriter
+__divsint
+\newline
+_divuint.rel:
+\layout Standard
+
+\family typewriter
+__divuint_a_1_1
\layout Standard
-\backslash
-/
-\end_inset
--compile-only
-\begin_inset LatexCommand \index{-\/-compile-only}
+\family typewriter
+__divuint_PARM_2
+\layout Standard
-\end_inset
+\family typewriter
+__divuint_reste_1_1
+\layout Standard
-\begin_inset LatexCommand \index{-c -\/-compile-only}
-\end_inset
+\family typewriter
+__divuint_count_1_1
+\layout Standard
-\series default
- will compile and assemble the source, but will not call the linkage editor.
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__divuint
+\newline
+_modsint.rel:
+\layout Standard
-\series bold
--
-\series default
+\family typewriter
+__modsint_a_1_1
+\layout Standard
-\begin_inset ERT
-status Collapsed
+\family typewriter
+__modsint_PARM_2
\layout Standard
-\backslash
-/
-\end_inset
+\family typewriter
+__modsint
+\newline
+_moduint.rel:
+\layout Standard
-\series bold
--c1mode
-\begin_inset LatexCommand \index{-\/-c1mode}
-\end_inset
+\family typewriter
+__moduint_a_1_1
+\layout Standard
-\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
+\family typewriter
+__moduint_PARM_2
+\layout Standard
-\series bold
--E
-\begin_inset LatexCommand \index{-E}
+\family typewriter
+__moduint_count_1_1
+\layout Standard
-\end_inset
+
+\family typewriter
+__moduint
+\newline
+_mulint.rel:
+\layout Standard
-\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
+\family typewriter
+__mulint_PARM_2
+\layout Standard
+\family typewriter
+__mulint
+\family default
\series bold
--o\SpecialChar ~
-<path/file>
-\begin_inset LatexCommand \index{-o <path/file>}
-
-\end_inset
-
-\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
+\newline
+\layout Standard
-\series bold
--
+If the source files are compiled using -
\begin_inset ERT
-status Collapsed
+status Open
\layout Standard
/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
\end_inset
+, the corresponding debug information file .adb will be include in the library
+ file as well.
+ The library files created with sdcclib are plain text files, so they can
+ be viewed with a text editor.
+ It is not recomended to modify a library file created with sdcclib using
+ a text editor, as there are file indexes numbers located accross the file
+ used by the linker to quickly locate the required module to link.
+ Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
+ it can be safely deleted, since all the information required for linking
+ is embedded in the library file itself.
+ Library files created using sdcclib are used as described in the preceding
+ sections.
+\layout Section
-\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
+Command Line Options
+\begin_inset LatexCommand \index{Command Line Options}
-\begin_inset LatexCommand \index{reentrant}
+\end_inset
+
+
+\layout Subsection
+
+Processor Selection Options
+\begin_inset LatexCommand \index{Options processor selection}
\end_inset
-, i.e.
- the parameters and local variables will be allocated on the stack
-\begin_inset LatexCommand \index{stack}
+
+\begin_inset LatexCommand \index{Processor selection options}
\end_inset
-.
- 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
--
-\begin_inset ERT
-status Collapsed
+-mmcs51
+\begin_inset LatexCommand \index{-mmcs51}
-\layout Standard
+\end_inset
+
+
+\series default
+ Generate code for the Intel MCS51
+\begin_inset LatexCommand \index{MCS51}
-\backslash
-/
\end_inset
--xstack
-\begin_inset LatexCommand \index{-\/-xstack}
+ family of processors.
+ This is the default processor target.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mds390
+\begin_inset LatexCommand \index{-mds390}
\end_inset
\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.
+ Generate code for the Dallas DS80C390
+\begin_inset LatexCommand \index{DS80C390}
+
+\end_inset
+
+ processor.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-mds400
+\begin_inset LatexCommand \index{-mds400}
-\backslash
-/
\end_inset
--callee-saves
-\begin_inset LatexCommand \index{-\/-callee-saves}
+
+\series default
+ Generate code for the Dallas DS80C400
+\begin_inset LatexCommand \index{DS80C400}
\end_inset
+ processor.
+\layout List
+\labelwidthstring 00.00.0000
+
-\begin_inset LatexCommand \index{function prologue}
+\series bold
+-mhc08
+\begin_inset LatexCommand \index{-mhc08}
\end_inset
- function1[,function2][,function3]....
\series default
- The compiler by default uses a caller saves convention for register saving
- across function calls, however this can cause unnecessary 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 inter procedural 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 _mulint..., 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 -
-\begin_inset ERT
-status Collapsed
+ Generate code for the Freescale/Motorola HC08
+\begin_inset LatexCommand \index{HC08}
-\layout Standard
+\end_inset
+
+ family of processors.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mz80
+\begin_inset LatexCommand \index{-mz80}
-\backslash
-/
\end_inset
--callee-saves option string.
- Also see #pragma\SpecialChar ~
-CALLEE-SAVES
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+
+\series default
+ Generate code for the Zilog Z80
+\begin_inset LatexCommand \index{Z80}
\end_inset
-.
+ family of processors.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-mgbz80
+\begin_inset LatexCommand \index{-mgbz80}
-\backslash
-/
\end_inset
--debug
-\begin_inset LatexCommand \index{-\/-debug}
-\end_inset
+\series default
+ Generate code for the GameBoy Z80
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
+\end_inset
-\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.
+ processor (Not actively maintained).
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-mavr
+\begin_inset LatexCommand \index{-mavr}
-\backslash
-/
\end_inset
--peep-file
+
\series default
+ Generate code for the Atmel AVR
+\begin_inset LatexCommand \index{AVR}
-\begin_inset LatexCommand \index{-\/-peep-file}
+\end_inset
+
+ processor (In development, not complete).
+ AVR users should probably have a look at winavr
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
\end_inset
-<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.
+ or
+\begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
+
+\end_inset
+
+.
+\layout Comment
+
+I think it is fair to direct users there for now.
+ Open source is also about avoiding unnecessary work .
+ But I didn't find the 'official' link.
\layout List
\labelwidthstring 00.00.0000
\series bold
--S
-\begin_inset LatexCommand \index{-S}
+-mpic14
+\begin_inset LatexCommand \index{-mpic14}
\end_inset
-\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.
+ Generate code for the Microchip PIC 14
+\begin_inset LatexCommand \index{PIC14}
+
+\end_inset
+
+-bit processors (p16f84 and variants.
+ In development, not complete).
+\layout Comment
+
+p16f627 p16f628 p16f84 p16f873 p16f877?
\layout List
\labelwidthstring 00.00.0000
\series bold
--Wa_asmOption[,asmOption]
-\series default
+-mpic16
+\begin_inset LatexCommand \index{-mpic16}
+
+\end_inset
+
-\begin_inset LatexCommand \index{-Wa\_asmOption[,asmOption]}
+\series default
+ Generate code for the Microchip PIC 16
+\begin_inset LatexCommand \index{PIC16}
\end_inset
-...
- Pass the asmOption to the assembler.
+-bit processors (p18f452 and variants.
+ In development, not complete).
\layout List
\labelwidthstring 00.00.0000
\series bold
--Wl_linkOption[,linkOption]
+-mtlcs900h
\series default
-
-\begin_inset LatexCommand \index{-Wl\_linkOption[,linkOption]}
+ Generate code for the Toshiba TLCS-900H
+\begin_inset LatexCommand \index{TLCS-900H}
\end_inset
-...
- Pass the linkOption to the linker.
+ processor (Not maintained, not complete).
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--int-long-reent
-\begin_inset LatexCommand \index{-\/-int-long-reent}
+-mxa51
+\begin_inset LatexCommand \index{-mxa51}
\end_inset
\series 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
+ Generate code for the Phillips XA51
+\begin_inset LatexCommand \index{XA51}
+\end_inset
-\series bold
--
-\begin_inset ERT
-status Collapsed
+ processor (Not maintained, not complete).
+\layout Subsection
-\layout Standard
+Preprocessor Options
+\begin_inset LatexCommand \index{Options preprocessor}
-\backslash
-/
\end_inset
--cyclomatic
-\begin_inset LatexCommand \index{-\/-cyclomatic}
+
+\begin_inset LatexCommand \index{Preprocessor options}
\end_inset
-\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
-\begin_inset LatexCommand \index{Cyclomatic complexity}
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
\end_inset
-\emph default
- see section on Cyclomatic Complexity for more details.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--float-reent
-\begin_inset LatexCommand \index{-\/-float-reent}
+-I<path>
+\begin_inset LatexCommand \index{-I<path>}
\end_inset
-\bar under
-
\series default
-\bar default
- Floating point library is compiled as reentrant
-\begin_inset LatexCommand \index{reentrant}
+ 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
-.See section Installation for more details.
+ files.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--nooverlay
-\begin_inset LatexCommand \index{-\/-nooverlay}
+-D<macro[=value]>
+\begin_inset LatexCommand \index{-D<macro[=value]>}
\end_inset
\series default
- The compiler will not overlay parameters and local variables of any function,
- see section Parameters and local variables for more details.
+ Command line definition of macros.
+ Passed to the preprocessor.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--main-return
-\begin_inset LatexCommand \index{-\/-main-return}
+-M
+\begin_inset LatexCommand \index{-M}
\end_inset
\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'
-\begin_inset LatexCommand \index{main return}
+ 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
+\begin_inset LatexCommand \index{-E}
\end_inset
- function.
- The default option is to lock up i.e.
- generate a 'ljmp '.
+'.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--no-peep
-\begin_inset LatexCommand \index{-\/-no-peep}
+-C
+\begin_inset LatexCommand \index{-C}
\end_inset
\series default
- Disable peep-hole optimization.
+ Tell the preprocessor not to discard comments.
+ Used with the `-E' option.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-MM
+\begin_inset LatexCommand \index{-MM}
-\backslash
-/
\end_inset
--peep-asm
-\begin_inset LatexCommand \index{-\/-peep-asm}
+\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 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
-\begin_inset LatexCommand \index{Peephole optimizer}
+
+\series bold
+-Aquestion(answer)
+\begin_inset LatexCommand \index{-Aquestion(answer)}
\end_inset
- rules defined in the source file tree '<target>/peeph.def' before using
- this option.
+
+\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
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-Umacro
+\begin_inset LatexCommand \index{-Umacro}
-\backslash
-/
\end_inset
--iram-size
+
\series default
-<Value>
-\begin_inset LatexCommand \index{-\/-iram-size<Value>}
+ 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
+\begin_inset LatexCommand \index{-dM}
\end_inset
- Causes the linker to check if the internal ram usage is within limits of
- the given value.
+
+\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
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-dD
+\begin_inset LatexCommand \index{-dD}
-\backslash
-/
\end_inset
--xram-size
+
\series default
-<Value>
-\begin_inset LatexCommand \index{-\/-xram-size<Value>}
+ 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
+\begin_inset LatexCommand \index{-dN}
\end_inset
- Causes the linker to check if the external ram usage is within limits of
- the given value.
+
+\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 List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
+-Wp\SpecialChar ~
+preprocessorOption[,preprocessorOption]
+\series default
-\layout Standard
+\begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
-\backslash
-/
\end_inset
--code-size
-\series default
-<Value>
-\begin_inset LatexCommand \index{-\/-code-size<Value>}
+...
+ Pass the preprocessorOption to the preprocessor
+\family typewriter
+sdcpp
+\family default
+
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
\end_inset
- Causes the linker to check if the code usage is within limits of the given
- value.
-\layout List
-\labelwidthstring 00.00.0000
+.
+ SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
+ Collection (gcc), if you need more dedicated options please refer to the
+ documentation at
+\begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
+\end_inset
-\series bold
--
-\begin_inset ERT
-status Collapsed
+.
+\layout Subsection
-\layout Standard
+Linker Options
+\begin_inset LatexCommand \index{Options linker}
-\backslash
-/
\end_inset
--nostdincl
-\begin_inset LatexCommand \index{-\/-nostdincl}
+
+\begin_inset LatexCommand \index{Linker options}
\end_inset
-\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
+-L\SpecialChar ~
-
+\series default
+
\begin_inset ERT
status Collapsed
/
\end_inset
--nostdlib
-\begin_inset LatexCommand \index{-\/-nostdlib}
+
+\series bold
+-lib-path
+\begin_inset LatexCommand \index{-\/-lib-path <path>}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{-L -\/-lib-path}
\end_inset
\series default
- This will prevent the compiler from passing on the default library
+\SpecialChar ~
+<absolute path to additional libraries> This option is passed to the linkage
+ editor's additional libraries
\begin_inset LatexCommand \index{Libraries}
\end_inset
- path to the linker.
+ 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
/
\end_inset
--verbose
-\begin_inset LatexCommand \index{-\/-verbose}
-
-\end_inset
-
-
+-xram-loc
\series default
- Shows the various actions the compiler is performing.
-\layout List
-\labelwidthstring 00.00.0000
-
-\series bold
--V
-\begin_inset LatexCommand \index{-V}
+\begin_inset LatexCommand \index{-\/-xram-loc <Value>}
\end_inset
+\SpecialChar ~
+<Value> The start location of the external ram
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
-\series default
- Shows the actual commands the compiler is executing.
-\layout List
-\labelwidthstring 00.00.0000
-
+\end_inset
-\series bold
--
+, default value is 0.
+ The value entered can be in Hexadecimal or Decimal format, e.g.: -
\begin_inset ERT
status Collapsed
/
\end_inset
--no-c-code-in-asm
-\begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
+-xram-loc 0x8000 or -
+\begin_inset ERT
+status Collapsed
-\end_inset
+\layout Standard
+\backslash
+/
+\end_inset
-\series default
- Hides your ugly and inefficient c-code from the asm file, so you can always
- blame the compiler :).
+-xram-loc 32768.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--i-code-in-asm
-\begin_inset LatexCommand \index{-\/-i-code-in-asm}
+-code-loc
+\series default
-\end_inset
+\begin_inset LatexCommand \index{-\/-code-loc <Value>}
+\end_inset
-\series default
- Include i-codes in the asm file.
- Sounds like noise but is most helpful for debugging the compiler itself.
-\layout List
-\labelwidthstring 00.00.0000
+\SpecialChar ~
+<Value> The start location of the code
+\begin_inset LatexCommand \index{code}
+\end_inset
-\series bold
--
+ 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.: -
\begin_inset ERT
status Collapsed
/
\end_inset
--less-pedantic
-\begin_inset LatexCommand \index{-\/-less-pedantic}
+-code-loc 0x8000 or -
+\begin_inset ERT
+status Collapsed
-\end_inset
+\layout Standard
+\backslash
+/
+\end_inset
-\series default
- Disable some of the more pedantic warnings (jwk burps: please be more specific
- here, please!)
+-code-loc 32768.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--print-search-dirs
-\begin_inset LatexCommand \index{-\/-print-search-dirs}
+-stack-loc
+\series default
-\end_inset
+\begin_inset LatexCommand \index{-\/-stack-loc <Value>}
+\end_inset
-\series default
- Display the directories in the compiler's search path
-\layout List
-\labelwidthstring 00.00.0000
+\SpecialChar ~
+<Value> By default the stack
+\begin_inset LatexCommand \index{stack}
+\end_inset
-\series bold
--
+ 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.
+ -
\begin_inset ERT
status Collapsed
/
\end_inset
--vc
-\begin_inset LatexCommand \index{-\/-vc}
+-stack-loc 0x20 or -
+\begin_inset ERT
+status Collapsed
-\end_inset
-
-
-\series default
- Display errors and warnings using MSVC style, so you can use SDCC with
- visual studio
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+\backslash
+/
+\end_inset
+-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.
+ The
\series bold
-
\begin_inset ERT
/
\end_inset
--use-stderr
-\begin_inset LatexCommand \index{-\/-use-stdout}
-
-\end_inset
-
-
+-pack-iram
\series default
- Send errors and warnings to stdout instead of stderr
-\layout Subsubsection
+\SpecialChar ~
-Intermediate Dump Options
-\begin_inset LatexCommand \index{Options intermediate dump}
+\begin_inset LatexCommand \index{-\/-pack-iram}
\end_inset
+ option (which is now a default setting) will override this setting, so
+ you should also specify the
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\begin_inset LatexCommand \index{Intermediate dump options}
+\layout Standard
+\backslash
+/
\end_inset
+-no-pack-iram
+\series default
+\SpecialChar ~
-\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
-\begin_inset LatexCommand \index{iCode}
+\begin_inset LatexCommand \index{-\/-no-pack-iram}
\end_inset
-) generated by the compiler in human readable form at various stages of
- the compilation process.
-
+ option if you need to manually place the stack.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--dumpraw
-\begin_inset LatexCommand \index{-\/-dumpraw}
-
-\end_inset
-
-
+-xstack-loc
\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
-\begin_inset LatexCommand \index{Basic blocks}
+
+\begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
\end_inset
- at this stage ordered in the depth first number, so they may not be in
- sequence of execution.
-\layout List
-\labelwidthstring 00.00.0000
+\SpecialChar ~
+<Value> By default the external stack
+\begin_inset LatexCommand \index{xstack}
+\end_inset
-\series bold
--
+ is placed after the pdata segment.
+ Using this option the xstack can be placed anywhere in the external memory
+ space of the 8051.
+ The value entered can be in Hexadecimal or Decimal format, e.g.
+ -
\begin_inset ERT
status Collapsed
/
\end_inset
--dumpgcse
-\begin_inset LatexCommand \index{-\/-dumpgcse}
-
-\end_inset
-
+-xstack-loc 0x8000 or -
+\begin_inset ERT
+status Collapsed
-\series default
- Will create a dump of iCode's, after global subexpression elimination
-\begin_inset LatexCommand \index{Global subexpression elimination}
+\layout Standard
+\backslash
+/
\end_inset
-, into a file named
-\emph on
-<source filename>.dumpgcse.
+-stack-loc 32768.
+ The provided value should not overlap any other memory areas such as the
+ pdata or xdata segment and with enough space for the current application.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--dumpdeadcode
-\begin_inset LatexCommand \index{-\/-dumpdeadcode}
-
-\end_inset
-
-
+-data-loc
\series default
- Will create a dump of iCode's, after deadcode elimination
-\begin_inset LatexCommand \index{Dead-code elimination}
+
+\begin_inset LatexCommand \index{-\/-data-loc <Value>}
\end_inset
-, into a file named
-\emph on
-<source filename>.dumpdeadcode.
-\layout List
-\labelwidthstring 00.00.0000
+\SpecialChar ~
+<Value> The start location of the internal ram data
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
+\end_inset
-\series bold
--
+ segment.
+ The value entered can be in Hexadecimal or Decimal format, eg.
+ -
\begin_inset ERT
status Collapsed
/
\end_inset
--dumploop
-\begin_inset LatexCommand \index{-\/-dumploop}
+-data-loc 0x20 or -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-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 -
+\begin_inset ERT
+status Collapsed
-\series default
-\size large
-
-\size default
-Will create a dump of iCode's, after loop optimizations
-\begin_inset LatexCommand \index{Loop optimization}
+\layout Standard
+\backslash
+/
\end_inset
-, into a file named
-\emph on
-<source filename>.dumploop.
+-data-loc is not used, to location 0x10.)
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--dumprange
-\begin_inset LatexCommand \index{-\/-dumprange}
+-idata-loc
+\series default
+
+\begin_inset LatexCommand \index{-\/-idata-loc <Value>}
\end_inset
+\SpecialChar ~
+<Value> The start location of the indirectly addressable internal ram
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
-\series default
-\size large
-
-\size default
-Will create a dump of iCode's, after live range analysis
-\begin_inset LatexCommand \index{Live range analysis}
+\end_inset
+
+ of the 8051, default value is 0x80.
+ The value entered can be in Hexadecimal or Decimal format, eg.
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
-, into a file named
-\emph on
-<source filename>.dumprange.
+-idata-loc 0x88 or -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-idata-loc 136.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--dumlrange
-\begin_inset LatexCommand \index{-\/-dumlrange}
-
-\end_inset
-
-
+-bit-loc
\series default
- Will dump the life ranges
-\begin_inset LatexCommand \index{Live range analysis}
+\SpecialChar ~
+<Value> The start location of the bit
+\begin_inset LatexCommand \index{bit}
\end_inset
- for all symbols.
+ addressable internal ram of the 8051.
+ This is
+\emph on
+not
+\emph default
+ implemented yet.
+ Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
+-bBSEG=<Value>.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--dumpregassign
-\begin_inset LatexCommand \index{-\/-dumpregassign}
+-out-fmt-ihx
+\begin_inset LatexCommand \index{-\/-out-fmt-ihx}
\end_inset
\series default
\bar default
-Will create a dump of iCode's, after register assignment
-\begin_inset LatexCommand \index{Register assignment}
+The linker output (final object code) is in Intel Hex format.
+\begin_inset LatexCommand \index{Intel hex format}
\end_inset
-, into a file named
-\emph on
-<source filename>.dumprassgn.
+ This is the default option.
+ The format itself is documented in the documentation of srecord
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
+
+\end_inset
+
+.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--dumplrange
-\begin_inset LatexCommand \index{-\/-dumplrange}
+-out-fmt-s19
+\begin_inset LatexCommand \index{-\/-out-fmt-s19}
\end_inset
+\bar under
+
\series default
- Will create a dump of the live ranges of iTemp's
+\bar default
+The linker output (final object code) is in Motorola S19 format
+\begin_inset LatexCommand \index{Motorola S19 format}
+
+\end_inset
+
+.
+ The format itself is documented in the documentation of srecord.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--dumpall
-\begin_inset LatexCommand \index{-\/-dumpall}
+-out-fmt-elf
+\begin_inset LatexCommand \index{-\/-out-fmt-s19}
\end_inset
-\size large
\bar under
\series default
-\size default
\bar default
-Will cause all the above mentioned dumps to be created.
-\layout Subsection
-
-Environment variables
-\begin_inset LatexCommand \index{Environment variables}
+The linker output (final object code) is in ELF format
+\begin_inset LatexCommand \index{ELF format}
\end_inset
-
-\layout Standard
-
-SDCC recognizes the following environment variables:
+.
+ (Currently only supported for the HC08 processors)
\layout List
\labelwidthstring 00.00.0000
\series bold
-SDCC_LEAVE_SIGNALS
-\begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
+-Wl\SpecialChar ~
+linkOption[,linkOption]
+\series default
+
+\begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
\end_inset
+...
+ Pass the linkOption to the linker.
+ See file sdcc/as/doc/asxhtm.html for more on linker options.
+\layout Subsection
-\series default
- SDCC installs a signal handler
-\begin_inset LatexCommand \index{signal handler}
+MCS51 Options
+\begin_inset LatexCommand \index{Options MCS51}
\end_inset
- 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
-\begin_inset LatexCommand \index{TMP}
+\begin_inset LatexCommand \index{MCS51 options}
\end_inset
-,\SpecialChar ~
-TEMP
-\begin_inset LatexCommand \index{TEMP}
-\end_inset
+\layout List
+\labelwidthstring 00.00.0000
-,\SpecialChar ~
-TMPDIR
-\begin_inset LatexCommand \index{TMPDIR}
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-small
+\begin_inset LatexCommand \index{-\/-model-small}
\end_inset
\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.
+\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 List
\labelwidthstring 00.00.0000
\series bold
-SDCC_HOME
-\begin_inset LatexCommand \index{SDCC\_HOME}
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-model-medium
+\begin_inset LatexCommand \index{-\/-model-medium}
-\series default
- Path, see
-\begin_inset Quotes sld
\end_inset
-2.3 Install and search paths
-\begin_inset Quotes srd
-\end_inset
-.
+\series default
+ Generate code for Medium model programs, see section Memory Models for
+ more details.
+ If this option is used all source files in the project have to be compiled
+ with this option.
+ It must also be used when invoking the linker.
\layout List
\labelwidthstring 00.00.0000
\series bold
-SDCC_INCLUDE
-\begin_inset LatexCommand \index{SDCC\_INCLUDE}
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-model-large
+\begin_inset LatexCommand \index{-\/-model-large}
-\series default
- Path, see
-\begin_inset Quotes sld
\end_inset
-2.3 Install and search paths
-\begin_inset Quotes srd
-\end_inset
-.
+\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 have to be compiled
+ with this option.
+ It must also be used when invoking the linker.
\layout List
\labelwidthstring 00.00.0000
\series bold
-SDCC_LIB
-\begin_inset LatexCommand \index{SDCC\_LIB}
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-xstack
+\begin_inset LatexCommand \index{-\/-xstack}
-\series default
- Path, see
-\begin_inset Quotes sld
\end_inset
-2.3 Install and search paths
-\begin_inset Quotes srd
-\end_inset
-.
-\layout Standard
+\series default
+ Uses a pseudo stack in the first 256 bytes in the external ram for allocating
+ variables and passing parameters.
+ See section
+\begin_inset LatexCommand \ref{sub:External-Stack}
-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 documented.
-\layout Subsection
+\end_inset
-MCS51/DS390 Storage Class
-\begin_inset LatexCommand \index{Storage class}
+\SpecialChar ~
+ External Stack for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
- Language Extensions
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-In addition to the ANSI storage classes SDCC allows the following MCS51
- specific storage classes.
-\layout Subsubsection
+\backslash
+/
+\end_inset
-xdata
-\begin_inset LatexCommand \index{xdata}
+-iram-size
+\series default
+\SpecialChar ~
+<Value>
+\begin_inset LatexCommand \index{-\/-iram-size <Value>}
\end_inset
+ Causes the linker to check if the internal ram usage is within limits of
+ the given value.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-Variables declared with this storage class will be placed in the external
- RAM.
- This is the
\series bold
-default
-\series default
- storage class for Large Memory model, e.g.:
-\layout Verse
+-
+\begin_inset ERT
+status Collapsed
+\layout Standard
-\family typewriter
-xdata unsigned char xduc;
-\layout Subsubsection
+\backslash
+/
+\end_inset
-data
-\begin_inset LatexCommand \index{data}
+-xram-size
+\series default
+\SpecialChar ~
+<Value>
+\begin_inset LatexCommand \index{-\/-xram-size <Value>}
\end_inset
+ Causes the linker to check if the external ram usage is within limits of
+ the given value.
+\layout List
+\labelwidthstring 00.00.0000
-\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 directly
- addressable portion of the internal RAM of a 8051, e.g.:
-\layout Verse
+-
+\begin_inset ERT
+status Collapsed
+\layout Standard
-\family typewriter
-data int iramdata;
-\layout Subsubsection
+\backslash
+/
+\end_inset
-idata
-\begin_inset LatexCommand \index{idata}
+-code-size
+\series default
+\SpecialChar ~
+<Value>
+\begin_inset LatexCommand \index{-\/-code-size <Value>}
\end_inset
+ Causes the linker to check if the code memory usage is within limits of
+ the given value.
+\layout List
+\labelwidthstring 00.00.0000
-\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.:
-\layout Verse
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+\layout Standard
-\family typewriter
-idata int idi;
-\layout Subsubsection
+\backslash
+/
+\end_inset
-bit
-\begin_inset LatexCommand \index{bit}
+-stack-size
+\series default
+\SpecialChar ~
+<Value>
+\begin_inset LatexCommand \index{-\/-stack-size <Value>}
\end_inset
+ Causes the linker to check if there is at minimum <Value> bytes for stack.
+\layout List
+\labelwidthstring 00.00.0000
-\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.:
-\layout Verse
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+\layout Standard
-\family typewriter
-bit iFlag;
-\layout Subsubsection
+\backslash
+/
+\end_inset
-sfr
-\begin_inset LatexCommand \index{sfr}
+-pack-iram
+\series default
+\SpecialChar ~
+
+\begin_inset LatexCommand \index{-\/-pack-iram}
\end_inset
- / sbit
-\begin_inset LatexCommand \index{sbit}
+ Causes the linker to use unused register banks for data variables and pack
+ data, idata and stack together.
+ This is the default now.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\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:
-\layout Verse
+\backslash
+/
+\end_inset
+-no-pack-iram
+\series default
+\SpecialChar ~
-\family typewriter
-sfr at
-\begin_inset LatexCommand \index{at}
+\begin_inset LatexCommand \index{-\/-no-pack-iram}
\end_inset
- 0x80 P0; /* special function register P0 at location 0x80 */
-\newline
-sbit at 0xd7 CY; /* CY (Carry Flag
-\begin_inset LatexCommand \index{Flags}
+ Causes the linker to use old style for allocating memory areas.
+\layout Subsection
+
+DS390 / DS400 Options
+\begin_inset LatexCommand \index{Options DS390}
\end_inset
-\begin_inset LatexCommand \index{Carry flag}
+\begin_inset LatexCommand \index{DS390 options}
\end_inset
-) */
-\layout Subsection
-Pointers
-\begin_inset LatexCommand \index{Pointers}
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-SDCC allows (via language extensions) pointers to explicitly point to any
- of the memory spaces
-\begin_inset LatexCommand \index{Memory model}
-
+\backslash
+/
\end_inset
- 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
+-model-flat24
+\series default
-\newline
-Pointer declaration examples:
-\layout Verse
-
-
-\family typewriter
-/* 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
+\begin_inset LatexCommand \index{-\/-model-flat24}
-\newline
-/* the following is a generic pointer physically located in xdata space
- */
-\newline
-char * xdata p;
-\layout Standard
+\end_inset
-Well you get the idea.
-
-\newline
-\newline
-All unqualified pointers are treated as 3-byte (4-byte for the ds390)
+\size large
\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
+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
-generic
+-mds390
\emph default
- pointers.
- These are useful for developing reusable library
-\begin_inset LatexCommand \index{Libraries}
+.
+ See section Memory Models for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
- routines.
- Explicitly specifying the pointer type will generate the most efficient
- code.
-\layout Subsection
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-Parameters
-\begin_inset LatexCommand \index{Parameters}
+\layout Standard
+\backslash
+/
\end_inset
- & Local Variables
-\begin_inset LatexCommand \index{Local variable}
+-protect-sp-update
+\begin_inset LatexCommand \index{-\/-protect-sp-update}
\end_inset
-\layout Standard
-
-Automatic (local) variables and parameters to functions can either be placed
- on the stack or in data-space.
- The default action of the compiler is to place these variables in the internal
- RAM (for small model) or external RAM (for large model).
- This in fact makes them
-\emph on
-static
-\begin_inset LatexCommand \index{static}
+\series default
+ disable interrupts during ESP:SP updates.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\emph default
- so by default functions are non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+\layout Standard
+\backslash
+/
\end_inset
-.
-\newline
+-stack-10bit
+\series default
-\newline
-They can be placed on the stack
-\begin_inset LatexCommand \index{stack}
+\begin_inset LatexCommand \index{-\/-stack-10bit}
\end_inset
- either by using the
+ 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
+-
\begin_inset ERT
status Collapsed
\emph default
- option or by using the
+ option, but that has not been tested.
+ It is incompatible with the
\emph on
-reentrant
-\begin_inset LatexCommand \index{reentrant}
+-
+\begin_inset ERT
+status Collapsed
-\end_inset
+\layout Standard
+\backslash
+/
+\end_inset
-\emph default
- keyword in the function declaration, e.g.:
-\layout Verse
+-xstack
+\begin_inset LatexCommand \index{-\/-xstack}
+\end_inset
-\family typewriter
-unsigned char foo(char i) reentrant
-\newline
-{
-\newline
-...
-
-\newline
-}
-\layout Standard
-Since stack space on 8051 is limited, the
-\emph on
-reentrant
\emph default
-keyword or the
+ option.
+ It also only makes sense if the processor is in 24 bit contiguous addressing
+ mode (see the
\emph on
- -
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--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
+-model-flat24 option
\emph default
- mean that the function is register bank independent.
-\newline
-
-\newline
-Local variables can be assigned storage classes and absolute
-\begin_inset LatexCommand \index{Absolute addressing}
-
-\end_inset
-
- addresses, e.g.:
-\layout Verse
-
+).
+\layout List
+\labelwidthstring 00.00.0000
-\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 unsigned char j;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
-\layout Standard
-In the above example the variable
-\emph on
-i
-\emph default
- will be allocated in the external ram,
-\emph on
-bvar
-\emph default
- in bit addressable space and
-\emph on
- j
-\emph default
- in internal ram.
- When compiled with
-\emph on
+\series bold
-
\begin_inset ERT
status Collapsed
/
\end_inset
--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
+-stack-probe
+\begin_inset LatexCommand \index{-\/-stack-probe}
-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
+\end_inset
-Overlaying
-\begin_inset LatexCommand \index{Overlaying}
-\end_inset
+\series default
+ insert call to function __stack_probe at each function prologue.
+\layout List
+\labelwidthstring 00.00.0000
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-For non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+\backslash
+/
+\end_inset
+
+-tini-libid
+\begin_inset LatexCommand \index{-\/-tini-libid}
\end_inset
- 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
-\begin_inset LatexCommand \index{Memory model}
-
-\end_inset
- is small.
+\series default
+ <nnnn> LibraryID used in -mTININative.
+
+\layout List
+\labelwidthstring 00.00.0000
-\emph default
- If an explicit storage class
-\begin_inset LatexCommand \index{Storage class}
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
- 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
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
-
+\backslash
+/
\end_inset
- if they are not reentrant.
-\layout Standard
-
-Also note that the compiler does not do any processing of inline
-\begin_inset LatexCommand \index{inline}
+-use-accelerator
+\begin_inset LatexCommand \index{-\/-use-accelerator}
\end_inset
- 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
-\begin_inset LatexCommand \index{Multiplication}
+\series default
+ generate code for DS390 Arithmetic Accelerator.
+
+\layout Subsection
+
+Z80 Options
+\begin_inset LatexCommand \index{Options Z80}
\end_inset
- or division
-\begin_inset LatexCommand \index{Division}
-\end_inset
+\begin_inset LatexCommand \index{Z80 options}
- will NOT be overlayed since these are implemented using external functions,
- e.g.:
-\layout Verse
+\end_inset
-\family typewriter
-#pragma SAVE
-\newline
-#pragma NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
-
-\newline
-void set_error(unsigned char errcd)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-P3 = errcd;
-\newline
-}
-\newline
-#pragma RESTORE
-\newline
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\newline
-void some_isr () interrupt
-\begin_inset LatexCommand \index{interrupt}
+\layout Standard
+\backslash
+/
\end_inset
- 2 using
-\begin_inset LatexCommand \index{using}
+-callee-saves-bc
+\series default
+
+\begin_inset LatexCommand \index{-\/-callee-saves-bc}
\end_inset
- 1
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-set_error(10);
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
-\layout Standard
-In the above example the parameter
-\emph on
-errcd
-\emph default
- for the function
+\size large
\emph on
-set_error
+
+\size default
\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
+Force a called function to always save BC.
+\layout List
+\labelwidthstring 00.00.0000
-SDCC allows interrupt service routines to be coded in C, with some extended
- keywords.
-\layout Verse
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\family typewriter
-void timer_isr (void) interrupt 1 using 1
-\newline
-{
-\newline
-..
-
-\newline
-}
\layout Standard
-The optional number following the
-\emph on
-interrupt
-\begin_inset LatexCommand \index{interrupt}
-
+\backslash
+/
\end_inset
+-no-std-crt0
+\series default
-\emph default
- keyword is the interrupt number this routine will service.
- When present, 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 can be 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
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+\begin_inset LatexCommand \index{-\/-no-std-crt0}
\end_inset
- if it is not reentrant.
- Furthermore nonreentrant functions should not be called from the main program
- while the interrupt service routine might be active.
- If the interrupt service routines changes variables which are accessed
- by other functions these variables should be declared
-\emph on
-volatile
-\emph default
+ When linking, skip the standard crt0.o object file.
+ You must provide your own crt0.o for your system when linking.
+
+\layout Subsection
-\begin_inset LatexCommand \index{volatile}
+Optimization Options
+\begin_inset LatexCommand \index{Options optimization}
\end_inset
-.
-
-\layout Standard
-A special note here, int (16 bit) and long (32 bit) integer division
-\begin_inset LatexCommand \index{Division}
+\begin_inset LatexCommand \index{Optimization options}
\end_inset
-, multiplication
-\begin_inset LatexCommand \index{Multiplication}
-
-\end_inset
- & modulus
-\begin_inset LatexCommand \index{Modulus}
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
- 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
- -
+\series bold
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+-nogcse
+\begin_inset LatexCommand \index{-\/-nogcse}
\end_inset
+\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 (
+\emph on
+s
\emph default
- option and the source file will need to be compiled using the
+pill
\emph on
+loc
+\emph default
+ations, sloc
+\begin_inset LatexCommand \index{sloc (spill location)}
+
+\end_inset
+
+).
+ A warning message will be generated when this happens and the compiler
+ will indicate the number of extra bytes it allocated.
+ It is recommended that this option NOT be used, #pragma\SpecialChar ~
+nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
+
+\end_inset
+
+ can be used to turn off global subexpression elimination
+\begin_inset LatexCommand \index{Subexpression elimination}
+
+\end_inset
+
+ for a given function only.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
-
\begin_inset ERT
status Collapsed
/
\end_inset
--int-long-ren
-\emph default
-t
-\begin_inset LatexCommand \index{-\/-int-long-rent}
+-noinvariant
+\begin_inset LatexCommand \index{-\/-noinvariant}
\end_inset
- 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
+\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 Loop Invariants in
+ section
+\begin_inset LatexCommand \ref{sub:Loop-Optimizations}
+
+\end_inset
+
.
-\layout Standard
+ It is recommended that this option NOT be used, #pragma\SpecialChar ~
+noinvariant
+\begin_inset LatexCommand \index{\#pragma noinvariant}
-Interrupt numbers and the corresponding address & descriptions for the Standard
- 8051/8052 are listed below.
- SDCC will automatically adjust the interrupt vector table to the maximum
- interrupt number specified.
-\newline
+\end_inset
+
+ can be used to turn off invariant optimizations for a given function only.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="7" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0in">
-<column alignment="center" valignment="top" leftline="true" width="0in">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\backslash
+/
+\end_inset
-\layout Standard
+-noinduction
+\begin_inset LatexCommand \index{-\/-noinduction}
-Interrupt #
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Description
+\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 ~
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ can be used to turn off induction optimizations for a given function only.
+\layout List
+\labelwidthstring 00.00.0000
-Vector Address
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-0
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-nojtbound
+\begin_inset LatexCommand \index{-\/-nojtbound}
-External 0
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-0x0003
+\size large
+\bar under
+
+\series default
+\size default
+\bar default
+ Will not generate boundary condition check when switch statements
+\begin_inset LatexCommand \index{switch statement}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ are implemented using jump-tables.
+ See section
+\begin_inset LatexCommand \ref{sub:'switch'-Statements}
-1
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\SpecialChar ~
+Switch Statements for more details.
+ It is recommended that this option is NOT used, #pragma\SpecialChar ~
+nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
-Timer 0
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ can be used to turn off boundary checking for jump tables for a given function
+ only.
+\layout List
+\labelwidthstring 00.00.0000
-0x000B
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-2
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-noloopreverse
+\begin_inset LatexCommand \index{-\/-noloopreverse}
-External 1
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-0x0013
+\series default
+\size large
+
+\size default
+Will not do loop reversal
+\begin_inset LatexCommand \index{Loop reversing}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+optimization.
+\layout List
+\labelwidthstring 00.00.0000
-3
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Timer 1
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-
+\series bold
+nolabelopt
+\series default
+
+\begin_inset LatexCommand \index{-\/-nolabelopt }
-0x001B
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+Will not optimize labels (makes the dumpfiles more readable).
+\layout List
+\labelwidthstring 00.00.0000
-4
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Serial
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-no-xinit-opt
+\begin_inset LatexCommand \index{-\/-no-xinit-opt}
-0x0023
\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
-5
+\series default
+ Will not memcpy initialized data from code space into xdata space.
+ This saves a few bytes in code space if you don't have initialized data
+\begin_inset LatexCommand \index{Variable initialization}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+\layout List
+\labelwidthstring 00.00.0000
-Timer 2 (8052)
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-0x002B
+\backslash
+/
\end_inset
-</cell>
-</row>
-</lyxtabular>
+
+-nooverlay
+\begin_inset LatexCommand \index{-\/-nooverlay}
\end_inset
-\newline
+\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
-\layout Standard
-If the interrupt service routine is defined without
-\emph on
-using
-\begin_inset LatexCommand \index{using}
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-no-peep
+\begin_inset LatexCommand \index{-\/-no-peep}
-\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
+\end_inset
-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
+\series default
+ Disable peep-hole optimization with built-in rules.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-Also see the _naked modifier.
-\layout Subsection
-Critical Functions
-\layout Standard
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+\layout Standard
-\shape italic
-<TODO: this isn't implemented at all!>
-\shape default
+\backslash
+/
+\end_inset
-\newline
+-peep-file
+\series default
-\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.
-\layout Verse
+\begin_inset LatexCommand \index{-\/-peep-file}
+\end_inset
+
+\SpecialChar ~
+<filename> This option can be used to use additional rules to be used by
+ the peep hole optimizer.
+ See section
+\begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
+
+\end_inset
+
+\SpecialChar ~
+Peep Hole optimizations for details on how to write these rules.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\family typewriter
-int foo () critical
-\newline
-{
-\newline
-...
-
-\newline
-...
-
-\newline
-}
\layout Standard
-The critical attribute maybe used with other attributes like
-\emph on
-reentrant.
-\layout Subsection
+\backslash
+/
+\end_inset
+
+-peep-asm
+\begin_inset LatexCommand \index{-\/-peep-asm}
+
+\end_inset
-Naked Functions
-\begin_inset LatexCommand \index{Naked functions}
+
+\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
+\begin_inset LatexCommand \index{Peephole optimizer}
\end_inset
+ rules defined in the source file tree '<target>/peeph.def' before using
+ this option.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-A special keyword may be associated with a function declaring it as
-\emph on
-_naked
-\begin_inset LatexCommand \index{\_naked}
+\backslash
+/
+\end_inset
+
+-opt-code-speed
+\begin_inset LatexCommand \index{-\/-opt-code-speed}
\end_inset
-.
-
-\emph default
-The
-\emph on
-_naked
-\emph default
- function modifier attribute prevents the compiler from generating prologue
-\begin_inset LatexCommand \index{function prologue}
+\series default
+ The compiler will optimize code generation towards fast code, possibly
+ at the expense of code size.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
\end_inset
- and epilogue
-\begin_inset LatexCommand \index{function epilogue}
+-opt-code-size
+\begin_inset LatexCommand \index{-\/-opt-code-size}
\end_inset
- 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:
-\layout Verse
+\series default
+ The compiler will optimize code generation towards compact code, possibly
+ at the expense of code speed.
+\layout Subsection
+
+Other Options
+\begin_inset LatexCommand \index{Options other}
-\family typewriter
-volatile
-\begin_inset LatexCommand \index{volatile}
+\end_inset
+
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-c\SpecialChar ~
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- data unsigned char counter;
-\newline
-void simpleInterrupt(void) interrupt
-\begin_inset LatexCommand \index{interrupt}
+-compile-only
+\begin_inset LatexCommand \index{-\/-compile-only}
\end_inset
- 1
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-counter++;
-\newline
-}
-\newline
-\newline
-void nakedInterrupt(void) interrupt 2 _naked
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_asm
-\begin_inset LatexCommand \index{\_asm}
+\begin_inset LatexCommand \index{-c -\/-compile-only}
\end_inset
-\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 or reti in _naked function.
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_endasm
-\begin_inset LatexCommand \index{\_endasm}
+\series default
+ will compile and assemble the source, but will not call the linkage editor.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
-;
-\newline
-}
+\series bold
+-
+\series default
+
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-For an 8051 target, the generated simpleInterrupt looks like:
-\layout Verse
+\backslash
+/
+\end_inset
-\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
-\layout Standard
+\series bold
+-c1mode
+\begin_inset LatexCommand \index{-\/-c1mode}
-whereas nakedInterrupt looks like:
-\layout Verse
+\end_inset
-\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.
-\layout Standard
+\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
-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
-\begin_inset LatexCommand \index{bank}
+\series bold
+-E
+\begin_inset LatexCommand \index{-E}
\end_inset
-\layout Standard
+\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
-The
-\emph on
-using
-\begin_inset LatexCommand \index{using}
+
+\series bold
+-o\SpecialChar ~
+<path/file>
+\begin_inset LatexCommand \index{-o <path/file>}
\end_inset
+
+\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
+
-\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
-\begin_inset LatexCommand \index{interrupt}
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
-\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
+\series default
+\size large
\emph on
-using
+
+\size default
\emph default
- attribute will have no effect on the generated code for a
+All functions in the source file will be compiled as
\emph on
-non-interrupt
+reentrant
\emph default
- function (but may occasionally be useful anyway
-\begin_inset Foot
-collapsed false
-\layout Standard
+\begin_inset LatexCommand \index{reentrant}
-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
+, i.e.
+ the parameters and local variables will be allocated on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+.
+ See section
+\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+ Parameters and Local Variables for more details.
+ If this option is used all source files in the project should be compiled
+ with this option.
+ It automatically implies --int-long-reent and --float-reent.
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\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
-\begin_inset LatexCommand \index{interrupt priority}
+\backslash
+/
+\end_inset
+
+-callee-saves
+\begin_inset LatexCommand \index{-\/-callee-saves}
\end_inset
- 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
+ function1[,function2][,function3]....
-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
+\series default
+ The compiler by default uses a caller saves convention for register saving
+ across function calls, however this can cause unnecessary 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 (function prologue
+\series bold
-Absolute Addressing
-\begin_inset LatexCommand \index{Absolute addressing}
+\begin_inset LatexCommand \index{function prologue}
\end_inset
-\layout Standard
+\series default
+ & epilogue
+\series bold
-Data items can be assigned an absolute address with the
-\emph on
-at
-\begin_inset LatexCommand \index{at}
+\begin_inset LatexCommand \index{function epilogue}
\end_inset
- <address>
-\emph default
- keyword, in addition to a storage class, e.g.:
-\layout Verse
+\series default
+) 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 inter procedural 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 _mulint..., 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 -
+\begin_inset ERT
+status Collapsed
-\family typewriter
-xdata
-\begin_inset LatexCommand \index{xdata}
+\layout Standard
+\backslash
+/
\end_inset
- at
-\begin_inset LatexCommand \index{at}
+-callee-saves option string.
+ Also see #pragma\SpecialChar ~
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
\end_inset
- 0x7ffe unsigned int chksum;
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-In the above example the variable chksum will located at 0x7ffe and 0x7fff
- of the external ram.
- 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
-\begin_inset LatexCommand \index{.lst}
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
\end_inset
-) and the linker output files (.rst
-\begin_inset LatexCommand \index{.rst}
+
+\bar under
+
+\series default
+\bar default
+When this option is used the compiler will generate debug information.
+ The debug information collected in a file with .cdb extension can be used
+ with the SDCDB.
+ For more information see documentation for SDCDB.
+ Another file with no extension contains debug information in AOMF or AOMF51
+\begin_inset LatexCommand \index{AOMF, AOMF51}
\end_inset
-) and (.map
-\begin_inset LatexCommand \index{.map}
+ format which is commonly used by third party tools.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-S
+\begin_inset LatexCommand \index{-S}
\end_inset
-) are good places to look for such overlaps.
+
+\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
+-
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-In case of memory mapped I/O devices the keyword
+\backslash
+/
+\end_inset
+
+-int-long-reent
+\begin_inset LatexCommand \index{-\/-int-long-reent}
+
+\end_inset
+
+
+\series 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
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-cyclomatic
+\begin_inset LatexCommand \index{-\/-cyclomatic}
+
+\end_inset
+
+
+\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
-volatile
+important
\emph default
- should be used to tell the compiler that accesses might not be optimized
- away:
-\layout Verse
+ 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
+\begin_inset LatexCommand \index{Cyclomatic complexity}
+
+\end_inset
-\family typewriter
-volatile
-\begin_inset LatexCommand \index{volatile}
+\emph default
+ see section on Cyclomatic Complexity for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- xdata
-\begin_inset LatexCommand \index{xdata}
+-float-reent
+\begin_inset LatexCommand \index{-\/-float-reent}
\end_inset
- at
-\begin_inset LatexCommand \index{at}
+
+\series default
+ Floating point library is compiled as reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
- 0x8000 unsigned char PORTA_8255;
-\layout Standard
+.
+ See section Installation for more details.
+\layout List
+\labelwidthstring 00.00.0000
-Absolute address can be specified for variables in all storage classes,
- e.g.:
-\layout Verse
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\family typewriter
-bit
-\begin_inset LatexCommand \index{bit}
+\layout Standard
+\backslash
+/
\end_inset
- at
-\begin_inset LatexCommand \index{at}
+-main-return
+\begin_inset LatexCommand \index{-\/-main-return}
\end_inset
- 0x02 bvar;
-\layout Standard
-The above example will allocate the variable at offset 0x02 in the bit-addressab
-le space.
- There is no real advantage to assigning absolute addresses to variables
- in this manner, unless you want strict control over all the variables allocated.
- One possible use would be to write hardware portable code.
- For example, if you have a routine that uses one or more of the microcontroller
- I/O pins, and such pins are different for two different hardwares, you
- can declare the I/O pins in you routine using
-\layout Verse
+\series default
+ This option can be used if the code generated is called by a monitor program
+ or if the main routine includes an endless loop.
+ This option might result in slightly smaller code and save two bytes of
+ stack space.
+ The return from the 'main'
+\begin_inset LatexCommand \index{main return}
+\end_inset
+ function will return to the function calling main.
+ The default setting is to lock up i.e.
+ generate a '
\family typewriter
-extern bit SDI;
-\newline
-extern bit SCLK;
-\newline
-extern bit CPOL;
-\newline
+sjmp .
+\family default
+'.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-void DS1306_put(unsigned char value)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-unsigned char mask=0x80;
-\newline
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-while(mask)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SDI=(value & mask)?1:0;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SCLK=!CPOL;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SCLK=CPOL;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mask/=2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-}
-\newline
-}
-\layout Standard
-
-Then, someplace in the code for the first hardware you would use
-\layout Verse
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\family typewriter
-bit at 0x80 SDI;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/*I/O port 0, bit 0*/
-\newline
-bit at 0x81 SCLK;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/*I/O port 0, bit 1*/
-\newline
-bit CPOL;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/*This is a variable, let the linker allocate this one*/
\layout Standard
-Similarly, for the second hardware you would use
-\layout Verse
+\backslash
+/
+\end_inset
+-nostdinc
+\begin_inset LatexCommand \index{-\/-nostdinc}
-\family typewriter
-bit at 0x83 SDI;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/*I/O port 0, bit 3*/
-\newline
-bit at 0x91 SCLK;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/*I/O port 1, bit 1*/
-\newline
-bit CPOL;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/*This is a variable, let the linker allocate this one*/
-\layout Standard
+\end_inset
-and you can use the same hardware dependent routine without changes, as
- for example in a library.
- This is somehow similar to sbit, but only one absolute address has to be
- specified in the whole project.
-\layout Subsection
-Startup Code
-\begin_inset LatexCommand \index{Startup code}
+\series default
+ This will prevent the compiler from passing on the default include path
+ to the preprocessor.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-The compiler inserts a call to the C routine
-\emph on
-_sdcc_external_startup()
-\begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
-
+\backslash
+/
\end_inset
-
-\series bold
-\emph default
-
-\series default
-at the start of the CODE area.
- This routine is in the runtime library
-\begin_inset LatexCommand \index{Runtime library}
+-nostdlib
+\begin_inset LatexCommand \index{-\/-nostdlib}
\end_inset
-.
- 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
-\begin_inset LatexCommand \index{Assembler routines}
+\series default
+ This will prevent the compiler from passing on the default library
+\begin_inset LatexCommand \index{Libraries}
\end_inset
+ path to the linker.
+\layout List
+\labelwidthstring 00.00.0000
-\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
+\series bold
-
\begin_inset ERT
status Collapsed
/
\end_inset
--peep-asm
-\begin_inset LatexCommand \index{-\/-peep-asm}
+-verbose
+\begin_inset LatexCommand \index{-\/-verbose}
\end_inset
-\emph default
- command line option is used, the inline assembler code will be passed through
- the peephole optimizer
-\begin_inset LatexCommand \index{Peephole optimizer}
+\series default
+ Shows the various actions the compiler is performing.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
-.
- This might cause some unexpected changes in the inline assembler code.
- Please go through the peephole optimizer rules defined in file
-\emph on
-SDCCpeeph.def
-\emph default
- carefully before using this option.
-\layout Verse
+\series bold
+-V
+\begin_inset LatexCommand \index{-V}
+\end_inset
-\family typewriter
-_asm
-\begin_inset LatexCommand \index{\_asm}
-\end_inset
+\series default
+ Shows the actual commands the compiler is executing.
+\layout List
+\labelwidthstring 00.00.0000
-
-\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
-\begin_inset LatexCommand \index{\_endasm}
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
- ;
\layout Standard
-The inline assembler code can contain any valid code understood by the assembler
-, this includes any assembler directives and comment lines.
- The compiler does not do any validation of the code within the
-\family typewriter
-_asm ...
- _endasm;
-\family default
- keyword pair.
-
-\newline
+\backslash
+/
+\end_inset
-\newline
-Inline assembler code cannot reference any C-Labels, however it can reference
- labels
-\begin_inset LatexCommand \index{Labels}
+-no-c-code-in-asm
+\begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
\end_inset
- defined by the inline assembler, e.g.:
-\layout Verse
-
-\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
-}
-\layout Standard
+\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
-In other words inline assembly code can access labels defined in inline
- assembly within the scope of the function.
- The same goes the other way, ie.
- labels defines in inline assembly CANNOT be accessed by C statements.
-\layout Subsection
-int (16 bit)
-\begin_inset LatexCommand \index{int (16 bit)}
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+\layout Standard
+
+\backslash
+/
\end_inset
- and long (32 bit)
-\begin_inset LatexCommand \index{long (32 bit)}
+-no-peep-comments
+\begin_inset LatexCommand \index{-\/-no-peep-comments}
\end_inset
- 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 optimizations are
- used.
- The following files contain the described routine, all of them can be found
- in <installdir>/share/sdcc/lib.
-\newline
+\series default
+ Will not include peep-hole comments in the generated files.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="11" columns="2">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
+\backslash
+/
+\end_inset
+
+-i-code-in-asm
+\begin_inset LatexCommand \index{-\/-i-code-in-asm}
-\series bold
-Function
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+
+\series default
+ Include i-codes in the asm file.
+ Sounds like noise but is most helpful for debugging the compiler itself.
+\layout List
+\labelwidthstring 00.00.0000
\series bold
-Description
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-_mulint.c
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-less-pedantic
+\begin_inset LatexCommand \index{-\/-less-pedantic}
-16 bit multiplication
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-_divsint.c
+\series default
+ Disable some of the more pedantic warnings
+\begin_inset LatexCommand \index{Warnings}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ (jwk burps: please be more specific here, please!).
+\layout List
+\labelwidthstring 00.00.0000
- signed 16 bit division (calls _divuint)
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-_divuint.c
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-disable-warning\SpecialChar ~
+<nnnn>
+\begin_inset LatexCommand \index{-\/-disable-warning}
- unsigned 16 bit division
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-_modsint.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\series default
+ Disable specific warning with number <nnnn>.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-signed 16 bit modulus (calls _moduint)
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-_moduint.c
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-print-search-dirs
+\begin_inset LatexCommand \index{-\/-print-search-dirs}
-unsigned 16 bit modulus
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-_mullong.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\series default
+ Display the directories in the compiler's search path
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-32 bit multiplication
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-_divslong.c
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-vc
+\begin_inset LatexCommand \index{-\/-vc}
- signed 32 division (calls _divulong)
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-_divulong.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\series default
+ Display errors and warnings using MSVC style, so you can use SDCC with
+ visual studio.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-unsigned 32 division
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-_modslong.c
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-use-stdout
+\begin_inset LatexCommand \index{-\/-use-stdout}
- signed 32 bit modulus (calls _modulong)
\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
-_modulong.c
+\series default
+ Send errors and warnings to stdout instead of stderr.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-Wa\SpecialChar ~
+asmOption[,asmOption]
+\series default
+
+\begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+...
+ Pass the asmOption to the assembler
+\begin_inset LatexCommand \index{Options assembler}
-unsigned 32 bit modulus
\end_inset
-</cell>
-</row>
-</lyxtabular>
+
+
+\begin_inset LatexCommand \index{Assembler options}
\end_inset
+.
+ See file sdcc/as/doc/asxhtm.html for assembler options.cd
+\layout List
+\labelwidthstring 00.00.0000
-\newline
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Since they are compiled as
-\emph on
-non-reentrant
-\emph default
+\backslash
+/
+\end_inset
-\begin_inset LatexCommand \index{reentrant}
+-std-sdcc89
+\begin_inset LatexCommand \index{-\/-std-sdcc89}
\end_inset
-, interrupt
-\begin_inset LatexCommand \index{interrupt}
-\end_inset
+\series default
+ Generally follow the C89 standard, but allow SDCC features that conflict
+ with the standard (default).
+\layout List
+\labelwidthstring 00.00.0000
- 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
+
+\series bold
-
\begin_inset ERT
status Collapsed
/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+-std-c89
+\begin_inset LatexCommand \index{-\/-std-c89}
\end_inset
-\emph default
- option, after which the source program will have to be compiled with
-\emph on
+\series default
+ Follow the C89 standard and disable SDCC features that conflict with the
+ standard.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
-
\begin_inset ERT
status Collapsed
/
\end_inset
--int-long-rent
-\begin_inset LatexCommand \index{-\/-int-long-rent}
+-std-sdcc99
+\begin_inset LatexCommand \index{-\/-std-sdcc99}
\end_inset
-\emph default
- option.
- Notice that you don't have to call this routines directly.
- The compiler will use them automatically every time a integer operation
- is required.
-\layout Subsection
-
-Floating Point Support
-\begin_inset LatexCommand \index{Floating point support}
+\series default
+ Generally follow the C99 standard, but allow SDCC features that conflict
+ with the standard (incomplete support).
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
- floating point support routines are derived from gcc's floatlib.c and consists
- of the following routines:
-\newline
+\backslash
+/
+\end_inset
-\layout Standard
-\align center
+-std-c99
+\begin_inset LatexCommand \index{-\/-std-sdcc99}
-\size footnotesize
+\end_inset
-\begin_inset Tabular
-<lyxtabular version="3" rows="17" columns="2">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\series default
+ Follow the C99 standard and disable SDCC features that conflict with the
+ standard (incomplete support).
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-Function
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Description
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-codeseg
+\series default
+\begin_inset LatexCommand \index{-\/-codeseg <Value>}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fsadd.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+\SpecialChar ~
+<Name> The name to be used for the code
+\begin_inset LatexCommand \index{code}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-add floating point numbers
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ segment, default CSEG.
+ This is useful if you need to tell the compiler to put the code in a special
+ segment so you can later on tell the linker to put this segment in a special
+ place in memory.
+ Can be used for instance when using bank switching to put the code in a
+ bank.
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fssub.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-subtract floating point numbers
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-constseg
+\series default
+\begin_inset LatexCommand \index{-\/-constseg <Value>}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fsdiv.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\SpecialChar ~
+<Name> The name to be used for the const
+\begin_inset LatexCommand \index{code}
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-divide floating point numbers
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ segment, default CONST.
+ This is useful if you need to tell the compiler to put the const data in
+ a special segment so you can later on tell the linker to put this segment
+ in a special place in memory.
+ Can be used for instance when using bank switching to put the const data
+ in a bank.
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fsmul.c
+\series bold
+more-pedantic
+\series default
+ Actually this is
+\series bold
+\emph on
+not
+\series default
+\emph default
+ a SDCC compiler option but if you want
+\emph on
+more
+\emph default
+ warnings you can use a separate tool dedicated to syntax checking like
+ splint
+\begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{lint (syntax checking tool)}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-multiply floating point numbers
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+
+\begin_inset LatexCommand \url{http://www.splint.org}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2uchar.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+ To make your source files parseable by splint you will have to include
+
+\family sans
+lint.h
+\family default
+\begin_inset LatexCommand \index{splint (syntax checking tool)}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to unsigned char
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ in your source file and add brackets around extended keywords (like
+\family sans
+\begin_inset Quotes sld
+\end_inset
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2char.c
+__at\SpecialChar ~
+
+\series bold
+(
+\series default
+0xab
+\series bold
+)
+\series default
+
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\family default
+ and
+\family sans
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to signed char
+\begin_inset Quotes sld
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+__interrupt\SpecialChar ~
+(2)
+\begin_inset Quotes srd
+\end_inset
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2uint.c
+\family default
+).
+
+\newline
+Splint has an excellent on line manual at
+\begin_inset LatexCommand \url{http://www.splint.org/manual/}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ and it's capabilities go beyond pure syntax checking.
+ You'll need to tell splint the location of SDCC's include files so a typical
+ command line could look like this:
+\newline
+\family sans
+splint\SpecialChar ~
+-I\SpecialChar ~
+/usr/local/share/sdcc/include/mcs51/\SpecialChar ~
+\SpecialChar ~
+myprogram.c
+\layout Subsection
+
+Intermediate Dump Options
+\begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to unsigned int
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{Options intermediate dump}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2int.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{Intermediate dump options}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to signed int
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
\layout Standard
+The following options are provided for the purpose of retargetting and debugging
+ the compiler.
+ They provide a means to dump the intermediate code (iCode
+\begin_inset LatexCommand \index{iCode}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2ulong.
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color default
-c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+) generated by the compiler in human readable form at various stages of
+ the compilation process.
+ More on iCodes see chapter
+\begin_inset LatexCommand \ref{sub:The-anatomy-of}
+\end_inset
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to unsigned long
+
+\begin_inset Quotes srd
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+The anatomy of the compiler
+\begin_inset Quotes srd
+\end_inset
+.
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2long.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
+\backslash
+/
+\end_inset
+
+-dumpraw
+\begin_inset LatexCommand \index{-\/-dumpraw}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to signed long
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\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
+\begin_inset LatexCommand \index{Basic blocks}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_uchar2fs.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ at this stage ordered in the depth first number, so they may not be in
+ sequence of execution.
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert unsigned char to floating point
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
+\backslash
+/
+\end_inset
+
+-dumpgcse
+\begin_inset LatexCommand \index{-\/-dumpgcse}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_char2fs.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\series default
+ Will create a dump of iCode's, after global subexpression elimination
+\begin_inset LatexCommand \index{Global subexpression elimination}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert char to floating point number
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+, into a file named
+\emph on
+<source filename>.dumpgcse.
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_uint2fs.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
+\backslash
+/
+\end_inset
+
+-dumpdeadcode
+\begin_inset LatexCommand \index{-\/-dumpdeadcode}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert unsigned int to floating point
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\series default
+ Will create a dump of iCode's, after deadcode elimination
+\begin_inset LatexCommand \index{Dead-code elimination}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_int2fs.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+, into a file named
+\emph on
+<source filename>.dumpdeadcode.
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert int to floating point numbers
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
+\backslash
+/
+\end_inset
+
+-dumploop
+\begin_inset LatexCommand \index{-\/-dumploop}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_ulong2fs.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\series default
+\size large
+
+\size default
+Will create a dump of iCode's, after loop optimizations
+\begin_inset LatexCommand \index{Loop optimization}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert unsigned long to floating point number
\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
+, into a file named
+\emph on
+<source filename>.dumploop.
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_long2fs.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert long to floating point number
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
+\backslash
+/
\end_inset
-
-\newline
-
-\layout Standard
-
-Note if all these routines are used simultaneously the data space might
- overflow.
- For serious floating point usage it is strongly recommended that the large
- model be used.
- Also notice that you don't have to call this routines directly.
- The compiler will use them automatically every time a floating point operation
- is required.
-\layout Subsection
-
-MCS51 Memory Models
-\begin_inset LatexCommand \index{Memory model}
+-dumprange
+\begin_inset LatexCommand \index{-\/-dumprange}
\end_inset
-\begin_inset LatexCommand \index{MCS51 memory}
+\series default
+\size large
+
+\size default
+Will create a dump of iCode's, after live range analysis
+\begin_inset LatexCommand \index{Live range analysis}
\end_inset
-
-\layout Standard
-
-SDCC allows two memory models for MCS51 code, small and large.
- Modules compiled with different memory models should
+, into a file named
\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 separate directories as small
- and large so that you can link to either set.
-
-\layout Standard
+<source filename>.dumprange.
+\layout List
+\labelwidthstring 00.00.0000
-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
-\begin_inset LatexCommand \index{reentrant}
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
- 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
-\begin_inset LatexCommand \index{Storage class}
-
+\backslash
+/
\end_inset
- 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 recommended that the small model
- be used unless absolutely required.
-\layout Subsection
-
-DS390 Memory Models
-\begin_inset LatexCommand \index{Memory model}
+-dumlrange
+\begin_inset LatexCommand \index{-\/-dumlrange}
\end_inset
-\begin_inset LatexCommand \index{DS390 memory model}
+\series default
+ Will dump the life ranges
+\begin_inset LatexCommand \index{Live range analysis}
\end_inset
+ for all symbols.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-The only model supported is Flat 24
-\begin_inset LatexCommand \index{Flat 24 (memory model)}
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
-.
- 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
+-dumpregassign
+\begin_inset LatexCommand \index{-\/-dumpregassign}
-\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
+\end_inset
-\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
-\begin_inset LatexCommand \index{Tinibios (DS390)}
+\bar under
+
+\series default
+\bar default
+Will create a dump of iCode's, after register assignment
+\begin_inset LatexCommand \index{Register assignment}
\end_inset
-, 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
+, into a file named
\emph on
+<source filename>.dumprassgn.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
-
\begin_inset ERT
status Collapsed
/
\end_inset
--model-large
-\emph default
- option, variables will by default be placed into the XDATA segment.
-
-\newline
+-dumplrange
+\begin_inset LatexCommand \index{-\/-dumplrange}
-\newline
-Segments may be placed anywhere in the 4 meg address space using the usual
- -
+\end_inset
+
+
+\series default
+ Will create a dump of the live ranges of iTemp's
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--*-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
-\begin_inset LatexCommand \index{Defines created by the compiler}
+-dumpall
+\begin_inset LatexCommand \index{-\/-dumpall}
\end_inset
+\size large
+\bar under
+
+\series default
+\size default
+\bar default
+Will cause all the above mentioned dumps to be created.
+\layout Subsection
+
+Redirecting output on Windows Shells
\layout Standard
-The compiler creates the following #defines
-\begin_inset LatexCommand \index{\#defines}
+By default SDCC writes it's error messages to
+\begin_inset Quotes sld
+\end_inset
+standard error
+\begin_inset Quotes srd
\end_inset
-:
-\newline
+.
+ To force all messages to
+\begin_inset Quotes sld
+\end_inset
-\layout Standard
+standard output
+\begin_inset Quotes srd
+\end_inset
+ use
+\series bold
+-
+\series default
+\emph on
-\begin_inset Tabular
-<lyxtabular version="3" rows="10" columns="2">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_inset ERT
+status Collapsed
\layout Standard
+\backslash
+/
+\end_inset
+
\series bold
-#define
+\emph default
+-
+\series default
+use-stdout
+\begin_inset LatexCommand \index{-\/-use-stdout}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+.
+ Additionally, if you happen to have visual studio installed in your windows
+ machine, you can use it to compile your sources using a custom build and
+ the SDCC -
+\emph on
+
+\begin_inset ERT
+status Collapsed
\layout Standard
+\backslash
+/
+\end_inset
+
+
+\emph default
+-vc
+\begin_inset LatexCommand \index{-\/-vc}
-\series bold
-Description
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ option.
+ Something like this should work:
+\newline
-SDCC
-\begin_inset LatexCommand \index{SDCC}
+\newline
-\end_inset
+\series bold
+c:
+\backslash
+sdcc
+\backslash
+bin
+\backslash
+sdcc.exe -
+\series default
+\emph on
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_inset ERT
+status Collapsed
\layout Standard
-this Symbol is always defined
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-SDCC_mcs51
-\begin_inset LatexCommand \index{SDCC\_mcs51}
+\series bold
+\emph default
+-vc -
+\series default
+\emph on
-\end_inset
+\begin_inset ERT
+status Collapsed
- or SDCC_ds390
-\begin_inset LatexCommand \index{SDCC\_ds390}
+\layout Standard
+\backslash
+/
\end_inset
- or SDCC_z80
-\begin_inset LatexCommand \index{SDCC\_z80}
-\end_inset
+\series bold
+\emph default
+-model-large -c $(InputPath)
+\layout Section
+
+Environment variables
+\begin_inset LatexCommand \index{Environment variables}
-, etc
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
\layout Standard
-depending on the model used (e.g.: -mds390
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+SDCC recognizes the following environment variables:
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-__mcs51
-\begin_inset LatexCommand \index{\_\_mcs51}
+\series bold
+SDCC_LEAVE_SIGNALS
+\begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
\end_inset
- or __ds390
-\begin_inset LatexCommand \index{\_\_ds390}
+
+\series default
+ SDCC installs a signal handler
+\begin_inset LatexCommand \index{signal handler}
\end_inset
- or __z80
-\begin_inset LatexCommand \index{\_\_z80}
+ 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
-\end_inset
-, etc
+\series bold
+TMP,\SpecialChar ~
+TEMP,\SpecialChar ~
+TMPDIR
+\begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-depending on the model used (e.g.
- -mz80)
+\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
+SDCC_HOME
+\begin_inset LatexCommand \index{SDCC\_HOME}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-SDCC_STACK_AUTO
-\begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
+\series default
+ Path, see section
+\begin_inset LatexCommand \ref{sub:Install-paths}
\end_inset
+\SpecialChar ~
+\begin_inset Quotes sld
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ Install Paths
+\begin_inset Quotes srd
+\end_inset
-when
-\emph on
--
-\begin_inset ERT
-status Collapsed
+.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-\backslash
-/
-\end_inset
+\series bold
+SDCC_INCLUDE
+\begin_inset LatexCommand \index{SDCC\_INCLUDE}
--stack-auto
-\emph default
- option is used
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-SDCC_MODEL_SMALL
-\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
+\series default
+ Path, see section
+\begin_inset LatexCommand \ref{sub:Search-Paths}
\end_inset
+\SpecialChar ~
+\begin_inset Quotes sld
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+Search Paths
+\begin_inset Quotes srd
+\end_inset
-when
-\emph on
--
-\begin_inset ERT
-status Collapsed
+.
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
-\backslash
-/
-\end_inset
+\series bold
+SDCC_LIB
+\begin_inset LatexCommand \index{SDCC\_LIB}
--model-small
-\emph default
- is used
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-SDCC_MODEL_LARGE
-\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
+\series default
+ Path, see section
+\begin_inset LatexCommand \ref{sub:Search-Paths}
\end_inset
+\SpecialChar ~
+
+\begin_inset Quotes sld
+\end_inset
+Search Paths
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+..
\layout Standard
-when
-\emph on
--
-\begin_inset ERT
-status Collapsed
+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 documented.
+\layout Section
-\layout Standard
+Storage Class Language Extensions
+\layout Subsection
-\backslash
-/
-\end_inset
+MCS51/DS390 Storage Class
+\begin_inset LatexCommand \index{Storage class}
--model-large
-\emph default
- is used
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ Language Extensions
\layout Standard
-SDCC_USE_XSTACK
-\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
+In addition to the ANSI storage classes SDCC allows the following MCS51
+ specific storage classes:
+\layout Subsubsection
+
+data
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
\end_inset
+\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ / near
+\begin_inset LatexCommand \index{near (storage class)}
-when
-\emph on
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--xstack
-\emph default
- option is used
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-SDCC_STACK_TENBIT
-\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
+\begin_inset LatexCommand \index{\_\_near (storage class)}
\end_inset
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
\layout Standard
-when
+This is the
+\series bold
+default
+\series default
+ storage class for the Small Memory model (
\emph on
--mds390
+data
\emph default
- is used
-\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ and
+\emph on
+near
+\emph default
+ or the more ANSI-C compliant forms
+\emph on
+__data
+\emph default
+ and
+\emph on
+__near
+\emph default
+ can be used synonymously).
+ Variables declared with this storage class will be allocated in the directly
+ addressable portion of the internal RAM of a 8051, e.g.:
+\layout Verse
+
+\family typewriter
+__data unsigned char test_data;
\layout Standard
-SDCC_MODEL_FLAT24
-\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
-\end_inset
+\family typewriter
+75*00 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+_test_data,#0x01
+\layout Subsubsection
+
+xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-when
-\emph on
--mds390
-\emph default
- is used
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
\end_inset
+ / far
+\begin_inset LatexCommand \index{far (storage class)}
-\newline
-
-\layout Subsection
+\end_inset
-Redirecting output on Windows Shells
-\layout Standard
-By default SDCC writes it's error messages to
-\begin_inset Quotes sld
-\end_inset
+\begin_inset LatexCommand \index{\_\_far (storage class)}
-standard error
-\begin_inset Quotes srd
\end_inset
-.
- To force all messages to
-\begin_inset Quotes sld
-\end_inset
-standard output
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
- use
+Variables declared with this storage class will be placed in the external
+ RAM.
+ This is the
\series bold
--
+default
\series default
-\emph on
+ storage class for the Large Memory model, e.g.:
+\layout Verse
-\begin_inset ERT
-status Collapsed
+\family typewriter
+__xdata unsigned char test_xdata;
\layout Standard
-\backslash
-/
-\end_inset
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
-\series bold
-\emph default
--
-\series default
-use-stdout
-\begin_inset LatexCommand \index{-\/-use-stdout}
+\family typewriter
+90s00r00\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+dptr,#_test_xdata
+\newline
+74\SpecialChar ~
+01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+a,#0x01
+\newline
+F0\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+movx\SpecialChar ~
+@dptr,a
+\layout Subsubsection
-\end_inset
+idata
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
-.
- Aditionaly, if you happen to have visual studio installed in your windows
- machine, you can use it to compile your sources using a custom build and
- the SDCC -
-\emph on
+\end_inset
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
-\backslash
-/
\end_inset
-\emph default
--vc
-\begin_inset LatexCommand \index{-\/-vc}
+\layout Standard
-\end_inset
+Variables declared with this storage class will be allocated into the indirectly
+ addressable portion of the internal ram of a 8051, e.g.:
+\layout Verse
- option.
- Something like this should work:
-\newline
-\newline
+\family typewriter
+__idata unsigned char test_idata;
+\layout Standard
-\series bold
-c:
-\backslash
-sdcc
-\backslash
-bin
-\backslash
-sdcc.exe -
-\series default
-\emph on
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
-\begin_inset ERT
-status Collapsed
+\family typewriter
+78r00\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+r0,#_test_idata
+\newline
+76\SpecialChar ~
+01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+@r0,#0x01
\layout Standard
-\backslash
-/
-\end_inset
-
+Please note, the first 128 byte of idata physically access the same RAM
+ as the data memory.
+ The original 8051 had 128 byte idata memory, nowadays most devices have
+ 256 byte idata memory.
+ The stack
+\begin_inset LatexCommand \index{stack}
-\series bold
-\emph default
--vc -
-\series default
-\emph on
+\end_inset
-\begin_inset ERT
-status Collapsed
+ is located in idata memory.
+\layout Subsubsection
-\layout Standard
+pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
-\backslash
-/
\end_inset
-\series bold
-\emph default
--model-large -c $(InputPath)
-\layout Section
-\pagebreak_top
-SDCC Technical Data
-\layout Subsection
-
-Optimizations
-\begin_inset LatexCommand \index{Optimizations}
+\begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
\end_inset
\layout Standard
-SDCC performs a host of standard optimizations in addition to some MCU specific
- optimizations.
-
-\layout Subsubsection
-
-Sub-expression Elimination
-\begin_inset LatexCommand \index{Subexpression elimination}
+Paged xdata access is just as straightforward as using the other addressing
+ modes of a 8051.
+ It is typically located at the start of xdata and has a maximum size of
+ 256 bytes.
+ The following example writes 0x01 to the pdata variable.
+ Please note, pdata access physically accesses xdata memory.
+ The high byte of the address is determined by port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
\end_inset
+(or in case of some 8051 variants by a separate Special Function Register,
+ see section
+\begin_inset LatexCommand \ref{sub:MCS51-variants}
-\layout Standard
+\end_inset
-The compiler does local and global common subexpression elimination, e.g.:
-
+).
+ This is the
+\series bold
+default
+\series default
+ storage class for the Medium Memory model, e.g.:
\layout Verse
\family typewriter
-i = x + y + 1;
-\newline
-j = x + y;
+__pdata unsigned char test_pdata;
\layout Standard
-will be translated to
+Writing 0x01 to this variable generates the assembly code:
\layout Verse
\family typewriter
-iTemp = x + y
+78r00\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov r0,#_test_pdata
\newline
-i = iTemp + 1
+74 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov a,#0x01
\newline
-j = iTemp
-\layout Standard
-
-Some subexpressions are not as obvious as the above example, e.g.:
-\layout Verse
+F2\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+movx @r0,a
+\layout Standard
+If the -
+\begin_inset ERT
+status Collapsed
-\family typewriter
-a->b[i].c = 10;
-\newline
-a->b[i].d = 11;
\layout Standard
-In this case the address arithmetic a->b[i] will be computed only once;
- the equivalent code in C would be.
-\layout Verse
+\backslash
+/
+\end_inset
+-xstack
+\begin_inset LatexCommand \index{-\/-xstack}
-\family typewriter
-iTemp = a->b[i];
-\newline
-iTemp.c = 10;
-\newline
-iTemp.d = 11;
-\layout Standard
+\end_inset
-The compiler will try to keep these temporary variables in registers.
+ option is used the pdata memory area is followed by the xstack memory area
+ and the sum of their sizes is limited to 256 bytes.
\layout Subsubsection
-Dead-Code Elimination
-\begin_inset LatexCommand \index{Dead-code elimination}
+code
+\begin_inset LatexCommand \index{code}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_code}
\end_inset
+\layout Standard
+
+'Variables' declared with this storage class will be placed in the code
+ memory:
\layout Verse
\family typewriter
-int global;
-\newline
-void f () {
-\newline
+__code unsigned char test_code;
+\layout Standard
+
+Read access to this variable generates the assembly code:
+\layout Verse
+
+
+\family typewriter
+90s00r6F\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-int i;
+mov dptr,#_test_code
\newline
+E4\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-i = 1; \SpecialChar ~
-/* dead store */
-\newline
\SpecialChar ~
\SpecialChar ~
-global = 1;\SpecialChar ~
-/* dead store */
-\newline
\SpecialChar ~
\SpecialChar ~
-global = 2;
-\newline
\SpecialChar ~
\SpecialChar ~
-return;
+clr a
\newline
+93\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-global = 3;\SpecialChar ~
-/* unreachable */
-\newline
-}
-\layout Standard
-
-will be changed to
-\layout Verse
-
-
-\family typewriter
-int global; void f ()
-\newline
-{
-\newline
\SpecialChar ~
\SpecialChar ~
-global = 2;
-\newline
\SpecialChar ~
\SpecialChar ~
-return;
-\newline
-}
-\layout Subsubsection
+\SpecialChar ~
+\SpecialChar ~
+movc a,@a+dptr
+\layout Standard
-Copy-Propagation
-\begin_inset LatexCommand \index{Copy propagation}
-\end_inset
+\family typewriter
+char
+\family default
+ indexed arrays of characters in code memory can be accessed efficiently:
+\layout Verse
+
+\family typewriter
+__code char test_array[] = {'c','h','e','a','p'};
+\layout Standard
+Read access to this array using an 8-bit unsigned index generates the assembly
+ code:
\layout Verse
\family typewriter
-int f() {
-\newline
+E5*00\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-int i, j;
-\newline
\SpecialChar ~
\SpecialChar ~
-i = 10;
-\newline
-\SpecialChar ~
\SpecialChar ~
-j = i;
-\newline
+mov a,_index
+\layout Verse
+
+
+\family typewriter
+90s00r41\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-return j;
-\newline
-}
-\layout Standard
-
-will be changed to
+mov dptr,#_test_array
\layout Verse
\family typewriter
-int f() {
-\newline
+93\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-int i, j;
-\newline
\SpecialChar ~
\SpecialChar ~
-i = 10;
-\newline
\SpecialChar ~
\SpecialChar ~
-j = 10;
-\newline
\SpecialChar ~
\SpecialChar ~
-return 10;
-\newline
-}
-\layout Standard
-
-Note: the dead stores created by this copy propagation will be eliminated
- by dead-code elimination.
+movc a,@a+dptr
\layout Subsubsection
-Loop Optimizations
-\begin_inset LatexCommand \index{Loop optimization}
+bit
+\begin_inset LatexCommand \index{bit}
\end_inset
-\layout Standard
-
-Two types of loop optimizations are done by SDCC loop invariant lifting
- and strength reduction of loop induction variables.
- In addition to the strength reduction the optimizer marks the induction
- variables and the register allocator tries to keep the induction variables
- in registers for the duration of the loop.
- Because of this preference of the register allocator
-\begin_inset LatexCommand \index{Register allocation}
-
-\end_inset
-
-, loop induction optimization causes an increase in register pressure, which
- may cause unwanted spilling of other temporary variables into the stack
-\begin_inset LatexCommand \index{stack}
+\begin_inset LatexCommand \index{\_\_bit}
\end_inset
- / 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 -
-\begin_inset ERT
-status Collapsed
\layout Standard
-\backslash
-/
-\end_inset
-
--noinduction option) or for a given function only using #pragma\SpecialChar ~
-NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
-
-\end_inset
-
-.
-\newline
-
-\newline
-Loop Invariant:
+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.:
\layout Verse
\family typewriter
-for (i = 0 ; i < 100 ; i ++)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-f += k + l;
+bit test_bit;
\layout Standard
-changed to
+Writing 1 to this variable generates the assembly code:
\layout Verse
\family typewriter
-itemp = k + l;
-\newline
-for (i = 0; i < 100; i++)
-\newline
+D2*00\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-f += itemp;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+setb\SpecialChar ~
+_test_bit
\layout Standard
-As mentioned previously some loop invariants are not as apparent, all static
- address computations are also moved out of the loop.
-\newline
-
+The bit addressable memory consists of 128 bits which are located from 0x20
+ to 0x2f in data memory.
+
\newline
-Strength Reduction
-\begin_inset LatexCommand \index{Strength reduction}
+Apart from this 8051 specific storage class most architectures support ANSI-C
+ bitfields
+\begin_inset LatexCommand \index{bitfields}
\end_inset
-, this optimization substitutes an expression by a cheaper expression:
-\layout Verse
-
-
-\family typewriter
-for (i=0;i < 100; i++)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-ar[i*5] = i*3;
-\layout Standard
-
-changed to
-\layout Verse
+\begin_inset Foot
+collapsed false
-\family typewriter
-itemp1 = 0;
-\newline
-itemp2 = 0;
-\newline
-for (i=0;i< 100;i++) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ar[itemp1] = itemp2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-itemp1 += 5;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-itemp2 += 3;
-\newline
-}
\layout Standard
-The more expensive multiplication
-\begin_inset LatexCommand \index{Multiplication}
-
+Not really meant as examples, but nevertheless showing what bitfields are
+ about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
\end_inset
- is changed to a less expensive addition.
+.
+ In accordance with ISO/IEC 9899 bits and bitfields without an explicit
+ signed modifier are implemented as unsigned.
\layout Subsubsection
-Loop Reversing
-\begin_inset LatexCommand \index{Loop reversing}
+sfr
+\begin_inset LatexCommand \index{sfr}
\end_inset
-\layout Standard
+\begin_inset LatexCommand \index{\_\_sfr}
-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
+ / sfr16
+\begin_inset LatexCommand \index{sfr16}
+
\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
+\begin_inset LatexCommand \index{\_\_sfr16}
+
+\end_inset
+
+ / sfr32
+\begin_inset LatexCommand \index{sfr32}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_sfr32}
+
+\end_inset
+
+ / sbit
+\begin_inset LatexCommand \index{\_\_sbit}
+
+\end_inset
+
+
+\layout Standard
+
+Like the bit keyword,
+\emph on
+sfr / sfr16 / sfr32 / sbit
+\emph default
+signify both a data-type and storage class, they are used to describe the
+
+\emph on
+s
+\emph default
+pecial
+\emph on
+f
+\emph default
+unction
+\emph on
+r
+\emph default
+egisters and
+\emph on
+s
+\emph default
+pecial
+\emph on
+bit
+\emph default
+ variables of a 8051, eg:
+\layout Verse
-\newline
\family typewriter
-for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
- += 1])
+__sfr __at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
+\end_inset
+
+ (0x80) P0;\SpecialChar ~
+ /* special function register P0 at location 0x80 */
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-<for body>
-\layout Itemize
+/* 16 bit special function register combination for timer 0 */
+\newline
+/* with the high byte at location 0x8C and the low byte at location 0x8A
+ */
+\newline
+__sfr16 __at
+\begin_inset LatexCommand \index{at}
-The <for body> does not contain
-\begin_inset Quotes eld
\end_inset
-continue
-\begin_inset Quotes erd
+
+\begin_inset LatexCommand \index{\_\_at}
+
\end_inset
- or 'break
-\begin_inset Quotes erd
+ (0x8C8A) TMR0;
+\newline
+__sbit __at (0xd7) CY; /* CY (Carry Flag
+\begin_inset LatexCommand \index{Flags}
+
\end_inset
-.
-\layout Itemize
-All goto's are contained within the loop.
-\layout Itemize
+\begin_inset LatexCommand \index{Carry flag}
-No function calls within the loop.
-\layout Itemize
+\end_inset
-The loop control variable <sym> is not assigned any value within the loop
-\layout Itemize
+) */
+\layout Standard
-The loop control variable does NOT participate in any arithmetic operation
- within the loop.
-\layout Itemize
+Special function registers which are located on an address dividable by
+ 8 are bit-addressable, an
+\emph on
+ sbit
+\emph default
+ addresses a specific bit within these sfr.
+\newline
+16 Bit and 32 bit special function register combinations which require a
+ certain access order are better not declared using
+\emph on
+sfr16
+\emph default
+ or
+\emph on
+sfr32.
-There are NO switch statements in the loop.
+\emph default
+ Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
+ this is not guaranteed.
\layout Subsubsection
-Algebraic Simplifications
+Pointers
+\begin_inset LatexCommand \index{Pointer}
+
+\end_inset
+
+ to MCS51/DS390 specific memory spaces
\layout Standard
-SDCC does numerous algebraic simplifications, the following is a small sub-set
- of these optimizations.
+SDCC allows (via language extensions) pointers to explicitly point to any
+ of the memory spaces
+\begin_inset LatexCommand \index{Memory model}
+
+\end_inset
+
+ 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:
\layout Verse
\family typewriter
-i = j + 0 ; /* changed to */ i = j;
+/* pointer physically in internal ram pointing to object in external ram
+ */
+\newline
+__xdata unsigned char * __data p;
+\newline
+
+\newline
+/* pointer physically in external 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
-i /= 2; /* changed to */ i >>= 1;
+/* the following is a generic pointer physically located in xdata space
+ */
+\newline
+char * __xdata p;
+\newline
+
\newline
-i = j - j ; /* changed to */ i = 0;
+/* the following is a function pointer physically located in data space
+ */
\newline
-i = j / 1 ; /* changed to */ i = j;
+char (* __data fp)(void);
\layout Standard
-Note the subexpressions
-\begin_inset LatexCommand \index{Subexpression}
+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
+\begin_inset LatexCommand \index{Libraries}
\end_inset
- given above are generally introduced by macro expansions or as a result
- of copy/constant propagation.
+ routines.
+ Explicitly specifying the pointer type will generate the most efficient
+ code.
\layout Subsubsection
-'switch' Statements
-\begin_inset LatexCommand \index{switch statement}
+Notes on MCS51 memory
+\begin_inset LatexCommand \index{MCS51 memory}
\end_inset
+ layout
+\layout Standard
+
+The 8051 family of microcontrollers have a minimum of 128 bytes of internal
+ RAM memory which is structured as follows:
+\newline
+
+\newline
+- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
+
+\newline
+- Bytes 20-2F - 16 bytes to hold 128 bit
+\begin_inset LatexCommand \index{bit}
+
+\end_inset
+
+ variables and,
+\newline
+- Bytes 30-7F - 80 bytes for general purpose use.
+\newline
\layout Standard
-SDCC changes switch statements to jump tables
-\begin_inset LatexCommand \index{jump tables}
+Additionally some members of the MCS51 family may have up to 128 bytes of
+ additional, indirectly addressable, internal RAM memory (
+\emph on
+idata
+\emph default
+
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
\end_inset
- 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.
-\begin_deeper
-\layout Verse
+\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
+\end_inset
+
+).
+ Furthermore, some chips may have some built in external memory (
+\emph on
+xdata
+\emph default
+
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+) which should not be confused with the internal, directly addressable RAM
+ memory (
+\emph on
+data
+\emph default
+
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
+
+\end_inset
+
+).
+ Sometimes this built in
+\emph on
+xdata
+\emph default
+ memory has to be activated before using it (you can probably find this
+ information on the datasheet of the microcontroller your are using, see
+ also section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
+\end_inset
-\family typewriter
-switch(i) {\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-switch (i) {
+Startup-Code).
+\layout Standard
+
+Normally SDCC will only use the first bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
+
+\end_inset
+
+ of registers (register bank 0), but it is possible to specify that other
+ banks of registers (keyword
+\emph on
+using
+\emph default
+
+\emph on
+
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
+\emph default
+) should be used in interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_interrupt}
+
+\end_inset
+
+ routines.
+ By default, the compiler will place the stack after the last byte of allocated
+ memory for variables.
+ For example, if the first 2 banks of registers are used, and only four
+ bytes are used for
+\emph on
+data
+\emph default
+ variables, it will position the base of the internal stack at address 20
+ (0x14).
+ This implies that as the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ grows, it will use up the remaining register banks, and the 16 bytes used
+ by the 128 bit variables, and 80 bytes for general purpose use.
+ If any bit variables are used, the data variables will be placed in unused
+ register banks and after the byte holding the last bit variable.
+ For example, if register banks 0 and 1 are used, and there are 9 bit variables
+ (two bytes used),
+\emph on
+data
+\emph default
+ variables will be placed starting from address 0x10 to 0x20 and continue
+ at address 0x22.
+ You can also use -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-data-loc
+\begin_inset LatexCommand \index{-\/-data-loc <Value>}
+
+\end_inset
+
+ to specify the start address of the
+\emph on
+data
+\emph default
+ and -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-iram-size
+\begin_inset LatexCommand \index{-\/-iram-size <Value>}
+
+\end_inset
+
+ to specify the size of the total internal RAM (
+\emph on
+data
+\emph default
++
+\emph on
+idata
+\emph default
+).
+
\newline
+
+\layout Standard
+
+By default the 8051 linker will place the stack after the last byte of (i)data
+ variables.
+ Option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-loc
+\begin_inset LatexCommand \index{-\/-stack-loc <Value>}
+
+\end_inset
+
+ allows you to specify the start of the stack, i.e.
+ you could start it after any data in the general purpose area.
+ If your microcontroller has additional indirectly addressable internal
+ RAM (
+\emph on
+idata
+\emph default
+) you can place the stack on it.
+ You may also need to use -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xdata-loc
+\begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
+
+\end_inset
+
+ to set the start address of the external RAM (
+\emph on
+xdata
+\emph default
+) and -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xram-size
+\begin_inset LatexCommand \index{-\/-xram-size <Value>}
+
+\end_inset
+
+ to specify its size.
+ Same goes for the code memory, using -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-code-loc
+\begin_inset LatexCommand \index{-\/-code-loc <Value>}
+
+\end_inset
+
+ and -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-code-size
+\begin_inset LatexCommand \index{-\/-code-size <Value>}
+
+\end_inset
+
+.
+ If in doubt, don't specify any options and see if the resulting memory
+ layout is appropriate, then you can adjust it.
+\layout Standard
+
+The linker generates two files with memory allocation information.
+ The first, with extension .map
+\begin_inset LatexCommand \index{<file>.map}
+
+\end_inset
+
+ shows all the variables and segments.
+ The second with extension .mem
+\begin_inset LatexCommand \index{<file>.mem}
+
+\end_inset
+
+ shows the final memory layout.
+ The linker will complain either if memory segments overlap, there is not
+ enough memory, or there is not enough space for stack.
+ If you get any linking warnings and/or errors related to stack or segments
+ allocation, take a look at either the .map or .mem files to find out what
+ the problem is.
+ The .mem file may even suggest a solution to the problem.
+\layout Subsection
+
+Z80/Z180 Storage Class
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ Language Extensions
+\layout Subsubsection
+
+sfr
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_sfr}
+
+\end_inset
+
+ (in/out to 8-bit addresses)
+\layout Standard
+
+The Z80
+\begin_inset LatexCommand \index{Z80}
+
+\end_inset
+
+ family has separate address spaces for memory and
+\emph on
+i
+\emph default
+nput/
+\emph on
+o
+\emph default
+utput memory.
+ I/O memory
+\begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
+
+\end_inset
+
+ is accessed with special instructions, e.g.:
+\layout Verse
+
+
+\family typewriter
+sfr at 0x78 IoPort;\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 4: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+/* define a var in I/O space at 78h called IoPort */
+
+\layout Standard
+
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
+
+
+\family typewriter
+3E 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ld a,#0x01
+\newline
+D3 78\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 1: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 5: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 2: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 3: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 3: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 6: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\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 ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-}
-\layout Standard
+out (_IoPort),a
+\layout Subsubsection
-Both the above switch statements will be implemented using a jump-table.
-\end_deeper
-\layout Itemize
+banked sfr
+\begin_inset LatexCommand \index{sfr}
-The number of case labels is at least three, since it takes two conditional
- statements to handle the boundary conditions.
-\layout Itemize
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_sfr}
+
+\end_inset
-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.
+ (in/out to 16-bit addresses)
\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.:
+The keyword
+\emph on
+banked
+\emph default
+ is used to support 16 bit addresses in I/O memory e.g.:
\layout Verse
\family typewriter
-switch (i) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-case 1: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-case 2: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-case 3: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-case 4: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-case 9: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-case 10: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-case 11: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-case 12: ...
-
-\newline
-}
+sfr banked at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
+\end_inset
+
+ 0x123 IoPort;
\layout Standard
-If the above switch statement is broken down into two switch statements
+Writing 0x01 to this variable generates the assembly code:
\layout Verse
\family typewriter
-switch (i) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-case 1: ...
-
-\newline
+01 23 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 2: ...
-
+ld bc,#_IoPort
\newline
+3E 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 3: ...
-
-\newline
-\SpecialChar ~
\SpecialChar ~
-case 4: ...
-
-\newline
-}
-\layout Standard
-
-and
-\layout Verse
-
-
-\family typewriter
-switch (i) {
-\newline
\SpecialChar ~
\SpecialChar ~
-case 9: \SpecialChar ~
-...
-
+ld a,#0x01
\newline
+ED 79\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 10: ...
-
-\newline
-\SpecialChar ~
\SpecialChar ~
-case 11: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 12:\SpecialChar ~
-...
-
-\newline
-}
-\layout Standard
+out (c),a
+\layout Subsubsection
-then both the switch statements will be implemented using jump-tables whereas
- the unmodified switch statement will not be.
- The pragma NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+sfr
+\begin_inset LatexCommand \index{sfr}
\end_inset
- can be used to turn off checking the
-\emph on
-j
-\emph default
-ump
-\emph on
-t
-\emph default
-able
-\emph on
-bound
-\emph default
-aries.
-\layout Subsubsection
-Bit-shifting Operations
-\begin_inset LatexCommand \index{Bit shifting}
+\begin_inset LatexCommand \index{\_\_sfr}
\end_inset
-.
+ (in0/out0 to 8 bit addresses on Z180
+\begin_inset LatexCommand \index{Z180}
+
+\end_inset
+
+/HD64180
+\begin_inset LatexCommand \index{HD64180}
+
+\end_inset
+
+)
\layout Standard
-Bit shifting is one of the most frequently used operation in embedded programmin
-g.
- SDCC tries to implement bit-shift operations in the most efficient way
- possible, e.g.:
-\layout Verse
+The compiler option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-portmode=180 (80) and a compiler #pragma\SpecialChar ~
+portmode
+\begin_inset LatexCommand \index{\#pragma portmode}
+\end_inset
+=z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
+ns
\family typewriter
-unsigned char i;
-\newline
-...
+in0/out0
+\family default
+ instead of
+\family typewriter
+in/out
+\family default
+.
+ If you include the file z180.h this will be set automatically.
+\layout Subsection
+
+HC08 Storage Class
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ Language Extensions
+\layout Subsubsection
+
+data
+\begin_inset LatexCommand \index{data (hc08 storage class)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
+
+\end_inset
+
-\newline
-i>>= 4;
-\newline
-...
\layout Standard
-generates the following code:
-\layout Verse
+The data storage class declares a variable that resides in the first 256
+ bytes of memory (the direct page).
+ The HC08 is most efficient at accessing variables (especially pointers)
+ stored here.
+\layout Subsubsection
+xdata
+\begin_inset LatexCommand \index{xdata (hc08 storage class)}
-\family typewriter
-mov a,_i
-\newline
-swap a
-\newline
-anl a,#0x0f
-\newline
-mov _i,a
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
+
+\end_inset
+
+
\layout Standard
-In general SDCC will never setup a loop if the shift count is known.
- Another example:
+The xdata storage class declares a variable that can reside anywhere in
+ memory.
+ This is the default if no storage class is specified.
+
+\layout Section
+
+Absolute Addressing
+\begin_inset LatexCommand \index{Absolute addressing}
+
+\end_inset
+
+
+\layout Standard
+
+Data items can be assigned an absolute address with the
+\emph on
+at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
+\end_inset
+
+ <address>
+\emph default
+ keyword, in addition to a storage class, e.g.:
\layout Verse
\family typewriter
-unsigned int i;
-\newline
-...
-
-\newline
-i >>= 9;
-\newline
-...
+xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
+\end_inset
+
+ (0x7ffe) unsigned int chksum;
\layout Standard
-will generate:
+or
\layout Verse
\family typewriter
-mov a,(_i + 1)
-\newline
-mov (_i + 1),#0x00
-\newline
-clr c
-\newline
-rrc a
-\newline
-mov _i,a
+__xdata __at (0x7ffe) unsigned int chksum;
\layout Standard
-Note that SDCC stores numbers in little-endian format (i.e.
- lowest order first).
-\layout Subsubsection
+In the above example the variable chksum will be located at 0x7ffe and 0x7fff
+ of the external ram.
+ The compiler does
+\emph on
+not
+\emph default
+ reserve any space for variables declared in this way
+\begin_inset Marginal
+collapsed true
-Bit-rotation
-\begin_inset LatexCommand \index{Bit rotation}
+\layout Standard
+
+
+\series bold
+!
+\end_inset
+
+ (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
+\begin_inset LatexCommand \index{<file>.lst}
+
+\end_inset
+
+) and the linker output files (.rst
+\begin_inset LatexCommand \index{<file>.rst}
+
+\end_inset
+
+) and (.map
+\begin_inset LatexCommand \index{<file>.map}
\end_inset
+) are good places to look for such overlaps.
+ Variables with an absolute address are
+\emph on
+not
+\begin_inset Marginal
+collapsed true
\layout Standard
-A special case of the bit-shift operation is bit rotation, SDCC recognizes
- the following expression to be a left bit-rotation:
-\layout Verse
+\series bold
+!
+\end_inset
-\family typewriter
-unsigned char i;
-\newline
-...
-
-\newline
-i = ((i << 1) | (i >> 7));
-\family default
-\newline
+\emph default
+ initialized
+\begin_inset LatexCommand \index{Variable initialization}
-\family typewriter
-...
+\end_inset
+
+.
\layout Standard
-will generate the following code:
+In case of memory mapped I/O devices the keyword
+\emph on
+volatile
+\emph default
+ has to be used to tell the compiler that accesses might not be removed:
\layout Verse
\family typewriter
-mov a,_i
-\newline
-rl a
-\newline
-mov _i,a
+volatile
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+ __xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ __at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ (0x8000) unsigned char PORTA_8255;
\layout Standard
-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.:
+For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
+r) array
+\family typewriter
+\size footnotesize
+
+\begin_inset LatexCommand \index{Aligned array}
+
+\end_inset
+
+
+\family default
+\size default
+ starts at a block (256 byte) boundary
+\begin_inset LatexCommand \index{block boundary}
+
+\end_inset
+
+ (section
+\begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
+
+\end_inset
+
+ has an example).
+\newline
+Absolute addresses can be specified for variables in all storage classes,
+ e.g.:
\layout Verse
\family typewriter
-i = ((i >> 7) | (i << 1)); /* left-bit rotation */
-\layout Subsubsection
-
-Highest Order Bit
-\begin_inset LatexCommand \index{Highest Order Bit}
+bit
+\begin_inset LatexCommand \index{bit}
\end_inset
+ __at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+ (0x02) bvar;
\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.:
+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.
+ One possible use would be to write hardware portable code.
+ For example, if you have a routine that uses one or more of the microcontroller
+ I/O pins, and such pins are different for two different hardwares, you
+ can declare the I/O pins in your routine using:
\layout Verse
\family typewriter
-unsigned int gint;
-\newline
+extern volatile
+\begin_inset LatexCommand \index{volatile}
-\newline
-foo () {
-\newline
-unsigned char hob;
-\newline
+\end_inset
+
+ bit MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
+\SpecialChar ~
+/* master out, slave in */
\newline
+extern volatile bit MISO;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-hob = (gint >> 15) & 1;
+\SpecialChar ~
+/* master in, slave out */
\newline
+extern volatile bit MCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-..
-
+\SpecialChar ~
+/* master clock */
\newline
-}
-\layout Standard
-
-will generate the following code:
-\layout Verse
-
-\family typewriter
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+\newline
+/* Input and Output of a byte on a 3-wire serial bus.
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+If needed adapt polarity of clock, polarity of data and bit order
+\newline
\SpecialChar ~
+*/
+\newline
+unsigned char spi_io(unsigned char out_byte)
+\newline
+{
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+unsigned char i=8;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+do {
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 61 ;\SpecialChar ~
- hob.c 7
+MOSI = out_byte & 0x80;
\newline
-000A E5*01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- 62\SpecialChar ~
+out_byte <<= 1;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- mov\SpecialChar ~
\SpecialChar ~
- a,(_gint + 1)
+MCLK = 1;
\newline
-000C 23\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* _asm nop _endasm; */\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* for slow peripherals */
+\newline
\SpecialChar ~
- 63\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- rl\SpecialChar ~
+if(MISO)
+\newline
\SpecialChar ~
\SpecialChar ~
- a
-\newline
-000D 54 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+out_byte += 1;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 64\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+MCLK = 0;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- anl\SpecialChar ~
\SpecialChar ~
- a,#0x01
+} while(--i);
\newline
-000F F5*02\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+return out_byte;
+\newline
+}
+\layout Standard
+
+Then, someplace in the code for the first hardware you would use
+\layout Verse
+
+
+\family typewriter
+bit __at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
+\end_inset
+
+ (0x80) MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* I/O port 0, bit 0 */
+\newline
+bit __at (0x81) MISO;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* I/O port 0, bit 1 */
+\newline
+bit __at (0x82) MCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* I/O port 0, bit 2 */
+\layout Standard
+
+Similarly, for the second hardware you would use
+\layout Verse
+
+
+\family typewriter
+bit __at (0x83) MOSI;\SpecialChar ~
\SpecialChar ~
- 65\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* I/O port 0, bit 3 */
+\newline
+bit __at (0x91) MISO;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* I/O port 1, bit 1 */
+\newline
+bit
+\begin_inset LatexCommand \index{bit}
+
+\end_inset
+
+ __at (0x92) MCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- mov\SpecialChar ~
\SpecialChar ~
- _foo_hob_1_1,a
+/* I/O port 1, bit 2 */
\layout Standard
-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.:
-\layout Verse
+and you can use the same hardware dependent routine without changes, as
+ for example in a library.
+ This is somehow similar to sbit, but only one absolute address has to be
+ specified in the whole project.
+\layout Section
+Parameters
+\begin_inset LatexCommand \index{Parameters}
-\family typewriter
-xyz = gint + ((gint >> 15) & 1);
-\layout Standard
+\end_inset
-will still be recognized.
-\layout Subsubsection
-Peephole Optimizer
-\begin_inset LatexCommand \index{Peephole optimizer}
+\begin_inset LatexCommand \index{function parameter}
+
+\end_inset
+
+ & Local Variables
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+
+\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
\end_inset
\layout Standard
-The compiler uses a rule based, pattern matching and re-writing mechanism
- for peep-hole optimization.
- It is inspired by
+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 similar to
\emph on
-copt
+static
+\begin_inset LatexCommand \index{static}
+
+\end_inset
+
+
\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
+ so by default functions are non-reentrant
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+.
+
+\newline
+
+\newline
+They can be placed on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ by using the
\emph on
--
+ -
\begin_inset ERT
status Collapsed
/
\end_inset
--peep-file
-\begin_inset LatexCommand \index{-\/-peep-file}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
- <filename>
+
\emph default
- option.
- The rule language is best illustrated with examples.
+ option, by using
+\emph on
+#pragma\SpecialChar ~
+stackauto
+\emph default
+
+\begin_inset LatexCommand \index{\#pragma stackauto}
+
+\end_inset
+
+ or by using the
+\emph on
+reentrant
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+
+\emph default
+ keyword in the function declaration, e.g.:
\layout Verse
\family typewriter
-replace {
+unsigned char foo(char i) __reentrant
\newline
-\SpecialChar ~
-\SpecialChar ~
-mov %1,a
+{
\newline
\SpecialChar ~
\SpecialChar ~
-mov a,%1
-\newline
-} by {
-\newline
\SpecialChar ~
\SpecialChar ~
-mov %1,a
+...
+
\newline
}
\layout Standard
-The above rule will change the following assembly
-\begin_inset LatexCommand \index{Assembler routines}
+Since stack space on 8051 is limited, the
+\emph on
+reentrant
+\emph default
+keyword or the
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- sequence:
-\layout Verse
+-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
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
+\end_inset
-\family typewriter
-mov r1,a
+ independent.
\newline
-mov a,r1
-\layout Standard
-to
-\layout Verse
+\newline
+Local variables
+\begin_inset LatexCommand \index{local variables}
+\end_inset
-\family typewriter
-mov r1,a
-\layout Standard
+ can be assigned storage classes and absolute
+\begin_inset LatexCommand \index{Absolute addressing}
-Note: All occurrences of a
-\emph on
-%n
-\emph default
- (pattern variable) must denote the same string.
- With the above rule, the assembly sequence:
+\end_inset
+
+ addresses, e.g.:
\layout Verse
\family typewriter
-mov r1,a
+unsigned char foo()
\newline
-mov a,r2
-\layout Standard
-
-will remain unmodified.
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+xdata unsigned char i;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+bit bvar;
\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+data __at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+ (0x31) unsigned char j;
\newline
-Other special case optimizations may be added by the user (via
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Standard
+
+In the above example the variable
+\emph on
+i
+\emph default
+ will be allocated in the external ram,
+\emph on
+bvar
+\emph default
+ in bit addressable space and
+\emph on
+ j
+\emph default
+ in internal ram.
+ When compiled with
\emph on
-
\begin_inset ERT
/
\end_inset
--peep-file option
+-stack-auto
\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
-\layout Verse
+ or when a function is declared as
+\emph on
+reentrant
+\emph default
+ this should only be done for static variables.
+\layout Standard
+Parameters
+\begin_inset LatexCommand \index{function parameter}
-\family typewriter
-replace { lcall %1 } by { acall %1 }
-\newline
-replace { ljmp %1 } by { ajmp %1 }
+\end_inset
+
+ however are not allowed any storage class
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+, (storage classes for parameters will be ignored), their allocation is
+ governed by the memory model in use, and the reentrancy options.
\layout Standard
-The
+It is however allowed to use bit parameters in reentrant functions and also
+ non-static local bit variables are supported.
+ Efficient use is limited to 8 semi-bitregisters in bit space.
+ They are pushed and popped to stack as a single byte just like the normal
+ registers.
+\layout Section
+
+Overlaying
+\begin_inset LatexCommand \label{sub:Overlaying}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Overlaying}
+
+\end_inset
+
+
+\layout Standard
+
+For non-reentrant
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+ of a function will be allocated to an overlayable segment if the function
+ has
\emph on
-inline-assembler code
+no other function calls and the function is non-reentrant and the memory
+ model
+\begin_inset LatexCommand \index{Memory model}
+
+\end_inset
+
+ is small.
+
\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
+ If an explicit storage class
+\begin_inset LatexCommand \index{Storage class}
-\newline
-The syntax for a rule is as follows:
+\end_inset
+
+ 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
+\begin_inset Marginal
+collapsed true
+
+\layout Standard
+
+
+\series bold
+!
+\end_inset
+
+ should be preceded by a #pragma\SpecialChar ~
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{Multiplication}
+
+\end_inset
+
+ or division
+\begin_inset LatexCommand \index{Division}
+
+\end_inset
+
+ will NOT be overlayed since these are implemented using external functions,
+ e.g.:
\layout Verse
\family typewriter
-rule := replace [ restart ] '{' <assembly sequence> '
-\backslash
-n'
+#pragma save
\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- '}' by '{' '
-\backslash
-n'
+#pragma nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+
+
\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- <assembly sequence> '
-\backslash
-n'
+void set_error(unsigned char errcd)
+\newline
+{
\newline
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- '}' [if <functionName> ] '
-\backslash
-n'
-\layout Standard
-
-<assembly sequence> := assembly instruction (each instruction including
- labels must be on a separate line).
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+P3 = errcd;
+\newline
+}
+\newline
+#pragma restore
\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:
-\layout Verse
+void some_isr () __interrupt
+\begin_inset LatexCommand \index{interrupt}
+\end_inset
-\family typewriter
-replace restart {
+ (2)
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
-pop %1
+\SpecialChar ~
+\SpecialChar ~
+...
\newline
\SpecialChar ~
\SpecialChar ~
-push %1 } by {
+\SpecialChar ~
+\SpecialChar ~
+set_error(10);
\newline
\SpecialChar ~
\SpecialChar ~
-; nop
+\SpecialChar ~
+\SpecialChar ~
+...
+
\newline
}
\layout Standard
-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.:
-\layout Verse
-
-
-\family typewriter
-pop ar1
-\newline
-pop ar2
-\newline
-push ar2
-\newline
-push ar1
-\layout Standard
+In the above example the parameter
+\emph on
+errcd
+\emph default
+ for the function
+\emph on
+set_error
+\emph default
+ would be assigned to the overlayable segment if the #pragma\SpecialChar ~
+nooverlay was
+ not present, this could cause unpredictable runtime behavior when called
+ from an interrupt service routine.
+ The #pragma\SpecialChar ~
+nooverlay ensures that the parameters and local variables for
+ the function are NOT overlayed.
+\layout Section
-would result in:
-\layout Verse
+Interrupt Service Routines
+\begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
+\end_inset
-\family typewriter
-pop ar1
-\newline
-; nop
-\newline
-push ar1
-\layout Standard
+\layout Subsection
+
+General Information
+\layout Standard
+SDCC allows
\emph on
-with
+i
\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:
+nterrupt
+\emph on
+s
+\emph default
+ervice
+\emph on
+r
+\emph default
+outines to be coded in C, with some extended keywords.
\layout Verse
\family typewriter
-; nop
+void timer_isr (void) __interrupt (1) __using (1)
\newline
-; nop
-\layout Standard
-
-A conditional function can be attached to a rule.
- Attaching rules are somewhat more involved, let me illustrate this with
- an example.
-\layout Verse
-
-
-\family typewriter
-replace {
+{
\newline
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-ljmp %5
-\newline
-%2:
-\newline
-} by {
-\newline
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-sjmp %5
-\newline
-%2:
+\SpecialChar ~
+\SpecialChar ~
+...
+
\newline
-} if labelInRange
+}
\layout Standard
-The optimizer does a look-up of a function name table defined in function
-
+The optional number following the
\emph on
-callFuncByName
+interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_interrupt}
+
+\end_inset
+
+
\emph default
- in the source file SDCCpeeph.c, with the name
+ keyword is the interrupt number this routine will service.
+ When present, the compiler will insert a call to this routine in the interrupt
+ vector table for the interrupt number specified.
+ 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
-labelInRange
+main
\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
+ The optional
\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 -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+using
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
-\backslash
-/
\end_inset
--peep-file option.
-\layout Subsection
-Pragmas
-\begin_inset LatexCommand \index{Pragmas}
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
\end_inset
+\emph default
+ keyword can be used to tell the compiler to use the specified register
+ bank (8051 specific) when generating code for this function.
+
+\newline
+
\layout Standard
-SDCC supports the following #pragma directives.
-\layout Itemize
+Interrupt service routines open the door for some very interesting bugs:
+\newline
+If an interrupt service routine changes variables which are accessed by
+ other functions these variables have to be declared
+\emph on
+volatile
+\emph default
-SAVE
-\begin_inset LatexCommand \index{\#pragma SAVE}
+\begin_inset LatexCommand \index{volatile}
\end_inset
- - this will save all current options to the SAVE/RESTORE stack.
- See RESTORE.
-\layout Itemize
+.
+
+\layout Standard
-RESTORE
-\begin_inset LatexCommand \index{\#pragma RESTORE}
+If the access to these variables is not
+\emph on
+atomic
+\begin_inset LatexCommand \index{atomic}
\end_inset
- - will restore saved options from the last save.
- SAVEs & RESTOREs can be nested.
- SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
- RESTORE pulls current options from the stack.
- See SAVE.
-\layout Itemize
-
-NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+\emph default
+ (i.e.
+ the processor needs more than one instruction for the access and could
+ be interrupted while accessing the variable) the interrupt must be disabled
+ during the access to avoid inconsistent data.
+ Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
+ and should be protected by disabling interrupts.
+ You're not automatically on the safe side if you use 8 bit variables though.
+ We need an example here: f.e.
+ on the 8051 the harmless looking
+\begin_inset Quotes srd
\end_inset
- - will stop global subexpression elimination.
-\layout Itemize
-NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x80;
+\family default
+\begin_inset Quotes sld
\end_inset
- - will stop loop induction optimizations.
-\layout Itemize
-
-NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
-
+ is not atomic if
+\family typewriter
+flags
+\family default
+ resides in xdata.
+ Setting
+\begin_inset Quotes srd
\end_inset
- - will not generate code for boundary value checking, when switch statements
- are turned into jump-tables.
-\layout Itemize
-NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x40;
+\family default
+\begin_inset Quotes sld
\end_inset
- - the compiler will not overlay the parameters and local variables of a
- function.
-\layout Itemize
-
-LESS_PEDANTIC
-\begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
-
+ from within an interrupt routine might get lost if the interrupt occurs
+ at the wrong time.
+
+\begin_inset Quotes sld
\end_inset
- - the compiler will not warn you anymore for obvious mistakes, you'r on
- your own now ;-(
-\layout Itemize
-NOLOOPREVERSE
-\begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
+\family typewriter
+counter\SpecialChar ~
++=\SpecialChar ~
+8;
+\family default
+\begin_inset Quotes srd
\end_inset
- - Will not do loop reversal optimization
-\layout Itemize
+ is not atomic on the 8051 even if
+\family typewriter
+counter
+\family default
+ is located in data memory.
+ Bugs like these are hard to reproduce and can cause a lot of trouble.
+
+\layout Standard
-EXCLUDE
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+The return address and the registers used in the interrupt service routine
+ are saved on the stack
+\begin_inset LatexCommand \index{stack}
\end_inset
- NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
- pair of push/pop
-\begin_inset LatexCommand \index{push/pop}
-
-\end_inset
+ so there must be sufficient stack space.
+ If there isn't variables or registers (or even the return address itself)
+ will be corrupted.
+ This
+\emph on
+stack overflow
+\emph default
- instruction in ISR function (using interrupt
-\begin_inset LatexCommand \index{interrupt}
+\begin_inset LatexCommand \index{stack overflow}
\end_inset
- 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
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+ is most likely to happen if the interrupt occurs during the
+\begin_inset Quotes sld
+\end_inset
+deepest
+\begin_inset Quotes srd
\end_inset
-.
-\layout Itemize
+ subroutine when the stack is already in use for f.e.
+ many return addresses.
+\layout Standard
-NOIV
-\begin_inset LatexCommand \index{\#pragma NOIV}
+A special note here, int (16 bit) and long (32 bit) integer division
+\begin_inset LatexCommand \index{Division}
\end_inset
- - 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
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+, multiplication
+\begin_inset LatexCommand \index{Multiplication}
\end_inset
+ & modulus
+\begin_inset LatexCommand \index{Modulus}
+
+\end_inset
-\begin_inset LatexCommand \index{function prologue}
+ and floating-point
+\begin_inset LatexCommand \index{Floating point support}
\end_inset
- function1[,function2[,function3...]] - The compiler by default uses a caller
- saves convention for register saving across function calls, however this
- can cause unnecessary register pushing & popping when calling small functions
- from larger functions.
- This option can be used to switch off the register saving convention for
- the function names specified.
- The compiler will not save registers when calling these functions, extra
- code need to be manually inserted 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 inter procedural analysis) may be able
- to determine the appropriate scheme to use for each function call.
- If -
+ 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
+ -
\begin_inset ERT
status Collapsed
/
\end_inset
--callee-saves command line option is used, the function names specified
- in #pragma\SpecialChar ~
-CALLEE-SAVES
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
- is appended to the list of functions specified in the 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.
-\layout Verse
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
-\family typewriter
-#pragma SAVE
-\begin_inset LatexCommand \index{\#pragma SAVE}
+\layout Standard
+\backslash
+/
\end_inset
- /* save the current settings */
-\newline
-#pragma NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+-int-long-reent
+\emph default
+
+\begin_inset LatexCommand \index{-\/-int-long-reent}
\end_inset
- /* turnoff global subexpression elimination */
-\newline
-#pragma NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+ compiler option.
+ Note, the type promotion
+\begin_inset LatexCommand \index{type promotion}
\end_inset
- /* turn off induction optimizations */
-\newline
-int foo ()
-\newline
-{
-\newline
-\SpecialChar ~
- \SpecialChar ~
- ...
+ required by ANSI C can cause 16 bit routines to be used without the programmer
+ being aware of it.
+\layout Standard
+
+Calling other functions from an interrupt service routine is not recommended,
+ avoid it if possible.
+ Note that when some function is called from an interrupt service routine
+ it should be preceded by a #pragma\SpecialChar ~
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+
+ if it is not reentrant.
+ Furthermore nonreentrant functions should not be called from the main program
+ while the interrupt service routine might be active.
+ They also must not be called from low priority interrupt service routines
+ while a high priority interrupt service routine might be active.
+ You could use semaphores or make the function
+\emph on
+ critical
+\emph default
+ if all parameters are passed in registers.
\newline
-\SpecialChar ~
- \SpecialChar ~
- /* large code */
+
\newline
+Also see section
+\begin_inset LatexCommand \ref{sub:Overlaying}
+
+\end_inset
+
\SpecialChar ~
- \SpecialChar ~
- ...
-
-\newline
-}
-\newline
-#pragma RESTORE
-\begin_inset LatexCommand \index{\#pragma RESTORE}
+about Overlaying and section
+\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
\end_inset
- /* turn the optimizations back on */
+\SpecialChar ~
+about Functions using private register banks.
+\layout Subsection
+
+MCS51/DS390 Interrupt Service Routines
\layout Standard
-The compiler will generate a warning message when extra space is allocated.
- It is strongly recommended that the SAVE and RESTORE pragma's be used when
- changing options for a function.
-\layout Subsection
+Interrupt numbers and the corresponding address & descriptions for the Standard
+ 8051/8052 are listed below.
+ SDCC will automatically adjust the interrupt vector table to the maximum
+ interrupt number specified.
+\newline
-Library Routines
-\emph on
- <pending: this is messy and incomplete>
-\emph default
-
-\layout Enumerate
+\layout Standard
+\align center
-Compiler support routines (_gptrget, _mulint etc)
-\layout Enumerate
+\begin_inset Tabular
+<lyxtabular version="3" rows="9" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Stdclib functions (puts, printf, strcat etc)
-\layout Enumerate
+\layout Standard
-Math functions (sin, pow, sqrt etc)
-\layout Comment
+Interrupt #
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-license statements for the libraries are missing
-\layout Subsection
+\layout Standard
-Interfacing with Assembly Routines
-\begin_inset LatexCommand \index{Assembler routines}
+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
-\layout Subsubsection
+0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Global Registers used for Parameter Passing
-\begin_inset LatexCommand \index{Parameter passing}
+\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
-The compiler always uses the global registers
-\emph on
-DPL, DPH
-\begin_inset LatexCommand \index{DPTR, DPH, DPL}
+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
-, B
-\begin_inset LatexCommand \index{B (register)}
+\layout Standard
+0x000b
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\emph default
-and
-\emph on
- ACC
-\begin_inset LatexCommand \index{ACC}
+\layout Standard
+2
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\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 -
-\begin_inset ERT
-status Collapsed
+External 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+0x0013
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--stack-auto is used) or in the internal / external ram (depending on the
- memory model).
-
-\layout Subsubsection
+\layout Standard
-Assembler Routine(non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+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
-)
-\begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
+\layout Standard
+0x001b
\end_inset
+</cell>
+</row>
+<row topline="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
-In the following example the function c_func calls an assembler routine
- asm_func, which takes two parameters.
-\layout Verse
+Serial
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\family typewriter
-extern int asm_func(unsigned char, unsigned char);
-\newline
+0x0023
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-int c_func (unsigned char i, unsigned char j)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return asm_func(i,j);
-\newline
-}
-\newline
+\layout Standard
+
+5
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-int main()
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return c_func(10,9);
-\newline
-}
\layout Standard
-The corresponding assembler function is:
-\layout Verse
+Timer 2 (8052)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\family typewriter
-.globl _asm_func_PARM_2
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+0x002b
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+...
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\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" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+n
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0003 + 8*n
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Standard
+
+If the interrupt service routine is defined without
+\emph on
+using
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
+\emph default
+ a register bank or with register bank 0 (
+\emph on
+using
+\emph default
+ 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
+ & psw are saved 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 Subsection
+
+HC08 Interrupt Service Routines
+\layout Standard
+
+Since the number of interrupts available is chip specific and the interrupt
+ vector table always ends at the last byte of memory, the interrupt numbers
+ corresponds to the interrupt vectors in reverse order of address.
+ For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
+ 2 will use the interrupt vector at 0xfffa, and so on.
+ However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
+ this way; instead see section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
+\end_inset
+
+ for details on customizing startup.
+\layout Subsection
+
+Z80 Interrupt Service Routines
+\layout Standard
+
+The Z80 uses several different methods for determining the correct interrupt
+ vector depending on the hardware implementation.
+ Therefore, SDCC ignores the optional interrupt number and does not attempt
+ to generate an interrupt vector table.
+\layout Standard
+
+By default, SDCC generates code for a maskable interrupt, which uses a RETI
+ instruction to return from the interrupt.
+ To write an interrupt handler for the non-maskable interrupt, which needs
+ a RETN instruction instead, add the
+\emph on
+critical
+\emph default
+ keyword:
+\layout Verse
+
+
+\family typewriter
+void nmi_isr (void) critical interrupt
+\newline
+{
+\newline
\SpecialChar ~
\SpecialChar ~
-.globl _asm_func
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Standard
+
+However if you need to create a non-interruptable interrupt service routine
+ you would also require the
+\emph on
+critical
+\emph default
+ keyword.
+ To distinguish between this and an nmi_isr you must provide an interrupt
+ number.
+\layout Section
+
+Enabling and Disabling Interrupts
+\layout Subsection
+
+Critical Functions and Critical Statements
+\layout Standard
+
+A special keyword may be associated with a block or a function declaring
+ it as
+\emph on
+critical
+\emph default
+.
+ SDCC will generate code to disable all interrupts
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ upon entry to a critical function and restore the interrupt enable to the
+ previous state before returning.
+ Nesting critical functions will need one additional byte on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ for each call.
+\layout Verse
+
+
+\family typewriter
+int foo () __critical
+\begin_inset LatexCommand \index{critical}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_critical}
+
+\end_inset
+
+
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-.area OSEG
+...
+
\newline
-_asm_func_PARM_2:
+}
+\layout Standard
+
+The critical attribute maybe used with other attributes like
+\emph on
+reentrant.
+\emph default
+
\newline
+The keyword
+\emph on
+critical
+\emph default
+ may also be used to disable interrupts more locally:
+\layout Verse
+
+
+\family typewriter
+__critical{ i++; }
+\layout Standard
+
+More than one statement could have been included in the block.
+\layout Subsection
+
+Enabling and Disabling Interrupts directly
+\layout Standard
+
+Interrupts
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ can also be disabled and enabled directly (8051):
+\layout Verse
+
+
+\family typewriter
+EA = 0;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-.ds 1
-\newline
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+or:\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-.area CSEG
-\newline
-_asm_func:
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+EA_SAVE = EA;
+\layout Verse
+
+
+\family typewriter
+...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov a,dpl
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,_asm_func_PARM_2
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov dpl,a
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-dpl
-\begin_inset LatexCommand \index{DPTR, DPH, DPL}
+EA = 0;
+\layout Verse
-\end_inset
-,#0x00
-\newline
+\family typewriter
+EA = 1;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ret
-\layout Standard
-
-Note here that the return values are placed in 'dpl' - One byte return value,
- 'dpl' LSB & 'dph' MSB for two byte values.
- 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
-b' & 'acc' for four byte values.
-\layout Standard
-
-The parameter naming convention is _<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 variable name for the second parameter will be _<function_n
-ame>_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
-\begin_inset LatexCommand \index{reentrant}
-
-\end_inset
-
-)
-\begin_inset LatexCommand \index{Assembler routines (reentrant)}
-
-\end_inset
-
-
-\layout Standard
-
-In this case the second parameter onwards will be passed on the stack, the
- parameters are pushed from right to left i.e.
- after the call the left most parameter will be on the top of the stack.
- Here is an example:
-\layout Verse
-
-
-\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
-}
-\layout Standard
-
-The corresponding assembler routine is:
-\layout Verse
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+\layout Verse
\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 ~
+EA = EA_SAVE;
+\layout Standard
+
+On other architectures which have seperate opcodes for enabling and disabling
+ interrupts you might want to make use of defines with inline assembly
+\begin_inset LatexCommand \index{Assembler routines}
+
+\end_inset
+
+ (HC08):
+\layout Verse
+
+
+\family typewriter
+#define CLI _asm
+\begin_inset LatexCommand \index{\_asm}
+
+\end_inset
+
\SpecialChar ~
-pop _bp
-\newline
\SpecialChar ~
+cli\SpecialChar ~
\SpecialChar ~
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+;
+\layout Verse
+
+
+\family typewriter
+#define SEI _asm\SpecialChar ~
\SpecialChar ~
+sei\SpecialChar ~
\SpecialChar ~
-ret
-\layout Standard
+_endasm;
+\layout Verse
-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
-\begin_inset LatexCommand \index{stack}
+\family typewriter
+...
+\layout Standard
+
+Note: it is sometimes sufficient to disable only a specific interrupt source
+ like f.e.
+ a timer or serial interrupt by manipulating an
+\emph on
+interrupt mask
+\begin_inset LatexCommand \index{interrupt mask}
\end_inset
-\begin_inset LatexCommand \index{External stack}
+\emph default
+ register.
+
+\layout Standard
+
+Usually the time during which interrupts are disabled should be kept as
+ short as possible.
+ This minimizes both
+\emph on
+interrupt latency
+\emph default
+
+\begin_inset LatexCommand \index{interrupt latency}
\end_inset
+ (the time between the occurrence of the interrupt and the execution of
+ the first code in the interrupt routine) and
+\emph on
+interrupt jitter
+\emph default
-\layout Standard
+\begin_inset LatexCommand \index{interrupt jitter}
-The external stack is located at the start of the external ram segment,
- and is 256 bytes in size.
- When -
-\begin_inset ERT
-status Collapsed
+\end_inset
+ (the difference between the shortest and the longest interrupt latency).
+ These really are something different, f.e.
+ a serial interrupt has to be served before its buffer overruns so it cares
+ for the maximum interrupt latency, whereas it does not care about jitter.
+ On a loudspeaker driven via a digital to analog converter which is fed
+ by an interrupt a latency of a few milliseconds might be tolerable, whereas
+ a much smaller jitter will be very audible.
\layout Standard
-\backslash
-/
+You can reenable interrupts within an interrupt routine and on some architecture
+s you can make use of two (or more) levels of
+\emph on
+interrupt priorities
+\emph default
+
+\begin_inset LatexCommand \index{interrupt priority}
+
\end_inset
--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 -
-\begin_inset ERT
-status Collapsed
+.
+ On some architectures which don't support interrupt priorities these can
+ be implemented by manipulating the interrupt mask and reenabling interrupts
+ within the interrupt routine.
+ Check there is sufficient space on the stack
+\begin_inset LatexCommand \index{stack}
-\layout Standard
+\end_inset
+
+ and don't add complexity unless you have to.
+
+\layout Subsection
+
+Semaphore
+\begin_inset LatexCommand \index{semaphore}
-\backslash
-/
\end_inset
--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).
+ locking (mcs51/ds390)
\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
-\begin_inset LatexCommand \index{ANSI-compliance}
+Some architectures (mcs51/ds390) have an atomic
+\begin_inset LatexCommand \index{atomic}
\end_inset
+ bit test and
+\emph on
+
+\emph default
+clear
+\emph on
+
+\emph default
+instruction.
+ These type of instructions are typically used in preemptive multitasking
+ systems, where a routine f.e.
+ claims the use of a data structure ('acquires a lock
+\begin_inset LatexCommand \index{lock}
+
+\end_inset
-\layout Standard
+ on it'), makes some modifications and then releases the lock when the data
+ structure is consistent again.
+ The instruction may also be used if interrupt and non-interrupt code have
+ to compete for a resource.
+ With the atomic bit test and clear instruction interrupts
+\begin_inset LatexCommand \index{interrupt}
-Deviations from the compliance:
-\layout Itemize
+\end_inset
-functions are not always reentrant.
-\layout Itemize
+ don't have to be disabled for the locking operation.
+
+\layout Standard
-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.:
-\begin_deeper
+SDCC generates this instruction if the source follows this pattern:
\layout Verse
\family typewriter
-struct s { ...
- };
+volatile
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+ bit resource_is_free;
\newline
-struct s s1, s2;
+
\newline
-foo()
+if (resource_is_free)
\newline
+\SpecialChar ~
+\SpecialChar ~
{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
+resource_is_free=0;
\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) /* invalid in SDCC although allowed in ANSI
- */
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-struct s rets;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
+resource_is_free=1;
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return rets;/* is invalid in SDCC although allowed in ANSI */
-\newline
-}
-\end_deeper
-\layout Itemize
+}
+\layout Standard
-'long long
-\begin_inset LatexCommand \index{long long (not supported)}
+Note, mcs51 and ds390 support only an atomic
+\begin_inset LatexCommand \index{atomic}
\end_inset
-' (64 bit integers
-\begin_inset LatexCommand \index{int (64 bit) (not supported)}
+ bit test and
+\emph on
+clear
+\emph default
+ instruction (as opposed to atomic bit test and
+\emph on
+set).
+\layout Section
+
+Functions using private register banks
+\begin_inset LatexCommand \label{sub:Functions-using-private-banks}
\end_inset
-) not supported.
-\layout Itemize
+ (mcs51/ds390)
+\layout Standard
-'double
-\begin_inset LatexCommand \index{double (not supported)}
+Some architectures have support for quickly changing register sets.
+ SDCC supports this feature with the
+\emph on
+using
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
\end_inset
-' precision floating point
-\begin_inset LatexCommand \index{Floating point support}
-\end_inset
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
-not supported.
-\layout Itemize
+\end_inset
-No support for setjmp and longjmp (for now).
-\layout Itemize
-Old K&R style
-\begin_inset LatexCommand \index{K\&R style}
+\emph default
+ attribute (which tells the compiler to use a register bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
\end_inset
- function declarations are NOT allowed.
-\begin_deeper
-\layout Verse
-
+ other than the default bank zero).
+ It should only be applied to
+\emph on
+interrupt
+\begin_inset LatexCommand \index{interrupt}
-\family typewriter
-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
-}
-\end_deeper
-\layout Itemize
+\end_inset
-functions declared as pointers must be dereferenced during the call.
-\begin_deeper
-\layout Verse
+\emph default
+ functions (see footnote 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
-\family typewriter
-int (*foo)();
-\newline
-...
-
-\newline
-/* has to be called like this */
-\newline
-(*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
-\end_deeper
-\layout Subsection
+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 false
-Cyclomatic Complexity
-\begin_inset LatexCommand \index{Cyclomatic complexity}
+\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
-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
+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
+\begin_inset LatexCommand \index{interrupts}
-\newline
-SDCC uses the following formula to compute the complexity:
-\newline
+\end_inset
-\layout Standard
-complexity = (number of edges in control flow graph) - (number of nodes
- in control flow graph) + 2;
-\newline
+\begin_inset LatexCommand \index{interrupt priority}
-\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
-\pagebreak_top
-TIPS
+\end_inset
+
+ 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
-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
+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 Section
-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
+Startup Code
+\begin_inset LatexCommand \label{sub:Startup-Code}
-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
+\end_inset
-NEVER jump into a LOOP.
-\layout Itemize
-Declare the variables to be local whenever possible, especially loop control
- variables (induction).
-\layout Itemize
+\begin_inset LatexCommand \index{Startup code}
-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
+\end_inset
-Reducing the size of division, multiplication & modulus operations can reduce
- code size substantially.
- Take the following code for example.
-\begin_deeper
-\layout Verse
+\layout Subsection
-\family typewriter
-foobar(unsigned int p1, unsigned char ch)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-unsigned char ch1 = p1 % ch ;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-....
-\newline
-}
+MCS51/DS390 Startup Code
\layout Standard
-For the modulus operation the variable ch will be promoted to unsigned int
- first then the modulus operation will be performed (this will lead to a
- call to support routine _moduint()), and the result will be casted to a
- char.
- If the code is changed to
-\layout Verse
+The compiler inserts a call to the C routine
+\emph on
+_sdcc_external_startup()
+\begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
+\end_inset
-\family typewriter
-foobar(unsigned int p1, unsigned char ch)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-unsigned char ch1 = (unsigned char)p1 % ch ;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-....
-\newline
-}
-\layout Standard
-
-It would substantially reduce the code generated (future versions of the
- compiler will be smart enough to detect such optimization opportunities).
-\end_deeper
-\layout Subsection
-
-Notes on MCS51 memory
-\begin_inset LatexCommand \index{MCS51 memory}
-
-\end_inset
-
- layout
-\layout Standard
-
-The 8051 family of microcontrollers have a minimum of 128 bytes of internal
- RAM memory which is structured as follows
-\newline
-\newline
-- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
+\series bold
+\emph default
-\newline
-- Bytes 20-2F - 16 bytes to hold 128 bit variables and,
-\newline
-- Bytes 30-7F - 80 bytes for general purpose use.
-\newline
+\series default
+at the start of the CODE area.
+ This routine is in the runtime library
+\begin_inset LatexCommand \index{Runtime library}
-\layout Standard
+\end_inset
-Additionally some members of the MCS51 family may have up to 128 bytes of
- additional, indirectly addressable, internal RAM memory (
-\emph on
-idata
-\emph default
-).
- Furthermore, some chips may have some built in external memory (
-\emph on
-xdata
-\emph default
-) which should not be confused with the internal, directly addressable RAM
- memory (
-\emph on
-data
-\emph default
-).
- Usually this built in
+.
+ 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.
+ Otherwise static & global variables will be initialized before the function
+ main is invoked.
+ You could add a
\emph on
-xdata
+_sdcc_external_startup()
\emph default
- memory has to be activated before using it (you can probably find this
- information on the datasheet of the microcontroller your are using).
-\layout Standard
-
-Normally SDCC will only use the first bank
-\begin_inset LatexCommand \index{bank}
-
-\end_inset
-
- of registers (register bank 0), but it is possible to specify that other
- banks of registers should be used in interrupt
-\begin_inset LatexCommand \index{interrupt}
+ 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
+\begin_inset LatexCommand \index{Variable initialization}
\end_inset
- routines.
- By default, the compiler will place the stack after the last byte of allocated
- memory for variables.
- For example, if the first 2 banks of registers are used, and only four
- bytes are used for
-\emph on
-data
-\emph default
- variables, it will position the base of the internal stack at address 20
- (0x14).
- This implies that as the stack
-\begin_inset LatexCommand \index{stack}
+.
+ On some mcs51 variants xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
\end_inset
- grows, it will use up the remaining register banks, and the 16 bytes used
- by the 128 bit variables, and 80 bytes for general purpose use.
- If any bit variables are used, the data variables will be placed after
- the byte holding the last bit variable.
- For example, if register banks 0 and 1 are used, and there are 9 bit variables
- (two bytes used),
+ memory has to be explicitly enabled before it can be accessed or if the
+ watchdog needs to be disabled, this is the place to do it.
+ The startup code clears all internal data memory, 256 bytes by default,
+ but from 0 to n-1 if
\emph on
-data
-\emph default
- variables will be placed starting at address 0x22.
- You can also use -
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--data-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
+-iram-size
+\begin_inset LatexCommand \index{-\/-iram-size <Value>}
\end_inset
- to specify the start address of the
-\emph on
-data
+n
\emph default
- and -
+ is used.
+ (recommended for Chipcon CC1010).
+\layout Standard
+
+See also the compiler option
+\emph on
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--iram-size to specify the size of the total internal RAM (
-\emph on
-data
+-no-xinit
\emph default
-+
+-
\emph on
-idata
+opt
\emph default
-).
-
-\layout Standard
-By default the 8051 linker will place the stack after the last byte of data
- variables.
- Option -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+\begin_inset LatexCommand \index{-\/-no-xinit-opt}
-\backslash
-/
\end_inset
--stack-loc
-\begin_inset LatexCommand \index{-\/-stack-loc}
+ and section
+\begin_inset LatexCommand \ref{sub:MCS51-variants}
\end_inset
- allows you to specify the start of the stack, i.e.
- you could start it after any data in the general purpose area.
- If your microcontroller has additional indirectly addressable internal
- RAM (
-\emph on
-idata
-\emph default
-) you can place the stack on it.
- You may also need to use -
-\begin_inset ERT
-status Collapsed
+\SpecialChar ~
+about MCS51-variants.
+\layout Subsection
+HC08 Startup Code
\layout Standard
-\backslash
-/
-\end_inset
-
--xdata-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
+The HC08 startup code follows the same scheme as the MCS51 startup code.
+\layout Subsection
-\end_inset
+Z80 Startup Code
+\layout Standard
- to set the start address of the external RAM (
+On the Z80 the startup code is inserted by linking with crt0.o which is generated
+ from sdcc/device/lib/z80/crt0.s.
+ If you need a different startup code you can use the compiler option
\emph on
-xdata
+-
+\series bold
\emph default
-) and -
+
\begin_inset ERT
status Collapsed
/
\end_inset
--xram-size
-\begin_inset LatexCommand \index{-\/-data-loc}
+
+\series default
+\emph on
+-no-std-crt0
+\emph default
+
+\begin_inset LatexCommand \index{-\/-no-std-crt0}
\end_inset
- to specify its size.
- Same goes for the code memory, using -
-\begin_inset ERT
-status Collapsed
+ and provide your own crt0.o.
+
+\layout Section
-\layout Standard
+Inline Assembler Code
+\begin_inset LatexCommand \index{Assembler routines}
-\backslash
-/
\end_inset
--code-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
+
+\layout Subsection
+
+A Step by Step Introduction
+\begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
\end_inset
- and -
-\begin_inset ERT
-status Collapsed
\layout Standard
-\backslash
-/
-\end_inset
+Starting from a small snippet of c-code this example shows for the MCS51
+ how to use inline assembly, access variables, a function parameter and
+ an array in xdata memory.
+ The example uses an MCS51 here but is easily adapted for other architectures.
+ This is a buffer routine which should be optimized:
+\layout Verse
--code-size
-\begin_inset LatexCommand \index{-\/-data-loc}
-\end_inset
+\family typewriter
+\size footnotesize
+unsigned char far
+\begin_inset LatexCommand \index{far (storage class)}
-.
- If in doubt, don't specify any options and see if the resulting memory
- layout is appropriate, then you can adjust it.
-\layout Standard
+\end_inset
-The 8051 linker generates two files with memory allocation information.
- The first, with extension .map shows all the variables and segments.
- The second with extension .mem shows the final memory layout.
- The linker will complaint either if memory segments overlap, there is not
- enough memory, or there is not enough space for stack.
- If you get any linking warnings and/or errors related to stack or segments
- allocation, take a look at either the .map or .mem files to find out what
- the problem is.
- The .mem file may even suggest a solution to the problem.
-\layout Subsection
-Tools
-\begin_inset LatexCommand \index{Tools}
+\begin_inset LatexCommand \index{\_\_far (storage class)}
\end_inset
- included in the distribution
-\newline
+ __at
+\begin_inset LatexCommand \index{at}
-\layout Standard
-\align center
+\end_inset
-\begin_inset Tabular
-<lyxtabular version="3" rows="12" 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
+\begin_inset LatexCommand \index{\_\_at}
-Name
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+(0x7f00) buf[0x100];
+\begin_inset LatexCommand \index{Aligned array}
-Purpose
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Directory
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\newline
+unsigned char head, tail;
+\newline
-\layout Standard
+\newline
+void to_buffer( unsigned char c )
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+if( head != (unsigned char)(tail-1) )\SpecialChar ~
+/* cast
+\series bold
+needed
+\series default
+ to avoid promotion
+\begin_inset LatexCommand \index{promotion to signed int}
-uCsim
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Simulator for various architectures
+\begin_inset LatexCommand \index{type promotion}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+ to integer */
+\begin_inset Marginal
+collapsed false
\layout Standard
-sdcc/sim/ucsim
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-keil2sdcc.pl
+\series bold
+!
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-
-header file conversion
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+buf[ head++ ] = c;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* access to a 256 byte aligned array */
+\newline
+}
\layout Standard
-sdcc/support/scripts
+If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
+ then a corresponding buffer.asm file is generated.
+ We define a new function
+\family typewriter
+to_buffer_asm()
+\family default
+ in file buffer.c in which we cut and paste the generated code, removing
+ unwanted comments and some ':'.
+ Then add
+\begin_inset Quotes sld
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-mh2h.c
+_asm
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-header file conversion
+ and
+\begin_inset Quotes sld
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-sdcc/support/scripts
+_endasm;
+\begin_inset Quotes srd
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ to the beginning and the end of the function body:
+\layout Verse
-as-gbz80
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\family typewriter
+\size footnotesize
+/* With a cut and paste from the .asm file, we have something to start with.
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+The function is not yet OK! (registers aren't saved) */
+\newline
+void to_buffer_asm( unsigned char c )
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
+\begin_inset LatexCommand \index{\_asm}
-Assembler
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{\_\_asm}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-as-z80
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+r2,dpl
+\newline
+;buffer.c if( head != (unsigned char)(tail-1) )
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+a,_tail
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dec\SpecialChar ~
+\SpecialChar ~
+a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+r3,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+a,_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+cjne a,ar3,00106$
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
+\newline
+00106$:
+\newline
+;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
+\begin_inset LatexCommand \index{Aligned array}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Assembler
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+r3,_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+inc\SpecialChar ~
+\SpecialChar ~
+_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+dpl,r3
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+dph,#(_buf >> 8)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+a,r2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+movx @dptr,a
+\newline
+00103$:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{\_\_endasm}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+;
+\newline
+}
\layout Standard
-asx8051
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The new file buffer.c should compile with only one warning about the unreferenced
+ function argument 'c'.
+ Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
+ (1) and finally have:
+\layout Verse
-\layout Standard
-Assembler
+\family typewriter
+\size footnotesize
+unsigned char far __at(0x7f00) buf[0x100];
+\newline
+unsigned char head, tail;
+\newline
+#define USE_ASSEMBLY (1)
+\newline
+
+\newline
+#if !USE_ASSEMBLY
+\newline
+
+\newline
+void to_buffer( unsigned char c )
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+if( head != (unsigned char)(tail-1) )
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+buf[ head++ ] = c;
+\newline
+}
+\newline
+
+\newline
+#else
+\newline
+
+\newline
+void to_buffer( unsigned char c )
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+c; // to avoid warning: unreferenced function argument
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
+\begin_inset LatexCommand \index{\_asm}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{\_\_asm}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-sdcdb
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; save used registers here.
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; If we were still using r2,r3 we would have to push them here.
+
+\newline
+; if( head != (unsigned char)(tail-1) )
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+ a,_tail
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dec\SpecialChar ~
+ a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+xrl\SpecialChar ~
+ a,_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+jz\SpecialChar ~
+\SpecialChar ~
+ t_b_end$
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+;
+\newline
+; buf[ head++ ] = c;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+ a,dpl \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; dpl holds lower byte of function argument
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+ dpl,_head \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; buf is 0x100 byte aligned so head can be used directly
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+ dph,#(_buf>>8)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+movx @dptr,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+inc \SpecialChar ~
+_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
+\newline
+t_b_end$:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; restore used registers here
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Simulator
+\begin_inset LatexCommand \index{\_\_endasm}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+;
+\newline
+}
+\newline
+#endif
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The inline assembler code can contain any valid code understood by the assembler
+, this includes any assembler directives and comment lines
+\begin_inset Foot
+collapsed false
\layout Standard
-aslink
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+The assembler does not like some characters like ':' or ''' in comments.
+ You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
+\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
-Linker
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{Assembler documentation}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-link-z80
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+ The compiler does not do any validation of the code within the
+\family typewriter
+_asm
+\begin_inset LatexCommand \index{\_asm}
-Linker
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{\_\_asm}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ ...
+ _endasm
+\size footnotesize
+
+\begin_inset LatexCommand \index{\_endasm}
-link-gbz80
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Linker
+\begin_inset LatexCommand \index{\_\_endasm}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\size default
+;
+\family default
+ keyword pair.
+ Specifically it will not know which registers are used and thus register
+ pushing/popping
+\begin_inset LatexCommand \index{push/pop}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ has to be done manually.
+
\layout Standard
-packihx
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+It is recommended that each assembly instruction (including labels) be placed
+ in a separate line (as the example shows).
+ When the -
+\begin_inset ERT
+status Collapsed
\layout Standard
-ihx packer
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+-
+\emph on
+peep-asm
+\begin_inset LatexCommand \index{-\/-peep-asm}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-</lyxtabular>
-\end_inset
+\emph default
+ command line option is used, the inline assembler code will be passed through
+ the peephole optimizer
+\begin_inset LatexCommand \index{Peephole optimizer}
-\newline
+\end_inset
+.
+ There are only a few (if any) cases where this option makes sense, it might
+ cause some unexpected changes in the inline assembler code.
+ Please go through the peephole optimizer rules defined in file
+\emph on
+SDCCpeeph.def
+\emph default
+ before using this option.
\layout Subsection
-Related open source tools
-\begin_inset LatexCommand \index{Related tools}
+Naked Functions
+\begin_inset LatexCommand \label{sub:Naked-Functions}
\end_inset
-\newline
-
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="8" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="block" valignment="top" leftline="true" width="30line%">
-<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
+\begin_inset LatexCommand \index{Naked functions}
-Name
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-Purpose
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
\layout Standard
-Where to get
+A special keyword may be associated with a function declaring it as
+\emph on
+_naked
+\begin_inset LatexCommand \index{\_naked}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-gpsim
-\begin_inset LatexCommand \index{gpsim}
+\begin_inset LatexCommand \index{\_\_naked}
\end_inset
+.
+
+\emph default
+The
+\emph on
+_naked
+\emph default
+ function modifier attribute prevents the compiler from generating prologue
+\begin_inset LatexCommand \index{function prologue}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ and epilogue
+\begin_inset LatexCommand \index{function epilogue}
-PIC simulator
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+ 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:
+\layout Verse
-\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
-
-\end_inset
+\family typewriter
+volatile
+\begin_inset LatexCommand \index{volatile}
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-flP5
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ data unsigned char counter;
+\newline
-\layout Standard
+\newline
+void simpleInterrupt(void) __interrupt
+\begin_inset LatexCommand \index{interrupt}
-PIC programmer
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
+\begin_inset LatexCommand \index{\_\_interrupt}
\end_inset
-
+ (1)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+counter++;
+\newline
+}
+\newline
+
+\newline
+void nakedInterrupt(void) __interrupt (2) __naked
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
+\begin_inset LatexCommand \index{\_asm}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-srecord
-\begin_inset LatexCommand \index{srecord}
+\begin_inset LatexCommand \index{\_\_asm}
\end_inset
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+inc\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_counter ; does not change flags, no need to save psw
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+reti\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; MUST explicitly include ret or reti in _naked function.
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Object file conversion, checksumming, ...
+\begin_inset LatexCommand \index{\_\_endasm}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+;
+\newline
+}
\layout Standard
+For an 8051 target, the generated simpleInterrupt looks like:
+\layout Verse
-\begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
-\end_inset
+\family typewriter
+Note, this is an
+\series bold
+outdated
+\series default
+ example, recent versions of SDCC generate
+\newline
+the same code for simpleInterrupt() and nakedInterrupt()!
+\newline
+
+\newline
+_simpleInterrupt:
+\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
+\layout Standard
+whereas nakedInterrupt looks like:
+\layout Verse
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+_nakedInterrupt:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+inc\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_counter ; does not change flags, no need to save psw
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+reti\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; MUST explicitly include ret or reti in _naked function
\layout Standard
-objdump
-\begin_inset LatexCommand \index{objdump}
+The related directive #pragma exclude
+\begin_inset LatexCommand \index{\#pragma exclude}
\end_inset
+ allows a more fine grained control over pushing & popping
+\begin_inset LatexCommand \index{push/pop}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ the registers.
\layout Standard
-Object file conversion, ...
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+While there is nothing preventing you from writing C code inside a
+\family typewriter
+_naked
+\family default
+ 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
+Use of Labels within Inline Assembler
\layout Standard
-Part of binutils (should be there anyway)
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+SDCC allows the use of in-line assembler with a few restrictions regarding
+ labels.
+ In older versions of the compiler all labels defined within inline assembler
+ code
+\emph on
+had 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
+.
+
+\layout Verse
-\layout Standard
-doxygen
-\begin_inset LatexCommand \index{doxygen}
+\family typewriter
+_asm
+\begin_inset LatexCommand \index{\_asm}
\end_inset
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+\begin_inset LatexCommand \index{\_\_asm}
-Source code documentation system
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-\begin_inset LatexCommand \url{http://www.doxygen.org}
+
+\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
+\begin_inset LatexCommand \index{\_endasm}
\end_inset
+\begin_inset LatexCommand \index{\_\_endasm}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ ;
\layout Standard
-splint
-\begin_inset LatexCommand \index{splint}
+Inline assembler code cannot reference any C-Labels, however it can reference
+ labels
+\begin_inset LatexCommand \index{Labels}
\end_inset
+ defined by the inline assembler, e.g.:
+\layout Verse
+
+
+\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 referenced by inline assembler only)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Statically checks c sources
+\begin_inset LatexCommand \index{\_\_endasm}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+ ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* some more c code */
+\newline
+}
\layout Standard
+In other words inline assembly code can access labels defined in inline
+ assembly within the scope of the function.
+ The same goes the other way, i.e.
+ labels defines in inline assembly can not be accessed by C statements.
+\layout Section
-\begin_inset LatexCommand \url{http://www.splint.org}
+Interfacing with Assembler Code
+\begin_inset LatexCommand \index{Assembler routines}
\end_inset
+\layout Subsection
+
+Global Registers used for Parameter Passing
+\begin_inset LatexCommand \index{Parameter passing}
+
\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
-ddd
-\begin_inset LatexCommand \index{ddd}
+The compiler always uses the global registers
+\emph on
+DPL, DPH
+\begin_inset LatexCommand \index{DPTR, DPH, DPL}
\end_inset
+\begin_inset LatexCommand \index{DPTR}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+, B
+\begin_inset LatexCommand \index{B (mcs51, ds390 register)}
-Debugger, serves nicely as GUI to sdcdb
-\begin_inset LatexCommand \index{sdcdb}
+\end_inset
+
+
+\emph default
+and
+\emph on
+ ACC
+\begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
\end_inset
-\begin_inset Foot
-collapsed false
+\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 -
+\begin_inset ERT
+status Collapsed
\layout Standard
-(sdcdb and ddd are available for Unix only)
+\backslash
+/
\end_inset
+-stack-auto is used) or in data / xdata memory (depending on the memory
+ model).
+
+\layout Subsection
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
+Assembler Routine (non-reentrant)
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
+In the following example
+\begin_inset LatexCommand \index{reentrant}
\end_inset
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+\begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
\end_inset
+ the function c_func calls an assembler routine asm_func, which takes two
+ parameters
+\begin_inset LatexCommand \index{function parameter}
-\newline
+\end_inset
-\layout Subsection
+.
+\layout Verse
-Related documentation / recommended reading
-\newline
-\layout Standard
-\align center
+\family typewriter
+extern int asm_func(unsigned char, unsigned char);
+\newline
-\begin_inset Tabular
-<lyxtabular version="3" rows="5" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="block" valignment="top" leftline="true" width="30line%">
-<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
+\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
+}
\layout Standard
-Name
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+The corresponding assembler function is:
+\layout Verse
-Subject / Title
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\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\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+a,dpl
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+a,_asm_func_PARM_2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dph
+\begin_inset LatexCommand \index{DPTR, DPH, DPL}
-Where to get
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
\layout Standard
-S.
- S.
- Muchnick
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+Note here that the return values
+\begin_inset LatexCommand \index{return value}
-Advanced Compiler Design and Implementation
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+ 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
-bookstore
+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
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+dpl
+\begin_inset Quotes erd
+\end_inset
+ for a one byte parameter,
+\begin_inset Quotes eld
+\end_inset
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-c-refcard.pdf
+dptr
+\begin_inset Quotes erd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ for two bytes,
+\begin_inset Quotes eld
+\end_inset
-C Reference Card
-\begin_inset LatexCommand \index{C Reference card}
+b,dptr
+\begin_inset Quotes erd
+\end_inset
+ for three bytes and
+\begin_inset Quotes eld
\end_inset
-, 2 pages
+acc,b,dptr
+\begin_inset Quotes erd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ for a four bytes parameter.
+ The variable name for the second parameter will be _<function_name>_PARM_2.
+\newline
+\newline
+Assemble the assembler routine with the following command:
+\newline
-\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
+\newline
-\end_inset
+\family sans
+\series bold
+asx8051 -losg asmfunc.asm
+\newline
+\newline
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family default
+\series default
+Then compile and link the assembler routine to the C source file with the
+ following command:
+\newline
-\layout Standard
+\newline
-test_suite_spec.pdf
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family sans
+\series bold
+sdcc cfunc.c asmfunc.rel
+\layout Subsection
+Assembler Routine (reentrant)
\layout Standard
-sdcc regression test
-\begin_inset LatexCommand \index{Regression test}
+In this case
+\begin_inset LatexCommand \index{reentrant}
\end_inset
+\begin_inset LatexCommand \index{Assembler routines (reentrant)}
+
+\end_inset
+
+ the second parameter
+\begin_inset LatexCommand \index{function parameter}
+
+\end_inset
+
+ onwards will be passed on the stack, the parameters are pushed from right
+ to left i.e.
+ after the call the leftmost parameter will be on the top of the stack.
+ Here is an example:
+\layout Verse
+
+
+\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
+}
+\layout Standard
+
+The corresponding assembler routine is:
+\layout Verse
+
+
+\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 ~
+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
+\layout Standard
+
+The compiling and linking procedure remains the same, however note the extra
+ entry & exit linkage required for the assembler code, _bp is the stack
+ frame pointer and is used to compute the offset into the stack for parameters
+ and local variables.
+\layout Section
+
+int (16 bit)
+\begin_inset LatexCommand \index{int (16 bit)}
+
+\end_inset
+
+ and long (32 bit)
+\begin_inset LatexCommand \index{long (32 bit)}
+
+\end_inset
+
+ 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 optimizations are
+ used.
+ The following files contain the described routines, all of them can be
+ found in <installdir>/share/sdcc/lib.
+\newline
+
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Function
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/doc
+
+\series bold
+Description
\end_inset
</cell>
</row>
-<row topline="true" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
+_mulint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-cdbfileformat.pd
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color default
-f
+\layout Standard
+
+16 bit multiplication
\end_inset
</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-sdcc internal documentation
+_divsint.c
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/doc
+ signed 16 bit division (calls _divuint)
\end_inset
</cell>
</row>
-</lyxtabular>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+
+_divuint.c
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\newline
+ unsigned 16 bit division
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\layout Section
-\pagebreak_top
-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.
+_modsint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+signed 16 bit modulus (calls _moduint)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_moduint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+unsigned 16 bit modulus
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_mullong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+32 bit multiplication
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_divslong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ signed 32 division (calls _divulong)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_divulong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+unsigned 32 division
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_modslong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ signed 32 bit modulus (calls _modulong)
+\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
+
+_modulong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+unsigned 32 bit modulus
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Standard
+
+Since they are compiled as
+\emph on
+non-reentrant
+\emph default
+
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+, interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ 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
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+
+\emph default
+ option, after which the source program will have to be compiled with
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-int-long-reent
+\begin_inset LatexCommand \index{-\/-int-long-reent}
+
+\end_inset
+
+
+\emph default
+ option.
+ Notice that you don't have to call these routines directly.
+ The compiler will use them automatically every time an integer operation
+ is required.
+\layout Section
+
+Floating Point Support
+\begin_inset LatexCommand \index{Floating point support}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
+ floating point support routines are derived from gcc's floatlib.c and consist
+ of the following routines:
+\newline
+
+\layout Standard
+\align center
+
+\size footnotesize
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="17" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+Function
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fsadd.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+add floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fssub.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+subtract floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fsdiv.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+divide floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fsmul.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+multiply floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2uchar.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert floating point to unsigned char
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2char.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert floating point to signed char
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2uint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert floating point to unsigned int
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2int.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert floating point to signed int
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2ulong.
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert floating point to unsigned long
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2long.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert floating point to signed long
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_uchar2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert unsigned char to floating point
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_char2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert char to floating point number
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_uint2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert unsigned int to floating point
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_int2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert int to floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_ulong2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert unsigned long to floating point number
+\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
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_long2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert long to floating point number
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Standard
+
+These support routines are developed in ANSI-C so there is room for space
+ and speed improvement
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+These floating point routines (
+\emph on
+not
+\emph default
+ sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
+
+\end_inset
+
+.
+ Note if all these routines are used simultaneously the data space might
+ overflow.
+ For serious floating point usage the large model might be needed.
+ Also notice that you don't have to call this routines directly.
+ The compiler will use them automatically every time a floating point operation
+ is required.
+\layout Section
+
+Library Routines
+\begin_inset LatexCommand \index{Libraries}
+
+\end_inset
+
+
+\layout Standard
+
+
+\emph on
+<pending: this is messy and incomplete - a little more information is in
+ sdcc/doc/libdoc.txt
+\emph default
+ >
+\layout Subsection
+
+Compiler support routines (_gptrget, _mulint etc.)
+\layout Subsection
+
+Stdclib functions (puts, printf, strcat etc.)
+\layout Subsubsection
+
+<stdio.h>
+\layout Standard
+
+
+\begin_inset LatexCommand \index{<stdio.h>}
+
+\end_inset
+
+As usual on embedded systems you have to provide your own
+\family typewriter
+getchar()
+\begin_inset LatexCommand \index{getchar()}
+
+\end_inset
+
+
+\family default
+and
+\family typewriter
+putchar()
+\begin_inset LatexCommand \index{putchar()}
+
+\end_inset
+
+
+\family default
+ routines.
+ SDCC does not know whether the system connects to a serial line with or
+ without handshake, LCD, keyboard or other device.
+ And whether a
+\family typewriter
+lf
+\family default
+ to
+\family typewriter
+crlf
+\family default
+ conversion within
+\family typewriter
+putchar()
+\family default
+ is intended.
+ You'll find examples for serial routines f.e.
+ in sdcc/device/lib.
+\layout Standard
+
+The default
+\family typewriter
+ printf()
+\begin_inset LatexCommand \index{printf()}
+
+\end_inset
+
+
+\family default
+implementation in
+\family typewriter
+ printf_large.c
+\family default
+ does not support float (except on ds390).
+ To enable this recompile it with the option
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+DUSE_FLOATS=1
+\begin_inset LatexCommand \index{USE\_FLOATS}
+
+\end_inset
+
+
+\emph default
+ on the command line.
+ Use
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-large
+\begin_inset LatexCommand \index{-\/-model-large}
+
+\end_inset
+
+
+\emph default
+ for the mcs51 port, since this uses a lot of memory.
+\layout Standard
+
+If you're short on memory you might want to use
+\family typewriter
+printf_small()
+\begin_inset LatexCommand \index{printf\_small()}
+
+\end_inset
+
+
+\family default
+
+\emph on
+instead
+\emph default
+ of
+\family typewriter
+ printf().
+
+\family default
+ For the mcs51 there additionally are assembly versions
+\family typewriter
+printf_tiny()
+\begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
+
+\end_inset
+
+
+\family default
+ (subset of printf using less than 270 bytes) and
+\family typewriter
+printf_fast()
+\begin_inset LatexCommand \index{printf\_fast() (mcs51)}
+
+\end_inset
+
+
+\family default
+and
+\family typewriter
+ printf_fast_f()
+\begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
+
+\end_inset
+
+
+\family default
+ (floating-point aware version of printf_fast) which should fit the requirements
+ of many embedded systems (printf_fast() can be customized by unsetting
+ #defines to
+\emph on
+not
+\emph default
+ support long variables and field widths).
+\layout Subsection
+
+Math functions (sinf, powf, sqrtf etc.)
+\layout Subsubsection
+
+<math.h>
+\layout Standard
+
+See definitions in file <math.h>.
+\layout Subsection
+
+Other libraries
+\layout Standard
+
+Libraries
+\begin_inset LatexCommand \index{Libraries}
+
+\end_inset
+
+ included in SDCC should have a license at least as liberal as the GNU Lesser
+ General Public License
+\begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
+
+\end_inset
+
+
+\emph on
+LGPL
+\emph default
+.
+\layout Comment
+
+license statements for the libraries are missing.
+ sdcc/device/lib/ser_ir.c
+\layout Comment
+
+or _decdptr f.e.
+ come with a GPL (as opposed to LGPL) License - this will not be liberal
+ enough for many embedded programmers.
+\layout Standard
+
+If you have ported some library or want to share experience about some code
+ which f.e.
+ falls into any of these categories Busses (I
+\begin_inset Formula $^{\textrm{2}}$
+\end_inset
+
+C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
+ cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
+ Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
+\begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
+
+\end_inset
+
+\SpecialChar ~
+would certainly like to hear about it.
+ Programmers coding for embedded systems are not especially famous for being
+ enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
+e these references are very valuable.
+ Let's help to create a climate where information is shared.
+\layout Section
+
+Memory Models
+\layout Subsection
+
+MCS51 Memory Models
+\begin_inset LatexCommand \index{Memory model}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{MCS51 memory model}
+
+\end_inset
+
+
+\layout Subsubsection
+
+Small, Medium and Large
+\layout Standard
+
+SDCC allows three memory models for MCS51 code,
+\shape slanted
+small, medium
+\shape default
+ and
+\shape slanted
+large
+\shape default
+.
+ 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 small,
+ medium and large.
+ The compiled library modules are contained in separate directories as small,
+ medium and large so that you can link to the appropriate set.
+\layout Standard
+
+When the medium or 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
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ 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 recommended that the small model be used unless
+ absolutely required.
+\layout Subsubsection
+
+External Stack
+\begin_inset LatexCommand \label{sub:External-Stack}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{External stack (mcs51)}
+
+\end_inset
+
+
+\layout Standard
+
+The external stack (-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xstack option
+\begin_inset LatexCommand \index{-\/-xstack}
+
+\end_inset
+
+) is located in pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ memory (usually at the start of the external ram segment) and uses all
+ unused space in pdata (max.
+ 256 bytes).
+ When -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xstack option is used to compile the program, the parameters and local
+ variables
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+ of all reentrant functions are allocated in this area.
+ This option is provided for programs with large stack space requirements.
+ When used with the -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+ option, all parameters and local variables are allocated on the external
+ stack (note: support libraries will need to be recompiled with the same
+ options.
+ There is a predefined target in the library makefile).
+\layout Standard
+
+The compiler outputs the higher order address byte of the external ram segment
+ into port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
+
+\end_inset
+
+ (see also section
+\begin_inset LatexCommand \ref{sub:MCS51-variants}
+
+\end_inset
+
+), therefore when using the External Stack option, this port
+\emph on
+may not
+\emph default
+ be used by the application program.
+\layout Subsection
+
+DS390 Memory Model
+\begin_inset LatexCommand \index{Memory model}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{DS390 memory model}
+
+\end_inset
+
+
+\layout Standard
+
+The only model supported is Flat 24
+\begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
+
+\end_inset
+
+.
+ 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
+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
+
+\begin_inset LatexCommand \index{Tinibios (DS390)}
+
+\end_inset
+
+, 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
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-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
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-*-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 Section
+
+Pragmas
+\begin_inset LatexCommand \index{Pragmas}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC supports the following #pragma directives:
+\layout Itemize
+
+save
+\begin_inset LatexCommand \index{\#pragma save}
+
+\end_inset
+
+ - this will save all current options to the save/restore stack.
+ See #pragma\SpecialChar ~
+restore.
+\layout Itemize
+
+restore
+\begin_inset LatexCommand \index{\#pragma restore}
+
+\end_inset
+
+ - will restore saved options from the last save.
+ saves & restores can be nested.
+ SDCC uses a save/restore stack: save pushes current options to the stack,
+ restore pulls current options from the stack.
+ See #pragma\SpecialChar ~
+save.
+\newline
+
+\layout Itemize
+
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{function prologue}
+
+\end_inset
+
+ function1[,function2[,function3...]] - The compiler by default uses a caller
+ saves convention for register saving across function calls, however this
+ can cause unnecessary register pushing & popping
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
+
+ when calling small functions from larger functions.
+ This option can be used to switch off the register saving convention for
+ the function names specified.
+ The compiler will not save registers when calling these functions, extra
+ code need to be manually inserted 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 inter procedural analysis) may be able
+ to determine the appropriate scheme to use for each function call.
+ If -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-callee-saves command line option is used, the function names specified
+ in #pragma\SpecialChar ~
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
+
+\end_inset
+
+ is appended to the list of functions specified in the command line.
+\layout Itemize
+
+exclude
+\begin_inset LatexCommand \index{\#pragma exclude}
+
+\end_inset
+
+ none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
+ of pairs of push/pop
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
+
+ instructions in
+\emph on
+I
+\emph default
+nterrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\emph on
+S
+\emph default
+ervice
+\emph on
+R
+\emph default
+outines.
+ 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
+\begin_inset LatexCommand \index{\#pragma exclude}
+
+\end_inset
+
+.
+ See also the related keyword _naked
+\begin_inset LatexCommand \index{\_naked}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_naked}
+
+\end_inset
+
+.
+\layout Itemize
+
+less_pedantic
+\begin_inset LatexCommand \index{\#pragma less\_pedantic}
+
+\end_inset
+
+ - the compiler will not warn you anymore for obvious mistakes, you'r on
+ your own now ;-(
+\layout Itemize
+
+disable_warning <nnnn>
+\begin_inset LatexCommand \index{\#pragma disable\_warning}
+
+\end_inset
+
+ - the compiler will not warn you anymore about warning number <nnnn>.
+\layout Itemize
+
+nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
+
+\end_inset
+
+ - will stop global common subexpression elimination.
+\layout Itemize
+
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+
+\end_inset
+
+ - will stop loop induction optimizations.
+\layout Itemize
+
+noinvariant
+\begin_inset LatexCommand \index{\#pragma noinvariant}
+
+\end_inset
+
+ - will not do loop invariant optimizations.
+ For more details see Loop Invariants in section
+\begin_inset LatexCommand \ref{sub:Loop-Optimizations}
+
+\end_inset
+
+.
+\layout Itemize
+
+noiv
+\begin_inset LatexCommand \index{\#pragma noiv}
+
+\end_inset
+
+ - Do not generate interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ 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).
+ More elegantly this can be achieved by obmitting the optional interrupt
+ number after the interrupt keyword, see section
+\begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
+
+\end_inset
+
+\SpecialChar ~
+about interrupts.
+\layout Itemize
+
+nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
+
+\end_inset
+
+ - will not generate code for boundary value checking, when switch statements
+ are turned into jump-tables (dangerous).
+ For more details see section
+\begin_inset LatexCommand \ref{sub:'switch'-Statements}
+
+\end_inset
+
+.
+\layout Itemize
+
+noloopreverse
+\begin_inset LatexCommand \index{\#pragma noloopreverse}
+
+\end_inset
+
+ - Will not do loop reversal optimization
+\layout Itemize
+
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+
+ - the compiler will not overlay the parameters and local variables of a
+ function.
+\layout Itemize
+
+stackauto
+\begin_inset LatexCommand \index{\#pragma stackauto}
+
+\end_inset
+
+- See option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+ and section
+\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+ Parameters and Local Variables.
+\layout Itemize
+
+opt_code_speed
+\begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
+
+\end_inset
+
+- The compiler will optimize code generation towards fast code, possibly
+ at the expense of code size.
+\layout Itemize
+
+opt_code_size
+\begin_inset LatexCommand \index{\#pragma opt\_code\_size}
+
+\end_inset
+
+- The compiler will optimize code generation towards compact code, possibly
+ at the expense of code speed.
+\layout Itemize
+
+opt_code_balanced
+\begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
+
+\end_inset
+
+- The compiler will attempt to generate code that is both compact and fast,
+ as long as meeting one goal is not a detriment to the other (this is the
+ default).
+
+\layout Itemize
+
+std_sdcc89
+\begin_inset LatexCommand \index{\#pragma std\_sdcc89}
+
+\end_inset
+
+- Generally follow the C89 standard, but allow SDCC features that conflict
+ with the standard (default).
+\layout Itemize
+
+std_c89
+\begin_inset LatexCommand \index{\#pragma std\_c89}
+
+\end_inset
+
+- Follow the C89 standard and disable SDCC features that conflict with the
+ standard.
+\layout Itemize
+
+std_sdcc99
+\begin_inset LatexCommand \index{\#pragma std\_sdcc99}
+
+\end_inset
+
+- Generally follow the C99 standard, but allow SDCC features that conflict
+ with the standard (incomplete support).
+\layout Itemize
+
+std_c99
+\begin_inset LatexCommand \index{\#pragma std\_c99}
+
+\end_inset
+
+- Follow the C99 standard and disable SDCC features that conflict with the
+ standard (incomplete support).
+\layout Itemize
+
+codeseg <name>
+\begin_inset LatexCommand \index{\#pragma codeseg}
+
+\end_inset
+
+- Use this name (max.
+ 8 characters) for the code segment.
+ See option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-codeseg.
+\layout Itemize
+
+constseg <name>
+\begin_inset LatexCommand \index{\#pragma constseg}
+
+\end_inset
+
+- Use this name (max.
+ 8 characters) for the const segment.
+ See option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-constseg.
+\layout Standard
+
+SDCPP supports the following #pragma directives:
+\layout Itemize
+
+preproc_asm
+\begin_inset LatexCommand \index{\#pragma preproc\_asm}
+
+\end_inset
+
+ (+ | -) - switch _asm _endasm block preprocessing on / off.
+ Default is on.
+\layout Standard
+
+The pragma's are intended to be used to turn-on or 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.
+\layout Verse
+
+
+\family typewriter
+#pragma save
+\begin_inset LatexCommand \index{\#pragma save}
+
+\end_inset
+
+ \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* save the current settings */
+\newline
+#pragma nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
+
+\end_inset
+
+ \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* turnoff global subexpression elimination */
+\newline
+#pragma noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+
+\end_inset
+
+ /* turn off induction optimizations */
+\newline
+int foo ()
+\newline
+{
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ /* large code */
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+}
+\newline
+#pragma restore
+\begin_inset LatexCommand \index{\#pragma restore}
+
+\end_inset
+
+ /* turn the optimizations back on */
+\layout Standard
+
+The compiler will generate a warning message when extra space is allocated.
+ It is strongly recommended that the save and restore pragma's be used when
+ changing options for a function.
+\layout Section
+
+Defines Created by the Compiler
+\layout Standard
+
+The compiler creates the following #defines
+\begin_inset LatexCommand \index{\#defines}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Defines created by the compiler}
+
+\end_inset
+
+:
+\newline
+
+\layout Standard
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+#define
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC
+\begin_inset LatexCommand \index{SDCC}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Always defined.
+ Since version 2.5.6 the version number as an int (ex.
+ 256)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_mcs51
+\begin_inset LatexCommand \index{SDCC\_mcs51}
+
+\end_inset
+
+ or SDCC_ds390
+\begin_inset LatexCommand \index{SDCC\_ds390}
+
+\end_inset
+
+ or SDCC_z80
+\begin_inset LatexCommand \index{SDCC\_z80}
+
+\end_inset
+
+, etc
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+depending on the model used (e.g.: -mds390
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+__mcs51
+\begin_inset LatexCommand \index{\_\_mcs51}
+
+\end_inset
+
+, __ds390
+\begin_inset LatexCommand \index{\_\_ds390}
+
+\end_inset
+
+, __hc08
+\begin_inset LatexCommand \index{\_\_hc08}
+
+\end_inset
+
+, __z80
+\begin_inset LatexCommand \index{\_\_z80}
+
+\end_inset
+
+, etc
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+depending on the model used (e.g.
+ -mz80)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_STACK_AUTO
+\begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\emph default
+ option is used
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_MODEL_SMALL
+\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-small
+\emph default
+ is used
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_MODEL_MEDIUM
+\begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-medium
+\emph default
+ is used
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_MODEL_LARGE
+\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-large
+\emph default
+ is used
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_USE_XSTACK
+\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xstack
+\emph default
+ option is used
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_STACK_TENBIT
+\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-mds390
+\emph default
+ is used
+\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
+
+SDCC_MODEL_FLAT24
+\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-mds390
+\emph default
+ is used
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Chapter
+
+Notes on supported Processors
+\layout Section
+
+MCS51 variants
+\begin_inset LatexCommand \label{sub:MCS51-variants}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{MCS51 variants}
+
+\end_inset
+
+
+\layout Standard
+
+MCS51 processors are available from many vendors and come in many different
+ flavours.
+ While they might differ considerably in respect to Special Function Registers
+ the core MCS51 is usually not modified or is kept compatible.
+
+\layout Subsection
+
+pdata access by SFR
+\layout Standard
+
+With the upcome of devices with internal xdata and flash memory devices
+ using port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
+
+\end_inset
+
+ as dedicated I/O port is becoming more popular.
+ Switching the high byte for pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ access which was formerly done by port P2 is then achieved by a Special
+ Function Register
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+.
+ In well-established MCS51 tradition the address of this
+\emph on
+sfr
+\emph default
+ is where the chip designers decided to put it.
+ Needless to say that they didn't agree on a common name either.
+ So that the startup code can correctly initialize xdata variables, you
+ should define an sfr with the name _XPAGE
+\family typewriter
+
+\begin_inset LatexCommand \index{\_XPAGE (mcs51)}
+
+\end_inset
+
+
+\family default
+ at the appropriate location if the default, port P2, is not used for this.
+ Some examples are:
+\layout Verse
+
+
+\family typewriter
+sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
+\layout Verse
+
+
+\family typewriter
+sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
+\layout Verse
+
+
+\family typewriter
+sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
+\layout Standard
+
+For more exotic implementations further customizations may be needed.
+ See section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
+\end_inset
+
+ for other possibilities.
+\layout Subsection
+
+Other Features available by SFR
+\layout Standard
+
+Some MCS51 variants offer features like Double DPTR
+\begin_inset LatexCommand \index{DPTR}
+
+\end_inset
+
+, multiple DPTR, decrementing DPTR, 16x16 Multiply.
+ These are currently not used for the MCS51 port.
+ If you absolutely need them you can fall back to inline assembly or submit
+ a patch to SDCC.
+\layout Section
+
+DS400 port
+\layout Standard
+
+The DS80C400 microcontroller has a rich set of peripherals.
+ In its built-in ROM library it includes functions to access some of the
+ features, among them is a TCP stack with IP4 and IP6 support.
+ Library headers (currently in beta status) and other files are provided
+ at
+\size footnotesize
+
+\begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
+
+\end_inset
+
+.
+
+\layout Section
+
+The Z80 and gbz80 port
+\layout Standard
+
+SDCC can target both the Zilog
+\begin_inset LatexCommand \index{Z80}
+
+\end_inset
+
+ and the Nintendo Gameboy's Z80-like gbz80
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
+
+\end_inset
+
+.
+ The Z80 port is passed through the same
+\emph on
+regressions tests
+\begin_inset LatexCommand \index{Regression test}
+
+\end_inset
+
+
+\emph default
+ as the MCS51 and DS390 ports, so floating point support, support for long
+ variables and bitfield support is fine.
+ See mailing lists and forums about interrupt routines.
+\layout Standard
+
+As always, the code is the authoritative reference - see z80/ralloc.c and
+ z80/gen.c.
+ The stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ frame is similar to that generated by the IAR Z80 compiler.
+ IX is used as the base pointer, HL and IY are used as a temporary registers,
+ and BC and DE are available for holding variables.
+ Return values
+\begin_inset LatexCommand \index{return value}
+
+\end_inset
+
+ for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
+ bytes).
+ The gbz80 port use the same set of registers for the return values, but
+ in a different order of significance: E (one byte), DE (two bytes), or
+ HLDE (four bytes).
+\layout Section
+
+The HC08 port
+\layout Standard
+
+The port to the Motorola HC08
+\begin_inset LatexCommand \index{HC08}
+
+\end_inset
+
+ family has been added in October 2003, and is still undergoing some basic
+ development.
+ The code generator is complete, but the register allocation is still quite
+ unoptimized.
+ Some of the SDCC's standard C library functions have embedded non-HC08
+ inline assembly and so are not yet usable.
+\newline
+
+\newline
+
+\layout Section
+
+The PIC14 port
+\layout Standard
+
+The 14bit PIC
+\begin_inset LatexCommand \index{PIC14}
+
+\end_inset
+
+ port still requires a major effort from the development community.
+ However it can work for very simple code.
+\layout Subsection
+
+C code and 14bit PIC code page
+\begin_inset LatexCommand \index{code page (pic14)}
+
+\end_inset
+
+ and RAM banks
+\begin_inset LatexCommand \index{RAM bank (pic14)}
+
+\end_inset
+
+
+\layout Standard
+
+The linker organizes allocation for the code page and RAM banks.
+ It does not have intimate knowledge of the code flow.
+ It will put all the code section of a single asm file into a single code
+ page.
+ In order to make use of multiple code pages, separate asm files must be
+ used.
+ The compiler treats all functions of a single C file as being in the same
+ code page unless it is non static.
+ The compiler treats all local variables of a single C file as being in
+ the same RAM bank unless it is an extern.
+\newline
+
+\newline
+To get the best follow these guide lines:
+\layout Enumerate
+
+make local functions static, as non static functions require code page selection
+ overhead.
+\layout Enumerate
+
+Make local variables static as extern variables require RAM bank selection
+ overhead.
+\layout Enumerate
+
+For devices that have multiple code pages it is more efficient to use the
+ same number of files as pages, i.e.
+ for the 16F877 use 4 separate files and i.e.
+ for the 16F874 use 2 separate files.
+ This way the linker can put the code for each file into different code
+ pages and the compiler can allocate reusable variables more efficiently
+ and there's less page selection overhead.
+ And as for any 8 bit micro (especially for PIC 14 as they have a very simple
+ instruction set) use 'unsigned char' whereever possible instead of 'int'.
+\layout Subsection
+
+Creating a device include file
+\layout Standard
+
+For generating a device include file use the support perl script inc2h.pl
+ kept in directory support/script.
+\layout Subsection
+
+Interrupt code
+\layout Standard
+
+For the interrupt function, use the keyword 'interrupt'
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ with level number of 0 (PIC14 only has 1 interrupt so this number is only
+ there to avoid a syntax error - it ought to be fixed).
+ E.g.:
+\layout Verse
+
+
+\family typewriter
+void Intr(void) interrupt 0
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+T0IF = 0; /* Clear timer interrupt */
+\newline
+}
+\layout Subsection
+
+Linking and assembling
+\layout Standard
+
+For assembling you can use either GPUTILS'
+\begin_inset LatexCommand \index{gputils (pic tools)}
+
+\end_inset
+
+ gpasm.exe or MPLAB's mpasmwin.exe.
+ GPUTILS is available from
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
+
+\end_inset
+
+.
+ For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
+ If you use MPLAB and an interrupt function then the linker script file
+ vectors section will need to be enlarged to link with mplink.
+\newline
+
+\newline
+Here is a
+\family typewriter
+Makefile
+\family default
+ using GPUTILS:
+\layout Verse
+
+
+\family typewriter
+.c.o:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcc -S -V -mpic14 -p16F877 $<
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+gpasm -c $*.asm
+\newline
+
+\newline
+$(PRJ).hex: $(OBJS)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
+\layout Standard
+
+Here is a
+\family typewriter
+Makefile
+\family default
+ using MPLAB:
+\layout Verse
+
+
+\family typewriter
+.c.o:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcc -S -V -mpic14 -p16F877 $<
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mpasmwin /q /o $*.asm
+\newline
+
+\newline
+$(PRJ).hex: $(OBJS)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
+\layout Standard
+
+Please note that indentations within a
+\family typewriter
+ Makefile
+\family default
+ have to be done with a tabulator character.
+\layout Subsection
+
+Command-line options
+\layout Standard
+
+Besides the switches common to all SDCC backends, the PIC14 port accepts
+ the following options (for an updated list see sdcc -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-help):
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug-extra emit debug info in assembly output
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-pcode-opt disable (slightly faulty) optimization on pCode
+\layout Subsection
+
+The library
+\layout Subsubsection
+
+error: missing definition for symbol
+\begin_inset Quotes sld
+\end_inset
+
+__gptrget1
+\begin_inset Quotes srd
+\end_inset
+
+
+\layout Standard
+
+The PIC14 port uses library routines to provide more complex operations
+ like multiplication, division/modulus and (generic) pointer dereferencing.
+ In order to add these routines to your project, you must link with PIC14's
+
+\family typewriter
+libsdcc.lib
+\family default
+.
+ For single source file projects this is done automatically, more complex
+ projects must add
+\family typewriter
+libsdcc.lib
+\family default
+ to the linker's arguments.
+ Make sure you also add an include path for the library (using the -I switch
+ to the linker)!
+\layout Subsubsection
+
+Processor mismatch in file
+\begin_inset Quotes sld
+\end_inset
+
+XXX
+\begin_inset Quotes srd
+\end_inset
+
+.
+\layout Standard
+
+This warning can usually be ignored due to the very good compatibility amongst
+ 14 bit PIC devices.
+\layout Standard
+
+You might also consider recompiling the library for your specific device
+ by changing the ARCH=p16f877 (default target) entry in
+\family typewriter
+device/lib/pic/Makefile.in
+\family default
+ and
+\family typewriter
+device/lib/pic/Makefile
+\family default
+ to reflect your device.
+ This might even improve performance for smaller devices as unneccesary
+ BANKSELs migth be removed.
+\layout Subsection
+
+Known bugs
+\layout Subsubsection
+
+initialized data
+\layout Standard
+
+Currently, data can only be initialized if it resides in the source file
+ together with
+\emph on
+main()
+\emph default
+.
+ Data in other source files will silently
+\series bold
+not
+\series default
+ be initialized.
+\layout Section
+
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port
+\layout Standard
+
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port is the portion of SDCC that is responsible to produce code for the
+ Microchip
+\begin_inset LatexCommand \index{Microchip}
+
+\end_inset
+
+(TM) microcontrollers with 16 bit core.
+ Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
+ Currently supported devices are:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="6">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F242
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F248
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F252
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F258
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F442
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F448
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F452
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F458
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F1220
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F2220
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F2550
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F4331
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F4455
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F6520
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F6620
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F6680
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F6720
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F8520
+\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
+
+18F8620
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F8680
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18F8720
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\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>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Global Options
+\layout Standard
+
+PIC16 port supports the standard command line arguments as supposed, with
+ the exception of certain cases that will be mentioned in the following
+ list:
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-callee-saves See -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-all-callee-saves
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-all-callee-saves All function arguments are passed on stack by default.
+
+\emph on
+There is no need to specify this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-fommit-frame-pointer Frame pointer will be omitted when the function uses
+ no local variables.
+\layout Subsection
+
+Port Specific Options
+\begin_inset LatexCommand \index{Options PIC16}
+
+\end_inset
+
+
+\layout Standard
+
+The port specific options appear after the global options in the sdcc --help
+ output.
+\layout Subsubsection
+
+General Options
+\layout Standard
+
+General options enable certain port features and optimizations.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-model=[model] Used in conjuction with the command above.
+ Defines the stack model to be used, valid stack models are :
+\begin_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\emph on
+small
+\emph default
+ Selects small stack model.
+ 8 bit stack and frame pointers.
+ Supports 256 bytes stack size.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\emph on
+large
+\emph default
+ Selects large stack model.
+ 16 bit stack and frame pointers.
+ Supports 65536 bytes stack size.
+\end_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-preplace-udata-with=[kword] Replaces the default udata keyword for allocating
+ unitialized data variables with [kword].
+ Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
+ Useful for bootloaders.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-asm= sets the full path and name of an external assembler to call.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-link= sets the full path and name of an external linker to call.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-mplab-comp MPLAB compatibility option.
+ Currently only suppresses special gpasm directives.
+\layout Subsubsection
+
+Optimization Options
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-optimize-goto Try to use (conditional) BRA instead of GOTO
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-optimize-cmp Try to optimize some compares.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-optimize-df Analyze the dataflow of the generated code and improve it.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-obanksel=nn Set optimization level for inserting BANKSELs.
+\newline
+
+\begin_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+0 no optimization
+\layout List
+\labelwidthstring 00.00.0000
+
+1 checks previous used register and if it is the same then does not emit
+ BANKSEL, accounts only for labels.
+\layout List
+\labelwidthstring 00.00.0000
+
+2 tries to check the location of (even different) symbols and removes BANKSELs
+ if they are in the same bank.
+
+\newline
+
+\emph on
+Important: There might be problems if the linker script has data sections
+ across bank borders!
+\end_deeper
+\layout Subsubsection
+
+Linking Options
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-nodefaultlibs do not link default libraries when linking
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-crt Don't link the default run-time modules
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-use-crt= Use a custom run-time module instead of the defaults.
+\layout Subsubsection
+
+Debugging Options
+\layout Standard
+
+Debugging options enable extra debugging information in the output files.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug-xtra Similar to -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
+
+\end_inset
+
+, but dumps more information.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug-ralloc Force register allocator to dump <source>.d file with debugging
+ information.
+ <source> is the name of the file compiled.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pcode-verbose Enable pcode debugging information in translation.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-denable-peeps Force the usage of peepholes.
+ Use with care.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-gstack Trace push/pops for stack pointer overflow
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-call-tree dump call tree in .calltree file
+\layout Subsection
+
+Enviromental Variables
+\layout Standard
+
+There is a number of enviromental variables that can be used when running
+ SDCC to enable certain optimizations or force a specific program behaviour.
+ these variables are primarily for debugging purposes so they can be enabled/dis
+abled at will.
+\layout Standard
+
+Currently there is only two such variables available:
+\layout List
+\labelwidthstring 00.00.0000
+
+OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
+ bitfields is optimized by directly loading FSR0 with the address of the
+ bitfield structure.
+ Normally SDCC will cast the bitfield structure to a bitfield pointer and
+ then load FSR0.
+ This step saves data ram and code space for functions that perform heavy
+ use of bitfields.
+ (ie.
+ 80 bytes of code space are saved when compiling malloc.c with this option).
+
+\layout List
+\labelwidthstring 00.00.0000
+
+NO_REG_OPT do not perform pCode registers optimization.
+ This should be used for debugging purposes.
+ In some where bugs in the pcode optimizer are found, users can benefit
+ from temporarily disabling the optimizer until the bug is fixed.
+\layout Subsection
+
+Preprocessor Macros
+\layout Standard
+
+PIC16 port defines the following preprocessor macros while translating a
+ source.
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Macro
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Port identification
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+_pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Port identification (same as above)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+pic18fxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+MCU Identification.
+
+\emph on
+xxxx
+\emph default
+ is the microcontrol identification number, i.e.
+ 452, 6620, etc
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+_18Fxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+MCU Identification (same as above)
+\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
+
+STACK_MODEL_nnn
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+nnn = SMALL or LARGE respectively according to the stack model used
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+In addition the following macros are defined when calling assembler:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Macro
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+__18Fxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+MCU Identification.
+
+\emph on
+xxxx
+\emph default
+ is the microcontrol identification number, i.e.
+ 452, 6620, etc
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_MODEL_nnn
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+nnn = SMALL or LARGE respectively according to the memory model used for
+ SDCC
+\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
+
+STACK_MODEL_nnn
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+nnn = SMALL or LARGE respectively according to the stack model used
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Directories
+\layout Standard
+
+PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port uses the following directories for searching header files and libraries.
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="4">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Directory
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
+
+Target
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Command prefix
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PREFIX/sdcc/include/pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC16 specific headers
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Compiler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-I
+\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
+
+PREFIX/sdcc/lib/pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC16 specific libraries
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Linker
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-L
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Pragmas
+\begin_inset LatexCommand \label{sub:PIC16_Pragmas}
+
+\end_inset
+
+
+\layout Standard
+
+PIC16 port currently supports the following pragmas:
+\layout List
+\labelwidthstring 00.00.0000
+
+stack pragma stack forces the code generator to initialize the stack & frame
+ pointers at a specific address.
+ This is an adhoc solution for cases where no STACK directive is available
+ in the linker script or gplink is not instructed to create a stack section.
+\newline
+The stack pragma should be used only once in a project.
+ Multiple pragmas may result in indeterminate behaviour of the program.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+The old format (ie.
+ #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
+ cross page boundaries (or even exceed the available data RAM) and crash
+ the program.
+ Make sure that stack does not cross page boundaries when using the SMALL
+ stack model.
+\end_inset
+
+
+\newline
+The format is as follows:
+\layout LyX-Code
+
+#pragma stack bottom_address [stack_size]
+\layout Standard
+
+
+\emph on
+bottom_address
+\emph default
+ is the lower bound of the stack section.
+ The stack pointer initially will point at address (bottom_address+stack_size-1).
+\layout LyX-Code
+
+Example:
+\layout LyX-Code
+
+\layout LyX-Code
+
+/* initializes stack of 100 bytes at RAM address 0x200 */
+\layout LyX-Code
+
+#pragma stack 0x200 100
+\layout Standard
+
+If the stack_size field is omitted then a stack is created with the default
+ size of 64.
+ This size might be enough for most programs, but its not enough for operations
+ with deep function nesting or excessive stack usage.
+\layout List
+\labelwidthstring 00.00.0000
+
+wparam
+\emph on
+This pragma is deprecated.
+ Its use will cause a warning message to be issued.
+\emph default
+
+\newline
+
+\layout List
+\labelwidthstring 00.00.0000
+
+code place a function symbol at static FLASH address
+\layout LyX-Code
+
+Example:
+\layout LyX-Code
+
+\layout LyX-Code
+
+/* place function test_func at 0x4000 */
+\layout LyX-Code
+
+#pragma code test_func 0x4000
+\layout LyX-Code
+
+\layout List
+\labelwidthstring 00.00.0000
+
+library instructs the linker to use a library module.
+\newline
+Usage:
+\layout LyX-Code
+
+#pragma library module_name
+\layout Standard
+
+
+\emph on
+module_name
+\emph default
+ can be any library or object file (including its path).
+ Note that there are four reserved keywords which have special meaning.
+ These are:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="block" valignment="top" leftline="true" width="20page%">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Keyword
+\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
+
+Module to link
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+ignore
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ignore all library pragmas
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on
+(none)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+link the C library
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on
+libc18f
+\emph default
+.lib
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+math
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+link the Math libarary
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on
+libm18f
+\emph default
+.lib
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+io
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+link the I/O library
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on
+libio18f*
+\emph default
+.lib
+\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
+
+
+\series bold
+debug
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+link the debug library
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on
+libdebug
+\emph default
+.lib
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+* is the device number, i.e.
+ 452 for PIC18F452 MCU.
+\layout Standard
+
+This feature allows for linking with specific libraries withoug having to
+ explicit name them in the command line.
+ Note that the
+\noun on
+ignore
+\noun default
+ keyword will reject all modules specified by the library pragma.
+\layout List
+\labelwidthstring 00.00.0000
+
+udata pragma udata instructs the compiler to emit code so that linker will
+ place a variable at a specific memory bank
+\layout LyX-Code
+
+Example:
+\layout LyX-Code
+
+\layout LyX-Code
+
+/* places variable foo at bank2 */
+\layout LyX-Code
+
+#pragma udata bank2 foo
+\layout LyX-Code
+
+char foo;
+\layout Standard
+
+In order for this pragma to work extra SECTION directives should be added
+ in the .lkr script.
+ In the following example a sample .lkr file is shown:
+\layout LyX-Code
+
+\layout LyX-Code
+
+// Sample linker script for the PIC18F452 processor
+\layout LyX-Code
+
+LIBPATH .
+\layout LyX-Code
+
+CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED
+\layout LyX-Code
+
+CODEPAGE NAME=page START=0x2A END=0x7FFF
+\layout LyX-Code
+
+CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED
+\layout LyX-Code
+
+CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED
+\layout LyX-Code
+
+CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED
+\layout LyX-Code
+
+CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED
+\layout LyX-Code
+
+ACCESSBANK NAME=accessram START=0x0 END=0x7F
+\layout LyX-Code
+
+\layout LyX-Code
+
+DATABANK NAME=gpr0 START=0x80 END=0xFF
+\layout LyX-Code
+
+DATABANK NAME=gpr1 START=0x100 END=0x1FF
+\layout LyX-Code
+
+DATABANK NAME=gpr2 START=0x200 END=0x2FF
+\layout LyX-Code
+
+DATABANK NAME=gpr3 START=0x300 END=0x3FF
+\layout LyX-Code
+
+DATABANK NAME=gpr4 START=0x400 END=0x4FF
+\layout LyX-Code
+
+DATABANK NAME=gpr5 START=0x500 END=0x5FF
+\layout LyX-Code
+
+ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED
+\layout LyX-Code
+
+\layout LyX-Code
+
+SECTION NAME=CONFIG ROM=config
+\layout LyX-Code
+
+\layout LyX-Code
+
+SECTION NAME=bank0 RAM=gpr0 # these SECTION directives
+\layout LyX-Code
+
+SECTION NAME=bank1 RAM=gpr1 # should be added to link
+\layout LyX-Code
+
+SECTION NAME=bank2 RAM=gpr2 # section name 'bank?' with
+\layout LyX-Code
+
+SECTION NAME=bank3 RAM=gpr3 # a specific DATABANK name
+\layout LyX-Code
+
+SECTION NAME=bank4 RAM=gpr4
+\layout LyX-Code
+
+SECTION NAME=bank5 RAM=gpr5
+\layout Standard
+
+The linker will recognise the section name set in the pragma statement and
+ will position the variable at the memory bank set with the RAM field at
+ the SECTION line in the linker script file.
+\layout Subsection
+
+Header Files
+\begin_inset LatexCommand \label{sub:PIC16_Header-Files}
+
+\end_inset
+
+
+\layout Standard
+
+There is one main header file that can be included to the source files using
+ the pic16 port.
+ That file is the
+\series bold
+pic18fregs.h
+\series default
+.
+ This header file contains the definitions for the processor special registers,
+ so it is necessary if the source accesses them.
+ It can be included by adding the following line in the beginning of the
+ file:
+\layout LyX-Code
+
+#include <pic18fregs.h>
+\layout Standard
+
+The specific microcontroller is selected within the pic18fregs.h automatically,
+ so the same source can be used with a variety of devices.
+\layout Subsection
+
+Libraries
+\layout Standard
+
+The libraries that PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port depends on are the microcontroller device libraries which contain
+ the symbol definitions for the microcontroller special function registers.
+ These libraries have the format pic18fxxxx.lib, where
+\emph on
+xxxx
+\emph default
+ is the microcontroller identification number.
+ The specific library is selected automatically by the compiler at link
+ stage according to the selected device.
+\layout Standard
+
+Libraries are created with gplib which is part of the gputils package
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
+
+\end_inset
+
+.
+\layout Subsubsection*
+
+Building the libraries
+\layout Standard
+
+Before using SDCC/pic16 there are some libraries that need to be compiled.
+ This process is not done automatically by SDCC since not all users use
+ SDCC for pic16 projects.
+ So each user should compile the libraries separately.
+\layout Standard
+
+The steps to compile the pic16 libraries under Linux are:
+\layout LyX-Code
+
+cd device/lib/pic16
+\layout LyX-Code
+
+./configure
+\layout LyX-Code
+
+make
+\layout LyX-Code
+
+cd ..
+\layout LyX-Code
+
+make model-pic16
+\layout LyX-Code
+
+su -c 'make install' # install the libraries, you need the root password
+\layout Standard
+
+If you need to install the headers too, do:
+\layout LyX-Code
+
+cd device/include
+\layout LyX-Code
+
+su -c 'make install' # install the headers, you need the root password
+\layout Standard
+
+There exist a special target to build the I/O libraries.
+ This target is not automatically build because it will build the I/O library
+ for
+\emph on
+every
+\emph default
+ supported device.
+ This way building will take quite a lot of time.
+ Users are advised to edit the
+\series bold
+device/lib/pic16/pics.build
+\series default
+ file and then execute:
+\layout LyX-Code
+
+make lib-io
+\layout Subsection
+
+Memory Models
+\layout Standard
+
+The following memory models are supported by the PIC16 port:
+\layout Itemize
+
+small model
+\layout Itemize
+
+large model
+\layout Standard
+
+Memory model affects the default size of pointers within the source.
+ The sizes are shown in the next table:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Pointer sizes according to memory model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+small model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+large model
+\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
+
+code pointers
+\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+24-bits
+\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
+
+data pointers
+\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+It is advisable that all sources within a project are compiled with the
+ same memory model.
+ If one wants to override the default memory model, this can be done by
+ declaring a pointer as
+\series bold
+far
+\series default
+ or
+\series bold
+near
+\series default
+.
+ Far selects large memory model's pointers, while near selects small memory
+ model's pointers.
+\layout Standard
+
+The standard device libraries (see
+\begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
+
+\end_inset
+
+) contain no reference to pointers, so they can be used with both memory
+ models.
+\layout Subsection
+
+Stack
+\layout Standard
+
+The stack implementation for the PIC16 port uses two indirect registers,
+ FSR1 and FSR2.
+\layout List
+\labelwidthstring 00.00.0000
+
+FSR1 is assigned as stack pointer
+\layout List
+\labelwidthstring 00.00.0000
+
+FSR2 is assigned as frame pointer
+\layout Standard
+
+The following stack models are supported by the PIC16 port
+\layout Itemize
+
+
+\noun on
+small
+\noun default
+ model
+\layout Itemize
+
+
+\noun on
+large
+\noun default
+ model
+\layout Standard
+
+
+\noun on
+Small
+\noun default
+ model means that only the FSRxL byte is used to access stack and frame,
+ while
+\emph on
+\noun on
+large
+\emph default
+\noun default
+ uses both FSRxL and FSRxH registers.
+ The following table shows the stack/frame pointers sizes according to stack
+ model and the maximum space they can address:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Stack & Frame pointer sizes according to stack model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+small
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+large
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Stack pointer FSR1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\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
+
+Frame pointer FSR2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+
+\noun on
+Large
+\noun default
+stack model is currently not working properly throughout the code generator.
+ So its use is not advised.
+ Also there are some other points that need special care:
+\newline
+
+\layout Enumerate
+
+Do not create stack sections with size more than one physical bank (that
+ is 256 bytes)
+\layout Enumerate
+
+Stack sections should no cross physical bank limits (i.e.
+ #pragma stack 0x50 0x100)
+\layout Standard
+
+These limitations are caused by the fact that only FSRxL is modified when
+ using SMALL stack model, so no more than 256 bytes of stack can be used.
+ This problem will disappear after LARGE model is fully implemented.
+\layout Subsection
+
+Functions
+\layout Standard
+
+In addition to the standard SDCC function keywords, PIC16 port makes available
+ two more:
+\layout List
+\labelwidthstring 00.00.0000
+
+wparam Use the WREG to pass one byte of the first function argument.
+ This improves speed but you may not use this for functions with arguments
+ that are called via function pointers, otherwise the first byte of the
+ first parameter will get lost.
+ Usage:
+\layout LyX-Code
+
+void func_wparam(int a) wparam
+\layout LyX-Code
+
+{
+\layout LyX-Code
+
+ /* WREG hold the lower part of a */
+\layout LyX-Code
+
+ /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
+ */
+\layout LyX-Code
+
+...
+\layout LyX-Code
+
+}
+\layout Standard
+
+This keyword replaces the deprecated wparam pragma.
+\layout List
+\labelwidthstring 00.00.0000
+
+shadowregs When entering/exiting an ISR, it is possible to take advantage
+ of the PIC18F hardware shadow registers which hold the values of WREG,
+ STATUS and BSR registers.
+ This can be done by adding the keyword
+\emph on
+shadowregs
+\emph default
+ before the
+\emph on
+interrupt
+\emph default
+ keyword in the function's header.
+\layout LyX-Code
+
+void isr_shadow(void) shadowregs interrupt 1
+\layout LyX-Code
+
+{
+\layout LyX-Code
+
+...
+\layout LyX-Code
+
+}
+\layout Standard
+
+
+\emph on
+shadowregs
+\emph default
+ instructs the code generator not to store/restore WREG, STATUS, BSR when
+ entering/exiting the ISR.
+\layout Subsection
+
+Function return values
+\layout Standard
+
+Return values from functions are placed to the appropriate registers following
+ a modified Microchip policy optimized for SDCC.
+ The following table shows these registers:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+size
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+destination register
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+WREG
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PRODL:WREG
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+24 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PRODH:PRODL:WREG
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+32 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+FSR0L:PRODH:PRODL:WREG
+\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
+
+>32 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+on stack, FSR0 points to the beginning
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Interrupts
+\layout Standard
+
+An interrupt servive routine (ISR) is declared using the
+\emph on
+interrupt
+\emph default
+ keyword.
+\layout LyX-Code
+
+void isr(void) interrupt
+\emph on
+n
+\layout LyX-Code
+
+{
+\layout LyX-Code
+
+...
+\layout LyX-Code
+
+}
+\layout Standard
+
+
+\emph on
+n
+\emph default
+ is the interrupt number, which for PIC18F devices can be:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on
+n
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Interrupt Vector
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Interrupt 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
+
+RESET vector
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x000000
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+HIGH priority interrupts
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x000008
+\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
+
+2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+LOW priority interrupts
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x000018
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+When generating assembly code for ISR the code generator places a
+\noun on
+goto
+\noun default
+instruction at the
+\emph on
+Interrupt Vector Address
+\emph default
+ which points at the genetated ISR.
+ This single GOTO instruction is part of an automatically generated
+\emph on
+interrupt entry point
+\emph default
+ function.
+ The actuall ISR code is placed as normally would in the code space.
+ Upon interrupt request, the GOTO instruction is executed which jumps to
+ the ISR code.
+ When declaring interrupt functions as _naked this GOTO instruction is
+\series bold
+not
+\series default
+ generated.
+ The whole interrupt functions is therefore placed at the Interrupt Vector
+ Address of the specific interrupt.
+ This is not a problem for the LOW priority interrupts, but it is a problem
+ for the RESET and the HIGH priority interrupts because code may be written
+ at the next interrupt´s vector address and cause undeterminate program
+ behaviour if that interrupt is raised.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+This is not a problem when
+\layout Enumerate
+
+this is a HIGH interrupt ISR and LOW interrupts are
+\emph on
+disabled
+\emph default
+ or not used.
+\layout Enumerate
+
+when the ISR is small enough not to reach the next interrupt´s vector address.
+\end_inset
+
+
+\layout Standard
+
+
+\emph on
+n
+\emph default
+ is possible to be omitted.
+ This way a function is generated similar to an ISR, but it is not assigned
+ to any interrupt.
+\layout Standard
+
+When entering an interrupt, currently the PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port automatically saves the following registers:
+\layout Itemize
+
+WREG
+\layout Itemize
+
+STATUS
+\layout Itemize
+
+BSR
+\layout Itemize
+
+PROD (PRODL and PRODH)
+\layout Itemize
+
+FSR0 (FSR0L and FSR0H)
+\layout Standard
+
+These registers are restored upon return from the interrupt routine.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+NOTE that when the _naked attribute is specified for an interrupt routine,
+ then NO registers are stored or restored.
+\end_inset
+
+
+\layout Subsection
+
+Generic Pointers
+\layout Standard
+
+Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
+ There are 3 types of generic pointers currently implemented data, code
+ and eeprom pointers.
+ They are differentiated by the value of the 7th and 6th bits of the upper
+ byte:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="5">
+<features>
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="left" valignment="top" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+pointer type
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+7th bit
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+6th bit
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+rest of the pointer
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+descrption
+\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
+
+data
+\end_inset
+</cell>
+<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" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family typewriter
+\shape slanted
+\emph on
+uuuuuu uuuuxxxx xxxxxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+a 12-bit data pointer in data RAM memory
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+code
+\end_inset
+</cell>
+<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" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family typewriter
+\shape slanted
+\emph on
+uxxxxx xxxxxxxx xxxxxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+a 21-bit code pointer in FLASH memory
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+eeprom
+\end_inset
+</cell>
+<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" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family typewriter
+\shape slanted
+\emph on
+uuuuuu uuuuuuxx xxxxxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+a 10-bit eeprom pointer in EEPROM memory
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+(unimplemented)
+\end_inset
+</cell>
+<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" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family typewriter
+\shape slanted
+\emph on
+xxxxxx xxxxxxxx xxxxxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+unimplemented pointer type
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+Generic pointer are read and written with a set of library functions which
+ read/write 1, 2, 3, 4 bytes.
+\layout Subsection
+
+PIC16 C Libraries
+\layout Subsubsection
+
+Standard I/O Streams
+\layout Standard
+
+In the
+\emph on
+stdio.h
+\emph default
+ the type FILE is defined as:
+\layout LyX-Code
+
+typedef char * FILE;
+\layout Standard
+
+This type is the stream type implemented I/O in the PIC18F devices.
+ Also the standard input and output streams are declared in stdio.h:
+\layout LyX-Code
+
+extern FILE * stdin;
+\layout LyX-Code
+
+extern FILE * stdout;
+\layout Standard
+
+The FILE type is actually a generic pointer which defines one more type
+ of generic pointers, the
+\emph on
+stream
+\emph default
+pointer.
+ This new type has the format:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="7">
+<features>
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="left" valignment="top" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+pointer type
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+<7:6>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+<5>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+<4>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+<3:0>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+rest of the pointer
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+descrption
+\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
+
+stream
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+00
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+nnnn
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family typewriter
+\shape slanted
+\emph on
+uuuuuuuu uuuuuuuu
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+upper byte high nubble is 0x2n, the rest are zeroes
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+Currently implemented there are 3 types of streams defined:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="4">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+stream type
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+value
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+module
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+STREAM_USART
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family typewriter
+0x200000UL
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+USART
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Writes/Reads characters via the USART peripheral
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+STREAM_MSSP
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family typewriter
+0x210000UL
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+MSSP
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Writes/Reads characters via the MSSP peripheral
+\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
+
+STREAM_USER
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family typewriter
+0x2f0000UL
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+(none)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Writes/Reads characters via used defined functions
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+The stream identifiers are declared as macros in the stdio.h header.
+\layout Standard
+
+In the libc library there exist the functions that are used to write to
+ each of the above streams.
+ These are
+\layout List
+\labelwidthstring 00.00.0000
+
+_
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+_stream_usart_putchar writes a character at the USART stream
+\layout List
+\labelwidthstring 00.00.0000
+
+_
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+_stream_mssp_putchar writes a character at the MSSP stream
+\layout List
+\labelwidthstring 00.00.0000
+
+putchar dummy function.
+ This writes a character to a user specified manner.
+\layout Standard
+
+In order to increase performance
+\emph on
+putchar
+\emph default
+is declared in stdio.h as having its parameter in WREG (it has the wparam
+ keyword).
+ In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
+ in a user-friendly way.
+
+\emph on
+arg
+\emph default
+ is the name of the variable that holds the character to print.
+ An example follows:
+\layout LyX-Code
+
+#include <pic18fregs.h>
+\newline
+#include <stdio.h>
+\newline
+
+\newline
+PUTCHAR( c )
+\layout LyX-Code
+
+{
+\layout LyX-Code
+
+ PORTA = c; /* dump character c to PORTA */
+\layout LyX-Code
+
+}
+\newline
+
+\newline
+void main(void)
+\layout LyX-Code
+
+{
+\layout LyX-Code
+
+ stdout = STREAM_USER; /* this is not necessery, since stdout points
+\layout LyX-Code
+
+ * by default to STREAM_USER */
+\layout LyX-Code
+
+ printf (¨This is a printf test
+\backslash
+n¨);
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+\layout Subsubsection
+
+Printing functions
+\layout Standard
+
+PIC16 contains an implementation of the printf-family of functions.
+ There exist the following functions:
+\layout LyX-Code
+
+extern unsigned int sprintf(char *buf, char *fmt, ...);
+\layout LyX-Code
+
+extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
+\layout LyX-Code
+
+\layout LyX-Code
+
+extern unsigned int printf(char *fmt, ...);
+\layout LyX-Code
+
+extern unsigned int vprintf(char *fmt, va_lista ap);
+\layout LyX-Code
+
+\layout LyX-Code
+
+extern unsigned int fprintf(FILE *fp, char *fmt, ...);
+\layout LyX-Code
+
+extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
+\layout Standard
+
+For sprintf and vsprintf
+\emph on
+buf
+\emph default
+should normally be a data pointer where the resulting string will be placed.
+ No range checking is done so the user should allocate the necessery buffer.
+ For fprintf and vfprintf
+\emph on
+fp
+\emph default
+ should be a stream pointer (i.e.
+ stdout, STREAM_MSSP, etc...).
+\layout Subsubsection
+
+Signals
+\layout Standard
+
+The PIC18F family of microcontrollers supports a number of interrupt sources.
+ A list of these interrupts is shown in the following table:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" columns="4">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+signal name
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
+
+signal name
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+descritpion
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_RB
+\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PORTB change interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_EE
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+EEPROM/FLASH write complete interrupt
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_INT0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+INT0 external interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_BCOL
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Bus collision interrupt
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_INT1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+INT1 external interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_LVD
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Low voltage detect interrupt
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_INT2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+INT2 external interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_PSP
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Parallel slave port interrupt
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_CCP1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+CCP1 module interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_AD
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+AD convertion complete interrupt
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_CCP2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+CCP2 module interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_RC
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+USART receive interrupt
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_TMR0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+TMR0 overflow interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_TX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+USART transmit interrupt
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_TMR1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+TMR1 overflow interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_MSSP
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SSP receive/transmit interrupt
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_TMR2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+TMR2 matches PR2 interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\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" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SIG_TMR3
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+TMR3 overflow interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\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>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+The prototypes for these names are defined in the header file
+\emph on
+signal.h
+\emph default
+ .
+\layout Standard
+
+In order to simplify signal handling, a number of macros is provided:
+\layout List
+\labelwidthstring 00.00.0000
+
+DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
+ high priority interrupts.
+
+\emph on
+name
+\emph default
+ is the function name to use.
+\layout List
+\labelwidthstring 00.00.0000
+
+DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
+ low priority interrupt.
+
+\emph on
+name
+\emph default
+ is the function name to use.
+\layout List
+\labelwidthstring 00.00.0000
+
+DEF_HANDLER(sig,handler) define a handler for signal
+\emph on
+sig.
+\layout List
+\labelwidthstring 00.00.0000
+
+END_DEF end the declaration of the dispatch table.
+\layout Standard
+
+Additionally there are two more macros to simplify the declaration of the
+ signal handler:
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series medium
+SIGHANDLER(handler)
+\series default
+this declares the function prototype for the
+\emph on
+handler
+\emph default
+ function.
+\layout List
+\labelwidthstring 00.00.0000
+
+SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
+\layout Standard
+
+An example of using the macros above is shown below:
+\layout LyX-Code
+
+#include <pic18fregs.h>
+\layout LyX-Code
+
+#include <signal.h>
+\newline
+
+\newline
+DEF_INTHIGH(high_int)
+\layout LyX-Code
+
+DEF_HANDLER(SIG_TMR0, _tmr0_handler)
+\layout LyX-Code
+
+DEF_HANDLER(SIG_BCOL, _bcol_handler)
+\layout LyX-Code
+
+END_DEF
+\newline
+
+\newline
+SIGHANDLER(_tmr0_handler)
+\layout LyX-Code
+
+{
+\layout LyX-Code
+
+ /* action to be taken when timer 0 overflows */
+\layout LyX-Code
+
+}
+\newline
+
+\newline
+SIGHANDLERNAKED(_bcol_handler)
+\layout LyX-Code
+
+{
+\layout LyX-Code
+
+ _asm
+\layout LyX-Code
+
+ /* action to be taken when bus collision occurs */
+\layout LyX-Code
+
+ retfie
+\layout LyX-Code
+
+ _endasm;
+\layout LyX-Code
+
+}
+\layout Standard
+
+
+\series bold
+NOTES:
+\series default
+ Special care should be taken when using the above scheme:
+\layout Itemize
+
+do not place a colon (;) at the end of the DEF_* and END_DEF macros.
+\layout Itemize
+
+when declaring SIGHANDLERNAKED handler never forget to use
+\emph on
+retfie
+\emph default
+ for proper returning.
+\layout Subsection
+
+PIC16 Port -- Tips
+\layout Standard
+
+Here you can find some general tips for compiling programs with SDCC/pic16.
+\layout Subsubsection
+
+Stack size
+\layout Standard
+
+The default stack size (that is 64 bytes) probably is enough for many programs.
+ One must take care that when there are many levels of function nesting,
+ or there is excessive usage of stack, its size should be extended.
+ An example of such a case is the printf/sprintf family of functions.
+ If you encounter problems like not being able to print integers, then you
+ need to set the stack size around the maximum (256 for small stack model).
+ The following diagram shows what happens when calling printf to print an
+ integer:
+\layout LyX-Code
+
+printf () --> ltoa () --> ultoa () --> divschar ()
+\layout Standard
+
+It is should be understood that stack is easily consumed when calling complicate
+d functions.
+ Using command line arguments like -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-fommit-frame-pointer might reduce stack usage by not creating unnecessery
+ stack frames.
+ Other ways to reduce stack usage may exist.
+\layout Chapter
+
+Debugging
+\layout Standard
+
+There are several approaches to debugging your code.
+ This chapter is meant to show your options and to give detail on some of
+ them:
+\newline
+
+\newline
+When writing your code:
+\layout Itemize
+
+write your code with debugging in mind (avoid duplicating code, put conceptually
+ similar variables into structs, use structured code, have strategic points
+ within your code where all variables are consistent, ...)
+\layout Itemize
+
+run a syntax-checking tool like splint
+\begin_inset LatexCommand \index{splint (syntax checking tool)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{lint (syntax checking tool)}
+
+\end_inset
+
+ (see -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-more-pedantic
+\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
+
+\end_inset
+
+) over the code.
+\layout Itemize
+
+for the high level code use a C-compiler (like f.e.
+ GCC) to compile run and debug the code on your host.
+ See (see -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-more-pedantic
+\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
+
+\end_inset
+
+ ) on howto handle syntax extensions like __xdata, __at(), ...
+
+\layout Itemize
+
+use another C-compiler to compile code for your target.
+ Always an option but not recommended:) And not very likely to help you.
+ If you seriously consider walking this path you should at least occasionally
+ check portability of your code.
+ Most commercial compiler vendors will offer an evaluation version so you
+ can test compile your code or snippets of your code.
+\layout Standard
+
+Debugging on a simulator:
+\layout Itemize
+
+there is a separate section about SDCDB (section
+\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
+
+\end_inset
+
+) below.
+\layout Itemize
+
+or (8051 specific) use a freeware/commercial simulator which interfaces
+ to the AOMF
+\begin_inset LatexCommand \index{AOMF, AOMF51}
+
+\end_inset
+
+ file (see
+\begin_inset LatexCommand \ref{OMF file}
+
+\end_inset
+
+) optionally generated by SDCC.
+\layout Standard
+
+Debugging On-target:
+\layout Itemize
+
+use a MCU port pin to serially output debug data to the RS232 port of your
+ host.
+ You'll probably want some level shifting device typically involving a MAX232
+ or similar IC.
+ If the hardware serial port of the MCU is not available search for 'Software
+ UART' in your favourite search machine.
+\layout Itemize
+
+use an on-target monitor.
+ In this context a monitor is a small program which usually accepts commands
+ via a serial line and allows to set program counter, to single step through
+ a program and read/write memory locations.
+ For the 8051 a good example of a monitor with a very liberal licence is
+ paulmon (
+\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
+
+\end_inset
+
+).
+\layout Itemize
+
+toggle MCU port pins at strategic points within your code and use an oscilloscop
+e.
+ A
+\emph on
+digital oscilloscope
+\emph default
+
+\begin_inset LatexCommand \index{oscilloscope}
+
+\end_inset
+
+ with deep trace memory is really helpful especially if you have to debug
+ a realtime application.
+ If you need to monitor more pins than your oscilloscope provides you can
+ sometimes get away with a small R-2R network.
+ On a single channel oscilloscope you could f.e.
+ monitor 2 push-pull driven pins by connecting one via a 10\SpecialChar ~
+k
+\begin_inset Formula $\Omega$
+\end_inset
+
+ resistor and the other one by a 5\SpecialChar ~
+k
+\begin_inset Formula $\Omega$
+\end_inset
+
+ resistor to the oscilloscope probe (check output drive capability of the
+ pins you want to monitor).
+ If you need to monitor many more pins a
+\emph on
+logic analyzer
+\emph default
+ will be handy.
+\layout Itemize
+
+use an ICE (
+\emph on
+i
+\emph default
+n
+\emph on
+c
+\emph default
+ircuit
+\emph on
+e
+\emph default
+mulator
+\begin_inset LatexCommand \index{ICE (in circuit emulator)}
+
+\end_inset
+
+).
+ Usually very expensive.
+ And very nice to have too.
+ And usually locks you (for years...) to the devices the ICE can emulate.
+
+\layout Itemize
+
+use a remote debugger.
+ In most 8-bit systems the symbol information is not available on the target,
+ and a complete debugger is too bulky for the target system.
+ Therefore usually a debugger on the host system connects to an on-target
+ debugging stub which accepts only primitive commands.
+
+\newline
+Terms to enter into your favourite search engine could be 'remote debugging',
+ 'gdb stub' or 'inferior debugger'.
+ (is there one?)
+\layout Itemize
+
+use an on target hardware debugger.
+ Some of the more modern MCUs include hardware support for setting break
+ points and monitoring/changing variables by using dedicated hardware pins.
+ This facility doesn't require additional code to run on the target and
+
+\emph on
+usually
+\emph default
+ doesn't affect runtime behaviour until a breakpoint is hit.
+ For the mcs51 most hardware debuggers use the AOMF
+\begin_inset LatexCommand \index{AOMF, AOMF51}
+
+\end_inset
+
+ file (see
+\begin_inset LatexCommand \ref{OMF file}
+
+\end_inset
+
+) as input file.
+
+\layout Standard
+
+Last not least:
+\layout Itemize
+
+if you are not familiar with any of the following terms you're likely to
+ run into problems rather sooner than later:
+\emph on
+volatile
+\emph default
+,
+\emph on
+atomic
+\emph default
+,
+\emph on
+memory map
+\emph default
+,
+\emph on
+overlay
+\emph default
+.
+ As an embedded programmer you
+\emph on
+have
+\emph default
+ to know them so why not look them up
+\emph on
+before
+\emph default
+ you have problems?)
+\layout Itemize
+
+tell someone else about your problem (actually this is a surprisingly effective
+ means to hunt down the bug even if the listener is not familiar with your
+ environment).
+ As 'failure to communicate' is probably one of the job-induced deformations
+ of an embedded programmer this is highly encouraged.
+\layout Section
+
+Debugging with SDCDB
+\begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC is distributed with a source level debugger
+\begin_inset LatexCommand \index{Debugger}
+
+\end_inset
+
+.
+ The debugger uses a command line interface, the command repertoire of the
+ debugger has been kept as close to gdb
+\begin_inset LatexCommand \index{gdb}
+
+\end_inset
+
+ (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.
+ Sdcdb is currently not available on Win32 platforms.
+\layout Subsection
+
+Compiling for Debugging
+\layout Standard
+
+The -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
+
+\end_inset
+
+ option must be specified for all files for which debug information is to
+ be generated.
+ The compiler generates a .adb file for each of these files.
+ The linker creates the .cdb
+\begin_inset LatexCommand \index{<file>.cdb}
+
+\end_inset
+
+ file from the .adb
+\begin_inset LatexCommand \index{<file>.adb}
+
+\end_inset
+
+ files and the address information.
+ This .cdb is used by the debugger.
+\layout Subsection
+
+How the Debugger Works
+\layout Standard
+
+When the -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug option is specified the compiler generates extra symbol information
+ some of which are put into the assembler source and some are put into the
+ .adb file.
+ Then the linker creates the .cdb file from the individual .adb files 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.
+ (Currently sdcdb only connects to the simulator but
+\emph on
+newcdb
+\emph default
+ at
+\begin_inset LatexCommand \url{http://ec2drv.sf.net/}
+
+\end_inset
+
+ is an effort to connect directly to the hardware.)
+\layout Subsection
+
+Starting the Debugger SDCDB
+\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
+\begin_inset LatexCommand \index{Intel hex format}
+
+\end_inset
+
+ object file.
+\layout Subsection
+
+SDCDB Command Line Options
+\layout Itemize
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-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 -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-directory option should be -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-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 Itemize
+
+-k <port number> passed to simulator see the simulator docs for details.
+\layout Subsection
+
+SDCDB Debugger Commands
+\layout Standard
+
+As mentioned earlier the command interface for the debugger has been deliberatel
+y 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.
+ If you use a graphical user interface for the debugger you can skip this
+ section.
+\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.
+ Note: pressing <return> repeats the last command.
+\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 SDCDB with DDD
+\layout Comment
+
+The screenshot was converted from png to eps with:
+\begin_inset Quotes sld
+\end_inset
+
+bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
+\begin_inset Quotes srd
+\end_inset
+
+ which produces a pretty compact eps file which is free from compression
+ artifacts.
+\layout Comment
+
+The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
+ as this broke the build system on Sourceforge (pdf-file was broken).
+\layout Standard
+
+The .eps File
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.eps}
+
+\end_inset
+
+
+\size default
+ shows a screenshot of a debugging session with DDD
+\begin_inset LatexCommand \index{DDD (debugger)}
+
+\end_inset
+
+ (Unix only) on a simulated 8032.
+ The debugging session might not run as smoothly as the screenshot suggests.
+ The debugger allows setting of breakpoints, displaying and changing variables,
+ single stepping through C and assembler code.
+
+\newline
+The source was compiled with
+\family sans
+\series bold
+
+\newline
+
+\newline
+sdcc -
+\family default
+\series default
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+
+\family sans
+\series bold
+-debug ddd_example.c
+\family default
+\series default
+
+\family sans
+\series bold
+
+\newline
+
+\family default
+\series default
+
+\newline
+and DDD was invoked with
+\family sans
+\series bold
+
+\newline
+
+\newline
+ddd -debugger 'sdcdb -cpu 8032 ddd_example'
+\layout Subsection
+
+Interfacing SDCDB with XEmacs
+\begin_inset LatexCommand \index{XEmacs}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Emacs}
+
+\end_inset
+
+
+\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
+;;\SpecialChar ~
+Current Listing ::
+\newline
+;;key\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 ~
+-------
+\newline
+;;
+\newline
+;;\SpecialChar ~
+n\SpecialChar ~
+\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
+;;\SpecialChar ~
+b\SpecialChar ~
+\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
+;;\SpecialChar ~
+c\SpecialChar ~
+\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
+;;\SpecialChar ~
+s\SpecialChar ~
+\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 ~
+\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 ~
+\SpecialChar ~
+buffer point
+\newline
+;;\SpecialChar ~
+x\SpecialChar ~
+\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 ~
+\SpecialChar ~
+given or delete arg (C-u arg x)
+\newline
+;;\SpecialChar ~
+m\SpecialChar ~
+\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 ~
+\SpecialChar ~
+\SpecialChar ~
+sdcdbsrc-goto-sdcdb\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Goto the SDCDB output buffer
+\newline
+;;\SpecialChar ~
+p\SpecialChar ~
+\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 ~
+\SpecialChar ~
+buffer point
+\newline
+;;\SpecialChar ~
+g\SpecialChar ~
+\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
+;;\SpecialChar ~
+t\SpecialChar ~
+\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
+;;\SpecialChar ~
+C-c\SpecialChar ~
+C-f\SpecialChar ~
+\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
+;;\SpecialChar ~
+C-x\SpecialChar ~
+SPC\SpecialChar ~
+\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
+;;\SpecialChar ~
+ESC\SpecialChar ~
+t\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 ~
+Toggle Sdcdbsrc mode
+\newline
+;;\SpecialChar ~
+ESC\SpecialChar ~
+m\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcdbsrc-srcmode\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Toggle list mode
+\newline
+;;
+\newline
+
+\layout Chapter
+\pagebreak_top
+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'.
+ Please note, that ANSI C requires both signed and unsigned chars to be
+ promoted to 'signed int'
+\begin_inset LatexCommand \index{promotion to signed int}
+
+\end_inset
+
+ before doing any operation.
+ This promotion
+\begin_inset LatexCommand \index{type promotion}
+
+\end_inset
+
+
+\begin_inset LatexCommand \label{type promotion}
+
+\end_inset
+
+ can be omitted, if the result is the same.
+ The effect of the promotion rules together with the sign-extension is often
+ surprising:
+\begin_deeper
+\layout Verse
+
+
+\family typewriter
+unsigned char uc = 0xfe;
+\newline
+if (uc * uc < 0) /* this is true! */
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....
+\newline
+}
+\layout Standard
+
+
+\family typewriter
+uc * uc
+\family default
+ is evaluated as
+\family typewriter
+(int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
+\family default
+.
+
+\newline
+Another one:
+\layout Verse
+
+
+\family typewriter
+(unsigned char) -12 / (signed char) -3 = ...
+\layout Standard
+
+No, the result is not 4:
+\layout Verse
+
+
+\family typewriter
+(int) (unsigned char) -12 / (int) (signed char) -3 =
+\newline
+(int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
+\newline
+(int) 0x00f4 / (int) 0xfffd =
+\newline
+(int) 0x00f4 / (int) 0xfffd =
+\newline
+(int) 244 / (int) -3 =
+\newline
+(int) -81 = (int) 0xffaf;
+\layout Standard
+
+Don't complain, that gcc gives you a different result.
+ gcc uses 32 bit ints, while SDCC uses 16 bit ints.
+ Therefore the results are different.
+\newline
+From
+\begin_inset Quotes sld
+\end_inset
+
+comp.lang.c FAQ
+\begin_inset Quotes srd
+\end_inset
+
+:
+\layout Quote
+
+If well-defined overflow characteristics are important and negative values
+ are not, or if you want to steer clear of sign-extension problems when
+ manipulating bits or bytes, use one of the corresponding unsigned types.
+ (Beware when mixing signed and unsigned values in expressions, though.)
+\newline
+Although character types (especially unsigned char) can be used as "tiny"
+ integers, doing so is sometimes more trouble than it's worth, due to unpredicta
+ble sign extension and increased code size.
+\end_deeper
+\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, bit-shifting
+ or are using an array index.
+\layout Itemize
+
+NEVER jump into a LOOP.
+\layout Itemize
+
+Declare the variables to be local
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+ 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.
+\begin_deeper
+\layout Verse
+
+
+\family typewriter
+foobar(unsigned int p1, unsigned char ch)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+unsigned char ch1 = p1 % ch ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....
+\newline
+}
+\layout Standard
+
+For the modulus operation the variable ch will be promoted to unsigned int
+ first then the modulus operation will be performed (this will lead to a
+ call to support routine _moduint()), and the result will be casted to a
+ char.
+ If the code is changed to
+\layout Verse
+
+
+\family typewriter
+foobar(unsigned int p1, unsigned char ch)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+unsigned char ch1 = (unsigned char)p1 % ch ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....
+\newline
+}
+\layout Standard
+
+It would substantially reduce the code generated (future versions of the
+ compiler will be smart enough to detect such optimization opportunities).
+\end_deeper
+\layout Itemize
+
+Have a look at the assembly listing to get a
+\begin_inset Quotes sld
+\end_inset
+
+feeling
+\begin_inset Quotes srd
+\end_inset
+
+ for the code generation.
+\layout Section
+
+Porting code from or to other compilers
+\layout Itemize
+
+check whether endianness of the compilers differs and adapt where needed.
+\layout Itemize
+
+check the device specific header files for compiler specific syntax.
+ Eventually include the file <compiler.h
+\begin_inset LatexCommand \index{compiler.h (include file)}
+
+\end_inset
+
+> to allow using common header files.
+\layout Itemize
+
+check whether the startup code contains the correct initialization (watchdog,
+ peripherals).
+\layout Itemize
+
+check whether the sizes of short, int, long match.
+\layout Itemize
+
+check if some 16 or 32 bit hardware registers require a specific addressing
+ order (least significant or most significant byte first) and adapt if needed
+ (
+\emph on
+first
+\emph default
+ and
+\emph on
+last
+\emph default
+ relate to time and not to lower/upper memory location here, so this is
+
+\emph on
+not
+\emph default
+ the same as endianness).check whether the keyword
+\emph on
+volatile
+\emph default
+ is used where needed.
+ The compilers might differ in their optimization characteristics (as different
+ versions of the same compiler might also use more clever optimizations
+ this is good idea anyway).
+\layout Itemize
+
+check that the compilers are not told to supress warnings.
+\layout Itemize
+
+check and convert compiler specific extensions (interrupts, memory areas,
+ pragmas etc.).
+\layout Itemize
+
+check for differences in type promotion (especially check for math operations
+ on char variables and for the use of the ~\SpecialChar ~
+operator on bit variables.
+ See
+\begin_inset LatexCommand \ref{type promotion}
+
+\end_inset
+
+ and
+\begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
+
+\end_inset
+
+).
+\layout Itemize
+
+check the assembly code generated for interrupt routines (f.e.
+ for calls to possibly non-reentrant library functions).
+\layout Itemize
+
+check whether timing loops result in proper timing (or preferably consider
+ a rewrite of the code with timer based delays instead).
+\layout Itemize
+
+check for differences in printf parameters (some compilers push (va_arg)
+ char variables as integers others as char).
+\layout Itemize
+
+check the resulting memory layout.
+\layout Section
+
+Tools
+\begin_inset LatexCommand \index{Tools}
+
+\end_inset
+
+ included in the distribution
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="12" 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
+
+Name
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Purpose
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Directory
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+uCsim
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Simulator for various architectures
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/sim/ucsim
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+keil2sdcc.pl
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+header file conversion
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/support/scripts
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+mh2h.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+header file conversion
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/support/scripts
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+as-gbz80
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Assembler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+as-z80
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Assembler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+asx8051
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Assembler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcdb
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Simulator
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+aslink
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Linker
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+link-z80
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Linker
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+link-gbz80
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Linker
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\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
+
+packihx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ihx packer
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Section
+
+Documentation
+\begin_inset LatexCommand \index{Documentation}
+
+\end_inset
+
+ included in the distribution
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="10" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0">
+<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
+
+Subject / Title
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Where to get / filename
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC Compiler User Guide
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+You're reading it right now
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Changelog of SDCC
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/Changelog
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ASXXXX
+\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Assembler documentation}
+
+\end_inset
+
+ Assemblers and ASLINK
+\begin_inset LatexCommand \index{aslink}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Linker documentation}
+
+\end_inset
+
+ Relocating Linker
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/as/doc/asxhtm.html
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC regression test
+\begin_inset LatexCommand \index{Regression test}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/doc/test_suite_spec.pdf
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Various notes
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/doc/*
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Notes on debugging with sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/debugger/README
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Software simulator for microcontrollers
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/sim/ucsim/doc
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+/index.html
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Temporary notes on the pic16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/src/pic16/NOTES
+\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
+
+SDCC internal documentation (debugging file format)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/doc/
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+cdbfileformat.pd
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+f
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Section
+
+Related open source tools
+\begin_inset LatexCommand \index{Related tools}
+
+\end_inset
+
+
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="13" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0pt">
+<column alignment="block" valignment="top" leftline="true" width="30line%">
+<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
+
+Name
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Purpose
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Where to get
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+gpsim
+\begin_inset LatexCommand \index{gpsim (pic simulator)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC simulator
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+gputils
+\begin_inset LatexCommand \index{gputils (pic tools)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+GNU PIC utilities
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+flP5
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC programmer
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ec2drv/newcdb
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Tools for Silicon Laboratories JTAG debug adapter, partly based on sdcdb
+ (Unix only)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+indent
+\begin_inset LatexCommand \index{indent (source formatting tool)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Formats C source - Master of the white spaces
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+srecord
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Object file conversion, checksumming, ...
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+objdump
+\begin_inset LatexCommand \index{objdump (tool)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Object file conversion, ...
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Part of binutils (should be there anyway)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+doxygen
+\begin_inset LatexCommand \index{doxygen (source documentation tool)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Source code documentation system
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.doxygen.org}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+kdevelop
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.kdevelop.org}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+paulmon
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8051 monitor (hex up-/download, single step, disassemble)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+splint
+\begin_inset LatexCommand \index{splint (syntax checking tool)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Statically checks c sources (see
+\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
+
+\end_inset
+
+)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.splint.org}
+
+\end_inset
+
+
+\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
+
+ddd
+\begin_inset LatexCommand \index{ddd (debugger)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Debugger, serves nicely as GUI to sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
+\end_inset
+
+ (Unix only)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Section
+
+Related documentation / recommended reading
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="block" valignment="top" leftline="true" width="30line%">
+<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
+
+Name
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Subject / Title
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Where to get
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+c-refcard.pdf
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+C Reference Card
+\begin_inset LatexCommand \index{C Reference card}
+
+\end_inset
+
+, 2 pages
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+c-faq
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+C-FAQ-list
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Latest datasheet of the target CPU
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+vendor
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Revision history of datasheet
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+vendor
+\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
+
+S.
+ S.
+ Muchnick
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Advanced Compiler Design and Implementation
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+bookstore (very dedicated, probably read other books first)
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Section
+
+Some Questions
+\layout Standard
+
+Some questions answered, some pointers given - it might be time to in turn
+ ask
+\emph on
+you
+\emph default
+ some questions:
+\layout Itemize
+
+can you solve your project with the selected microcontroller? Would you
+ find out early or rather late that your target is too small/slow/whatever?
+ Can you switch to a slightly better device if it doesn't fit?
+\layout Itemize
+
+should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
+ and/or another programming language be more adequate? Would an operating
+ system on the target device help?
+\layout Itemize
+
+if you solved the problem, will the marketing department be happy?
+\layout Itemize
+
+if the marketing department is happy, will customers be happy?
+\layout Itemize
+
+if you're the project manager, marketing department and maybe even the customer
+ in one person, have you tried to see the project from the outside?
+\layout Itemize
+
+is the project done if you think it is done? Or is just that other interface/pro
+tocol/feature/configuration/option missing? How about website, manual(s),
+ internationali(z|s)ation, packaging, labels, 2nd source for components,
+ electromagnetic compatability/interference, documentation for production,
+ production test software, update mechanism, patent issues?
+\layout Itemize
+
+is your project adequately positioned in that magic triangle: fame, fortune,
+ fun?
+\layout Standard
+
+Maybe not all answers to these questions are known and some answers may
+ even be
+\emph on
+no
+\emph default
+, nevertheless knowing these questions may help you to avoid burnout
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+burnout is bad for electronic devices, programmers and motorcycle tyres
+\end_inset
+
+.
+ Chances are you didn't want to hear some of them...
+\layout Chapter
+
+Support
+\begin_inset LatexCommand \index{Support}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC has grown to be a large project.
+ The compiler alone (without the preprocessor, assembler and linker) is
+ well over 100,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 Standard
+
+The SDCC project is hosted on the SDCC sourceforge site at
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
+
+\end_inset
+
+.
+ You'll find the complete set of mailing lists
+\begin_inset LatexCommand \index{Mailing list(s)}
+
+\end_inset
+
+, forums, bug reporting system, patch submission
+\begin_inset LatexCommand \index{Patch submission}
+
+\end_inset
+
+ system, download
+\begin_inset LatexCommand \index{download}
+
+\end_inset
+
+ area and Subversion code repository
+\begin_inset LatexCommand \index{Subversion code repository}
+
+\end_inset
+
+ there.
+\layout Section
+
+Reporting Bugs
+\begin_inset LatexCommand \index{Bug reporting}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Reporting bugs}
+
+\end_inset
+
+
+\layout Standard
+
+The recommended way of reporting bugs is using the infrastructure of the
+ sourceforge site.
+ You can follow the status of bug reports there and have an overview about
+ the known bugs.
+\layout Standard
+
+Bug reports are automatically forwarded to the developer mailing list and
+ will be fixed ASAP.
+ When reporting a bug, it is very useful to include a small test program
+ (the smaller the better) 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 -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-dumpall
+\begin_inset LatexCommand \index{-\/-dumpall}
+
+\end_inset
+
+ option can sometimes be useful in locating optimization problems.
+ When reporting a bug please maker sure you:
+\layout Enumerate
+
+Attach the code you are compiling with SDCC.
+
+\layout Enumerate
+
+Specify the exact command you use to run SDCC, or attach your Makefile.
+
+\layout Enumerate
+
+Specify the SDCC version (type "
+\family sans
+\series bold
+sdcc -v
+\family default
+\series default
+"), your platform, and operating system.
+
+\layout Enumerate
+
+Provide an exact copy of any error message or incorrect output.
+
+\layout Enumerate
+
+Put something meaningful in the subject of your message.
+\layout Standard
+
+Please attempt to include these 5 important parts, as applicable, in all
+ requests for support or when reporting any problems or bugs with SDCC.
+ Though this will make your message lengthy, it will greatly improve your
+ chance that SDCC users and developers will be able to help you.
+ Some SDCC developers are frustrated by bug reports without code provided
+ that they can use to reproduce and ultimately fix the problem, so please
+ be sure to provide sample code if you are reporting a bug!
+\layout Standard
+
+Please have a short check that you are using a recent version of SDCC and
+ the bug is not yet known.
+ This is the link for reporting bugs:
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
+
+\end_inset
+
+.
+\layout Section
+
+Requesting Features
+\begin_inset LatexCommand \label{sub:Requesting-Features}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Feature request}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Requesting features}
+
+\end_inset
+
+
+\layout Standard
+
+Like bug reports feature requests are forwarded to the developer mailing
+ list.
+ This is the link for requesting features:
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
+
+\end_inset
+
+.
+\layout Section
+
+Submitting patches
+\layout Standard
+
+Like bug reports contributed patches are forwarded to the developer mailing
+ list.
+ This is the link for submitting patches
+\begin_inset LatexCommand \index{Patch submission}
+
+\end_inset
+
+:
+\begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
+
+\end_inset
+
+.
+\layout Standard
+
+You need to specify some parameters to the
+\family typewriter
+diff
+\family default
+ command for the patches to be useful.
+ If you modified more than one file a patch created f.e.
+ with
+\family sans
+\series bold
+
+\begin_inset Quotes sld
+\end_inset
+
+diff -Naur unmodified_directory modified_directory >my_changes.patch
+\begin_inset Quotes srd
+\end_inset
+
+
+\family default
+\series default
+ will be fine, otherwise
+\family sans
+\series bold
+
+\begin_inset Quotes sld
+\end_inset
+
+diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
+\begin_inset Quotes srd
+\end_inset
+
+
+\series default
+
+\family default
+will do.
+\layout Section
+
+Getting Help
+\layout Standard
+
+These links should take you directly to the
+\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
+
+\end_inset
+
+
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
+ automated messages (mid 2003)
+\end_inset
+
+ and the
+\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
+
+\end_inset
+
+, lists
+\begin_inset LatexCommand \index{Mailing list(s)}
+
+\end_inset
+
+ and forums are archived and searchable so if you are lucky someone already
+ had a similar problem.
+ While mails to the lists themselves are delivered promptly their web front
+ end on sourceforge sometimes shows a severe time lag (up to several weeks),
+ if you're seriously using SDCC please consider subscribing to the lists.
+\layout Section
+
+ChangeLog
+\layout Standard
+
+You can follow the status of the Subversion version
+\begin_inset LatexCommand \index{version}
+
+\end_inset
+
+ of SDCC by watching the Changelog
+\begin_inset LatexCommand \index{Changelog}
+
+\end_inset
+
+ in the Subversion repository
+\size footnotesize
+
+\begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
+
+\end_inset
+
+.
+\layout Section
+
+Subversion Source Code Repository
+\layout Standard
+
+The output of
+\family sans
+\series bold
+sdcc --version
+\family default
+\series default
+ or the filenames of the snapshot versions of SDCC include date and its
+ Subversion
+\begin_inset LatexCommand \index{Subversion}
+
+\end_inset
+
+ number.
+ Subversion allows to download the source of recent or previous versions
+
+\begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599}
+
+\end_inset
+
+ (by number or by date).
+ An on-line source code browser and detailled instructions are also available
+ there.
+ SDCC versions starting from 1999 up to now are available (currently the
+ versions prior to the conversion from cvs to Subversion (April 2006) are
+ either by accessible by Subversion or by cvs).
+\layout Section
+
+Release policy
+\begin_inset LatexCommand \index{Release policy}
+
+\end_inset
+
+
+\layout Standard
+
+Historically there often were long delays between official releases and
+ the sourceforge download area tends to get not updated at all.
+ Excuses in the past might have referred to problems with live range analysis,
+ but as this was fixed a while ago, the current problem is that another
+ excuse has to be found.
+ Kidding aside, we have to get better there! On the other hand there are
+ daily snapshots available at
+\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
+
+\end_inset
+
+, and you can always build the very last version (hopefully with many bugs
+ fixed, and features added) from the source code available at
+\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
+
+\end_inset
+
+.
+\layout Section
+
+Examples
+\begin_inset LatexCommand \index{Examples}
+
+\end_inset
+
+
+\layout Standard
+
+You'll find some small examples in the directory
+\emph on
+sdcc/device/examples/.
+
+\emph default
+More examples and libraries are available at
+\emph on
+ The SDCC Open Knowledge Resource
+\begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
+
+\end_inset
+
+
+\emph default
+web site or at
+\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
+
+\end_inset
+
+.
+\layout Comment
+
+I did insert a reference to Paul's web site here although it seems rather
+ dedicated to a specific 8032 board (I think it's okay because it f.e.
+ shows LCD/Harddisc interface and has a free 8051 monitor.
+ Independent 8032 board vendors face hard competition of heavily subsidized
+ development boards anyway).
+\layout Comment
+
+Maybe we should include some links to real world applications.
+ Preferably pointer to pointers (one for each architecture) so this stays
+ manageable here?
+\layout Section
+
+Quality control
+\begin_inset LatexCommand \index{Quality control}
+
+\end_inset
+
+
+\layout Standard
+
+The compiler is passed through nightly compile and build checks.
+ The so called
+\shape italic
+regression tests
+\shape default
+
+\begin_inset LatexCommand \index{Regression test}
+
+\end_inset
+
+ check that SDCC itself compiles flawlessly on several platforms and checks
+ the quality of the code generated by SDCC by running the code through simulator
+s.
+ There is a separate document
+\shape italic
+test_suite.pdf
+\begin_inset LatexCommand \index{Test suite}
+
+\end_inset
+
+
+\shape default
+ about this.
+\layout Standard
+
+You'll find the test code in the directory
+\shape italic
+sdcc/support/regression
+\shape default
+.
+ You can run these tests manually by running
+\family sans
+make
+\family default
+ in this directory (or f.e.
+
+\family sans
+\series bold
+
+\begin_inset Quotes sld
+\end_inset
+
+make test-mcs51
+\begin_inset Quotes srd
+\end_inset
+
+
+\family default
+\series default
+ if you don't want to run the complete tests).
+ The test code might also be interesting if you want to look for examples
+\begin_inset LatexCommand \index{Examples}
+
+\end_inset
+
+ checking corner cases of SDCC or if you plan to submit patches
+\begin_inset LatexCommand \index{Patch submission}
+
+\end_inset
+
+.
+\layout Standard
+
+The pic port uses a different set of regression tests, you'll find them
+ in the directory
+\shape italic
+sdcc/src/regression
+\shape default
+.
+\layout Section
+
+Use of SDCC in Education
+\layout Standard
+
+In short:
+\emph on
+highly
+\emph default
+ encouraged
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+the phrase "use in education" might evoke the association "
+\emph on
+only
+\emph default
+ fit for use in education".
+ This connotation is not intended but nevertheless risked as the licensing
+ of SDCC makes it difficult to offer educational discounts
+\end_inset
+
+.
+ If your rationales are to:
+\layout Enumerate
+
+give students a chance to understand the
+\emph on
+complete
+\emph default
+ steps of code generation
+\layout Enumerate
+
+have a curriculum that can be extended for years.
+ Then you could use an fpga board as target and your curriculum will seamlessly
+ extend from logic synthesis (
+\begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
+
+\end_inset
+
+,
+\begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
+
+\end_inset
+
+), over assembly programming, to C to FPGA compilers (
+\begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
+
+\end_inset
+
+) and to C.
+\layout Enumerate
+
+be able to insert excursions about skills like using a revision control
+ system, submitting/applying patches, using a type-setting (as opposed to
+ word-processing) engine LyX/LaTeX, using
+\begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
+
+\end_inset
+
+, following some
+\begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
+
+\end_inset
+
+, understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
+ Source Software, CPU simulation, compiler regression tests
+\begin_inset LatexCommand \index{Regression test}
+
+\end_inset
+
+.
+
+\newline
+And if there should be a shortage of ideas then you can always point students
+ to the ever-growing feature request list
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
+
+\end_inset
+
+.
+\layout Enumerate
+
+not tie students to a specific host platform and instead allow them to use
+ a host platform of
+\emph on
+their
+\emph default
+ choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
+ eventually
+\begin_inset LatexCommand \url[OLPC]{http://wiki.laptop.org/wiki/One_Laptop_per_Child}
+
+\end_inset
+
+)
+\layout Enumerate
+
+not encourage students to use illegal copies of educational software
+\layout Enumerate
+
+be immune to licensing/availability/price changes of the chosen tool chain
+\layout Enumerate
+
+be able to change to a new target platform without having to adopt a new
+ tool chain
+\layout Enumerate
+
+have complete control over and insight into the tool chain
+\layout Enumerate
+
+make your students aware about the pros and cons of open source software
+ development
+\layout Enumerate
+
+give back to the public as you are probably at least partially publically
+ funded
+\layout Enumerate
+
+give students a chance to publically prove their skills and to possibly
+ see a world wide impact
+\layout Standard
+
+then SDCC is probably among the first choices.
+ Well, probably SDCC might be the only choice.
+\layout Chapter
+\pagebreak_top
+SDCC Technical Data
+\layout Section
+
+Optimizations
+\begin_inset LatexCommand \index{Optimizations}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC performs a host of standard optimizations in addition to some MCU specific
+ optimizations.
+
+\layout Subsection
+
+Sub-expression Elimination
+\begin_inset LatexCommand \index{Subexpression elimination}
+
+\end_inset
+
+
+\layout Standard
+
+The compiler does local and
+\emph on
+g
+\emph default
+lobal
+\emph on
+c
+\emph default
+ommon
+\emph on
+s
+\emph default
+ubexpression
+\emph on
+e
+\emph default
+limination, e.g.:
+\layout Verse
+
+
+\family typewriter
+i = x + y + 1;
+\newline
+j = x + y;
+\layout Standard
+
+will be translated to
+\layout Verse
+
+
+\family typewriter
+iTemp = x + y;
+\newline
+i = iTemp + 1;
+\newline
+j = iTemp;
+\layout Standard
+
+Some subexpressions are not as obvious as the above example, e.g.:
+\layout Verse
+
+
+\family typewriter
+a->b[i].c = 10;
+\newline
+a->b[i].d = 11;
+\layout Standard
+
+In this case the address arithmetic a->b[i] will be computed only once;
+ the equivalent code in C would be.
+\layout Verse
+
+
+\family typewriter
+iTemp = a->b[i];
+\newline
+iTemp.c = 10;
+\newline
+iTemp.d = 11;
+\layout Standard
+
+The compiler will try to keep these temporary variables in registers.
+\layout Subsection
+
+Dead-Code Elimination
+\begin_inset LatexCommand \index{Dead-code elimination}
+
+\end_inset
+
+
+\layout Verse
+
+
+\family typewriter
+int global;
+\newline
+
+\newline
+void f () {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+int i;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+i = 1; \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\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
+}
+\layout Standard
+
+will be changed to
+\layout Verse
+
+
+\family typewriter
+int global;
+\newline
+
+\newline
+void f () {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+global = 2;
+\newline
+}
+\layout Subsection
+
+Copy-Propagation
+\begin_inset LatexCommand \index{Copy propagation}
+
+\end_inset
+
+
+\layout Verse
+
+
+\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
+}
+\layout Standard
+
+will be changed to
+\layout Verse
+
+
+\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
+}
+\layout Standard
+
+Note: the dead stores created by this copy propagation will be eliminated
+ by dead-code elimination.
+\layout Subsection
+
+Loop Optimizations
+\begin_inset LatexCommand \index{Loop optimization}
+
+\end_inset
+
+
+\begin_inset LatexCommand \label{sub:Loop-Optimizations}
+
+\end_inset
+
+
+\layout Standard
+
+Two types of loop optimizations are done by SDCC
+\emph on
+loop invariant
+\emph default
+ lifting and
+\emph on
+ strength reduction
+\emph default
+ 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
+\begin_inset LatexCommand \index{Register allocation}
+
+\end_inset
+
+, loop induction optimization causes an increase in register pressure, which
+ may cause unwanted spilling of other temporary variables into the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ / 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 -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-noinduction option) or for a given function only using #pragma\SpecialChar ~
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+
+\end_inset
+
+.
+\newline
+
+\newline
+Loop Invariant:
+\layout Verse
+
+
+\family typewriter
+for (i = 0 ; i < 100 ; i ++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+f += k + l;
+\layout Standard
+
+changed to
+\layout Verse
+
+
+\family typewriter
+itemp = k + l;
+\newline
+for (i = 0; i < 100; i++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+f += itemp;
+\layout Standard
+
+As mentioned previously some loop invariants are not as apparent, all static
+ address computations are also moved out of the loop.
+\newline
+
+\newline
+Strength Reduction
+\begin_inset LatexCommand \index{Strength reduction}
+
+\end_inset
+
+, this optimization substitutes an expression by a cheaper expression:
+\layout Verse
+
+
+\family typewriter
+for (i=0;i < 100; i++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ar[i*5] = i*3;
+\layout Standard
+
+changed to
+\layout Verse
+
+
+\family typewriter
+itemp1 = 0;
+\newline
+itemp2 = 0;
+\newline
+for (i=0;i< 100;i++) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ar[itemp1] = itemp2;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+itemp1 += 5;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+itemp2 += 3;
+\newline
+}
+\layout Standard
+
+The more expensive multiplication
+\begin_inset LatexCommand \index{Multiplication}
+
+\end_inset
+
+ is changed to a less expensive addition.
+\layout Subsection
+
+Loop Reversing
+\begin_inset LatexCommand \index{Loop reversing}
+
+\end_inset
+
+
+\layout Standard
+
+This optimization is done to reduce the overhead of checking loop boundaries
+ for every iteration.
+ Some simple loops can be reversed and implemented using a
+\begin_inset Quotes eld
+\end_inset
+
+decrement and jump if not zero
+\begin_inset Quotes erd
+\end_inset
+
+ instruction.
+ SDCC checks for the following criterion to determine if a loop is reversible
+ (note: more sophisticated 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 Subsection
+
+Algebraic Simplifications
+\layout Standard
+
+SDCC does numerous algebraic simplifications, the following is a small sub-set
+ of these optimizations.
+\layout Verse
+
+
+\family typewriter
+i = j + 0;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = j;
+\newline
+i /= 2;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i >>= 1;
+\newline
+i = j - j;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = 0;
+\newline
+i = j / 1;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = j;
+\layout Standard
+
+Note the subexpressions
+\begin_inset LatexCommand \index{Subexpression}
+
+\end_inset
+
+ given above are generally introduced by macro expansions or as a result
+ of copy/constant propagation.
+\layout Subsection
+
+'switch' Statements
+\begin_inset LatexCommand \label{sub:'switch'-Statements}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{switch statement}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC can optimize switch statements to jump tables
+\begin_inset LatexCommand \index{jump tables}
+
+\end_inset
+
+.
+ It makes the decision based on an estimate of the generated code size.
+ SDCC is quite liberal in the requirements for jump table generation:
+\layout Itemize
+
+The labels need not be in order, and the starting number need not be one
+ or zero, the case labels are in numerical sequence or not too many case
+ labels are missing.
+\begin_deeper
+\layout Verse
+
+
+\family typewriter
+switch(i) {\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+switch (i) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 0: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 5: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 8: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 5: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 9: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 10: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 11: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 8: ...
+
+\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 ~
+}
+\layout Standard
+
+Both the above switch statements will be implemented using a jump-table.
+ The example to the right side is slightly more efficient as the check for
+ the lower boundary of the jump-table is not needed.
+\end_deeper
\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.
+The number of case labels is not larger than supported by the target architectur
+e.
\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 -
-\begin_inset ERT
-status Collapsed
+If the case labels are not in numerical sequence ('gaps' between cases)
+ SDCC checks whether a jump table with additionally inserted dummy cases
+ is still attractive.
+
+\layout Itemize
+If the starting number is not zero and a check for the lower boundary of
+ the jump-table can thus be eliminated SDCC might insert dummy cases 0,
+ ...
+ .
\layout Standard
-\backslash
-/
-\end_inset
+Switch statements which have large gaps in the numeric sequence or those
+ that have too many case labels can be split into more than one switch statement
+ for efficient code generation, e.g.:
+\layout Verse
--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:
+\family typewriter
+switch (i) {
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
\newline
-Break down intermediate code (iCode) into basic blocks.
+\SpecialChar ~
+\SpecialChar ~
+case 2: ...
+
\newline
-Do control flow & data flow analysis on the basic blocks.
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
\newline
-Do local common subexpression elimination, then global subexpression elimination
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...
+
\newline
-Dead code elimination
+\SpecialChar ~
+\SpecialChar ~
+case 5: ...
+
\newline
-Loop optimizations
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...
+
\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
-\begin_inset LatexCommand \index{Live range analysis}
-
-\end_inset
-
- is essential for register allocation, since these computation 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.
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...
+
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+case 101: ...
+
\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.
+\SpecialChar ~
+\SpecialChar ~
+case 102: ...
+
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+case 103: ...
+
\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
-\pagebreak_top
-SDCDB
-\begin_inset LatexCommand \index{sdcdb}
-
-\end_inset
-
- - Source Level Debugger
-\begin_inset LatexCommand \index{Debugger}
-
-\end_inset
-
-
-\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
-\begin_inset LatexCommand \index{gdb}
-
-\end_inset
-
- (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.
- Sdcdb is available on Unix platforms only.
-\layout Subsection
-
-Compiling for Debugging
+\SpecialChar ~
+\SpecialChar ~
+case 104: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 105: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 106: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 107: ...
+
+\newline
+}
\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 .adb file for each of these files.
- The linker creates the .cdb file from the .adb files and the address information.
- This .cdb is used by the debugger.
-\layout Subsection
-
-How the Debugger Works
-\layout Standard
+If the above switch statement is broken down into two switch statements
+\layout Verse
-When the -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+switch (i) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 2: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 5: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...
+
+\newline
+}
\layout Standard
-\backslash
-/
-\end_inset
-
--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 .adb file.
- Then the linker creates the .cdb file from the individual .adb files 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
+and
+\layout Verse
-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).
+\family typewriter
+switch (i) {
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+case 101: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 102: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 103: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 104: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 105: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 106: ...
+
\newline
-
-\family sans
-\series bold
-sdcdb foo
+\SpecialChar ~
+\SpecialChar ~
+case 107: ...
+
\newline
+}
+\layout Standard
-\family default
-\series default
+then both the switch statements will be implemented using jump-tables whereas
+ the unmodified switch statement will not be.
+\layout Comment
-\newline
-The debugger will look for the following files.
-\layout Itemize
+There might be reasons which SDCC cannot know about to either favour or
+ not favour jump tables.
+ If the target system has to be as quick for the last switch case as for
+ the first (pro jump table), or if the switch argument is known to be zero
+ in the majority of the cases (contra jump table).
+\layout Standard
-foo.c - the source file.
-\layout Itemize
+The pragma nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
-foo.cdb - the debugger symbol information file.
-\layout Itemize
+\end_inset
-foo.ihx - the Intel hex format
-\begin_inset LatexCommand \index{Intel hex format}
+ can be used to turn off checking the
+\emph on
+j
+\emph default
+ump
+\emph on
+t
+\emph default
+able
+\emph on
+bound
+\emph default
+aries.
+ It has no effect if a default label is supplied.
+ Use of this pragma is dangerous: if the switch
+\begin_inset LatexCommand \index{switch statement}
\end_inset
- object file.
+ argument is not matched by a case statement the processor will happily
+ jump into Nirvana.
\layout Subsection
-Command Line Options.
-\layout Itemize
+Bit-shifting Operations
+\begin_inset LatexCommand \index{Bit shifting}
--
-\begin_inset ERT
-status Collapsed
+\end_inset
+.
\layout Standard
-\backslash
-/
-\end_inset
+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.:
+\layout Verse
--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 -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+unsigned char i;
+\newline
+...
+
+\newline
+i >>= 4;
+\newline
+...
\layout Standard
-\backslash
-/
-\end_inset
+generates the following code:
+\layout Verse
--directory option should be -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+mov\SpecialChar ~
+ a,_i
+\newline
+swap a
+\newline
+anl\SpecialChar ~
+ a,#0x0f
+\newline
+mov\SpecialChar ~
+ _i,a
\layout Standard
-\backslash
-/
-\end_inset
+In general SDCC will never setup a loop if the shift count is known.
+ Another example:
+\layout Verse
--directory=/home/src1:/home/src2.
- Note there can be no spaces in the option.
+
+\family typewriter
+unsigned int i;
+\newline
+...
-\layout Itemize
+\newline
+i >>= 9;
+\newline
+...
+\layout Standard
--cd <directory> - change to the <directory>.
-\layout Itemize
+will generate:
+\layout Verse
--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
+\family typewriter
+mov\SpecialChar ~
+\SpecialChar ~
+a,(_i + 1)
+\newline
+mov\SpecialChar ~
+\SpecialChar ~
+(_i + 1),#0x00
+\newline
+clr\SpecialChar ~
+\SpecialChar ~
+c
+\newline
+rrc\SpecialChar ~
+\SpecialChar ~
+a
+\newline
+mov\SpecialChar ~
+\SpecialChar ~
+_i,a
+\layout Subsection
--X <Clock frequency > this options is passed to the simulator please see
- the simulator docs for details.
-\layout Itemize
+Bit-rotation
+\begin_inset LatexCommand \index{Bit rotation}
--s <serial port file> passed to simulator see the simulator docs for details.
-\layout Itemize
+\end_inset
--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
+A special case of the bit-shift operation is bit rotation
+\begin_inset LatexCommand \index{rotating bits}
-break [line | file:line | function | file:function]
-\layout Standard
+\end_inset
-Set breakpoint at specified line or function:
-\newline
+, SDCC recognizes the following expression to be a left bit-rotation:
+\layout Verse
-\newline
-\family sans
+\family typewriter
\series bold
-sdcdb>break 100
+unsigned
+\series default
+\SpecialChar ~
+\SpecialChar ~
+char i;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* unsigned is needed for rotation */
\newline
-sdcdb>break foo.c:100
+...
+
\newline
-sdcdb>break funcfoo
+i = ((i << 1) | (i >> 7));
+\family default
+
\newline
-sdcdb>break foo.c:funcfoo
-\layout Subsubsection
-clear [line | file:line | function | file:function ]
+\family typewriter
+...
\layout Standard
-Clear breakpoint at specified line or function:
-\newline
+will generate the following code:
+\layout Verse
-\newline
-\family sans
-\series bold
-sdcdb>clear 100
-\newline
-sdcdb>clear foo.c:100
+\family typewriter
+mov\SpecialChar ~
+\SpecialChar ~
+a,_i
\newline
-sdcdb>clear funcfoo
+rl\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+a
\newline
-sdcdb>clear foo.c:funcfoo
-\layout Subsubsection
-
-continue
+mov\SpecialChar ~
+\SpecialChar ~
+_i,a
\layout Standard
-Continue program being debugged, after breakpoint.
-\layout Subsubsection
+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.:
+\layout Verse
-finish
-\layout Standard
-Execute till the end of the current function.
-\layout Subsubsection
+\family typewriter
+i = ((i >> 7) | (i << 1)); /* left-bit rotation */
+\layout Subsection
-delete [n]
+Nibble and Byte Swapping
\layout Standard
-Delete breakpoint number 'n'.
- If used without any option clear ALL user defined break points.
-\layout Subsubsection
+Other special cases of the bit-shift operations are nibble or byte swapping
+\begin_inset LatexCommand \index{swapping nibbles/bytes}
-info [break | stack | frame | registers ]
-\layout Itemize
+\end_inset
-info break - list all breakpoints
-\layout Itemize
+, SDCC recognizes the following expressions:
+\layout Verse
-info stack - show the function call stack.
-\layout Itemize
-info frame - show information about the current execution frame.
-\layout Itemize
+\family typewriter
+\series bold
+unsigned
+\series default
+\SpecialChar ~
+\SpecialChar ~
+char i;
+\newline
-info registers - show content of all registers.
-\layout Subsubsection
+\series bold
+unsigned
+\series default
+\SpecialChar ~
+\SpecialChar ~
+int j;
+\newline
+...
+
+\newline
+i = ((i << 4) | (i >> 4));
+\family default
-step
+\newline
+
+\family typewriter
+j = ((j << 8) | (j >> 8));
\layout Standard
-Step program until it reaches a different source line.
-\layout Subsubsection
+and generates a swap instruction for the nibble swapping
+\begin_inset LatexCommand \index{Nibble swapping}
-next
-\layout Standard
+\end_inset
-Step program, proceeding through subroutine calls.
-\layout Subsubsection
+ or move instructions for the byte swapping
+\begin_inset LatexCommand \index{Byte swapping}
+
+\end_inset
-run
-\layout Standard
+.
+ The
+\begin_inset Quotes sld
+\end_inset
-Start debugged program.
-\layout Subsubsection
+j
+\begin_inset Quotes srd
+\end_inset
-ptype variable
+ example can be used to convert from little to big-endian or vice versa.
+ If you want to change the endianness of a
+\emph on
+signed
+\emph default
+ integer you have to cast to
+\family typewriter
+(unsigned int)
+\family default
+ first.
\layout Standard
-Print type information of the variable.
-\layout Subsubsection
+Note that SDCC stores numbers in little-endian
+\begin_inset Foot
+collapsed false
-print variable
\layout Standard
-print value of variable.
-\layout Subsubsection
+Usually 8-bit processors don't care much about endianness.
+ This is not the case for the standard 8051 which only has an instruction
+ to increment its
+\emph on
+dptr
+\emph default
-file filename
-\layout Standard
+\begin_inset LatexCommand \index{DPTR}
-load the given file name.
- Note this is an alternate method of loading file for debugging.
-\layout Subsubsection
+\end_inset
-frame
-\layout Standard
+-datapointer
+\emph on
+
+\emph default
+so little-endian is the more efficient byte order.
+\end_inset
-print information about current frame.
-\layout Subsubsection
-set srcmode
-\layout Standard
+\begin_inset LatexCommand \index{little-endian}
-Toggle between C source & assembly source.
-\layout Subsubsection
+\end_inset
-! 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
+\begin_inset LatexCommand \index{Endianness}
-quit.
-\layout Standard
+\end_inset
-"Watch me now.
- Iam going Down.
- My name is Bobby Brown"
+ format (i.e.
+ lowest order first).
\layout Subsection
-Interfacing with XEmacs
-\begin_inset LatexCommand \index{XEmacs}
+Highest Order Bit
+\begin_inset LatexCommand \index{Highest Order Bit}
\end_inset
-
-\begin_inset LatexCommand \index{Emacs}
+ / Any Order Bit
+\begin_inset LatexCommand \index{Any Order Bit}
\end_inset
-.
+
\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
+It is frequently required to obtain the highest order bit of an integral
+ type (long, int, short or char types).
+ Also obtaining any other order bit is not uncommon.
+ SDCC recognizes the following expressions to yield the highest order bit
+ and generates optimized code for it, e.g.:
+\layout Verse
-\newline
\family typewriter
-(load-file sdcdbsrc.el)
-\family default
-
+unsigned int gint;
\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:
+foo () {
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+unsigned char hob1, aob1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+bit hob2, hob3, aob2, aob3;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+hob1 = (gint >> 15) & 1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+hob2 = (gint >> 15) & 1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+hob3 = gint & 0x8000;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+aob1 = (gint >> 9) & 1;
\newline
+\SpecialChar ~
+\SpecialChar ~
+aob2 = (gint >> 8) & 1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+aob3 = gint & 0x0800;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+..
+
+\newline
+}
+\layout Standard
-\family sans
-\series bold
-ESC-x sdcdbsrc
-\family default
-\series default
+will generate the following code:
+\layout Verse
-\newline
+\family typewriter
+\SpecialChar ~
+\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
+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 ~
+\SpecialChar ~
+ a,(_gint + 1)
+\newline
+000C 23\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 ~
+ rl\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ a
+\newline
+000D 54 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 64\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ anl\SpecialChar ~
+\SpecialChar ~
+ a,#0x01
+\newline
+000F F5*02\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 65\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ _foo_hob1_1_1,a
\newline
-You will prompted to enter the file name to be debugged.
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 66 ;\SpecialChar ~
+ hob.c 8
\newline
-
+0011 E5*01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 67\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ a,(_gint + 1)
\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
-
+0013 33\SpecialChar ~
\SpecialChar ~
-
-\family typewriter
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 68\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ rlc\SpecialChar ~
+\SpecialChar ~
+ a
\newline
-;; Current Listing ::
+0014 92*00\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 69\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ _foo_hob2_1_1,c
\newline
-;;key\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-binding\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 66 ;\SpecialChar ~
+ hob.c 9
+\newline
+0016 E5*01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-Comment
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 67\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ a,(_gint + 1)
\newline
-;;---\SpecialChar ~
+0018 33\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 68\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-------\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ rlc\SpecialChar ~
+\SpecialChar ~
+ a
+\newline
+0019 92*01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 69\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
---------
+ mov\SpecialChar ~
+\SpecialChar ~
+ _foo_hob3_1_1,c
\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 ~
+ 70 ;\SpecialChar ~
+ hob.c 10
\newline
-;; n\SpecialChar ~
+001B E5*01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-next-from-src\SpecialChar ~
\SpecialChar ~
+ 71\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
-SDCDB next command
+ a,(_gint + 1)
\newline
-;; b\SpecialChar ~
+001D 03\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-back-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 72\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB back command
+\SpecialChar ~
+\SpecialChar ~
+ rr\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ a
\newline
-;; c\SpecialChar ~
+001E 54 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-cont-from-src\SpecialChar ~
\SpecialChar ~
+ 73\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ anl\SpecialChar ~
\SpecialChar ~
-SDCDB continue command
+ a,#0x01
\newline
-;; s\SpecialChar ~
+0020 F5*03\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-step-from-src\SpecialChar ~
\SpecialChar ~
+ 74\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
-SDCDB step command
+ _foo_aob1_1_1,a
\newline
-;; ?\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-whatis-c-sexp\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB ptypecommand for data at
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 75 ;\SpecialChar ~
+ hob.c 11
\newline
-;;\SpecialChar ~
+0022 E5*01\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 76\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ a,(_gint + 1)
+\newline
+0024 13\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 77\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ rrc\SpecialChar ~
\SpecialChar ~
- buffer point
+ a
\newline
-;; x\SpecialChar ~
+0025 92*02\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-delete\SpecialChar ~
\SpecialChar ~
+ 78\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
+ _foo_aob2_1_1,c
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB Delete all breakpoints if no arg
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 79 ;\SpecialChar ~
+ hob.c 12
\newline
-;;\SpecialChar ~
+0027 E5*01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 80\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ a,(_gint + 1)
+\newline
+0029 A2 E3\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 81\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
+ c,acc[3]
+\newline
+002B 92*03\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-given or delete arg (C-u arg x)
-\newline
-;; m\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 82\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-frame\SpecialChar ~
+ _foo_aob3_1_1,c
+\layout Standard
+
+Other variations of these cases however will
+\emph on
+not
+\emph default
+ be recognized.
+ They are standard C expressions, so I heartily recommend these 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.:
+\layout Verse
+
+
+\family typewriter
+xyz = gint + ((gint >> 15) & 1);
+\layout Standard
+
+will still be recognized.
+\layout Subsection
+
+Higher Order Byte
+\begin_inset LatexCommand \index{Higher Order Byte}
+
+\end_inset
+
+ / Higher Order Word
+\begin_inset LatexCommand \index{Higher Order Word}
+
+\end_inset
+
+
+\layout Standard
+
+It is also frequently required to obtain a higher order byte or word of
+ a larger integral type (long, int or short types).
+ SDCC recognizes the following expressions to yield the higher order byte
+ or word and generates optimized code for it, e.g.:
+\layout Verse
+
+
+\family typewriter
+unsigned int gint;
+\newline
+unsigned long int glong;
+\newline
+
+\newline
+foo () {
+\newline
\SpecialChar ~
\SpecialChar ~
+unsigned char hob1, hob2;
+\newline
\SpecialChar ~
\SpecialChar ~
+unsigned int how1, how2;
+\newline
\SpecialChar ~
\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
\SpecialChar ~
+hob1 = (gint >> 8) & 0xFF;
+\newline
\SpecialChar ~
\SpecialChar ~
+hob2 = glong >> 24;
+\newline
\SpecialChar ~
\SpecialChar ~
+how1 = (glong >> 16) & 0xFFFF;
+\newline
\SpecialChar ~
\SpecialChar ~
-SDCDB Display current frame if no arg,
+how2 = glong >> 8;
\newline
-;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+..
+
+\newline
+}
+\layout Standard
+
+will generate the following code:
+\layout Verse
+
+
+\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 91 ;\SpecialChar ~
+ hob.c 15
+\newline
+0037 85*01*06\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 92\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
-given or display frame arg
+ _foo_hob1_1_1,(_gint + 1)
\newline
-;;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 93 ;\SpecialChar ~
+ hob.c 16
+\newline
+003A 85*05*07\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 94\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
-buffer point
+ _foo_hob2_1_1,(_glong + 3)
\newline
-;; !\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-goto-sdcdb\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-Goto the SDCDB output buffer
-\newline
-;; p\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 95 ;\SpecialChar ~
+ hob.c 17
+\newline
+003D 85*04*08\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-print-c-sexp\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 96\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
-SDCDB print command for data at
+ _foo_how1_1_1,(_glong + 2)
\newline
-;;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+0040 85*05*09\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 97\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
+ (_foo_how1_1_1 + 1),(_glong + 3)
+\newline
+0043 85*03*0A\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 98\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
+ _foo_how2_1_1,(_glong + 1)
+\newline
+0046 85*04*0B\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- buffer point
-\newline
-;; g\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 99\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-goto-sdcdb\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
+ (_foo_how2_1_1 + 1),(_glong + 2)
+\layout Standard
+
+Again, variations of these cases may
+\emph on
+not
+\emph default
+ be recognized.
+ They are standard C expressions, so I heartily recommend these be the only
+ way to get the higher order byte/word, (it is portable).
+ Of course it will be recognized even if it is embedded in other expressions,
+ e.g.:
+\layout Verse
+
+
+\family typewriter
+xyz = gint + ((gint >> 8) & 0xFF);
+\layout Standard
+
+will still be recognized.
+\layout Subsection
+
+Peephole Optimizer
+\begin_inset LatexCommand \label{sub:Peephole-Optimizer}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Peephole optimizer}
+
+\end_inset
+
+
+\layout Standard
+
+The compiler uses a rule based, pattern matching and re-writing mechanism
+ for peep-hole optimization.
+ It is inspired by
+\emph on
+copt
+\emph default
+ a peep-hole optimizer by Christopher W.
+ Fraser (cwfraser\SpecialChar ~
+@\SpecialChar ~
+microsoft.com).
+ A default set of rules are compiled into the compiler, additional rules
+ may be added with the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-peep-file
+\begin_inset LatexCommand \index{-\/-peep-file}
+
+\end_inset
+
+ <filename>
+\emph default
+ option.
+ The rule language is best illustrated with examples.
+\layout Verse
+
+
+\family typewriter
+replace {
+\newline
\SpecialChar ~
\SpecialChar ~
+mov %1,a
+\newline
\SpecialChar ~
\SpecialChar ~
+mov a,%1
+\newline
+} by {
+\newline
\SpecialChar ~
\SpecialChar ~
-Goto the SDCDB output buffer
+mov %1,a
+\newline
+}
+\layout Standard
+
+The above rule will change the following assembly
+\begin_inset LatexCommand \index{Assembler routines}
+
+\end_inset
+
+ sequence:
+\layout Verse
+
+
+\family typewriter
+mov r1,a
+\newline
+mov a,r1
+\layout Standard
+
+to
+\layout Verse
+
+
+\family typewriter
+mov r1,a
+\layout Standard
+
+Note: All occurrences of a
+\emph on
+%n
+\emph default
+ (pattern variable) must denote the same string.
+ With the above rule, the assembly sequence:
+\layout Verse
+
+
+\family typewriter
+mov r1,a
+\newline
+mov a,r2
+\layout Standard
+
+will remain unmodified.
+\newline
+
+\newline
+Other special case optimizations may be added by the user (via
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-peep-file option
+\emph default
+).
+ E.g.
+ some variants of the 8051 MCU
+\begin_inset LatexCommand \index{MCS51 variants}
+
+\end_inset
+
+ 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
+\layout Verse
+
+
+\family typewriter
+replace { lcall %1 } by { acall %1 }
\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)
+replace { ljmp %1 } by { ajmp %1 }
+\layout Standard
+
+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:
+\layout Verse
+
+
+\family typewriter
+rule := replace [ restart ] '{' <assembly sequence> '
+\backslash
+n'
\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 ~
+ \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 ~
-SDCDB finish command
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' [if <functionName> ] '
+\backslash
+n'
+\layout Standard
+
+<assembly sequence> := assembly instruction (each instruction including
+ labels must be on a separate line).
\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
+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:
+\layout Verse
+
+
+\family typewriter
+replace restart {
\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
+pop %1
\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 ~
+push %1 } by {
+\newline
\SpecialChar ~
\SpecialChar ~
- Toggle list mode
+; nop
\newline
-;;
-\family default
+}
+\layout Standard
+
+Note that the replace pattern cannot be a blank, but can be a comment line.
+ Without the 'restart' option only the innermost 'pop' 'push' pair would
+ be eliminated, i.e.:
+\layout Verse
+
+\family typewriter
+pop ar1
\newline
+pop ar2
+\newline
+push ar2
+\newline
+push ar1
+\layout Standard
-\layout Section
+would result in:
+\layout Verse
-Other Processors
-\layout Subsection
-The Z80 and gbz80 port
+\family typewriter
+pop ar1
+\newline
+; nop
+\newline
+push ar1
\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
- unimplemented), 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 variables.
- IY is currently unused.
- 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
-\pagebreak_top
-Support
-\begin_inset LatexCommand \index{Support}
+\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:
+\layout Verse
-\end_inset
+
+\family typewriter
+; nop
+\newline
+; nop
+\layout Standard
+
+A conditional function can be attached to a rule.
+ Attaching rules are somewhat more involved, let me illustrate this with
+ an example.
+\layout Verse
+\family typewriter
+replace {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ljmp %5
+\newline
+%2:
+\newline
+} by {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+sjmp %5
+\newline
+%2:
+\newline
+} if labelInRange
\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.
+The optimizer does a look-up of a function name table defined in function
-\layout Standard
-
-The SDCC project is hosted on the sdcc sourceforge site at
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
-
-\end_inset
-
+\emph on
+callFuncByName
+\emph default
+ in the source file SDCCpeeph.c, with the name
+\emph on
+labelInRange
+\emph default
.
- You'll find the complete set of mailing lists
-\begin_inset LatexCommand \index{Mailing list}
+ 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.
+ Currently implemented are
+\emph on
+labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
+ 24bitMode, portIsDS390, 24bitModeAndPortDS390
+\emph default
+and
+\emph on
+ notVolatile
+\emph default
+.
+\layout Standard
-\end_inset
+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 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 -
+\begin_inset ERT
+status Collapsed
-, forums, bug reporting system, patch submission
-\begin_inset LatexCommand \index{Patch submission}
+\layout Standard
+\backslash
+/
\end_inset
- system, download
-\begin_inset LatexCommand \index{download}
-
-\end_inset
+-peep-file option.
+\layout Section
- area and cvs code repository
-\begin_inset LatexCommand \index{cvs code repository}
+ANSI-Compliance
+\begin_inset LatexCommand \index{ANSI-compliance}
\end_inset
- there.
-\layout Subsection
-Reporting Bugs
-\begin_inset LatexCommand \index{Bugs}
+\begin_inset LatexCommand \label{sub:ANSI-Compliance}
\end_inset
-\begin_inset LatexCommand \index{Reporting bugs}
-
-\end_inset
+\layout Standard
+Deviations from the compliance:
+\layout Itemize
-\layout Standard
+functions are not reentrant
+\begin_inset LatexCommand \index{reentrant}
-The recommended way of reporting bugs is using the infrastructure of the
- sourceforge site.
- You can follow the status of bug reports there and have an overview about
- the known bugs.
-\layout Standard
+\end_inset
-Bug reports are automatically forwarded to the developer mailing list and
- will be fixed ASAP.
- When reporting a bug, it is very useful to include a small test program
- (the smaller the better) 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 -
+ unless explicitly declared as such or the
+\series bold
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--dumpall
-\begin_inset LatexCommand \index{-\/-dumpall}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
- option can sometimes be useful in locating optimization problems.
- When reporting a bug please maker sure you:
-\layout Enumerate
-Attach the code you are compiling with SDCC.
-
-\layout Enumerate
+\series default
+ command line option is specified.
+\layout Itemize
-Specify the exact command you use to run SDCC, or attach your Makefile.
-
-\layout Enumerate
+structures and unions 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.:
+\begin_deeper
+\layout Verse
-Specify the SDCC version (type "sdcc -v"), your platform, and operating
- system.
-
-\layout Enumerate
-Provide an exact copy of any error message or incorrect output.
+\family typewriter
+struct s { ...
+ };
+\newline
+struct s s1, s2;
+\newline
+foo()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
-\layout Enumerate
+\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) /* 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
+}
+\end_deeper
+\layout Itemize
-Put something meaningful in the subject of your message.
-\layout Standard
+initialization of structure arrays must be fully braced.
+\begin_deeper
+\layout Verse
-Please attempt to include these 5 important parts, as applicable, in all
- requests for support or when reporting any problems or bugs with SDCC.
- Though this will make your message lengthy, it will greatly improve your
- chance that SDCC users and developers will be able to help you.
- Some SDCC developers are frustrated by bug reports without code provided
- that they can use to reproduce and ultimately fix the problem, so please
- be sure to provide sample code if you are reporting a bug!
-\layout Standard
-Please have a short check that you are using a recent version of SDCC and
- the bug is not yet known.
- This is the link for reporting bugs:
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
+\family typewriter
+struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
+\newline
+struct s { char x } a[] = {{1}, {2}}; /* OK */
+\end_deeper
+\layout Itemize
-\end_inset
+'long long
+\begin_inset LatexCommand \index{long long (not supported)}
-.
-\layout Subsection
+\end_inset
-Requesting Features
-\begin_inset LatexCommand \index{Feature request}
+' (64 bit integers
+\begin_inset LatexCommand \index{int (64 bit) (not supported)}
\end_inset
+) not supported.
+\layout Itemize
-\begin_inset LatexCommand \index{Requesting features}
+'double
+\begin_inset LatexCommand \index{double (not supported)}
\end_inset
+' precision floating point
+\begin_inset LatexCommand \index{Floating point support}
-\layout Standard
+\end_inset
-Like bug reports feature requests are forwarded to the developer mailing
- list.
- This is the link for requesting features:
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
+not supported.
+\layout Itemize
+
+Old K&R style
+\begin_inset LatexCommand \index{K\&R style}
\end_inset
-.
-\layout Subsection
+ function declarations are NOT allowed.
+\begin_deeper
+\layout Verse
-Getting Help
-\layout Standard
-These links should take you directly to the
-\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
+\family typewriter
+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
+}
+\end_deeper
+\layout Itemize
+
+Most enhancements in C99 are not supported, f.e.:
+\begin_deeper
+\layout Verse
-\end_inset
+\family typewriter
+\series bold
+inline
+\series default
+ int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
+ in C99 */
+\newline
+for (
+\series bold
+int
+\series default
+ i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
+\end_deeper
+\layout Itemize
-\begin_inset Foot
-collapsed false
+Certain words that are valid identifiers in the standard may be reserved
+ words in SDCC unless the
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
- automated messages (mid 2003)
-\end_inset
-
- and the
-\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
-
+\backslash
+/
\end_inset
-, lists and forums are archived so if you are lucky someone already had
- a similar problem.
-\layout Subsection
-
-ChangeLog
-\begin_inset LatexCommand \index{Changelog}
+-std-c89
+\begin_inset LatexCommand \index{-\/-std-c89}
\end_inset
+ or -
+\begin_inset ERT
+status Collapsed
\layout Standard
-You can follow the status of the cvs version
-\begin_inset LatexCommand \index{version}
-
+\backslash
+/
\end_inset
- of SDCC by watching the file
-\begin_inset LatexCommand \htmlurl[ChangeLog]{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
+-std-c99
+\begin_inset LatexCommand \index{-\/-std-c99}
\end_inset
- in the cvs-repository.
-\layout Subsection
-Release policy
-\begin_inset LatexCommand \index{Release policy}
+\series default
+ command line options are used.
+ These may include (depending on the selected processor): 'at', 'banked',
+ 'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
+t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
+ 'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
+ '_naked'.
+ Compliant equivalents of these keywords are always available in a form
+ that begin with two underscores
+\begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
\end_inset
+, f.e.
+ '__data' instead of 'data'.
+\layout Section
-\layout Standard
-
-Historically there often were long delays between official releases and
- the sourceforge download area tends to get not updated at all.
- Current excuses might refer to problems with live range analysis, but if
- this is fixed, the next problem rising is that another excuse will have
- to be found.
- Kidding aside, we have to get better there! On the other hand there are
- daily snapshots available at
-\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
-
-\end_inset
-
-, and you can always built the very last version (hopefully with many bugs
- fixed, and features added) from the source code available at
-\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
+Cyclomatic Complexity
+\begin_inset LatexCommand \index{Cyclomatic complexity}
\end_inset
-.
-\layout Subsection
-Examples
-\begin_inset LatexCommand \index{Examples}
+\layout Standard
-\end_inset
+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
-You'll find some small examples in the directory sdcc/device/examples/
-\layout Comment
+complexity = (number of edges in control flow graph) - (number of nodes
+ in control flow graph) + 2;
+\newline
-Maybe we should include some links to real world applications.
- Preferably pointer to pointers (one for each architecture) so this stays
- manageable here?
-\layout Subsection
+\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
-Quality control
-\begin_inset LatexCommand \index{Quality control}
+Retargetting for other Processors
+\layout Standard
-\end_inset
+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 -
+\begin_inset ERT
+status Collapsed
\layout Standard
-The compiler is passed through nightly compile and build checks.
- The so called
-\shape italic
-regression tests
-\shape default
+\backslash
+/
+\end_inset
-\begin_inset LatexCommand \index{Regression test}
+-dumpraw option.
+\layout Itemize
-\end_inset
+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
- check that SDCC itself compiles flawlessly on several platforms and checks
- the quality of the code generated by SDCC by running the code through simulator
+\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.
- There is a separate document
-\shape italic
-test_suite.pdf
-\begin_inset LatexCommand \index{Test suite}
+ Live range analysis
+\begin_inset LatexCommand \index{Live range analysis}
\end_inset
+ is essential for register allocation, since these computation determines
+ which of these iTemps will be assigned to registers, and for how long.
+\layout Itemize
-\shape default
- about this.
-\layout Standard
-
-You'll find the test code in the directory
-\shape italic
-sdcc/support/regression
-\shape default
-.
- You can run these tests manually by running
-\family sans
-make
-\family default
- in this directory (or f.e.
-
-\family sans
-make test-mcs51
-\family default
- if you don't want to run the complete tests).
- The test code might also be interesting if you want to look for examples
-\begin_inset LatexCommand \index{Examples}
+Phase five is register allocation.
+ There are two parts to this process.
+\newline
-\end_inset
+\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
- checking corner cases of SDCC or if you plan to submit patches
-\begin_inset LatexCommand \index{Patch submission}
+\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
-\end_inset
+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
-.
-\layout Standard
+As mentioned in the optimization section the peep-hole optimizer is rule
+ based system, which can reprogrammed for other MCUs.
+\layout Chapter
-The pic port uses a different set of regression tests, you'll find them
- in the directory
-\shape italic
-sdcc/src/regression
-\shape default
-.
-\layout Section
-\pagebreak_top
Compiler internals
\begin_inset LatexCommand \index{Compiler internals}
\end_inset
-\layout Subsection
+\layout Section
The anatomy of the compiler
+\begin_inset LatexCommand \label{sub:The-anatomy-of}
+
+\end_inset
+
+
\layout Standard
\shape italic
This is an excerpt from an article published in Circuit Cellar Magazine
- in august 2000.
+ in
+\series bold
+August 2000
+\series default
+.
It's a little outdated (the compiler is much more efficient now and user/develo
per friendly), but pretty well exposes the guts of it all.
\shape default
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.
+ to the accumulator instead of a general-purpose register.
\layout Paragraph*
Code generation
\series bold
\shape italic
\color red
-<Where is Figure II ?>
+<Where is Figure II?>
+\layout Comment
+
+In the original article Figure II was announced to be downloadable on
+\shape italic
+Circuit Cellar
+\shape default
+'s web site.
+ Unfortunately it never seemed to have shown up there, so: where is Figure
+ II?
\layout Paragraph*
ICode Example
7.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-short i=10; /* dead initialization eliminated */
+short i=10; \SpecialChar ~
+\SpecialChar ~
+/* dead initialization eliminated */
\newline
8.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mul += i * 3; /* this multiplication remains */
+mul += i * 3; \SpecialChar ~
+\SpecialChar ~
+/* this multiplication remains */
\newline
18.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-gint += j * 3;/* this multiplication changed to addition */
+gint += j * 3;\SpecialChar ~
+\SpecialChar ~
+/* this multiplication changed to addition */
\newline
19.\SpecialChar ~
\SpecialChar ~
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).
+ used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (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
ret
\newline
-\layout Subsection
+\layout Section
A few words about basic block successors, predecessors and dominators
\layout Standard
if (something)
\layout Standard
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
[basic block 2]
\layout Standard
else
\layout Standard
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
[basic block 3]
\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
+\layout Chapter
Acknowledgments
\layout Standard
of their respective companies.
-\layout Section
+\layout Section*
Alphabetical index
\layout Standard
-To avoid confusion, the installation and building options for sdcc itself
+To avoid confusion, the installation and building options for SDCC itself
(chapter 2) are not part of the index.
\layout Standard
projects / fw / sdcc / blobdiff