X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fsdccman.lyx;h=c0f42a80498e1180610aac440003a7c98ed0fe58;hb=ddf1d4a532dc2d70db406df774758db1960a04b8;hp=83becfc4bb5916b8eefe08cc824916dbd2f29dfe;hpb=23f54e969819d389479533aada003262660961f5;p=fw%2Fsdcc diff --git a/doc/sdccman.lyx b/doc/sdccman.lyx index 83becfc4..c0f42a80 100644 --- a/doc/sdccman.lyx +++ b/doc/sdccman.lyx @@ -7,8 +7,8 @@ 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 CPU DS390 embedded free Freescale GPL HC08 Intel manual Maxim mcs51 Microchip microcontroller open source PIC Z80 Zilog}, + pdfpagemode=UseOutlines, colorlinks=true, linkcolor=blue] {hyperref} % @@ -82,7 +82,7 @@ SDCC Compiler User Guide \size normal -SDCC 2.5.1 +SDCC 2.6.0 \size footnotesize \newline @@ -91,7 +91,7 @@ $Date$ $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 @@ -202,549 +202,548 @@ The peep hole optimizer uses a rule based substitution mechanism which is \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 + + + + + + + + + +\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 + + +\begin_inset Text \layout Standard -\backslash -/ +width \end_inset + + +\begin_inset Text --cyclomatic) to report the relative complexity of a function. - These functions can then be further optimized, or hand coded in assembly - if needed. - -\newline +\layout Standard -\newline -SDCC also comes with a companion source level debugger SDCDB, the debugger - currently uses ucSim a freeware simulator for 8051 and other micro-controllers. - -\newline +default +\end_inset + + +\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 + + +\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 + + + + +\begin_inset Text -\begin_inset LatexCommand \index{Status of documentation} +\layout Standard +bool \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset Foot -collapsed false +1 bit +\end_inset + + +\begin_inset Text \layout Standard -Obviously this has pros and cons +unsigned \end_inset + + +\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 + + +\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 + + + + +\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 - + + +\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 + + +\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 + + +\begin_inset Text -Compatibility with previous versions -\begin_inset LatexCommand \index{Compatibility with previous versions} +\layout Standard +-128, +127 \end_inset - + + +\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 + + + + +\begin_inset Text - (see section -\begin_inset LatexCommand \ref{sub:ANSI-Compliance} +\layout Standard +short \end_inset + + +\begin_inset Text - for ANSI-Compliance). - -\newline +\layout Standard -\layout Itemize +16 bits, 2 bytes +\end_inset + + +\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 + + +\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 + + +\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 + + + + +\begin_inset Text \layout Standard -\backslash -/ +int \end_inset + + +\begin_inset Text --regextend has been removed. -\layout Itemize +\layout Standard -option - -\begin_inset ERT -status Collapsed +16 bits, 2 bytes +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ +signed \end_inset + + +\begin_inset Text --noregparms has been removed. -\layout Itemize +\layout Standard -option - -\begin_inset ERT -status Collapsed +-32.768, +32.767 +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ +0, +65.535 \end_inset + + + + +\begin_inset Text --stack-after-data has been removed. -\layout Itemize - -bit -\begin_inset LatexCommand \index{bit} +\layout Standard +long \end_inset + + +\begin_inset Text - and sbit -\begin_inset LatexCommand \index{sbit} +\layout Standard +32 bits, 4 bytes \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{\_\_sbit} - +signed \end_inset + + +\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 + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{type promotion} - +0, +4.294.967.296 \end_inset + + + + +\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 + + +\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 + + +\begin_inset Text -\family default -In previous versions, both forms would have toggled the bit. \layout Standard +signed +\end_inset + + +\begin_inset Text -\emph on - -\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 + + +\begin_inset Text -Other Resources \layout Standard -The SDCC home page at -\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/} - \end_inset + + + + +\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 + + +\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 + + +\begin_inset Text \layout Standard - -\family typewriter -char KernelFunction3(char p) at 0x340; -\newline +generic +\end_inset + + +\begin_inset Text \layout Standard +\end_inset + + +\begin_inset Text -\family typewriter -code banking -\begin_inset LatexCommand \index{code banking (not supported)} +\layout Standard \end_inset + + + - support for mcs51 +\end_inset + + +\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. + SDCDB and ucSim are currently not available on Win32 platforms. + +\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 functions are casted to int unless explicitly + casted, e.g.: +\newline +\family typewriter +\SpecialChar ~ +\SpecialChar ~ +char a=3; +\newline +\SpecialChar ~ +\SpecialChar ~ +printf ("%d %c \backslash -/ -\end_inset +n", a, (char)a); +\family default --disable-z80-port Excludes the z80 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 @@ -754,11 +753,10 @@ status Collapsed / \end_inset --disable-avr-port Excludes the AVR port -\layout List -\labelwidthstring 00.00.0000 +-regextend has been removed. +\layout Itemize -- +option - \begin_inset ERT status Collapsed @@ -768,11 +766,10 @@ status Collapsed / \end_inset --disable-ds390-port Excludes the DS390 port -\layout List -\labelwidthstring 00.00.0000 +-noregparms has been removed. +\layout Itemize -- +option - \begin_inset ERT status Collapsed @@ -782,571 +779,423 @@ status Collapsed / \end_inset --disable-hc08-port Excludes the HC08 port -\layout List -\labelwidthstring 00.00.0000 +-stack-after-data has been removed. +\layout Itemize -- -\begin_inset ERT -status Collapsed +bit +\begin_inset LatexCommand \index{bit} -\layout Standard +\end_inset + + and sbit +\begin_inset LatexCommand \index{sbit} -\backslash -/ \end_inset --disable-pic-port Excludes the PIC port -\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-xa51-port Excludes the XA51 port -\layout List -\labelwidthstring 00.00.0000 -- -\begin_inset ERT -status Collapsed +\begin_inset LatexCommand \index{type promotion} -\layout Standard +\end_inset + +. + The most common incompatibility resulting from this change is related to + bit toggling +\begin_inset LatexCommand \index{Bit toggling} -\backslash -/ \end_inset --disable-ucsim Disables configuring and building of ucsim -\layout List -\labelwidthstring 00.00.0000 + idioms, e.g.: +\newline -- -\begin_inset ERT -status Collapsed +\family typewriter +\SpecialChar ~ +\SpecialChar ~ +bit b; +\newline +\SpecialChar ~ +\SpecialChar ~ +b = ~b; /* equivalent to b=1 instead of toggling b */ +\begin_inset Marginal +collapsed false \layout Standard -\backslash -/ + +\series bold +\SpecialChar ~ +! \end_inset --disable-device-lib-build Disables automatically building device libraries -\layout List -\labelwidthstring 00.00.0000 -- -\begin_inset ERT -status Collapsed +\newline +\SpecialChar ~ +\SpecialChar ~ +b = !b; /* toggles b */ +\newline +\family default +In previous versions, both forms would have toggled the bit. \layout Standard -\backslash -/ -\end_inset - --disable-packihx Disables building packihx -\layout List -\labelwidthstring 00.00.0000 -- -\begin_inset ERT -status Collapsed +\emph on + +\layout Section +System Requirements \layout Standard -\backslash -/ -\end_inset +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 --enable-libgc Use the Bohem memory allocator. - Lower runtime footprint. +Other Resources \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 SDCC home page at +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/} -\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). -\newline - -\newline -The settings for -\begin_inset Quotes sld -\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} -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 +. + 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 -open source, -\layout Enumerate +Wishes for the future +\layout Standard -a gcc compiler and last but not least -\layout Enumerate +There are (and always will be) some things that could be done. + Here are some I can think of: +\newline -the binaries can be built by cross compiling on Sourceforge's compile farm. \layout Standard -See the examples, how to pass the Win32 settings to 'configure'. - The other Win32 builds using Borland, VC or whatever don't use 'configure', - but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure' - for Win32. -\newline -\newline -These defaults are: +\family typewriter +char KernelFunction3(char p) at 0x340; \newline \layout Standard -\align center -\begin_inset Tabular - - - - - - - -\begin_inset Text -\layout Standard +\family typewriter +better code banking +\begin_inset LatexCommand \index{code banking (limited support)} -Variable \end_inset - - -\begin_inset Text -\layout Standard + support for mcs51 +\newline -default -\end_inset - - -\begin_inset Text +\newline -\layout Standard +\family default +If you can think of some more, please see the section +\begin_inset LatexCommand \ref{sub:Requesting-Features} -Win32 builds \end_inset - - - - -\begin_inset Text - -\layout Standard + about filing feature requests +\begin_inset LatexCommand \index{Requesting features} -\emph on -PREFIX \end_inset - - -\begin_inset Text -\layout Standard -/usr/local +\begin_inset LatexCommand \index{Feature request} + \end_inset - - -\begin_inset Text -\layout Standard +. +\newline +\layout Chapter + +Installing SDCC +\begin_inset LatexCommand \index{Installation} -\backslash -sdcc \end_inset - - - - -\begin_inset Text + \layout Standard +For most users it is sufficient to skip to either section +\begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux} -\emph on -EXEC_PREFIX \end_inset - - -\begin_inset Text - -\layout Standard + or section +\begin_inset LatexCommand \ref{sub:Windows-Install} -\emph on -$PREFIX \end_inset - - -\begin_inset Text -\layout Standard +. + More detailled instructions follow below. +\layout Section +Configure Options +\begin_inset LatexCommand \index{Options SDCC configuration} -\emph on -$PREFIX \end_inset - - - - -\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 -BINDIR -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard - -\emph on -$EXECPREFIX -\emph default -/bin +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-prefix see table below +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed -\emph on -$EXECPREFIX -\emph default +\layout Standard \backslash -bin +/ \end_inset - - - - -\begin_inset Text -\layout Standard +-exec_prefix see table below +\layout List +\labelwidthstring 00.00.0000 - -\emph on -DATADIR -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard - -\emph on -$PREFIX -\emph default -/share +\backslash +/ \end_inset - - -\begin_inset Text - -\layout Standard +-bindir see table below +\layout List +\labelwidthstring 00.00.0000 -\emph on -$PREFIX -\end_inset - - - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard - -\emph on -DOCDIR +\backslash +/ \end_inset - - -\begin_inset Text - -\layout Standard +-datadir see table below +\layout List +\labelwidthstring 00.00.0000 -\emph on -$DATADIR -\emph default -/sdcc/doc -\end_inset - - -\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 -$DATADIR -\emph default +sdccconf_h_dir_separator environment variable, either / or +\backslash \backslash -doc -\end_inset - - - - -\begin_inset Text + 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 -\layout Standard +- +\begin_inset ERT +status Collapsed +\layout Standard -\emph on -INCLUDE_DIR_SUFFIX +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-disable-mcs51-port Excludes the Intel mcs51 port +\layout List +\labelwidthstring 00.00.0000 -sdcc/include -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -include +\backslash +/ \end_inset - - - - -\begin_inset Text - -\layout Standard +-disable-gbz80-port Excludes the Gameboy gbz80 port +\layout List +\labelwidthstring 00.00.0000 -\emph on -LIB_DIR_SUFFIX -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -sdcc/lib +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-disable-z80-port Excludes the z80 port +\layout List +\labelwidthstring 00.00.0000 -lib -\end_inset - - - +- +\begin_inset ERT +status Collapsed + +\layout Standard +\backslash +/ \end_inset +-disable-avr-port Excludes the AVR 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 - - - - - - - -\begin_inset Text +\backslash +/ +\end_inset -\layout Standard +-disable-ds390-port Excludes the DS390 port +\layout List +\labelwidthstring 00.00.0000 -Variable (computed) -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -default +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-disable-hc08-port Excludes the HC08 port +\layout List +\labelwidthstring 00.00.0000 -Win32 builds -\end_inset - - - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard - -\emph on -BIN2DATA_DIR +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-disable-pic-port Excludes the PIC port +\layout List +\labelwidthstring 00.00.0000 -../share -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -.. +\backslash +/ \end_inset - - - - -\begin_inset Text - -\layout Standard +-disable-xa51-port Excludes the XA51 port +\layout List +\labelwidthstring 00.00.0000 -\emph on -PREFIX2BIN_DIR -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -bin +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard - -bin -\end_inset - - - - -\begin_inset Text - -\layout Standard - - -\emph on -PREFIX2DATA_DIR -\end_inset - - -\begin_inset Text - -\layout Standard +-disable-ucsim Disables configuring and building of ucsim +\layout List +\labelwidthstring 00.00.0000 -share/sdcc -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard +\backslash +/ \end_inset - - - - -\end_inset - -\newline - -\layout Standard -\noindent -Examples: -\layout LyX-Code +-disable-device-lib Disables automatically building device libraries +\layout List +\labelwidthstring 00.00.0000 -./configure -\newline -./configure - +- \begin_inset ERT status Collapsed @@ -1356,15 +1205,11 @@ status Collapsed / \end_inset --prefix= -\begin_inset Quotes srd -\end_inset - -/usr/bin -\begin_inset Quotes srd -\end_inset +-disable-packihx Disables building packihx +\layout List +\labelwidthstring 00.00.0000 - - +- \begin_inset ERT status Collapsed @@ -1374,17 +1219,11 @@ status Collapsed / \end_inset --datadir= -\begin_inset Quotes srd -\end_inset - -/usr/share -\begin_inset Quotes srd -\end_inset - +-enable-doc Build pdf, html and txt files from the lyx sources +\layout List +\labelwidthstring 00.00.0000 -\newline -./configure - +- \begin_inset ERT status Collapsed @@ -1394,7 +1233,13 @@ status Collapsed / \end_inset --disable-avr-port - +-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 @@ -1404,421 +1249,354 @@ 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 +-help` and the man/info pages of `configure` for details. +\newline -./configure -\backslash +\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 -CC= -\begin_inset Quotes srd -\end_inset +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 -i586-mingw32msvc-gcc -\begin_inset Quotes srd +\newline +The settings for +\begin_inset Quotes sld \end_inset - CXX= +Win32 builds \begin_inset Quotes srd \end_inset -i586-mingw32msvc-g++ -\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 - -\backslash - -\newline -RANLIB= -\begin_inset Quotes srd -\end_inset +open source, +\layout Enumerate -i586-mingw32msvc-ranlib -\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 -STRIP= -\begin_inset Quotes srd -\end_inset -i586-mingw32msvc-strip -\begin_inset Quotes srd -\end_inset +\newline +These defaults are: +\newline - -\backslash +\layout Standard +\align center -\newline -- -\begin_inset ERT -status Collapsed +\begin_inset Tabular + + + + + + + +\begin_inset Text \layout Standard -\backslash -/ +Variable \end_inset + + +\begin_inset Text --prefix= -\begin_inset Quotes srd -\end_inset +\layout Standard -/sdcc -\begin_inset Quotes srd +default \end_inset + + +\begin_inset Text - -\backslash +\layout Standard -\newline -- -\begin_inset ERT -status Collapsed +Win32 builds +\end_inset + + + + +\begin_inset Text \layout Standard -\backslash -/ -\end_inset --datadir= -\begin_inset Quotes srd +\emph on +PREFIX \end_inset + + +\begin_inset Text -/sdcc -\begin_inset Quotes srd +\layout Standard + +/usr/local \end_inset + + +\begin_inset Text - -\backslash +\layout Standard -\newline -docdir= -\begin_inset Quotes srd -\end_inset -/sdcc/doc -\begin_inset Quotes srd +\backslash +sdcc \end_inset + + + + +\begin_inset Text - -\backslash +\layout Standard -\newline -include_dir_suffix= -\begin_inset Quotes srd -\end_inset -include -\begin_inset Quotes srd +\emph on +EXEC_PREFIX \end_inset + + +\begin_inset Text - -\backslash - -\newline -lib_dir_suffix= -\begin_inset Quotes srd -\end_inset - -lib -\begin_inset Quotes srd -\end_inset +\layout Standard - -\backslash -\newline -sdccconf_h_dir_separator= -\begin_inset Quotes srd +\emph on +$PREFIX \end_inset + + +\begin_inset Text +\layout Standard -\backslash -\backslash +\emph on +$PREFIX +\end_inset + + + + +\begin_inset Text -\backslash +\layout Standard -\backslash -\begin_inset Quotes srd +\emph on +BINDIR \end_inset - - -\backslash - -\newline -- -\begin_inset ERT -status Collapsed + + +\begin_inset Text \layout Standard -\backslash -/ + +\emph on +$EXECPREFIX +\emph default +/bin \end_inset + + +\begin_inset Text --disable-device-lib-build -\backslash +\layout Standard -\newline -- -\begin_inset ERT -status Collapsed -\layout Standard +\emph on +$EXECPREFIX +\emph default \backslash -/ +bin \end_inset - --disable-ucsim -\backslash - -\newline -- -\begin_inset ERT -status Collapsed + + + + +\begin_inset Text \layout Standard -\backslash -/ -\end_inset --host=i586-mingw32msvc - -\begin_inset ERT -status Collapsed +\emph on +DATADIR +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ + +\emph on +$PREFIX +\emph default +/share \end_inset + + +\begin_inset Text --build=unknown-unknown-linux-gnu \layout Standard -To -\begin_inset Quotes sld -\end_inset -cross -\begin_inset Quotes srd +\emph on +$PREFIX \end_inset + + + + +\begin_inset Text -compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32 -): -\layout LyX-Code - -./configure -C -\backslash +\layout Standard -\newline -CFLAGS= -\begin_inset Quotes srd -\end_inset --mno-cygwin -O2 -\begin_inset Quotes srd +\emph on +DOCDIR \end_inset + + +\begin_inset Text - -\backslash +\layout Standard -\newline -LDFLAGS= -\begin_inset Quotes srd -\end_inset --mno-cygwin -\begin_inset Quotes srd +\emph on +$DATADIR +\emph default +/sdcc/doc \end_inset + + +\begin_inset Text - -\backslash +\layout Standard -\newline -- -\begin_inset ERT -status Collapsed -\layout Standard +\emph on +$DATADIR +\emph default \backslash -/ -\end_inset - --prefix= -\begin_inset Quotes srd +doc \end_inset + + + + +\begin_inset Text -/sdcc -\begin_inset Quotes srd -\end_inset +\layout Standard - -\backslash -\newline -- -\begin_inset ERT -status Collapsed +\emph on +INCLUDE_DIR_SUFFIX +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ +sdcc/include \end_inset + + +\begin_inset Text --datadir= -\begin_inset Quotes srd -\end_inset +\layout Standard -/sdcc -\begin_inset Quotes srd +include \end_inset + + + + +\begin_inset Text - -\backslash +\layout Standard -\newline -docdir= -\begin_inset Quotes srd -\end_inset -/sdcc/doc -\begin_inset Quotes srd +\emph on +LIB_DIR_SUFFIX \end_inset + + +\begin_inset Text - -\backslash - -\newline -include_dir_suffix= -\begin_inset Quotes srd -\end_inset +\layout Standard -include -\begin_inset Quotes srd +sdcc/lib \end_inset + + +\begin_inset Text - -\backslash - -\newline -lib_dir_suffix= -\begin_inset Quotes srd -\end_inset +\layout Standard lib -\begin_inset Quotes srd \end_inset + + + - -\backslash - -\newline -sdccconf_h_dir_separator= -\begin_inset Quotes srd \end_inset -\backslash +\newline -\backslash - -\backslash - -\backslash - -\begin_inset Quotes srd -\end_inset - - -\backslash - -\newline -- -\begin_inset ERT -status Collapsed - -\layout Standard - -\backslash -/ -\end_inset - --disable-ucsim \layout Standard - -'configure' is quite slow on Cygwin (at least on windows before Win2000/XP). - The option '- -\begin_inset ERT -status Collapsed - -\layout Standard - -\backslash -/ -\end_inset - --C' turns on caching, which gives a little bit extra speed. - However if options are changed, it can be necessary to delete the config.cache - file. -\layout Section - -Install paths -\begin_inset LatexCommand \label{sub:Install-paths} - -\end_inset - - -\begin_inset LatexCommand \index{Install paths} - -\end_inset - - +\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 -\added_space_top medskip \align center +\align center \begin_inset Tabular - + - - - - + + + \begin_inset Text \layout Standard - -\series bold -Description -\end_inset - - -\begin_inset Text - -\layout Standard - - -\series bold -Path +Variable (computed) \end_inset @@ -1826,9 +1604,7 @@ Path \layout Standard - -\series bold -Default +default \end_inset @@ -1836,21 +1612,11 @@ Default \layout Standard - -\series bold Win32 builds \end_inset - - -\begin_inset Text - -\layout Standard - -Binary files* -\end_inset - + \begin_inset Text @@ -1858,7 +1624,7 @@ Binary files* \emph on -$EXEC_PREFIX +BIN2DATA_DIR \end_inset @@ -1866,7 +1632,7 @@ $EXEC_PREFIX \layout Standard -/usr/local/bin +../share \end_inset @@ -1874,23 +1640,11 @@ $EXEC_PREFIX \layout Standard - -\backslash -sdcc -\backslash -bin +.. \end_inset - - -\begin_inset Text - -\layout Standard - -Include files -\end_inset - + \begin_inset Text @@ -1898,7 +1652,7 @@ Include files \emph on -$DATADIR/ $INCLUDE_DIR_SUFFIX +PREFIX2BIN_DIR \end_inset @@ -1906,7 +1660,7 @@ $DATADIR/ $INCLUDE_DIR_SUFFIX \layout Standard -/usr/local/share/sdcc/include +bin \end_inset @@ -1914,23 +1668,11 @@ $DATADIR/ $INCLUDE_DIR_SUFFIX \layout Standard - -\backslash -sdcc -\backslash -include +bin \end_inset - - -\begin_inset Text - -\layout Standard - -Library file** -\end_inset - + \begin_inset Text @@ -1938,7 +1680,7 @@ Library file** \emph on -$DATADIR/$LIB_DIR_SUFFIX +PREFIX2DATA_DIR \end_inset @@ -1946,7 +1688,7 @@ $DATADIR/$LIB_DIR_SUFFIX \layout Standard -/usr/local/share/sdcc/lib +share/sdcc \end_inset @@ -1954,299 +1696,236 @@ $DATADIR/$LIB_DIR_SUFFIX \layout Standard - -\backslash -sdcc -\backslash -lib \end_inset - - -\begin_inset Text - -\layout Standard + -Documentation \end_inset - - -\begin_inset Text - -\layout Standard -\emph on -$DOCDIR -\end_inset - - -\begin_inset Text +\newline \layout Standard +\noindent +Examples: +\layout LyX-Code -/usr/local/share/sdcc/doc -\end_inset - - -\begin_inset Text +./configure +\newline +./configure - +\begin_inset ERT +status Collapsed \layout Standard - -\backslash -sdcc \backslash -doc +/ \end_inset - - - +-prefix= +\begin_inset Quotes srd \end_inset +/usr/bin +\begin_inset Quotes srd +\end_inset -\layout Verse - - -\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 + - +\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 - -\newline -Moreover the install path can be changed by defining DESTDIR -\begin_inset LatexCommand \index{DESTDIR} +\backslash +/ +\end_inset +-datadir= +\begin_inset Quotes srd \end_inset -: -\layout LyX-Code +/usr/share +\begin_inset Quotes srd +\end_inset -make install DESTDIR=$(HOME)/sdcc.rpm/ -\layout Standard -Please note that DESTDIR must have a trailing slash! -\layout Section +\newline +./configure - +\begin_inset ERT +status Collapsed -Search Paths -\begin_inset LatexCommand \label{sub:Search-Paths} +\layout Standard +\backslash +/ \end_inset +-disable-avr-port - +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \index{Search path} +\layout Standard +\backslash +/ \end_inset - +-disable-xa51-port \layout Standard -Some search paths or parts of them are determined by configure variables - (in -\emph on -italics -\emph default -, see section above). - Further search paths are determined by environment variables during runtime. - -\newline -The paths searched when running the compiler are as follows (the first catch - wins): -\newline +To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw +32'): +\layout LyX-Code -\newline -1. - Binary files (preprocessor, assembler and linker) -\newline +./configure +\backslash -\layout Standard -\align center +\newline +CC= +\begin_inset Quotes srd +\end_inset -\begin_inset Tabular - - - - - - - -\begin_inset Text +i586-mingw32msvc-gcc +\begin_inset Quotes srd +\end_inset -\layout Standard + CXX= +\begin_inset Quotes srd +\end_inset -Search path +i586-mingw32msvc-g++ +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard + +\backslash + +\newline +RANLIB= +\begin_inset Quotes srd +\end_inset -default +i586-mingw32msvc-ranlib +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard + +\backslash -Win32 builds +\newline +STRIP= +\begin_inset Quotes srd \end_inset - - - - -\begin_inset Text - -\layout Standard -$SDCC_HOME/ -\emph on -$PPREFIX2BIN_DIR +i586-mingw32msvc-strip +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard + +\backslash -$SDCC_HOME/bin -\end_inset - - -\begin_inset Text +\newline +- +\begin_inset ERT +status Collapsed \layout Standard -$SDCC_HOME \backslash -bin +/ \end_inset - - - - -\begin_inset Text -\layout Standard - -Path of argv[0] (if available) +-prefix= +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard - -Path of argv[0] +/sdcc +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard + +\backslash -Path of argv[0] -\end_inset - - - - -\begin_inset Text +\newline +- +\begin_inset ERT +status Collapsed \layout Standard -$PATH +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-datadir= +\begin_inset Quotes srd +\end_inset -$PATH +/sdcc +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard + +\backslash -$PATH +\newline +docdir= +\begin_inset Quotes srd \end_inset - - - +/sdcc/doc +\begin_inset Quotes srd \end_inset -\newline +\backslash -\layout Standard -\noindent -2. - Include files \newline +include_dir_suffix= +\begin_inset Quotes srd +\end_inset -\layout Standard -\align center +include +\begin_inset Quotes srd +\end_inset -\begin_inset Tabular - - - - - - - -\begin_inset Text + +\backslash -\layout Standard +\newline +lib_dir_suffix= +\begin_inset Quotes srd +\end_inset -Search path +lib +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard + +\backslash -default +\newline +sdccconf_h_dir_separator= +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard -Win32 builds +\backslash + +\backslash + +\backslash + +\backslash + +\begin_inset Quotes srd \end_inset - - - - -\begin_inset Text -\layout Standard + +\backslash +\newline - \begin_inset ERT status Collapsed @@ -2257,14 +1936,10 @@ status Collapsed / \end_inset --I dir -\end_inset - - -\begin_inset Text - -\layout Standard +-disable-device-lib +\backslash +\newline - \begin_inset ERT status Collapsed @@ -2275,14 +1950,10 @@ status Collapsed / \end_inset --I dir -\end_inset - - -\begin_inset Text - -\layout Standard +-disable-ucsim +\backslash +\newline - \begin_inset ERT status Collapsed @@ -2293,226 +1964,174 @@ status Collapsed / \end_inset --I dir -\end_inset - - - - -\begin_inset Text +-host=i586-mingw32msvc - +\begin_inset ERT +status Collapsed \layout Standard -$SDCC_INCLUDE +\backslash +/ \end_inset - - -\begin_inset Text +-build=unknown-unknown-linux-gnu \layout Standard -$SDCC_INCLUDE +To +\begin_inset Quotes sld \end_inset - - -\begin_inset Text - -\layout Standard -$SDCC_INCLUDE +cross +\begin_inset Quotes srd \end_inset - - - - -\begin_inset Text -\layout Standard +compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32 +): +\layout LyX-Code -$SDCC_HOME/ -\newline +./configure -C +\backslash -\emph on -$PREFIX2DATA_DIR/ \newline -$INCLUDE_DIR_SUFFIX +CFLAGS= +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard +-mno-cygwin -O2 +\begin_inset Quotes srd +\end_inset + + +\backslash -$SDCC_ HOME/ -\newline -share/sdcc/ \newline -include +LDFLAGS= +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard - -$SDCC_HOME -\backslash -include +-mno-cygwin +\begin_inset Quotes srd \end_inset - - - - -\begin_inset Text -\layout Standard + +\backslash -path(argv[0])/ \newline +- +\begin_inset ERT +status Collapsed -\emph on -$BIN2DATADIR/ -\emph default +\layout Standard -\newline +\backslash +/ +\end_inset -\emph on -$INCLUDE_DIR_SUFFIX +-prefix= +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard +/sdcc +\begin_inset Quotes srd +\end_inset -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 ~ + +\backslash -\end_inset - - -\begin_inset Text +\newline +- +\begin_inset ERT +status Collapsed \layout Standard -path(argv[0]) -\backslash -.. \backslash -include +/ \end_inset - - - - -\begin_inset Text -\layout Standard +-datadir= +\begin_inset Quotes srd +\end_inset +/sdcc +\begin_inset Quotes srd +\end_inset -\emph on -$DATADIR/ -\emph default + +\backslash \newline - -\emph on -$INCLUDE_DIR_SUFFIX +docdir= +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard +/sdcc/doc +\begin_inset Quotes srd +\end_inset -/usr/local/share/sdcc/ + +\backslash + \newline +include_dir_suffix= +\begin_inset Quotes srd +\end_inset + include +\begin_inset Quotes srd \end_inset - - -\begin_inset Text -\layout Standard + +\backslash -(not on Win32) +\newline +lib_dir_suffix= +\begin_inset Quotes srd \end_inset - - - +lib +\begin_inset Quotes srd \end_inset +\backslash + \newline +sdccconf_h_dir_separator= +\begin_inset Quotes srd +\end_inset -\layout Standard -\noindent -The option - -\begin_inset ERT -status Collapsed -\layout Standard +\backslash \backslash -/ + +\backslash + +\backslash + +\begin_inset Quotes srd \end_inset --nostdinc disables the last two search paths. -\newline + +\backslash \newline -3. - Library files -\newline +- +\begin_inset ERT +status Collapsed \layout Standard -With the exception of -\begin_inset Quotes sld +\backslash +/ \end_inset -- +-disable-ucsim +\layout Standard + +'configure' is quite slow on Cygwin (at least on windows before Win2000/XP). + The option '- \begin_inset ERT status Collapsed @@ -2522,43 +2141,61 @@ status Collapsed / \end_inset --L dir -\begin_inset Quotes srd -\end_inset +-C' turns on caching, which gives a little bit extra speed. + However if options are changed, it can be necessary to delete the config.cache + file. +\layout Section + +Install paths +\begin_inset LatexCommand \label{sub:Install-paths} + +\end_inset + + +\begin_inset LatexCommand \index{Install paths} + +\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 - + - - - + + + + - + \begin_inset Text \layout Standard -Search path + +\series bold +Description \end_inset - + \begin_inset Text \layout Standard -default + +\series bold +Path +\end_inset + + +\begin_inset Text + +\layout Standard + + +\series bold +Default \end_inset @@ -2566,27 +2203,29 @@ default \layout Standard + +\series bold Win32 builds \end_inset - + \begin_inset Text \layout Standard -- -\begin_inset ERT -status Collapsed +Binary files* +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ -\end_inset --L dir +\emph on +$EXEC_PREFIX \end_inset @@ -2594,17 +2233,7 @@ status Collapsed \layout Standard -- -\begin_inset ERT -status Collapsed - -\layout Standard - -\backslash -/ -\end_inset - --L dir +/usr/local/bin \end_inset @@ -2612,17 +2241,11 @@ status Collapsed \layout Standard -- -\begin_inset ERT -status Collapsed - -\layout Standard \backslash -/ -\end_inset - --L dir +sdcc +\backslash +bin \end_inset @@ -2632,156 +2255,105 @@ status Collapsed \layout Standard -$SDCC_LIB/ -\newline - -\emph on - +Include files \end_inset - + \begin_inset Text \layout Standard -$SDCC_LIB/ -\newline \emph on - +$DATADIR/ $INCLUDE_DIR_SUFFIX \end_inset - + \begin_inset Text \layout Standard -$SDCC_LIB -\backslash +/usr/local/share/sdcc/include +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\emph on - + +\backslash +sdcc +\backslash +include \end_inset - + +\begin_inset Text + +\layout Standard + +Library file** +\end_inset + + \begin_inset Text \layout Standard -$SDCC_HOME/ -\newline \emph on -$PREFIX2DATA_DIR/ -\newline -$LIB_DIR_SUFFIX/ +$DATADIR/$LIB_DIR_SUFFIX \end_inset - + \begin_inset Text \layout Standard -$SDCC_HOME/ -\newline -share/sdcc/ -\newline -lib/ -\emph on - +/usr/local/share/sdcc/lib \end_inset - + \begin_inset Text \layout Standard -$SDCC_HOME + \backslash -lib +sdcc \backslash - -\emph on - -\newline - +lib \end_inset - - + + \begin_inset Text \layout Standard -path(argv[0])/ -\newline +Documentation +\end_inset + + +\begin_inset Text -\emph on -$BIN2DATADIR/ -\emph default +\layout Standard -\newline \emph on -$LIB_DIR_SUFFIX/ +$DOCDIR \end_inset - + \begin_inset Text \layout Standard -path(argv[0])/ -\newline -../sdcc/lib/ -\emph on - -\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/doc \end_inset @@ -2789,68 +2361,104 @@ path(argv[0])/ \layout Standard -path(argv[0]) -\backslash -\newline -.. \backslash -lib +sdcc \backslash +doc +\end_inset + + + -\emph on - +\end_inset + + +\layout Verse + + +\size footnotesize +*compiler, preprocessor, assembler, and linker \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 ~ +**the +\shape italic +model +\shape default + is auto-appended by the compiler, e.g. + small, large, z80, ds390 etc +\layout Standard +\noindent +The install paths can still be changed during `make install` with e.g.: +\layout LyX-Code + +make install prefix=$(HOME)/local/sdcc +\layout Standard + +Of course this doesn't change the search paths compiled into the binaries. +\newline + +\newline +Moreover the install path can be changed by defining DESTDIR +\begin_inset LatexCommand \index{DESTDIR} \end_inset - - - - -\begin_inset Text +: +\layout LyX-Code + +make install DESTDIR=$(HOME)/sdcc.rpm/ \layout Standard +Please note that DESTDIR must have a trailing slash! +\layout Section + +Search Paths +\begin_inset LatexCommand \label{sub:Search-Paths} + +\end_inset + + +\begin_inset LatexCommand \index{Search path} + +\end_inset + +\layout Standard + +Some search paths or parts of them are determined by configure variables + (in \emph on -$DATADIR/ +italics +\emph default +, see section above). + Further search paths are determined by environment variables during runtime. + \newline -$LIB_DIR_SUFFIX/ +The paths searched when running the compiler are as follows (the first catch + wins): +\newline + +\newline +1. + Binary files (preprocessor, assembler and linker) +\newline + +\layout Standard +\align center + +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +Search path \end_inset @@ -2858,11 +2466,7 @@ $LIB_DIR_SUFFIX/ \layout Standard -/usr/local/share/sdcc/ -\newline -lib/ -\emph on - +default \end_inset @@ -2870,295 +2474,183 @@ lib/ \layout Standard -(not on Win32) +Win32 builds \end_inset - - -\end_inset - + + +\begin_inset Text -\newline +\layout Standard -\layout Comment +$SDCC_HOME/ +\emph on +$PPREFIX2BIN_DIR +\end_inset + + +\begin_inset Text -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 +$SDCC_HOME/bin +\end_inset + + +\begin_inset Text \layout Standard +$SDCC_HOME \backslash -/ +bin \end_inset + + + + +\begin_inset Text --nostdlib disables the last two search paths. -\layout Section +\layout Standard -Building SDCC -\begin_inset LatexCommand \index{Building SDCC} +Path of argv[0] (if available) +\end_inset + + +\begin_inset Text +\layout Standard + +Path of argv[0] \end_inset + + +\begin_inset Text +\layout Standard -\layout Subsection +Path of argv[0] +\end_inset + + + + +\begin_inset Text -Building SDCC on Linux -\begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux} +\layout Standard +$PATH \end_inset + + +\begin_inset Text +\layout Standard -\layout Enumerate +$PATH +\end_inset + + +\begin_inset Text +\layout Standard -\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} +$PATH +\end_inset + + + \end_inset -. -\layout Enumerate + +\newline +\layout Standard +\noindent +2. + Include files +\newline -\series medium -Bring up a command line terminal, such as xterm. -\layout Enumerate +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text -\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 +Search path +\end_inset + + +\begin_inset Text +\layout Standard -\series medium -Type -\family sans -\series bold -"./configure -\family default -\series default -". - This configures the package for compilation on your system. -\layout Enumerate - - -\series medium -Type -\family sans -\series bold -"make -\family default -\series default -" -\series medium -. - -\series default - All of the source packages will compile, this can take a while. -\layout Enumerate - - -\series medium -Type -\family sans -\series bold -"make install" -\family default -\series default - as root -\series medium -. - -\series default - This copies the binary executables, the include files, the libraries and - the documentation to the install directories. - Proceed with section -\begin_inset LatexCommand \ref{sec:Testing-the-SDCC} - +default \end_inset + + +\begin_inset Text -. -\layout Subsection - -Building SDCC on OSX 2.x -\layout Standard - -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 - -./configure CC=gcc2 CXX=g++2 -\layout Subsection - -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 +Win32 builds +\end_inset + + + + +\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 +- +\begin_inset ERT +status Collapsed -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 -\end_inset - -native -\begin_inset Quotes srd -\end_inset - - Win32-binary can be built, which will not need the Cygwin-DLL. - For the necessary 'configure' options see section 'configure options' or - the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'. -\newline - -\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 - -default text file type -\begin_inset Quotes srd -\end_inset - - to -\begin_inset Quotes sld +\backslash +/ \end_inset -unix -\begin_inset Quotes srd +-I dir \end_inset + + +\begin_inset Text - and download/install at least the following packages. - Some packages are selected by default, others will be automatically selected - because of dependencies with the manually selected packages. - Never deselect these packages! -\layout Itemize - -flex -\layout Itemize - -bison -\layout Itemize - -gcc ; version 3.x is fine, no need to use the old 2.9x -\layout Itemize - -binutils ; selected with gcc -\layout Itemize - -make -\layout Itemize - -rxvt ; a nice console, which makes life much easier under windoze (see below) -\layout Itemize - -man ; not really needed for building SDCC, but you'll miss it sooner or - later -\layout Itemize - -less ; not really needed for building SDCC, but you'll miss it sooner or - later -\layout Itemize - -cvs ; only if you use CVS access \layout Standard -If you want to develop something you'll need: -\layout Itemize +- +\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 + + +\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 @@ -3168,551 +2660,606 @@ status Collapsed / \end_inset --login -i +-I dir +\end_inset + + + + +\begin_inset Text + \layout Standard -with (one line): -\layout LyX-Code +$SDCC_INCLUDE +\end_inset + + +\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 +$SDCC_INCLUDE +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ +$SDCC_INCLUDE \end_inset + + + + +\begin_inset Text --login \layout Standard -Text selected with the mouse is automatically copied to the clipboard, pasting - works with shift-insert. +$SDCC_HOME/ \newline +\emph on +$PREFIX2DATA_DIR/ \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 +$INCLUDE_DIR_SUFFIX \end_inset + + +\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_ HOME/ +\newline +share/sdcc/ +\newline +include +\end_inset + + +\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_HOME +\backslash +include \end_inset + + + + +\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 +path(argv[0])/ +\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 +$BIN2DATADIR/ +\emph default -\end_inset +\newline +\emph on +$INCLUDE_DIR_SUFFIX +\end_inset + + +\begin_inset Text -\series medium -, it will be named something like sdcc -\series default -.src -\series medium -.tgz. +\layout Standard -\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. - +path(argv[0])/ \newline - +../sdcc/include \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. - If you are getting a message such as "This makefile was not generated by - Developer Studio etc. - etc. -\begin_inset Quotes srd -\end_inset - - 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 +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ -unix2dos -\begin_inset Quotes srd \end_inset + + +\begin_inset Text - utility freely available on the internet. - Doug Hawkins reported in the sdcc-user list that this works: -\newline +\layout Standard -\newline -C: -\backslash -Programming -\backslash -SDCC> unix2dos sdcc.dsw -\newline -C: +path(argv[0]) \backslash -Programming +.. \backslash -SDCC> for /R %I in (*.dsp) do @unix2dos "%I" -\newline +include +\end_inset + + + + +\begin_inset Text + +\layout Standard + + +\emph on +$DATADIR/ +\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 + + +\begin_inset Text +\layout Standard +/usr/local/share/sdcc/ \newline +include +\end_inset + + +\begin_inset Text -\newline -Download the file UnxUtils -\begin_inset LatexCommand \index{UnxUtils} +\layout Standard +(not on Win32) \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 +\end_inset -The easy way: + \newline -\newline -a) Extract UnxUtils.zip to your C: +\layout Standard +\noindent +The option - +\begin_inset ERT +status Collapsed + +\layout Standard + \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) +/ +\end_inset + +-nostdinc disables the last two search paths. \newline \newline -b) In the Visual C++ IDE click Tools, Options, select the Directory tab, - in 'Show directories for:' select 'Executable files', and in the directories - window add a new path: 'C: -\backslash -user -\backslash -local -\backslash -wbin', click ok. +3. + Library files \newline -\newline -(As a side effect, you get a bunch of Unix utilities that could be useful, - such as diff and patch.) -\layout Enumerate +\layout Standard -A more compact way: -\newline +With the exception of +\begin_inset Quotes sld +\end_inset -\newline -This one avoids extracting a bunch of files you may not use, but requires - some extra work: -\newline +- +\begin_inset ERT +status Collapsed + +\layout Standard -\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 +-L dir +\begin_inset Quotes srd +\end_inset -\newline -c) Rename bison.exe to '_bison.exe'. + the +\shape italic +model +\shape default + is auto-appended by the compiler (e.g. + small, large, z80, ds390 etc.). + \newline -\newline -d) Create a batch file 'bison.bat' in 'C: -\backslash -util -\backslash -' and add these lines: -\newline -\SpecialChar ~ -\SpecialChar ~ -set BISON_SIMPLE=C: -\backslash -util -\backslash -bison.simple -\newline -\SpecialChar ~ -\SpecialChar ~ -set BISON_HAIRY=C: -\backslash -util -\backslash -bison.hairy -\newline -\SpecialChar ~ -\SpecialChar ~ -_bison %1 %2 %3 %4 %5 %6 %7 %8 %9 -\newline - -\newline -Steps 'c' and 'd' are needed because bison requires by default that the - files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory, - '/usr/local/share/' I think. - So it is necessary to tell bison where those files are located if they - are not in such directory. - That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY. -\newline - -\newline -e) In the Visual C++ IDE click Tools, Options, select the Directory tab, - in 'Show directories for:' select 'Executable files', and in the directories - window add a new path: 'c: -\backslash -util', click ok. - Note that you can use any other path instead of 'c: -\backslash -util', even the path where the Visual C++ tools are, probably: 'C: -\backslash -Program Files -\backslash -Microsoft Visual Studio -\backslash -Common -\backslash -Tools'. - So you don't have to execute step 'e' :) \layout Standard +\align center -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 +\begin_inset Tabular + + + + + + + +\begin_inset Text -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 +\layout Standard -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 +Search path +\end_inset + + +\begin_inset Text -\newline +\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 +default +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\newline -or on Windows NT/2000/XP from the command prompt with the command: -\newline +Win32 builds +\end_inset + + + + +\begin_inset Text -\family sans -\series bold +\layout Standard -\newline -del /s *.obj *.lib *.rul -\family default -\series default - from the sdcc directory. -\layout Subsection +- +\begin_inset ERT +status Collapsed -Windows Install Using a ZIP Package -\layout Enumerate +\layout Standard -Download the binary zip package from -\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php} +\backslash +/ +\end_inset +-L dir \end_inset + + +\begin_inset Text - and unpack it using your favorite unpacking tool (gunzip, WinZip, etc). - This should unpack to a group of sub-directories. - An example directory structure after unpacking the mingw32 package is: - c: -\backslash -sdcc -\backslash -bin for the executables, c: -\backslash -sdcc -\backslash -include and c: -\backslash -sdcc -\backslash -lib for the include and libraries. -\layout Enumerate +\layout Standard -Adjust your environment variable PATH to include the location of the bin - directory or start sdcc using the full path. -\layout Subsection +- +\begin_inset ERT +status Collapsed -Windows Install Using the Setup Program -\begin_inset LatexCommand \label{sub:Windows-Install} +\layout Standard +\backslash +/ \end_inset +-L dir +\end_inset + + +\begin_inset Text \layout Standard -Download the setup program -\emph on -sdcc-x.y.z-setup.exe -\emph default - for an official release from -\newline +- +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599} +\layout Standard +\backslash +/ \end_inset - 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} - +-L dir \end_inset + + + + +\begin_inset Text - and execute it. - A windows typical installer will guide you through the installation process. -\layout Section - -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 Quotes srd -\end_inset +$SDCC_LIB/ +\newline -make -\begin_inset Quotes srd +\emph on + \end_inset + + +\begin_inset Text +\layout Standard -\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} +$SDCC_LIB/ +\newline +\emph on + \end_inset + + +\begin_inset Text - 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 -\end_inset +$SDCC_LIB +\backslash -. -\layout Section +\newline + +\emph on + +\end_inset + + + + +\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 +$SDCC_HOME/ +\newline + +\emph on +$PREFIX2DATA_DIR/ +\newline +$LIB_DIR_SUFFIX/ +\end_inset + + +\begin_inset Text \layout Standard -If you should know why please drop us a note +$SDCC_HOME/ +\newline +share/sdcc/ +\newline +lib/ +\emph on + \end_inset + + +\begin_inset Text -. - -\newline -You'll find the pdf version -\begin_inset LatexCommand \index{PDF version of this document} +\layout Standard -\end_inset +$SDCC_HOME +\backslash +lib +\backslash - at -\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf} +\emph on +\newline + \end_inset + + + + +\begin_inset Text + +\layout Standard + +path(argv[0])/ +\newline + +\emph on +$BIN2DATADIR/ +\emph default -. - \newline -A html version -\begin_inset LatexCommand \index{HTML version of this document} +\emph on +$LIB_DIR_SUFFIX/ \end_inset + + +\begin_inset Text - should be online at -\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html} +\layout Standard + +path(argv[0])/ +\newline +../sdcc/lib/ +\emph on + +\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 ~ \end_inset + + +\begin_inset Text + +\layout Standard + +path(argv[0]) +\backslash -. \newline -This documentation is in some aspects different from a commercial documentation: - -\layout Itemize +.. +\backslash +lib +\backslash -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 + +\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 + + + + +\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} +\emph on +$DATADIR/ +\newline +$LIB_DIR_SUFFIX/ \end_inset + + +\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 +/usr/local/share/sdcc/ +\newline +lib/ \emph on -a -\emph default -rray -\begin_inset LatexCommand \index{fpga (field programmable gate array)} - + \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset Quotes srd +(not on Win32) \end_inset + + + - we expect you to have a quick look there and come back. - If you read this you are on the right track. -\layout Itemize +\end_inset -Some sections attribute more space to problems, restrictions and warnings - than to the solution. -\layout Itemize -The installation section and the section about the debugger is intimidating. -\layout Itemize +\newline -There are still lots of typos and there are more different writing styles - than pictures. -\layout Section +\layout Comment -Testing the SDCC Compiler -\begin_inset LatexCommand \label{sec:Testing-the-SDCC} +Don't delete any of the stray spaces in the table above without checking + the HTML output (last line)! +\layout Standard -\end_inset +\SpecialChar ~ - -\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 - -\begin_inset ERT -status Collapsed +\newline +The option - +\begin_inset ERT +status Collapsed \layout Standard @@ -3720,644 +3267,775 @@ 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. +, this will create a sub-directory called sdcc with all of the sources. +\layout Enumerate + +Change directory into the main SDCC directory, for example type: +\family sans +\series bold +"cd sdcc \series default +". +\layout Enumerate -\newline -\newline +\series medium +Type +\family sans +\series bold +"./configure +\family default +\series default +". + This configures the package for compilation on your system. +\layout Enumerate + \series medium -The next step is to try it with the linker. - Type in +Type \family sans \series bold -"sdcc test.c +"make \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 -/ + All of the source packages will compile, this can take a while. +\layout Enumerate + + \series medium -usr/local/share/sdcc/lib directory +Type +\family sans +\series bold +"make install" +\family default \series default - + as root \series medium -(see +. + \series default -section -\begin_inset LatexCommand \ref{sub: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 -\SpecialChar ~ +. +\layout Subsection -\series medium -Install trouble-shooting for suggestions). -\series default +Building SDCC on OSX 2.x +\layout Standard +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 -\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 - +./configure CC=gcc2 CXX=g++2 +\layout Subsection -\family typewriter -#include -\newline +Cross compiling SDCC on Linux for Windows +\layout Standard -\newline -char str1[10]; -\newline +With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32. + See section 'Configure Options'. +\layout Subsection -\newline -void main(void) { -\newline -\SpecialChar ~ -\SpecialChar ~ -strcpy(str1, "testing"); -\newline -} +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 -\series medium -Compile this by typing -\family sans -\series bold -"sdcc test.c" -\family default -\series medium -. - This should generate a test.ihx output file, and it should give no warnings - such as not finding the string.h file. - If it cannot find the string.h file, then the problem is that -\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} +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 \end_inset -\SpecialChar ~ +native +\begin_inset Quotes srd +\end_inset -\series medium -Install trouble-shooting section for suggestions). + 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 -\series default - Use option -\series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +\newline +In order to install Cygwin on Windows download setup.exe from +\begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/} -\backslash -/ \end_inset --print-search-dirs -\series default - -\begin_inset LatexCommand \index{-\/-print-search-dirs} - +. + Run it, set the +\begin_inset Quotes sld \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} - +default text file type +\begin_inset Quotes srd \end_inset + to +\begin_inset Quotes sld +\end_inset -\begin_inset LatexCommand \index{Install trouble-shooting} - +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 -\layout Subsection +flex +\layout Itemize -If SDCC does not build correctly -\layout Standard +bison +\layout Itemize -A thing to try is starting from scratch by unpacking the .tgz source package - again in an empty directory. - Configure it like: -\newline +gcc ; version 3.x is fine, no need to use the old 2.9x +\layout Itemize -\newline +binutils ; selected with gcc +\layout Itemize -\family sans -\series bold -./configure 2>&1 | tee configure.log -\family default -\series default +make +\layout Itemize -\newline +rxvt ; a nice console, which makes life much easier under windoze (see below) +\layout Itemize -\newline -and build it like: -\newline +man ; not really needed for building SDCC, but you'll miss it sooner or + later +\layout Itemize -\newline +less ; not really needed for building SDCC, but you'll miss it sooner or + later +\layout Itemize -\family sans -\series bold -make 2>&1 | tee make.log -\family default -\series default +svn ; only if you use Subversion access +\layout Standard -\newline +If you want to develop something you'll need: +\layout Itemize -\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 +python ; for the regression tests +\layout Itemize -What the +gdb ; the gnu debugger, together with the nice GUI \begin_inset Quotes sld \end_inset -./configure +insight \begin_inset Quotes srd \end_inset - does -\layout Standard -The -\begin_inset Quotes sld -\end_inset +\layout Itemize -./configure -\begin_inset Quotes srd -\end_inset +openssh ; to access the CF or commit changes +\layout Itemize - 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 +autoconf and autoconf-devel ; if you want to fight with 'configure', don't + use autoconf-stable! +\layout Standard -What the -\begin_inset Quotes sld -\end_inset +rxvt is a nice console with history. + Replace in your cygwin.bat the line +\layout LyX-Code -make -\begin_inset Quotes srd -\end_inset +bash - +\begin_inset ERT +status Collapsed - does \layout Standard -This runs the GNU make tool, which automatically compiles all the source - packages into the final installed binary executables. -\layout Subsection - -What the -\begin_inset Quotes sld -\end_inset - -make install -\begin_inset Quotes erd +\backslash +/ \end_inset - command does. +-login -i \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} +with (one line): +\layout LyX-Code -\end_inset +rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red +\layout LyX-Code -,\SpecialChar ~ + -bg black -fg white -geometry 100x65 -e bash - +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \ref{sub:Search-Paths} +\layout Standard +\backslash +/ \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 +-login \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. +Text selected with the mouse is automatically copied to the clipboard, pasting + works with shift-insert. \newline \newline -You might want to look at the files which are installed in . - At the time of this writing, we find the following programs for gcc-builds: -\newline - -\newline -In /bin: -\layout Itemize - -sdcc - The compiler. -\layout Itemize - -sdcpp - The C preprocessor. -\layout Itemize +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 -asx8051 - The assembler for 8051 type processors. -\layout Itemize +cygdrive +\begin_inset Quotes srd +\end_inset -as-z80 -\series bold -, -\series default -as-gbz80 - The Z80 and GameBoy Z80 assemblers. -\layout Itemize + is too long, you can change it with e.g. +\layout LyX-Code -aslink -The linker for 8051 type processors. -\layout Itemize +mount -s -u -c /mnt +\layout Standard -link-z80 -\series bold -, -\series default -link-gbz80 - The Z80 and GameBoy Z80 linkers. -\layout Itemize +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)} -s51 - The ucSim 8051 simulator. -\layout Itemize +\end_inset -sdcdb - The source debugger. -\layout Itemize + used in the project is 8. + Although a tabulator spacing of 8 is a sensible choice for programmers + (it's a power of 2 and allows to display 8/16 bit signed variables without + loosing columns) the plan is to move towards using only spaces in the source. +\layout Subsection -packihx - A tool to pack (compress) Intel hex files. +Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC) \layout Standard -In /share/sdcc/include -\layout Itemize - -the include files -\layout Standard -In /share/sdcc/lib -\layout Itemize +\series medium +Download the source package +\series default + either from the SDCC Subversion repository or from the +\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php} -the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled - relocatables. -\layout Standard +\end_inset -In /share/sdcc/doc -\layout Itemize -the documentation -\layout Standard - -As development for other processors proceeds, this list will expand to include - executables to support processors like AVR, PIC, etc. -\layout Subsection - -sdcc - The Compiler -\layout Standard - -This is the actual compiler, it in turn uses the c-preprocessor and invokes - the assembler and linkage editor. -\layout Subsection - -sdcpp - The C-Preprocessor -\layout Standard +\series medium +, it will be named something like sdcc +\series default +.src +\series medium +.tgz. -The preprocessor -\begin_inset LatexCommand \index{sdcpp (preprocessor)} +\series default + SDCC is distributed with all the projects, workspaces, and files you need + to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently + doesn't build under MSVC). + The workspace name is 'sdcc.dsw'. + Please note that as it is now, all the executables are created in a folder + called sdcc +\backslash +bin_vc. + Once built you need to copy the executables from sdcc +\backslash +bin_vc to sdcc +\backslash +bin before running SDCC. + +\newline +\newline +WARNING: Visual studio is very picky with line terminations; it expects + the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings. + When using the Subversion repository it's easiest to configure the svn + client to convert automatically for you. + If however you are getting a message such as "This makefile was not generated + by Developer Studio etc. + etc. +\begin_inset Quotes srd \end_inset - 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 - -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 - -S51 -\begin_inset LatexCommand \index{s51} - + 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 - 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} - +unix2dos +\begin_inset Quotes srd \end_inset -. - It currently supports the core mcs51, the Dallas DS80C390 and the Phillips - XA51 family. -\layout Subsection + utility freely available on the internet. + Doug Hawkins reported in the sdcc-user list that this works: +\newline -sdcdb - Source Level Debugger -\layout Standard +\newline +C: +\backslash +Programming +\backslash +SDCC> unix2dos sdcc.dsw +\newline +C: +\backslash +Programming +\backslash +SDCC> for /R %I in (*.dsp) do @unix2dos "%I" +\newline -Sdcdb -\begin_inset LatexCommand \index{sdcdb (debugger)} +\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 - is the companion source level debugger. - More about sdcdb in section -\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB} -\end_inset +\newline -. - The current version of the debugger uses Daniel's Simulator S51 -\begin_inset LatexCommand \index{s51} +\newline +Download the file UnxUtils +\begin_inset LatexCommand \index{UnxUtils} \end_inset -, but can be easily changed to use other simulators. - -\layout Chapter +.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 -Using SDCC -\layout Section +The easy way: +\newline -Compiling -\layout Subsection +\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 -Single Source File Projects -\layout Standard +\newline +b) In the Visual C++ IDE click Tools, Options, select the Directory tab, + in 'Show directories for:' select 'Executable files', and in the directories + window add a new path: 'C: +\backslash +user +\backslash +local +\backslash +wbin', click ok. +\newline -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". +\newline +(As a side effect, you get a bunch of Unix utilities that could be useful, + such as diff and patch.) +\layout Enumerate -\family default -\series default - This will compile, assemble and link your source file. - Output files are as follows: -\layout Itemize +A more compact way: +\newline -sourcefile.asm -\begin_inset LatexCommand \index{.asm} +\newline +This one avoids extracting a bunch of files you may not use, but requires + some extra work: +\newline -\end_inset +\newline +a) Create a directory were to put the tools needed, or use a directory already + present. + Say for example 'C: +\backslash +util'. +\newline - - Assembler source -\begin_inset LatexCommand \index{Assembler source} +\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 -\end_inset +\newline +c) Rename bison.exe to '_bison.exe'. +\newline - file created by the compiler -\layout Itemize +\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 -sourcefile.lst -\begin_inset LatexCommand \index{.lst} +\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 -\end_inset +\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 - - Assembler listing -\begin_inset LatexCommand \index{Assembler listing} +That is it. + Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy + the executables from sdcc +\backslash +bin_vc to sdcc +\backslash +bin, and you can compile using SDCC. +\layout Subsection -\end_inset +Building SDCC Using Borland +\layout Enumerate - file created by the Assembler -\layout Itemize +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 -sourcefile.rst -\begin_inset LatexCommand \index{.rst} +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 -\end_inset +\newline - - Assembler listing -\begin_inset LatexCommand \index{Assembler listing} +\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 +\newline - file updated with linkedit information, created by linkage editor -\layout Itemize +\newline +or on Windows NT/2000/XP from the command prompt with the command: +\newline -sourcefile.sym -\begin_inset LatexCommand \index{.sym} +\family sans +\series bold -\end_inset +\newline +del /s *.obj *.lib *.rul +\family default +\series default + from the sdcc directory. +\layout Subsection - - symbol listing -\begin_inset LatexCommand \index{Symbol listing} +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 - for the sourcefile, created by the assembler -\layout Itemize + 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 -sourcefile.rel -\begin_inset LatexCommand \index{.rel} +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} \end_inset - or sourcefile.o -\begin_inset LatexCommand \index{.o} + +\layout Standard + +Download the setup program +\emph on +sdcc-x.y.z-setup.exe +\emph default + for an official release from +\newline + +\begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599} \end_inset - - Object file -\begin_inset LatexCommand \index{Object file} + 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 - created by the assembler, input to Linkage editor -\layout Itemize + and execute it. + A windows typical installer will guide you through the installation process. +\layout Subsection -sourcefile.map -\begin_inset LatexCommand \index{.map} +VPATH +\begin_inset LatexCommand \index{VPATH} \end_inset - - The memory map -\begin_inset LatexCommand \index{Memory map} + feature +\layout Standard -\end_inset +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 - for the load module, created by the Linker -\layout Itemize -sourcefile.mem -\begin_inset LatexCommand \index{.mem} +\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 -\end_inset - - A file with a summary of the memory usage -\layout Itemize +\family typewriter +tar -xzf sdcc.src.tar.gz\SpecialChar ~ +# extract source to directory sdcc +\layout Standard -sourcefile.ihx -\begin_inset LatexCommand \index{.ihx} -\end_inset +\family typewriter +mkdir sdcc.build\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +# put output in sdcc.build +\layout Standard - - The load module in Intel hex format -\begin_inset LatexCommand \index{Intel hex format} -\end_inset +\family typewriter +cd sdcc.build +\layout Standard - (you can select the Motorola S19 format -\begin_inset LatexCommand \index{Motorola S19 format} -\end_inset +\family typewriter +../sdcc/configure\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +# configure is doing all the magic! +\layout Standard - with - + +\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 + +Building the Documentation +\layout Standard + +Add - \begin_inset ERT status Collapsed @@ -4367,1378 +4045,1472 @@ status Collapsed / \end_inset --out-fmt-s19 -\begin_inset LatexCommand \index{-\/-out-fmt-s19} - -\end_inset - -. - If you need another format you might want to use +-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 -\shape italic -objdump -\family default -\shape default +\series bold -\begin_inset LatexCommand \index{objdump (tool)} +\begin_inset Quotes srd +\end_inset +make +\begin_inset Quotes srd \end_inset - or -\family sans -\shape italic - srecord -\family default -\shape default -\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)} +\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 -). - Both formats are documented in the documentation of srecord -\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)} + as editor is straightforward. + Prebuilt documentation in html and pdf format is available from +\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php} \end_inset +. +\layout Section -\layout Itemize +Reading the Documentation +\layout Standard -sourcefile.adb -\begin_inset LatexCommand \index{.adb} - -\end_inset - - - An intermediate file containing debug information needed to create the - .cdb file (with - -\begin_inset ERT -status Open +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 \layout Standard -\backslash -/ +If you should know why please drop us a note \end_inset --debug -\begin_inset LatexCommand \index{-\/-debug} +. + +\newline +You'll find the pdf version +\begin_inset LatexCommand \index{PDF version of this document} \end_inset -) -\layout Itemize - -sourcefile.cdb -\begin_inset LatexCommand \index{.cdb} + at +\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf} \end_inset - - An optional file (with - -\begin_inset ERT -status Collapsed +. + +\newline +A html version +\begin_inset LatexCommand \index{HTML version of this document} -\layout Standard +\end_inset + + should be online at +\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html} -\backslash -/ \end_inset --debug) containing debug information. - The format is documented in cdbfileformat.pdf +. +\newline +This documentation is in some aspects different from a commercial documentation: + \layout Itemize -sourcefile. - - (no extension) -\begin_inset LatexCommand \index{ (no extension)} +It tries to document SDCC for several processor architectures in one document + (commercially these probably would be separate documents/products). + This document +\begin_inset LatexCommand \index{Status of documentation} \end_inset - An optional AOMF or AOMF51 -\begin_inset LatexCommand \index{AOMF, AOMF51} - -\end_inset + 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 - file containing debug information (generated with option - -\begin_inset ERT -status Collapsed +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} -\layout Standard +\end_inset -\backslash -/ + together with a statement +\begin_inset Quotes sld \end_inset --debug). - The (Intel) +some processors which are targetted by SDCC can be implemented in a \emph on - a +f \emph default -bsolute +ield \emph on -o +p \emph default -bject +rogrammable \emph on -m +g \emph default -odule +ate \emph on -f +a \emph default -ormat is commonly used by third party tools (debuggers -\begin_inset LatexCommand \index{Debugger} +rray +\begin_inset LatexCommand \index{FPGA (field programmable gate array)} \end_inset -, simulators, emulators) -\layout Itemize - -sourcefile.dump* -\begin_inset LatexCommand \index{.dump*} +\begin_inset Quotes srd \end_inset - - Dump file to debug the compiler it self (generated with option - -\begin_inset ERT -status Collapsed - -\layout Standard + or +\begin_inset LatexCommand \url{http://sf.net/projects/fpgac} -\backslash -/ \end_inset --dumpall) (see section -\begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options} - -\end_inset -\SpecialChar ~ - and section -\begin_inset LatexCommand \ref{sub:The-anatomy-of} +\begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)} \end_inset -\SpecialChar ~ - + \begin_inset Quotes sld \end_inset -Anatomy of the compiler +have you ever heard of an open source compiler that compiles a subset of + C for an FPGA? \begin_inset Quotes srd \end_inset -). -\layout Subsection - -Projects with Multiple Source Files -\layout Standard + we expect you to have a quick look there and come back. + If you read this you are on the right track. +\layout Itemize -SDCC can compile only ONE file at a time. - Let us for example assume that you have a project containing the following - files: -\newline +Some sections attribute more space to problems, restrictions and warnings + than to the solution. +\layout Itemize -\newline -foo1.c (contains some functions) -\newline -foo2.c (contains some more functions) -\newline -foomain.c (contains more functions and the function main) -\newline +The installation section and the section about the debugger is intimidating. +\layout Itemize -\size footnotesize +There are still lots of typos and there are more different writing styles + than pictures. +\layout Section -\newline +Testing the SDCC Compiler +\begin_inset LatexCommand \label{sec:Testing-the-SDCC} -\size default -The first two files will need to be compiled separately with the commands: -\size footnotesize - -\size default +\end_inset -\newline -\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 -sdcc\SpecialChar ~ --c\SpecialChar ~ -foo1.c -\family default -\series default -\size footnotesize - -\newline +"sdcc - +\begin_inset ERT +status Collapsed -\family sans -\series bold -\size default -sdcc\SpecialChar ~ --c\SpecialChar ~ -foo2.c -\family default -\series default +\layout Standard -\newline +\backslash +/ +\end_inset -\newline -Then compile the source file containing the -\emph on -main() -\emph default - function and link -\begin_inset LatexCommand \index{Linker} +-version" +\begin_inset LatexCommand \index{version} \end_inset - 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 + at the prompt, and the program should run and output its version like: + +\newline -\begin_inset LatexCommand \index{.rel} +\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} \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 \newline -Alternatively, -\emph on -foomain.c -\emph default -can be separately compiled as well: -\family sans -\series bold -\newline +\series medium +SDCC +\series default +is commonly installed as described in section +\begin_inset Quotes sld +\end_inset -\newline -sdcc\SpecialChar ~ --c\SpecialChar ~ -foomain.c -\newline -sdcc foomain.rel foo1.rel foo2.rel +Install and search paths +\begin_inset Quotes srd +\end_inset + +. \newline \newline -\family default +\series medium +Make sure the compiler works on a very simple example. + Type in the following test.c program using your favorite \series default -The file containing the -\emph on -main() -\emph default - function -\emph on - -\emph default -\noun on -must -\noun default - be the -\noun on -first -\noun default - file specified in the command line, since the linkage editor processes - file in the order they are presented to it. - The linker is invoked from SDCC using a script file with extension .lnk -\begin_inset LatexCommand \index{.lnk} - -\end_inset - -. - 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} +ASCII +\series medium +editor: +\layout Verse -\end_inset +\family typewriter +char test; +\newline +\newline +void main(void) { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +test=0; +\newline +} \layout Standard -Some reusable routines may be compiled into a library, see the documentation - for the assembler and linkage editor (which are in /share/sdcc/doc) - for how to create a -\emph on -.lib -\begin_inset LatexCommand \index{.lib} -\end_inset +\series medium +Compile this using the following command: +\family sans +\series bold +"sdcc -c test.c". +\family default +\series default + +\series medium +If all goes well, the compiler will generate a test.asm and test.rel file. + Congratulations, you've just compiled your first program with SDCC. + We used the -c option to tell SDCC not to link the generated code, just + to keep things simple for this step. +\series default -\emph default - library file. - Libraries created in this manner can be included in the command line. - Make sure you include the -L option to tell the linker where - to look for these files if they are not in the current directory. - Here is an example, assuming you have the source file -\emph on -foomain.c -\emph default - and a library -\emph on - foolib.lib -\emph default - in the directory -\emph on -mylib -\emph default - (if that is not the same as your current project): \newline \newline +\series medium +The next step is to try it with the linker. + Type in \family sans \series bold -sdcc foomain.c foolib.lib -L mylib -\newline - -\newline - +"sdcc test.c \family default \series default -Note here that -\emph on - mylib -\emph default - must be an absolute path name. -\newline - -\newline -The most efficient way to use libraries is to keep separate modules in separate - source files. - The lib file now should name all the modules.rel -\begin_inset LatexCommand \index{.rel} +" +\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 - files. - For an example see the standard library file -\emph on -libsdcc.lib -\emph default - in the directory /share/lib/small. -\layout Subsection +\SpecialChar ~ -Using sdcclib to Create and Manage Libraries -\begin_inset LatexCommand \index{sdcclib} +\series medium +Install trouble-shooting for suggestions). +\series default -\end_inset +\newline +\newline -\layout Standard +\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 -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: + +\family typewriter +#include +\newline + +\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 -? -\begin_inset LatexCommand \index{sdcclib} +"sdcc test.c" +\family default +\series medium +. + This should generate a test.ihx output file, and it should give no warnings + such as not finding the string.h file. + If it cannot find the string.h file, then the problem is that +\series default +SDCC +\series medium + cannot find the /usr/local/share/sdcc/include directory +\series default + +\series medium +(see the +\series default +section +\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting} \end_inset +\SpecialChar ~ -\newline - -\newline +\series medium +Install trouble-shooting section for suggestions). -\family default \series default -To create a new library file, start by compiling all the required modules. - For example: -\newline + Use option +\series bold +- +\begin_inset ERT +status Collapsed \layout Standard +\backslash +/ +\end_inset -\family sans -\series bold -sdcc -c _divsint.c -\layout Standard +-print-search-dirs +\series default +\begin_inset LatexCommand \index{-\/-print-search-dirs} -\family sans -\series bold -sdcc -c _divuint.c -\layout Standard +\end_inset + to find exactly where SDCC is looking for the include and lib files. +\layout Section -\family sans -\series bold -sdcc -c _modsint.c -\layout Standard +Install Trouble-shooting +\begin_inset LatexCommand \label{sub:Install-Trouble-shooting} +\end_inset -\family sans -\series bold -sdcc -c _moduint.c -\layout Standard +\begin_inset LatexCommand \index{Install trouble-shooting} -\family sans -\series bold -sdcc -c _mulint.c -\newline +\end_inset -\layout Standard -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 +\layout Subsection +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 + +\newline \family sans \series bold -sdcclib libint.lib _divsint.rel +./configure 2>&1 | tee configure.log \family default +\series default -\begin_inset LatexCommand \index{sdcclib} +\newline + +\newline +and build it like: +\newline + +\newline + +\family sans +\series bold +make 2>&1 | tee make.log +\family default +\series default + +\newline + +\newline +If anything goes wrong, you can review the log files to locate the problem. + Or a relevant part of this can be attached to an email that could be helpful + when requesting help from the mailing list. +\layout Subsection +What the +\begin_inset Quotes sld \end_inset +./configure +\begin_inset Quotes srd +\end_inset + does \layout Standard +The +\begin_inset Quotes sld +\end_inset -\family sans -\series bold -sdcclib libint.lib _divuint.rel -\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 sans -\series bold -sdcclib libint.lib _modsint.rel -\layout Standard +What the +\begin_inset Quotes sld +\end_inset +make +\begin_inset Quotes srd +\end_inset -\family sans -\series bold -sdcclib libint.lib _moduint.rel + 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 sans -\series bold -sdcclib libint.lib _mulint.rel -\series default +What the +\begin_inset Quotes sld +\end_inset -\newline +make install +\begin_inset Quotes erd +\end_inset + command does. \layout Standard -If the file already exists in the library, it will be replaced. - To see what modules and symbols are included in the library, options -s - and -m are available. - For example: -\newline +This will install the compiler, other executables libraries and include + files into the appropriate directories. + See sections +\begin_inset LatexCommand \ref{sub:Install-paths} -\newline +\end_inset -\family sans -\series bold -sdcclib -s libint.lib -\family default +,\SpecialChar ~ -\begin_inset LatexCommand \index{sdcclib} +\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 -\family typewriter -\series default -_divsint.rel: +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 -\family typewriter -__divsint_a_1_1 -\layout Standard +\newline +You might want to look at the files which are installed in . + At the time of this writing, we find the following programs for gcc-builds: +\newline + +\newline +In /bin: +\layout Itemize +sdcc - The compiler. +\layout Itemize -\family typewriter -__divsint_PARM_2 -\layout Standard +sdcpp - The C preprocessor. +\layout Itemize +asx8051 - The assembler for 8051 type processors. +\layout Itemize -\family typewriter -__divsint -\newline -_divuint.rel: -\layout Standard +as-z80 +\series bold +, +\series default +as-gbz80 - The Z80 and GameBoy Z80 assemblers. +\layout Itemize +aslink -The linker for 8051 type processors. +\layout Itemize -\family typewriter -__divuint_a_1_1 -\layout Standard +link-z80 +\series bold +, +\series default +link-gbz80 - The Z80 and GameBoy Z80 linkers. +\layout Itemize +s51 - The ucSim 8051 simulator. + Not available on Win32 platforms. +\layout Itemize -\family typewriter -__divuint_PARM_2 +sdcdb - The source debugger. + Not available on Win32 platforms. +\layout Itemize + +packihx - A tool to pack (compress) Intel hex files. \layout Standard +In /share/sdcc/include +\layout Itemize -\family typewriter -__divuint_reste_1_1 +the include files \layout Standard +In /share/sdcc/lib +\layout Itemize -\family typewriter -__divuint_count_1_1 +the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled + relocatables. \layout Standard +In /share/sdcc/doc +\layout Itemize -\family typewriter -__divuint -\newline -_modsint.rel: +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 -\family typewriter -__modsint_a_1_1 +sdcc - The Compiler \layout Standard +This is the actual compiler, it in turn uses the c-preprocessor and invokes + the assembler and linkage editor. +\layout Subsection -\family typewriter -__modsint_PARM_2 +sdcpp - The C-Preprocessor \layout Standard +The preprocessor +\begin_inset LatexCommand \index{sdcpp (preprocessor)} -\family typewriter -__modsint -\newline -_moduint.rel: -\layout Standard +\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 -\family typewriter -__moduint_a_1_1 +as +\emph on +xxxx +\emph default +, aslink, link- +\emph on +xxx +\emph default + - The Assemblers and Linkage Editors \layout Standard +This is retargettable assembler & linkage editor, it was developed by Alan + Baldwin. + John Hartman created the version for 8051, and I (Sandeep) have made some + enhancements and bug fixes for it to work properly with SDCC. +\layout Subsection -\family typewriter -__moduint_PARM_2 +s51 - The Simulator \layout Standard +S51 +\begin_inset LatexCommand \index{s51} -\family typewriter -__moduint_count_1_1 -\layout Standard +\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} -\family typewriter -__moduint -\newline -_mulint.rel: -\layout Standard +\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 -\family typewriter -__mulint_PARM_2 +sdcdb - Source Level Debugger \layout Standard +Sdcdb +\begin_inset LatexCommand \index{sdcdb (debugger)} -\family typewriter -__mulint -\family default -\series bold - -\newline - -\layout Standard - -If the source files are compiled using - -\begin_inset ERT -status Open +\end_inset -\layout Standard + is the companion source level debugger. + More about sdcdb in section +\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB} -\backslash -/ \end_inset --debug -\begin_inset LatexCommand \index{-\/-debug} +. + The current version of the debugger uses Daniel's Simulator S51 +\begin_inset LatexCommand \index{s51} \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. +, but can be easily changed to use other simulators. + Sdcdb is currently not available on Win32 platfors. +\layout Chapter + +Using SDCC \layout Section -Command Line Options -\begin_inset LatexCommand \index{Command Line Options} +Compiling +\layout Subsection -\end_inset +Single Source File Projects +\layout Standard +For single source file 8051 projects the process is very simple. + Compile your programs with the following command +\family sans +\series bold +"sdcc sourcefile.c". -\layout Subsection +\family default +\series default + This will compile, assemble and link your source file. + Output files are as follows: +\layout Itemize -Processor Selection Options -\begin_inset LatexCommand \index{Options processor selection} +sourcefile.asm +\begin_inset LatexCommand \index{.asm} \end_inset - -\begin_inset LatexCommand \index{Processor selection options} + - Assembler source +\begin_inset LatexCommand \index{Assembler source} \end_inset + file created by the compiler +\layout Itemize -\layout List -\labelwidthstring 00.00.0000 +sourcefile.lst +\begin_inset LatexCommand \index{.lst} +\end_inset -\series bold --mmcs51 -\begin_inset LatexCommand \index{-mmcs51} + - Assembler listing +\begin_inset LatexCommand \index{Assembler listing} \end_inset + file created by the Assembler +\layout Itemize -\series default - Generate code for the Intel MCS51 -\begin_inset LatexCommand \index{MCS51} +sourcefile.rst +\begin_inset LatexCommand \index{.rst} \end_inset - family of processors. - This is the default processor target. -\layout List -\labelwidthstring 00.00.0000 - - -\series bold --mds390 -\begin_inset LatexCommand \index{-mds390} + - Assembler listing +\begin_inset LatexCommand \index{Assembler listing} \end_inset + file updated with linkedit information, created by linkage editor +\layout Itemize -\series default - Generate code for the Dallas DS80C390 -\begin_inset LatexCommand \index{DS80C390} +sourcefile.sym +\begin_inset LatexCommand \index{.sym} \end_inset - processor. -\layout List -\labelwidthstring 00.00.0000 - - -\series bold --mds400 -\begin_inset LatexCommand \index{-mds400} + - 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 Dallas DS80C400 -\begin_inset LatexCommand \index{DS80C400} +sourcefile.rel +\begin_inset LatexCommand \index{.rel} \end_inset - processor. -\layout List -\labelwidthstring 00.00.0000 + or sourcefile.o +\begin_inset LatexCommand \index{.o} +\end_inset -\series bold --mhc08 -\begin_inset LatexCommand \index{-mhc08} + - 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 Freescale/Motorola HC08 -\begin_inset LatexCommand \index{HC08} +sourcefile.map +\begin_inset LatexCommand \index{.map} \end_inset - family of processors. -\layout List -\labelwidthstring 00.00.0000 + - The memory map +\begin_inset LatexCommand \index{Memory map} +\end_inset -\series bold --mz80 -\begin_inset LatexCommand \index{-mz80} + for the load module, created by the Linker +\layout Itemize + +sourcefile.mem +\begin_inset LatexCommand \index{.mem} \end_inset + - A file with a summary of the memory usage +\layout Itemize -\series default - Generate code for the Zilog Z80 -\begin_inset LatexCommand \index{Z80} +sourcefile.ihx +\begin_inset LatexCommand \index{.ihx} \end_inset - family of processors. -\layout List -\labelwidthstring 00.00.0000 + - The load module in Intel hex format +\begin_inset LatexCommand \index{Intel hex format} +\end_inset -\series bold --mgbz80 -\begin_inset LatexCommand \index{-mgbz80} + (you can select the Motorola S19 format +\begin_inset LatexCommand \index{Motorola S19 format} \end_inset + with - +\begin_inset ERT +status Collapsed -\series default - Generate code for the GameBoy Z80 -\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)} +\layout Standard +\backslash +/ \end_inset - processor (Not actively maintained). -\layout List -\labelwidthstring 00.00.0000 +-out-fmt-s19 +\begin_inset LatexCommand \index{-\/-out-fmt-s19} +\end_inset -\series bold --mavr -\begin_inset LatexCommand \index{-mavr} +. + If you need another format you might want to use +\family sans +\shape italic +objdump +\family default +\shape default + +\begin_inset LatexCommand \index{objdump (tool)} \end_inset + or +\family sans +\shape italic + srecord +\family default +\shape default -\series default - Generate code for the Atmel AVR -\begin_inset LatexCommand \index{AVR} +\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)} \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} +). + Both formats are documented in the documentation of srecord +\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)} \end_inset - or -\begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index} -\end_inset +\layout Itemize -. -\layout Comment +sourcefile.adb +\begin_inset LatexCommand \index{.adb} -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 +\end_inset + - An intermediate file containing debug information needed to create the + .cdb file (with - +\begin_inset ERT +status Open -\series bold --mpic14 -\begin_inset LatexCommand \index{-mpic14} +\layout Standard +\backslash +/ \end_inset - -\series default - Generate code for the Microchip PIC 14 -\begin_inset LatexCommand \index{PIC14} +-debug +\begin_inset LatexCommand \index{-\/-debug} \end_inset --bit processors (p16f84 and variants. - In development, not complete). -\layout Comment +) +\layout Itemize -p16f627 p16f628 p16f84 p16f873 p16f877? -\layout List -\labelwidthstring 00.00.0000 +sourcefile.cdb +\begin_inset LatexCommand \index{.cdb} +\end_inset -\series bold --mpic16 -\begin_inset LatexCommand \index{-mpic16} - -\end_inset - + - An optional file (with - +\begin_inset ERT +status Collapsed -\series default - Generate code for the Microchip PIC 16 -\begin_inset LatexCommand \index{PIC16} +\layout Standard +\backslash +/ \end_inset --bit processors (p18f452 and variants. - In development, not complete). -\layout List -\labelwidthstring 00.00.0000 - +-debug) containing debug information. + The format is documented in cdbfileformat.pdf +\layout Itemize -\series bold --mtlcs900h -\series default - Generate code for the Toshiba TLCS-900H -\begin_inset LatexCommand \index{TLCS-900H} +sourcefile. + - (no extension) +\begin_inset LatexCommand \index{ (no extension)} \end_inset - processor (Not maintained, not complete). -\layout List -\labelwidthstring 00.00.0000 - - -\series bold --mxa51 -\begin_inset LatexCommand \index{-mxa51} + An optional AOMF or AOMF51 +\begin_inset LatexCommand \index{AOMF, AOMF51} \end_inset - -\series default - Generate code for the Phillips XA51 -\begin_inset LatexCommand \index{XA51} + +\begin_inset LatexCommand \label{OMF file} \end_inset - processor (Not maintained, not complete). -\layout Subsection +file containing debug information (generated with option - +\begin_inset ERT +status Collapsed -Preprocessor Options -\begin_inset LatexCommand \index{Options preprocessor} +\layout Standard +\backslash +/ \end_inset - -\begin_inset LatexCommand \index{Preprocessor options} +-debug). + The (Intel) +\emph on + a +\emph default +bsolute +\emph on +o +\emph default +bject +\emph on +m +\emph default +odule +\emph on +f +\emph default +ormat is commonly used by third party tools (debuggers +\begin_inset LatexCommand \index{Debugger} \end_inset +, simulators, emulators) +\layout Itemize -\begin_inset LatexCommand \index{sdcpp (preprocessor)} +sourcefile.dump* +\begin_inset LatexCommand \index{.dump*} \end_inset + - Dump file to debug the compiler it self (generated with option - +\begin_inset ERT +status Collapsed -\layout List -\labelwidthstring 00.00.0000 - - -\series bold --I -\begin_inset LatexCommand \index{-I} +\layout Standard +\backslash +/ \end_inset +-dumpall) (see section +\begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options} -\series default - The additional location where the pre processor will look for <..h> or -\begin_inset Quotes eld -\end_inset - -..h -\begin_inset Quotes erd \end_inset - files. -\layout List -\labelwidthstring 00.00.0000 +\SpecialChar ~ + and section +\begin_inset LatexCommand \ref{sub:The-anatomy-of} +\end_inset -\series bold --D -\begin_inset LatexCommand \index{-D} +\SpecialChar ~ +\begin_inset Quotes sld \end_inset +Anatomy of the compiler +\begin_inset Quotes srd +\end_inset -\series default - Command line definition of macros. - Passed to the preprocessor. -\layout List -\labelwidthstring 00.00.0000 +). +\layout Subsection +Projects with Multiple Source Files +\layout Standard -\series bold --M -\begin_inset LatexCommand \index{-M} +SDCC can compile only ONE file at a time. + Let us for example assume that you have a project containing the following + files: +\newline -\end_inset +\newline +foo1.c (contains some functions) +\newline +foo2.c (contains some more functions) +\newline +foomain.c (contains more functions and the function main) +\newline +\size footnotesize -\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} +\newline -\end_inset +\size default +The first two files will need to be compiled separately with the commands: +\size footnotesize + +\size default -'. -\layout List -\labelwidthstring 00.00.0000 +\newline +\newline +\family sans \series bold --C -\begin_inset LatexCommand \index{-C} - -\end_inset - - +sdcc\SpecialChar ~ +-c\SpecialChar ~ +foo1.c +\family default \series default - Tell the preprocessor not to discard comments. - Used with the `-E' option. -\layout List -\labelwidthstring 00.00.0000 +\size footnotesize +\newline +\family sans \series bold --MM -\begin_inset LatexCommand \index{-MM} +\size default +sdcc\SpecialChar ~ +-c\SpecialChar ~ +foo2.c +\family default +\series default -\end_inset +\newline +\newline +Then compile the source file containing the +\emph on +main() +\emph default + function and link +\begin_inset LatexCommand \index{Linker} -\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 ' are omitted. -\layout List -\labelwidthstring 00.00.0000 + the files together with the following command: +\newline +\newline +\family sans \series bold --Aquestion(answer) -\begin_inset LatexCommand \index{-Aquestion(answer)} +sdcc\SpecialChar ~ +foomain.c\SpecialChar ~ +foo1.rel\SpecialChar ~ +foo2.rel +\family default +\series default -\end_inset +\begin_inset LatexCommand \index{.rel} +\end_inset -\series default - Assert the answer answer for question, in case it is tested with a preprocessor - conditional such as `#if #question(answer)'. - `-A-' disables the standard assertions that normally describe the target - machine. -\layout List -\labelwidthstring 00.00.0000 +\newline +\newline +Alternatively, +\emph on +foomain.c +\emph default +can be separately compiled as well: +\family sans \series bold --Umacro -\begin_inset LatexCommand \index{-Umacro} -\end_inset +\newline +\newline +sdcc\SpecialChar ~ +-c\SpecialChar ~ +foomain.c +\newline +sdcc foomain.rel foo1.rel foo2.rel +\newline -\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 - +\newline -\series bold --dM -\begin_inset LatexCommand \index{-dM} +\family default +\series default +The file containing the +\emph on +main() +\emph default + function +\emph on + +\emph default +\noun on +must +\noun default + be the +\noun on +first +\noun default + file specified in the command line, since the linkage editor processes + file in the order they are presented to it. + The linker is invoked from SDCC using a script file with extension .lnk +\begin_inset LatexCommand \index{.lnk} \end_inset +. + You can view this file to troubleshoot linking problems such as those arising + from missing libraries. +\layout Subsection -\series default - Tell the preprocessor to output only a list of the macro definitions that - are in effect at the end of preprocessing. - Used with the `-E' option. -\layout List -\labelwidthstring 00.00.0000 - - -\series bold --dD -\begin_inset LatexCommand \index{-dD} +Projects with Additional Libraries +\begin_inset LatexCommand \index{Libraries} \end_inset -\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 - +\layout Standard -\series bold --dN -\begin_inset LatexCommand \index{-dN} +Some reusable routines may be compiled into a library, see the documentation + for the assembler and linkage editor (which are in /share/sdcc/doc) + for how to create a +\emph on +.lib +\begin_inset LatexCommand \index{.lib} \end_inset -\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 +\emph default + library file. + Libraries created in this manner can be included in the command line. + Make sure you include the -L option to tell the linker where + to look for these files if they are not in the current directory. + Here is an example, assuming you have the source file +\emph on +foomain.c +\emph default + and a library +\emph on + foolib.lib +\emph default + in the directory +\emph on +mylib +\emph default + (if that is not the same as your current project): +\newline +\newline +\family sans \series bold --Wp\SpecialChar ~ -preprocessorOption[,preprocessorOption] -\series default - -\begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]} +sdcc foomain.c foolib.lib -L mylib +\newline -\end_inset +\newline -... - Pass the preprocessorOption to the preprocessor -\family typewriter -sdcpp \family default +\series default +Note here that +\emph on + mylib +\emph default + must be an absolute path name. +\newline -\begin_inset LatexCommand \index{sdcpp (preprocessor)} +\newline +The most efficient way to use libraries is to keep separate modules in separate + source files. + The lib file now should name all the modules.rel +\begin_inset LatexCommand \index{.rel} \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/} + files. + For an example see the standard library file +\emph on +libsdcc.lib +\emph default + in the directory /share/lib/small. +\layout Subsection + +Using sdcclib to Create and Manage Libraries +\begin_inset LatexCommand \index{sdcclib} \end_inset -. -\layout Subsection -Linker Options -\begin_inset LatexCommand \index{Options linker} +\layout Standard -\end_inset +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 -\begin_inset LatexCommand \index{Linker options} + +\family sans +\series bold +sdcclib -? +\begin_inset LatexCommand \index{sdcclib} \end_inset -\layout List -\labelwidthstring 00.00.0000 +\newline +\newline -\series bold --L\SpecialChar ~ -- +\family default \series default - -\begin_inset ERT -status Collapsed +To create a new library file, start by compiling all the required modules. + For example: +\newline \layout Standard -\backslash -/ -\end_inset - +\family sans \series bold --lib-path -\begin_inset LatexCommand \index{-\/-lib-path } - -\end_inset - +sdcc -c _divsint.c +\layout Standard -\begin_inset LatexCommand \index{-L -\/-lib-path} -\end_inset +\family sans +\series bold +sdcc -c _divuint.c +\layout Standard -\series default -\SpecialChar ~ - This option is passed to the linkage - editor's additional libraries -\begin_inset LatexCommand \index{Libraries} +\family sans +\series bold +sdcc -c _modsint.c +\layout Standard -\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 +\family sans +\series bold +sdcc -c _moduint.c +\layout Standard +\family sans \series bold -- -\begin_inset ERT -status Collapsed +sdcc -c _mulint.c +\newline \layout Standard -\backslash -/ -\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 --xram-loc -\series default +\layout Standard -\begin_inset LatexCommand \index{-\/-xram-loc } -\end_inset +\family sans +\series bold +sdcclib libint.lib _divsint.rel +\family default -\SpecialChar ~ - The start location of the external ram -\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} +\begin_inset LatexCommand \index{sdcclib} \end_inset -, 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 +\family sans +\series bold +sdcclib libint.lib _divuint.rel \layout Standard -\backslash -/ -\end_inset --xram-loc 32768. -\layout List -\labelwidthstring 00.00.0000 +\family sans +\series bold +sdcclib libint.lib _modsint.rel +\layout Standard +\family sans \series bold -- -\begin_inset ERT -status Collapsed - +sdcclib libint.lib _moduint.rel \layout Standard -\backslash -/ -\end_inset --code-loc +\family sans +\series bold +sdcclib libint.lib _mulint.rel \series default -\begin_inset LatexCommand \index{-\/-code-loc } +\newline -\end_inset +\layout Standard -\SpecialChar ~ - The start location of the code -\begin_inset LatexCommand \index{code} +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 -\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 sans +\series bold +sdcclib -s libint.lib +\family default -\layout Standard +\begin_inset LatexCommand \index{sdcclib} -\backslash -/ \end_inset --code-loc 0x8000 or - -\begin_inset ERT -status Collapsed -\layout Standard +\newline -\backslash -/ -\end_inset +\family typewriter +\series default +_divsint.rel: +\layout Standard --code-loc 32768. -\layout List -\labelwidthstring 00.00.0000 +\family typewriter +__divsint_a_1_1 +\layout Standard -\series bold -- -\begin_inset ERT -status Collapsed +\family typewriter +__divsint_PARM_2 \layout Standard -\backslash -/ -\end_inset --stack-loc -\series default +\family typewriter +__divsint +\newline +_divuint.rel: +\layout Standard -\begin_inset LatexCommand \index{-\/-stack-loc } -\end_inset +\family typewriter +__divuint_a_1_1 +\layout Standard -\SpecialChar ~ - By default the stack -\begin_inset LatexCommand \index{stack} -\end_inset +\family typewriter +__divuint_PARM_2 +\layout Standard - 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 +\family typewriter +__divuint_reste_1_1 \layout Standard -\backslash -/ -\end_inset --stack-loc 0x20 or - -\begin_inset ERT -status Collapsed +\family typewriter +__divuint_count_1_1 +\layout Standard + +\family typewriter +__divuint +\newline +_modsint.rel: \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 -status Collapsed +\family typewriter +__modsint_a_1_1 +\layout Standard + +\family typewriter +__modsint_PARM_2 \layout Standard -\backslash -/ -\end_inset --pack-iram -\series default -\SpecialChar ~ +\family typewriter +__modsint +\newline +_moduint.rel: +\layout Standard -\begin_inset LatexCommand \index{-\/-pack-iram} -\end_inset +\family typewriter +__moduint_a_1_1 +\layout Standard - option (which is now a default setting) will override this setting, so - you should also specify the -\series bold -- -\begin_inset ERT -status Collapsed +\family typewriter +__moduint_PARM_2 \layout Standard -\backslash -/ -\end_inset --no-pack-iram -\series default -\SpecialChar ~ +\family typewriter +__moduint_count_1_1 +\layout Standard -\begin_inset LatexCommand \index{-\/-no-pack-iram} -\end_inset +\family typewriter +__moduint +\newline +_mulint.rel: +\layout Standard - option if you need to manually place the stack. -\layout List -\labelwidthstring 00.00.0000 + +\family typewriter +__mulint_PARM_2 +\layout Standard +\family typewriter +__mulint +\family default \series bold -- + +\newline + +\layout Standard + +If the source files are compiled using - \begin_inset ERT -status Collapsed +status Open \layout Standard @@ -5746,583 +5518,511 @@ status Collapsed / \end_inset --data-loc -\series default - -\begin_inset LatexCommand \index{-\/-data-loc } - -\end_inset - -\SpecialChar ~ - The start location of the internal ram data -\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)} +-debug +\begin_inset LatexCommand \index{-\/-debug} \end_inset - segment. - The value entered can be in Hexadecimal or Decimal format, eg. - - -\begin_inset ERT -status Collapsed +, 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 -\layout Standard +Command Line Options +\begin_inset LatexCommand \index{Command Line Options} -\backslash -/ \end_inset --data-loc 0x20 or - -\begin_inset ERT -status Collapsed -\layout Standard +\layout Subsection + +Processor Selection Options +\begin_inset LatexCommand \index{Options processor selection} -\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 -\layout Standard +\begin_inset LatexCommand \index{Processor selection options} -\backslash -/ \end_inset --data-loc is not used, to location 0x10.) + \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-mmcs51 +\begin_inset LatexCommand \index{-mmcs51} -\backslash -/ \end_inset --idata-loc -\series default -\begin_inset LatexCommand \index{-\/-idata-loc } +\series default + Generate code for the Intel MCS51 +\begin_inset LatexCommand \index{MCS51} \end_inset -\SpecialChar ~ - The start location of the indirectly addressable internal ram -\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)} - -\end_inset + family of processors. + This is the default processor target. +\layout List +\labelwidthstring 00.00.0000 - of the 8051, default value is 0x80. - The value entered can be in Hexadecimal or Decimal format, eg. - - -\begin_inset ERT -status Collapsed -\layout Standard +\series bold +-mds390 +\begin_inset LatexCommand \index{-mds390} -\backslash -/ \end_inset --idata-loc 0x88 or - -\begin_inset ERT -status Collapsed -\layout Standard +\series default + Generate code for the Dallas DS80C390 +\begin_inset LatexCommand \index{DS80C390} -\backslash -/ \end_inset --idata-loc 136. + processor. \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-mds400 +\begin_inset LatexCommand \index{-mds400} -\backslash -/ \end_inset --bit-loc + \series default -\SpecialChar ~ - The start location of the bit -\begin_inset LatexCommand \index{bit} + Generate code for the Dallas DS80C400 +\begin_inset LatexCommand \index{DS80C400} \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=. + processor. \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard - -\backslash -/ -\end_inset - --out-fmt-ihx -\begin_inset LatexCommand \index{-\/-out-fmt-ihx} +-mhc08 +\begin_inset LatexCommand \index{-mhc08} \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} - -\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)} + Generate code for the Freescale/Motorola HC08 +\begin_inset LatexCommand \index{HC08} \end_inset -. + family of processors. \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} +-mz80 +\begin_inset LatexCommand \index{-mz80} \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 Zilog Z80 +\begin_inset LatexCommand \index{Z80} \end_inset -. - The format itself is documented in the documentation of srecord. + family of processors. \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} +-mgbz80 +\begin_inset LatexCommand \index{-mgbz80} \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 GameBoy Z80 +\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)} \end_inset -. - (Currently only supported for the HC08 processors) + processor (Not actively maintained). \layout List \labelwidthstring 00.00.0000 \series bold --Wl\SpecialChar ~ -linkOption[,linkOption] -\series default - -\begin_inset LatexCommand \index{-Wl linkOption[,linkOption]} +-mavr +\begin_inset LatexCommand \index{-mavr} \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} +\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 -\begin_inset LatexCommand \index{MCS51 options} + or +\begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index} \end_inset +. +\layout Comment +I think it is fair to direct users there for now. + Open source is also about avoiding unnecessary work . + But I didn't find the 'official' link. \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-mpic14 +\begin_inset LatexCommand \index{-mpic14} -\backslash -/ \end_inset --model-small -\begin_inset LatexCommand \index{-\/-model-small} + +\series default + Generate code for the Microchip PIC 14 +\begin_inset LatexCommand \index{PIC14} \end_inset +-bit processors (p16f84 and variants. + In development, not complete). +\layout Comment -\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. +p16f627 p16f628 p16f84 p16f873 p16f877? \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-mpic16 +\begin_inset LatexCommand \index{-mpic16} -\backslash -/ \end_inset --model-large -\begin_inset LatexCommand \index{-\/-model-large} -\end_inset +\series default + Generate code for the Microchip PIC 16 +\begin_inset LatexCommand \index{PIC16} +\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. +-bit processors (p18f452 and variants. + In development, not complete). \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-mtlcs900h +\series default + Generate code for the Toshiba TLCS-900H +\begin_inset LatexCommand \index{TLCS-900H} -\backslash -/ \end_inset --xstack -\begin_inset LatexCommand \index{-\/-xstack} + processor (Not maintained, not complete). +\layout List +\labelwidthstring 00.00.0000 + + +\series bold +-mxa51 +\begin_inset LatexCommand \index{-mxa51} \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} + Generate code for the Phillips XA51 +\begin_inset LatexCommand \index{XA51} \end_inset -\SpecialChar ~ - External Stack for more details. -\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 --iram-size -\series default -\SpecialChar ~ - -\begin_inset LatexCommand \index{-\/-iram-size } + +\begin_inset LatexCommand \index{sdcpp (preprocessor)} \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 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-I +\begin_inset LatexCommand \index{-I} -\backslash -/ \end_inset --xram-size + \series default -\SpecialChar ~ - -\begin_inset LatexCommand \index{-\/-xram-size } + 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 check if the external ram usage is within limits of - the given value. + files. \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-D +\begin_inset LatexCommand \index{-D} -\backslash -/ \end_inset --code-size -\series default -\SpecialChar ~ - -\begin_inset LatexCommand \index{-\/-code-size } - -\end_inset - Causes the linker to check if the code memory usage is within limits of - the given value. +\series default + Command line definition of macros. + Passed to the preprocessor. \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-M +\begin_inset LatexCommand \index{-M} -\backslash -/ \end_inset --stack-size + \series default -\SpecialChar ~ - -\begin_inset LatexCommand \index{-\/-stack-size } + 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 - Causes the linker to check if there is at minimum bytes for stack. +'. \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-C +\begin_inset LatexCommand \index{-C} -\backslash -/ \end_inset --pack-iram + \series default -\SpecialChar ~ + Tell the preprocessor not to discard comments. + Used with the `-E' option. +\layout List +\labelwidthstring 00.00.0000 -\begin_inset LatexCommand \index{-\/-pack-iram} + +\series bold +-MM +\begin_inset LatexCommand \index{-MM} \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. + +\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 ' 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 --no-pack-iram + \series default -\SpecialChar ~ + 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 -\begin_inset LatexCommand \index{-\/-no-pack-iram} -\end_inset +\series bold +-Umacro +\begin_inset LatexCommand \index{-Umacro} - Causes the linker to use old style for allocating memory areas. -\layout Subsection +\end_inset -DS390 / DS400 Options -\begin_inset LatexCommand \index{Options DS390} -\end_inset +\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 -\begin_inset LatexCommand \index{DS390 options} +\series bold +-dM +\begin_inset LatexCommand \index{-dM} \end_inset +\series default + Tell the preprocessor to output only a list of the macro definitions that + are in effect at the end of preprocessing. + Used with the `-E' option. \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed - -\layout Standard +-dD +\begin_inset LatexCommand \index{-dD} -\backslash -/ \end_inset --model-flat24 + \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 -\begin_inset LatexCommand \index{-\/-model-flat24} + +\series bold +-dN +\begin_inset LatexCommand \index{-dN} \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 `-dD' except that the macro arguments and contents are omitted. + Only `#define name' is included in the output. \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed +-Wp\SpecialChar ~ +preprocessorOption[,preprocessorOption] +\series default -\layout Standard +\begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]} -\backslash -/ \end_inset --protect-sp-update -\begin_inset LatexCommand \index{-\/-protect-sp-update} +... + Pass the preprocessorOption to the preprocessor +\family typewriter +sdcpp +\family default + +\begin_inset LatexCommand \index{sdcpp (preprocessor)} + +\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 + +. +\layout Subsection + +Linker Options +\begin_inset LatexCommand \index{Options linker} + +\end_inset + + +\begin_inset LatexCommand \index{Linker options} \end_inset -\series default - disable interrupts during ESP:SP updates. \layout List \labelwidthstring 00.00.0000 \series bold +-L\SpecialChar ~ - +\series default + \begin_inset ERT status Collapsed @@ -6332,34 +6032,36 @@ status Collapsed / \end_inset --stack-10bit -\series default -\begin_inset LatexCommand \index{-\/-stack-10bit} +\series bold +-lib-path +\begin_inset LatexCommand \index{-\/-lib-path } \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 LatexCommand \index{-L -\/-lib-path} + +\end_inset + + +\series default +\SpecialChar ~ + 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 + + +\series bold - \begin_inset ERT status Collapsed @@ -6370,17 +6072,21 @@ status Collapsed / \end_inset --stack-auto -\begin_inset LatexCommand \index{-\/-stack-auto} +-xram-loc +\series default + +\begin_inset LatexCommand \index{-\/-xram-loc } \end_inset +\SpecialChar ~ + The start location of the external ram +\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} -\emph default - option, but that has not been tested. - It is incompatible with the -\emph on -- +\end_inset + +, default value is 0. + The value entered can be in Hexadecimal or Decimal format, e.g.: - \begin_inset ERT status Collapsed @@ -6390,18 +6096,7 @@ status Collapsed / \end_inset --xstack -\begin_inset LatexCommand \index{-\/-xstack} - -\end_inset - - -\emph default - option. - It also only makes sense if the processor is in 24 bit contiguous addressing - mode (see the -\emph on -- +-xram-loc 0x8000 or - \begin_inset ERT status Collapsed @@ -6411,9 +6106,7 @@ status Collapsed / \end_inset --model-flat24 option -\emph default -). +-xram-loc 32768. \layout List \labelwidthstring 00.00.0000 @@ -6429,20 +6122,23 @@ status Collapsed / \end_inset --stack-probe -\begin_inset LatexCommand \index{-\/-stack-probe} +-code-loc +\series default -\end_inset +\begin_inset LatexCommand \index{-\/-code-loc } +\end_inset -\series default - insert call to function __stack_probe at each function prologue. -\layout List -\labelwidthstring 00.00.0000 +\SpecialChar ~ + The start location of the code +\begin_inset LatexCommand \index{code} +\end_inset -\series bold -- + segment, default value 0. + Note when this option is used the interrupt vector table is also relocated + to the given address. + The value entered can be in Hexadecimal or Decimal format, e.g.: - \begin_inset ERT status Collapsed @@ -6452,15 +6148,17 @@ status Collapsed / \end_inset --tini-libid -\begin_inset LatexCommand \index{-\/-tini-libid} +-code-loc 0x8000 or - +\begin_inset ERT +status Collapsed -\end_inset +\layout Standard +\backslash +/ +\end_inset -\series default - LibraryID used in -mTININative. - +-code-loc 32768. \layout List \labelwidthstring 00.00.0000 @@ -6476,34 +6174,24 @@ status Collapsed / \end_inset --use-accelerator -\begin_inset LatexCommand \index{-\/-use-accelerator} - -\end_inset - - +-stack-loc \series default - generate code for DS390 Arithmetic Accelerator. - -\layout Subsection -Z80 Options -\begin_inset LatexCommand \index{Options Z80} +\begin_inset LatexCommand \index{-\/-stack-loc } \end_inset - -\begin_inset LatexCommand \index{Z80 options} +\SpecialChar ~ + By default the stack +\begin_inset LatexCommand \index{stack} \end_inset - -\layout List -\labelwidthstring 00.00.0000 - - -\series bold -- + is placed after the data segment. + Using this option the stack can be placed anywhere in the internal memory + space of the 8051. + The value entered can be in Hexadecimal or Decimal format, e.g. + - \begin_inset ERT status Collapsed @@ -6513,24 +6201,23 @@ status Collapsed / \end_inset --callee-saves-bc -\series default +-stack-loc 0x20 or - +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \index{-\/-callee-saves-bc} +\layout Standard +\backslash +/ \end_inset - -\size large -\emph on - -\size default -\emph default -Force a called function to always save BC. -\layout List -\labelwidthstring 00.00.0000 - - +-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 @@ -6542,29 +6229,36 @@ status Collapsed / \end_inset --no-std-crt0 +-pack-iram \series default +\SpecialChar ~ -\begin_inset LatexCommand \index{-\/-no-std-crt0} +\begin_inset LatexCommand \index{-\/-pack-iram} \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 + option (which is now a default setting) will override this setting, so + you should also specify the +\series bold +- +\begin_inset ERT +status Collapsed -Optimization Options -\begin_inset LatexCommand \index{Options optimization} +\layout Standard +\backslash +/ \end_inset +-no-pack-iram +\series default +\SpecialChar ~ -\begin_inset LatexCommand \index{Optimization options} +\begin_inset LatexCommand \index{-\/-no-pack-iram} \end_inset - + option if you need to manually place the stack. \layout List \labelwidthstring 00.00.0000 @@ -6580,43 +6274,46 @@ status Collapsed / \end_inset --nogcse -\begin_inset LatexCommand \index{-\/-nogcse} +-xstack-loc +\series default -\end_inset +\begin_inset LatexCommand \index{-\/-xstack-loc } +\end_inset -\series default - Will not do global subexpression elimination, this option may be used when - the compiler creates undesirably large stack/data spaces to store compiler - temporaries ( -\emph on -s -\emph default -pill -\emph on -loc -\emph default -ations, sloc -\begin_inset LatexCommand \index{sloc (spill location)} +\SpecialChar ~ + By default the external stack +\begin_inset LatexCommand \index{xstack} \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} + 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 + +\layout Standard +\backslash +/ \end_inset - can be used to turn off global subexpression elimination -\begin_inset LatexCommand \index{Subexpression elimination} +-xstack-loc 0x8000 or - +\begin_inset ERT +status Collapsed + +\layout Standard +\backslash +/ \end_inset - 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 @@ -6632,35 +6329,22 @@ status Collapsed / \end_inset --noinvariant -\begin_inset LatexCommand \index{-\/-noinvariant} +-data-loc +\series default + +\begin_inset LatexCommand \index{-\/-data-loc } \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} - -\end_inset - -. - It is recommended that this option NOT be used, #pragma\SpecialChar ~ -noinvariant -\begin_inset LatexCommand \index{\#pragma noinvariant} +\SpecialChar ~ + 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 invariant optimizations 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 @@ -6670,22 +6354,32 @@ status Collapsed / \end_inset --noinduction -\begin_inset LatexCommand \index{-\/-noinduction} +-data-loc 0x20 or - +\begin_inset ERT +status Collapsed + +\layout Standard +\backslash +/ \end_inset +-data-loc 32. + (By default, the start location of the internal ram data segment is set + as low as possible in memory, taking into account the used register banks + and the bit segment at address 0x20. + For example if register banks 0 and 1 are used without bit variables, the + data segment will be set, if - +\begin_inset ERT +status Collapsed -\series default - 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. +-data-loc is not used, to location 0x10.) \layout List \labelwidthstring 00.00.0000 @@ -6701,45 +6395,22 @@ status Collapsed / \end_inset --nojtbound -\begin_inset LatexCommand \index{-\/-nojtbound} - -\end_inset - - -\size large -\bar under - +-idata-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{-\/-idata-loc } \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} + The start location of the indirectly addressable internal ram +\begin_inset LatexCommand \index{idata (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 -- + of the 8051, default value is 0x80. + The value entered can be in Hexadecimal or Decimal format, eg. + - \begin_inset ERT status Collapsed @@ -6749,25 +6420,22 @@ status Collapsed / \end_inset --noloopreverse -\begin_inset LatexCommand \index{-\/-noloopreverse} - -\end_inset - +-idata-loc 0x88 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. +-idata-loc 136. \layout List \labelwidthstring 00.00.0000 + +\series bold - \begin_inset ERT status Collapsed @@ -6778,16 +6446,22 @@ status Collapsed / \end_inset -- -\series bold -nolabelopt +-bit-loc \series default - -\begin_inset LatexCommand \index{-\/-nolabelopt } +\SpecialChar ~ + The start location of the bit +\begin_inset LatexCommand \index{bit} \end_inset -Will not optimize labels (makes the dumpfiles more readable). + 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=. \layout List \labelwidthstring 00.00.0000 @@ -6803,16 +6477,24 @@ status Collapsed / \end_inset --no-xinit-opt -\begin_inset LatexCommand \index{-\/-no-xinit-opt} +-out-fmt-ihx +\begin_inset LatexCommand \index{-\/-out-fmt-ihx} \end_inset +\bar under + \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} +\bar default +The linker output (final object code) is in Intel Hex format. +\begin_inset LatexCommand \index{Intel hex format} + +\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 @@ -6832,15 +6514,23 @@ status Collapsed / \end_inset --nooverlay -\begin_inset LatexCommand \index{-\/-nooverlay} +-out-fmt-s19 +\begin_inset LatexCommand \index{-\/-out-fmt-s19} \end_inset +\bar under + \series default - The compiler will not overlay parameters and local variables of any function, - see section Parameters and local variables for more details. +\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 @@ -6856,46 +6546,52 @@ status Collapsed / \end_inset --no-peep -\begin_inset LatexCommand \index{-\/-no-peep} +-out-fmt-elf +\begin_inset LatexCommand \index{-\/-out-fmt-s19} \end_inset +\bar under + \series default - Disable peep-hole optimization. +\bar default +The linker output (final object code) is in ELF format +\begin_inset LatexCommand \index{ELF format} + +\end_inset + +. + (Currently only supported for the HC08 processors) \layout List \labelwidthstring 00.00.0000 \series bold -- -\begin_inset ERT -status Collapsed +-Wl\SpecialChar ~ +linkOption[,linkOption] +\series default -\layout Standard +\begin_inset LatexCommand \index{-Wl linkOption[,linkOption]} -\backslash -/ \end_inset --peep-file -\series default +... + Pass the linkOption to the linker. + See file sdcc/as/doc/asxhtm.html for more on linker options. +\layout Subsection -\begin_inset LatexCommand \index{-\/-peep-file} +MCS51 Options +\begin_inset LatexCommand \index{Options MCS51} \end_inset -\SpecialChar ~ - 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} + +\begin_inset LatexCommand \index{MCS51 options} \end_inset -\SpecialChar ~ -Peep Hole optimizations for details on how to write these rules. + \layout List \labelwidthstring 00.00.0000 @@ -6911,22 +6607,21 @@ status Collapsed / \end_inset --peep-asm -\begin_inset LatexCommand \index{-\/-peep-asm} +-model-small +\begin_inset LatexCommand \index{-\/-model-small} \end_inset \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 '/peeph.def' before using - this option. +\size large +\emph on + +\size default +\emph default +Generate code for Small Model programs, see section Memory Models for more + details. + This is the default model. \layout List \labelwidthstring 00.00.0000 @@ -6942,15 +6637,18 @@ status Collapsed / \end_inset --opt-code-speed -\begin_inset LatexCommand \index{-\/-opt-code-speed} +-model-medium +\begin_inset LatexCommand \index{-\/-model-medium} \end_inset \series default - The compiler will optimize code generation towards fast code, possibly - at the expense of code size. + Generate code for Medium model programs, see section Memory Models for + more details. + If this option is used all source files in the project have to be compiled + with this option. + It must also be used when invoking the linker. \layout List \labelwidthstring 00.00.0000 @@ -6966,29 +6664,23 @@ status Collapsed / \end_inset --opt-code-size -\begin_inset LatexCommand \index{-\/-opt-code-size} +-model-large +\begin_inset LatexCommand \index{-\/-model-large} \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} - -\end_inset - - + 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 --c\SpecialChar ~ - \begin_inset ERT status Collapsed @@ -6999,27 +6691,28 @@ status Collapsed / \end_inset --compile-only -\begin_inset LatexCommand \index{-\/-compile-only} +-xstack +\begin_inset LatexCommand \index{-\/-xstack} \end_inset -\begin_inset LatexCommand \index{-c -\/-compile-only} +\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} \end_inset - -\series default - will compile and assemble the source, but will not call the linkage editor. +\SpecialChar ~ + External Stack for more details. \layout List \labelwidthstring 00.00.0000 \series bold - -\series default - \begin_inset ERT status Collapsed @@ -7029,50 +6722,41 @@ status Collapsed / \end_inset - -\series bold --c1mode -\begin_inset LatexCommand \index{-\/-c1mode} +-iram-size +\series default +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-iram-size } \end_inset - -\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. + Causes the linker to check if the internal ram usage is within limits of + the given value. \layout List \labelwidthstring 00.00.0000 \series bold --E -\begin_inset LatexCommand \index{-E} +- +\begin_inset ERT +status Collapsed -\end_inset +\layout Standard +\backslash +/ +\end_inset +-xram-size \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 ~ - -\begin_inset LatexCommand \index{-o } +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-xram-size } \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. - + Causes the linker to check if the external ram usage is within limits of + the given value. \layout List \labelwidthstring 00.00.0000 @@ -7088,44 +6772,16 @@ status Collapsed / \end_inset --stack-auto -\begin_inset LatexCommand \index{-\/-stack-auto} - -\end_inset - - +-code-size \series default -\size large -\emph on - -\size default -\emph default -All functions in the source file will be compiled as -\emph on -reentrant -\emph default - -\begin_inset LatexCommand \index{reentrant} - -\end_inset - -, 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} +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-code-size } \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. - + Causes the linker to check if the code memory usage is within limits of + the given value. \layout List \labelwidthstring 00.00.0000 @@ -7141,48 +6797,21 @@ status Collapsed / \end_inset --callee-saves -\begin_inset LatexCommand \index{-\/-callee-saves} - -\end_inset - - function1[,function2][,function3].... - +-stack-size \series default - The compiler by default uses a caller saves convention for register saving - across function calls, however this can cause unnecessary register pushing - & popping when calling small functions from larger functions. - This option can be used to switch the register saving convention for the - function names specified. - The compiler will not save registers when calling these functions, no extra - code will be generated at the entry & exit (function prologue -\series bold - -\begin_inset LatexCommand \index{function prologue} +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-stack-size } \end_inset - -\series default - & epilogue -\series bold - -\begin_inset LatexCommand \index{function epilogue} - -\end_inset + Causes the linker to check if there is at minimum bytes for stack. +\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 @@ -7192,14 +6821,17 @@ status Collapsed / \end_inset --callee-saves option string. - Also see #pragma\SpecialChar ~ -callee_saves -\begin_inset LatexCommand \index{\#pragma callee\_saves} +-pack-iram +\series default +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-pack-iram} \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. \layout List \labelwidthstring 00.00.0000 @@ -7215,45 +6847,28 @@ status Collapsed / \end_inset --debug -\begin_inset LatexCommand \index{-\/-debug} +-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 -\bar under - -\series default -\bar default -When this option is used the compiler will generate debug information. - The debug information collected in a file with .cdb extension can be used - with the SDCDB. - For more information see documentation for SDCDB. - Another file with no extension contains debug information in AOMF or AOMF51 -\begin_inset LatexCommand \index{AOMF, AOMF51} +DS390 / DS400 Options +\begin_inset LatexCommand \index{Options DS390} \end_inset - format which is commonly used by third party tools. -\layout List -\labelwidthstring 00.00.0000 - -\series bold --S -\begin_inset LatexCommand \index{-S} +\begin_inset LatexCommand \index{DS390 options} \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 @@ -7269,16 +6884,27 @@ status Collapsed / \end_inset --int-long-reent -\begin_inset LatexCommand \index{-\/-int-long-reent} +-model-flat24 +\series default + +\begin_inset LatexCommand \index{-\/-model-flat24} \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. +\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 @@ -7294,34 +6920,14 @@ status Collapsed / \end_inset --cyclomatic -\begin_inset LatexCommand \index{-\/-cyclomatic} +-protect-sp-update +\begin_inset LatexCommand \index{-\/-protect-sp-update} \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. + disable interrupts during ESP:SP updates. \layout List \labelwidthstring 00.00.0000 @@ -7337,25 +6943,54 @@ status Collapsed / \end_inset --float-reent -\begin_inset LatexCommand \index{-\/-float-reent} - -\end_inset - - +-stack-10bit \series default - Floating point library is compiled as reentrant -\begin_inset LatexCommand \index{reentrant} + +\begin_inset LatexCommand \index{-\/-stack-10bit} \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 . - See section Installation for more details. -\layout List -\labelwidthstring 00.00.0000 + 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 bold +\backslash +/ +\end_inset + +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} + +\end_inset + + +\emph default + option, but that has not been tested. + It is incompatible with the +\emph on - \begin_inset ERT status Collapsed @@ -7366,29 +7001,30 @@ status Collapsed / \end_inset --main-return -\begin_inset LatexCommand \index{-\/-main-return} +-xstack +\begin_inset LatexCommand \index{-\/-xstack} \end_inset -\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} +\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 +\backslash +/ \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 -'. +-model-flat24 option +\emph default +). \layout List \labelwidthstring 00.00.0000 @@ -7404,15 +7040,14 @@ status Collapsed / \end_inset --nostdinc -\begin_inset LatexCommand \index{-\/-nostdinc} +-stack-probe +\begin_inset LatexCommand \index{-\/-stack-probe} \end_inset \series default - This will prevent the compiler from passing on the default include path - to the preprocessor. + insert call to function __stack_probe at each function prologue. \layout List \labelwidthstring 00.00.0000 @@ -7428,19 +7063,15 @@ status Collapsed / \end_inset --nostdlib -\begin_inset LatexCommand \index{-\/-nostdlib} +-tini-libid +\begin_inset LatexCommand \index{-\/-tini-libid} \end_inset \series default - This will prevent the compiler from passing on the default library -\begin_inset LatexCommand \index{Libraries} - -\end_inset - - path to the linker. + LibraryID used in -mTININative. + \layout List \labelwidthstring 00.00.0000 @@ -7456,27 +7087,28 @@ status Collapsed / \end_inset --verbose -\begin_inset LatexCommand \index{-\/-verbose} +-use-accelerator +\begin_inset LatexCommand \index{-\/-use-accelerator} \end_inset \series default - Shows the various actions the compiler is performing. -\layout List -\labelwidthstring 00.00.0000 + generate code for DS390 Arithmetic Accelerator. + +\layout Subsection +Z80 Options +\begin_inset LatexCommand \index{Options Z80} -\series bold --V -\begin_inset LatexCommand \index{-V} +\end_inset + + +\begin_inset LatexCommand \index{Z80 options} \end_inset -\series default - Shows the actual commands the compiler is executing. \layout List \labelwidthstring 00.00.0000 @@ -7492,15 +7124,20 @@ status Collapsed / \end_inset --no-c-code-in-asm -\begin_inset LatexCommand \index{-\/-no-c-code-in-asm} +-callee-saves-bc +\series default + +\begin_inset LatexCommand \index{-\/-callee-saves-bc} \end_inset -\series default - Hides your ugly and inefficient c-code from the asm file, so you can always - blame the compiler :) +\size large +\emph on + +\size default +\emph default +Force a called function to always save BC. \layout List \labelwidthstring 00.00.0000 @@ -7516,14 +7153,29 @@ status Collapsed / \end_inset --no-peep-comments -\begin_inset LatexCommand \index{-\/-no-peep-comments} +-no-std-crt0 +\series default + +\begin_inset LatexCommand \index{-\/-no-std-crt0} + +\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} + +\end_inset + + +\begin_inset LatexCommand \index{Optimization options} \end_inset -\series default - Will not include peep-hole comments in the generated files. \layout List \labelwidthstring 00.00.0000 @@ -7539,15 +7191,43 @@ status Collapsed / \end_inset --i-code-in-asm -\begin_inset LatexCommand \index{-\/-i-code-in-asm} +-nogcse +\begin_inset LatexCommand \index{-\/-nogcse} \end_inset \series default - Include i-codes in the asm file. - Sounds like noise but is most helpful for debugging the compiler itself. + 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 + +). + A warning message will be generated when this happens and the compiler + will indicate the number of extra bytes it allocated. + It is recommended that this option NOT be used, #pragma\SpecialChar ~ +nogcse +\begin_inset LatexCommand \index{\#pragma nogcse} + +\end_inset + + can be used to turn off global subexpression elimination +\begin_inset LatexCommand \index{Subexpression elimination} + +\end_inset + + for a given function only. \layout List \labelwidthstring 00.00.0000 @@ -7563,19 +7243,29 @@ status Collapsed / \end_inset --less-pedantic -\begin_inset LatexCommand \index{-\/-less-pedantic} +-noinvariant +\begin_inset LatexCommand \index{-\/-noinvariant} \end_inset \series default - Disable some of the more pedantic warnings -\begin_inset LatexCommand \index{Warnings} + 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 - (jwk burps: please be more specific here, please!). +. + 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 @@ -7591,15 +7281,22 @@ status Collapsed / \end_inset --disable-warning\SpecialChar ~ - -\begin_inset LatexCommand \index{-\/-disable-warning} +-noinduction +\begin_inset LatexCommand \index{-\/-noinduction} \end_inset \series default - Disable specific warning with number . + 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 @@ -7615,14 +7312,39 @@ status Collapsed / \end_inset --print-search-dirs -\begin_inset LatexCommand \index{-\/-print-search-dirs} +-nojtbound +\begin_inset LatexCommand \index{-\/-nojtbound} \end_inset +\size large +\bar under + \series default - Display the directories in the compiler's search path +\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 @@ -7638,20 +7360,25 @@ status Collapsed / \end_inset --vc -\begin_inset LatexCommand \index{-\/-vc} +-noloopreverse +\begin_inset LatexCommand \index{-\/-noloopreverse} \end_inset \series default - Display errors and warnings using MSVC style, so you can use SDCC with - visual studio. +\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 @@ -7662,40 +7389,45 @@ status Collapsed / \end_inset --use-stdout -\begin_inset LatexCommand \index{-\/-use-stdout} +- +\series bold +nolabelopt +\series default + +\begin_inset LatexCommand \index{-\/-nolabelopt } \end_inset - -\series default - Send errors and warnings to stdout instead of stderr. +Will not optimize labels (makes the dumpfiles more readable). \layout List \labelwidthstring 00.00.0000 \series bold --Wa\SpecialChar ~ -asmOption[,asmOption] -\series default +- +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \index{-Wa asmOption[,asmOption]} +\layout Standard +\backslash +/ \end_inset -... - Pass the asmOption to the assembler -\begin_inset LatexCommand \index{Options assembler} +-no-xinit-opt +\begin_inset LatexCommand \index{-\/-no-xinit-opt} \end_inset -\begin_inset LatexCommand \index{Assembler options} +\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 . - See file sdcc/as/doc/asxhtm.html for assembler options.cd \layout List \labelwidthstring 00.00.0000 @@ -7711,15 +7443,15 @@ status Collapsed / \end_inset --std-sdcc89 -\begin_inset LatexCommand \index{-\/-std-sdcc89} +-nooverlay +\begin_inset LatexCommand \index{-\/-nooverlay} \end_inset \series default - Generally follow the C89 standard, but allow SDCC features that conflict - with the standard (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 @@ -7735,15 +7467,14 @@ status Collapsed / \end_inset --std-c89 -\begin_inset LatexCommand \index{-\/-std-c89} +-no-peep +\begin_inset LatexCommand \index{-\/-no-peep} \end_inset \series default - Follow the C89 standard and disable SDCC features that conflict with the - standard. + Disable peep-hole optimization with built-in rules. \layout List \labelwidthstring 00.00.0000 @@ -7759,15 +7490,23 @@ status Collapsed / \end_inset --std-sdcc99 -\begin_inset LatexCommand \index{-\/-std-sdcc99} +-peep-file +\series default + +\begin_inset LatexCommand \index{-\/-peep-file} \end_inset +\SpecialChar ~ + 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 -\series default - Generally follow the C99 standard, but allow SDCC features that conflict - with the standard (incomplete support). +\SpecialChar ~ +Peep Hole optimizations for details on how to write these rules. \layout List \labelwidthstring 00.00.0000 @@ -7783,160 +7522,84 @@ status Collapsed / \end_inset --std-c99 -\begin_inset LatexCommand \index{-\/-std-sdcc99} +-peep-asm +\begin_inset LatexCommand \index{-\/-peep-asm} \end_inset \series default - Follow the C99 standard and disable SDCC features that conflict with the - standard (incomplete support). -\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} - -\end_inset - - -\begin_inset LatexCommand \index{lint (syntax checking tool)} + 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 - -\begin_inset LatexCommand \url{http://www.splint.org} + rules defined in the source file tree '/peeph.def' before using + this option. +\layout List +\labelwidthstring 00.00.0000 -\end_inset -. - To make your source files parseable by splint you will have to include - -\family sans -lint.h -\family default +\series bold +- +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \index{splint (syntax checking tool)} +\layout Standard +\backslash +/ \end_inset - in your source file and add brackets around extended keywords (like -\family sans +-opt-code-speed +\begin_inset LatexCommand \index{-\/-opt-code-speed} -\begin_inset Quotes sld \end_inset -__at\SpecialChar ~ -\series bold -( -\series default -0xab -\series bold -) \series default - -\begin_inset Quotes srd -\end_inset + The compiler will optimize code generation towards fast code, possibly + at the expense of code size. +\layout List +\labelwidthstring 00.00.0000 -\family default - and -\family sans +\series bold +- +\begin_inset ERT +status Collapsed -\begin_inset Quotes sld -\end_inset +\layout Standard -__interrupt\SpecialChar ~ -(2) -\begin_inset Quotes srd +\backslash +/ \end_inset - -\family default -). - -\newline -Splint has an excellent on line manual at -\begin_inset LatexCommand \url{http://www.splint.org/manual/} +-opt-code-size +\begin_inset LatexCommand \index{-\/-opt-code-size} \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 ~ -myprogram.c +\series default + The compiler will optimize code generation towards compact code, possibly + at the expense of code speed. \layout Subsection -Intermediate Dump Options -\begin_inset LatexCommand \label{sub:Intermediate-Dump-Options} - -\end_inset - - -\begin_inset LatexCommand \index{Options intermediate dump} - -\end_inset - - -\begin_inset LatexCommand \index{Intermediate dump options} - -\end_inset - - -\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} - -\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 +Other Options +\begin_inset LatexCommand \index{Options other} - -\begin_inset Quotes srd \end_inset -The anatomy of the compiler -\begin_inset Quotes srd -\end_inset -. \layout List \labelwidthstring 00.00.0000 \series bold +-c\SpecialChar ~ - \begin_inset ERT status Collapsed @@ -7947,33 +7610,27 @@ status Collapsed / \end_inset --dumpraw -\begin_inset LatexCommand \index{-\/-dumpraw} +-compile-only +\begin_inset LatexCommand \index{-\/-compile-only} \end_inset -\series default - This option will cause the compiler to dump the intermediate code into - a file of named -\emph on -.dumpraw -\emph default - just after the intermediate code has been generated for a function, i.e. - before any optimizations are done. - The basic blocks -\begin_inset LatexCommand \index{Basic blocks} +\begin_inset LatexCommand \index{-c -\/-compile-only} \end_inset - at this stage ordered in the depth first number, so they may not be in - sequence of execution. + +\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 @@ -7983,51 +7640,50 @@ status Collapsed / \end_inset --dumpgcse -\begin_inset LatexCommand \index{-\/-dumpgcse} + +\series bold +-c1mode +\begin_inset LatexCommand \index{-\/-c1mode} \end_inset \series default - Will create a dump of iCode's, after global subexpression elimination -\begin_inset LatexCommand \index{Global subexpression elimination} - -\end_inset - -, into a file named -\emph on -.dumpgcse. + 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 -- -\begin_inset ERT -status Collapsed - -\layout Standard +-E +\begin_inset LatexCommand \index{-E} -\backslash -/ \end_inset --dumpdeadcode -\begin_inset LatexCommand \index{-\/-dumpdeadcode} -\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 default - Will create a dump of iCode's, after deadcode elimination -\begin_inset LatexCommand \index{Dead-code elimination} +\series bold +-o\SpecialChar ~ + +\begin_inset LatexCommand \index{-o } \end_inset -, into a file named -\emph on -.dumpdeadcode. + +\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 @@ -8043,24 +7699,44 @@ status Collapsed / \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 -.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 @@ -8076,30 +7752,48 @@ status Collapsed / \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 -.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 @@ -8109,19 +7803,14 @@ 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 @@ -8137,8 +7826,8 @@ status Collapsed / \end_inset --dumpregassign -\begin_inset LatexCommand \index{-\/-dumpregassign} +-debug +\begin_inset LatexCommand \index{-\/-debug} \end_inset @@ -8147,14 +7836,35 @@ status Collapsed \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 -.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 @@ -8170,14 +7880,16 @@ status Collapsed / \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 @@ -8193,47 +7905,40 @@ status Collapsed / \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 @@ -8243,22 +7948,26 @@ 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 @@ -8268,30 +7977,35 @@ status Collapsed / \end_inset +-main-return +\begin_inset LatexCommand \index{-\/-main-return} -\emph default --vc -\begin_inset LatexCommand \index{-\/-vc} +\end_inset + + +\series default + This option can be used if the code generated is called by a monitor program + or if the main routine includes an endless loop. + This option might result in slightly smaller code and save two bytes of + stack space. + The return from the 'main' +\begin_inset LatexCommand \index{main return} \end_inset - 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 @@ -8301,13 +8015,21 @@ 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 @@ -8317,429 +8039,352 @@ 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} +- +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-no-peep-comments +\begin_inset LatexCommand \index{-\/-no-peep-comments} \end_inset \series default - Path, see section -\begin_inset LatexCommand \ref{sub:Search-Paths} + Will not include peep-hole comments in the generated files. +\layout List +\labelwidthstring 00.00.0000 -\end_inset -\SpecialChar ~ +\series bold +- +\begin_inset ERT +status Collapsed -\begin_inset Quotes sld +\layout Standard + +\backslash +/ \end_inset -Search Paths -\begin_inset Quotes srd +-i-code-in-asm +\begin_inset LatexCommand \index{-\/-i-code-in-asm} + \end_inset -. + +\series default + Include i-codes in the asm file. + Sounds like noise but is most helpful for debugging the compiler itself. \layout List \labelwidthstring 00.00.0000 \series bold -SDCC_LIB -\begin_inset LatexCommand \index{SDCC\_LIB} +- +\begin_inset ERT +status Collapsed -\end_inset +\layout Standard +\backslash +/ +\end_inset -\series default - Path, see section -\begin_inset LatexCommand \ref{sub:Search-Paths} +-less-pedantic +\begin_inset LatexCommand \index{-\/-less-pedantic} \end_inset -\SpecialChar ~ -\begin_inset Quotes sld -\end_inset +\series default + Disable some of the more pedantic warnings +\begin_inset LatexCommand \index{Warnings} -Search Paths -\begin_inset Quotes srd \end_inset -.. -\layout Standard + (jwk burps: please be more specific here, please!). +\layout List +\labelwidthstring 00.00.0000 -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 +\series bold +- +\begin_inset ERT +status Collapsed -MCS51/DS390 Storage Class -\begin_inset LatexCommand \index{Storage class} +\layout Standard +\backslash +/ \end_inset - Language Extensions -\layout Standard +-disable-warning\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-disable-warning} -In addition to the ANSI storage classes SDCC allows the following MCS51 - specific storage classes: -\layout Subsubsection +\end_inset -data -\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)} -\end_inset +\series default + Disable specific warning with number . +\layout List +\labelwidthstring 00.00.0000 -\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)} +\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 -\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 - - -\family typewriter -data unsigned char test_data; -\layout Standard +\backslash +/ +\end_inset -Writing 0x01 to this variable generates the assembly code: -\layout Verse +-vc +\begin_inset LatexCommand \index{-\/-vc} +\end_inset -\family typewriter -75*00 01\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov\SpecialChar ~ -\SpecialChar ~ -_test_data,#0x01 -\layout Subsubsection -xdata -\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} +\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 +\series bold +- +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)} +\layout Standard +\backslash +/ \end_inset - / far -\begin_inset LatexCommand \index{far (storage class)} +-use-stdout +\begin_inset LatexCommand \index{-\/-use-stdout} \end_inset -\begin_inset LatexCommand \index{\_\_far (storage class)} - -\end_inset - +\series default + Send errors and warnings to stdout instead of stderr. +\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 +-Wa\SpecialChar ~ +asmOption[,asmOption] \series default - storage class for the Large Memory model, e.g.: -\layout Verse +\begin_inset LatexCommand \index{-Wa asmOption[,asmOption]} -\family typewriter -xdata unsigned char test_xdata; -\layout Standard +\end_inset -Writing 0x01 to this variable generates the assembly code: -\layout Verse +... + Pass the asmOption to the assembler +\begin_inset LatexCommand \index{Options assembler} +\end_inset -\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 -idata -\begin_inset LatexCommand \index{idata (mcs51, ds390 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 -\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)} - -\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 + +-std-sdcc89 +\begin_inset LatexCommand \index{-\/-std-sdcc89} +\end_inset -\family typewriter -idata unsigned char test_idata; -\layout Standard -Writing 0x01 to this variable generates the assembly code: -\layout Verse +\series default + Generally follow the C89 standard, but allow SDCC features that conflict + with the standard (default). +\layout List +\labelwidthstring 00.00.0000 -\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 bold +- +\begin_inset ERT +status Collapsed -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} +\layout Standard +\backslash +/ \end_inset - is located in idata memory. -\layout Subsubsection - -pdata -\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} +-std-c89 +\begin_inset LatexCommand \index{-\/-std-c89} \end_inset -\begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)} +\series default + Follow the C89 standard and disable SDCC features that conflict with the + standard. +\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-sdcc99 +\begin_inset LatexCommand \index{-\/-std-sdcc99} \end_inset -). -\layout Verse - - -\family typewriter -pdata unsigned char test_pdata; -\layout Standard - -Writing 0x01 to this variable generates the assembly code: -\layout Verse +\series default + Generally follow the C99 standard, but allow SDCC features that conflict + with the standard (incomplete support). +\layout List +\labelwidthstring 00.00.0000 -\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 -If the - +\series bold +- \begin_inset ERT status Collapsed @@ -8749,511 +8394,452 @@ status Collapsed / \end_inset --xstack -\begin_inset LatexCommand \index{-\/-xstack} +-std-c99 +\begin_inset LatexCommand \index{-\/-std-sdcc99} \end_inset - 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 -code -\begin_inset LatexCommand \index{code} +\series default + Follow the C99 standard and disable SDCC features that conflict with the + standard (incomplete support). +\layout List +\labelwidthstring 00.00.0000 + + +\series bold +- +\begin_inset ERT +status Collapsed +\layout Standard + +\backslash +/ \end_inset +-codeseg +\series default -\begin_inset LatexCommand \index{\_\_code} +\begin_inset LatexCommand \index{-\/-codeseg } \end_inset +\SpecialChar ~ + The name to be used for the code +\begin_inset LatexCommand \index{code} -\layout Standard +\end_inset -'Variables' declared with this storage class will be placed in the code - memory: -\layout Verse + segment, default CSEG. + This is useful if you need to tell the compiler to put the code in a special + segment so you can later on tell the linker to put this segment in a special + place in memory. + Can be used for instance when using bank switching to put the code in a + bank. +\layout List +\labelwidthstring 00.00.0000 -\family typewriter -code unsigned char test_code; +\series bold +- +\begin_inset ERT +status Collapsed + \layout Standard -Read access to this variable generates the assembly code: -\layout Verse +\backslash +/ +\end_inset +-constseg +\series default + +\begin_inset LatexCommand \index{-\/-constseg } + +\end_inset -\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 + The name to be used for the const +\begin_inset LatexCommand \index{code} +\end_inset -\family typewriter -char -\family default - indexed arrays of characters in code memory can be accessed efficiently: -\layout Verse + segment, default CONST. + This is useful if you need to tell the compiler to put the const data in + a special segment so you can later on tell the linker to put this segment + in a special place in memory. + Can be used for instance when using bank switching to put the const data + in a bank. +\layout List +\labelwidthstring 00.00.0000 -\family typewriter -code char test_array[] = {'c','h','e','a','p'}; -\layout Standard +\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} -Read access to this array using an 8-bit unsigned index generates the assembly - code: -\layout Verse +\end_inset -\family typewriter -E5*00\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov a,_index -\layout Verse +\begin_inset LatexCommand \index{lint (syntax checking tool)} +\end_inset -\family typewriter -90s00r41\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov dptr,#_test_array -\layout Verse + +\begin_inset LatexCommand \url{http://www.splint.org} +\end_inset -\family typewriter -93\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -movc a,@a+dptr -\layout Subsubsection +. + To make your source files parseable by splint you will have to include + +\family sans +lint.h +\family default -bit -\begin_inset LatexCommand \index{bit} +\begin_inset LatexCommand \index{splint (syntax checking tool)} \end_inset + in your source file and add brackets around extended keywords (like +\family sans -\begin_inset LatexCommand \index{\_\_bit} - +\begin_inset Quotes sld \end_inset +__at\SpecialChar ~ -\layout Standard +\series bold +( +\series default +0xab +\series bold +) +\series default -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 +\begin_inset Quotes srd +\end_inset -\family typewriter -bit test_bit; -\layout Standard +\family default + and +\family sans -Writing 1 to this variable generates the assembly code: -\layout Verse +\begin_inset Quotes sld +\end_inset +__interrupt\SpecialChar ~ +(2) +\begin_inset Quotes srd +\end_inset -\family typewriter -D2*00\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -setb\SpecialChar ~ -_test_bit -\layout Standard -The bit addressable memory consists of 128 bits which are located from 0x20 - to 0x2f in data memory. +\family default +). \newline -Apart from this 8051 specific storage class most architectures support ANSI-C - bitfields -\begin_inset LatexCommand \index{bitfields} +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 -\begin_inset Foot -collapsed false +\family sans +splint\SpecialChar ~ +-I\SpecialChar ~ +/usr/local/share/sdcc/include/mcs51/\SpecialChar ~ +\SpecialChar ~ +myprogram.c +\layout Subsection -\layout Standard +Intermediate Dump Options +\begin_inset LatexCommand \label{sub:Intermediate-Dump-Options} -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 -sfr -\begin_inset LatexCommand \index{sfr} +\begin_inset LatexCommand \index{Options intermediate dump} \end_inset -\begin_inset LatexCommand \index{\_\_sfr} +\begin_inset LatexCommand \index{Intermediate dump options} \end_inset - / sbit -\begin_inset LatexCommand \index{\_\_sbit} + +\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} \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} -\layout Standard +\end_inset -Like the bit keyword, -\emph on -sfr / sbit -\emph default -signifies 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 + +\begin_inset Quotes srd +\end_inset +The anatomy of the compiler +\begin_inset Quotes srd +\end_inset -\family typewriter -sfr at -\begin_inset LatexCommand \index{at} +. +\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 - 0x80 P0;\SpecialChar ~ - /* special function register P0 at location 0x80 */ -\newline -sbit at 0xd7 CY; /* CY (Carry Flag -\begin_inset LatexCommand \index{Flags} +-dumpraw +\begin_inset LatexCommand \index{-\/-dumpraw} \end_inset -\begin_inset LatexCommand \index{Carry flag} +\series default + This option will cause the compiler to dump the intermediate code into + a file of named +\emph on +.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 -) */ + 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 +- +\begin_inset ERT +status Collapsed + \layout Standard -Special function registers which are located on an address dividable by - 8 are bit-addressable, an -\emph on - sbit -\emph default - addresses a specific bit within these sfr. -\layout Subsubsection +\backslash +/ +\end_inset -Pointers -\begin_inset LatexCommand \index{Pointer} +-dumpgcse +\begin_inset LatexCommand \index{-\/-dumpgcse} \end_inset - 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} +\series default + Will create a dump of iCode's, after global subexpression elimination +\begin_inset LatexCommand \index{Global subexpression elimination} \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 +, into a file named +\emph on +.dumpgcse. +\layout List +\labelwidthstring 00.00.0000 -\newline -Pointer declaration examples: -\layout Verse +\series bold +- +\begin_inset ERT +status Collapsed -\family typewriter -/* pointer physically in internal ram pointing to object in external ram - */ -\newline -xdata unsigned char * data p; -\newline +\layout Standard -\newline -/* pointer physically in external ram pointing to object in internal ram - */ -\newline -data unsigned char * xdata p; -\newline +\backslash +/ +\end_inset -\newline -/* pointer physically in code rom pointing to data in xdata space */ -\newline -xdata unsigned char * code p; -\newline +-dumpdeadcode +\begin_inset LatexCommand \index{-\/-dumpdeadcode} -\newline -/* pointer physically in code space pointing to data in code space */ -\newline -code unsigned char * code p; -\newline +\end_inset -\newline -/* the following is a generic pointer physically located in xdata space - */ -\newline -char * xdata p; -\layout Standard -Well you get the idea. - -\newline +\series default + Will create a dump of iCode's, after deadcode elimination +\begin_inset LatexCommand \index{Dead-code elimination} -\newline -All unqualified pointers are treated as 3-byte (4-byte for the ds390) +\end_inset + +, into a file named \emph on -generic -\emph default - pointers. - -\size small +.dumpdeadcode. +\layout List +\labelwidthstring 00.00.0000 -\newline -\newline +\series bold +- +\begin_inset ERT +status Collapsed -\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} +\layout Standard +\backslash +/ \end_inset - routines. - Explicitly specifying the pointer type will generate the most efficient - code. -\layout Subsubsection - -Notes on MCS51 memory -\begin_inset LatexCommand \index{MCS51 memory} +-dumploop +\begin_inset LatexCommand \index{-\/-dumploop} \end_inset - layout -\layout Standard - -The 8051 family of microcontrollers have a minimum of 128 bytes of internal - RAM memory which is structured as follows: -\newline -\newline -- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7, +\series default +\size large -\newline -- Bytes 20-2F - 16 bytes to hold 128 bit -\begin_inset LatexCommand \index{bit} +\size default +Will create a dump of iCode's, after loop optimizations +\begin_inset LatexCommand \index{Loop optimization} \end_inset - variables and, -\newline -- Bytes 30-7F - 80 bytes for general purpose use. -\newline +, into a file named +\emph on +.dumploop. +\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)} +-dumprange +\begin_inset LatexCommand \index{-\/-dumprange} \end_inset -\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)} +\series default +\size large + +\size default +Will create a dump of iCode's, after live range analysis +\begin_inset LatexCommand \index{Live range analysis} \end_inset -). - Furthermore, some chips may have some built in external memory ( +, into a file named \emph on -xdata -\emph default +.dumprange. +\layout List +\labelwidthstring 00.00.0000 -\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} -\end_inset +\series bold +- +\begin_inset ERT +status Collapsed +\layout Standard -\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)} +\backslash +/ +\end_inset + +-dumlrange +\begin_inset LatexCommand \index{-\/-dumlrange} \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)} +\series default + Will dump the life ranges +\begin_inset LatexCommand \index{Live range analysis} \end_inset + for all symbols. +\layout List +\labelwidthstring 00.00.0000 -\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)} - -\end_inset - -). - Sometimes this built in -\emph on -xdata -\emph default - memory has to be activated before using it (you can probably find this - information on the datasheet of the microcontroller your are using, see - also section -\begin_inset LatexCommand \ref{sub:Startup-Code} -\end_inset +\series bold +- +\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 - -\emph default -) should be used in interrupt -\begin_inset LatexCommand \index{interrupt} +-dumpregassign +\begin_inset LatexCommand \index{-\/-dumpregassign} \end_inset -\begin_inset LatexCommand \index{\_\_interrupt} +\bar under + +\series default +\bar default +Will create a dump of iCode's, after register assignment +\begin_inset LatexCommand \index{Register assignment} \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 +, into a file named \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} +.dumprassgn. +\layout List +\labelwidthstring 00.00.0000 -\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 - +\series bold +- \begin_inset ERT status Collapsed @@ -9263,16 +8849,20 @@ status Collapsed / \end_inset --data-loc -\begin_inset LatexCommand \index{-\/-data-loc } +-dumplrange +\begin_inset LatexCommand \index{-\/-dumplrange} \end_inset - to specify the start address of the -\emph on -data -\emph default - and - + +\series default + Will create a dump of the live ranges of iTemp's +\layout List +\labelwidthstring 00.00.0000 + + +\series bold +- \begin_inset ERT status Collapsed @@ -9282,49 +8872,47 @@ status Collapsed / \end_inset --iram-size -\begin_inset LatexCommand \index{-\/-iram-size } +-dumpall +\begin_inset LatexCommand \index{-\/-dumpall} \end_inset - to specify the size of the total internal RAM ( -\emph on -data -\emph 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 +\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 -\backslash -/ +By default SDCC writes it's error messages to +\begin_inset Quotes sld \end_inset --stack-loc -\begin_inset LatexCommand \index{-\/-stack-loc } +standard error +\begin_inset Quotes srd +\end_inset +. + To force all messages to +\begin_inset Quotes sld \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 ( +standard output +\begin_inset Quotes srd +\end_inset + + use +\series bold +- +\series default \emph on -idata -\emph default -) you can place the stack on it. - You may also need to use - + \begin_inset ERT status Collapsed @@ -9334,16 +8922,22 @@ status Collapsed / \end_inset --xdata-loc -\begin_inset LatexCommand \index{-\/-xdata-loc} + +\series bold +\emph default +- +\series default +use-stdout +\begin_inset LatexCommand \index{-\/-use-stdout} \end_inset - to set the start address of the external RAM ( +. + 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 -xdata -\emph default -) and - + \begin_inset ERT status Collapsed @@ -9353,13 +8947,30 @@ status Collapsed / \end_inset --xram-size -\begin_inset LatexCommand \index{-\/-xram-size } + +\emph default +-vc +\begin_inset LatexCommand \index{-\/-vc} \end_inset - to specify its size. - Same goes for the code memory, using - + option. + Something like this should work: +\newline + +\newline + +\series bold +c: +\backslash +sdcc +\backslash +bin +\backslash +sdcc.exe - +\series default +\emph on + \begin_inset ERT status Collapsed @@ -9369,12 +8980,13 @@ status Collapsed / \end_inset --code-loc -\begin_inset LatexCommand \index{-\/-code-loc } -\end_inset +\series bold +\emph default +-vc - +\series default +\emph on - and - \begin_inset ERT status Collapsed @@ -9384,86 +8996,214 @@ status Collapsed / \end_inset --code-size -\begin_inset LatexCommand \index{-\/-code-size } + +\series bold +\emph default +-model-large -c $(InputPath) +\layout Section + +Environment variables +\begin_inset LatexCommand \index{Environment variables} \end_inset -. - If in doubt, don't specify any options and see if the resulting memory - layout is appropriate, then you can adjust it. + \layout Standard -The linker generates two files with memory allocation information. - The first, with extension .map -\begin_inset LatexCommand \index{.map} +SDCC recognizes the following environment variables: +\layout List +\labelwidthstring 00.00.0000 -\end_inset - shows all the variables and segments. - The second with extension .mem -\begin_inset LatexCommand \index{.mem} +\series bold +SDCC_LEAVE_SIGNALS +\begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS} \end_inset - shows the final memory layout. - The linker will complain either if memory segments overlap, there is not - enough memory, or there is not enough space for stack. - If you get any linking warnings and/or errors related to stack or segments - allocation, take a look at either the .map or .mem files to find out what - the problem is. - The .mem file may even suggest a solution to the problem. -\layout Subsection -Z80/Z180 Storage Class +\series default + SDCC installs a signal handler +\begin_inset LatexCommand \index{signal handler} + +\end_inset + + to be able to delete temporary files after an user break (^C) or an exception. + If this environment variable is set, SDCC won't install the signal handler + in order to be able to debug SDCC. +\layout List +\labelwidthstring 00.00.0000 + + +\series bold +TMP,\SpecialChar ~ +TEMP,\SpecialChar ~ +TMPDIR +\begin_inset LatexCommand \index{TMP, TEMP, TMPDIR} + +\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. +\layout List +\labelwidthstring 00.00.0000 + + +\series bold +SDCC_HOME +\begin_inset LatexCommand \index{SDCC\_HOME} + +\end_inset + + +\series default + Path, see section +\begin_inset LatexCommand \ref{sub:Install-paths} + +\end_inset + +\SpecialChar ~ + +\begin_inset Quotes sld +\end_inset + + Install Paths +\begin_inset Quotes srd +\end_inset + +. +\layout List +\labelwidthstring 00.00.0000 + + +\series bold +SDCC_INCLUDE +\begin_inset LatexCommand \index{SDCC\_INCLUDE} + +\end_inset + + +\series default + Path, see section +\begin_inset LatexCommand \ref{sub:Search-Paths} + +\end_inset + +\SpecialChar ~ + +\begin_inset Quotes sld +\end_inset + +Search Paths +\begin_inset Quotes srd +\end_inset + +. +\layout List +\labelwidthstring 00.00.0000 + + +\series bold +SDCC_LIB +\begin_inset LatexCommand \index{SDCC\_LIB} + +\end_inset + + +\series default + Path, see section +\begin_inset LatexCommand \ref{sub:Search-Paths} + +\end_inset + +\SpecialChar ~ + +\begin_inset Quotes sld +\end_inset + +Search Paths +\begin_inset Quotes srd +\end_inset + +.. +\layout Standard + +There are some more environment variables recognized by SDCC, but these + are solely used for debugging purposes. + They can change or disappear very quickly, and will never be 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 -sfr -\begin_inset LatexCommand \index{sfr} +data +\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)} \end_inset -\begin_inset LatexCommand \index{\_\_sfr} +\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)} \end_inset - (in/out to 8-bit addresses) -\layout Standard + / near +\begin_inset LatexCommand \index{near (storage class)} -The Z80 -\begin_inset LatexCommand \index{Z80} +\end_inset + + +\begin_inset LatexCommand \index{\_\_near (storage class)} \end_inset - family has separate address spaces for memory and + +\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: @@ -9471,56 +9211,49 @@ 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: @@ -9528,628 +9261,748 @@ 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} +\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)} \end_inset - (in0/out0 to 8 bit addresses on Z180 -\begin_inset LatexCommand \index{Z180} -\end_inset +\layout Standard -/HD64180 -\begin_inset LatexCommand \index{HD64180} - -\end_inset - -) -\layout Standard +Variables declared with this storage class will be allocated into the indirectly + addressable portion of the internal ram of a 8051, e.g.: +\layout Verse -The compiler option - -\begin_inset ERT -status Collapsed +\family typewriter +__idata unsigned char test_idata; \layout Standard -\backslash -/ -\end_inset - --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 +). + This is the +\series bold +default +\series default + storage class for the Medium Memory model, e.g.: +\layout Verse -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} +\family typewriter +__pdata unsigned char test_pdata; +\layout Standard -\end_inset +Writing 0x01 to this variable generates the assembly code: +\layout Verse +\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 -Data items can be assigned an absolute address with the -\emph on -at -\begin_inset LatexCommand \index{at} +If the - +\begin_inset ERT +status Collapsed -\end_inset +\layout Standard +\backslash +/ +\end_inset -\begin_inset LatexCommand \index{\_\_at} +-xstack +\begin_inset LatexCommand \index{-\/-xstack} \end_inset -
-\emph default - keyword, in addition to a storage class, e.g.: -\layout Verse - + 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 -\family typewriter -xdata -\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} +code +\begin_inset LatexCommand \index{code} \end_inset -\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)} +\begin_inset LatexCommand \index{\_\_code} \end_inset - at -\begin_inset LatexCommand \index{at} - -\end_inset +\layout Standard -\begin_inset LatexCommand \index{\_\_at} +'Variables' declared with this storage class will be placed in the code + memory: +\layout Verse -\end_inset - 0x7ffe unsigned int chksum; +\family typewriter +__code unsigned char test_code; \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{.lst} - -\end_inset - -) and the linker output files (.rst -\begin_inset LatexCommand \index{.rst} +Read access to this variable generates the assembly code: +\layout Verse -\end_inset -) and (.map -\begin_inset LatexCommand \index{.map} +\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 -) 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} +\family typewriter +char +\family default + indexed arrays of characters in code memory can be accessed efficiently: +\layout Verse -\end_inset -. +\family typewriter +__code char test_array[] = {'c','h','e','a','p'}; \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: +Read access to this array using an 8-bit unsigned index generates the assembly + code: \layout Verse \family typewriter -volatile -\begin_inset LatexCommand \index{volatile} +E5*00\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov a,_index +\layout Verse -\end_inset - xdata -\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} +\family typewriter +90s00r41\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov dptr,#_test_array +\layout Verse + + +\family typewriter +93\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +movc a,@a+dptr +\layout Subsubsection + +bit +\begin_inset LatexCommand \index{bit} \end_inset - at -\begin_inset LatexCommand \index{at} + +\begin_inset LatexCommand \index{\_\_bit} \end_inset - 0x8000 unsigned char PORTA_8255; + \layout Standard -For some architectures (mcs51) array accesses are more efficient if an (xdata/fa -r) array +This is a data-type and a storage class specifier. + When a variable is declared as a bit, it is allocated into the bit addressable + memory of 8051, e.g.: +\layout Verse + + \family typewriter -\size footnotesize +__bit test_bit; +\layout Standard -\begin_inset LatexCommand \index{Aligned array} +Writing 1 to this variable generates the assembly code: +\layout Verse + + +\family typewriter +D2*00\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +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 +Apart from this 8051 specific storage class most architectures support ANSI-C + bitfields +\begin_inset LatexCommand \index{bitfields} \end_inset -\family default -\size default - starts at a block (256 byte) boundary -\begin_inset LatexCommand \index{block boundary} +\begin_inset Foot +collapsed false + +\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 - (section -\begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction} +. + 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} \end_inset - has an example). -\newline -Absolute addresses can be specified for variables in all storage classes, - e.g.: -\layout Verse +\begin_inset LatexCommand \index{\_\_sfr} -\family typewriter -bit -\begin_inset LatexCommand \index{bit} +\end_inset + + / sfr16 +\begin_inset LatexCommand \index{sfr16} \end_inset - at -\begin_inset LatexCommand \index{at} + +\begin_inset LatexCommand \index{\_\_sfr16} + +\end_inset + + / sfr32 +\begin_inset LatexCommand \index{sfr32} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_sfr32} \end_inset - 0x02 bvar; + / sbit +\begin_inset LatexCommand \index{\_\_sbit} + +\end_inset + + \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: +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 \family typewriter -extern volatile -\begin_inset LatexCommand \index{volatile} +__sfr __at +\begin_inset LatexCommand \index{at} \end_inset - bit MOSI;\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* master out, slave in */ + +\begin_inset LatexCommand \index{\_\_at} + +\end_inset + + (0x80) P0;\SpecialChar ~ + /* special function register P0 at location 0x80 */ \newline -extern volatile bit MISO;\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* master in, slave out */ +/* 16 bit special function register combination for timer 0 */ \newline -extern volatile bit MCLK;\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* master clock */ +/* with the high byte at location 0x8C and the low byte at location 0x8A + */ \newline +__sfr16 __at +\begin_inset LatexCommand \index{at} + +\end_inset + +\begin_inset LatexCommand \index{\_\_at} + +\end_inset + + (0x8C8A) TMR0; \newline -/* Input and Output of a byte on a 3-wire serial bus. +__sbit __at (0xd7) CY; /* CY (Carry Flag +\begin_inset LatexCommand \index{Flags} + +\end_inset + + +\begin_inset LatexCommand \index{Carry flag} + +\end_inset + +) */ +\layout Standard + +Special function registers which are located on an address dividable by + 8 are bit-addressable, an +\emph on + sbit +\emph default + addresses a specific bit within these sfr. \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -If needed adapt polarity of clock, polarity of data and bit order +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 + +Pointers +\begin_inset LatexCommand \index{Pointer} + +\end_inset + + 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} + +\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 -\SpecialChar ~ -*/ + \newline -unsigned char spi_io(unsigned char out_byte) +Pointer declaration examples: +\layout Verse + + +\family typewriter +/* pointer physically in internal ram pointing to object in external ram + */ \newline -{ +__xdata unsigned char * __data p; \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -unsigned char i=8; + \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -do { +/* pointer physically in external ram pointing to object in internal ram + */ \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -MOSI = out_byte & 0x80; +__data unsigned char * __xdata p; \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -out_byte <<= 1; + \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -MCLK = 1; +/* pointer physically in code rom pointing to data in xdata space */ \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* _asm nop _endasm; */\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* for slow peripherals */ +__xdata unsigned char * __code p; \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; +/* pointer physically in code space pointing to data in code space */ \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -MCLK = 0; +__code unsigned char * __code p; \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -} while(--i); + \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -return out_byte; +/* the following is a generic pointer physically located in xdata space + */ \newline -} +char * __xdata p; +\newline + +\newline +/* the following is a function pointer physically located in data space + */ +\newline +char (* __data fp)(void); \layout Standard -Then, someplace in the code for the first hardware you would use -\layout Verse +Well you get the idea. + +\newline + +\newline +All unqualified pointers are treated as 3-byte (4-byte for the ds390) +\emph on +generic +\emph default + pointers. + +\size small +\newline -\family typewriter -bit at -\begin_inset LatexCommand \index{at} +\newline + +\size default +The highest order byte of the +\emph on +generic +\emph default + pointers contains the data space information. + Assembler support routines are called whenever data is stored or retrieved + using +\emph on +generic +\emph default + pointers. + These are useful for developing reusable library +\begin_inset LatexCommand \index{Libraries} \end_inset + routines. + Explicitly specifying the pointer type will generate the most efficient + code. +\layout Subsubsection -\begin_inset LatexCommand \index{\_\_at} +Notes on MCS51 memory +\begin_inset LatexCommand \index{MCS51 memory} \end_inset - 0x80 MOSI;\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* I/O port 0, bit 0 */ -\newline -bit at 0x81 MISO;\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* I/O port 0, bit 1 */ -\newline -bit at 0x82 MCLK;\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* I/O port 0, bit 2 */ + layout \layout Standard -Similarly, for the second hardware you would use -\layout Verse - +The 8051 family of microcontrollers have a minimum of 128 bytes of internal + RAM memory which is structured as follows: +\newline -\family typewriter -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 */ +- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7, + \newline -bit +- Bytes 20-2F - 16 bytes to hold 128 bit \begin_inset LatexCommand \index{bit} \end_inset - at 0x92 MCLK;\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* I/O port 1, bit 2 */ + variables and, +\newline +- Bytes 30-7F - 80 bytes for general purpose use. +\newline + \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 +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 -Parameters -\begin_inset LatexCommand \index{Parameters} +\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)} \end_inset -\begin_inset LatexCommand \index{function parameter} - -\end_inset - - & Local Variables -\begin_inset LatexCommand \index{local variables} +\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)} \end_inset +). + Furthermore, some chips may have some built in external memory ( +\emph on +xdata +\emph default -\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables} +\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} \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{\_\_xdata (mcs51, ds390 storage class)} \end_inset - +) which should not be confused with the internal, directly addressable RAM + memory ( +\emph on +data \emph default - so by default functions are non-reentrant -\begin_inset LatexCommand \index{reentrant} + +\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)} \end_inset -. - -\newline -\newline -They can be placed on the stack -\begin_inset LatexCommand \index{stack} +\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)} \end_inset - by using the +). + Sometimes this built in \emph on - - -\begin_inset ERT -status Collapsed - -\layout Standard +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} -\backslash -/ \end_inset --stack-auto -\begin_inset LatexCommand \index{-\/-stack-auto} +\SpecialChar ~ +Startup-Code). +\layout Standard + +Normally SDCC will only use the first bank +\begin_inset LatexCommand \index{register bank (mcs51, ds390)} \end_inset - -\emph default - option, by using + of registers (register bank 0), but it is possible to specify that other + banks of registers (keyword \emph on -#pragma\SpecialChar ~ -stackauto +using \emph default + +\emph on -\begin_inset LatexCommand \index{\#pragma stackauto} +\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)} \end_inset - or by using the -\emph on -reentrant -\begin_inset LatexCommand \index{reentrant} + +\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)} \end_inset \emph default - keyword in the function declaration, e.g.: -\layout Verse +) should be used in interrupt +\begin_inset LatexCommand \index{interrupt} +\end_inset -\family typewriter -unsigned char foo(char i) reentrant -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -... - -\newline -} -\layout Standard -Since stack space on 8051 is limited, the +\begin_inset LatexCommand \index{\_\_interrupt} + +\end_inset + + routines. + By default, the compiler will place the stack after the last byte of allocated + memory for variables. + For example, if the first 2 banks of registers are used, and only four + bytes are used for \emph on -reentrant +data \emph default -keyword or the + 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 @@ -10159,91 +10012,47 @@ status Collapsed / \end_inset --stack-auto -\emph default - option should be used sparingly. - Note that the reentrant keyword just means that the parameters & local - variables will be allocated to the stack, it -\emph on -does not -\emph default - mean that the function is register bank -\begin_inset LatexCommand \index{register bank (mcs51, ds390)} +-data-loc +\begin_inset LatexCommand \index{-\/-data-loc } \end_inset - independent. -\newline - -\newline -Local variables -\begin_inset LatexCommand \index{local variables} - -\end_inset + to specify the start address of the +\emph on +data +\emph default + and - +\begin_inset ERT +status Collapsed - can be assigned storage classes and absolute -\begin_inset LatexCommand \index{Absolute addressing} +\layout Standard +\backslash +/ \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} +-iram-size +\begin_inset LatexCommand \index{-\/-iram-size } \end_inset - 0x31 unsigned char j; -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -... - -\newline -} -\layout Standard - -In the above example the variable -\emph on -i -\emph default - will be allocated in the external ram, + to specify the size of the total internal RAM ( \emph on -bvar +data \emph default - in bit addressable space and ++ \emph on - j +idata \emph default - in internal ram. - When compiled with -\emph on -- +). + +\newline + +\layout Standard + +By default the 8051 linker will place the stack after the last byte of (i)data + variables. + Option - \begin_inset ERT status Collapsed @@ -10253,773 +10062,580 @@ status Collapsed / \end_inset --stack-auto -\emph default - or when a function is declared as +-stack-loc +\begin_inset LatexCommand \index{-\/-stack-loc } + +\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 -reentrant +idata \emph default - this should only be done for static variables. -\layout Standard +) you can place the stack on it. + You may also need to use - +\begin_inset ERT +status Collapsed -Parameters -\begin_inset LatexCommand \index{function parameter} +\layout Standard +\backslash +/ \end_inset - however are not allowed any storage class -\begin_inset LatexCommand \index{Storage class} +-xdata-loc +\begin_inset LatexCommand \index{-\/-xdata-loc} \end_inset -, (storage classes for parameters will be ignored), their allocation is - governed by the memory model in use, and the reentrancy options. -\layout Section + to set the start address of the external RAM ( +\emph on +xdata +\emph default +) and - +\begin_inset ERT +status Collapsed -Overlaying -\begin_inset LatexCommand \label{sub:Overlaying} +\layout Standard +\backslash +/ \end_inset - -\begin_inset LatexCommand \index{Overlaying} +-xram-size +\begin_inset LatexCommand \index{-\/-xram-size } \end_inset + to specify its size. + Same goes for the code memory, using - +\begin_inset ERT +status Collapsed \layout Standard -For non-reentrant -\begin_inset LatexCommand \index{reentrant} - +\backslash +/ \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} +-code-loc +\begin_inset LatexCommand \index{-\/-code-loc } \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} + and - +\begin_inset ERT +status Collapsed -\end_inset +\layout Standard - is small. +\backslash +/ +\end_inset -\emph default - If an explicit storage class -\begin_inset LatexCommand \index{Storage class} +-code-size +\begin_inset LatexCommand \index{-\/-code-size } \end_inset - is specified for a local variable, it will NOT be overlayed. +. + If in doubt, don't specify any options and see if the resulting memory + layout is appropriate, then you can adjust it. \layout Standard -Note that the compiler (not the linkage editor) makes the decision for overlayin -g the data items. - Functions that are called from an interrupt service routine should be preceded - by a #pragma\SpecialChar ~ -nooverlay -\begin_inset LatexCommand \index{\#pragma nooverlay} +The linker generates two files with memory allocation information. + The first, with extension .map +\begin_inset LatexCommand \index{.map} \end_inset - if they are not reentrant. -\layout Standard + shows all the variables and segments. + The second with extension .mem +\begin_inset LatexCommand \index{.mem} -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 +\end_inset -Parameters and local variables of functions that contain 16 or 32 bit multiplica -tion -\begin_inset LatexCommand \index{Multiplication} + shows the final memory layout. + The linker will complain either if memory segments overlap, there is not + enough memory, or there is not enough space for stack. + If you get any linking warnings and/or errors related to stack or segments + allocation, take a look at either the .map or .mem files to find out what + the problem is. + The .mem file may even suggest a solution to the problem. +\layout Subsection + +Z80/Z180 Storage Class +\begin_inset LatexCommand \index{Storage class} \end_inset - or division -\begin_inset LatexCommand \index{Division} + Language Extensions +\layout Subsubsection -\end_inset +sfr +\begin_inset LatexCommand \index{sfr} - will NOT be overlayed since these are implemented using external functions, - e.g.: -\layout Verse +\end_inset -\family typewriter -#pragma save -\newline -#pragma nooverlay -\begin_inset LatexCommand \index{\#pragma nooverlay} +\begin_inset LatexCommand \index{\_\_sfr} \end_inset - -\newline -void set_error(unsigned char errcd) -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -P3 = errcd; -\newline -} -\newline -#pragma restore -\newline + (in/out to 8-bit addresses) +\layout Standard -\newline -void some_isr () interrupt -\begin_inset LatexCommand \index{interrupt} +The Z80 +\begin_inset LatexCommand \index{Z80} \end_inset - 2 -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ + family has separate address spaces for memory and +\emph on +i +\emph default +nput/ +\emph on +o +\emph default +utput memory. + I/O memory +\begin_inset LatexCommand \index{I/O memory (Z80, Z180)} + +\end_inset + + is accessed with special instructions, e.g.: +\layout Verse + + +\family typewriter +sfr at 0x78 IoPort;\SpecialChar ~ \SpecialChar ~ +/* define a var in I/O space at 78h called IoPort */ + +\layout Standard + +Writing 0x01 to this variable generates the assembly code: +\layout Verse + + +\family typewriter +3E 01\SpecialChar ~ \SpecialChar ~ -... -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -set_error(10); +ld a,#0x01 \newline +D3 78\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -... - -\newline -} +\SpecialChar ~ +out (_IoPort),a +\layout Subsubsection + +banked sfr +\begin_inset LatexCommand \index{sfr} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_sfr} + +\end_inset + + (in/out to 16-bit addresses) \layout Standard -In the above example the parameter -\emph on -errcd -\emph default - for the function +The keyword \emph on -set_error +banked \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 + is used to support 16 bit addresses in I/O memory e.g.: +\layout Verse -Interrupt Service Routines -\begin_inset LatexCommand \label{sub:Interrupt-Service-Routines} + +\family typewriter +sfr banked at +\begin_inset LatexCommand \index{at} \end_inset -\layout Subsection +\begin_inset LatexCommand \index{\_\_at} -General Information +\end_inset + + 0x123 IoPort; \layout Standard -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. +Writing 0x01 to this variable generates the assembly code: \layout Verse \family typewriter -void timer_isr (void) interrupt 1 using 1 -\newline -{ +01 23 01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ld bc,#_IoPort \newline +3E 01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -... - +\SpecialChar ~ +ld a,#0x01 \newline -} -\layout Standard +ED 79\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +out (c),a +\layout Subsubsection -The optional number following the -\emph on -interrupt -\begin_inset LatexCommand \index{interrupt} +sfr +\begin_inset LatexCommand \index{sfr} \end_inset -\begin_inset LatexCommand \index{\_\_interrupt} +\begin_inset LatexCommand \index{\_\_sfr} \end_inset - -\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)} + (in0/out0 to 8 bit addresses on Z180 +\begin_inset LatexCommand \index{Z180} \end_inset - -\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)} +/HD64180 +\begin_inset LatexCommand \index{HD64180} \end_inset - -\emph default - keyword can be used to tell the compiler to use the specified register - bank (8051 specific) when generating code for this function. - -\newline - +) \layout Standard -Interrupt service routines open the door for some very interesting bugs: -\newline -If an interrupt service routine changes variables which are accessed by - other functions these variables have to be declared -\emph on -volatile -\emph default +The compiler option - +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \index{volatile} +\layout Standard +\backslash +/ \end_inset -. - -\layout Standard - -If the access to these variables is not -\emph on -atomic -\begin_inset LatexCommand \index{atomic} +-portmode=180 (80) and a compiler #pragma\SpecialChar ~ +portmode +\begin_inset LatexCommand \index{\#pragma portmode} \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. - 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 - - +=z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio +ns \family typewriter -flags\SpecialChar ~ -|=\SpecialChar ~ -0x80; +in0/out0 \family default - -\begin_inset Quotes sld -\end_inset - - is not atomic if + instead of \family typewriter -flags +in/out \family default - resides in xdata. - Setting -\begin_inset Quotes srd -\end_inset - +. + If you include the file z180.h this will be set automatically. +\layout Subsection -\family typewriter -flags\SpecialChar ~ -|=\SpecialChar ~ -0x40; -\family default +HC08 Storage Class +\begin_inset LatexCommand \index{Storage class} -\begin_inset Quotes sld \end_inset - from within an interrupt routine might get lost if the interrupt occurs - at the wrong time. - -\begin_inset Quotes sld + Language Extensions +\layout Subsubsection + +data +\begin_inset LatexCommand \index{data (hc08 storage class)} + \end_inset -\family typewriter -counter\SpecialChar ~ -+=\SpecialChar ~ -8; -\family default +\begin_inset LatexCommand \index{\_\_data (hc08 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} +The data storage class declares a variable that resides in the first 256 + bytes of memory (the direct page). + The HC08 is most efficient at accessing variables (especially pointers) + stored here. +\layout Subsubsection + +xdata +\begin_inset LatexCommand \index{xdata (hc08 storage class)} \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 -\begin_inset LatexCommand \index{stack overflow} +\begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)} \end_inset - is most likely to happen if the interrupt occurs during the -\begin_inset Quotes sld -\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} -deepest -\begin_inset Quotes srd \end_inset - subroutine when the stack is already in use for f.e. - many return addresses. + \layout Standard -A special note here, int (16 bit) and long (32 bit) integer division -\begin_inset LatexCommand \index{Division} +Data items can be assigned an absolute address with the +\emph on +at +\begin_inset LatexCommand \index{at} \end_inset -, multiplication -\begin_inset LatexCommand \index{Multiplication} + +\begin_inset LatexCommand \index{\_\_at} \end_inset - & modulus -\begin_inset LatexCommand \index{Modulus} +
+\emph default + keyword, in addition to a storage class, e.g.: +\layout Verse -\end_inset - and floating-point -\begin_inset LatexCommand \index{Floating point support} +\family typewriter +xdata +\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} \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 - - -\begin_inset ERT -status Collapsed -\layout Standard +\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)} -\backslash -/ \end_inset --stack-auto -\begin_inset LatexCommand \index{-\/-stack-auto} + at +\begin_inset LatexCommand \index{at} \end_inset -\emph default - option and the source file will need to be compiled using the -\emph on -- -\begin_inset ERT -status Collapsed +\begin_inset LatexCommand \index{\_\_at} + +\end_inset + (0x7ffe) unsigned int chksum; \layout Standard -\backslash -/ -\end_inset +or +\layout Verse --int-long-reent -\emph default -\begin_inset LatexCommand \index{-\/-int-long-reent} +\family typewriter +__xdata __at (0x7ffe) unsigned int chksum; +\layout Standard -\end_inset +In the above example the variable chksum will be located at 0x7ffe and 0x7fff + of the external ram. + The compiler does +\emph on +not +\emph default + reserve any space for variables declared in this way +\begin_inset Marginal +collapsed true - 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} +\series bold +\SpecialChar ~ +! \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. - -\newline + (they are implemented with an equate in the assembler). + Thus it is left to the programmer to make sure there are no overlaps with + other variables that are declared without the absolute address. + The assembler listing file (.lst +\begin_inset LatexCommand \index{.lst} -\newline -Also see section -\begin_inset LatexCommand \ref{sub:Overlaying} +\end_inset + +) and the linker output files (.rst +\begin_inset LatexCommand \index{.rst} \end_inset -\SpecialChar ~ -about Overlaying and section -\begin_inset LatexCommand \ref{sub:Functions-using-private-banks} +) and (.map +\begin_inset LatexCommand \index{.map} \end_inset -\SpecialChar ~ -about Functions using private register banks. -\layout Subsection +) are good places to look for such overlaps. + Variables with an absolute address are +\emph on +not +\begin_inset Marginal +collapsed true -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 -\layout Standard -\align center +\series bold +\SpecialChar ~ +! +\end_inset -\begin_inset Tabular - - - - - - - -\begin_inset Text -\layout Standard +\emph default + initialized +\begin_inset LatexCommand \index{Variable initialization} -Interrupt # \end_inset - - -\begin_inset Text +. \layout Standard -Description -\end_inset - - -\begin_inset Text +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 -\layout Standard -Vector Address +\family typewriter +volatile +\begin_inset LatexCommand \index{volatile} + \end_inset - - - - -\begin_inset Text -\layout Standard + __xdata +\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} -0 -\end_inset - - -\begin_inset Text - -\layout Standard - -External 0 -\end_inset - - -\begin_inset Text - -\layout Standard - -0x0003 -\end_inset - - - - -\begin_inset Text - -\layout Standard - -1 -\end_inset - - -\begin_inset Text - -\layout Standard - -Timer 0 -\end_inset - - -\begin_inset Text - -\layout Standard - -0x000B -\end_inset - - - - -\begin_inset Text - -\layout Standard - -2 -\end_inset - - -\begin_inset Text - -\layout Standard - -External 1 -\end_inset - - -\begin_inset Text - -\layout Standard - -0x0013 -\end_inset - - - - -\begin_inset Text - -\layout Standard - -3 -\end_inset - - -\begin_inset Text - -\layout Standard - -Timer 1 -\end_inset - - -\begin_inset Text - -\layout Standard - -0x001B \end_inset - - - - -\begin_inset Text -\layout Standard + __at +\begin_inset LatexCommand \index{at} -4 \end_inset - - -\begin_inset Text + (0x8000) unsigned char PORTA_8255; \layout Standard -Serial -\end_inset - - -\begin_inset Text +For some architectures (mcs51) array accesses are more efficient if an (xdata/fa +r) array +\family typewriter +\size footnotesize -\layout Standard +\begin_inset LatexCommand \index{Aligned array} -0x0023 \end_inset - - - - -\begin_inset Text - -\layout Standard -5 -\end_inset - - -\begin_inset Text -\layout Standard +\family default +\size default + starts at a block (256 byte) boundary +\begin_inset LatexCommand \index{block boundary} -Timer 2 (8052) \end_inset - - -\begin_inset Text - -\layout Standard -0x002B -\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 -\layout Standard -If the interrupt service routine is defined without -\emph on -using -\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)} +\family typewriter +__bit +\begin_inset LatexCommand \index{bit} \end_inset - -\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)} + __at +\begin_inset LatexCommand \index{at} \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. + (0x02) bvar; \layout Standard -If the interrupt service routine is defined to be using a specific register - bank then only -\emph on -a, b, dptr -\emph default - & psw are saved and restored, if such an interrupt service routine calls - another function (using another register bank) then the entire register - bank of the called function will be saved on the stack. - This scheme is recommended for larger interrupt service routines. -\layout Subsection +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 -HC08 Interrupt Service Routines -\layout Standard -Since the number of interrupts available is chip specific and the interrupt - vector table always ends at the last byte of memory, the interrupt numbers - corresponds to the interrupt vectors in reverse order of address. - For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt - 2 will use the interrupt vector at 0xfffa, and so on. - However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in - this way; instead see section -\begin_inset LatexCommand \ref{sub:Startup-Code} +\family typewriter +extern volatile +\begin_inset LatexCommand \index{volatile} \end_inset - for details on customizing startup. -\layout Subsection - -Z80 Interrupt Service Routines -\layout Standard - -The Z80 uses several different methods for determining the correct interrupt - vector depending on the hardware implementation. - Therefore, SDCC ignores the optional interrupt number and does not attempt - to generate an interrupt vector table. -\layout Standard - -By default, SDCC generates code for a maskable interrupt, which uses 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 - + __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 -\family typewriter -void nmi_isr (void) critical interrupt +\newline +/* Input and Output of a byte on a 3-wire serial bus. +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +If needed adapt polarity of clock, polarity of data and bit order +\newline +\SpecialChar ~ +*/ +\newline +unsigned char spi_io(unsigned char out_byte) \newline { \newline @@ -11027,107 +10643,14 @@ void nmi_isr (void) critical interrupt \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -... - -\newline -} -\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 ~ -... - +unsigned char i=8; \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -... - -\newline -} -\layout Standard - -The critical attribute maybe used with other attributes like -\emph on -reentrant. -\emph default - +do { \newline -The keyword -\emph on -critical -\emph default - may also be used to disable interrupts more locally: -\layout Verse - - -\family typewriter -critical{ i++; } -\layout Standard - -More than one statement could have been included in the block. -\layout Subsection - -Enabling and Disabling Interrupts directly -\layout Standard - -Interrupts -\begin_inset LatexCommand \index{interrupt} - -\end_inset - - can also be disabled and enabled directly (8051): -\layout Verse - - -\family typewriter -EA = 0;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -11136,29 +10659,28 @@ EA = 0;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +MOSI = out_byte & 0x80; +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -or:\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +out_byte <<= 1; +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -EA_SAVE = EA; -\layout Verse - - -\family typewriter -...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +MCLK = 1; +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -11167,6 +10689,7 @@ EA_SAVE = EA; \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +/* _asm nop _endasm; */\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -11174,6 +10697,8 @@ EA_SAVE = EA; \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +/* for slow peripherals */ +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -11182,15 +10707,11 @@ EA_SAVE = EA; \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +if(MISO) +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -EA = 0; -\layout Verse - - -\family typewriter -EA = 1;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -11200,6 +10721,8 @@ EA = 1;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +out_byte += 1; +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -11208,1508 +10731,1391 @@ EA = 1;\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 ~ +/* I/O port 0, bit 2 */ +\layout Standard + +Similarly, for the second hardware you would use +\layout Verse + + +\family typewriter +__bit __at (0x83) MOSI;\SpecialChar ~ \SpecialChar ~ \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 ~ \SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -EA = EA_SAVE; +/* I/O port 1, 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} +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 -\end_inset +Parameters +\begin_inset LatexCommand \index{Parameters} - (HC08): -\layout Verse +\end_inset -\family typewriter -#define CLI _asm -\begin_inset LatexCommand \index{\_asm} +\begin_inset LatexCommand \index{function parameter} \end_inset -\SpecialChar ~ -\SpecialChar ~ -cli\SpecialChar ~ -\SpecialChar ~ -_endasm -\begin_inset LatexCommand \index{\_endasm} + & Local Variables +\begin_inset LatexCommand \index{local variables} \end_inset -; -\layout Verse +\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables} -\family typewriter -#define SEI _asm\SpecialChar ~ -\SpecialChar ~ -sei\SpecialChar ~ -\SpecialChar ~ -_endasm; -\layout Verse +\end_inset -\family typewriter -... \layout Standard -Note: it is sometimes sufficient to disable only a specific interrupt source - like f.e. - a timer or serial interrupt by manipulating an +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 mask -\begin_inset LatexCommand \index{interrupt mask} +static +\begin_inset LatexCommand \index{static} \end_inset \emph default - register. - -\layout Standard + so by default functions are non-reentrant +\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 +\end_inset -\begin_inset LatexCommand \index{interrupt latency} +. + +\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 -\end_inset +\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} +In the above example the variable +\emph on +i +\emph default + will be allocated in the external ram, +\emph on +bvar +\emph default + in bit addressable space and +\emph on + j +\emph default + in internal ram. + When compiled with +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard +\backslash +/ \end_inset - bit test and -\emph on -clear +-stack-auto \emph default - instruction (as opposed to atomic bit test and + or when a function is declared as \emph on -set). -\layout Section +reentrant +\emph default + this should only be done for static variables. +\layout Standard -Functions using private register banks -\begin_inset LatexCommand \label{sub:Functions-using-private-banks} +Parameters +\begin_inset LatexCommand \index{function parameter} \end_inset - (mcs51/ds390) + 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 -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)} +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{\_\_using (mcs51, ds390 register bank)} +\begin_inset LatexCommand \index{Overlaying} \end_inset -\emph default - attribute (which tells the compiler to use a register bank -\begin_inset LatexCommand \index{register bank (mcs51, ds390)} +\layout Standard + +For non-reentrant +\begin_inset LatexCommand \index{reentrant} \end_inset - other than the default bank zero). - It should only be applied to + 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 -interrupt -\begin_inset LatexCommand \index{interrupt} +no other function calls and the function is non-reentrant and the memory + model +\begin_inset LatexCommand \index{Memory model} \end_inset + is small. \emph default - 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. + If an explicit storage class +\begin_inset LatexCommand \index{Storage class} + +\end_inset + + is specified for a local variable, it will NOT be overlayed. \layout Standard -The -\emph on -using -\emph default - attribute will have no effect on the generated code for a -\emph on -non-interrupt -\emph default - function (but may occasionally be useful anyway -\begin_inset Foot -collapsed false +Note that the compiler (not the linkage editor) makes the decision for overlayin +g the data items. + Functions that are called from an interrupt service routine +\begin_inset Marginal +collapsed true \layout Standard -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 + +\series bold +! \end_inset -). -\newline + should be preceded by a #pragma\SpecialChar ~ +nooverlay +\begin_inset LatexCommand \index{\#pragma nooverlay} -\emph on -(pending: I don't think this has been done yet) +\end_inset + + if they are not reentrant. \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} +Also note that the compiler does not do any processing of inline assembler + code, so the compiler might incorrectly assign local variables and parameters + of a function into the overlay segment if the inline assembler code calls + other c-functions that might use the overlay. + In that case the #pragma\SpecialChar ~ +nooverlay should be used. +\layout Standard + +Parameters and local variables of functions that contain 16 or 32 bit multiplica +tion +\begin_inset LatexCommand \index{Multiplication} \end_inset + or division +\begin_inset LatexCommand \index{Division} -\begin_inset LatexCommand \index{interrupt priority} +\end_inset + + will NOT be overlayed since these are implemented using external functions, + e.g.: +\layout Verse + + +\family typewriter +#pragma save +\newline +#pragma nooverlay +\begin_inset LatexCommand \index{\#pragma nooverlay} \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 + +\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 + +In the above example the parameter \emph on -using +errcd \emph default - the same bank, terrible and bad things can happen. - To prevent this, no single register bank should be + for the function \emph on -used +set_error \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. - + 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 -Startup Code -\begin_inset LatexCommand \label{sub:Startup-Code} +Interrupt Service Routines +\begin_inset LatexCommand \label{sub:Interrupt-Service-Routines} \end_inset -\begin_inset LatexCommand \index{Startup code} +\layout Subsection -\end_inset +General Information +\layout Standard +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 -\layout Subsection -MCS51/DS390 Startup Code +\family typewriter +void timer_isr (void) __interrupt (1) __using (1) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +} \layout Standard -The compiler inserts a call to the C routine +The optional number following the \emph on -_sdcc_external_startup() -\begin_inset LatexCommand \index{\_sdcc\_external\_startup()} +interrupt +\begin_inset LatexCommand \index{interrupt} \end_inset -\series bold -\emph default - -\series default -at the start of the CODE area. - This routine is in the runtime library -\begin_inset LatexCommand \index{Runtime library} +\begin_inset LatexCommand \index{\_\_interrupt} \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 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 -_sdcc_external_startup() +main \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)} + The optional +\emph on +using +\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)} \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 -\layout Standard +\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)} -\backslash -/ \end_inset --iram-size -\begin_inset LatexCommand \index{-\/-iram-size } - -\end_inset -n \emph default - is used. - (recommended for Chipcon CC1010). + keyword can be used to tell the compiler to use the specified register + bank (8051 specific) when generating code for this function. + +\newline + \layout Standard -See also the compiler option +Interrupt service routines open the door for some very interesting bugs: +\newline +If an interrupt service routine changes variables which are accessed by + other functions these variables have to be declared \emph on -- -\begin_inset ERT -status Collapsed +volatile +\emph default -\layout Standard +\begin_inset LatexCommand \index{volatile} -\backslash -/ \end_inset --no-xinit -\emph default -- -\emph on -opt -\emph default +. + +\layout Standard -\begin_inset LatexCommand \index{-\/-no-xinit-opt} +If the access to these variables is not +\emph on +atomic +\begin_inset LatexCommand \index{atomic} \end_inset - and section -\begin_inset LatexCommand \ref{sub:MCS51-variants} +\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 -\SpecialChar ~ -about MCS51-variants. -\layout Subsection - -HC08 Startup Code -\layout Standard -The HC08 startup code follows the same scheme as the MCS51 startup code. -\layout Subsection +\family typewriter +flags\SpecialChar ~ +|=\SpecialChar ~ +0x80; +\family default -Z80 Startup Code -\layout Standard +\begin_inset Quotes sld +\end_inset -On the Z80 the startup code is inserted by linking with crt0.o which is generated - from sdcc/device/lib/z80/crt0.s. - If you need a different startup code you can use the compiler option -\emph on -- -\series bold -\emph default + is not atomic if +\family typewriter +flags +\family default + resides in xdata. + Setting +\begin_inset Quotes srd +\end_inset -\begin_inset ERT -status Collapsed -\layout Standard +\family typewriter +flags\SpecialChar ~ +|=\SpecialChar ~ +0x40; +\family default -\backslash -/ +\begin_inset Quotes sld \end_inset + from within an interrupt routine might get lost if the interrupt occurs + at the wrong time. + +\begin_inset Quotes sld +\end_inset -\series default -\emph on --no-std-crt0 -\emph default -\begin_inset LatexCommand \index{-\/-no-std-crt0} +\family typewriter +counter\SpecialChar ~ ++=\SpecialChar ~ +8; +\family default +\begin_inset Quotes srd \end_inset - and provide your own crt0.o. + 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 Section +\layout Standard -Inline Assembler Code -\begin_inset LatexCommand \index{Assembler routines} +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 -\layout Subsection +\begin_inset LatexCommand \index{stack overflow} -A Step by Step Introduction -\begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction} +\end_inset + is most likely to happen if the interrupt occurs during the +\begin_inset Quotes sld \end_inset +deepest +\begin_inset Quotes srd +\end_inset + subroutine when the stack is already in use for f.e. + many return addresses. \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 +A special note here, int (16 bit) and long (32 bit) integer division +\begin_inset LatexCommand \index{Division} +\end_inset -\family typewriter -\size footnotesize -unsigned char far -\begin_inset LatexCommand \index{far (storage class)} +, multiplication +\begin_inset LatexCommand \index{Multiplication} \end_inset - -\begin_inset LatexCommand \index{\_\_far (storage class)} + & modulus +\begin_inset LatexCommand \index{Modulus} \end_inset - at -\begin_inset LatexCommand \index{at} + and floating-point +\begin_inset LatexCommand \index{Floating point support} \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 + - +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \index{\_\_at} +\layout Standard +\backslash +/ \end_inset - 0x7f00 buf[0x100]; -\begin_inset LatexCommand \index{Aligned array} +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} \end_inset -\newline -unsigned char head,tail; -\newline +\emph default + option and the source file will need to be compiled using the +\emph on +- +\begin_inset ERT +status Collapsed -\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() -\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 +\backslash +/ \end_inset -_asm -\begin_inset Quotes srd -\end_inset +-int-long-reent +\emph default + +\begin_inset LatexCommand \index{-\/-int-long-reent} - and -\begin_inset Quotes sld \end_inset -_endasm; -\begin_inset Quotes srd + compiler option. + Note, the type promotion +\begin_inset LatexCommand \index{type promotion} + \end_inset - to the beginning and the end of the function body: -\layout Verse + required by ANSI C can cause 16 bit routines to be used without the programmer + being aware of it. + +\layout Standard + +Calling other functions from an interrupt service routine is not recommended, + avoid it if possible. + Note that when some function is called from an interrupt service routine + it should be preceded by a #pragma\SpecialChar ~ +nooverlay +\begin_inset LatexCommand \index{\#pragma nooverlay} +\end_inset -\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 ) + if it is not reentrant. + Furthermore nonreentrant functions should not be called from the main program + while the interrupt service routine might be active. + They also must not be called from low priority interrupt service routines + while a high priority interrupt service routine might be active. + You could use semaphores or make the function +\emph on + critical +\emph default + if all parameters are passed in registers. \newline -{ + \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_asm -\begin_inset LatexCommand \index{\_asm} +Also see section +\begin_inset LatexCommand \ref{sub:Overlaying} \end_inset - -\begin_inset LatexCommand \index{\_\_asm} +\SpecialChar ~ +about Overlaying and section +\begin_inset LatexCommand \ref{sub:Functions-using-private-banks} \end_inset +\SpecialChar ~ +about Functions using private register banks. +\layout Subsection + +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 -\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} -\end_inset +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text -\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} +\layout Standard +Interrupt # \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{\_\_endasm} +Description +\end_inset + + +\begin_inset Text +\layout Standard + +Vector Address \end_inset + + + + +\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 +0 +\end_inset + + +\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 +External 0 +\end_inset + + +\begin_inset Text -\newline -#if !USE_ASSEMBLY -\newline +\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 +0x0003 +\end_inset + + + + +\begin_inset Text -\newline -#else -\newline +\layout Standard -\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} +1 +\end_inset + + +\begin_inset Text +\layout Standard + +Timer 0 \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{\_\_asm} +0x000b +\end_inset + + + + +\begin_inset Text + +\layout Standard +2 \end_inset + + +\begin_inset Text +\layout Standard -\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} - +External 1 \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{\_\_endasm} - +0x0013 \end_inset + + + + +\begin_inset Text -; -\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 +3 +\end_inset + + +\begin_inset Text \layout Standard -The assembler does not like some characters like ':' or ''' in comments. - You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html -\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)} - +Timer 1 \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{Assembler documentation} - +0x001b \end_inset + + + + +\begin_inset Text +\layout Standard +4 \end_inset + + +\begin_inset Text -. - The compiler does not do any validation of the code within the -\family typewriter -_asm -\begin_inset LatexCommand \index{\_asm} +\layout Standard +Serial \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{\_\_asm} - +0x0023 \end_inset + + + + +\begin_inset Text - ... - _endasm -\size footnotesize - -\begin_inset LatexCommand \index{\_endasm} +\layout Standard +5 \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{\_\_endasm} - +Timer 2 (8052) \end_inset + + +\begin_inset Text +\layout Standard -\size default -; -\family default - keyword pair. - Specifically it will not know which registers are used and thus register - pushing/popping -\begin_inset LatexCommand \index{push/pop} - +0x002b \end_inset + + + + +\begin_inset Text - 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 +... +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ \end_inset + + +\begin_inset Text -- -\emph on -peep-asm -\begin_inset LatexCommand \index{-\/-peep-asm} +\layout Standard +... \end_inset + + + + +\begin_inset Text +\layout Standard -\emph default - command line option is used, the inline assembler code will be passed through - the peephole optimizer -\begin_inset LatexCommand \index{Peephole optimizer} - +n \end_inset + + +\begin_inset Text -. - 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} +\layout Standard \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{Naked functions} +0x0003 + 8*n +\end_inset + + + \end_inset +\newline + \layout Standard -A special keyword may be associated with a function declaring it as +If the interrupt service routine is defined without \emph on -_naked -\begin_inset LatexCommand \index{\_naked} +using +\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)} \end_inset -\begin_inset LatexCommand \index{\_\_naked} +\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)} \end_inset -. - + \emph default -The + a register bank or with register bank 0 ( \emph on -_naked +using \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 + 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 - 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 +If the interrupt service routine is defined to be using a specific register + bank then only \emph on -return +a, b, dptr \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 + & psw are saved and restored, if such an interrupt service routine calls + another function (using another register bank) then the entire register + bank of the called function will be saved on the stack. + This scheme is recommended for larger interrupt service routines. +\layout Subsection +HC08 Interrupt Service Routines +\layout Standard -\family typewriter -volatile -\begin_inset LatexCommand \index{volatile} +Since the number of interrupts available is chip specific and the interrupt + vector table always ends at the last byte of memory, the interrupt numbers + corresponds to the interrupt vectors in reverse order of address. + For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt + 2 will use the interrupt vector at 0xfffa, and so on. + However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in + this way; instead see section +\begin_inset LatexCommand \ref{sub:Startup-Code} \end_inset - data unsigned char counter; -\newline - -\newline -void simpleInterrupt(void) interrupt -\begin_inset LatexCommand \index{interrupt} + for details on customizing startup. +\layout Subsection -\end_inset +Z80 Interrupt Service Routines +\layout Standard +The Z80 uses several different methods for determining the correct interrupt + vector depending on the hardware implementation. + Therefore, SDCC ignores the optional interrupt number and does not attempt + to generate an interrupt vector table. +\layout Standard -\begin_inset LatexCommand \index{\_\_interrupt} +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 -\end_inset - 1 +\family typewriter +void nmi_isr (void) critical interrupt \newline -{ +{ \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -counter++; +... + \newline } -\newline +\layout Standard -\newline -void nakedInterrupt(void) interrupt 2 _naked -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_asm -\begin_inset LatexCommand \index{\_asm} +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 + -\begin_inset LatexCommand \index{\_\_asm} +\family typewriter +int foo () __critical +\begin_inset LatexCommand \index{critical} \end_inset +\begin_inset LatexCommand \index{\_\_critical} + +\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 +... + +\newline +} +\layout Standard +The critical attribute maybe used with other attributes like +\emph on +reentrant. +\emph default -\begin_inset LatexCommand \index{\_\_endasm} +\newline +The keyword +\emph on +critical +\emph default + may also be used to disable interrupts more locally: +\layout Verse -\end_inset -; -\newline -} +\family typewriter +__critical{ i++; } \layout Standard -For an 8051 target, the generated simpleInterrupt looks like: +More than one statement could have been included in the block. +\layout Subsection + +Enabling and Disabling Interrupts directly +\layout Standard + +Interrupts +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + can also be disabled and enabled directly (8051): \layout Verse \family typewriter -_simpleInterrupt: -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -push\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -acc -\newline -\SpecialChar ~ -\SpecialChar ~ +EA = 0;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -push\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -b -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -push\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +or:\SpecialChar ~ \SpecialChar ~ -dpl -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -push\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -dph -\newline \SpecialChar ~ \SpecialChar ~ +EA_SAVE = EA; +\layout Verse + + +\family typewriter +...\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 +EA = 0; +\layout Verse + + +\family typewriter +EA = 1;\SpecialChar ~ \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 ~ +... +\layout Verse + + +\family typewriter \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 ~ @@ -12721,310 +12127,552 @@ reti\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -; MUST explicitly include ret or reti in _naked function +EA = EA_SAVE; \layout Standard -The related directive #pragma exclude -\begin_inset LatexCommand \index{\#pragma exclude} +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 - allows a more fine grained control over pushing & popping -\begin_inset LatexCommand \index{push/pop} - -\end_inset + (HC08): +\layout Verse - 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 +#define CLI _asm +\begin_inset LatexCommand \index{\_asm} -Use of Labels within Inline Assembler -\layout Standard +\end_inset -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 -. - +\SpecialChar ~ +\SpecialChar ~ +cli\SpecialChar ~ +\SpecialChar ~ +_endasm +\begin_inset LatexCommand \index{\_endasm} + +\end_inset + +; \layout Verse \family typewriter -_asm -\begin_inset LatexCommand \index{\_asm} +#define SEI _asm\SpecialChar ~ +\SpecialChar ~ +sei\SpecialChar ~ +\SpecialChar ~ +_endasm; +\layout Verse -\end_inset +\family typewriter +... +\layout Standard -\begin_inset LatexCommand \index{\_\_asm} +Note: it is sometimes sufficient to disable only a specific interrupt source + like f.e. + a timer or serial interrupt by manipulating an +\emph on +interrupt mask +\begin_inset LatexCommand \index{interrupt mask} \end_inset + +\emph default + register. -\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} +\layout Standard + +Usually the time during which interrupts are disabled should be kept as + short as possible. + This minimizes both +\emph on +interrupt latency +\emph default + +\begin_inset LatexCommand \index{interrupt latency} \end_inset + (the time between the occurrence of the interrupt and the execution of + the first code in the interrupt routine) and +\emph on +interrupt jitter +\emph default -\begin_inset LatexCommand \index{\_\_endasm} +\begin_inset LatexCommand \index{interrupt jitter} \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 -Inline assembler code cannot reference any C-Labels, however it can reference - labels -\begin_inset LatexCommand \index{Labels} - -\end_inset +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 - defined by the inline assembler, e.g.: -\layout Verse +\begin_inset LatexCommand \index{interrupt priority} +\end_inset -\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 +. + 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 + + and don't add complexity unless you have to. + +\layout Subsection + +Semaphore +\begin_inset LatexCommand \index{semaphore} + +\end_inset + + locking (mcs51/ds390) +\layout Standard + +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 +volatile +\begin_inset LatexCommand \index{volatile} + +\end_inset + + bit resource_is_free; \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -ljmp $0003 + \newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_endasm; +if (resource_is_free) \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 +resource_is_free=0; \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 - - ; +resource_is_free=1; \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} +Note, mcs51 and ds390 support only an atomic +\begin_inset LatexCommand \index{atomic} \end_inset + bit test and +\emph on +clear +\emph default + instruction (as opposed to atomic bit test and +\emph on +set). +\layout Section -\layout Subsection - -Global Registers used for Parameter Passing -\begin_inset LatexCommand \index{Parameter passing} +Functions using private register banks +\begin_inset LatexCommand \label{sub:Functions-using-private-banks} \end_inset - + (mcs51/ds390) \layout Standard -The compiler always uses the global registers +Some architectures have support for quickly changing register sets. + SDCC supports this feature with the \emph on -DPL, DPH -\begin_inset LatexCommand \index{DPTR, DPH, DPL} +using +\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)} \end_inset -\begin_inset LatexCommand \index{DPTR} +\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)} \end_inset -, B -\begin_inset LatexCommand \index{B (mcs51, ds390 register)} + +\emph default + attribute (which tells the compiler to use a register bank +\begin_inset LatexCommand \index{register bank (mcs51, ds390)} \end_inset - -\emph default -and + other than the default bank zero). + It should only be applied to \emph on - ACC -\begin_inset LatexCommand \index{ACC (mcs51, ds390 register)} +interrupt +\begin_inset LatexCommand \index{interrupt} \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 + 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 + +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 -\backslash -/ +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 --stack-auto is used) or in data / xdata memory (depending on the memory - model). - -\layout Subsection +). +\newline -Assembler Routine (non-reentrant) +\emph on +(pending: I don't think this has been done yet) \layout Standard -In the following example -\begin_inset LatexCommand \index{reentrant} +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 -\begin_inset LatexCommand \index{Assembler routines (non-reentrant)} +\begin_inset LatexCommand \index{interrupt priority} \end_inset - the function c_func calls an assembler routine asm_func, which takes two - parameters -\begin_inset LatexCommand \index{function parameter} + can interrupt low-priority ones on the 8051 and friends, this means that + if a high-priority ISR +\emph on +using +\emph default + a particular bank occurs while processing a low-priority ISR +\emph on +using +\emph default + the same bank, terrible and bad things can happen. + To prevent this, no single register bank should be +\emph on +used +\emph default + by both a high priority and a low priority ISR. + This is probably most easily done by having all high priority ISRs use + one bank and all low priority ISRs use another. + If you have an ISR which can change priority at runtime, you're on your + own: I suggest using the default bank zero and taking the small performance + hit. +\layout Standard + +It is most efficient if your ISR calls no other functions. + If your ISR must call other functions, it is most efficient if those functions + use the same bank as the ISR (see note 1 below); the next best is if the + called functions use bank zero. + It is very inefficient to call a function using a different, non-zero bank + from an ISR. + +\layout Section + +Startup Code +\begin_inset LatexCommand \label{sub:Startup-Code} + +\end_inset + + +\begin_inset LatexCommand \index{Startup code} + +\end_inset + + +\layout Subsection + +MCS51/DS390 Startup Code +\layout Standard + +The compiler inserts a call to the C routine +\emph on +_sdcc_external_startup() +\begin_inset LatexCommand \index{\_sdcc\_external\_startup()} + +\end_inset + + +\series bold +\emph default + +\series default +at the start of the CODE area. + This routine is in the runtime library +\begin_inset LatexCommand \index{Runtime library} + +\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)} + +\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 + +\layout Standard + +\backslash +/ +\end_inset + +-iram-size +\begin_inset LatexCommand \index{-\/-iram-size } + +\end_inset + +n +\emph default + is used. + (recommended for Chipcon CC1010). +\layout Standard + +See also the compiler option +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-no-xinit +\emph default +- +\emph on +opt +\emph default + +\begin_inset LatexCommand \index{-\/-no-xinit-opt} + +\end_inset + + and section +\begin_inset LatexCommand \ref{sub:MCS51-variants} + +\end_inset + +\SpecialChar ~ +about MCS51-variants. +\layout Subsection + +HC08 Startup Code +\layout Standard + +The HC08 startup code follows the same scheme as the MCS51 startup code. +\layout Subsection + +Z80 Startup Code +\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 +\emph on +- +\series bold +\emph default + +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + + +\series default +\emph on +-no-std-crt0 +\emph default + +\begin_inset LatexCommand \index{-\/-no-std-crt0} + +\end_inset + + and provide your own crt0.o. + +\layout Section + +Inline Assembler Code +\begin_inset LatexCommand \index{Assembler routines} + +\end_inset + + +\layout Subsection + +A Step by Step Introduction +\begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction} + +\end_inset + + +\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 typewriter -extern int asm_func(unsigned char, unsigned char); -\newline +\size footnotesize +unsigned char __far +\begin_inset LatexCommand \index{far (storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_far (storage class)} + +\end_inset + + __at +\begin_inset LatexCommand \index{at} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_at} + +\end_inset + +(0x7f00) buf[0x100]; +\begin_inset LatexCommand \index{Aligned array} + +\end_inset + \newline -int c_func (unsigned char i, unsigned char j) -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -return asm_func(i,j); -\newline -} +unsigned char head, tail; \newline \newline -int main() +void to_buffer( unsigned char c ) \newline { \newline @@ -13032,17 +12680,34 @@ int main() \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -return c_func(10,9); -\newline -} +if( head != (unsigned char)(tail-1) )\SpecialChar ~ +/* cast +\series bold +needed +\series default + to avoid promotion +\begin_inset LatexCommand \index{promotion to signed int} + +\end_inset + + +\begin_inset LatexCommand \index{type promotion} + +\end_inset + + to integer */ +\begin_inset Marginal +collapsed false + \layout Standard -The corresponding assembler function is: -\layout Verse + +\series bold +\SpecialChar ~ +! +\end_inset -\family typewriter -.globl _asm_func_PARM_2 \newline \SpecialChar ~ \SpecialChar ~ @@ -13052,9 +12717,7 @@ The corresponding assembler function is: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -.globl _asm_func -\newline -\SpecialChar ~ +buf[ head++ ] = c;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -13062,10 +12725,6 @@ The corresponding assembler function is: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -.area OSEG -\newline -_asm_func_PARM_2: -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -13074,1722 +12733,1851 @@ _asm_func_PARM_2: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -.ds 1 +/* 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() +\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 +\begin_inset Quotes srd +\end_inset + + and +\begin_inset Quotes sld +\end_inset + +_endasm; +\begin_inset Quotes srd +\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 ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -.area CSEG -\newline -_asm_func: +_asm +\begin_inset LatexCommand \index{\_asm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_asm} + +\end_inset + + \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +r2,dpl +\newline +;buffer.c if( head != (unsigned char)(tail-1) ) +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ mov\SpecialChar ~ \SpecialChar ~ +a,_tail +\newline +\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -a,dpl +\SpecialChar ~ +dec\SpecialChar ~ +\SpecialChar ~ +a \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +r3,a +\newline +\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +mov\SpecialChar ~ \SpecialChar ~ -add\SpecialChar ~ +a,_head +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -a,_asm_func_PARM_2 +\SpecialChar ~ +cjne a,ar3,00106$ \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +ret +\newline +00106$: +\newline +;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */ +\begin_inset LatexCommand \index{Aligned array} + +\end_inset + + +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ mov\SpecialChar ~ \SpecialChar ~ +r3,_head +\newline \SpecialChar ~ \SpecialChar ~ -dpl,a +\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 ~ -dph -\begin_inset LatexCommand \index{DPTR, DPH, DPL} - -\end_inset - -,#0x00 +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +a,r2 \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +movx @dptr,a +\newline +00103$: +\newline \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 __PARM_, 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 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_endasm +\begin_inset LatexCommand \index{\_endasm} - 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 +\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 __PARM_2. +; \newline +} +\layout Standard -\newline -Assemble the assembler routine with the following command: -\newline +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 -\newline -\family sans -\series bold -asx8051 -losg asmfunc.asm +\family typewriter +\size footnotesize +unsigned char __far __at(0x7f00) buf[0x100]; \newline - +unsigned char head, tail; \newline - -\family default -\series default -Then compile and link the assembler routine to the C source file with the - following command: +#define USE_ASSEMBLY (1) \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); +#if !USE_ASSEMBLY \newline \newline -int c_func (unsigned char i, unsigned char j) reentrant +void to_buffer( unsigned char c ) \newline -{ +{ \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -return asm_func(i,j); +if( head != (unsigned char)(tail-1) ) \newline -} +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +buf[ head++ ] = c; +\newline +} \newline \newline -int main() +#else \newline -{ + +\newline +void to_buffer( unsigned char c ) +\newline +{ \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -return c_func(10,9); +c; // to avoid warning: unreferenced function argument \newline -} -\layout Standard +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_asm +\begin_inset LatexCommand \index{\_asm} -The corresponding assembler routine is: -\layout Verse +\end_inset + + +\begin_inset LatexCommand \index{\_\_asm} + +\end_inset -\family typewriter -.globl _asm_func \newline -_asm_func: +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; save used registers here. + \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -push _bp +\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 ~ -mov _bp,sp +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ + a,_tail \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov r2,dpl +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dec\SpecialChar ~ + a \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov a,_bp +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +xrl\SpecialChar ~ + a,_head \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -add a,#0xfd +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; we could do an ANL a,#0x0f here to use a smaller buffer (see below) \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov r0,a +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +jz\SpecialChar ~ +\SpecialChar ~ + t_b_end$ \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -add a,#0xfc ;? +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; +\newline +; buf[ head++ ] = c; \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov r1,a +\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 ~ -mov a,@r0 +\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 ~ -add a,r2 ;? +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ + dph,#(_buf>>8) \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov dpl,a +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +movx @dptr,a \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov dph,#0x00 +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc \SpecialChar ~ +_head \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov sp,_bp +\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 ~ -pop _bp +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; restore used registers here \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)} +_endasm +\begin_inset LatexCommand \index{\_endasm} \end_inset - and long (32 bit) -\begin_inset LatexCommand \index{long (32 bit)} -\end_inset +\begin_inset LatexCommand \index{\_\_endasm} - Support -\layout Standard +\end_inset -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 /share/sdcc/lib. +; \newline - +} +\newline +#endif \layout Standard -\align center -\begin_inset Tabular - - - - - - -\begin_inset Text +The inline assembler code can contain any valid code understood by the assembler +, this includes any assembler directives and comment lines +\begin_inset Foot +collapsed false \layout Standard +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)} -\series bold -Function \end_inset - - -\begin_inset Text -\layout Standard +\begin_inset LatexCommand \index{Assembler documentation} -\series bold -Description \end_inset - - - - -\begin_inset Text -\layout Standard -_mulint.c \end_inset - - -\begin_inset Text -\layout Standard +. + The compiler does not do any validation of the code within the +\family typewriter +_asm +\begin_inset LatexCommand \index{\_asm} -16 bit multiplication \end_inset - - - - -\begin_inset Text - -\layout Standard -_divsint.c -\end_inset - - -\begin_inset Text -\layout Standard +\begin_inset LatexCommand \index{\_\_asm} - signed 16 bit division (calls _divuint) \end_inset - - - - -\begin_inset Text -\layout Standard + ... + _endasm +\size footnotesize + +\begin_inset LatexCommand \index{\_endasm} -_divuint.c \end_inset - - -\begin_inset Text -\layout Standard - unsigned 16 bit division +\begin_inset LatexCommand \index{\_\_endasm} + \end_inset - - - - -\begin_inset Text -\layout Standard -_modsint.c -\end_inset - - -\begin_inset Text - -\layout Standard - -signed 16 bit modulus (calls _moduint) -\end_inset - - - - -\begin_inset Text - -\layout Standard +\size default +; +\family default + keyword pair. + Specifically it will not know which registers are used and thus register + pushing/popping +\begin_inset LatexCommand \index{push/pop} -_moduint.c \end_inset - - -\begin_inset Text + has to be done manually. + \layout Standard -unsigned 16 bit modulus -\end_inset - - - - -\begin_inset Text +It is recommended that each assembly instruction (including labels) be placed + in a separate line (as the example shows). + When the - +\begin_inset ERT +status Collapsed \layout Standard -_mullong.c +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +- +\emph on +peep-asm +\begin_inset LatexCommand \index{-\/-peep-asm} -32 bit multiplication \end_inset - - - - -\begin_inset Text -\layout Standard - -_divslong.c -\end_inset - - -\begin_inset Text -\layout Standard +\emph default + command line option is used, the inline assembler code will be passed through + the peephole optimizer +\begin_inset LatexCommand \index{Peephole optimizer} - signed 32 division (calls _divulong) \end_inset - - - - -\begin_inset Text - -\layout Standard -_divulong.c -\end_inset - - -\begin_inset Text +. + 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 -\layout Standard +Naked Functions +\begin_inset LatexCommand \label{sub:Naked-Functions} -unsigned 32 division \end_inset - - - - -\begin_inset Text - -\layout Standard -_modslong.c -\end_inset - - -\begin_inset Text -\layout Standard +\begin_inset LatexCommand \index{Naked functions} - signed 32 bit modulus (calls _modulong) \end_inset - - - - -\begin_inset Text - -\layout Standard -_modulong.c -\end_inset - - -\begin_inset Text \layout Standard -unsigned 32 bit modulus -\end_inset - - - +A special keyword may be associated with a function declaring it as +\emph on +_naked +\begin_inset LatexCommand \index{\_naked} \end_inset -\newline +\begin_inset LatexCommand \index{\_\_naked} -\layout Standard +\end_inset -Since they are compiled as +. + +\emph default +The \emph on -non-reentrant +_naked \emph default - -\begin_inset LatexCommand \index{reentrant} + function modifier attribute prevents the compiler from generating prologue +\begin_inset LatexCommand \index{function prologue} \end_inset -, interrupt -\begin_inset LatexCommand \index{interrupt} + and epilogue +\begin_inset LatexCommand \index{function epilogue} \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 + 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 -- -\begin_inset ERT -status Collapsed - -\layout Standard +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 -\backslash -/ -\end_inset --stack-auto -\begin_inset LatexCommand \index{-\/-stack-auto} +\family typewriter +volatile +\begin_inset LatexCommand \index{volatile} \end_inset + data unsigned char counter; +\newline -\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} +\newline +void simpleInterrupt(void) __interrupt +\begin_inset LatexCommand \index{interrupt} \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} +\begin_inset LatexCommand \index{\_\_interrupt} \end_inset + (1) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +counter++; +\newline +} +\newline -\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 +void nakedInterrupt(void) __interrupt (2) __naked +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_asm +\begin_inset LatexCommand \index{\_asm} -\layout Standard -\align center +\end_inset -\size footnotesize -\begin_inset Tabular - - - - - - -\begin_inset Text +\begin_inset LatexCommand \index{\_\_asm} -\layout Standard +\end_inset -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -Function -\end_inset - - -\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} -Description \end_inset - - - - -\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 -_fsadd.c \end_inset - - -\begin_inset Text +; +\newline +} \layout Standard - -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -add floating point numbers -\end_inset - - - - -\begin_inset Text - -\layout Standard +For an 8051 target, the generated simpleInterrupt looks like: +\layout Verse -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_fssub.c -\end_inset - - -\begin_inset Text +\family typewriter +Note, this is an +\series bold +outdated +\series default + example, recent versions of SDCC generate +\newline +the same code for simpleInterrupt() and nakedInterrupt()! +\newline +\newline +_simpleInterrupt: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +acc +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +b +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dph +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +psw +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +psw,#0x00 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_counter +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +psw +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dph +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +b +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +acc +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +reti \layout Standard - -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -subtract floating point numbers -\end_inset - - - - -\begin_inset Text - -\layout Standard +whereas nakedInterrupt looks like: +\layout Verse -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_fsdiv.c -\end_inset - - -\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} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -divide floating point numbers \end_inset - - - - -\begin_inset Text - -\layout Standard + allows a more fine grained control over pushing & popping +\begin_inset LatexCommand \index{push/pop} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_fsmul.c \end_inset - - -\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 -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -multiply floating point numbers -\end_inset - - - - -\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 -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_fs2uchar.c -\end_inset - - -\begin_inset Text - -\layout Standard +\family typewriter +_asm +\begin_inset LatexCommand \index{\_asm} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert floating point to unsigned char \end_inset - - - - -\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 -_fs2char.c \end_inset - - -\begin_inset Text - -\layout Standard + +\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} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert floating point to signed char \end_inset - - - - -\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 -_fs2uint.c \end_inset - - -\begin_inset Text + ; \layout Standard +Inline assembler code cannot reference any C-Labels, however it can reference + labels +\begin_inset LatexCommand \index{Labels} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert floating point to unsigned int \end_inset - - - - -\begin_inset Text -\layout Standard + defined by the inline assembler, e.g.: +\layout Verse -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_fs2int.c -\end_inset - - -\begin_inset Text +\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} -\layout Standard +\end_inset -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert floating point to signed int +\begin_inset LatexCommand \index{\_\_endasm} + \end_inset - - - - -\begin_inset Text + ; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* some more c code */ +\newline +} \layout Standard +In other words inline assembly code can access labels defined in inline + assembly within the scope of the function. + The same goes the other way, i.e. + labels defines in inline assembly can not be accessed by C statements. +\layout Section + +Interfacing with Assembler Code +\begin_inset LatexCommand \index{Assembler routines} -\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 - - -\begin_inset Text -\layout Standard +\layout Subsection + +Global Registers used for Parameter Passing +\begin_inset LatexCommand \index{Parameter passing} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert floating point to unsigned long \end_inset - - - - -\begin_inset Text + \layout Standard +The compiler always uses the global registers +\emph on +DPL, DPH +\begin_inset LatexCommand \index{DPTR, DPH, DPL} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_fs2long.c \end_inset - - -\begin_inset Text -\layout Standard +\begin_inset LatexCommand \index{DPTR} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert floating point to signed long \end_inset - - - - -\begin_inset Text -\layout Standard +, 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)} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_uchar2fs.c \end_inset - - -\begin_inset Text -\layout Standard +\emph default + to pass the first parameter to a routine. + The second parameter onwards is either allocated on the stack (for reentrant + routines or if - +\begin_inset ERT +status Collapsed -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert unsigned char to floating point +\layout Standard + +\backslash +/ \end_inset - - - - -\begin_inset Text +-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} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_char2fs.c \end_inset - - -\begin_inset Text -\layout Standard +\begin_inset LatexCommand \index{Assembler routines (non-reentrant)} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert char to floating point number \end_inset - - - - -\begin_inset Text - -\layout Standard + the function c_func calls an assembler routine asm_func, which takes two + parameters +\begin_inset LatexCommand \index{function parameter} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_uint2fs.c \end_inset - - -\begin_inset Text -\layout Standard +. +\layout Verse -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert unsigned int to floating point -\end_inset - - - - -\begin_inset Text +\family typewriter +extern int asm_func(unsigned char, unsigned char); +\newline -\layout Standard +\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 -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_int2fs.c -\end_inset - - -\begin_inset Text +The corresponding assembler function is: +\layout Verse -\layout Standard +\family typewriter +.globl _asm_func_PARM_2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.globl _asm_func +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area OSEG +\newline +_asm_func_PARM_2: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.ds 1 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area CSEG +\newline +_asm_func: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +a,dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +add\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +a,_asm_func_PARM_2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dpl,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dph +\begin_inset LatexCommand \index{DPTR, DPH, DPL} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert int to floating point numbers \end_inset - - - - -\begin_inset Text +,#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} -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_ulong2fs.c \end_inset - - -\begin_inset Text + are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for + two byte values. + 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph',' +b' & 'acc' for four byte values. \layout Standard - -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert unsigned long to floating point number +The parameter naming convention is __PARM_, where n is + the parameter number starting from 1, and counting from the left. + The first parameter is passed in +\begin_inset Quotes eld \end_inset - - - - -\begin_inset Text -\layout Standard +dpl +\begin_inset Quotes erd +\end_inset + for a one byte parameter, +\begin_inset Quotes eld +\end_inset -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -_long2fs.c -\end_inset - - -\begin_inset Text - -\layout Standard - - -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -convert long to floating point number +dptr +\begin_inset Quotes erd \end_inset - - - + for two bytes, +\begin_inset Quotes eld \end_inset - -\newline - -\layout Standard - -These support routines are developed in ANSI-C so there is room for space - and speed improvement -\begin_inset Foot -collapsed false - -\layout Standard - -The floating point routines for the mcs51 are implemented in assembler +b,dptr +\begin_inset Quotes erd \end_inset -. - Note if all these routines are used simultaneously the data space might - overflow. - For serious floating point usage the large model might be needed. - Also notice that you don't have to call this routines directly. - The compiler will use them automatically every time a floating point operation - is required. -\layout Section - -Library Routines -\begin_inset LatexCommand \index{Libraries} - + for three bytes and +\begin_inset Quotes eld \end_inset - -\layout Standard - - -\emph on - -\layout Subsection - -Compiler support routines (_gptrget, _mulint etc.) -\layout Subsection - -Stdclib functions (puts, printf, strcat etc.) -\layout Subsubsection - - -\layout Standard - - -\begin_inset LatexCommand \index{} - +acc,b,dptr +\begin_inset Quotes erd \end_inset -As usual on embedded systems you have to provide your own -\family typewriter -getchar() -\begin_inset LatexCommand \index{getchar()} + for a four bytes parameter. + The variable name for the second parameter will be __PARM_2. +\newline -\end_inset +\newline +Assemble the assembler routine with the following command: +\newline - -\family default -and -\family typewriter -putchar() -\begin_inset LatexCommand \index{putchar()} +\newline -\end_inset +\family sans +\series bold +asx8051 -losg asmfunc.asm +\newline +\newline \family default - routines. - SDCC does not know whether the system connects to a serial line with or - without handshake, LCD, keyboard or other device. - You'll find examples for serial routines f.e. - in sdcc/device/lib. -\layout Standard - -The default -\family typewriter - printf() -\begin_inset LatexCommand \index{printf()} - -\end_inset +\series default +Then compile and link the assembler routine to the C source file with the + following command: +\newline +\newline -\family default -implementation in -\family typewriter - printf_large.c -\family default - does not support float (except on ds390). - To enable this recompile it with the option -\emph on -- -\begin_inset ERT -status Collapsed +\family sans +\series bold +sdcc cfunc.c asmfunc.rel +\layout Subsection +Assembler Routine (reentrant) \layout Standard -\backslash -/ -\end_inset - -DUSE_FLOATS=1 -\begin_inset LatexCommand \index{USE\_FLOATS} +In this case +\begin_inset LatexCommand \index{reentrant} \end_inset -\emph default - on the command line. - Use -\emph on -- -\begin_inset ERT -status Collapsed - -\layout Standard - -\backslash -/ -\end_inset - --model-large -\begin_inset LatexCommand \index{-\/-model-large} +\begin_inset LatexCommand \index{Assembler routines (reentrant)} \end_inset - -\emph default - for the mcs51 port, since this uses a lot of memory. -\layout Standard - -If you're short on memory you might want to use -\family typewriter -printf_small() -\begin_inset LatexCommand \index{printf\_small()} + 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 default - -\emph on -instead -\emph default - of -\family typewriter - printf(). -\family default - For the mcs51 there additionally are assembly versions \family typewriter -printf_tiny() -\begin_inset LatexCommand \index{printf\_tiny() (mcs51)} +extern int asm_func(unsigned char, unsigned char); +\newline -\end_inset +\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 -\family default - and -\family typewriter -printf_fast() -\begin_inset LatexCommand \index{printf\_fast() (mcs51)} +The corresponding assembler routine is: +\layout Verse -\end_inset - -\family default -and \family typewriter - printf_fast_f() -\begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)} - -\end_inset - - -\family default - which should fit the requirements of many embedded systems (printf_fast() - can be customized by unsetting #defines to -\emph on -not -\emph default - support long variables and field widths). -\layout Subsection - -Math functions (sin, pow, sqrt etc.) -\layout Subsection - -Other libraries -\layout Standard - -Libraries -\begin_inset LatexCommand \index{Libraries} +.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 -\end_inset +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 - included in SDCC should have a license at least as liberal as the GNU Lesser - General Public License -\begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL} +int (16 bit) +\begin_inset LatexCommand \index{int (16 bit)} \end_inset - -\emph on -LGPL -\emph default -. -\layout Comment + and long (32 bit) +\begin_inset LatexCommand \index{long (32 bit)} -license statements for the libraries are missing. - sdcc/device/lib/ser_ir.c -\layout Comment +\end_inset -or _decdptr f.e. - come with a GPL (as opposed to LGPL) License - this will not be liberal - enough for many embedded programmers. + Support \layout Standard -If you have ported some library or want to share experience about some code - which f.e. - falls into any of these categories Busses (I -\begin_inset Formula $^{\textrm{2}}$ -\end_inset - -C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory - cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel, - Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list -\begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599} +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 /share/sdcc/lib. +\newline -\end_inset +\layout Standard +\align center -\SpecialChar ~ -would certainly like to hear about it. - Programmers coding for embedded systems are not especially famous for being - enthusiastic, so don't expect a big hurray but as the mailing list is searchabl -e these references are very valuable. - Let's help to create a climate where information is shared. -\layout Section +\begin_inset Tabular + + + + + + +\begin_inset Text -Memory Models -\layout Subsection +\layout Standard -MCS51 Memory Models -\begin_inset LatexCommand \index{Memory model} +\series bold +Function \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{MCS51 memory model} +\series bold +Description \end_inset + + + + +\begin_inset Text +\layout Standard -\layout Subsubsection +_mulint.c +\end_inset + + +\begin_inset Text -Small and Large \layout Standard -SDCC allows two memory models for MCS51 code, -\shape slanted -small -\shape default - and -\shape slanted -large -\shape default -. - Modules compiled with different memory models should -\emph on -never -\emph default - be combined together or the results would be unpredictable. - The library routines supplied with the compiler are compiled as both small - and large. - The compiled library modules are contained in separate directories as small - and large so that you can link to either set. - -\layout Standard +16 bit multiplication +\end_inset + + + + +\begin_inset Text -When the large model is used all variables declared without a storage class - will be allocated into the external ram, this includes all parameters and - local variables (for non-reentrant -\begin_inset LatexCommand \index{reentrant} +\layout Standard +_divsint.c \end_inset + + +\begin_inset Text - functions). - When the small model is used variables without storage class are allocated - in the internal ram. \layout Standard -Judicious usage of the processor specific storage classes -\begin_inset LatexCommand \index{Storage class} - + signed 16 bit division (calls _divuint) \end_inset + + + + +\begin_inset Text - and the 'reentrant' function type will yield much more efficient code, - than using the large model. - Several optimizations are disabled when the program is compiled using the - large model, it is therefore recommended that the small model be used unless - absolutely required. -\layout Subsubsection - -External Stack -\begin_inset LatexCommand \label{sub:External-Stack} +\layout Standard +_divuint.c \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{stack} - + unsigned 16 bit division \end_inset + + + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{External stack (mcs51)} - +_modsint.c \end_inset - + + +\begin_inset Text \layout Standard -The external stack (- -\begin_inset ERT -status Collapsed +signed 16 bit modulus (calls _moduint) +\end_inset + + + + +\begin_inset Text \layout Standard -\backslash -/ +_moduint.c \end_inset + + +\begin_inset Text --xstack option -\begin_inset LatexCommand \index{-\/-xstack} +\layout Standard +unsigned 16 bit modulus \end_inset + + + + +\begin_inset Text -) is located in pdata -\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} +\layout Standard +_mullong.c \end_inset - - memory (usually at the start of the external ram segment) and uses all - unused space in pdata (max. - 256 bytes). - When - -\begin_inset ERT -status Collapsed + + +\begin_inset Text \layout Standard -\backslash -/ +32 bit multiplication \end_inset + + + + +\begin_inset Text --xstack option is used to compile the program, the parameters and local - variables -\begin_inset LatexCommand \index{local variables} +\layout Standard +_divslong.c \end_inset - - of all reentrant functions are allocated in this area. - This option is provided for programs with large stack space requirements. - When used with the - -\begin_inset ERT -status Collapsed + + +\begin_inset Text \layout Standard -\backslash -/ + signed 32 division (calls _divulong) \end_inset + + + + +\begin_inset Text --stack-auto -\begin_inset LatexCommand \index{-\/-stack-auto} +\layout Standard +_divulong.c \end_inset + + +\begin_inset Text - option, all parameters and local variables are allocated on the external - stack (note: support libraries will need to be recompiled with the same - options. - There is a predefined target in the library makefile). \layout Standard -The compiler outputs the higher order address byte of the external ram segment - into port P2 -\begin_inset LatexCommand \index{P2 (mcs51 sfr)} - +unsigned 32 division \end_inset + + + + +\begin_inset Text - (see also section -\begin_inset LatexCommand \ref{sub:MCS51-variants} +\layout Standard +_modslong.c \end_inset + + +\begin_inset Text -), therefore when using the External Stack option, this port -\emph on -may not -\emph default - be used by the application program. -\layout Subsection - -DS390 Memory Model -\begin_inset LatexCommand \index{Memory model} +\layout Standard + signed 32 bit modulus (calls _modulong) \end_inset + + + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{DS390 memory model} - +_modulong.c \end_inset - + + +\begin_inset Text \layout Standard -The only model supported is Flat 24 -\begin_inset LatexCommand \index{Flat 24 (DS390 memory model)} +unsigned 32 bit modulus +\end_inset + + + \end_inset -. - This generates code for the 24 bit contiguous addressing mode of the Dallas - DS80C390 part. - In this mode, up to four meg of external RAM or code space can be directly - addressed. - See the data sheets at www.dalsemi.com for further information on this part. -\newline \newline -Note that the compiler does not generate any code to place the processor - into 24 bitmode (although -\emph on -tinibios -\emph default - in the ds390 libraries will do that for you). - If you don't use + +\layout Standard + +Since they are compiled as \emph on -tinibios +non-reentrant \emph default -\begin_inset LatexCommand \index{Tinibios (DS390)} +\begin_inset LatexCommand \index{reentrant} \end_inset -, the boot loader or similar code must ensure that the processor is in 24 - bit contiguous addressing mode before calling the SDCC startup code. -\newline +, interrupt +\begin_inset LatexCommand \index{interrupt} -\newline -Like the +\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 @@ -14801,15 +14589,16 @@ status Collapsed / \end_inset --model-large -\emph default - option, variables will by default be placed into the XDATA segment. - -\newline +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} -\newline -Segments may be placed anywhere in the 4 meg address space using the usual - - +\end_inset + + +\emph default + option, after which the source program will have to be compiled with +\emph on +- \begin_inset ERT status Collapsed @@ -14819,472 +14608,562 @@ status Collapsed / \end_inset --*-loc options. - Note that if any segments are located above 64K, the -r flag must be passed - to the linker to generate the proper segment relocations, and the Intel - HEX output format must be used. - The -r flag can be passed to the linker by using the option -\emph on --Wl-r -\emph default - on the SDCC command line. - However, currently the linker can not handle code segments > 64k. -\layout Section - -Pragmas -\begin_inset LatexCommand \index{Pragmas} +-int-long-reent +\begin_inset LatexCommand \index{-\/-int-long-reent} \end_inset -\layout Standard - -SDCC supports the following #pragma directives: -\layout Itemize +\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 -save -\begin_inset LatexCommand \index{\#pragma save} +Floating Point Support +\begin_inset LatexCommand \index{Floating point support} \end_inset - - this will save all current options to the save/restore stack. - See #pragma\SpecialChar ~ -restore. -\layout Itemize -restore -\begin_inset LatexCommand \index{\#pragma restore} - -\end_inset +\layout Standard - - will restore saved options from the last save. - saves & restores can be nested. - SDCC uses a save/restore stack: save pushes current options to the stack, - restore pulls current options from the stack. - See #pragma\SpecialChar ~ -save. +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 Itemize +\layout Standard +\align center -callee_saves -\begin_inset LatexCommand \index{\#pragma callee\_saves} +\size footnotesize -\end_inset +\begin_inset Tabular + + + + + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{function prologue} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +Function \end_inset + + +\begin_inset Text - function1[,function2[,function3...]] - The compiler by default uses a caller - saves convention for register saving across function calls, however this - can cause unnecessary register pushing & popping -\begin_inset LatexCommand \index{push/pop} +\layout Standard +Description \end_inset - - when calling small functions from larger functions. - This option can be used to switch off the register saving convention for - the function names specified. - The compiler will not save registers when calling these functions, extra - code need to be manually inserted at the entry & exit for these functions - to save & restore the registers used by these functions, this can SUBSTANTIALLY - reduce code & improve run time performance of the generated code. - In the future the compiler (with inter procedural analysis) may be able - to determine the appropriate scheme to use for each function call. - If - -\begin_inset ERT -status Collapsed + + + + +\begin_inset Text \layout Standard -\backslash -/ -\end_inset - --callee-saves command line option is used, the function names specified - in #pragma\SpecialChar ~ -callee_saves -\begin_inset LatexCommand \index{\#pragma callee\_saves} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fsadd.c \end_inset + + +\begin_inset Text - is appended to the list of functions specified in the command line. -\layout Itemize +\layout Standard -exclude -\begin_inset LatexCommand \index{\#pragma exclude} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +add floating point numbers \end_inset + + + + +\begin_inset Text - none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation - of pairs of push/pop -\begin_inset LatexCommand \index{push/pop} - -\end_inset +\layout Standard - instructions in -\emph on -I -\emph default -nterrupt -\begin_inset LatexCommand \index{interrupt} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fssub.c \end_inset + + +\begin_inset Text - -\emph on -S -\emph default -ervice -\emph on -R -\emph default -outines. - The directive should be placed immediately before the ISR function definition - and it affects ALL ISR functions following it. - To enable the normal register saving for ISR functions use #pragma\SpecialChar ~ -exclude\SpecialChar ~ -none -\begin_inset LatexCommand \index{\#pragma exclude} - -\end_inset +\layout Standard -. - See also the related keyword _naked -\begin_inset LatexCommand \index{\_naked} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +subtract floating point numbers \end_inset + + + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{\_\_naked} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fsdiv.c \end_inset + + +\begin_inset Text -. -\layout Itemize +\layout Standard -less_pedantic -\begin_inset LatexCommand \index{\#pragma less\_pedantic} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +divide floating point numbers \end_inset + + + + +\begin_inset Text - - the compiler will not warn you anymore for obvious mistakes, you'r on - your own now ;-( -\layout Itemize +\layout Standard -disable_warning -\begin_inset LatexCommand \index{\#pragma disable\_warning} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fsmul.c \end_inset + + +\begin_inset Text - - the compiler will not warn you anymore about warning number . -\layout Itemize +\layout Standard -nogcse -\begin_inset LatexCommand \index{\#pragma nogcse} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +multiply floating point numbers \end_inset + + + + +\begin_inset Text - - will stop global common subexpression elimination. -\layout Itemize +\layout Standard -noinduction -\begin_inset LatexCommand \index{\#pragma noinduction} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2uchar.c \end_inset + + +\begin_inset Text - - will stop loop induction optimizations. -\layout Itemize - -noinvariant -\begin_inset LatexCommand \index{\#pragma noinvariant} - -\end_inset +\layout Standard - - will not do loop invariant optimizations. - For more details see Loop Invariants in section -\begin_inset LatexCommand \ref{sub:Loop-Optimizations} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to unsigned char \end_inset + + + + +\begin_inset Text -. -\layout Itemize +\layout Standard -noiv -\begin_inset LatexCommand \index{\#pragma noiv} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2char.c \end_inset + + +\begin_inset Text - - Do not generate interrupt -\begin_inset LatexCommand \index{interrupt} +\layout Standard -\end_inset - - vector table entries for all ISR functions defined after the pragma. - This is useful in cases where the interrupt vector table must be defined - manually, or when there is a secondary, manually defined interrupt vector - table (e.g. - for the autovector feature of the Cypress EZ-USB FX2). - More elegantly this can be achieved by obmitting the optional interrupt - number after the interrupt keyword, see section -\begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to signed char \end_inset + + + + +\begin_inset Text -\SpecialChar ~ -about interrupts. -\layout Itemize - -nojtbound -\begin_inset LatexCommand \index{\#pragma nojtbound} - -\end_inset +\layout Standard - - will not generate code for boundary value checking, when switch statements - are turned into jump-tables (dangerous). - For more details see section -\begin_inset LatexCommand \ref{sub:'switch'-Statements} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2uint.c \end_inset + + +\begin_inset Text -. -\layout Itemize +\layout Standard -noloopreverse -\begin_inset LatexCommand \index{\#pragma noloopreverse} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to unsigned int \end_inset + + + + +\begin_inset Text - - Will not do loop reversal optimization -\layout Itemize +\layout Standard -nooverlay -\begin_inset LatexCommand \index{\#pragma nooverlay} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2int.c \end_inset + + +\begin_inset Text - - the compiler will not overlay the parameters and local variables of a - function. -\layout Itemize +\layout Standard -stackauto -\begin_inset LatexCommand \index{\#pragma stackauto} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to signed int \end_inset - -- See option - -\begin_inset ERT -status Collapsed + + + + +\begin_inset Text \layout Standard -\backslash -/ -\end_inset - --stack-auto -\begin_inset LatexCommand \index{-\/-stack-auto} +\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 + + +\begin_inset Text - and section -\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables} +\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 + + + + +\begin_inset Text - Parameters and Local Variables. -\layout Itemize +\layout Standard -opt_code_speed -\begin_inset LatexCommand \index{\#pragma opt\_code\_speed} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2long.c \end_inset + + +\begin_inset Text -- The compiler will optimize code generation towards fast code, possibly - at the expense of code size. -\layout Itemize +\layout Standard -opt_code_size -\begin_inset LatexCommand \index{\#pragma opt\_code\_size} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to signed long \end_inset + + + + +\begin_inset Text -- The compiler will optimize code generation towards compact code, possibly - at the expense of code speed. -\layout Itemize +\layout Standard -opt_code_balanced -\begin_inset LatexCommand \index{\#pragma opt\_code\_balanced} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_uchar2fs.c \end_inset + + +\begin_inset Text -- The compiler will attempt to generate code that is both compact and fast, - as long as meeting one goal is not a detriment to the other (this is the - default). - -\layout Itemize +\layout Standard -std_sdcc89 -\begin_inset LatexCommand \index{\#pragma std\_sdcc89} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert unsigned char to floating point \end_inset + + + + +\begin_inset Text -- Generally follow the C89 standard, but allow SDCC features that conflict - with the standard (default). -\layout Itemize +\layout Standard -std_c89 -\begin_inset LatexCommand \index{\#pragma std\_c89} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_char2fs.c \end_inset + + +\begin_inset Text -- Follow the C89 standard and disable SDCC features that conflict with the - standard. -\layout Itemize - -std_sdcc99 -\begin_inset LatexCommand \index{\#pragma std\_sdcc99} +\layout Standard -\end_inset - -- Generally follow the C99 standard, but allow SDCC features that conflict - with the standard (incomplete support). -\layout Itemize - -std_c99 -\begin_inset LatexCommand \index{\#pragma std\_c99} - -\end_inset - -- Follow the C99 standard and disable SDCC features that conflict with the - standard (incomplete support). -\layout Standard - -SDCPP supports the following #pragma directives: -\layout Itemize - -preproc_asm -\begin_inset LatexCommand \index{\#pragma preproc\_asm} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert char to floating point number \end_inset + + + + +\begin_inset Text - (+ | -) - switch _asm _endasm block preprocessing on / off. - Default is on. \layout Standard -The pragma's are intended to be used to turn-on or off certain optimizations - which might cause the compiler to generate extra stack / data space to - store compiler generated temporary variables. - This usually happens in large functions. - Pragma directives should be used as shown in the following example, they - are used to control options & optimizations for a given function; pragmas - should be placed before and/or after a function, placing pragma's inside - a function body could have unpredictable results. -\layout Verse - - -\family typewriter -#pragma save -\begin_inset LatexCommand \index{\#pragma save} - -\end_inset - - \SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* save the current settings */ -\newline -#pragma nogcse -\begin_inset LatexCommand \index{\#pragma nogcse} - -\end_inset - - \SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* turnoff global subexpression elimination */ -\newline -#pragma noinduction -\begin_inset LatexCommand \index{\#pragma noinduction} - -\end_inset - - /* turn off induction optimizations */ -\newline -int foo () -\newline -{ -\newline -\SpecialChar ~ - \SpecialChar ~ - ... - -\newline -\SpecialChar ~ - \SpecialChar ~ - /* large code */ -\newline -\SpecialChar ~ - \SpecialChar ~ - ... - -\newline -} -\newline -#pragma restore -\begin_inset LatexCommand \index{\#pragma restore} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_uint2fs.c \end_inset + + +\begin_inset Text - /* turn the optimizations back on */ -\layout Standard - -The compiler will generate a warning message when extra space is allocated. - It is strongly recommended that the save and restore pragma's be used when - changing options for a function. -\layout Section - -Defines Created by the Compiler \layout Standard -The compiler creates the following #defines -\begin_inset LatexCommand \index{\#defines} - -\end_inset - - -\begin_inset LatexCommand \index{Defines created by the compiler} +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert unsigned int to floating point \end_inset - -: -\newline - -\layout Standard - - -\begin_inset Tabular - - - - - + + + \begin_inset Text \layout Standard -\series bold -#define +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_int2fs.c \end_inset @@ -15293,8 +15172,15 @@ The compiler creates the following #defines \layout Standard -\series bold -Description +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert int to floating point numbers \end_inset @@ -15304,12 +15190,16 @@ Description \layout Standard -SDCC -\begin_inset LatexCommand \index{SDCC} - -\end_inset - +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_ulong2fs.c \end_inset @@ -15317,32 +15207,35 @@ SDCC \layout Standard -this Symbol is always defined + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert unsigned long to floating point number \end_inset - + \begin_inset Text \layout Standard -SDCC_mcs51 -\begin_inset LatexCommand \index{SDCC\_mcs51} - -\end_inset - - or SDCC_ds390 -\begin_inset LatexCommand \index{SDCC\_ds390} - -\end_inset - - or SDCC_z80 -\begin_inset LatexCommand \index{SDCC\_z80} - -\end_inset -, etc +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_long2fs.c \end_inset @@ -15350,106 +15243,135 @@ SDCC_mcs51 \layout Standard -depending on the model used (e.g.: -mds390 + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert long to floating point number \end_inset - - -\begin_inset Text - -\layout Standard - -__mcs51 -\begin_inset LatexCommand \index{\_\_mcs51} + \end_inset -, __ds390 -\begin_inset LatexCommand \index{\_\_ds390} - -\end_inset -, __hc08 -\begin_inset LatexCommand \index{\_\_hc08} +\newline -\end_inset +\layout Standard -, __z80 -\begin_inset LatexCommand \index{\_\_z80} +These support routines are developed in ANSI-C so there is room for space + and speed improvement +\begin_inset Foot +collapsed false -\end_inset +\layout Standard -, etc +These floating point routines ( +\emph on +not +\emph default + sinf(), cosf(), ...) for the mcs51 are implemented in assembler. + \end_inset - - -\begin_inset Text -\layout Standard +. + Note if all these routines are used simultaneously the data space might + overflow. + For serious floating point usage the large model might be needed. + Also notice that you don't have to call this routines directly. + The compiler will use them automatically every time a floating point operation + is required. +\layout Section + +Library Routines +\begin_inset LatexCommand \index{Libraries} -depending on the model used (e.g. - -mz80) \end_inset - - - - -\begin_inset Text + \layout Standard -SDCC_STACK_AUTO -\begin_inset LatexCommand \index{SDCC\_STACK\_AUTO} -\end_inset +\emph on + +\layout Subsection +Compiler support routines (_gptrget, _mulint etc.) +\layout Subsection -\end_inset - - -\begin_inset Text +Stdclib functions (puts, printf, strcat etc.) +\layout Subsubsection + \layout Standard -when -\emph on -- -\begin_inset ERT -status Collapsed -\layout Standard +\begin_inset LatexCommand \index{} -\backslash -/ \end_inset --stack-auto -\emph default - option is used -\end_inset - - - - -\begin_inset Text +As usual on embedded systems you have to provide your own +\family typewriter +getchar() +\begin_inset LatexCommand \index{getchar()} -\layout Standard +\end_inset -SDCC_MODEL_SMALL -\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL} + +\family default +and +\family typewriter +putchar() +\begin_inset LatexCommand \index{putchar()} \end_inset +\family default + routines. + SDCC does not know whether the system connects to a serial line with or + without handshake, LCD, keyboard or other device. + And whether a +\family typewriter +lf +\family default + to +\family typewriter +crlf +\family default + conversion within +\family typewriter +putchar() +\family default + is intended. + You'll find examples for serial routines f.e. + in sdcc/device/lib. +\layout Standard + +The default +\family typewriter + printf() +\begin_inset LatexCommand \index{printf()} + \end_inset - - -\begin_inset Text -\layout Standard -when +\family default +implementation in +\family typewriter + printf_large.c +\family default + does not support float (except on ds390). + To enable this recompile it with the option \emph on - \begin_inset ERT @@ -15461,34 +15383,17 @@ status Collapsed / \end_inset --model-small -\emph default - is used -\end_inset - - - - -\begin_inset Text - -\layout Standard - -SDCC_MODEL_LARGE -\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE} - -\end_inset - +DUSE_FLOATS=1 +\begin_inset LatexCommand \index{USE\_FLOATS} \end_inset - - -\begin_inset Text -\layout Standard -when +\emph default + on the command line. + Use \emph on -- + - \begin_inset ERT status Collapsed @@ -15499,888 +15404,718 @@ status Collapsed \end_inset -model-large -\emph default - is used -\end_inset - - - - -\begin_inset Text +\begin_inset LatexCommand \index{-\/-model-large} -\layout Standard +\end_inset -SDCC_USE_XSTACK -\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK} -\end_inset +\emph default + for the mcs51 port, since this uses a lot of memory. +\layout Standard +If you're short on memory you might want to use +\family typewriter +printf_small() +\begin_inset LatexCommand \index{printf\_small()} \end_inset - - -\begin_inset Text -\layout Standard -when +\family default + \emph on -- -\begin_inset ERT -status Collapsed - -\layout Standard +instead +\emph default + of +\family typewriter + printf(). -\backslash -/ -\end_inset +\family default + For the mcs51 there additionally are assembly versions +\family typewriter +printf_tiny() +\begin_inset LatexCommand \index{printf\_tiny() (mcs51)} --xstack -\emph default - option is used \end_inset - - - - -\begin_inset Text -\layout Standard -SDCC_STACK_TENBIT -\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT} +\family default + (subset of printf using less than 270 bytes) and +\family typewriter +printf_fast() +\begin_inset LatexCommand \index{printf\_fast() (mcs51)} \end_inset +\family default +and +\family typewriter + printf_fast_f() +\begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)} + \end_inset - - -\begin_inset Text -\layout Standard -when +\family default + (floating-point aware version of printf_fast) which should fit the requirements + of many embedded systems (printf_fast() can be customized by unsetting + #defines to \emph on --mds390 +not \emph default - is used -\end_inset - - - - -\begin_inset Text + support long variables and field widths). +\layout Subsection + +Math functions (sinf, powf, sqrtf etc.) +\layout Subsubsection + \layout Standard -SDCC_MODEL_FLAT24 -\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24} +See definitions in file . +\layout Subsection -\end_inset +Other libraries +\layout Standard +Libraries +\begin_inset LatexCommand \index{Libraries} \end_inset - - -\begin_inset Text -\layout Standard + included in SDCC should have a license at least as liberal as the GNU Lesser + General Public License +\begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL} -when -\emph on --mds390 -\emph default - is used \end_inset - - - -\end_inset - - -\layout Chapter + +\emph on +LGPL +\emph default +. +\layout Comment -Notes on supported Processors -\layout Section +license statements for the libraries are missing. + sdcc/device/lib/ser_ir.c +\layout Comment -MCS51 variants -\begin_inset LatexCommand \label{sub:MCS51-variants} +or _decdptr f.e. + come with a GPL (as opposed to LGPL) License - this will not be liberal + enough for many embedded programmers. +\layout Standard +If you have ported some library or want to share experience about some code + which f.e. + falls into any of these categories Busses (I +\begin_inset Formula $^{\textrm{2}}$ \end_inset - -\begin_inset LatexCommand \index{MCS51 variants} +C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory + cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel, + Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list +\begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599} \end_inset +\SpecialChar ~ +would certainly like to hear about it. + Programmers coding for embedded systems are not especially famous for being + enthusiastic, so don't expect a big hurray but as the mailing list is searchabl +e these references are very valuable. + Let's help to create a climate where information is shared. +\layout Section -\layout Standard - -MCS51 processors are available from many vendors and come in many different - flavours. - While they might differ considerably in respect to Special Function Registers - the core MCS51 is usually not modified or is kept compatible. - +Memory Models \layout Subsection -pdata access by SFR -\layout Standard - -With the upcome of devices with internal xdata and flash memory devices - using port P2 -\begin_inset LatexCommand \index{P2 (mcs51 sfr)} +MCS51 Memory Models +\begin_inset LatexCommand \index{Memory model} \end_inset - as dedicated I/O port is becoming more popular. - Switching the high byte for pdata -\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} + +\begin_inset LatexCommand \index{MCS51 memory model} \end_inset - access which was formerly done by port P2 is then achieved by a Special - Function Register -\begin_inset LatexCommand \index{sfr} -\end_inset +\layout Subsubsection + +Small, Medium and Large +\layout Standard +SDCC allows three memory models for MCS51 code, +\shape slanted +small, medium +\shape default + and +\shape slanted +large +\shape default . - In well-established MCS51 tradition the address of this + Modules compiled with different memory models should \emph on -sfr +never \emph default - is where the chip designers decided to put it. - Needless to say that they didn't agree on a common name either. - So that the startup code can correctly initialize xdata variables, you - should define an sfr with the name _XPAGE -\family typewriter + be combined together or the results would be unpredictable. + The library routines supplied with the compiler are compiled as small, + medium and large. + The compiled library modules are contained in separate directories as small, + medium and large so that you can link to the appropriate set. +\layout Standard -\begin_inset LatexCommand \index{\_XPAGE (mcs51)} +When the medium or large model is used all variables declared without a + storage class will be allocated into the external ram, this includes all + parameters and local variables (for non-reentrant +\begin_inset LatexCommand \index{reentrant} \end_inset + functions). + When the small model is used variables without storage class are allocated + in the internal ram. +\layout Standard -\family default - at the appropriate location if the default, port P2, is not used for this. - Some examples are: -\layout Verse - +Judicious usage of the processor specific storage classes +\begin_inset LatexCommand \index{Storage class} -\family typewriter -sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */ -\layout Verse +\end_inset + and the 'reentrant' function type will yield much more efficient code, + than using the large model. + Several optimizations are disabled when the program is compiled using the + large model, it is therefore recommended that the small model be used unless + absolutely required. +\layout Subsubsection -\family typewriter -sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */ -\layout Verse +External Stack +\begin_inset LatexCommand \label{sub:External-Stack} +\end_inset -\family typewriter -sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */ -\layout Standard -For more exotic implementations further customizations may be needed. - See section -\begin_inset LatexCommand \ref{sub:Startup-Code} +\begin_inset LatexCommand \index{stack} \end_inset - for other possibilities. -\layout Subsection - -Other Features available by SFR -\layout Standard -Some MCS51 variants offer features like Double DPTR -\begin_inset LatexCommand \index{DPTR} +\begin_inset LatexCommand \index{External stack (mcs51)} \end_inset -, multiple DPTR, decrementing DPTR, 16x16 Multiply. - These are currently not used for the MCS51 port. - If you absolutely need them you can fall back to inline assembly or submit - a patch to SDCC. -\layout Section -DS400 port \layout Standard -The DS80C400 microcontroller has a rich set of peripherals. - In its built-in ROM library it includes functions to access some of the - features, among them is a TCP stack with IP4 and IP6 support. - Library headers (currently in beta status) and other files are provided - at -\size footnotesize - -\begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html} - -\end_inset - -. - -\layout Section +The external stack (- +\begin_inset ERT +status Collapsed -The Z80 and gbz80 port \layout Standard -SDCC can target both the Zilog -\begin_inset LatexCommand \index{Z80} - +\backslash +/ \end_inset - and the Nintendo Gameboy's Z80-like gbz80 -\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)} +-xstack option +\begin_inset LatexCommand \index{-\/-xstack} \end_inset -. - The Z80 port is passed through the same -\emph on -regressions tests -\begin_inset LatexCommand \index{Regression test} +) is located in pdata +\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} \end_inset + memory (usually at the start of the external ram segment) and uses all + unused space in pdata (max. + 256 bytes). + When - +\begin_inset ERT +status Collapsed -\emph default - as the MCS51 and DS390 ports, so floating point support, support for long - variables and bitfield support is fine. - See mailing lists and forums about interrupt routines. \layout Standard -As always, the code is the authoritative reference - see z80/ralloc.c and - z80/gen.c. - The stack -\begin_inset LatexCommand \index{stack} - +\backslash +/ \end_inset - frame is similar to that generated by the IAR Z80 compiler. - IX is used as the base pointer, HL and IY are used as a temporary registers, - and BC and DE are available for holding variables. - Return values -\begin_inset LatexCommand \index{return value} +-xstack option is used to compile the program, the parameters and local + variables +\begin_inset LatexCommand \index{local variables} \end_inset - for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four - bytes). - The gbz80 port use the same set of registers for the return values, but - in a different order of significance: E (one byte), DE (two bytes), or - HLDE (four bytes). -\layout Section + of all reentrant functions are allocated in this area. + This option is provided for programs with large stack space requirements. + When used with the - +\begin_inset ERT +status Collapsed -The HC08 port \layout Standard -The port to the Motorola HC08 -\begin_inset LatexCommand \index{HC08} - +\backslash +/ \end_inset - family has been added in October 2003, and is still undergoing some basic - development. - The code generator is complete, but the register allocation is still quite - unoptimized. - Some of the SDCC's standard C library functions have embedded non-HC08 - inline assembly and so are not yet usable. -\newline - -\newline +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} -\layout Section +\end_inset -The PIC14 port + option, all parameters and local variables are allocated on the external + stack (note: support libraries will need to be recompiled with the same + options. + There is a predefined target in the library makefile). \layout Standard -The 14bit PIC -\begin_inset LatexCommand \index{PIC14} +The compiler outputs the higher order address byte of the external ram segment + into port P2 +\begin_inset LatexCommand \index{P2 (mcs51 sfr)} \end_inset - port still requires a major effort from the development community. - However it can work for very simple code. + (see also section +\begin_inset LatexCommand \ref{sub:MCS51-variants} + +\end_inset + +), therefore when using the External Stack option, this port +\emph on +may not +\emph default + be used by the application program. \layout Subsection -C code and 14bit PIC code page -\begin_inset LatexCommand \index{code page (pic14)} +DS390 Memory Model +\begin_inset LatexCommand \index{Memory model} \end_inset - and RAM banks -\begin_inset LatexCommand \index{RAM bank (pic14)} + +\begin_inset LatexCommand \index{DS390 memory model} \end_inset \layout Standard -The linker organizes allocation for the code page and RAM banks. - It does not have intimate knowledge of the code flow. - It will put all the code section of a single asm file into a single code - page. - In order to make use of multiple code pages, separate asm files must be - used. - The compiler treats all functions of a single C file as being in the same - code page unless it is non static. - The compiler treats all local variables of a single C file as being in - the same RAM bank unless it is an extern. -\newline +The only model supported is Flat 24 +\begin_inset LatexCommand \index{Flat 24 (DS390 memory model)} +\end_inset + +. + This generates code for the 24 bit contiguous addressing mode of the Dallas + DS80C390 part. + In this mode, up to four meg of external RAM or code space can be directly + addressed. + See the data sheets at www.dalsemi.com for further information on this part. \newline -To get the best follow these guide lines: -\layout Enumerate -make local functions static, as non static functions require code page selection - overhead. -\layout Enumerate +\newline +Note that the compiler does not generate any code to place the processor + into 24 bitmode (although +\emph on +tinibios +\emph default + in the ds390 libraries will do that for you). + If you don't use +\emph on +tinibios +\emph default -Make local variables static as extern variables require RAM bank selection - overhead. -\layout Enumerate +\begin_inset LatexCommand \index{Tinibios (DS390)} -For devices that have multiple code pages it is more efficient to use the - same number of files as pages, i.e. - for the 16F877 use 4 separate files and i.e. - for the 16F874 use 2 separate files. - This way the linker can put the code for each file into different code - pages and the compiler can allocate reusable variables more efficiently - and there's less page selection overhead. - And as for any 8 bit micro (especially for PIC 14 as they have a very simple - instruction set) use 'unsigned char' whereever possible instead of 'int'. -\layout Subsection +\end_inset -Creating a device include file -\layout Standard +, the boot loader or similar code must ensure that the processor is in 24 + bit contiguous addressing mode before calling the SDCC startup code. +\newline -For generating a device include file use the support perl script inc2h.pl - kept in directory support/script. -\layout Subsection +\newline +Like the +\emph on +- +\begin_inset ERT +status Collapsed -Interrupt code \layout Standard -For the interrupt function, use the keyword 'interrupt' -\begin_inset LatexCommand \index{interrupt} - +\backslash +/ \end_inset - with level number of 0 (PIC14 only has 1 interrupt so this number is only - there to avoid a syntax error - it ought to be fixed). - E.g.: -\layout Verse - - -\family typewriter -void Intr(void) interrupt 0 -\newline -{ +-model-large +\emph default + option, variables will by default be placed into the XDATA segment. + \newline -\SpecialChar ~ -\SpecialChar ~ -T0IF = 0; /* Clear timer interrupt */ + \newline -} -\layout Subsection +Segments may be placed anywhere in the 4 meg address space using the usual + - +\begin_inset ERT +status Collapsed -Linking and assembling \layout Standard -For assembling you can use either GPUTILS' -\begin_inset LatexCommand \index{gputils (pic tools)} - +\backslash +/ \end_inset - gpasm.exe or MPLAB's mpasmwin.exe. - GPUTILS is available from -\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils} +-*-loc options. + Note that if any segments are located above 64K, the -r flag must be passed + to the linker to generate the proper segment relocations, and the Intel + HEX output format must be used. + The -r flag can be passed to the linker by using the option +\emph on +-Wl-r +\emph default + on the SDCC command line. + However, currently the linker can not handle code segments > 64k. +\layout Section + +Pragmas +\begin_inset LatexCommand \index{Pragmas} \end_inset -. - For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe. - If you use MPLAB and an interrupt function then the linker script file - vectors section will need to be enlarged to link with mplink. -\newline -\newline -Here is a -\family typewriter -Makefile -\family default - using GPUTILS: -\layout Verse +\layout Standard +SDCC supports the following #pragma directives: +\layout Itemize -\family typewriter -.c.o: -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -sdcc -S -V -mpic14 -p16F877 $< -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -gpasm -c $*.asm -\newline +save +\begin_inset LatexCommand \index{\#pragma save} -\newline -$(PRJ).hex: $(OBJS) -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) -\layout Standard +\end_inset -Here is a -\family typewriter -Makefile -\family default - using MPLAB: -\layout Verse + - this will save all current options to the save/restore stack. + See #pragma\SpecialChar ~ +restore. +\layout Itemize +restore +\begin_inset LatexCommand \index{\#pragma restore} -\family typewriter -.c.o: -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -sdcc -S -V -mpic14 -p16F877 $< -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mpasmwin /q /o $*.asm -\newline +\end_inset + - will restore saved options from the last save. + saves & restores can be nested. + SDCC uses a save/restore stack: save pushes current options to the stack, + restore pulls current options from the stack. + See #pragma\SpecialChar ~ +save. \newline -$(PRJ).hex: $(OBJS) -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) -\layout Standard -Please note that indentations within a -\family typewriter - Makefile -\family default - have to be done with a tabulator character. -\layout Section +\layout Itemize -The PIC16 -\begin_inset LatexCommand \index{PIC16} +callee_saves +\begin_inset LatexCommand \index{\#pragma callee\_saves} \end_inset - port -\layout Standard -The PIC16 -\begin_inset LatexCommand \index{PIC16} +\begin_inset LatexCommand \index{function prologue} \end_inset - port is the portion of SDCC that is responsible to produce code for the - Microchip -\begin_inset LatexCommand \index{Microchip} + function1[,function2[,function3...]] - The compiler by default uses a caller + saves convention for register saving across function calls, however this + can cause unnecessary register pushing & popping +\begin_inset LatexCommand \index{push/pop} \end_inset -(TM) microcontrollers with 16 bit core. - Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx. - Currently supported devices are: -\layout Standard -\align center - -\begin_inset Tabular - - - - - - - - - - -\begin_inset Text + when calling small functions from larger functions. + This option can be used to switch off the register saving convention for + the function names specified. + The compiler will not save registers when calling these functions, extra + code need to be manually inserted at the entry & exit for these functions + to save & restore the registers used by these functions, this can SUBSTANTIALLY + reduce code & improve run time performance of the generated code. + In the future the compiler (with inter procedural analysis) may be able + to determine the appropriate scheme to use for each function call. + If - +\begin_inset ERT +status Collapsed \layout Standard -18F242 +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-callee-saves command line option is used, the function names specified + in #pragma\SpecialChar ~ +callee_saves +\begin_inset LatexCommand \index{\#pragma callee\_saves} -18F248 \end_inset - - -\begin_inset Text -\layout Standard + is appended to the list of functions specified in the command line. +\layout Itemize + +exclude +\begin_inset LatexCommand \index{\#pragma exclude} -18F252 \end_inset - - -\begin_inset Text -\layout Standard + none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation + of pairs of push/pop +\begin_inset LatexCommand \index{push/pop} -18F258 \end_inset - - -\begin_inset Text -\layout Standard + instructions in +\emph on +I +\emph default +nterrupt +\begin_inset LatexCommand \index{interrupt} -18F442 \end_inset - - -\begin_inset Text -\layout Standard + +\emph on +S +\emph default +ervice +\emph on +R +\emph default +outines. + The directive should be placed immediately before the ISR function definition + and it affects ALL ISR functions following it. + To enable the normal register saving for ISR functions use #pragma\SpecialChar ~ +exclude\SpecialChar ~ +none +\begin_inset LatexCommand \index{\#pragma exclude} -18F448 \end_inset - - - - -\begin_inset Text -\layout Standard +. + See also the related keyword _naked +\begin_inset LatexCommand \index{\_naked} -18F452 \end_inset - - -\begin_inset Text -\layout Standard -18F458 +\begin_inset LatexCommand \index{\_\_naked} + \end_inset - - -\begin_inset Text -\layout Standard +. +\layout Itemize + +less_pedantic +\begin_inset LatexCommand \index{\#pragma less\_pedantic} -18F1220 \end_inset - - -\begin_inset Text -\layout Standard + - the compiler will not warn you anymore for obvious mistakes, you'r on + your own now ;-( +\layout Itemize + +disable_warning +\begin_inset LatexCommand \index{\#pragma disable\_warning} -18F2220 \end_inset - - -\begin_inset Text -\layout Standard + - the compiler will not warn you anymore about warning number . +\layout Itemize + +nogcse +\begin_inset LatexCommand \index{\#pragma nogcse} -18F2550 \end_inset - - -\begin_inset Text -\layout Standard + - will stop global common subexpression elimination. +\layout Itemize + +noinduction +\begin_inset LatexCommand \index{\#pragma noinduction} -18F4331 \end_inset - - - - -\begin_inset Text -\layout Standard + - will stop loop induction optimizations. +\layout Itemize + +noinvariant +\begin_inset LatexCommand \index{\#pragma noinvariant} -18F4455 \end_inset - - -\begin_inset Text -\layout Standard + - will not do loop invariant optimizations. + For more details see Loop Invariants in section +\begin_inset LatexCommand \ref{sub:Loop-Optimizations} -18F6520 \end_inset - - -\begin_inset Text -\layout Standard +. +\layout Itemize + +noiv +\begin_inset LatexCommand \index{\#pragma noiv} -18F6620 \end_inset - - -\begin_inset Text -\layout Standard + - Do not generate interrupt +\begin_inset LatexCommand \index{interrupt} -18F6680 \end_inset - - -\begin_inset Text -\layout Standard + vector table entries for all ISR functions defined after the pragma. + This is useful in cases where the interrupt vector table must be defined + manually, or when there is a secondary, manually defined interrupt vector + table (e.g. + for the autovector feature of the Cypress EZ-USB FX2). + More elegantly this can be achieved by obmitting the optional interrupt + number after the interrupt keyword, see section +\begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines} -18F6720 \end_inset - - -\begin_inset Text -\layout Standard +\SpecialChar ~ +about interrupts. +\layout Itemize + +nojtbound +\begin_inset LatexCommand \index{\#pragma nojtbound} -18F8520 \end_inset - - - - -\begin_inset Text -\layout Standard + - will not generate code for boundary value checking, when switch statements + are turned into jump-tables (dangerous). + For more details see section +\begin_inset LatexCommand \ref{sub:'switch'-Statements} -18F8620 \end_inset - - -\begin_inset Text -\layout Standard +. +\layout Itemize + +noloopreverse +\begin_inset LatexCommand \index{\#pragma noloopreverse} -18F8680 \end_inset - - -\begin_inset Text -\layout Standard + - Will not do loop reversal optimization +\layout Itemize + +nooverlay +\begin_inset LatexCommand \index{\#pragma nooverlay} -18F8720 \end_inset - - -\begin_inset Text -\layout Standard + - the compiler will not overlay the parameters and local variables of a + function. +\layout Itemize + +stackauto +\begin_inset LatexCommand \index{\#pragma stackauto} \end_inset - - -\begin_inset Text + +- See option - +\begin_inset ERT +status Collapsed \layout Standard +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} \end_inset - - - -\end_inset - - -\layout Subsection - -Global Options -\layout Standard + and section +\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables} -PIC16 port supports the standard command line arguments as supposed, with - the exception of certain cases that will be mentioned in the following - list: -\layout List -\labelwidthstring 00.00.0000 +\end_inset -- -\begin_inset ERT -status Collapsed + Parameters and Local Variables. +\layout Itemize -\layout Standard +opt_code_speed +\begin_inset LatexCommand \index{\#pragma opt\_code\_speed} -\backslash -/ \end_inset --callee-saves See - -\begin_inset ERT -status Collapsed +- The compiler will optimize code generation towards fast code, possibly + at the expense of code size. +\layout Itemize -\layout Standard +opt_code_size +\begin_inset LatexCommand \index{\#pragma opt\_code\_size} -\backslash -/ \end_inset --all-callee-saves -\layout List -\labelwidthstring 00.00.0000 - -- -\begin_inset ERT -status Collapsed +- The compiler will optimize code generation towards compact code, possibly + at the expense of code speed. +\layout Itemize -\layout Standard +opt_code_balanced +\begin_inset LatexCommand \index{\#pragma opt\_code\_balanced} -\backslash -/ \end_inset --all-callee-saves All function arguments are passed on stack by default. +- The compiler will attempt to generate code that is both compact and fast, + as long as meeting one goal is not a detriment to the other (this is the + default). -\emph on -There is no need to specify this in the command line. -\layout List -\labelwidthstring 00.00.0000 - -- -\begin_inset ERT -status Collapsed +\layout Itemize -\layout Standard +std_sdcc89 +\begin_inset LatexCommand \index{\#pragma std\_sdcc89} -\backslash -/ \end_inset --fommit-frame-pointer Frame pointer will be omitted when the function uses - no local variables. -\layout Subsection +- Generally follow the C89 standard, but allow SDCC features that conflict + with the standard (default). +\layout Itemize -Port Specific Options -\begin_inset LatexCommand \index{Options PIC16} +std_c89 +\begin_inset LatexCommand \index{\#pragma std\_c89} \end_inset +- Follow the C89 standard and disable SDCC features that conflict with the + standard. +\layout Itemize -\layout Standard - -The port specific options appear after the global options in the sdcc --help - output. -\layout Subsubsection - -General Options -\layout Standard - -General options enable certain port features and optimizations. -\layout List -\labelwidthstring 00.00.0000 - -- -\begin_inset ERT -status Collapsed - -\layout Standard +std_sdcc99 +\begin_inset LatexCommand \index{\#pragma std\_sdcc99} -\backslash -/ \end_inset --stack-model=[model] Used in conjuction with the command above. - Defines the stack model to be used, valid stack models are : -\begin_deeper -\layout List -\labelwidthstring 00.00.0000 - - -\emph on -small -\emph default - Selects small stack model. - 8 bit stack and frame pointers. - Supports 256 bytes stack size. -\layout List -\labelwidthstring 00.00.0000 +- Generally follow the C99 standard, but allow SDCC features that conflict + with the standard (incomplete support). +\layout Itemize +std_c99 +\begin_inset LatexCommand \index{\#pragma std\_c99} -\emph on -large -\emph default - Selects large stack model. - 16 bit stack and frame pointers. - Supports 65536 bytes stack size. -\end_deeper -\layout List -\labelwidthstring 00.00.0000 +\end_inset -- -\begin_inset ERT -status Collapsed +- Follow the C99 standard and disable SDCC features that conflict with the + standard (incomplete support). +\layout Itemize -\layout Standard +codeseg +\begin_inset LatexCommand \index{\#pragma codeseg} -\backslash -/ \end_inset --preplace-udata-with=[kword] Replaces the default udata keyword for allocating - unitialized data variables with [kword]. - Valid keywords are: "udata_acs", "udata_shr", "udata_ovr". -\layout List -\labelwidthstring 00.00.0000 - -- +- Use this name (max. + 8 characters) for the code segment. + See option - \begin_inset ERT status Collapsed @@ -16390,26 +16125,17 @@ status Collapsed / \end_inset --ivt-loc positions the Interrupt Vector Table at location . - Useful for bootloaders. -\layout List -\labelwidthstring 00.00.0000 - -- -\begin_inset ERT -status Collapsed +-codeseg. +\layout Itemize -\layout Standard +constseg +\begin_inset LatexCommand \index{\#pragma constseg} -\backslash -/ \end_inset --asm= sets the full path and name of an external assembler to call. -\layout List -\labelwidthstring 00.00.0000 - -- +- Use this name (max. + 8 characters) for the const segment. + See option - \begin_inset ERT status Collapsed @@ -16419,233 +16145,263 @@ status Collapsed / \end_inset --link= sets the full path and name of an external linker to call. -\layout List -\labelwidthstring 00.00.0000 - -- -\begin_inset ERT -status Collapsed - +-constseg. \layout Standard -\backslash -/ -\end_inset - --mplab-comp MPLAB compatibility option. - Currently only suppresses special gpasm directives. -\layout Subsubsection +SDCPP supports the following #pragma directives: +\layout Itemize -Optimization Options -\layout List -\labelwidthstring 00.00.0000 +preproc_asm +\begin_inset LatexCommand \index{\#pragma preproc\_asm} -- -\begin_inset ERT -status Collapsed +\end_inset + (+ | -) - switch _asm _endasm block preprocessing on / off. + Default is on. \layout Standard -\backslash -/ -\end_inset - --optimize-goto Try to use (conditional) BRA instead of GOTO -\layout List -\labelwidthstring 00.00.0000 +The pragma's are intended to be used to turn-on or off certain optimizations + which might cause the compiler to generate extra stack / data space to + store compiler generated temporary variables. + This usually happens in large functions. + Pragma directives should be used as shown in the following example, they + are used to control options & optimizations for a given function; pragmas + should be placed before and/or after a function, placing pragma's inside + a function body could have unpredictable results. +\layout Verse -- -\begin_inset ERT -status Collapsed -\layout Standard +\family typewriter +#pragma save +\begin_inset LatexCommand \index{\#pragma save} -\backslash -/ \end_inset --optimize-cmp Try to optimize some compares. -\layout List -\labelwidthstring 00.00.0000 - -- -\begin_inset ERT -status Collapsed - -\layout Standard + \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* save the current settings */ +\newline +#pragma nogcse +\begin_inset LatexCommand \index{\#pragma nogcse} -\backslash -/ \end_inset --obanksel=nn Set optimization level for inserting BANKSELs. + \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* turnoff global subexpression elimination */ \newline +#pragma noinduction +\begin_inset LatexCommand \index{\#pragma noinduction} -\begin_deeper -\layout List -\labelwidthstring 00.00.0000 +\end_inset -0 no optimization -\layout List -\labelwidthstring 00.00.0000 - -1 checks previous used register and if it is the same then does not emit - BANKSEL, accounts only for labels. -\layout List -\labelwidthstring 00.00.0000 - -2 tries to check the location of (even different) symbols and removes BANKSELs - if they are in the same bank. + /* turn off induction optimizations */ +\newline +int foo () +\newline +{ +\newline +\SpecialChar ~ + \SpecialChar ~ + ... + +\newline +\SpecialChar ~ + \SpecialChar ~ + /* large code */ +\newline +\SpecialChar ~ + \SpecialChar ~ + ... \newline +} +\newline +#pragma restore +\begin_inset LatexCommand \index{\#pragma restore} -\emph on -Important: There might be problems if the linker script has data sections - across bank borders! -\end_deeper -\layout Subsubsection +\end_inset -Linking Options -\layout List -\labelwidthstring 00.00.0000 + /* turn the optimizations back on */ +\layout Standard -- -\begin_inset ERT -status Collapsed +The compiler will generate a warning message when extra space is allocated. + It is strongly recommended that the save and restore pragma's be used when + changing options for a function. +\layout Section +Defines Created by the Compiler \layout Standard -\backslash -/ -\end_inset +The compiler creates the following #defines +\begin_inset LatexCommand \index{\#defines} --nodefaultlibs do not link default libraries when linking -\layout List -\labelwidthstring 00.00.0000 +\end_inset -- -\begin_inset ERT -status Collapsed -\layout Standard +\begin_inset LatexCommand \index{Defines created by the compiler} -\backslash -/ \end_inset --no-crt Don't link the default run-time modules -\layout List -\labelwidthstring 00.00.0000 +: +\newline -- -\begin_inset ERT -status Collapsed +\layout Standard + + +\begin_inset Tabular + + + + + + +\begin_inset Text \layout Standard -\backslash -/ -\end_inset --use-crt= Use a custom run-time module instead of the defaults. -\layout Subsubsection +\series bold +#define +\end_inset + + +\begin_inset Text -Debugging Options \layout Standard -Debugging options enable extra debugging information in the output files. -\layout List -\labelwidthstring 00.00.0000 -- -\begin_inset ERT -status Collapsed +\series bold +Description +\end_inset + + + + +\begin_inset Text \layout Standard -\backslash -/ +SDCC +\begin_inset LatexCommand \index{SDCC} + \end_inset --debug-xtra Similar to - -\begin_inset ERT -status Collapsed + +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ +Always defined. + Since version 2.5.6 the version number as an int (ex. + 256) +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SDCC_mcs51 +\begin_inset LatexCommand \index{SDCC\_mcs51} + \end_inset --debug -\begin_inset LatexCommand \index{-\/-debug} + or SDCC_ds390 +\begin_inset LatexCommand \index{SDCC\_ds390} \end_inset -, but dumps more information. -\layout List -\labelwidthstring 00.00.0000 + or SDCC_z80 +\begin_inset LatexCommand \index{SDCC\_z80} -- -\begin_inset ERT -status Collapsed +\end_inset + +, etc +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ +depending on the model used (e.g.: -mds390 \end_inset + + + + +\begin_inset Text --debug-ralloc Force register allocator to dump .d file with debugging - information. - is the name of the file compiled. -\layout List -\labelwidthstring 00.00.0000 +\layout Standard -- -\begin_inset ERT -status Collapsed +__mcs51 +\begin_inset LatexCommand \index{\_\_mcs51} -\layout Standard +\end_inset + +, __ds390 +\begin_inset LatexCommand \index{\_\_ds390} -\backslash -/ \end_inset --pcode-verbose Enable pcode debugging information in translation. -\layout List -\labelwidthstring 00.00.0000 +, __hc08 +\begin_inset LatexCommand \index{\_\_hc08} -- -\begin_inset ERT -status Collapsed +\end_inset -\layout Standard +, __z80 +\begin_inset LatexCommand \index{\_\_z80} -\backslash -/ \end_inset --denable-peeps Force the usage of peepholes. - Use with care. -\layout List -\labelwidthstring 00.00.0000 +, etc +\end_inset + + +\begin_inset Text -- -\begin_inset ERT -status Collapsed +\layout Standard + +depending on the model used (e.g. + -mz80) +\end_inset + + + + +\begin_inset Text \layout Standard -\backslash -/ +SDCC_STACK_AUTO +\begin_inset LatexCommand \index{SDCC\_STACK\_AUTO} + \end_inset --gstack Trace push/pops for stack pointer overflow -\layout List -\labelwidthstring 00.00.0000 +\end_inset + + +\begin_inset Text + +\layout Standard + +when +\emph on - \begin_inset ERT status Collapsed @@ -16656,69 +16412,46 @@ status Collapsed / \end_inset --call-tree dump call tree in .calltree file -\layout Subsection +-stack-auto +\emph default + option is used +\end_inset + + + + +\begin_inset Text -Enviromental Variables \layout Standard -There is a number of enviromental variables that can be used when running - SDCC to enable certain optimizations or force a specific program behaviour. - these variables are primarily for debugging purposes so they can be enabled/dis -abled at will. -\layout Standard +SDCC_MODEL_SMALL +\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL} -Currently there is only two such variables available: -\layout List -\labelwidthstring 00.00.0000 - -OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure - bitfields is optimized by directly loading FSR0 with the address of the - bitfield structure. - Normally SDCC will cast the bitfield structure to a bitfield pointer and - then load FSR0. - This step saves data ram and code space for functions that perform heavy - use of bitfields. - (ie. - 80 bytes of code space are saved when compiling malloc.c with this option). - -\layout List -\labelwidthstring 00.00.0000 +\end_inset -NO_REG_OPT do not perform pCode registers optimization. - This should be used for debugging purposes. - In some where bugs in the pcode optimizer are found, users can benefit - from temporarily disabling the optimizer until the bug is fixed. -\layout Subsection -Preprocessor Macros -\layout Standard +\end_inset + + +\begin_inset Text -PIC16 port defines the following preprocessor macros while translating a - source. \layout Standard -\align center -\begin_inset Tabular - - - - - - -\begin_inset Text +when +\emph on +- +\begin_inset ERT +status Collapsed \layout Standard -Macro +\backslash +/ \end_inset - - -\begin_inset Text - -\layout Standard -Description +-model-small +\emph default + is used \end_inset @@ -16728,25 +16461,22 @@ Description \layout Standard -SDCC_pic16 +SDCC_MODEL_MEDIUM +\begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM} + \end_inset - - -\begin_inset Text -\layout Standard -Port identification \end_inset - - - + \begin_inset Text \layout Standard -_ +when +\emph on +- \begin_inset ERT status Collapsed @@ -16756,15 +16486,9 @@ status Collapsed / \end_inset -_pic16 -\end_inset - - -\begin_inset Text - -\layout Standard - -Port identification (same as above) +-model-medium +\emph default + is used \end_inset @@ -16774,31 +16498,22 @@ Port identification (same as above) \layout Standard -pic18fxxxx +SDCC_MODEL_LARGE +\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE} + \end_inset - - -\begin_inset Text -\layout Standard -MCU Identification. - -\emph on -xxxx -\emph default - is the microcontrol identification number, i.e. - 452, 6620, etc \end_inset - - - + \begin_inset Text \layout Standard -_ +when +\emph on +- \begin_inset ERT status Collapsed @@ -16808,67 +16523,46 @@ status Collapsed / \end_inset -_18Fxxxx -\end_inset - - -\begin_inset Text - -\layout Standard - -MCU Identification (same as above) +-model-large +\emph default + is used \end_inset - + \begin_inset Text \layout Standard -STACK_MODEL_nnn +SDCC_USE_XSTACK +\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK} + \end_inset - - -\begin_inset Text -\layout Standard -nnn = SMALL or LARGE respectively according to the stack model used \end_inset - - - -\end_inset - - -\layout Standard + +\begin_inset Text -In addition the following macros are defined when calling assembler: \layout Standard -\align center -\begin_inset Tabular - - - - - - -\begin_inset Text +when +\emph on +- +\begin_inset ERT +status Collapsed \layout Standard -Macro +\backslash +/ \end_inset - - -\begin_inset Text - -\layout Standard -Description +-xstack +\emph default + option is used \end_inset @@ -16878,7 +16572,12 @@ Description \layout Standard -__18Fxxxx +SDCC_STACK_TENBIT +\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT} + +\end_inset + + \end_inset @@ -16886,42 +16585,26 @@ __18Fxxxx \layout Standard -MCU Identification. - +when \emph on -xxxx +-mds390 \emph default - is the microcontrol identification number, i.e. - 452, 6620, etc + is used \end_inset - + \begin_inset Text \layout Standard -SDCC_MODEL_nnn -\end_inset - - -\begin_inset Text - -\layout Standard +SDCC_MODEL_FLAT24 +\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24} -nnn = SMALL or LARGE respectively according to the memory model used for - SDCC \end_inset - - - - -\begin_inset Text -\layout Standard -STACK_MODEL_nnn \end_inset @@ -16929,7 +16612,11 @@ STACK_MODEL_nnn \layout Standard -nnn = SMALL or LARGE respectively according to the stack model used +when +\emph on +-mds390 +\emph default + is used \end_inset @@ -16938,415 +16625,586 @@ nnn = SMALL or LARGE respectively according to the stack model used \end_inset -\layout Subsection +\layout Chapter -Directories -\layout Standard +Notes on supported Processors +\layout Section -PIC16 -\begin_inset LatexCommand \index{PIC16} +MCS51 variants +\begin_inset LatexCommand \label{sub:MCS51-variants} \end_inset - port uses the following directories for searching header files and libraries. -\layout Standard -\align center - -\begin_inset Tabular - - - - - - - - -\begin_inset Text -\layout Standard +\begin_inset LatexCommand \index{MCS51 variants} -Directory \end_inset - - -\begin_inset Text + \layout Standard -Description -\end_inset - - -\begin_inset Text +MCS51 processors are available from many vendors and come in many different + flavours. + While they might differ considerably in respect to Special Function Registers + the core MCS51 is usually not modified or is kept compatible. + +\layout Subsection +pdata access by SFR \layout Standard -Target +With the upcome of devices with internal xdata and flash memory devices + using port P2 +\begin_inset LatexCommand \index{P2 (mcs51 sfr)} + \end_inset - - -\begin_inset Text -\layout Standard + as dedicated I/O port is becoming more popular. + Switching the high byte for pdata +\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} -Command prefix \end_inset - - - - -\begin_inset Text -\layout Standard + access which was formerly done by port P2 is then achieved by a Special + Function Register +\begin_inset LatexCommand \index{sfr} -PREFIX/sdcc/include/pic16 \end_inset - - -\begin_inset Text -\layout Standard +. + In well-established MCS51 tradition the address of this +\emph on +sfr +\emph default + is where the chip designers decided to put it. + Needless to say that they didn't agree on a common name either. + So that the startup code can correctly initialize xdata variables, you + should define an sfr with the name _XPAGE +\family typewriter + +\begin_inset LatexCommand \index{\_XPAGE (mcs51)} -PIC16 specific headers \end_inset - - -\begin_inset Text -\layout Standard -Compiler -\end_inset - - -\begin_inset Text +\family default + at the appropriate location if the default, port P2, is not used for this. + Some examples are: +\layout Verse -\layout Standard --I -\end_inset - - - - -\begin_inset Text +\family typewriter +sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */ +\layout Verse + +\family typewriter +sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */ +\layout Verse + + +\family typewriter +sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */ \layout Standard -PREFIX/sdcc/lib/pic16 +For more exotic implementations further customizations may be needed. + See section +\begin_inset LatexCommand \ref{sub:Startup-Code} + \end_inset - - -\begin_inset Text + for other possibilities. +\layout Subsection + +Other Features available by SFR \layout Standard -PIC16 specific libraries +Some MCS51 variants offer features like Double DPTR +\begin_inset LatexCommand \index{DPTR} + \end_inset - - -\begin_inset Text +, multiple DPTR, decrementing DPTR, 16x16 Multiply. + These are currently not used for the MCS51 port. + If you absolutely need them you can fall back to inline assembly or submit + a patch to SDCC. +\layout Section + +DS400 port \layout Standard -Linker +The DS80C400 microcontroller has a rich set of peripherals. + In its built-in ROM library it includes functions to access some of the + features, among them is a TCP stack with IP4 and IP6 support. + Library headers (currently in beta status) and other files are provided + at +\size footnotesize + +\begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html} + \end_inset - - -\begin_inset Text +. + +\layout Section + +The Z80 and gbz80 port \layout Standard --L -\end_inset - - - +SDCC can target both the Zilog +\begin_inset LatexCommand \index{Z80} \end_inset + and the Nintendo Gameboy's Z80-like gbz80 +\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)} -\layout Subsection +\end_inset -Pragmas -\begin_inset LatexCommand \label{sub:PIC16_Pragmas} +. + The Z80 port is passed through the same +\emph on +regressions tests +\begin_inset LatexCommand \index{Regression test} \end_inset +\emph default + as the MCS51 and DS390 ports, so floating point support, support for long + variables and bitfield support is fine. + See mailing lists and forums about interrupt routines. \layout Standard -PIC16 port currently supports the following pragmas: -\layout List -\labelwidthstring 00.00.0000 +As always, the code is the authoritative reference - see z80/ralloc.c and + z80/gen.c. + The stack +\begin_inset LatexCommand \index{stack} -stack pragma stack forces the code generator to initialize the stack & frame - pointers at a specific address. - This is an adhoc solution for cases where no STACK directive is available - in the linker script or gplink is not instructed to create a stack section. -\newline -The stack pragma should be used only once in a project. - Multiple pragmas may result in indeterminate behaviour of the program. -\begin_inset Foot -collapsed false +\end_inset -\layout Standard + frame is similar to that generated by the IAR Z80 compiler. + IX is used as the base pointer, HL and IY are used as a temporary registers, + and BC and DE are available for holding variables. + Return values +\begin_inset LatexCommand \index{return value} -The old format (ie. - #pragma stack 0x5ff) is deprecated and will cause the stack pointer to - cross page boundaries (or even exceed the available data RAM) and crash - the program. - Make sure that stack does not cross page boundaries when using the SMALL - stack model. \end_inset + for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four + bytes). + The gbz80 port use the same set of registers for the return values, but + in a different order of significance: E (one byte), DE (two bytes), or + HLDE (four bytes). +\layout Section -\newline -The format is as follows: -\layout LyX-Code - -#pragma stack bottom_address [stack_size] +The HC08 port \layout Standard +The port to the Motorola HC08 +\begin_inset LatexCommand \index{HC08} -\emph on -bottom_address -\emph default - is the lower bound of the stack section. - The stack pointer initially will point at address (bottom_address+stack_size-1). -\layout LyX-Code +\end_inset -Example: -\layout LyX-Code + family has been added in October 2003, and is still undergoing some basic + development. + The code generator is complete, but the register allocation is still quite + unoptimized. + Some of the SDCC's standard C library functions have embedded non-HC08 + inline assembly and so are not yet usable. +\newline -\layout LyX-Code +\newline -/* initializes stack of 100 bytes at RAM address 0x200 */ -\layout LyX-Code +\layout Section -#pragma stack 0x200 100 +The PIC14 port \layout Standard -If the stack_size field is omitted then a stack is created with the default - size of 64. - This size might be enough for most programs, but its not enough for operations - with deep function nesting or excessive stack usage. -\layout List -\labelwidthstring 00.00.0000 - -wparam -\emph on -This pragma is deprecated. - Its use will cause a warning message to be issued. -\emph default +The 14bit PIC +\begin_inset LatexCommand \index{PIC14} -\newline +\end_inset -\layout List -\labelwidthstring 00.00.0000 + port still requires a major effort from the development community. + However it can work for very simple code. +\layout Subsection -code place a function symbol at static FLASH address -\layout LyX-Code +C code and 14bit PIC code page +\begin_inset LatexCommand \index{code page (pic14)} -Example: -\layout LyX-Code +\end_inset -\layout LyX-Code + and RAM banks +\begin_inset LatexCommand \index{RAM bank (pic14)} -/* place function test_func at 0x4000 */ -\layout LyX-Code +\end_inset -#pragma code test_func 0x4000 -\layout LyX-Code -\layout List -\labelwidthstring 00.00.0000 +\layout Standard -library instructs the linker to use a library module. +The linker organizes allocation for the code page and RAM banks. + It does not have intimate knowledge of the code flow. + It will put all the code section of a single asm file into a single code + page. + In order to make use of multiple code pages, separate asm files must be + used. + The compiler treats all functions of a single C file as being in the same + code page unless it is non static. + The compiler treats all local variables of a single C file as being in + the same RAM bank unless it is an extern. \newline -Usage: -\layout LyX-Code -#pragma library module_name -\layout Standard +\newline +To get the best follow these guide lines: +\layout Enumerate +make local functions static, as non static functions require code page selection + overhead. +\layout Enumerate -\emph on -module_name -\emph default - can be any library or object file (including its path). - Note that there are four reserved keywords which have special meaning. - These are: -\layout Standard -\align center +Make local variables static as extern variables require RAM bank selection + overhead. +\layout Enumerate -\begin_inset Tabular - - - - - - - -\begin_inset Text +For devices that have multiple code pages it is more efficient to use the + same number of files as pages, i.e. + for the 16F877 use 4 separate files and i.e. + for the 16F874 use 2 separate files. + This way the linker can put the code for each file into different code + pages and the compiler can allocate reusable variables more efficiently + and there's less page selection overhead. + And as for any 8 bit micro (especially for PIC 14 as they have a very simple + instruction set) use 'unsigned char' whereever possible instead of 'int'. +\layout Subsection +Creating a device include file \layout Standard -Keyword -\end_inset - - -\begin_inset Text +For generating a device include file use the support perl script inc2h.pl + kept in directory support/script. +\layout Subsection +Interrupt code \layout Standard -Description +For the interrupt function, use the keyword 'interrupt' +\begin_inset LatexCommand \index{interrupt} + \end_inset - - -\begin_inset Text -\layout Standard + with level number of 0 (PIC14 only has 1 interrupt so this number is only + there to avoid a syntax error - it ought to be fixed). + E.g.: +\layout Verse -Module to link -\end_inset - - - - -\begin_inset Text +\family typewriter +void Intr(void) interrupt 0 +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +T0IF = 0; /* Clear timer interrupt */ +\newline +} +\layout Subsection + +Linking and assembling \layout Standard +For assembling you can use either GPUTILS' +\begin_inset LatexCommand \index{gputils (pic tools)} -\series bold -ignore \end_inset - - -\begin_inset Text -\layout Standard + gpasm.exe or MPLAB's mpasmwin.exe. + GPUTILS is available from +\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils} -ignore all library pragmas \end_inset - - -\begin_inset Text -\layout Standard +. + For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe. + If you use MPLAB and an interrupt function then the linker script file + vectors section will need to be enlarged to link with mplink. +\newline + +\newline +Here is a +\family typewriter +Makefile +\family default + using GPUTILS: +\layout Verse -\emph on -(none) -\end_inset - - - - -\begin_inset Text +\family typewriter +.c.o: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcc -S -V -mpic14 -p16F877 $< +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +gpasm -c $*.asm +\newline +\newline +$(PRJ).hex: $(OBJS) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib \layout Standard +Here is a +\family typewriter +Makefile +\family default + using MPLAB: +\layout Verse + -\series bold -c -\end_inset - - -\begin_inset Text +\family typewriter +.c.o: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcc -S -V -mpic14 -p16F877 $< +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mpasmwin /q /o $*.asm +\newline +\newline +$(PRJ).hex: $(OBJS) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib \layout Standard -link the C library -\end_inset - - -\begin_inset Text +Please note that indentations within a +\family typewriter + Makefile +\family default + have to be done with a tabulator character. +\layout Subsection +Command-line options \layout Standard - -\emph on -libc18f -\emph default -.lib -\end_inset - - - - -\begin_inset Text +Besides the switches common to all SDCC backends, the PIC14 port accepts + the following options (for an updated list see sdcc - +\begin_inset ERT +status Collapsed \layout Standard - -\series bold -math +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-help): +\layout List +\labelwidthstring 00.00.0000 -link the Math libarary -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard - -\emph on -libm18f -\emph default -.lib +\backslash +/ \end_inset - - - - -\begin_inset Text + +-debug-extra emit debug info in assembly output +\layout List +\labelwidthstring 00.00.0000 + +- +\begin_inset ERT +status Collapsed \layout Standard +\backslash +/ +\end_inset -\series bold -io +-no-pcode-opt disable (slightly faulty) optimization on pCode +\layout Subsection + +The library +\layout Subsubsection + +error: missing definition for symbol +\begin_inset Quotes sld +\end_inset + +__gptrget1 +\begin_inset Quotes srd \end_inset - - -\begin_inset Text + \layout Standard -link the I/O library +The PIC14 port uses library routines to provide more complex operations + like multiplication, division/modulus and (generic) pointer dereferencing. + In order to add these routines to your project, you must link with PIC14's + +\family typewriter +libsdcc.lib +\family default +. + For single source file projects this is done automatically, more complex + projects must add +\family typewriter +libsdcc.lib +\family default + to the linker's arguments. + Make sure you also add an include path for the library (using the -I switch + to the linker)! +\layout Subsubsection + +Processor mismatch in file +\begin_inset Quotes sld \end_inset - - -\begin_inset Text +XXX +\begin_inset Quotes srd +\end_inset + +. +\layout Standard + +This warning can usually be ignored due to the very good compatibility amongst + 14 bit PIC devices. \layout Standard +You might also consider recompiling the library for your specific device + by changing the ARCH=p16f877 (default target) entry in +\family typewriter +device/lib/pic/Makefile.in +\family default + and +\family typewriter +device/lib/pic/Makefile +\family default + to reflect your device. + This might even improve performance for smaller devices as unneccesary + BANKSELs migth be removed. +\layout Subsection + +Known bugs +\layout Subsubsection + +initialized data +\layout Standard +Currently, data can only be initialized if it resides in the source file + together with \emph on -libio18f* +main() \emph default -.lib +. + Data in other source files will silently +\series bold +not +\series default + be initialized. +\layout Section + +The PIC16 +\begin_inset LatexCommand \index{PIC16} + \end_inset - - - + + port +\layout Standard + +The PIC16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port is the portion of SDCC that is responsible to produce code for the + Microchip +\begin_inset LatexCommand \index{Microchip} + +\end_inset + +(TM) microcontrollers with 16 bit core. + Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx. + Currently supported devices are: +\layout Standard +\align center + +\begin_inset Tabular + + + + + + + + + \begin_inset Text \layout Standard +18F242 +\end_inset + + +\begin_inset Text -\series bold -debug +\layout Standard + +18F248 \end_inset @@ -17354,7 +17212,7 @@ debug \layout Standard -link the debug library +18F252 \end_inset @@ -17362,281 +17220,133 @@ link the debug library \layout Standard - -\emph on -libdebug -\emph default -.lib +18F258 \end_inset - - + +\begin_inset Text -\end_inset +\layout Standard +18F442 +\end_inset + + +\begin_inset Text -\newline -* is the device number, i.e. - 452 for PIC18F452 MCU. \layout Standard -This feature allows for linking with specific libraries withoug having to - explicit name them in the command line. - Note that the -\noun on -ignore -\noun default - keyword will reject all modules specified by the library pragma. -\layout List -\labelwidthstring 00.00.0000 - -udata pragma udata instructs the compiler to emit code so that linker will - place a variable at a specific memory bank -\layout LyX-Code +18F448 +\end_inset + + + + +\begin_inset Text -Example: -\layout LyX-Code +\layout Standard -\layout LyX-Code +18F452 +\end_inset + + +\begin_inset Text -/* places variable foo at bank2 */ -\layout LyX-Code +\layout Standard -#pragma udata bank2 foo -\layout LyX-Code +18F458 +\end_inset + + +\begin_inset Text -char foo; \layout Standard -In order for this pragma to work extra SECTION directives should be added - in the .lkr script. - In the following example a sample .lkr file is shown: -\layout LyX-Code +18F1220 +\end_inset + + +\begin_inset Text -\layout LyX-Code +\layout Standard -// Sample linker script for the PIC18F452 processor -\layout LyX-Code +18F2220 +\end_inset + + +\begin_inset Text -LIBPATH . -\layout LyX-Code +\layout Standard -CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED -\layout LyX-Code +18F2550 +\end_inset + + +\begin_inset Text -CODEPAGE NAME=page START=0x2A END=0x7FFF -\layout LyX-Code +\layout Standard -CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED -\layout LyX-Code +18F4331 +\end_inset + + + + +\begin_inset Text -CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED -\layout LyX-Code +\layout Standard -CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED -\layout LyX-Code +18F4455 +\end_inset + + +\begin_inset Text -CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED -\layout LyX-Code +\layout Standard -ACCESSBANK NAME=accessram START=0x0 END=0x7F -\layout LyX-Code +18F6520 +\end_inset + + +\begin_inset Text -\layout LyX-Code +\layout Standard -DATABANK NAME=gpr0 START=0x80 END=0xFF -\layout LyX-Code +18F6620 +\end_inset + + +\begin_inset Text -DATABANK NAME=gpr1 START=0x100 END=0x1FF -\layout LyX-Code +\layout Standard -DATABANK NAME=gpr2 START=0x200 END=0x2FF -\layout LyX-Code +18F6680 +\end_inset + + +\begin_inset Text -DATABANK NAME=gpr3 START=0x300 END=0x3FF -\layout LyX-Code +\layout Standard -DATABANK NAME=gpr4 START=0x400 END=0x4FF -\layout LyX-Code +18F6720 +\end_inset + + +\begin_inset Text -DATABANK NAME=gpr5 START=0x500 END=0x5FF -\layout LyX-Code - -ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED -\layout LyX-Code - -\layout LyX-Code - -SECTION NAME=CONFIG ROM=config -\layout LyX-Code - -\layout LyX-Code - -SECTION NAME=bank0 RAM=gpr0 # these SECTION directives -\layout LyX-Code - -SECTION NAME=bank1 RAM=gpr1 # should be added to link -\layout LyX-Code - -SECTION NAME=bank2 RAM=gpr2 # section name 'bank?' with -\layout LyX-Code - -SECTION NAME=bank3 RAM=gpr3 # a specific DATABANK name -\layout LyX-Code - -SECTION NAME=bank4 RAM=gpr4 -\layout LyX-Code - -SECTION NAME=bank5 RAM=gpr5 -\layout Standard - -The linker will recognise the section name set in the pragma statement and - will position the variable at the memory bank set with the RAM field at - the SECTION line in the linker script file. -\layout Subsection - -Header Files -\begin_inset LatexCommand \label{sub:PIC16_Header-Files} - -\end_inset - - -\layout Standard - -There is one main header file that can be included to the source files using - the pic16 port. - That file is the -\series bold -pic18fregs.h -\series default -. - This header file contains the definitions for the processor special registers, - so it is necessary if the source accesses them. - It can be included by adding the following line in the beginning of the - file: -\layout LyX-Code - -#include -\layout Standard - -The specific microcontroller is selected within the pic18fregs.h automatically, - so the same source can be used with a variety of devices. -\layout Subsection - -Libraries -\layout Standard - -The libraries that PIC16 -\begin_inset LatexCommand \index{PIC16} - -\end_inset - - port depends on are the microcontroller device libraries which contain - the symbol definitions for the microcontroller special function registers. - These libraries have the format pic18fxxxx.lib, where -\emph on -xxxx -\emph default - is the microcontroller identification number. - The specific library is selected automatically by the compiler at link - stage according to the selected device. -\layout Standard - -Libraries are created with gplib which is part of the gputils package -\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils} +\layout Standard +18F8520 \end_inset - -. -\layout Subsubsection* - -Building the libraries -\layout Standard - -Before using SDCC/pic16 there are some libraries that need to be compiled. - This process is not done automatically by SDCC since not all users use - SDCC for pic16 projects. - So each user should compile the libraries separately. -\layout Standard - -The steps to compile the pic16 libraries under Linux are: -\layout LyX-Code - -cd device/lib/pic16 -\layout LyX-Code - -./configure -\layout LyX-Code - -make -\layout LyX-Code - -cd .. -\layout LyX-Code - -make model-pic16 -\layout LyX-Code - -su -c 'make install' # install the libraries, you need the root password -\layout Standard - -If you need to install the headers too, do: -\layout LyX-Code - -cd device/include -\layout LyX-Code - -su -c 'make install' # install the headers, you need the root password -\layout Standard - -There exist a special target to build the I/O libraries. - This target is not automatically build because it will build the I/O library - for -\emph on -every -\emph default - supported device. - This way building will take quite a lot of time. - Users are advised to edit the -\series bold -device/lib/pic16/pics.build -\series default - file and then execute: -\layout LyX-Code - -make lib-io -\layout Subsection - -Memory Models -\layout Standard - -The following memory models are supported by the PIC16 port: -\layout Itemize - -small model -\layout Itemize - -large model -\layout Standard - -Memory model affects the default size of pointers within the source. - The sizes are shown in the next table: -\layout Standard -\align center - -\begin_inset Tabular - - - - - + + \begin_inset Text \layout Standard -Pointer sizes according to memory model +18F8620 \end_inset @@ -17644,33 +17354,15 @@ Pointer sizes according to memory model \layout Standard -small model -\end_inset - - -\begin_inset Text - -\layout Standard - -large model +18F8680 \end_inset - - \begin_inset Text \layout Standard -code pointers -\end_inset - - -\begin_inset Text - -\layout Standard - -16-bits +18F8720 \end_inset @@ -17678,25 +17370,13 @@ code pointers \layout Standard -24-bits -\end_inset - - - - -\begin_inset Text - -\layout Standard - -data pointers \end_inset - + \begin_inset Text \layout Standard -16-bits \end_inset @@ -17704,7 +17384,6 @@ data pointers \layout Standard -16-bits \end_inset @@ -17713,453 +17392,489 @@ data pointers \end_inset -\layout Standard +\layout Subsection -It is advisable that all sources within a project are compiled with the - same memory model. - If one wants to override the default memory model, this can be done by - declaring a pointer as -\series bold -far -\series default - or -\series bold -near -\series default -. - Far selects large memory model's pointers, while near selects small memory - model's pointers. +Global Options \layout Standard -The standard device libraries (see -\begin_inset LatexCommand \ref{sub:PIC16_Header-Files} +PIC16 port supports the standard command line arguments as supposed, with + the exception of certain cases that will be mentioned in the following + list: +\layout List +\labelwidthstring 00.00.0000 + +- +\begin_inset ERT +status Collapsed + +\layout Standard +\backslash +/ \end_inset -) contain no reference to pointers, so they can be used with both memory - models. -\layout Subsection +-callee-saves See - +\begin_inset ERT +status Collapsed -Stack \layout Standard -The stack implementation for the PIC16 port uses two indirect registers, - FSR1 and FSR2. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ +\end_inset -FSR1 is assigned as stack pointer +-all-callee-saves \layout List \labelwidthstring 00.00.0000 -FSR2 is assigned as frame pointer +- +\begin_inset ERT +status Collapsed + \layout Standard -The following stack models are supported by the PIC16 port -\layout Itemize +\backslash +/ +\end_inset +-all-callee-saves All function arguments are passed on stack by default. + +\emph on +There is no need to specify this in the command line. +\layout List +\labelwidthstring 00.00.0000 -\noun on -small -\noun default - model -\layout Itemize +- +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-fommit-frame-pointer Frame pointer will be omitted when the function uses + no local variables. +\layout Subsection + +Port Specific Options +\begin_inset LatexCommand \index{Options PIC16} + +\end_inset -\noun on -large -\noun default - model \layout Standard +The port specific options appear after the global options in the sdcc --help + output. +\layout Subsubsection -\noun on -Small -\noun default - model means that only the FSRxL byte is used to access stack and frame, - while -\emph on -\noun on -large -\emph default -\noun default - uses both FSRxL and FSRxH registers. - The following table shows the stack/frame pointers sizes according to stack - model and the maximum space they can address: +General Options \layout Standard -\align center -\begin_inset Tabular - - - - - - - -\begin_inset Text +General options enable certain port features and optimizations. +\layout List +\labelwidthstring 00.00.0000 + +- +\begin_inset ERT +status Collapsed \layout Standard -Stack & Frame pointer sizes according to stack model +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-stack-model=[model] Used in conjuction with the command above. + Defines the stack model to be used, valid stack models are : +\begin_deeper +\layout List +\labelwidthstring 00.00.0000 + +\emph on small -\end_inset - - -\begin_inset Text +\emph default + Selects small stack model. + 8 bit stack and frame pointers. + Supports 256 bytes stack size. +\layout List +\labelwidthstring 00.00.0000 -\layout Standard +\emph on large -\end_inset - - - - -\begin_inset Text - -\layout Standard +\emph default + Selects large stack model. + 16 bit stack and frame pointers. + Supports 65536 bytes stack size. +\end_deeper +\layout List +\labelwidthstring 00.00.0000 -Stack pointer FSR1 -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -8-bits +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-preplace-udata-with=[kword] Replaces the default udata keyword for allocating + unitialized data variables with [kword]. + Valid keywords are: "udata_acs", "udata_shr", "udata_ovr". +\layout List +\labelwidthstring 00.00.0000 -16-bits -\end_inset - - - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -Frame pointer FSR2 +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-ivt-loc positions the Interrupt Vector Table at location . + Useful for bootloaders. +\layout List +\labelwidthstring 00.00.0000 -8-bits -\end_inset - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -16-bits +\backslash +/ \end_inset - - - -\end_inset +-asm= sets the full path and name of an external assembler to call. +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed \layout Standard +\backslash +/ +\end_inset -\noun on -Large -\noun default -stack model is currently not working properly throughout the code generator. - So its use is not advised. - Also there are some other points that need special care: -\newline - -\layout Enumerate +-link= sets the full path and name of an external linker to call. +\layout List +\labelwidthstring 00.00.0000 -Do not create stack sections with size more than one physical bank (that - is 256 bytes) -\layout Enumerate +- +\begin_inset ERT +status Collapsed -Stack sections should no cross physical bank limits (i.e. - #pragma stack 0x50 0x100) \layout Standard -These limitations are caused by the fact that only FSRxL is modified when - using SMALL stack model, so no more than 256 bytes of stack can be used. - This problem will disappear after LARGE model is fully implemented. -\layout Subsection +\backslash +/ +\end_inset -Functions -\layout Standard +-mplab-comp MPLAB compatibility option. + Currently only suppresses special gpasm directives. +\layout Subsubsection -In addition to the standard SDCC function keywords, PIC16 port makes available - two more: +Optimization Options \layout List \labelwidthstring 00.00.0000 -wparam Use the WREG to pass one byte of the first function argument. - This improves speed but you may not use this for functions with arguments - that are called via function pointers, otherwise the first byte of the - first parameter will get lost. - Usage: -\layout LyX-Code - -void func_wparam(int a) wparam -\layout LyX-Code +- +\begin_inset ERT +status Collapsed -{ -\layout LyX-Code +\layout Standard - /* WREG hold the lower part of a */ -\layout LyX-Code +\backslash +/ +\end_inset - /* the high part of a is stored in FSR2+2 (or +3 for large stack model) - */ -\layout LyX-Code +-optimize-goto Try to use (conditional) BRA instead of GOTO +\layout List +\labelwidthstring 00.00.0000 -... -\layout LyX-Code +- +\begin_inset ERT +status Collapsed -} \layout Standard -This keyword replaces the deprecated wparam pragma. +\backslash +/ +\end_inset + +-optimize-cmp Try to optimize some compares. \layout List \labelwidthstring 00.00.0000 -shadowregs When entering/exiting an ISR, it is possible to take advantage - of the PIC18F hardware shadow registers which hold the values of WREG, - STATUS and BSR registers. - This can be done by adding the keyword -\emph on -shadowregs -\emph default - before the -\emph on -interrupt -\emph default - keyword in the function's header. -\layout LyX-Code - -void isr_shadow(void) shadowregs interrupt 1 -\layout LyX-Code - -{ -\layout LyX-Code - -... -\layout LyX-Code +- +\begin_inset ERT +status Collapsed -} \layout Standard +\backslash +/ +\end_inset -\emph on -shadowregs -\emph default - instructs the code generator not to store/restore WREG, STATUS, BSR when - entering/exiting the ISR. -\layout Subsection +-optimize-df Analyze the dataflow of the generated code and improve it. +\layout List +\labelwidthstring 00.00.0000 -Function return values -\layout Standard +- +\begin_inset ERT +status Collapsed -Return values from functions are placed to the appropriate registers following - a modified Microchip policy optimized for SDCC. - The following table shows these registers: \layout Standard -\align center -\begin_inset Tabular - - - - - - -\begin_inset Text +\backslash +/ +\end_inset -\layout Standard +-obanksel=nn Set optimization level for inserting BANKSELs. +\newline -size -\end_inset - - -\begin_inset Text +\begin_deeper +\layout List +\labelwidthstring 00.00.0000 -\layout Standard +0 no optimization +\layout List +\labelwidthstring 00.00.0000 -destination register -\end_inset - - - - -\begin_inset Text +1 checks previous used register and if it is the same then does not emit + BANKSEL, accounts only for labels. +\layout List +\labelwidthstring 00.00.0000 -\layout Standard +2 tries to check the location of (even different) symbols and removes BANKSELs + if they are in the same bank. + +\newline -8 bits -\end_inset - - -\begin_inset Text +\emph on +Important: There might be problems if the linker script has data sections + across bank borders! +\end_deeper +\layout Subsubsection -\layout Standard +Linking Options +\layout List +\labelwidthstring 00.00.0000 -WREG -\end_inset - - - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -16 bits +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-nodefaultlibs do not link default libraries when linking +\layout List +\labelwidthstring 00.00.0000 -PRODL:WREG -\end_inset - - - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -24 bits +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-no-crt Don't link the default run-time modules +\layout List +\labelwidthstring 00.00.0000 -PRODH:PRODL:WREG -\end_inset - - - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard -32 bits +\backslash +/ \end_inset - - -\begin_inset Text +-use-crt= Use a custom run-time module instead of the defaults. +\layout Subsubsection + +Debugging Options \layout Standard -FSR0L:PRODH:PRODL:WREG -\end_inset - - - - -\begin_inset Text +Debugging options enable extra debugging information in the output files. +\layout List +\labelwidthstring 00.00.0000 + +- +\begin_inset ERT +status Collapsed \layout Standard ->32 bits +\backslash +/ \end_inset - - -\begin_inset Text + +-debug-xtra Similar to - +\begin_inset ERT +status Collapsed \layout Standard -on stack, FSR0 points to the beginning +\backslash +/ \end_inset - - - + +-debug +\begin_inset LatexCommand \index{-\/-debug} \end_inset +, but dumps more information. +\layout List +\labelwidthstring 00.00.0000 -\layout Subsection +- +\begin_inset ERT +status Collapsed -Interrupts \layout Standard -An interrupt servive routine (ISR) is declared using the -\emph on -interrupt -\emph default - keyword. -\layout LyX-Code - -void isr(void) interrupt -\emph on -n -\layout LyX-Code +\backslash +/ +\end_inset -{ -\layout LyX-Code +-debug-ralloc Force register allocator to dump .d file with debugging + information. + is the name of the file compiled. +\layout List +\labelwidthstring 00.00.0000 -... -\layout LyX-Code +- +\begin_inset ERT +status Collapsed -} \layout Standard +\backslash +/ +\end_inset -\emph on -n -\emph default - is the interrupt number, which for PIC18F devices can be: -\layout Standard -\align center +-pcode-verbose Enable pcode debugging information in translation. +\layout List +\labelwidthstring 00.00.0000 -\begin_inset Tabular - - - - - - - -\begin_inset Text +- +\begin_inset ERT +status Collapsed \layout Standard +\backslash +/ +\end_inset -\emph on -n +-denable-peeps Force the usage of peepholes. + Use with care. +\layout List +\labelwidthstring 00.00.0000 + +- +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ \end_inset - + +-gstack Trace push/pops for stack pointer overflow +\layout List +\labelwidthstring 00.00.0000 + +- +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-call-tree dump call tree in .calltree file +\layout Subsection + +Enviromental Variables +\layout Standard + +There is a number of enviromental variables that can be used when running + SDCC to enable certain optimizations or force a specific program behaviour. + these variables are primarily for debugging purposes so they can be enabled/dis +abled at will. +\layout Standard + +Currently there is only two such variables available: +\layout List +\labelwidthstring 00.00.0000 + +OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure + bitfields is optimized by directly loading FSR0 with the address of the + bitfield structure. + Normally SDCC will cast the bitfield structure to a bitfield pointer and + then load FSR0. + This step saves data ram and code space for functions that perform heavy + use of bitfields. + (ie. + 80 bytes of code space are saved when compiling malloc.c with this option). + +\layout List +\labelwidthstring 00.00.0000 + +NO_REG_OPT do not perform pCode registers optimization. + This should be used for debugging purposes. + In some where bugs in the pcode optimizer are found, users can benefit + from temporarily disabling the optimizer until the bug is fixed. +\layout Subsection + +Preprocessor Macros +\layout Standard + +PIC16 port defines the following preprocessor macros while translating a + source. +\layout Standard +\align center + +\begin_inset Tabular + + + + + \begin_inset Text \layout Standard -Interrupt Vector +Macro \end_inset @@ -18167,7 +17882,7 @@ Interrupt Vector \layout Standard -Interrupt Vector Address +Description \end_inset @@ -18177,15 +17892,35 @@ Interrupt Vector Address \layout Standard -0 +SDCC_pic16 +\end_inset + + +\begin_inset Text + +\layout Standard + +Port identification \end_inset + + \begin_inset Text \layout Standard -RESET vector +_ +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +_pic16 \end_inset @@ -18193,7 +17928,7 @@ RESET vector \layout Standard -0x000000 +Port identification (same as above) \end_inset @@ -18203,59 +17938,59 @@ RESET vector \layout Standard - -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -1 +pic18fxxxx \end_inset - + \begin_inset Text \layout Standard - -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -HIGH priority interrupts +MCU Identification. + +\emph on +xxxx +\emph default + is the microcontrol identification number, i.e. + 452, 6620, etc \end_inset - + + + \begin_inset Text \layout Standard -0x000008 +_ +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +_18Fxxxx \end_inset - - - + \begin_inset Text \layout Standard -2 +MCU Identification (same as above) \end_inset + + \begin_inset Text \layout Standard -LOW priority interrupts +STACK_MODEL_nnn \end_inset @@ -18263,7 +17998,7 @@ LOW priority interrupts \layout Standard -0x000018 +nnn = SMALL or LARGE respectively according to the stack model used \end_inset @@ -18274,134 +18009,64 @@ LOW priority interrupts \layout Standard -When generating assembly code for ISR the code generator places a -\noun on -goto -\noun default -instruction at the -\emph on -Interrupt Vector Address -\emph default - which points at the genetated ISR. - This single GOTO instruction is part of an automatically generated -\emph on -interrupt entry point -\emph default - function. - The actuall ISR code is placed as normally would in the code space. - Upon interrupt request, the GOTO instruction is executed which jumps to - the ISR code. - When declaring interrupt functions as _naked this GOTO instruction is -\series bold -not -\series default - generated. - The whole interrupt functions is therefore placed at the Interrupt Vector - Address of the specific interrupt. - This is not a problem for the LOW priority interrupts, but it is a problem - for the RESET and the HIGH priority interrupts because code may be written - at the next interrupt´s vector address and cause undeterminate program - behaviour if that interrupt is raised. -\begin_inset Foot -collapsed false - +In addition the following macros are defined when calling assembler: \layout Standard +\align center -This is not a problem when -\layout Enumerate +\begin_inset Tabular + + + + + + +\begin_inset Text -this is a HIGH interrupt ISR and LOW interrupts are -\emph on -disabled -\emph default - or not used. -\layout Enumerate +\layout Standard -when the ISR is small enough not to reach the next interrupt´s vector address. +Macro \end_inset - + + +\begin_inset Text \layout Standard +Description +\end_inset + + + + +\begin_inset Text -\emph on -n -\emph default - is possible to be omitted. - This way a function is generated similar to an ISR, but it is not assigned - to any interrupt. \layout Standard -When entering an interrupt, currently the PIC16 -\begin_inset LatexCommand \index{PIC16} - +__18Fxxxx \end_inset + + +\begin_inset Text - port automatically saves the following registers: -\layout Itemize - -WREG -\layout Itemize - -STATUS -\layout Itemize - -BSR -\layout Itemize +\layout Standard -PROD (PRODL and PRODH) -\layout Itemize - -FSR0 (FSR0L and FSR0H) -\layout Standard - -These registers are restored upon return from the interrupt routine. -\begin_inset Foot -collapsed false - -\layout Standard - -NOTE that when the _naked attribute is specified for an interrupt routine, - then NO registers are stored or restored. -\end_inset - - -\layout Subsection - -Generic Pointers -\layout Standard - -Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types. - There are 3 types of generic pointers currently implemented data, code - and eeprom pointers. - They are differentiated by the value of the 7th and 6th bits of the upper - byte: -\layout Standard -\align center - -\begin_inset Tabular - - - - - - - - - -\begin_inset Text - -\layout Standard - -pointer type +MCU Identification. + +\emph on +xxxx +\emph default + is the microcontrol identification number, i.e. + 452, 6620, etc \end_inset + + \begin_inset Text \layout Standard -7th bit +SDCC_MODEL_nnn \end_inset @@ -18409,15 +18074,18 @@ pointer type \layout Standard -6th bit +nnn = SMALL or LARGE respectively according to the memory model used for + SDCC \end_inset - + + + \begin_inset Text \layout Standard -rest of the pointer +STACK_MODEL_nnn \end_inset @@ -18425,33 +18093,43 @@ rest of the pointer \layout Standard -descrption +nnn = SMALL or LARGE respectively according to the stack model used \end_inset - - -\begin_inset Text + + +\end_inset + + +\layout Subsection +Directories \layout Standard -data +PIC16 +\begin_inset LatexCommand \index{PIC16} + \end_inset - - -\begin_inset Text + port uses the following directories for searching header files and libraries. \layout Standard +\align center -1 -\end_inset - - +\begin_inset Tabular + + + + + + + + \begin_inset Text \layout Standard -0 +Directory \end_inset @@ -18459,11 +18137,7 @@ data \layout Standard - -\family typewriter -\shape slanted -\emph on -uuuuuu uuuuxxxx xxxxxxxx +Description \end_inset @@ -18471,25 +18145,25 @@ uuuuuu uuuuxxxx xxxxxxxx \layout Standard -a 12-bit data pointer in data RAM memory +Target \end_inset - - - + \begin_inset Text \layout Standard -code +Command prefix \end_inset + + \begin_inset Text \layout Standard -0 +PREFIX/sdcc/include/pic16 \end_inset @@ -18497,7 +18171,7 @@ code \layout Standard -0 +PIC16 specific headers \end_inset @@ -18505,11 +18179,7 @@ code \layout Standard - -\family typewriter -\shape slanted -\emph on -uxxxxx xxxxxxxx xxxxxxxx +Compiler \end_inset @@ -18517,25 +18187,17 @@ uxxxxx xxxxxxxx xxxxxxxx \layout Standard -a 21-bit code pointer in FLASH memory +-I \end_inset - - -\begin_inset Text - -\layout Standard - -eeprom -\end_inset - + \begin_inset Text \layout Standard -0 +PREFIX/sdcc/lib/pic16 \end_inset @@ -18543,7 +18205,7 @@ eeprom \layout Standard -1 +PIC16 specific libraries \end_inset @@ -18551,11 +18213,7 @@ eeprom \layout Standard - -\family typewriter -\shape slanted -\emph on -uuuuuu uuuuuuxx xxxxxxxx +Linker \end_inset @@ -18563,178 +18221,142 @@ uuuuuu uuuuuuxx xxxxxxxx \layout Standard -a 10-bit eeprom pointer in EEPROM memory +-L \end_inset - - -\begin_inset Text - -\layout Standard + -(unimplemented) \end_inset - - -\begin_inset Text -\layout Standard -1 -\end_inset - - -\begin_inset Text +\layout Subsection -\layout Standard +Pragmas +\begin_inset LatexCommand \label{sub:PIC16_Pragmas} -1 \end_inset - - -\begin_inset Text + \layout Standard +PIC16 port currently supports the following pragmas: +\layout List +\labelwidthstring 00.00.0000 -\family typewriter -\shape slanted -\emph on -xxxxxx xxxxxxxx xxxxxxxx -\end_inset - - -\begin_inset Text +stack pragma stack forces the code generator to initialize the stack & frame + pointers at a specific address. + This is an adhoc solution for cases where no STACK directive is available + in the linker script or gplink is not instructed to create a stack section. +\newline +The stack pragma should be used only once in a project. + Multiple pragmas may result in indeterminate behaviour of the program. +\begin_inset Foot +collapsed false \layout Standard -unimplemented pointer type +The old format (ie. + #pragma stack 0x5ff) is deprecated and will cause the stack pointer to + cross page boundaries (or even exceed the available data RAM) and crash + the program. + Make sure that stack does not cross page boundaries when using the SMALL + stack model. \end_inset - - - -\end_inset +\newline +The format is as follows: +\layout LyX-Code +#pragma stack bottom_address [stack_size] \layout Standard -Generic pointer are read and written with a set of library functions which - read/write 1, 2, 3, 4 bytes. -\layout Subsection - -PIC16 C Libraries -\layout Subsubsection - -Standard I/O Streams -\layout Standard -In the \emph on -stdio.h +bottom_address \emph default - the type FILE is defined as: + is the lower bound of the stack section. + The stack pointer initially will point at address (bottom_address+stack_size-1). \layout LyX-Code -typedef char * FILE; -\layout Standard +Example: +\layout LyX-Code -This type is the stream type implemented I/O in the PIC18F devices. - Also the standard input and output streams are declared in stdio.h: \layout LyX-Code -extern FILE * stdin; +/* initializes stack of 100 bytes at RAM address 0x200 */ \layout LyX-Code -extern FILE * stdout; +#pragma stack 0x200 100 \layout Standard -The FILE type is actually a generic pointer which defines one more type - of generic pointers, the +If the stack_size field is omitted then a stack is created with the default + size of 64. + This size might be enough for most programs, but its not enough for operations + with deep function nesting or excessive stack usage. +\layout List +\labelwidthstring 00.00.0000 + +wparam \emph on -stream +This pragma is deprecated. + Its use will cause a warning message to be issued. \emph default -pointer. - This new type has the format: -\layout Standard -\align center -\begin_inset Tabular - - - - - - - - - - - -\begin_inset Text - -\layout Standard - -pointer type -\end_inset - - -\begin_inset Text +\newline -\layout Standard +\layout List +\labelwidthstring 00.00.0000 -<7:6> -\end_inset - - -\begin_inset Text +code place a function symbol at static FLASH address +\layout LyX-Code -\layout Standard +Example: +\layout LyX-Code -<5> -\end_inset - - -\begin_inset Text +\layout LyX-Code -\layout Standard +/* place function test_func at 0x4000 */ +\layout LyX-Code -<4> -\end_inset - - -\begin_inset Text +#pragma code test_func 0x4000 +\layout LyX-Code -\layout Standard +\layout List +\labelwidthstring 00.00.0000 -<3:0> -\end_inset - - -\begin_inset Text +library instructs the linker to use a library module. +\newline +Usage: +\layout LyX-Code +#pragma library module_name \layout Standard -rest of the pointer -\end_inset - - -\begin_inset Text +\emph on +module_name +\emph default + can be any library or object file (including its path). + Note that there are four reserved keywords which have special meaning. + These are: \layout Standard +\align center -descrption -\end_inset - - +\begin_inset Tabular + + + + + \begin_inset Text \layout Standard -stream +Keyword \end_inset @@ -18742,7 +18364,7 @@ stream \layout Standard -00 +Description \end_inset @@ -18750,23 +18372,27 @@ stream \layout Standard -1 +Module to link \end_inset - + + + \begin_inset Text \layout Standard -0 + +\series bold +ignore \end_inset - + \begin_inset Text \layout Standard -nnnn +ignore all library pragmas \end_inset @@ -18775,54 +18401,20 @@ nnnn \layout Standard -\family typewriter -\shape slanted \emph on -uuuuuuuu uuuuuuuu -\end_inset - - -\begin_inset Text - -\layout Standard - -upper byte high nubble is 0x2n, the rest are zeroes +(none) \end_inset - - -\end_inset - - -\layout Standard - -Currently implemented there are 3 types of streams defined: -\layout Standard -\align center - -\begin_inset Tabular - - - - - - - + \begin_inset Text \layout Standard -stream type -\end_inset - - -\begin_inset Text - -\layout Standard -value +\series bold +c \end_inset @@ -18830,7 +18422,7 @@ value \layout Standard -module +link the C library \end_inset @@ -18838,7 +18430,11 @@ module \layout Standard -description + +\emph on +libc18f +\emph default +.lib \end_inset @@ -18848,17 +18444,9 @@ description \layout Standard -STREAM_USART -\end_inset - - -\begin_inset Text - -\layout Standard - -\family typewriter -0x200000UL +\series bold +math \end_inset @@ -18866,7 +18454,7 @@ STREAM_USART \layout Standard -USART +link the Math libarary \end_inset @@ -18874,7 +18462,11 @@ USART \layout Standard -Writes/Reads characters via the USART peripheral + +\emph on +libm18f +\emph default +.lib \end_inset @@ -18884,17 +18476,9 @@ Writes/Reads characters via the USART peripheral \layout Standard -STREAM_MSSP -\end_inset - - -\begin_inset Text - -\layout Standard - -\family typewriter -0x210000UL +\series bold +io \end_inset @@ -18902,7 +18486,7 @@ STREAM_MSSP \layout Standard -MSSP +link the I/O library \end_inset @@ -18910,7 +18494,11 @@ MSSP \layout Standard -Writes/Reads characters via the MSSP peripheral + +\emph on +libio18f* +\emph default +.lib \end_inset @@ -18920,17 +18508,9 @@ Writes/Reads characters via the MSSP peripheral \layout Standard -STREAM_USER -\end_inset - - -\begin_inset Text - -\layout Standard - -\family typewriter -0x2f0000UL +\series bold +debug \end_inset @@ -18938,7 +18518,7 @@ STREAM_USER \layout Standard -(none) +link the debug library \end_inset @@ -18946,7 +18526,11 @@ STREAM_USER \layout Standard -Writes/Reads characters via used defined functions + +\emph on +libdebug +\emph default +.lib \end_inset @@ -18955,163 +18539,260 @@ Writes/Reads characters via used defined functions \end_inset +\newline +* is the device number, i.e. + 452 for PIC18F452 MCU. \layout Standard -The stream identifiers are declared as macros in the stdio.h header. -\layout Standard - -In the libc library there exist the functions that are used to write to - each of the above streams. - These are +This feature allows for linking with specific libraries withoug having to + explicit name them in the command line. + Note that the +\noun on +ignore +\noun default + keyword will reject all modules specified by the library pragma. \layout List \labelwidthstring 00.00.0000 -_ -\begin_inset ERT -status Collapsed +udata pragma udata instructs the compiler to emit code so that linker will + place a variable at a specific memory bank +\layout LyX-Code -\layout Standard +Example: +\layout LyX-Code -\backslash -/ -\end_inset +\layout LyX-Code -_stream_usart_putchar writes a character at the USART stream -\layout List -\labelwidthstring 00.00.0000 +/* places variable foo at bank2 */ +\layout LyX-Code -_ -\begin_inset ERT -status Collapsed +#pragma udata bank2 foo +\layout LyX-Code +char foo; \layout Standard -\backslash -/ -\end_inset - -_stream_mssp_putchar writes a character at the MSSP stream -\layout List -\labelwidthstring 00.00.0000 +In order for this pragma to work extra SECTION directives should be added + in the .lkr script. + In the following example a sample .lkr file is shown: +\layout LyX-Code -putchar dummy function. - This writes a character to a user specified manner. -\layout Standard +\layout LyX-Code -In order to increase performance -\emph on -putchar -\emph default -is declared in stdio.h as having its parameter in WREG (it has the wparam - keyword). - In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function - in a user-friendly way. - -\emph on -arg -\emph default - is the name of the variable that holds the character to print. - An example follows: +// Sample linker script for the PIC18F452 processor \layout LyX-Code -#include -\newline -#include -\newline +LIBPATH . +\layout LyX-Code -\newline -PUTCHAR( c ) +CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED \layout LyX-Code -{ +CODEPAGE NAME=page START=0x2A END=0x7FFF \layout LyX-Code - PORTA = c; /* dump character c to PORTA */ +CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED \layout LyX-Code -} -\newline +CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED +\layout LyX-Code -\newline -void main(void) +CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED \layout LyX-Code -{ +CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED \layout LyX-Code - stdout = STREAM_USER; /* this is not necessery, since stdout points +ACCESSBANK NAME=accessram START=0x0 END=0x7F \layout LyX-Code - * by default to STREAM_USER */ \layout LyX-Code - printf (¨This is a printf test -\backslash -n¨); +DATABANK NAME=gpr0 START=0x80 END=0xFF \layout LyX-Code -} +DATABANK NAME=gpr1 START=0x100 END=0x1FF \layout LyX-Code -\layout Subsubsection +DATABANK NAME=gpr2 START=0x200 END=0x2FF +\layout LyX-Code -Printing functions -\layout Standard +DATABANK NAME=gpr3 START=0x300 END=0x3FF +\layout LyX-Code -PIC16 contains an implementation of the printf-family of functions. - There exist the following functions: +DATABANK NAME=gpr4 START=0x400 END=0x4FF \layout LyX-Code -extern unsigned int sprintf(char *buf, char *fmt, ...); +DATABANK NAME=gpr5 START=0x500 END=0x5FF \layout LyX-Code -extern unsigned int vsprintf(char *buf, char *fmt, va_list ap); +ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED \layout LyX-Code \layout LyX-Code -extern unsigned int printf(char *fmt, ...); +SECTION NAME=CONFIG ROM=config \layout LyX-Code -extern unsigned int vprintf(char *fmt, va_lista ap); \layout LyX-Code +SECTION NAME=bank0 RAM=gpr0 # these SECTION directives \layout LyX-Code -extern unsigned int fprintf(FILE *fp, char *fmt, ...); +SECTION NAME=bank1 RAM=gpr1 # should be added to link \layout LyX-Code -extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap); +SECTION NAME=bank2 RAM=gpr2 # section name 'bank?' with +\layout LyX-Code + +SECTION NAME=bank3 RAM=gpr3 # a specific DATABANK name +\layout LyX-Code + +SECTION NAME=bank4 RAM=gpr4 +\layout LyX-Code + +SECTION NAME=bank5 RAM=gpr5 \layout Standard -For sprintf and vsprintf +The linker will recognise the section name set in the pragma statement and + will position the variable at the memory bank set with the RAM field at + the SECTION line in the linker script file. +\layout Subsection + +Header Files +\begin_inset LatexCommand \label{sub:PIC16_Header-Files} + +\end_inset + + +\layout Standard + +There is one main header file that can be included to the source files using + the pic16 port. + That file is the +\series bold +pic18fregs.h +\series default +. + This header file contains the definitions for the processor special registers, + so it is necessary if the source accesses them. + It can be included by adding the following line in the beginning of the + file: +\layout LyX-Code + +#include +\layout Standard + +The specific microcontroller is selected within the pic18fregs.h automatically, + so the same source can be used with a variety of devices. +\layout Subsection + +Libraries +\layout Standard + +The libraries that PIC16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port depends on are the microcontroller device libraries which contain + the symbol definitions for the microcontroller special function registers. + These libraries have the format pic18fxxxx.lib, where \emph on -buf +xxxx \emph default -should normally be a data pointer where the resulting string will be placed. - No range checking is done so the user should allocate the necessery buffer. - For fprintf and vfprintf + is the microcontroller identification number. + The specific library is selected automatically by the compiler at link + stage according to the selected device. +\layout Standard + +Libraries are created with gplib which is part of the gputils package +\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils} + +\end_inset + +. +\layout Subsubsection* + +Building the libraries +\layout Standard + +Before using SDCC/pic16 there are some libraries that need to be compiled. + This process is not done automatically by SDCC since not all users use + SDCC for pic16 projects. + So each user should compile the libraries separately. +\layout Standard + +The steps to compile the pic16 libraries under Linux are: +\layout LyX-Code + +cd device/lib/pic16 +\layout LyX-Code + +./configure +\layout LyX-Code + +make +\layout LyX-Code + +cd .. +\layout LyX-Code + +make model-pic16 +\layout LyX-Code + +su -c 'make install' # install the libraries, you need the root password +\layout Standard + +If you need to install the headers too, do: +\layout LyX-Code + +cd device/include +\layout LyX-Code + +su -c 'make install' # install the headers, you need the root password +\layout Standard + +There exist a special target to build the I/O libraries. + This target is not automatically build because it will build the I/O library + for \emph on -fp +every \emph default - should be a stream pointer (i.e. - stdout, STREAM_MSSP, etc...). -\layout Subsubsection + supported device. + This way building will take quite a lot of time. + Users are advised to edit the +\series bold +device/lib/pic16/pics.build +\series default + file and then execute: +\layout LyX-Code -Signals +make lib-io +\layout Subsection + +Memory Models \layout Standard -The PIC18F family of microcontrollers supports a number of interrupt sources. - A list of these interrupts is shown in the following table: +The following memory models are supported by the PIC16 port: +\layout Itemize + +small model +\layout Itemize + +large model +\layout Standard + +Memory model affects the default size of pointers within the source. + The sizes are shown in the next table: \layout Standard \align center \begin_inset Tabular - + - - + @@ -19119,15 +18800,15 @@ The PIC18F family of microcontrollers supports a number of interrupt sources. \layout Standard -signal name +Pointer sizes according to memory model \end_inset - + \begin_inset Text \layout Standard -description +small model \end_inset @@ -19135,151 +18816,172 @@ description \layout Standard -signal name +large model \end_inset - + + + \begin_inset Text \layout Standard -descritpion +code pointers \end_inset - - - + \begin_inset Text \layout Standard -SIG_RB +16-bits \end_inset - + \begin_inset Text \layout Standard -PORTB change interrupt +24-bits \end_inset - + + + \begin_inset Text \layout Standard -SIG_EE +data pointers \end_inset - + \begin_inset Text \layout Standard -EEPROM/FLASH write complete interrupt +16-bits \end_inset - - - + \begin_inset Text \layout Standard -SIG_INT0 +16-bits \end_inset - -\begin_inset Text - -\layout Standard + + -INT0 external interrupt \end_inset - - -\begin_inset Text -\layout Standard -SIG_BCOL -\end_inset - - -\begin_inset Text +\layout Standard +It is advisable that all sources within a project are compiled with the + same memory model. + If one wants to override the default memory model, this can be done by + declaring a pointer as +\series bold +far +\series default + or +\series bold +near +\series default +. + Far selects large memory model's pointers, while near selects small memory + model's pointers. \layout Standard -Bus collision interrupt +The standard device libraries (see +\begin_inset LatexCommand \ref{sub:PIC16_Header-Files} + \end_inset - - - - -\begin_inset Text +) contain no reference to pointers, so they can be used with both memory + models. +\layout Subsection + +Stack \layout Standard -SIG_INT1 -\end_inset - - -\begin_inset Text +The stack implementation for the PIC16 port uses two indirect registers, + FSR1 and FSR2. +\layout List +\labelwidthstring 00.00.0000 + +FSR1 is assigned as stack pointer +\layout List +\labelwidthstring 00.00.0000 +FSR2 is assigned as frame pointer \layout Standard -INT1 external interrupt -\end_inset - - -\begin_inset Text +The following stack models are supported by the PIC16 port +\layout Itemize -\layout Standard -SIG_LVD -\end_inset - - -\begin_inset Text +\noun on +small +\noun default + model +\layout Itemize + +\noun on +large +\noun default + model \layout Standard -Low voltage detect interrupt -\end_inset - - - - -\begin_inset Text +\noun on +Small +\noun default + model means that only the FSRxL byte is used to access stack and frame, + while +\emph on +\noun on +large +\emph default +\noun default + uses both FSRxL and FSRxH registers. + The following table shows the stack/frame pointers sizes according to stack + model and the maximum space they can address: \layout Standard +\align center -SIG_INT2 -\end_inset - - +\begin_inset Tabular + + + + + + + \begin_inset Text \layout Standard -INT2 external interrupt +Stack & Frame pointer sizes according to stack model \end_inset - + \begin_inset Text \layout Standard -SIG_PSP +small \end_inset - + \begin_inset Text \layout Standard -Parallel slave port interrupt +large \end_inset @@ -19289,125 +18991,176 @@ Parallel slave port interrupt \layout Standard -SIG_CCP1 +Stack pointer FSR1 \end_inset - + \begin_inset Text \layout Standard -CCP1 module interrupt +8-bits \end_inset - + \begin_inset Text \layout Standard -SIG_AD +16-bits \end_inset - + + + \begin_inset Text \layout Standard -AD convertion complete interrupt +Frame pointer FSR2 \end_inset - - \begin_inset Text \layout Standard -SIG_CCP2 +8-bits \end_inset - + \begin_inset Text \layout Standard -CCP2 module interrupt +16-bits \end_inset - -\begin_inset Text - -\layout Standard + + -SIG_RC \end_inset - - -\begin_inset Text + \layout Standard -USART receive interrupt -\end_inset - - - - -\begin_inset Text -\layout Standard +\noun on +Large +\noun default +stack model is currently not working properly throughout the code generator. + So its use is not advised. + Also there are some other points that need special care: +\newline -SIG_TMR0 -\end_inset - - -\begin_inset Text +\layout Enumerate + +Do not create stack sections with size more than one physical bank (that + is 256 bytes) +\layout Enumerate +Stack sections should no cross physical bank limits (i.e. + #pragma stack 0x50 0x100) \layout Standard -TMR0 overflow interrupt -\end_inset - - -\begin_inset Text +These limitations are caused by the fact that only FSRxL is modified when + using SMALL stack model, so no more than 256 bytes of stack can be used. + This problem will disappear after LARGE model is fully implemented. +\layout Subsection +Functions \layout Standard -SIG_TX -\end_inset - - -\begin_inset Text +In addition to the standard SDCC function keywords, PIC16 port makes available + two more: +\layout List +\labelwidthstring 00.00.0000 -\layout Standard +wparam Use the WREG to pass one byte of the first function argument. + This improves speed but you may not use this for functions with arguments + that are called via function pointers, otherwise the first byte of the + first parameter will get lost. + Usage: +\layout LyX-Code -USART transmit interrupt -\end_inset - - - - -\begin_inset Text +void func_wparam(int a) wparam +\layout LyX-Code -\layout Standard +{ +\layout LyX-Code -SIG_TMR1 -\end_inset - - -\begin_inset Text + /* WREG hold the lower part of a */ +\layout LyX-Code -\layout Standard + /* the high part of a is stored in FSR2+2 (or +3 for large stack model) + */ +\layout LyX-Code -TMR1 overflow interrupt -\end_inset - - -\begin_inset Text +... +\layout LyX-Code +} \layout Standard -SIG_MSSP +This keyword replaces the deprecated wparam pragma. +\layout List +\labelwidthstring 00.00.0000 + +shadowregs When entering/exiting an ISR, it is possible to take advantage + of the PIC18F hardware shadow registers which hold the values of WREG, + STATUS and BSR registers. + This can be done by adding the keyword +\emph on +shadowregs +\emph default + before the +\emph on +interrupt +\emph default + keyword in the function's header. +\layout LyX-Code + +void isr_shadow(void) shadowregs interrupt 1 +\layout LyX-Code + +{ +\layout LyX-Code + +... +\layout LyX-Code + +} +\layout Standard + + +\emph on +shadowregs +\emph default + instructs the code generator not to store/restore WREG, STATUS, BSR when + entering/exiting the ISR. +\layout Subsection + +Function return values +\layout Standard + +Return values from functions are placed to the appropriate registers following + a modified Microchip policy optimized for SDCC. + The following table shows these registers: +\layout Standard +\align center + +\begin_inset Tabular + + + + + + +\begin_inset Text + +\layout Standard + +size \end_inset @@ -19415,7 +19168,7 @@ SIG_MSSP \layout Standard -SSP receive/transmit interrupt +destination register \end_inset @@ -19425,7 +19178,7 @@ SSP receive/transmit interrupt \layout Standard -SIG_TMR2 +8 bits \end_inset @@ -19433,14 +19186,17 @@ SIG_TMR2 \layout Standard -TMR2 matches PR2 interrupt +WREG \end_inset - + + + \begin_inset Text \layout Standard +16 bits \end_inset @@ -19448,16 +19204,17 @@ TMR2 matches PR2 interrupt \layout Standard +PRODL:WREG \end_inset - + \begin_inset Text \layout Standard -SIG_TMR3 +24 bits \end_inset @@ -19465,7 +19222,17 @@ SIG_TMR3 \layout Standard -TMR3 overflow interrupt +PRODH:PRODL:WREG +\end_inset + + + + +\begin_inset Text + +\layout Standard + +32 bits \end_inset @@ -19473,6 +19240,17 @@ TMR3 overflow interrupt \layout Standard +FSR0L:PRODH:PRODL:WREG +\end_inset + + + + +\begin_inset Text + +\layout Standard + +>32 bits \end_inset @@ -19480,6 +19258,7 @@ TMR3 overflow interrupt \layout Standard +on stack, FSR0 points to the beginning \end_inset @@ -19488,650 +19267,2386 @@ TMR3 overflow interrupt \end_inset -\layout Standard +\layout Subsection -The prototypes for these names are defined in the header file -\emph on -signal.h -\emph default - . +Interrupts \layout Standard -In order to simplify signal handling, a number of macros is provided: -\layout List -\labelwidthstring 00.00.0000 - -DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for - high priority interrupts. - +An interrupt servive routine (ISR) is declared using the \emph on -name +interrupt \emph default - is the function name to use. -\layout List -\labelwidthstring 00.00.0000 + keyword. +\layout LyX-Code -DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo - low priority interrupt. - +void isr(void) interrupt \emph on -name -\emph default - is the function name to use. -\layout List -\labelwidthstring 00.00.0000 +n +\layout LyX-Code -DEF_HANDLER(sig,handler) define a handler for signal -\emph on -sig. -\layout List -\labelwidthstring 00.00.0000 +{ +\layout LyX-Code -END_DEF end the declaration of the dispatch table. -\layout Standard +... +\layout LyX-Code -Additionally there are two more macros to simplify the declaration of the - signal handler: -\layout List -\labelwidthstring 00.00.0000 +} +\layout Standard -\series medium -SIGHANDLER(handler) -\series default -this declares the function prototype for the \emph on -handler +n \emph default - function. -\layout List -\labelwidthstring 00.00.0000 - -SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function. + is the interrupt number, which for PIC18F devices can be: \layout Standard +\align center -An example of using the macros above is shown below: -\layout LyX-Code - -#include -\layout LyX-Code - -#include -\newline - -\newline -DEF_INTHIGH(high_int) -\layout LyX-Code +\begin_inset Tabular + + + + + + + +\begin_inset Text -DEF_HANDLER(SIG_TMR0, _tmr0_handler) -\layout LyX-Code +\layout Standard -DEF_HANDLER(SIG_BCOL, _bcol_handler) -\layout LyX-Code -END_DEF -\newline +\emph on +n +\end_inset + + +\begin_inset Text -\newline -SIGHANDLER(_tmr0_handler) -\layout LyX-Code +\layout Standard -{ -\layout LyX-Code +Interrupt Vector +\end_inset + + +\begin_inset Text - /* action to be taken when timer 0 overflows */ -\layout LyX-Code +\layout Standard -} -\newline +Interrupt Vector Address +\end_inset + + + + +\begin_inset Text -\newline -SIGHANDLERNAKED(_bcol_handler) -\layout LyX-Code +\layout Standard -{ -\layout LyX-Code +0 +\end_inset + + +\begin_inset Text - _asm -\layout LyX-Code +\layout Standard - /* action to be taken when bus collision occurs */ -\layout LyX-Code +RESET vector +\end_inset + + +\begin_inset Text - retfie -\layout LyX-Code +\layout Standard - _endasm; -\layout LyX-Code +0x000000 +\end_inset + + + + +\begin_inset Text -} \layout Standard -\series bold -NOTES: -\series default - Special care should be taken when using the above scheme: -\layout Itemize - -do not place a colon (;) at the end of the DEF_* and END_DEF macros. -\layout Itemize - -when declaring SIGHANDLERNAKED handler never forget to use -\emph on -retfie -\emph default - for proper returning. -\layout Subsection +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +1 +\end_inset + + +\begin_inset Text -PIC16 Port -- Tips \layout Standard -Here you can find some general tips for compiling programs with SDCC/pic16. -\layout Subsubsection -Stack size +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +HIGH priority interrupts +\end_inset + + +\begin_inset Text + \layout Standard -The default stack size (that is 64 bytes) probably is enough for many programs. - One must take care that when there are many levels of function nesting, - or there is excessive usage of stack, its size should be extended. - An example of such a case is the printf/sprintf family of functions. - If you encounter problems like not being able to print integers, then you - need to set the stack size around the maximum (256 for small stack model). - The following diagram shows what happens when calling printf to print an - integer: -\layout LyX-Code +0x000008 +\end_inset + + + + +\begin_inset Text -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 +2 +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ +LOW priority interrupts \end_inset + + +\begin_inset Text --fommit-frame-pointer might reduce stack usage by not creating unnecessery - stack frames. - Other ways to reduce stack usage may exist. -\layout Chapter +\layout Standard -Debugging with SDCDB -\begin_inset LatexCommand \label{cha:Debugging-with-SDCDB} +0x000018 +\end_inset + + + \end_inset -\begin_inset LatexCommand \index{sdcdb (debugger)} +\layout Standard -\end_inset +When generating assembly code for ISR the code generator places a +\noun on +goto +\noun default +instruction at the +\emph on +Interrupt Vector Address +\emph default + which points at the genetated ISR. + This single GOTO instruction is part of an automatically generated +\emph on +interrupt entry point +\emph default + function. + The actuall ISR code is placed as normally would in the code space. + Upon interrupt request, the GOTO instruction is executed which jumps to + the ISR code. + When declaring interrupt functions as _naked this GOTO instruction is +\series bold +not +\series default + generated. + The whole interrupt functions is therefore placed at the Interrupt Vector + Address of the specific interrupt. + This is not a problem for the LOW priority interrupts, but it is a problem + for the RESET and the HIGH priority interrupts because code may be written + at the next interrupt´s vector address and cause undeterminate program + behaviour if that interrupt is raised. +\begin_inset Foot +collapsed false - \layout Standard -SDCC is distributed with a source level debugger -\begin_inset LatexCommand \index{Debugger} - -\end_inset +This is not a problem when +\layout Enumerate -. - The debugger uses a command line interface, the command repertoire of the - debugger has been kept as close to gdb -\begin_inset LatexCommand \index{gdb} +this is a HIGH interrupt ISR and LOW interrupts are +\emph on +disabled +\emph default + or not used. +\layout Enumerate +when the ISR is small enough not to reach the next interrupt´s vector address. \end_inset - (the GNU debugger) as possible. - The configuration and build process is part of the standard compiler installati -on, which also builds and installs the debugger in the target directory - specified during configuration. - The debugger allows you debug BOTH at the C source and at the ASM source - level. - Sdcdb is available on Unix platforms only. -\layout Section -Compiling for Debugging \layout Standard -The - -\begin_inset ERT -status Collapsed +\emph on +n +\emph default + is possible to be omitted. + This way a function is generated similar to an ISR, but it is not assigned + to any interrupt. \layout Standard -\backslash -/ -\end_inset - --debug -\begin_inset LatexCommand \index{-\/-debug} +When entering an interrupt, currently the PIC16 +\begin_inset LatexCommand \index{PIC16} \end_inset - option must be specified for all files for which debug information is to - be generated. - The complier generates a .adb file for each of these files. - The linker creates the .cdb -\begin_inset LatexCommand \index{.cdb} + port automatically saves the following registers: +\layout Itemize -\end_inset +WREG +\layout Itemize - file from the .adb -\begin_inset LatexCommand \index{.adb} +STATUS +\layout Itemize -\end_inset +BSR +\layout Itemize - files and the address information. - This .cdb is used by the debugger. -\layout Section +PROD (PRODL and PRODH) +\layout Itemize -How the Debugger Works +FSR0 (FSR0L and FSR0H) \layout Standard -When the - -\begin_inset ERT -status Collapsed +These registers are restored upon return from the interrupt routine. +\begin_inset Foot +collapsed false \layout Standard -\backslash -/ +NOTE that when the _naked attribute is specified for an interrupt routine, + then NO registers are stored or restored. \end_inset --debug option is specified the compiler generates extra symbol information - some of which are put into the assembler source and some are put into the - .adb file. - Then the linker creates the .cdb file from the individual .adb files with - the address information for the symbols. - The debugger reads the symbolic information generated by the compiler & - the address information generated by the linker. - It uses the SIMULATOR (Daniel's S51) to execute the program, the program - execution is controlled by the debugger. - When a command is issued for the debugger, it translates it into appropriate - commands for the simulator. -\layout Section -Starting the Debugger -\layout Standard +\layout Subsection -The debugger can be started using the following command line. - (Assume the file you are debugging has the file name foo). -\newline +Generic Pointers +\layout Standard -\newline +Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types. + There are 3 types of generic pointers currently implemented data, code + and eeprom pointers. + They are differentiated by the value of the 7th and 6th bits of the upper + byte: +\layout Standard +\align center -\family sans -\series bold -sdcdb foo -\newline +\begin_inset Tabular + + + + + + + + + +\begin_inset Text -\family default -\series default +\layout Standard -\newline -The debugger will look for the following files. -\layout Itemize +pointer type +\end_inset + + +\begin_inset Text -foo.c - the source file. -\layout Itemize +\layout Standard -foo.cdb - the debugger symbol information file. -\layout Itemize +7th bit +\end_inset + + +\begin_inset Text -foo.ihx - the Intel hex format -\begin_inset LatexCommand \index{Intel hex format} +\layout Standard +6th bit \end_inset + + +\begin_inset Text - object file. -\layout Section - -Command Line Options. -\layout Itemize +\layout Standard -- -\begin_inset ERT -status Collapsed +rest of the pointer +\end_inset + + +\begin_inset Text \layout Standard -\backslash -/ +descrption \end_inset - --directory= this option can used to specify the directory - search list. - The debugger will look into the directory list specified for source, cdb - & ihx files. - The items in the directory list must be separated by ':', e.g. - if the source files can be in the directories /home/src1 and /home/src2, - the - -\begin_inset ERT -status Collapsed + + + + +\begin_inset Text \layout Standard -\backslash -/ +data \end_inset - --directory option should be - -\begin_inset ERT -status Collapsed + + +\begin_inset Text \layout Standard -\backslash -/ +1 \end_inset + + +\begin_inset Text --directory=/home/src1:/home/src2. - Note there can be no spaces in the option. - -\layout Itemize - --cd - change to the . -\layout Itemize +\layout Standard --fullname - used by GUI front ends. -\layout Itemize +0 +\end_inset + + +\begin_inset Text --cpu - this argument is passed to the simulator please see the - simulator docs for details. -\layout Itemize +\layout Standard --X this options is passed to the simulator please see - the simulator docs for details. -\layout Itemize --s passed to simulator see the simulator docs for details. -\layout Itemize +\family typewriter +\shape slanted +\emph on +uuuuuu uuuuxxxx xxxxxxxx +\end_inset + + +\begin_inset Text --S passed to simulator see the simulator docs for details. -\layout Itemize +\layout Standard --k passed to simulator see the simulator docs for details. -\layout Section +a 12-bit data pointer in data RAM memory +\end_inset + + + + +\begin_inset Text -Debugger Commands. \layout Standard -As mentioned earlier the command interface for the debugger has been deliberatel -y kept as close the GNU debugger gdb, as possible. - This will help the integration with existing graphical user interfaces - (like ddd, xxgdb or xemacs) existing for the GNU debugger. - If you use a graphical user interface for the debugger you can skip the - next sections. -\layout Subsubsection* +code +\end_inset + + +\begin_inset Text -break [line | file:line | function | file:function] \layout Standard -Set breakpoint at specified line or function: -\newline +0 +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\family sans -\series bold -sdcdb>break 100 -\newline -sdcdb>break foo.c:100 -\newline -sdcdb>break funcfoo -\newline -sdcdb>break foo.c:funcfoo -\layout Subsubsection* +0 +\end_inset + + +\begin_inset Text -clear [line | file:line | function | file:function ] \layout Standard -Clear breakpoint at specified line or function: -\newline - -\newline -\family sans -\series bold -sdcdb>clear 100 -\newline -sdcdb>clear foo.c:100 -\newline -sdcdb>clear funcfoo -\newline -sdcdb>clear foo.c:funcfoo -\layout Subsubsection* +\family typewriter +\shape slanted +\emph on +uxxxxx xxxxxxxx xxxxxxxx +\end_inset + + +\begin_inset Text -continue \layout Standard -Continue program being debugged, after breakpoint. -\layout Subsubsection* +a 21-bit code pointer in FLASH memory +\end_inset + + + + +\begin_inset Text -finish \layout Standard -Execute till the end of the current function. -\layout Subsubsection* +eeprom +\end_inset + + +\begin_inset Text -delete [n] \layout Standard -Delete breakpoint number 'n'. - If used without any option clear ALL user defined break points. -\layout Subsubsection* +0 +\end_inset + + +\begin_inset Text -info [break | stack | frame | registers ] -\layout Itemize +\layout Standard -info break - list all breakpoints -\layout Itemize +1 +\end_inset + + +\begin_inset Text -info stack - show the function call stack. -\layout Itemize +\layout Standard -info frame - show information about the current execution frame. -\layout Itemize -info registers - show content of all registers. -\layout Subsubsection* +\family typewriter +\shape slanted +\emph on +uuuuuu uuuuuuxx xxxxxxxx +\end_inset + + +\begin_inset Text -step \layout Standard -Step program until it reaches a different source line. - Note: pressing repeats the last command. -\layout Subsubsection* +a 10-bit eeprom pointer in EEPROM memory +\end_inset + + + + +\begin_inset Text -next \layout Standard -Step program, proceeding through subroutine calls. -\layout Subsubsection* +(unimplemented) +\end_inset + + +\begin_inset Text -run \layout Standard -Start debugged program. -\layout Subsubsection* +1 +\end_inset + + +\begin_inset Text -ptype variable \layout Standard -Print type information of the variable. -\layout Subsubsection* +1 +\end_inset + + +\begin_inset Text -print variable \layout Standard -print value of variable. -\layout Subsubsection* - -file filename -\layout Standard -load the given file name. - Note this is an alternate method of loading file for debugging. -\layout Subsubsection* +\family typewriter +\shape slanted +\emph on +xxxxxx xxxxxxxx xxxxxxxx +\end_inset + + +\begin_inset Text -frame \layout Standard -print information about current frame. -\layout Subsubsection* +unimplemented pointer type +\end_inset + + + + +\end_inset + -set srcmode \layout Standard -Toggle between C source & assembly source. -\layout Subsubsection* +Generic pointer are read and written with a set of library functions which + read/write 1, 2, 3, 4 bytes. +\layout Subsection -! simulator command +PIC16 C Libraries +\layout Subsubsection + +Standard I/O Streams \layout Standard -Send the string following '!' to the simulator, the simulator response is - displayed. - Note the debugger does not interpret the command being sent to the simulator, - so if a command like 'go' is sent the debugger can loose its execution - context and may display incorrect values. -\layout Subsubsection* +In the +\emph on +stdio.h +\emph default + the type FILE is defined as: +\layout LyX-Code -quit +typedef char * FILE; \layout Standard -"Watch me now. - Iam going Down. - My name is Bobby Brown" -\layout Section +This type is the stream type implemented I/O in the PIC18F devices. + Also the standard input and output streams are declared in stdio.h: +\layout LyX-Code -Interfacing with XEmacs -\begin_inset LatexCommand \index{XEmacs} +extern FILE * stdin; +\layout LyX-Code + +extern FILE * stdout; +\layout Standard + +The FILE type is actually a generic pointer which defines one more type + of generic pointers, the +\emph on +stream +\emph default +pointer. + This new type has the format: +\layout Standard +\align center + +\begin_inset Tabular + + + + + + + + + + + +\begin_inset Text + +\layout Standard +pointer type \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{Emacs} +<7:6> +\end_inset + + +\begin_inset Text + +\layout Standard +<5> \end_inset + + +\begin_inset Text -. \layout Standard -Two files (in emacs lisp) are provided for the interfacing with XEmacs, - sdcdb.el and sdcdbsrc.el. - These two files can be found in the $(prefix)/bin directory after the installat -ion is complete. - These files need to be loaded into XEmacs for the interface to work. - This can be done at XEmacs startup time by inserting the following into - your '.xemacs' file (which can be found in your HOME directory): -\newline +<4> +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\family typewriter -(load-file sdcdbsrc.el) -\family default +<3:0> +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\newline -.xemacs is a lisp file so the () around the command is REQUIRED. - The files can also be loaded dynamically while XEmacs is running, set the - environment variable 'EMACSLOADPATH' to the installation bin directory - (/bin), then enter the following command ESC-x load-file sdcdbsrc. - To start the interface enter the following command: -\newline +rest of the pointer +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\family sans -\series bold -ESC-x sdcdbsrc -\family default -\series default +descrption +\end_inset + + + + +\begin_inset Text -\newline +\layout Standard -\newline -You will prompted to enter the file name to be debugged. - -\newline +stream +\end_inset + + +\begin_inset Text -\newline -The command line options that are passed to the simulator directly are bound - to default values in the file sdcdbsrc.el. - The variables are listed below, these values maybe changed as required. -\layout Itemize +\layout Standard -sdcdbsrc-cpu-type '51 -\layout Itemize +00 +\end_inset + + +\begin_inset Text -sdcdbsrc-frequency '11059200 -\layout Itemize +\layout Standard + +1 +\end_inset + + +\begin_inset Text -sdcdbsrc-serial nil \layout Standard -The following is a list of key mapping for the debugger interface. +0 +\end_inset + + +\begin_inset Text + +\layout Standard + +nnnn +\end_inset + + +\begin_inset Text + \layout Standard -\SpecialChar ~ \family typewriter +\shape slanted +\emph on +uuuuuuuu uuuuuuuu +\end_inset + + +\begin_inset Text -\newline -;;\SpecialChar ~ -Current Listing :: -\newline -;;key\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -binding\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -Comment -\newline -;;---\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\layout Standard + +upper byte high nubble is 0x2n, the rest are zeroes +\end_inset + + + + +\end_inset + + +\layout Standard + +Currently implemented there are 3 types of streams defined: +\layout Standard +\align center + +\begin_inset Tabular + + + + + + + + +\begin_inset Text + +\layout Standard + +stream type +\end_inset + + +\begin_inset Text + +\layout Standard + +value +\end_inset + + +\begin_inset Text + +\layout Standard + +module +\end_inset + + +\begin_inset Text + +\layout Standard + +description +\end_inset + + + + +\begin_inset Text + +\layout Standard + +STREAM_USART +\end_inset + + +\begin_inset Text + +\layout Standard + + +\family typewriter +0x200000UL +\end_inset + + +\begin_inset Text + +\layout Standard + +USART +\end_inset + + +\begin_inset Text + +\layout Standard + +Writes/Reads characters via the USART peripheral +\end_inset + + + + +\begin_inset Text + +\layout Standard + +STREAM_MSSP +\end_inset + + +\begin_inset Text + +\layout Standard + + +\family typewriter +0x210000UL +\end_inset + + +\begin_inset Text + +\layout Standard + +MSSP +\end_inset + + +\begin_inset Text + +\layout Standard + +Writes/Reads characters via the MSSP peripheral +\end_inset + + + + +\begin_inset Text + +\layout Standard + +STREAM_USER +\end_inset + + +\begin_inset Text + +\layout Standard + + +\family typewriter +0x2f0000UL +\end_inset + + +\begin_inset Text + +\layout Standard + +(none) +\end_inset + + +\begin_inset Text + +\layout Standard + +Writes/Reads characters via used defined functions +\end_inset + + + + +\end_inset + + +\layout Standard + +The stream identifiers are declared as macros in the stdio.h header. +\layout Standard + +In the libc library there exist the functions that are used to write to + each of the above streams. + These are +\layout List +\labelwidthstring 00.00.0000 + +_ +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +_stream_usart_putchar writes a character at the USART stream +\layout List +\labelwidthstring 00.00.0000 + +_ +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +_stream_mssp_putchar writes a character at the MSSP stream +\layout List +\labelwidthstring 00.00.0000 + +putchar dummy function. + This writes a character to a user specified manner. +\layout Standard + +In order to increase performance +\emph on +putchar +\emph default +is declared in stdio.h as having its parameter in WREG (it has the wparam + keyword). + In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function + in a user-friendly way. + +\emph on +arg +\emph default + is the name of the variable that holds the character to print. + An example follows: +\layout LyX-Code + +#include +\newline +#include +\newline + +\newline +PUTCHAR( c ) +\layout LyX-Code + +{ +\layout LyX-Code + + PORTA = c; /* dump character c to PORTA */ +\layout LyX-Code + +} +\newline + +\newline +void main(void) +\layout LyX-Code + +{ +\layout LyX-Code + + stdout = STREAM_USER; /* this is not necessery, since stdout points +\layout LyX-Code + + * by default to STREAM_USER */ +\layout LyX-Code + + printf (¨This is a printf test +\backslash +n¨); +\layout LyX-Code + +} +\layout LyX-Code + +\layout Subsubsection + +Printing functions +\layout Standard + +PIC16 contains an implementation of the printf-family of functions. + There exist the following functions: +\layout LyX-Code + +extern unsigned int sprintf(char *buf, char *fmt, ...); +\layout LyX-Code + +extern unsigned int vsprintf(char *buf, char *fmt, va_list ap); +\layout LyX-Code + +\layout LyX-Code + +extern unsigned int printf(char *fmt, ...); +\layout LyX-Code + +extern unsigned int vprintf(char *fmt, va_lista ap); +\layout LyX-Code + +\layout LyX-Code + +extern unsigned int fprintf(FILE *fp, char *fmt, ...); +\layout LyX-Code + +extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap); +\layout Standard + +For sprintf and vsprintf +\emph on +buf +\emph default +should normally be a data pointer where the resulting string will be placed. + No range checking is done so the user should allocate the necessery buffer. + For fprintf and vfprintf +\emph on +fp +\emph default + should be a stream pointer (i.e. + stdout, STREAM_MSSP, etc...). +\layout Subsubsection + +Signals +\layout Standard + +The PIC18F family of microcontrollers supports a number of interrupt sources. + A list of these interrupts is shown in the following table: +\layout Standard +\align center + +\begin_inset Tabular + + + + + + + + +\begin_inset Text + +\layout Standard + +signal name +\end_inset + + +\begin_inset Text + +\layout Standard + +description +\end_inset + + +\begin_inset Text + +\layout Standard + +signal name +\end_inset + + +\begin_inset Text + +\layout Standard + +descritpion +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_RB +\end_inset + + +\begin_inset Text + +\layout Standard + +PORTB change interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +SIG_EE +\end_inset + + +\begin_inset Text + +\layout Standard + +EEPROM/FLASH write complete interrupt +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_INT0 +\end_inset + + +\begin_inset Text + +\layout Standard + +INT0 external interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +SIG_BCOL +\end_inset + + +\begin_inset Text + +\layout Standard + +Bus collision interrupt +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_INT1 +\end_inset + + +\begin_inset Text + +\layout Standard + +INT1 external interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +SIG_LVD +\end_inset + + +\begin_inset Text + +\layout Standard + +Low voltage detect interrupt +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_INT2 +\end_inset + + +\begin_inset Text + +\layout Standard + +INT2 external interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +SIG_PSP +\end_inset + + +\begin_inset Text + +\layout Standard + +Parallel slave port interrupt +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_CCP1 +\end_inset + + +\begin_inset Text + +\layout Standard + +CCP1 module interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +SIG_AD +\end_inset + + +\begin_inset Text + +\layout Standard + +AD convertion complete interrupt +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_CCP2 +\end_inset + + +\begin_inset Text + +\layout Standard + +CCP2 module interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +SIG_RC +\end_inset + + +\begin_inset Text + +\layout Standard + +USART receive interrupt +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_TMR0 +\end_inset + + +\begin_inset Text + +\layout Standard + +TMR0 overflow interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +SIG_TX +\end_inset + + +\begin_inset Text + +\layout Standard + +USART transmit interrupt +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_TMR1 +\end_inset + + +\begin_inset Text + +\layout Standard + +TMR1 overflow interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +SIG_MSSP +\end_inset + + +\begin_inset Text + +\layout Standard + +SSP receive/transmit interrupt +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_TMR2 +\end_inset + + +\begin_inset Text + +\layout Standard + +TMR2 matches PR2 interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +\end_inset + + +\begin_inset Text + +\layout Standard + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SIG_TMR3 +\end_inset + + +\begin_inset Text + +\layout Standard + +TMR3 overflow interrupt +\end_inset + + +\begin_inset Text + +\layout Standard + +\end_inset + + +\begin_inset Text + +\layout Standard + +\end_inset + + + + +\end_inset + + +\layout Standard + +The prototypes for these names are defined in the header file +\emph on +signal.h +\emph default + . +\layout Standard + +In order to simplify signal handling, a number of macros is provided: +\layout List +\labelwidthstring 00.00.0000 + +DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for + high priority interrupts. + +\emph on +name +\emph default + is the function name to use. +\layout List +\labelwidthstring 00.00.0000 + +DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo + low priority interrupt. + +\emph on +name +\emph default + is the function name to use. +\layout List +\labelwidthstring 00.00.0000 + +DEF_HANDLER(sig,handler) define a handler for signal +\emph on +sig. +\layout List +\labelwidthstring 00.00.0000 + +END_DEF end the declaration of the dispatch table. +\layout Standard + +Additionally there are two more macros to simplify the declaration of the + signal handler: +\layout List +\labelwidthstring 00.00.0000 + + +\series medium +SIGHANDLER(handler) +\series default +this declares the function prototype for the +\emph on +handler +\emph default + function. +\layout List +\labelwidthstring 00.00.0000 + +SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function. +\layout Standard + +An example of using the macros above is shown below: +\layout LyX-Code + +#include +\layout LyX-Code + +#include +\newline + +\newline +DEF_INTHIGH(high_int) +\layout LyX-Code + +DEF_HANDLER(SIG_TMR0, _tmr0_handler) +\layout LyX-Code + +DEF_HANDLER(SIG_BCOL, _bcol_handler) +\layout LyX-Code + +END_DEF +\newline + +\newline +SIGHANDLER(_tmr0_handler) +\layout LyX-Code + +{ +\layout LyX-Code + + /* action to be taken when timer 0 overflows */ +\layout LyX-Code + +} +\newline + +\newline +SIGHANDLERNAKED(_bcol_handler) +\layout LyX-Code + +{ +\layout LyX-Code + + _asm +\layout LyX-Code + + /* action to be taken when bus collision occurs */ +\layout LyX-Code + + retfie +\layout LyX-Code + + _endasm; +\layout LyX-Code + +} +\layout Standard + + +\series bold +NOTES: +\series default + Special care should be taken when using the above scheme: +\layout Itemize + +do not place a colon (;) at the end of the DEF_* and END_DEF macros. +\layout Itemize + +when declaring SIGHANDLERNAKED handler never forget to use +\emph on +retfie +\emph default + for proper returning. +\layout Subsection + +PIC16 Port -- Tips +\layout Standard + +Here you can find some general tips for compiling programs with SDCC/pic16. +\layout Subsubsection + +Stack size +\layout Standard + +The default stack size (that is 64 bytes) probably is enough for many programs. + One must take care that when there are many levels of function nesting, + or there is excessive usage of stack, its size should be extended. + An example of such a case is the printf/sprintf family of functions. + If you encounter problems like not being able to print integers, then you + need to set the stack size around the maximum (256 for small stack model). + The following diagram shows what happens when calling printf to print an + integer: +\layout LyX-Code + +printf () --> ltoa () --> ultoa () --> divschar () +\layout Standard + +It is should be understood that stack is easily consumed when calling complicate +d functions. + Using command line arguments like - +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-fommit-frame-pointer might reduce stack usage by not creating unnecessery + stack frames. + Other ways to reduce stack usage may exist. +\layout Chapter + +Debugging +\layout Standard + +There are several approaches to debugging your code. + This chapter is meant to show your options and to give detail on some of + them: +\newline + +\newline +When writing your code: +\layout Itemize + +write your code with debugging in mind (avoid duplicating code, put conceptually + similar variables into structs, use structured code, have strategic points + within your code where all variables are consistent, ...) +\layout Itemize + +run a syntax-checking tool like splint +\begin_inset LatexCommand \index{splint (syntax checking tool)} + +\end_inset + + +\begin_inset LatexCommand \index{lint (syntax checking tool)} + +\end_inset + + (see - +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-more-pedantic +\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT} + +\end_inset + +) over the code. +\layout Itemize + +for the high level code use a C-compiler (like f.e. + GCC) to compile run and debug the code on your host. + See (see - +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-more-pedantic +\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT} + +\end_inset + + ) on howto handle syntax extensions like __xdata, __at(), ... + +\layout Itemize + +use another C-compiler to compile code for your target. + Always an option but not recommended:) And not very likely to help you. + If you seriously consider walking this path you should at least occasionally + check portability of your code. + Most commercial compiler vendors will offer an evaluation version so you + can test compile your code or snippets of your code. +\layout Standard + +Debugging on a simulator: +\layout Itemize + +there is a separate section about SDCDB (section +\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB} + +\end_inset + +) below. +\layout Itemize + +or (8051 specific) use a freeware/commercial simulator which interfaces + to the AOMF +\begin_inset LatexCommand \index{AOMF, AOMF51} + +\end_inset + + file (see +\begin_inset LatexCommand \ref{OMF file} + +\end_inset + +) optionally generated by SDCC. +\layout Standard + +Debugging On-target: +\layout Itemize + +use a MCU port pin to serially output debug data to the RS232 port of your + host. + You'll probably want some level shifting device typically involving a MAX232 + or similar IC. + If the hardware serial port of the MCU is not available search for 'Software + UART' in your favourite search machine. +\layout Itemize + +use an on-target monitor. + In this context a monitor is a small program which usually accepts commands + via a serial line and allows to set program counter, to single step through + a program and read/write memory locations. + For the 8051 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} + +\end_inset + + file (see +\begin_inset LatexCommand \ref{OMF file} + +\end_inset + +) as input file. + +\layout Standard + +Last not least: +\layout Itemize + +if you are not familiar with any of the following terms you're likely to + run into problems rather sooner than later: +\emph on +volatile +\emph default +, +\emph on +atomic +\emph default +, +\emph on +memory map +\emph default +, +\emph on +overlay +\emph default +. + As an embedded programmer you +\emph on +have +\emph default + to know them so why not look them up +\emph on +before +\emph default + you have problems?) +\layout Itemize + +tell someone else about your problem (actually this is a surprisingly effective + means to hunt down the bug even if the listener is not familiar with your + environment). + As 'failure to communicate' is probably one of the job-induced deformations + of an embedded programmer this is highly encouraged. +\layout Section + +Debugging with SDCDB +\begin_inset LatexCommand \label{cha:Debugging-with-SDCDB} + +\end_inset + + +\begin_inset LatexCommand \index{sdcdb (debugger)} + +\end_inset + + +\layout Standard + +SDCC is distributed with a source level debugger +\begin_inset LatexCommand \index{Debugger} + +\end_inset + +. + The debugger uses a command line interface, the command repertoire of the + debugger has been kept as close to gdb +\begin_inset LatexCommand \index{gdb} + +\end_inset + + (the GNU debugger) as possible. + The configuration and build process is part of the standard compiler installati +on, which also builds and installs the debugger in the target directory + specified during configuration. + The debugger allows you debug BOTH at the C source and at the ASM source + level. + Sdcdb is currently not available on Win32 platforms. +\layout Subsection + +Compiling for Debugging +\layout Standard + +The - +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-debug +\begin_inset LatexCommand \index{-\/-debug} + +\end_inset + + option must be specified for all files for which debug information is to + be generated. + The compiler generates a .adb file for each of these files. + The linker creates the .cdb +\begin_inset LatexCommand \index{.cdb} + +\end_inset + + file from the .adb +\begin_inset LatexCommand \index{.adb} + +\end_inset + + files and the address information. + This .cdb is used by the debugger. +\layout Subsection + +How the Debugger Works +\layout Standard + +When the - +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-debug option is specified the compiler generates extra symbol information + some of which are put into the assembler source and some are put into the + .adb file. + Then the linker creates the .cdb file from the individual .adb files with + the address information for the symbols. + The debugger reads the symbolic information generated by the compiler & + the address information generated by the linker. + It uses the SIMULATOR (Daniel's S51) to execute the program, the program + execution is controlled by the debugger. + When a command is issued for the debugger, it translates it into appropriate + commands for the simulator. + (Currently sdcdb only connects to the simulator but +\emph on +newcdb +\emph default + at +\begin_inset LatexCommand \url{http://ec2drv.sf.net/} + +\end_inset + + is an effort to connect directly to the hardware.) +\layout Subsection + +Starting the Debugger SDCDB +\layout Standard + +The debugger can be started using the following command line. + (Assume the file you are debugging has the file name foo). +\newline + +\newline + +\family sans +\series bold +sdcdb foo +\newline + +\family default +\series default + +\newline +The debugger will look for the following files. +\layout Itemize + +foo.c - the source file. +\layout Itemize + +foo.cdb - the debugger symbol information file. +\layout Itemize + +foo.ihx - the Intel hex format +\begin_inset LatexCommand \index{Intel hex format} + +\end_inset + + object file. +\layout Subsection + +SDCDB Command Line Options +\layout Itemize + +- +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-directory= this option can used to specify the directory + search list. + The debugger will look into the directory list specified for source, cdb + & ihx files. + The items in the directory list must be separated by ':', e.g. + if the source files can be in the directories /home/src1 and /home/src2, + the - +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-directory option should be - +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + +-directory=/home/src1:/home/src2. + Note there can be no spaces in the option. + +\layout Itemize + +-cd - change to the . +\layout Itemize + +-fullname - used by GUI front ends. +\layout Itemize + +-cpu - this argument is passed to the simulator please see the + simulator docs for details. +\layout Itemize + +-X this options is passed to the simulator please see + the simulator docs for details. +\layout Itemize + +-s passed to simulator see the simulator docs for details. +\layout Itemize + +-S passed to simulator see the simulator docs for details. +\layout Itemize + +-k passed to simulator see the simulator docs for details. +\layout Subsection + +SDCDB Debugger Commands +\layout Standard + +As mentioned earlier the command interface for the debugger has been deliberatel +y kept as close the GNU debugger gdb, as possible. + This will help the integration with existing graphical user interfaces + (like ddd, xxgdb or xemacs) existing for the GNU debugger. + If you use a graphical user interface for the debugger you can skip this + section. +\layout Subsubsection* + +break [line | file:line | function | file:function] +\layout Standard + +Set breakpoint at specified line or function: +\newline + +\newline + +\family sans +\series bold +sdcdb>break 100 +\newline +sdcdb>break foo.c:100 +\newline +sdcdb>break funcfoo +\newline +sdcdb>break foo.c:funcfoo +\layout Subsubsection* + +clear [line | file:line | function | file:function ] +\layout Standard + +Clear breakpoint at specified line or function: +\newline + +\newline + +\family sans +\series bold +sdcdb>clear 100 +\newline +sdcdb>clear foo.c:100 +\newline +sdcdb>clear funcfoo +\newline +sdcdb>clear foo.c:funcfoo +\layout Subsubsection* + +continue +\layout Standard + +Continue program being debugged, after breakpoint. +\layout Subsubsection* + +finish +\layout Standard + +Execute till the end of the current function. +\layout Subsubsection* + +delete [n] +\layout Standard + +Delete breakpoint number 'n'. + If used without any option clear ALL user defined break points. +\layout Subsubsection* + +info [break | stack | frame | registers ] +\layout Itemize + +info break - list all breakpoints +\layout Itemize + +info stack - show the function call stack. +\layout Itemize + +info frame - show information about the current execution frame. +\layout Itemize + +info registers - show content of all registers. +\layout Subsubsection* + +step +\layout Standard + +Step program until it reaches a different source line. + Note: pressing repeats the last command. +\layout Subsubsection* + +next +\layout Standard + +Step program, proceeding through subroutine calls. +\layout Subsubsection* + +run +\layout Standard + +Start debugged program. +\layout Subsubsection* + +ptype variable +\layout Standard + +Print type information of the variable. +\layout Subsubsection* + +print variable +\layout Standard + +print value of variable. +\layout Subsubsection* + +file filename +\layout Standard + +load the given file name. + Note this is an alternate method of loading file for debugging. +\layout Subsubsection* + +frame +\layout Standard + +print information about current frame. +\layout Subsubsection* + +set srcmode +\layout Standard + +Toggle between C source & assembly source. +\layout Subsubsection* + +! simulator command +\layout Standard + +Send the string following '!' to the simulator, the simulator response is + displayed. + Note the debugger does not interpret the command being sent to the simulator, + so if a command like 'go' is sent the debugger can loose its execution + context and may display incorrect values. +\layout Subsubsection* + +quit +\layout Standard + +"Watch me now. + Iam going Down. + My name is Bobby Brown" +\layout Subsection + +Interfacing SDCDB with DDD +\layout Comment + +The screenshot was converted from png to eps with: +\begin_inset Quotes sld +\end_inset + +bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps +\begin_inset Quotes srd +\end_inset + + which produces a pretty compact eps file which is free from compression + artifacts. +\layout Comment + +The screenshot was included in sdccman.lyx cvs version 1.120 but later removed + as this broke the build system on Sourceforge (pdf-file was broken). +\layout Standard + +The .eps File +\size footnotesize + +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.eps} + +\end_inset + + +\size default + shows a screenshot of a debugging session with DDD +\begin_inset LatexCommand \index{DDD (debugger)} + +\end_inset + + (Unix only) on a simulated 8032. + The debugging session might not run as smoothly as the screenshot suggests. + The debugger allows setting of breakpoints, displaying and changing variables, + single stepping through C and assembler code. + +\newline +The source was compiled with +\family sans +\series bold + +\newline + +\newline +sdcc - +\family default +\series default + +\begin_inset ERT +status Collapsed + +\layout Standard + +\backslash +/ +\end_inset + + +\family sans +\series bold +-debug ddd_example.c +\family default +\series default + +\family sans +\series bold + +\newline + +\family default +\series default + +\newline +and DDD was invoked with +\family sans +\series bold + +\newline + +\newline +ddd -debugger 'sdcdb -cpu 8032 ddd_example' +\layout Subsection + +Interfacing SDCDB with XEmacs +\begin_inset LatexCommand \index{XEmacs} + +\end_inset + + +\begin_inset LatexCommand \index{Emacs} + +\end_inset + + +\layout Standard + +Two files (in emacs lisp) are provided for the interfacing with XEmacs, + sdcdb.el and sdcdbsrc.el. + These two files can be found in the $(prefix)/bin directory after the installat +ion is complete. + These files need to be loaded into XEmacs for the interface to work. + This can be done at XEmacs startup time by inserting the following into + your '.xemacs' file (which can be found in your HOME directory): +\newline + +\newline + +\family typewriter +(load-file sdcdbsrc.el) +\family default + +\newline + +\newline +.xemacs is a lisp file so the () around the command is REQUIRED. + The files can also be loaded dynamically while XEmacs is running, set the + environment variable 'EMACSLOADPATH' to the installation bin directory + (/bin), then enter the following command ESC-x load-file sdcdbsrc. + To start the interface enter the following command: +\newline + +\newline + +\family sans +\series bold +ESC-x sdcdbsrc +\family default +\series default + +\newline + +\newline +You will prompted to enter the file name to be debugged. + +\newline + +\newline +The command line options that are passed to the simulator directly are bound + to default values in the file sdcdbsrc.el. + The variables are listed below, these values maybe changed as required. +\layout Itemize + +sdcdbsrc-cpu-type '51 +\layout Itemize + +sdcdbsrc-frequency '11059200 +\layout Itemize + +sdcdbsrc-serial nil +\layout Standard + +The following is a list of key mapping for the debugger interface. +\layout Standard + +\SpecialChar ~ + +\family typewriter + +\newline +;;\SpecialChar ~ +Current Listing :: +\newline +;;key\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +binding\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Comment +\newline +;;---\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -20852,229 +22367,1349 @@ sdcdbsrc-srcmode\SpecialChar ~ \SpecialChar ~ Toggle list mode \newline -;; +;; +\newline + +\layout Chapter +\pagebreak_top +TIPS +\layout Standard + +Here are a few guidelines that will help the compiler generate more efficient + code, some of the tips are specific to this compiler others are generally + good programming practice. +\layout Itemize + +Use the smallest data type to represent your data-value. + If it is known in advance that the value is going to be less than 256 then + use an 'unsigned char' instead of a 'short' or 'int'. + Please note, that ANSI C requires both signed and unsigned chars to be + promoted to 'signed int' +\begin_inset LatexCommand \index{promotion to signed int} + +\end_inset + + before doing any operation. + This promotion +\begin_inset LatexCommand \index{type promotion} + +\end_inset + + +\begin_inset LatexCommand \label{type promotion} + +\end_inset + + can be omitted, if the result is the same. + The effect of the promotion rules together with the sign-extension is often + surprising: +\begin_deeper +\layout Verse + + +\family typewriter +unsigned char uc = 0xfe; +\newline +if (uc * uc < 0) /* this is true! */ +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.... +\newline +} +\layout Standard + + +\family typewriter +uc * uc +\family default + is evaluated as +\family typewriter +(int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024 +\family default +. + +\newline +Another one: +\layout Verse + + +\family typewriter +(unsigned char) -12 / (signed char) -3 = ... +\layout Standard + +No, the result is not 4: +\layout Verse + + +\family typewriter +(int) (unsigned char) -12 / (int) (signed char) -3 = +\newline +(int) (unsigned char) 0xf4 / (int) (signed char) 0xfd = +\newline +(int) 0x00f4 / (int) 0xfffd = +\newline +(int) 0x00f4 / (int) 0xfffd = +\newline +(int) 244 / (int) -3 = +\newline +(int) -81 = (int) 0xffaf; +\layout Standard + +Don't complain, that gcc gives you a different result. + gcc uses 32 bit ints, while SDCC uses 16 bit ints. + Therefore the results are different. +\newline +From +\begin_inset Quotes sld +\end_inset + +comp.lang.c FAQ +\begin_inset Quotes srd +\end_inset + +: +\layout Quote + +If well-defined overflow characteristics are important and negative values + are not, or if you want to steer clear of sign-extension problems when + manipulating bits or bytes, use one of the corresponding unsigned types. + (Beware when mixing signed and unsigned values in expressions, though.) +\newline +Although character types (especially unsigned char) can be used as "tiny" + integers, doing so is sometimes more trouble than it's worth, due to unpredicta +ble sign extension and increased code size. +\end_deeper +\layout Itemize + +Use unsigned when it is known in advance that the value is not going to + be negative. + This helps especially if you are doing division or multiplication, bit-shifting + or are using an array index. +\layout Itemize + +NEVER jump into a LOOP. +\layout Itemize + +Declare the variables to be local +\begin_inset LatexCommand \index{local variables} + +\end_inset + + whenever possible, especially loop control variables (induction). +\layout Itemize + +Since the compiler does not always do implicit integral promotion, the programme +r should do an explicit cast when integral promotion is required. +\layout Itemize + +Reducing the size of division, multiplication & modulus operations can reduce + code size substantially. + Take the following code for example. +\begin_deeper +\layout Verse + + +\family typewriter +foobar(unsigned int p1, unsigned char ch) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +unsigned char ch1 = p1 % ch ; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.... +\newline +} +\layout Standard + +For the modulus operation the variable ch will be promoted to unsigned int + first then the modulus operation will be performed (this will lead to a + call to support routine _moduint()), and the result will be casted to a + char. + If the code is changed to +\layout Verse + + +\family typewriter +foobar(unsigned int p1, unsigned char ch) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +unsigned char ch1 = (unsigned char)p1 % ch ; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.... +\newline +} +\layout Standard + +It would substantially reduce the code generated (future versions of the + compiler will be smart enough to detect such optimization opportunities). +\end_deeper +\layout Itemize + +Have a look at the assembly listing to get a +\begin_inset Quotes sld +\end_inset + +feeling +\begin_inset Quotes srd +\end_inset + + for the code generation. +\layout Section + +Porting code from or to other compilers +\layout Itemize + +check whether endianness of the compilers differs and adapt where needed. +\layout Itemize + +check the device specific header files for compiler specific syntax. + Eventually include the file to allow using common header files. +\layout Itemize + +check whether the startup code contains the correct initialization (watchdog, + peripherals). +\layout Itemize + +check whether the sizes of short, int, long match. +\layout Itemize + +check if some 16 or 32 bit hardware registers require a specific addressing + order (least significant or most significant byte first) and adapt if needed + ( +\emph on +first +\emph default + and +\emph on +last +\emph default + relate to time and not to lower/upper memory location here, so this is + +\emph on +not +\emph default + the same as endianness). +\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). +\layout Itemize + +check that the compilers are not told to supress warnings. +\layout Itemize + +check and convert compiler specific extensions (interrupts, memory areas, + pragmas etc.). +\layout Itemize + +check for differences in type promotion (especially check for math operations + on char variables and for the use of the ~\SpecialChar ~ +operator on bit variables. + See +\begin_inset LatexCommand \ref{type promotion} + +\end_inset + + and +\begin_inset LatexCommand \ref{sec:Compatibility-with-previous} + +\end_inset + +). +\layout Itemize + +check the assembly code generated for interrupt routines (f.e. + for calls to possibly non-reentrant library functions). +\layout Itemize + +check whether timing loops result in proper timing (or preferably consider + a rewrite of the code with timer based delays instead). +\layout Itemize + +check for differences in printf parameters (some compilers push (va_arg +\begin_inset LatexCommand \index{va\_arg} + +\end_inset + +) char variables as integers others as char). +\layout Itemize + +check the resulting memory layout. +\layout Section + +Tools +\begin_inset LatexCommand \index{Tools} + +\end_inset + + included in the distribution +\layout Standard +\align center + +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +Name +\end_inset + + +\begin_inset Text + +\layout Standard + +Purpose +\end_inset + + +\begin_inset Text + +\layout Standard + +Directory +\end_inset + + + + +\begin_inset Text + +\layout Standard + +uCsim +\end_inset + + +\begin_inset Text + +\layout Standard + +Simulator for various architectures +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/sim/ucsim +\end_inset + + + + +\begin_inset Text + +\layout Standard + +keil2sdcc.pl +\end_inset + + +\begin_inset Text + +\layout Standard + +header file conversion +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/support/scripts +\end_inset + + + + +\begin_inset Text + +\layout Standard + +mh2h.c +\end_inset + + +\begin_inset Text + +\layout Standard + +header file conversion +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/support/scripts +\end_inset + + + + +\begin_inset Text + +\layout Standard + +as-gbz80 +\end_inset + + +\begin_inset Text + +\layout Standard + +Assembler +\end_inset + + +\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 + + + + +\begin_inset Text + +\layout Standard + +as-z80 +\end_inset + + +\begin_inset Text + +\layout Standard + +Assembler +\end_inset + + +\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 + + + + +\begin_inset Text + +\layout Standard + +asx8051 +\end_inset + + +\begin_inset Text + +\layout Standard + +Assembler +\end_inset + + +\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 + + + + +\begin_inset Text + +\layout Standard + +sdcdb +\end_inset + + +\begin_inset Text + +\layout Standard + +Simulator +\end_inset + + +\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 + + + + +\begin_inset Text + +\layout Standard + +aslink +\end_inset + + +\begin_inset Text + +\layout Standard + +Linker +\end_inset + + +\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 + + + + +\begin_inset Text + +\layout Standard + +link-z80 +\end_inset + + +\begin_inset Text + +\layout Standard + +Linker +\end_inset + + +\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 + + + + +\begin_inset Text + +\layout Standard + +link-gbz80 +\end_inset + + +\begin_inset Text + +\layout Standard + +Linker +\end_inset + + +\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 + + + + +\begin_inset Text + +\layout Standard + +packihx +\end_inset + + +\begin_inset Text + +\layout Standard + +ihx packer +\end_inset + + +\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 + + + + +\end_inset + + +\newline + +\layout Section + +Documentation +\begin_inset LatexCommand \index{Documentation} + +\end_inset + + included in the distribution +\layout Standard +\align center + +\begin_inset Tabular + + + + + + +\begin_inset Text + +\layout Standard + +Subject / Title +\end_inset + + +\begin_inset Text + +\layout Standard + +Where to get / filename +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SDCC Compiler User Guide +\end_inset + + +\begin_inset Text + +\layout Standard + +You're reading it right now +\end_inset + + + + +\begin_inset Text + +\layout Standard + +Changelog of SDCC +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/Changelog +\end_inset + + + + +\begin_inset Text + +\layout Standard + +ASXXXX +\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)} + +\end_inset + + +\begin_inset LatexCommand \index{Assembler documentation} + +\end_inset + + Assemblers and ASLINK +\begin_inset LatexCommand \index{aslink} + +\end_inset + + +\begin_inset LatexCommand \index{Linker documentation} + +\end_inset + + Relocating Linker +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/as/doc/asxhtm.html +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SDCC regression test +\begin_inset LatexCommand \index{Regression test} + +\end_inset + + +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/doc/test_suite_spec.pdf +\end_inset + + + + +\begin_inset Text + +\layout Standard + +Various notes +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/doc/* +\end_inset + + + + +\begin_inset Text + +\layout Standard + +Notes on debugging with sdcdb +\begin_inset LatexCommand \index{sdcdb (debugger)} + +\end_inset + + +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/debugger/README +\end_inset + + + + +\begin_inset Text + +\layout Standard + +Software simulator for microcontrollers +\end_inset + + +\begin_inset Text + +\layout Standard + + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +sdcc/sim/ucsim/doc +\family default +\series default +\shape default +\size default +\emph default +\bar default +\noun default +\color default +/index.html +\end_inset + + + + +\begin_inset Text + +\layout Standard + +Temporary notes on the pic16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/src/pic16/NOTES +\end_inset + + + + +\begin_inset Text + +\layout Standard + +SDCC internal documentation (debugging file format) +\end_inset + + +\begin_inset Text + +\layout Standard + +sdcc/doc/ +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +cdbfileformat.pd +\family default +\series default +\shape default +\size default +\emph default +\bar default +\noun default +\color default +f +\end_inset + + + + +\end_inset + + \newline -\layout Chapter -\pagebreak_top -TIPS +\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 center + +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +Name +\end_inset + + +\begin_inset Text + +\layout Standard + +Purpose +\end_inset + + +\begin_inset Text + \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 +Where to get +\end_inset + + + + +\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 + +gpsim +\begin_inset LatexCommand \index{gpsim (pic simulator)} \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 +\end_inset + + +\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 +PIC simulator +\end_inset + + +\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 + + +\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html} + +\end_inset + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +gputils +\begin_inset LatexCommand \index{gputils (pic tools)} + +\end_inset + + +\end_inset + + +\begin_inset Text + +\layout Standard + +GNU PIC utilities +\end_inset + + +\begin_inset Text + +\layout Standard + + +\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils} + +\end_inset + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +flP5 +\end_inset + + +\begin_inset Text + +\layout Standard + +PIC programmer +\end_inset + + +\begin_inset Text + +\layout Standard + + +\begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/} + +\end_inset + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +ec2drv/newcdb +\end_inset + + +\begin_inset Text + +\layout Standard + +Tools for Silicon Laboratories JTAG debug adapter, partly based on sdcdb + (Unix only) +\end_inset + + +\begin_inset Text + +\layout Standard + + +\begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv} + +\end_inset + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +indent +\begin_inset LatexCommand \index{indent (source formatting tool)} + +\end_inset + + +\end_inset + + +\begin_inset Text + +\layout Standard + +Formats C source - Master of the white spaces +\end_inset + + +\begin_inset Text + +\layout Standard + + +\begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html} + +\end_inset + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +srecord +\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)} + +\end_inset + + +\end_inset + + +\begin_inset Text + +\layout Standard + +Object file conversion, checksumming, ... +\end_inset + + +\begin_inset Text + +\layout Standard + + +\begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord} + +\end_inset + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +objdump +\begin_inset LatexCommand \index{objdump (tool)} + +\end_inset + + +\end_inset + + +\begin_inset Text -\family typewriter -(unsigned char) -12 / (signed char) -3 = ... \layout Standard -No, the result is not 4: -\layout Verse - +Object file conversion, ... +\end_inset + + +\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 +Part of binutils (should be there anyway) \end_inset + + + + +\begin_inset Text -comp.lang.c FAQ -\begin_inset Quotes srd +\layout Standard + +cmon51 \end_inset + + +\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 +8051 monitor (hex up-/download, single step, disassemble) +\end_inset + + +\begin_inset Text -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 +\layout Standard -NEVER jump into a LOOP. -\layout Itemize -Declare the variables to be local -\begin_inset LatexCommand \index{local variables} +\begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51} \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 +\end_inset + + + + +\begin_inset Text -Reducing the size of division, multiplication & modulus operations can reduce - code size substantially. - Take the following code for example. -\begin_deeper -\layout Verse +\layout Standard +doxygen +\begin_inset LatexCommand \index{doxygen (source documentation tool)} -\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 +\end_inset -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 +\end_inset + + +\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 +Source code documentation system \end_inset + + +\begin_inset Text -feeling -\begin_inset Quotes srd -\end_inset +\layout Standard - for the code generation. -\layout Section -Tools -\begin_inset LatexCommand \index{Tools} +\begin_inset LatexCommand \url{http://www.doxygen.org} \end_inset - included in the distribution -\layout Standard -\align center -\begin_inset Tabular - - - - - - +\end_inset + + + \begin_inset Text \layout Standard -Name +kdevelop \end_inset @@ -21082,7 +23717,7 @@ Name \layout Standard -Purpose +IDE (has anyone tried integrating SDCC & sdcdb? Unix only) \end_inset @@ -21090,7 +23725,12 @@ Purpose \layout Standard -Directory + +\begin_inset LatexCommand \url{http://www.kdevelop.org} + +\end_inset + + \end_inset @@ -21100,7 +23740,7 @@ Directory \layout Standard -uCsim +paulmon \end_inset @@ -21108,7 +23748,7 @@ uCsim \layout Standard -Simulator for various architectures +8051 monitor (hex up-/download, single step, disassemble) \end_inset @@ -21116,7 +23756,12 @@ Simulator for various architectures \layout Standard -sdcc/sim/ucsim + +\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html} + +\end_inset + + \end_inset @@ -21126,7 +23771,12 @@ sdcc/sim/ucsim \layout Standard -keil2sdcc.pl +splint +\begin_inset LatexCommand \index{splint (syntax checking tool)} + +\end_inset + + \end_inset @@ -21134,7 +23784,12 @@ keil2sdcc.pl \layout Standard -header file conversion +Statically checks c sources (see +\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT} + +\end_inset + +) \end_inset @@ -21142,17 +23797,27 @@ header file conversion \layout Standard -sdcc/support/scripts + +\begin_inset LatexCommand \url{http://www.splint.org} + +\end_inset + + \end_inset - + \begin_inset Text \layout Standard -mh2h.c +ddd +\begin_inset LatexCommand \index{ddd (debugger)} + +\end_inset + + \end_inset @@ -21160,7 +23825,12 @@ mh2h.c \layout Standard -header file conversion +Debugger, serves nicely as GUI to sdcdb +\begin_inset LatexCommand \index{sdcdb (debugger)} + +\end_inset + + (Unix only) \end_inset @@ -21168,28 +23838,62 @@ header file conversion \layout Standard -sdcc/support/scripts + +\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/} + +\end_inset + + +\end_inset + + + + +\end_inset + + +\newline + +\layout Section + +Related documentation / recommended reading +\layout Standard +\align center + +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +Name \end_inset - - \begin_inset Text \layout Standard -as-gbz80 +Subject / Title \end_inset - + \begin_inset Text \layout Standard -Assembler +Where to get \end_inset - + + + \begin_inset Text \layout Standard @@ -21203,25 +23907,20 @@ Assembler \bar no \noun off \color none -sdcc/bin +c-refcard.pdf \end_inset - - \begin_inset Text \layout Standard -as-z80 -\end_inset - - -\begin_inset Text +C Reference Card +\begin_inset LatexCommand \index{C Reference card} -\layout Standard +\end_inset -Assembler +, 2 pages \end_inset @@ -21230,15 +23929,11 @@ Assembler \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://refcards.com/refcards/c/index.html} + +\end_inset + + \end_inset @@ -21248,7 +23943,7 @@ sdcc/bin \layout Standard -asx8051 +c-faq \end_inset @@ -21256,7 +23951,7 @@ asx8051 \layout Standard -Assembler +C-FAQ-list \end_inset @@ -21265,15 +23960,11 @@ Assembler \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.eskimo.com/~scs/C-faq/top.html} + +\end_inset + + \end_inset @@ -21283,7 +23974,7 @@ sdcc/bin \layout Standard -sdcdb +ISO/IEC 9899:TC2 \end_inset @@ -21291,7 +23982,15 @@ sdcdb \layout Standard -Simulator + +\begin_inset Quotes sld +\end_inset + +C-Standard +\begin_inset Quotes srd +\end_inset + + \end_inset @@ -21300,15 +23999,13 @@ Simulator \layout Standard -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -sdcc/bin +\size footnotesize + +\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899} + +\end_inset + + \end_inset @@ -21318,7 +24015,7 @@ sdcc/bin \layout Standard -aslink +ISO/IEC DTR 18037 \end_inset @@ -21326,7 +24023,15 @@ aslink \layout Standard -Linker + +\begin_inset Quotes sld +\end_inset + +Extensions for Embedded C +\begin_inset Quotes srd +\end_inset + + \end_inset @@ -21335,15 +24040,13 @@ Linker \layout Standard -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -sdcc/bin +\size footnotesize + +\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf} + +\end_inset + + \end_inset @@ -21353,7 +24056,6 @@ sdcc/bin \layout Standard -link-z80 \end_inset @@ -21361,7 +24063,7 @@ link-z80 \layout Standard -Linker +Latest datasheet of the target CPU \end_inset @@ -21369,16 +24071,7 @@ Linker \layout Standard - -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -sdcc/bin +vendor \end_inset @@ -21388,7 +24081,6 @@ sdcc/bin \layout Standard -link-gbz80 \end_inset @@ -21396,7 +24088,7 @@ link-gbz80 \layout Standard -Linker +Revision history of datasheet \end_inset @@ -21404,16 +24096,7 @@ Linker \layout Standard - -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -sdcc/bin +vendor \end_inset @@ -21423,7 +24106,9 @@ sdcc/bin \layout Standard -packihx +S. + S. + Muchnick \end_inset @@ -21431,7 +24116,7 @@ packihx \layout Standard -ihx packer +Advanced Compiler Design and Implementation \end_inset @@ -21439,16 +24124,7 @@ ihx packer \layout Standard - -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -sdcc/bin +bookstore (very dedicated, probably read other books first) \end_inset @@ -21457,1917 +24133,2357 @@ sdcc/bin \end_inset -\newline - -\layout Section +\newline + +\layout Section + +Some Questions +\layout Standard + +Some questions answered, some pointers given - it might be time to in turn + ask +\emph on +you +\emph default + some questions: +\layout Itemize + +can you solve your project with the selected microcontroller? Would you + find out early or rather late that your target is too small/slow/whatever? + Can you switch to a slightly better device if it doesn't fit? +\layout Itemize + +should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU + and/or another programming language be more adequate? Would an operating + system on the target device help? +\layout Itemize + +if you solved the problem, will the marketing department be happy? +\layout Itemize + +if the marketing department is happy, will customers be happy? +\layout Itemize + +if you're the project manager, marketing department and maybe even the customer + in one person, have you tried to see the project from the outside? +\layout Itemize + +is the project done if you think it is done? Or is just that other interface/pro +tocol/feature/configuration/option missing? How about website, manual(s), + internationali(z|s)ation, packaging, labels, 2nd source for components, + electromagnetic compatability/interference, documentation for production, + production test software, update mechanism, patent issues? +\layout Itemize + +is your project adequately positioned in that magic triangle: fame, fortune, + fun? +\layout Standard + +Maybe not all answers to these questions are known and some answers may + even be +\emph on +no +\emph default +, nevertheless knowing these questions may help you to avoid burnout +\begin_inset Foot +collapsed false + +\layout Standard + +burnout is bad for electronic devices, programmers and motorcycle tyres +\end_inset + +. + Chances are you didn't want to hear some of them... +\layout Chapter + +Support +\begin_inset LatexCommand \index{Support} + +\end_inset + + +\layout Standard + +SDCC has grown to be a large project. + The compiler alone (without the preprocessor, assembler and linker) is + well over 100,000 lines of code (blank stripped). + The open source nature of this project is a key to its continued growth + and support. + You gain the benefit and support of many active software developers and + end users. + Is SDCC perfect? No, that's why we need your help. + The developers take pride in fixing reported bugs. + You can help by reporting the bugs and helping other SDCC users. + There are lots of ways to contribute, and we encourage you to take part + in making SDCC a great software package. + +\layout Standard + +The SDCC project is hosted on the SDCC sourceforge site at +\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc} + +\end_inset + +. + You'll find the complete set of mailing lists +\begin_inset LatexCommand \index{Mailing list(s)} + +\end_inset + +, forums, bug reporting system, patch submission +\begin_inset LatexCommand \index{Patch submission} + +\end_inset -Documentation -\begin_inset LatexCommand \index{Documentation} + system, download +\begin_inset LatexCommand \index{download} \end_inset - included in the distribution -\layout Standard -\align center + area and Subversion code repository +\begin_inset LatexCommand \index{Subversion code repository} -\begin_inset Tabular - - - - - - -\begin_inset Text +\end_inset -\layout Standard + there. +\layout Section + +Reporting Bugs +\begin_inset LatexCommand \index{Bug reporting} -Subject / Title \end_inset - - -\begin_inset Text -\layout Standard -Where to get / filename +\begin_inset LatexCommand \index{Reporting bugs} + \end_inset - - - - -\begin_inset Text -\layout Standard -SDCC Compiler User Guide -\end_inset - - -\begin_inset Text +\layout Standard +The recommended way of reporting bugs is using the infrastructure of the + sourceforge site. + You can follow the status of bug reports there and have an overview about + the known bugs. \layout Standard -You're reading it right now -\end_inset - - - - -\begin_inset Text +Bug reports are automatically forwarded to the developer mailing list and + will be fixed ASAP. + When reporting a bug, it is very useful to include a small test program + (the smaller the better) which reproduces the problem. + If you can isolate the problem by looking at the generated assembly code, + this can be very helpful. + Compiling your program with the - +\begin_inset ERT +status Collapsed \layout Standard -Changelog of SDCC +\backslash +/ \end_inset - - -\begin_inset Text -\layout Standard +-dumpall +\begin_inset LatexCommand \index{-\/-dumpall} -sdcc/Changelog \end_inset - - - - -\begin_inset Text -\layout Standard + option can sometimes be useful in locating optimization problems. + When reporting a bug please maker sure you: +\layout Enumerate -ASXXXX -\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)} +Attach the code you are compiling with SDCC. + +\layout Enumerate -\end_inset +Specify the exact command you use to run SDCC, or attach your Makefile. + +\layout Enumerate +Specify the SDCC version (type " +\family sans +\series bold +sdcc -v +\family default +\series default +"), your platform, and operating system. + +\layout Enumerate -\begin_inset LatexCommand \index{Assembler documentation} +Provide an exact copy of any error message or incorrect output. + +\layout Enumerate -\end_inset +Put something meaningful in the subject of your message. +\layout Standard - Assemblers and ASLINK -\begin_inset LatexCommand \index{aslink} +Please attempt to include these 5 important parts, as applicable, in all + requests for support or when reporting any problems or bugs with SDCC. + Though this will make your message lengthy, it will greatly improve your + chance that SDCC users and developers will be able to help you. + Some SDCC developers are frustrated by bug reports without code provided + that they can use to reproduce and ultimately fix the problem, so please + be sure to provide sample code if you are reporting a bug! +\layout Standard + +Please have a short check that you are using a recent version of SDCC and + the bug is not yet known. + This is the link for reporting bugs: +\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599} \end_inset +. +\layout Section -\begin_inset LatexCommand \index{Linker documentation} +Requesting Features +\begin_inset LatexCommand \label{sub:Requesting-Features} \end_inset - Relocating Linker -\end_inset - - -\begin_inset Text -\layout Standard +\begin_inset LatexCommand \index{Feature request} -sdcc/as/doc/asxhtm.html \end_inset - - - - -\begin_inset Text -\layout Standard -SDCC regression test -\begin_inset LatexCommand \index{Regression test} +\begin_inset LatexCommand \index{Requesting features} \end_inset -\end_inset - - -\begin_inset Text - \layout Standard -sdcc/doc/test_suite_spec.pdf +Like bug reports feature requests are forwarded to the developer mailing + list. + This is the link for requesting features: +\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599} + \end_inset - - - - -\begin_inset Text +. +\layout Section + +Submitting patches \layout Standard -Various notes +Like bug reports contributed patches are forwarded to the developer mailing + list. + This is the link for submitting patches +\begin_inset LatexCommand \index{Patch submission} + \end_inset - - -\begin_inset Text -\layout Standard +: +\begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599} -sdcc/doc/* \end_inset - - - - -\begin_inset Text +. \layout Standard -Notes on debugging with sdcdb -\begin_inset LatexCommand \index{sdcdb (debugger)} +You need to specify some parameters to the +\family typewriter +diff +\family default + command for the patches to be useful. + If you modified more than one file a patch created f.e. + with +\family sans +\series bold +\begin_inset Quotes sld \end_inset - +diff -Naur unmodified_directory modified_directory >my_changes.patch +\begin_inset Quotes srd \end_inset - - -\begin_inset Text - -\layout Standard -sdcc/debugger/README -\end_inset - - - - -\begin_inset Text -\layout Standard +\family default +\series default + will be fine, otherwise +\family sans +\series bold -Software simulator for microcontrollers +\begin_inset Quotes sld \end_inset - - -\begin_inset Text -\layout Standard +diff -u sourcefile.c.orig sourcefile.c >my_changes.patch +\begin_inset Quotes srd +\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 - - - - -\begin_inset Text + +\family default +will do. +\layout Section +Getting Help \layout Standard -Temporary notes on the pic16 -\begin_inset LatexCommand \index{PIC16} +These links should take you directly to the +\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599} \end_inset - port -\end_inset - - -\begin_inset Text + +\begin_inset Foot +collapsed false \layout Standard -sdcc/src/pic16/NOTES +Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting + automated messages (mid 2003) \end_inset - - - - -\begin_inset Text -\layout Standard + and the +\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599} -SDCC internal documentation (debugging file format) \end_inset - - -\begin_inset Text -\layout Standard +, lists +\begin_inset LatexCommand \index{Mailing list(s)} -sdcc/doc/ -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -cdbfileformat.pd -\family default -\series default -\shape default -\size default -\emph default -\bar default -\noun default -\color default -f \end_inset - - - -\end_inset + and forums are archived and searchable so if you are lucky someone already + had a similar problem. + While mails to the lists themselves are delivered promptly their web front + end on sourceforge sometimes shows a severe time lag (up to several weeks), + if you're seriously using SDCC please consider subscribing to the lists. +\layout Section +ChangeLog +\layout Standard -\newline +You can follow the status of the Subversion version +\begin_inset LatexCommand \index{version} -\layout Section +\end_inset -Related open source tools -\begin_inset LatexCommand \index{Related tools} + of SDCC by watching the Changelog +\begin_inset LatexCommand \index{Changelog} \end_inset + in the Subversion repository +\size footnotesize + +\begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog} -\layout Standard -\align center +\end_inset -\begin_inset Tabular - - - - - - - -\begin_inset Text +. +\layout Section +Subversion Source Code Repository \layout Standard -Name +The output of +\family sans +\series bold +sdcc --version +\family default +\series default + or the filenames of the snapshot versions of SDCC include date and its + Subversion +\begin_inset LatexCommand \index{Subversion} + \end_inset - - -\begin_inset Text -\layout Standard + number. + Subversion allows to download the source of recent or previous versions + +\begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599} -Purpose \end_inset - - -\begin_inset Text -\layout Standard + (by number or by date). + An on-line source code browser and detailled instructions are also available + there. + SDCC versions starting from 1999 up to now are available (currently the + versions prior to the conversion from cvs to Subversion (April 2006) are + either by accessible by Subversion or by cvs). +\layout Section + +Release policy +\begin_inset LatexCommand \index{Release policy} -Where to get \end_inset - - - - -\begin_inset Text + \layout Standard -gpsim -\begin_inset LatexCommand \index{gpsim (pic simulator)} +Historically there often were long delays between official releases and + the sourceforge download area tends to get not updated at all. + Excuses in the past might have referred to problems with live range analysis, + but as this was fixed a while ago, the current problem is that another + excuse has to be found. + Kidding aside, we have to get better there! On the other hand there are + daily snapshots available at +\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php} \end_inset +, and you can always build the very last version (hopefully with many bugs + fixed, and features added) from the source code available at +\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source} \end_inset - - -\begin_inset Text -\layout Standard +. +\layout Section + +Examples +\begin_inset LatexCommand \index{Examples} -PIC simulator \end_inset - - -\begin_inset Text + \layout Standard +You'll find some small examples in the directory +\emph on +sdcc/device/examples/. + +\emph default +More examples and libraries are available at +\emph on + The SDCC Open Knowledge Resource +\begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/} + +\end_inset -\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html} + +\emph default +web site or at +\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/} \end_inset +. +\layout Comment + +I did insert a reference to Paul's web site here although it seems rather + dedicated to a specific 8032 board (I think it's okay because it f.e. + shows LCD/Harddisc interface and has a free 8051 monitor. + Independent 8032 board vendors face hard competition of heavily subsidized + development boards anyway). +\layout Comment + +Maybe we should include some links to real world applications. + Preferably pointer to pointers (one for each architecture) so this stays + manageable here? +\layout Section + +Quality control +\begin_inset LatexCommand \index{Quality control} \end_inset - - - - -\begin_inset Text + \layout Standard -gputils -\begin_inset LatexCommand \index{gputils (pic tools)} +The compiler is passed through nightly compile and build checks. + The so called +\shape italic +regression tests +\shape default + +\begin_inset LatexCommand \index{Regression test} \end_inset + check that SDCC itself compiles flawlessly on several platforms and checks + the quality of the code generated by SDCC by running the code through simulator +s. + There is a separate document +\shape italic +test_suite.pdf +\begin_inset LatexCommand \index{Test suite} \end_inset - - -\begin_inset Text + +\shape default + about this. \layout Standard -GNU PIC utilities +You'll find the test code in the directory +\shape italic +sdcc/support/regression +\shape default +. + You can run these tests manually by running +\family sans +make +\family default + in this directory (or f.e. + +\family sans +\series bold + +\begin_inset Quotes sld \end_inset - - -\begin_inset Text -\layout Standard +make test-mcs51 +\begin_inset Quotes srd +\end_inset -\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils} +\family default +\series default + if you don't want to run the complete tests). + The test code might also be interesting if you want to look for examples +\begin_inset LatexCommand \index{Examples} \end_inset + checking corner cases of SDCC or if you plan to submit patches +\begin_inset LatexCommand \index{Patch submission} \end_inset - - - - -\begin_inset Text +. \layout Standard -flP5 -\end_inset - - -\begin_inset Text +The pic port uses a different set of regression tests, you'll find them + in the directory +\shape italic +sdcc/src/regression +\shape default +. +\layout Section + +Use of SDCC in Education +\layout Standard + +In short: +\emph on +highly +\emph default + encouraged +\begin_inset Foot +collapsed false \layout Standard -PIC programmer +the phrase "use in education" might evoke the association " +\emph on +only +\emph default + fit for use in education". + This connotation is not intended but nevertheless risked as the licensing + of SDCC makes it difficult to offer educational discounts \end_inset - - -\begin_inset Text -\layout Standard +. + If your rationales are to: +\layout Enumerate +give students a chance to understand the +\emph on +complete +\emph default + steps of code generation +\layout Enumerate -\begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/} +have a curriculum that can be extended for years. + Then you could use an fpga board as target and your curriculum will seamlessly + extend from logic synthesis ( +\begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org} \end_inset +, +\begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm} \end_inset - - - - -\begin_inset Text - -\layout Standard -indent -\begin_inset LatexCommand \index{indent (source formatting tool)} +), over assembly programming, to C to FPGA compilers ( +\begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac} \end_inset +) and to C. +\layout Enumerate + +be able to insert excursions about skills like using a revision control + system, submitting/applying patches, using a type-setting (as opposed to + word-processing) engine LyX/LaTeX, using +\begin_inset LatexCommand \url[SourceForge]{http://www.sf.net} \end_inset - - -\begin_inset Text -\layout Standard +, following some +\begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette} -Formats C source - Master of the white spaces \end_inset - - -\begin_inset Text -\layout Standard +, understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open + Source Software, CPU simulation, compiler regression tests +\begin_inset LatexCommand \index{Regression test} +\end_inset -\begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html} +. + +\newline +And if there should be a shortage of ideas then you can always point students + to the ever-growing feature request list +\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599} \end_inset +. +\layout Enumerate + +not tie students to a specific host platform and instead allow them to use + a host platform of +\emph on +their +\emph default + choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and + eventually +\begin_inset LatexCommand \url[OLPC]{http://wiki.laptop.org/wiki/One_Laptop_per_Child} \end_inset - - - - -\begin_inset Text -\layout Standard +) +\layout Enumerate -srecord -\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)} +not encourage students to use illegal copies of educational software +\layout Enumerate -\end_inset +be immune to licensing/availability/price changes of the chosen tool chain +\layout Enumerate +be able to change to a new target platform without having to adopt a new + tool chain +\layout Enumerate -\end_inset - - -\begin_inset Text +have complete control over and insight into the tool chain +\layout Enumerate -\layout Standard +make your students aware about the pros and cons of open source software + development +\layout Enumerate -Object file conversion, checksumming, ... -\end_inset - - -\begin_inset Text +give back to the public as you are probably at least partially publically + funded +\layout Enumerate +give students a chance to publically prove their skills and to possibly + see a world wide impact \layout Standard +then SDCC is probably among the first choices. + Well, probably SDCC might be the only choice. +\layout Chapter +\pagebreak_top +SDCC Technical Data +\layout Section -\begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord} +Optimizations +\begin_inset LatexCommand \index{Optimizations} \end_inset -\end_inset - - - - -\begin_inset Text - \layout Standard -objdump -\begin_inset LatexCommand \index{objdump (tool)} - -\end_inset +SDCC performs a host of standard optimizations in addition to some MCU specific + optimizations. + +\layout Subsection +Sub-expression Elimination +\begin_inset LatexCommand \index{Subexpression elimination} \end_inset - - -\begin_inset Text - -\layout Standard -Object file conversion, ... -\end_inset - - -\begin_inset Text \layout Standard -Part of binutils (should be there anyway) -\end_inset - - - - -\begin_inset Text +The compiler does local and +\emph on +g +\emph default +lobal +\emph on +c +\emph default +ommon +\emph on +s +\emph default +ubexpression +\emph on +e +\emph default +limination, e.g.: +\layout Verse + +\family typewriter +i = x + y + 1; +\newline +j = x + y; \layout Standard -doxygen -\begin_inset LatexCommand \index{doxygen (source documentation tool)} +will be translated to +\layout Verse -\end_inset +\family typewriter +iTemp = x + y; +\newline +i = iTemp + 1; +\newline +j = iTemp; +\layout Standard + +Some subexpressions are not as obvious as the above example, e.g.: +\layout Verse -\end_inset - - -\begin_inset Text +\family typewriter +a->b[i].c = 10; +\newline +a->b[i].d = 11; \layout Standard -Source code documentation system -\end_inset - - -\begin_inset Text +In this case the address arithmetic a->b[i] will be computed only once; + the equivalent code in C would be. +\layout Verse + +\family typewriter +iTemp = a->b[i]; +\newline +iTemp.c = 10; +\newline +iTemp.d = 11; \layout Standard +The compiler will try to keep these temporary variables in registers. +\layout Subsection -\begin_inset LatexCommand \url{http://www.doxygen.org} +Dead-Code Elimination +\begin_inset LatexCommand \index{Dead-code elimination} \end_inset -\end_inset - - - - -\begin_inset Text +\layout Verse -\layout Standard -kdevelop -\end_inset - - -\begin_inset Text +\family typewriter +int global; +\newline +\newline +void f () { +\newline +\SpecialChar ~ +\SpecialChar ~ +int i; +\newline +\SpecialChar ~ +\SpecialChar ~ +i = 1; \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* dead store */ +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 1;\SpecialChar ~ +/* dead store */ +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 2; +\newline +\SpecialChar ~ +\SpecialChar ~ +return; +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 3;\SpecialChar ~ +/* unreachable */ +\newline +} \layout Standard -IDE (has anyone tried integrating SDCC & sdcdb? Unix only) -\end_inset - - -\begin_inset Text - -\layout Standard +will be changed to +\layout Verse -\begin_inset LatexCommand \url{http://www.kdevelop.org} +\family typewriter +int global; +\newline -\end_inset +\newline +void f () { +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 2; +\newline +} +\layout Subsection +Copy-Propagation +\begin_inset LatexCommand \index{Copy propagation} \end_inset - - - - -\begin_inset Text - -\layout Standard - -splint -\begin_inset LatexCommand \index{splint (syntax checking tool)} -\end_inset +\layout Verse -\end_inset - - -\begin_inset Text +\family typewriter +int f() { +\newline +\SpecialChar ~ +\SpecialChar ~ +int i, j; +\newline +\SpecialChar ~ +\SpecialChar ~ +i = 10; +\newline +\SpecialChar ~ +\SpecialChar ~ +j = i; +\newline +\SpecialChar ~ +\SpecialChar ~ +return j; +\newline +} \layout Standard -Statically checks c sources (see -\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT} - -\end_inset +will be changed to +\layout Verse -) -\end_inset - - -\begin_inset Text +\family typewriter +int f() { +\newline +\SpecialChar ~ +\SpecialChar ~ +int i, j; +\newline +\SpecialChar ~ +\SpecialChar ~ +i = 10; +\newline +\SpecialChar ~ +\SpecialChar ~ +j = 10; +\newline +\SpecialChar ~ +\SpecialChar ~ +return 10; +\newline +} \layout Standard +Note: the dead stores created by this copy propagation will be eliminated + by dead-code elimination. +\layout Subsection -\begin_inset LatexCommand \url{http://www.splint.org} - -\end_inset - +Loop Optimizations +\begin_inset LatexCommand \index{Loop optimization} \end_inset - - - - -\begin_inset Text -\layout Standard -ddd -\begin_inset LatexCommand \index{ddd (debugger)} +\begin_inset LatexCommand \label{sub:Loop-Optimizations} \end_inset -\end_inset - - -\begin_inset Text - \layout Standard -Debugger, serves nicely as GUI to sdcdb -\begin_inset LatexCommand \index{sdcdb (debugger)} +Two types of loop optimizations are done by SDCC +\emph on +loop invariant +\emph default + lifting and +\emph on + strength reduction +\emph default + of loop induction variables. + In addition to the strength reduction the optimizer marks the induction + variables and the register allocator tries to keep the induction variables + in registers for the duration of the loop. + Because of this preference of the register allocator +\begin_inset LatexCommand \index{Register allocation} \end_inset - (Unix only) -\end_inset - - -\begin_inset Text +, loop induction optimization causes an increase in register pressure, which + may cause unwanted spilling of other temporary variables into the stack +\begin_inset LatexCommand \index{stack} -\layout Standard +\end_inset + / data space. + The compiler will generate a warning message when it is forced to allocate + extra space either on the stack or data space. + If this extra space allocation is undesirable then induction optimization + can be eliminated either for the entire source file (with - +\begin_inset ERT +status Collapsed -\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/} +\layout Standard +\backslash +/ \end_inset - -\end_inset - - - +-noinduction option) or for a given function only using #pragma\SpecialChar ~ +noinduction +\begin_inset LatexCommand \index{\#pragma noinduction} \end_inset +. +\newline \newline +Loop Invariant: +\layout Verse -\layout Section -Related documentation / recommended reading +\family typewriter +for (i = 0 ; i < 100 ; i ++) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +f += k + l; \layout Standard -\align center - -\begin_inset Tabular - - - - - - - -\begin_inset Text -\layout Standard +changed to +\layout Verse -Name -\end_inset - - -\begin_inset Text +\family typewriter +itemp = k + l; +\newline +for (i = 0; i < 100; i++) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +f += itemp; \layout Standard -Subject / Title -\end_inset - - -\begin_inset Text +As mentioned previously some loop invariants are not as apparent, all static + address computations are also moved out of the loop. +\newline -\layout Standard +\newline +Strength Reduction +\begin_inset LatexCommand \index{Strength reduction} -Where to get \end_inset - - - - -\begin_inset Text - -\layout Standard +, this optimization substitutes an expression by a cheaper expression: +\layout Verse -\family roman -\series medium -\shape up -\size normal -\emph off -\bar no -\noun off -\color none -c-refcard.pdf -\end_inset - - -\begin_inset Text +\family typewriter +for (i=0;i < 100; i++) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ar[i*5] = i*3; \layout Standard -C Reference Card -\begin_inset LatexCommand \index{C Reference card} - -\end_inset +changed to +\layout Verse -, 2 pages -\end_inset - - -\begin_inset Text +\family typewriter +itemp1 = 0; +\newline +itemp2 = 0; +\newline +for (i=0;i< 100;i++) { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ar[itemp1] = itemp2; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +itemp1 += 5; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +itemp2 += 3; +\newline +} \layout Standard - -\begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html} +The more expensive multiplication +\begin_inset LatexCommand \index{Multiplication} \end_inset + is changed to a less expensive addition. +\layout Subsection + +Loop Reversing +\begin_inset LatexCommand \index{Loop reversing} \end_inset - - - - -\begin_inset Text + \layout Standard -c-faq +This optimization is done to reduce the overhead of checking loop boundaries + for every iteration. + Some simple loops can be reversed and implemented using a +\begin_inset Quotes eld \end_inset - - -\begin_inset Text - -\layout Standard -C-FAQ-list +decrement and jump if not zero +\begin_inset Quotes erd \end_inset - - -\begin_inset Text -\layout Standard + instruction. + SDCC checks for the following criterion to determine if a loop is reversible + (note: more sophisticated compilers use data-dependency analysis to make + this determination, SDCC uses a more simple minded analysis). +\layout Itemize + +The 'for' loop is of the form +\newline +\newline -\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html} +\family typewriter +for( = ; [< | <=] ; [++ | + += 1]) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\layout Itemize +The does not contain +\begin_inset Quotes eld \end_inset +continue +\begin_inset Quotes erd +\end_inset + or 'break +\begin_inset Quotes erd \end_inset - - - - -\begin_inset Text -\layout Standard +. +\layout Itemize -\end_inset - - -\begin_inset Text +All goto's are contained within the loop. +\layout Itemize -\layout Standard +No function calls within the loop. +\layout Itemize -Latest datasheet of the target CPU -\end_inset - - -\begin_inset Text +The loop control variable is not assigned any value within the loop +\layout Itemize -\layout Standard +The loop control variable does NOT participate in any arithmetic operation + within the loop. +\layout Itemize -vendor -\end_inset - - - - -\begin_inset Text +There are NO switch statements in the loop. +\layout Subsection +Algebraic Simplifications \layout Standard -\end_inset - - -\begin_inset Text +SDCC does numerous algebraic simplifications, the following is a small sub-set + of these optimizations. +\layout Verse + +\family typewriter +i = j + 0;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + /* changed to: */\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + i = j; +\newline +i /= 2;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + /* changed to: */\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + i >>= 1; +\newline +i = j - j;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + /* changed to: */\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + i = 0; +\newline +i = j / 1;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + /* changed to: */\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + i = j; \layout Standard -Revision history of datasheet +Note the subexpressions +\begin_inset LatexCommand \index{Subexpression} + \end_inset - - -\begin_inset Text -\layout Standard + given above are generally introduced by macro expansions or as a result + of copy/constant propagation. +\layout Subsection + +'switch' Statements +\begin_inset LatexCommand \label{sub:'switch'-Statements} -vendor \end_inset - - - - -\begin_inset Text -\layout Standard -S. - S. - Muchnick +\begin_inset LatexCommand \index{switch statement} + \end_inset - - -\begin_inset Text + \layout Standard -Advanced Compiler Design and Implementation +SDCC can optimize switch statements to jump tables +\begin_inset LatexCommand \index{jump tables} + \end_inset - - -\begin_inset Text -\layout Standard +. + It makes the decision based on an estimate of the generated code size. + SDCC is quite liberal in the requirements for jump table generation: +\layout Itemize -bookstore (very dedicated, probably read other books first) -\end_inset - - - +The labels need not be in order, and the starting number need not be one + or zero, the case labels are in numerical sequence or not too many case + labels are missing. +\begin_deeper +\layout Verse -\end_inset +\family typewriter +switch(i) {\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +switch (i) { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 4: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 0: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 5: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 1: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 3: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ \newline - -\layout Section - -Some Questions +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 6: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 3: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 7: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 4: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 8: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 5: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 9: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 6: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 10: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 7: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 11: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 8: ... + +\newline +}\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +} \layout Standard -Some questions answered, some pointers given - it might be time to in turn - ask -\emph on -you -\emph default - some questions: -\layout Itemize - -can you solve your project with the selected microcontroller? Would you - find out early or rather late that your target is too small/slow/whatever? - Can you switch to a slightly better device if it doesn't fit? -\layout Itemize - -should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU - and/or another programming language be more adequate? Would an operating - system on the target device help? -\layout Itemize - -if you solved the problem, will the marketing department be happy? -\layout Itemize - -if the marketing department is happy, will customers be happy? +Both the above switch statements will be implemented using a jump-table. + The example to the right side is slightly more efficient as the check for + the lower boundary of the jump-table is not needed. +\end_deeper \layout Itemize -if you're the project manager, marketing department and maybe even the customer - in one person, have you tried to see the project from the outside? +The number of case labels is not larger than supported by the target architectur +e. \layout Itemize -is the project done if you think it is done? Or is just that other interface/pro -tocol/feature/configuration/option missing? How about website, manual(s), - internationali(z|s)ation, packaging, labels, 2nd source for components, - electromagnetic compatability/interference, documentation for production, - production test software, update mechanism, patent issues? +If the case labels are not in numerical sequence ('gaps' between cases) + SDCC checks whether a jump table with additionally inserted dummy cases + is still attractive. + \layout Itemize -is your project adequately positioned in that magic triangle: fame, fortune, - fun? -\layout Standard - -Maybe not all answers to these questions are known and some answers may - even be -\emph on -no -\emph default -, nevertheless knowing these questions may help you to avoid burnout -\begin_inset Foot -collapsed false - +If the starting number is not zero and a check for the lower boundary of + the jump-table can thus be eliminated SDCC might insert dummy cases 0, + ... + . \layout Standard -burnout is bad for electronic devices, programmers and motorcycle tyres -\end_inset - -. - Chances are you didn't want to hear some of them... -\layout Chapter - -Support -\begin_inset LatexCommand \index{Support} - -\end_inset - +Switch statements which have large gaps in the numeric sequence or those + that have too many case labels can be split into more than one switch statement + for efficient code generation, e.g.: +\layout Verse -\layout Standard -SDCC has grown to be a large project. - The compiler alone (without the preprocessor, assembler and linker) is - well over 100,000 lines of code (blank stripped). - The open source nature of this project is a key to its continued growth - and support. - You gain the benefit and support of many active software developers and - end users. - Is SDCC perfect? No, that's why we need your help. - The developers take pride in fixing reported bugs. - You can help by reporting the bugs and helping other SDCC users. - There are lots of ways to contribute, and we encourage you to take part - in making SDCC a great software package. +\family typewriter +switch (i) { +\newline +\SpecialChar ~ +\SpecialChar ~ +case 1: ... +\newline +\SpecialChar ~ +\SpecialChar ~ +case 2: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 3: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 4: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 5: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 6: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 7: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 101: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 102: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 103: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 104: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 105: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 106: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 107: ... + +\newline +} \layout Standard -The SDCC project is hosted on the SDCC sourceforge site at -\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc} - -\end_inset - -. - You'll find the complete set of mailing lists -\begin_inset LatexCommand \index{Mailing list(s)} - -\end_inset - -, forums, bug reporting system, patch submission -\begin_inset LatexCommand \index{Patch submission} - -\end_inset - - system, download -\begin_inset LatexCommand \index{download} - -\end_inset - - area and cvs code repository -\begin_inset LatexCommand \index{cvs code repository} - -\end_inset - - there. -\layout Section - -Reporting Bugs -\begin_inset LatexCommand \index{Bug reporting} - -\end_inset - - -\begin_inset LatexCommand \index{Reporting bugs} - -\end_inset - - -\layout Standard - -The recommended way of reporting bugs is using the infrastructure of the - sourceforge site. - You can follow the status of bug reports there and have an overview about - the known bugs. -\layout Standard - -Bug reports are automatically forwarded to the developer mailing list and - will be fixed ASAP. - When reporting a bug, it is very useful to include a small test program - (the smaller the better) which reproduces the problem. - If you can isolate the problem by looking at the generated assembly code, - this can be very helpful. - Compiling your program with the - -\begin_inset ERT -status Collapsed - -\layout Standard - -\backslash -/ -\end_inset - --dumpall -\begin_inset LatexCommand \index{-\/-dumpall} - -\end_inset +If the above switch statement is broken down into two switch statements +\layout Verse - option can sometimes be useful in locating optimization problems. - When reporting a bug please maker sure you: -\layout Enumerate -Attach the code you are compiling with SDCC. +\family typewriter +switch (i) { +\newline +\SpecialChar ~ +\SpecialChar ~ +case 1: ... -\layout Enumerate - -Specify the exact command you use to run SDCC, or attach your Makefile. +\newline +\SpecialChar ~ +\SpecialChar ~ +case 2: ... -\layout Enumerate - -Specify the SDCC version (type " -\family sans -\series bold -sdcc -v -\family default -\series default -"), your platform, and operating system. +\newline +\SpecialChar ~ +\SpecialChar ~ +case 3: ... -\layout Enumerate - -Provide an exact copy of any error message or incorrect output. +\newline +\SpecialChar ~ +\SpecialChar ~ +case 4: ... -\layout Enumerate - -Put something meaningful in the subject of your message. -\layout Standard - -Please attempt to include these 5 important parts, as applicable, in all - requests for support or when reporting any problems or bugs with SDCC. - Though this will make your message lengthy, it will greatly improve your - chance that SDCC users and developers will be able to help you. - Some SDCC developers are frustrated by bug reports without code provided - that they can use to reproduce and ultimately fix the problem, so please - be sure to provide sample code if you are reporting a bug! +\newline +\SpecialChar ~ +\SpecialChar ~ +case 5: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 6: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 7: ... + +\newline +} \layout Standard -Please have a short check that you are using a recent version of SDCC and - the bug is not yet known. - This is the link for reporting bugs: -\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599} - -\end_inset +and +\layout Verse -. -\layout Section -Requesting Features -\begin_inset LatexCommand \label{sub:Requesting-Features} +\family typewriter +switch (i) { +\newline +\SpecialChar ~ +\SpecialChar ~ +case 101: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 102: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 103: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 104: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 105: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 106: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 107: ... + +\newline +} +\layout Standard -\end_inset +then both the switch statements will be implemented using jump-tables whereas + the unmodified switch statement will not be. +\layout Comment +There might be reasons which SDCC cannot know about to either favour or + not favour jump tables. + If the target system has to be as quick for the last switch case as for + the first (pro jump table), or if the switch argument is known to be zero + in the majority of the cases (contra jump table). +\layout Standard -\begin_inset LatexCommand \index{Feature request} +The pragma nojtbound +\begin_inset LatexCommand \index{\#pragma nojtbound} \end_inset - -\begin_inset LatexCommand \index{Requesting features} + can be used to turn off checking the +\emph on +j +\emph default +ump +\emph on +t +\emph default +able +\emph on +bound +\emph default +aries. + It has no effect if a default label is supplied. + Use of this pragma is dangerous: if the switch +\begin_inset LatexCommand \index{switch statement} \end_inset + argument is not matched by a case statement the processor will happily + jump into Nirvana. +\layout Subsection -\layout Standard - -Like bug reports feature requests are forwarded to the developer mailing - list. - This is the link for requesting features: -\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599} +Bit-shifting Operations +\begin_inset LatexCommand \index{Bit shifting} \end_inset . -\layout Section - -Submitting patches \layout Standard -Like bug reports contributed patches are forwarded to the developer mailing - list. - This is the link for submitting patches -\begin_inset LatexCommand \index{Patch submission} - -\end_inset - -: -\begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599} - -\end_inset +Bit shifting is one of the most frequently used operation in embedded programmin +g. + SDCC tries to implement bit-shift operations in the most efficient way + possible, e.g.: +\layout Verse -. -\layout Standard -You need to specify some parameters to the \family typewriter -diff -\family default - command for the patches to be useful. - If you modified more than one file a patch created f.e. - with -\family sans -\series bold - -\begin_inset Quotes sld -\end_inset - -diff -Naur unmodified_directory modified_directory >my_changes.patch -\begin_inset Quotes srd -\end_inset - - -\family default -\series default - will be fine, otherwise -\family sans -\series bold - -\begin_inset Quotes sld -\end_inset - -diff -u sourcefile.c.orig sourcefile.c >my_changes.patch -\begin_inset Quotes srd -\end_inset - - -\series default +unsigned char i; +\newline +... -\family default -will do. -\layout Section - -Getting Help +\newline +i >>= 4; +\newline +... \layout Standard -These links should take you directly to the -\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599} +generates the following code: +\layout Verse -\end_inset +\family typewriter +mov\SpecialChar ~ + a,_i +\newline +swap a +\newline +anl\SpecialChar ~ + a,#0x0f +\newline +mov\SpecialChar ~ + _i,a +\layout Standard + +In general SDCC will never setup a loop if the shift count is known. + Another example: +\layout Verse -\begin_inset Foot -collapsed false +\family typewriter +unsigned int i; +\newline +... + +\newline +i >>= 9; +\newline +... \layout Standard -Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting - automated messages (mid 2003) -\end_inset +will generate: +\layout Verse - and the -\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599} -\end_inset +\family typewriter +mov\SpecialChar ~ +\SpecialChar ~ +a,(_i + 1) +\newline +mov\SpecialChar ~ +\SpecialChar ~ +(_i + 1),#0x00 +\newline +clr\SpecialChar ~ +\SpecialChar ~ +c +\newline +rrc\SpecialChar ~ +\SpecialChar ~ +a +\newline +mov\SpecialChar ~ +\SpecialChar ~ +_i,a +\layout Subsection -, lists -\begin_inset LatexCommand \index{Mailing list(s)} +Bit-rotation +\begin_inset LatexCommand \index{Bit rotation} \end_inset - and forums are archived and searchable so if you are lucky someone already - had a similar problem. - While mails to the lists themselves are delivered promptly their web front - end on sourceforge sometimes shows a severe time lag (up to several weeks), - if you're seriously using SDCC please consider subscribing to the lists. -\layout Section -ChangeLog \layout Standard -You can follow the status of the cvs version -\begin_inset LatexCommand \index{version} +A special case of the bit-shift operation is bit rotation +\begin_inset LatexCommand \index{rotating bits} \end_inset - of SDCC by watching the Changelog -\begin_inset LatexCommand \index{Changelog} +, SDCC recognizes the following expression to be a left bit-rotation: +\layout Verse -\end_inset - in the cvs-repository +\family typewriter +\series bold +unsigned +\series default +\SpecialChar ~ +\SpecialChar ~ +char i;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* unsigned is needed for rotation */ +\newline +... + +\newline +i = ((i << 1) | (i >> 7)); +\family default + \newline -\size footnotesize +\family typewriter +... +\layout Standard -\begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain} +will generate the following code: +\layout Verse -\end_inset -. -\layout Section +\family typewriter +mov\SpecialChar ~ +\SpecialChar ~ +a,_i +\newline +rl\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +a +\newline +mov\SpecialChar ~ +\SpecialChar ~ +_i,a +\layout Standard -Release policy -\begin_inset LatexCommand \index{Release policy} +SDCC uses pattern matching on the parse tree to determine this operation.Variatio +ns of this case will also be recognized as bit-rotation, i.e.: +\layout Verse -\end_inset +\family typewriter +i = ((i >> 7) | (i << 1)); /* left-bit rotation */ +\layout Subsection +Nibble and Byte Swapping \layout Standard -Historically there often were long delays between official releases and - the sourceforge download area tends to get not updated at all. - Excuses in the past might have referred to problems with live range analysis, - but as this was fixed a while ago, the current problem is that another - excuse has to be found. - Kidding aside, we have to get better there! On the other hand there are - daily snapshots available at -\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php} +Other special cases of the bit-shift operations are nibble or byte swapping +\begin_inset LatexCommand \index{swapping nibbles/bytes} \end_inset -, and you can always build the very last version (hopefully with many bugs - fixed, and features added) from the source code available at -\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source} - -\end_inset +, SDCC recognizes the following expressions: +\layout Verse -. -\layout Section -Examples -\begin_inset LatexCommand \index{Examples} +\family typewriter +\series bold +unsigned +\series default +\SpecialChar ~ +\SpecialChar ~ +char i; +\newline -\end_inset +\series bold +unsigned +\series default +\SpecialChar ~ +\SpecialChar ~ +int j; +\newline +... + +\newline +i = ((i << 4) | (i >> 4)); +\family default +\newline +\family typewriter +j = ((j << 8) | (j >> 8)); \layout Standard -You'll find some small examples in the directory -\emph on -sdcc/device/examples/. - -\emph default -More examples and libraries are available at -\emph on - The SDCC Open Knowledge Resource -\begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/} +and generates a swap instruction for the nibble swapping +\begin_inset LatexCommand \index{Nibble swapping} \end_inset - -\emph default -web site or at -\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/} + or move instructions for the byte swapping +\begin_inset LatexCommand \index{Byte swapping} \end_inset . -\layout Comment - -I did insert a reference to Paul's web site here although it seems rather - dedicated to a specific 8032 board (I think it's okay because it f.e. - shows LCD/Harddisc interface and has a free 8051 monitor. - Independent 8032 board vendors face hard competition of heavily subsidized - development boards anyway). -\layout Comment - -Maybe we should include some links to real world applications. - Preferably pointer to pointers (one for each architecture) so this stays - manageable here? -\layout Section - -Quality control -\begin_inset LatexCommand \index{Quality control} - + The +\begin_inset Quotes sld \end_inset - -\layout Standard - -The compiler is passed through nightly compile and build checks. - The so called -\shape italic -regression tests -\shape default - -\begin_inset LatexCommand \index{Regression test} - +j +\begin_inset Quotes srd \end_inset - check that SDCC itself compiles flawlessly on several platforms and checks - the quality of the code generated by SDCC by running the code through simulator -s. - There is a separate document -\shape italic -test_suite.pdf -\begin_inset LatexCommand \index{Test suite} - -\end_inset + example can be used to convert from little to big-endian or vice versa. + If you want to change the endianness of a +\emph on +signed +\emph default + integer you have to cast to +\family typewriter +(unsigned int) +\family default + first. +\layout Standard +Note that SDCC stores numbers in little-endian +\begin_inset Foot +collapsed false -\shape default - about this. \layout Standard -You'll find the test code in the directory -\shape italic -sdcc/support/regression -\shape default -. - You can run these tests manually by running -\family sans -make -\family default - in this directory (or f.e. - -\family sans -\series bold +Usually 8-bit processors don't care much about endianness. + This is not the case for the standard 8051 which only has an instruction + to increment its +\emph on +dptr +\emph default -\begin_inset Quotes sld -\end_inset +\begin_inset LatexCommand \index{DPTR} -make test-mcs51 -\begin_inset Quotes srd \end_inset - -\family default -\series default - if you don't want to run the complete tests). - The test code might also be interesting if you want to look for examples -\begin_inset LatexCommand \index{Examples} - +-datapointer +\emph on + +\emph default +so little-endian is the more efficient byte order. \end_inset - checking corner cases of SDCC or if you plan to submit patches -\begin_inset LatexCommand \index{Patch submission} -\end_inset +\begin_inset LatexCommand \index{little-endian} -. -\layout Standard +\end_inset -The pic port uses a different set of regression tests, you'll find them - in the directory -\shape italic -sdcc/src/regression -\shape default -. -\layout Chapter -\pagebreak_top -SDCC Technical Data -\layout Section -Optimizations -\begin_inset LatexCommand \index{Optimizations} +\begin_inset LatexCommand \index{Endianness} \end_inset + format (i.e. + lowest order first). +\layout Subsection -\layout Standard +Highest Order Bit +\begin_inset LatexCommand \index{Highest Order Bit} -SDCC performs a host of standard optimizations in addition to some MCU specific - optimizations. - -\layout Subsection +\end_inset -Sub-expression Elimination -\begin_inset LatexCommand \index{Subexpression elimination} + / Any Order Bit +\begin_inset LatexCommand \index{Any Order Bit} \end_inset \layout Standard -The compiler does local and -\emph on -g -\emph default -lobal -\emph on -c -\emph default -ommon -\emph on -s -\emph default -ubexpression -\emph on -e -\emph default -limination, e.g.: +It is frequently required to obtain the highest order bit of an integral + type (long, int, short or char types). + Also obtaining any other order bit is not uncommon. + SDCC recognizes the following expressions to yield the highest order bit + and generates optimized code for it, e.g.: \layout Verse \family typewriter -i = x + y + 1; +unsigned int gint; \newline -j = x + y; -\layout Standard - -will be translated to -\layout Verse - -\family typewriter -iTemp = x + y; \newline -i = iTemp + 1; +foo () { \newline -j = iTemp; -\layout Standard - -Some subexpressions are not as obvious as the above example, e.g.: -\layout Verse - - -\family typewriter -a->b[i].c = 10; +\SpecialChar ~ +\SpecialChar ~ +unsigned char hob1, aob1; \newline -a->b[i].d = 11; -\layout Standard - -In this case the address arithmetic a->b[i] will be computed only once; - the equivalent code in C would be. -\layout Verse - - -\family typewriter -iTemp = a->b[i]; +\SpecialChar ~ +\SpecialChar ~ +bit hob2, hob3, aob2, aob3; \newline -iTemp.c = 10; +\SpecialChar ~ +\SpecialChar ~ +... + \newline -iTemp.d = 11; +\SpecialChar ~ +\SpecialChar ~ +hob1 = (gint >> 15) & 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +hob2 = (gint >> 15) & 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +hob3 = gint & 0x8000; +\newline +\SpecialChar ~ +\SpecialChar ~ +aob1 = (gint >> 9) & 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +aob2 = (gint >> 8) & 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +aob3 = gint & 0x0800; +\newline +\SpecialChar ~ +\SpecialChar ~ +.. + +\newline +} \layout Standard -The compiler will try to keep these temporary variables in registers. -\layout Subsection - -Dead-Code Elimination -\begin_inset LatexCommand \index{Dead-code elimination} - -\end_inset - - +will generate the following code: \layout Verse \family typewriter -int global; +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 61 ;\SpecialChar ~ + hob.c 7 \newline - +000A E5*01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 62\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + a,(_gint + 1) \newline -void f () { +000C 23\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 63\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + rl\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + a \newline +000D 54 01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 64\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ \SpecialChar ~ + anl\SpecialChar ~ \SpecialChar ~ -int i; + a,#0x01 \newline +000F F5*02\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -i = 1; \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -/* dead store */ -\newline \SpecialChar ~ \SpecialChar ~ -global = 1;\SpecialChar ~ -/* dead store */ -\newline \SpecialChar ~ \SpecialChar ~ -global = 2; -\newline \SpecialChar ~ \SpecialChar ~ -return; -\newline \SpecialChar ~ \SpecialChar ~ -global = 3;\SpecialChar ~ -/* unreachable */ -\newline -} -\layout Standard - -will be changed to -\layout Verse - - -\family typewriter -int global; -\newline - -\newline -void f () { -\newline + 65\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -global = 2; -\newline -} -\layout Subsection - -Copy-Propagation -\begin_inset LatexCommand \index{Copy propagation} - -\end_inset - - -\layout Verse - - -\family typewriter -int f() { -\newline \SpecialChar ~ \SpecialChar ~ -int i, j; -\newline \SpecialChar ~ \SpecialChar ~ -i = 10; -\newline \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ -j = i; + _foo_hob1_1_1,a \newline \SpecialChar ~ \SpecialChar ~ -return j; -\newline -} -\layout Standard - -will be changed to -\layout Verse - - -\family typewriter -int f() { -\newline \SpecialChar ~ \SpecialChar ~ -int i, j; -\newline \SpecialChar ~ \SpecialChar ~ -i = 10; -\newline \SpecialChar ~ \SpecialChar ~ -j = 10; -\newline \SpecialChar ~ \SpecialChar ~ -return 10; -\newline -} -\layout Standard - -Note: the dead stores created by this copy propagation will be eliminated - by dead-code elimination. -\layout Subsection - -Loop Optimizations -\begin_inset LatexCommand \index{Loop optimization} - -\end_inset - - -\begin_inset LatexCommand \label{sub:Loop-Optimizations} - -\end_inset - - -\layout Standard - -Two types of loop optimizations are done by SDCC -\emph on -loop invariant -\emph default - lifting and -\emph on - strength reduction -\emph default - of loop induction variables. - In addition to the strength reduction the optimizer marks the induction - variables and the register allocator tries to keep the induction variables - in registers for the duration of the loop. - Because of this preference of the register allocator -\begin_inset LatexCommand \index{Register allocation} - -\end_inset - -, loop induction optimization causes an increase in register pressure, which - may cause unwanted spilling of other temporary variables into the stack -\begin_inset LatexCommand \index{stack} - -\end_inset - - / data space. - The compiler will generate a warning message when it is forced to allocate - extra space either on the stack or data space. - If this extra space allocation is undesirable then induction optimization - can be eliminated either for the entire source file (with - -\begin_inset ERT -status Collapsed - -\layout Standard - -\backslash -/ -\end_inset - --noinduction option) or for a given function only using #pragma\SpecialChar ~ -noinduction -\begin_inset LatexCommand \index{\#pragma noinduction} - -\end_inset - -. -\newline - -\newline -Loop Invariant: -\layout Verse - - -\family typewriter -for (i = 0 ; i < 100 ; i ++) -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -f += k + l; -\layout Standard - -changed to -\layout Verse - - -\family typewriter -itemp = k + l; -\newline -for (i = 0; i < 100; i++) -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -f += itemp; -\layout Standard - -As mentioned previously some loop invariants are not as apparent, all static - address computations are also moved out of the loop. -\newline - -\newline -Strength Reduction -\begin_inset LatexCommand \index{Strength reduction} - -\end_inset - -, this optimization substitutes an expression by a cheaper expression: -\layout Verse - - -\family typewriter -for (i=0;i < 100; i++) -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -ar[i*5] = i*3; -\layout Standard - -changed to -\layout Verse - - -\family typewriter -itemp1 = 0; -\newline -itemp2 = 0; -\newline -for (i=0;i< 100;i++) { +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 66 ;\SpecialChar ~ + hob.c 8 \newline +0011 E5*01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -ar[itemp1] = itemp2; -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -itemp1 += 5; -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -itemp2 += 3; -\newline -} -\layout Standard - -The more expensive multiplication -\begin_inset LatexCommand \index{Multiplication} - -\end_inset - - is changed to a less expensive addition. -\layout Subsection - -Loop Reversing -\begin_inset LatexCommand \index{Loop reversing} - -\end_inset - - -\layout Standard - -This optimization is done to reduce the overhead of checking loop boundaries - for every iteration. - Some simple loops can be reversed and implemented using a -\begin_inset Quotes eld -\end_inset - -decrement and jump if not zero -\begin_inset Quotes erd -\end_inset - - instruction. - SDCC checks for the following criterion to determine if a loop is reversible - (note: more sophisticated compilers use data-dependency analysis to make - this determination, SDCC uses a more simple minded analysis). -\layout Itemize - -The 'for' loop is of the form -\newline - -\newline - -\family typewriter -for( = ; [< | <=] ; [++ | - += 1]) +\SpecialChar ~ +\SpecialChar ~ + 67\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + a,(_gint + 1) \newline +0013 33\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - -\layout Itemize - -The does not contain -\begin_inset Quotes eld -\end_inset - -continue -\begin_inset Quotes erd -\end_inset - - or 'break -\begin_inset Quotes erd -\end_inset - -. -\layout Itemize - -All goto's are contained within the loop. -\layout Itemize - -No function calls within the loop. -\layout Itemize - -The loop control variable is not assigned any value within the loop -\layout Itemize - -The loop control variable does NOT participate in any arithmetic operation - within the loop. -\layout Itemize - -There are NO switch statements in the loop. -\layout Subsection - -Algebraic Simplifications -\layout Standard - -SDCC does numerous algebraic simplifications, the following is a small sub-set - of these optimizations. -\layout Verse - - -\family typewriter -i = j + 0;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - /* changed to: */\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - i = j; -\newline -i /= 2;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - /* changed to: */\SpecialChar ~ \SpecialChar ~ + 68\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - i >>= 1; -\newline -i = j - j;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - /* changed to: */\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + rlc\SpecialChar ~ \SpecialChar ~ - i = 0; + a \newline -i = j / 1;\SpecialChar ~ +0014 92*00\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - /* changed to: */\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - i = j; -\layout Standard - -Note the subexpressions -\begin_inset LatexCommand \index{Subexpression} - -\end_inset - - given above are generally introduced by macro expansions or as a result - of copy/constant propagation. -\layout Subsection - -'switch' Statements -\begin_inset LatexCommand \label{sub:'switch'-Statements} - -\end_inset - - -\begin_inset LatexCommand \index{switch statement} - -\end_inset - - -\layout Standard - -SDCC can optimize switch statements to jump tables -\begin_inset LatexCommand \index{jump tables} - -\end_inset - -. - It makes the decision based on an estimate of the generated code size. - SDCC is quite liberal in the requirements for jump table generation: -\layout Itemize - -The labels need not be in order, and the starting number need not be one - or zero, the case labels are in numerical sequence or not too many case - labels are missing. -\begin_deeper -\layout Verse - - -\family typewriter -switch(i) {\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23376,6 +26492,7 @@ switch(i) {\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 69\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23383,7 +26500,10 @@ switch(i) {\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + _foo_hob2_1_1,c +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23393,12 +26513,9 @@ switch(i) {\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -switch (i) { -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 4: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23412,6 +26529,10 @@ case 4: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 66 ;\SpecialChar ~ + hob.c 9 +\newline +0016 E5*01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23424,20 +26545,21 @@ case 4: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 0: ... - -\newline \SpecialChar ~ \SpecialChar ~ + 67\SpecialChar ~ \SpecialChar ~ -case 5: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + a,(_gint + 1) +\newline +0018 33\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23455,18 +26577,19 @@ case 5: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 68\SpecialChar ~ \SpecialChar ~ -case 1: ... - -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 3: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + rlc\SpecialChar ~ \SpecialChar ~ + a +\newline +0019 92*01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23481,6 +26604,7 @@ case 3: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 69\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23488,12 +26612,13 @@ case 3: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - + mov\SpecialChar ~ +\SpecialChar ~ + _foo_hob3_1_1,c \newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 6: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23516,16 +26641,16 @@ case 6: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 70 ;\SpecialChar ~ + hob.c 10 +\newline +001B E5*01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 3: ... - -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 7: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23534,6 +26659,7 @@ case 7: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 71\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23541,7 +26667,11 @@ case 7: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + a,(_gint + 1) +\newline +001D 03\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23551,18 +26681,15 @@ case 7: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 4: ... - -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 8: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 72\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23570,8 +26697,12 @@ case 8: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + rr\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + a +\newline +001E 54 01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23583,13 +26714,10 @@ case 8: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 5: ... - -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 9: ...\SpecialChar ~ + 73\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23597,7 +26725,11 @@ case 9: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + anl\SpecialChar ~ \SpecialChar ~ + a,#0x01 +\newline +0020 F5*03\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23612,18 +26744,18 @@ case 9: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 74\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 6: ... - -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 10: ...\SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + _foo_aob1_1_1,a +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23646,13 +26778,13 @@ case 10: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 7: ... - -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 11: ...\SpecialChar ~ + 75 ;\SpecialChar ~ + hob.c 11 +\newline +0022 E5*01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23667,6 +26799,7 @@ case 11: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 76\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23674,13 +26807,13 @@ case 11: ...\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + a,(_gint + 1) +\newline +0024 13\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 8: ... - -\newline -}\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23696,6 +26829,7 @@ case 8: ... \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 77\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23703,7 +26837,11 @@ case 8: ... \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + rrc\SpecialChar ~ \SpecialChar ~ + a +\newline +0025 92*02\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -23716,537 +26854,185 @@ case 8: ... \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -} -\layout Standard - -Both the above switch statements will be implemented using a jump-table. - The example to the right side is slightly more efficient as the check for - the lower boundary of the jump-table is not needed. -\end_deeper -\layout Itemize - -The number of case labels is not larger than supported by the target architectur -e. -\layout Itemize - -If the case labels are not in numerical sequence ('gaps' between cases) - SDCC checks whether a jump table with additionally inserted dummy cases - is still attractive. - -\layout Itemize - -If the starting number is not zero and a check for the lower boundary of - the jump-table can thus be eliminated SDCC might insert dummy cases 0, - ... - . -\layout Standard - -Switch statements which have large gaps in the numeric sequence or those - that have too many case labels can be split into more than one switch statement - for efficient code generation, e.g.: -\layout Verse - - -\family typewriter -switch (i) { -\newline \SpecialChar ~ \SpecialChar ~ -case 1: ... - -\newline + 78\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 2: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 3: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 4: ... - -\newline \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ -case 5: ... - + _foo_aob2_1_1,c \newline \SpecialChar ~ \SpecialChar ~ -case 6: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 7: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 101: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 102: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 103: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 104: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 105: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 106: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 107: ... - -\newline -} -\layout Standard - -If the above switch statement is broken down into two switch statements -\layout Verse - - -\family typewriter -switch (i) { -\newline \SpecialChar ~ \SpecialChar ~ -case 1: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 2: ... - +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 79 ;\SpecialChar ~ + hob.c 12 \newline +0027 E5*01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 3: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 4: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 5: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 6: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 7: ... - -\newline -} -\layout Standard - -and -\layout Verse - - -\family typewriter -switch (i) { -\newline \SpecialChar ~ \SpecialChar ~ -case 101: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 102: ... - -\newline + 80\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 103: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 104: ... - -\newline \SpecialChar ~ \SpecialChar ~ -case 105: ... - -\newline \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ -case 106: ... - + a,(_gint + 1) \newline +0029 A2 E3\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -case 107: ... - -\newline -} -\layout Standard - -then both the switch statements will be implemented using jump-tables whereas - the unmodified switch statement will not be. -\layout Comment - -There might be reasons which SDCC cannot know about to either favour or - not favour jump tables. - If the target system has to be as quick for the last switch case as for - the first (pro jump table), or if the switch argument is known to be zero - in the majority of the cases (contra jump table). -\layout Standard - -The pragma nojtbound -\begin_inset LatexCommand \index{\#pragma nojtbound} - -\end_inset - - can be used to turn off checking the -\emph on -j -\emph default -ump -\emph on -t -\emph default -able -\emph on -bound -\emph default -aries. - It has no effect if a default label is supplied. - Use of this pragma is dangerous: if the switch -\begin_inset LatexCommand \index{switch statement} - -\end_inset - - argument is not matched by a case statement the processor will happily - jump into Nirvana. -\layout Subsection - -Bit-shifting Operations -\begin_inset LatexCommand \index{Bit shifting} - -\end_inset - -. -\layout Standard - -Bit shifting is one of the most frequently used operation in embedded programmin -g. - SDCC tries to implement bit-shift operations in the most efficient way - possible, e.g.: -\layout Verse - - -\family typewriter -unsigned char i; -\newline -... - -\newline -i >>= 4; -\newline -... -\layout Standard - -generates the following code: -\layout Verse - - -\family typewriter -mov\SpecialChar ~ - a,_i -\newline -swap a -\newline -anl\SpecialChar ~ - a,#0x0f -\newline -mov\SpecialChar ~ - _i,a -\layout Standard - -In general SDCC will never setup a loop if the shift count is known. - Another example: -\layout Verse - - -\family typewriter -unsigned int i; -\newline -... - -\newline -i >>= 9; -\newline -... -\layout Standard - -will generate: -\layout Verse - - -\family typewriter -mov\SpecialChar ~ \SpecialChar ~ -a,(_i + 1) -\newline -mov\SpecialChar ~ \SpecialChar ~ -(_i + 1),#0x00 -\newline -clr\SpecialChar ~ \SpecialChar ~ -c -\newline -rrc\SpecialChar ~ \SpecialChar ~ -a -\newline -mov\SpecialChar ~ \SpecialChar ~ -_i,a -\layout Subsection - -Bit-rotation -\begin_inset LatexCommand \index{Bit rotation} - -\end_inset - - -\layout Standard - -A special case of the bit-shift operation is bit rotation -\begin_inset LatexCommand \index{rotating bits} - -\end_inset - -, SDCC recognizes the following expression to be a left bit-rotation: -\layout Verse - - -\family typewriter -\series bold -unsigned -\series default \SpecialChar ~ \SpecialChar ~ -char i;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 81\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -/* unsigned is needed for rotation */ -\newline -... - -\newline -i = ((i << 1) | (i >> 7)); -\family default - -\newline - -\family typewriter -... -\layout Standard - -will generate the following code: -\layout Verse - - -\family typewriter -mov\SpecialChar ~ \SpecialChar ~ -a,_i -\newline -rl\SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ -a + c,acc[3] \newline -mov\SpecialChar ~ +002B 92*03\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ \SpecialChar ~ -_i,a -\layout Standard - -SDCC uses pattern matching on the parse tree to determine this operation.Variatio -ns of this case will also be recognized as bit-rotation, i.e.: -\layout Verse - - -\family typewriter -i = ((i >> 7) | (i << 1)); /* left-bit rotation */ -\layout Subsection - -Nibble and Byte Swapping -\layout Standard - -Other special cases of the bit-shift operations are nibble or byte swapping -\begin_inset LatexCommand \index{swapping nibbles/bytes} - -\end_inset - -, SDCC recognizes the following expressions: -\layout Verse - - -\family typewriter -\series bold -unsigned -\series default \SpecialChar ~ \SpecialChar ~ -char i; -\newline - -\series bold -unsigned -\series default \SpecialChar ~ \SpecialChar ~ -int j; -\newline -... - -\newline -i = ((i << 4) | (i >> 4)); -\family default - -\newline - -\family typewriter -j = ((j << 8) | (j >> 8)); +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 82\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_aob3_1_1,c \layout Standard -and generates a swap instruction for the nibble swapping -\begin_inset LatexCommand \index{Nibble swapping} - -\end_inset - - or move instructions for the byte swapping -\begin_inset LatexCommand \index{Byte swapping} - -\end_inset - -. - The -\begin_inset Quotes sld -\end_inset - -j -\begin_inset Quotes srd -\end_inset - - example can be used to convert from little to big-endian or vice versa. - If you want to change the endianness of a +Other variations of these cases however will \emph on -signed +not \emph default - integer you have to cast to -\family typewriter -(unsigned int) -\family default - first. -\layout Standard + be recognized. + They are standard C expressions, so I heartily recommend these be the only + way to get the highest order bit, (it is portable). + Of course it will be recognized even if it is embedded in other expressions, + e.g.: +\layout Verse -Note that SDCC stores numbers in little-endian -\begin_inset Foot -collapsed false +\family typewriter +xyz = gint + ((gint >> 15) & 1); \layout Standard -Usually 8-bit processors don't care much about endianness. - This is not the case for the standard 8051 which only has an instruction - to increment its -\emph on -dptr -\emph default - -\begin_inset LatexCommand \index{DPTR} - -\end_inset - --datapointer -\emph on - -\emph default -so little-endian is the more efficient byte order. -\end_inset - - -\begin_inset LatexCommand \index{little-endian} - -\end_inset - +will still be recognized. +\layout Subsection -\begin_inset LatexCommand \index{Endianness} +Higher Order Byte +\begin_inset LatexCommand \index{Higher Order Byte} \end_inset - format (i.e. - lowest order first). -\layout Subsection - -Highest Order Bit -\begin_inset LatexCommand \index{Highest Order Bit} + / Higher Order Word +\begin_inset LatexCommand \index{Higher Order Word} \end_inset \layout Standard -It is frequently required to obtain the highest order bit of an integral - type (long, int, short or char types). - SDCC recognizes the following expression to yield the highest order bit - and generates optimized code for it, e.g.: +It is also frequently required to obtain a higher order byte or word of + a larger integral type (long, int or short types). + SDCC recognizes the following expressions to yield the higher order byte + or word and generates optimized code for it, e.g.: \layout Verse \family typewriter unsigned int gint; \newline +unsigned long int glong; +\newline \newline foo () { \newline \SpecialChar ~ \SpecialChar ~ -unsigned char hob; +unsigned char hob1, hob2; +\newline +\SpecialChar ~ +\SpecialChar ~ +unsigned int how1, how2; \newline \SpecialChar ~ \SpecialChar ~ @@ -24255,7 +27041,19 @@ unsigned char hob; \newline \SpecialChar ~ \SpecialChar ~ -hob = (gint >> 15) & 1; +hob1 = (gint >> 8) & 0xFF; +\newline +\SpecialChar ~ +\SpecialChar ~ +hob2 = glong >> 24; +\newline +\SpecialChar ~ +\SpecialChar ~ +how1 = (glong >> 16) & 0xFFFF; +\newline +\SpecialChar ~ +\SpecialChar ~ +how2 = glong >> 8; \newline \SpecialChar ~ \SpecialChar ~ @@ -24295,10 +27093,10 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 61 ;\SpecialChar ~ - hob.c 7 + 91 ;\SpecialChar ~ + hob.c 15 \newline -000A E5*01\SpecialChar ~ +0037 85*01*06\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -24310,22 +27108,47 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 92\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 62\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + _foo_hob1_1_1,(_gint + 1) +\newline \SpecialChar ~ \SpecialChar ~ - mov\SpecialChar ~ \SpecialChar ~ - a,(_gint + 1) +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 93 ;\SpecialChar ~ + hob.c 16 \newline -000C 23\SpecialChar ~ +003A 85*05*07\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -24337,26 +27160,47 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 94\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 63\SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + _foo_hob2_1_1,(_glong + 3) +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - rl\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - a +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 95 ;\SpecialChar ~ + hob.c 17 \newline -000D 54 01\SpecialChar ~ +003D 85*04*08\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -24368,22 +27212,43 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 96\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 64\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + _foo_how1_1_1,(_glong + 2) +\newline +0040 85*05*09\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - anl\SpecialChar ~ \SpecialChar ~ - a,#0x01 +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 97\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + (_foo_how1_1_1 + 1),(_glong + 3) \newline -000F F5*02\SpecialChar ~ +0043 85*03*0A\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -24394,11 +27259,32 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +\SpecialChar ~ + 98\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_how2_1_1,(_glong + 1) +\newline +0046 85*04*0B\SpecialChar ~ +\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 65\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 99\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -24408,23 +27294,23 @@ will generate the following code: \SpecialChar ~ mov\SpecialChar ~ \SpecialChar ~ - _foo_hob_1_1,a + (_foo_how2_1_1 + 1),(_glong + 2) \layout Standard -Variations of this case however will +Again, variations of these cases may \emph on not \emph default be recognized. - It is a standard C expression, so I heartily recommend this be the only - way to get the highest order bit, (it is portable). + They are standard C expressions, so I heartily recommend these be the only + way to get the higher order byte/word, (it is portable). Of course it will be recognized even if it is embedded in other expressions, e.g.: \layout Verse \family typewriter -xyz = gint + ((gint >> 15) & 1); +xyz = gint + ((gint >> 8) & 0xFF); \layout Standard will still be recognized. @@ -24842,6 +27728,20 @@ ANSI-Compliance \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: @@ -24941,6 +27841,18 @@ return rets;/* is invalid in SDCC although allowed in ANSI */ \end_deeper \layout Itemize +initialization of structure arrays must be fully braced. +\begin_deeper +\layout Verse + + +\family typewriter +struct s { char x } a[] = {1, 2}; /* invalid in SDCC */ +\newline +struct s { char x } a[] = {{1}, {2}}; /* OK */ +\end_deeper +\layout Itemize + 'long long \begin_inset LatexCommand \index{long long (not supported)} @@ -24967,19 +27879,6 @@ return rets;/* is invalid in SDCC although allowed in ANSI */ not supported. \layout Itemize -No support for setjmp -\begin_inset LatexCommand \index{setjmp (not supported)} - -\end_inset - - and longjmp -\begin_inset LatexCommand \index{longjmp (not supported)} - -\end_inset - - (for now). -\layout Itemize - Old K&R style \begin_inset LatexCommand \index{K\&R style} @@ -25008,6 +27907,26 @@ int i,j; /* are valid in ANSI but not valid in SDCC */ \end_deeper \layout Itemize +Most enhancements in C99 are not supported, f.e.: +\begin_deeper +\layout Verse + + +\family typewriter +\series bold +inline +\series default + int increment (int a) { return a+1; } /* is invalid in SDCC although allowed + in C99 */ +\newline +for ( +\series bold +int +\series default + i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */ +\end_deeper +\layout Itemize + Certain words that are valid identifiers in the standard may be reserved words in SDCC unless the \series bold