pdftitle={SDCC Compiler User Guide},
pdfauthor={SDCC development team},
pdfsubject={installation, user manual},
- pdfkeywords={8032 8051 ansi c compiler CPU DS390
- embedded GPL HC08 manual mcs51 microcontroller PIC Z80},
+ pdfkeywords={68hc08 8032 8051 ansi c compiler assembler CPU DS390 embedded development free Floating Point Arithmetic Freescale GPL HC08 inline Intel ISO/IEC 9899:1990 Linux MAC OS X manual Maxim mcs51 Microchip microcontroller open source PIC Unix Windows Z80 Zilog},
+ pdfpagemode=UseOutlines,
colorlinks=true,
linkcolor=blue] {hyperref}
%
\size normal
-SDCC 2.5.5
+SDCC 2.6.1
\size footnotesize
\newline
$Revision$
\layout Comment
-The above strings enclosed in $ are automatically updated by cvs
+The above strings enclosed in $ are automatically updated by Subversion
\layout Standard
, 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.
+ It can be retargeted 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
\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
\end_inset
-, an open source retargettable assembler & linker.
+, an open source retargetable 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="block" valignment="top" leftline="true" rightline="true" width="20text%">
+<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.
- SDCDB and ucSim are currently not available on Win32 platforms.
-
-\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 Section
-
-Open Source
\layout Standard
-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}
-
+-
\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 Section
-
-Typographic conventions
-\begin_inset LatexCommand \index{Typographic conventions}
+\layout Standard
+char
\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
-.
+8 bits, 1 byte
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="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 Section
+signed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Compatibility with previous versions
-\begin_inset LatexCommand \index{Compatibility with previous versions}
+\layout Standard
+-128, +127
\end_inset
-
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\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}
-
+0, +255
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- (see section
-\begin_inset LatexCommand \ref{sub:ANSI-Compliance}
+\layout Standard
+short
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- for ANSI-Compliance).
-
-\newline
+\layout Standard
-\layout Itemize
+16 bits, 2 bytes
+\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
+signed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="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
+-32.768, +32.767
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
+0, +65.535
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+int
\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
+16 bits, 2 bytes
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+signed
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--noregparms has been removed.
-\layout Itemize
+\layout Standard
-option -
-\begin_inset ERT
-status Collapsed
+-32.768, +32.767
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+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
--stack-after-data has been removed.
-\layout Itemize
-
-bit
-\begin_inset LatexCommand \index{bit}
+\layout Standard
+long
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- and sbit
-\begin_inset LatexCommand \index{sbit}
+\layout Standard
+32 bits, 4 bytes
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{\_\_sbit}
-
+signed
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- types now consistently behave like the C99 _Bool type with respect to type
- conversion
-\begin_inset LatexCommand \index{type conversion}
+\layout Standard
+-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
+\layout Standard
-\begin_inset LatexCommand \index{type promotion}
-
+0, +4.294.967.295
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
- The most common incompatibility resulting from this change is related to
- bit toggling
-\begin_inset LatexCommand \index{Bit toggling}
+\layout Standard
+float
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- idioms, e.g.:
-\newline
+\layout Standard
-\family typewriter
-\SpecialChar ~
-\SpecialChar ~
-bit b;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-b = ~b; /* equivalent to b=1 instead of toggling b */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-b = !b; /* toggles b */
-\newline
+4 bytes IEEE 754
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family default
-In previous versions, both forms would have toggled the bit.
\layout Standard
+signed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\emph on
-<pending: more incompatibilities?>
-\layout Section
-
-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 Section
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-Other Resources
\layout Standard
-The SDCC home page at
-\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
-
+1.175494351E-38,
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+3.402823466E+38
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="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.
- A pdf version of this document is available at
-\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
+\layout Standard
+pointer
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
- 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 Section
-
-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
+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
-
-\family typewriter
-char KernelFunction3(char p) at 0x340;
-\newline
+generic
+\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
-\family typewriter
-better code banking
-\begin_inset LatexCommand \index{code banking (limited support)}
+\layout Standard
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
\end_inset
- support for mcs51
+
+\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
-\family default
-If you can think of some more, please see the section
-\begin_inset LatexCommand \ref{sub:Requesting-Features}
+\layout Standard
+\backslash
+/
\end_inset
- about filing feature requests
-\begin_inset LatexCommand \index{Requesting features}
-
-\end_inset
+-cyclomatic) to report the relative complexity of a function.
+ These functions can then be further optimized, or hand coded in assembly
+ if needed.
+
+\newline
+\newline
+SDCC also comes with a companion source level debugger SDCDB, the debugger
+ currently uses ucSim a freeware simulator for 8051 and other micro-controllers.<
+\newline
-\begin_inset LatexCommand \index{Feature request}
+\newline
+The latest version can be downloaded from
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
\end_inset
.
-\newline
-\layout Chapter
+\series bold
+
+\series default
+\emph on
+Please note: the compiler will probably always be some steps ahead of this
+ documentation
+\series bold
+\emph default
-Installing SDCC
-\begin_inset LatexCommand \index{Installation}
+\begin_inset LatexCommand \index{Status of documentation}
\end_inset
-\layout Standard
-
-For most users it is sufficient to skip to either section
-\begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
-
-\end_inset
+\begin_inset Foot
+collapsed false
- or section
-\begin_inset LatexCommand \ref{sub:Windows-Install}
+\layout Standard
+Obviously this has pros and cons
\end_inset
.
- More detailled instructions follow below.
\layout Section
-Configure Options
-\begin_inset LatexCommand \index{Options SDCC configuration}
-
-\end_inset
-
-
+Open Source
\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
-
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+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}
-\backslash
-/
\end_inset
--prefix see table below
-\layout List
-\labelwidthstring 00.00.0000
-
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+ 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
-/
\end_inset
--exec_prefix see table below
-\layout List
-\labelwidthstring 00.00.0000
-
--
-\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
--bindir see table below
-\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
+.
--datadir see table below
-\layout List
-\labelwidthstring 00.00.0000
+\family default
+ Code samples are printed in
+\family typewriter
+typewriter font.
-docdir environment variable, see table below
-\layout List
-\labelwidthstring 00.00.0000
+\family default
+ Interesting items and new terms are printed in
+\emph on
+italic.
+\layout Section
-include_dir_suffix environment variable, see table below
-\layout List
-\labelwidthstring 00.00.0000
+Compatibility
+\begin_inset LatexCommand \label{sec:Compatibility-with-previous}
-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
+ with previous versions
+\begin_inset LatexCommand \index{Compatibility with previous versions}
-\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
\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-mcs51-port Excludes the Intel mcs51 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-gbz80-port Excludes the Gameboy gbz80 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
+\begin_inset LatexCommand \index{vararg, va\_arg}
-\backslash
-/
\end_inset
--disable-z80-port Excludes the z80 port
-\layout List
-\labelwidthstring 00.00.0000
-
--
-\begin_inset ERT
-status Collapsed
+ functions are casted to int unless explicitly casted
+\begin_inset Marginal
+collapsed true
\layout Standard
-\backslash
-/
-\end_inset
-
--disable-avr-port Excludes the AVR port
-\layout List
-\labelwidthstring 00.00.0000
--
-\begin_inset ERT
-status Collapsed
+\series bold
+\SpecialChar ~
+!
+\end_inset
-\layout Standard
+, 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-ds390-port Excludes the DS390 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-hc08-port Excludes the HC08 port
-\layout List
-\labelwidthstring 00.00.0000
+-regextend has been removed.
+\layout Itemize
--
+option -
\begin_inset ERT
status Collapsed
/
\end_inset
--disable-pic-port Excludes the PIC port
-\layout List
-\labelwidthstring 00.00.0000
+-noregparms has been removed.
+\layout Itemize
--
+option -
\begin_inset ERT
status Collapsed
/
\end_inset
--disable-xa51-port Excludes the XA51 port
-\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-ucsim Disables configuring and building of ucsim
-\layout List
-\labelwidthstring 00.00.0000
-
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+ and sbit
+\begin_inset LatexCommand \index{sbit}
-\backslash
-/
\end_inset
--disable-device-lib-build Disables automatically building device libraries
-\layout List
-\labelwidthstring 00.00.0000
--
-\begin_inset ERT
-status Collapsed
+\begin_inset LatexCommand \index{\_\_sbit}
-\layout Standard
+\end_inset
+
+ types now consistently behave like the C99 _Bool type with respect to type
+ conversion
+\begin_inset LatexCommand \index{type conversion}
-\backslash
-/
\end_inset
--disable-packihx Disables building packihx
-\layout List
-\labelwidthstring 00.00.0000
--
-\begin_inset ERT
-status Collapsed
+\begin_inset LatexCommand \index{type promotion}
-\layout Standard
+\end_inset
-\backslash
-/
-\end_inset
-
--enable-libgc Use the Bohem memory allocator.
- Lower runtime footprint.
-\layout Standard
-
-Furthermore the environment variables CC, CFLAGS, ...
- the tools and their arguments can be influenced.
- Please see `configure -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+.
+ The most common incompatibility resulting from this change is related to
+ bit toggling
+\begin_inset LatexCommand \index{Bit toggling}
-\backslash
-/
\end_inset
--help` and the man/info pages of `configure` for details.
-\newline
-
-\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
-
-\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
+\SpecialChar ~
+\SpecialChar ~
+b = ~
+\begin_inset LatexCommand \index{\~\/ Operator}
-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
+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
+\SpecialChar ~
+!
+\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
+\emph on
+<pending: more incompatibilities?>
+\layout Section
+System Requirements
\layout Standard
-default
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
-Win32 builds
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The SDCC home page at
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
-\layout Standard
+\end_inset
+ is a great place to find distribution sets.
+ You can also find links to the user mailing lists that offer help or discuss
+ SDCC with other SDCC users.
+ Web links to other SDCC related sites can also be found here.
+ This document can be found in the DOC directory of the source package as
+ a text or HTML file.
+ A pdf version of this document is available at
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
-\emph on
-PREFIX
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+.
+ 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
-/usr/local
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
-\backslash
-sdcc
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<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
-EXEC_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" usebox="none">
-\begin_inset Text
-\layout Standard
+ support for mcs51
+\newline
+\newline
-\emph on
-$PREFIX
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
-$PREFIX
\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{Feature request}
-\emph on
-BINDIR
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+\newline
+\layout Chapter
+
+Installing SDCC
+\begin_inset LatexCommand \index{Installation}
-\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
+\layout Standard
-\emph on
-$EXECPREFIX
-\emph default
+For most users it is sufficient to skip to either section
+\begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
-\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
+ (Unix) or section
+\begin_inset LatexCommand \ref{sub:Windows-Install}
-\emph on
-DATADIR
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ (Windows).
+ More detailed instructions follow below.
+\layout Section
+Configure Options
+\begin_inset LatexCommand \index{Options SDCC configuration}
-\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
+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
-$PREFIX
-\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
-
-\emph on
-DOCDIR
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-prefix see table below
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\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
+-exec_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
+-bindir 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
+-datadir 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
+docdir environment variable, see table below
+\layout List
+\labelwidthstring 00.00.0000
-\layout Standard
+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
-\emph on
-LIB_DIR_SUFFIX
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+sdccconf_h_dir_separator environment variable, either / or
+\backslash
-\layout Standard
+\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
-sdcc/lib
-\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
-lib
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
+\backslash
+/
\end_inset
+-disable-mcs51-port Excludes the Intel mcs51 port
+\layout List
+\labelwidthstring 00.00.0000
-\newline
+-
+\begin_inset ERT
+status Collapsed
\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
-\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
+-disable-gbz80-port Excludes the Gameboy gbz80 port
+\layout List
+\labelwidthstring 00.00.0000
-Variable (computed)
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\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
-\layout Standard
+-disable-z80-port Excludes the z80 port
+\layout List
+\labelwidthstring 00.00.0000
-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
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\emph on
-BIN2DATA_DIR
+\backslash
+/
\end_inset
-</cell>
-<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
-../share
-\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
-..
+\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-ds390-port Excludes the DS390 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-hc08-port Excludes the HC08 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
-
-share/sdcc
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\newline
-
-\layout Standard
-\noindent
-Examples:
-\layout LyX-Code
+-disable-pic-port Excludes the PIC port
+\layout List
+\labelwidthstring 00.00.0000
-./configure
-\newline
-./configure -
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--prefix=
-\begin_inset Quotes srd
-\end_inset
-
-/usr/bin
-\begin_inset Quotes srd
-\end_inset
+-disable-xa51-port Excludes the XA51 port
+\layout List
+\labelwidthstring 00.00.0000
- -
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--datadir=
-\begin_inset Quotes srd
-\end_inset
-
-/usr/share
-\begin_inset Quotes srd
-\end_inset
-
+-disable-ucsim Disables configuring and building of ucsim
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-./configure -
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--disable-avr-port -
+-disable-device-lib Disables automatically building device libraries
+\layout List
+\labelwidthstring 00.00.0000
+
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--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
-
-\newline
-CC=
-\begin_inset Quotes srd
-\end_inset
-
-i586-mingw32msvc-gcc
-\begin_inset Quotes srd
-\end_inset
-
- CXX=
-\begin_inset Quotes srd
-\end_inset
-
-i586-mingw32msvc-g++
-\begin_inset Quotes srd
-\end_inset
+-disable-packihx Disables building packihx
+\layout List
+\labelwidthstring 00.00.0000
-
-\backslash
-
-\newline
-RANLIB=
-\begin_inset Quotes srd
-\end_inset
+-
+\begin_inset ERT
+status Collapsed
-i586-mingw32msvc-ranlib
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-
\backslash
-
-\newline
-STRIP=
-\begin_inset Quotes srd
-\end_inset
-
-i586-mingw32msvc-strip
-\begin_inset Quotes srd
+/
\end_inset
-
-\backslash
+-enable-doc Build pdf, html and txt files from the lyx sources
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-
\begin_inset ERT
status Collapsed
/
\end_inset
--prefix=
-\begin_inset Quotes srd
-\end_inset
-
-/sdcc
-\begin_inset Quotes srd
-\end_inset
-
-
-\backslash
+-enable-libgc Use the Bohem memory allocator.
+ Lower runtime footprint.
+\layout Standard
-\newline
--
+Furthermore the environment variables CC, CFLAGS, ...
+ the tools and their arguments can be influenced.
+ Please see `configure -
\begin_inset ERT
status Collapsed
/
\end_inset
--datadir=
-\begin_inset Quotes srd
-\end_inset
-
-/sdcc
-\begin_inset Quotes srd
-\end_inset
-
-
-\backslash
-
+-help` and the man/info pages of `configure` for details.
\newline
-docdir=
-\begin_inset Quotes srd
-\end_inset
-/sdcc/doc
-\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
-
-\backslash
+\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
\newline
-include_dir_suffix=
-\begin_inset Quotes srd
+The settings for
+\begin_inset Quotes sld
\end_inset
-include
+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
-lib_dir_suffix=
-\begin_inset Quotes srd
-\end_inset
+open source,
+\layout Enumerate
-lib
-\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
-sdccconf_h_dir_separator=
-\begin_inset Quotes srd
-\end_inset
+\newline
+These defaults are:
+\newline
-\backslash
-
-\backslash
+\layout Standard
+\align center
-\backslash
+\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
-\backslash
+\layout Standard
-\begin_inset Quotes srd
+Variable
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\backslash
+\layout Standard
-\newline
--
-\begin_inset ERT
-status Collapsed
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+Win32 builds
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--disable-device-lib-build
-\backslash
+\layout Standard
-\newline
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-\backslash
-/
+\emph on
+PREFIX
\end_inset
-
--disable-ucsim
-\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
-/
+/usr/local
\end_inset
-
--host=i586-mingw32msvc -
-\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
-/
+sdcc
\end_inset
+</cell>
+</row>
+<row topline="true">
+<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
+EXEC_PREFIX
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-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
+\emph on
+$PREFIX
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--mno-cygwin -O2
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-
-\backslash
-\newline
-LDFLAGS=
-\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
--mno-cygwin
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-
-\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
-/
-\end_inset
-
--prefix=
-\begin_inset Quotes srd
-\end_inset
-/sdcc
-\begin_inset Quotes srd
+\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
-
-\backslash
+\layout Standard
-\newline
--
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\emph on
+$EXECPREFIX
+\emph default
\backslash
-/
+bin
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--datadir=
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-/sdcc
-\begin_inset Quotes srd
+
+\emph on
+DATADIR
\end_inset
+</cell>
+<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
+\emph default
+/share
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-
-\backslash
-
-\newline
-include_dir_suffix=
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-include
-\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
-lib_dir_suffix=
-\begin_inset Quotes srd
-\end_inset
-lib
-\begin_inset Quotes srd
+\emph on
+DOCDIR
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\backslash
+\layout Standard
-\newline
-sdccconf_h_dir_separator=
-\begin_inset Quotes srd
+
+\emph on
+$DATADIR
+\emph default
+/sdcc/doc
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\backslash
-\backslash
+\emph on
+$DATADIR
+\emph default
\backslash
+doc
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\backslash
+\layout Standard
-\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
+\layout Standard
-\newline
--
-\begin_inset ERT
-status Collapsed
+sdcc/include
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+include
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--disable-ucsim
\layout Standard
-'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
- The option '-
-\begin_inset ERT
-status Collapsed
+
+\emph on
+LIB_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+sdcc/lib
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--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
-
-Install paths
-\begin_inset LatexCommand \label{sub:Install-paths}
+\layout Standard
+lib
\end_inset
-
-
-\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
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-
-\series bold
-Path
+Variable (computed)
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-
-\series bold
-Default
+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="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Binary files*
-\end_inset
-</cell>
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\emph on
-$EXEC_PREFIX
+BIN2DATA_DIR
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-/usr/local/bin
+../share
\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
+PREFIX2BIN_DIR
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-/usr/local/share/sdcc/include
+bin
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\backslash
-sdcc
-\backslash
-include
+bin
\end_inset
</cell>
</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Library file**
-\end_inset
-</cell>
+<row bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\emph on
-$DATADIR/$LIB_DIR_SUFFIX
+PREFIX2DATA_DIR
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-/usr/local/share/sdcc/lib
+share/sdcc
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\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
+</lyxtabular>
-Documentation
\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
-$DOCDIR
+\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/doc
+/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
-doc
+/
\end_inset
-</cell>
-</row>
-</lyxtabular>
+-datadir=
+\begin_inset Quotes srd
\end_inset
-
-\layout Verse
+/usr/share
+\begin_inset Quotes srd
+\end_inset
-\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
+./configure -
+\begin_inset ERT
+status Collapsed
-make install prefix=$(HOME)/local/sdcc
\layout Standard
-Of course this doesn't change the search paths compiled into the binaries.
-\newline
+\backslash
+/
+\end_inset
-\newline
-Moreover the install path can be changed by defining DESTDIR
-\begin_inset LatexCommand \index{DESTDIR}
+-disable-avr-port -
+\begin_inset ERT
+status Collapsed
-\end_inset
+\layout Standard
-:
-\layout LyX-Code
+\backslash
+/
+\end_inset
-make install DESTDIR=$(HOME)/sdcc.rpm/
+-disable-xa51-port
\layout Standard
-Please note that DESTDIR must have a trailing slash!
-\layout Section
+To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
+32'):
+\layout LyX-Code
-Search Paths
-\begin_inset LatexCommand \label{sub:Search-Paths}
+./configure
+\backslash
+\newline
+CC=
+\begin_inset Quotes srd
\end_inset
+i586-mingw32msvc-gcc
+\begin_inset Quotes srd
+\end_inset
-\begin_inset LatexCommand \index{Search path}
+ CXX=
+\begin_inset Quotes srd
+\end_inset
+i586-mingw32msvc-g++
+\begin_inset Quotes srd
\end_inset
+
+\backslash
+
+\newline
+RANLIB=
+\begin_inset Quotes srd
+\end_inset
-\layout Standard
+i586-mingw32msvc-ranlib
+\begin_inset Quotes srd
+\end_inset
-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
-
-\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
-
-\layout Standard
+STRIP=
+\begin_inset Quotes srd
+\end_inset
-Search path
+i586-mingw32msvc-strip
+\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
+-prefix=
+\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
-\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
-$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
+-datadir=
+\begin_inset Quotes srd
+\end_inset
-Path of argv[0] (if available)
+/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
-Path of argv[0]
+\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
-
-Path of argv[0]
+/sdcc/doc
+\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
+include_dir_suffix=
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-
-$PATH
+include
+\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
+
+\backslash
-$PATH
+\newline
+lib_dir_suffix=
+\begin_inset Quotes srd
\end_inset
-</cell>
-</row>
-</lyxtabular>
+lib
+\begin_inset Quotes srd
\end_inset
-\newline
+\backslash
-\layout Standard
-\noindent
-2.
- Include files
\newline
+sdccconf_h_dir_separator=
+\begin_inset Quotes srd
+\end_inset
-\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
-\layout Standard
+\backslash
-Search path
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\backslash
-\layout Standard
+\backslash
-default
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+
+\backslash
+
+\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
+-disable-device-lib
+\backslash
+\newline
-
\begin_inset ERT
status Collapsed
/
\end_inset
--I dir
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+-host=i586-mingw32msvc
+\backslash
+\newline
-
\begin_inset ERT
status Collapsed
/
\end_inset
--I dir
+-build=unknown-unknown-linux-gnu
+\layout Standard
+
+To
+\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
+cross
+\begin_inset Quotes srd
+\end_inset
+
+compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
+):
+\layout LyX-Code
+
+./configure -C
+\backslash
+\newline
-
\begin_inset ERT
status Collapsed
/
\end_inset
--I dir
+-prefix=
+\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
-\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
-$SDCC_INCLUDE
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-$SDCC_HOME/
-\newline
+-datadir=
+\begin_inset Quotes srd
+\end_inset
-\emph on
-$PREFIX2DATA_DIR/
-\newline
-$INCLUDE_DIR_SUFFIX
+/sdcc
+\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
+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
-include
+
+\newline
+include_dir_suffix=
+\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
-path(argv[0])/
-\newline
+include
+\begin_inset Quotes srd
+\end_inset
-\emph on
-$BIN2DATADIR/
-\emph default
+
+\backslash
\newline
+lib_dir_suffix=
+\begin_inset Quotes srd
+\end_inset
-\emph on
-$INCLUDE_DIR_SUFFIX
+lib
+\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(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
+CC=
+\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
+gcc -mno-cygwin
+\begin_inset Quotes srd
+\end_inset
-(not on Win32)
+
+\backslash
+
+\newline
+CXX=
+\begin_inset Quotes srd
\end_inset
-</cell>
-</row>
-</lyxtabular>
+g++ -mno-cygwin
+\begin_inset Quotes srd
\end_inset
-\newline
-
\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" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Win32 builds
+
+\series bold
+Default
\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
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
--L dir
+\series bold
+Win32 builds
\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
-
--L dir
+Binary files*
\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
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
--L dir
+\emph on
+$EXEC_PREFIX
\end_inset
</cell>
-</row>
-<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-$SDCC_LIB/
-\newline
-
-\emph on
-<model>
+/usr/local/bin
\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
-$SDCC_LIB/
-\newline
-\emph on
-<model>
+\backslash
+sdcc
+\backslash
+bin
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-$SDCC_LIB
-\backslash
-
-\newline
-
-\emph on
-<model>
+Include files
\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
-$SDCC_HOME/
-\newline
\emph on
-$PREFIX2DATA_DIR/
-\newline
-$LIB_DIR_SUFFIX/<model>
+$DATADIR/ $INCLUDE_DIR_SUFFIX
\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_HOME/
-\newline
-share/sdcc/
-\newline
-lib/
-\emph on
-<model>
+/usr/local/share/sdcc/include
\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" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-$SDCC_HOME
+
\backslash
-lib
+sdcc
\backslash
-
-\emph on
-
-\newline
-<model>
+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" usebox="none">
\begin_inset Text
\layout Standard
-path(argv[0])/
-\newline
+Library file**
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\emph on
-$BIN2DATADIR/
-\emph default
+\layout Standard
-\newline
\emph on
-$LIB_DIR_SUFFIX/<model>
+$DATADIR/$LIB_DIR_SUFFIX
\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
-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 ~
-
+/usr/local/share/sdcc/lib
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-path(argv[0])
-\backslash
-\newline
-..
\backslash
-lib
+sdcc
\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 ~
-
+lib
\end_inset
</cell>
</row>
\layout Standard
+Documentation
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
\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 Section
-
-Building SDCC
-\begin_inset LatexCommand \index{Building SDCC}
-
-\end_inset
+:
+\layout LyX-Code
+make install DESTDIR=$(HOME)/sdcc.rpm/
+\layout Standard
-\layout Subsection
+Please note that DESTDIR must have a trailing slash!
+\layout Section
-Building SDCC on Linux
-\begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
+Search Paths
+\begin_inset LatexCommand \label{sub:Search-Paths}
\end_inset
-\layout Enumerate
-
-
-\series medium
-Download the source package
-\series default
- either from the SDCC CVS 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}
+\begin_inset LatexCommand \index{Search path}
\end_inset
-.
-\layout Enumerate
-
-
-\series medium
-Bring up a command line terminal, such as xterm.
-\layout Enumerate
-
-\series medium
-Unpack the file using a command like:
-\family sans
-\series bold
-"tar -xvzf 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
+\layout Standard
-Change directory into the main SDCC directory, for example type:
-\family sans
-\series bold
-"cd sdcc
-\series default
-".
-\layout Enumerate
+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
+\newline
+1.
+ Binary files (preprocessor, assembler and linker)
+\newline
-\series medium
-Type
-\family sans
-\series bold
-"./configure
-\family default
-\series default
-".
- This configures the package for compilation on your system.
-\layout Enumerate
+\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
-\series medium
-Type
-\family sans
-\series bold
-"make
-\family default
-\series default
-"
-\series medium
-.
+\layout Standard
-\series default
- All of the source packages will compile, this can take a while.
-\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 install"
-\family default
-\series default
- as root
-\series medium
-.
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\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}
+\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
-.
-\layout Subsection
-
-Building SDCC on OSX 2.x
\layout Standard
-Follow the instruction for Linux.
-\newline
+$SDCC_HOME/
+\emph on
+$PPREFIX2BIN_DIR
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="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 Subsection
+$SDCC_HOME/bin
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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 Subsection
+$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
-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 Subsection
+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 using Cygwin and Mingw32
\layout Standard
-For building and installing a Cygwin executable follow the instructions
- for Linux.
-\newline
-
-\newline
-On Cygwin a
-\begin_inset Quotes sld
+Path of argv[0]
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-native
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
- 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
+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
-\newline
-In order to install Cygwin on Windows download setup.exe from
-\begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
+\layout Standard
+$PATH
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
- Run it, set the
-\begin_inset Quotes sld
-\end_inset
+\layout Standard
-default text file type
-\begin_inset Quotes srd
+$PATH
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- to
-\begin_inset Quotes sld
+\layout Standard
+
+$PATH
\end_inset
+</cell>
+</row>
+</lyxtabular>
-unix
-\begin_inset Quotes srd
\end_inset
- 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
+
+\newline
-flex
-\layout Itemize
+\layout Standard
+\noindent
+2.
+ Include files
+\newline
-bison
-\layout Itemize
+\layout Standard
+\align center
-gcc ; version 3.x is fine, no need to use the old 2.9x
-\layout Itemize
+\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
-binutils ; selected with gcc
-\layout Itemize
+\layout Standard
-make
-\layout Itemize
+Search path
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-rxvt ; a nice console, which makes life much easier under windoze (see below)
-\layout Itemize
+\layout Standard
-man ; not really needed for building SDCC, but you'll miss it sooner or
- later
-\layout Itemize
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-less ; not really needed for building SDCC, but you'll miss it sooner or
- later
-\layout Itemize
+\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
-cvs ; only if you use CVS access
\layout Standard
-If you want to develop something you'll need:
-\layout Itemize
+-
+\begin_inset ERT
+status Collapsed
-python ; for the regression tests
-\layout Itemize
+\layout Standard
-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
+-I dir
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Text selected with the mouse is automatically copied to the clipboard, pasting
- works with shift-insert.
-\newline
+\layout Standard
-\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
+$SDCC_INCLUDE
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-cygdrive
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
- is too long, you can change it with e.g.
-\layout LyX-Code
+$SDCC_INCLUDE
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-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 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)}
-
+$SDCC_INCLUDE
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- 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
-
-Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
\layout Standard
+$SDCC_HOME/
+\newline
-\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}
-
+\emph on
+$PREFIX2DATA_DIR/
+\newline
+$INCLUDE_DIR_SUFFIX
\end_inset
+</cell>
+<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
-
+share/sdcc/
\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 CVS repository it's easiest to configure the cvs 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
+include
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- 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
+\layout Standard
-unix2dos
-\begin_inset Quotes srd
+$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
- utility freely available on the internet.
- Doug Hawkins reported in the sdcc-user list that this works:
-\newline
+\layout Standard
+path(argv[0])/
\newline
-C:
-\backslash
-Programming
-\backslash
-SDCC> unix2dos sdcc.dsw
-\newline
-C:
-\backslash
-Programming
-\backslash
-SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
-\newline
+
+\emph on
+$BIN2DATADIR/
+\emph default
\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}
+\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
-Download the file UnxUtils
-\begin_inset LatexCommand \index{UnxUtils}
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\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
-.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
+path(argv[0])
\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
+include
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-A more compact way:
-\newline
+\layout Standard
-\newline
-This one avoids extracting a bunch of files you may not use, but requires
- some extra work:
-\newline
-\newline
-a) Create a directory were to put the tools needed, or use a directory already
- present.
- Say for example 'C:
-\backslash
-util'.
-\newline
+\emph on
+$DATADIR/
+\emph default
\newline
-b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
- to such directory WITHOUT preserving the original paths.
- (If you are using WinZip make certain that 'Use folder names' is not selected)
-\newline
-\newline
-c) Rename bison.exe to '_bison.exe'.
-\newline
+\emph on
+$INCLUDE_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\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
+\layout Standard
+/usr/local/share/sdcc/
\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
+include
+\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
-\backslash
-bin_vc to sdcc
-\backslash
-bin, and you can compile using SDCC.
-\layout Subsection
-
-Building SDCC Using Borland
-\layout Enumerate
+(not on Win32)
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-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
+\end_inset
-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
+\layout Standard
+\noindent
+The option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
-\family sans
-\series bold
-find .
-
-\backslash
-( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
-\backslash
-) -print -exec rm {}
\backslash
-;
-\family default
-\series default
+/
+\end_inset
+-nostdinc disables the last two search paths.
\newline
\newline
-or on Windows NT/2000/XP from the command prompt with the command:
+3.
+ Library files
\newline
-\family sans
-\series bold
+\layout Standard
-\newline
-del /s *.obj *.lib *.rul
-\family default
-\series default
- from the sdcc directory.
-\layout Subsection
+With the exception of
+\begin_inset Quotes sld
+\end_inset
-Windows Install Using a ZIP Package
-\layout Enumerate
+-
+\begin_inset ERT
+status Collapsed
-Download the binary zip package from
-\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
+\layout Standard
+\backslash
+/
\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
-
-Adjust your environment variable PATH to include the location of the bin
- directory or start sdcc using the full path.
-\layout Subsection
-
-Windows Install Using the Setup Program
-\begin_inset LatexCommand \label{sub:Windows-Install}
-
+-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
-Download the setup program
-\emph on
-sdcc-x.y.z-setup.exe
-\emph default
- for an official release from
-\newline
+\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
-\begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
+\layout Standard
+Search path
\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- or a setup program for one of the snapshots
-\emph on
-sdcc_yyyymmdd_setup.exe
-\emph default
- from
-\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
+\layout Standard
+default
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- and execute it.
- A windows typical installer will guide you through the installation process.
-\layout Section
+\layout Standard
+
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Building the Documentation
\layout Standard
-If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
- as changing into the doc directory and typing
-\family sans
-\series bold
+-
+\begin_inset ERT
+status Collapsed
-\begin_inset Quotes srd
-\end_inset
+\layout Standard
-make
-\begin_inset Quotes srd
+\backslash
+/
\end_inset
+-L dir
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family default
-\series default
- 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}
+\layout Standard
-\end_inset
+-
+\begin_inset ERT
+status Collapsed
- as editor this is straightforward.
- Prebuilt documentation in html and pdf format is available from
-\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
+\layout Standard
+\backslash
+/
\end_inset
-.
-\layout Section
+-L dir
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-Reading the Documentation
\layout Standard
-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
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-If you should know why please drop us a note
+\backslash
+/
\end_inset
-.
-
-\newline
-You'll find the pdf version
-\begin_inset LatexCommand \index{PDF version of this document}
-
+-L dir
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- at
-\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
+\layout Standard
+
+$SDCC_LIB/
+\newline
+\emph on
+<model>
\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-
+\layout Standard
+
+$SDCC_LIB/
\newline
-A html version
-\begin_inset LatexCommand \index{HTML version of this document}
+\emph on
+<model>
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- should be online at
-\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
+\layout Standard
-\end_inset
+$SDCC_LIB
+\backslash
-.
\newline
-This documentation is in some aspects different from a commercial documentation:
-
-\layout Itemize
-
-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}
+\emph on
+<model>
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- 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
+\layout Standard
-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}
+$SDCC_HOME/
+\newline
+\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
- together with a statement
-\begin_inset Quotes sld
-\end_inset
+\layout Standard
-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
+$SDCC_HOME/
+\newline
+share/sdcc/
+\newline
+lib/
\emph on
-a
-\emph default
-rray
-\begin_inset LatexCommand \index{FPGA (field programmable gate array)}
-
+<model>
\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset Quotes srd
-\end_inset
+$SDCC_HOME
+\backslash
+lib
+\backslash
- or
-\begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
+\emph on
+\newline
+<model>
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
+path(argv[0])/
+\newline
-\end_inset
+\emph on
+$BIN2DATADIR/
+\emph default
-
-\begin_inset Quotes sld
-\end_inset
+\newline
-have you ever heard of an open source compiler that compiles a subset of
- C for an FPGA?
-\begin_inset Quotes srd
+\emph on
+$LIB_DIR_SUFFIX/<model>
\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- we expect you to have a quick look there and come back.
- If you read this you are on the right track.
-\layout Itemize
+\layout Standard
-Some sections attribute more space to problems, restrictions and warnings
- than to the solution.
-\layout Itemize
+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 ~
-The installation section and the section about the debugger is intimidating.
-\layout Itemize
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-There are still lots of typos and there are more different writing styles
- than pictures.
-\layout Section
+\layout Standard
-Testing the SDCC Compiler
-\begin_inset LatexCommand \label{sec:Testing-the-SDCC}
+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 ~
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\emph on
+$DATADIR/
+\newline
+$LIB_DIR_SUFFIX/<model>
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+
+/usr/local/share/sdcc/
+\newline
+lib/
+\emph on
+<model>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-The first thing you should do after installing your SDCC compiler is to
- see if it runs.
- Type
-\family sans
-\series bold
-"sdcc -
+(not on Win32)
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Comment
+
+Don't delete any of the stray spaces in the table above without checking
+ the HTML output (last line)!
+\layout Standard
+
+\SpecialChar ~
+
+\newline
+The option -
\begin_inset ERT
status Collapsed
/
\end_inset
--version"
-\begin_inset LatexCommand \index{version}
+-nostdlib disables the last two search paths.
+\layout Section
+
+Building SDCC
+\begin_inset LatexCommand \index{Building SDCC}
\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 (
-\series medium
-see
-\series default
-section
-\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
+\layout Subsection
+
+Building SDCC on Linux
+\begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
\end_inset
-\SpecialChar ~
-\series medium
-Install trouble-shooting for suggestions
-\series default
-).
- Make sure that the sdcc program is in the bin folder, if not perhaps something
- did not install correctly.
-\newline
+\layout Enumerate
-\newline
\series medium
-SDCC
+Download the source package
\series default
-is commonly installed as described in section
-\begin_inset Quotes sld
-\end_inset
+ 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}
-Install and search paths
-\begin_inset Quotes srd
\end_inset
.
-\newline
+\layout Enumerate
-\newline
\series medium
-Make sure the compiler works on a very simple example.
- Type in the following test.c program using your favorite
-\series default
-ASCII
-\series medium
-editor:
-\layout Verse
-
-
-\family typewriter
-char test;
-\newline
-
-\newline
-void main(void) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-test=0;
-\newline
-}
-\layout Standard
+Bring up a command line terminal, such as xterm.
+\layout Enumerate
\series medium
-Compile this using the following command:
+Unpack the file using a command like:
\family sans
\series bold
-"sdcc -c test.c".
-
+"tar -xvzf sdcc.src.tar.gz
\family default
\series default
-
+"
\series medium
-If all goes well, the compiler will generate a test.asm and test.rel file.
- Congratulations, you've just compiled your first program with SDCC.
- We used the -c option to tell SDCC not to link the generated code, just
- to keep things simple for this step.
-\series default
-
-\newline
-
-\newline
+, this will create a sub-directory called sdcc with all of the sources.
+\layout Enumerate
-\series medium
-The next step is to try it with the linker.
- Type in
+Change directory into the main SDCC directory, for example type:
\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
-\series default
-SDCC
-\series medium
- cannot find the
-\series default
-/
-\series medium
-usr/local/share/sdcc/lib directory
-\series default
-
-\series medium
-(see
+"cd sdcc
\series default
-section
-\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
-
-\end_inset
+".
+\layout Enumerate
-\SpecialChar ~
\series medium
-Install trouble-shooting for suggestions).
+Type
+\family sans
+\series bold
+"./configure
+\family default
\series default
+".
+ This configures the package for compilation on your system.
+\layout Enumerate
-\newline
-
-\newline
\series medium
-The final test is to ensure
-\series default
-SDCC
-\series medium
- can use the
+Type
+\family sans
+\series bold
+"make
+\family default
\series default
-standard
+"
\series medium
- header files and libraries.
- Edit test.c and change it to the following:
-\layout Verse
-
-
-\family typewriter
-#include <string.h>
-\newline
-
-\newline
-char str1[10];
-\newline
+.
-\newline
-void main(void) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-strcpy(str1, "testing");
-\newline
-}
-\layout Standard
+\series default
+ All of the source packages will compile, this can take a while.
+\layout Enumerate
\series medium
-Compile this by typing
+Type
\family sans
\series bold
-"sdcc test.c"
+"make install"
\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
-
-\series medium
-(see the
-\series default
-section
-\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
-
-\end_inset
-
-\SpecialChar ~
-
+ as root
\series medium
-Install trouble-shooting section for suggestions).
-
-\series default
- Use option
-\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
+.
--print-search-dirs
\series default
-
-\begin_inset LatexCommand \index{-\/-print-search-dirs}
-
-\end_inset
-
- to find exactly where SDCC is looking for the include and lib files.
-\layout Section
-
-Install Trouble-shooting
-\begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{Install trouble-shooting}
+ 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}
\end_inset
-
+.
\layout Subsection
-If SDCC does not build correctly
+Building SDCC on OSX 2.x
\layout Standard
-A thing to try is starting from scratch by unpacking the .tgz source package
- again in an empty directory.
- Configure it like:
+Follow the instruction for Linux.
\newline
\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
-\family sans
-\series bold
-./configure 2>&1 | tee configure.log
-\family default
-\series default
-
-\newline
+./configure CC=gcc2 CXX=g++2
+\layout Subsection
-\newline
-and build it like:
-\newline
+Cross compiling SDCC on Linux for Windows
+\layout Standard
-\newline
+With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
+ See section 'Configure Options'.
+\layout Subsection
-\family sans
-\series bold
-make 2>&1 | tee make.log
-\family default
-\series default
+Building SDCC using Cygwin and Mingw32
+\layout Standard
+For building and installing a Cygwin executable follow the instructions
+ for Linux.
\newline
\newline
-If anything goes wrong, you can review the log files to locate the problem.
- Or a relevant part of this can be attached to an email that could be helpful
- when requesting help from the mailing list.
-\layout Subsection
-
-What the
+On Cygwin a
\begin_inset Quotes sld
\end_inset
-./configure
+native
\begin_inset Quotes srd
\end_inset
- does
-\layout Standard
+ 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
-The
+\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
+
+.
+ Run it, set the
\begin_inset Quotes sld
\end_inset
-./configure
+default text file type
\begin_inset Quotes srd
\end_inset
- command is a script that analyzes your system and performs some configuration
- to ensure the source package compiles on your system.
- It will take a few minutes to run, and will compile a few tests to determine
- what compiler features are installed.
-\layout Subsection
-
-What the
+ to
\begin_inset Quotes sld
\end_inset
-make
+unix
\begin_inset Quotes srd
\end_inset
- does
-\layout Standard
+ 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
-This runs the GNU make tool, which automatically compiles all the source
- packages into the final installed binary executables.
-\layout Subsection
+flex
+\layout Itemize
-What the
-\begin_inset Quotes sld
-\end_inset
+bison
+\layout Itemize
-make install
-\begin_inset Quotes erd
-\end_inset
-
- command does.
-\layout Standard
-
-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
-
-,\SpecialChar ~
-
-\begin_inset LatexCommand \ref{sub:Search-Paths}
-
-\end_inset
-
-\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
-
-SDCC is not just a compiler, but a collection of tools by various developers.
- These include linkers, assemblers, simulators and other components.
- Here is a summary of some of the components.
- Note that the included simulator and assembler have separate documentation
- which you can find in the source package in their respective directories.
- As SDCC grows to include support for other processors, other packages from
- various developers are included and may have their own sets of documentation.
-\newline
-
-\newline
-You might want to look at the files which are installed in <installdir>.
- At the time of this writing, we find the following programs for gcc-builds:
-\newline
-
-\newline
-In <installdir>/bin:
+gcc ; version 3.x is fine, no need to use the old 2.9x
\layout Itemize
-sdcc - The compiler.
+binutils ; selected with gcc
\layout Itemize
-sdcpp - The C preprocessor.
+make
\layout Itemize
-asx8051 - The assembler for 8051 type processors.
+rxvt ; a nice console, which makes life much easier under windoze (see below)
\layout Itemize
-as-z80
-\series bold
-,
-\series default
-as-gbz80 - The Z80 and GameBoy Z80 assemblers.
+man ; not really needed for building SDCC, but you'll miss it sooner or
+ later
\layout Itemize
-aslink -The linker for 8051 type processors.
+less ; not really needed for building SDCC, but you'll miss it sooner or
+ later
\layout Itemize
-link-z80
-\series bold
-,
-\series default
-link-gbz80 - The Z80 and GameBoy Z80 linkers.
-\layout Itemize
+svn ; only if you use Subversion access
+\layout Standard
-s51 - The ucSim 8051 simulator.
- Not available on Win32 platforms.
+If you want to develop something you'll need:
\layout Itemize
-sdcdb - The source debugger.
- Not available on Win32 platforms.
+python ; for the regression tests
\layout Itemize
-packihx - A tool to pack (compress) Intel hex files.
-\layout Standard
+gdb ; the gnu debugger, together with the nice GUI
+\begin_inset Quotes sld
+\end_inset
-In <installdir>/share/sdcc/include
-\layout Itemize
+insight
+\begin_inset Quotes srd
+\end_inset
-the include files
-\layout Standard
-In <installdir>/share/sdcc/lib
\layout Itemize
-the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
- relocatables.
-\layout Standard
-
-In <installdir>/share/sdcc/doc
+openssh ; to access the CF or commit changes
\layout Itemize
-the documentation
+autoconf and autoconf-devel ; if you want to fight with 'configure', don't
+ use autoconf-stable!
\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
+rxvt is a nice console with history.
+ Replace in your cygwin.bat the line
+\layout LyX-Code
-This is the actual compiler, it in turn uses the c-preprocessor and invokes
- the assembler and linkage editor.
-\layout Subsection
+bash -
+\begin_inset ERT
+status Collapsed
-sdcpp - The C-Preprocessor
\layout Standard
-The preprocessor
-\begin_inset LatexCommand \index{sdcpp (preprocessor)}
-
+\backslash
+/
\end_inset
- 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
-
-as
-\emph on
-xxxx
-\emph default
-, aslink, link-
-\emph on
-xxx
-\emph default
- - The Assemblers and Linkage Editors
+-login -i
\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 SDCC.
-\layout Subsection
-
-s51 - The Simulator
-\layout Standard
+with (one line):
+\layout LyX-Code
-S51
-\begin_inset LatexCommand \index{s51}
+rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
+\layout LyX-Code
-\end_inset
+ -bg black -fg white -geometry 100x65 -e bash -
+\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}
+\layout Standard
+\backslash
+/
\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
+-login
\layout Standard
-Sdcdb
-\begin_inset LatexCommand \index{sdcdb (debugger)}
+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
- is the companion source level debugger.
- More about sdcdb in section
-\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
-
+cygdrive
+\begin_inset Quotes srd
\end_inset
-.
- The current version of the debugger uses Daniel's Simulator S51
-\begin_inset LatexCommand \index{s51}
+ is too long, you can change it with e.g.
+\layout LyX-Code
-\end_inset
+mount -s -u -c /mnt
+\layout Standard
-, but can be easily changed to use other simulators.
- Sdcdb is currently not available on Win32 platfors.
-\layout Chapter
+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)}
-Using SDCC
-\layout Section
+\end_inset
-Compiling
+ 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
-Single Source File Projects
+Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
\layout Standard
-For single source file 8051 projects the process is very simple.
- Compile your programs with the following command
-\family sans
-\series bold
-"sdcc sourcefile.c".
-\family default
+\series medium
+Download the source package
\series default
- This will compile, assemble and link your source file.
- Output files are as follows:
-\layout Itemize
-
-sourcefile.asm
-\begin_inset LatexCommand \index{<file>.asm}
+ either from the SDCC Subversion repository or from the
+\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
\end_inset
- - Assembler source
-\begin_inset LatexCommand \index{Assembler source}
-
-\end_inset
- file created by the compiler
-\layout Itemize
+\series medium
+, it will be named something like sdcc
+\series default
+.src
+\series medium
+.tgz.
-sourcefile.lst
-\begin_inset LatexCommand \index{<file>.lst}
+\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 and ucSim).
+ 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
- - Assembler listing
-\begin_inset LatexCommand \index{Assembler listing}
-
-\end_inset
-
- file created by the Assembler
-\layout Itemize
-
-sourcefile.rst
-\begin_inset LatexCommand \index{<file>.rst}
-
+ 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
- - Assembler listing
-\begin_inset LatexCommand \index{Assembler listing}
-
+unix2dos
+\begin_inset Quotes srd
\end_inset
- file updated with linkedit information, created by linkage editor
-\layout Itemize
-
-sourcefile.sym
-\begin_inset LatexCommand \index{<file>.sym}
+ utility freely available on the internet.
+ Doug Hawkins reported in the sdcc-user list that this works:
+\newline
-\end_inset
+\newline
+C:
+\backslash
+Programming
+\backslash
+SDCC> unix2dos sdcc.dsw
+\newline
+C:
+\backslash
+Programming
+\backslash
+SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
+\newline
- - symbol listing
-\begin_inset LatexCommand \index{Symbol listing}
+\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
- for the sourcefile, created by the assembler
-\layout Itemize
-
-sourcefile.rel
-\begin_inset LatexCommand \index{<file>.rel}
-\end_inset
+\newline
- or sourcefile.o
-\begin_inset LatexCommand \index{<file>.o}
+\newline
+Download the file UnxUtils
+\begin_inset LatexCommand \index{UnxUtils}
\end_inset
- - Object file
-\begin_inset LatexCommand \index{Object file}
-
-\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
- created by the assembler, input to Linkage editor
-\layout Itemize
+The easy way:
+\newline
-sourcefile.map
-\begin_inset LatexCommand \index{<file>.map}
+\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
-\end_inset
+\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
- - The memory map
-\begin_inset LatexCommand \index{Memory map}
+\newline
+(As a side effect, you get a bunch of Unix utilities that could be useful,
+ such as diff and patch.)
+\layout Enumerate
-\end_inset
+A more compact way:
+\newline
- for the load module, created by the Linker
-\layout Itemize
+\newline
+This one avoids extracting a bunch of files you may not use, but requires
+ some extra work:
+\newline
-sourcefile.mem
-\begin_inset LatexCommand \index{<file>.mem}
+\newline
+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
- - A file with a summary of the memory usage
-\layout Itemize
+\newline
+c) Rename bison.exe to '_bison.exe'.
+\newline
-sourcefile.ihx
-\begin_inset LatexCommand \index{<file>.ihx}
+\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
-\end_inset
+\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
- - The load module in Intel hex format
-\begin_inset LatexCommand \index{Intel hex format}
+\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
-\end_inset
+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
- (you can select the Motorola S19 format
-\begin_inset LatexCommand \index{Motorola S19 format}
+Building SDCC Using Borland
+\layout Enumerate
-\end_inset
+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 and ucSim.
+\layout Enumerate
- with -
-\begin_inset ERT
-status Collapsed
+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
-\layout Standard
+\newline
+\family sans
+\series bold
+find .
+
\backslash
-/
-\end_inset
+( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
+\backslash
+) -print -exec rm {}
+\backslash
+;
+\family default
+\series default
--out-fmt-s19
-\begin_inset LatexCommand \index{-\/-out-fmt-s19}
+\newline
-\end_inset
+\newline
+or on Windows NT/2000/XP from the command prompt with the command:
+\newline
-.
- If you need another format you might want to use
\family sans
-\shape italic
-objdump
+\series bold
+
+\newline
+del /s *.obj *.lib *.rul
\family default
-\shape default
+\series default
+ from the sdcc directory.
+\layout Subsection
-\begin_inset LatexCommand \index{objdump (tool)}
+Windows Install Using a ZIP Package
+\layout Enumerate
+
+Download the binary zip package from
+\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
\end_inset
- or
-\family sans
-\shape italic
- srecord
-\family default
-\shape default
-
-\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
+ 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
-\end_inset
+Adjust your environment variable PATH to include the location of the bin
+ directory or start sdcc using the full path.
+\layout Subsection
-).
- Both formats are documented in the documentation of srecord
-\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
+Windows Install Using the Setup Program
+\begin_inset LatexCommand \label{sub:Windows-Install}
\end_inset
-\layout Itemize
-
-sourcefile.adb
-\begin_inset LatexCommand \index{<file>.adb}
-
-\end_inset
+\layout Standard
- - An intermediate file containing debug information needed to create the
- .cdb file (with -
-\begin_inset ERT
-status Open
+Download the setup program
+\emph on
+sdcc-x.y.z-setup.exe
+\emph default
+ for an official release from
+\newline
-\layout Standard
+\begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
-\backslash
-/
\end_inset
--debug
-\begin_inset LatexCommand \index{-\/-debug}
+ or a setup program for one of the snapshots
+\emph on
+sdcc-yyyymmdd-xxxx-setup.exe
+\emph default
+ from
+\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
\end_inset
-)
-\layout Itemize
+ and execute it.
+ A windows typical installer will guide you through the installation process.
+\layout Subsection
-sourcefile.cdb
-\begin_inset LatexCommand \index{<file>.cdb}
+VPATH
+\begin_inset LatexCommand \index{VPATH}
\end_inset
- - An optional file (with -
-\begin_inset ERT
-status Collapsed
+ feature
+\layout Standard
+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
-\backslash
-/
-\end_inset
--debug) containing debug information.
- The format is documented in cdbfileformat.pdf
-\layout Itemize
+\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
-sourcefile.
- - (no extension)
-\begin_inset LatexCommand \index{<file> (no extension)}
-\end_inset
+\family typewriter
+tar -xzf sdcc.src.tar.gz\SpecialChar ~
+# extract source to directory sdcc
+\layout Standard
- An optional AOMF or AOMF51
-\begin_inset LatexCommand \index{AOMF, AOMF51}
-\end_inset
+\family typewriter
+mkdir sdcc.build\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+# put output in sdcc.build
+\layout Standard
- file containing debug information (generated with option -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+cd sdcc.build
\layout Standard
-\backslash
-/
-\end_inset
-
--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
+\family typewriter
+../sdcc/configure\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+# configure is doing all the magic!
+\layout Standard
-, simulators, emulators)
-\layout Itemize
-sourcefile.dump*
-\begin_inset LatexCommand \index{<file>.dump*}
+\family typewriter
+make
+\layout Standard
+\noindent
+That's it!
+\series bold
+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
- - Dump file to debug the compiler it self (generated with option -
+Add -
\begin_inset ERT
status Collapsed
/
\end_inset
--dumpall) (see section
-\begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
+-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
+\begin_inset Quotes srd
\end_inset
-\SpecialChar ~
- and section
-\begin_inset LatexCommand \ref{sub:The-anatomy-of}
+make
+\begin_inset Quotes srd
+\end_inset
+
+
+\family default
+\series default
+ 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
-\SpecialChar ~
+ as editor is straightforward.
+ Prebuilt documentation in html and pdf format is available from
+\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
-\begin_inset Quotes sld
\end_inset
-Anatomy of the compiler
-\begin_inset Quotes srd
+.
+\layout Section
+
+Reading the Documentation
+\begin_inset LatexCommand \index{Documentation}
+
\end_inset
-).
-\layout Subsection
-Projects with Multiple Source Files
\layout Standard
-SDCC can compile only ONE file at a time.
- Let us for example assume that you have a project containing the following
- files:
-\newline
-
-\newline
-foo1.c (contains some functions)
-\newline
-foo2.c (contains some more functions)
-\newline
-foomain.c (contains more functions and the function main)
-\newline
+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
-\size footnotesize
+\layout Standard
-\newline
+If you should know why please drop us a note
+\end_inset
-\size default
-The first two files will need to be compiled separately with the commands:
-\size footnotesize
+.
-\size default
-
\newline
+You'll find the pdf version
+\begin_inset LatexCommand \index{PDF version of this document}
-\newline
+\end_inset
-\family sans
-\series bold
-sdcc\SpecialChar ~
--c\SpecialChar ~
-foo1.c
-\family default
-\series default
-\size footnotesize
+ at
+\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
+
+\end_inset
+.
+
\newline
+A html version
+\begin_inset LatexCommand \index{HTML version of this document}
-\family sans
-\series bold
-\size default
-sdcc\SpecialChar ~
--c\SpecialChar ~
-foo2.c
-\family default
-\series default
-
-\newline
+\end_inset
-\newline
-Then compile the source file containing the
-\emph on
-main()
-\emph default
- function and link
-\begin_inset LatexCommand \index{Linker}
+ should be online at
+\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
\end_inset
- the files together with the following command:
+.
\newline
+This documentation is in some aspects different from a commercial documentation:
+
+\layout Itemize
-\newline
+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}
-\family sans
-\series bold
-sdcc\SpecialChar ~
-foomain.c\SpecialChar ~
-foo1.rel\SpecialChar ~
-foo2.rel
-\family default
-\series default
+\end_inset
-\begin_inset LatexCommand \index{<file>.rel}
+ 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
-\end_inset
+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
-\newline
+ together with a statement
+\begin_inset Quotes sld
+\end_inset
-\newline
-Alternatively,
+some processors which are targetted by SDCC can be implemented in a
\emph on
-foomain.c
+f
\emph default
-can be separately compiled as well:
-\family sans
-\series bold
-
-\newline
-
-\newline
-sdcc\SpecialChar ~
--c\SpecialChar ~
-foomain.c
-\newline
-sdcc foomain.rel foo1.rel foo2.rel
-\newline
-
-\newline
-
-\family default
-\series default
-The file containing the
+ield
\emph on
-main()
+p
\emph default
- function
+rogrammable
\emph on
-
+g
\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}
+ate
+\emph on
+a
+\emph default
+rray
+\begin_inset LatexCommand \index{FPGA (field programmable gate array)}
\end_inset
-.
- You can view this file to troubleshoot linking problems such as those arising
- from missing libraries.
-\layout Subsection
-
-Projects with Additional Libraries
-\begin_inset LatexCommand \index{Libraries}
+\begin_inset Quotes srd
\end_inset
-
-\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}
+ or
+\begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
\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
+\begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
-\newline
+\end_inset
-\family sans
-\series bold
-sdcc foomain.c foolib.lib -L mylib
-\newline
+
+\begin_inset Quotes sld
+\end_inset
-\newline
+have you ever heard of an open source compiler that compiles a subset of
+ C for an FPGA?
+\begin_inset Quotes srd
+\end_inset
-\family default
-\series default
-Note here that
-\emph on
- mylib
-\emph default
- must be an absolute path name.
-\newline
+ we expect you to have a quick look there and come back.
+ If you read this you are on the right track.
+\layout Itemize
-\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}
+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
- files.
- For an example see the standard library file
-\emph on
-libsdcc.lib
-\emph default
- in the directory <installdir>/share/lib/small.
-\layout Subsection
+There are still lots of typos and there are more different writing styles
+ than pictures.
+\layout Section
-Using sdcclib to Create and Manage Libraries
-\begin_inset LatexCommand \index{sdcclib}
+Testing the SDCC Compiler
+\begin_inset LatexCommand \label{sec:Testing-the-SDCC}
\end_inset
\layout Standard
-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
-
-
+The first thing you should do after installing your SDCC compiler is to
+ see if it runs.
+ Type
\family sans
\series bold
-sdcclib -?
-\begin_inset LatexCommand \index{sdcclib}
+"sdcc -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-version"
+\begin_inset LatexCommand \index{version}
-\newline
+\end_inset
-\newline
\family default
\series default
-To create a new library file, start by compiling all the required modules.
- For example:
+ 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
+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}
-\family sans
-\series bold
-sdcc -c _divsint.c
-\layout Standard
+\end_inset
+\SpecialChar ~
-\family sans
-\series bold
-sdcc -c _divuint.c
-\layout Standard
+\series medium
+Install trouble-shooting for suggestions
+\series default
+).
+ Make sure that the sdcc program is in the bin folder, if not perhaps something
+ did not install correctly.
+\newline
+\newline
-\family sans
-\series bold
-sdcc -c _modsint.c
-\layout Standard
-
+\series medium
+SDCC
+\series default
+is commonly installed as described in section
+\begin_inset Quotes sld
+\end_inset
-\family sans
-\series bold
-sdcc -c _moduint.c
-\layout Standard
+Install and search paths
+\begin_inset Quotes srd
+\end_inset
+.
+\newline
-\family sans
-\series bold
-sdcc -c _mulint.c
\newline
-\layout Standard
+\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
-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:
+
+\family typewriter
+char test;
\newline
+\newline
+void main(void) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+test=0;
+\newline
+}
\layout Standard
+\series medium
+Compile this using the following command:
\family sans
\series bold
-sdcclib libint.lib _divsint.rel
-\family default
-
-\begin_inset LatexCommand \index{sdcclib}
-
-\end_inset
+"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
+\newline
+\series medium
+The next step is to try it with the linker.
+ Type in
\family sans
\series bold
-sdcclib libint.lib _divuint.rel
-\layout Standard
+"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
-\family sans
-\series bold
-sdcclib libint.lib _modsint.rel
-\layout Standard
+\SpecialChar ~
+\series medium
+Install trouble-shooting for suggestions).
+\series default
-\family sans
-\series bold
-sdcclib libint.lib _moduint.rel
-\layout Standard
+\newline
+\newline
-\family sans
-\series bold
-sdcclib libint.lib _mulint.rel
+\series medium
+The final test is to ensure
+\series default
+SDCC
+\series medium
+ can use the
\series default
+standard
+\series medium
+ header files and libraries.
+ Edit test.c and change it to the following:
+\layout Verse
-\newline
-\layout Standard
+\family typewriter
+#include <string.h>
+\newline
-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
+char str1[10];
\newline
\newline
+void main(void) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+strcpy(str1, "testing");
+\newline
+}
+\layout Standard
+
+\series medium
+Compile this by typing
\family sans
\series bold
-sdcclib -s libint.lib
+"sdcc test.c"
\family default
-
-\begin_inset LatexCommand \index{sdcclib}
+\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
+
+\series medium
+(see the
+\series default
+section
+\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
\end_inset
+\SpecialChar ~
-\newline
+\series medium
+Install trouble-shooting section for suggestions).
-\family typewriter
\series default
-_divsint.rel:
-\layout Standard
-
+ Use option
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\family typewriter
-__divsint_a_1_1
\layout Standard
+\backslash
+/
+\end_inset
-\family typewriter
-__divsint_PARM_2
-\layout Standard
+-print-search-dirs
+\series default
+\begin_inset LatexCommand \index{-\/-print-search-dirs}
-\family typewriter
-__divsint
-\newline
-_divuint.rel:
-\layout Standard
+\end_inset
+ to find exactly where SDCC is looking for the include and lib files.
+\layout Section
-\family typewriter
-__divuint_a_1_1
-\layout Standard
+Install Trouble-shooting
+\begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
+
+\end_inset
-\family typewriter
-__divuint_PARM_2
-\layout Standard
+\begin_inset LatexCommand \index{Install trouble-shooting}
+\end_inset
-\family typewriter
-__divuint_reste_1_1
-\layout Standard
+\layout Subsection
-\family typewriter
-__divuint_count_1_1
+If 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
-\family typewriter
-__divuint
\newline
-_modsint.rel:
-\layout Standard
+\family sans
+\series bold
+./configure 2>&1 | tee configure.log
+\family default
+\series default
-\family typewriter
-__modsint_a_1_1
-\layout Standard
+\newline
+\newline
+and build it like:
+\newline
-\family typewriter
-__modsint_PARM_2
-\layout Standard
+\newline
+\family sans
+\series bold
+make 2>&1 | tee make.log
+\family default
+\series default
-\family typewriter
-__modsint
\newline
-_moduint.rel:
-\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
+
+What the
+\begin_inset Quotes sld
+\end_inset
-\family typewriter
-__moduint_a_1_1
-\layout Standard
-
+./configure
+\begin_inset Quotes srd
+\end_inset
-\family typewriter
-__moduint_PARM_2
+ does
\layout Standard
+The
+\begin_inset Quotes sld
+\end_inset
-\family typewriter
-__moduint_count_1_1
-\layout Standard
+./configure
+\begin_inset Quotes srd
+\end_inset
+ command is a script that analyzes your system and performs some configuration
+ to ensure the source package compiles on your system.
+ It will take a few minutes to run, and will compile a few tests to determine
+ what compiler features are installed.
+\layout Subsection
-\family typewriter
-__moduint
-\newline
-_mulint.rel:
-\layout Standard
+What the
+\begin_inset Quotes sld
+\end_inset
+make
+\begin_inset Quotes srd
+\end_inset
-\family typewriter
-__mulint_PARM_2
+ does
\layout Standard
+This runs the GNU make tool, which automatically compiles all the source
+ packages into the final installed binary executables.
+\layout Subsection
-\family typewriter
-__mulint
-\family default
-\series bold
+What the
+\begin_inset Quotes sld
+\end_inset
-\newline
+make install
+\begin_inset Quotes erd
+\end_inset
+ command does.
\layout Standard
-If the source files are compiled using -
-\begin_inset ERT
-status Open
-
-\layout Standard
+This will install the compiler, other executables libraries and include
+ files into the appropriate directories.
+ See sections
+\begin_inset LatexCommand \ref{sub:Install-paths}
-\backslash
-/
\end_inset
--debug
-\begin_inset LatexCommand \index{-\/-debug}
+,\SpecialChar ~
+
+\begin_inset LatexCommand \ref{sub:Search-Paths}
\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.
+\SpecialChar ~
+about install and search paths.
+\newline
+On most systems you will need super-user privileges to do this.
\layout Section
-Command Line Options
-\begin_inset LatexCommand \index{Command Line Options}
+Components of SDCC
+\layout Standard
-\end_inset
+SDCC is not just a compiler, but a collection of tools by various developers.
+ These include linkers, assemblers, simulators and other components.
+ Here is a summary of some of the components.
+ Note that the included simulator and assembler have separate documentation
+ which you can find in the source package in their respective directories.
+ As SDCC grows to include support for other processors, other packages from
+ various developers are included and may have their own sets of documentation.
+\newline
+\newline
+You might want to look at the files which are installed in <installdir>.
+ At the time of this writing, we find the following programs for gcc-builds:
+\newline
+
+\newline
+In <installdir>/bin:
+\layout Itemize
-\layout Subsection
+sdcc - The compiler.
+\layout Itemize
-Processor Selection Options
-\begin_inset LatexCommand \index{Options processor selection}
+sdcpp - The C preprocessor.
+\layout Itemize
-\end_inset
+asx8051 - The assembler for 8051 type processors.
+\layout Itemize
+as-z80
+\series bold
+,
+\series default
+as-gbz80 - The Z80 and GameBoy Z80 assemblers.
+\layout Itemize
-\begin_inset LatexCommand \index{Processor selection options}
+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
+s51 - The ucSim 8051 simulator.
+\layout Itemize
-\layout List
-\labelwidthstring 00.00.0000
+sdcdb - The source debugger.
+\layout Itemize
+packihx - A tool to pack (compress) Intel hex files.
+\layout Standard
-\series bold
--mmcs51
-\begin_inset LatexCommand \index{-mmcs51}
+In <installdir>/share/sdcc/include
+\layout Itemize
-\end_inset
+the include files
+\layout Standard
+In <installdir>/share/sdcc/lib
+\layout Itemize
-\series default
- Generate code for the Intel MCS51
-\begin_inset LatexCommand \index{MCS51}
+the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
+ relocatables.
+\layout Standard
-\end_inset
+In <installdir>/share/sdcc/doc
+\layout Itemize
- family of processors.
- This is the default processor target.
-\layout List
-\labelwidthstring 00.00.0000
+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
-\series bold
--mds390
-\begin_inset LatexCommand \index{-mds390}
+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 Subsection
+sdcpp - The C-Preprocessor
+\layout Standard
-\series default
- Generate code for the Dallas DS80C390
-\begin_inset LatexCommand \index{DS80C390}
+The preprocessor
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
\end_inset
- processor.
-\layout List
-\labelwidthstring 00.00.0000
+ 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
+as
+\emph on
+xxxx
+\emph default
+, aslink, link-
+\emph on
+xxx
+\emph default
+ - The Assemblers and Linkage Editors
+\layout Standard
-\series bold
--mds400
-\begin_inset LatexCommand \index{-mds400}
+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
-\end_inset
+s51 - The Simulator
+\layout Standard
+S51
+\begin_inset LatexCommand \index{s51}
-\series default
- Generate code for the Dallas DS80C400
-\begin_inset LatexCommand \index{DS80C400}
+\end_inset
+
+ 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
- processor.
-\layout List
-\labelwidthstring 00.00.0000
+.
+ It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
+ XA51 family.
+\layout Subsection
+sdcdb - Source Level Debugger
+\layout Standard
-\series bold
--mhc08
-\begin_inset LatexCommand \index{-mhc08}
+SDCDB
+\begin_inset LatexCommand \index{SDCDB (debugger)}
\end_inset
-
-\series default
- Generate code for the Freescale/Motorola HC08
-\begin_inset LatexCommand \index{HC08}
+ is the companion source level debugger.
+ More about SDCDB in section
+\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
\end_inset
- family of processors.
-\layout List
-\labelwidthstring 00.00.0000
+.
+ The current version of the debugger uses Daniel's Simulator S51
+\begin_inset LatexCommand \index{s51}
+\end_inset
-\series bold
--mz80
-\begin_inset LatexCommand \index{-mz80}
-
-\end_inset
+, but can be easily changed to use other simulators.
+\layout Chapter
+Using SDCC
+\layout Section
-\series default
- Generate code for the Zilog Z80
-\begin_inset LatexCommand \index{Z80}
+Compiling
+\layout Subsection
-\end_inset
+Single Source File Projects
+\layout Standard
- family of processors.
-\layout List
-\labelwidthstring 00.00.0000
+For single source file 8051 projects the process is very simple.
+ Compile your programs with the following command
+\family sans
+\series bold
+"sdcc sourcefile.c".
+\family default
+\series default
+ This will compile, assemble and link your source file.
+ Output files are as follows:
+\layout Itemize
-\series bold
--mgbz80
-\begin_inset LatexCommand \index{-mgbz80}
+sourcefile.asm
+\begin_inset LatexCommand \index{<file>.asm}
\end_inset
-
-\series default
- Generate code for the GameBoy Z80
-\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
+ - Assembler source
+\begin_inset LatexCommand \index{Assembler source}
\end_inset
- processor (Not actively maintained).
-\layout List
-\labelwidthstring 00.00.0000
-
+ file created by the compiler
+\layout Itemize
-\series bold
--mavr
-\begin_inset LatexCommand \index{-mavr}
+sourcefile.lst
+\begin_inset LatexCommand \index{<file>.lst}
\end_inset
-
-\series default
- Generate code for the Atmel AVR
-\begin_inset LatexCommand \index{AVR}
+ - Assembler listing
+\begin_inset LatexCommand \index{Assembler listing}
\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}
+ file created by the Assembler
+\layout Itemize
+
+sourcefile.rst
+\begin_inset LatexCommand \index{<file>.rst}
\end_inset
- or
-\begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
+ - Assembler listing
+\begin_inset LatexCommand \index{Assembler listing}
\end_inset
-.
-\layout Comment
+ file updated with linkedit information, created by linkage editor
+\layout Itemize
-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
+sourcefile.sym
+\begin_inset LatexCommand \index{<file>.sym}
+\end_inset
-\series bold
--mpic14
-\begin_inset LatexCommand \index{-mpic14}
+ - symbol listing
+\begin_inset LatexCommand \index{Symbol listing}
\end_inset
+ for the sourcefile, created by the assembler
+\layout Itemize
-\series default
- Generate code for the Microchip PIC 14
-\begin_inset LatexCommand \index{PIC14}
+sourcefile.rel
+\begin_inset LatexCommand \index{<file>.rel}
\end_inset
--bit processors (p16f84 and variants.
- In development, not complete).
-\layout Comment
-
-p16f627 p16f628 p16f84 p16f873 p16f877?
-\layout List
-\labelwidthstring 00.00.0000
+ or sourcefile.o
+\begin_inset LatexCommand \index{<file>.o}
+\end_inset
-\series bold
--mpic16
-\begin_inset LatexCommand \index{-mpic16}
+ - Object file
+\begin_inset LatexCommand \index{Object file}
\end_inset
+ created by the assembler, input to Linkage editor
+\layout Itemize
-\series default
- Generate code for the Microchip PIC 16
-\begin_inset LatexCommand \index{PIC16}
+sourcefile.map
+\begin_inset LatexCommand \index{<file>.map}
\end_inset
--bit processors (p18f452 and variants.
- In development, not complete).
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--mtlcs900h
-\series default
- Generate code for the Toshiba TLCS-900H
-\begin_inset LatexCommand \index{TLCS-900H}
+ - The memory map
+\begin_inset LatexCommand \index{Memory map}
\end_inset
- processor (Not maintained, not complete).
-\layout List
-\labelwidthstring 00.00.0000
-
+ for the load module, created by the Linker
+\layout Itemize
-\series bold
--mxa51
-\begin_inset LatexCommand \index{-mxa51}
+sourcefile.mem
+\begin_inset LatexCommand \index{<file>.mem}
\end_inset
+ - A file with a summary of the memory usage
+\layout Itemize
-\series default
- Generate code for the Phillips XA51
-\begin_inset LatexCommand \index{XA51}
+sourcefile.ihx
+\begin_inset LatexCommand \index{<file>.ihx}
\end_inset
- processor (Not maintained, not complete).
-\layout Subsection
-
-Preprocessor Options
-\begin_inset LatexCommand \index{Options preprocessor}
+ - The load module in Intel hex format
+\begin_inset LatexCommand \index{Intel hex format}
\end_inset
-
-\begin_inset LatexCommand \index{Preprocessor options}
+ (you can select the Motorola S19 format
+\begin_inset LatexCommand \index{Motorola S19 format}
\end_inset
+ with -
+\begin_inset ERT
+status Collapsed
-\begin_inset LatexCommand \index{sdcpp (preprocessor)}
+\layout Standard
+\backslash
+/
\end_inset
+-out-fmt-s19
+\begin_inset LatexCommand \index{-\/-out-fmt-s19}
-\layout List
-\labelwidthstring 00.00.0000
+\end_inset
+.
+ If you need another format you might want to use
+\family sans
+\shape italic
+objdump
+\family default
+\shape default
-\series bold
--I<path>
-\begin_inset LatexCommand \index{-I<path>}
+\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)}
-\series default
- The additional location where the pre processor will look for <..h> or
-\begin_inset Quotes eld
\end_inset
-..h
-\begin_inset Quotes erd
+).
+ Both formats are documented in the documentation of srecord
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
+
\end_inset
- files.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Itemize
-\series bold
--D<macro[=value]>
-\begin_inset LatexCommand \index{-D<macro[=value]>}
+sourcefile.adb
+\begin_inset LatexCommand \index{<file>.adb}
\end_inset
+ - An intermediate file containing debug information needed to create the
+ .cdb file (with -
+\begin_inset ERT
+status Collapsed
-\series default
- Command line definition of macros.
- Passed to the preprocessor.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+\backslash
+/
+\end_inset
-\series bold
--M
-\begin_inset LatexCommand \index{-M}
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
\end_inset
+)
+\layout Itemize
-\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
-\begin_inset LatexCommand \index{-E}
+sourcefile.cdb
+\begin_inset LatexCommand \index{<file>.cdb}
\end_inset
-'.
-\layout List
-\labelwidthstring 00.00.0000
-
+ - An optional file (with -
+\begin_inset ERT
+status Collapsed
-\series bold
--C
-\begin_inset LatexCommand \index{-C}
+\layout Standard
+\backslash
+/
\end_inset
+-debug) containing debug information.
+ The format is documented in cdbfileformat.pdf
+\layout Itemize
-\series default
- Tell the preprocessor not to discard comments.
- Used with the `-E' option.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--MM
-\begin_inset LatexCommand \index{-MM}
+sourcefile.
+ - (no extension)
+\begin_inset LatexCommand \index{<file> (no extension)}
\end_inset
+ An optional AOMF or AOMF51
+\begin_inset LatexCommand \index{AOMF, AOMF51}
-\size large
-\bar under
-
-\series default
-\size default
-\bar default
-Like `-M' but the output mentions only the user header files included with
- `#include
-\begin_inset Quotes eld
\end_inset
-file"'.
- System header files included with `#include <file>' are omitted.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--Aquestion(answer)
-\begin_inset LatexCommand \index{-Aquestion(answer)}
+
+\begin_inset LatexCommand \label{OMF file}
\end_inset
+file containing debug information (generated with option -
+\begin_inset ERT
+status Collapsed
-\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
--Umacro
-\begin_inset LatexCommand \index{-Umacro}
+\layout Standard
+\backslash
+/
\end_inset
+-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}
-\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
+\end_inset
+, simulators, emulators)
+\layout Itemize
-\series bold
--dM
-\begin_inset LatexCommand \index{-dM}
+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
-\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
+\layout Standard
+\backslash
+/
+\end_inset
-\series bold
--dD
-\begin_inset LatexCommand \index{-dD}
+-dumpall) (see section
+\begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
\end_inset
+\SpecialChar ~
+ and section
+\begin_inset LatexCommand \ref{sub:The-anatomy-of}
-\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
+\end_inset
+\SpecialChar ~
-\series bold
--dN
-\begin_inset LatexCommand \index{-dN}
+\begin_inset Quotes sld
+\end_inset
+Anatomy of the compiler
+\begin_inset Quotes srd
\end_inset
+).
+\layout Subsection
-\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
+Postprocessing the Intel Hex
+\begin_inset LatexCommand \index{Intel hex format}
+\end_inset
-\series bold
--Wp\SpecialChar ~
-preprocessorOption[,preprocessorOption]
-\series default
+ file
+\layout Standard
-\begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
+The Intel Hex file
+\begin_inset LatexCommand \index{<file>.ihx}
\end_inset
-...
- Pass the preprocessorOption to the preprocessor
+ which is generated by SDCC might include lines of varying length and the
+ addresses within the file are not guaranteed to be strictly ascending.
+ If your toolchain or a bootloader does not like this you can use the tool
+
\family typewriter
-sdcpp
+packihx
\family default
-\begin_inset LatexCommand \index{sdcpp (preprocessor)}
+\begin_inset LatexCommand \index{packihx (tool)}
\end_inset
-.
- 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
+ which is part of the SDCC distribution:
+\newline
-.
-\layout Subsection
+\newline
-Linker Options
-\begin_inset LatexCommand \index{Options linker}
+\family sans
+\series bold
+ packihx sourcefile.ihx >sourcefile.hex
+\family default
+\series default
-\end_inset
+\newline
+\newline
+The separately available
+\emph on
+ srecord
+\emph default
-\begin_inset LatexCommand \index{Linker options}
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
\end_inset
+ package additionally allows to set undefined locations to a predefined
+ value, to insert checksums of various flavours (crc, add, xor) and to perform
+ other manipulations (convert, split, crop, offset, ...).
+
+\newline
-\layout List
-\labelwidthstring 00.00.0000
-
+\newline
+\family sans
\series bold
--L\SpecialChar ~
--
-\series default
+srec_cat\SpecialChar ~
+\SpecialChar ~
+sourcefile.ihx -intel\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+-fill 0xff 0x0000 0x8000\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+-o sourcefile.hex -intel
+\newline
-\begin_inset ERT
-status Collapsed
+\newline
-\layout Standard
+\family default
+\series default
+The srecord package is available at
+\begin_inset LatexCommand \url{http://sf.net/projects/srecord}
-\backslash
-/
\end_inset
+ .
+\layout Subsection
-\series bold
--lib-path
-\begin_inset LatexCommand \index{-\/-lib-path <path>}
+Projects with Multiple Source Files
+\layout Standard
-\end_inset
+SDCC can compile only ONE file at a time.
+ Let us for example assume that you have a project containing the following
+ files:
+\newline
+\newline
+foo1.c (contains some functions)
+\newline
+foo2.c (contains some more functions)
+\newline
+foomain.c (contains more functions and the function main)
+\newline
-\begin_inset LatexCommand \index{-L -\/-lib-path}
+\size footnotesize
-\end_inset
+\newline
+\size default
+The first two files will need to be compiled separately with the commands:
+\size footnotesize
+
+\size default
-\series default
-\SpecialChar ~
-<absolute path to additional libraries> This option is passed to the linkage
- editor's additional libraries
-\begin_inset LatexCommand \index{Libraries}
+\newline
-\end_inset
+\newline
- 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
+\family sans
+\series bold
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foo1.c
+\family default
+\series default
+\size footnotesize
+\newline
+\family sans
\series bold
--
-\begin_inset ERT
-status Collapsed
+\size default
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foo2.c
+\family default
+\series default
-\layout Standard
+\newline
+
+\newline
+Then compile the source file containing the
+\emph on
+main()
+\emph default
+ function and link
+\begin_inset LatexCommand \index{Linker}
-\backslash
-/
\end_inset
--xram-loc
+ the files together with the following command:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcc\SpecialChar ~
+foomain.c\SpecialChar ~
+foo1.rel\SpecialChar ~
+foo2.rel
+\family default
\series default
-\begin_inset LatexCommand \index{-\/-xram-loc <Value>}
+\begin_inset LatexCommand \index{<file>.rel}
\end_inset
-\SpecialChar ~
-<Value> The start location of the external ram
-\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
-\end_inset
+\newline
-, default value is 0.
- The value entered can be in Hexadecimal or Decimal format, e.g.: -
-\begin_inset ERT
-status Collapsed
+\newline
+Alternatively,
+\emph on
+foomain.c
+\emph default
+can be separately compiled as well:
+\family sans
+\series bold
-\layout Standard
+\newline
-\backslash
-/
-\end_inset
+\newline
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foomain.c
+\newline
+sdcc foomain.rel foo1.rel foo2.rel
+\newline
--xram-loc 0x8000 or -
-\begin_inset ERT
-status Collapsed
+\newline
-\layout Standard
+\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}
-\backslash
-/
\end_inset
--xram-loc 32768.
-\layout List
-\labelwidthstring 00.00.0000
+.
+ You can view this file to troubleshoot linking problems such as those arising
+ from missing libraries.
+\layout Subsection
+Projects with Additional Libraries
+\begin_inset LatexCommand \index{Libraries}
+
+\end_inset
-\series bold
--
-\begin_inset ERT
-status Collapsed
\layout Standard
-\backslash
-/
+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
--code-loc
-\series default
-\begin_inset LatexCommand \index{-\/-code-loc <Value>}
+\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
-\end_inset
+\newline
-\SpecialChar ~
-<Value> The start location of the code
-\begin_inset LatexCommand \index{code}
+\family sans
+\series bold
+sdcc foomain.c foolib.lib -L mylib
+\newline
-\end_inset
+\newline
- 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
+\family default
+\series default
+Note here that
+\emph on
+ mylib
+\emph default
+ must be an absolute path name.
+\newline
-\layout Standard
+\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}
-\backslash
-/
\end_inset
--code-loc 0x8000 or -
-\begin_inset ERT
-status Collapsed
+ files.
+ For an example see the standard library file
+\emph on
+libsdcc.lib
+\emph default
+ in the directory <installdir>/share/lib/small.
+\layout Subsection
-\layout Standard
+Using sdcclib to Create and Manage Libraries
+\begin_inset LatexCommand \index{sdcclib}
-\backslash
-/
\end_inset
--code-loc 32768.
-\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
-
--stack-loc
-\series default
-\begin_inset LatexCommand \index{-\/-stack-loc <Value>}
+\family sans
+\series bold
+sdcclib -?
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\SpecialChar ~
-<Value> By default the stack
-\begin_inset LatexCommand \index{stack}
-\end_inset
+\newline
- 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
+\newline
-\layout Standard
+\family default
+\series default
+To create a new library file, start by compiling all the required modules.
+ For example:
+\newline
-\backslash
-/
-\end_inset
+\layout Standard
--stack-loc 0x20 or -
-\begin_inset ERT
-status Collapsed
+\family sans
+\series bold
+sdcc -c _divsint.c
\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
+\family sans
\series bold
--
-\begin_inset ERT
-status Collapsed
-
+sdcc -c _divuint.c
\layout Standard
-\backslash
-/
-\end_inset
--pack-iram
-\series default
-\SpecialChar ~
-
-\begin_inset LatexCommand \index{-\/-pack-iram}
+\family sans
+\series bold
+sdcc -c _modsint.c
+\layout Standard
-\end_inset
- option (which is now a default setting) will override this setting, so
- you should also specify the
+\family sans
\series bold
--
-\begin_inset ERT
-status Collapsed
-
+sdcc -c _moduint.c
\layout Standard
-\backslash
-/
-\end_inset
--no-pack-iram
-\series default
-\SpecialChar ~
+\family sans
+\series bold
+sdcc -c _mulint.c
+\newline
-\begin_inset LatexCommand \index{-\/-no-pack-iram}
+\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
- option if you need to manually place the stack.
-\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
--xstack-loc
-\series default
-\begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
+\layout Standard
-\end_inset
-\SpecialChar ~
-<Value> By default the external stack
-\begin_inset LatexCommand \index{xstack}
+\family sans
+\series bold
+sdcclib libint.lib _divuint.rel
+\layout Standard
-\end_inset
- 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
+\family sans
+\series bold
+sdcclib libint.lib _modsint.rel
+\layout Standard
+
+\family sans
+\series bold
+sdcclib libint.lib _moduint.rel
\layout Standard
-\backslash
-/
-\end_inset
--xstack-loc 0x8000 or -
-\begin_inset ERT
-status Collapsed
+\family sans
+\series bold
+sdcclib libint.lib _mulint.rel
+\series default
-\layout Standard
+\newline
-\backslash
-/
-\end_inset
+\layout Standard
--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
+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
--data-loc
-\series default
-\begin_inset LatexCommand \index{-\/-data-loc <Value>}
+\newline
-\end_inset
+\family typewriter
+\series default
+_divsint.rel:
+\layout Standard
-\SpecialChar ~
-<Value> The start location of the internal ram data
-\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
-\end_inset
+\family typewriter
+__divsint_a_1_1
+\layout Standard
- segment.
- The value entered can be in Hexadecimal or Decimal format, eg.
- -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+__divsint_PARM_2
\layout Standard
-\backslash
-/
-\end_inset
--data-loc 0x20 or -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+__divsint
+\newline
+_divuint.rel:
+\layout Standard
+
+\family typewriter
+__divuint_a_1_1
\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
+\family typewriter
+__divuint_PARM_2
+\layout Standard
+
+\family typewriter
+__divuint_reste_1_1
\layout Standard
-\backslash
-/
-\end_inset
--data-loc is not used, to location 0x10.)
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__divuint_count_1_1
+\layout Standard
-\series bold
--
-\begin_inset ERT
-status Collapsed
+\family typewriter
+__divuint
+\newline
+_modsint.rel:
+\layout Standard
+
+\family typewriter
+__modsint_a_1_1
\layout Standard
-\backslash
-/
-\end_inset
--idata-loc
-\series default
+\family typewriter
+__modsint_PARM_2
+\layout Standard
-\begin_inset LatexCommand \index{-\/-idata-loc <Value>}
-\end_inset
+\family typewriter
+__modsint
+\newline
+_moduint.rel:
+\layout Standard
-\SpecialChar ~
-<Value> The start location of the indirectly addressable internal ram
-\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
-\end_inset
+\family typewriter
+__moduint_a_1_1
+\layout Standard
- of the 8051, default value is 0x80.
- The value entered can be in Hexadecimal or Decimal format, eg.
- -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+__moduint_PARM_2
\layout Standard
-\backslash
-/
-\end_inset
--idata-loc 0x88 or -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+__moduint_count_1_1
+\layout Standard
+
+\family typewriter
+__moduint
+\newline
+_mulint.rel:
\layout Standard
-\backslash
-/
-\end_inset
--idata-loc 136.
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__mulint_PARM_2
+\layout Standard
+\family typewriter
+__mulint
+\family default
\series bold
--
+
+\newline
+
+\layout Standard
+\added_space_bottom bigskip
+If the source files are compiled using -
\begin_inset ERT
status Collapsed
/
\end_inset
--bit-loc
-\series default
-\SpecialChar ~
-<Value> The start location of the bit
-\begin_inset LatexCommand \index{bit}
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
\end_inset
- 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
+, 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
+Command Line Options
+\begin_inset LatexCommand \index{Command Line Options}
-\series bold
--
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
-\backslash
-/
-\end_inset
+\layout Subsection
--out-fmt-ihx
-\begin_inset LatexCommand \index{-\/-out-fmt-ihx}
+Processor Selection Options
+\begin_inset LatexCommand \index{Options processor selection}
\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}
+\begin_inset LatexCommand \index{Processor selection options}
\end_inset
- 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
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--out-fmt-s19
-\begin_inset LatexCommand \index{-\/-out-fmt-s19}
+-mmcs51
+\begin_inset LatexCommand \index{-mmcs51}
\end_inset
-\bar under
-
\series default
-\bar default
-The linker output (final object code) is in Motorola S19 format
-\begin_inset LatexCommand \index{Motorola S19 format}
+ Generate code for the Intel MCS51
+\begin_inset LatexCommand \index{MCS51}
\end_inset
-.
- The format itself is documented in the documentation of srecord.
+ family of processors.
+ This is the default processor target.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--out-fmt-elf
-\begin_inset LatexCommand \index{-\/-out-fmt-s19}
+-mds390
+\begin_inset LatexCommand \index{-mds390}
\end_inset
-\bar under
-
\series default
-\bar default
-The linker output (final object code) is in ELF format
-\begin_inset LatexCommand \index{ELF format}
+ Generate code for the Dallas DS80C390
+\begin_inset LatexCommand \index{DS80C390}
\end_inset
-.
- (Currently only supported for the HC08 processors)
+ processor.
\layout List
\labelwidthstring 00.00.0000
\series bold
--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
-
-MCS51 Options
-\begin_inset LatexCommand \index{Options MCS51}
+-mds400
+\begin_inset LatexCommand \index{-mds400}
\end_inset
-\begin_inset LatexCommand \index{MCS51 options}
+\series default
+ Generate code for the Dallas DS80C400
+\begin_inset LatexCommand \index{DS80C400}
\end_inset
-
+ processor.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-mhc08
+\begin_inset LatexCommand \index{-mhc08}
-\backslash
-/
\end_inset
--model-small
-\begin_inset LatexCommand \index{-\/-model-small}
-\end_inset
+\series default
+ Generate code for the Freescale/Motorola HC08
+\begin_inset LatexCommand \index{HC08}
+\end_inset
-\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.
+ family of processors.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-mz80
+\begin_inset LatexCommand \index{-mz80}
-\backslash
-/
\end_inset
--model-medium
-\begin_inset LatexCommand \index{-\/-model-medium}
-\end_inset
+\series default
+ Generate code for the Zilog Z80
+\begin_inset LatexCommand \index{Z80}
+\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.
+ 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
--model-large
-\begin_inset LatexCommand \index{-\/-model-large}
-\end_inset
+\series default
+ Generate code for the GameBoy Z80
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
+\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.
+ 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
--xstack
-\begin_inset LatexCommand \index{-\/-xstack}
+
+\series default
+ Generate code for the Atmel AVR
+\begin_inset LatexCommand \index{AVR}
\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
-\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}
+ or
+\begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
\end_inset
-\SpecialChar ~
- External Stack for more details.
+.
+\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
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-mpic14
+\begin_inset LatexCommand \index{-mpic14}
-\backslash
-/
\end_inset
--iram-size
+
\series default
-\SpecialChar ~
-<Value>
-\begin_inset LatexCommand \index{-\/-iram-size <Value>}
+ Generate code for the Microchip PIC 14
+\begin_inset LatexCommand \index{PIC14}
\end_inset
- Causes the linker to check if the internal ram usage is within limits of
- the given value.
+-bit processors (p16f84 and variants.
+ In development, not complete).
+\layout Comment
+
+p16f627 p16f628 p16f84 p16f873 p16f877?
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
+-mpic16
+\begin_inset LatexCommand \index{-mpic16}
-\layout Standard
+\end_inset
-\backslash
-/
-\end_inset
--xram-size
\series default
-\SpecialChar ~
-<Value>
-\begin_inset LatexCommand \index{-\/-xram-size <Value>}
+ Generate code for the Microchip PIC 16
+\begin_inset LatexCommand \index{PIC16}
\end_inset
- Causes the linker to check if the external ram usage is within limits of
- the given value.
+-bit processors (p18f452 and variants.
+ In development, not complete).
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
+-mtlcs900h
+\series default
+ Generate code for the Toshiba TLCS-900H
+\begin_inset LatexCommand \index{TLCS-900H}
-\layout Standard
+\end_inset
+
+ processor (Not maintained, not complete).
+\layout List
+\added_space_bottom bigskip \labelwidthstring 00.00.0000
+
+
+\series bold
+-mxa51
+\begin_inset LatexCommand \index{-mxa51}
-\backslash
-/
\end_inset
--code-size
+
\series default
-\SpecialChar ~
-<Value>
-\begin_inset LatexCommand \index{-\/-code-size <Value>}
+ Generate code for the Phillips XA51
+\begin_inset LatexCommand \index{XA51}
\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
+ processor (Not maintained, not complete).
+\layout Subsection
+Preprocessor Options
+\begin_inset LatexCommand \index{Options preprocessor}
-\series bold
--
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
-\backslash
-/
+\begin_inset LatexCommand \index{Preprocessor options}
+
\end_inset
--stack-size
-\series default
-\SpecialChar ~
-<Value>
-\begin_inset LatexCommand \index{-\/-stack-size <Value>}
+
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
\end_inset
- Causes the linker to check if there is at minimum <Value> bytes for stack.
+
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-I<path>
+\begin_inset LatexCommand \index{-I<path>}
-\backslash
-/
\end_inset
--pack-iram
-\series default
-\SpecialChar ~
-\begin_inset LatexCommand \index{-\/-pack-iram}
+\series default
+ The additional location where the pre processor will look for <..h> or
+\begin_inset Quotes eld
+\end_inset
+..h
+\begin_inset Quotes erd
\end_inset
- Causes the linker to use unused register banks for data variables and pack
- data, idata and stack together.
- This is the default now.
+ files.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-D<macro[=value]>
+\begin_inset LatexCommand \index{-D<macro[=value]>}
-\backslash
-/
\end_inset
--no-pack-iram
-\series default
-\SpecialChar ~
-
-\begin_inset LatexCommand \index{-\/-no-pack-iram}
-\end_inset
+\series default
+ Command line definition of macros.
+ Passed to the preprocessor.
+\layout List
+\labelwidthstring 00.00.0000
- Causes the linker to use old style for allocating memory areas.
-\layout Subsection
-DS390 / DS400 Options
-\begin_inset LatexCommand \index{Options DS390}
+\series bold
+-M
+\begin_inset LatexCommand \index{-M}
\end_inset
-\begin_inset LatexCommand \index{DS390 options}
+\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
+\begin_inset LatexCommand \index{-E}
\end_inset
-
+'.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-C
+\begin_inset LatexCommand \index{-C}
-\backslash
-/
\end_inset
--model-flat24
+
\series default
+ Tell the preprocessor not to discard comments.
+ Used with the `-E' option.
+\layout List
+\labelwidthstring 00.00.0000
+
-\begin_inset LatexCommand \index{-\/-model-flat24}
+\series bold
+-MM
+\begin_inset LatexCommand \index{-MM}
\end_inset
\size large
-\emph on
+\bar under
+\series default
\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.
+\bar default
+Like `-M' but the output mentions only the user header files included with
+ `#include
+\begin_inset Quotes eld
+\end_inset
+
+file"'.
+ System header files included with `#include <file>' are omitted.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-Aquestion(answer)
+\begin_inset LatexCommand \index{-Aquestion(answer)}
-\backslash
-/
\end_inset
--protect-sp-update
-\begin_inset LatexCommand \index{-\/-protect-sp-update}
+
+\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
+-Umacro
+\begin_inset LatexCommand \index{-Umacro}
\end_inset
\series default
- disable interrupts during ESP:SP updates.
+ 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
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+-dM
+\begin_inset LatexCommand \index{-dM}
-\backslash
-/
\end_inset
--stack-10bit
+
\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
-\begin_inset LatexCommand \index{-\/-stack-10bit}
+
+\series bold
+-dD
+\begin_inset LatexCommand \index{-dD}
\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
+\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
-\backslash
-/
-\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+\series bold
+-dN
+\begin_inset LatexCommand \index{-dN}
\end_inset
-\emph default
- option, but that has not been tested.
- It is incompatible with the
-\emph on
--
-\begin_inset ERT
-status Collapsed
+\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
+\added_space_bottom bigskip \labelwidthstring 00.00.0000
-\layout Standard
-\backslash
-/
-\end_inset
+\series bold
+-Wp\SpecialChar ~
+preprocessorOption[,preprocessorOption]
+\series default
--xstack
-\begin_inset LatexCommand \index{-\/-xstack}
+\begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
\end_inset
+...
+ Pass the preprocessorOption to the preprocessor
+\family typewriter
+sdcpp
+\family default
-\emph default
- 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
-
-\layout Standard
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
-\backslash
-/
\end_inset
--model-flat24 option
-\emph default
-).
-\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
--stack-probe
-\begin_inset LatexCommand \index{-\/-stack-probe}
+
+\begin_inset LatexCommand \index{Linker options}
\end_inset
-\series default
- insert call to function __stack_probe at each function prologue.
\layout List
\labelwidthstring 00.00.0000
\series bold
+-L\SpecialChar ~
-
+\series default
+
\begin_inset ERT
status Collapsed
/
\end_inset
--tini-libid
-\begin_inset LatexCommand \index{-\/-tini-libid}
+
+\series bold
+-lib-path
+\begin_inset LatexCommand \index{-\/-lib-path <path>}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{-L -\/-lib-path}
\end_inset
\series default
- <nnnn> LibraryID used in -mTININative.
-
+\SpecialChar ~
+<absolute path to additional libraries> This option is passed to the linkage
+ editor's additional libraries
+\begin_inset LatexCommand \index{Libraries}
+
+\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
/
\end_inset
--use-accelerator
-\begin_inset LatexCommand \index{-\/-use-accelerator}
+-xram-loc
+\series default
+
+\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
- generate code for DS390 Arithmetic Accelerator.
-
-\layout Subsection
+\end_inset
-Z80 Options
-\begin_inset LatexCommand \index{Options Z80}
+, default value is 0.
+ The value entered can be in Hexadecimal or Decimal format, e.g.: -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-xram-loc 0x8000 or -
+\begin_inset ERT
+status Collapsed
-\begin_inset LatexCommand \index{Z80 options}
+\layout Standard
+\backslash
+/
\end_inset
-
+-xram-loc 32768.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--callee-saves-bc
+-code-loc
\series default
-\begin_inset LatexCommand \index{-\/-callee-saves-bc}
+\begin_inset LatexCommand \index{-\/-code-loc <Value>}
\end_inset
+\SpecialChar ~
+<Value> The start location of the code
+\begin_inset LatexCommand \index{code}
-\size large
-\emph on
-
-\size default
-\emph default
-Force a called function to always save BC.
+\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
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-code-loc 0x8000 or -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-code-loc 32768.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--no-std-crt0
+-stack-loc
\series default
-\begin_inset LatexCommand \index{-\/-no-std-crt0}
+\begin_inset LatexCommand \index{-\/-stack-loc <Value>}
\end_inset
- When linking, skip the standard crt0.o object file.
- You must provide your own crt0.o for your system when linking.
-
-\layout Subsection
-
-Optimization Options
-\begin_inset LatexCommand \index{Options optimization}
+\SpecialChar ~
+<Value> By default the stack
+\begin_inset LatexCommand \index{stack}
\end_inset
+ 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
-\begin_inset LatexCommand \index{Optimization options}
+\layout Standard
+\backslash
+/
\end_inset
+-stack-loc 0x20 or -
+\begin_inset ERT
+status Collapsed
-\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
--nogcse
-\begin_inset LatexCommand \index{-\/-nogcse}
+-pack-iram
+\series default
+\SpecialChar ~
+
+\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
-\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
-pill
-\emph on
-loc
-\emph default
-ations, sloc
-\begin_inset LatexCommand \index{sloc (spill location)}
+\layout Standard
+\backslash
+/
\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
+-no-pack-iram
+\series default
+\SpecialChar ~
- can be used to turn off global subexpression elimination
-\begin_inset LatexCommand \index{Subexpression elimination}
+\begin_inset LatexCommand \index{-\/-no-pack-iram}
\end_inset
- for a given function only.
+ option if you need to manually place the stack.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--noinvariant
-\begin_inset LatexCommand \index{-\/-noinvariant}
+-xstack-loc
+\series default
-\end_inset
-
-
-\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}
+\begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
\end_inset
-.
- It is recommended that this option NOT be used, #pragma\SpecialChar ~
-noinvariant
-\begin_inset LatexCommand \index{\#pragma noinvariant}
+\SpecialChar ~
+<Value> By default the external stack
+\begin_inset LatexCommand \index{xstack}
\end_inset
- can be used to turn off invariant optimizations for a given function only.
-\layout List
-\labelwidthstring 00.00.0000
+ is placed after the pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
+\end_inset
-\series bold
--
+ 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
--noinduction
-\begin_inset LatexCommand \index{-\/-noinduction}
-
-\end_inset
-
+-xstack-loc 0x8000 or -
+\begin_inset ERT
+status Collapsed
-\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}
+\layout Standard
+\backslash
+/
\end_inset
- can be used to turn off induction optimizations for a given function only.
+-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
--nojtbound
-\begin_inset LatexCommand \index{-\/-nojtbound}
-
-\end_inset
-
-
-\size large
-\bar under
-
+-data-loc
\series default
-\size default
-\bar default
- Will not generate boundary condition check when switch statements
-\begin_inset LatexCommand \index{switch statement}
-
-\end_inset
- are implemented using jump-tables.
- See section
-\begin_inset LatexCommand \ref{sub:'switch'-Statements}
+\begin_inset LatexCommand \index{-\/-data-loc <Value>}
\end_inset
\SpecialChar ~
-Switch Statements for more details.
- It is recommended that this option is NOT used, #pragma\SpecialChar ~
-nojtbound
-\begin_inset LatexCommand \index{\#pragma nojtbound}
+<Value> The start location of the internal ram data
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
\end_inset
- can be used to turn off boundary checking for jump tables for a given function
- only.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--
+ segment.
+ The value entered can be in Hexadecimal or Decimal format, eg.
+ -
\begin_inset ERT
status Collapsed
/
\end_inset
--noloopreverse
-\begin_inset LatexCommand \index{-\/-noloopreverse}
-
-\end_inset
-
+-data-loc 0x20 or -
+\begin_inset ERT
+status Collapsed
-\series default
-\size large
-
-\size default
-Will not do loop reversal
-\begin_inset LatexCommand \index{Loop reversing}
+\layout Standard
+\backslash
+/
\end_inset
-optimization.
-\layout List
-\labelwidthstring 00.00.0000
-
--
+-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
/
\end_inset
--
-\series bold
-nolabelopt
-\series default
-
-\begin_inset LatexCommand \index{-\/-nolabelopt }
-
-\end_inset
-
-Will not optimize labels (makes the dumpfiles more readable).
+-data-loc is not used, to location 0x10.)
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--no-xinit-opt
-\begin_inset LatexCommand \index{-\/-no-xinit-opt}
-
-\end_inset
-
-
+-idata-loc
\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}
+
+\begin_inset LatexCommand \index{-\/-idata-loc <Value>}
\end_inset
-.
-\layout List
-\labelwidthstring 00.00.0000
+\SpecialChar ~
+<Value> The start location of the indirectly addressable internal ram
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
+\end_inset
-\series bold
--
+ of the 8051, default value is 0x80.
+ The value entered can be in Hexadecimal or Decimal format, eg.
+ -
\begin_inset ERT
status Collapsed
/
\end_inset
--nooverlay
-\begin_inset LatexCommand \index{-\/-nooverlay}
-
-\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.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--
+-idata-loc 0x88 or -
\begin_inset ERT
status Collapsed
/
\end_inset
--no-peep
-\begin_inset LatexCommand \index{-\/-no-peep}
-
-\end_inset
-
-
-\series default
- Disable peep-hole optimization.
+-idata-loc 136.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--peep-file
+-bit-loc
\series default
-
-\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}
+<Value> The start location of the bit
+\begin_inset LatexCommand \index{bit}
\end_inset
-\SpecialChar ~
-Peep Hole optimizations for details on how to write these rules.
+ 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
--peep-asm
-\begin_inset LatexCommand \index{-\/-peep-asm}
+-out-fmt-ihx
+\begin_inset LatexCommand \index{-\/-out-fmt-ihx}
\end_inset
+\bar under
+
\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}
+\bar default
+The linker output (final object code) is in Intel Hex format.
+\begin_inset LatexCommand \index{Intel hex format}
\end_inset
- rules defined in the source file tree '<target>/peeph.def' before using
- this option.
+ 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
--opt-code-speed
-\begin_inset LatexCommand \index{-\/-opt-code-speed}
+-out-fmt-s19
+\begin_inset LatexCommand \index{-\/-out-fmt-s19}
\end_inset
+\bar under
+
\series default
- The compiler will optimize code generation towards fast code, possibly
- at the expense of code size.
+\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
--opt-code-size
-\begin_inset LatexCommand \index{-\/-opt-code-size}
+-out-fmt-elf
+\begin_inset LatexCommand \index{-\/-out-fmt-s19}
\end_inset
-\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}
+\begin_inset LatexCommand \index{HC08!Options!-\/-out-fmt-elf}
\end_inset
-\layout List
-\labelwidthstring 00.00.0000
+\bar under
+
+\series default
+\bar default
+The linker output (final object code) is in ELF format
+\begin_inset LatexCommand \index{ELF format}
+\end_inset
-\series bold
--c\SpecialChar ~
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--compile-only
-\begin_inset LatexCommand \index{-\/-compile-only}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{-c -\/-compile-only}
+.
+ (Currently only supported for the HC08
+\begin_inset LatexCommand \index{HC08}
\end_inset
-
-\series default
- will compile and assemble the source, but will not call the linkage editor.
+ processors)
\layout List
-\labelwidthstring 00.00.0000
+\added_space_bottom bigskip \labelwidthstring 00.00.0000
\series bold
--
+-Wl\SpecialChar ~
+linkOption[,linkOption]
\series default
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+\begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
-\backslash
-/
\end_inset
+...
+ Pass the linkOption to the linker.
+ If a bootloader is used an option like
+\begin_inset Quotes sld
+\end_inset
-\series bold
--c1mode
-\begin_inset LatexCommand \index{-\/-c1mode}
-
+-Wl\SpecialChar ~
+-bCSEG=0x1000
+\begin_inset Quotes srd
\end_inset
+ would be typical to set the start of the code segment.
+ See also #pragma constseg and #pragma codeseg in section
+\begin_inset LatexCommand \ref{sec:Pragmas}
-\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
+\end_inset
+ .
+ File sdcc/as/doc/asxhtm.html has more on linker options.
+\layout Subsection
-\series bold
--E
-\begin_inset LatexCommand \index{-E}
+MCS51 Options
+\begin_inset LatexCommand \index{Options MCS51}
\end_inset
-\series default
- Run only the C preprocessor.
- Preprocess all the C source files specified and output the results to standard
- output.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--o\SpecialChar ~
-<path/file>
-\begin_inset LatexCommand \index{-o <path/file>}
+\begin_inset LatexCommand \index{MCS51 options}
\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
/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+-model-small
+\begin_inset LatexCommand \index{-\/-model-small}
\end_inset
\size default
\emph default
-All functions in the source file will be compiled as
-\emph on
-reentrant
-\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
-\begin_inset LatexCommand \index{reentrant}
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-, i.e.
- the parameters and local variables will be allocated on the stack
-\begin_inset LatexCommand \index{stack}
+\layout Standard
+\backslash
+/
\end_inset
-.
- See section
-\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
+-model-medium
+\begin_inset LatexCommand \index{-\/-model-medium}
\end_inset
- Parameters and Local Variables for more details.
- If this option is used all source files in the project should be compiled
+
+\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 automatically implies --int-long-reent and --float-reent.
-
+ It must also be used when invoking the linker.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--callee-saves
-\begin_inset LatexCommand \index{-\/-callee-saves}
+-model-large
+\begin_inset LatexCommand \index{-\/-model-large}
\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 (function prologue
+ 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
+-
+\begin_inset ERT
+status Collapsed
-\begin_inset LatexCommand \index{function prologue}
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xstack
+\begin_inset LatexCommand \index{-\/-xstack}
\end_inset
\series default
- & epilogue
-\series bold
+ Uses a pseudo stack in the pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
-\begin_inset LatexCommand \index{function epilogue}
+\end_inset
+
+ area (usually the first 256 bytes in the external ram) for allocating variables
+ and passing parameters.
+ See section
+\begin_inset LatexCommand \ref{sub:External-Stack}
\end_inset
+\SpecialChar ~
+ External Stack for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
-\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 -
+\series bold
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--callee-saves option string.
- Also see #pragma\SpecialChar ~
-callee_saves
-\begin_inset LatexCommand \index{\#pragma callee\_saves}
+-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
/
\end_inset
--debug
-\begin_inset LatexCommand \index{-\/-debug}
-
-\end_inset
-
-
-\bar under
-
+-xram-size
\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}
+\SpecialChar ~
+<Value>
+\begin_inset LatexCommand \index{-\/-xram-size <Value>}
\end_inset
- format which is commonly used by third party tools.
+ Causes the linker to check if the external ram usage is within limits of
+ the given value.
\layout List
\labelwidthstring 00.00.0000
\series bold
--S
-\begin_inset LatexCommand \index{-S}
+-
+\begin_inset ERT
+status Collapsed
-\end_inset
+\layout Standard
+\backslash
+/
+\end_inset
-\size large
-\bar under
-
+-code-size
\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.
+\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
/
\end_inset
--int-long-reent
-\begin_inset LatexCommand \index{-\/-int-long-reent}
+-stack-size
+\series default
+\SpecialChar ~
+<Value>
+\begin_inset LatexCommand \index{-\/-stack-size <Value>}
\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.
+ Causes the linker to check if there is at minimum <Value> bytes for stack.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--cyclomatic
-\begin_inset LatexCommand \index{-\/-cyclomatic}
+-pack-iram
+\series default
+\SpecialChar ~
+
+\begin_inset LatexCommand \index{-\/-pack-iram}
\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}
-
-\end_inset
-
-
-\emph default
- see section on Cyclomatic Complexity for more details.
+ 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
+\added_space_bottom bigskip \labelwidthstring 00.00.0000
\series bold
/
\end_inset
--float-reent
-\begin_inset LatexCommand \index{-\/-float-reent}
+-no-pack-iram
+\series default
+\SpecialChar ~
+
+\begin_inset LatexCommand \index{-\/-no-pack-iram}
\end_inset
+ Causes the linker to use old style for allocating memory areas.
+\layout Subsection
-\series default
- Floating point library is compiled as reentrant
-\begin_inset LatexCommand \index{reentrant}
+DS390 / DS400 Options
+\begin_inset LatexCommand \index{Options DS390}
\end_inset
-.
- See section Installation for more details.
+
+\begin_inset LatexCommand \index{DS390}
+
+\end_inset
+
+
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--main-return
-\begin_inset LatexCommand \index{-\/-main-return}
-
-\end_inset
-
-
+-model-flat24
\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}
+
+\begin_inset LatexCommand \index{DS390!Options!-\/-model-flat24}
\end_inset
- function will return to the function calling main.
- The default setting is to lock up i.e.
- generate a '
-\family typewriter
-sjmp .
-\family default
-'.
+
+\size large
+\emph on
+
+\size default
+\emph default
+Generate 24-bit flat mode code.
+ This is the one and only that the ds390 code generator supports right now
+ and is default when using
+\emph on
+-mds390
+\emph default
+.
+ See section Memory Models for more details.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--nostdinc
-\begin_inset LatexCommand \index{-\/-nostdinc}
+-protect-sp-update
+\begin_inset LatexCommand \index{DS390!Options!-\/-protect-sp-update}
\end_inset
\series default
- This will prevent the compiler from passing on the default include path
- to the preprocessor.
+ disable interrupts during ESP:SP updates.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--nostdlib
-\begin_inset LatexCommand \index{-\/-nostdlib}
-
-\end_inset
-
-
+-stack-10bit
\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
+\begin_inset LatexCommand \index{DS390!Options!-\/-stack-10bit}
+\end_inset
-\series bold
+ 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
/
\end_inset
--verbose
-\begin_inset LatexCommand \index{-\/-verbose}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
-\series default
- Shows the various actions the compiler is performing.
-\layout List
-\labelwidthstring 00.00.0000
-
+\emph default
+ option, but that has not been tested.
+ It is incompatible with the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
-\series bold
--V
-\begin_inset LatexCommand \index{-V}
+\layout Standard
+\backslash
+/
\end_inset
+-xstack
+\begin_inset LatexCommand \index{-\/-xstack}
-\series default
- Shows the actual commands the compiler is executing.
-\layout List
-\labelwidthstring 00.00.0000
+\end_inset
-\series bold
+\emph default
+ 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
--no-c-code-in-asm
-\begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
-
-\end_inset
-
-
-\series default
- Hides your ugly and inefficient c-code from the asm file, so you can always
- blame the compiler :)
+-model-flat24 option
+\emph default
+).
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--no-peep-comments
-\begin_inset LatexCommand \index{-\/-no-peep-comments}
+-stack-probe
+\begin_inset LatexCommand \index{DS390!Options!-\/-stack-probe}
\end_inset
\series default
- Will not include peep-hole comments in the generated files.
+ insert call to function __stack_probe at each function prologue.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--i-code-in-asm
-\begin_inset LatexCommand \index{-\/-i-code-in-asm}
+-tini-libid
+\begin_inset LatexCommand \index{DS390!Options!-\/-tini-libid}
\end_inset
\series default
- Include i-codes in the asm file.
- Sounds like noise but is most helpful for debugging the compiler itself.
+ <nnnn> LibraryID used in -mTININative.
+
\layout List
-\labelwidthstring 00.00.0000
+\added_space_bottom bigskip \labelwidthstring 00.00.0000
\series bold
/
\end_inset
--less-pedantic
-\begin_inset LatexCommand \index{-\/-less-pedantic}
+-use-accelerator
+\begin_inset LatexCommand \index{DS390!Options!-\/-use-accelerator}
\end_inset
\series default
- Disable some of the more pedantic warnings
-\begin_inset LatexCommand \index{Warnings}
+ generate code for DS390 Arithmetic Accelerator.
+
+\layout Subsection
+
+Z80 Options
+\begin_inset LatexCommand \index{Options Z80}
\end_inset
- (jwk burps: please be more specific here, please!).
+
+\begin_inset LatexCommand \index{Z80}
+
+\end_inset
+
+
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--disable-warning\SpecialChar ~
-<nnnn>
-\begin_inset LatexCommand \index{-\/-disable-warning}
+-callee-saves-bc
+\series default
+
+\begin_inset LatexCommand \index{Z80!Options!-\/-callee-saves-bc}
\end_inset
-\series default
- Disable specific warning with number <nnnn>.
+\size large
+\emph on
+
+\size default
+\emph default
+Force a called function to always save BC.
\layout List
-\labelwidthstring 00.00.0000
+\added_space_bottom bigskip \labelwidthstring 00.00.0000
\series bold
/
\end_inset
--print-search-dirs
-\begin_inset LatexCommand \index{-\/-print-search-dirs}
-
-\end_inset
-
-
+-no-std-crt0
\series default
- Display the directories in the compiler's search path
-\layout List
-\labelwidthstring 00.00.0000
+\begin_inset LatexCommand \index{Z80!Options!-\/-no-std-crt0}
-\series bold
--
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
+ When linking, skip the standard crt0.o object file.
+ You must provide your own crt0.o for your system when linking.
+
+\layout Subsection
+
+Optimization Options
+\begin_inset LatexCommand \index{Options optimization}
-\backslash
-/
\end_inset
--vc
-\begin_inset LatexCommand \index{-\/-vc}
+
+\begin_inset LatexCommand \index{Optimization options}
\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
/
\end_inset
--use-stdout
-\begin_inset LatexCommand \index{-\/-use-stdout}
+-nogcse
+\begin_inset LatexCommand \index{-\/-nogcse}
\end_inset
\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]}
+ 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
+pill
+\emph on
+loc
+\emph default
+ations, sloc
+\begin_inset LatexCommand \index{sloc (spill location)}
\end_inset
-...
- Pass the asmOption to the assembler
-\begin_inset LatexCommand \index{Options assembler}
+).
+ 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
-
-\begin_inset LatexCommand \index{Assembler options}
+ can be used to turn off global subexpression elimination
+\begin_inset LatexCommand \index{Subexpression elimination}
\end_inset
-.
- See file sdcc/as/doc/asxhtm.html for assembler options.cd
+ for a given function only.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--std-sdcc89
-\begin_inset LatexCommand \index{-\/-std-sdcc89}
+-noinvariant
+\begin_inset LatexCommand \index{-\/-noinvariant}
\end_inset
\series default
- Generally follow the C89 standard, but allow SDCC features that conflict
- with the standard (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
+
+.
+ It is recommended that this option NOT be used, #pragma\SpecialChar ~
+noinvariant
+\begin_inset LatexCommand \index{\#pragma noinvariant}
+
+\end_inset
+
+ can be used to turn off invariant optimizations for a given function only.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--std-c89
-\begin_inset LatexCommand \index{-\/-std-c89}
+-noinduction
+\begin_inset LatexCommand \index{-\/-noinduction}
\end_inset
\series default
- Follow the C89 standard and disable SDCC features that conflict with the
- standard.
+ 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
+
+ can be used to turn off induction optimizations for a given function only.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--std-sdcc99
-\begin_inset LatexCommand \index{-\/-std-sdcc99}
+-nojtbound
+\begin_inset LatexCommand \index{-\/-nojtbound}
\end_inset
+\size large
+\bar under
+
\series default
- Generally follow the C99 standard, but allow SDCC features that conflict
- with the standard (incomplete support).
+\size default
+\bar default
+ Will not generate boundary condition check when switch statements
+\begin_inset LatexCommand \index{switch statement}
+
+\end_inset
+
+ are implemented using jump-tables.
+ See section
+\begin_inset LatexCommand \ref{sub:'switch'-Statements}
+
+\end_inset
+
+\SpecialChar ~
+Switch Statements for more details.
+ It is recommended that this option is NOT used, #pragma\SpecialChar ~
+nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
+
+\end_inset
+
+ can be used to turn off boundary checking for jump tables for a given function
+ only.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--std-c99
-\begin_inset LatexCommand \index{-\/-std-sdcc99}
+-noloopreverse
+\begin_inset LatexCommand \index{-\/-noloopreverse}
\end_inset
\series default
- Follow the C99 standard and disable SDCC features that conflict with the
- standard (incomplete support).
+\size large
+
+\size default
+Will not do loop reversal
+\begin_inset LatexCommand \index{Loop reversing}
+
+\end_inset
+
+optimization.
\layout List
\labelwidthstring 00.00.0000
-
-\series bold
-
\begin_inset ERT
status Collapsed
/
\end_inset
--codeseg
+-
+\series bold
+nolabelopt
\series default
-
-\begin_inset LatexCommand \index{-\/-codeseg <Value>}
-
-\end_inset
-
-\SpecialChar ~
-<Name> The name to be used for the code
-\begin_inset LatexCommand \index{code}
+
+\begin_inset LatexCommand \index{-\/-nolabelopt }
\end_inset
- 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.
+Will not optimize labels (makes the dumpfiles more readable).
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--constseg
-\series default
-
-\begin_inset LatexCommand \index{-\/-constseg <Value>}
+-no-xinit-opt
+\begin_inset LatexCommand \index{-\/-no-xinit-opt}
\end_inset
-\SpecialChar ~
-<Name> The name to be used for the const
-\begin_inset LatexCommand \index{code}
+
+\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
- 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
\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}
+-
+\begin_inset ERT
+status Collapsed
-\end_inset
+\layout Standard
+\backslash
+/
+\end_inset
-\begin_inset LatexCommand \index{lint (syntax checking tool)}
+-nooverlay
+\begin_inset LatexCommand \index{-\/-nooverlay}
\end_inset
-
-\begin_inset LatexCommand \url{http://www.splint.org}
-\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.
+\layout List
+\labelwidthstring 00.00.0000
-.
- 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)}
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- in your source file and add brackets around extended keywords (like
-\family sans
+-no-peep
+\begin_inset LatexCommand \index{-\/-no-peep}
-\begin_inset Quotes sld
\end_inset
-__at\SpecialChar ~
-\series bold
-(
\series default
-0xab
+ Disable peep-hole optimization with built-in rules.
+\layout List
+\labelwidthstring 00.00.0000
+
+
\series bold
-)
-\series default
+-
+\begin_inset ERT
+status Collapsed
-\begin_inset Quotes srd
+\layout Standard
+
+\backslash
+/
\end_inset
+-peep-file
+\series default
-\family default
- and
-\family sans
+\begin_inset LatexCommand \index{-\/-peep-file}
-\begin_inset Quotes sld
\end_inset
-__interrupt\SpecialChar ~
-(2)
-\begin_inset Quotes srd
+\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
-\family default
-).
-
-\newline
-Splint has an excellent on line manual at
-\begin_inset LatexCommand \url{http://www.splint.org/manual/}
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
- 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
+\layout Standard
-\family sans
-splint\SpecialChar ~
--I\SpecialChar ~
-/usr/local/share/sdcc/include/mcs51/\SpecialChar ~
-\SpecialChar ~
-myprogram.c
-\layout Subsection
+\backslash
+/
+\end_inset
-Intermediate Dump Options
-\begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
+-peep-asm
+\begin_inset LatexCommand \index{-\/-peep-asm}
\end_inset
-\begin_inset LatexCommand \index{Options intermediate dump}
+\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
-\begin_inset LatexCommand \index{Intermediate dump options}
-
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\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}
-
+\backslash
+/
\end_inset
-) 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
+-opt-code-speed
+\begin_inset LatexCommand \index{-\/-opt-code-speed}
-
-\begin_inset Quotes srd
\end_inset
-The anatomy of the compiler
-\begin_inset Quotes srd
-\end_inset
-.
+\series default
+ The compiler will optimize code generation towards fast code, possibly
+ at the expense of code size.
\layout List
-\labelwidthstring 00.00.0000
+\added_space_bottom bigskip \labelwidthstring 00.00.0000
\series bold
/
\end_inset
--dumpraw
-\begin_inset LatexCommand \index{-\/-dumpraw}
+-opt-code-size
+\begin_inset LatexCommand \index{-\/-opt-code-size}
\end_inset
\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}
+ 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}
\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
\series bold
+-c\SpecialChar ~
-
\begin_inset ERT
status Collapsed
/
\end_inset
--dumpgcse
-\begin_inset LatexCommand \index{-\/-dumpgcse}
+-compile-only
+\begin_inset LatexCommand \index{-\/-compile-only}
\end_inset
-\series default
- Will create a dump of iCode's, after global subexpression elimination
-\begin_inset LatexCommand \index{Global subexpression elimination}
+\begin_inset LatexCommand \index{-c -\/-compile-only}
\end_inset
-, into a file named
-\emph on
-<source filename>.dumpgcse.
+
+\series default
+ will compile and assemble the source, but will not call the linkage editor.
\layout List
\labelwidthstring 00.00.0000
\series bold
-
+\series default
+
\begin_inset ERT
status Collapsed
/
\end_inset
--dumpdeadcode
-\begin_inset LatexCommand \index{-\/-dumpdeadcode}
+
+\series bold
+-c1mode
+\begin_inset LatexCommand \index{-\/-c1mode}
\end_inset
\series default
- Will create a dump of iCode's, after deadcode elimination
-\begin_inset LatexCommand \index{Dead-code elimination}
+ reads the preprocessed source from standard input and compiles it.
+ The file name for the assembler output must be specified using the -o option.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-E
+\begin_inset LatexCommand \index{-E}
\end_inset
-, into a file named
-\emph on
-<source filename>.dumpdeadcode.
+
+\series default
+ Run only the C preprocessor.
+ Preprocess all the C source files specified and output the results to standard
+ output.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-o\SpecialChar ~
+<path/file>
+\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
/
\end_inset
--dumploop
-\begin_inset LatexCommand \index{-\/-dumploop}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
\series default
\size large
+\emph on
\size default
-Will create a dump of iCode's, after loop optimizations
-\begin_inset LatexCommand \index{Loop optimization}
+\emph default
+All functions in the source file will be compiled as
+\emph on
+reentrant
+\emph default
+
+\begin_inset LatexCommand \index{reentrant}
\end_inset
-, into a file named
-\emph on
-<source filename>.dumploop.
+, 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
/
\end_inset
--dumprange
-\begin_inset LatexCommand \index{-\/-dumprange}
+-callee-saves
+\begin_inset LatexCommand \index{-\/-callee-saves}
\end_inset
+ function1[,function2][,function3]....
\series default
-\size large
-
-\size default
-Will create a dump of iCode's, after live range analysis
-\begin_inset LatexCommand \index{Live range analysis}
+ 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
-\end_inset
+\begin_inset LatexCommand \index{function prologue}
-, into a file named
-\emph on
-<source filename>.dumprange.
-\layout List
-\labelwidthstring 00.00.0000
+\end_inset
+\series default
+ & epilogue
\series bold
--
+
+\begin_inset LatexCommand \index{function epilogue}
+
+\end_inset
+
+
+\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
/
\end_inset
--dumlrange
-\begin_inset LatexCommand \index{-\/-dumlrange}
-
-\end_inset
-
-
-\series default
- Will dump the life ranges
-\begin_inset LatexCommand \index{Live range analysis}
+-callee-saves option string.
+ Also see #pragma\SpecialChar ~
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
\end_inset
- for all symbols.
+.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--dumpregassign
-\begin_inset LatexCommand \index{-\/-dumpregassign}
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
\end_inset
\series default
\bar default
-Will create a dump of iCode's, after register assignment
-\begin_inset LatexCommand \index{Register assignment}
-
+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
-, into a file named
-\emph on
-<source filename>.dumprassgn.
+ 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
+
+
+\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
/
\end_inset
--dumplrange
-\begin_inset LatexCommand \index{-\/-dumplrange}
+-int-long-reent
+\begin_inset LatexCommand \index{-\/-int-long-reent}
\end_inset
\series default
- Will create a dump of the live ranges of iTemp's
+ 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
/
\end_inset
--dumpall
-\begin_inset LatexCommand \index{-\/-dumpall}
+-cyclomatic
+\begin_inset LatexCommand \index{-\/-cyclomatic}
\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
+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}
-By default SDCC writes it's error messages to
-\begin_inset Quotes sld
\end_inset
-standard error
-\begin_inset Quotes srd
-\end_inset
-.
- To force all messages to
-\begin_inset Quotes sld
-\end_inset
+\emph default
+ see section on Cyclomatic Complexity for more details.
+\layout List
+\labelwidthstring 00.00.0000
-standard output
-\begin_inset Quotes srd
-\end_inset
- use
\series bold
-
-\series default
-\emph on
-
\begin_inset ERT
status Collapsed
/
\end_inset
+-float-reent
+\begin_inset LatexCommand \index{-\/-float-reent}
+
+\end_inset
+
-\series bold
-\emph default
--
\series default
-use-stdout
-\begin_inset LatexCommand \index{-\/-use-stdout}
+ Floating point library is compiled as reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
.
- 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
+ See section Installation for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+\series bold
+-
\begin_inset ERT
status Collapsed
/
\end_inset
+-main-return
+\begin_inset LatexCommand \index{-\/-main-return}
+
+\end_inset
+
-\emph default
--vc
-\begin_inset LatexCommand \index{-\/-vc}
+\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 results in slightly smaller code and saves two bytes of stack
+ space.
+ The return from the 'main'
+\begin_inset LatexCommand \index{main return}
\end_inset
- option.
- Something like this should work:
-\newline
+ function will return to the function calling main.
+ The default setting is to lock up i.e.
+ generate a '
+\family typewriter
+sjmp .
+\family default
+'.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
\series bold
-c:
-\backslash
-sdcc
-\backslash
-bin
-\backslash
-sdcc.exe -
-\series default
-\emph on
-
+-
\begin_inset ERT
status Collapsed
/
\end_inset
+-nostdinc
+\begin_inset LatexCommand \index{-\/-nostdinc}
+
+\end_inset
+
-\series bold
-\emph default
--vc -
\series default
-\emph on
+ This will prevent the compiler from passing on the default include path
+ to the preprocessor.
+\layout List
+\labelwidthstring 00.00.0000
+
+\series bold
+-
\begin_inset ERT
status Collapsed
/
\end_inset
-
-\series bold
-\emph default
--model-large -c $(InputPath)
-\layout Section
-
-Environment variables
-\begin_inset LatexCommand \index{Environment variables}
+-nostdlib
+\begin_inset LatexCommand \index{-\/-nostdlib}
\end_inset
-\layout Standard
+\series default
+ This will prevent the compiler from passing on the default library
+\begin_inset LatexCommand \index{Libraries}
-SDCC recognizes the following environment variables:
+\end_inset
+
+ path to the linker.
\layout List
\labelwidthstring 00.00.0000
\series bold
-SDCC_LEAVE_SIGNALS
-\begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
+-
+\begin_inset ERT
+status Collapsed
-\end_inset
+\layout Standard
+\backslash
+/
+\end_inset
-\series default
- SDCC installs a signal handler
-\begin_inset LatexCommand \index{signal handler}
+-verbose
+\begin_inset LatexCommand \index{-\/-verbose}
\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.
+
+\series default
+ Shows the various actions the compiler is performing.
\layout List
\labelwidthstring 00.00.0000
\series bold
-TMP,\SpecialChar ~
-TEMP,\SpecialChar ~
-TMPDIR
-\begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
+-V
+\begin_inset LatexCommand \index{-V}
\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.
+ Shows the actual commands the compiler is executing.
\layout List
\labelwidthstring 00.00.0000
\series bold
-SDCC_HOME
-\begin_inset LatexCommand \index{SDCC\_HOME}
-
-\end_inset
-
+-
+\begin_inset ERT
+status Collapsed
-\series default
- Path, see section
-\begin_inset LatexCommand \ref{sub:Install-paths}
+\layout Standard
+\backslash
+/
\end_inset
-\SpecialChar ~
+-no-c-code-in-asm
+\begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
-\begin_inset Quotes sld
\end_inset
- Install Paths
-\begin_inset Quotes srd
-\end_inset
-.
+\series default
+ Hides your ugly and inefficient c-code from the asm file, so you can always
+ blame the compiler :)
\layout List
\labelwidthstring 00.00.0000
\series bold
-SDCC_INCLUDE
-\begin_inset LatexCommand \index{SDCC\_INCLUDE}
-
-\end_inset
-
+-
+\begin_inset ERT
+status Collapsed
-\series default
- Path, see section
-\begin_inset LatexCommand \ref{sub:Search-Paths}
+\layout Standard
+\backslash
+/
\end_inset
-\SpecialChar ~
+-no-peep-comments
+\begin_inset LatexCommand \index{-\/-no-peep-comments}
-\begin_inset Quotes sld
\end_inset
-Search Paths
-\begin_inset Quotes srd
-\end_inset
-.
+\series default
+ Will not include peep-hole comments in the generated files.
\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
+
+-i-code-in-asm
+\begin_inset LatexCommand \index{-\/-i-code-in-asm}
\end_inset
\series default
- Path, see section
-\begin_inset LatexCommand \ref{sub:Search-Paths}
+ 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
-\end_inset
-\SpecialChar ~
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\begin_inset Quotes sld
-\end_inset
+\layout Standard
-Search Paths
-\begin_inset Quotes srd
+\backslash
+/
\end_inset
-..
-\layout Standard
+-less-pedantic
+\begin_inset LatexCommand \index{-\/-less-pedantic}
-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
+\end_inset
-Storage Class Language Extensions
-\layout Subsection
-MCS51/DS390 Storage Class
-\begin_inset LatexCommand \index{Storage class}
+\series default
+ Disable some of the more pedantic warnings
+\begin_inset LatexCommand \index{Warnings}
\end_inset
- Language Extensions
+ (jwk burps: please be more specific here, please!).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\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
-data
-\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
+-disable-warning\SpecialChar ~
+<nnnn>
+\begin_inset LatexCommand \index{-\/-disable-warning}
\end_inset
-\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
+\series default
+ Disable specific warning with number <nnnn>.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- / near
-\begin_inset LatexCommand \index{near (storage class)}
+-print-search-dirs
+\begin_inset LatexCommand \index{-\/-print-search-dirs}
\end_inset
-\begin_inset LatexCommand \index{\_\_near (storage class)}
+\series default
+ Display the directories in the compiler's search path
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-This is the
-\series bold
-default
+\backslash
+/
+\end_inset
+
+-vc
+\begin_inset LatexCommand \index{-\/-vc}
+
+\end_inset
+
+
\series default
- storage class for the Small Memory model (
-\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
+ Display errors and warnings using MSVC style, so you can use SDCC with
+ visual studio.
+ With SDCC both offering a GCC-like (the default) and a MSVC-like output
+ style, integration into most programming editors should be straightforward.
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-data unsigned char test_data;
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-Writing 0x01 to this variable generates the assembly code:
-\layout Verse
+\backslash
+/
+\end_inset
+-use-stdout
+\begin_inset LatexCommand \index{-\/-use-stdout}
-\family typewriter
-75*00 01\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov\SpecialChar ~
-\SpecialChar ~
-_test_data,#0x01
-\layout Subsubsection
+\end_inset
-xdata
-\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
-\end_inset
+\series default
+ Send errors and warnings to stdout instead of stderr.
+\layout List
+\labelwidthstring 00.00.0000
-\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
+\series bold
+-Wa\SpecialChar ~
+asmOption[,asmOption]
+\series default
+
+\begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
\end_inset
- / far
-\begin_inset LatexCommand \index{far (storage class)}
+...
+ Pass the asmOption to the assembler
+\begin_inset LatexCommand \index{Options assembler}
\end_inset
-\begin_inset LatexCommand \index{\_\_far (storage class)}
+\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
-\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 the Large Memory model, e.g.:
-\layout Verse
-
+-
+\begin_inset ERT
+status Collapsed
-\family typewriter
-xdata unsigned char test_xdata;
\layout Standard
-Writing 0x01 to this variable generates the assembly code:
-\layout Verse
-
-
-\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
+\backslash
+/
+\end_inset
-idata
-\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
+-std-sdcc89
+\begin_inset LatexCommand \index{-\/-std-sdcc89}
\end_inset
-\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
+\series default
+ Generally follow the C89 standard, but allow SDCC features that conflict
+ with the standard (default).
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\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
-
+\backslash
+/
+\end_inset
-\family typewriter
-idata unsigned char test_idata;
-\layout Standard
+-std-c89
+\begin_inset LatexCommand \index{-\/-std-c89}
-Writing 0x01 to this variable generates the assembly code:
-\layout Verse
+\end_inset
-\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
+\series default
+ Follow the C89 standard and disable SDCC features that conflict with the
+ standard.
+\layout List
+\labelwidthstring 00.00.0000
-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}
-\end_inset
+\series bold
+-
+\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
+
+-std-sdcc99
+\begin_inset LatexCommand \index{-\/-std-sdcc99}
\end_inset
-\begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
+\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
-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)}
-
+\backslash
+/
\end_inset
-(or in case of some 8051 variants by a separate Special Function Register,
- see section
-\begin_inset LatexCommand \ref{sub:MCS51-variants}
+-std-c99
+\begin_inset LatexCommand \index{-\/-std-sdcc99}
\end_inset
-).
- This is the
-\series bold
-default
+
\series default
- storage class for the Medium Memory model, e.g.:
-\layout Verse
+ Follow the C99 standard and disable SDCC features that conflict with the
+ standard (incomplete support).
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-pdata unsigned char test_pdata;
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-Writing 0x01 to this variable generates the assembly code:
-\layout Verse
+\backslash
+/
+\end_inset
+-codeseg
+\series default
+
+\begin_inset LatexCommand \index{-\/-codeseg <Value>}
+
+\end_inset
-\family typewriter
-78r00\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov r0,#_test_pdata
-\newline
-74 01\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov a,#0x01
-\newline
-F2\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
-movx @r0,a
-\layout Standard
+<Name> The name to be used for the code
+\begin_inset LatexCommand \index{code}
-If the -
+\end_inset
+
+ 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
+
+
+\series bold
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--xstack
-\begin_inset LatexCommand \index{-\/-xstack}
+-constseg
+\series default
-\end_inset
+\begin_inset LatexCommand \index{-\/-constseg <Value>}
- 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
+\end_inset
-code
+\SpecialChar ~
+<Name> The name to be used for the const
\begin_inset LatexCommand \index{code}
\end_inset
+ 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
+\added_space_bottom bigskip \labelwidthstring 00.00.0000
+
-\begin_inset LatexCommand \index{\_\_code}
+\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
-\layout Standard
+\begin_inset LatexCommand \index{lint (syntax checking tool)}
-'Variables' declared with this storage class will be placed in the code
- memory:
-\layout Verse
+\end_inset
+
+\begin_inset LatexCommand \url{http://www.splint.org}
-\family typewriter
-code unsigned char test_code;
-\layout Standard
+\end_inset
-Read access to this variable generates the assembly code:
-\layout Verse
+.
+ 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 typewriter
-90s00r6F\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov dptr,#_test_code
-\newline
-E4\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-clr a
-\newline
-93\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-movc a,@a+dptr
-\layout Standard
+\end_inset
+ in your source file and add brackets around extended keywords (like
+\family sans
-\family typewriter
-char
-\family default
- indexed arrays of characters in code memory can be accessed efficiently:
-\layout Verse
+\begin_inset Quotes sld
+\end_inset
+__at\SpecialChar ~
-\family typewriter
-code char test_array[] = {'c','h','e','a','p'};
-\layout Standard
+\series bold
+(
+\series default
+0xab
+\series bold
+)
+\series default
-Read access to this array using an 8-bit unsigned index generates the assembly
- code:
-\layout Verse
+\begin_inset Quotes srd
+\end_inset
-\family typewriter
-E5*00\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov a,_index
-\layout Verse
+\family default
+ and
+\family sans
+\begin_inset Quotes sld
+\end_inset
-\family typewriter
-90s00r41\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov dptr,#_test_array
-\layout Verse
+__interrupt\SpecialChar ~
+(2)
+\begin_inset Quotes srd
+\end_inset
-\family typewriter
-93\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+\family default
+).
+
+\newline
+Splint has an excellent on line manual at
+\begin_inset LatexCommand \url{http://www.splint.org/manual/}
+
+\end_inset
+
+ 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 ~
-movc a,@a+dptr
-\layout Subsubsection
+myprogram.c
+\layout Subsection
-bit
-\begin_inset LatexCommand \index{bit}
+Intermediate Dump Options
+\begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
\end_inset
-\begin_inset LatexCommand \index{\_\_bit}
+\begin_inset LatexCommand \index{Options intermediate dump}
\end_inset
-\layout Standard
+\begin_inset LatexCommand \index{Intermediate dump options}
-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
+\end_inset
-\family typewriter
-bit test_bit;
\layout Standard
-Writing 1 to this variable generates the assembly code:
-\layout Verse
+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}
+\end_inset
-\family typewriter
-D2*00\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-setb\SpecialChar ~
-_test_bit
-\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
-The bit addressable memory consists of 128 bits which are located from 0x20
- to 0x2f in data memory.
-\newline
-Apart from this 8051 specific storage class most architectures support ANSI-C
- bitfields
-\begin_inset LatexCommand \index{bitfields}
+\begin_inset Quotes srd
+\end_inset
+The anatomy of the compiler
+\begin_inset Quotes srd
\end_inset
+.
+\layout List
+\labelwidthstring 00.00.0000
-\begin_inset Foot
-collapsed false
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Not really meant as examples, but nevertheless showing what bitfields are
- about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
+\backslash
+/
\end_inset
-.
- In accordance with ISO/IEC 9899 bits and bitfields without an explicit
- signed modifier are implemented as unsigned.
-\layout Subsubsection
-
-sfr
-\begin_inset LatexCommand \index{sfr}
+-dumpraw
+\begin_inset LatexCommand \index{-\/-dumpraw}
\end_inset
-\begin_inset LatexCommand \index{\_\_sfr}
+\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}
\end_inset
- / sfr16
-\begin_inset LatexCommand \index{sfr16}
+ at this stage ordered in the depth first number, so they may not be in
+ sequence of execution.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\begin_inset LatexCommand \index{\_\_sfr16}
+\layout Standard
+\backslash
+/
\end_inset
- / sfr32
-\begin_inset LatexCommand \index{sfr32}
+-dumpgcse
+\begin_inset LatexCommand \index{-\/-dumpgcse}
\end_inset
-\begin_inset LatexCommand \index{\_\_sfr32}
+\series default
+ Will create a dump of iCode's, after global subexpression elimination
+\begin_inset LatexCommand \index{Global subexpression elimination}
\end_inset
- / sbit
-\begin_inset LatexCommand \index{\_\_sbit}
+, into a file named
+\emph on
+<source filename>.dumpgcse.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\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
-
+\backslash
+/
+\end_inset
-\family typewriter
-sfr at
-\begin_inset LatexCommand \index{at}
+-dumpdeadcode
+\begin_inset LatexCommand \index{-\/-dumpdeadcode}
\end_inset
-\begin_inset LatexCommand \index{\_\_at}
+\series default
+ Will create a dump of iCode's, after deadcode elimination
+\begin_inset LatexCommand \index{Dead-code elimination}
\end_inset
- 0x80 P0;\SpecialChar ~
- /* special function register P0 at location 0x80 */
-\newline
-/* 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}
+, into a file named
+\emph on
+<source filename>.dumpdeadcode.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\begin_inset LatexCommand \index{\_\_at}
+\layout Standard
+\backslash
+/
\end_inset
- 0x8C8A TMR0;
-\newline
-sbit at 0xd7 CY; /* CY (Carry Flag
-\begin_inset LatexCommand \index{Flags}
+-dumploop
+\begin_inset LatexCommand \index{-\/-dumploop}
\end_inset
-\begin_inset LatexCommand \index{Carry flag}
+\series default
+\size large
+
+\size default
+Will create a dump of iCode's, after loop optimizations
+\begin_inset LatexCommand \index{Loop optimization}
\end_inset
-) */
-\layout Standard
-
-Special function registers which are located on an address dividable by
- 8 are bit-addressable, an
+, into a file named
\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.
-
-\emph default
- Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
- this is not guaranteed.
-\layout Subsubsection
+<source filename>.dumploop.
+\layout List
+\labelwidthstring 00.00.0000
-Pointers
-\begin_inset LatexCommand \index{Pointer}
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
- to MCS51/DS390 specific memory spaces
\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
+-dumprange
+\begin_inset LatexCommand \index{-\/-dumprange}
-\newline
-Pointer declaration examples:
-\layout Verse
+\end_inset
-\family typewriter
-/* pointer physically in internal ram pointing to object in external ram
- */
-\newline
-xdata unsigned char * data p;
-\newline
+\series default
+\size large
+
+\size default
+Will create a dump of iCode's, after live range analysis
+\begin_inset LatexCommand \index{Live range analysis}
-\newline
-/* pointer physically in external ram pointing to object in internal ram
- */
-\newline
-data unsigned char * xdata p;
-\newline
+\end_inset
-\newline
-/* pointer physically in code rom pointing to data in xdata space */
-\newline
-xdata unsigned char * code p;
-\newline
+, into a file named
+\emph on
+<source filename>.dumprange.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-/* pointer physically in code space pointing to data in code space */
-\newline
-code unsigned char * code p;
-\newline
-\newline
-/* the following is a generic pointer physically located in xdata space
- */
-\newline
-char * xdata p;
-\newline
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\newline
-/* the following is a function pointer physically located in data space
- */
-\newline
-char (* data fp)(void);
\layout Standard
-Well you get the idea.
-
-\newline
+\backslash
+/
+\end_inset
-\newline
-All unqualified pointers are treated as 3-byte (4-byte for the ds390)
-\emph on
-generic
-\emph default
- pointers.
-
-\size small
+-dumlrange
+\begin_inset LatexCommand \index{-\/-dumlrange}
-\newline
+\end_inset
-\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}
+\series default
+ Will dump the life ranges
+\begin_inset LatexCommand \index{Live range analysis}
\end_inset
- routines.
- Explicitly specifying the pointer type will generate the most efficient
- code.
-\layout Subsubsection
+ for all symbols.
+\layout List
+\labelwidthstring 00.00.0000
-Notes on MCS51 memory
-\begin_inset LatexCommand \index{MCS51 memory}
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
- layout
\layout Standard
-The 8051 family of microcontrollers have a minimum of 128 bytes of internal
- RAM memory which is structured as follows:
-\newline
+\backslash
+/
+\end_inset
-\newline
-- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
+-dumpregassign
+\begin_inset LatexCommand \index{-\/-dumpregassign}
+
+\end_inset
+
+
+\bar under
-\newline
-- Bytes 20-2F - 16 bytes to hold 128 bit
-\begin_inset LatexCommand \index{bit}
+\series default
+\bar default
+Will create a dump of iCode's, after register assignment
+\begin_inset LatexCommand \index{Register assignment}
\end_inset
- variables and,
-\newline
-- Bytes 30-7F - 80 bytes for general purpose use.
-\newline
+, into a file named
+\emph on
+<source filename>.dumprassgn.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-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
+\backslash
+/
+\end_inset
-\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
+-dumplrange
+\begin_inset LatexCommand \index{-\/-dumplrange}
\end_inset
-\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
+\series default
+ Will create a dump of the live ranges of iTemp's
+\layout List
+\added_space_bottom bigskip \labelwidthstring 00.00.0000
-\end_inset
-).
- Furthermore, some chips may have some built in external memory (
-\emph on
-xdata
-\emph default
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+\layout Standard
+\backslash
+/
\end_inset
-
-\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
+-dumpall
+\begin_inset LatexCommand \index{-\/-dumpall}
\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)}
+\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
+\added_space_bottom bigskip
+By default SDCC writes it's error messages to
+\begin_inset Quotes sld
\end_inset
+standard error
+\begin_inset Quotes srd
+\end_inset
-\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
+.
+ To force all messages to
+\begin_inset Quotes sld
+\end_inset
+standard output
+\begin_inset Quotes srd
\end_inset
-).
- Sometimes this built in
+ use
+\series bold
+-
+\series default
\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
+\begin_inset ERT
+status Collapsed
-\SpecialChar ~
-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)}
-
+\backslash
+/
\end_inset
+\series bold
\emph default
-) should be used in interrupt
-\begin_inset LatexCommand \index{interrupt}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{\_\_interrupt}
+-
+\series default
+use-stdout
+\begin_inset LatexCommand \index{-\/-use-stdout}
\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
+.
+ 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
-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
/
\end_inset
--data-loc
-\begin_inset LatexCommand \index{-\/-data-loc <Value>}
+
+\emph default
+-vc
+\begin_inset LatexCommand \index{-\/-vc}
\end_inset
- to specify the start address of the
+ option.
+ Something like this should work:
+\newline
+
+\newline
+
+\series bold
+c:
+\backslash
+sdcc
+\backslash
+bin
+\backslash
+sdcc.exe -
+\series default
\emph on
-data
-\emph default
- and -
+
\begin_inset ERT
status Collapsed
/
\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
+\series bold
\emph default
-+
+-vc -
+\series default
\emph on
-idata
-\emph default
-).
-
-\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
/
\end_inset
--stack-loc
-\begin_inset LatexCommand \index{-\/-stack-loc <Value>}
+
+\series bold
+\emph default
+-model-large -c $(InputPath)
+\layout Section
+
+Environment variables
+\begin_inset LatexCommand \index{Environment variables}
\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
+SDCC recognizes the following environment variables:
+\layout List
+\labelwidthstring 00.00.0000
--xdata-loc
-\begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
+
+\series bold
+SDCC_LEAVE_SIGNALS
+\begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
\end_inset
- to set the start address of the external RAM (
-\emph on
-xdata
-\emph default
-) and -
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\series default
+ SDCC installs a signal handler
+\begin_inset LatexCommand \index{signal handler}
-\backslash
-/
\end_inset
--xram-size
-\begin_inset LatexCommand \index{-\/-xram-size <Value>}
+ to be able to delete temporary files after an user break (^C) or an exception.
+ If this environment variable is set, SDCC won't install the signal handler
+ in order to be able to debug SDCC.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+TMP,\SpecialChar ~
+TEMP,\SpecialChar ~
+TMPDIR
+\begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
\end_inset
- to specify its size.
- Same goes for the code memory, using -
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\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
-\backslash
-/
-\end_inset
--code-loc
-\begin_inset LatexCommand \index{-\/-code-loc <Value>}
+\series bold
+SDCC_HOME
+\begin_inset LatexCommand \index{SDCC\_HOME}
\end_inset
- and -
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\series default
+ Path, see section
+\begin_inset LatexCommand \ref{sub:Install-paths}
-\backslash
-/
\end_inset
--code-size
-\begin_inset LatexCommand \index{-\/-code-size <Value>}
+\SpecialChar ~
+
+\begin_inset Quotes sld
+\end_inset
+ Install Paths
+\begin_inset Quotes srd
\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
+\layout List
+\labelwidthstring 00.00.0000
-The linker generates two files with memory allocation information.
- The first, with extension .map
-\begin_inset LatexCommand \index{<file>.map}
+
+\series bold
+SDCC_INCLUDE
+\begin_inset LatexCommand \index{SDCC\_INCLUDE}
\end_inset
- shows all the variables and segments.
- The second with extension .mem
-\begin_inset LatexCommand \index{<file>.mem}
+
+\series default
+ Path, see section
+\begin_inset LatexCommand \ref{sub:Search-Paths}
\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
+\SpecialChar ~
-Z80/Z180 Storage Class
-\begin_inset LatexCommand \index{Storage class}
+\begin_inset Quotes sld
+\end_inset
+Search Paths
+\begin_inset Quotes srd
\end_inset
- Language Extensions
-\layout Subsubsection
+.
+\layout List
+\labelwidthstring 00.00.0000
-sfr
-\begin_inset LatexCommand \index{sfr}
+
+\series bold
+SDCC_LIB
+\begin_inset LatexCommand \index{SDCC\_LIB}
\end_inset
-\begin_inset LatexCommand \index{\_\_sfr}
+\series default
+ Path, see section
+\begin_inset LatexCommand \ref{sub:Search-Paths}
\end_inset
- (in/out to 8-bit addresses)
-\layout Standard
-
-The Z80
-\begin_inset LatexCommand \index{Z80}
+\SpecialChar ~
+\begin_inset Quotes sld
\end_inset
- family has separate address spaces for memory and
+Search Paths
+\begin_inset Quotes srd
+\end_inset
+
+..
+\layout Standard
+\added_space_bottom bigskip
+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
+
+Storage Class Language Extensions
+\layout Subsection
+
+MCS51/DS390 Storage Class
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ Language Extensions
+\layout Standard
+
+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
+
+ / near
+\begin_inset LatexCommand \index{near (storage class)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_near (storage class)}
+
+\end_inset
+
+
+\layout Standard
+
+This is the
+\series bold
+default
+\series default
+ storage class for the Small Memory model (
\emph on
-i
+data
\emph default
-nput/
+ and
\emph on
-o
+near
\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.:
+ 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
-sfr at 0x78 IoPort;\SpecialChar ~
-\SpecialChar ~
-/* define a var in I/O space at 78h called IoPort */
-
+__data unsigned char test_data;
\layout Standard
Writing 0x01 to this variable generates the assembly code:
\family typewriter
-3E 01\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ld a,#0x01
-\newline
-D3 78\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+75*00 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+mov\SpecialChar ~
\SpecialChar ~
-out (_IoPort),a
+_test_data,#0x01
\layout Subsubsection
-banked sfr
-\begin_inset LatexCommand \index{sfr}
+xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
\end_inset
-\begin_inset LatexCommand \index{\_\_sfr}
+\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
\end_inset
- (in/out to 16-bit addresses)
-\layout Standard
+ / far
+\begin_inset LatexCommand \index{far (storage class)}
-The keyword
-\emph on
-banked
-\emph default
- is used to support 16 bit addresses in I/O memory e.g.:
-\layout Verse
+\end_inset
-\family typewriter
-sfr banked at
-\begin_inset LatexCommand \index{at}
+\begin_inset LatexCommand \index{\_\_far (storage class)}
\end_inset
-\begin_inset LatexCommand \index{\_\_at}
+\layout Standard
-\end_inset
+Variables declared with this storage class will be placed in the external
+ RAM.
+ This is the
+\series bold
+default
+\series default
+ storage class for the Large Memory model, e.g.:
+\layout Verse
- 0x123 IoPort;
+
+\family typewriter
+__xdata unsigned char test_xdata;
\layout Standard
Writing 0x01 to this variable generates the assembly code:
\family typewriter
-01 23 01\SpecialChar ~
+90s00r00\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ld bc,#_IoPort
+mov\SpecialChar ~
+\SpecialChar ~
+dptr,#_test_xdata
\newline
-3E 01\SpecialChar ~
+74\SpecialChar ~
+01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ld a,#0x01
+mov\SpecialChar ~
+\SpecialChar ~
+a,#0x01
\newline
-ED 79\SpecialChar ~
+F0\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-out (c),a
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+movx\SpecialChar ~
+@dptr,a
\layout Subsubsection
-sfr
-\begin_inset LatexCommand \index{sfr}
+idata
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
\end_inset
-\begin_inset LatexCommand \index{\_\_sfr}
-
-\end_inset
-
- (in0/out0 to 8 bit addresses on Z180
-\begin_inset LatexCommand \index{Z180}
+\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
\end_inset
-/HD64180
-\begin_inset LatexCommand \index{HD64180}
-
-\end_inset
-)
\layout Standard
-The compiler option -
-\begin_inset ERT
-status Collapsed
+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
-\layout Standard
-\backslash
-/
-\end_inset
+\family typewriter
+__idata unsigned char test_idata;
+\layout Standard
--portmode=180 (80) and a compiler #pragma\SpecialChar ~
-portmode
-\begin_inset LatexCommand \index{\#pragma portmode}
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
-\end_inset
-=z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
-ns
-\family typewriter
-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
+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
-HC08 Storage Class
-\begin_inset LatexCommand \index{Storage class}
+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}
\end_inset
- Language Extensions
+ is located in idata memory.
\layout Subsubsection
-data
-\begin_inset LatexCommand \index{data (hc08 storage class)}
+pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
\end_inset
-\begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
+\begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
\end_inset
-
-\layout Standard
-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
+\layout Standard
-xdata
-\begin_inset LatexCommand \index{xdata (hc08 storage class)}
+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
-
-\begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
+(or in case of some 8051 variants by a separate Special Function Register,
+ see section
+\begin_inset LatexCommand \ref{sub:MCS51-variants}
\end_inset
-
-\layout Standard
-
-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.:
+).
+ This is the
+\series bold
+default
+\series default
+ storage class for the Medium Memory model, e.g.:
\layout Verse
\family typewriter
-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
-
-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 (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
-\emph default
- initialized
-\begin_inset LatexCommand \index{Variable initialization}
-
-\end_inset
-
-.
+__pdata unsigned char test_pdata;
\layout Standard
-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:
+Writing 0x01 to this variable generates the assembly code:
\layout Verse
\family typewriter
-volatile
-\begin_inset LatexCommand \index{volatile}
+78r00\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov r0,#_test_pdata
+\newline
+74 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov a,#0x01
+\newline
+F2\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+movx @r0,a
+\layout Standard
-\end_inset
+If the -
+\begin_inset ERT
+status Collapsed
- xdata
-\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+\layout Standard
+\backslash
+/
\end_inset
- at
-\begin_inset LatexCommand \index{at}
+-xstack
+\begin_inset LatexCommand \index{-\/-xstack}
\end_inset
- 0x8000 unsigned char PORTA_8255;
-\layout Standard
-
-For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
-r) array
-\family typewriter
-\size footnotesize
+ 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
-\begin_inset LatexCommand \index{Aligned array}
+code
+\begin_inset LatexCommand \index{code}
\end_inset
-\family default
-\size default
- starts at a block (256 byte) boundary
-\begin_inset LatexCommand \index{block boundary}
+\begin_inset LatexCommand \index{\_\_code}
\end_inset
- (section
-\begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
-\end_inset
+\layout Standard
- has an example).
-\newline
-Absolute addresses can be specified for variables in all storage classes,
- e.g.:
+'Variables' declared with this storage class will be placed in the code
+ memory:
\layout Verse
\family typewriter
-bit
-\begin_inset LatexCommand \index{bit}
-
-\end_inset
-
- at
-\begin_inset LatexCommand \index{at}
-
-\end_inset
-
- 0x02 bvar;
+__code unsigned char test_code;
\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 your routine using:
+Read access to this variable generates the assembly code:
\layout Verse
\family typewriter
-extern volatile
-\begin_inset LatexCommand \index{volatile}
-
-\end_inset
-
- bit MOSI;\SpecialChar ~
-\SpecialChar ~
+90s00r6F\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* master out, slave in */
+mov dptr,#_test_code
\newline
-extern volatile bit MISO;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+E4\SpecialChar ~
\SpecialChar ~
-/* master in, slave out */
-\newline
-extern volatile bit MCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* master clock */
-\newline
-
-\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
-{
+clr a
\newline
+93\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char i=8;
-\newline
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-do {
-\newline
\SpecialChar ~
\SpecialChar ~
+movc a,@a+dptr
+\layout Standard
+
+
+\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
+E5*00\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+mov a,_index
+\layout Verse
+
+
+\family typewriter
+90s00r41\SpecialChar ~
\SpecialChar ~
-MOSI = out_byte & 0x80;
-\newline
\SpecialChar ~
+mov dptr,#_test_array
+\layout Verse
+
+
+\family typewriter
+93\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-out_byte <<= 1;
-\newline
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-MCLK = 1;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* _asm nop _endasm; */\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* for slow peripherals */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-if(MISO)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-out_byte += 1;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-MCLK = 0;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-} while(--i);
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return out_byte;
-\newline
-}
-\layout Standard
+movc a,@a+dptr
+\layout Subsubsection
-Then, someplace in the code for the first hardware you would use
-\layout Verse
+bit
+\begin_inset LatexCommand \index{bit}
+\end_inset
-\family typewriter
-bit at
-\begin_inset LatexCommand \index{at}
+
+\begin_inset LatexCommand \index{\_\_bit}
\end_inset
-\begin_inset LatexCommand \index{\_\_at}
+\layout Standard
-\end_inset
+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
- 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 */
+
+\family typewriter
+__bit test_bit;
\layout Standard
-Similarly, for the second hardware you would use
+Writing 1 to this variable generates the assembly code:
\layout Verse
\family typewriter
-bit at 0x83 MOSI;\SpecialChar ~
+D2*00\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* I/O port 0, bit 3 */
-\newline
-bit at 0x91 MISO;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* I/O port 1, bit 1 */
+setb\SpecialChar ~
+_test_bit
+\layout Standard
+
+The bit addressable memory consists of 128 bits which are located from 0x20
+ to 0x2f in data memory.
+
\newline
-bit
-\begin_inset LatexCommand \index{bit}
+Apart from this 8051 specific storage class most architectures support ANSI-C
+ bitfields
+\begin_inset LatexCommand \index{bitfields}
\end_inset
- at 0x92 MCLK;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* I/O port 1, bit 2 */
-\layout Standard
-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
+\begin_inset Foot
+collapsed false
-Parameters
-\begin_inset LatexCommand \index{Parameters}
+\layout Standard
+Not really meant as examples, but nevertheless showing what bitfields are
+ about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
\end_inset
+.
+ In accordance with ISO/IEC 9899 bits and bitfields without an explicit
+ signed modifier are implemented as unsigned.
+\layout Subsubsection
-\begin_inset LatexCommand \index{function parameter}
+sfr
+\begin_inset LatexCommand \index{sfr}
\end_inset
- & Local Variables
-\begin_inset LatexCommand \index{local variables}
-\end_inset
+\begin_inset LatexCommand \index{\_\_sfr}
+\end_inset
-\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
+ / sfr16
+\begin_inset LatexCommand \index{sfr16}
\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 similar to
-\emph on
-static
-\begin_inset LatexCommand \index{static}
+\begin_inset LatexCommand \index{\_\_sfr16}
\end_inset
-
-\emph default
- so by default functions are non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+ / sfr32
+\begin_inset LatexCommand \index{sfr32}
\end_inset
-.
-
-\newline
-\newline
-They can be placed on the stack
-\begin_inset LatexCommand \index{stack}
+\begin_inset LatexCommand \index{\_\_sfr32}
\end_inset
- by using the
-\emph on
- -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+ / sbit
+\begin_inset LatexCommand \index{\_\_sbit}
-\backslash
-/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\begin_inset LatexCommand \index{sbit}
\end_inset
+\layout Standard
+
+Like the bit keyword,
+\emph on
+sfr / sfr16 / sfr32 / sbit
\emph default
- option, by using
+signify both a data-type and storage class, they are used to describe the
+
\emph on
-#pragma\SpecialChar ~
-stackauto
+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
-\begin_inset LatexCommand \index{\#pragma stackauto}
-
-\end_inset
- or by using the
-\emph on
-reentrant
-\begin_inset LatexCommand \index{reentrant}
+\family typewriter
+__sfr __at
+\begin_inset LatexCommand \index{at}
\end_inset
-\emph default
- keyword in the function declaration, e.g.:
-\layout Verse
+\begin_inset LatexCommand \index{\_\_at}
+\end_inset
-\family typewriter
-unsigned char foo(char i) reentrant
+ (0x80) P0;\SpecialChar ~
+ /* special function register P0 at location 0x80 */
\newline
-{
+/* 16 bit special function register combination for timer 0 */
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
+/* with the high byte at location 0x8C and the low byte at location 0x8A
+ */
\newline
-}
-\layout Standard
-
-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
-
--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)}
+__sfr16 __at
+\begin_inset LatexCommand \index{at}
\end_inset
- independent.
-\newline
-\newline
-Local variables
-\begin_inset LatexCommand \index{local variables}
+\begin_inset LatexCommand \index{\_\_at}
\end_inset
- can be assigned storage classes and absolute
-\begin_inset LatexCommand \index{Absolute addressing}
+ (0x8C8A) TMR0;
+\newline
+__sbit __at (0xd7) CY; /* CY (Carry Flag
+\begin_inset LatexCommand \index{Flags}
\end_inset
- addresses, e.g.:
-\layout Verse
-
-\family typewriter
-unsigned char foo()
-\newline
-{
-\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}
+\begin_inset LatexCommand \index{Carry flag}
\end_inset
- 0x31 unsigned char j;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
+) */
\layout Standard
-In the above example the variable
+Special function registers which are located on an address dividable by
+ 8 are bit-addressable, an
\emph on
-i
+ sbit
\emph default
- will be allocated in the external ram,
+ 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
-bvar
+sfr16
\emph default
- in bit addressable space and
+ or
\emph on
- j
+sfr32.
+
\emph default
- in internal ram.
- When compiled with
-\emph on
--
-\begin_inset ERT
-status Collapsed
+ Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
+ this is not guaranteed.
+\newline
\layout Standard
-\backslash
-/
-\end_inset
-
--stack-auto
-\emph default
- or when a function is declared as
+Please note, if you use a header file which was written for another compiler
+ then the sfr / sfr16 / sfr32 / sbit Storage Class extensions will most
+ likely be
\emph on
-reentrant
+not
\emph default
- this should only be done for static variables.
-\layout Standard
-
-Parameters
-\begin_inset LatexCommand \index{function parameter}
-
-\end_inset
+compatible.
+ Specifically the syntax
+\family typewriter
+\SpecialChar ~
+sfr P0 = 0x80;\SpecialChar ~
- however are not allowed any storage class
-\begin_inset LatexCommand \index{Storage class}
+\family default
+ is compiled
+\emph on
+without warning
+\emph default
+ by SDCC to an assignment of 0x80 to a variable called P0
+\family typewriter
-\end_inset
+\begin_inset Marginal
+collapsed true
-, (storage classes for parameters will be ignored), their allocation is
- governed by the memory model in use, and the reentrancy options.
\layout Standard
-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}
+\series bold
+\SpecialChar ~
+!
\end_inset
-
-\layout Standard
-
-For non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+.
+
+\family default
+Nevertheless it is possible to write header files
+\begin_inset LatexCommand \index{Header files}
\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
-no other function calls and the function is non-reentrant and the memory
- model
-\begin_inset LatexCommand \index{Memory model}
+\begin_inset LatexCommand \index{Include files}
\end_inset
- is small.
-
-\emph default
- If an explicit storage class
-\begin_inset LatexCommand \index{Storage class}
+ which can be shared among different compilers (see section
+\begin_inset LatexCommand \ref{sec:Porting-code-to-other-compilers}
\end_inset
- is specified for a local variable, it will NOT be overlayed.
-\layout Standard
+).
+
+\layout Subsubsection
-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}
+Pointers
+\begin_inset LatexCommand \index{Pointer}
\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.
+ to MCS51/DS390 specific memory spaces
\layout Standard
-Parameters and local variables of functions that contain 16 or 32 bit multiplica
-tion
-\begin_inset LatexCommand \index{Multiplication}
+SDCC allows (via language extensions) pointers to explicitly point to any
+ of the memory spaces
+\begin_inset LatexCommand \index{Memory model}
\end_inset
- or division
-\begin_inset LatexCommand \index{Division}
-
-\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
- will NOT be overlayed since these are implemented using external functions,
- e.g.:
+\newline
+Pointer declaration examples:
\layout Verse
\family typewriter
-#pragma save
+/* pointer physically in internal ram pointing to object in external ram
+ */
+\newline
+__xdata unsigned char * __data p;
\newline
-#pragma nooverlay
-\begin_inset LatexCommand \index{\#pragma nooverlay}
-
-\end_inset
-
\newline
-void set_error(unsigned char errcd)
+/* pointer physically in external ram pointing to object in internal ram
+ */
\newline
-{
+__data unsigned char * __xdata p;
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-P3 = errcd;
+
\newline
-}
+/* pointer physically in code rom pointing to data in xdata space */
\newline
-#pragma restore
+__xdata unsigned char * __code p;
\newline
\newline
-void some_isr () interrupt
-\begin_inset LatexCommand \index{interrupt}
+/* pointer physically in code space pointing to data in code space */
+\newline
+__code unsigned char * __code p;
+\newline
-\end_inset
+\newline
+/* generic pointer physically located in xdata space */
+\newline
+unsigned char * __xdata p;
+\newline
- 2
\newline
-{
+/* generic pointer physically located in default memory space */
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
+unsigned char * p;
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-set_error(10);
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
+/* the following is a function pointer physically located in data space
+ */
\newline
-}
+char (* __data fp)(void);
\layout Standard
-In the above example the parameter
-\emph on
-errcd
-\emph default
- for the function
+Well you get the idea.
+
+\newline
+
+\newline
+All unqualified pointers are treated as 3-byte (4-byte for the ds390)
\emph on
-set_error
+generic
\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
-
-Interrupt Service Routines
-\begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
-
-\end_inset
-
+ pointers.
+
+\size small
-\layout Subsection
+\newline
-General Information
-\layout Standard
+\newline
-SDCC allows
-\emph on
-i
-\emph default
-nterrupt
+\size default
+The highest order byte of the
\emph on
-s
+generic
\emph default
-ervice
+ pointers contains the data space information.
+ Assembler support routines are called whenever data is stored or retrieved
+ using
\emph on
-r
+generic
\emph default
-outines to be coded in C, with some extended keywords.
-\layout Verse
-
-
-\family typewriter
-void timer_isr (void) interrupt 1 using 1
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
-\layout Standard
-
-The optional number following the
-\emph on
-interrupt
-\begin_inset LatexCommand \index{interrupt}
+ pointers.
+ These are useful for developing reusable library
+\begin_inset LatexCommand \index{Libraries}
\end_inset
+ routines.
+ Explicitly specifying the pointer type will generate the most efficient
+ code.
+\layout Subsubsection
-\begin_inset LatexCommand \index{\_\_interrupt}
+Notes on MCS51 memory
+\begin_inset LatexCommand \index{MCS51 memory}
\end_inset
+ layout
+\layout Standard
-\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.
- 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
-.
- The optional
-\emph on
-using
-\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
-
-\end_inset
-
+The 8051 family of microcontrollers have a minimum of 128 bytes of internal
+ RAM memory which is structured as follows:
+\newline
-\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
+\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
-
-\emph default
- keyword can be used to tell the compiler to use the specified register
- bank (8051 specific) when generating code for this function.
-
+ variables and,
+\newline
+- Bytes 30-7F - 80 bytes for general purpose use.
\newline
\layout Standard
-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
+Additionally some members of the MCS51 family may have up to 128 bytes of
+ additional, indirectly addressable, internal RAM memory (
\emph on
-volatile
+idata
\emph default
-\begin_inset LatexCommand \index{volatile}
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
\end_inset
-.
-
-\layout Standard
-If the access to these variables is not
-\emph on
-atomic
-\begin_inset LatexCommand \index{atomic}
+\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
- (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
-
-
-\family typewriter
-flags\SpecialChar ~
-|=\SpecialChar ~
-0x80;
-\family default
-\begin_inset Quotes sld
-\end_inset
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
- is not atomic if
-\family typewriter
-flags
-\family default
- resides in xdata.
- Setting
-\begin_inset Quotes srd
\end_inset
-\family typewriter
-flags\SpecialChar ~
-|=\SpecialChar ~
-0x40;
-\family default
-
-\begin_inset Quotes sld
-\end_inset
+\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
- from within an interrupt routine might get lost if the interrupt occurs
- at the wrong time.
-
-\begin_inset Quotes sld
\end_inset
+) which should not be confused with the internal, directly addressable RAM
+ memory (
+\emph on
+data
+\emph default
-\family typewriter
-counter\SpecialChar ~
-+=\SpecialChar ~
-8;
-\family default
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
-\begin_inset Quotes srd
\end_inset
- 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
-The return address and the registers used in the interrupt service routine
- are saved on the stack
-\begin_inset LatexCommand \index{stack}
+\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
\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
+).
+ Sometimes this built in
\emph on
-stack overflow
+xdata
\emph default
-
-\begin_inset LatexCommand \index{stack overflow}
+ 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
- is most likely to happen if the interrupt occurs during the
-\begin_inset Quotes sld
-\end_inset
+\SpecialChar ~
+Startup-Code).
+\layout Standard
+
+Normally SDCC will only use the first bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
-deepest
-\begin_inset Quotes srd
\end_inset
- subroutine when the stack is already in use for f.e.
- many return addresses.
-\layout Standard
+ of registers (register bank 0), but it is possible to specify that other
+ banks of registers (keyword
+\emph on
+using
+\emph default
+
+\emph on
-A special note here, int (16 bit) and long (32 bit) integer division
-\begin_inset LatexCommand \index{Division}
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
\end_inset
-, multiplication
-\begin_inset LatexCommand \index{Multiplication}
+
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
\end_inset
- & modulus
-\begin_inset LatexCommand \index{Modulus}
+
+\emph default
+) should be used in interrupt
+\begin_inset LatexCommand \index{interrupt}
\end_inset
- and floating-point
-\begin_inset LatexCommand \index{Floating point support}
+
+\begin_inset LatexCommand \index{\_\_interrupt}
\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
- -
+ 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
/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+-data-loc
+\begin_inset LatexCommand \index{-\/-data-loc <Value>}
\end_inset
-
-\emph default
- option and the source file will need to be compiled using the
+ to specify the start address of the
\emph on
--
+data
+\emph default
+ and -
\begin_inset ERT
status Collapsed
/
\end_inset
--int-long-reent
+-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
-\begin_inset LatexCommand \index{-\/-int-long-reent}
+\layout Standard
-\end_inset
+By default the 8051 linker will place the stack after the last byte of (i)data
+ variables.
+ Option -
+\begin_inset ERT
+status Collapsed
- compiler option.
\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}
+\backslash
+/
+\end_inset
+
+-stack-loc
+\begin_inset LatexCommand \index{-\/-stack-loc <Value>}
\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
+ 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
- critical
+idata
\emph default
- if all parameters are passed in registers.
-\newline
+) you can place the stack on it.
+ You may also need to use -
+\begin_inset ERT
+status Collapsed
-\newline
-Also see section
-\begin_inset LatexCommand \ref{sub:Overlaying}
+\layout Standard
+\backslash
+/
\end_inset
-\SpecialChar ~
-about Overlaying and section
-\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
+-xdata-loc
+\begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
\end_inset
-\SpecialChar ~
-about Functions using private register banks.
-\layout Subsection
+ to set the start address of the external RAM (
+\emph on
+xdata
+\emph default
+) and -
+\begin_inset ERT
+status Collapsed
-MCS51/DS390 Interrupt Service Routines
\layout Standard
-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
+\backslash
+/
+\end_inset
-\layout Standard
-\align center
+-xram-size
+\begin_inset LatexCommand \index{-\/-xram-size <Value>}
-\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
+\end_inset
+
+ to specify its size.
+ Same goes for the code memory, using -
+\begin_inset ERT
+status Collapsed
\layout Standard
-Interrupt #
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-code-loc
+\begin_inset LatexCommand \index{-\/-code-loc <Value>}
-Description
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+ and -
+\begin_inset ERT
+status Collapsed
\layout Standard
-Vector Address
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-code-size
+\begin_inset LatexCommand \index{-\/-code-size <Value>}
-0
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+.
+ If in doubt, don't specify any options and see if the resulting memory
+ layout is appropriate, then you can adjust it.
\layout Standard
+\added_space_bottom bigskip
+The linker generates two files with memory allocation information.
+ The first, with extension .map
+\begin_inset LatexCommand \index{<file>.map}
-External 0
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ shows all the variables and segments.
+ The second with extension .mem
+\begin_inset LatexCommand \index{<file>.mem}
-0x0003
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ 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{Z80!Storage class}
-1
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ Language Extensions
+\layout Subsubsection
+
+sfr
+\begin_inset LatexCommand \index{sfr}
-Timer 0
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-0x000B
+\begin_inset LatexCommand \index{\_\_sfr}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ (in/out to 8-bit addresses)
\layout Standard
-2
+The Z80
+\begin_inset LatexCommand \index{Z80}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ 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)}
-External 1
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-0x0013
+\begin_inset LatexCommand \index{Z80!I/O memory}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-3
+\begin_inset LatexCommand \index{Z180!I/O memory}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ is accessed with special instructions, e.g.:
+\layout Verse
-Timer 1
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+sfr at 0x78 IoPort;\SpecialChar ~
+\SpecialChar ~
+/* define a var in I/O space at 78h called IoPort */
+
\layout Standard
-0x001B
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
-\layout Standard
-4
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+3E 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ld a,#0x01
+\newline
+D3 78\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out (_IoPort),a
+\layout Subsubsection
-\layout Standard
+banked sfr
+\begin_inset LatexCommand \index{sfr}
-Serial
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-0x0023
+\begin_inset LatexCommand \index{\_\_sfr}
+
\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ (in/out to 16-bit addresses)
\layout Standard
-5
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The keyword
+\emph on
+banked
+\emph default
+ is used to support 16 bit addresses in I/O memory e.g.:
+\layout Verse
-\layout Standard
-Timer 2 (8052)
+\family typewriter
+sfr banked at
+\begin_inset LatexCommand \index{at}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-0x002B
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+\begin_inset LatexCommand \index{\_\_at}
\end_inset
+ 0x123 IoPort;
+\layout Standard
+
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
-\newline
-\layout Standard
+\family typewriter
+01 23 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ld bc,#_IoPort
+\newline
+3E 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ld a,#0x01
+\newline
+ED 79\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out (c),a
+\layout Subsubsection
-If the interrupt service routine is defined without
-\emph on
-using
-\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
+sfr
+\begin_inset LatexCommand \index{sfr}
\end_inset
-\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
+\begin_inset LatexCommand \index{\_\_sfr}
\end_inset
+ (in0/out0 to 8 bit addresses on Z180
+\begin_inset LatexCommand \index{Z180}
-\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
+\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
- & 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
+/HD64180
+\begin_inset LatexCommand \index{HD64180 (see Z180)}
+
+\end_inset
-HC08 Interrupt Service Routines
+)
\layout Standard
+\added_space_bottom bigskip
+The compiler option -
+\begin_inset ERT
+status Collapsed
-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}
+\layout Standard
+\backslash
+/
\end_inset
- for details on customizing startup.
-\layout Subsection
-
-Z80 Interrupt Service Routines
-\layout Standard
+-portmode
+\begin_inset LatexCommand \index{Z180!Options!-\/-portmode}
-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
+\end_inset
-By default, SDCC generates code for a maskable interrupt, which uses an
- RETI instruction to return from the interrupt.
- To write an interrupt handler for the non-maskable interrupt, which needs
- an RETN instruction instead, add the
-\emph on
-critical
-\emph default
- keyword:
-\layout Verse
+=180 (80) and a compiler #pragma\SpecialChar ~
+portmode
+\begin_inset LatexCommand \index{Z180!Pragmas!\#pragma portmode}
+\end_inset
+=z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
+ns
\family typewriter
-void nmi_isr (void) critical interrupt
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
-\layout Section
-
-Enabling and Disabling Interrupts
+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
-Critical Functions and Critical Statements
-\layout Standard
+HC08 Storage Class
+\begin_inset LatexCommand \index{HC08!Storage class}
-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
+
+ Language Extensions
+\layout Subsubsection
+
+data
+\begin_inset LatexCommand \index{data (hc08 storage class)}
\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}
+
+\begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
\end_inset
- for each call.
-\layout Verse
+
+\layout Standard
+The data storage class declares a variable that resides in the first 256
+ bytes of memory (the direct page).
+ The HC08
+\begin_inset LatexCommand \index{HC08}
-\family typewriter
-int foo () critical
-\begin_inset LatexCommand \index{critical}
+\end_inset
+
+ is most efficient at accessing variables (especially pointers) stored here.
+\layout Subsubsection
+
+xdata
+\begin_inset LatexCommand \index{xdata (hc08 storage class)}
\end_inset
-\begin_inset LatexCommand \index{\_\_critical}
+\begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
\end_inset
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
+\layout Standard
+\added_space_bottom bigskip
+The xdata storage class declares a variable that can reside anywhere in
+ memory.
+ This is the default if no storage class is specified.
-\newline
-}
+\layout Section
+
+Absolute Addressing
+\begin_inset LatexCommand \index{Absolute addressing}
+
+\end_inset
+
+
\layout Standard
-The critical attribute maybe used with other attributes like
+Data items can be assigned an absolute address with the
\emph on
-reentrant.
+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
-\newline
-The keyword
+
+\family typewriter
+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
+
+or, better conforming to ISO/IEC 9899 C:
+\layout Verse
+
+
+\family typewriter
+__xdata __at (0x7ffe) unsigned int chksum;
+\layout Standard
+
+In the above example the variable chksum will be located at 0x7ffe and 0x7fff
+ of the external ram.
+ The compiler does
\emph on
-critical
+not
\emph default
- may also be used to disable interrupts more locally:
+ reserve any space for variables declared in this way
+\begin_inset Marginal
+collapsed true
+
+\layout Standard
+
+
+\series bold
+\SpecialChar ~
+!
+\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
+
+
+\series bold
+\SpecialChar ~
+!
+\end_inset
+
+
+\emph default
+ initialized
+\begin_inset LatexCommand \index{Variable initialization}
+
+\end_inset
+
+.
+\layout Standard
+
+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
-critical{ i++; }
-\layout Standard
+volatile
+\begin_inset LatexCommand \index{volatile}
-More than one statement could have been included in the block.
-\layout Subsection
+\end_inset
-Enabling and Disabling Interrupts directly
+ __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
-Interrupts
-\begin_inset LatexCommand \index{interrupt}
+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
- can also be disabled and enabled directly (8051):
+
+\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
-EA = 0;\SpecialChar ~
-\SpecialChar ~
+__bit
+\begin_inset LatexCommand \index{bit}
+
+\end_inset
+
+ __at
+\begin_inset LatexCommand \index{at}
+
+\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 your routine using:
+\layout Verse
+
+
+\family typewriter
+extern volatile
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+ __bit MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* master out, slave in */
+\newline
+extern volatile __bit MISO;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* master in, slave out */
+\newline
+extern volatile __bit MCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* master clock */
+\newline
+
+\newline
+/* Input and Output of a byte on a 3-wire serial bus.
+\newline
\SpecialChar ~
-or:\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 ~
-EA_SAVE = EA;
-\layout Verse
-
-
-\family typewriter
-...\SpecialChar ~
\SpecialChar ~
+do {
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+MOSI = out_byte & 0x80;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+out_byte <<= 1;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+MCLK = 1;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-EA = 0;
-\layout Verse
-
-
-\family typewriter
-EA = 1;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* _asm nop _endasm; */\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* for slow peripherals */
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+if(MISO)
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-\layout Verse
-
-
-\family typewriter
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+out_byte += 1;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+MCLK = 0;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+} while(--i);
+\newline
\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 ~
-EA = EA_SAVE;
+/* I/O port 0, bit 2 */
\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):
+Similarly, for the second hardware you would use
\layout Verse
\family typewriter
-#define CLI _asm
-\begin_inset LatexCommand \index{\_asm}
+__bit __at (0x83) MOSI;\SpecialChar ~
+\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 ~
-cli\SpecialChar ~
\SpecialChar ~
-_endasm
-\begin_inset LatexCommand \index{\_endasm}
+/* I/O port 1, bit 2 */
+\layout Standard
+\added_space_bottom bigskip
+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}
\end_inset
-;
-\layout Verse
+\begin_inset LatexCommand \index{function parameter}
-\family typewriter
-#define SEI _asm\SpecialChar ~
-\SpecialChar ~
-sei\SpecialChar ~
-\SpecialChar ~
-_endasm;
-\layout Verse
+\end_inset
+ & Local Variables
+\begin_inset LatexCommand \index{local variables}
-\family typewriter
-...
-\layout Standard
+\end_inset
-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}
+
+\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
\end_inset
-\emph default
- register.
-
\layout Standard
-Usually the time during which interrupts are disabled should be kept as
- short as possible.
- This minimizes both
+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
-interrupt latency
+static
+\begin_inset LatexCommand \index{static}
+
+\end_inset
+
+
\emph default
+ so by default functions are non-reentrant
+\begin_inset LatexCommand \index{reentrant}
-\begin_inset LatexCommand \index{interrupt latency}
+\end_inset
+
+.
+
+\newline
+
+\newline
+They can be placed on the stack
+\begin_inset LatexCommand \index{stack}
\end_inset
- (the time between the occurrence of the interrupt and the execution of
- the first code in the interrupt routine) and
+ by using the
\emph on
-interrupt jitter
-\emph default
+ -
+\begin_inset ERT
+status Collapsed
-\begin_inset LatexCommand \index{interrupt jitter}
+\layout Standard
+\backslash
+/
\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
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
-You can reenable interrupts within an interrupt routine and on some architecture
-s you can make use of two (or more) levels of
+\end_inset
+
+
+\emph default
+ option, by using
\emph on
-interrupt priorities
+#pragma\SpecialChar ~
+stackauto
\emph default
-\begin_inset LatexCommand \index{interrupt priority}
+\begin_inset LatexCommand \index{\#pragma stackauto}
\end_inset
-.
- 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}
+ or by using the
+\emph on
+reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
- and don't add complexity unless you have to.
-
-\layout Subsection
-Semaphore
-\begin_inset LatexCommand \index{semaphore}
+\emph default
+ keyword in the function declaration, e.g.:
+\layout Verse
-\end_inset
- locking (mcs51/ds390)
+\family typewriter
+unsigned char foo(char i) __reentrant
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
\layout Standard
-Some architectures (mcs51/ds390) have an atomic
-\begin_inset LatexCommand \index{atomic}
+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
- bit test and
-\emph on
-
+-stack-auto
\emph default
-clear
+ 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
-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}
+ mean that the function is register bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
\end_inset
- 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}
+ independent.
+\newline
+
+\newline
+Local variables
+\begin_inset LatexCommand \index{local variables}
\end_inset
- don't have to be disabled for the locking operation.
-
-\layout Standard
+ can be assigned storage classes and absolute
+\begin_inset LatexCommand \index{Absolute addressing}
-SDCC generates this instruction if the source follows this pattern:
+\end_inset
+
+ addresses, e.g.:
\layout Verse
\family typewriter
-volatile
-\begin_inset LatexCommand \index{volatile}
-
-\end_inset
-
- bit resource_is_free;
-\newline
-
+unsigned char foo()
\newline
-if (resource_is_free)
+{
\newline
\SpecialChar ~
\SpecialChar ~
-{
+\SpecialChar ~
+\SpecialChar ~
+__xdata unsigned char i;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-resource_is_free=0;
+__bit bvar;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
+__data __at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ (0x31) unsigned char j;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-resource_is_free=1;
+...
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-}
+}
\layout Standard
-Note, mcs51 and ds390 support only an atomic
-\begin_inset LatexCommand \index{atomic}
-
-\end_inset
-
- bit test and
+In the above example the variable
\emph on
-clear
+i
\emph default
- instruction (as opposed to atomic bit test and
+ will be allocated in the external ram,
\emph on
-set).
-\layout Section
+bvar
+\emph default
+ in bit addressable space and
+\emph on
+ j
+\emph default
+ in internal ram.
+ When compiled with
+\emph on
+-
+\begin_inset ERT
+status Collapsed
-Functions using private register banks
-\begin_inset LatexCommand \label{sub:Functions-using-private-banks}
+\layout Standard
+\backslash
+/
\end_inset
- (mcs51/ds390)
+-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
-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)}
+Parameters
+\begin_inset LatexCommand \index{function parameter}
\end_inset
-
-\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
+ 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
-\emph default
- attribute (which tells the compiler to use a register bank
-\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
+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
+\begin_inset LatexCommand \index{stack}
\end_inset
- other than the default bank zero).
- It should only be applied to
-\emph on
-interrupt
-\begin_inset LatexCommand \index{interrupt}
-
-\end_inset
+ as a single byte just like the normal registers.
+\layout Section
+Overlaying
+\begin_inset LatexCommand \label{sub:Overlaying}
-\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
+\end_inset
-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
-\layout Standard
+\begin_inset LatexCommand \index{Overlaying}
-possible exception: if a function is called ONLY from 'interrupt' functions
- using a particular bank, it can be declared with the same 'using' attribute
- as the calling 'interrupt' functions.
- For instance, if you have several ISRs using bank one, and all of them
- call memcpy(), it might make sense to create a specialized version of memcpy()
- 'using 1', since this would prevent the ISR from having to save bank zero
- to the stack on entry and switch to bank zero before calling the function
\end_inset
-).
-\newline
-\emph on
-(pending: I don't think this has been done yet)
\layout Standard
-An
-\emph on
-interrupt
-\emph default
- function using a non-zero bank will assume that it can trash that register
- bank, and will not save it.
- Since high-priority interrupts
-\begin_inset LatexCommand \index{interrupts}
+For non-reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
-
-\begin_inset LatexCommand \index{interrupt priority}
+ 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
- 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
+ of a function will be allocated to an overlayable segment if the function
+ has
\emph on
-used
-\emph default
- by both a high priority and a low priority ISR.
- This is probably most easily done by having all high priority ISRs use
- one bank and all low priority ISRs use another.
- If you have an ISR which can change priority at runtime, you're on your
- own: I suggest using the default bank zero and taking the small performance
- hit.
-\layout Standard
-
-It is most efficient if your ISR calls no other functions.
- If your ISR must call other functions, it is most efficient if those functions
- use the same bank as the ISR (see note 1 below); the next best is if the
- called functions use bank zero.
- It is very inefficient to call a function using a different, non-zero bank
- from an ISR.
-
-\layout Section
-
-Startup Code
-\begin_inset LatexCommand \label{sub:Startup-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.
-\begin_inset LatexCommand \index{Startup code}
+\emph default
+ If an explicit storage class
+\begin_inset LatexCommand \index{Storage class}
\end_inset
-
-\layout Subsection
-
-MCS51/DS390 Startup Code
+ is specified for a local variable, it will NOT be overlayed.
\layout Standard
-The compiler inserts a call to the C routine
-\emph on
-_sdcc_external_startup()
-\begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
+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
-\end_inset
+\layout Standard
\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}
-
-\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.
- Otherwise 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
-\begin_inset LatexCommand \index{Variable initialization}
-
+!
\end_inset
-.
- On some mcs51 variants xdata
-\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+ should be preceded by a #pragma\SpecialChar ~
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
\end_inset
- 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
--
-\begin_inset ERT
-status Collapsed
+ 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
-\backslash
-/
+Parameters and local variables of functions that contain 16 or 32 bit multiplica
+tion
+\begin_inset LatexCommand \index{Multiplication}
+
\end_inset
--iram-size
-\begin_inset LatexCommand \index{-\/-iram-size <Value>}
+ or division
+\begin_inset LatexCommand \index{Division}
\end_inset
-n
-\emph default
- is used.
- (recommended for Chipcon CC1010).
-\layout Standard
+ will NOT be overlayed since these are implemented using external functions,
+ e.g.:
+\layout Verse
-See also the compiler option
-\emph on
--
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\family typewriter
+#pragma save
+\newline
+#pragma nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
-\backslash
-/
\end_inset
--no-xinit
+
+\newline
+void set_error(unsigned char errcd)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+P3 = errcd;
+\newline
+}
+\newline
+#pragma restore
+\newline
+
+\newline
+void some_isr () __interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ (2)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+set_error(10);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Standard
+\added_space_bottom bigskip
+In the above example the parameter
+\emph on
+errcd
\emph default
--
+ for the function
\emph on
-opt
+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
-\begin_inset LatexCommand \index{-\/-no-xinit-opt}
+Interrupt Service Routines
+\begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
\end_inset
- and section
-\begin_inset LatexCommand \ref{sub:MCS51-variants}
-
-\end_inset
-\SpecialChar ~
-about MCS51-variants.
\layout Subsection
-HC08 Startup Code
+General Information
\layout Standard
-The HC08 startup code follows the same scheme as the MCS51 startup code.
-\layout Subsection
+SDCC allows
+\emph on
+i
+\emph default
+nterrupt
+\emph on
+s
+\emph default
+ervice
+\emph on
+r
+\emph default
+outines to be coded in C, with some extended keywords.
+\layout Verse
-Z80 Startup Code
+
+\family typewriter
+void timer_isr (void) __interrupt (1) __using (1)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
\layout Standard
-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
+The optional number following the
\emph on
--
-\series bold
-\emph default
+interrupt
+\begin_inset LatexCommand \index{interrupt}
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
-\backslash
-/
+\begin_inset LatexCommand \index{\_\_interrupt}
+
\end_inset
-\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.
+ 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
--no-std-crt0
+main
\emph default
-
-\begin_inset LatexCommand \index{-\/-no-std-crt0}
+.
+ The optional (8051 specific) keyword
+\emph on
+using
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
\end_inset
- and provide your own crt0.o.
-
-\layout Section
-Inline Assembler Code
-\begin_inset LatexCommand \index{Assembler routines}
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
\end_inset
-\layout Subsection
+\emph default
+ can be used to tell the compiler to use the specified register bank when
+ generating code for this function.
+
+\newline
+Interrupt service routines open the door for some very interesting bugs:
+\layout Subsubsection
-A Step by Step Introduction
-\begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
-\end_inset
+\begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-volatile}
+\end_inset
+Common interrupt pitfall: variable not declared
+\emph on
+volatile
\layout Standard
-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
-
+If an interrupt service routine changes variables which are accessed by
+ other functions these variables have to be declared
+\emph on
+volatile
+\emph default
-\family typewriter
-\size footnotesize
-unsigned char far
-\begin_inset LatexCommand \index{far (storage class)}
+\begin_inset LatexCommand \index{volatile}
\end_inset
-
-\begin_inset LatexCommand \index{\_\_far (storage class)}
+.
+ See
+\begin_inset LatexCommand \url{http://en.wikipedia.org/wiki/Volatile_variable}
\end_inset
- at
-\begin_inset LatexCommand \index{at}
-
-\end_inset
+ .
+\layout Subsubsection
-\begin_inset LatexCommand \index{\_\_at}
+\begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-atomic}
\end_inset
- 0x7f00 buf[0x100];
-\begin_inset LatexCommand \index{Aligned array}
+Common interrupt pitfall:
+\emph on
+non-atomic access
+\layout Standard
+
+If the access to these variables is not
+\emph on
+atomic
+\begin_inset LatexCommand \index{atomic}
\end_inset
+\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.
+
\newline
-unsigned char head,tail;
-\newline
+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
-\newline
-void to_buffer( unsigned char c )
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-if( head != tail-1 )
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-buf[ head++ ] = c;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* access to a 256 byte aligned array */
-\newline
-}
-\layout Standard
-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()
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x80;
\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
-_asm
+ is not atomic if
+\family typewriter
+flags
+\family default
+ resides in xdata.
+ Setting
\begin_inset Quotes srd
\end_inset
- and
+
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x40;
+\family default
+
\begin_inset Quotes sld
\end_inset
-_endasm;
-\begin_inset Quotes srd
+ from within an interrupt routine might get lost if the interrupt occurs
+ at the wrong time.
+
+\begin_inset Quotes sld
\end_inset
- to the beginning and the end of the function body:
-\layout Verse
-
\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}
+counter\SpecialChar ~
++=\SpecialChar ~
+8;
+\family default
+\begin_inset Quotes srd
\end_inset
+ is not atomic on the 8051 even if
+\family typewriter
+counter
+\family default
+ is located in data memory.
+\newline
+Bugs like these are hard to reproduce and can cause a lot of trouble.
+
+\layout Subsubsection
+
-\begin_inset LatexCommand \index{\_\_asm}
+\begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-stack-overflow}
\end_inset
+Common interrupt pitfall:
+\emph on
+stack overflow
+\layout Standard
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov\SpecialChar ~
-\SpecialChar ~
-r2,dpl
-\newline
-;buffer.c if( head != 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}
+The return address and the registers used in the interrupt service routine
+ are saved on the stack
+\begin_inset LatexCommand \index{stack}
\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
-\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}
+\begin_inset LatexCommand \index{stack overflow}
\end_inset
+ is most likely to happen if the interrupt occurs during the
+\begin_inset Quotes sld
+\end_inset
-\begin_inset LatexCommand \index{\_\_endasm}
-
+deepest
+\begin_inset Quotes srd
\end_inset
-;
-\newline
-}
-\layout Standard
+ subroutine when the stack is already in use for f.e.
+ many return addresses.
+\layout Subsubsection
-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
+\begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-reentrant}
-\family typewriter
-\size footnotesize
-unsigned char far at 0x7f00 buf[0x100];
-\newline
-unsigned char head,tail;
-\newline
-#define USE_ASSEMBLY (1)
-\newline
+\end_inset
-\newline
-#if !USE_ASSEMBLY
-\newline
+Common interrupt pitfall:
+\emph on
+use of non-reentrant functions
+\layout Standard
-\newline
-void to_buffer( unsigned char c )
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-if( head != tail-1 )
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-buf[ head++ ] = c;
-\newline
-}
-\newline
+A special note here, int (16 bit) and long (32 bit) integer division
+\begin_inset LatexCommand \index{Division}
-\newline
-#else
-\newline
+\end_inset
-\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}
+, multiplication
+\begin_inset LatexCommand \index{Multiplication}
\end_inset
-
-\begin_inset LatexCommand \index{\_\_asm}
+ & modulus
+\begin_inset LatexCommand \index{Modulus}
\end_inset
-
-\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 != 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
-
-
-\begin_inset LatexCommand \index{\_\_endasm}
+ and floating-point
+\begin_inset LatexCommand \index{Floating point support}
\end_inset
-;
-\newline
-}
-\newline
-#endif
-\layout Standard
-
-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
+ operations are implemented using external support routines.
+ 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
\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)}
-
+\backslash
+/
\end_inset
-
-\begin_inset LatexCommand \index{Assembler documentation}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
-\end_inset
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
-.
- The compiler does not do any validation of the code within the
-\family typewriter
-_asm
-\begin_inset LatexCommand \index{\_asm}
+\layout Standard
+\backslash
+/
\end_inset
+-int-long-reent
+\emph default
-\begin_inset LatexCommand \index{\_\_asm}
+\begin_inset LatexCommand \index{-\/-int-long-reent}
\end_inset
- ...
- _endasm
-\size footnotesize
-
-\begin_inset LatexCommand \index{\_endasm}
+ compiler option.
+
+\newline
+Note, the type promotion
+\begin_inset LatexCommand \index{type promotion}
\end_inset
+ required by ANSI C can cause 16 bit routines to be used
+\begin_inset Marginal
+collapsed true
-\begin_inset LatexCommand \index{\_\_endasm}
+\layout Standard
-\end_inset
+\series bold
+\SpecialChar ~
+!
+\end_inset
-\size default
-;
+ without the programmer being aware of it.
+ See f.e.
+ the cast
+\family typewriter
+(unsigned char)(tail-1)
\family default
- keyword pair.
- Specifically it will not know which registers are used and thus register
- pushing/popping
-\begin_inset LatexCommand \index{push/pop}
+ within the if clause in section
+\begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
\end_inset
- has to be done manually.
-
-\layout Standard
-
-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
+\added_space_bottom bigskip
+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}
-\backslash
-/
\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
-peep-asm
-\begin_inset LatexCommand \index{-\/-peep-asm}
+ critical
+\emph default
+ if all parameters are passed in registers.
+\newline
+ Also see section
+\begin_inset LatexCommand \ref{sub:Overlaying}
\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}
+\SpecialChar ~
+about Overlaying and section
+\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
\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.
+\SpecialChar ~
+about Functions using private register banks.
\layout Subsection
-Naked Functions
-\begin_inset LatexCommand \label{sub:Naked-Functions}
+MCS51/DS390 Interrupt Service Routines
+\layout Standard
-\end_inset
+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
+\layout Standard
+\align center
-\begin_inset LatexCommand \index{Naked functions}
+\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
-\end_inset
+\layout Standard
+Interrupt #
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-A special keyword may be associated with a function declaring it as
-\emph on
-_naked
-\begin_inset LatexCommand \index{\_naked}
-
+Description
\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{\_\_naked}
-
+Vector Address
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-
-\emph default
-The
-\emph on
-_naked
-\emph default
- function modifier attribute prevents the compiler from generating prologue
-\begin_inset LatexCommand \index{function prologue}
+\layout Standard
+0
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- and epilogue
-\begin_inset LatexCommand \index{function epilogue}
+\layout Standard
+External 0
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- 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
+\layout Standard
+0x0003
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family typewriter
-volatile
-\begin_inset LatexCommand \index{volatile}
+\layout Standard
+1
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- data unsigned char counter;
-\newline
-
-\newline
-void simpleInterrupt(void) interrupt
-\begin_inset LatexCommand \index{interrupt}
+\layout Standard
+Timer 0
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{\_\_interrupt}
-
+0x000b
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- 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}
+\layout Standard
+2
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{\_\_asm}
-
+External 1
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\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}
-
+0x0013
\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{\_\_endasm}
-
+3
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-;
-\newline
-}
\layout Standard
-For an 8051 target, the generated simpleInterrupt looks like:
-\layout Verse
+Timer 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\family typewriter
-_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
+0x001b
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-whereas nakedInterrupt looks like:
-\layout Verse
+\layout Standard
+4
+\end_inset
+</cell>
+<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
-The related directive #pragma exclude
-\begin_inset LatexCommand \index{\#pragma exclude}
-
+Serial
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- allows a more fine grained control over pushing & popping
-\begin_inset LatexCommand \index{push/pop}
+\layout Standard
+0x0023
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- the registers.
\layout Standard
-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
+5
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Use of Labels within Inline Assembler
\layout Standard
-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
-
+Timer 2 (8052)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\family typewriter
-_asm
-\begin_inset LatexCommand \index{\_asm}
+\layout Standard
+0x002b
\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{\_\_asm}
+...
+\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
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov\SpecialChar ~
+\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
+\added_space_bottom bigskip
+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
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+.
+ This scheme is recommended for larger interrupt service routines.
+\layout Subsection
+
+HC08
+\begin_inset LatexCommand \index{HC08}
+
+\end_inset
+
+ Interrupt Service Routines
+\layout Standard
+\added_space_bottom bigskip
+Since the number of interrupts
+\begin_inset LatexCommand \index{HC08!interrupt}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{Z80}
+
+\end_inset
+
+ uses several different methods for determining the correct interrupt
+\begin_inset LatexCommand \index{Z80!interrupt}
+
+\end_inset
+
+ 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 ~
\SpecialChar ~
\SpecialChar ~
-b,#10
+...
+
\newline
-00001$:
+}
+\layout Standard
+\added_space_bottom bigskip
+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 ~
-djnz\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-b,00001$
+\SpecialChar ~
+...
+
\newline
-_endasm
-\begin_inset LatexCommand \index{\_endasm}
+}
+\layout Standard
-\end_inset
+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
-\begin_inset LatexCommand \index{\_\_endasm}
+\family typewriter
+__critical{ i++; }
+\layout Standard
-\end_inset
+More than one statement could have been included in the block.
+\layout Subsection
- ;
+Enabling and Disabling Interrupts directly
\layout Standard
-Inline assembler code cannot reference any C-Labels, however it can reference
- labels
-\begin_inset LatexCommand \index{Labels}
+Interrupts
+\begin_inset LatexCommand \index{interrupt}
\end_inset
- defined by the inline assembler, e.g.:
+ can also be disabled and enabled directly (8051):
\layout Verse
\family typewriter
-foo() {
-\newline
+EA = 0;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* some c code */
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_asm
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+or:\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-; some assembler code
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ljmp $0003
-\newline
\SpecialChar ~
+EA_SAVE = EA;
+\layout Verse
+
+
+\family typewriter
+...\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
-
-
-\begin_inset LatexCommand \index{\_\_endasm}
-
-\end_inset
-
- ;
-\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
-
-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
-
-
-\layout Standard
-
-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
-
-, B
-\begin_inset LatexCommand \index{B (mcs51, ds390 register)}
-
-\end_inset
-
-
-\emph default
-and
-\emph on
- ACC
-\begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
-
-\end_inset
-
-
-\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
-
-\backslash
-/
-\end_inset
-
--stack-auto is used) or in data / xdata memory (depending on the memory
- model).
-
-\layout Subsection
-
-Assembler Routine (non-reentrant)
-\layout Standard
-
-In the following example
-\begin_inset LatexCommand \index{reentrant}
-
-\end_inset
-
-
-\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}
-
-\end_inset
-
-.
-\layout Verse
-
-
-\family typewriter
-extern int asm_func(unsigned char, unsigned char);
-\newline
-
-\newline
-int c_func (unsigned char i, unsigned char j)
-\newline
-{
-\newline
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-return asm_func(i,j);
-\newline
-}
-\newline
-
-\newline
-int main()
-\newline
-{
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-return c_func(10,9);
-\newline
-}
-\layout Standard
-
-The corresponding assembler function is:
+EA = 0;
\layout Verse
\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 ~
+EA = 1;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-.area CSEG
-\newline
-_asm_func:
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-a,dpl
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add\SpecialChar ~
+...
+\layout Verse
+
+
+\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-a,_asm_func_PARM_2
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-dpl,a
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-dph
-\begin_inset LatexCommand \index{DPTR, DPH, DPL}
-
-\end_inset
-
-,#0x00
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ret
+EA = EA_SAVE;
\layout Standard
-Note here that the return values
-\begin_inset LatexCommand \index{return value}
+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
- 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
+ (HC08
+\begin_inset LatexCommand \index{HC08!interrupt}
-dpl
-\begin_inset Quotes erd
\end_inset
- for a one byte parameter,
-\begin_inset Quotes eld
-\end_inset
+):
+\layout Verse
-dptr
-\begin_inset Quotes erd
-\end_inset
- for two bytes,
-\begin_inset Quotes eld
-\end_inset
+\family typewriter
+#define CLI _asm
+\begin_inset LatexCommand \index{\_asm}
-b,dptr
-\begin_inset Quotes erd
\end_inset
- for three bytes and
-\begin_inset Quotes eld
-\end_inset
+\SpecialChar ~
+\SpecialChar ~
+cli\SpecialChar ~
+\SpecialChar ~
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
-acc,b,dptr
-\begin_inset Quotes erd
\end_inset
- 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
+;
+\layout Verse
-\newline
-\family sans
-\series bold
-asx8051 -losg asmfunc.asm
-\newline
+\family typewriter
+#define SEI _asm\SpecialChar ~
+\SpecialChar ~
+sei\SpecialChar ~
+\SpecialChar ~
+_endasm;
+\layout Verse
-\newline
-\family default
-\series default
-Then compile and link the assembler routine to the C source file with the
- following command:
-\newline
+\family typewriter
+...
+\layout Standard
-\newline
+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}
-\family sans
-\series bold
-sdcc cfunc.c asmfunc.rel
-\layout Subsection
+\end_inset
-Assembler Routine (reentrant)
+
+\emph default
+ register.
+
\layout Standard
-In this case
-\begin_inset LatexCommand \index{reentrant}
+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
-\begin_inset LatexCommand \index{Assembler routines (reentrant)}
+\begin_inset LatexCommand \index{interrupt jitter}
\end_inset
- the second parameter
-\begin_inset LatexCommand \index{function parameter}
+ (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
+
+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
- 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
+.
+ 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}
+\end_inset
-\family typewriter
-extern int asm_func(unsigned char, unsigned char);
-\newline
+ and don't add complexity unless you have to.
+
+\layout Subsection
-\newline
-int c_func (unsigned char i, unsigned char j) reentrant
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return asm_func(i,j);
-\newline
-}
-\newline
+Semaphore
+\begin_inset LatexCommand \index{semaphore}
-\newline
-int main()
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return c_func(10,9);
-\newline
-}
+\end_inset
+
+ locking (mcs51/ds390)
\layout Standard
-The corresponding assembler routine is:
+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
+
+ 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}
+
+\end_inset
+
+ don't have to be disabled for the locking operation.
+
+\layout Standard
+
+SDCC generates this instruction if the source follows this pattern:
\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
+volatile
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+ bit resource_is_free;
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov a,@r0
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-add a,r2 ;?
+if (resource_is_free)
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov dpl,a
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov dph,#0x00
+resource_is_free=0;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov sp,_bp
+...
+
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-pop _bp
+resource_is_free=1;
\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)}
+Note, mcs51 and ds390 support only an atomic
+\begin_inset LatexCommand \index{atomic}
\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
+ bit test and
+\emph on
+clear
+\emph default
+ instruction (as opposed to atomic bit test and
+\emph on
+set).
+\layout Section
-\layout Standard
-\align center
+Functions using private register banks
+\begin_inset LatexCommand \label{sub:Functions-using-private-banks}
-\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
+\end_inset
+ (mcs51/ds390)
\layout Standard
+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)}
-\series bold
-Function
\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{\_\_using (mcs51, ds390 register bank)}
-\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
-_mulint.c
+\emph default
+ attribute (which tells the compiler to use a register bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ other than the default bank zero).
+ It should only be applied to
+\emph on
+interrupt
+\begin_inset LatexCommand \index{interrupt}
-16 bit multiplication
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+\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
-_divsint.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+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
\layout Standard
- signed 16 bit division (calls _divuint)
+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
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+).
+\newline
+
+\emph on
+(pending: Note, nowadays the
+\emph default
+using
+\emph on
+ attribute has an effect on
+\emph default
+
+\emph on
+the generated code for a
+\emph default
+non-interrupt
+\emph on
+ function
+\emph default
+.
+\emph on
+)
\layout Standard
-_divuint.c
+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}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
- unsigned 16 bit division
+\begin_inset LatexCommand \index{interrupt priority}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ 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
+\added_space_bottom bigskip
+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
+
+Startup Code
+\begin_inset LatexCommand \label{sub:Startup-Code}
-_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)
+\begin_inset LatexCommand \index{Startup code}
+
\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 Subsection
+MCS51/DS390 Startup Code
\layout Standard
-unsigned 16 bit modulus
+The compiler inserts a call to the C routine
+\emph on
+_sdcc_external_startup()
+\begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
+
\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
+\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}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+ 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
+_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
+\begin_inset LatexCommand \index{Variable initialization}
-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
+.
+ On some mcs51 variants xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
-_divslong.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ memory has to be explicitly enabled before it can be accessed or if the
+ watchdog
+\begin_inset LatexCommand \index{watchdog}
- 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
+ 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
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-unsigned 32 division
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-iram-size
+\begin_inset LatexCommand \index{-\/-iram-size <Value>}
-_modslong.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+n
+\emph default
+ is used.
+ (recommended for Chipcon CC1010).
\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
+\added_space_bottom bigskip
+See also the compiler options
+\emph on
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-_modulong.c
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-no-xinit
+\emph default
+-
+\emph on
+opt
+\emph default
-unsigned 32 bit modulus
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+\begin_inset LatexCommand \index{-\/-no-xinit-opt}
\end_inset
-
-\newline
+,
+\emph on
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Since they are compiled as
-\emph on
-non-reentrant
+\backslash
+/
+\end_inset
+
+-main-return
\emph default
-\begin_inset LatexCommand \index{reentrant}
+\begin_inset LatexCommand \index{-\/-main-return}
\end_inset
-, interrupt
-\begin_inset LatexCommand \index{interrupt}
+and section
+\begin_inset LatexCommand \ref{sub:MCS51-variants}
\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
+\SpecialChar ~
+about MCS51-variants.
+\layout Subsection
+HC08 Startup Code
\layout Standard
+\added_space_bottom bigskip
+The HC08
+\begin_inset LatexCommand \index{HC08}
-\backslash
-/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+ startup code follows the same scheme as the MCS51 startup code.
+\layout Subsection
-\end_inset
+Z80 Startup Code
+\layout Standard
+\added_space_bottom bigskip
+On the Z80
+\begin_inset LatexCommand \index{Z80}
+\end_inset
-\emph default
- option, after which the source program will have to be compiled with
+ 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
-
+\series bold
+\emph default
+
\begin_inset ERT
status Collapsed
/
\end_inset
--int-long-reent
-\begin_inset LatexCommand \index{-\/-int-long-reent}
-\end_inset
+\series default
+\emph on
+-no-std-crt0
+\emph default
+
+\begin_inset LatexCommand \index{-\/-no-std-crt0}
+\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.
+ and provide your own crt0.o.
+
\layout Section
-Floating Point Support
-\begin_inset LatexCommand \index{Floating point support}
+Inline Assembler Code
+\begin_inset LatexCommand \index{Assembler routines}
\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 Subsection
-\layout Standard
-\align center
+A Step by Step Introduction
+\begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
-\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
+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
-\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
+\family typewriter
+\size footnotesize
+unsigned char __far
+\begin_inset LatexCommand \index{far (storage class)}
-Description
\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{\_\_far (storage class)}
-\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
+ __at
+\begin_inset LatexCommand \index{at}
-\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
+\begin_inset LatexCommand \index{\_\_at}
-\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
+(0x7f00) buf[0x100];
+\begin_inset LatexCommand \index{Aligned array}
-\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
+\newline
+unsigned char head, tail;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* if interrupts
+\begin_inset LatexCommand \index{interrupt}
-\layout Standard
+\end_inset
+ are involved see
+\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 ~
+section
+\begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
-\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
+ about
+\series bold
+ volatile
+\series default
+ */
+\newline
+\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}
-\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
+\begin_inset LatexCommand \index{type promotion}
-\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
+
+ to integer */
+\begin_inset Marginal
+collapsed true
\layout Standard
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2uchar.c
+\series bold
+\SpecialChar ~
+!
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\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
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to unsigned char
+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
+_asm
+\begin_inset Quotes srd
+\end_inset
+ and
+\begin_inset Quotes sld
+\end_inset
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2char.c
+_endasm;
+\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
+ to the beginning and the end of the function body:
+\layout Verse
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to signed char
+\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}
+
\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{\_\_asm}
-\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
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+r2,dpl
+\newline
+;buffer.c if( head != (unsigned char)(tail-1) ) \SpecialChar ~
+/* cast
+\series bold
+needed
+\series default
+ to avoid promotion
+\begin_inset LatexCommand \index{promotion to signed int}
-\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{type promotion}
-\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
+ to integer */
+\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}
-\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
+\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}
-\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
+\begin_inset LatexCommand \index{\_\_endasm}
-\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
+;
+\newline
+}
\layout Standard
+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
-\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 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
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to signed long
-\end_inset
+\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
+
+
+\begin_inset LatexCommand \index{\_\_asm}
+
+\end_inset
+
+
+\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
+
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
+\end_inset
+
+;
+\newline
+}
+\newline
+#endif
+\layout Standard
+
+The inline assembler code can contain any valid code understood by the assembler
+, this includes any assembler directives and comment lines.
+ 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)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Assembler documentation}
+
+\end_inset
+
+ or online at
+\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html}
+
+\end_inset
+
+\SpecialChar ~
+.
+\layout Standard
+
+The compiler does not do any validation of the code within the
+\family typewriter
+_asm
+\begin_inset LatexCommand \index{\_asm}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_asm}
+
+\end_inset
+
+ ...
+ _endasm
+\size footnotesize
+
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
+\end_inset
+
+
+\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}
+
+\end_inset
+
+ has to be done manually.
+
+\layout Standard
+
+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
+
+\backslash
+/
+\end_inset
+
+-
+\emph on
+peep-asm
+\begin_inset LatexCommand \index{-\/-peep-asm}
+
+\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}
+
+\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
+
+Naked Functions
+\begin_inset LatexCommand \label{sub:Naked-Functions}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Naked functions}
+
+\end_inset
+
+
+\layout Standard
+
+A special keyword may be associated with a function declaring it as
+\emph on
+_naked
+\begin_inset LatexCommand \index{\_naked}
+
+\end_inset
+
+
+\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
+
+ and epilogue
+\begin_inset LatexCommand \index{function epilogue}
+
+\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
+
+
+\family typewriter
+volatile
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+ data unsigned char counter;
+\newline
+
+\newline
+void simpleInterrupt(void) __interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\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
+
+
+\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
+
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
+\end_inset
+
+;
+\newline
+}
+\layout Standard
+
+For an 8051 target, the generated simpleInterrupt looks like:
+\layout Verse
+
+
+\family typewriter
+Note, this is an
+\emph on
+outdated
+\emph default
+ example, recent versions of SDCC generate
+\newline
+the
+\emph on
+same
+\emph default
+ 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
+
+
+\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
+
+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
+
+ the registers.
+\layout Standard
+
+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
+
+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
+
+
+\family typewriter
+_asm
+\begin_inset LatexCommand \index{\_asm}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_asm}
+
+\end_inset
+
+
+\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
+
+ ;
+\layout Standard
+
+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
+
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
+\end_inset
+
+ ;
+\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
+
+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
+
+
+\layout Standard
+
+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
+
+, B
+\begin_inset LatexCommand \index{B (mcs51, ds390 register)}
+
+\end_inset
+
+
+\emph default
+and
+\emph on
+ ACC
+\begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
+
+\end_inset
+
+
+\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
+
+\backslash
+/
+\end_inset
+
+-stack-auto is used) or in data / xdata memory (depending on the memory
+ model).
+
+\layout Subsection
+
+Assembler Routine (non-reentrant)
+\layout Standard
+
+In the following example
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+
+\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}
+
+\end_inset
+
+.
+\layout Verse
+
+
+\family typewriter
+extern int asm_func(unsigned char, unsigned char);
+\newline
+
+\newline
+int c_func (unsigned char i, unsigned char j)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return asm_func(i,j);
+\newline
+}
+\newline
+
+\newline
+int main()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c_func(10,9);
+\newline
+}
+\layout Standard
+
+The corresponding assembler function is:
+\layout Verse
+
+
+\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}
+
+\end_inset
+
+,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
+\layout Standard
+
+Note here that the return values
+\begin_inset LatexCommand \index{return value}
+
+\end_inset
+
+ 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 a one byte parameter,
+\begin_inset Quotes eld
+\end_inset
+
+dptr
+\begin_inset Quotes erd
+\end_inset
+
+ for 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 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
+
+\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 Subsection
+
+Assembler Routine (reentrant)
+\layout Standard
+
+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
+\added_space_bottom bigskip
+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">
+\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
+
+_mulint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\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
+
+_divsint.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 division (calls _divuint)
+\end_inset
+</cell>
+</row>
+<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
+
+ 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
+
+\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">
\newline
\layout Standard
-
+\added_space_bottom bigskip
These support routines are developed in ANSI-C so there is room for space
and speed improvement
\begin_inset Foot
\layout Standard
-The floating point routines for the mcs51 are implemented in assembler
+These floating point routines (
+\emph on
+not
+\emph default
+ sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
+
\end_inset
.
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
on the command line.
Use
\emph on
--
+ -
\begin_inset ERT
status Collapsed
\family default
- and
+ (subset of printf using less than 270 bytes) and
\family typewriter
printf_fast()
\begin_inset LatexCommand \index{printf\_fast() (mcs51)}
\family default
- which should fit the requirements of many embedded systems (printf_fast()
- can be customized by unsetting #defines to
+ (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 Subsubsection
+
+<malloc.h>
+\begin_inset LatexCommand \index{malloc.h}
+
+\end_inset
+
+
+\layout Standard
+
+Before using dynamic
+\begin_inset LatexCommand \index{dynamic}
+
+\end_inset
+
+ memory allocation with SDCC, you have to provide heap
+\begin_inset LatexCommand \index{heap}
+
+\end_inset
+
+ space for malloc to allocate memory from
+\family typewriter
+.
+
+\family default
+You can acomplish this by including the following code into your source:
+\layout Verse
+
+
+\family typewriter
+#include <malloc.h>
+\begin_inset LatexCommand \index{malloc.h}
+
+\end_inset
+
+ /* calloc
+\begin_inset LatexCommand \index{calloc}
+
+\end_inset
+
+, malloc
+\begin_inset LatexCommand \index{malloc}
+
+\end_inset
+
+, realloc
+\begin_inset LatexCommand \index{realloc}
+
+\end_inset
+
+, and free
+\begin_inset LatexCommand \index{free}
+
+\end_inset
+
+ */
+\newline
+
+\newline
+#define HEAPSIZE 0x1000 /* Adjust depending on available memory */
+\newline
+unsigned char xdata myheap[HEAPSIZE]; /* The actual heap for dynamic memory
+ */
+\newline
+
+\newline
+void main (void)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* Your variable declarations come here*/
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+init_dynamic_memory((MEMHEADER xdata *)myheap, HEAPSIZE);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+ /* Rest of your code*/
+\newline
+}
+\newline
+
\layout Subsection
-Math functions (sin, pow, sqrt etc.)
+Math functions (sinf, powf, sqrtf etc.)
+\layout Subsubsection
+
+<math.h>
+\layout Standard
+
+See definitions in file <math.h>.
\layout Subsection
Other libraries
\SpecialChar ~
would certainly like to hear about it.
- Programmers coding for embedded systems are not especially famous for being
+\layout Standard
+\added_space_bottom bigskip
+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
Pragmas
+\begin_inset LatexCommand \label{sec:Pragmas}
+
+\end_inset
+
+
\begin_inset LatexCommand \index{Pragmas}
\end_inset
SDCC supports the following #pragma directives:
\layout Itemize
+
+\series bold
save
+\series default
+
\begin_inset LatexCommand \index{\#pragma save}
\end_inset
- - this will save all current options to the save/restore stack.
+ - this will save most current options to the save/restore stack.
See #pragma\SpecialChar ~
restore.
\layout Itemize
+
+\series bold
restore
+\series default
+
\begin_inset LatexCommand \index{\#pragma restore}
\end_inset
\layout Itemize
+
+\series bold
callee_saves
+\series default
+
\begin_inset LatexCommand \index{\#pragma callee\_saves}
\end_inset
is appended to the list of functions specified in the command line.
\layout Itemize
+
+\series bold
exclude
+\series default
+
\begin_inset LatexCommand \index{\#pragma exclude}
\end_inset
.
\layout Itemize
+
+\series bold
less_pedantic
+\series default
+
\begin_inset LatexCommand \index{\#pragma less\_pedantic}
\end_inset
your own now ;-(
\layout Itemize
-disable_warning <nnnn>
+
+\series bold
+disable_warning
+\series default
+ <nnnn>
\begin_inset LatexCommand \index{\#pragma disable\_warning}
\end_inset
- the compiler will not warn you anymore about warning number <nnnn>.
\layout Itemize
+
+\series bold
nogcse
+\series default
+
\begin_inset LatexCommand \index{\#pragma nogcse}
\end_inset
- will stop global common subexpression elimination.
\layout Itemize
+
+\series bold
noinduction
+\series default
+
\begin_inset LatexCommand \index{\#pragma noinduction}
\end_inset
- will stop loop induction optimizations.
\layout Itemize
+
+\series bold
noinvariant
+\series default
+
\begin_inset LatexCommand \index{\#pragma noinvariant}
\end_inset
.
\layout Itemize
+
+\series bold
noiv
+\series default
+
\begin_inset LatexCommand \index{\#pragma noiv}
\end_inset
about interrupts.
\layout Itemize
+
+\series bold
nojtbound
+\series default
+
\begin_inset LatexCommand \index{\#pragma nojtbound}
\end_inset
.
\layout Itemize
+
+\series bold
noloopreverse
+\series default
+
\begin_inset LatexCommand \index{\#pragma noloopreverse}
\end_inset
- Will not do loop reversal optimization
\layout Itemize
+
+\series bold
nooverlay
+\series default
+
\begin_inset LatexCommand \index{\#pragma nooverlay}
\end_inset
function.
\layout Itemize
+
+\series bold
stackauto
+\series default
+
\begin_inset LatexCommand \index{\#pragma stackauto}
\end_inset
Parameters and Local Variables.
\layout Itemize
-opt_code_speed
+
+\series bold
+opt_code_speed
+\series default
+
\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.
+ Currently this has little effect.
\layout Itemize
-opt_code_size
+
+\series bold
+opt_code_size
+\series default
+
\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.
+ Currently this has little effect.
\layout Itemize
-opt_code_balanced
+
+\series bold
+opt_code_balanced
+\series default
+
\begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
\end_inset
\layout Itemize
-std_sdcc89
+
+\series bold
+std_sdcc89
+\series default
+
\begin_inset LatexCommand \index{\#pragma std\_sdcc89}
\end_inset
with the standard (default).
\layout Itemize
-std_c89
+
+\series bold
+std_c89
+\series default
+
\begin_inset LatexCommand \index{\#pragma std\_c89}
\end_inset
standard.
\layout Itemize
-std_sdcc99
+
+\series bold
+std_sdcc99
+\series default
+
\begin_inset LatexCommand \index{\#pragma std\_sdcc99}
\end_inset
with the standard (incomplete support).
\layout Itemize
-std_c99
+
+\series bold
+std_c99
+\series default
+
\begin_inset LatexCommand \index{\#pragma std\_c99}
\end_inset
standard (incomplete support).
\layout Itemize
-codeseg <name>
+
+\series bold
+codeseg
+\series default
+ <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>
+
+\series bold
+constseg
+\series default
+ <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:
+The preprocessor SDCPP
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
+
+\end_inset
+
+ supports the following #pragma directives:
\layout Itemize
+
+\series bold
preproc_asm
+\series default
+
\begin_inset LatexCommand \index{\#pragma preproc\_asm}
\end_inset
(+ | -) - switch _asm _endasm block preprocessing on / off.
Default is on.
+ You use this prama to define multilines of assembly code.
+ This will prevent the preprocessor from changing the formating required
+ by assembly code.
+ Below is an example on how to use this pragma.
+\layout Verse
+
+
+\family typewriter
+#pragma preproc_asm -
+\begin_inset LatexCommand \index{\#pragma preproc\_asm}
+
+\end_inset
+
+
+\newline
+#define MYDELAY _asm
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+nop ;my assembly comment...
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+nop
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+nop
+\newline
+_endasm
+\newline
+#pragma preproc_asm +
+\newline
+
+\newline
+void foo (void)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ MYDELAY;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ...
+
+\newline
+}
+\newline
+
\layout Standard
The pragma's are intended to be used to turn-on or off certain optimizations
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.
+\newline
+
+\newline
+
+\newline
+
\layout Section
Defines Created by the Compiler
\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">
+<column alignment="left" valignment="top" leftline="true" width="3in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-this Symbol is always defined
+Always defined.
+ Since version 2.5.6 the version number as an int (ex.
+ 256)
\end_inset
</cell>
</row>
\end_inset
-, etc
+, etc.
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-depending on the model used (e.g.: -mds390
+depending on the model used (e.g.: -mds390)
\end_inset
</cell>
</row>
\family typewriter
-sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
+__sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family */
\layout Verse
\family typewriter
-sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
+__sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips */
\layout Verse
\family typewriter
-sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
+__sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips */
\layout Standard
For more exotic implementations further customizations may be needed.
Other Features available by SFR
\layout Standard
-
+\added_space_bottom bigskip
Some MCS51 variants offer features like Double DPTR
\begin_inset LatexCommand \index{DPTR}
DS400 port
\layout Standard
+\added_space_bottom bigskip
+The DS80C400
+\begin_inset LatexCommand \index{DS80C400}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{DS400}
-The DS80C400 microcontroller has a rich set of peripherals.
+\end_inset
+
+ 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
The Z80 and gbz80 port
\layout Standard
-SDCC can target both the Zilog
+SDCC can target both the Zilog Z80
\begin_inset LatexCommand \index{Z80}
\end_inset
variables and bitfield support is fine.
See mailing lists and forums about interrupt routines.
\layout Standard
-
+\added_space_bottom bigskip
As always, the code is the authoritative reference - see z80/ralloc.c and
z80/gen.c.
The stack
-\begin_inset LatexCommand \index{stack}
+\begin_inset LatexCommand \index{Z80!stack}
\end_inset
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}
+\begin_inset LatexCommand \index{Z80!return value}
\end_inset
The HC08 port
\layout Standard
-
+\added_space_bottom bigskip
The port to the Motorola HC08
\begin_inset LatexCommand \index{HC08}
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
-
+\pagebreak_top
The PIC14 port
\layout Standard
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.
+For generating a device include file
+\begin_inset LatexCommand \index{PIC14!Header files}
+
+\end_inset
+
+ 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}
+\begin_inset LatexCommand \index{PIC14!interrupt}
\end_inset
/
\end_inset
--debug-extra emit debug info in assembly output
+-debug-extra
+\begin_inset LatexCommand \index{PIC14!Options!-\/-debug-extra}
+
+\end_inset
+
+ emit debug info in assembly output
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--no-pcode-opt disable (slightly faulty) optimization on pCode
+-no-pcode-opt
+\begin_inset LatexCommand \index{PIC14!Options!-\/-no-pcode-opt}
+
+\end_inset
+
+ disable (slightly faulty) optimization on pCode
\layout Subsection
The library
\layout Standard
This warning can usually be ignored due to the very good compatibility amongst
- 14 bit PIC devices.
+ 14 bit PIC
+\begin_inset LatexCommand \index{PIC14}
+
+\end_inset
+
+ devices.
\layout Standard
You might also consider recompiling the library for your specific device
not
\series default
be initialized.
-\layout Section
+\family typewriter
+\size footnotesize
+
+\begin_inset Marginal
+collapsed true
+
+\layout Standard
+
+\series bold
+\SpecialChar ~
+!
+\end_inset
+
+
+\layout Section
+\pagebreak_top
The PIC16
\begin_inset LatexCommand \index{PIC16}
/
\end_inset
--callee-saves See -
+-callee-saves
+\begin_inset LatexCommand \index{PIC16!Options!-\/-callee-saves}
+
+\end_inset
+
+ See -
\begin_inset ERT
status Collapsed
/
\end_inset
--all-callee-saves All function arguments are passed on stack by default.
+-all-callee-saves
+\begin_inset LatexCommand \index{PIC16!Options!-\/-all-callee-saves}
+
+\end_inset
+
+ All function arguments are passed on stack by default.
\emph on
There is no need to specify this in the command line.
/
\end_inset
--fommit-frame-pointer Frame pointer will be omitted when the function uses
- no local variables.
+-fommit-frame-pointer
+\begin_inset LatexCommand \index{PIC16!Options!-\/-fommit-frame-pointer}
+
+\end_inset
+
+ Frame pointer will be omitted when the function uses no local variables.
\layout Subsection
Port Specific Options
/
\end_inset
--mplab-comp MPLAB compatibility option.
+-mplab-comp MPLAB
+\begin_inset LatexCommand \index{PIC16!MPLAB}
+
+\end_inset
+
+ compatibility option.
Currently only suppresses special gpasm directives.
\layout Subsubsection
Preprocessor Macros
\layout Standard
-PIC16 port defines the following preprocessor macros while translating a
- source.
+PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port defines the following preprocessor macros while translating a source.
\layout Standard
\align center
\layout Standard
-PIC16 port currently supports the following pragmas:
+PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ 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.
+stack
+\begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma stack}
+
+\end_inset
+
+ pragma stack
+\begin_inset LatexCommand \index{PIC16!stack}
+
+\end_inset
+
+ 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
\layout List
\labelwidthstring 00.00.0000
-code place a function symbol at static FLASH address
+code
+\begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma code}
+
+\end_inset
+
+ place a function symbol at static FLASH address
\layout LyX-Code
Example:
\layout Standard
-There is one main header file that can be included to the source files using
- the pic16 port.
+There is one main header file
+\begin_inset LatexCommand \index{PIC16!Header files}
+
+\end_inset
+
+ that can be included to the source files using the pic16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port.
That file is the
\series bold
pic18fregs.h
Libraries
\layout Standard
-The libraries that PIC16
+The libraries
+\begin_inset LatexCommand \index{PIC16!Libraries}
+
+\end_inset
+
+ that PIC16
\begin_inset LatexCommand \index{PIC16}
\end_inset
Stack
\layout Standard
-The stack implementation for the PIC16 port uses two indirect registers,
- FSR1 and FSR2.
+The stack
+\begin_inset LatexCommand \index{PIC16!stack}
+
+\end_inset
+
+ implementation for the PIC16 port uses two indirect registers, FSR1 and
+ FSR2.
\layout List
\labelwidthstring 00.00.0000
Functions
\layout Standard
-In addition to the standard SDCC function keywords, PIC16 port makes available
- two more:
+In addition to the standard SDCC function keywords, PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port makes available two more:
\layout List
\labelwidthstring 00.00.0000
-wparam Use the WREG to pass one byte of the first function argument.
+wparam
+\begin_inset LatexCommand \index{PIC16!wparam}
+
+\end_inset
+
+ 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.
\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.
+shadowregs
+\begin_inset LatexCommand \index{PIC16!shadowregs}
+
+\end_inset
+
+ 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
Interrupts
\layout Standard
-An interrupt servive routine (ISR) is declared using the
+An interrupt
+\begin_inset LatexCommand \index{PIC16!interrupt}
+
+\end_inset
+
+ service routine (ISR) is declared using the
\emph on
interrupt
\emph default
\layout Standard
-descrption
+description
\end_inset
</cell>
</row>
{
\layout LyX-Code
- stdout = STREAM_USER; /* this is not necessery, since stdout points
+ stdout = STREAM_USER; /* this is not necessary, since stdout points
\layout LyX-Code
* by default to STREAM_USER */
Stack size
\layout Standard
-The default stack size (that is 64 bytes) probably is enough for many programs.
+The default stack
+\begin_inset LatexCommand \index{PIC16!stack}
+
+\end_inset
+
+ 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.
integer:
\layout LyX-Code
-printf () --> ltoa () --> ultoa () --> divschar ()
-\layout Standard
+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 good examples of monitors are paulmon and cmon51 (see section
+
+\begin_inset LatexCommand \ref{sec:Related-open-source-tools}
+
+\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}
-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
+\end_inset
-\layout Standard
+ file (see
+\begin_inset LatexCommand \ref{OMF file}
-\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
+) 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)}
+\begin_inset LatexCommand \index{SDCDB (debugger)}
\end_inset
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 Section
+\layout Subsection
Compiling for Debugging
\layout Standard
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 compiler generates a .adb file for each of these files.
The linker creates the .cdb
\begin_inset LatexCommand \index{<file>.cdb}
files and the address information.
This .cdb is used by the debugger.
-\layout Section
+\layout Subsection
How the Debugger Works
\layout Standard
-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
+ 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.
execution is controlled by the debugger.
When a command is issued for the debugger, it translates it into appropriate
commands for the simulator.
-\layout Section
+ (Currently SDCDM only connects to the simulator but
+\emph on
+newcdb
+\emph default
+ at
+\begin_inset LatexCommand \url{http://ec2drv.sf.net/}
+
+\end_inset
-Starting the Debugger
+ 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.
\end_inset
object file.
-\layout Section
+\layout Subsection
-Command Line Options
+SDCDB Command Line Options
\layout Itemize
-
\layout Itemize
-k <port number> passed to simulator see the simulator docs for details.
-\layout Section
+\layout Subsection
-Debugger Commands
+SDCDB Debugger Commands
\layout Standard
As mentioned earlier the command interface for the debugger has been deliberatel
"Watch me now.
Iam going Down.
My name is Bobby Brown"
-\layout Section
+\layout Subsection
-Interfacing with DDD
+Interfacing SDCDB with DDD
\layout Comment
The screenshot was converted from png to eps with:
\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).
+ as this broke the build system on Sourceforge (pdf-file was broken.
+ pdflatex does not accept eps files).
\layout Standard
-The .eps File
+The
+\emph on
+p
+\emph default
+ortable
+\emph on
+n
+\emph default
+etwork
+\emph on
+g
+\emph default
+raphics File
\size footnotesize
-\begin_inset LatexCommand \url{http://cvs.sourceforge.net/viewcvs.py/*checkout*/sdcc/sdcc/doc/figures/ddd_example.eps}
+\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png}
\end_inset
\newline
ddd -debugger 'sdcdb -cpu 8032 ddd_example'
-\layout Section
+\layout Subsection
-Interfacing with XEmacs
+Interfacing SDCDB with XEmacs
\begin_inset LatexCommand \index{XEmacs}
\end_inset
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-Toggle list mode
-\newline
-;;
+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
+
+
+\begin_inset Marginal
+collapsed true
+
+\layout Standard
+
+
+\series bold
+\SpecialChar ~
+!
+\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
+
+
+\emph on
+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
+\begin_inset LatexCommand \label{sec:Porting-code-to-other-compilers}
+
+\end_inset
+
+
+\layout Itemize
+
+check whether endianness of the compilers differs and adapt where needed.
+\layout Itemize
+
+check the device specific header files
+\begin_inset LatexCommand \index{Header files}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Include files}
+
+\end_inset
+
+ 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.
+ (see f.e.
+ cc2510fx.h
+\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/P89c51RD2.h?view=markup}
+
+\end_inset
+
+).
+\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).
+\layout Itemize
+
+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).
+ See section
+\begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
+
+\end_inset
+
+.
+\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
+\family typewriter
+char
+\family default
+ or
+\family typewriter
+unsigned char
+\family default
+ variables.
+ For the sake of C99 compatibility SDCC will probably promote these to
+\family typewriter
+int
+\family default
+ more often than other compilers.
+ Eventually insert explicit casts to
+\family typewriter
+(char)
+\family default
+or
+\family typewriter
+ (unsigned char)
+\family default
+.
+ Also check that the ~\SpecialChar ~
+operator
+\begin_inset LatexCommand \index{\~\/ Operator}
+
+\end_inset
+
+ is not used on
+\family typewriter
+bit
+\begin_inset LatexCommand \index{bit}
+
+\end_inset
+
+
+\family default
+ variables, use the !\SpecialChar ~
+operator instead.
+ See sections
+\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
+\begin_inset LatexCommand \index{vararg, va\_arg}
+
+\end_inset
+
+) char variables as
+\family typewriter
+int
+\family default
+ others push them as
+\family typewriter
+char
+\family default
+.
+ See section
+\begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
+
+\end_inset
+
+).
+\layout Itemize
+
+check the resulting memory map
+\begin_inset LatexCommand \index{Memory map}
+
+\end_inset
+
+.
+ Usage of different memory spaces: code, stack, data (for mcs51/ds390 additional
+ly idata, pdata, xdata).
+ Eventually check if unexpected library functions are included.
+\layout Section
+
+Tools
+\begin_inset LatexCommand \index{Tools}
+
+\end_inset
+
+ included in the distribution
+\layout Standard
+\align left
+
+\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
+
+ucSsim
+\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
+\begin_inset LatexCommand \index{Header files}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Include files}
+
+\end_inset
+
+ 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 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
+mh2h.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-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' before doing any operation.
- This promotion
-\begin_inset LatexCommand \index{type promotion}
+\layout Standard
+header file conversion
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- 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
+\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
-\family typewriter
-unsigned char uc = 0xfe;
-\newline
-if (uc * uc < 0) /* this is true! */
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-....
-\newline
-}
\layout Standard
+as-gbz80
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\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
+\layout Standard
+Assembler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\family typewriter
-(unsigned char) -12 / (signed char) -3 = ...
\layout Standard
-No, the result is not 4:
-\layout Verse
+\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
-\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
+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
-comp.lang.c FAQ
-\begin_inset Quotes srd
+\layout Standard
+
+Linker
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-:
-\layout Quote
+\layout Standard
-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
+\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
-NEVER jump into a LOOP.
-\layout Itemize
+\layout Standard
-Declare the variables to be local
-\begin_inset LatexCommand \index{local variables}
+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
- whenever possible, especially loop control variables (induction).
-\layout Itemize
+\layout Standard
-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 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
-\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
+Intel Hex packer
+\begin_inset LatexCommand \index{packihx (tool)}
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\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
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
+</cell>
+</row>
+</lyxtabular>
-feeling
-\begin_inset Quotes srd
\end_inset
- for the code generation.
+
+\newline
+
\layout Section
-Tools
-\begin_inset LatexCommand \index{Tools}
+Documentation
+\begin_inset LatexCommand \index{Documentation}
\end_inset
included in the distribution
\layout Standard
-\align center
+\align left
\begin_inset Tabular
-<lyxtabular version="3" rows="12" columns="3">
+<lyxtabular version="3" rows="10" columns="2">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
+<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">
\layout Standard
-Name
+Subject / Title
\end_inset
</cell>
-<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
-Purpose
+Where to get / filename
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Directory
+SDCC Compiler User Guide
\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
-uCsim
+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
-Simulator for various architectures
+Changelog of SDCC
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/sim/ucsim
+sdcc/Changelog
\end_inset
</cell>
</row>
\layout Standard
-keil2sdcc.pl
+ASXXXX
+\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-header file conversion
+\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">
\layout Standard
-sdcc/support/scripts
+sdcc/as/doc/asxhtm.html
\end_inset
</cell>
</row>
\layout Standard
-mh2h.c
+SDCC regression test
+\begin_inset LatexCommand \index{Regression test}
+
\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">
\layout Standard
-sdcc/support/scripts
+sdcc/doc/test_suite_spec.pdf
\end_inset
</cell>
</row>
\layout Standard
-as-gbz80
+Various notes
\end_inset
</cell>
-<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
-Assembler
+sdcc/doc/*
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</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
+
-\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">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-as-z80
+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
-Assembler
+Software simulator for microcontrollers
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\bar no
\noun off
\color none
-sdcc/bin
+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>
\layout Standard
-asx8051
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Temporary notes on the pic16
+\begin_inset LatexCommand \index{PIC16}
-\layout Standard
+\end_inset
-Assembler
+ port
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+sdcc/src/pic16/NOTES
\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>
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Simulator
+SDCC internal documentation (debugging file format)
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
+sdcc/doc/
\family roman
\series medium
\shape up
\bar no
\noun off
\color none
-sdcc/bin
+cdbfileformat.pd
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+f
\end_inset
</cell>
</row>
-<row topline="true">
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Section
+
+Related open source tools
+\begin_inset LatexCommand \label{sec:Related-open-source-tools}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Related tools}
+
+\end_inset
+
+
+\layout Standard
+\align left
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="14" 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
-aslink
+Name
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Linker
+Purpose
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+Where to get
\end_inset
</cell>
</row>
\layout Standard
-link-z80
+gpsim
+\begin_inset LatexCommand \index{gpsim (pic simulator)}
+
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Linker
+PIC simulator
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-link-gbz80
+gputils
+\begin_inset LatexCommand \index{gputils (pic tools)}
+
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Linker
+GNU PIC utilities
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
+
+\end_inset
+
+
\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
-packihx
+flP5
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-ihx packer
+PIC programmer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\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>
+\begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
\end_inset
-\newline
-
-\layout Section
-
-Documentation
-\begin_inset LatexCommand \index{Documentation}
-
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- 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">
+ec2drv/newcdb
+\end_inset
+</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Subject / Title
+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">
\layout Standard
-Where to get / filename
+
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-SDCC Compiler User Guide
+indent
+\begin_inset LatexCommand \index{indent (source formatting tool)}
+
\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
+Formats C source - Master of the white spaces
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/Changelog
+
+\begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-ASXXXX
-\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
+srecord
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
\end_inset
-\begin_inset LatexCommand \index{Assembler documentation}
-
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- Assemblers and ASLINK
-\begin_inset LatexCommand \index{aslink}
+\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 \index{Linker documentation}
-\end_inset
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
- 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>
<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
+\layout Standard
+objdump
+\begin_inset LatexCommand \index{objdump (tool)}
\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
+Object file conversion, ...
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/doc/*
+Part of binutils (should be there anyway)
\end_inset
</cell>
</row>
\layout Standard
-Notes on debugging with sdcdb
-\begin_inset LatexCommand \index{sdcdb (debugger)}
-
+cmon51
\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">
\layout Standard
-sdcc/debugger/README
+
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\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
+doxygen
+\begin_inset LatexCommand \index{doxygen (source documentation tool)}
-\layout Standard
+\end_inset
-\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
+Source code documentation system
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/src/pic16/NOTES
+
+\begin_inset LatexCommand \url{http://www.doxygen.org}
+
+\end_inset
+
+
\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
-SDCC internal documentation (debugging file format)
+kdevelop
\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/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
+IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
\end_inset
</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\layout Section
-Related open source tools
-\begin_inset LatexCommand \index{Related tools}
+\begin_inset LatexCommand \url{http://www.kdevelop.org}
\end_inset
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="11" columns="3">
-<features>
-<column alignment="center" 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">
+\end_inset
+</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
+paulmon
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Purpose
+8051 monitor (hex up-/download, single step, disassemble)
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Where to get
+
+\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-gpsim
-\begin_inset LatexCommand \index{gpsim (pic simulator)}
+splint
+\begin_inset LatexCommand \index{splint (syntax checking tool)}
\end_inset
\layout Standard
-PIC simulator
+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">
\layout Standard
-\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
+\begin_inset LatexCommand \url{http://www.splint.org}
\end_inset
\end_inset
</cell>
</row>
-<row topline="true">
+<row topline="true" bottomline="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)}
+ddd
+\begin_inset LatexCommand \index{ddd (debugger)}
\end_inset
\layout Standard
-GNU PIC utilities
+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">
\layout Standard
-\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
+\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
\end_inset
\end_inset
</cell>
</row>
-<row topline="true">
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Section
+
+Related documentation / recommended reading
+\layout Standard
+\align left
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" 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
-flP5
+Name
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-PIC programmer
+Subject / Title
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
-
-\end_inset
-
-
+Where to get
\end_inset
</cell>
</row>
\layout Standard
-indent
-\begin_inset LatexCommand \index{indent (source formatting tool)}
-
-\end_inset
-
+\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">
\layout Standard
-Formats C source - Master of the white spaces
+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">
\layout Standard
-\begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
+\begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
\end_inset
\layout Standard
-srecord
-\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
-
-\end_inset
-
-
+c-faq
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Object file conversion, checksumming, ...
+C-FAQ-list
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
+\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
\end_inset
\layout Standard
-objdump
-\begin_inset LatexCommand \index{objdump (tool)}
-
-\end_inset
-
-
+ISO/IEC 9899:TC2
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Object file conversion, ...
+
+\begin_inset Quotes sld
+\end_inset
+
+C-Standard
+\begin_inset Quotes srd
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Part of binutils (should be there anyway)
+
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-doxygen
-\begin_inset LatexCommand \index{doxygen (source documentation tool)}
-
-\end_inset
-
-
+ISO/IEC DTR 18037
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Source code documentation system
+
+\begin_inset Quotes sld
+\end_inset
+
+Extensions for Embedded C
+\begin_inset Quotes srd
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.doxygen.org}
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf}
\end_inset
\layout Standard
-kdevelop
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
+Latest datasheet of the target CPU
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.kdevelop.org}
-
-\end_inset
-
-
+vendor
\end_inset
</cell>
</row>
\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">
\layout Standard
-Statically checks c sources (see
-\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
-
-\end_inset
-
-)
+Revision history of datasheet
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.splint.org}
-
-\end_inset
-
-
+vendor
\end_inset
</cell>
</row>
\layout Standard
-ddd
-\begin_inset LatexCommand \index{ddd (debugger)}
-
-\end_inset
-
-
+S.
+ S.
+ Muchnick
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Debugger, serves nicely as GUI to sdcdb
-\begin_inset LatexCommand \index{sdcdb (debugger)}
-
-\end_inset
-
- (Unix only)
+Advanced Compiler Design and Implementation
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
-
-\end_inset
-
-
+bookstore (very dedicated, probably read other books first)
\end_inset
</cell>
</row>
\layout Section
-Related documentation / recommended reading
+Application notes specifically for SDCC
\layout Standard
-\align center
+
+SDCC makes no claims about the completeness of this list and about up-to-datenes
+s or correctness of the application notes
+\begin_inset LatexCommand \index{Application notes}
+
+\end_inset
+
+.
+\layout Standard
+\align left
+
+\size footnotesize
\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
+<lyxtabular version="3" rows="7" 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">
+<column alignment="block" valignment="top" leftline="true" width="17col%">
+<column alignment="block" valignment="top" leftline="true" width="27col%">
+<column alignment="block" valignment="top" leftline="true" rightline="true" width="57col%">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
+
+\size footnotesize
+Vendor
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
+
+\size footnotesize
Subject / Title
\end_inset
</cell>
\layout Standard
+
+\size footnotesize
Where to get
\end_inset
</cell>
\layout Standard
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-c-refcard.pdf
+\size footnotesize
+Maxim / Dallas
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-C Reference Card
-\begin_inset LatexCommand \index{C Reference card}
+
+\size footnotesize
+Using the SDCC Compiler for the DS80C400
+\begin_inset LatexCommand \index{DS80C400}
\end_inset
-, 2 pages
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3346.pdf}
\end_inset
\layout Standard
-c-faq
+
+\size footnotesize
+Maxim / Dallas
+\end_inset
+</cell>
+<cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none" width="30line%">
+\begin_inset Text
+
+\layout Standard
+
+
+\size footnotesize
+Using the Free SDCC C Compiler to Develop Firmware for the DS89C420/430/440/450
+\begin_inset LatexCommand \index{DS89C4x0}
+
+\end_inset
+
+ Family of Microcontrollers
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3477.pdf}
+
+\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-list
+
+\size footnotesize
+Silicon Laboratories / Cygnal
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size footnotesize
+Integrating SDCC 8051 Tools Into The Silicon Labs IDE
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/en/an198.pdf}
\end_inset
\layout Standard
+
+\size footnotesize
+Ramtron / Goal Semiconductor
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Latest datasheet of the target CPU
+
+\size footnotesize
+Interfacing SDCC to Syn and Textpad
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-vendor
+
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
+
+\size footnotesize
+Ramtron / Goal Semiconductor
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Revision history of datasheet
+
+\size footnotesize
+Installing and Configuring SDCC and Crimson Editor
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-vendor
+
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-S.
- S.
- Muchnick
+
+\size footnotesize
+Texas Instruments
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Advanced Compiler Design and Implementation
+
+\size footnotesize
+MSC12xx Programming with SDCC
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-bookstore (very dedicated, probably read other books first)
+
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://focus.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=sbaa109&fileType=pdf}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\end_inset
-\newline
-
\layout Section
Some Questions
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).
+ well over 150,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_inset
- area and cvs code repository
-\begin_inset LatexCommand \index{cvs code repository}
+ area and Subversion code repository
+\begin_inset LatexCommand \index{Subversion code repository}
\end_inset
\end_inset
option can sometimes be useful in locating optimization problems.
- When reporting a bug please maker sure you:
+ When reporting a bug please make sure you:
\layout Enumerate
Attach the code you are compiling with SDCC.
\end_inset
+.
+ With SDCC on average having more than 200 downloads
+\begin_inset LatexCommand \index{download}
+
+\end_inset
+
+ on sourceforge per day
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+220 daily downloads on average Jan-Sept 2006 and about 150 daily downloads
+ between 2002 and 2005.
+ This does not include other methods of distribution.
+\end_inset
+
+ there must be some users.
+ So it's not exactly easy to find a new bug.
+ If you find one we need it:
+\emph on
+reporting bugs is good
+\emph default
.
\layout Section
ChangeLog
\layout Standard
-You can follow the status of the cvs version
+You can follow the status of the Subversion version
\begin_inset LatexCommand \index{version}
\end_inset
\end_inset
- in the cvs-repository
-\newline
-
+ in the Subversion repository
\size footnotesize
-
-\begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
+
+\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 code repository}
+
+\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
+\begin_inset LatexCommand \index{cvs (see Subversion)}
+
+\end_inset
+
+ 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
), over assembly programming, to C to FPGA compilers (
-\begin_inset LatexCommand \url[FPGAC]{http://fpgac.sf.net}
+\begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
\end_inset
\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}
+\begin_inset LatexCommand \url[OLPC]{http://www.laptop.org}
\end_inset
\end_inset
+\layout Standard
+
+The latest publically available version of the standard
+\emph on
+ISO/IEC 9899 - Programming languages - C
+\emph default
+ should be available at:
+\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
+
+\end_inset
+
+.
+\newline
+
\layout Standard
Deviations from the compliance:
command line option is specified.
\layout Itemize
-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.:
+structures
+\begin_inset LatexCommand \index{struct}
+
+\end_inset
+
+ and unions
+\begin_inset LatexCommand \index{union}
+
+\end_inset
+
+ cannot be assigned values directly, cannot be passed as function parameters
+ or assigned to each other and cannot be a return value
+\begin_inset LatexCommand \index{return value}
+
+\end_inset
+
+ from a function, e.g.:
\begin_deeper
\layout Verse
\newline
}
\newline
-struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
- */
+
+\series bold
+struct
+\series default
+ s foo1 (
+\series bold
+struct
+\series default
+ s parms) /* invalid in SDCC although allowed in ANSI */
\newline
{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-return rets;/* is invalid in SDCC although allowed in ANSI */
+return rets; /* is invalid in SDCC although allowed in ANSI */
\newline
}
\end_deeper
\family typewriter
-struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
+struct s { char x } a[] = {1, 2};\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* invalid in SDCC */
\newline
struct s { char x } a[] = {{1}, {2}}; /* OK */
\end_deeper
\family typewriter
\series bold
inline
+\begin_inset LatexCommand \index{inline (not supported)}
+
+\end_inset
+
+
\series default
int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
- in C99 */
+ in C99.
+ An empty define
+\emph on
+#define inline
+\emph default
+ can be used as a work around */
+\newline
+
\newline
for (
\series bold
projects / fw / sdcc / blobdiff