X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fsdccman.lyx;h=d74af8026033a626ba71e3e63b5e1dfa897aec0d;hb=41ff3b55f586efb58903dd992714556f7ab07151;hp=81f1d5117ecaf035db5f444a037081b975ea78bf;hpb=154fe0924783c2d24349b85e7f539c00d5681448;p=fw%2Fsdcc diff --git a/doc/sdccman.lyx b/doc/sdccman.lyx index 81f1d511..d74af802 100644 --- a/doc/sdccman.lyx +++ b/doc/sdccman.lyx @@ -1,796 +1,566 @@ -#LyX 1.2 created this file. For more info see http://www.lyx.org/ -\lyxformat 220 -\textclass article +#LyX 1.4.1 created this file. For more info see http://www.lyx.org/ +\lyxformat 221 +\textclass book +\begin_preamble +\pdfoptionpdfminorversion=3 +\usepackage[ + pdftitle={SDCC Compiler User Guide}, + pdfauthor={SDCC development team}, + pdfsubject={installation, user manual}, + pdfkeywords={68hc08 8032 8051 ansi c compiler assembler CPU DS390 embedded development free Floating Point Arithmetic Freescale GPL HC08 inline Intel ISO/IEC 9899:1990 Linux MAC OS X manual Maxim mcs51 Microchip microcontroller open source PIC Unix Windows Z80 Zilog}, + pdfpagemode=UseOutlines, + colorlinks=true, + linkcolor=blue] {hyperref} +% +\sloppy +\tolerance=500 +\emergencystretch=30pt +% +\date{} +\end_preamble \language english \inputencoding default \fontscheme pslatex \graphics default \paperfontsize default -\spacing single -\papersize Default -\paperpackage a4 -\use_geometry 0 +\spacing single +\papersize letterpaper +\use_geometry 1 \use_amsmath 0 \use_natbib 0 \use_numerical_citations 0 \paperorientation portrait +\leftmargin 30mm +\topmargin 20mm +\rightmargin 25mm +\bottommargin 20mm \secnumdepth 3 \tocdepth 3 \paragraph_separation indent \defskip medskip \quotes_language swedish -\quotes_times 2 \papercolumns 1 \papersides 1 \paperpagestyle fancy -\layout Title +\layout Standard +\begin_inset Note +collapsed true + +\layout Standard +Please note: double dashed longoptions (e.g. + --version) are written this way: - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +- + +\layout Standard +Two resp. + three consecutive dashes simply result in a long resp. + extra long dash. + +\layout Standard +Architecture specific stuff (like memory models, code examples) should maybe + later go +\layout Standard +into seperate sections/chapters/appendices (it is hard to document PIC or + Z80 in + +\layout Standard +a 8051 centered document) - for now simply add. + +\end_inset + + + +\layout Title SDCC Compiler User Guide + +\layout Date + +\size normal +SDCC 2.6.4 +\size footnotesize + +\newline +$Date:: $ +\newline +$Revision$ + \layout Standard +\begin_inset Note +collapsed true + +\layout Standard +The above strings enclosed in $ are automatically updated by Subversion + +\end_inset + +\layout Standard \begin_inset LatexCommand \tableofcontents{} -\end_inset +\end_inset -\layout Section +\layout Chapter Introduction -\layout Subsection +\layout Section About SDCC -\layout Standard +\layout Standard -\series bold +\series bold SDCC -\series default - is a Freeware, retargettable, optimizing ANSI-C compiler by -\series bold +\series default + ( +\emph on +S +\emph default +mall +\emph on +D +\emph default +evice +\emph on +C +\emph default + +\emph on +C +\emph default +ompiler) is an open source, retargettable, optimizing ANSI-C compiler by + +\series bold Sandeep Dutta -\series default +\series default designed for 8 bit Microprocessors. - The current version targets Intel MCS51 based Microprocessors(8051,8052, - etc), Zilog Z80 based MCUs, and the Dallas DS80C390 variant. - It can be retargetted for other microprocessors, support for PIC, AVR and - 186 is under development. + The current version targets Intel MCS51 based Microprocessors (8031, 8032, + 8051, 8052 +\begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU} + +\end_inset + +, etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and + Zilog Z80 based MCUs. + It can be retargeted for other microprocessors, support for Microchip PIC, + Atmel AVR is under development. The entire source code for the compiler is distributed under GPL. - SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker. + SDCC uses ASXXXX +\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)} + +\end_inset + + & ASLINK +\begin_inset LatexCommand \index{aslink} + +\end_inset + +, an open source retargetable assembler & linker. SDCC has extensive language extensions suitable for utilizing various microcont rollers and underlying hardware effectively. -\newline +\newline -\newline -In addition to the MCU specific optimizations SDCC also does a host of standard - optimizations like: -\layout Itemize +\newline +In addition to the MCU specific optimizations SDCC also does a host of + standard optimizations like: -global sub expression elimination, \layout Itemize +global sub expression elimination, +\layout Itemize loop optimizations (loop invariant, strength reduction of induction variables and loop reversing), -\layout Itemize -constant folding & propagation, \layout Itemize +constant folding & propagation, -copy propagation, \layout Itemize +copy propagation, -dead code elimination \layout Itemize +dead code elimination -jumptables for -\emph on +\layout Itemize +jump tables for +\emph on switch -\emph default +\emph default statements. -\layout Standard +\layout Standard For the back-end SDCC uses a global register allocation scheme which should be well suited for other 8 bit MCUs. -\newline +\newline -\newline -The peep hole optimizer uses a rule based substitution mechanism which is - MCU independent. +\newline +The peep hole optimizer uses a rule based substitution mechanism which + is MCU independent. -\newline +\newline -\newline +\newline Supported data-types are: -\layout Itemize -char (8 bits, 1 byte), -\layout Itemize +\layout Standard +\begin_inset Tabular + + + + + + + + + +\begin_inset Text -short and int (16 bits, 2 bytes), -\layout Itemize +\layout Standard +type -long (32 bit, 4 bytes) -\layout Itemize +\end_inset + + +\begin_inset Text -float (4 byte IEEE). - \layout Standard +width -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 +\end_inset + + +\begin_inset Text -\newline -SDCC also provides an option (--cyclomatic) to report the relative complexity - of a function. - These functions can then be further optimized, or hand coded in assembly - if needed. - -\newline +\layout Standard +default -\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 +\end_inset + + +\begin_inset Text -\newline -The latest version can be downloaded from -\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/} +\layout Standard +signed range -\end_inset +\end_inset + + +\begin_inset Text +\layout Standard +unsigned range -\series bold -. -\layout Subsection +\end_inset + + + + +\begin_inset Text -Open Source \layout Standard +bool -All packages used in this compiler system are -\emph on -opensource -\emph default - and -\emph on -freeware -\emph default -; source code for all the sub-packages (pre-processor, assemblers, linkers - etc) is distributed with the package. - This documentation is maintained using a freeware word processor (LyX). -\newline -This program is free software; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by the Free - Software Foundation; either version 2, or (at your option) any later version. - This program is distributed in the hope that it will be useful, but WITHOUT - ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS - FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, 59 Temple - Place - Suite 330, Boston, MA 02111-1307, USA. - In other words, you are welcome to use, share and improve this program. - You are forbidden to forbid anyone else to use, share and improve what - you give them. - Help stamp out software-hoarding! -\layout Subsection +\end_inset + + +\begin_inset Text -Typographic conventions \layout Standard +1 bit -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 -. +\end_inset + + +\begin_inset Text -\family default - Code samples are printed in -\family typewriter -typewriter font. +\layout Standard +unsigned -\family default - Interesting items and new terms are printed in -\emph on -italic. -\layout Subsection +\end_inset + + +\begin_inset Text -Compatibility with previous versions \layout Standard +- -This version has numerous bug fixes compared with the previous version. - But we also introduced some incompatibilities with older versions. - Not just for the fun of it, but to make the compiler more stable, efficient - and ANSI compliant. - -\newline +\end_inset + + +\begin_inset Text -\layout Itemize +\layout Standard +0, 1 -short is now equivalent to int (16 bits), it used to be equivalent to char - (8 bits) which is not ANSI compliant -\layout Itemize +\end_inset + + + + +\begin_inset Text -the default directory where include, library and documention files are stored - is now in /usr/local/share -\layout Itemize +\layout Standard +char -char type parameters to vararg functions are casted to int unless explicitly - casted, e.g.: -\newline +\end_inset + + +\begin_inset Text -\family typewriter -\SpecialChar ~ -\SpecialChar ~ -char a=3; -\newline -\SpecialChar ~ -\SpecialChar ~ -printf ("%d %c -\backslash -n", a, (char)a); -\family default +\layout Standard +8 bits, 1 byte -\newline - will push a as an int and as a char resp. -\layout Itemize +\end_inset + + +\begin_inset Text -option --regextend has been removed -\layout Itemize +\layout Standard +signed -option --noregparms has been removed -\layout Itemize +\end_inset + + +\begin_inset Text -option --stack-after-data has been removed \layout Standard +-128, +127 +\end_inset + + +\begin_inset Text -\emph on - -\layout Subsection - -System Requirements \layout Standard +0, +255 -What do you need before you start installation of SDCC? A computer, and - a desire to compute. - The preferred method of installation is to compile SDCC from source using - GNU gcc and make. - For Windows some pre-compiled binary distributions are available for your - convenience. - You should have some experience with command line tools and compiler use. -\layout Subsection +\end_inset + + + + +\begin_inset Text -Other Resources \layout Standard +short -The SDCC home page at -\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/} +\end_inset + + +\begin_inset Text -\end_inset +\layout Standard +16 bits, 2 bytes - is a great place to find distribution sets. - You can also find links to the user mailing lists that offer help or discuss - SDCC with other SDCC users. - Web links to other SDCC related sites can also be found here. - This document can be found in the DOC directory of the source package as - a text or HTML file. - Some of the other tools (simulator and assembler) included with SDCC contain - their own documentation and can be found in the source distribution. - If you want the latest unreleased software, the complete source package - is available directly by anonymous CVS on cvs.sdcc.sourceforge.net. -\layout Subsection +\end_inset + + +\begin_inset Text -Wishes for the future \layout Standard +signed -There are (and always will be) some things that could be done. - Here are some I can think of: -\newline +\end_inset + + +\begin_inset Text \layout Standard +-32.768, +32.767 +\end_inset + + +\begin_inset Text -\family typewriter -char KernelFunction3(char p) at 0x340; -\newline +\layout Standard +0, +65.535 -\newline +\end_inset + + + + +\begin_inset Text -\family default -If you can think of some more, please send them to the list. -\newline +\layout Standard +int -\newline +\end_inset + + +\begin_inset Text -\emph on - + +\begin_inset Text -> -\layout Section +\layout Standard +signed -Installation -\layout Subsection +\end_inset + + +\begin_inset Text -Linux/Unix Installation -\layout Enumerate +\layout Standard +-32.768, +32.767 +\end_inset + + +\begin_inset Text -\series medium -Download the source package, it will be named something like sdcc- -\series default -x -\series medium -.x.x.tgz. -\layout Enumerate - - -\series medium -Bring up a command line terminal, such as xterm. -\layout Enumerate - - -\series medium -Unpack the file using a command like: -\family sans -\series bold -"tar -xzf sdcc-x.x.x.tgz -\family default -\series default -" -\series medium -, this will create a sub-directory called sdcc with all of the sources. -\layout Enumerate - -Change directory into the main SDCC directory, for example type: -\family sans -\series bold -"cd sdcc -\series default -". -\layout Enumerate - - -\series medium -Type -\family sans -\series bold -"./configure -\family default -\series default -". - This configures the package for compilation on your system. -\layout Enumerate - - -\series medium -Type -\family sans -\series bold -"make -\family default -\series default -" -\series medium -. - -\series default - All of the source packages will compile, this can take a while. -\layout Enumerate - - -\series medium -Type -\family sans -\series bold -"make install" -\family default -\series default - as root -\series medium -. - -\series default - This copies the binary executables, the include files, the libraries and - the documentation to the install directories. -\layout Subsection - -Windows Installation \layout Standard +0, +65.535 +\end_inset + + + + +\begin_inset Text -\emph on - -\newline - -\layout Subsubsection - -Windows Install Using a Binary Package -\layout Enumerate - -Download the binary package and unpack it using your favorite unpacking - tool (gunzip, WinZip, etc). - This should unpack to a group of sub-directories. - An example directory structure after unpacking is: c: -\backslash -usr -\backslash -local -\backslash -bin for the executables, c: -\backslash -usr -\backslash -local -\backslash -share -\backslash -sdcc -\backslash -include and c: -\backslash -usr -\backslash -local -\backslash -share -\backslash -sdcc -\backslash -lib for the include and libraries. -\layout Enumerate - -Adjust your environment PATH to include the location of the bin directory. - For example, make a setsdcc.bat file with the following: set PATH=c: -\backslash -usr -\backslash -local -\backslash -bin;%PATH% -\layout Enumerate - -When you compile with sdcc, you may need to specify the location of the - lib and include folders. - For example, sdcc test.c -I c: -\backslash -usr -\backslash -local -\backslash -share -\backslash -sdcc -\backslash -include -L c: -\backslash -usr -\backslash -local -\backslash -share -\backslash -sdcc -\backslash -lib -\backslash -small -\layout Subsubsection - -Windows Install Using Cygwin -\layout Enumerate - - -\series medium -Download and install the cygwin package from the redhat site -\series default - -\begin_inset LatexCommand \htmlurl{http://sources.redhat.com/cygwin/} - -\end_inset - - -\series medium -. - Currently, this involved downloading a small install program which then - automates downloading and installing -\series default -selected parts of -\series medium - the package -\series default - (a large 80M byte sized dowload for the whole thing) -\series medium -. - -\series default - -\layout Enumerate - - -\series medium -Bring up a -\series default -Unix/Bash -\series medium -command line terminal from the Cygwin menu. -\layout Enumerate - - -\series medium -Follow the instructions in the preceding Linux/Unix installation section -\layout Subsubsection - -Windows Install Using Microsoft Visual C++ 6.0/NET \layout Standard +long -(By Jesus Calvino-Fraga (jesus@ieee.org) Jan/31/2003, many thanks to "Borut - Razem" for fixing all the sources, projects, and workspace - so to build SDCC with Visual C++). -\newline - -\newline -SDCC is distributed with all the projects, workspaces, and files you need - to build it using Visual C++ 6.0/NET. - The workspace name is 'sdcc.dsw'. - Please note that as it is now, all the executables are created in a folder - called sdcc -\backslash -bin_vc. - Once built you need to copy the executables from sdcc -\backslash -bin_vc to sdcc -\backslash -bin before runnng SDCC. - -\newline - -\newline -In order to build SDCC with Visual C++ 6.0/NET you need win32 executables - of bison.exe, flex.exe, and gawk.exe. - One good place to get them is -\begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net} - -\end_inset - - -\newline - -\newline -Download the file UnxUtils.zip. - Now you have to install the utilities and setup Visual C++ so it can locate - the required programs. - Here there are two alternatives (choose one!): -\layout Enumerate - -The easy way: -\newline - -\newline -a) Extract UnxUtils.zip to your C: -\backslash - hard disk PRESERVING the original paths, otherwise bison won't work. - (If you are using WinZip make certain that 'Use folder names' is selected) -\newline - -\newline -b) In the Visual C++ IDE click Tools, Options, select the Directory tab, - in 'Show directories for:' select 'Executable files', and in the directories - window add a new path: 'C: -\backslash -user -\backslash -local -\backslash -wbin', click ok. -\newline - -\newline -(As a side effect, you get a bunch of Unix utilities that could be useful, - such as diff and patch.) -\layout Enumerate - -A more compact way: -\newline +\end_inset + + +\begin_inset Text -\newline -This one avoids extracting a bunch of files you may not use, but requires - some extra work: -\newline +\layout Standard +32 bits, 4 bytes -\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 + + +\begin_inset Text -\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 +\layout Standard +signed -\newline -c) Rename bison.exe to '_bison.exe'. -\newline +\end_inset + + +\begin_inset Text -\newline -d) Create a batch file 'bison.bat' in 'C: -\backslash -util -\backslash -' and add these lines: -\newline -\SpecialChar ~ -\SpecialChar ~ -set BISON_SIMPLE=C: -\backslash -util -\backslash -bison.simple -\newline -\SpecialChar ~ -\SpecialChar ~ -set BISON_HAIRY=C: -\backslash -util -\backslash -bison.hairy -\newline -\SpecialChar ~ -\SpecialChar ~ -_bison %1 %2 %3 %4 %5 %6 %7 %8 %9 -\newline +\layout Standard +-2.147.483.648, +2.147.483.647 -\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 + + +\begin_inset Text -\newline -e) In the Visual C++ IDE click Tools, Options, select the Directory tab, - in 'Show directories for:' select 'Executable files', and in the directories - window add a new path: 'c: -\backslash -util', click ok. - Note that you can use any other path instead of 'c: -\backslash -util', even the path where the Visual C++ tools are, probably: 'C: -\backslash -Program Files -\backslash -Microsoft Visual Studio -\backslash -Common -\backslash -Tools'. - So you don't have to execute step 'e' :) \layout Standard +0, +4.294.967.295 -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 + + + + +\begin_inset Text -Testing out the SDCC Compiler \layout Standard +float -The first thing you should do after installing your SDCC compiler is to - see if it runs. - Type -\family sans -\series bold -"sdcc --version" -\family default -\series default - at the prompt, and the program should run and tell you the version. - If it doesn't run, or gives a message about not finding sdcc program, then - you need to check over your installation. - Make sure that the sdcc bin directory is in your executable search path - defined by the PATH environment setting (see the Trouble-shooting section - for suggestions). - Make sure that the sdcc program is in the bin folder, if not perhaps something - did not install correctly. -\newline - -\newline +\end_inset + + +\begin_inset Text -\series medium -SDCC binaries are commonly installed in a directory arrangement like this: -\series default +\layout Standard +4 bytes IEEE 754 -\newline +\end_inset + + +\begin_inset Text -\newline +\layout Standard +signed -\begin_inset Tabular - - - - - +\end_inset + \begin_inset Text \layout Standard -/ -\series medium -usr/local/bin -\end_inset + +\end_inset \begin_inset Text \layout Standard - - -\series medium -Holds executables(sdcc, s51, aslink, -\series default -... -\series medium -) -\end_inset +1.175494351E-38, +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +3.402823466E+38 + +\end_inset - + \begin_inset Text \layout Standard +pointer -/ -\series medium -usr/local/share/sdcc/lib -\end_inset +\end_inset - + \begin_inset Text \layout Standard +1, 2, 3 or 4 bytes + +\end_inset + + +\begin_inset Text +\layout Standard +generic -\series medium -Holds common C -\series default -libraries -\end_inset +\end_inset - - \begin_inset Text \layout Standard -/ -\series medium -usr/local/share/sdcc/include -\end_inset + +\end_inset \begin_inset Text @@ -798,2111 +568,1064 @@ usr/local/share/sdcc/include \layout Standard -\series medium -Holds common C header files -\end_inset +\end_inset -\end_inset +\end_inset -\newline +\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 +\newline +SDCC also + provides an option (- +\begin_inset ERT +status Collapsed -\series medium -Make sure the compiler works on a very simple example. - Type in the following test.c program using your favorite editor: -\series default +\layout Standard -\newline -\family typewriter +\backslash +/ -\newline -char test; -\newline +\end_inset -\newline -void main(void) { -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -test=0; -\newline -} -\family default +-cyclomatic) to report the relative complexity of a function. + These functions can then be further optimized, or hand coded in assembly + if needed. + +\newline + +\newline +SDCC also comes with a companion source level debugger SDCDB, the debugger + currently uses ucSim a freeware simulator for 8051 and other micro-controllers.< +\newline -\newline +\newline -\emph on +The latest version can be downloaded from +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php} -\newline +\end_inset -\series medium -\emph default -Compile this using the following command: -\family sans -\series bold -"sdcc -c test.c". +. -\family default -\series default +\series bold -\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 +\series default +\emph on +Please note: the compiler will probably always be some steps ahead of this + documentation +\series bold +\emph default -\newline +\begin_inset LatexCommand \index{Status of documentation} -\newline +\end_inset -\series medium -The next step is to try it with the linker. - Type in -\family sans -\series bold -"sdcc test.c -\family default -\series default -" -\series medium -. - If all goes well the compiler will link with the libraries and produce - a test.ihx output file. - If this step fails -\series default - -\series medium -(no test.ihx, and the linker generates warnings), then the problem is most - likely that sdcc cannot find the -\series default -/ -\series medium -usr/local/share/sdcc/lib directory -\series default - -\series medium -(see the Install trouble-shooting section for suggestions). -\series default - -\newline - -\newline - -\series medium -The final test is to ensure sdcc can use the -\series default -standard -\series medium - header files and libraries. - Edit test.c and change it to the following: -\series default -\newline - -\newline - -\family typewriter -#include -\newline - -\newline -char str1[10]; -\newline +\begin_inset Foot +collapsed false -\newline -void main(void) { -\newline -\SpecialChar ~ -\SpecialChar ~ -strcpy(str1, "testing"); -\newline -} -\newline +\layout Standard +Obviously this has pros and cons -\newline +\end_inset -\family default -\series medium -Compile this by typing -\family sans -\series bold -"sdcc test.c" -\family default -\series medium . - This should generate a test.ihx output file, and it should give no warnings - such as not finding the string.h file. - If it cannot find the string.h file, then the problem is that sdcc cannot - find the /usr/local/share/sdcc/include directory -\series default - -\series medium -(see the Install trouble-shooting section for suggestions). -\layout Subsection -Install Trouble-shooting -\layout Subsubsection +\layout Section +Open Source -SDCC cannot find libraries or header files. \layout Standard - -The default installation assumes the libraries and header files are located - at -\begin_inset Quotes eld -\end_inset - -/usr/local/share/sdcc/lib -\begin_inset Quotes erd -\end_inset - +All packages used in this compiler system are +\emph on +open source +\emph default and -\begin_inset Quotes eld -\end_inset - -/usr/local/share/sdcc/include -\begin_inset Quotes erd -\end_inset - -. - An alternative is to specify these locations as compiler options like this: - -\family sans -\series bold -"sdcc\SpecialChar ~ --L\SpecialChar ~ -/usr/local/sdcc/lib/small\SpecialChar ~ --I\SpecialChar ~ -/usr/local/sdcc/include\SpecialChar ~ -test.c" -\family default -\series default -. -\layout Subsubsection - -SDCC does not compile correctly. -\layout Standard +\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} -A thing to try is starting from scratch by unpacking the .tgz source package - again in an empty directory. - Confure it like: -\newline +\end_inset -\newline + 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} -\family typewriter -./configure 2&>1 | tee configure.log -\family default +\end_inset -\newline + 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! -\newline -and build it like: -\newline +\layout Section +Typographic conventions +\begin_inset LatexCommand \index{Typographic conventions} -\newline +\end_inset -\family typewriter -make 2&>1 | tee make.log -\family default -\newline -\newline -If anything goes wrong, you can review the log files to locate the problem. - Or a relevant part of this can be attached to an email that could be helpful - when requesting help from the mailing list. -\layout Subsubsection +\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 +. -What the -\begin_inset Quotes sld -\end_inset +\family default + Code samples are printed in +\family typewriter +typewriter font. -./configure -\begin_inset Quotes srd -\end_inset +\family default + Interesting items and new terms are printed in +\emph on +italic. - does -\layout Standard +\layout Section +Compatibility +\begin_inset LatexCommand \label{sec:Compatibility-with-previous} -The -\begin_inset Quotes sld -\end_inset +\end_inset -./configure -\begin_inset Quotes srd -\end_inset + with previous versions +\begin_inset LatexCommand \index{Compatibility with previous versions} - command is a script that analyzes your system and performs some configuration - to ensure the source package compiles on your system. - It will take a few minutes to run, and will compile a few tests to determine - what compiler features are installed. -\layout Subsubsection +\end_inset -What the -\begin_inset Quotes sld -\end_inset -make -\begin_inset Quotes srd -\end_inset - does. \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} -This runs the GNU make tool, which automatically compiles all the source - packages into the final installed binary executables. -\layout Subsubsection - -What the -\begin_inset Quotes sld -\end_inset +\end_inset -make install -\begin_inset Quotes erd -\end_inset + (see section +\begin_inset LatexCommand \ref{sub:ANSI-Compliance} - command does. -\layout Standard +\end_inset -This will install the compiler, other executables and libraries in to the - appropriate system directories. - The default is to copy the executables to /usr/local/bin and the libraries - and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include. - On most systems you will need super-user privilages to do this. -\layout Subsection + for ANSI-Compliance). + +\newline -Advanced Install Options -\layout Standard -The -\begin_inset Quotes eld -\end_inset +\layout Itemize +short is now equivalent to int (16 bits), it used to be equivalent to char + (8 bits) which is not ANSI compliant. -configure -\begin_inset Quotes erd -\end_inset - - command has several options. - The most commonly used option is --prefix=, where is the final location for the sdcc executables and libraries, (default - location is /usr/local). - The installation process will create the following directory structure - under the specified (if they do not already exist). - -\newline - -\newline -bin/ - binary exectables (add to PATH environment variable) -\newline -bin/share/ -\newline -bin/share/sdcc/include/ - include header files -\newline -bin/share/sdcc/lib/ -\newline -bin/share/sdcc/lib/small/ - Object & library files for small model library -\newline -bin/share/sdcc/lib/large/ - Object & library files for large model library -\newline -bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390 library -\newline - -\newline -The command -\family sans -\series bold +\layout Itemize +the default directory for gcc-builds where include, library and documentation + files are stored is now in /usr/local/share. -\begin_inset Quotes sld -\end_inset +\layout Itemize +char type parameters to vararg +\begin_inset LatexCommand \index{vararg, va\_arg} -./configure --prefix=/usr/local -\begin_inset Quotes erd -\end_inset +\end_inset - -\family default -\series default -will configure the compiler to be installed in directory /usr/local. -\layout Subsection + functions are casted to int unless explicitly casted +\begin_inset Marginal +collapsed true -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 +\series bold +\SpecialChar ~ +! -\newline -You might want to look at the files which are installed in . - At the time of this writing, we find the following programs: -\newline - -\newline -In /bin: -\layout Itemize +\end_inset -sdcc - The compiler. -\layout Itemize +, e.g.: +\newline -sdcpp - The C preprocessor. -\layout Itemize +\family typewriter +\SpecialChar ~ +\SpecialChar ~ +char a=3; +\newline +\SpecialChar ~ +\SpecialChar ~ +printf ("%d %c +\backslash +n", a, (char)a); +\family default -asx8051 - The assembler for 8051 type processors. -\layout Itemize +\newline + will push a as an int and as a char resp. -as-z80 -\series bold -, -\series default -as-gbz80 - The Z80 and GameBoy Z80 assemblers. \layout Itemize +option - +\begin_inset ERT +status Collapsed -aslink -The linker for 8051 type processors. -\layout Itemize +\layout Standard -link-z80 -\series bold -, -\series default -link-gbz80 - The Z80 and GameBoy Z80 linkers. -\layout Itemize -s51 - The ucSim 8051 simulator. -\layout Itemize +\backslash +/ -sdcdb - The source debugger. -\layout Itemize +\end_inset -packihx - A tool to pack (compress) Intel hex files. -\layout Standard +-regextend has been removed. -In /share/sdcc/include \layout Itemize +option - +\begin_inset ERT +status Collapsed -the include files \layout Standard -In /share/sdcc/lib -\layout Itemize -the sources of the runtime library and the subdirs small large and ds390 - with the precompiled relocatables. -\layout Standard +\backslash +/ -In /share/sdcc/doc -\layout Itemize +\end_inset -the documentation -\layout Standard +-noregparms has been removed. -As development for other processors proceeds, this list will expand to include - executables to support processors like AVR, PIC, etc. -\layout Subsubsection +\layout Itemize +option - +\begin_inset ERT +status Collapsed -sdcc - The Compiler \layout Standard -This is the actual compiler, it in turn uses the c-preprocessor and invokes - the assembler and linkage editor. -\layout Subsubsection -sdcpp - The C-Preprocessor) -\layout Standard +\backslash +/ -The preprocessor is a modified version of the GNU preprocessor. - The C preprocessor is used to pull in #include sources, process #ifdef - statements, #defines and so on. -\layout Subsubsection +\end_inset -asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 - The Assemblers - and Linkage Editors -\layout Standard +-stack-after-data has been removed. -This is retargettable assembler & linkage editor, it was developed by Alan - Baldwin. - John Hartman created the version for 8051, and I (Sandeep) have made some - enhancements and bug fixes for it to work properly with the SDCC. -\layout Subsubsection +\layout Itemize +bit +\begin_inset LatexCommand \index{bit} -s51 - The Simulator -\layout Standard +\end_inset -S51 is a freeware, opensource simulator developed by Daniel Drotos ( -\begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu} + and sbit +\begin_inset LatexCommand \index{sbit} -\end_inset +\end_inset -). - The simulator is built as part of the build process. - For more information visit Daniel's website at: -\begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51} -\end_inset +\begin_inset LatexCommand \index{\_\_sbit} -. - It currently support the core mcs51, the Dallas DS80C390 and the Philips - XA51 family. -\layout Subsubsection +\end_inset -sdcdb - Source Level Debugger -\layout Standard + types now consistently behave like the C99 _Bool type with respect to type + conversion +\begin_inset LatexCommand \index{type conversion} +\end_inset -\family typewriter -\shape italic - -\newline -\newline +\begin_inset LatexCommand \index{type promotion} -\family default -\shape default -Sdcdb is the companion source level debugger. - The current version of the debugger uses Daniel's Simulator S51, but can - be easily changed to use other simulators. -\layout Section +\end_inset -Using SDCC -\layout Subsection +. + The most common incompatibility resulting from this change is related to + bit toggling +\begin_inset LatexCommand \index{Bit toggling} -Compiling -\layout Subsubsection +\end_inset -Single Source File Projects -\layout Standard + idioms, e.g.: +\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". +\family typewriter +\SpecialChar ~ +\SpecialChar ~ +bit b; +\newline +\SpecialChar ~ +\SpecialChar ~ +b = ~ +\begin_inset LatexCommand \index{\~\/ Operator} -\family default -\series default - This will compile, assemble and link your source file. - Output files are as follows -\newline - -\newline -sourcefile.asm - Assembler source file created by the compiler -\newline -sourcefile.lst - Assembler listing file created by the Assembler -\newline -sourcefile.rst - Assembler listing file updated with linkedit information, - created by linkage editor -\newline -sourcefile.sym - symbol listing for the sourcefile, created by the assembler -\newline -sourcefile.rel - Object file created by the assembler, input to Linkage editor -\newline -sourcefile.map - The memory map for the load module, created by the Linker -\newline -sourcefile.ihx - The load module in Intel hex format (you can select the - Motorola S19 format with --out-fmt-s19) -\newline -sourcefile.cdb - An optional file (with --debug) containing debug information -\newline +\end_inset -\layout Subsubsection +b; /* equivalent to b=1 instead of toggling b */ +\begin_inset Marginal +collapsed true -Projects with Multiple Source Files \layout Standard -SDCC can compile only ONE file at a time. - Let us for example assume that you have a project containing the following - files: -\newline +\series bold +\SpecialChar ~ +! -\newline -foo1.c (contains some functions) -\newline -foo2.c (contains some more functions) -\newline -foomain.c (contains more functions and the function main) -\newline +\end_inset -\size footnotesize -\newline +\newline +\SpecialChar ~ +\SpecialChar ~ +b = !b; /* toggles b */ +\newline -\size default -The first two files will need to be compiled separately with the commands: -\size footnotesize - -\size default +\family default +In previous versions, both forms would have toggled the bit. -\newline +\layout Standard -\newline +\emph on + -\family sans -\series bold -sdcc\SpecialChar ~ --c\SpecialChar ~ -foo1.c -\family default -\series default -\size footnotesize +\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. -\newline +\layout Section +Other Resources -\family sans -\series bold -\size default -sdcc\SpecialChar ~ --c\SpecialChar ~ -foo2.c -\family default -\series default +\layout Standard +The SDCC home page at +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/} -\newline +\end_inset -\newline -Then compile the source file containing the -\emph on -main() -\emph default - function and link the files together with the following command: -\newline + 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} -\newline +\end_inset -\family sans -\series bold -sdcc\SpecialChar ~ -foomain.c\SpecialChar ~ -foo1.rel\SpecialChar ~ -foo2.rel -\family default -\series default +. + 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. -\newline +\layout Section +Wishes for the future -\newline -Alternatively, -\emph on -foomain.c -\emph default -can be separately compiled as well: -\family sans -\series bold +\layout Standard +There are (and always will be) some things that could be done. + Here are some I can think of: +\newline -\newline -\newline -sdcc\SpecialChar ~ --c\SpecialChar ~ -foomain.c -\newline -sdcc foomain.rel foo1.rel foo2.rel -\newline +\layout Standard -\newline +\family typewriter +char KernelFunction3(char p) at 0x340; +\newline -\family default -\series default -The file containing the -\emph on -main() -\emph default - function -\emph on - -\emph default -\noun on -must -\noun default - be the -\noun on -first -\noun default - file specified in the command line, since the linkage editor processes - file in the order they are presented to it. -\layout Subsubsection -Projects with Additional Libraries \layout Standard -Some reusable routines may be compiled into a library, see the documentation - for the assembler and linkage editor (which are in /share/sdcc/doc) - for how to create a -\emph on -.lib -\emph default - library file. - Libraries created in this manner can be included in the command line. - Make sure you include the -L 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 +\family typewriter +better code banking +\begin_inset LatexCommand \index{code banking (limited support)} -\newline +\end_inset -\family sans -\series bold -sdcc foomain.c foolib.lib -L mylib -\newline + support for mcs51 +\newline -\newline +\newline -\family default -\series default -Note here that -\emph on - mylib -\emph default - must be an absolute path name. -\newline +\family default +If you can think of some more, please see the section +\begin_inset LatexCommand \ref{sub:Requesting-Features} -\newline -The most efficient way to use libraries is to keep seperate modules in seperate - source files. - The lib file now should name all the modules.rel files. - For an example see the standard library file -\emph on -libsdcc.lib -\emph default - in the directory /share/lib/small. -\layout Subsection +\end_inset -Command Line Options -\layout Subsubsection + about filing feature requests +\begin_inset LatexCommand \index{Requesting features} -Processor Selection Options -\layout List -\labelwidthstring 00.00.0000 +\end_inset -\series bold --mmcs51 -\series default - Generate code for the MCS51 (8051) family of processors. - This is the default processor target. -\layout List -\labelwidthstring 00.00.0000 +\begin_inset LatexCommand \index{Feature request} +\end_inset -\series bold --mds390 -\series default - Generate code for the DS80C390 processor. -\layout List -\labelwidthstring 00.00.0000 +. +\newline -\series bold --mz80 -\series default - Generate code for the Z80 family of processors. -\layout List -\labelwidthstring 00.00.0000 +\layout Chapter +Installing SDCC +\begin_inset LatexCommand \index{Installation} +\end_inset -\series bold --mgbz80 -\series default - Generate code for the GameBoy Z80 processor. -\layout List -\labelwidthstring 00.00.0000 -\series bold --mavr -\series default - Generate code for the Atmel AVR processor (In development, not complete). -\layout List -\labelwidthstring 00.00.0000 +\layout Standard +For most users it is sufficient to skip to either section +\begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux} +\end_inset -\series bold --mpic14 -\series default - Generate code for the PIC 14-bit processors (In development, not complete). -\layout List -\labelwidthstring 00.00.0000 + (Unix) or section +\begin_inset LatexCommand \ref{sub:Windows-Install} +\end_inset -\series bold --mtlcs900h -\series default - Generate code for the Toshiba TLCS-900H processor (In development, not - complete). -\layout List -\labelwidthstring 00.00.0000 + (Windows). + More detailed instructions follow below. + +\layout Section +Configure Options +\begin_inset LatexCommand \index{Options SDCC configuration} +\end_inset -\series bold --mxa51 -\series default - Generate code for the Philips XA51 processor (In development, not complete). -\layout Subsubsection -Preprocessor Options + +\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 -\series bold --I -\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 +\backslash +/ - files. -\layout List -\labelwidthstring 00.00.0000 +\end_inset +-prefix see table below -\series bold --D -\series default - Command line definition of macros. - Passed to the pre processor. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold --M -\series default - Tell the preprocessor to output a rule suitable for make describing the - dependencies of each object file. - For each source file, the preprocessor outputs one make-rule whose target - is the object file name for that source file and whose dependencies are - all the files `#include'd in it. - This rule may be a single line or may be continued with ` -\backslash -'-newline if it is long. - The list of rules is printed on standard output instead of the preprocessed - C program. - `-M' implies `-E'. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ + +\end_inset + +-exec_prefix see table below -\series bold --C -\series default - Tell the preprocessor not to discard comments. - Used with the `-E' option. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold --MM -\size large -\bar under - -\series default -\size default -\bar default -Like `-M' but the output mentions only the user header files included with - `#include -\begin_inset Quotes eld -\end_inset -file"'. - System header files included with `#include ' are omitted. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ +\end_inset + +-bindir see table below -\series bold --Aquestion(answer) -\series default - Assert the answer answer for question, in case it is tested with a preprocessor - conditional such as `#if #question(answer)'. - `-A-' disables the standard assertions that normally describe the target - machine. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold --Aquestion -\series default - (answer) Assert the answer answer for question, in case it is tested with - a preprocessor conditional such as `#if #question(answer)'. - `-A-' disables the standard assertions that normally describe the target - machine. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ -\series bold --Umacro -\series default - Undefine macro macro. - `-U' options are evaluated after all `-D' options, but before any `-include' - and `-imacros' options. -\layout List -\labelwidthstring 00.00.0000 +\end_inset +-datadir see table below -\series bold --dM -\series default - Tell the preprocessor to output only a list of the macro definitions that - are in effect at the end of preprocessing. - Used with the `-E' option. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold --dD -\series default - Tell the preprocessor to pass all macro definitions into the output, in - their proper sequence in the rest of the output. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ -\series bold --dN -\size large -\bar under - -\series default -\size default -\bar default -Like `-dD' except that the macro arguments and contents are omitted. - Only `#define name' is included in the output. -\layout Subsubsection +\end_inset -Linker Options -\layout List -\labelwidthstring 00.00.0000 +-datarootdir see table below +\newline -\series bold --L\SpecialChar ~ ---lib-path -\bar under - -\series default -\bar default - This option is passed to the linkage - editor's additional libraries search path. - The path name must be absolute. - Additional library files may be specified in the command line. - See section Compiling programs for more details. \layout List \labelwidthstring 00.00.0000 +\SpecialChar ~ +\SpecialChar ~ +docdir environment variable, see table below - -\series bold ---xram-loc -\series default - The start location of the external ram, default value is 0. - The value entered can be in Hexadecimal or Decimal format, e.g.: --xram-loc - 0x8000 or --xram-loc 32768. \layout List \labelwidthstring 00.00.0000 +\SpecialChar ~ +\SpecialChar ~ +include_dir_suffix environment variable, see table below - -\series bold ---code-loc -\series default - The start location of the code segment, default value 0. - Note when this option is used the interrupt vector table is also relocated - to the given address. - The value entered can be in Hexadecimal or Decimal format, e.g.: --code-loc - 0x8000 or --code-loc 32768. \layout List \labelwidthstring 00.00.0000 +\SpecialChar ~ +\SpecialChar ~ +lib_dir_suffix environment variable, see table below - -\series bold ---stack-loc -\series default - The initial value of the stack pointer. - The default value of the stack pointer is 0x07 if only register bank 0 - is used, if other register banks are used then the stack pointer is initialized - to the location above the highest register bank used. - eg. - if register banks 1 & 2 are used the stack pointer will default to location - 0x18. - The value entered can be in Hexadecimal or Decimal format, eg. - --stack-loc 0x20 or --stack-loc 32. - If all four register banks are used the stack will be placed after the - data segment (equivalent to --stack-after-data) \layout List \labelwidthstring 00.00.0000 +\SpecialChar ~ +\SpecialChar ~ +sdccconf_h_dir_separator environment variable, either / or +\backslash + +\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. +\newline -\series bold ---data-loc -\series default - The start location of the internal ram data segment, the default - value is 0x30.The value entered can be in Hexadecimal or Decimal format, - eg. - --data-loc 0x20 or --data-loc 32. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold ---idata-loc -\series default - The start location of the indirectly addressable internal ram, default - value is 0x80. - The value entered can be in Hexadecimal or Decimal format, eg. - --idata-loc 0x88 or --idata-loc 136. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ + +\end_inset + +-disable-mcs51-port Excludes the Intel mcs51 port -\series bold ---out-fmt-ihx -\bar under - -\series default -\bar default -The linker output (final object code) is in Intel Hex format. - (This is the default option). \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold ---out-fmt-s19 -\bar under - -\series default -\bar default -The linker output (final object code) is in Motorola S19 format. -\layout Subsubsection -MCS51 Options -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ +\end_inset + +-disable-gbz80-port Excludes the Gameboy gbz80 port -\series bold ---model-large -\series default - Generate code for Large model programs see section Memory Models for more - details. - If this option is used all source files in the project should be compiled - with this option. - In addition the standard library routines are compiled with small model, - they will need to be recompiled. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold ---model-small -\series default -\size large -\emph on - -\size default -\emph default -Generate code for Small Model programs see section Memory Models for more - details. - This is the default model. -\layout Subsubsection -DS390 Options -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ +\end_inset + +-disable-z80-port Excludes the z80 port -\series bold ---model-flat24 -\series default -\size large -\emph on - -\size default -\emph default -Generate 24-bit flat mode code. - This is the one and only that the ds390 code generator supports right now - and is default when using -\emph on --mds390 -\emph default -. - See section Memory Models for more details. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold ---stack-10bit -\series default - Generate code for the 10 bit stack mode of the Dallas DS80C390 part. - This is the one and only that the ds390 code generator supports right now - and is default when using -\emph on --mds390 -\emph default -. - In this mode, the stack is located in the lower 1K of the internal RAM, - which is mapped to 0x400000. - Note that the support is incomplete, since it still uses a single byte - as the stack pointer. - This means that only the lower 256 bytes of the potential 1K stack space - will actually be used. - However, this does allow you to reclaim the precious 256 bytes of low RAM - for use for the DATA and IDATA segments. - The compiler will not generate any code to put the processor into 10 bit - stack mode. - It is important to ensure that the processor is in this mode before calling - any re-entrant functions compiled with this option. - In principle, this should work with the -\emph on ---stack-auto -\emph default - option, but that has not been tested. - It is incompatible with the -\emph on ---xstack -\emph default - option. - It also only makes sense if the processor is in 24 bit contiguous addressing - mode (see the -\emph on ---model-flat24 option -\emph default -). -\layout Subsubsection - -Optimization Options -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ -\series bold ---nogcse -\series default - Will not do global subexpression elimination, this option may be used when - the compiler creates undesirably large stack/data spaces to store compiler - temporaries. - A warning message will be generated when this happens and the compiler - will indicate the number of extra bytes it allocated. - It recommended that this option NOT be used, #pragma\SpecialChar ~ -NOGCSE can be used - to turn off global subexpression elimination for a given function only. -\layout List -\labelwidthstring 00.00.0000 +\end_inset +-disable-avr-port Excludes the AVR port -\series bold ---noinvariant -\series default - Will not do loop invariant optimizations, this may be turned off for reasons - explained for the previous option. - For more details of loop optimizations performed see section Loop Invariants.It - recommended that this option NOT be used, #pragma\SpecialChar ~ -NOINVARIANT can be used - to turn off invariant optimizations for a given function only. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold ---noinduction -\series default - Will not do loop induction optimizations, see section strength reduction - for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~ -NOINDUCT -ION can be used to turn off induction optimizations for a given function - only. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ -\series bold ---nojtbound -\size large -\bar under - -\series default -\size default -\bar default - Will not generate boundary condition check when switch statements are implement -ed using jump-tables. - See section Switch Statements for more details. - It is recommended that this option is NOT used, #pragma\SpecialChar ~ -NOJTBOUND can be - used to turn off boundary checking for jump tables for a given function - only. -\layout List -\labelwidthstring 00.00.0000 +\end_inset +-disable-ds390-port Excludes the DS390 port -\series bold ---noloopreverse -\series default -\size large - -\size default -Will not do loop reversal optimization. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold ---no-xinit-opt -\series default - This will disable the memcpy of initialized data in far space from code - space -\layout Subsubsection - -Other Options -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ -\series bold --c\SpecialChar ~ ---compile-only -\series default - will compile and assemble the source, but will not call the linkage editor. -\layout List -\labelwidthstring 00.00.0000 +\end_inset +-disable-hc08-port Excludes the HC08 port -\series bold --E -\series default - Run only the C preprocessor. - Preprocess all the C source files specified and output the results to standard - output. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed - -\series bold ---stack-auto -\series default -\size large -\emph on - -\size default -\emph default -All functions in the source file will be compiled as -\emph on -reentrant -\emph default -, i.e. - the parameters and local variables will be allocated on the stack. - see section Parameters and Local Variables for more details. - If this option is used all source files in the project should be compiled - with this option. - -\layout List -\labelwidthstring 00.00.0000 +\layout Standard -\series bold ---xstack -\series default - Uses a pseudo stack in the first 256 bytes in the external ram for allocating - variables and passing parameters. - See section on external stack for more details. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ +\end_inset -\series bold ---callee-saves function1[,function2][,function3].... +-disable-pic-port Excludes the PIC port -\series default - The compiler by default uses a caller saves convention for register saving - across function calls, however this can cause unneccessary register pushing - & popping when calling small functions from larger functions. - This option can be used to switch the register saving convention for the - function names specified. - The compiler will not save registers when calling these functions, no extra - code will be generated at the entry & exit for these functions to save - & restore the registers used by these functions, this can SUBSTANTIALLY - reduce code & improve run time performance of the generated code. - In the future the compiler (with interprocedural analysis) will be able - to determine the appropriate scheme to use for each function call. - DO NOT use this option for built-in functions such as _muluint..., if this - option is used for a library function the appropriate library function - needs to be recompiled with the same option. - If the project consists of multiple source files then all the source file - should be compiled with the same --callee-saves option string. - Also see #pragma\SpecialChar ~ -CALLEE-SAVES. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold ---debug -\bar under - -\series default -\bar default -When this option is used the compiler will generate debug information, that - can be used with the SDCDB. - The debug information is collected in a file with .cdb extension. - For more information see documentation for SDCDB. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ -\series bold -\emph on ---regextend -\bar under - -\series default -\bar default - This option is obsolete and isn't supported anymore. -\layout List -\labelwidthstring 00.00.0000 +\end_inset +-disable-xa51-port Excludes the XA51 port -\series bold -\emph on ---noregparms -\series default - This option is obsolete and isn't supported anymore. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold ---peep-file -\series default - This option can be used to use additional rules to be used by - the peep hole optimizer. - See section Peep Hole optimizations for details on how to write these rules. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ -\series bold --S -\size large -\bar under - -\series default -\size default -\bar default -Stop after the stage of compilation proper; do not assemble. - The output is an assembler code file for the input file specified. -\layout List -\labelwidthstring 00.00.0000 +\end_inset +-disable-ucsim Disables configuring and building of ucsim -\series bold --Wa_asmOption[,asmOption] -\series default -... - Pass the asmOption to the assembler. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold --Wl_linkOption[,linkOption] -\series default -... - Pass the linkOption to the linker. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ -\series bold ---int-long-reent -\series default -\size large - -\size default - Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant. - Note by default these libraries are compiled as non-reentrant. - See section Installation for more details. -\layout List -\labelwidthstring 00.00.0000 +\end_inset +-disable-device-lib Disables automatically building device libraries -\series bold ---cyclomatic -\bar under - -\series default -\bar default -This option will cause the compiler to generate an information message for - each function in the source file. - The message contains some -\emph on -important -\emph default - information about the function. - The number of edges and nodes the compiler detected in the control flow - graph of the function, and most importantly the -\emph on -cyclomatic complexity -\emph default - see section on Cyclomatic Complexity for more details. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed - -\series bold ---float-reent -\bar under - -\series default -\bar default - Floating point library is compiled as reentrant.See section Installation - for more details. -\layout List -\labelwidthstring 00.00.0000 +\layout Standard -\series bold ---nooverlay -\series default - The compiler will not overlay parameters and local variables of any function, - see section Parameters and local variables for more details. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ +\end_inset -\series bold ---main-return -\series default - This option can be used when the code generated is called by a monitor - program. - The compiler will generate a 'ret' upon return from the 'main' function. - The default option is to lock up i.e. - generate a 'ljmp '. -\layout List -\labelwidthstring 00.00.0000 +-disable-packihx Disables building packihx +\newline -\series bold ---no-peep -\series default - Disable peep-hole optimization. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed +\layout Standard -\series bold ---peep-asm -\series default - Pass the inline assembler code through the peep hole optimizer. - This can cause unexpected changes to inline assembler code, please go through - the peephole optimizer rules defined in the source file tree '/peeph.def -' before using this option. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ -\series bold ---iram-size -\series default - Causes the linker to check if the interal ram usage is within limits - of the given value. -\layout List -\labelwidthstring 00.00.0000 +\end_inset +-enable-doc Build pdf, html and txt files from the lyx sources -\series bold ---nostdincl -\series default - This will prevent the compiler from passing on the default include path - to the preprocessor. \layout List \labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed - -\series bold ---nostdlib -\series default - This will prevent the compiler from passing on the default library path - to the linker. -\layout List -\labelwidthstring 00.00.0000 +\layout Standard -\series bold ---verbose -\series default - Shows the various actions the compiler is performing. -\layout List -\labelwidthstring 00.00.0000 +\backslash +/ +\end_inset -\series bold --V -\series default - Shows the actual commands the compiler is executing. -\layout Subsubsection +-enable-libgc Use the Bohem memory allocator. + Lower runtime footprint. -Intermediate Dump Options \layout Standard +Furthermore the environment variables CC, CFLAGS, ... + the tools and their arguments can be influenced. + Please see `configure - +\begin_inset ERT +status Collapsed -The following options are provided for the purpose of retargetting and debugging - the compiler. - These provided a means to dump the intermediate code (iCode) generated - by the compiler in human readable form at various stages of the compilation - process. - -\layout List -\labelwidthstring 00.00.0000 - - -\series bold ---dumpraw -\series default - This option will cause the compiler to dump the intermediate code into - a file of named -\emph on -.dumpraw -\emph default - just after the intermediate code has been generated for a function, i.e. - before any optimizations are done. - The basic blocks at this stage ordered in the depth first number, so they - may not be in sequence of execution. -\layout List -\labelwidthstring 00.00.0000 +\layout Standard -\series bold ---dumpgcse -\series default - Will create a dump of iCode's, after global subexpression elimination, - into a file named -\emph on -.dumpgcse. -\layout List -\labelwidthstring 00.00.0000 +\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_LI +B, 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 -\series bold ---dumpdeadcode -\series default - Will create a dump of iCode's, after deadcode elimination, into a file - named -\emph on -.dumpdeadcode. -\layout List -\labelwidthstring 00.00.0000 +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 -\series bold ---dumploop -\series default -\size large - -\size default -Will create a dump of iCode's, after loop optimizations, into a file named - -\emph on -.dumploop. -\layout List -\labelwidthstring 00.00.0000 +\layout Enumerate +open source, +\layout Enumerate +a gcc compiler and last but not least -\series bold ---dumprange -\series default -\size large - -\size default -Will create a dump of iCode's, after live range analysis, into a file named - -\emph on -.dumprange. -\layout List -\labelwidthstring 00.00.0000 +\layout Enumerate +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 -\series bold ---dumlrange -\series default - Will dump the life ranges for all symbols. -\layout List -\labelwidthstring 00.00.0000 +\newline +These defaults are: +\newline -\series bold ---dumpregassign -\bar under - -\series default -\bar default -Will create a dump of iCode's, after register assignment, into a file named - -\emph on -.dumprassgn. -\layout List -\labelwidthstring 00.00.0000 +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text +\layout Standard +Variable -\series bold ---dumplrange -\series default - Will create a dump of the live ranges of iTemp's -\layout List -\labelwidthstring 00.00.0000 +\end_inset + + +\begin_inset Text +\layout Standard +default -\series bold ---dumpall -\size large -\bar under - -\series default -\size default -\bar default -Will cause all the above mentioned dumps to be created. -\layout Subsection +\end_inset + + +\begin_inset Text -MCS51/DS390 Storage Class Language Extensions \layout Standard +Win32 builds -In addition to the ANSI storage classes SDCC allows the following MCS51 - specific storage classes. -\layout Subsubsection +\end_inset + + + + +\begin_inset Text -xdata \layout Standard -Variables declared with this storage class will be placed in the extern - RAM. - This is the -\series bold -default -\series default - storage class for Large Memory model, e.g.: -\newline - -\newline +\emph on +PREFIX -\family typewriter -xdata unsigned char xduc; -\layout Subsubsection +\end_inset + + +\begin_inset Text -data \layout Standard +/usr/local -This is the -\series bold -default -\series default - storage class for Small Memory model. - Variables declared with this storage class will be allocated in the internal - RAM, e.g.: -\newline +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\family typewriter -data int iramdata; -\layout Subsubsection - -idata -\layout Standard - -Variables declared with this storage class will be allocated into the indirectly - addressable portion of the internal ram of a 8051, e.g.: -\newline - -\newline +\backslash +sdcc -\family typewriter -idata int idi; -\layout Subsubsection +\end_inset + + + + +\begin_inset Text -bit \layout Standard -This is a data-type and a storage class specifier. - When a variable is declared as a bit, it is allocated into the bit addressable - memory of 8051, e.g.: -\newline - -\newline - -\family typewriter -bit iFlag; -\layout Subsubsection - -sfr / sbit -\layout Standard +\emph on +EXEC_PREFIX -Like the bit keyword, -\emph on -sfr / sbit -\emph default -signifies both a data-type and storage class, they are used to describe - the special function registers and special bit variables of a 8051, eg: -\newline - -\newline - -\family typewriter -sfr at 0x80 P0; /* special function register P0 at location 0x80 */ -\newline -sbit at 0xd7 CY; /* CY (Carry Flag) */ -\layout Subsection +\end_inset + + +\begin_inset Text -Pointers \layout Standard -SDCC allows (via language extensions) pointers to explicitly point to any - of the memory spaces of the 8051. - In addition to the explicit pointers, the compiler uses (by default) generic - pointers which can be used to point to any of the memory spaces. -\newline - -\newline -Pointer declaration examples: -\newline - -\size small - -\newline - -\family typewriter -\size default -/* pointer physically in xternal ram pointing to object in internal ram - */ -\newline -data unsigned char * xdata p; -\newline - -\newline -/* pointer physically in code rom pointing to data in xdata space */ -\newline -xdata unsigned char * code p; -\newline - -\newline -/* pointer physically in code space pointing to data in code space */ -\newline -code unsigned char * code p; -\newline - -\newline -/* the folowing is a generic pointer physically located in xdata space */ -\newline -char * xdata p; -\family default -\size small - -\newline - -\newline - -\size default -Well you get the idea. - -\newline - -\newline -All unqualified pointers are treated as 3-byte (4-byte for the ds390) -\emph on -generic -\emph default - pointers. - -\size small +\emph on +$PREFIX -\newline - -\newline - -\size default -The highest order byte of the -\emph on -generic -\emph default - pointers contains the data space information. - Assembler support routines are called whenever data is stored or retrieved - using -\emph on -generic -\emph default - pointers. - These are useful for developing reusable library routines. - Explicitly specifying the pointer type will generate the most efficient - code. -\layout Subsection +\end_inset + + +\begin_inset Text -Parameters & Local Variables \layout Standard -Automatic (local) variables and parameters to functions can either be placed - on the stack or in data-space. - The default action of the compiler is to place these variables in the internal - RAM (for small model) or external RAM (for large model). - This in fact makes them -\emph on -static -\emph default - so by default functions are non-reentrant. -\newline - -\newline -They can be placed on the stack either by using the -\emph on - --stack-auto -\emph default - option or by using the -\emph on -reentrant -\emph default - keyword in the function declaration, e.g.: -\newline - -\size small - -\newline - -\family typewriter -\size default -unsigned char foo(char i) reentrant -\newline -{ -\newline -... - -\newline -} -\newline - -\family default - -\newline -Since stack space on 8051 is limited, the -\emph on -reentrant -\emph default -keyword or the -\emph on - --stack-auto -\emph default - option should be used sparingly. - Note that the reentrant keyword just means that the parameters & local - variables will be allocated to the stack, it -\emph on -does not -\emph default - mean that the function is register bank independent. -\newline - -\newline -Local variables can be assigned storage classes and absolute addresses, - e.g.: -\newline - -\newline - -\family typewriter -unsigned char foo() { -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -xdata unsigned char i; -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -bit bvar; -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -data at 0x31 unsiged char j; -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -... - -\newline -} -\newline - -\newline - -\family default -In the above example the variable -\emph on -i -\emph default - will be allocated in the external ram, -\emph on -bvar -\emph default - in bit addressable space and -\emph on - j -\emph default - in internal ram. - When compiled with -\emph on ---stack-auto -\emph default - or when a function is declared as -\emph on -reentrant -\emph default - this should only be done for static variables. -\layout Standard +\emph on +$PREFIX -Parameters however are not allowed any storage class, (storage classes for - parameters will be ignored), their allocation is governed by the memory - model in use, and the reentrancy options. -\layout Subsection +\end_inset + + + + +\begin_inset Text -Overlaying \layout Standard -For non-reentrant functions SDCC will try to reduce internal ram space usage - by overlaying parameters and local variables of a function (if possible). - Parameters and local variables of a function will be allocated to an overlayabl -e segment if the function has -\emph on -no other function calls and the function is non-reentrant and the memory - model is small. - -\emph default - If an explicit storage class is specified for a local variable, it will - NOT be overlayed. -\layout Standard +\emph on +BINDIR -Note that the compiler (not the linkage editor) makes the decision for overlayin -g the data items. - Functions that are called from an interrupt service routine should be preceded - by a #pragma\SpecialChar ~ -NOOVERLAY if they are not reentrant. -\layout Standard +\end_inset + + +\begin_inset Text -Also note that the compiler does not do any processing of inline assembler - code, so the compiler might incorrectly assign local variables and parameters - of a function into the overlay segment if the inline assembler code calls - other c-functions that might use the overlay. - In that case the #pragma\SpecialChar ~ -NOOVERLAY should be used. \layout Standard -Parameters and Local variables of functions that contain 16 or 32 bit multiplica -tion or division will NOT be overlayed since these are implemented using - external functions, e.g.: -\newline +\emph on +$EXEC_PREFIX +\emph default +/bin -\newline +\end_inset + + +\begin_inset Text -\family typewriter -#pragma SAVE -\newline -#pragma NOOVERLAY -\newline -void set_error(unsigned char errcd) -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -P3 = errcd; -\newline -} -\newline -#pragma RESTORE -\newline +\layout Standard -\newline -void some_isr () interrupt 2 using 1 -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -... -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -set_error(10); -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -... - -\newline -} -\newline +\emph on +$EXEC_PREFIX +\emph default -\newline +\backslash +bin -\family default -In the above example the parameter -\emph on -errcd -\emph default - for the function -\emph on -set_error -\emph default - would be assigned to the overlayable segment if the #pragma\SpecialChar ~ -NOOVERLAY was - not present, this could cause unpredictable runtime behavior when called - from an ISR. - The #pragma\SpecialChar ~ -NOOVERLAY ensures that the parameters and local variables for - the function are NOT overlayed. -\layout Subsection +\end_inset + + + + +\begin_inset Text -Interrupt Service Routines \layout Standard -SDCC allows interrupt service routines to be coded in C, with some extended - keywords. -\newline - -\newline +\emph on +DATADIR -\family typewriter -void timer_isr (void) interrupt 2 using 1 -\newline -{ -\newline -.. - -\newline -} -\newline - -\newline +\end_inset + + +\begin_inset Text -\family default -The number following the -\emph on -interrupt -\emph default - keyword is the interrupt number this routine will service. - The compiler will insert a call to this routine in the interrupt vector - table for the interrupt number specified. - The -\emph on -using -\emph default - keyword is used to tell the compiler to use the specified register bank - (8051 specific) when generating code for this function. - Note that when some function is called from an interrupt service routine - it should be preceded by a #pragma\SpecialChar ~ -NOOVERLAY if it is not reentrant. - A special note here, int (16 bit) and long (32 bit) integer division, multiplic -ation & modulus operations are implemented using external support routines - developed in ANSI-C, if an interrupt service routine needs to do any of - these operations then the support routines (as mentioned in a following - section) will have to be recompiled using the -\emph on - --stack-auto -\emph default - option and the source file will need to be compiled using the -\emph on ---int-long-ren -\emph default -t compiler option. \layout Standard -If you have multiple source files in your project, interrupt service routines - can be present in any of them, but a prototype of the isr MUST be present - or included in the file that contains the function -\emph on -main -\emph default -. -\layout Standard +\emph on +$DATAROOTDIR -Interrupt Numbers and the corresponding address & descriptions for the Standard - 8051 are listed below. - SDCC will automatically adjust the interrupt vector table to the maximum - interrupt number specified. -\newline +\end_inset + + +\begin_inset Text \layout Standard +\emph on +$DATAROOTDIR -\begin_inset Tabular - - - - - - +\end_inset + + + \begin_inset Text \layout Standard -Interrupt # -\end_inset +\emph on +DATAROOTDIR + +\end_inset \begin_inset Text \layout Standard -Description -\end_inset +\emph on +$PREFIX +\emph default +/share + +\end_inset \begin_inset Text \layout Standard -Vector Address -\end_inset +\emph on +$PREFIX + +\end_inset @@ -2911,24 +1634,36 @@ Vector Address \layout Standard -0 -\end_inset +\emph on +DOCDIR + +\end_inset \begin_inset Text \layout Standard -External 0 -\end_inset +\emph on +$DATAROOTDIR +\emph default +/sdcc/doc + +\end_inset \begin_inset Text \layout Standard -0x0003 -\end_inset +\emph on +$DATAROOTDIR +\emph default + +\backslash +doc + +\end_inset @@ -2937,76 +1672,104 @@ External 0 \layout Standard -1 -\end_inset +\emph on +INCLUDE_DIR_SUFFIX + +\end_inset \begin_inset Text \layout Standard +sdcc/include -Timer 0 -\end_inset +\end_inset \begin_inset Text \layout Standard +include -0x000B -\end_inset +\end_inset - + \begin_inset Text \layout Standard -2 -\end_inset +\emph on +LIB_DIR_SUFFIX + +\end_inset \begin_inset Text \layout Standard +sdcc/lib -External 1 -\end_inset +\end_inset \begin_inset Text \layout Standard +lib -0x0013 -\end_inset +\end_inset - + + +\end_inset + + +\newline + + +\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 \layout Standard +Variable (computed) -3 -\end_inset +\end_inset \begin_inset Text \layout Standard +default -Timer 1 -\end_inset +\end_inset \begin_inset Text \layout Standard +Win32 builds -0x001B -\end_inset +\end_inset @@ -3015,1866 +1778,1157 @@ Timer 1 \layout Standard -4 -\end_inset +\emph on +BIN2DATA_DIR + +\end_inset \begin_inset Text \layout Standard +../share -Serial -\end_inset +\end_inset \begin_inset Text \layout Standard +.. -0x0023 -\end_inset +\end_inset - + + +\begin_inset Text -\end_inset +\layout Standard +\emph on +PREFIX2BIN_DIR -\newline +\end_inset + + +\begin_inset Text -\newline -If the interrupt service routine is defined without -\emph on -using -\emph default - a register bank or with register bank 0 (using 0), the compiler will save - the registers used by itself on the stack upon entry and restore them at - exit, however if such an interrupt service routine calls another function - then the entire register bank will be saved on the stack. - This scheme may be advantageous for small interrupt service routines which - have low register usage. \layout Standard +bin -If the interrupt service routine is defined to be using a specific register - bank then only -\emph on -a, b & dptr -\emph default - are save and restored, if such an interrupt service routine calls another - function (using another register bank) then the entire register bank of - the called function will be saved on the stack. - This scheme is recommended for larger interrupt service routines. -\layout Standard +\end_inset + + +\begin_inset Text -Calling other functions from an interrupt service routine is not recommended, - avoid it if possible. -\newline +\layout Standard +bin -\newline -Also see the _naked modifier. -\layout Subsection +\end_inset + + + + +\begin_inset Text -Critical Functions \layout Standard +\emph on +PREFIX2DATA_DIR -\shape italic - -\shape default +\end_inset + + +\begin_inset Text -\newline +\layout Standard +share/sdcc -\newline -A special keyword may be associated with a function declaring it as -\emph on -critical -\emph default -. - SDCC will generate code to disable all interrupts upon entry to a critical - function and enable them back before returning. - Note that nesting critical functions may cause unpredictable results. -\newline +\end_inset + + +\begin_inset Text -\size small +\layout Standard -\newline -\family typewriter -\size default -int foo () critical -\newline -{ -\newline -... - -\newline -... - -\newline -} -\newline +\end_inset + + + -\family default +\end_inset + + +\newline -\newline -The critical attribute maybe used with other attributes like -\emph on -reentrant. -\layout Subsection -Naked Functions \layout Standard +\noindent +Examples: -A special keyword may be associated with a function declaring it as -\emph on -_naked. - -\emph default -The -\emph on -_naked -\emph default - function modifier attribute prevents the compiler from generating prologue - and epilogue code for that function. - This means that the user is entirely responsible for such things as saving - any registers that may need to be preserved, selecting the proper register - bank, generating the -\emph on -return -\emph default - instruction at the end, etc. - Practically, this means that the contents of the function must be written - in inline assembler. - This is particularly useful for interrupt functions, which can have a large - (and often unnecessary) prologue/epilogue. - For example, compare the code generated by these two functions: -\newline +\layout LyX-Code +./configure +\newline +./configure - +\begin_inset ERT +status Collapsed -\newline +\layout Standard -\family typewriter -data unsigned char counter; -\newline -void simpleInterrupt(void) interrupt 1 -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -counter++; -\newline -} -\newline -\newline -void nakedInterrupt(void) interrupt 2 _naked -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_asm -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -inc\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_counter -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -reti\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -; MUST explicitly include ret in _naked function. -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_endasm; -\newline -} -\family default +\backslash +/ -\newline +\end_inset -\newline -For an 8051 target, the generated simpleInterrupt looks like: -\newline +-prefix= +\begin_inset Quotes srd +\end_inset -\newline +/usr/bin +\begin_inset Quotes srd +\end_inset -\family typewriter -_simpleIterrupt: -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -push\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -acc -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -push\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -b -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -push\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -dpl -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -push\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -dph -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -push\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -psw -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -psw,#0x00 -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -inc\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_counter -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -pop\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -psw -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -pop\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -dph -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -pop\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -dpl -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -pop\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -b -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -pop\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -acc -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -reti -\family default + - +\begin_inset ERT +status Collapsed -\newline +\layout Standard -\newline -whereas nakedInterrupt looks like: -\newline -\newline +\backslash +/ -\family typewriter -_nakedInterrupt: -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -inc\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_counter -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -reti\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -; MUST explicitly include ret(i) in _naked function. -\family default +\end_inset -\newline +-datarootdir= +\begin_inset Quotes srd +\end_inset -\newline -While there is nothing preventing you from writing C code inside a _naked - function, there are many ways to shoot yourself in the foot doing this, - and is is recommended that you stick to inline assembler. -\layout Subsection +/usr/share +\begin_inset Quotes srd +\end_inset -Functions using private banks -\layout Standard -The -\emph on -using -\emph default - attribute (which tells the compiler to use a register bank other than the - default bank zero) should only be applied to -\emph on -interrupt -\emph default - functions (see note 1 below). - This will in most circumstances make the generated ISR code more efficient - since it will not have to save registers on the stack. +\newline +./configure - +\begin_inset ERT +status Collapsed + \layout Standard -The -\emph on -using -\emph default - attribute will have no effect on the generated code for a -\emph on -non-interrupt -\emph default - function (but may occasionally be useful anyway -\begin_inset Foot -collapsed true -\layout Standard +\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 +\end_inset -). -\newline +-disable-avr-port - +\begin_inset ERT +status Collapsed -\emph on -(pending: I don't think this has been done yet) \layout Standard -An -\emph on -interrupt -\emph default - function using a non-zero bank will assume that it can trash that register - bank, and will not save it. - Since high-priority interrupts can interrupt low-priority ones on the 8051 - and friends, this means that if a high-priority ISR -\emph on -using -\emph default - a particular bank occurs while processing a low-priority ISR -\emph on -using -\emph default - the same bank, terrible and bad things can happen. - To prevent this, no single register bank should be -\emph on -used -\emph default - by both a high priority and a low priority ISR. - This is probably most easily done by having all high priority ISRs use - one bank and all low priority ISRs use another. - If you have an ISR which can change priority at runtime, you're on your - own: I suggest using the default bank zero and taking the small performance - hit. -\layout Standard -It is most efficient if your ISR calls no other functions. - If your ISR must call other functions, it is most efficient if those functions - use the same bank as the ISR (see note 1 below); the next best is if the - called functions use bank zero. - It is very inefficient to call a function using a different, non-zero bank - from an ISR. - -\layout Subsection +\backslash +/ -Absolute Addressing -\layout Standard +\end_inset -Data items can be assigned an absolute address with the -\emph on -at
-\emph default - keyword, in addition to a storage class, e.g.: -\newline +-disable-xa51-port -\newline +\layout Standard +To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw +32'): -\family typewriter -xdata at 0x8000 unsigned char PORTA_8255 ; -\newline +\layout LyX-Code +./configure +\backslash -\family default +\newline +CC= +\begin_inset Quotes srd +\end_inset -\newline -In the above example the PORTA_8255 will be allocated to the location 0x8000 - of the external ram. - Note that this feature is provided to give the programmer access to -\emph on -memory mapped -\emph default - devices attached to the controller. - The compiler does not actually reserve any space for variables declared - in this way (they are implemented with an equate in the assembler). - Thus it is left to the programmer to make sure there are no overlaps with - other variables that are declared without the absolute address. - The assembler listing file (.lst) and the linker output files (.rst) and - (.map) are a good places to look for such overlaps. -\newline +i586-mingw32msvc-gcc +\begin_inset Quotes srd +\end_inset -\newline -Absolute address can be specified for variables in all storage classes, - e.g.: -\newline + CXX= +\begin_inset Quotes srd +\end_inset -\newline +i586-mingw32msvc-g++ +\begin_inset Quotes srd +\end_inset -\family typewriter -bit at 0x02 bvar; -\newline + +\backslash + +\newline +RANLIB= +\begin_inset Quotes srd +\end_inset -\newline +i586-mingw32msvc-ranlib +\begin_inset Quotes srd +\end_inset -\family default -The above example will allocate the variable at offset 0x02 in the bit-addressab -le space. - There is no real advantage to assigning absolute addresses to variables - in this manner, unless you want strict control over all the variables allocated. -\layout Subsection + +\backslash -Startup Code -\layout Standard +\newline +STRIP= +\begin_inset Quotes srd +\end_inset + +i586-mingw32msvc-strip +\begin_inset Quotes srd +\end_inset -The compiler inserts a call to the C routine -\emph on -_sdcc__external__startup() -\series bold -\emph default -\series default -at the start of the CODE area. - This routine is in the runtime library. - By default this routine returns 0, if this routine returns a non-zero value, - the static & global variable initialization will be skipped and the function - main will be invoked Other wise static & global variables will be initialized - before the function main is invoked. - You could add a -\emph on -_sdcc__external__startup() -\emph default - routine to your program to override the default if you need to setup hardware - or perform some other critical operation prior to static & global variable - initialization. -\layout Subsection +\backslash + +\newline +- +\begin_inset ERT +status Collapsed -Inline Assembler Code \layout Standard -SDCC allows the use of in-line assembler with a few restriction as regards - labels. - All labels defined within inline assembler code -\emph on -has to be -\emph default - of the form -\emph on -nnnnn$ -\emph default - where nnnn is a number less than 100 (which implies a limit of utmost 100 - inline assembler labels -\emph on -per function -\emph default -\noun on -) -\noun default -. - It is strongly recommended that each assembly instruction (including labels) - be placed in a separate line (as the example shows). - When the -\emph on ---peep-asm -\emph default - command line option is used, the inline assembler code will be passed through - the peephole optimizer. - This might cause some unexpected changes in the inline assembler code. - Please go throught the peephole optimizer rules defined in file -\emph on -SDCCpeeph.def -\emph default - carefully before using this option. -\newline -\newline +\backslash +/ -\family typewriter -_asm -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -b,#10 -\newline -00001$: -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -djnz\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -b,00001$ -\newline -_endasm ; -\family default -\size small +\end_inset -\newline +-prefix= +\begin_inset Quotes srd +\end_inset -\newline +/sdcc +\begin_inset Quotes srd +\end_inset -\size default -The inline assembler code can contain any valid code understood by the assembler -, this includes any assembler directives and comment lines. - The compiler does not do any validation of the code within the -\family typewriter -_asm ... - _endasm; -\family default - keyword pair. -\newline +\backslash -\newline -Inline assembler code cannot reference any C-Labels, however it can reference - labels defined by the inline assembler, e.g.: -\newline +\newline +- +\begin_inset ERT +status Collapsed -\newline +\layout Standard -\family typewriter -foo() { -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* some c code */ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_asm -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -; some assembler code -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -ljmp $0003 -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_endasm; -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* some more c code */ -\newline -clabel:\SpecialChar ~ -\SpecialChar ~ -/* inline assembler cannot reference this label */ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_asm -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -$0003: ;label (can be reference by inline assembler only) -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -_endasm ; -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -/* some more c code */ -\newline -} -\newline -\newline +\backslash +/ -\family default -In other words inline assembly code can access labels defined in inline - assembly within the scope of the funtion. - -\layout Standard +\end_inset -The same goes the other way, ie. - labels defines in inline assembly CANNOT be accessed by C statements. -\layout Subsection +-datarootdir= +\begin_inset Quotes srd +\end_inset -int(16 bit) and long (32 bit) Support -\layout Standard +/sdcc +\begin_inset Quotes srd +\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 optimations are used. - The following files contain the described routine, all of them can be found - in /share/sdcc/lib. -\newline - -\newline - -\emph on - -\emph default - -\newline - -\newline -_mulsint.c - signed 16 bit multiplication (calls _muluint) -\newline -_muluint.c - unsigned 16 bit multiplication -\newline -_divsint.c - signed 16 bit division (calls _divuint) -\newline -_divuint.c - unsigned 16 bit division -\newline -_modsint.c - signed 16 bit modulus (call _moduint) -\newline -_moduint.c - unsigned 16 bit modulus -\newline -_mulslong.c - signed 32 bit multiplication (calls _mululong) -\newline -_mululong.c - unsigned32 bit multiplication -\newline -_divslong.c - signed 32 division (calls _divulong) -\newline -_divulong.c - unsigned 32 division -\newline -_modslong.c - signed 32 bit modulus (calls _modulong) -\newline -_modulong.c - unsigned 32 bit modulus -\size footnotesize - -\newline - -\newline - -\size default -Since they are compiled as -\emph on -non-reentrant -\emph default -, interrupt service routines should not do any of the above operations. - If this is unavoidable then the above routines will need to be compiled - with the -\emph on ---stack-auto -\emph default - option, after which the source program will have to be compiled with -\emph on ---int-long-rent -\emph default - option. -\layout Subsection + +\backslash -Floating Point Support -\layout Standard +\newline +docdir= +\begin_inset Quotes srd +\end_inset -SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating - point support routines are derived from gcc's floatlib.c and consists of - the following routines: -\newline - -\newline - -\emph on - -\emph default - -\newline - -\newline -_fsadd.c - add floating point numbers -\newline -_fssub.c - subtract floating point numbers -\newline -_fsdiv.c - divide floating point numbers -\newline -_fsmul.c - multiply floating point numbers -\newline -_fs2uchar.c - convert floating point to unsigned char -\newline -_fs2char.c - convert floating point to signed char -\newline -_fs2uint.c - convert floating point to unsigned int -\newline -_fs2int.c - convert floating point to signed int -\newline -_fs2ulong.c - convert floating point to unsigned long -\newline -_fs2long.c - convert floating point to signed long -\newline -_uchar2fs.c - convert unsigned char to floating point -\newline -_char2fs.c - convert char to floating point number -\newline -_uint2fs.c - convert unsigned int to floating point -\newline -_int2fs.c - convert int to floating point numbers -\newline -_ulong2fs.c - convert unsigned long to floating point number -\newline -_long2fs.c - convert long to floating point number -\size footnotesize - -\newline - -\newline - -\size default -Note if all these routines are used simultaneously the data space might - overflow. - For serious floating point usage it is strongly recommended that the large - model be used. -\layout Subsection -MCS51 Memory Models -\layout Standard +\backslash +${datarootdir}/doc +\begin_inset Quotes srd +\end_inset -SDCC allows two memory models for MCS51 code, small and large. - Modules compiled with different memory models should -\emph on -never -\emph default - be combined together or the results would be unpredictable. - The library routines supplied with the compiler are compiled as both small - and large. - The compiled library modules are contained in seperate directories as small - and large so that you can link to either set. -\layout Standard +\backslash -When the large model is used all variables declared without a storage class - will be allocated into the external ram, this includes all parameters and - local variables (for non-reentrant functions). - When the small model is used variables without storage class are allocated - in the internal ram. -\layout Standard +\newline +include_dir_suffix= +\begin_inset Quotes srd +\end_inset -Judicious usage of the processor specific storage classes and the 'reentrant' - function type will yield much more efficient code, than using the large - model. - Several optimizations are disabled when the program is compiled using the - large model, it is therefore strongly recommdended that the small model - be used unless absolutely required. -\layout Subsection +include +\begin_inset Quotes srd +\end_inset -DS390 Memory Models -\layout Standard + +\backslash -The only model supported is Flat 24. - This generates code for the 24 bit contiguous addressing mode of the Dallas - DS80C390 part. - In this mode, up to four meg of external RAM or code space can be directly - addressed. - See the data sheets at www.dalsemi.com for further information on this part. -\newline +\newline +lib_dir_suffix= +\begin_inset Quotes srd +\end_inset + +lib +\begin_inset Quotes srd +\end_inset -\newline -In older versions of the compiler, this option was used with the MCS51 code - generator ( -\emph on --mmcs51 -\emph default -). - Now, however, the '390 has it's own code generator, selected by the -\emph on --mds390 -\emph default - switch. -\newline +\backslash -\newline -Note that the compiler does not generate any code to place the processor - into 24 bitmode (although -\emph on -tinibios -\emph default - in the ds390 libraries will do that for you). - If you don't use -\emph on -tinibios -\emph default -, the boot loader or similar code must ensure that the processor is in 24 - bit contiguous addressing mode before calling the SDCC startup code. -\newline +\newline +sdccconf_h_dir_separator= +\begin_inset Quotes srd +\end_inset -\newline -Like the -\emph on ---model-large -\emph default - option, variables will by default be placed into the XDATA segment. - -\newline -\newline -Segments may be placed anywhere in the 4 meg address space using the usual - --*-loc options. - Note that if any segments are located above 64K, the -r flag must be passed - to the linker to generate the proper segment relocations, and the Intel - HEX output format must be used. - The -r flag can be passed to the linker by using the option -\emph on --Wl-r -\emph default - on the sdcc command line. - However, currently the linker can not handle code segments > 64k. -\layout Subsection +\backslash -Defines Created by the Compiler -\layout Standard +\backslash -The compiler creates the following #defines. -\layout Itemize +\backslash -SDCC - this Symbol is always defined. -\layout Itemize +\backslash -SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model used - (e.g.: -mds390) -\layout Itemize +\begin_inset Quotes srd +\end_inset -__mcs51 or __ds390 or __z80, etc - depending on the model used (e.g. - -mz80) -\layout Itemize + +\backslash -SDCC_STACK_AUTO - this symbol is defined when -\emph on ---stack-auto -\emph default - option is used. -\layout Itemize +\newline +- +\begin_inset ERT +status Collapsed -SDCC_MODEL_SMALL - when -\emph on ---model-small -\emph default - is used. -\layout Itemize +\layout Standard -SDCC_MODEL_LARGE - when -\emph on ---model-large -\emph default - is used. -\layout Itemize -SDCC_USE_XSTACK - when -\emph on ---xstack -\emph default - option is used. -\layout Itemize +\backslash +/ -SDCC_STACK_TENBIT - when -\emph on --mds390 -\emph default - is used -\layout Itemize +\end_inset -SDCC_MODEL_FLAT24 - when -\emph on --mds390 -\emph default - is used -\layout Section +-disable-device-lib +\backslash -SDCC Technical Data -\layout Subsection +\newline +- +\begin_inset ERT +status Collapsed -Optimizations \layout Standard -SDCC performs a host of standard optimizations in addition to some MCU specific - optimizations. - -\layout Subsubsection - -Sub-expression Elimination -\layout Standard -The compiler does local and global common subexpression elimination, e.g.: - -\newline +\backslash +/ -\newline +\end_inset -\family typewriter -i = x + y + 1; -\newline -j = x + y; -\family default +-host=i586-mingw32msvc +\backslash -\newline +\newline +- +\begin_inset ERT +status Collapsed -\newline -will be translated to -\newline +\layout Standard -\newline -\family typewriter -iTemp = x + y -\newline -i = iTemp + 1 -\newline -j = iTemp -\newline +\backslash +/ -\family default +\end_inset -\newline -Some subexpressions are not as obvious as the above example, e.g.: -\newline +-build=unknown-unknown-linux-gnu -\newline +\layout Standard +To +\begin_inset Quotes sld +\end_inset -\family typewriter -a->b[i].c = 10; -\newline -a->b[i].d = 11; -\family default +cross +\begin_inset Quotes srd +\end_inset -\newline +compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32 +): -\newline -In this case the address arithmetic a->b[i] will be computed only once; - the equivalent code in C would be. -\newline +\layout LyX-Code +./configure -C +\backslash -\newline +\newline +- +\begin_inset ERT +status Collapsed -\family typewriter -iTemp = a->b[i]; -\newline -iTemp.c = 10; -\newline -iTemp.d = 11; -\family default +\layout Standard -\newline -\newline -The compiler will try to keep these temporary variables in registers. -\layout Subsubsection +\backslash +/ -Dead-Code Elimination -\layout Standard +\end_inset +-prefix= +\begin_inset Quotes srd +\end_inset -\family typewriter -int global; -\newline -void f () { -\newline -\SpecialChar ~ -\SpecialChar ~ -int i; -\newline -\SpecialChar ~ -\SpecialChar ~ -i = 1; \SpecialChar ~ -/* dead store */ -\newline -\SpecialChar ~ -\SpecialChar ~ -global = 1;\SpecialChar ~ -/* dead store */ -\newline -\SpecialChar ~ -\SpecialChar ~ -global = 2; -\newline -\SpecialChar ~ -\SpecialChar ~ -return; -\newline -\SpecialChar ~ -\SpecialChar ~ -global = 3;\SpecialChar ~ -/* unreachable */ -\newline -} -\family default +/sdcc +\begin_inset Quotes srd +\end_inset -\newline + +\backslash -\newline -will be changed to -\newline +\newline +- +\begin_inset ERT +status Collapsed -\newline +\layout Standard -\family typewriter -int global; void f () -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -global = 2; -\newline -\SpecialChar ~ -\SpecialChar ~ -return; -\newline -} -\layout Subsubsection -Copy-Propagation -\layout Standard +\backslash +/ +\end_inset -\family typewriter -int f() { -\newline -\SpecialChar ~ -\SpecialChar ~ -int i, j; -\newline -\SpecialChar ~ -\SpecialChar ~ -i = 10; -\newline -\SpecialChar ~ -\SpecialChar ~ -j = i; -\newline -\SpecialChar ~ -\SpecialChar ~ -return j; -\newline -} -\family default +-datarootdir= +\begin_inset Quotes srd +\end_inset -\newline +/sdcc +\begin_inset Quotes srd +\end_inset -\newline -will be changed to -\newline + +\backslash -\newline +\newline +docdir= +\begin_inset Quotes srd +\end_inset -\family typewriter -int f() { -\newline -\SpecialChar ~ - \SpecialChar ~ - int i,j; -\newline -\SpecialChar ~ - \SpecialChar ~ - i = 10; -\newline -\SpecialChar ~ - \SpecialChar ~ - j = 10; -\newline -\SpecialChar ~ - \SpecialChar ~ - return 10; -\newline -} -\newline -\newline +\backslash +${datarootdir}/doc +\begin_inset Quotes srd +\end_inset -\family default -Note: the dead stores created by this copy propagation will be eliminated - by dead-code elimination. -\layout Subsubsection + +\backslash + +\newline +include_dir_suffix= +\begin_inset Quotes srd +\end_inset -Loop Optimizations -\layout Standard +include +\begin_inset Quotes srd +\end_inset -Two types of loop optimizations are done by SDCC loop invariant lifting - and strength reduction of loop induction variables. - In addition to the strength reduction the optimizer marks the induction - variables and the register allocator tries to keep the induction variables - in registers for the duration of the loop. - Because of this preference of the register allocator, loop induction optimizati -on causes an increase in register pressure, which may cause unwanted spilling - of other temporary variables into the stack / data space. - The compiler will generate a warning message when it is forced to allocate - extra space either on the stack or data space. - If this extra space allocation is undesirable then induction optimization - can be eliminated either for the entire source file (with --noinduction - option) or for a given function only using #pragma\SpecialChar ~ -NOINDUCTION. -\newline + +\backslash -\newline -Loop Invariant: -\newline +\newline +lib_dir_suffix= +\begin_inset Quotes srd +\end_inset -\newline +lib +\begin_inset Quotes srd +\end_inset -\family typewriter -for (i = 0 ; i < 100 ; i ++) -\newline - \SpecialChar ~ - \SpecialChar ~ -f += k + l; -\family default + +\backslash -\newline +\newline +sdccconf_h_dir_separator= +\begin_inset Quotes srd +\end_inset -\newline -changed to -\newline -\newline +\backslash -\family typewriter -itemp = k + l; -\newline -for (i = 0; i < 100; i++) -\newline -\SpecialChar ~ -\SpecialChar ~ -f += itemp; -\family default +\backslash -\newline +\backslash -\newline -As mentioned previously some loop invariants are not as apparent, all static - address computations are also moved out of the loop. -\newline +\backslash -\newline -Strength Reduction, this optimization substitutes an expression by a cheaper - expression: -\newline +\begin_inset Quotes srd +\end_inset -\newline + +\backslash -\family typewriter -for (i=0;i < 100; i++) -\newline -\SpecialChar ~ -\SpecialChar ~ -ar[i*5] = i*3; -\family default +\newline +CC= +\begin_inset Quotes srd +\end_inset -\newline +gcc -mno-cygwin +\begin_inset Quotes srd +\end_inset -\newline -changed to -\newline + +\backslash -\newline +\newline +CXX= +\begin_inset Quotes srd +\end_inset -\family typewriter -itemp1 = 0; -\newline -itemp2 = 0; -\newline -for (i=0;i< 100;i++) { -\newline - \SpecialChar ~ - \SpecialChar ~ -ar[itemp1] = itemp2; -\newline - \SpecialChar ~ - \SpecialChar ~ -itemp1 += 5; -\newline - \SpecialChar ~ - \SpecialChar ~ -itemp2 += 3; -\newline -} -\family default +g++ -mno-cygwin +\begin_inset Quotes srd +\end_inset -\newline + -\newline -The more expensive multiplication is changed to a less expensive addition. -\layout Subsubsection +\layout Standard +'configure' is quite slow on Cygwin (at least on windows before Win2000/XP). + The option '- +\begin_inset ERT +status Collapsed -Loop Reversing \layout Standard -This optimization is done to reduce the overhead of checking loop boundaries - for every iteration. - Some simple loops can be reversed and implemented using a -\begin_inset Quotes eld -\end_inset -decrement and jump if not zero -\begin_inset Quotes erd -\end_inset +\backslash +/ - 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 +\end_inset -The 'for' loop is of the form -\newline +-C' turns on caching, which gives a little bit extra speed. + However if options are changed, it can be necessary to delete the config.cache + file. -\newline +\layout Section +Install paths +\added_space_bottom medskip +\begin_inset LatexCommand \label{sub:Install-paths} -\family typewriter -for ( = ; [< | <=] ; [++ | - += 1]) -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - -\layout Itemize +\end_inset -The does not contain -\begin_inset Quotes eld -\end_inset -continue -\begin_inset Quotes erd -\end_inset +\begin_inset LatexCommand \index{Install paths} - or 'break -\begin_inset Quotes erd -\end_inset +\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 +\layout Standard +\align center +\begin_inset Tabular + + + + + + + + +\begin_inset Text -The loop control variable does NOT participate in any arithmetic operation - within the loop. -\layout Itemize +\layout Standard -There are NO switch statements in the loop. -\layout Subsubsection +\series bold +Description + +\end_inset + + +\begin_inset Text -Algebraic Simplifications \layout Standard -SDCC does numerous algebraic simplifications, the following is a small sub-set - of these optimizations. -\newline +\series bold +Path -\newline +\end_inset + + +\begin_inset Text -\family typewriter -i = j + 0 ; /* changed to */ i = j; -\newline -i /= 2; /* changed to */ i >>= 1; -\newline -i = j - j ; /* changed to */ i = 0; -\newline -i = j / 1 ; /* changed to */ i = j; -\family default +\layout Standard -\newline +\series bold +Default -\newline -Note the subexpressions given above are generally introduced by macro expansions - or as a result of copy/constant propagation. -\layout Subsubsection +\end_inset + + +\begin_inset Text -'switch' Statements \layout Standard -SDCC changes switch statements to jump tables when the following conditions - are true. - -\layout Itemize +\series bold +Win32 builds -The case labels are in numerical sequence, the labels need not be in order, - and the starting number need not be one or zero. -\newline +\end_inset + + + + +\begin_inset Text -\newline +\layout Standard +Binary files* -\family typewriter -switch(i) {\SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ -switch (i) { -\newline -case 4:... - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ -case 1: ... - -\newline -case 5:... - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ -case 2: ... - -\newline -case 3:... - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ -case 3: ... - -\newline -case 6:... - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ -case 4: ... - -\newline -}\SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ -} -\newline +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\family default -Both the above switch statements will be implemented using a jump-table. -\layout Itemize +\emph on +$EXEC_PREFIX -The number of case labels is at least three, since it takes two conditional - statements to handle the boundary conditions. -\layout Itemize +\end_inset + + +\begin_inset Text -The number of case labels is less than 84, since each label takes 3 bytes - and a jump-table can be utmost 256 bytes long. - \layout Standard +/usr/local/bin -Switch statements which have gaps in the numeric sequence or those that - have more that 84 case labels can be split into more than one switch statement - for efficient code generation, e.g.: -\newline +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\family typewriter -switch (i) { -\newline -case 1: ... - -\newline -case 2: ... - -\newline -case 3: ... - -\newline -case 4: ... - -\newline -case 9: ... - -\newline -case 10: ... - -\newline -case 11: ... - -\newline -case 12: ... - -\newline -} -\family default +\backslash +sdcc +\backslash +bin + +\end_inset + + + + +\begin_inset Text -\newline +\layout Standard +Include files -\newline -If the above switch statement is broken down into two switch statements -\newline +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\family typewriter -switch (i) { -\newline -case 1: ... - -\newline -case 2: ... - -\newline -case 3: ... - -\newline -case 4: ... - -\newline -} -\newline +\emph on +$DATADIR/ $INCLUDE_DIR_SUFFIX -\newline +\end_inset + + +\begin_inset Text -\family default -and -\family typewriter +\layout Standard +/usr/local/share/sdcc/include -\newline +\end_inset + + +\begin_inset Text -\newline -switch (i) { -\newline -case 9: \SpecialChar ~ -... - -\newline -case 10: ... - -\newline -case 11: ... - -\newline -case 12:\SpecialChar ~ -... - -\newline -} -\newline +\layout Standard -\newline +\backslash +sdcc +\backslash +include -\family default -then both the switch statements will be implemented using jump-tables whereas - the unmodified switch statement will not be. -\layout Subsubsection +\end_inset + + + + +\begin_inset Text -Bit-shifting Operations. \layout Standard +Library file** -Bit shifting is one of the most frequently used operation in embedded programmin -g. - SDCC tries to implement bit-shift operations in the most efficient way - possible, e.g.: -\newline +\end_inset + + +\begin_inset Text -\family typewriter +\layout Standard -\newline -unsigned char i; -\newline -... - -\newline -i>>= 4; -\newline -... -\newline +\emph on +$DATADIR/$LIB_DIR_SUFFIX -\family default +\end_inset + + +\begin_inset Text -\newline -generates the following code: -\newline +\layout Standard +/usr/local/share/sdcc/lib + +\end_inset + + +\begin_inset Text -\family typewriter +\layout Standard -\newline -mov a,_i -\newline -swap a -\newline -anl a,#0x0f -\newline -mov _i,a -\family default +\backslash +sdcc +\backslash +lib -\newline +\end_inset + + + + +\begin_inset Text -\newline -In general SDCC will never setup a loop if the shift count is known. - Another example: -\newline +\layout Standard +Documentation -\newline +\end_inset + + +\begin_inset Text -\family typewriter -unsigned int i; -\newline -... - -\newline -i >>= 9; -\newline -... -\family default +\layout Standard -\newline +\emph on +$DOCDIR -\newline -will generate: -\newline - -\newline - -\family typewriter -mov a,(_i + 1) -\newline -mov (_i + 1),#0x00 -\newline -clr c -\newline -rrc a -\newline -mov _i,a -\family default - -\newline - -\newline -Note that SDCC stores numbers in little-endian format (i.e. - lowest order first). -\layout Subsubsection +\end_inset + + +\begin_inset Text -Bit-rotation \layout Standard +/usr/local/share/sdcc/doc -A special case of the bit-shift operation is bit rotation, SDCC recognizes - the following expression to be a left bit-rotation: -\newline +\end_inset + + +\begin_inset Text -\newline +\layout Standard -\family typewriter -unsigned char i; -\newline -... - -\newline -i = ((i << 1) | (i >> 7)); -\family default +\backslash +sdcc +\backslash +doc -\newline -... -\newline +\end_inset + + + -\newline -will generate the following code: -\newline +\end_inset -\newline -\family typewriter -mov a,_i -\newline -rl a -\newline -mov _i,a -\family default -\newline +\layout Verse -\newline -SDCC uses pattern matching on the parse tree to determine this operation.Variatio -ns of this case will also be recognized as bit-rotation, i.e.: -\newline +\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 -\newline +\layout Standard +\noindent +The install paths can still be changed during `make install` with e.g.: -\family typewriter -i = ((i >> 7) | (i << 1)); /* left-bit rotation */ -\layout Subsubsection +\layout LyX-Code +make install prefix=$(HOME)/local/sdcc -Highest Order Bit \layout Standard +Of course this doesn't change the search paths compiled into the binaries. +\newline -It is frequently required to obtain the highest order bit of an integral - type (long, int, short or char types). - SDCC recognizes the following expression to yield the highest order bit - and generates optimized code for it, e.g.: -\newline +\newline +Moreove +r the install path can be changed by defining DESTDIR +\begin_inset LatexCommand \index{DESTDIR} -\newline - -\family typewriter -unsigned int gint; -\newline +\end_inset -\newline -foo () { -\newline -unsigned char hob; -\newline -\SpecialChar ~ -\SpecialChar ~ -... - -\newline -\SpecialChar ~ -\SpecialChar ~ -hob = (gint >> 15) & 1; -\newline -\SpecialChar ~ -\SpecialChar ~ -.. +: + +\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 +italics +\emph default +, see section above). + Further search paths are determined by environment variables during runtime. -\newline -} -\family default +\newline +The paths searched when running the compiler are as follows (the first + catch wins): +\newline -\newline +\newline +1. + Binary files (preprocessor, assembler and linker) +\newline -\newline -will generate the following code: -\newline -\family typewriter +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - 61 ;\SpecialChar ~ - hob.c 7 -\newline -\SpecialChar ~ +\layout Standard +Search path + +\end_inset + + +\begin_inset Text + +\layout Standard +default + +\end_inset + + +\begin_inset Text + +\layout Standard +Win32 builds + +\end_inset + + + + +\begin_inset Text + +\layout Standard +$SDCC_HOME/ +\emph on +$PPREFIX2BIN_DIR + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_HOME/bin + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_HOME +\backslash +bin + +\end_inset + + + + +\begin_inset Text + +\layout Standard +Path of argv[0] (if available) + +\end_inset + + +\begin_inset Text + +\layout Standard +Path of argv[0] + +\end_inset + + +\begin_inset Text + +\layout Standard +Path of argv[0] + +\end_inset + + + + +\begin_inset Text + +\layout Standard +$PATH + +\end_inset + + +\begin_inset Text + +\layout Standard +$PATH + +\end_inset + + +\begin_inset Text + +\layout Standard +$PATH + +\end_inset + + + + +\end_inset + + +\newline + + +\layout Standard +\noindent +2. + Include files +\newline + + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard +Search path + +\end_inset + + +\begin_inset Text + +\layout Standard +default + +\end_inset + + +\begin_inset Text + +\layout Standard +Win32 builds + +\end_inset + + + + +\begin_inset Text + +\layout Standard +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-I dir + +\end_inset + + +\begin_inset Text + +\layout Standard +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-I dir + +\end_inset + + +\begin_inset Text + +\layout Standard +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-I dir + +\end_inset + + + + +\begin_inset Text + +\layout Standard +$SDCC_INCLUDE + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_INCLUDE + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_INCLUDE + +\end_inset + + + + +\begin_inset Text + +\layout Standard +$SDCC_HOME/ +\newline + +\emph on +$PREFIX2DATA_DIR/ +\newline +$INCLUDE_DIR_SUFFIX + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_ HOME/ +\newline +share/sdcc/ +\newline +include + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_HOME +\backslash +include + +\end_inset + + + + +\begin_inset Text + +\layout Standard +path(argv[0])/ +\newline + +\emph on +$BIN2DATADIR/ +\emph default + +\newline + +\emph on +$INCLUDE_DIR_SUFFIX + +\end_inset + + +\begin_inset Text + +\layout Standard +path(argv[0])/ +\newline +../sdcc/include +\newline \SpecialChar ~ - 000A E5*01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -4889,7 +2943,6 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 62\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -4897,12 +2950,8 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - mov\SpecialChar ~ - a,(_gint + 1) -\newline \SpecialChar ~ \SpecialChar ~ - 000C 33\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -4917,24 +2966,334 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + + +\end_inset + + +\begin_inset Text + +\layout Standard +path(argv[0]) +\backslash +.. +\backslash +include + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\emph on +$DATADIR/ +\emph default + +\newline + +\emph on +$INCLUDE_DIR_SUFFIX + +\end_inset + + +\begin_inset Text + +\layout Standard +/usr/local/share/sdcc/ +\newline +include + +\end_inset + + +\begin_inset Text + +\layout Standard +(not on Win32) + +\end_inset + + + + +\end_inset + + +\newline + + +\layout Standard +\noindent +The option - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-nostdinc disables the last two search paths. +\newline + +\newline +3. + Library files +\newline + + +\layout Standard +With the exception of +\begin_inset Quotes sld +\end_inset + +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-L dir +\begin_inset Quotes srd +\end_inset + + the +\shape italic +model +\shape default + is auto-appended by the compiler (e.g. + small, large, z80, ds390 etc.). + +\newline + + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard +Search path + +\end_inset + + +\begin_inset Text + +\layout Standard +default + +\end_inset + + +\begin_inset Text + +\layout Standard +Win32 builds + +\end_inset + + + + +\begin_inset Text + +\layout Standard +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-L dir + +\end_inset + + +\begin_inset Text + +\layout Standard +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-L dir + +\end_inset + + +\begin_inset Text + +\layout Standard +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-L dir + +\end_inset + + + + +\begin_inset Text + +\layout Standard +$SDCC_LIB/ +\newline + +\emph on + + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_LIB/ +\newline + +\emph on + + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_LIB +\backslash + +\newline + +\emph on + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +$SDCC_HOME/ +\newline + +\emph on +$PREFIX2DATA_DIR/ +\newline +$LIB_DIR_SUFFIX/ + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_HOME/ +\newline +share/sdcc/ +\newline +lib/ +\emph on + + +\end_inset + + +\begin_inset Text + +\layout Standard +$SDCC_HOME +\backslash +lib +\backslash + +\emph on + +\newline + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +path(argv[0])/ +\newline + +\emph on +$BIN2DATADIR/ +\emph default + +\newline + +\emph on +$LIB_DIR_SUFFIX/ + +\end_inset + + +\begin_inset Text + +\layout Standard +path(argv[0])/ +\newline +../sdcc/lib/ +\emph on + +\newline \SpecialChar ~ \SpecialChar ~ -\SpecialChar ~ - 63\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - rlc\SpecialChar ~ - a -\newline -\SpecialChar ~ -\SpecialChar ~ - 000D E4\SpecialChar ~ -\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -4951,7 +3310,6 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 64\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -4959,12 +3317,8 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - clr\SpecialChar ~ - a -\newline \SpecialChar ~ \SpecialChar ~ - 000E 13\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -4977,12 +3331,31 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + + +\end_inset + + +\begin_inset Text + +\layout Standard +path(argv[0]) +\backslash + +\newline +.. +\backslash +lib +\backslash + +\emph on + +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 65\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -4990,12 +3363,8 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - rrc\SpecialChar ~ - a -\newline \SpecialChar ~ \SpecialChar ~ - 000F F5*02\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -5010,7 +3379,6 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 66\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -5018,692 +3386,753 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - mov\SpecialChar ~ - _foo_hob_1_1,a -\newline -\newline -\family default -Variations of this case however will -\emph on -not -\emph default - be recognized. - It is a standard C expression, so I heartily recommend this be the only - way to get the highest order bit, (it is portable). - Of course it will be recognized even if it is embedded in other expressions, - e.g.: -\newline +\end_inset + + + + +\begin_inset Text + +\layout Standard -\newline +\emph on +$DATADIR/ +\newline +$LIB_DIR_SUFFIX/ -\family typewriter -xyz = gint + ((gint >> 15) & 1); -\family default +\end_inset + + +\begin_inset Text -\newline +\layout Standard +/usr/local/share/sdcc/ +\newline +lib/ +\emph on + -\newline -will still be recognized. -\layout Subsubsection +\end_inset + + +\begin_inset Text -Peep-hole Optimizer \layout Standard +(not on Win32) -The compiler uses a rule based, pattern matching and re-writing mechanism - for peep-hole optimization. - It is inspired by -\emph on -copt -\emph default - a peep-hole optimizer by Christopher W. - Fraser (cwfraser@microsoft.com). - A default set of rules are compiled into the compiler, additional rules - may be added with the -\emph on ---peep-file -\emph default - option. - The rule language is best illustrated with examples. -\newline +\end_inset + + + -\newline +\end_inset -\family typewriter -replace { -\newline -\SpecialChar ~ -\SpecialChar ~ -mov %1,a -\newline -\SpecialChar ~ -\SpecialChar ~ -mov a,%1 -\newline -} by { -\newline -\SpecialChar ~ -\SpecialChar ~ -mov %1,a -\newline -} -\family default -\newline +\newline -\newline -The above rule will change the following assembly sequence: -\newline -\newline +\layout Standard +\begin_inset Note +collapsed true -\family typewriter -\SpecialChar ~ -\SpecialChar ~ -mov r1,a -\newline -\SpecialChar ~ -\SpecialChar ~ -mov a,r1 -\family default +\layout Standard +Don't delete any of the stray spaces in the table above without checking + the HTML output (last line)! -\newline +\end_inset -\newline -to -\newline -\newline -\family typewriter -mov r1,a -\family default +\layout Standard +\SpecialChar ~ -\newline +\newline +The option - +\begin_inset ERT +status Collapsed -\newline -Note: All occurrences of a -\emph on -%n -\emph default - (pattern variable) must denote the same string. - With the above rule, the assembly sequence: -\newline +\layout Standard -\newline -\family typewriter -\SpecialChar ~ -\SpecialChar ~ -mov r1,a -\newline -\SpecialChar ~ -\SpecialChar ~ -mov a,r2 -\family default +\backslash +/ -\newline +\end_inset -\newline -will remain unmodified. -\newline +-nostdlib disables the last two search paths. -\newline -Other special case optimizations may be added by the user (via -\emph on ---peep-file option -\emph default -). - E.g. - some variants of the 8051 MCU allow only -\family typewriter -ajmp -\family default - and -\family typewriter -acall -\family default -. - The following two rules will change all -\family typewriter -ljmp -\family default - and -\family typewriter -lcall -\family default - to -\family typewriter -ajmp -\family default - and -\family typewriter -acall -\family default +\layout Section +Building SDCC +\begin_inset LatexCommand \index{Building SDCC} -\newline +\end_inset -\newline -\family typewriter -replace { lcall %1 } by { acall %1 } -\newline -replace { ljmp %1 } by { ajmp %1 } -\family default -\newline +\layout Subsection +Building SDCC on Linux +\begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux} -\newline -The -\emph on -inline-assembler code -\emph default - is also passed through the peep hole optimizer, thus the peephole optimizer - can also be used as an assembly level macro expander. - The rules themselves are MCU dependent whereas the rule language infra-structur -e is MCU independent. - Peephole optimization rules for other MCU can be easily programmed using - the rule language. -\newline +\end_inset -\newline -The syntax for a rule is as follows: -\newline -\newline -\family typewriter -rule := replace [ restart ] '{' ' -\backslash -n' -\newline -\SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - '}' by '{' ' -\backslash -n' -\newline -\SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - ' -\backslash -n' -\newline -\SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - '}' [if ] ' -\backslash -n' -\newline +\layout Enumerate -\family default +\series medium +Download the source package +\series default + either from the SDCC Subversion repository or from the nightly snapshots +\series medium +, it will be named something like sdcc +\series default +.src +\series medium +.t +\series default +ar. +\series medium +gz +\series default + +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php} -\newline - := assembly instruction (each instruction including - labels must be on a separate line). -\newline +\end_inset -\newline -The optimizer will apply to the rules one by one from the top in the sequence - of their appearance, it will terminate when all rules are exhausted. - If the 'restart' option is specified, then the optimizer will start matching - the rules again from the top, this option for a rule is expensive (performance) -, it is intended to be used in situations where a transformation will trigger - the same rule again. - An example of this (not a good one, it has side effects) is the following - rule: -\newline +. -\newline +\layout Enumerate -\family typewriter -replace restart { -\newline -\SpecialChar ~ -\SpecialChar ~ -pop %1 -\newline -\SpecialChar ~ -\SpecialChar ~ -push %1 } by { -\newline -\SpecialChar ~ -\SpecialChar ~ -; nop -\newline -} -\family default +\series medium +Bring up a command line terminal, such as xterm. -\newline +\layout Enumerate -\newline -Note that the replace pattern cannot be a blank, but can be a comment line. - Without the 'restart' option only the inner most 'pop' 'push' pair would - be eliminated, i.e.: -\newline +\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. -\newline +\layout Enumerate +Change directory into the main SDCC directory, for example type: +\family sans +\series bold +"cd sdcc +\series default +". -\family typewriter -\SpecialChar ~ -\SpecialChar ~ -pop ar1 -\newline -\SpecialChar ~ -\SpecialChar ~ -pop ar2 -\newline -\SpecialChar ~ -\SpecialChar ~ -push ar2 -\newline -\SpecialChar ~ -\SpecialChar ~ -push ar1 -\family default +\layout Enumerate -\newline +\series medium +Type +\family sans +\series bold +"./configure +\family default +\series default +". + This configures the package for compilation on your system. -\newline -would result in: -\newline +\layout Enumerate -\newline +\series medium +Type +\family sans +\series bold +"make +\family default +\series default +" +\series medium +. -\family typewriter -\SpecialChar ~ -\SpecialChar ~ -pop ar1 -\newline -\SpecialChar ~ -\SpecialChar ~ -; nop -\newline -\SpecialChar ~ -\SpecialChar ~ -push ar1 -\family default +\series default + All of the source packages will compile, this can take a while. -\newline +\layout Enumerate -\newline +\series medium +Type +\family sans +\series bold +"make install" +\family default +\series default + as root +\series medium +. -\emph on -with -\emph default - the restart option the rule will be applied again to the resulting code - and then all the pop-push pairs will be eliminated to yield: -\newline +\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} -\newline +\end_inset -\family typewriter -\SpecialChar ~ -\SpecialChar ~ -; nop -\newline -\SpecialChar ~ -\SpecialChar ~ -; nop -\family default +. -\newline +\layout Subsection +Building SDCC on OSX 2.x -\newline -A conditional function can be attached to a rule. - Attaching rules are somewhat more involved, let me illustrate this with - an example. -\newline +\layout Standard +Follow the instruction for Linux. +\newline -\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: -\family typewriter -replace { -\newline -\SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ -ljmp %5 -\newline -%2: -\newline -} by { -\newline -\SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ -sjmp %5 -\newline -%2: -\newline -} if labelInRange -\family default +\layout LyX-Code +./configure CC=gcc2 CXX=g++2 -\newline +\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'. -\newline -The optimizer does a look-up of a function name table defined in function - -\emph on -callFuncByName -\emph default - in the source file SDCCpeeph.c, with the name -\emph on -labelInRange -\emph default -. - If it finds a corresponding entry the function is called. - Note there can be no parameters specified for these functions, in this - case the use of -\emph on -%5 -\emph default - is crucial, since the function -\emph on -labelInRange -\emph default - expects to find the label in that particular variable (the hash table containin -g the variable bindings is passed as a parameter). - If you want to code more such functions, take a close look at the function - labelInRange and the calling mechanism in source file SDCCpeeph.c. - I know this whole thing is a little kludgey, but maybe some day we will - have some better means. - If you are looking at this file, you will also see the default rules that - are compiled into the compiler, you can add your own rules in the default - set there if you get tired of specifying the --peep-file option. \layout Subsection +Building SDCC using Cygwin and Mingw32 -Pragmas \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 +\end_inset + +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! -SDCC supports the following #pragma directives. - This directives are applicable only at a function level. \layout Itemize +flex -SAVE - this will save all the current options. \layout Itemize +bison -RESTORE - will restore the saved options from the last save. - Note that SAVES & RESTOREs cannot be nested. - SDCC uses the same buffer to save the options each time a SAVE is called. \layout Itemize +gcc ; version 3.x is fine, no need to use the old 2.9x -NOGCSE - will stop global subexpression elimination. \layout Itemize +binutils ; selected with gcc -NOINDUCTION - will stop loop induction optimizations. \layout Itemize +make -NOJTBOUND - will not generate code for boundary value checking, when switch - statements are turned into jump-tables. \layout Itemize +rxvt ; a nice console, which makes life much easier under windoze (see below) -NOOVERLAY - the compiler will not overlay the parameters and local variables - of a function. \layout Itemize +man ; not really needed for building SDCC, but you'll miss it sooner or + later -NOLOOPREVERSE - Will not do loop reversal optimization \layout Itemize +less ; not really needed for building SDCC, but you'll miss it sooner or + later -EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation - of pair of push/pop instruction in ISR function (using interrupt keyword). - The directive should be placed immediately before the ISR function definition - and it affects ALL ISR functions following it. - To enable the normal register saving for ISR functions use #pragma\SpecialChar ~ -EXCLUDE\SpecialChar ~ -none. \layout Itemize +svn ; only if you use Subversion access -CALLEE-SAVES function1[,function2[,function3...]] - The compiler by default - uses a caller saves convention for register saving across function calls, - however this can cause unneccessary register pushing & popping when calling - small functions from larger functions. - This option can be used to switch the register saving convention for the - function names specified. - The compiler will not save registers when calling these functions, extra - code will be generated at the entry & exit for these functions to save - & restore the registers used by these functions, this can SUBSTANTIALLY - reduce code & improve run time performance of the generated code. - In future the compiler (with interprocedural analysis) will be able to - determine the appropriate scheme to use for each function call. - If --callee-saves command line option is used, the function names specified - in #pragma\SpecialChar ~ -CALLEE-SAVES is appended to the list of functions specified inthe - command line. \layout Standard +If you want to develop something you'll need: -The pragma's are intended to be used to turn-off certain optimizations which - might cause the compiler to generate extra stack / data space to store - compiler generated temporary variables. - This usually happens in large functions. - Pragma directives should be used as shown in the following example, they - are used to control options & optimizations for a given function; pragmas - should be placed before and/or after a function, placing pragma's inside - a function body could have unpredictable results. -\newline +\layout Itemize +python ; for the regression tests + +\layout Itemize +gdb ; the gnu debugger, together with the nice GUI +\begin_inset Quotes sld +\end_inset -\newline +insight +\begin_inset Quotes srd +\end_inset -\family typewriter -#pragma SAVE /* save the current settings */ -\newline -#pragma NOGCSE /* turnoff global subexpression elimination */ -\newline -#pragma NOINDUCTION /* turn off induction optimizations */ -\newline -int foo () -\newline -{ -\newline -\SpecialChar ~ - \SpecialChar ~ - ... + + +\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 + +\layout Standard + + +\backslash +/ + +\end_inset + +-login -i + +\layout Standard +with (one line): + +\layout LyX-Code +rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red + +\layout LyX-Code + -bg black -fg white -geometry 100x65 -e bash - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-login + +\layout Standard +Text selected with the mouse is automatically copied to the clipboard, pasting + works with shift-insert. +\newline + +\newline +The other good tip is to make sure you have no //c/-styl +e paths anywhere, use /cygdrive/c/ instead. + Using // invokes a network lookup which is very slow. + If you think +\begin_inset Quotes sld +\end_inset + +cygdrive +\begin_inset Quotes srd +\end_inset + + is too long, you can change it with e.g. + +\layout LyX-Code +mount -s -u -c /mnt + +\layout Standard +SDCC sources use the unix line ending LF. + Life is much easier, if you store the source tree on a drive which is mounted + in binary mode. + And use an editor which can handle LF-only line endings. + Make sure not to commit files with windows line endings. + The tabulator spacing +\begin_inset LatexCommand \index{tabulator spacing (8 columns)} + +\end_inset + + 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 + +\series medium +Download the source package +\series default + either from the SDCC Subversion repository or from the +\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php} + +\end_inset + + +\series medium +, it will be named something like sdcc +\series default +.src +\series medium +.tgz. + +\series default + SDCC is distributed with all the projects, workspaces, and files you need + to build it using Visual C++ 6.0/NET (except for SDCDB and ucSim). + The workspace name is 'sdcc.dsw'. + Please note that as it is now, all the executables are created in a folder + called sdcc +\backslash +bin_vc. + Once built you need to copy the executables from sdcc +\backslash +bin_vc to sdcc +\backslash +bin before running SDCC. -\newline +\newline + +\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 + + 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 + +unix2dos +\begin_inset Quotes srd +\end_inset + + utility freely available on the internet. + Doug Hawkins reported in the sdcc-user list that this works: +\newline + +\newline +C: +\backslash +Programming +\backslash +SDCC> unix2dos sdcc.dsw +\newline +C: +\backslash +Programming +\backslash +SDCC> for /R %I in (*.dsp) do @unix2dos "%I" +\newline + +\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 + + +\newline + +\newline +Download the file UnxUtils +\begin_inset LatexCommand \index{UnxUtils} + +\end_inset + +.zip. + Now you have to install the utilities and setup MSVC so it can locate the + required programs. + Here there are two alternatives (choose one!): + +\layout Enumerate +The easy way: +\newline + +\newline +a) Extract UnxUtils.zip to your C: +\backslash + hard disk PRESERVING the original paths, otherwise bison won't work. + (If you are using WinZip make certain that 'Use folder names' is selected) +\newline + +\newline +b) + In the Visual C++ IDE click Tools, Options, select the Directory tab, in + 'Show directories for:' select 'Executable files', and in the directories + window add a new path: 'C: +\backslash +user +\backslash +local +\backslash +wbin', click ok. +\newline + +\newline +(As a side effect, you get a bunch of Unix utilities that + could be useful, such as diff and patch.) + +\layout Enumerate +A more compact way: +\newline + +\newline +This one avoids extracting a bunch of files you may not + use, but requires some extra work: +\newline + +\newline +a) Create a directory were to put the + tools needed, or use a directory already present. + Say for example 'C: +\backslash +util'. +\newline + +\newline +b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and + gawk.exe to such directory WITHOUT preserving the original paths. + (If you are using WinZip make certain that 'Use folder names' is not selected) +\newline + +\newline +c +) Rename bison.exe to '_bison.exe'. +\newline + +\newline +d) Create a batch file 'bison.bat' in 'C: +\backslash +util +\backslash +' and add these lines: +\newline \SpecialChar ~ - \SpecialChar ~ - /* large code */ -\newline \SpecialChar ~ - \SpecialChar ~ - ... - -\newline -} -\newline -#pragma RESTORE /* turn the optimizations back on */ -\family default +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 +\newline +e +) In the Visual C++ IDE click Tools, Options, select the Directory tab, + in 'Show directories for:' select 'Executable files', and in the directories + window add a new path: 'c: +\backslash +util', click ok. + Note that you can use any other path instead of 'c: +\backslash +util', even the path where the Visual C++ tools are, probably: 'C: +\backslash +Program Files +\backslash +Microsoft Visual Studio +\backslash +Common +\backslash +Tools'. + So you don't have to execute step 'e' :) + +\layout Standard +That is it. + Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy + the executables from sdcc +\backslash +bin_vc to sdcc +\backslash +bin, and you can compile using SDCC. -\newline -The compiler will generate a warning message when extra space is allocated. - It is strongly recommended that the SAVE and RESTORE pragma's be used when - changing options for a function. \layout Subsection +Building SDCC Using Borland +\layout Enumerate +From the sdcc directory, run the command "make -f Makefile.bcc". + This should regenerate all the .exe files in the bin directory except for + SDCDB and ucSim. -\emph on - -\emph default - Library Routines \layout Enumerate +If you modify any source files and need to rebuild, be aware that the dependenci +es may not be correctly calculated. + The safest option is to delete all .obj files and run the build again. + From a Cygwin BASH prompt, this can easily be done with the command (be + sure you are in the sdcc directory): +\newline + +\newline + +\family sans +\series bold +find . + +\backslash +( -name '*.obj' -o -name '*.lib' -o -name '*.rul' +\backslash +) -print -exec rm {} +\backslash +; +\family default +\series default + +\newline + +\newline +or on Windows NT/2000/XP from the command prompt with the command: +\newline + +\family sans +\series bold + +\newline +del /s *.obj *.lib *.rul +\family default +\series default + from the sdcc directory. + +\layout Subsection +Windows Install Using a ZIP Package -Compiler support routines (_gptrget, _mulint etc) \layout Enumerate +Download the binary zip package from +\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php} + +\end_inset + + and unpack it using your favorite unpacking tool (gunzip, WinZip, etc). + This should unpack to a group of sub-directories. + An example directory structure after unpacking the mingw32 package is: + c: +\backslash +sdcc +\backslash +bin for the executables, c: +\backslash +sdcc +\backslash +include and c: +\backslash +sdcc +\backslash +lib for the include and libraries. -Stdclib functions (puts, printf, strcat etc) \layout Enumerate +Adjust your environment variable PATH to include the location of the bin + directory or start sdcc using the full path. -Math functions (sin, pow, sqrt etc) \layout Subsection +Windows Install Using the Setup Program +\begin_inset LatexCommand \label{sub:Windows-Install} -Interfacing with Assembly Routines -\layout Subsubsection +\end_inset -Global Registers used for Parameter Passing -\layout Standard -The compiler always uses the global registers -\emph on -DPL,DPH,B -\emph default -and -\emph on - ACC -\emph default - to pass the first parameter to a routine. - The second parameter onwards is either allocated on the stack (for reentrant - routines or if --stack-auto is used) or in the internal / external ram - (depending on the memory model). - -\layout Subsubsection -Assembler Routine(non-reentrant) \layout Standard +Download the setup program +\emph on +sdcc-x.y.z-setup.exe +\emph default + for an official release from +\newline -In the following example the function cfunc calls an assembler routine asm_func, - which takes two parameters. -\newline +\begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599} -\newline +\end_inset -\family typewriter -extern int asm_func(unsigned char, unsigned char); -\newline + 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} -\newline -int c_func (unsigned char i, unsigned char j) -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -return asm_func(i,j); -\newline -} -\newline +\end_inset -\newline -int main() -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -return c_func(10,9); -\newline -} -\newline + and execute it. + A windows typical installer will guide you through the installation process. -\newline +\layout Subsection +VPATH +\begin_inset LatexCommand \index{VPATH} -\family default -The corresponding assembler function is: -\newline +\end_inset -\newline + feature -\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 ~ +\layout Standard +SDCC supports the VPATH feature provided by configure and make. + It allows to separate the source and build trees. + Here's an example: + +\layout Standard + +\family typewriter +cd ~\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov a,dpl -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -5712,8 +4141,6 @@ mov a,dpl \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -add a,_asm_func_PARM_2 -\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -5722,9 +4149,19 @@ add a,_asm_func_PARM_2 \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov dpl,a -\newline \SpecialChar ~ +# cd $HOME + +\layout Standard + +\family typewriter +tar -xzf sdcc.src.tar.gz\SpecialChar ~ +# extract source to directory sdcc + +\layout Standard + +\family typewriter +mkdir sdcc.build\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -5732,9 +4169,18 @@ mov dpl,a \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -mov dpl,#0x00 -\newline \SpecialChar ~ +# put output in sdcc.build + +\layout Standard + +\family typewriter +cd sdcc.build + +\layout Standard + +\family typewriter +../sdcc/configure\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -5742,1223 +4188,27121 @@ mov dpl,#0x00 \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -ret -\newline +# configure is doing all the magic! -\newline - -\family default -Note here that the return values are placed in 'dpl' - One byte return value, - 'dpl' LSB & 'dph' MSB for two byte values. - 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph',' -b' & 'acc' for four byte values. \layout Standard -The parameter naming convention is __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 +\family typewriter +make -dpl -\begin_inset Quotes erd -\end_inset +\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! - for One bye parameter, -\begin_inset Quotes eld -\end_inset +\layout Section +Building the Documentation -dptr -\begin_inset Quotes erd -\end_inset +\layout Standard +Add - +\begin_inset ERT +status Collapsed - if two bytes, -\begin_inset Quotes eld -\end_inset +\layout Standard -b,dptr -\begin_inset Quotes erd -\end_inset - for three bytes and -\begin_inset Quotes eld -\end_inset +\backslash +/ -acc,b,dptr -\begin_inset Quotes erd -\end_inset +\end_inset - for four bytes, the varible name for the second parameter will be __PARM_2. -\newline +-enable-doc to the configure arguments to build the documentation together + with all the other stuff. + You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf, + dvips and makeindex) to get the job done. + Another possibility is to change to the doc directory and to type +\family sans +\series bold -\newline -Assemble the assembler routine with the following command: -\newline +\begin_inset Quotes srd +\end_inset -\newline +make +\begin_inset Quotes srd +\end_inset -\family sans -\series bold -asx8051 -losg asmfunc.asm -\newline -\newline +\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} -\family default -\series default -Then compile and link the assembler routine to the C source file with the - following command: -\newline +\end_inset -\newline + as editor is straightforward. + Prebuilt documentation in html and pdf format is available from +\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php} -\family sans -\series bold -sdcc cfunc.c asmfunc.rel -\layout Subsubsection +\end_inset -Assembler Routine(reentrant) -\layout Standard +. -In this case the second parameter onwards will be passed on the stack, the - parameters are pushed from right to left i.e. - after the call the left most parameter will be on the top of the stack. - Here is an example: -\newline +\layout Section +Reading the Documentation +\begin_inset LatexCommand \index{Documentation} -\newline +\end_inset -\family typewriter -extern int asm_func(unsigned char, unsigned char); -\newline -\newline -int c_func (unsigned char i, unsigned char j) reentrant -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -return asm_func(i,j); -\newline -} -\newline -\newline -int main() -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -return c_func(10,9); -\newline -} -\newline +\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 -\family default +\layout Standard +If you should know why please drop us a note -\newline -The corresponding assembler routine is: -\newline +\end_inset -\newline +. + +\newline +You'll find the pdf version +\begin_inset LatexCommand \index{PDF version of this document} -\family typewriter -.globl _asm_func -\newline -_asm_func: -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -push _bp -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov _bp,sp -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov r2,dpl -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov a,_bp -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -clr c -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -add a,#0xfd -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov r0,a -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -add a,#0xfc -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov r1,a -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov a,@r0 -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -add a,r2 -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov dpl,a -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov dph,#0x00 -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -mov sp,_bp -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -pop _bp -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -ret -\newline +\end_inset -\newline + at +\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf} -\family default -The compiling and linking procedure remains the same, however note the extra - entry & exit linkage required for the assembler code, _bp is the stack - frame pointer and is used to compute the offset into the stack for parameters - and local variables. -\layout Subsection +\end_inset -External Stack -\layout Standard +. + +\newline +A html version +\begin_inset LatexCommand \index{HTML version of this document} -The external stack is located at the start of the external ram segment, - and is 256 bytes in size. - When --xstack option is used to compile the program, the parameters and - local variables of all reentrant functions are allocated in this area. - This option is provided for programs with large stack space requirements. - When used with the --stack-auto option, all parameters and local variables - are allocated on the external stack (note support libraries will need to - be recompiled with the same options). -\layout Standard +\end_inset -The compiler outputs the higher order address byte of the external ram segment - into PORT P2, therefore when using the External Stack option, this port - MAY NOT be used by the application program. -\layout Subsection + should be online at +\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html} -ANSI-Compliance -\layout Standard +\end_inset -Deviations from the compliancy. -\layout Itemize +. +\newline +This documentation is in some aspects different from a commercial documentation: + -functions are not always reentrant. \layout Itemize +It tries to document SDCC for several processor architectures in one document + (commercially these probably would be separate documents/products). + This document +\begin_inset LatexCommand \index{Status of documentation} -structures cannot be assigned values directly, cannot be passed as function - parameters or assigned to each other and cannot be a return value from - a function, e.g.: -\family typewriter +\end_inset -\newline - -\newline -struct s { ... - }; -\newline -struct s s1, s2; -\newline -foo() -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -... - -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -... - -\newline -} -\newline -struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in - ANSI */ -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -struct s rets; -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -... - -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -return rets;/* is invalid in SDCC although allowed in ANSI */ -\newline -} -\layout Itemize + currently matches SDCC for mcs51 and DS390 best and does give too few informati +on about f.e. + Z80, PIC14, PIC16 and HC08. -'long long' (64 bit integers) not supported. \layout Itemize +There are many references pointing away from this documentation. + Don't let this distract you. + If there f.e. + was a reference like +\begin_inset LatexCommand \url{http://www.opencores.org} -'double' precision floating point not supported. -\layout Itemize +\end_inset -No support for setjmp and longjmp (for now). -\layout Itemize + together with a statement +\begin_inset Quotes sld +\end_inset + +some processors which are targetted by SDCC can be implemented in a +\emph on +f +\emph default +ield +\emph on +p +\emph default +rogrammable +\emph on +g +\emph default +ate +\emph on +a +\emph default +rray +\begin_inset LatexCommand \index{FPGA (field programmable gate array)} + +\end_inset -Old K&R style function declarations are NOT allowed. -\newline -\family typewriter +\begin_inset Quotes srd +\end_inset -\newline -foo(i,j) /* this old style of function declarations */ -\newline -int i,j; /* are valid in ANSI but not valid in SDCC */ -\newline -{ -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -... - -\newline -} -\layout Itemize + or +\begin_inset LatexCommand \url{http://sf.net/projects/fpgac} -functions declared as pointers must be dereferenced during the call. -\newline +\end_inset -\family typewriter -\newline -int (*foo)(); -\newline -... - -\newline -/* has to be called like this */ -\newline -(*foo)(); /* ansi standard allows calls to be made like 'foo()' */ -\layout Subsection +\begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)} -Cyclomatic Complexity -\layout Standard +\end_inset -Cyclomatic complexity of a function is defined as the number of independent - paths the program can take during execution of the function. - This is an important number since it defines the number test cases you - have to generate to validate the function. - The accepted industry standard for complexity number is 10, if the cyclomatic - complexity reported by SDCC exceeds 10 you should think about simplification - of the function logic. - Note that the complexity level is not related to the number of lines of - code in a function. - Large functions can have low complexity, and small functions can have large - complexity levels. -\newline - -\newline -SDCC uses the following formula to compute the complexity: -\newline - -\layout Standard - -complexity = (number of edges in control flow graph) - (number of nodes - in control flow graph) + 2; -\newline +\begin_inset Quotes sld +\end_inset -\newline -Having said that the industry standard is 10, you should be aware that in - some cases it be may unavoidable to have a complexity level of less than - 10. - For example if you have switch statement with more than 10 case labels, - each case label adds one to the complexity level. - The complexity level is by no means an absolute measure of the algorithmic - complexity of the function, it does however provide a good starting point - for which functions you might look at for further optimization. -\layout Section +have you ever heard of an open source compiler that compiles a subset of + C for an FPGA? +\begin_inset Quotes srd +\end_inset -TIPS -\layout Standard + we expect you to have a quick look there and come back. + If you read this you are on the right track. -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 +Some sections attribute more space to problems, restrictions and warnings + than to the solution. -Use the smallest data type to represent your data-value. - If it is known in advance that the value is going to be less than 256 then - use a 'char' instead of a 'short' or 'int'. \layout Itemize +The installation section and the section about the debugger is intimidating. -Use unsigned when it is known in advance that the value is not going to - be negative. - This helps especially if you are doing division or multiplication. \layout Itemize +There are still lots of typos and there are more different writing styles + than pictures. -NEVER jump into a LOOP. -\layout Itemize +\layout Section +Testing the SDCC Compiler +\begin_inset LatexCommand \label{sec:Testing-the-SDCC} -Declare the variables to be local whenever possible, especially loop control - variables (induction). -\layout Itemize +\end_inset -Since the compiler does not do implicit integral promotion, the programmer - should do an explicit cast when integral promotion is required. -\layout Itemize -Reducing the size of division, multiplication & modulus operations can reduce - code size substantially. - Take the following code for example. -\family typewriter -\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 - +\begin_inset ERT +status Collapsed -\newline -foobar(unsigned int p1, unsigned char ch) -\newline -{ -\newline - unsigned char ch1 = p1 % ch ; -\newline - .... - -\newline -} -\newline +\layout Standard -\family default -\newline -For the modulus operation the variable ch will be promoted to unsigned int - first then the modulus operation will be performed (this will lead to a - call to support routine _moduint()), and the result will be casted to a - char. - If the code is changed to -\newline +\backslash +/ -\family typewriter +\end_inset -\newline -foobar(unsigned int p1, unsigned char ch) -\newline -{ -\newline - unsigned char ch1 = (unsigned char)p1 % ch ; -\newline - .... - -\newline -} -\newline +-version" +\begin_inset LatexCommand \index{version} -\family default +\end_inset -\newline -It would substantially reduce the code generated (future versions of the - compiler will be smart enough to detect such optimization oppurtunities). -\layout Subsection -Notes on MCS51 memory layout +\family default +\series default + at the prompt, and the program should run and output its version like: + +\newline + +\family typewriter +SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006) + (UNIX) + \layout Standard +If it doesn't run, or gives a message about not finding sdcc program, then + you need to check over your installation. + Make sure that the sdcc bin directory is in your executable search path + defined by the PATH environment setting ( +\series medium +see +\series default +section +\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting} -The 8051 family of micro controller have a minimum of 128 bytes of internal - memory which is structured as follows -\newline +\end_inset -\newline -- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7 - -\newline -- Bytes 20-2F - 16 bytes to hold 128 bit variables and -\newline -- Bytes 30-7F - 60 bytes for general purpose use. -\newline +\SpecialChar ~ -\newline -Normally the SDCC compiler will only utilise the first bank of registers, - but it is possible to specify that other banks of registers should be used - in interrupt routines. - By default, the compiler will place the stack after the last bank of used - registers, i.e. - if the first 2 banks of registers are used, it will position the base of - the internal stack at address 16 (0X10). - This implies that as the stack grows, it will use up the remaining register - banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for - general purpose use. -\layout Standard +\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 -By default, the compiler uses the 60 general purpose bytes to hold "near - data". - The compiler/optimiser may also declare some Local Variables in this area - to hold local data. - -\layout Standard +\newline -If any of the 128 bit variables are used, or near data is being used then - care needs to be taken to ensure that the stack does not grow so much that - it starts to over write either your bit variables or "near data". - There is no runtime checking to prevent this from happening. -\layout Standard +\series medium +SDCC +\series default +is commonly installed as described in section +\begin_inset Quotes sld +\end_inset -The amount of stack being used is affected by the use of the "internal stack" - to save registers before a subroutine call is made (--stack-auto will declare - parameters and local variables on the stack) and the number of nested subroutin -es. -\layout Standard +Install and search paths +\begin_inset Quotes srd +\end_inset -If you detect that the stack is over writing you data, then the following - can be done. - --xstack will cause an external stack to be used for saving registers and - (if --stack-auto is being used) storing parameters and local variables. - However this will produce more code which will be slower to execute. - -\layout Standard +. +\newline ---stack-loc will allow you specify the start of the stack, i.e. - you could start it after any data in the general purpose area. - However this may waste the memory not used by the register banks and if - the size of the "near data" increases, it may creep into the bottom of - the stack. -\layout Standard +\newline ---stack-after-data, similar to the --stack-loc, but it automatically places - the stack after the end of the "near data". - Again this could waste any spare register space. -\layout Standard +\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 ---data-loc allows you to specify the start address of the near data. - This could be used to move the "near data" further away from the stack - giving it more room to grow. - This will only work if no bit variables are being used and the stack can - grow to use the bit variable space. -\newline +\family typewriter +char test; +\newline -\newline -Conclusion. -\newline +\newline +void main(void) { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +test=0; +\newline +} -\newline -If you find that the stack is over writing your bit variables or "near data" - then the approach which best utilised the internal memory is to position - the "near data" after the last bank of used registers or, if you use bit - variables, after the last bit variable by using the --data-loc, e.g. - if two register banks are being used and no bit variables, --data-loc 16, - and use the --stack-after-data option. \layout Standard -If bit variables are being used, another method would be to try and squeeze - the data area in the unused register banks if it will fit, and start the - stack after the last bit variable. -\layout Section +\series medium +Compile this using the following command: +\family sans +\series bold +"sdcc -c test.c". -Retargetting for other MCUs. -\layout Standard +\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 -The issues for retargetting the compiler are far too numerous to be covered - by this document. - What follows is a brief description of each of the seven phases of the - compiler and its MCU dependency. -\layout Itemize +\newline -Parsing the source and building the annotated parse tree. - This phase is largely MCU independent (except for the language extensions). - Syntax & semantic checks are also done in this phase, along with some initial - optimizations like back patching labels and the pattern matching optimizations - like bit-rotation etc. -\layout Itemize +\newline -The second phase involves generating an intermediate code which can be easy - manipulated during the later phases. - This phase is entirely MCU independent. - The intermediate code generation assumes the target machine has unlimited - number of registers, and designates them with the name iTemp. - The compiler can be made to dump a human readable form of the code generated - by using the --dumpraw option. -\layout Itemize +\series medium +The next step is to try it with the linker. + Type in +\family sans +\series bold +"sdcc test.c +\family default +\series default +" +\series medium +. + If all goes well the compiler will link with the libraries and produce + a test.ihx output file. + If this step fails +\series default + +\series medium +(no test.ihx, and the linker generates warnings), then the problem is most + likely that +\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} -This phase does the bulk of the standard optimizations and is also MCU independe -nt. - This phase can be broken down into several sub-phases: -\newline - -\newline -Break down intermediate code (iCode) into basic blocks. -\newline -Do control flow & data flow analysis on the basic blocks. -\newline -Do local common subexpression elimination, then global subexpression elimination -\newline -Dead code elimination -\newline -Loop optimizations -\newline -If loop optimizations caused any changes then do 'global subexpression eliminati -on' and 'dead code elimination' again. -\layout Itemize +\end_inset -This phase determines the live-ranges; by live range I mean those iTemp - variables defined by the compiler that still survive after all the optimization -s. - Live range analysis is essential for register allocation, since these computati -on determines which of these iTemps will be assigned to registers, and for - how long. -\layout Itemize +\SpecialChar ~ -Phase five is register allocation. - There are two parts to this process. -\newline +\series medium +Install trouble-shooting for suggestions). +\series default -\newline -The first part I call 'register packing' (for lack of a better term). - In this case several MCU specific expression folding is done to reduce - register pressure. -\newline +\newline -\newline -The second part is more MCU independent and deals with allocating registers - to the remaining live ranges. - A lot of MCU specific code does creep into this phase because of the limited - number of index registers available in the 8051. -\layout Itemize +\newline -The Code generation phase is (unhappily), entirely MCU dependent and very - little (if any at all) of this code can be reused for other MCU. - However the scheme for allocating a homogenized assembler operand for each - iCode operand may be reused. -\layout Itemize +\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: -As mentioned in the optimization section the peep-hole optimizer is rule - based system, which can reprogrammed for other MCUs. -\layout Section +\layout Verse -SDCDB - Source Level Debugger -\layout Standard +\family typewriter +#include +\newline -SDCC is distributed with a source level debugger. - The debugger uses a command line interface, the command repertoire of the - debugger has been kept as close to gdb (the GNU debugger) as possible. - The configuration and build process is part of the standard compiler installati -on, which also builds and installs the debugger in the target directory - specified during configuration. - The debugger allows you debug BOTH at the C source and at the ASM source - level. -\layout Subsection +\newline +char str1[10]; +\newline + +\newline +void main(void) { +\newline +\SpecialChar ~ +\SpecialChar ~ +strcpy(str1, "testing"); +\newline +} -Compiling for Debugging \layout Standard -The \SpecialChar \- -\SpecialChar \- -debug option must be specified for all files for which debug information - is to be generated. - The complier generates a .cdb file for each of these files. - The linker updates the .cdb file with the address information. - This .cdb is used by the debugger. -\layout Subsection +\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} -How the Debugger Works -\layout Standard +\end_inset -When the --debug option is specified the compiler generates extra symbol - information some of which are put into the the assembler source and some - are put into the .cdb file, the linker updates the .cdb file with the address - information for the symbols. - The debugger reads the symbolic information generated by the compiler & - the address information generated by the linker. - It uses the SIMULATOR (Daniel's S51) to execute the program, the program - execution is controlled by the debugger. - When a command is issued for the debugger, it translates it into appropriate - commands for the simulator. -\layout Subsection +\SpecialChar ~ -Starting the Debugger -\layout Standard +\series medium +Install trouble-shooting section for suggestions). -The debugger can be started using the following command line. - (Assume the file you are debugging has the file name foo). -\newline +\series default + Use option +\series bold +- +\begin_inset ERT +status Collapsed -\newline +\layout Standard -\family sans -\series bold -sdcdb foo -\newline -\family default -\series default +\backslash +/ -\newline -The debugger will look for the following files. -\layout Itemize +\end_inset -foo.c - the source file. -\layout Itemize +-print-search-dirs +\series default -foo.cdb - the debugger symbol information file. -\layout Itemize +\begin_inset LatexCommand \index{-\/-print-search-dirs} -foo.ihx - the intel hex format object file. -\layout Subsection +\end_inset -Command Line Options. -\layout Itemize + to find exactly where SDCC is looking for the include and lib files. ---directory= this option can used to specify the - directory search list. - The debugger will look into the directory list specified for source, cdb - & ihx files. - The items in the directory list must be separated by ':', e.g. - if the source files can be in the directories /home/src1 and /home/src2, - the --directory option should be --directory=/home/src1:/home/src2. - Note there can be no spaces in the option. - -\layout Itemize +\layout Section +Install Trouble-shooting +\begin_inset LatexCommand \label{sub:Install-Trouble-shooting} --cd - change to the . -\layout Itemize +\end_inset --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 +\begin_inset LatexCommand \index{Install trouble-shooting} + +\end_inset --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 Subsection +If SDCC does not build correctly -Debugger Commands. \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 -As mention earlier the command interface for the debugger has been deliberately - kept as close the GNU debugger gdb, as possible. - This will help the integration with existing graphical user interfaces - (like ddd, xxgdb or xemacs) existing for the GNU debugger. -\layout Subsubsection +\newline -break [line | file:line | function | file:function] -\layout Standard +\family sans +\series bold +./configure 2>&1 | tee configure.log +\family default +\series default -Set breakpoint at specified line or function: -\newline +\newline -\newline +\newline +and build it like: +\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 +\newline -clear [line | file:line | function | file:function ] -\layout Standard +\family sans +\series bold +make 2>&1 | tee make.log +\family default +\series default -Clear breakpoint at specified line or function: -\newline +\newline -\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. -\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 +\layout Subsection +What the +\begin_inset Quotes sld +\end_inset -continue -\layout Standard +./configure +\begin_inset Quotes srd +\end_inset -Continue program being debugged, after breakpoint. -\layout Subsubsection + does -finish \layout Standard +The +\begin_inset Quotes sld +\end_inset -Execute till the end of the current function. -\layout Subsubsection +./configure +\begin_inset Quotes srd +\end_inset -delete [n] -\layout Standard + 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. -Delete breakpoint number 'n'. - If used without any option clear ALL user defined break points. -\layout Subsubsection +\layout Subsection +What the +\begin_inset Quotes sld +\end_inset -info [break | stack | frame | registers ] -\layout Itemize +make +\begin_inset Quotes srd +\end_inset -info break - list all breakpoints -\layout Itemize + does -info stack - show the function call stack. -\layout Itemize +\layout Standard +This runs the GNU make tool, which automatically compiles all the source + packages into the final installed binary executables. -info frame - show information about the current execution frame. -\layout Itemize +\layout Subsection +What the +\begin_inset Quotes sld +\end_inset -info registers - show content of all registers. -\layout Subsubsection +make install +\begin_inset Quotes erd +\end_inset + + command does. -step \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} -Step program until it reaches a different source line. -\layout Subsubsection +\end_inset + +,\SpecialChar ~ + +\begin_inset LatexCommand \ref{sub:Search-Paths} + +\end_inset + +\SpecialChar ~ +about install and search paths. +\newline +On most systems you will need super-user privilege +s to do this. + +\layout Section +Components of SDCC -next \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 -Step program, proceeding through subroutine calls. -\layout Subsubsection +\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 +asx8051 - The assembler for 8051 type processors. + +\layout Itemize +as-z80 +\series bold +, +\series default +as-gbz80 - The Z80 and GameBoy Z80 assemblers. + +\layout Itemize +aslink -The linker for 8051 type processors. + +\layout Itemize +link-z80 +\series bold +, +\series default +link-gbz80 - The Z80 and GameBoy Z80 linkers. + +\layout Itemize +s51 - The ucSim 8051 simulator. + +\layout Itemize +sdcdb - The source debugger. + +\layout Itemize +packihx - A tool to pack (compress) Intel hex files. -run \layout Standard +In /share/sdcc/include -Start debugged program. -\layout Subsubsection +\layout Itemize +the include files -ptype variable \layout Standard +In /share/sdcc/lib -Print type information of the variable. -\layout Subsubsection +\layout Itemize +the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled + relocatables. -print variable \layout Standard +In /share/sdcc/doc -print value of variable. -\layout Subsubsection +\layout Itemize +the documentation -file filename \layout Standard +As development for other processors proceeds, this list will expand to include + executables to support processors like AVR, PIC, etc. -load the given file name. - Note this is an alternate method of loading file for debugging. -\layout Subsubsection +\layout Subsection +sdcc - The Compiler -frame \layout Standard +This is the actual compiler, it in turn uses the c-preprocessor and invokes + the assembler and linkage editor. -print information about current frame. -\layout Subsubsection +\layout Subsection +sdcpp - The C-Preprocessor -set srcmode \layout Standard +The preprocessor +\begin_inset LatexCommand \index{sdcpp (preprocessor)} -Toggle between C source & assembly source. -\layout Subsubsection +\end_inset + + is a modified version of the GNU cpp +\begin_inset LatexCommand \index{cpp|see{sdcpp}} + +\end_inset + + preprocessor +\begin_inset LatexCommand \url{http://gcc.gnu.org/} + +\end_inset + +. + 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 -! simulator command \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. -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 +\layout Subsection +s51 - The Simulator -quit. \layout Standard +S51 +\begin_inset LatexCommand \index{s51} + +\end_inset + + is a freeware, opensource simulator developed by Daniel Drotos. + The simulator is built as part of the build process. + For more information visit Daniel's web site at: +\begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51} + +\end_inset + +. + It currently supports the core mcs51, the Dallas DS80C390 and the Phillips + XA51 family. -"Watch me now. - Iam going Down. - My name is Bobby Brown" \layout Subsection +sdcdb - Source Level Debugger -Interfacing with XEmacs. \layout Standard +SDCDB +\begin_inset LatexCommand \index{SDCDB (debugger)} -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 +\end_inset -\newline + is the companion source level debugger. + More about SDCDB in section +\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB} -\family typewriter -(load-file sdcdbsrc.el) -\family default +\end_inset -\newline +. + The current version of the debugger uses Daniel's Simulator S51 +\begin_inset LatexCommand \index{s51} -\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 +\end_inset -\newline +, but can be easily changed to use other simulators. -\family sans -\series bold -ESC-x sdcdbsrc -\family default -\series default +\layout Chapter +Using SDCC -\newline +\layout Section +Compiling -\newline -You will prompted to enter the file name to be debugged. - -\newline +\layout Subsection +Single Source File Projects + +\layout Standard +For single source file 8051 projects the process is very simple. + Compile your programs with the following command +\family sans +\series bold +"sdcc sourcefile.c". + +\family default +\series default + This will compile, assemble and link your source file. + Output files are as follows: -\newline -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 +sourcefile.asm +\begin_inset LatexCommand \index{.asm} + +\end_inset + + - Assembler source +\begin_inset LatexCommand \index{Assembler source} + +\end_inset + + file created by the compiler -sdcdbsrc-cpu-type '51 \layout Itemize +sourcefile.lst +\begin_inset LatexCommand \index{.lst} + +\end_inset + + - Assembler listing +\begin_inset LatexCommand \index{Assembler listing} + +\end_inset + + file created by the Assembler -sdcdbsrc-frequency '11059200 \layout Itemize +sourcefile.rst +\begin_inset LatexCommand \index{.rst} + +\end_inset + + - Assembler listing +\begin_inset LatexCommand \index{Assembler listing} + +\end_inset + + file updated with linkedit information, created by linkage editor + +\layout Itemize +sourcefile.sym +\begin_inset LatexCommand \index{.sym} + +\end_inset + + - symbol listing +\begin_inset LatexCommand \index{Symbol listing} + +\end_inset + + for the sourcefile, created by the assembler + +\layout Itemize +sourcefile.rel +\begin_inset LatexCommand \index{.rel} + +\end_inset + + or sourcefile.o +\begin_inset LatexCommand \index{.o} + +\end_inset + + - Object file +\begin_inset LatexCommand \index{Object file} + +\end_inset + + created by the assembler, input to Linkage editor + +\layout Itemize +sourcefile.map +\begin_inset LatexCommand \index{.map} + +\end_inset + + - The memory map +\begin_inset LatexCommand \index{Memory map} + +\end_inset + + 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 +sourcefile.ihx +\begin_inset LatexCommand \index{.ihx} + +\end_inset + + - The load module in Intel hex format +\begin_inset LatexCommand \index{Intel hex format} + +\end_inset + + (you can select the Motorola S19 format +\begin_inset LatexCommand \index{Motorola S19 format} + +\end_inset + + with - +\begin_inset ERT +status Collapsed -sdcdbsrc-serial nil \layout Standard -The following is a list of key mapping for the debugger interface. + +\backslash +/ + +\end_inset + +-out-fmt-s19 +\begin_inset LatexCommand \index{-\/-out-fmt-s19} + +\end_inset + +. + If you need another format you might want to use +\family sans +\shape italic +objdump +\family default +\shape default + +\begin_inset LatexCommand \index{objdump (tool)} + +\end_inset + + or +\family sans +\shape italic + srecord +\family default +\shape default + +\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)} + +\end_inset + +). + Both formats are documented in the documentation of srecord +\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)} + +\end_inset + + + +\layout Itemize +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 Collapsed + \layout Standard -\SpecialChar ~ -\family typewriter +\backslash +/ + +\end_inset + +-debug +\begin_inset LatexCommand \index{-\/-debug} + +\end_inset + +) + +\layout Itemize +sourcefile.cdb +\begin_inset LatexCommand \index{.cdb} + +\end_inset + + - An optional file (with - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-debug) containing debug information. + The format is documented in cdbfileformat.pdf + +\layout Itemize +sourcefile. + - (no extension) +\begin_inset LatexCommand \index{ (no extension)} + +\end_inset + + An optional AOMF or AOMF51 +\begin_inset LatexCommand \index{AOMF, AOMF51} + +\end_inset + + +\begin_inset LatexCommand \label{OMF file} + +\end_inset + +file containing debug information (generated with option - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-debug). + The (Intel) +\emph on + a +\emph default +bsolute +\emph on +o +\emph default +bject +\emph on +m +\emph default +odule +\emph on +f +\emph default +ormat is commonly used by third party tools (debuggers +\begin_inset LatexCommand \index{Debugger} + +\end_inset + +, simulators, emulators) + +\layout Itemize +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 Standard + + +\backslash +/ + +\end_inset + +-dumpall) (see section +\begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options} + +\end_inset -\newline -;; Current Listing :: -\newline -;;key\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -binding\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -Comment -\newline -;;---\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ --------\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -------- -\newline -;; -\newline -;; n\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - sdcdb-next-from-src\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -SDCDB next command -\newline -;; b\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - sdcdb-back-from-src\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -SDCDB back command -\newline -;; c\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - sdcdb-cont-from-src\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -SDCDB continue command -\newline -;; s\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - sdcdb-step-from-src\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -SDCDB step command -\newline -;; ?\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - sdcdb-whatis-c-sexp\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -SDCDB ptypecommand for data at -\newline -;;\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ \SpecialChar ~ + and section +\begin_inset LatexCommand \ref{sub:The-anatomy-of} + +\end_inset + \SpecialChar ~ + +\begin_inset Quotes sld +\end_inset + +Anatomy of the compiler +\begin_inset Quotes srd +\end_inset + +). + +\layout Subsection +Postprocessing the Intel Hex +\begin_inset LatexCommand \index{Intel hex format} + +\end_inset + + file + +\layout Standard +In most cases this won't be needed but the Intel Hex file +\begin_inset LatexCommand \index{.ihx} + +\end_inset + + which is generated by SDCC might include lines of varying length and the + addresses within the file are not guaranteed to be strictly ascending. + If your toolchain or a bootloader does not like this you can use the tool + +\family typewriter +packihx +\family default + +\begin_inset LatexCommand \index{packihx (tool)} + +\end_inset + + which is part of the SDCC distribution: +\newline + +\newline + +\family sans +\series bold + packihx sourcefile.ihx >sourcefile.hex +\family default +\series default + +\newline + +\newline +The separately available +\emph on + srecord +\emph default + +\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)} + +\end_inset + + package additionally allows to set undefined locations to a predefined + value, to insert checksums +\begin_inset LatexCommand \index{checksum} + +\end_inset + + of various flavours (crc, add, xor) and to perform other manipulations + (convert, split, crop, offset, ...). + +\newline + +\newline + +\family sans +\series bold +srec_cat\SpecialChar ~ \SpecialChar ~ +sourcefile.ihx -intel\SpecialChar ~ \SpecialChar ~ +-o sourcefile.hex -intel +\newline + +\newline + +\family default +\series default +An example for a more complex command line +\begin_inset Foot +collapsed false + +\layout Standard +the command backfills +\begin_inset LatexCommand \index{backfill unused memory} + +\end_inset + + unused memory with 0x12 and the overall 16 bit sum of the complete 64 kByte + block is zero. + If the program counter on an mcs51 runs wild the backfill pattern 0x12 + will be interpreted as an +\family typewriter +lcall +\family default + to address +\family typewriter +0x1212 +\family default + (where an emergency routine could sit). + +\end_inset + + could look like: +\newline + +\newline + +\family sans +\series bold +\size footnotesize +srec_cat\SpecialChar ~ +sourcefile.ihx -intel\SpecialChar ~ \SpecialChar ~ +-fill 0x12 0x0000 0xfffe\SpecialChar ~ +-little-endian-checksum-nega +tive 0xfffe 0x02 0x02\SpecialChar ~ \SpecialChar ~ +-o sourcefile.hex -intel +\size default + +\newline + +\newline + +\family default +\series default +The srecord package is available at +\begin_inset LatexCommand \url{http://sf.net/projects/srecord} + +\end_inset + + . + +\layout Subsection +Projects with Multiple Source Files + +\layout Standard +SDCC can compile only ONE file at a time. + Let us for example assume that you have a project containing the following + files: +\newline + +\newline +foo1.c (contains some functions) +\newline +foo2.c (contains some more functions) +\newline +foomai +n.c (contains more functions and the function main) +\newline + +\size footnotesize + +\newline + +\size default +The first two files will need to be compiled separately with the commands: +\size footnotesize + +\size default + +\newline + +\newline + +\family sans +\series bold +sdcc\SpecialChar ~ +-c\SpecialChar ~ +foo1.c +\family default +\series default +\size footnotesize + +\newline + +\family sans +\series bold +\size default +sdcc\SpecialChar ~ +-c\SpecialChar ~ +foo2.c +\family default +\series default + +\newline + +\newline +Then compile the source file containing the +\emph on +main() +\emph default + function and link +\begin_inset LatexCommand \index{Linker} + +\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 + +\begin_inset LatexCommand \index{.rel} + +\end_inset + + +\newline + +\newline +Alternatively, +\emph on +foomain.c +\emph default +can be separately compiled as well: +\family sans +\series bold + +\newline + +\newline +sdcc\SpecialChar ~ +-c\SpecialChar ~ +foomain.c +\newline +sdcc foomain.rel foo1.rel foo2.rel +\newline + +\newline + +\family default +\series default +The file containing the +\emph on +main() +\emph default + function +\emph on + +\emph default +\noun on +must +\noun default + be the +\noun on +first +\noun default + file specified in the command line, since the linkage editor processes + file in the order they are presented to it. + 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} + +\end_inset + + + +\layout Standard +Some reusable routines may be compiled into a library, see the documentation + for the assembler and linkage editor (which are in /share/sdcc/doc) + for how to create a +\emph on +.lib +\begin_inset LatexCommand \index{.lib} + +\end_inset + + +\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 +sdcc foomain.c foolib.lib -L mylib +\newline + +\newline + +\family default +\series default +Note here that +\emph on + mylib +\emph default + must be an absolute path name. +\newline + +\newline +The most efficient way to use libraries is + to keep separate modules in separate source files. + The lib file now should name all the modules.rel +\begin_inset LatexCommand \index{.rel} + +\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 +Using sdcclib to Create and Manage Libraries +\begin_inset LatexCommand \index{sdcclib} + +\end_inset + + + +\layout Standard +Alternatively, instead of having a .rel file for each entry on the library + file as described in the preceding section, sdcclib can be used to embed + all the modules belonging to such library in the library file itself. + This results in a larger library file, but it greatly reduces the number + of disk files accessed by the linker. + Additionally, the packed library file contains an index of all include + modules and symbols that significantly speeds up the linking process. + To display a list of options supported by sdcclib type: +\newline + + +\layout Standard + +\family sans +\series bold +sdcclib -? +\begin_inset LatexCommand \index{sdcclib} + +\end_inset + + +\newline + +\newline + +\family default +\series default +To create a new library file, start by compiling all the required modules. + For example: +\newline + + +\layout Standard + +\family sans +\series bold +sdcc -c _divsint.c + +\layout Standard + +\family sans +\series bold +sdcc -c _divuint.c + +\layout Standard + +\family sans +\series bold +sdcc -c _modsint.c + +\layout Standard + +\family sans +\series bold +sdcc -c _moduint.c + +\layout Standard + +\family sans +\series bold +sdcc -c _mulint.c +\newline + + +\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 Standard + +\family sans +\series bold +sdcclib libint.lib _divsint.rel +\family default + +\begin_inset LatexCommand \index{sdcclib} + +\end_inset + + + +\layout Standard + +\family sans +\series bold +sdcclib libint.lib _divuint.rel + +\layout Standard + +\family sans +\series bold +sdcclib libint.lib _modsint.rel + +\layout Standard + +\family sans +\series bold +sdcclib libint.lib _moduint.rel + +\layout Standard + +\family sans +\series bold +sdcclib libint.lib _mulint.rel +\series default + +\newline + + +\layout Standard +If the file already exists in the library, it will be replaced. + To see what modules and symbols are included in the library, options -s + and -m are available. + For example: +\newline + +\newline + +\family sans +\series bold +sdcclib -s libint.lib +\family default + +\begin_inset LatexCommand \index{sdcclib} + +\end_inset + + +\newline + +\family typewriter +\series default +_divsint.rel: + +\layout Standard + +\family typewriter +__divsint_a_1_1 + +\layout Standard + +\family typewriter +__divsint_PARM_2 + +\layout Standard + +\family typewriter +__divsint +\newline +_divuint.rel: + +\layout Standard + +\family typewriter +__divuint_a_1_1 + +\layout Standard + +\family typewriter +__divuint_PARM_2 + +\layout Standard + +\family typewriter +__divuint_reste_1_1 + +\layout Standard + +\family typewriter +__divuint_count_1_1 + +\layout Standard + +\family typewriter +__divuint +\newline +_modsint.rel: + +\layout Standard + +\family typewriter +__modsint_a_1_1 + +\layout Standard + +\family typewriter +__modsint_PARM_2 + +\layout Standard + +\family typewriter +__modsint +\newline +_moduint.rel: + +\layout Standard + +\family typewriter +__moduint_a_1_1 + +\layout Standard + +\family typewriter +__moduint_PARM_2 + +\layout Standard + +\family typewriter +__moduint_count_1_1 + +\layout Standard + +\family typewriter +__moduint +\newline +_mulint.rel: + +\layout Standard + +\family typewriter +__mulint_PARM_2 + +\layout Standard + +\family typewriter +__mulint +\family default +\series bold + +\newline + + +\layout Standard +\added_space_bottom bigskip +If the source files are compiled using - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-debug +\begin_inset LatexCommand \index{-\/-debug} + +\end_inset + +, the corresponding debug information file .adb will be include in the library + file as well. + The library files created with sdcclib are plain text files, so they can + be viewed with a text editor. + It is not recomended to modify a library file created with sdcclib using + a text editor, as there are file indexes numbers located accross the file + used by the linker to quickly locate the required module to link. + Once a .rel file (as well as a .adb file) is added to a library using sdcclib, + it can be safely deleted, since all the information required for linking + is embedded in the library file itself. + Library files created using sdcclib are used as described in the preceding + sections. + + + +\layout Section +Command Line Options +\begin_inset LatexCommand \index{Command Line Options} + +\end_inset + + + +\layout Subsection +Processor Selection Options +\begin_inset LatexCommand \index{Options processor selection} + +\end_inset + + +\begin_inset LatexCommand \index{Processor selection options} + +\end_inset + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-mmcs51 +\begin_inset LatexCommand \index{-mmcs51} + +\end_inset + + +\series default + Generate code for the Intel MCS51 +\begin_inset LatexCommand \index{MCS51} + +\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} + +\end_inset + + +\series default + Generate code for the Dallas DS80C390 +\begin_inset LatexCommand \index{DS80C390} + +\end_inset + + processor. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-mds400 +\begin_inset LatexCommand \index{-mds400} + +\end_inset + + +\series default + Generate code for the Dallas DS80C400 +\begin_inset LatexCommand \index{DS80C400} + +\end_inset + + processor. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-mhc08 +\begin_inset LatexCommand \index{-mhc08} + +\end_inset + + +\series default + 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 +-mz80 +\begin_inset LatexCommand \index{-mz80} + +\end_inset + + +\series default + Generate code for the Zilog Z80 +\begin_inset LatexCommand \index{Z80} + +\end_inset + + family of processors. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-mgbz80 +\begin_inset LatexCommand \index{-mgbz80} + +\end_inset + + +\series default + Generate code for the GameBoy Z80 +\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)} + +\end_inset + + processor (Not actively maintained). + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-mavr +\begin_inset LatexCommand \index{-mavr} + +\end_inset + + +\series default + Generate code for the Atmel AVR +\begin_inset LatexCommand \index{AVR} + +\end_inset + + processor (Not maintained, not complete). + AVR users should probably have a look at winavr +\begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr} + +\end_inset + + or +\begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index} + +\end_inset + +. + +\layout Standard +\begin_inset Note +collapsed true + +\layout Standard +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. + +\end_inset + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-mpic14 +\begin_inset LatexCommand \index{-mpic14} + +\end_inset + + +\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 Standard +\begin_inset Note +collapsed true + +\layout Standard +p16f627 p16f628 p16f84 p16f873 p16f877? + +\end_inset + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-mpic16 +\begin_inset LatexCommand \index{-mpic16} + +\end_inset + + +\series default + Generate code for the Microchip PIC 16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + +-bit processors (p18f452 and variants. + In development, not complete). + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-mtlcs900h +\series default + Generate code for the Toshiba TLCS-900H +\begin_inset LatexCommand \index{TLCS-900H} + +\end_inset + + processor (Not maintained, not complete). + +\layout List +\labelwidthstring 00.00.0000 +\added_space_bottom bigskip + +\series bold +-mxa51 +\begin_inset LatexCommand \index{-mxa51} + +\end_inset + + +\series default + Generate code for the Phillips XA51 +\begin_inset LatexCommand \index{XA51} + +\end_inset + + processor (Not maintained, not complete). + + +\layout Subsection +Preprocessor Options +\begin_inset LatexCommand \index{Options preprocessor} + +\end_inset + + +\begin_inset LatexCommand \index{Preprocessor options} + +\end_inset + + +\begin_inset LatexCommand \index{sdcpp (preprocessor)} + +\end_inset + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-I +\begin_inset LatexCommand \index{-I} + +\end_inset + + +\series default + The additional location where the pre processor will look for <..h> or +\begin_inset Quotes eld +\end_inset + +..h +\begin_inset Quotes erd +\end_inset + + files. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-D +\begin_inset LatexCommand \index{-D} + +\end_inset + + +\series default + Command line definition of macros. + Passed to the preprocessor. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-M +\begin_inset LatexCommand \index{-M} + +\end_inset + + +\series default + Tell the preprocessor to output a rule suitable for make describing the + dependencies of each object file. + For each source file, the preprocessor outputs one make-rule whose target + is the object file name for that source file and whose dependencies are + all the files `#include'd in it. + This rule may be a single line or may be continued with ` +\backslash +'-newline if it is long. + The list of rules is printed on standard output instead of the preprocessed + C program. + `-M' implies `-E +\begin_inset LatexCommand \index{-E} + +\end_inset + +'. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-C +\begin_inset LatexCommand \index{-C} + +\end_inset + + +\series default + Tell the preprocessor not to discard comments. + Used with the `-E' option. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-MM +\begin_inset LatexCommand \index{-MM} + +\end_inset + + +\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 +-Aquestion(answer) +\begin_inset LatexCommand \index{-Aquestion(answer)} + +\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 + +\series bold +-Umacro +\begin_inset LatexCommand \index{-Umacro} + +\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 + +\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 +-dD +\begin_inset LatexCommand \index{-dD} + +\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 + +\series bold +-dN +\begin_inset LatexCommand \index{-dN} + +\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 + +\series bold +-pedantic-parse-number +\begin_inset LatexCommand \index{-pedantic-parse-number} + +\end_inset + + +\size large +\bar under + +\series default +\size default +\bar default +Pedentic parse numbers so that situations like 0xfe-LO_B(3) are parsed properly + and the macro LO_B(3) gets expanded. + See also #pragma pedantic_parse_number in section +\begin_inset LatexCommand \ref{sec:Pragmas} + +\end_inset + + +\emph on +Note: this functionality is not in conformance with standard! + +\layout List +\labelwidthstring 00.00.0000 +\added_space_bottom bigskip + +\series bold +-Wp\SpecialChar ~ +preprocessorOption[,preprocessorOption] +\series default + +\begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]} + +\end_inset + +... + 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 +\emph on +cpp +\emph default + of the GNU Compiler Collection +\begin_inset LatexCommand \index{gcc (GNU Compiler Collection)} + +\end_inset + + ( +\emph on +gcc +\emph default + +\begin_inset LatexCommand \url{http://gcc.gnu.org/} + +\end_inset + +), if you need more dedicated options please refer to the GCC\SpecialChar ~ +4.1.1\SpecialChar ~ +CPP\SpecialChar ~ +Manual + 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 + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-L\SpecialChar ~ +- +\series default + +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + + +\series bold +-lib-path +\begin_inset LatexCommand \index{-\/-lib-path } + +\end_inset + + +\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 + +\layout Standard + + +\backslash +/ + +\end_inset + +-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)} + +\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 + +\layout Standard + + +\backslash +/ + +\end_inset + +-xram-loc 32768. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-code-loc +\series default + +\begin_inset LatexCommand \index{-\/-code-loc } + +\end_inset + +\SpecialChar ~ + The start location of the code +\begin_inset LatexCommand \index{code} + +\end_inset + + segment, default value 0. + Note when this option is used the interrupt vector table +\begin_inset LatexCommand \index{interrupt vector table} + +\end_inset + + is also relocated to the given address. + The value entered can be in Hexadecimal or Decimal format, e.g.: - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-code-loc 0x8000 or - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-code-loc 32768. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-loc +\series default + +\begin_inset LatexCommand \index{-\/-stack-loc } + +\end_inset + +\SpecialChar ~ + By default the stack +\begin_inset LatexCommand \index{stack} + +\end_inset + + is placed after the data segment. + Using this option the stack can be placed anywhere in the internal memory + space of the 8051. + The value entered can be in Hexadecimal or Decimal format, e.g. + - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-loc 0x20 or - +\begin_inset ERT +status Collapsed + +\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 + +\layout Standard + + +\backslash +/ + +\end_inset + +-pack-iram +\series default +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-pack-iram} + +\end_inset + + option (which is now a default setting) will override this setting, so + you should also specify the +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-no-pack-iram +\series default +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-no-pack-iram} + +\end_inset + + option if you need to manually place the stack. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-xstack-loc +\series default + +\begin_inset LatexCommand \index{-\/-xstack-loc } + +\end_inset + +\SpecialChar ~ + By default the external stack +\begin_inset LatexCommand \index{xstack} + +\end_inset + + is placed after the pdata +\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} + +\end_inset + + 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 + +-xstack-loc 0x8000 or - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-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 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\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)} + +\end_inset + + segment. + The value entered can be in Hexadecimal or Decimal format, eg. + - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-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 + +\layout Standard + + +\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 + + +\backslash +/ + +\end_inset + +-idata-loc +\series default + +\begin_inset LatexCommand \index{-\/-idata-loc } + +\end_inset + +\SpecialChar ~ + The start location of the indirectly addressable internal ram +\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)} + +\end_inset + + of the 8051, default value is 0x80. + The value entered can be in Hexadecimal or Decimal format, eg. + - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-idata-loc 0x88 or - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-idata-loc 136. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-bit-loc +\series default +\SpecialChar ~ + The start location of the bit +\begin_inset LatexCommand \index{bit} + +\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=. + +\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} + +\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)} + +\end_inset + +. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-out-fmt-s19 +\begin_inset LatexCommand \index{-\/-out-fmt-s19} + +\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} + +\end_inset + +. + The format itself is documented in the documentation of srecord. + +\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} + +\end_inset + + +\begin_inset LatexCommand \index{HC08!Options!-\/-out-fmt-elf} + +\end_inset + + +\bar under + +\series default +\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 +\begin_inset LatexCommand \index{HC08} + +\end_inset + + processors) + +\layout List +\labelwidthstring 00.00.0000 +\added_space_bottom bigskip + +\series bold +-Wl\SpecialChar ~ +linkOption[,linkOption] +\series default + +\begin_inset LatexCommand \index{-Wl linkOption[,linkOption]} + +\end_inset + +... + Pass the linkOption to the linker. + If a bootloader is used an option like +\begin_inset Quotes sld +\end_inset + +-Wl\SpecialChar ~ +-bCSEG=0x1000 +\begin_inset Quotes srd +\end_inset + + would be typical to set the start of the code segment. + See also #pragma constseg and #pragma codeseg in section +\begin_inset LatexCommand \ref{sec:Pragmas} + +\end_inset + + . + File sdcc/as/doc/asxhtm.html has more on linker options. + + +\layout Subsection +MCS51 Options +\begin_inset LatexCommand \index{Options MCS51} + +\end_inset + + +\begin_inset LatexCommand \index{MCS51 options} + +\end_inset + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-small +\begin_inset LatexCommand \index{-\/-model-small} + +\end_inset + + +\series default +\size large +\emph on + +\size default +\emph default +Generate code for Small Model programs, see section Memory Models for more + details. + This is the default model. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-medium +\begin_inset LatexCommand \index{-\/-model-medium} + +\end_inset + + +\series default + Generate code for Medium model programs, see section Memory Models for + more details. + If this option is used all source files in the project have to be compiled + with this option. + It must also be used when invoking the linker. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-large +\begin_inset LatexCommand \index{-\/-model-large} + +\end_inset + + +\series default + Generate code for Large model programs, see section Memory Models for more + details. + If this option is used all source files in the project have to be compiled + with this option. + It must also be used when invoking the linker. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-xstack +\begin_inset LatexCommand \index{-\/-xstack} + +\end_inset + + +\series default + Uses a pseudo stack in the pdata +\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} + +\end_inset + + area (usually the first 256 bytes in the external ram) for allocating variables + and passing parameters. + See section +\begin_inset LatexCommand \ref{sub:External-Stack} + +\end_inset + +\SpecialChar ~ + External Stack for more details. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-iram-size +\series default +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-iram-size } + +\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 + + +\backslash +/ + +\end_inset + +-xram-size +\series default +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-xram-size } + +\end_inset + + Causes the linker to check if the external ram usage is within limits of + the given value. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\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. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-size +\series default +\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-stack-size } + +\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 + + +\backslash +/ + +\end_inset + +-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 +\added_space_bottom bigskip + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-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 +DS390 / DS400 Options +\begin_inset LatexCommand \index{Options DS390} + +\end_inset + + +\begin_inset LatexCommand \index{DS390} + +\end_inset + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-flat24 +\series default + +\begin_inset LatexCommand \index{DS390!Options!-\/-model-flat24} + +\end_inset + + +\size large +\emph on + +\size default +\emph default +Generate 24-bit flat mode code. + This is the one and only that the ds390 code generator supports right now + and is default when using +\emph on +-mds390 +\emph default +. + See section Memory Models for more details. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-protect-sp-update +\begin_inset LatexCommand \index{DS390!Options!-\/-protect-sp-update} + +\end_inset + + +\series default + disable interrupts during ESP:SP updates. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-10bit +\series default + +\begin_inset LatexCommand \index{DS390!Options!-\/-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 +. + 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 + + +\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 + +\layout Standard + + +\backslash +/ + +\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 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-flat24 option +\emph default +). + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-probe +\begin_inset LatexCommand \index{DS390!Options!-\/-stack-probe} + +\end_inset + + +\series default + insert call to function __stack_probe at each function prologue. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-tini-libid +\begin_inset LatexCommand \index{DS390!Options!-\/-tini-libid} + +\end_inset + + +\series default + LibraryID used in -mTININative. + + +\layout List +\labelwidthstring 00.00.0000 +\added_space_bottom bigskip + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-use-accelerator +\begin_inset LatexCommand \index{DS390!Options!-\/-use-accelerator} + +\end_inset + + +\series default + generate code for DS390 Arithmetic Accelerator. + + + +\layout Subsection +Z80 Options +\begin_inset LatexCommand \index{Options Z80} + +\end_inset + + +\begin_inset LatexCommand \index{Z80} + +\end_inset + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-callee-saves-bc +\series default + +\begin_inset LatexCommand \index{Z80!Options!-\/-callee-saves-bc} + +\end_inset + + +\size large +\emph on + +\size default +\emph default +Force a called function to always save BC. + +\layout List +\labelwidthstring 00.00.0000 +\added_space_bottom bigskip + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-no-std-crt0 +\series default + +\begin_inset LatexCommand \index{Z80!Options!-\/-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 + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-nogcse +\begin_inset LatexCommand \index{-\/-nogcse} + +\end_inset + + +\series default + Will not do global subexpression elimination, this option may be used when + the compiler creates undesirably large stack/data spaces to store compiler + temporaries ( +\emph on +s +\emph default +pill +\emph on +loc +\emph default +ations, sloc +\begin_inset LatexCommand \index{sloc (spill location)} + +\end_inset + +). + A warning message will be generated when this happens and the compiler + will indicate the number of extra bytes it allocated. + It is recommended that this option NOT be used, #pragma\SpecialChar ~ +nogcse +\begin_inset LatexCommand \index{\#pragma nogcse} + +\end_inset + + can be used to turn off global subexpression elimination +\begin_inset LatexCommand \index{Subexpression elimination} + +\end_inset + + for a given function only. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-noinvariant +\begin_inset LatexCommand \index{-\/-noinvariant} + +\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} + +\end_inset + + can be used to turn off invariant optimizations for a given function only. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-noinduction +\begin_inset LatexCommand \index{-\/-noinduction} + +\end_inset + + +\series default + Will not do loop induction optimizations, see section strength reduction + for more details. + It is recommended that this option is NOT used, #pragma\SpecialChar ~ +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 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-nojtbound +\begin_inset LatexCommand \index{-\/-nojtbound} + +\end_inset + + +\size large +\bar under + +\series default +\size default +\bar default + Will not generate boundary condition check when switch statements +\begin_inset LatexCommand \index{switch statement} + +\end_inset + + 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 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-noloopreverse +\begin_inset LatexCommand \index{-\/-noloopreverse} + +\end_inset + + +\series default +\size large + +\size default +Will not do loop reversal +\begin_inset LatexCommand \index{Loop reversing} + +\end_inset + +optimization. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +- +\series bold +nolabelopt +\series default + +\begin_inset LatexCommand \index{-\/-nolabelopt } + +\end_inset + +Will not optimize labels (makes the dumpfiles more readable). + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-no-xinit-opt +\begin_inset LatexCommand \index{-\/-no-xinit-opt} + +\end_inset + + +\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 + +. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-nooverlay +\begin_inset LatexCommand \index{-\/-nooverlay} + +\end_inset + + +\series default + The compiler will not overlay parameters and local variables of any function, + see section Parameters and local variables for more details. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-no-peep +\begin_inset LatexCommand \index{-\/-no-peep} + +\end_inset + + +\series default + Disable peep-hole optimization with built-in rules. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-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 + +\SpecialChar ~ +Peep Hole optimizations for details on how to write these rules. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-peep-asm +\begin_inset LatexCommand \index{-\/-peep-asm} + +\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. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-opt-code-speed +\begin_inset LatexCommand \index{-\/-opt-code-speed} + +\end_inset + + +\series default + The compiler will optimize code generation towards fast code, possibly + at the expense of code size. + +\layout List +\labelwidthstring 00.00.0000 +\added_space_bottom bigskip + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-opt-code-size +\begin_inset LatexCommand \index{-\/-opt-code-size} + +\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 + + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-c\SpecialChar ~ +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-compile-only +\begin_inset LatexCommand \index{-\/-compile-only} + +\end_inset + + +\begin_inset LatexCommand \index{-c -\/-compile-only} + +\end_inset + + +\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 + +\layout Standard + + +\backslash +/ + +\end_inset + + +\series bold +-c1mode +\begin_inset LatexCommand \index{-\/-c1mode} + +\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. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-E +\begin_inset LatexCommand \index{-E} + +\end_inset + + +\series default + Run only the C preprocessor. + Preprocess all the C source files specified and output the results to standard + output. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-o\SpecialChar ~ + +\begin_inset LatexCommand \index{-o } + +\end_inset + + +\series default +The output path resp. + file where everything will be placed. + If the parameter is a path, it must have a trailing slash (or backslash + for the Windows binaries) to be recognized as a path. + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} + +\end_inset + + +\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} + +\end_inset + + Parameters and Local Variables for more details. + If this option is used all source files in the project should be compiled + with this option. + It automatically implies --int-long-reent and --float-reent. + + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-callee-saves +\begin_inset LatexCommand \index{-\/-callee-saves} + +\end_inset + + function1[,function2][,function3].... + +\series default + The compiler by default uses a caller saves convention for register saving + across function calls, however this can cause unnecessary register pushing + & popping when calling small functions from larger functions. + This option can be used to switch the register saving convention for the + function names specified. + The compiler will not save registers when calling these functions, no extra + code will be generated at the entry & exit (function prologue +\series bold + +\begin_inset LatexCommand \index{function prologue} + +\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 + +\layout Standard + + +\backslash +/ + +\end_inset + +-callee-saves option string. + Also see #pragma\SpecialChar ~ +callee_saves +\begin_inset LatexCommand \index{\#pragma callee\_saves} + +\end_inset + +. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-debug +\begin_inset LatexCommand \index{-\/-debug} + +\end_inset + + +\bar under + +\series default +\bar default +When this option is used the compiler will generate debug information. + The debug information collected in a file with .cdb extension can be used + with the SDCDB. + For more information see documentation for SDCDB. + Another file with no extension contains debug information in AOMF or AOMF51 +\begin_inset LatexCommand \index{AOMF, AOMF51} + +\end_inset + + 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 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-int-long-reent +\begin_inset LatexCommand \index{-\/-int-long-reent} + +\end_inset + + +\series default + Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant. + Note by default these libraries are compiled as non-reentrant. + See section Installation for more details. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-cyclomatic +\begin_inset LatexCommand \index{-\/-cyclomatic} + +\end_inset + + +\bar under + +\series default +\bar default +This option will cause the compiler to generate an information message for + each function in the source file. + The message contains some +\emph on +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. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-float-reent +\begin_inset LatexCommand \index{-\/-float-reent} + +\end_inset + + +\series default + Floating point library is compiled as reentrant +\begin_inset LatexCommand \index{reentrant} + +\end_inset + +. + See section Installation for more details. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-funsigned-char +\begin_inset LatexCommand \index{-\/-funsigned-char} + +\end_inset + + +\series default + The default signedness for every type is +\family typewriter + signed +\family default +. + In some embedded environments the default signedness of +\family typewriter + char +\family default + is +\family typewriter + unsigned +\family default +. + To set the signess for characters to unsigned, use the option --funsigned-char. + If this option is set and no signedness keyword (unsigned/signed) is given, + a char will be signed. + All other types are unaffected. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-main-return +\begin_inset LatexCommand \index{-\/-main-return} + +\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 results in slightly smaller code and saves two bytes of stack + space. + The return from the 'main' +\begin_inset LatexCommand \index{main return} + +\end_inset + + 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 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-nostdinc +\begin_inset LatexCommand \index{-\/-nostdinc} + +\end_inset + + +\series default + This will prevent the compiler from passing on the default include path + to the preprocessor. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-nostdlib +\begin_inset LatexCommand \index{-\/-nostdlib} + +\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. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-verbose +\begin_inset LatexCommand \index{-\/-verbose} + +\end_inset + + +\series default + Shows the various actions the compiler is performing. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-V +\begin_inset LatexCommand \index{-V} + +\end_inset + + +\series default + Shows the actual commands the compiler is executing. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-no-c-code-in-asm +\begin_inset LatexCommand \index{-\/-no-c-code-in-asm} + +\end_inset + + +\series default + Hides your ugly and inefficient c-code from the asm file, so you can always + blame the compiler :) + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-no-peep-comments +\begin_inset LatexCommand \index{-\/-no-peep-comments} + +\end_inset + + +\series default + Will not include peep-hole comments in the generated files. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-no-gen-comments +\begin_inset LatexCommand \index{-\/-no-gen-comments} + +\end_inset + + +\series default + Will not include code generator comments in the generated files. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-i-code-in-asm +\begin_inset LatexCommand \index{-\/-i-code-in-asm} + +\end_inset + + +\series default + 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 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-less-pedantic +\begin_inset LatexCommand \index{-\/-less-pedantic} + +\end_inset + + +\series default + Disable some of the more pedantic warnings +\begin_inset LatexCommand \index{Warnings} + +\end_inset + + (jwk burps: please be more specific here, please!). + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-disable-warning\SpecialChar ~ + +\begin_inset LatexCommand \index{-\/-disable-warning} + +\end_inset + + +\series default + Disable specific warning with number . + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-print-search-dirs +\begin_inset LatexCommand \index{-\/-print-search-dirs} + +\end_inset + + +\series default + Display the directories in the compiler's search path + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-vc +\begin_inset LatexCommand \index{-\/-vc} + +\end_inset + + +\series default + Display errors and warnings using MSVC style, so you can use SDCC with + the visual studio IDE +\begin_inset LatexCommand \index{IDE} + +\end_inset + +. + With SDCC both offering a GCC-like (the default) and a MSVC-like +\begin_inset LatexCommand \index{MSVC output style} + +\end_inset + + output style, integration into most programming editors should be straightforwa +rd. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-use-stdout +\begin_inset LatexCommand \index{-\/-use-stdout} + +\end_inset + + +\series default + Send errors and warnings to stdout instead of stderr. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +-Wa\SpecialChar ~ +asmOption[,asmOption] +\series default + +\begin_inset LatexCommand \index{-Wa asmOption[,asmOption]} + +\end_inset + +... + Pass the asmOption to the assembler +\begin_inset LatexCommand \index{Options assembler} + +\end_inset + + +\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 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-std-sdcc89 +\begin_inset LatexCommand \index{-\/-std-sdcc89} + +\end_inset + + +\series default + Generally follow the C89 standard, but allow SDCC features that conflict + with the standard (default). + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-std-c89 +\begin_inset LatexCommand \index{-\/-std-c89} + +\end_inset + + +\series default + Follow the C89 standard and disable SDCC features that conflict with the + standard. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-std-sdcc99 +\begin_inset LatexCommand \index{-\/-std-sdcc99} + +\end_inset + + +\series default + Generally follow the C99 standard, but allow 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 + +-std-c99 +\begin_inset LatexCommand \index{-\/-std-sdcc99} + +\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 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-codeseg +\series default + +\begin_inset LatexCommand \index{-\/-codeseg } + +\end_inset + +\SpecialChar ~ + The name to be used for the code +\begin_inset LatexCommand \index{code} + +\end_inset + + segment, default CSEG. + This is useful if you need to tell the compiler to put the code in a special + segment so you can later on tell the linker to put this segment in a special + place in memory. + Can be used for instance when using bank switching to put the code in a + bank. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-constseg +\series default + +\begin_inset LatexCommand \index{-\/-constseg } + +\end_inset + +\SpecialChar ~ + The name to be used for the const +\begin_inset LatexCommand \index{code} + +\end_inset + + segment, default CONST. + This is useful if you need to tell the compiler to put the const data in + a special segment so you can later on tell the linker to put this segment + in a special place in memory. + Can be used for instance when using bank switching to put the const data + in a bank. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-fdollars-in-identifiers +\begin_inset LatexCommand \index{-\/-fdollars-in-identifiers} + +\end_inset + + +\series default + Permit '$' as an identifier character + +\layout List +\labelwidthstring 00.00.0000 +\added_space_bottom bigskip + +\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)} + +\end_inset + + +\begin_inset LatexCommand \url{http://www.splint.org} + +\end_inset + +. + To make your source files parseable by splint you will have to include + +\family sans +lint.h +\family default + +\begin_inset LatexCommand \index{splint (syntax checking tool)} + +\end_inset + + in your source file and add brackets around extended keywords (like +\family sans + +\begin_inset Quotes sld +\end_inset + +__at\SpecialChar ~ + +\series bold +( +\series default +0xab +\series bold +) +\series default + +\begin_inset Quotes srd +\end_inset + + +\family default + and +\family sans + +\begin_inset Quotes sld +\end_inset + +__interrupt\SpecialChar ~ +(2) +\begin_inset Quotes srd +\end_inset + + +\family default +). + +\newline +Splint has an excellent on line manual at +\begin_inset LatexCommand \url{http://www.splint.org/manual/} + +\end_inset + + and it's capabilities go beyond pure syntax checking. + You'll need to tell splint the location of SDCC's include files so a typical + command line could look like this: +\newline + +\family sans +splint\SpecialChar ~ +-I\SpecialChar ~ +/usr/local/share/sdcc/include/mcs51/\SpecialChar ~ +\SpecialChar ~ +myprogram.c + + +\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 + + +\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 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumpraw +\begin_inset LatexCommand \index{-\/-dumpraw} + +\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} + +\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 + + +\backslash +/ + +\end_inset + +-dumpgcse +\begin_inset LatexCommand \index{-\/-dumpgcse} + +\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. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumpdeadcode +\begin_inset LatexCommand \index{-\/-dumpdeadcode} + +\end_inset + + +\series default + Will create a dump of iCode's, after deadcode elimination +\begin_inset LatexCommand \index{Dead-code elimination} + +\end_inset + +, into a file named +\emph on +.dumpdeadcode. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumploop +\begin_inset LatexCommand \index{-\/-dumploop} + +\end_inset + + +\series default +\size large + +\size default +Will create a dump of iCode's, after loop optimizations +\begin_inset LatexCommand \index{Loop optimization} + +\end_inset + +, into a file named +\emph on +.dumploop. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumprange +\begin_inset LatexCommand \index{-\/-dumprange} + +\end_inset + + +\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 + +, into a file named +\emph on +.dumprange. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumlrange +\begin_inset LatexCommand \index{-\/-dumlrange} + +\end_inset + + +\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 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumpregassign +\begin_inset LatexCommand \index{-\/-dumpregassign} + +\end_inset + + +\bar under + +\series default +\bar default +Will create a dump of iCode's, after register assignment +\begin_inset LatexCommand \index{Register assignment} + +\end_inset + +, into a file named +\emph on +.dumprassgn. + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumplrange +\begin_inset LatexCommand \index{-\/-dumplrange} + +\end_inset + + +\series default + Will create a dump of the live ranges of iTemp's + +\layout List +\labelwidthstring 00.00.0000 +\added_space_bottom bigskip + +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumpall +\begin_inset LatexCommand \index{-\/-dumpall} + +\end_inset + + +\size large +\bar under + +\series default +\size default +\bar default +Will cause all the above mentioned dumps to be created. + + +\layout Subsection +Redirecting output on Windows Shells + +\layout Standard +\added_space_bottom bigskip +By default SDCC writes it's error messages to +\begin_inset Quotes sld +\end_inset + +standard error +\begin_inset Quotes srd +\end_inset + +. + To force all messages to +\begin_inset Quotes sld +\end_inset + +standard output +\begin_inset Quotes srd +\end_inset + + use +\series bold +- +\series default +\emph on + +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + + +\series bold +\emph default +- +\series default +use-stdout +\begin_inset LatexCommand \index{-\/-use-stdout} + +\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 + +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + + +\emph default +-vc +\begin_inset LatexCommand \index{-\/-vc} + +\end_inset + + 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 + +\layout Standard + + +\backslash +/ + +\end_inset + + +\series bold +\emph default +-vc - +\series default +\emph on + +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + + +\series bold +\emph default +-model-large -c $(InputPath) +\series default + + + + +\layout Section +Environment variables +\begin_inset LatexCommand \index{Environment variables} + +\end_inset + + + +\layout Standard +SDCC recognizes the following environment variables: + +\layout List +\labelwidthstring 00.00.0000 + +\series bold +SDCC_LEAVE_SIGNALS +\begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS} + +\end_inset + + +\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 +\added_space_bottom bigskip +There are some more environment variables recognized by SDCC, but these + are solely used for debugging purposes. + They can change or disappear very quickly, and will never be documented. + + + +\layout Section +Storage Class Language Extensions + +\layout Subsection +MCS51/DS390 Storage Class +\begin_inset LatexCommand \index{Storage class} + +\end_inset + + Language Extensions + +\layout Standard +In addition to the ANSI storage classes SDCC allows the following MCS51 + specific storage classes: + +\layout Subsubsection +data +\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)} + +\end_inset + + / near +\begin_inset LatexCommand \index{near (storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_near (storage class)} + +\end_inset + + + +\layout Standard +This is the +\series bold +default +\series default + storage class for the Small Memory model ( +\emph on +data +\emph default + and +\emph on +near +\emph default + or the more ANSI-C compliant forms +\emph on +__data +\emph default + and +\emph on +__near +\emph default + can be used synonymously). + Variables declared with this storage class will be allocated in the directly + addressable portion of the internal RAM of a 8051, e.g.: + +\layout Verse + +\family typewriter +__data unsigned char test_data; + +\layout Standard +Writing 0x01 to this variable generates the assembly code: + +\layout Verse + +\family typewriter +75*00 01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +_test_data,#0x01 + +\layout Subsubsection +xdata +\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)} + +\end_inset + + / far +\begin_inset LatexCommand \index{far (storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_far (storage class)} + +\end_inset + + + +\layout Standard +Variables declared with this storage class will be placed in the external + RAM. + This is the +\series bold +default +\series default + storage class for the Large Memory model, e.g.: + +\layout Verse + +\family typewriter +__xdata unsigned char test_xdata; + +\layout Standard +Writing 0x01 to this variable generates the assembly code: + +\layout Verse + +\family typewriter +90s00r00\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +dptr,#_test_xdata +\newline +74\SpecialChar ~ +01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +a,#0x01 +\newline +F0\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +movx\SpecialChar ~ +@dptr,a + +\layout Subsubsection +idata +\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)} + +\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 + +\family typewriter +__idata unsigned char test_idata; + +\layout Standard +Writing 0x01 to this variable generates the assembly code: + +\layout Verse + +\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 +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 + + is located in idata memory. + +\layout Subsubsection +pdata +\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)} + +\end_inset + + + +\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)} + +\end_inset + +(or in case of some 8051 variants by a separate Special Function Register, + see section +\begin_inset LatexCommand \ref{sub:MCS51-variants} + +\end_inset + +). + This is the +\series bold +default +\series default + storage class for the Medium Memory model, e.g.: + +\layout Verse + +\family typewriter +__pdata unsigned char test_pdata; + +\layout Standard +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 +If the - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-xstack +\begin_inset LatexCommand \index{-\/-xstack} + +\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} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_code} + +\end_inset + + + +\layout Standard +'Variables' declared with this storage class will be placed in the code + memory: + +\layout Verse + +\family typewriter +__code unsigned char test_code; + +\layout Standard +Read access to this variable generates the assembly code: + +\layout Verse + +\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 + +\family typewriter +char +\family default + indexed arrays of characters in code memory can be accessed efficiently: + +\layout Verse + +\family typewriter +__code char test_array[] = {'c','h','e','a','p'}; + +\layout Standard +Read access to this array using an 8-bit unsigned index generates the assembly + code: + +\layout Verse + +\family typewriter +E5*00\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov a,_index + +\layout Verse + +\family typewriter +90s00r41\SpecialChar ~ +\SpecialChar ~ +\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 + + +\begin_inset LatexCommand \index{\_\_bit} + +\end_inset + + + +\layout Standard +This is a data-type and a storage class specifier. + When a variable is declared as a bit, it is allocated into the bit addressable + memory of 8051, e.g.: + +\layout Verse + +\family typewriter +__bit test_bit; + +\layout Standard +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 + + +\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 + +. + 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 + + +\begin_inset LatexCommand \index{\_\_sfr} + +\end_inset + + / sfr16 +\begin_inset LatexCommand \index{sfr16} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_sfr16} + +\end_inset + + / sfr32 +\begin_inset LatexCommand \index{sfr32} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_sfr32} + +\end_inset + + / sbit +\begin_inset LatexCommand \index{\_\_sbit} + +\end_inset + + +\begin_inset LatexCommand \index{sbit} + +\end_inset + + + +\layout Standard +Like the bit keyword, +\emph on +sfr / sfr16 / sfr32 / sbit +\emph default +signify both a data-type and storage class, they are used to describe the + +\emph on +s +\emph default +pecial +\emph on +f +\emph default +unction +\emph on +r +\emph default +egisters and +\emph on +s +\emph default +pecial +\emph on +bit +\emph default + variables of a 8051, eg: + +\layout Verse + +\family typewriter +__sfr __at +\begin_inset LatexCommand \index{at} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_at} + +\end_inset + + (0x80) P0;\SpecialChar ~ + /* special function register P0 at location 0x80 */ +\newline + +\newline +/* 16 bit + special function register combination for timer 0 +\newline +\SpecialChar ~ +\SpecialChar ~ + with the high byte at + location 0x8C and the low byte at location 0x8A */ +\newline +__sfr16 __at (0x8C8A) + TMR0; +\newline + +\newline +__sbit __at +\begin_inset LatexCommand \index{at} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_at} + +\end_inset + + (0xd7) CY;\SpecialChar ~ + /* 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 +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. +\newline + + +\layout Standard +Please note, if you use a header file which was written for another compiler + then the sfr / sfr16 / sfr32 / sbit Storage Class extensions will most + likely be +\emph on +not +\emph default +compatible. + Specifically the syntax +\family typewriter +\SpecialChar ~ +sfr P0 = 0x80;\SpecialChar ~ + +\family default + is compiled +\emph on +without warning +\emph default + by SDCC to an assignment of 0x80 to a variable called P0 +\family typewriter + +\begin_inset Marginal +collapsed true + +\layout Standard + +\series bold +\SpecialChar ~ +! + +\end_inset + +. + +\family default +Nevertheless it is possible to write header files +\begin_inset LatexCommand \index{Header files} + +\end_inset + + +\begin_inset LatexCommand \index{Include files} + +\end_inset + + which can be shared among different compilers (see section +\begin_inset LatexCommand \ref{sec:Porting-code-to-other-compilers} + +\end_inset + +). + + +\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 + +\newline +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 + +\newline +/* pointer physically in external ram + pointing to object in internal ram */ +\newline +__data unsigned char * __xdata p; +\newline + +\newline +/* + pointer physically in code rom pointing to data in xdata space */ +\newline +__xdata + unsigned char * __code p; +\newline + +\newline +/* pointer physically in code space pointing to + data in code space */ +\newline +__code unsigned char * __code p; +\newline + +\newline +/* generic pointer + physically located in xdata space */ +\newline +unsigned char * __xdata p; +\newline + +\newline +/* generic + pointer physically located in default memory space */ +\newline +unsigned char * p; +\newline + +\newline +/* + the following is a function pointer +\begin_inset LatexCommand \index{function pointer} + +\end_inset + + physically located in data space */ +\newline +char (* __data fp)(void); + +\layout Standard +Well you get the idea. + +\newline + +\newline +All unqualified pointers are treated as 3-byte (4-byte for the ds390) +\emph on +generic +\emph default + pointers. + +\size small + +\newline + +\newline + +\size default +The highest order byte of the +\emph on +generic +\emph default + pointers contains the data space information. + Assembler support routines are called whenever data is stored or retrieved + using +\emph on +generic +\emph default + pointers. + These are useful for developing reusable library +\begin_inset LatexCommand \index{Libraries} + +\end_inset + + routines. + Explicitly specifying the pointer +\begin_inset LatexCommand \index{pointer} + +\end_inset + + type will generate the most efficient code. + +\layout Subsubsection +Notes on MCS51 memory +\begin_inset LatexCommand \index{MCS51 memory} + +\end_inset + + layout + +\layout Standard +The 8051 family of microcontrollers have a minimum of 128 bytes of internal + RAM memory which is structured as follows: +\newline + +\newline +- Bytes 00-1F - 32 bytes to hold + up to 4 banks of the registers R0 to R7, +\newline +- Bytes 20-2F - 16 bytes to hold + 128 bit +\begin_inset LatexCommand \index{bit} + +\end_inset + + variables and, +\newline +- Bytes 30-7F - 80 bytes for general purpose use. +\newline + + +\layout Standard +Additionally some members of the MCS51 family may have up to 128 bytes of + additional, indirectly addressable, internal RAM memory ( +\emph on +idata +\emph default + +\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)} + +\end_inset + +). + Furthermore, some chips may have some built in external memory ( +\emph on +xdata +\emph default + +\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)} + +\end_inset + +) which should not be confused with the internal, directly addressable RAM + memory ( +\emph on +data +\emph default + +\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)} + +\end_inset + +). + Sometimes this built in +\emph on +xdata +\emph default + memory has to be activated before using it (you can probably find this + information on the datasheet of the microcontroller your are using, see + also section +\begin_inset LatexCommand \ref{sub:Startup-Code} + +\end_inset + +\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)} + +\end_inset + + +\emph default +) should be used in interrupt +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_interrupt} + +\end_inset + + routines. + By default, the compiler will place the stack after the last byte of allocated + memory for variables. + For example, if the first 2 banks of registers are used, and only four + bytes are used for +\emph on +data +\emph default + variables, it will position the base of the internal stack at address 20 + (0x14). + This implies that as the stack +\begin_inset LatexCommand \index{stack} + +\end_inset + + grows, it will use up the remaining register banks, and the 16 bytes used + by the 128 bit variables, and 80 bytes for general purpose use. + If any bit variables are used, the data variables will be placed in unused + register banks and after the byte holding the last bit variable. + For example, if register banks 0 and 1 are used, and there are 9 bit variables + (two bytes used), +\emph on +data +\emph default + variables will be placed starting from address 0x10 to 0x20 and continue + at address 0x22. + You can also use - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-data-loc +\begin_inset LatexCommand \index{-\/-data-loc } + +\end_inset + + to specify the start address of the +\emph on +data +\emph default + and - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-iram-size +\begin_inset LatexCommand \index{-\/-iram-size } + +\end_inset + + to specify the size of the total internal RAM ( +\emph on +data +\emph default ++ +\emph on +idata +\emph default +). + +\newline + + +\layout Standard +By default the 8051 linker will place the stack after the last byte of (i)data + variables. + Option - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-loc +\begin_inset LatexCommand \index{-\/-stack-loc } + +\end_inset + + allows you to specify the start of the stack, i.e. + you could start it after any data in the general purpose area. + If your microcontroller has additional indirectly addressable internal + RAM ( +\emph on +idata +\emph default +) you can place the stack on it. + You may also need to use - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-xdata-loc +\begin_inset LatexCommand \index{-\/-xdata-loc} + +\end_inset + + to set the start address of the external RAM ( +\emph on +xdata +\emph default +) and - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-xram-size +\begin_inset LatexCommand \index{-\/-xram-size } + +\end_inset + + to specify its size. + Same goes for the code memory, using - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-code-loc +\begin_inset LatexCommand \index{-\/-code-loc } + +\end_inset + + and - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-code-size +\begin_inset LatexCommand \index{-\/-code-size } + +\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 +\added_space_bottom bigskip +The linker generates two files with memory allocation information. + The first, with extension .map +\begin_inset LatexCommand \index{.map} + +\end_inset + + shows all the variables and segments. + The second with extension .mem +\begin_inset LatexCommand \index{.mem} + +\end_inset + + shows the final memory layout. + The linker will complain either if memory segments overlap, there is not + enough memory, or there is not enough space for stack. + If you get any linking warnings and/or errors related to stack or segments + allocation, take a look at either the .map or .mem files to find out what + the problem is. + The .mem file may even suggest a solution to the problem. + + + +\layout Subsection +Z80/Z180 Storage Class +\begin_inset LatexCommand \index{Z80!Storage class} + +\end_inset + + Language Extensions + +\layout Subsubsection +sfr +\begin_inset LatexCommand \index{sfr} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_sfr} + +\end_inset + + (in/out to 8-bit addresses) + +\layout Standard +The Z80 +\begin_inset LatexCommand \index{Z80} + +\end_inset + + family has separate address spaces for memory and +\emph on +i +\emph default +nput/ +\emph on +o +\emph default +utput memory. + I/O memory +\begin_inset LatexCommand \index{I/O memory (Z80, Z180)} + +\end_inset + + +\begin_inset LatexCommand \index{Z80!I/O memory} + +\end_inset + + +\begin_inset LatexCommand \index{Z180!I/O memory} + +\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 ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ld a,#0x01 +\newline +D3 78\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\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 +The keyword +\emph on +banked +\emph default + is used to support 16 bit addresses in I/O memory e.g.: + +\layout Verse + +\family typewriter +sfr banked at +\begin_inset LatexCommand \index{at} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_at} + +\end_inset + + 0x123 IoPort; + +\layout Standard +Writing 0x01 to this variable generates the assembly code: + +\layout Verse + +\family typewriter +01 23 01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ld bc,#_IoPort +\newline +3E 01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ld a,#0x01 +\newline +ED 79\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +out (c),a + +\layout Subsubsection +sfr +\begin_inset LatexCommand \index{sfr} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_sfr} + +\end_inset + + (in0/out0 to 8 bit addresses on Z180 +\begin_inset LatexCommand \index{Z180} + +\end_inset + +/HD64180 +\begin_inset LatexCommand \index{HD64180 (see Z180)} + +\end_inset + +) + +\layout Standard +\added_space_bottom bigskip +The compiler option - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-portmode +\begin_inset LatexCommand \index{Z180!Options!-\/-portmode} + +\end_inset + +=180 (80) and a compiler #pragma\SpecialChar ~ +portmode +\begin_inset LatexCommand \index{Z180!Pragmas!\#pragma portmode} + +\end_inset + + z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio +ns +\family typewriter +in0/out0 +\family default + instead of +\family typewriter +in/out +\family default +. + If you include the file z180.h this will be set automatically. + + + +\layout Subsection +HC08 Storage Class +\begin_inset LatexCommand \index{HC08!Storage class} + +\end_inset + + Language Extensions + +\layout Subsubsection +data +\begin_inset LatexCommand \index{data (hc08 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_data (hc08 storage class)} + +\end_inset + + + +\layout Standard +The data storage class declares a variable that resides in the first 256 + bytes of memory (the direct page). + The HC08 +\begin_inset LatexCommand \index{HC08} + +\end_inset + + is most efficient at accessing variables (especially pointers) stored here. + +\layout Subsubsection +xdata +\begin_inset LatexCommand \index{xdata (hc08 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)} + +\end_inset + + + +\layout Standard +\added_space_bottom bigskip +The xdata storage class declares a variable that can reside anywhere in + memory. + This is the default if no storage class is specified. + + + + +\layout Section +Absolute Addressing +\begin_inset LatexCommand \index{Absolute addressing} + +\end_inset + + + +\layout Standard +Data items can be assigned an absolute address with the +\emph on +at +\begin_inset LatexCommand \index{at} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_at} + +\end_inset + +
+\emph default + keyword, in addition to a storage class, e.g.: + +\layout Verse + +\family typewriter +xdata +\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)} + +\end_inset + + at +\begin_inset LatexCommand \index{at} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_at} + +\end_inset + + 0x7ffe unsigned int chksum; + +\layout Standard +or, better conforming to ISO/IEC 9899 C: + +\layout Verse + +\family typewriter +__xdata __at (0x7ffe) unsigned int chksum; + +\layout Standard +In the above example the variable chksum will be located at 0x7ffe and 0x7fff + of the external ram. + The compiler does +\emph on +not +\emph default + reserve any space for variables declared in this way +\begin_inset Marginal +collapsed true + +\layout Standard + +\series bold +\SpecialChar ~ +! + +\end_inset + + (they are implemented with an equate in the assembler). + Thus it is left to the programmer to make sure there are no overlaps with + other variables that are declared without the absolute address. + The assembler listing file (.lst +\begin_inset LatexCommand \index{.lst} + +\end_inset + +) and the linker output files (.rst +\begin_inset LatexCommand \index{.rst} + +\end_inset + +) and (.map +\begin_inset LatexCommand \index{.map} + +\end_inset + +) are good places to look for such overlaps. + Variables with an absolute address are +\emph on +not +\begin_inset Marginal +collapsed true + +\layout Standard + +\series bold +\SpecialChar ~ +! + +\end_inset + + +\emph default + initialized +\begin_inset LatexCommand \index{Variable initialization} + +\end_inset + +. + +\layout Standard +In case of memory mapped I/O devices the keyword +\emph on +volatile +\emph default + has to be used to tell the compiler that accesses might not be removed: + +\layout Verse + +\family typewriter +volatile +\begin_inset LatexCommand \index{volatile} + +\end_inset + + __xdata +\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)} + +\end_inset + + __at +\begin_inset LatexCommand \index{at} + +\end_inset + + (0x8000) unsigned char PORTA_8255; + +\layout Standard +For some architectures (mcs51) array accesses are more efficient if an (xdata/fa +r) array +\family typewriter +\size footnotesize + +\begin_inset LatexCommand \index{Aligned array} + +\end_inset + + +\family default +\size default + starts at a block (256 byte) boundary +\begin_inset LatexCommand \index{block boundary} + +\end_inset + + (section +\begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction} + +\end_inset + + has an example). +\newline +Absolute addresses can be specified for variables in all + storage classes, e.g.: + +\layout Verse + +\family typewriter +__bit +\begin_inset LatexCommand \index{bit} + +\end_inset + + __at +\begin_inset LatexCommand \index{at} + +\end_inset + + (0x02) bvar; + +\layout Standard +The above example will allocate the variable at offset 0x02 in the bit-addressab +le space. + There is no real advantage to assigning absolute addresses to variables + in this manner, unless you want strict control over all the variables allocated. + One possible use would be to write hardware portable code. + For example, if you have a routine that uses one or more of the microcontroller + I/O pins, and such pins are different for two different hardwares, you + can declare the I/O pins in your routine using: + +\layout Verse + +\family typewriter +extern volatile +\begin_inset LatexCommand \index{volatile} + +\end_inset + + __bit MOSI;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* master out, slave in */ +\newline +extern volatile __bit MISO;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* master + in, slave out */ +\newline +extern volatile __bit MCLK;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* master clock */ +\newline + +\newline +/* Input and + Output of a byte on a 3-wire serial bus. +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +If needed adapt polarity of clock, + polarity of data and bit order +\newline +\SpecialChar ~ +*/ +\newline +unsigned char spi_io(unsigned char out_byte) + +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +unsigned char i=8; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +do { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +MOSI = out_byte & 0x80; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +out_byte <<= 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +MCLK = + 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* _asm nop _endasm; */\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* for slow peripherals */ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +if(MISO) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +out_byte += + 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +MCLK = 0; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +} while(--i); +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return out_byte; +\newline +} + +\layout Standard +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 ~ +/* I/O port 1, bit 2 */ + +\layout Standard +\added_space_bottom bigskip +and you can use the same hardware dependent routine without changes, as + for example in a library. + This is somehow similar to sbit, but only one absolute address has to be + specified in the whole project. + + + +\layout Section +Parameters +\begin_inset LatexCommand \index{Parameters} + +\end_inset + + +\begin_inset LatexCommand \index{function parameter} + +\end_inset + + & Local Variables +\begin_inset LatexCommand \index{local variables} + +\end_inset + + +\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables} + +\end_inset + + + +\layout Standard +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} + +\end_inset + + +\emph default + so by default functions are non-reentrant +\begin_inset LatexCommand \index{reentrant} + +\end_inset + +. + +\newline + +\newline +They can be placed on the stack +\begin_inset LatexCommand \index{stack} + +\end_inset + + by using the +\emph on + - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} + +\end_inset + + +\emph default + option, by using +\emph on +#pragma\SpecialChar ~ +stackauto +\emph default + +\begin_inset LatexCommand \index{\#pragma stackauto} + +\end_inset + + or by using the +\emph on +reentrant +\begin_inset LatexCommand \index{reentrant} + +\end_inset + + +\emph default + keyword in the function declaration, e.g.: + +\layout Verse + +\family typewriter +unsigned char foo(char i) __reentrant +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +} + +\layout Standard +Since stack space on 8051 is limited, the +\emph on +reentrant +\emph default +keyword or the +\emph on + - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto +\emph default + option should be used sparingly. + Note that the reentrant keyword just means that the parameters & local + variables will be allocated to the stack, it +\emph on +does not +\emph default + mean that the function is register bank +\begin_inset LatexCommand \index{register bank (mcs51, ds390)} + +\end_inset + + independent. +\newline + +\newline +Local variables +\begin_inset LatexCommand \index{local variables} + +\end_inset + + can be assigned storage classes and absolute +\begin_inset LatexCommand \index{Absolute addressing} + +\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} + +\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, +\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 + +-stack-auto +\emph default + or when a function is declared as +\emph on +reentrant +\emph default + this should only be done for static variables. + +\layout Standard +Parameters +\begin_inset LatexCommand \index{function parameter} + +\end_inset + + however are not allowed any storage class +\begin_inset LatexCommand \index{Storage class} + +\end_inset + +, (storage classes for parameters will be ignored), their allocation is + governed by the memory model in use, and the reentrancy options. + +\layout Standard +It is however allowed to use bit parameters in reentrant functions and also + non-static local bit variables are supported. + Efficient use is limited to 8 semi-bitregisters in bit space. + They are pushed and popped to stack +\begin_inset LatexCommand \index{stack} + +\end_inset + + as a single byte just like the normal registers. + +\layout Section +Overlaying +\begin_inset LatexCommand \label{sub:Overlaying} + +\end_inset + + +\begin_inset LatexCommand \index{Overlaying} + +\end_inset + + + +\layout Standard +For non-reentrant +\begin_inset LatexCommand \index{reentrant} + +\end_inset + + functions SDCC will try to reduce internal ram space usage by overlaying + parameters and local variables of a function (if possible). + Parameters and local variables +\begin_inset LatexCommand \index{local variables} + +\end_inset + + of a function will be allocated to an overlayable segment if the function + has +\emph on +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 + 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 +Note that the compiler (not the linkage editor) makes the decision for overlayin +g the data items. + Functions that are called from an interrupt service routine +\begin_inset Marginal +collapsed true + +\layout Standard + +\series bold +! + +\end_inset + + should be preceded by a #pragma\SpecialChar ~ +nooverlay +\begin_inset LatexCommand \index{\#pragma nooverlay} + +\end_inset + + if they are not reentrant. + +\layout Standard +Also note that the compiler does not do any processing of inline assembler + code, so the compiler might incorrectly assign local variables and parameters + of a function into the overlay segment if the inline assembler code calls + other c-functions that might use the overlay. + In that case the #pragma\SpecialChar ~ +nooverlay should be used. + +\layout Standard +Parameters and local variables of functions that contain 16 or 32 bit multiplica +tion +\begin_inset LatexCommand \index{Multiplication} + +\end_inset + + or division +\begin_inset LatexCommand \index{Division} + +\end_inset + + will NOT be overlayed since these are implemented using external functions, + e.g.: + +\layout Verse + +\family typewriter +#pragma save +\newline +#pragma nooverlay +\begin_inset LatexCommand \index{\#pragma nooverlay} + +\end_inset + + +\newline +void set_error(unsigned char errcd) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +P3 = errcd; +\newline +} +\newline +#pragma restore +\newline + +\newline +void + some_isr () __interrupt +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + (2) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +set_error(10); +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +} + +\layout Standard +\added_space_bottom bigskip +In the above example the parameter +\emph on +errcd +\emph default + for the function +\emph on +set_error +\emph default + would be assigned to the overlayable segment if the #pragma\SpecialChar ~ +nooverlay was + not present, this could cause unpredictable runtime behavior when called + from an interrupt service routine. + The #pragma\SpecialChar ~ +nooverlay ensures that the parameters and local variables for + the function are NOT overlayed. + + + +\layout Section +Interrupt Service Routines +\begin_inset LatexCommand \label{sub:Interrupt-Service-Routines} + +\end_inset + + + +\layout Subsection +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 + +\family typewriter +void timer_isr (void) __interrupt (1) __using (1) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +} + +\layout Standard +The optional number following the +\emph on +interrupt +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_interrupt} + +\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 +\begin_inset LatexCommand \index{interrupt vector table} + +\end_inset + + 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 (8051 specific) keyword +\emph on +using +\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)} + +\end_inset + + +\emph default + can be used to tell the compiler to use the specified register bank when + generating code for this function. + +\newline +Interrupt service routines open the door for some very interesting bugs: + +\layout Subsubsection +\begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-volatile} + +\end_inset + +Common interrupt pitfall: variable not declared +\emph on +volatile + +\layout Standard +If an interrupt service routine changes variables which are accessed by + other functions these variables have to be declared +\emph on +volatile +\emph default + +\begin_inset LatexCommand \index{volatile} + +\end_inset + +. + See +\begin_inset LatexCommand \url{http://en.wikipedia.org/wiki/Volatile_variable} + +\end_inset + + . + +\layout Subsubsection +\begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-atomic} + +\end_inset + +Common interrupt pitfall: +\emph on +non-atomic access + +\layout Standard +If the access to these variables is not +\emph on +atomic +\begin_inset LatexCommand \index{atomic} + +\end_inset + + +\emph default + (i.e. + the processor needs more than one instruction for the access and could + be interrupted while accessing the variable) the interrupt must be disabled + during the access to avoid inconsistent data. + +\newline +Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs + and should be protected by disabling interrupts. + You're not automatically on the safe side if you use 8 bit variables though. + We need an example here: f.e. + on the 8051 the harmless looking +\begin_inset Quotes srd +\end_inset + + +\family typewriter +flags\SpecialChar ~ +|=\SpecialChar ~ +0x80; +\family default + +\begin_inset Quotes sld +\end_inset + + is not atomic if +\family typewriter +flags +\family default + resides in xdata. + Setting +\begin_inset Quotes srd +\end_inset + + +\family typewriter +flags\SpecialChar ~ +|=\SpecialChar ~ +0x40; +\family default + +\begin_inset Quotes sld +\end_inset + + from within an interrupt routine might get lost if the interrupt occurs + at the wrong time. + +\begin_inset Quotes sld +\end_inset + + +\family typewriter +counter\SpecialChar ~ ++=\SpecialChar ~ +8; +\family default + +\begin_inset Quotes srd +\end_inset + + is not atomic on the 8051 even if +\family typewriter +counter +\family default + is located in data memory. +\newline +Bugs like these are hard to reproduce and can + cause a lot of trouble. + + +\layout Subsubsection +\begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-stack-overflow} + +\end_inset + +Common interrupt pitfall: +\emph on +stack overflow + +\layout Standard +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 + +\begin_inset LatexCommand \index{stack overflow} + +\end_inset + + is most likely to happen if the interrupt occurs during the +\begin_inset Quotes sld +\end_inset + +deepest +\begin_inset Quotes srd +\end_inset + + subroutine when the stack is already in use for f.e. + many return addresses. + +\layout Subsubsection +\begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-reentrant} + +\end_inset + +Common interrupt pitfall: +\emph on +use of non-reentrant functions + +\layout Standard +A special note here, int (16 bit) and long (32 bit) integer division +\begin_inset LatexCommand \index{Division} + +\end_inset + +, multiplication +\begin_inset LatexCommand \index{Multiplication} + +\end_inset + + & modulus +\begin_inset LatexCommand \index{Modulus} + +\end_inset + + and floating-point +\begin_inset LatexCommand \index{Floating point support} + +\end_inset + + operations are implemented using external support routines. + If an interrupt service routine needs to do any of these operations then + the support routines (as mentioned in a following section) will have to + be recompiled using the +\emph on + - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} + +\end_inset + + +\emph default + option and the source file will need to be compiled using the +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-int-long-reent +\emph default + +\begin_inset LatexCommand \index{-\/-int-long-reent} + +\end_inset + + compiler option. + +\newline +Note, the type promotion +\begin_inset LatexCommand \index{type promotion} + +\end_inset + + required by ANSI C can cause 16 bit routines to be used +\begin_inset Marginal +collapsed true + +\layout Standard + +\series bold +\SpecialChar ~ +! + +\end_inset + + without the programmer being aware of it. + See f.e. + the cast +\family typewriter +(unsigned char)(tail-1) +\family default + within the if clause in section +\begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction} + +\end_inset + +. + +\layout Standard +\added_space_bottom bigskip +Calling other functions from an interrupt service routine is not recommended, + avoid it if possible. + Note that when some function is called from an interrupt service routine + it should be preceded by a #pragma\SpecialChar ~ +nooverlay +\begin_inset LatexCommand \index{\#pragma nooverlay} + +\end_inset + + if it is not reentrant. + Furthermore nonreentrant functions should not be called from the main program + while the interrupt service routine might be active. + They also must not be called from low priority interrupt service routines + while a high priority interrupt service routine might be active. + You could use semaphores or make the function +\emph on + critical +\emph default + if all parameters are passed in registers. +\newline + Also see section +\begin_inset LatexCommand \ref{sub:Overlaying} + +\end_inset + +\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 +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + numbers and the corresponding address & descriptions for the Standard 8051/8052 + are listed below. + SDCC will automatically adjust the +\begin_inset LatexCommand \index{interrupt vector table} + +\end_inset + + to the maximum interrupt number specified. +\newline + + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard +Interrupt # + +\end_inset + + +\begin_inset Text + +\layout Standard +Description + +\end_inset + + +\begin_inset Text + +\layout Standard +Vector Address + +\end_inset + + + + +\begin_inset Text + +\layout Standard +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 +4 + +\end_inset + + +\begin_inset Text + +\layout Standard +Serial + +\end_inset + + +\begin_inset Text + +\layout Standard +0x0023 + +\end_inset + + + + +\begin_inset Text + +\layout Standard +5 + +\end_inset + + +\begin_inset Text + +\layout Standard +Timer 2 (8052) + +\end_inset + + +\begin_inset Text + +\layout Standard +0x002b + +\end_inset + + + + +\begin_inset Text + +\layout Standard +... + +\end_inset + + +\begin_inset Text + +\layout Standard + + +\end_inset + + +\begin_inset Text + +\layout Standard +... + +\end_inset + + + + +\begin_inset Text + +\layout Standard +n + +\end_inset + + +\begin_inset Text + +\layout Standard + + +\end_inset + + +\begin_inset Text + +\layout Standard +0x0003 + 8*n + +\end_inset + + + + +\end_inset + + +\newline + + +\layout Standard +If the interrupt service routine is defined without +\emph on +using +\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)} + +\end_inset + + +\emph default + a register bank or with register bank 0 ( +\emph on +using +\emph default + 0), the compiler will save the registers used by itself on the stack upon + entry and restore them at exit, however if such an interrupt service routine + calls another function then the entire register bank will be saved on the + stack. + This scheme may be advantageous for small interrupt service routines which + have low register usage. + +\layout Standard +\added_space_bottom bigskip +If the interrupt service routine is defined to be using a specific register + bank then only +\emph on +a, b, dptr +\emph default + & psw are saved and restored, if such an interrupt service routine calls + another function (using another register bank) then the entire register + bank of the called function will be saved on the stack +\begin_inset LatexCommand \index{stack} + +\end_inset + +. + This scheme is recommended for larger interrupt service routines. + + + +\layout Subsection +HC08 +\begin_inset LatexCommand \index{HC08} + +\end_inset + + Interrupt Service Routines + +\layout Standard +\added_space_bottom bigskip +Since the number of interrupts +\begin_inset LatexCommand \index{HC08!interrupt} + +\end_inset + + available is chip specific and the interrupt vector table always ends at + the last byte of memory, the interrupt numbers corresponds to the interrupt + vectors in reverse order of address. + For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt + 2 will use the interrupt vector at 0xfffa, and so on. + However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in + this way; instead see section +\begin_inset LatexCommand \ref{sub:Startup-Code} + +\end_inset + + for details on customizing startup. + + + +\layout Subsection +Z80 Interrupt Service Routines + +\layout Standard +The Z80 +\begin_inset LatexCommand \index{Z80} + +\end_inset + + uses several different methods for determining the correct interrupt +\begin_inset LatexCommand \index{Z80!interrupt} + +\end_inset + + vector depending on the hardware implementation. + Therefore, SDCC ignores the optional interrupt number and does not attempt + to generate an interrupt vector table. + +\layout Standard +By default, SDCC generates code for a maskable interrupt, which uses a RETI + instruction to return from the interrupt. + To write an interrupt handler for the non-maskable interrupt, which needs + a RETN instruction instead, add the +\emph on +critical +\emph default + keyword: + +\layout Verse + +\family typewriter +void nmi_isr (void) critical interrupt +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +} + +\layout Standard +\added_space_bottom bigskip +However if you need to create a non-interruptable interrupt service routine + you would also require the +\emph on +critical +\emph default + keyword. + To distinguish between this and an nmi_isr you must provide an interrupt + number. + + + +\layout Section +Enabling and Disabling Interrupts + +\layout Subsection +Critical Functions and Critical Statements + +\layout Standard +A special keyword may be associated with a block or a function declaring + it as +\emph on +critical +\emph default +. + SDCC will generate code to disable all interrupts +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + upon entry to a critical function and restore the interrupt enable to the + previous state before returning. + Nesting critical functions will need one additional byte on the stack +\begin_inset LatexCommand \index{stack} + +\end_inset + + for each call. + +\layout Verse + +\family typewriter +int foo () __critical +\begin_inset LatexCommand \index{critical} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_critical} + +\end_inset + + +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +} + +\layout Standard +The critical attribute maybe used with other attributes like +\emph on +reentrant. +\emph default + +\newline +The keyword +\emph on +critical +\emph default + may also be used to disable interrupts more locally: + +\layout Verse + +\family typewriter +__critical{ i++; } + +\layout Standard +More than one statement could have been included in the block. + +\layout Subsection +Enabling and Disabling Interrupts directly + +\layout Standard +Interrupts +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + can also be disabled and enabled directly (8051): + +\layout Verse + +\family typewriter +EA = 0;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +or:\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +EA_SAVE = EA; + +\layout Verse + +\family typewriter +...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +EA = 0; + +\layout Verse + +\family typewriter +EA = 1;\SpecialChar ~ +\SpecialChar ~ +\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 Verse + +\family typewriter +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +EA = EA_SAVE; + +\layout Standard +On other architectures which have seperate opcodes for enabling and disabling + interrupts you might want to make use of defines with inline assembly +\begin_inset LatexCommand \index{Assembler routines} + +\end_inset + + (HC08 +\begin_inset LatexCommand \index{HC08!interrupt} + +\end_inset + +): + +\layout Verse + +\family typewriter +#define CLI _asm +\begin_inset LatexCommand \index{\_asm} + +\end_inset + +\SpecialChar ~ +\SpecialChar ~ +cli\SpecialChar ~ +\SpecialChar ~ +_endasm +\begin_inset LatexCommand \index{\_endasm} + +\end_inset + +; + +\layout Verse + +\family typewriter +#define SEI _asm\SpecialChar ~ +\SpecialChar ~ +sei\SpecialChar ~ +\SpecialChar ~ +_endasm; + +\layout Verse + +\family typewriter +... + +\layout Standard +Note: it is sometimes sufficient to disable only a specific interrupt source + like f.e. + a timer or serial interrupt by manipulating an +\emph on +interrupt mask +\begin_inset LatexCommand \index{interrupt mask} + +\end_inset + + +\emph default + register. + + +\layout Standard +Usually the time during which interrupts are disabled should be kept as + short as possible. + This minimizes both +\emph on +interrupt latency +\emph default + +\begin_inset LatexCommand \index{interrupt latency} + +\end_inset + + (the time between the occurrence of the interrupt and the execution of + the first code in the interrupt routine) and +\emph on +interrupt jitter +\emph default + +\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 +You can reenable interrupts within an interrupt routine and on some architecture +s you can make use of two (or more) levels of +\emph on +interrupt priorities +\emph default + +\begin_inset LatexCommand \index{interrupt priority} + +\end_inset + +. + 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 + +\newline +if (resource_is_free) +\newline +\SpecialChar ~ +\SpecialChar ~ +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +resource_is_free=0; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +resource_is_free=1; +\newline +\SpecialChar ~ +\SpecialChar ~ +} + +\layout Standard +Note, mcs51 and ds390 support only an atomic +\begin_inset LatexCommand \index{atomic} + +\end_inset + + bit test and +\emph on +clear +\emph default + instruction (as opposed to atomic bit test and +\emph on +set). + +\layout Section +Functions using private register banks +\begin_inset LatexCommand \label{sub:Functions-using-private-banks} + +\end_inset + + (mcs51/ds390) + +\layout Standard +Some architectures have support for quickly changing register sets. + SDCC supports this feature with the +\emph on +using +\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)} + +\end_inset + + +\emph default + attribute (which tells the compiler to use a register bank +\begin_inset LatexCommand \index{register bank (mcs51, ds390)} + +\end_inset + + other than the default bank zero). + It should only be applied to +\emph on +interrupt +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + +\emph default + functions (see footnote below). + This will in most circumstances make the generated ISR code more efficient + since it will not have to save registers on the stack. + +\layout Standard +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 +possible exception: if a function is called ONLY from 'interrupt' functions + using a particular bank, it can be declared with the same 'using' attribute + as the calling 'interrupt' functions. + For instance, if you have several ISRs using bank one, and all of them + call memcpy(), it might make sense to create a specialized version of memcpy() + 'using 1', since this would prevent the ISR from having to save bank zero + to the stack on entry and switch to bank zero before calling the function + +\end_inset + +). +\newline + +\emph on +(pending: Note, nowadays the +\emph default +using +\emph on + attribute has an effect on +\emph default + +\emph on +the generated code for a +\emph default +non-interrupt +\emph on + function +\emph default +. +\emph on +) + +\layout Standard +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{interrupt priority} + +\end_inset + + can interrupt low-priority ones on the 8051 and friends, this means that + if a high-priority ISR +\emph on +using +\emph default + a particular bank occurs while processing a low-priority ISR +\emph on +using +\emph default + the same bank, terrible and bad things can happen. + To prevent this, no single register bank should be +\emph on +used +\emph default + by both a high priority and a low priority ISR. + This is probably most easily done by having all high priority ISRs use + one bank and all low priority ISRs use another. + If you have an ISR which can change priority at runtime, you're on your + own: I suggest using the default bank zero and taking the small performance + hit. + +\layout Standard +\added_space_bottom bigskip +It is most efficient if your ISR calls no other functions. + If your ISR must call other functions, it is most efficient if those functions + use the same bank as the ISR (see note 1 below); the next best is if the + called functions use bank zero. + It is very inefficient to call a function using a different, non-zero bank + from an ISR. + + + + +\layout Section +Startup Code +\begin_inset LatexCommand \label{sub:Startup-Code} + +\end_inset + + +\begin_inset LatexCommand \index{Startup code} + +\end_inset + + + +\layout Subsection +MCS51/DS390 Startup Code + +\layout Standard +The compiler triggers the linker to link certain initialization modules + from the runtime library +\begin_inset LatexCommand \index{Runtime library} + +\end_inset + + called crt. + Only the necessary ones are linked, for instance crtxstack.asm (GSINIT1, + GSINIT5) is not linked unless the --xstack option is used. + These modules are highly entangled by the use of special segments/areas, + but a common layout is shown below: + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(main.asm) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area HOME (CODE) +\newline +__interrupt_vect: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ljmp __sdcc_gsinit_startup + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(crtstart.asm) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area GSINIT0 (CODE) +\newline +__sdcc_gsinit_startup:: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov sp,#__start__stack - 1 + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(crtxstack.asm) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area GSINIT1 (CODE) +\newline +__sdcc_init_xstack:: +\newline +; Need to initialize in GSINIT1 in + case the user's __sdcc_external_startup uses the xstack. +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov __XPAGE,#(__start__x +stack >> 8) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov _spx,#__start__xstack + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(crtstart.asm) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area GSINIT2 (CODE) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +lcall __sdcc_external_startup +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov a,dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +jz __sdcc_init_data +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ljmp + __sdcc_program_startup +\newline +__sdcc_init_data: + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(crtxinit.asm) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area GSINIT3 (CODE) +\newline +__mcs51_genXINIT:: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r1,#l_XINIT +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov a,r1 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +orl a,#(l_XINIT + >> 8) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +jz 00003$ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r2,#((l_XINIT+255) >> 8) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov dptr,#s_XINIT +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r0,#s_XISEG +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov + __XPAGE,#(s_XISEG >> 8) +\newline +00001$:\SpecialChar ~ +clr a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +movc a,@a+dptr +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +movx @r0,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc dptr +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc + r0 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +cjne r0,#0,00002$ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc __XPAGE +\newline +00002$:\SpecialChar ~ +djnz r1,00001$ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +djnz r2,00001$ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov __XPAGE,#0 +xFF +\newline +00003$: + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(crtclear.asm) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area GSINIT4 (CODE) +\newline +__mcs51_genRAMCLEAR:: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +clr a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r0,#(l_IRAM-1) +\newline +00004$:\SpecialChar ~ +mov + @r0,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +djnz r0,00004$ +\newline +; _mcs51_genRAMCLEAR() end + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(crtxclear.asm) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area GSINIT4 (CODE) +\newline +__mcs51_genXRAMCLEAR:: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r0,#l_PSEG +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov a,r0 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +jz 00006$ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov + r1,#s_PSEG +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov __XPAGE,#(s_PSEG >> 8) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +clr a +\newline +00005$:\SpecialChar ~ +movx @r1,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc r1 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +djnz r0,00005$ +\newline +0 +0006$: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r0,#l_XSEG +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov a,r0 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +orl a,#(l_XSEG >> 8) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +jz 00008$ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r1,#((l_XSEG + + 255) >> 8) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov dptr,#s_XSEG +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +clr a +\newline +00007$:\SpecialChar ~ +movx @dptr,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc dptr +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +djnz r0,00007$ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +djnz + r1,00007$ +\newline +00008$: + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(crtxstack.asm) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area GSINIT5 (CODE) +\newline +; Need to initialize in GSINIT5 because __mcs51_genXINIT + modifies __XPAGE +\newline +; and __mcs51_genRAMCLEAR modifies _spx. +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov __XPAGE,#(__start__x +stack >> 8) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov _spx,#__start__xstack + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(application modules) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area GSINIT (CODE) + +\layout Verse + +\family typewriter +\series bold +\size footnotesize +(main.asm) + +\layout Verse + +\family typewriter +\size footnotesize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area GSFINAL (CODE) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ljmp __sdcc_program_startup +\newline +;--------------------------------- +----------------------- +\newline +; Home +\newline +;-------------------------------------------------- +------ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area HOME (CODE) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area CSEG (CODE) +\newline +__sdcc_program_startup: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +lcall _main +\newline +; + return from main will lock up +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sjmp . + +\layout Standard +One of these modules (crtstart.asm) contains 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 also in the runtime library +\begin_inset LatexCommand \index{Runtime library} + +\end_inset + + and returns 0 by default. + 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 an +\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 +\begin_inset LatexCommand \index{watchdog} + +\end_inset + + 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 +\added_space_bottom bigskip +See also the compiler options +\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 + +, +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-main-return +\emph default + +\begin_inset LatexCommand \index{-\/-main-return} + +\end_inset + + and section +\begin_inset LatexCommand \ref{sub:MCS51-variants} + +\end_inset + + about MCS51-variants. + + + +\layout Subsection +HC08 Startup Code + +\layout Standard +\added_space_bottom bigskip +The HC08 +\begin_inset LatexCommand \index{HC08} + +\end_inset + + startup code follows the same scheme as the MCS51 startup code. + + + +\layout Subsection +Z80 Startup Code + +\layout Standard +\added_space_bottom bigskip +On the Z80 +\begin_inset LatexCommand \index{Z80} + +\end_inset + + 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 +\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 +unsigned char head, tail;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* if interrupts +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + are involved see +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +section +\begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile} + +\end_inset + + about +\series bold + volatile +\series default + */ +\newline + +\newline +void to_buffer( unsigned char c ) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +if( head != (unsigned char)(tail-1) + )\SpecialChar ~ +/* cast +\series bold +needed +\series default + to avoid promotion +\begin_inset LatexCommand \index{promotion to signed int} + +\end_inset + + +\begin_inset LatexCommand \index{type promotion} + +\end_inset + + to integer */ +\begin_inset Marginal +collapsed true + +\layout Standard + +\series bold +\SpecialChar ~ +! + +\end_inset + + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +buf[ head++ ] = c;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* access to a 256 byte aligned array */ +\newline +} + +\layout Standard +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 ~ +_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) ) \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 */ +\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 + + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +r3,_head +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc\SpecialChar ~ +\SpecialChar ~ +_head +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +dpl,r3 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +dph,#(_buf >> 8) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +a,r2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +movx @dptr,a + +\newline +00103$: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ret +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_endasm +\begin_inset LatexCommand \index{\_endasm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_endasm} + +\end_inset + +; +\newline +} + +\layout Standard +The new file buffer.c should compile with only one warning about the unreferenced + function argument 'c'. + Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY + (1) and finally have: + +\layout Verse + +\family typewriter +\size footnotesize +unsigned char __far __at(0x7f00) buf[0x100]; +\newline +unsigned char head, tail; +\newline +#define + USE_ASSEMBLY (1) +\newline + +\newline +#if !USE_ASSEMBLY +\newline + +\newline +void to_buffer( unsigned char c ) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +if( + head != (unsigned char)(tail-1) ) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +buf[ head++ ] = c; +\newline +} +\newline + +\newline +#else +\newline + +\newline +void to_buffer( + unsigned char c ) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +c; // to avoid warning: unreferenced function argument +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_asm +\begin_inset LatexCommand \index{\_asm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_asm} + +\end_inset + + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; save used registers here. + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; If we were still using r2,r3 we would have to push them here. + +\newline +; if( head != (unsigned char)(tail-1) ) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ + a,_tail +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dec\SpecialChar ~ + a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +xrl\SpecialChar ~ + a,_head +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; we + could do an ANL a,#0x0f here to use a smaller buffer (see below) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +jz\SpecialChar ~ +\SpecialChar ~ + t_b_end$ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; +\newline +; + buf[ head++ ] = c; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ + a,dpl \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; dpl holds lower byte of function argument +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ + + dpl,_head \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; buf is 0x100 byte aligned so head can be used directly +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ + dph,#(_bu +f>>8) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +movx @dptr,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc \SpecialChar ~ +_head +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; we could do an ANL _head,#0x0f here to use a + smaller buffer (see above) +\newline +t_b_end$: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; restore used registers here +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_endasm +\begin_inset LatexCommand \index{\_endasm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_endasm} + +\end_inset + +; +\newline +} +\newline +#endif + +\layout Standard +The inline assembler code can contain any valid code understood by the assembler +, this includes any assembler directives and comment lines. + The assembler does not like some characters like ':' or ''' in comments. + You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html +\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)} + +\end_inset + + +\begin_inset LatexCommand \index{Assembler documentation} + +\end_inset + + or online at +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html} + +\end_inset + +\SpecialChar ~ +. + +\layout Standard +The compiler does not do any validation of the code within the +\family typewriter +_asm +\begin_inset LatexCommand \index{\_asm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_asm} + +\end_inset + + ... + _endasm +\size footnotesize + +\begin_inset LatexCommand \index{\_endasm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_endasm} + +\end_inset + + +\size default +; +\family default + keyword pair. + Specifically it will not know which registers are used and thus register + pushing/popping +\begin_inset LatexCommand \index{push/pop} + +\end_inset + + has to be done manually. + + +\layout Standard +It is recommended that each assembly instruction (including labels) be placed + in a separate line (as the example shows). + When the - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +- +\emph on +peep-asm +\begin_inset LatexCommand \index{-\/-peep-asm} + +\end_inset + + +\emph default + command line option is used, the inline assembler code will be passed through + the peephole optimizer +\begin_inset LatexCommand \index{Peephole optimizer} + +\end_inset + +. + There are only a few (if any) cases where this option makes sense, it might + cause some unexpected changes in the inline assembler code. + Please go through the peephole optimizer rules defined in file +\emph on +SDCCpeeph.def +\emph default + before using this option. + +\layout Subsection +Naked Functions +\begin_inset LatexCommand \label{sub:Naked-Functions} + +\end_inset + + +\begin_inset LatexCommand \index{Naked functions} + +\end_inset + + + +\layout Standard +A special keyword may be associated with a function declaring it as +\emph on +_naked +\begin_inset LatexCommand \index{\_naked} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_naked} + +\end_inset + +. + +\emph default +The +\emph on +_naked +\emph default + function modifier attribute prevents the compiler from generating prologue +\begin_inset LatexCommand \index{function prologue} + +\end_inset + + and epilogue +\begin_inset LatexCommand \index{function epilogue} + +\end_inset + + code for that function. + This means that the user is entirely responsible for such things as saving + any registers that may need to be preserved, selecting the proper register + bank, generating the +\emph on +return +\emph default + instruction at the end, etc. + Practically, this means that the contents of the function must be written + in inline assembler. + This is particularly useful for interrupt functions, which can have a large + (and often unnecessary) prologue/epilogue. + For example, compare the code generated by these two functions: + +\layout Verse + +\family typewriter +volatile +\begin_inset LatexCommand \index{volatile} + +\end_inset + + data unsigned char counter; +\newline + +\newline +void simpleInterrupt(void) __interrupt +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_interrupt} + +\end_inset + + (1) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +counter++; +\newline +} +\newline + +\newline +void nakedInterrupt(void) __interrupt (2) __naked +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_asm +\begin_inset LatexCommand \index{\_asm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_asm} + +\end_inset + + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_counter ; does not change flags, no need to save psw +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +reti\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; MUST explicitly + include ret or reti in _naked function. +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_endasm +\begin_inset LatexCommand \index{\_endasm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_endasm} + +\end_inset + +; +\newline +} + +\layout Standard +For an 8051 target, the generated simpleInterrupt looks like: + +\layout Verse + +\family typewriter +Note, this is an +\emph on +outdated +\emph default + example, recent versions of SDCC generate +\newline +the +\emph on +same +\emph default + code for simpleInterrupt() and nakedInterrupt()! +\newline + +\newline +_simpleInterrupt: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +acc +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +b +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pu +sh\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dph +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +psw +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +psw,#0x00 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_counter +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +psw +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dph +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +b +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +acc +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +reti + +\layout Standard +whereas nakedInterrupt looks like: + +\layout Verse + +\family typewriter +_nakedInterrupt: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +inc\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_counter ; does not change flags, no need to save psw +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +reti\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; + MUST explicitly include ret or reti in _naked function + +\layout Standard +The related directive #pragma exclude +\begin_inset LatexCommand \index{\#pragma exclude} + +\end_inset + + allows a more fine grained control over pushing & popping +\begin_inset LatexCommand \index{push/pop} + +\end_inset + + the registers. + +\layout Standard +While there is nothing preventing you from writing C code inside a +\family typewriter +_naked +\family default + function, there are many ways to shoot yourself in the foot doing this, + and it is recommended that you stick to inline assembler. + +\layout Subsection +Use of Labels within Inline Assembler + +\layout Standard +SDCC allows the use of in-line assembler with a few restrictions regarding + labels. + In older versions of the compiler all labels defined within inline assembler + code +\emph on +had to be +\emph default + of the form +\emph on +nnnnn$ +\emph default + where nnnn is a number less than 100 (which implies a limit of utmost 100 + inline assembler labels +\emph on +per function +\emph default +\noun on +) +\noun default +. + + +\layout Verse + +\family typewriter +_asm +\begin_inset LatexCommand \index{\_asm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_asm} + +\end_inset + + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +b,#10 +\newline +00001$: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +djnz\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +b,00001$ +\newline +_endasm +\begin_inset LatexCommand \index{\_endasm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_endasm} + +\end_inset + + ; + +\layout Standard +Inline assembler code cannot reference any C-Labels, however it can reference + labels +\begin_inset LatexCommand \index{Labels} + +\end_inset + + defined by the inline assembler, e.g.: + +\layout Verse + +\family typewriter +foo() { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* some c code */ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_asm +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; some assembler code +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ljmp $0003 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_endasm; + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* some more c code */ +\newline +clabel:\SpecialChar ~ +\SpecialChar ~ +/* inline assembler cannot reference this + label */ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_asm +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +$0003: ;label (can be referenced by inline assembler only) + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_endasm +\begin_inset LatexCommand \index{\_endasm} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_endasm} + +\end_inset + + ; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* some more c code */ +\newline +} + +\layout Standard +In other words inline assembly code can access labels defined in inline + assembly within the scope of the function. + The same goes the other way, i.e. + labels defines in inline assembly can not be accessed by C statements. + +\layout Section +Interfacing with Assembler Code +\begin_inset LatexCommand \index{Assembler routines} + +\end_inset + + + +\layout Subsection +Global Registers used for Parameter Passing +\begin_inset LatexCommand \index{Parameter passing} + +\end_inset + + + +\layout Standard +The compiler always uses the global registers +\emph on +DPL, DPH +\begin_inset LatexCommand \index{DPTR, DPH, DPL} + +\end_inset + + +\begin_inset LatexCommand \index{DPTR} + +\end_inset + +, B +\begin_inset LatexCommand \index{B (mcs51, ds390 register)} + +\end_inset + + +\emph default +and +\emph on + ACC +\begin_inset LatexCommand \index{ACC (mcs51, ds390 register)} + +\end_inset + + +\emph default + to pass the first parameter to a routine. + The second parameter onwards is either allocated on the stack (for reentrant + routines or if - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto is used) or in data / xdata memory (depending on the memory + model). + + +\layout Subsection +Assembler Routine (non-reentrant) + +\layout Standard +In the following example +\begin_inset LatexCommand \index{reentrant} + +\end_inset + + +\begin_inset LatexCommand \index{Assembler routines (non-reentrant)} + +\end_inset + + the function c_func calls an assembler routine asm_func, which takes two + parameters +\begin_inset LatexCommand \index{function parameter} + +\end_inset + +. + +\layout Verse + +\family typewriter +extern int asm_func(unsigned char, unsigned char); +\newline + +\newline +int c_func (unsigned char + i, unsigned char j) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return asm_func(i,j); +\newline +} +\newline + +\newline +int main() +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return c_func(10,9); +\newline +} + +\layout Standard +The corresponding assembler function is: + +\layout Verse + +\family typewriter +.globl _asm_func_PARM_2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.globl _asm_func +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area OSEG +\newline +_asm_func_PARM_2: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.ds + 1 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.area CSEG +\newline +_asm_func: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +a,dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +add\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +a,_asm_func_PARM_2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dpl,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +dph +\begin_inset LatexCommand \index{DPTR, DPH, DPL} + +\end_inset + +,#0x00 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ret + +\layout Standard +Note here that the return values +\begin_inset LatexCommand \index{return value} + +\end_inset + + are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for + two byte values. + 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph',' +b' & 'acc' for four byte values. + +\layout Standard +The parameter naming convention is __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 + + for two bytes, +\begin_inset Quotes eld +\end_inset + +b,dptr +\begin_inset Quotes erd +\end_inset + + for three bytes and +\begin_inset Quotes eld +\end_inset + +acc,b,dptr +\begin_inset Quotes erd +\end_inset + + for a four bytes parameter. + The variable name for the second parameter will be __PARM_2. +\newline + +\newline +Assem +ble the assembler routine with the following command: +\newline + +\newline + +\family sans +\series bold +asx8051 -losg asmfunc.asm +\newline + +\newline + +\family default +\series default +Then compile and link the assembler routine to the C source file with the + following command: +\newline + +\newline + +\family sans +\series bold +sdcc cfunc.c asmfunc.rel + +\layout Subsection +Assembler Routine (reentrant) + +\layout Standard +In this case +\begin_inset LatexCommand \index{reentrant} + +\end_inset + + +\begin_inset LatexCommand \index{Assembler routines (reentrant)} + +\end_inset + + the second parameter +\begin_inset LatexCommand \index{function parameter} + +\end_inset + + onwards will be passed on the stack, the parameters are pushed from right + to left i.e. + after the call the leftmost parameter will be on the top of the stack. + Here is an example: + +\layout Verse + +\family typewriter +extern int asm_func(unsigned char, unsigned char); +\newline + +\newline +int c_func (unsigned char + i, unsigned char j) reentrant +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return asm_func(i,j); +\newline +} +\newline + +\newline +int main() +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return + c_func(10,9); +\newline +} + +\layout Standard +The corresponding assembler routine is: + +\layout Verse + +\family typewriter +.globl _asm_func +\newline +_asm_func: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +push _bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov _bp,sp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r2,dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov a,_bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +add + a,#0xfd +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r0,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +add a,#0xfc ;? +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov r1,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov a,@r0 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +add a,r2 ;? +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov dpl,a + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov dph,#0x00 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov sp,_bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +pop _bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ret + +\layout Standard +\added_space_bottom bigskip +The compiling and linking procedure remains the same, however note the extra + entry & exit linkage required for the assembler code, _bp is the stack + frame pointer and is used to compute the offset into the stack for parameters + and local variables. + + + +\layout Section +int (16 bit) +\begin_inset LatexCommand \index{int (16 bit)} + +\end_inset + + and long (32 bit) +\begin_inset LatexCommand \index{long (32 bit)} + +\end_inset + + Support + +\layout Standard +For signed & unsigned int (16 bit) and long (32 bit) variables, division, + multiplication and modulus operations are implemented by support routines. + These support routines are all developed in ANSI-C to facilitate porting + to other MCUs, although some model specific assembler optimizations are + used. + The following files contain the described routines, all of them can be + found in /share/sdcc/lib. +\newline + + +\layout Standard +\align center +\begin_inset Tabular + + + + + + +\begin_inset Text + +\layout Standard + +\series bold +Function + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Description + +\end_inset + + + + +\begin_inset Text + +\layout Standard +_mulint.c + +\end_inset + + +\begin_inset Text + +\layout Standard +16 bit multiplication + +\end_inset + + + + +\begin_inset Text + +\layout Standard +_divsint.c + +\end_inset + + +\begin_inset Text + +\layout Standard + signed 16 bit division (calls _divuint) + +\end_inset + + + + +\begin_inset Text + +\layout Standard +_divuint.c + +\end_inset + + +\begin_inset Text + +\layout Standard + unsigned 16 bit division + +\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 +_moduint.c + +\end_inset + + +\begin_inset Text + +\layout Standard +unsigned 16 bit modulus + +\end_inset + + + + +\begin_inset Text + +\layout Standard +_mullong.c + +\end_inset + + +\begin_inset Text + +\layout Standard +32 bit multiplication + +\end_inset + + + + +\begin_inset Text + +\layout Standard +_divslong.c + +\end_inset + + +\begin_inset Text + +\layout Standard + signed 32 division (calls _divulong) + +\end_inset + + + + +\begin_inset Text + +\layout Standard +_divulong.c + +\end_inset + + +\begin_inset Text + +\layout Standard +unsigned 32 division + +\end_inset + + + + +\begin_inset Text + +\layout Standard +_modslong.c + +\end_inset + + +\begin_inset Text + +\layout Standard + 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 + + + + +\end_inset + + +\newline + + +\layout Standard +Since they are compiled as +\emph on +non-reentrant +\emph default + +\begin_inset LatexCommand \index{reentrant} + +\end_inset + +, interrupt +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + service routines should not do any of the above operations. + If this is unavoidable then the above routines will need to be compiled + with the +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} + +\end_inset + + +\emph default + option, after which the source program will have to be compiled with +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-int-long-reent +\begin_inset LatexCommand \index{-\/-int-long-reent} + +\end_inset + + +\emph default + option. + Notice that you don't have to call these routines directly. + The compiler will use them automatically every time an integer operation + is required. + +\layout Section +Floating Point Support +\begin_inset LatexCommand \index{Floating point support} + +\end_inset + + + +\layout Standard +SDCC supports IEEE (single precision 4 bytes) floating point numbers. + The floating point support routines are derived from gcc's floatlib.c and + consist of the following routines: +\newline + + +\layout Standard +\align center + +\size footnotesize +\begin_inset Tabular + + + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +Function + +\end_inset + + +\begin_inset Text + +\layout Standard +Description + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fsadd.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +add floating point numbers + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fssub.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +subtract floating point numbers + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fsdiv.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +divide floating point numbers + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fsmul.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +multiply floating point numbers + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2uchar.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to unsigned char + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2char.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to signed char + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2uint.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to unsigned int + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2int.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to signed int + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2ulong. +\family default +\series default +\shape default +\size default +\emph default +\bar default +\noun default +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 floating point to unsigned long + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_fs2long.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert floating point to signed long + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_uchar2fs.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert unsigned char to floating point + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_char2fs.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert char to floating point number + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_uint2fs.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert unsigned int to floating point + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_int2fs.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert int to floating point numbers + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_ulong2fs.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert unsigned long to floating point number + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +_long2fs.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +convert long to floating point number + +\end_inset + + + + +\end_inset + + +\newline + + +\layout Standard +\added_space_bottom bigskip +These support routines are developed in ANSI-C so there is room for space + and speed improvement +\begin_inset Foot +collapsed false + +\layout Standard +These floating point routines ( +\emph on +not +\emph default + sinf(), cosf(), ...) for the mcs51 are implemented in assembler. + + +\end_inset + +. + Note if all these routines are used simultaneously the data space might + overflow. + For serious floating point usage the large model might be needed. + Also notice that you don't have to call this routines directly. + The compiler will use them automatically every time a floating point operation + is required. + + + +\layout Section +Library Routines +\begin_inset LatexCommand \index{Libraries} + +\end_inset + + + +\layout Standard + +\emph on + + +\layout Subsection +Compiler support routines (_gptrget, _mulint etc.) + +\layout Subsection +Stdclib functions (puts, printf, strcat etc.) + +\layout Subsubsection + + +\layout Paragraph +getchar(), putchar() + +\layout Standard +\begin_inset LatexCommand \index{} + +\end_inset + +As usual on embedded systems you have to provide your own +\family typewriter +getchar() +\begin_inset LatexCommand \index{getchar()} + +\end_inset + + +\family default +and +\family typewriter +putchar() +\begin_inset LatexCommand \index{putchar()} + +\end_inset + + +\family default + routines. + SDCC does not know whether the system connects to a serial line with or + without handshake, LCD, keyboard or other device. + And whether a +\family typewriter +lf +\family default + to +\family typewriter +crlf +\family default + conversion within +\family typewriter +putchar() +\family default + is intended. + You'll find examples for serial routines f.e. + in sdcc/device/lib. + For the mcs51 this minimalistic polling +\family typewriter +putchar() +\family default + routine might be a start: + +\layout Verse + +\family typewriter +void putchar (char c) { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +while (!TI)\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + /* assumes UART is initialized */ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +TI + = 0; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SBUF = c; +\newline +} + +\layout Paragraph +printf() + +\layout Standard +The default +\family typewriter + printf() +\begin_inset LatexCommand \index{printf()} + +\end_inset + + +\family default + implementation in +\family typewriter + printf_large.c +\family default + does not support float (except on ds390). + To enable this recompile it with the option +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +DUSE_FLOATS=1 +\begin_inset LatexCommand \index{USE\_FLOATS} + +\end_inset + + +\emph default + on the command line. + Use +\emph on + - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-large +\begin_inset LatexCommand \index{-\/-model-large} + +\end_inset + + +\emph default + for the mcs51 port, since this uses a lot of memory. + +\layout Standard +If you're short on code memory you might want to use +\family typewriter +printf_small() +\begin_inset LatexCommand \index{printf\_small()} + +\end_inset + + +\family default + +\emph on +instead +\emph default + of +\family typewriter + printf(). + +\family default + For the mcs51 there additionally are assembly versions +\family typewriter +printf_tiny() +\begin_inset LatexCommand \index{printf\_tiny() (mcs51)} + +\end_inset + + +\family default + (subset of printf using less than 270 bytes) and +\family typewriter +printf_fast() +\begin_inset LatexCommand \index{printf\_fast() (mcs51)} + +\end_inset + + +\family default +and +\family typewriter + printf_fast_f() +\begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)} + +\end_inset + + +\family default + (floating-point aware version of printf_fast) which should fit the requirements + of many embedded systems (printf_fast() can be customized by unsetting + #defines to +\emph on +not +\emph default + support long variables and field widths). + Be sure to use only one of these printf options within a project. +\newline + + +\layout Standard +Feature matrix of different +\emph on +printf +\emph default + options on mcs51. + +\layout Standard +\begin_inset Tabular + + + + + + + + + + + +\begin_inset Text + +\layout Standard + +\series bold +\size large +mcs51 + +\end_inset + + +\begin_inset Text + +\layout Standard +printf +\begin_inset LatexCommand \index{printf} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +printf +\size scriptsize +USE_FLOATS=1 + +\end_inset + + +\begin_inset Text + +\layout Standard +printf_small + +\end_inset + + +\begin_inset Text + +\layout Standard +printf_fast + +\end_inset + + +\begin_inset Text + +\layout Standard +printf_fast_f + +\end_inset + + +\begin_inset Text + +\layout Standard +printf_tiny + +\end_inset + + + + +\begin_inset Text + +\layout Standard +filename + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size scriptsize +printf_large.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size scriptsize +printf_large.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size scriptsize +printfl.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size scriptsize +printf_fast.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size scriptsize +printf_fast_f.c + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size scriptsize +printf_tiny.c + +\end_inset + + + + +\begin_inset Text + +\layout Standard +\begin_inset Quotes sld +\end_inset + +Hello World +\begin_inset Quotes srd +\end_inset + + size + +\layout Standard +small / large + +\end_inset + + +\begin_inset Text + +\layout Standard +1.7k / 2.4k + +\end_inset + + +\begin_inset Text + +\layout Standard +4.3k / 5.6k + +\end_inset + + +\begin_inset Text + +\layout Standard +1.2k / 1.8k + +\end_inset + + +\begin_inset Text + +\layout Standard +1.3k / 1.3k + +\end_inset + + +\begin_inset Text + +\layout Standard +1.9k / 1.9k + +\end_inset + + +\begin_inset Text + +\layout Standard +0.44k / 0.44k + +\end_inset + + + + +\begin_inset Text + +\layout Standard +code size + +\layout Standard +small / large + +\end_inset + + +\begin_inset Text + +\layout Standard +1.4k / 2.0k + +\end_inset + + +\begin_inset Text + +\layout Standard +2.8k / 3.7k + +\end_inset + + +\begin_inset Text + +\layout Standard +0.45k / 0.47k (+ _ltoa) + +\end_inset + + +\begin_inset Text + +\layout Standard +1.2k / 1.2k + +\end_inset + + +\begin_inset Text + +\layout Standard +1.6k / 1.6k + +\end_inset + + +\begin_inset Text + +\layout Standard +0.26k / 0.26k + +\end_inset + + + + +\begin_inset Text + +\layout Standard +formats + +\end_inset + + +\begin_inset Text + +\layout Standard +cdi +\emph on +o +\emph default +psux + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +cd +\family default +\series default +\shape default +\size default +\emph default +\bar default +\noun default +f +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +i +\family default +\series default +\shape default +\size default +\emph on +\bar default +\noun default +o +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +psux + +\end_inset + + +\begin_inset Text + +\layout Standard +c +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +d +\family default +\series default +\shape default +\size default +\emph on +\bar default +\noun default +o +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +s +\family default +\series default +\shape default +\size default +\emph default +\bar default +\noun default +x + +\end_inset + + +\begin_inset Text + +\layout Standard +cdsux + +\end_inset + + +\begin_inset Text + +\layout Standard +cdfsux + +\end_inset + + +\begin_inset Text + +\layout Standard +cdsux + +\end_inset + + + + +\begin_inset Text + +\layout Standard +long (32 bit) support + +\end_inset + + +\begin_inset Text + +\layout Standard +x + +\end_inset + + +\begin_inset Text + +\layout Standard +x + +\end_inset + + +\begin_inset Text + +\layout Standard +x + +\end_inset + + +\begin_inset Text + +\layout Standard +x + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +x + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + + + +\begin_inset Text + +\layout Standard +byte arguments on stack + +\end_inset + + +\begin_inset Text + +\layout Standard +b + +\end_inset + + +\begin_inset Text + +\layout Standard +b + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + + + +\begin_inset Text + +\layout Standard +float format +\begin_inset LatexCommand \index{Floating point support} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +%f + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +%f +\begin_inset Foot +collapsed true + +\layout Standard +Range limited to +/- 4294967040, precision limited to 8 digits past decimal + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + + + +\begin_inset Text + +\layout Standard +float formats %e %g + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + + + +\begin_inset Text + +\layout Standard +field width + +\end_inset + + +\begin_inset Text + +\layout Standard +x + +\end_inset + + +\begin_inset Text + +\layout Standard +x + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +x + +\end_inset + + +\begin_inset Text + +\layout Standard +x + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + + + +\begin_inset Text + +\layout Standard +string speed +\begin_inset Foot +collapsed true + +\layout Standard +Execution time of printf("%s%c%s%c%c%c", "Hello", ' ', "World", '!', ' +\backslash +r', ' +\backslash +n'); standard 8051 @ 22.1184 MHz, empty putchar() + +\end_inset + +, + +\layout Standard +small / large + +\end_inset + + +\begin_inset Text + +\layout Standard +1.52 / 2.59 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +1.53 / 2.62 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +0.92 / 0.93 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +0.45 / 0.45 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +0.46 / 0.46 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +0.45 / 0.45 ms + +\end_inset + + + + +\begin_inset Text + +\layout Standard +int speed +\begin_inset Foot +collapsed true + +\layout Standard +Execution time of printf("%d", -12345); standard 8051 @ 22.1184 MHz, empty + putchar() + +\end_inset + +, + +\layout Standard +small / large + +\end_inset + + +\begin_inset Text + +\layout Standard +3.01 / 3.61 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +3.01 / 3.61 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +3.51 / 18.13 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +0.22 / 0.22 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +0.23 / 0.23 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +0.25 / 0.25 ms +\begin_inset Foot +collapsed true + +\layout Standard +printf_tiny integer speed is data dependent, worst case is 0.33 ms + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +long speed +\begin_inset Foot +collapsed true + +\layout Standard +Execution time of printf("%ld", -123456789); standard 8051 @ 22.1184 MHz, + empty putchar() + +\end_inset + +, + +\layout Standard +small / large + +\end_inset + + +\begin_inset Text + +\layout Standard +5.37 / 6.31 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +5.37 / 6.31 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +8.71 / 40.65 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +0.40 / 0.40 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +0.40 / 0.40 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + + + +\begin_inset Text + +\layout Standard +float speed +\begin_inset Foot +collapsed true + +\layout Standard +Execution time of printf("%.3f", -12345.678); standard 8051 @ 22.1184 MHz, + empty putchar() + +\end_inset + +, + +\layout Standard +small / large + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +7.49 / 22.47 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + +\begin_inset Text + +\layout Standard +1.04 / 1.04 ms + +\end_inset + + +\begin_inset Text + +\layout Standard +- + +\end_inset + + + + +\end_inset + + + +\layout Subsubsection + +\begin_inset LatexCommand \index{malloc.h} + +\end_inset + + + +\layout Standard +As of SDCC 2.6.2 you no longer need to call an initialization routine before + using dynamic memory allocation +\begin_inset LatexCommand \index{dynamic memory allocation (malloc)} + +\end_inset + + and a default heap +\begin_inset LatexCommand \index{heap (malloc)} + +\end_inset + + space of 1024 bytes is provided for malloc to allocate memory from. + If you need a different heap size you need to recompile _heap.c with the + required size defined in HEAP_SIZE. + It is recommended to make a copy of this file into your project directory + and compile it there with: + +\layout Verse + +\family typewriter +sdcc -c _heap.c -D HEAD_SIZE=2048 + +\layout Standard +And then link it with: + +\layout Verse + +\family typewriter +sdcc main.rel _heap.rel + +\layout Subsection +Math functions (sinf, powf, sqrtf etc.) + +\layout Subsubsection + + +\layout Standard +See definitions in file . + +\layout Subsection +Other libraries + +\layout Standard +Libraries +\begin_inset LatexCommand \index{Libraries} + +\end_inset + + included in SDCC should have a license at least as liberal as the GNU Lesser + General Public License +\begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL} + +\end_inset + + +\emph on +LGPL +\emph default +. + +\layout Standard +\begin_inset Note +collapsed true + +\layout Standard +license statements for the libraries are missing. + sdcc/device/lib/ser_ir.c + +\layout Standard +or _decdptr f.e. + come with a GPL (as opposed to LGPL) License - this will not be liberal + enough for many embedded programmers. + +\end_inset + + + +\layout Standard +If you have ported some library or want to share experience about some code + which f.e. + falls into any of these categories Busses (I +\begin_inset Formula $^{\textrm{2}}$ +\end_inset + +C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory + cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel, + Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list +\begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599} + +\end_inset + +\SpecialChar ~ +would certainly like to hear about it. + +\layout Standard +\added_space_bottom bigskip +Programmers coding for embedded systems are not especially famous for being + enthusiastic, so don't expect a big hurray but as the mailing list is searchabl +e these references are very valuable. + Let's help to create a climate where information is shared. + + + +\layout Section +Memory Models + +\layout Subsection +MCS51 Memory Models +\begin_inset LatexCommand \index{Memory model} + +\end_inset + + +\begin_inset LatexCommand \index{MCS51 memory model} + +\end_inset + + + +\layout Subsubsection +Small, Medium and Large + +\layout Standard +SDCC allows three memory models for MCS51 code, +\shape slanted +small, medium +\shape default + and +\shape slanted +large +\shape default +. + Modules compiled with different memory models should +\emph on +never +\emph default + be combined together or the results would be unpredictable. + The library routines supplied with the compiler are compiled as small, + medium and large. + The compiled library modules are contained in separate directories as small, + medium and large so that you can link to the appropriate set. + +\layout Standard +When the medium or large model is used all variables declared without a + storage class will be allocated into the external ram, this includes all + parameters and local variables (for non-reentrant +\begin_inset LatexCommand \index{reentrant} + +\end_inset + + functions). + When the small model is used variables without storage class are allocated + in the internal ram. + +\layout Standard +Judicious usage of the processor specific storage classes +\begin_inset LatexCommand \index{Storage class} + +\end_inset + + and the 'reentrant' function type will yield much more efficient code, + than using the large model. + Several optimizations are disabled when the program is compiled using the + large model, it is therefore recommended that the small model be used unless + absolutely required. + +\layout Subsubsection +External Stack +\begin_inset LatexCommand \label{sub:External-Stack} + +\end_inset + + +\begin_inset LatexCommand \index{stack} + +\end_inset + + +\begin_inset LatexCommand \index{External stack (mcs51)} + +\end_inset + + + +\layout Standard +The external stack (- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-xstack option +\begin_inset LatexCommand \index{-\/-xstack} + +\end_inset + +) is located in pdata +\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} + +\end_inset + + memory (usually at the start of the external ram segment) and uses all + unused space in pdata (max. + 256 bytes). + When - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-xstack option is used to compile the program, the parameters and local + variables +\begin_inset LatexCommand \index{local variables} + +\end_inset + + of all reentrant functions are allocated in this area. + This option is provided for programs with large stack space requirements. + When used with the - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} + +\end_inset + + option, all parameters and local variables are allocated on the external + stack (note: support libraries will need to be recompiled with the same + options. + There is a predefined target in the library makefile). + +\layout Standard +The compiler outputs the higher order address byte of the external ram segment + into port P2 +\begin_inset LatexCommand \index{P2 (mcs51 sfr)} + +\end_inset + + (see also section +\begin_inset LatexCommand \ref{sub:MCS51-variants} + +\end_inset + +), therefore when using the External Stack option, this port +\emph on +may not +\emph default + be used by the application program. + +\layout Subsection +DS390 Memory Model +\begin_inset LatexCommand \index{Memory model} + +\end_inset + + +\begin_inset LatexCommand \index{DS390 memory model} + +\end_inset + + + +\layout Standard +The only model supported is Flat 24 +\begin_inset LatexCommand \index{Flat 24 (DS390 memory model)} + +\end_inset + +. + This generates code for the 24 bit contiguous addressing mode of the Dallas + DS80C390 part. + In this mode, up to four meg of external RAM or code space can be directly + addressed. + See the data sheets at www.dalsemi.com for further information on this part. +\newline + +\newline +Note + that the compiler does not generate any code to place the processor into + 24 bitmode (although +\emph on +tinibios +\emph default + in the ds390 libraries will do that for you). + If you don't use +\emph on +tinibios +\emph default + +\begin_inset LatexCommand \index{Tinibios (DS390)} + +\end_inset + +, the boot loader or similar code must ensure that the processor is in 24 + bit contiguous addressing mode before calling the SDCC startup code. +\newline + +\newline +Like + the +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-large +\emph default + option, variables will by default be placed into the XDATA segment. + +\newline + +\newline +Segments may be placed anywhere in the 4 meg address space using the usual + - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-*-loc options. + Note that if any segments are located above 64K, the -r flag must be passed + to the linker to generate the proper segment relocations, and the Intel + HEX output format must be used. + The -r flag can be passed to the linker by using the option +\emph on +-Wl-r +\emph default + on the SDCC command line. + However, currently the linker can not handle code segments > 64k. + +\layout Section +Pragmas +\begin_inset LatexCommand \label{sec:Pragmas} + +\end_inset + + +\begin_inset LatexCommand \index{Pragmas} + +\end_inset + + + +\layout Standard +SDCC supports the following #pragma directives: + +\layout Itemize + +\series bold +save +\series default + +\begin_inset LatexCommand \index{\#pragma save} + +\end_inset + + - this will save most current options to the save/restore stack. + See #pragma\SpecialChar ~ +restore. + +\layout Itemize + +\series bold +restore +\series default + +\begin_inset LatexCommand \index{\#pragma restore} + +\end_inset + + - will restore saved options from the last save. + saves & restores can be nested. + SDCC uses a save/restore stack: save pushes current options to the stack, + restore pulls current options from the stack. + See #pragma\SpecialChar ~ +save. +\newline + + +\layout Itemize + +\series bold +callee_saves +\series default + +\begin_inset LatexCommand \index{\#pragma callee\_saves} + +\end_inset + + +\begin_inset LatexCommand \index{function prologue} + +\end_inset + + function1[,function2[,function3...]] - The compiler by default uses a caller + saves convention for register saving across function calls, however this + can cause unnecessary register pushing & popping +\begin_inset LatexCommand \index{push/pop} + +\end_inset + + when calling small functions from larger functions. + This option can be used to switch off the register saving convention for + the function names specified. + The compiler will not save registers when calling these functions, extra + code need to be manually inserted at the entry & exit for these functions + to save & restore the registers used by these functions, this can SUBSTANTIALLY + reduce code & improve run time performance of the generated code. + In the future the compiler (with inter procedural analysis) may be able + to determine the appropriate scheme to use for each function call. + If - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-callee-saves command line option is used, the function names specified + in #pragma\SpecialChar ~ +callee_saves +\begin_inset LatexCommand \index{\#pragma callee\_saves} + +\end_inset + + is appended to the list of functions specified in the command line. + +\layout Itemize + +\series bold +exclude +\series default + +\begin_inset LatexCommand \index{\#pragma exclude} + +\end_inset + + none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation + of pairs of push/pop +\begin_inset LatexCommand \index{push/pop} + +\end_inset + + instructions in +\emph on +I +\emph default +nterrupt +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + +\emph on +S +\emph default +ervice +\emph on +R +\emph default +outines. + The directive should be placed immediately before the ISR function definition + and it affects ALL ISR functions following it. + To enable the normal register saving for ISR functions use #pragma\SpecialChar ~ +exclude\SpecialChar ~ +none +\begin_inset LatexCommand \index{\#pragma exclude} + +\end_inset + +. + See also the related keyword _naked +\begin_inset LatexCommand \index{\_naked} + +\end_inset + + +\begin_inset LatexCommand \index{\_\_naked} + +\end_inset + +. + +\layout Itemize + +\series bold +less_pedantic +\series default + +\begin_inset LatexCommand \index{\#pragma less\_pedantic} + +\end_inset + + - the compiler will not warn you anymore for obvious mistakes, you'r on + your own now ;-( + +\layout Itemize + +\series bold +disable_warning +\series default + +\begin_inset LatexCommand \index{\#pragma disable\_warning} + +\end_inset + + - the compiler will not warn you anymore about warning number . + +\layout Itemize + +\series bold +nogcse +\series default + +\begin_inset LatexCommand \index{\#pragma nogcse} + +\end_inset + + - will stop global common subexpression elimination. + +\layout Itemize + +\series bold +noinduction +\series default + +\begin_inset LatexCommand \index{\#pragma noinduction} + +\end_inset + + - will stop loop induction optimizations. + +\layout Itemize + +\series bold +noinvariant +\series default + +\begin_inset LatexCommand \index{\#pragma noinvariant} + +\end_inset + + - will not do loop invariant optimizations. + For more details see Loop Invariants in section +\begin_inset LatexCommand \ref{sub:Loop-Optimizations} + +\end_inset + +. + +\layout Itemize + +\series bold +noiv +\series default + +\begin_inset LatexCommand \index{\#pragma noiv} + +\end_inset + + - Do not generate interrupt +\begin_inset LatexCommand \index{interrupt} + +\end_inset + + vector table +\begin_inset LatexCommand \index{interrupt vector table} + +\end_inset + + entries for all ISR functions defined after the pragma. + This is useful in cases where the interrupt vector table must be defined + manually, or when there is a secondary, manually defined interrupt vector + table (e.g. + for the autovector feature of the Cypress EZ-USB FX2). + More elegantly this can be achieved by obmitting the optional interrupt + number after the interrupt keyword, see section +\begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines} + +\end_inset + +\SpecialChar ~ +about interrupts. + +\layout Itemize + +\series bold +nojtbound +\series default + +\begin_inset LatexCommand \index{\#pragma nojtbound} + +\end_inset + + - will not generate code for boundary value checking, when switch statements + are turned into jump-tables (dangerous). + For more details see section +\begin_inset LatexCommand \ref{sub:'switch'-Statements} + +\end_inset + +. + +\layout Itemize + +\series bold +noloopreverse +\series default + +\begin_inset LatexCommand \index{\#pragma noloopreverse} + +\end_inset + + - Will not do loop reversal optimization + +\layout Itemize + +\series bold +nooverlay +\series default + +\begin_inset LatexCommand \index{\#pragma nooverlay} + +\end_inset + + - the compiler will not overlay the parameters and local variables of a + function. + +\layout Itemize + +\series bold +stackauto +\series default + +\begin_inset LatexCommand \index{\#pragma stackauto} + +\end_inset + +- See option - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} + +\end_inset + + and section +\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables} + +\end_inset + + Parameters and Local Variables. + +\layout Itemize + +\series bold +opt_code_speed +\series default + +\begin_inset LatexCommand \index{\#pragma opt\_code\_speed} + +\end_inset + +- The compiler will optimize code generation towards fast code, possibly + at the expense of code size. + Currently this has little effect. + +\layout Itemize + +\series bold +opt_code_size +\series default + +\begin_inset LatexCommand \index{\#pragma opt\_code\_size} + +\end_inset + +- The compiler will optimize code generation towards compact code, possibly + at the expense of code speed. + Currently this has little effect. + +\layout Itemize + +\series bold +opt_code_balanced +\series default + +\begin_inset LatexCommand \index{\#pragma opt\_code\_balanced} + +\end_inset + +- The compiler will attempt to generate code that is both compact and fast, + as long as meeting one goal is not a detriment to the other (this is the + default). + + +\layout Itemize + +\series bold +std_sdcc89 +\series default + +\begin_inset LatexCommand \index{\#pragma std\_sdcc89} + +\end_inset + +- Generally follow the C89 standard, but allow SDCC features that conflict + with the standard (default). + +\layout Itemize + +\series bold +std_c89 +\series default + +\begin_inset LatexCommand \index{\#pragma std\_c89} + +\end_inset + +- Follow the C89 standard and disable SDCC features that conflict with the + standard. + +\layout Itemize + +\series bold +std_sdcc99 +\series default + +\begin_inset LatexCommand \index{\#pragma std\_sdcc99} + +\end_inset + +- Generally follow the C99 standard, but allow SDCC features that conflict + with the standard (incomplete support). + +\layout Itemize + +\series bold +std_c99 +\series default + +\begin_inset LatexCommand \index{\#pragma std\_c99} + +\end_inset + +- Follow the C99 standard and disable SDCC features that conflict with the + standard (incomplete support). + +\layout Itemize + +\series bold +codeseg +\series default + +\begin_inset LatexCommand \index{\#pragma codeseg} + +\end_inset + +- Use this name (max. + 8 characters) for the code segment. + See option - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-codeseg. + +\layout Itemize + +\series bold +constseg +\series default + +\begin_inset LatexCommand \index{\#pragma constseg} + +\end_inset + +- Use this name (max. + 8 characters) for the const segment. + See option - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-constseg. + +\layout Standard +The preprocessor SDCPP +\begin_inset LatexCommand \index{sdcpp (preprocessor)} + +\end_inset + + supports the following #pragma directives: + +\layout Itemize + +\series bold +pedantic_parse_number +\series default + +\begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number} + +\end_inset + + (+ | -) - Pedantic parse numbers so that situations like 0xfe-LO_B(3) are + parsed properly and the macro LO_B(3) gets expanded. + Default is off. + Below is an example on how to use this pragma. + +\emph on + Note: this functionality is not in conformance with standard! + +\layout Verse + +\family typewriter +#pragma pedantic_parse_number + +\begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number} + +\end_inset + + +\newline + +\newline +#define LO_B(x) ((x) & 0xff) +\newline + +\newline +unsigned char foo(void) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +unsigned char c=0xfe-LO_B(3) +; +\newline + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return c; +\newline +} +\newline + + +\layout Itemize + +\series bold +preproc_asm +\series default + +\begin_inset LatexCommand \index{\#pragma preproc\_asm} + +\end_inset + + (+ | -) - switch _asm _endasm block preprocessing on / off. + Default is on. + You use this prama to define multilines of assembly code. + This will prevent the preprocessor from changing the formating required + by assembly code. + Below is an example on how to use this pragma. + +\layout Verse + +\family typewriter +#pragma preproc_asm - +\begin_inset LatexCommand \index{\#pragma preproc\_asm} + +\end_inset + + +\newline +#define MYDELAY _asm +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +nop ;my assembly comment... +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +nop +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +nop +\newline +_endasm +\newline +#pragma preproc_asm + + +\newline + +\newline +void foo (void) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + MYDELAY; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ... + +\newline +} +\newline + + +\layout Itemize + +\series bold +sdcc_hash +\series default + +\begin_inset LatexCommand \index{\#pragma sdcc\_hash} + +\end_inset + + (+ | -) - Allow "naked" hash in macro definition, for example: +\newline + +\family typewriter +#define DIR_LO(x) #(x & 0xff) +\family default + +\newline +Default is off. + Below is an example on how to use this pragma. + +\layout Verse + +\family typewriter +#pragma preproc_asm + +\newline +#pragma sdcc_hash + +\begin_inset LatexCommand \index{\#pragma sdcc\_hash} + +\end_inset + + +\newline + +\newline +#define ROMCALL(x) +\backslash + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov R6_B3, #(x & 0xff) +\backslash + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov R7_B3, #((x >> 8) & 0xff) +\backslash + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +lcall __romcall +\newline + +\newline +... +\newline +_asm +\newline +ROMCALL(72) +\newline +_endasm; +\newline +... +\newline + + +\layout Standard +The pragma's are intended to be used to turn-on or off certain optimizations + which might cause the compiler to generate extra stack / data space to + store compiler generated temporary variables. + This usually happens in large functions. + Pragma directives should be used as shown in the following example, they + are used to control options & optimizations for a given function; pragmas + should be placed before and/or after a function, placing pragma's inside + a function body could have unpredictable results. + +\layout Verse + +\family typewriter +#pragma save +\begin_inset LatexCommand \index{\#pragma save} + +\end_inset + + \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* save the current settings */ +\newline +#pragma nogcse +\begin_inset LatexCommand \index{\#pragma nogcse} + +\end_inset + + \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* turnoff global subexpression elimination */ +\newline +#pragma noinduction +\begin_inset LatexCommand \index{\#pragma noinduction} + +\end_inset + + /* turn off induction optimizations */ +\newline +int foo () +\newline +{ +\newline +\SpecialChar ~ + \SpecialChar ~ + ... + +\newline +\SpecialChar ~ + \SpecialChar ~ + /* large code */ +\newline +\SpecialChar ~ + \SpecialChar ~ + ... + +\newline +} +\newline +#pragma restore +\begin_inset LatexCommand \index{\#pragma restore} + +\end_inset + + /* turn the optimizations back on */ + +\layout Standard +The compiler will generate a warning message when extra space is allocated. + It is strongly recommended that the save and restore pragma's be used when + changing options for a function. +\newline + +\newline + +\newline + + +\layout Section +Defines Created by the Compiler + +\layout Standard +The compiler creates the following #defines +\begin_inset LatexCommand \index{\#defines} + +\end_inset + + +\begin_inset LatexCommand \index{Defines created by the compiler} + +\end_inset + +: +\newline + + +\layout Standard +\begin_inset Tabular + + + + + + +\begin_inset Text + +\layout Standard + +\series bold +#define + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Description + +\end_inset + + + + +\begin_inset Text + +\layout Standard +SDCC +\begin_inset LatexCommand \index{SDCC} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +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 + + or SDCC_ds390 +\begin_inset LatexCommand \index{SDCC\_ds390} + +\end_inset + + or SDCC_z80 +\begin_inset LatexCommand \index{SDCC\_z80} + +\end_inset + +, etc. + +\end_inset + + +\begin_inset Text + +\layout Standard +depending on the model used (e.g.: -mds390) + +\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} + +\end_inset + +, __z80 +\begin_inset LatexCommand \index{\_\_z80} + +\end_inset + +, etc + +\end_inset + + +\begin_inset Text + +\layout Standard +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 + + + +\end_inset + + +\begin_inset Text + +\layout Standard +when +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto +\emph default + option is used + +\end_inset + + + + +\begin_inset Text + +\layout Standard +SDCC_MODEL_SMALL +\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +when +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-small +\emph default + is used + +\end_inset + + + + +\begin_inset Text + +\layout Standard +SDCC_MODEL_MEDIUM +\begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +when +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-medium +\emph default + is used + +\end_inset + + + + +\begin_inset Text + +\layout Standard +SDCC_MODEL_LARGE +\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +when +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-model-large +\emph default + is used + +\end_inset + + + + +\begin_inset Text + +\layout Standard +SDCC_USE_XSTACK +\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +when +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-xstack +\emph default + option is used + +\end_inset + + + + +\begin_inset Text + +\layout Standard +SDCC_STACK_TENBIT +\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +when +\emph on +-mds390 +\emph default + is used + +\end_inset + + + + +\begin_inset Text + +\layout Standard +SDCC_MODEL_FLAT24 +\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +when +\emph on +-mds390 +\emph default + is used + +\end_inset + + + + +\end_inset + + + +\layout Chapter +Notes on supported Processors + +\layout Section +MCS51 variants +\begin_inset LatexCommand \label{sub:MCS51-variants} + +\end_inset + + +\begin_inset LatexCommand \index{MCS51 variants} + +\end_inset + + + +\layout Standard +MCS51 processors are available from many vendors and come in many different + flavours. + While they might differ considerably in respect to Special Function Registers + the core MCS51 is usually not modified or is kept compatible. + + +\layout Subsection +pdata access by SFR + +\layout Standard +With the upcome of devices with internal xdata and flash memory devices + using port P2 +\begin_inset LatexCommand \index{P2 (mcs51 sfr)} + +\end_inset + + as dedicated I/O port is becoming more popular. + Switching the high byte for pdata +\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)} + +\end_inset + + access which was formerly done by port P2 is then achieved by a Special + Function Register +\begin_inset LatexCommand \index{sfr} + +\end_inset + +. + In well-established MCS51 tradition the address of this +\emph on +sfr +\emph default + is where the chip designers decided to put it. + Needless to say that they didn't agree on a common name either. + So that the startup code can correctly initialize xdata variables, you + should define an sfr with the name _XPAGE +\family typewriter + +\begin_inset LatexCommand \index{\_XPAGE (mcs51)} + +\end_inset + + +\family default + at the appropriate location if the default, port P2, is not used for this. + Some examples are: + +\layout Verse + +\family typewriter +__sfr __at (0x85) _XPAGE; /* Ramtron VRS51 family a.k.a. + MPAGE */ + +\layout Verse + +\family typewriter +__sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family, Texas Instruments (Chipcon) + a.k.a. + MPAGE */ + +\layout Verse + +\family typewriter +__sfr __at (0x91) _XPAGE; /* Infineon (Siemens) C500 family a.k.a. + XPAGE */ + +\layout Verse + +\family typewriter +__sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a. + EMI0CN */ + +\layout Verse + +\family typewriter +__sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a. + EMI0CN */ + +\layout Standard +For more exotic implementations further customizations may be needed. + See section +\begin_inset LatexCommand \ref{sub:Startup-Code} + +\end_inset + + for other possibilities. + +\layout Subsection +Other Features available by SFR + +\layout Standard +\added_space_bottom bigskip +Some MCS51 variants offer features like Double DPTR +\begin_inset LatexCommand \index{DPTR} + +\end_inset + +, multiple DPTR, decrementing DPTR, 16x16 Multiply. + These are currently not used for the MCS51 port. + If you absolutely need them you can fall back to inline assembly or submit + a patch to SDCC. + + + +\layout Section +DS400 port + +\layout Standard +\added_space_bottom bigskip +The DS80C400 +\begin_inset LatexCommand \index{DS80C400} + +\end_inset + + +\begin_inset LatexCommand \index{DS400} + +\end_inset + + microcontroller has a rich set of peripherals. + In its built-in ROM library it includes functions to access some of the + features, among them is a TCP stack with IP4 and IP6 support. + Library headers (currently in beta status) and other files are provided + at +\size footnotesize + +\begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html} + +\end_inset + +. + + + + +\layout Section +The Z80 and gbz80 port + +\layout Standard +SDCC can target both the Zilog Z80 +\begin_inset LatexCommand \index{Z80} + +\end_inset + + and the Nintendo Gameboy's Z80-like gbz80 +\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)} + +\end_inset + +. + The Z80 port is passed through the same +\emph on +regressions tests +\begin_inset LatexCommand \index{Regression test} + +\end_inset + + +\emph default + (see section +\begin_inset LatexCommand \ref{sec:Quality-control} + +\end_inset + +) 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 +\added_space_bottom bigskip +As always, the code is the authoritative reference - see z80/ralloc.c and + z80/gen.c. + The stack +\begin_inset LatexCommand \index{Z80!stack} + +\end_inset + + frame is similar to that generated by the IAR Z80 compiler. + IX is used as the base pointer, HL and IY are used as a temporary registers, + and BC and DE are available for holding variables. + Return values +\begin_inset LatexCommand \index{Z80!return value} + +\end_inset + + for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four + bytes). + The gbz80 port use the same set of registers for the return values, but + in a different order of significance: E (one byte), DE (two bytes), or + HLDE (four bytes). + + + +\layout Section +The HC08 port + +\layout Standard +The port to the Freescale/Motorola HC08 +\begin_inset LatexCommand \index{HC08} + +\end_inset + + family has been added in October 2003, and is still undergoing some basic + development. + The code generator is complete, but the register allocation is still quite + unoptimized. + Some of the SDCC's standard C library functions have embedded non-HC08 + inline assembly and so are not yet usable. + +\layout Standard +\pagebreak_bottom +\added_space_bottom bigskip +The HC08 port passes the regression test suite (see section +\begin_inset LatexCommand \ref{sec:Quality-control} + +\end_inset + +). + + + + +\layout Section +The PIC14 port + +\layout Standard +The 14bit PIC +\begin_inset LatexCommand \index{PIC14} + +\end_inset + + port still requires a major effort from the development community. + However it can work for simple code. + It passes its (smaller set of) regression tests +\begin_inset LatexCommand \index{Regression test (PIC14)} + +\end_inset + + in the directory +\shape italic +sdcc/src/regression +\shape default +. + +\layout Subsection +C code and 14bit PIC code page +\begin_inset LatexCommand \index{code page (pic14)} + +\end_inset + + and RAM banks +\begin_inset LatexCommand \index{RAM bank (pic14)} + +\end_inset + + + +\layout Standard +The linker organizes allocation for the code page and RAM banks. + It does not have intimate knowledge of the code flow. + It will put all the code section of a single asm file into a single code + page. + In order to make use of multiple code pages, separate asm files must be + used. + The compiler treats all functions of a single C file as being in the same + code page unless it is non static. +\newline + +\newline +To get the best follow these guide lines: + +\layout Enumerate +Make local functions static, as non static functions require code page selection + overhead. + +\layout Enumerate +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 there's less page selection overhead. + +\layout Enumerate +And as for any 8 bit micro (especially for PIC 14 as they have a very simple + instruction set), use 'unsigned char' whereever possible instead of 'int'. + +\layout Subsection +Creating a device include file + +\layout Standard +For generating a device include file +\begin_inset LatexCommand \index{PIC14!Header files} + +\end_inset + + use the support perl script inc2h.pl kept in directory support/script. + +\layout Subsection +Interrupt code + +\layout Standard +For the interrupt function, use the keyword '__interrupt' +\begin_inset LatexCommand \index{PIC14!interrupt} + +\end_inset + + with level number of 0 (PIC14 only has 1 interrupt so this number is only + there to avoid a syntax error - it ought to be fixed). + E.g.: + +\layout Verse + +\family typewriter +void Intr(void) __interrupt 0 +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +T0IF = 0; /* Clear timer interrupt */ +\newline +} + +\layout Subsection +Linking and assembling + +\layout Standard +For assembling you can use either GPUTILS' +\begin_inset LatexCommand \index{gputils (pic tools)} + +\end_inset + + gpasm.exe or MPLAB's mpasmwin.exe. + GPUTILS is available from +\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils} + +\end_inset + +. + For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe. + If you use MPLAB and an interrupt function then the linker script file + vectors section will need to be enlarged to link with mplink. +\newline + +\newline +Here is a +\family typewriter +Makefile +\family default + using GPUTILS: + +\layout Verse + +\family typewriter +.c.o: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcc -S -V -mpic14 -p16F877 $< +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +gpasm -c $*.asm +\newline + +\newline +$(PRJ).hex: $(OBJS) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +gplink + -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib + +\layout Standard +Here is a +\family typewriter +Makefile +\family default + using MPLAB: + +\layout Verse + +\family typewriter +.c.o: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcc -S -V -mpic14 -p16F877 $< +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mpasmwin /q /o $*.asm +\newline + +\newline +$(PRJ).hex: $(OBJS) + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib + +\layout Standard +Please note that indentations within a +\family typewriter + Makefile +\family default + have to be done with a tabulator character. + +\layout Subsection +Command-line options + +\layout Standard +Besides the switches common to all SDCC backends, the PIC14 port accepts + the following options (for an updated list see sdcc - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-help): + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-debug-extra +\begin_inset LatexCommand \index{PIC14!Options!-\/-debug-extra} + +\end_inset + + emit debug info in assembly output + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-no-pcode-opt +\begin_inset LatexCommand \index{PIC14!Options!-\/-no-pcode-opt} + +\end_inset + + disable (slightly faulty) optimization on pCode + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-loc +\begin_inset LatexCommand \index{PIC14!Options!-\/-stack-loc} + +\end_inset + + sets the lowest address of the argument passing stack (defaults to a suitably + large shared databank to reduce BANKSEL overhead) + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-size +\begin_inset LatexCommand \index{PIC14!Options!-\/-stack-size} + +\end_inset + + sets the size if the argument passing stack (default: 16, minimum: 4) + +\layout Subsection +The library + +\layout Subsubsection +error: missing definition for symbol +\begin_inset Quotes sld +\end_inset + +__gptrget1 +\begin_inset Quotes srd +\end_inset + + + +\layout Standard +The PIC14 port uses library routines to provide more complex operations + like multiplication, division/modulus and (generic) pointer dereferencing. + In order to add these routines to your project, you must link with PIC14's + +\family typewriter +libsdcc.lib +\family default +. + For single source file projects this is done automatically, more complex + projects must add +\family typewriter +libsdcc.lib +\family default + to the linker's arguments. + Make sure you also add an include path for the library (using the -I switch + to the linker)! + +\layout Subsubsection +Processor mismatch in file +\begin_inset Quotes sld +\end_inset + +XXX +\begin_inset Quotes srd +\end_inset + +. + +\layout Standard +This warning can usually be ignored due to the very good compatibility amongst + 14 bit PIC +\begin_inset LatexCommand \index{PIC14} + +\end_inset + + 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 +\pagebreak_bottom +Currently, data can only be initialized if it resides in the source file + together with +\emph on +main() +\emph default +. + Data in other source files will silently +\series bold +not +\series default + be initialized. +\family typewriter +\size footnotesize + +\begin_inset Marginal +collapsed true + +\layout Standard + +\series bold +\SpecialChar ~ +! + +\end_inset + + +\family default + + + +\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 + +\layout Standard +18F248 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F252 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F258 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F442 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F448 + +\end_inset + + + + +\begin_inset Text + +\layout Standard +18F452 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F458 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F1220 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F2220 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F2550 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F4331 + +\end_inset + + + + +\begin_inset Text + +\layout Standard +18F4455 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F6520 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F6620 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F6680 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F6720 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F8520 + +\end_inset + + + + +\begin_inset Text + +\layout Standard +18F8620 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F8680 + +\end_inset + + +\begin_inset Text + +\layout Standard +18F8720 + +\end_inset + + +\begin_inset Text + +\layout Standard + + +\end_inset + + +\begin_inset Text + +\layout Standard + + +\end_inset + + +\begin_inset Text + +\layout Standard + + +\end_inset + + + + +\end_inset + + + +\layout Subsection +Global Options + +\layout Standard +PIC16 port supports the standard command line arguments as supposed, with + the exception of certain cases that will be mentioned in the following + list: + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-callee-saves +\begin_inset LatexCommand \index{PIC16!Options!-\/-callee-saves} + +\end_inset + + See - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-all-callee-saves + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-all-callee-saves +\begin_inset LatexCommand \index{PIC16!Options!-\/-all-callee-saves} + +\end_inset + + All function arguments are passed on stack by default. + +\emph on +There is no need to specify this in the command line. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-fommit-frame-pointer +\begin_inset LatexCommand \index{PIC16!Options!-\/-fommit-frame-pointer} + +\end_inset + + Frame pointer will be omitted when the function uses no local variables. + +\layout Subsection +Port Specific Options +\begin_inset LatexCommand \index{Options PIC16} + +\end_inset + + + +\layout Standard +The port specific options appear after the global options in the sdcc --help + output. + +\layout Subsubsection +General Options + +\layout Standard +General options enable certain port features and optimizations. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-pstack-model=[model] Used in conjuction with the command above. + Defines the stack model to be used, valid stack models are : + +\begin_deeper +\layout List +\labelwidthstring 00.00.0000 + +\emph on +small +\emph default + Selects small stack model. + 8 bit stack and frame pointers. + Supports 256 bytes stack size. + +\layout List +\labelwidthstring 00.00.0000 + +\emph on +large +\emph default + Selects large stack model. + 16 bit stack and frame pointers. + Supports 65536 bytes stack size. + +\end_deeper +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-preplace-udata-with=[kword] Replaces the default udata keyword for allocating + unitialized data variables with [kword]. + Valid keywords are: "udata_acs", "udata_shr", "udata_ovr". + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-ivt-loc positions the Interrupt Vector Table at location . + Useful for bootloaders. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-asm= sets the full path and name of an external assembler to call. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-link= sets the full path and name of an external linker to call. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-mplab-comp MPLAB +\begin_inset LatexCommand \index{PIC16!MPLAB} + +\end_inset + + compatibility option. + Currently only suppresses special gpasm directives. + +\layout Subsubsection +Optimization Options + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-optimize-goto Try to use (conditional) BRA instead of GOTO + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-optimize-cmp Try to optimize some compares. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-optimize-df Analyze the dataflow of the generated code and improve it. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-obanksel=nn Set optimization level for inserting BANKSELs. +\newline + + +\begin_deeper +\layout List +\labelwidthstring 00.00.0000 +0 no optimization + +\layout List +\labelwidthstring 00.00.0000 +1 checks previous used register and if it is the same then does not emit + BANKSEL, accounts only for labels. + +\layout List +\labelwidthstring 00.00.0000 +2 tries to check the location of (even different) symbols and removes BANKSELs + if they are in the same bank. + +\newline + +\emph on +Important: There might be problems if the linker script has data sections + across bank borders! + +\end_deeper +\layout Subsubsection +Linking Options + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-nodefaultlibs do not link default libraries when linking + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-no-crt Don't link the default run-time modules + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-use-crt= Use a custom run-time module instead of the defaults. + +\layout Subsubsection +Debugging Options + +\layout Standard +Debugging options enable extra debugging information in the output files. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-debug-xtra Similar to - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-debug +\begin_inset LatexCommand \index{-\/-debug} + +\end_inset + +, but dumps more information. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-debug-ralloc Force register allocator to dump .d file with debugging + information. + is the name of the file compiled. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-pcode-verbose Enable pcode debugging information in translation. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-denable-peeps Force the usage of peepholes. + Use with care. + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-gstack Trace push/pops for stack pointer overflow + +\layout List +\labelwidthstring 00.00.0000 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-call-tree dump call tree in .calltree file + +\layout Subsection +Enviromental Variables + +\layout Standard +There is a number of enviromental variables that can be used when running + SDCC to enable certain optimizations or force a specific program behaviour. + these variables are primarily for debugging purposes so they can be enabled/dis +abled at will. + +\layout Standard +Currently there is only two such variables available: + +\layout List +\labelwidthstring 00.00.0000 +OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure + bitfields is optimized by directly loading FSR0 with the address of the + bitfield structure. + Normally SDCC will cast the bitfield structure to a bitfield pointer and + then load FSR0. + This step saves data ram and code space for functions that perform heavy + use of bitfields. + (ie. + 80 bytes of code space are saved when compiling malloc.c with this option). + + +\layout List +\labelwidthstring 00.00.0000 +NO_REG_OPT do not perform pCode registers optimization. + This should be used for debugging purposes. + In some where bugs in the pcode optimizer are found, users can benefit + from temporarily disabling the optimizer until the bug is fixed. + +\layout Subsection +Preprocessor Macros + +\layout Standard +PIC16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port defines the following preprocessor macros while translating a source. + +\layout Standard +\align center +\begin_inset Tabular + + + + + + +\begin_inset Text + +\layout Standard +Macro + +\end_inset + + +\begin_inset Text + +\layout Standard +Description + +\end_inset + + + + +\begin_inset Text + +\layout Standard +SDCC_pic16 + +\end_inset + + +\begin_inset Text + +\layout Standard +Port identification + +\end_inset + + + + +\begin_inset Text + +\layout Standard +_ +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +_pic16 + +\end_inset + + +\begin_inset Text + +\layout Standard +Port identification (same as above) + +\end_inset + + + + +\begin_inset Text + +\layout Standard +pic18fxxxx + +\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 +_ +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +_18Fxxxx + +\end_inset + + +\begin_inset Text + +\layout Standard +MCU Identification (same as above) + +\end_inset + + + + +\begin_inset Text + +\layout Standard +STACK_MODEL_nnn + +\end_inset + + +\begin_inset Text + +\layout Standard +nnn = SMALL or LARGE respectively according to the stack model used + +\end_inset + + + + +\end_inset + + + +\layout Standard +In addition the following macros are defined when calling assembler: + +\layout Standard +\align center +\begin_inset Tabular + + + + + + +\begin_inset Text + +\layout Standard +Macro + +\end_inset + + +\begin_inset Text + +\layout Standard +Description + +\end_inset + + + + +\begin_inset Text + +\layout Standard +__18Fxxxx + +\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 +SDCC_MODEL_nnn + +\end_inset + + +\begin_inset Text + +\layout Standard +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 + + +\begin_inset Text + +\layout Standard +nnn = SMALL or LARGE respectively according to the stack model used + +\end_inset + + + + +\end_inset + + + +\layout Subsection +Directories + +\layout Standard +PIC16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port uses the following directories for searching header files and libraries. + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + + +\begin_inset Text + +\layout Standard +Directory + +\end_inset + + +\begin_inset Text + +\layout Standard +Description + +\end_inset + + +\begin_inset Text + +\layout Standard +Target + +\end_inset + + +\begin_inset Text + +\layout Standard +Command prefix + +\end_inset + + + + +\begin_inset Text + +\layout Standard +PREFIX/sdcc/include/pic16 + +\end_inset + + +\begin_inset Text + +\layout Standard +PIC16 specific headers + +\end_inset + + +\begin_inset Text + +\layout Standard +Compiler + +\end_inset + + +\begin_inset Text + +\layout Standard +-I + +\end_inset + + + + +\begin_inset Text + +\layout Standard +PREFIX/sdcc/lib/pic16 + +\end_inset + + +\begin_inset Text + +\layout Standard +PIC16 specific libraries + +\end_inset + + +\begin_inset Text + +\layout Standard +Linker + +\end_inset + + +\begin_inset Text + +\layout Standard +-L + +\end_inset + + + + +\end_inset + + + +\layout Subsection +Pragmas +\begin_inset LatexCommand \label{sub:PIC16_Pragmas} + +\end_inset + + + +\layout Standard +PIC16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port currently supports the following pragmas: + +\layout List +\labelwidthstring 00.00.0000 +stack +\begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma stack} + +\end_inset + + pragma stack +\begin_inset LatexCommand \index{PIC16!stack} + +\end_inset + + forces the code generator to initialize the stack & frame pointers at a + specific address. + This is an adhoc solution for cases where no STACK directive is available + in the linker script or gplink is not instructed to create a stack section. +\newline +The + stack pragma should be used only once in a project. + Multiple pragmas may result in indeterminate behaviour of the program. +\begin_inset Foot +collapsed false + +\layout Standard +The old format (ie. + #pragma stack 0x5ff) is deprecated and will cause the stack pointer to + cross page boundaries (or even exceed the available data RAM) and crash + the program. + Make sure that stack does not cross page boundaries when using the SMALL + stack model. + +\end_inset + + +\newline +The format is as follows: + +\layout LyX-Code +#pragma stack bottom_address [stack_size] + +\layout Standard + +\emph on +bottom_address +\emph default + is the lower bound of the stack section. + The stack pointer initially will point at address (bottom_address+stack_size-1). + +\layout LyX-Code +Example: + +\layout LyX-Code + + +\layout LyX-Code +/* initializes stack of 100 bytes at RAM address 0x200 */ + +\layout LyX-Code +#pragma stack 0x200 100 + +\layout Standard +If the stack_size field is omitted then a stack is created with the default + size of 64. + This size might be enough for most programs, but its not enough for operations + with deep function nesting or excessive stack usage. + +\layout List +\labelwidthstring 00.00.0000 +code +\begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma code} + +\end_inset + + place a function symbol at static FLASH address + +\layout LyX-Code +Example: + +\layout LyX-Code + + +\layout LyX-Code +/* place function test_func at 0x4000 */ + +\layout LyX-Code +#pragma code test_func 0x4000 + +\layout LyX-Code + + +\layout List +\labelwidthstring 00.00.0000 +library instructs the linker to use a library module. +\newline +Usage: + +\layout LyX-Code +#pragma library module_name + +\layout Standard + +\emph on +module_name +\emph default + can be any library or object file (including its path). + Note that there are four reserved keywords which have special meaning. + These are: + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard +Keyword + +\end_inset + + +\begin_inset Text + +\layout Standard +Description + +\end_inset + + +\begin_inset Text + +\layout Standard +Module to link + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\series bold +ignore + +\end_inset + + +\begin_inset Text + +\layout Standard +ignore all library pragmas + +\end_inset + + +\begin_inset Text + +\layout Standard + +\emph on +(none) + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\series bold +c + +\end_inset + + +\begin_inset Text + +\layout Standard +link the C library + +\end_inset + + +\begin_inset Text + +\layout Standard + +\emph on +libc18f +\emph default +.lib + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\series bold +math + +\end_inset + + +\begin_inset Text + +\layout Standard +link the Math libarary + +\end_inset + + +\begin_inset Text + +\layout Standard + +\emph on +libm18f +\emph default +.lib + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\series bold +io + +\end_inset + + +\begin_inset Text + +\layout Standard +link the I/O library + +\end_inset + + +\begin_inset Text + +\layout Standard + +\emph on +libio18f* +\emph default +.lib + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\series bold +debug + +\end_inset + + +\begin_inset Text + +\layout Standard +link the debug library + +\end_inset + + +\begin_inset Text + +\layout Standard + +\emph on +libdebug +\emph default +.lib + +\end_inset + + + + +\end_inset + + +\newline +* is the device number, i.e. + 452 for PIC18F452 MCU. + +\layout Standard +This feature allows for linking with specific libraries withoug having to + explicit name them in the command line. + Note that the +\noun on +ignore +\noun default + keyword will reject all modules specified by the library pragma. + +\layout List +\labelwidthstring 00.00.0000 +udata pragma udata instructs the compiler to emit code so that linker will + place a variable at a specific memory bank + +\layout LyX-Code +Example: + +\layout LyX-Code + + +\layout LyX-Code +/* places variable foo at bank2 */ + +\layout LyX-Code +#pragma udata bank2 foo + +\layout LyX-Code +char foo; + +\layout Standard +In order for this pragma to work extra SECTION directives should be added + in the .lkr script. + In the following example a sample .lkr file is shown: + +\layout LyX-Code + + +\layout LyX-Code +// Sample linker script for the PIC18F452 processor + +\layout LyX-Code +LIBPATH . + +\layout LyX-Code +CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED + +\layout LyX-Code +CODEPAGE NAME=page START=0x2A END=0x7FFF + +\layout LyX-Code +CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED + +\layout LyX-Code +CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED + +\layout LyX-Code +CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED + +\layout LyX-Code +CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED + +\layout LyX-Code +ACCESSBANK NAME=accessram START=0x0 END=0x7F + +\layout LyX-Code + + +\layout LyX-Code +DATABANK NAME=gpr0 START=0x80 END=0xFF + +\layout LyX-Code +DATABANK NAME=gpr1 START=0x100 END=0x1FF + +\layout LyX-Code +DATABANK NAME=gpr2 START=0x200 END=0x2FF + +\layout LyX-Code +DATABANK NAME=gpr3 START=0x300 END=0x3FF + +\layout LyX-Code +DATABANK NAME=gpr4 START=0x400 END=0x4FF + +\layout LyX-Code +DATABANK NAME=gpr5 START=0x500 END=0x5FF + +\layout LyX-Code +ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED + +\layout LyX-Code + + +\layout LyX-Code +SECTION NAME=CONFIG ROM=config + +\layout LyX-Code + + +\layout LyX-Code +SECTION NAME=bank0 RAM=gpr0 # these SECTION directives + +\layout LyX-Code +SECTION NAME=bank1 RAM=gpr1 # should be added to link + +\layout LyX-Code +SECTION NAME=bank2 RAM=gpr2 # section name 'bank?' with + +\layout LyX-Code +SECTION NAME=bank3 RAM=gpr3 # a specific DATABANK name + +\layout LyX-Code +SECTION NAME=bank4 RAM=gpr4 + +\layout LyX-Code +SECTION NAME=bank5 RAM=gpr5 + +\layout Standard +The linker will recognise the section name set in the pragma statement and + will position the variable at the memory bank set with the RAM field at + the SECTION line in the linker script file. + +\layout Subsection +Header Files +\begin_inset LatexCommand \label{sub:PIC16_Header-Files} + +\end_inset + + + +\layout Standard +There is one main header file +\begin_inset LatexCommand \index{PIC16!Header files} + +\end_inset + + that can be included to the source files using the pic16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port. + That file is the +\series bold +pic18fregs.h +\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 +\begin_inset LatexCommand \index{PIC16!Libraries} + +\end_inset + + that PIC16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port depends on are the microcontroller device libraries which contain + the symbol definitions for the microcontroller special function registers. + These libraries have the format pic18fxxxx.lib, where +\emph on +xxxx +\emph default + is the microcontroller identification number. + The specific library is selected automatically by the compiler at link + stage according to the selected device. + +\layout Standard +Libraries are created with gplib which is part of the gputils package +\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils} + +\end_inset + +. + +\layout Subsubsection* +Building the libraries + +\layout Standard +Before using SDCC/pic16 there are some libraries that need to be compiled. + This process is not done automatically by SDCC since not all users use + SDCC for pic16 projects. + So each user should compile the libraries separately. + +\layout Standard +The steps to compile the pic16 libraries under Linux are: + +\layout LyX-Code +cd device/lib/pic16 + +\layout LyX-Code +./configure + +\layout LyX-Code +make + +\layout LyX-Code +cd .. + +\layout LyX-Code +make model-pic16 + +\layout LyX-Code +su -c 'make install' # install the libraries, you need the root password + +\layout Standard +If you need to install the headers too, do: + +\layout LyX-Code +cd device/include + +\layout LyX-Code +su -c 'make install' # install the headers, you need the root password + +\layout Standard +There exist a special target to build the I/O libraries. + This target is not automatically build because it will build the I/O library + for +\emph on +every +\emph default + supported device. + This way building will take quite a lot of time. + Users are advised to edit the +\series bold +device/lib/pic16/pics.build +\series default + file and then execute: + +\layout LyX-Code +make lib-io + +\layout Subsection +Memory Models + +\layout Standard +The following memory models are supported by the PIC16 port: + +\layout Itemize +small model + +\layout Itemize +large model + +\layout Standard +Memory model affects the default size of pointers within the source. + The sizes are shown in the next table: + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard +Pointer sizes according to memory model + +\end_inset + + +\begin_inset Text + +\layout Standard +small model + +\end_inset + + +\begin_inset Text + +\layout Standard +large model + +\end_inset + + + + +\begin_inset Text + +\layout Standard +code pointers + +\end_inset + + +\begin_inset Text + +\layout Standard +16-bits + +\end_inset + + +\begin_inset Text + +\layout Standard +24-bits + +\end_inset + + + + +\begin_inset Text + +\layout Standard +data pointers + +\end_inset + + +\begin_inset Text + +\layout Standard +16-bits + +\end_inset + + +\begin_inset Text + +\layout Standard +16-bits + +\end_inset + + + + +\end_inset + + + +\layout Standard +It is advisable that all sources within a project are compiled with the + same memory model. + If one wants to override the default memory model, this can be done by + declaring a pointer as +\series bold +far +\series default + or +\series bold +near +\series default +. + Far selects large memory model's pointers, while near selects small memory + model's pointers. + +\layout Standard +The standard device libraries (see +\begin_inset LatexCommand \ref{sub:PIC16_Header-Files} + +\end_inset + +) contain no reference to pointers, so they can be used with both memory + models. + +\layout Subsection +Stack + +\layout Standard +The stack +\begin_inset LatexCommand \index{PIC16!stack} + +\end_inset + + implementation for the PIC16 port uses two indirect registers, FSR1 and + FSR2. + +\layout List +\labelwidthstring 00.00.0000 +FSR1 is assigned as stack pointer + +\layout List +\labelwidthstring 00.00.0000 +FSR2 is assigned as frame pointer + +\layout Standard +The following stack models are supported by the PIC16 port + +\layout Itemize + +\noun on +small +\noun default + model + +\layout Itemize + +\noun on +large +\noun default + model + +\layout Standard + +\noun on +Small +\noun default + model means that only the FSRxL byte is used to access stack and frame, + while +\emph on +\noun on +large +\emph default +\noun default + uses both FSRxL and FSRxH registers. + The following table shows the stack/frame pointers sizes according to stack + model and the maximum space they can address: + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard +Stack & Frame pointer sizes according to stack model + +\end_inset + + +\begin_inset Text + +\layout Standard +small + +\end_inset + + +\begin_inset Text + +\layout Standard +large + +\end_inset + + + + +\begin_inset Text + +\layout Standard +Stack pointer FSR1 + +\end_inset + + +\begin_inset Text + +\layout Standard +8-bits + +\end_inset + + +\begin_inset Text + +\layout Standard +16-bits + +\end_inset + + + + +\begin_inset Text + +\layout Standard +Frame pointer FSR2 + +\end_inset + + +\begin_inset Text + +\layout Standard +8-bits + +\end_inset + + +\begin_inset Text + +\layout Standard +16-bits + +\end_inset + + + + +\end_inset + + + +\layout Standard + +\noun on +Large +\noun default +stack model is currently not working properly throughout the code generator. + So its use is not advised. + Also there are some other points that need special care: +\newline + + +\layout Enumerate +Do not create stack sections with size more than one physical bank (that + is 256 bytes) + +\layout Enumerate +Stack sections should no cross physical bank limits (i.e. + #pragma stack 0x50 0x100) + +\layout Standard +These limitations are caused by the fact that only FSRxL is modified when + using SMALL stack model, so no more than 256 bytes of stack can be used. + This problem will disappear after LARGE model is fully implemented. + +\layout Subsection +Functions + +\layout Standard +In addition to the standard SDCC function keywords, PIC16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port makes available two more: + +\layout List +\labelwidthstring 00.00.0000 +wparam +\begin_inset LatexCommand \index{PIC16!wparam} + +\end_inset + + Use the WREG to pass one byte of the first function argument. + This improves speed but you may not use this for functions with arguments + that are called via function pointers, otherwise the first byte of the + first parameter will get lost. + Usage: + +\layout LyX-Code +void func_wparam(int a) wparam + +\layout LyX-Code +{ + +\layout LyX-Code + /* WREG hold the lower part of a */ + +\layout LyX-Code + /* the high part of a is stored in FSR2+2 (or +3 for large stack model) + */ + +\layout LyX-Code +... + +\layout LyX-Code +} + +\layout List +\labelwidthstring 00.00.0000 +shadowregs +\begin_inset LatexCommand \index{PIC16!shadowregs} + +\end_inset + + When entering/exiting an ISR, it is possible to take advantage of the PIC18F + hardware shadow registers which hold the values of WREG, STATUS and BSR + registers. + This can be done by adding the keyword +\emph on +shadowregs +\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 + + +\begin_inset Text + +\layout Standard +destination register + +\end_inset + + + + +\begin_inset Text + +\layout Standard +8 bits + +\end_inset + + +\begin_inset Text + +\layout Standard +WREG + +\end_inset + + + + +\begin_inset Text + +\layout Standard +16 bits + +\end_inset + + +\begin_inset Text + +\layout Standard +PRODL:WREG + +\end_inset + + + + +\begin_inset Text + +\layout Standard +24 bits + +\end_inset + + +\begin_inset Text + +\layout Standard +PRODH:PRODL:WREG + +\end_inset + + + + +\begin_inset Text + +\layout Standard +32 bits + +\end_inset + + +\begin_inset Text + +\layout Standard +FSR0L:PRODH:PRODL:WREG + +\end_inset + + + + +\begin_inset Text + +\layout Standard +>32 bits + +\end_inset + + +\begin_inset Text + +\layout Standard +on stack, FSR0 points to the beginning + +\end_inset + + + + +\end_inset + + + +\layout Subsection +Interrupts + +\layout Standard +An interrupt +\begin_inset LatexCommand \index{PIC16!interrupt} + +\end_inset + + service routine (ISR) is declared using the +\emph on +interrupt +\emph default + keyword. + +\layout LyX-Code +void isr(void) interrupt +\emph on +n + +\layout LyX-Code +{ + +\layout LyX-Code +... + +\layout LyX-Code +} + +\layout Standard + +\emph on +n +\emph default + is the interrupt number, which for PIC18F devices can be: + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +\emph on +n + +\end_inset + + +\begin_inset Text + +\layout Standard +Interrupt Vector + +\end_inset + + +\begin_inset Text + +\layout Standard +Interrupt Vector Address + +\end_inset + + + + +\begin_inset Text + +\layout Standard +0 + +\end_inset + + +\begin_inset Text + +\layout Standard +RESET vector + +\end_inset + + +\begin_inset Text + +\layout Standard +0x000000 + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +1 + +\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 + +\end_inset + + +\begin_inset Text + +\layout Standard +0x000008 + +\end_inset + + + + +\begin_inset Text + +\layout Standard +2 + +\end_inset + + +\begin_inset Text + +\layout Standard +LOW priority interrupts + +\end_inset + + +\begin_inset Text + +\layout Standard +0x000018 + +\end_inset + + + + +\end_inset + + + +\layout Standard +When generating assembly code for ISR the code generator places a +\noun on +goto +\noun default +instruction at the +\emph on +Interrupt Vector Address +\emph default + which points at the genetated ISR. + This single GOTO instruction is part of an automatically generated +\emph on +interrupt entry point +\emph default + function. + The actuall ISR code is placed as normally would in the code space. + Upon interrupt request, the GOTO instruction is executed which jumps to + the ISR code. + When declaring interrupt functions as _naked this GOTO instruction is +\series bold +not +\series default + generated. + The whole interrupt functions is therefore placed at the Interrupt Vector + Address of the specific interrupt. + This is not a problem for the LOW priority interrupts, but it is a problem + for the RESET and the HIGH priority interrupts because code may be written + at the next interrupt´s vector address and cause undeterminate program + behaviour if that interrupt is raised. +\begin_inset Foot +collapsed false + +\layout Standard +This is not a problem when + +\layout Enumerate +this is a HIGH interrupt ISR and LOW interrupts are +\emph on +disabled +\emph default + or not used. + +\layout Enumerate +when the ISR is small enough not to reach the next interrupt´s vector address. + +\end_inset + + + +\layout Standard + +\emph on +n +\emph default + is possible to be omitted. + This way a function is generated similar to an ISR, but it is not assigned + to any interrupt. + +\layout Standard +When entering an interrupt, currently the PIC16 +\begin_inset LatexCommand \index{PIC16} + +\end_inset + + port automatically saves the following registers: + +\layout Itemize +WREG + +\layout Itemize +STATUS + +\layout Itemize +BSR + +\layout Itemize +PROD (PRODL and PRODH) + +\layout Itemize +FSR0 (FSR0L and FSR0H) + +\layout Standard +These registers are restored upon return from the interrupt routine. +\begin_inset Foot +collapsed false + +\layout Standard +NOTE that when the _naked attribute is specified for an interrupt routine, + then NO registers are stored or restored. + +\end_inset + + + +\layout Subsection +Generic Pointers + +\layout Standard +Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types. + There are 3 types of generic pointers currently implemented data, code + and eeprom pointers. + They are differentiated by the value of the 7th and 6th bits of the upper + byte: + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + + + +\begin_inset Text + +\layout Standard +pointer type + +\end_inset + + +\begin_inset Text + +\layout Standard +7th bit + +\end_inset + + +\begin_inset Text + +\layout Standard +6th bit + +\end_inset + + +\begin_inset Text + +\layout Standard +rest of the pointer + +\end_inset + + +\begin_inset Text + +\layout Standard +description + +\end_inset + + + + +\begin_inset Text + +\layout Standard +data + +\end_inset + + +\begin_inset Text + +\layout Standard +1 + +\end_inset + + +\begin_inset Text + +\layout Standard +0 + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family typewriter +\shape slanted +\emph on +uuuuuu uuuuxxxx xxxxxxxx + +\end_inset + + +\begin_inset Text + +\layout Standard +a 12-bit data pointer in data RAM memory + +\end_inset + + + + +\begin_inset Text + +\layout Standard +code + +\end_inset + + +\begin_inset Text + +\layout Standard +0 + +\end_inset + + +\begin_inset Text + +\layout Standard +0 + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family typewriter +\shape slanted +\emph on +uxxxxx xxxxxxxx xxxxxxxx + +\end_inset + + +\begin_inset Text + +\layout Standard +a 21-bit code pointer in FLASH memory + +\end_inset + + + + +\begin_inset Text + +\layout Standard +eeprom + +\end_inset + + +\begin_inset Text + +\layout Standard +0 + +\end_inset + + +\begin_inset Text + +\layout Standard +1 + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family typewriter +\shape slanted +\emph on +uuuuuu uuuuuuxx xxxxxxxx + +\end_inset + + +\begin_inset Text + +\layout Standard +a 10-bit eeprom pointer in EEPROM memory + +\end_inset + + + + +\begin_inset Text + +\layout Standard +(unimplemented) + +\end_inset + + +\begin_inset Text + +\layout Standard +1 + +\end_inset + + +\begin_inset Text + +\layout Standard +1 + +\end_inset + + +\begin_inset Text + +\layout Standard + +\family typewriter +\shape slanted +\emph on +xxxxxx xxxxxxxx xxxxxxxx + +\end_inset + + +\begin_inset Text + +\layout Standard +unimplemented pointer type + +\end_inset + + + + +\end_inset + + + +\layout Standard +Generic pointer are read and written with a set of library functions which + read/write 1, 2, 3, 4 bytes. + +\layout Subsection +PIC16 C Libraries + +\layout Subsubsection +Standard I/O Streams + +\layout Standard +In the +\emph on +stdio.h +\emph default + the type FILE is defined as: + +\layout LyX-Code +typedef char * FILE; + +\layout Standard +This type is the stream type implemented I/O in the PIC18F devices. + Also the standard input and output streams are declared in stdio.h: + +\layout LyX-Code +extern FILE * stdin; + +\layout LyX-Code +extern FILE * stdout; + +\layout Standard +The FILE type is actually a generic pointer which defines one more type + of generic pointers, the +\emph on +stream +\emph default +pointer. + This new type has the format: + +\layout Standard +\align center +\begin_inset Tabular + + + + + + + + + + + +\begin_inset Text + +\layout Standard +pointer type + +\end_inset + + +\begin_inset Text + +\layout Standard +<7:6> + +\end_inset + + +\begin_inset Text + +\layout Standard +<5> + +\end_inset + + +\begin_inset Text + +\layout Standard +<4> + +\end_inset + + +\begin_inset Text + +\layout Standard +<3:0> + +\end_inset + + +\begin_inset Text + +\layout Standard +rest of the pointer + +\end_inset + + +\begin_inset Text + +\layout Standard +descrption + +\end_inset + + + + +\begin_inset Text + +\layout Standard +stream + +\end_inset + + +\begin_inset Text + +\layout Standard +00 + +\end_inset + + +\begin_inset Text + +\layout Standard +1 + +\end_inset + + +\begin_inset Text + +\layout Standard +0 + +\end_inset + + +\begin_inset Text + +\layout Standard +nnnn + +\end_inset + + +\begin_inset Text + +\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 + +\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 necessary, 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 +\begin_inset LatexCommand \index{PIC16!stack} + +\end_inset + + size (that is 64 bytes) probably is enough for many programs. + One must take care that when there are many levels of function nesting, + or there is excessive usage of stack, its size should be extended. + An example of such a case is the printf/sprintf family of functions. + 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 Subsection +Known bugs + +\layout Standard +The PIC16 Port currently does not pass SDCC's regression test +\begin_inset LatexCommand \index{Regression test (PIC16)} + +\end_inset + + suite (see section +\begin_inset LatexCommand \ref{sec:Quality-control} + +\end_inset + +) and thus the nightly regression tests for the PIC16 target are currently + disabled for all hosts except for +\emph on +Linux on Opteron. + +\emph default + This means you can see the result of the PIC16 regression tests f.e. + by checking the log files in +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/regression_test_results/amd64-unknown-linux2.3/} + +\end_inset + + (pick the most up to date file there, scroll down, lend a hand). + +\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. + +\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 SDCDM 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 Standard +\begin_inset Note +collapsed true + +\layout Standard +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 Standard +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. + pdflatex does not accept eps files). + +\end_inset + + + +\layout Standard +The +\emph on +p +\emph default +ortable +\emph on +n +\emph default +etwork +\emph on +g +\emph default +raphics File +\size footnotesize + +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png} + +\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 Standard +\begin_inset Note +collapsed false + +\layout Standard +Check that the double quotes or an apostroph within the command line survive + the LyX tool chain. + Previously the apostrophs got slanted in the PDF output so a cut and paste + did not work. + +\end_inset + + + +\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 +\pagebreak_bottom +\SpecialChar ~ + +\family typewriter + +\newline +;;\SpecialChar ~ +Current Listing :: +\newline +;;key\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +binding\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Comment +\newline +;;---\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +-------\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +------- +\newline +;; +\newline +;;\SpecialChar ~ +n\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdb-next-fro +m-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB next command +\newline +;;\SpecialChar ~ +b\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdb-back-from-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB back command +\newline +;;\SpecialChar ~ +c\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdb-cont-f +rom-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB continue command +\newline +;;\SpecialChar ~ +s\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdb-step-from-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB step command +\newline +;;\SpecialChar ~ +?\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdb-w +hatis-c-sexp\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB ptypecommand for data at +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +buffer point +\newline +;;\SpecialChar ~ +x\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdbsrc-delete\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCD +B Delete all breakpoints if no arg +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +given or delete arg (C-u arg x) +\newline +;;\SpecialChar ~ +m\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdbsrc +-frame\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB Display current frame if no arg, +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +given or display frame arg + +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +buffer point +\newline +;;\SpecialChar ~ +!\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdbsrc-goto-sdcdb\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Goto the SDCDB output buffer +\newline +;;\SpecialChar ~ +p\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdb-prin +t-c-sexp\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB print command for data at +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +buffer point +\newline +;;\SpecialChar ~ +g\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdbsrc-goto-sdcdb\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Got +o the SDCDB output buffer +\newline +;;\SpecialChar ~ +t\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdbsrc-mode\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Toggles Sdcdbsrc mode (turns it + off) +\newline +;; +\newline +;;\SpecialChar ~ +C-c\SpecialChar ~ +C-f\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdb-finish-from-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB finish command +\newline +;; +\newline +;;\SpecialChar ~ +C-x\SpecialChar ~ +SPC\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdb-brea +k\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Set break for line with point +\newline +;;\SpecialChar ~ +ESC\SpecialChar ~ +t\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcdbsrc-mode\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Toggle Sdcdbsrc mode +\newline +;;\SpecialChar ~ +ESC\SpecialChar ~ +m\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdc +dbsrc-srcmode\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Toggle list mode +\newline +;; +\newline + +\family default + + + +\layout Chapter +TIPS + +\layout Standard +Here are a few guidelines that will help the compiler generate more efficient + code, some of the tips are specific to this compiler others are generally + good programming practice. + +\layout Itemize +Use the smallest data type to represent your data-value. + If it is known in advance that the value is going to be less than 256 then + use an 'unsigned char' instead of a 'short' or 'int'. + Please note, that ANSI C requires both signed and unsigned chars to be + promoted to 'signed int' +\begin_inset LatexCommand \index{promotion to signed int} + +\end_inset + + +\begin_inset Marginal +collapsed true + +\layout Standard + +\series bold +\SpecialChar ~ +! + +\end_inset + + before doing any operation. + This promotion +\begin_inset LatexCommand \index{type promotion} + +\end_inset + + +\begin_inset LatexCommand \label{type promotion} + +\end_inset + + can be omitted, if the result is the same. + The effect of the promotion rules together with the sign-extension is often + surprising: + +\begin_deeper +\layout Verse + +\family typewriter +unsigned char uc = 0xfe; +\newline +if (uc * uc < 0) /* this is true! */ +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.... +\newline +} + +\layout Standard + +\family typewriter +uc * uc +\family default + is evaluated as +\family typewriter +(int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024 +\family default +. + +\newline +Another one: + +\layout Verse + +\family typewriter +(unsigned char) -12 / (signed char) -3 = ... + +\layout Standard +No, the result is not 4: + +\layout Verse + +\family typewriter +(int) (unsigned char) -12 / (int) (signed char) -3 = +\newline +(int) (unsigned char) + 0xf4 / (int) (signed char) 0xfd = +\newline +(int) 0x00f4 / (int) 0xfffd = +\newline +(int) 0x00f4 + / (int) 0xfffd = +\newline +(int) 244 / (int) -3 = +\newline +(int) -81 = (int) 0xffaf; + +\layout Standard +Don't complain, that gcc gives you a different result. + gcc uses 32 bit ints, while SDCC uses 16 bit ints. + Therefore the results are different. +\newline +From +\begin_inset Quotes sld +\end_inset + +comp.lang.c FAQ +\begin_inset Quotes srd +\end_inset + +: + +\layout Quote + +\emph on +If well-defined overflow characteristics are important and negative values + are not, or if you want to steer clear of sign-extension problems when + manipulating bits or bytes, use one of the corresponding unsigned types. + (Beware when mixing signed and unsigned values in expressions, though.) +\newline +Although + character types (especially unsigned char) can be used as "tiny" integers, + doing so is sometimes more trouble than it's worth, due to unpredictable + 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 +Have a look at the assembly listing to get a +\begin_inset Quotes sld +\end_inset + +feeling +\begin_inset Quotes srd +\end_inset + + for the code generation. + +\layout Section +Porting code from or to other compilers +\begin_inset LatexCommand \label{sec:Porting-code-to-other-compilers} + +\end_inset + + + +\layout Itemize +check whether endianness of the compilers differs and adapt where needed. + +\layout Itemize +check the device specific header files +\begin_inset LatexCommand \index{Header files} + +\end_inset + + +\begin_inset LatexCommand \index{Include files} + +\end_inset + + for compiler specific syntax. + Eventually include the file +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/compiler.h?view=markup} + +\end_inset + + to allow using common header files. + (see f.e. + cc2510fx.h +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/cc2510fx.h?view=markup} + +\end_inset + +). + +\layout Itemize +check whether the startup code contains the correct initialization (watchdog, + peripherals). + +\layout Itemize +check whether the sizes of short, int, long match. + +\layout Itemize +check if some 16 or 32 bit hardware registers require a specific addressing + order (least significant or most significant byte first) and adapt if needed + ( +\emph on +first +\emph default + and +\emph on +last +\emph default + relate to time and not to lower/upper memory location here, so this is + +\emph on +not +\emph default + the same as endianness). + +\layout Itemize +check whether the keyword +\emph on +volatile +\emph default + is used where needed. + The compilers might differ in their optimization characteristics (as different + versions of the same compiler might also use more clever optimizations + this is good idea anyway). + See section +\begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile} + +\end_inset + +. + +\layout Itemize +check that the compilers are not told to supress warnings. + +\layout Itemize +check and convert compiler specific extensions (interrupts, memory areas, + pragmas etc.). + +\layout Itemize +check for differences in type promotion. + Especially check for math operations on +\family typewriter +char +\family default + or +\family typewriter +unsigned char +\family default + variables. + For the sake of C99 compatibility SDCC will probably promote these to +\family typewriter +int +\family default + more often than other compilers. + Eventually insert explicit casts to +\family typewriter +(char) +\family default +or +\family typewriter + (unsigned char) +\family default +. + Also check that the ~\SpecialChar ~ +operator +\begin_inset LatexCommand \index{\~\/ Operator} + +\end_inset + + is not used on +\family typewriter +bit +\begin_inset LatexCommand \index{bit} + +\end_inset + + +\family default + variables, use the !\SpecialChar ~ +operator instead. + See sections +\begin_inset LatexCommand \ref{type promotion} + +\end_inset + + and +\begin_inset LatexCommand \ref{sec:Compatibility-with-previous} + +\end_inset + +. + +\layout Itemize +check the assembly code generated for interrupt routines (f.e. + for calls to possibly non-reentrant library functions). + +\layout Itemize +check whether timing loops result in proper timing (or preferably consider + a rewrite of the code with timer based delays instead). + +\layout Itemize +check for differences in printf parameters (some compilers push (va_arg +\begin_inset LatexCommand \index{vararg, va\_arg} + +\end_inset + +) char variables as +\family typewriter +int +\family default + others push them as +\family typewriter +char +\family default +. + See section +\begin_inset LatexCommand \ref{sec:Compatibility-with-previous} + +\end_inset + +). + +\layout Itemize +check the resulting memory map +\begin_inset LatexCommand \index{Memory map} + +\end_inset + +. + Usage of different memory spaces: code, stack, data (for mcs51/ds390 additional +ly idata, pdata, xdata). + Eventually check if unexpected library functions are included. + +\layout Section +Tools +\begin_inset LatexCommand \index{Tools} + +\end_inset + + included in the distribution + +\layout Standard +\align left +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +\series bold +Name + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Purpose + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Directory + +\end_inset + + + + +\begin_inset Text + +\layout Standard +uCsim +\begin_inset LatexCommand \index{uCsim} + +\end_inset + + + +\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 +\begin_inset LatexCommand \index{Header files} + +\end_inset + + +\begin_inset LatexCommand \index{Include files} + +\end_inset + + 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 +Intel Hex packer +\begin_inset LatexCommand \index{packihx (tool)} + +\end_inset + + + +\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 left +\begin_inset Tabular + + + + + + +\begin_inset Text + +\layout Standard + +\series bold +Subject / Title + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Filename / Where to get + +\end_inset + + + + +\begin_inset Text + +\layout Standard +SDCC Compiler User Guide + +\end_inset + + +\begin_inset Text + +\layout Standard +You're reading it right now +\emph on + \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\hfill +online at: +\emph default + +\newline + +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +Changelog of SDCC + +\end_inset + + +\begin_inset Text + +\layout Standard +sdcc/Changelog +\emph on + \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\hfill +online at: +\emph default + +\newline + +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/ChangeLog} + +\end_inset + + + +\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 +\newline +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 +\emph on +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\hfill +online at: +\emph default + +\newline + +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html} + +\end_inset + + + +\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 +\emph on +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\hfill +online at: +\emph default + +\newline + +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +Various notes + +\end_inset + + +\begin_inset Text + +\layout Standard +sdcc/doc/* +\emph on +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\hfill +online at: +\emph default + +\newline + +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/doc/} + +\end_inset + + + +\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 +\emph on +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\hfill +online at +\emph default +: +\newline + +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/debugger/README} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +uCsim +\begin_inset LatexCommand \index{uCsim} + +\end_inset + + 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 +/index.html +\emph on +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\hfill +online at: +\emph default + +\newline + +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/sim/ucsim/doc/index.html} + +\end_inset + + + +\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 +\emph on +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\hfill +online at: +\newline + +\emph default + +\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/src/pic16/NOTES} + +\end_inset + + + +\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 +f +\emph on + \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\hfill +online at: +\emph default + +\newline + +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/cdbfileformat.pdf} + +\end_inset + + + +\end_inset + + + + +\end_inset + + +\newline + + +\layout Section +Related open source tools +\begin_inset LatexCommand \label{sec:Related-open-source-tools} + +\end_inset + + +\begin_inset LatexCommand \index{Related tools} + +\end_inset + + + +\layout Standard +\align left +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +\series bold +Name + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Purpose + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Where to get + +\end_inset + + + + +\begin_inset Text + +\layout Standard +gpsim +\begin_inset LatexCommand \index{gpsim (pic simulator)} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +PIC simulator + +\end_inset + + +\begin_inset Text + +\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 + +\layout Standard +Object file conversion, ... + +\end_inset + + +\begin_inset Text + +\layout Standard +Part of binutils (should be there anyway) + +\end_inset + + + + +\begin_inset Text + +\layout Standard +cmon51 + +\end_inset + + +\begin_inset Text + +\layout Standard +8051 monitor (hex up-/download, single step, disassemble) + +\end_inset + + +\begin_inset Text + +\layout Standard +\begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +doxygen +\begin_inset LatexCommand \index{doxygen (source documentation tool)} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +Source code documentation system + +\end_inset + + +\begin_inset Text + +\layout Standard +\begin_inset LatexCommand \url{http://www.doxygen.org} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +kdevelop + +\end_inset + + +\begin_inset Text + +\layout Standard +IDE (has anyone tried integrating SDCC & SDCDB? Unix only) + +\end_inset + + +\begin_inset Text + +\layout Standard +\begin_inset LatexCommand \url{http://www.kdevelop.org} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +paulmon + +\end_inset + + +\begin_inset Text + +\layout Standard +8051 monitor (hex up-/download, single step, disassemble) + +\end_inset + + +\begin_inset Text + +\layout Standard +\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +splint +\begin_inset LatexCommand \index{splint (syntax checking tool)} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +Statically checks c sources (see +\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT} + +\end_inset + +) + +\end_inset + + +\begin_inset Text + +\layout Standard +\begin_inset LatexCommand \url{http://www.splint.org} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +ddd +\begin_inset LatexCommand \index{DDD (debugger)} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +Debugger, serves nicely as GUI to SDCDB +\begin_inset LatexCommand \index{SDCDB (debugger)} + +\end_inset + + (Unix only) + +\end_inset + + +\begin_inset Text + +\layout Standard +\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 left +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +\series bold +Name + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Subject / Title + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Where to get + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\family roman +\series medium +\shape up +\size normal +\emph off +\bar no +\noun off +\color none +c-refcard.pdf + +\end_inset + + +\begin_inset Text + +\layout Standard +C Reference Card +\begin_inset LatexCommand \index{C Reference card} + +\end_inset + +, 2 pages + +\end_inset + + +\begin_inset Text + +\layout Standard +\begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +c-faq + +\end_inset + + +\begin_inset Text + +\layout Standard +C-FAQ +\begin_inset LatexCommand \index{C FAQ} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard +\begin_inset LatexCommand \url{http://www.c-faq.com} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +ISO/IEC 9899:TC2 + +\end_inset + + +\begin_inset Text + +\layout Standard +\begin_inset Quotes sld +\end_inset + +C-Standard +\begin_inset Quotes srd +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard +ISO/IEC DTR 18037 + +\end_inset + + +\begin_inset Text + +\layout Standard +\begin_inset Quotes sld +\end_inset + +Extensions for Embedded C +\begin_inset Quotes srd +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + + +\end_inset + + +\begin_inset Text + +\layout Standard +Latest datasheet of target CPU + +\end_inset + + +\begin_inset Text + +\layout Standard +vendor + +\end_inset + + + + +\begin_inset Text + +\layout Standard + + +\end_inset + + +\begin_inset Text + +\layout Standard +Revision history of datasheet + +\end_inset + + +\begin_inset Text + +\layout Standard +vendor + +\end_inset + + + + +\end_inset + + +\newline + + +\layout Section +Application notes specifically for SDCC + +\layout Standard +SDCC makes no claims about the completeness of this list and about up-to-datenes +s or correctness of the application notes +\begin_inset LatexCommand \index{Application notes} + +\end_inset + +. + +\layout Standard +\align left + +\size footnotesize +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +\series bold +\size footnotesize +Vendor + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +\size footnotesize +Subject / Title + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +\size footnotesize +Where to get + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Maxim / Dallas + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Using the SDCC Compiler for the DS80C400 +\begin_inset LatexCommand \index{DS80C400} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +\begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3346.pdf} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Maxim / Dallas + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Using the Free SDCC C Compiler to Develop Firmware for the DS89C420/430/440/450 +\begin_inset LatexCommand \index{DS89C4x0} + +\end_inset + + Family of Microcontrollers + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +\begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3477.pdf} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Silicon Laboratories / Cygnal + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Integrating SDCC 8051 Tools Into The Silicon Labs IDE +\begin_inset LatexCommand \index{IDE} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +\begin_inset LatexCommand \url{http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/en/an198.pdf} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Ramtron / Goal Semiconductor + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Interfacing SDCC to Syn and Textpad + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +\begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Ramtron / Goal Semiconductor + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Installing and Configuring SDCC and Crimson Editor + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +\begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp} + +\end_inset + + + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Texas Instruments + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +MSC12xx Programming with SDCC + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +\begin_inset LatexCommand \url{http://focus.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=sbaa109&fileType=pdf} + +\end_inset + + + +\end_inset + + + + +\end_inset + + + +\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 150,000 lines of code (blank stripped). + The open source nature of this project is a key to its continued growth + and support. + You gain the benefit and support of many active software developers and + end users. + Is SDCC perfect? No, that's why we need your help. + The developers take pride in fixing reported bugs. + You can help by reporting the bugs and helping other SDCC users. + There are lots of ways to contribute, and we encourage you to take part + in making SDCC a great software package. + + +\layout Standard +The SDCC project is hosted on the SDCC sourceforge site at +\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc} + +\end_inset + +. + You'll find the complete set of mailing lists +\begin_inset LatexCommand \index{Mailing list(s)} + +\end_inset + +, forums, bug reporting system, patch submission +\begin_inset LatexCommand \index{Patch submission} + +\end_inset + + system, download +\begin_inset LatexCommand \index{download} + +\end_inset + + area and Subversion code repository +\begin_inset LatexCommand \index{Subversion code repository} + +\end_inset + + there. + +\layout Section +Reporting Bugs +\begin_inset LatexCommand \index{Bug reporting} + +\end_inset + + +\begin_inset LatexCommand \index{Reporting bugs} + +\end_inset + + + +\layout Standard +The recommended way of reporting bugs is using the infrastructure of the + sourceforge site. + You can follow the status of bug reports there and have an overview about + the known bugs. + +\layout Standard +Bug reports are automatically forwarded to the developer mailing list and + will be fixed ASAP. + When reporting a bug, it is very useful to include a small test program + (the smaller the better) which reproduces the problem. + If you can isolate the problem by looking at the generated assembly code, + this can be very helpful. + Compiling your program with the - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumpall +\begin_inset LatexCommand \index{-\/-dumpall} + +\end_inset + + option can sometimes be useful in locating optimization problems. + When reporting a bug please make sure you: + +\layout Enumerate +Attach the code you are compiling with SDCC. + + +\layout Enumerate +Specify the exact command you use to run SDCC, or attach your Makefile. + + +\layout Enumerate +Specify the SDCC version (type " +\family sans +\series bold +sdcc -v +\family default +\series default +"), your platform, and operating system. + + +\layout Enumerate +Provide an exact copy of any error message or incorrect output. + + +\layout Enumerate +Put something meaningful in the subject of your message. + +\layout Standard +Please attempt to include these 5 important parts, as applicable, in all + requests for support or when reporting any problems or bugs with SDCC. + Though this will make your message lengthy, it will greatly improve your + chance that SDCC users and developers will be able to help you. + Some SDCC developers are frustrated by bug reports without code provided + that they can use to reproduce and ultimately fix the problem, so please + be sure to provide sample code if you are reporting a bug! + +\layout Standard +Please have a short check that you are using a recent version of SDCC and + the bug is not yet known. + This is the link for reporting bugs: +\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599} + +\end_inset + +. + With SDCC on average having more than 200 downloads +\begin_inset LatexCommand \index{download} + +\end_inset + + on sourceforge per day +\begin_inset Foot +collapsed false + +\layout Standard +220 daily downloads on average Jan-Sept 2006 and about 150 daily downloads + between 2002 and 2005. + This does not include other methods of distribution. + +\end_inset + + there must be some users. + So it's not exactly easy to find a new bug. + If you find one we need it: +\emph on +reporting bugs is good +\emph default +. + +\layout Section +Requesting Features +\begin_inset LatexCommand \label{sub:Requesting-Features} + +\end_inset + + +\begin_inset LatexCommand \index{Feature request} + +\end_inset + + +\begin_inset LatexCommand \index{Requesting features} + +\end_inset + + + +\layout Standard +Like bug reports feature requests are forwarded to the developer mailing + list. + This is the link for requesting features: +\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599} + +\end_inset + +. + +\layout Section +Submitting patches + +\layout Standard +Like bug reports contributed patches are forwarded to the developer mailing + list. + This is the link for submitting patches +\begin_inset LatexCommand \index{Patch submission} + +\end_inset + +: +\begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599} + +\end_inset + +. + +\layout Standard +You need to specify some parameters to the +\family typewriter +diff +\family default + command for the patches to be useful. + If you modified more than one file a patch created f.e. + with +\family sans +\series bold + +\begin_inset Quotes sld +\end_inset + +diff -Naur unmodified_directory modified_directory >my_changes.patch +\begin_inset Quotes srd +\end_inset + + +\family default +\series default + will be fine, otherwise +\family sans +\series bold + +\begin_inset Quotes sld +\end_inset + +diff -u sourcefile.c.orig sourcefile.c >my_changes.patch +\begin_inset Quotes srd +\end_inset + + +\series default + +\family default +will do. + +\layout Section +Getting Help + +\layout Standard +These links should take you directly to the +\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599} + +\end_inset + + +\begin_inset Foot +collapsed false + +\layout Standard +Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting + automated messages (mid 2003) + +\end_inset + + and the +\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599} + +\end_inset + +, lists +\begin_inset LatexCommand \index{Mailing list(s)} + +\end_inset + + and forums are archived and searchable so if you are lucky someone already + had a similar problem. + While mails to the lists themselves are delivered promptly their web front + end on sourceforge sometimes shows a severe time lag (up to several weeks), + if you're seriously using SDCC please consider subscribing to the lists. + +\layout Section +ChangeLog + +\layout Standard +You can follow the status of the Subversion version +\begin_inset LatexCommand \index{version} + +\end_inset + + of SDCC by watching the Changelog +\begin_inset LatexCommand \index{Changelog} + +\end_inset + + in the Subversion repository +\size footnotesize + +\begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog} + +\end_inset + +. + +\layout Section +Subversion Source Code Repository + +\layout Standard +The output of +\family sans +\series bold +sdcc --version +\family default +\series default + or the filenames of the snapshot versions of SDCC include date and its + Subversion +\begin_inset LatexCommand \index{Subversion code repository} + +\end_inset + + number. + Subversion allows to download the source of recent or previous versions + +\begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599} + +\end_inset + + (by number or by date). + An on-line source code browser and detailled instructions are also available + there. + SDCC versions starting from 1999 up to now are available (currently the + versions prior to the conversion from cvs +\begin_inset LatexCommand \index{cvs|see{Subversion}} + +\end_inset + + to Subversion (April 2006) are either by accessible by Subversion or by + cvs). + +\layout Section +Release policy +\begin_inset LatexCommand \index{Release policy} + +\end_inset + + + +\layout Standard +Historically there often were long delays between official releases and + the sourceforge download area tends to get not updated at all. + Excuses in the past might have referred to problems with live range analysis, + but as this was fixed a while ago, the current problem is that another + excuse has to be found. + Kidding aside, we have to get better there! On the other hand there are + daily snapshots available at +\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php} + +\end_inset + +, and you can always build the very last version (hopefully with many bugs + fixed, and features added) from the source code available at +\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source} + +\end_inset + +. + A release wiki +\begin_inset LatexCommand \index{wiki} + +\end_inset + + +\begin_inset LatexCommand \index{Release wiki} + +\end_inset + + at +\begin_inset LatexCommand \url{http://sdcc.sf.net/release_wiki/} + +\end_inset + + also holds some information about past and future releases. + +\layout Section +Examples +\begin_inset LatexCommand \index{Examples} + +\end_inset + + + +\layout Standard +You'll find some small examples in the directory +\emph on +sdcc/device/examples/. + +\emph default +More examples and libraries are available at +\emph on + The SDCC Open Knowledge Resource +\begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/} + +\end_inset + + +\emph default +web site or at +\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/} + +\end_inset + +. + +\layout Standard +\begin_inset Note +collapsed true + +\layout Standard +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 Standard +Maybe we should include some links to real world applications. + Preferably pointer to pointers (one for each architecture) so this stays + manageable here? + +\end_inset + + + +\layout Section +Quality control +\begin_inset LatexCommand \label{sec:Quality-control} + +\end_inset + + +\begin_inset LatexCommand \index{Quality control} + +\end_inset + + + +\layout Standard +The compiler is passed through nightly compile and build checks. + The so called +\shape italic +regression tests +\shape default + +\begin_inset LatexCommand \index{Regression test} + +\end_inset + + check that SDCC itself compiles flawlessly on several host platforms (i386, + Opteron, 64 bit Alpha, ppc64, MacOS X on PPC, Solaris on Sparc) and checks + the quality of the code generated by SDCC by running the code for several + target platforms through simulators. + The regression test suite comprises more than 100 files which expand to + more than 500 test cases which include more than 4500 tests. + The results of these tests are published daily on SDCC's snapshot page + (click on the red or green symbols on the right side of +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php} + +\end_inset + +). + +\layout Standard +There is a separate document +\shape italic +test_suite.pdf +\begin_inset LatexCommand \index{Test suite} + +\end_inset + + +\shape default + +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf} + +\end_inset + + about the regression test suite. + +\layout Standard +You'll find the test code in the directory +\shape italic +sdcc/support/regression +\shape default +. + You can run these tests manually by running +\family sans +make +\family default + in this directory (or f.e. + +\family sans +\series bold + +\begin_inset Quotes sld +\end_inset + +make test-mcs51 +\begin_inset Quotes srd +\end_inset + + +\family default +\series default + if you don't want to run the complete tests). + The test code might also be interesting if you want to look for examples +\begin_inset LatexCommand \index{Examples} + +\end_inset + + checking corner cases of SDCC or if you plan to submit patches +\begin_inset LatexCommand \index{Patch submission} + +\end_inset + +. + +\layout Standard +The 14bit pic port uses a different set of regression tests +\begin_inset LatexCommand \index{Regression test (PIC14)} + +\end_inset + +, you'll find them in the directory +\shape italic +sdcc/src/regression +\shape default +. + +\layout Section +Use of SDCC in Education + +\layout Standard +In short: +\emph on +highly +\emph default + encouraged +\begin_inset Foot +collapsed false + +\layout Standard +the phrase "use in education" might evoke the association " +\emph on +only +\emph default + fit for use in education". + This connotation is not intended but nevertheless risked as the licensing + of SDCC makes it difficult to offer educational discounts + +\end_inset + +. + If your rationales are to: + +\layout Enumerate +give students a chance to understand the +\emph on +complete +\emph default + steps of code generation + +\layout Enumerate +have a curriculum that can be extended for years. + Then you could use an fpga board as target and your curriculum will seamlessly + extend from logic synthesis ( +\begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org} + +\end_inset + +, +\begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm} + +\end_inset + +), over assembly programming, to C to FPGA compilers ( +\begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac} + +\end_inset + +) and to C. + +\layout Enumerate +be able to insert excursions about skills like using a revision control + system, submitting/applying patches, using a type-setting (as opposed to + word-processing) engine LyX/LaTeX, using +\begin_inset LatexCommand \url[SourceForge]{http://www.sf.net} + +\end_inset + +, following some +\begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette} + +\end_inset + +, understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open + Source Software, CPU simulation, compiler regression tests +\begin_inset LatexCommand \index{Regression test} + +\end_inset + +. + +\newline +And if there should be a shortage of ideas then you can always point students + to the ever-growing feature request list +\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599} + +\end_inset + +. + +\layout Enumerate +not tie students to a specific host platform and instead allow them to use + a host platform of +\emph on +their +\emph default + choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and + eventually +\begin_inset LatexCommand \url[OLPC]{http://www.laptop.org} + +\end_inset + +) + +\layout Enumerate +not encourage students to use illegal copies of educational software + +\layout Enumerate +be immune to licensing/availability/price changes of the chosen tool chain + +\layout Enumerate +be able to change to a new target platform without having to adopt a new + tool chain + +\layout Enumerate +have complete control over and insight into the tool chain + +\layout Enumerate +make your students aware about the pros and cons of open source software + development + +\layout Enumerate +give back to the public as you are probably at least partially publically + funded + +\layout Enumerate +give students a chance to publically prove their skills and to possibly + see a world wide impact + +\layout Standard +\pagebreak_bottom +then SDCC is probably among the first choices. + Well, probably SDCC might be the only choice. + + +\layout Chapter +SDCC Technical Data + +\layout Section +Optimizations +\begin_inset LatexCommand \index{Optimizations} + +\end_inset + + + +\layout Standard +SDCC performs a host of standard optimizations in addition to some MCU specific + optimizations. + + +\layout Subsection +Sub-expression Elimination +\begin_inset LatexCommand \index{Subexpression elimination} + +\end_inset + + + +\layout Standard +The compiler does local and +\emph on +g +\emph default +lobal +\emph on +c +\emph default +ommon +\emph on +s +\emph default +ubexpression +\emph on +e +\emph default +limination, e.g.: + +\layout Verse + +\family typewriter +i = x + y + 1; +\newline +j = x + y; + +\layout Standard +will be translated to + +\layout Verse + +\family typewriter +iTemp = x + y; +\newline +i = iTemp + 1; +\newline +j = iTemp; + +\layout Standard +Some subexpressions are not as obvious as the above example, e.g.: + +\layout Verse + +\family typewriter +a->b[i].c = 10; +\newline +a->b[i].d = 11; + +\layout Standard +In this case the address arithmetic a->b[i] will be computed only once; + the equivalent code in C would be. + +\layout Verse + +\family typewriter +iTemp = a->b[i]; +\newline +iTemp.c = 10; +\newline +iTemp.d = 11; + +\layout Standard +The compiler will try to keep these temporary variables in registers. + +\layout Subsection +Dead-Code Elimination +\begin_inset LatexCommand \index{Dead-code elimination} + +\end_inset + + + +\layout Verse + +\family typewriter +int global; +\newline + +\newline +void f () { +\newline +\SpecialChar ~ +\SpecialChar ~ +int i; +\newline +\SpecialChar ~ +\SpecialChar ~ +i = 1; \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* dead store */ +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 1;\SpecialChar ~ +/* dead + store */ +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 2; +\newline +\SpecialChar ~ +\SpecialChar ~ +return; +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 3;\SpecialChar ~ +/* unreachable */ +\newline +} + +\layout Standard +will be changed to + +\layout Verse + +\family typewriter +int global; +\newline + +\newline +void f () { +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 2; +\newline +} + +\layout Subsection +Copy-Propagation +\begin_inset LatexCommand \index{Copy propagation} + +\end_inset + + + +\layout Verse + +\family typewriter +int f() { +\newline +\SpecialChar ~ +\SpecialChar ~ +int i, j; +\newline +\SpecialChar ~ +\SpecialChar ~ +i = 10; +\newline +\SpecialChar ~ +\SpecialChar ~ +j = i; +\newline +\SpecialChar ~ +\SpecialChar ~ +return j; +\newline +} + +\layout Standard +will be changed to + +\layout Verse + +\family typewriter +int f() { +\newline +\SpecialChar ~ +\SpecialChar ~ +int i, j; +\newline +\SpecialChar ~ +\SpecialChar ~ +i = 10; +\newline +\SpecialChar ~ +\SpecialChar ~ +j = 10; +\newline +\SpecialChar ~ +\SpecialChar ~ +return 10; +\newline +} + +\layout Standard +Note: the dead stores created by this copy propagation will be eliminated + by dead-code elimination. + +\layout Subsection +Loop Optimizations +\begin_inset LatexCommand \index{Loop optimization} + +\end_inset + + +\begin_inset LatexCommand \label{sub:Loop-Optimizations} + +\end_inset + + + +\layout Standard +Two types of loop optimizations are done by SDCC +\emph on +loop invariant +\emph default + lifting and +\emph on + strength reduction +\emph default + of loop induction variables. + In addition to the strength reduction the optimizer marks the induction + variables and the register allocator tries to keep the induction variables + in registers for the duration of the loop. + Because of this preference of the register allocator +\begin_inset LatexCommand \index{Register allocation} + +\end_inset + +, loop induction optimization causes an increase in register pressure, which + may cause unwanted spilling of other temporary variables into the stack +\begin_inset LatexCommand \index{stack} + +\end_inset + + / data space. + The compiler will generate a warning message when it is forced to allocate + extra space either on the stack or data space. + If this extra space allocation is undesirable then induction optimization + can be eliminated either for the entire source file (with - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-noinduction option) or for a given function only using #pragma\SpecialChar ~ +noinduction +\begin_inset LatexCommand \index{\#pragma noinduction} + +\end_inset + +. +\newline + +\newline +Loop Invariant: + +\layout Verse + +\family typewriter +for (i = 0 ; i < 100 ; i ++) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +f += k + l; + +\layout Standard +changed to + +\layout Verse + +\family typewriter +itemp = k + l; +\newline +for (i = 0; i < 100; i++) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +f += itemp; + +\layout Standard +As mentioned previously some loop invariants are not as apparent, all static + address computations are also moved out of the loop. +\newline + +\newline +Strength Reduction +\begin_inset LatexCommand \index{Strength reduction} + +\end_inset + +, this optimization substitutes an expression by a cheaper expression: + +\layout Verse + +\family typewriter +for (i=0;i < 100; i++) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ar[i*5] = i*3; + +\layout Standard +changed to + +\layout Verse + +\family typewriter +itemp1 = 0; +\newline +itemp2 = 0; +\newline +for (i=0;i< 100;i++) { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ar[itemp1] = itemp2; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +itemp1 + += 5; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +itemp2 += 3; +\newline +} + +\layout Standard +The more expensive multiplication +\begin_inset LatexCommand \index{Multiplication} + +\end_inset + + is changed to a less expensive addition. + +\layout Subsection +Loop Reversing +\begin_inset LatexCommand \index{Loop reversing} + +\end_inset + + + +\layout Standard +This optimization is done to reduce the overhead of checking loop boundaries + for every iteration. + Some simple loops can be reversed and implemented using a +\begin_inset Quotes eld +\end_inset + +decrement and jump if not zero +\begin_inset Quotes erd +\end_inset + + instruction. + SDCC checks for the following criterion to determine if a loop is reversible + (note: more sophisticated compilers use data-dependency analysis to make + this determination, SDCC uses a more simple minded analysis). + +\layout Itemize +The 'for' loop is of the form +\newline + +\newline + +\family typewriter +for( = ; [< | <=] ; [++ | + += 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 + +. + +\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 ~ +\SpecialChar ~ +\SpecialChar ~ + i >>= 1; +\newline +i + = j - j;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + /* changed to: */\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + i = 0; +\newline +i = j / 1;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + /* changed to: */\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + i = j; + +\layout Standard +Note the subexpressions +\begin_inset LatexCommand \index{Subexpression} + +\end_inset + + given above are generally introduced by macro expansions or as a result + of copy/constant propagation. + +\layout Subsection +'switch' Statements +\begin_inset LatexCommand \label{sub:'switch'-Statements} + +\end_inset + + +\begin_inset LatexCommand \index{switch statement} + +\end_inset + + + +\layout Standard +SDCC can optimize switch statements to jump tables +\begin_inset LatexCommand \index{jump tables} + +\end_inset + +. + It makes the decision based on an estimate of the generated code size. + SDCC is quite liberal in the requirements for jump table generation: + +\layout Itemize +The labels need not be in order, and the starting number need not be one + or zero, the case labels are in numerical sequence or not too many case + labels are missing. + +\begin_deeper +\layout Verse + +\family typewriter +switch(i) {\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +switch (i) { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 4: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 0: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 5: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 1: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 3: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 6: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 3: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 7: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 4: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 8: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 5: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 9: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 6: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 10: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 7: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 11: ...\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +case 8: ... + +\newline +}\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +} + +\layout Standard +Both the above switch statements will be implemented using a jump-table. + The example to the right side is slightly more efficient as the check for + the lower boundary of the jump-table is not needed. + +\end_deeper +\layout Itemize +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 +\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 +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: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 3: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 4: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 5: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 6: ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +case 7: ... + +\newline +} + +\layout Standard +and + +\layout Verse + +\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 +then both the switch statements will be implemented using jump-tables whereas + the unmodified switch statement will not be. + +\layout Standard +\begin_inset Note +collapsed true + +\layout Standard +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). + +\end_inset + + + +\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 ~ +\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 ~ +\SpecialChar ~ +a +\newline +mov\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)); + +\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 +\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 + +\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 + + +\begin_inset LatexCommand \index{Endianness} + +\end_inset + + format (i.e. + lowest order first). + +\layout Subsection +Highest Order Bit +\begin_inset LatexCommand \index{Highest Order Bit} + +\end_inset + + / Any Order Bit +\begin_inset LatexCommand \index{Any Order Bit} + +\end_inset + + + +\layout Standard +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 +unsigned int gint; +\newline + +\newline +foo () { +\newline +\SpecialChar ~ +\SpecialChar ~ +unsigned char hob1, aob1; +\newline +\SpecialChar ~ +\SpecialChar ~ +bit hob2, hob3, aob2, + aob3; +\newline +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +\SpecialChar ~ +\SpecialChar ~ +hob1 = (gint >> 15) & 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +hob2 = (gint >> 15) & 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +hob3 = gint & 0x8000; + +\newline +\SpecialChar ~ +\SpecialChar ~ +aob1 = (gint >> 9) & 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +aob2 = (gint >> 8) & 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +aob3 = gint & 0x0800; +\newline +\SpecialChar ~ +\SpecialChar ~ +.. + +\newline +} + +\layout Standard +will generate the following code: + +\layout Verse + +\family typewriter +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 61 ;\SpecialChar ~ + hob.c 7 +\newline +000A E5*01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 62\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + a,(_gint + 1) +\newline +000C 23\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 63\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + rl\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + a +\newline +000D 54 01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + + 64\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + anl\SpecialChar ~ +\SpecialChar ~ + a,#0x01 +\newline +000F F5*02\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 65\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_hob1_1_1,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 66 ;\SpecialChar ~ + hob.c 8 +\newline +0011 E5*01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + + 67\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + a,(_gint + 1) +\newline +0013 33\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 68\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + rlc\SpecialChar ~ +\SpecialChar ~ + a +\newline +0014 92*00\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 69\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_hob2_1_1,c + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 66 ;\SpecialChar ~ + hob.c 9 +\newline +0016 E5*01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 67\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + a,(_gint + 1) +\newline +0018 33\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 68\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + rlc\SpecialChar ~ +\SpecialChar ~ + a +\newline +0019 92*01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + + 69\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_hob3_1_1,c +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 70 ;\SpecialChar ~ + hob.c 10 +\newline +001B E5*01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 71\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + a,(_gint + 1) +\newline +001D + 03\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 72\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + rr\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + a +\newline +001E 54 01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 73\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + anl\SpecialChar ~ +\SpecialChar ~ + a,#0x01 +\newline +0020 F5*03\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 74\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -6966,7 +31310,11 @@ SDCDB ptypecommand for data at \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + _foo_aob1_1_1,a + +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -6988,13 +31336,14 @@ SDCDB ptypecommand for data at \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - buffer point -\newline -;; x\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 75 ;\SpecialChar ~ + hob.c 11 +\newline +0022 E5*01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7004,12 +31353,12 @@ SDCDB ptypecommand for data at \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - sdcdbsrc-delete\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 76\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7017,10 +31366,11 @@ SDCDB ptypecommand for data at \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ -SDCDB Delete all breakpoints if no arg -\newline -;;\SpecialChar ~ + a,(_gint + 1) +\newline +0024 13\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7038,6 +31388,7 @@ SDCDB Delete all breakpoints if no arg \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 77\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7045,7 +31396,11 @@ SDCDB Delete all breakpoints if no arg \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + rrc\SpecialChar ~ \SpecialChar ~ + a +\newline +0025 92*02\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7060,17 +31415,19 @@ SDCDB Delete all breakpoints if no arg \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + + 78\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -given or delete arg (C-u arg x) -\newline -;; m\SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + _foo_aob2_1_1,c +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7082,7 +31439,6 @@ given or delete arg (C-u arg x) \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - sdcdbsrc-frame\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7097,9 +31453,10 @@ given or delete arg (C-u arg x) \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -SDCDB Display current frame if no arg, -\newline -;;\SpecialChar ~ + 79 ;\SpecialChar ~ + hob.c 12 +\newline +0027 E5*01\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7114,6 +31471,7 @@ SDCDB Display current frame if no arg, \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 80\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7121,7 +31479,12 @@ SDCDB Display current frame if no arg, \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ \SpecialChar ~ + a,(_gint + 1) +\newline +0029 + A2 E3\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7135,6 +31498,244 @@ SDCDB Display current frame if no arg, \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +\SpecialChar ~ + 81\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + c,acc[3] +\newline +002B 92*03\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 82\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_aob3_1_1,c + +\layout Standard +Other variations of these cases however will +\emph on +not +\emph default + be recognized. + They are standard C expressions, so I heartily recommend these be the only + way to get the highest order bit, (it is portable). + Of course it will be recognized even if it is embedded in other expressions, + e.g.: + +\layout Verse + +\family typewriter +xyz = gint + ((gint >> 15) & 1); + +\layout Standard +will still be recognized. + +\layout Subsection +Higher Order Byte +\begin_inset LatexCommand \index{Higher Order Byte} + +\end_inset + + / Higher Order Word +\begin_inset LatexCommand \index{Higher Order Word} + +\end_inset + + + +\layout Standard +It is also frequently required to obtain a higher order byte or word of + a larger integral type (long, int or short types). + SDCC recognizes the following expressions to yield the higher order byte + or word and generates optimized code for it, e.g.: + +\layout Verse + +\family typewriter +unsigned int gint; +\newline +unsigned long int glong; +\newline + +\newline +foo () { +\newline +\SpecialChar ~ +\SpecialChar ~ +unsigned char hob1, + hob2; +\newline +\SpecialChar ~ +\SpecialChar ~ +unsigned int how1, how2; +\newline +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +\SpecialChar ~ +\SpecialChar ~ +hob1 = (gint >> 8) & 0xFF; +\newline +\SpecialChar ~ +\SpecialChar ~ +hob2 = glong >> 24; +\newline +\SpecialChar ~ +\SpecialChar ~ +how1 = (glong >> 16) & 0xFFFF; + +\newline +\SpecialChar ~ +\SpecialChar ~ +how2 = glong >> 8; +\newline +\SpecialChar ~ +\SpecialChar ~ +.. + +\newline +} + +\layout Standard +will generate the following code: + +\layout Verse + +\family typewriter +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 91 ;\SpecialChar ~ + hob.c 15 +\newline +0037 85*01*06\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 92\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_hob1_1_1,(_gint + 1) +\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 ~ + 93 ;\SpecialChar ~ + hob.c + 16 +\newline +003A 85*05*07\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 94\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_hob2_1_1,(_glong + 3) +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7146,9 +31747,6 @@ SDCDB Display current frame if no arg, \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -given or display frame arg -\newline -;;\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7163,6 +31761,10 @@ given or display frame arg \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 95 ;\SpecialChar ~ + hob.c 17 +\newline +003D 85*04*08\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7173,6 +31775,47 @@ given or display frame arg \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +\SpecialChar ~ + + 96\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_how1_1_1,(_glong + 2) +\newline +0040 85*05*09\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\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 +0043 85*03*0A\SpecialChar ~ +\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7183,6 +31826,7 @@ given or display frame arg \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + 98\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -7190,388 +31834,4134 @@ given or display frame arg \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + _foo_how2_1_1,(_glong + 1) +\newline +0046 85*04*0B\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + + 99\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ + (_foo_how2_1_1 + 1),(_glong + 2) + +\layout Standard +Again, variations of these cases may +\emph on +not +\emph default + be recognized. + They are standard C expressions, so I heartily recommend these be the only + way to get the higher order byte/word, (it is portable). + Of course it will be recognized even if it is embedded in other expressions, + e.g.: + +\layout Verse + +\family typewriter +xyz = gint + ((gint >> 8) & 0xFF); + +\layout Standard +will still be recognized. + +\layout Subsection +Peephole Optimizer +\begin_inset LatexCommand \label{sub:Peephole-Optimizer} + +\end_inset + + +\begin_inset LatexCommand \index{Peephole optimizer} + +\end_inset + + + +\layout Standard +The compiler uses a rule based, pattern matching and re-writing mechanism + for peep-hole optimization. + It is inspired by +\emph on +copt +\emph default + a peep-hole optimizer by Christopher W. + Fraser (cwfraser\SpecialChar ~ +@\SpecialChar ~ +microsoft.com). + A default set of rules are compiled into the compiler, additional rules + may be added with the +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-peep-file +\begin_inset LatexCommand \index{-\/-peep-file} + +\end_inset + + +\emph default + option. + The rule language is best illustrated with examples. + +\layout Verse + +\family typewriter +replace { +\newline +\SpecialChar ~ +\SpecialChar ~ +mov %1,a +\newline \SpecialChar ~ \SpecialChar ~ +mov a,%1 +\newline +} by { +\newline \SpecialChar ~ \SpecialChar ~ +mov %1,a +\newline +} + +\layout Standard +The above rule will change the following assembly +\begin_inset LatexCommand \index{Assembler routines} + +\end_inset + + sequence: + +\layout Verse + +\family typewriter +mov r1,a +\newline +mov a,r1 + +\layout Standard +to + +\layout Verse + +\family typewriter +mov r1,a + +\layout Standard +Note: All occurrences of a +\emph on +%n +\emph default + (pattern variable) must denote the same string. + With the above rule, the assembly sequence: + +\layout Verse + +\family typewriter +mov r1,a +\newline +mov a,r2 + +\layout Standard +will remain unmodified. +\newline + +\newline +Other special case optimizations may be added by the + user (via +\emph on +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-peep-file option +\emph default +). + E.g. + some variants of the 8051 MCU +\begin_inset LatexCommand \index{MCS51 variants} + +\end_inset + + allow only +\family typewriter +ajmp +\family default + and +\family typewriter +acall +\family default +. + The following two rules will change all +\family typewriter +ljmp +\family default + and +\family typewriter +lcall +\family default + to +\family typewriter +ajmp +\family default + and +\family typewriter +acall + +\layout Verse + +\family typewriter +replace { lcall %1 } by { acall %1 } +\newline +replace { ljmp %1 } by { ajmp %1 } + +\layout Standard +The +\emph on +inline-assembler code +\emph default + is also passed through the peep hole optimizer, thus the peephole optimizer + can also be used as an assembly level macro expander. + The rules themselves are MCU dependent whereas the rule language infra-structur +e is MCU independent. + Peephole optimization rules for other MCU can be easily programmed using + the rule language. +\newline + +\newline +The syntax for a rule is as follows: + +\layout Verse + +\family typewriter +rule := replace [ restart ] '{' ' +\backslash +n' +\newline \SpecialChar ~ -buffer point -\newline -;; !\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + '}' by '{' ' +\backslash +n' +\newline \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + ' +\backslash +n' +\newline \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + '}' [if ] ' +\backslash +n' + +\layout Standard + := assembly instruction (each instruction including + labels must be on a separate line). +\newline + +\newline +The optimizer will apply to the rules + one by one from the top in the sequence of their appearance, it will terminate + when all rules are exhausted. + If the 'restart' option is specified, then the optimizer will start matching + the rules again from the top, this option for a rule is expensive (performance) +, it is intended to be used in situations where a transformation will trigger + the same rule again. + An example of this (not a good one, it has side effects) is the following + rule: + +\layout Verse + +\family typewriter +replace restart { +\newline \SpecialChar ~ \SpecialChar ~ +pop %1 +\newline \SpecialChar ~ \SpecialChar ~ +push %1 } by { +\newline \SpecialChar ~ \SpecialChar ~ +; nop +\newline +} + +\layout Standard +Note that the replace pattern cannot be a blank, but can be a comment line. + Without the 'restart' option only the innermost 'pop' 'push' pair would + be eliminated, i.e.: + +\layout Verse + +\family typewriter +pop ar1 +\newline +pop ar2 +\newline +push ar2 +\newline +push ar1 + +\layout Standard +would result in: + +\layout Verse + +\family typewriter +pop ar1 +\newline +; nop +\newline +push ar1 + +\layout Standard + +\emph on +with +\emph default + the restart option the rule will be applied again to the resulting code + and then all the pop-push pairs will be eliminated to yield: + +\layout Verse + +\family typewriter +; nop +\newline +; nop + +\layout Standard +A conditional function can be attached to a rule. + Attaching rules are somewhat more involved, let me illustrate this with + an example. + +\layout Verse + +\family typewriter +replace { +\newline \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +ljmp %5 +\newline +%2: +\newline +} by { +\newline \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +sjmp %5 +\newline +%2: +\newline +} if labelInRange + +\layout Standard +The optimizer does a look-up of a function name table defined in function + +\emph on +callFuncByName +\emph default + in the source file SDCCpeeph.c, with the name +\emph on +labelInRange +\emph default +. + If it finds a corresponding entry the function is called. + Note there can be no parameters specified for these functions, in this + case the use of +\emph on +%5 +\emph default + is crucial, since the function +\emph on +labelInRange +\emph default + expects to find the label in that particular variable (the hash table containin +g the variable bindings is passed as a parameter). + If you want to code more such functions, take a close look at the function + labelInRange and the calling mechanism in source file SDCCpeeph.c. + Currently implemented are +\emph on +labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption, + 24bitMode, portIsDS390, 24bitModeAndPortDS390 +\emph default +and +\emph on + notVolatile +\emph default +. + +\layout Standard +I know this whole thing is a little kludgey, but maybe some day we will + have some better means. + If you are looking at this file, you will see the default rules that are + compiled into the compiler, you can add your own rules in the default set + there if you get tired of specifying the - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-peep-file option. + +\layout Section +ANSI-Compliance +\begin_inset LatexCommand \index{ANSI-compliance} + +\end_inset + + +\begin_inset LatexCommand \label{sub: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: + +\layout Itemize +functions are not reentrant +\begin_inset LatexCommand \index{reentrant} + +\end_inset + + unless explicitly declared as such or the +\series bold +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-stack-auto +\begin_inset LatexCommand \index{-\/-stack-auto} + +\end_inset + + +\series default + command line option is specified. + +\layout Itemize +structures +\begin_inset LatexCommand \index{struct} + +\end_inset + + and unions +\begin_inset LatexCommand \index{union} + +\end_inset + + cannot be assigned values directly, cannot be passed as function parameters + or assigned to each other and cannot be a return value +\begin_inset LatexCommand \index{return value} + +\end_inset + + from a function, e.g.: + +\begin_deeper +\layout Verse + +\family typewriter +struct s { ... + }; +\newline +struct s s1, s2; +\newline +foo() +\newline +{ +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - sdcdbsrc-goto-sdcdb\SpecialChar ~ \SpecialChar ~ +... + +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -Goto the SDCDB output buffer -\newline -;; p\SpecialChar ~ +... + +\newline +} +\newline + +\series bold +struct +\series default + s foo1 ( +\series bold +struct +\series default + s parms) /* invalid in SDCC although allowed in ANSI */ +\newline +{ +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +struct s rets; + +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +... + +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +return rets; /* is invalid in SDCC although allowed in ANSI */ +\newline +} + +\end_deeper +\layout Itemize +initialization of structure arrays must be fully braced. + +\begin_deeper +\layout Verse + +\family typewriter +struct s { char x } a[] = {1, 2};\SpecialChar ~ \SpecialChar ~ - sdcdb-print-c-sexp\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +/* 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)} + +\end_inset + +' (64 bit integers +\begin_inset LatexCommand \index{int (64 bit) (not supported)} + +\end_inset + +) not supported. + +\layout Itemize +'double +\begin_inset LatexCommand \index{double (not supported)} + +\end_inset + +' precision floating point +\begin_inset LatexCommand \index{Floating point support} + +\end_inset + +not supported. + +\layout Itemize +Old K&R style +\begin_inset LatexCommand \index{K\&R style} + +\end_inset + + function declarations are NOT allowed. + +\begin_deeper +\layout Verse + +\family typewriter +foo(i,j) /* this old style of function declarations */ +\newline +int i,j; /* are valid + in ANSI but not valid in SDCC */ +\newline +{ +\newline \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +... + +\newline +} + +\end_deeper +\layout Itemize +Most enhancements in C99 are not supported, f.e.: + +\begin_deeper +\layout Verse + +\family typewriter +\series bold +inline +\begin_inset LatexCommand \index{inline (not supported)} + +\end_inset + + +\series default + int increment (int a) { return a+1; } /* is invalid in SDCC although allowed + in C99. + An empty define +\emph on +#define inline +\emph default + can be used as a work around */ +\newline + +\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 +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-std-c89 +\begin_inset LatexCommand \index{-\/-std-c89} + +\end_inset + + or - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-std-c99 +\begin_inset LatexCommand \index{-\/-std-c99} + +\end_inset + + +\series default + command line options are used. + These may include (depending on the selected processor): 'at', 'banked', + 'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup +t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs', + 'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and + '_naked'. + Compliant equivalents of these keywords are always available in a form + that begin with two underscores +\begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)} + +\end_inset + +, f.e. + '__data' instead of 'data'. + +\layout Section +Cyclomatic Complexity +\begin_inset LatexCommand \index{Cyclomatic complexity} + +\end_inset + + + +\layout Standard +Cyclomatic complexity of a function is defined as the number of independent + paths the program can take during execution of the function. + This is an important number since it defines the number test cases you + have to generate to validate the function. + The accepted industry standard for complexity number is 10, if the cyclomatic + complexity reported by SDCC exceeds 10 you should think about simplification + of the function logic. + Note that the complexity level is not related to the number of lines of + code in a function. + Large functions can have low complexity, and small functions can have large + complexity levels. + +\newline + +\newline +SDCC uses the following formula to compute the complexity: +\newline + + +\layout Standard +complexity = (number of edges in control flow graph) - (number of nodes + in control flow graph) + 2; +\newline + +\newline +Having said that the industry standard is 10, + you should be aware that in some cases it be may unavoidable to have a + complexity level of less than 10. + For example if you have switch statement with more than 10 case labels, + each case label adds one to the complexity level. + The complexity level is by no means an absolute measure of the algorithmic + complexity of the function, it does however provide a good starting point + for which functions you might look at for further optimization. + +\layout Section +Retargetting for other Processors + +\layout Standard +The issues for retargetting the compiler are far too numerous to be covered + by this document. + What follows is a brief description of each of the seven phases of the + compiler and its MCU dependency. + +\layout Itemize +Parsing the source and building the annotated parse tree. + This phase is largely MCU independent (except for the language extensions). + Syntax & semantic checks are also done in this phase, along with some initial + optimizations like back patching labels and the pattern matching optimizations + like bit-rotation etc. + +\layout Itemize +The second phase involves generating an intermediate code which can be easy + manipulated during the later phases. + This phase is entirely MCU independent. + The intermediate code generation assumes the target machine has unlimited + number of registers, and designates them with the name iTemp. + The compiler can be made to dump a human readable form of the code generated + by using the - +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +-dumpraw option. + +\layout Itemize +This phase does the bulk of the standard optimizations and is also MCU independe +nt. + This phase can be broken down into several sub-phases: +\newline + +\newline +Break down intermediate + code (iCode) into basic blocks. +\newline +Do control flow & data flow analysis on the + basic blocks. +\newline +Do local common subexpression elimination, then global subexpressio +n elimination +\newline +Dead code elimination +\newline +Loop optimizations +\newline +If loop optimizations + caused any changes then do 'global subexpression elimination' and 'dead + code elimination' again. + +\layout Itemize +This phase determines the live-ranges; by live range I mean those iTemp + variables defined by the compiler that still survive after all the optimization +s. + Live range analysis +\begin_inset LatexCommand \index{Live range analysis} + +\end_inset + + is essential for register allocation, since these computation determines + which of these iTemps will be assigned to registers, and for how long. + +\layout Itemize +Phase five is register allocation. + There are two parts to this process. +\newline + +\newline +The first part I call 'register packing' + (for lack of a better term). + In this case several MCU specific expression folding is done to reduce + register pressure. +\newline + +\newline +The second part is more MCU independent and deals with + allocating registers to the remaining live ranges. + A lot of MCU specific code does creep into this phase because of the limited + number of index registers available in the 8051. + +\layout Itemize +The Code generation phase is (unhappily), entirely MCU dependent and very + little (if any at all) of this code can be reused for other MCU. + However the scheme for allocating a homogenized assembler operand for each + iCode operand may be reused. + +\layout Itemize +As mentioned in the optimization section the peep-hole optimizer is rule + based system, which can reprogrammed for other MCUs. + +\layout Standard +More information is available in a wiki +\begin_inset LatexCommand \index{wiki} + +\end_inset + + (preliminary link +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/release_wiki/index.php?page=SDCC+internals+and+porting} + +\end_inset + +) and in the thread +\begin_inset LatexCommand \url{http://sf.net/mailarchive/message.php?msg_id=13954144} + +\end_inset + + . + +\layout Chapter +Compiler internals +\begin_inset LatexCommand \index{Compiler internals} + +\end_inset + + + +\layout Section +The anatomy of the compiler +\begin_inset LatexCommand \label{sub:The-anatomy-of} + +\end_inset + + + +\layout Standard + +\shape italic +This is an excerpt from an article published in Circuit Cellar Magazine + in +\series bold +August 2000 +\series default +. + It's a little outdated (the compiler is much more efficient now and user/develo +per friendly), but pretty well exposes the guts of it all. +\shape default + +\newline + +\newline +The current version of SDCC can generate code for Intel 8051 and Z80 MCU. + It is fairly easy to retarget for other 8-bit MCU. + Here we take a look at some of the internals of the compiler. + + +\layout Paragraph* +Parsing +\begin_inset LatexCommand \index{Parsing} + +\end_inset + + + +\layout Standard +Parsing the input source file and creating an AST (Annotated Syntax Tree +\begin_inset LatexCommand \index{Annotated syntax tree} + +\end_inset + +). + This phase also involves propagating types (annotating each node of the + parse tree with type information) and semantic analysis. + There are some MCU specific parsing rules. + For example the storage classes, the extended storage classes are MCU specific + while there may be a xdata storage class for 8051 there is no such storage + class for z80 or Atmel AVR. + SDCC allows MCU specific storage class extensions, i.e. + xdata will be treated as a storage class specifier when parsing 8051 C + code but will be treated as a C identifier when parsing z80 or ATMEL AVR + C code. + +\layout Paragraph* +Generating iCode +\begin_inset LatexCommand \index{iCode} + +\end_inset + + + +\layout Standard +Intermediate code generation. + In this phase the AST is broken down into three-operand form (iCode). + These three operand forms are represented as doubly linked lists. + ICode is the term given to the intermediate form generated by the compiler. + ICode example section shows some examples of iCode generated for some simple + C source functions. + +\layout Paragraph* +Optimizations +\begin_inset LatexCommand \index{Optimizations} + +\end_inset + +. + +\layout Standard +Bulk of the target independent optimizations is performed in this phase. + The optimizations include constant propagation, common sub-expression eliminati +on, loop invariant code movement, strength reduction of loop induction variables + and dead-code elimination. + +\layout Paragraph* +Live range analysis +\begin_inset LatexCommand \index{Live range analysis} + +\end_inset + + + +\layout Standard +During intermediate code generation phase, the compiler assumes the target + machine has infinite number of registers and generates a lot of temporary + variables. + The live range computation determines the lifetime of each of these compiler-ge +nerated temporaries. + A picture speaks a thousand words. + ICode example sections show the live range annotations for each of the + operand. + It is important to note here, each iCode is assigned a number in the order + of its execution in the function. + The live ranges are computed in terms of these numbers. + The from number is the number of the iCode which first defines the operand + and the to number signifies the iCode which uses this operand last. + +\layout Paragraph* +Register Allocation +\begin_inset LatexCommand \index{Register allocation} + +\end_inset + + + +\layout Standard +The register allocation determines the type and number of registers needed + by each operand. + In most MCUs only a few registers can be used for indirect addressing. + In case of 8051 for example the registers R0 & R1 can be used to indirectly + address the internal ram and DPTR to indirectly address the external ram. + The compiler will try to allocate the appropriate register to pointer variables + if it can. + ICode example section shows the operands annotated with the registers assigned + to them. + The compiler will try to keep operands in registers as much as possible; + there are several schemes the compiler uses to do achieve this. + When the compiler runs out of registers the compiler will check to see + if there are any live operands which is not used or defined in the current + basic block being processed, if there are any found then it will push that + operand and use the registers in this block, the operand will then be popped + at the end of the basic block. + + +\layout Standard +There are other MCU specific considerations in this phase. + Some MCUs have an accumulator; very short-lived operands could be assigned + to the accumulator instead of a general-purpose register. + +\layout Paragraph* +Code generation + +\layout Standard +Figure II gives a table of iCode +\begin_inset LatexCommand \index{iCode} + +\end_inset + + operations supported by the compiler. + The code generation involves translating these operations into corresponding + assembly code for the processor. + This sounds overly simple but that is the essence of code generation. + Some of the iCode operations are generated on a MCU specific manner for + example, the z80 port does not use registers to pass parameters so the + SEND and RECV iCode operations will not be generated, and it also does + not support JUMPTABLES. + +\newline + + +\layout Standard + +\size footnotesize +Figure II +\begin_inset Tabular + + + + + + + + +\begin_inset Text + +\layout Standard + +\series bold +iCode +\series default + +\begin_inset LatexCommand \index{iCode} + +\end_inset + + + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Operands + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +Description + +\end_inset + + +\begin_inset Text + +\layout Standard + +\series bold +C Equivalent + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'!' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +NOT operation + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = ! IC_LEFT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'~' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Bitwise complement of + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = ~IC_LEFT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +RRC + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Rotate right with carry + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = (IC_LEFT << 1) | (IC_LEFT >> (sizeof(IC_LEFT)*8-1)); + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +RLC + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Rotate left with carry + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = (IC_LEFT << (sizeof(LC_LEFT)*8-1) ) | (IC_LEFT >> 1); + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +GETHBIT + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Get the highest order bit of IC_LEFT + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = (IC_LEFT >> (sizeof(IC_LEFT)*8 -1)); + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +UNARYMINUS + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Unary minus + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = - IC_LEFT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IPUSH + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Push the operand into stack + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +NONE + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IPOP + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Pop the operand from the stack + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +NONE + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +CALL + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Call the function represented by IC_LEFT + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT(); + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +PCALL + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Call via function pointer + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = (*IC_LEFT)(); + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +RETURN + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Return the value in operand IC_LEFT + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +return IC_LEFT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +LABEL + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LABEL() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Label + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LABEL: + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +GOTO + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LABEL() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Goto label + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +goto IC_LABEL(); + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'+' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Addition + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT + IC_RIGHT + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'-' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Subtraction + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT - IC_RIGHT + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'*' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Multiplication + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT * IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'/' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Division + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT / IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'%' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Modulus + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT % IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'<' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Less than + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT < IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'>' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Greater than + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT > IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +EQ_OP + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Equal to + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT == IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +AND_OP + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Logical and operation + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT && IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +OR_OP + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Logical or operation + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT || IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'^' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Exclusive OR + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT ^ IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'|' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Bitwise OR + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT | IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +BITWISEAND + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Bitwise AND + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT & IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +LEFT_OP + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Left shift + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT << IC_RIGHT + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +RIGHT_OP + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Right shift + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_LEFT >> IC_RIGHT + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +GET_VALUE_ +\newline +AT_ ADDRESS + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Indirect fetch + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = (*IC_LEFT); + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +POINTER_SET + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Indirect set + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +(*IC_RESULT) = IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +'=' + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RIGHT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Assignment + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IFX + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_COND IC_TRUE IC_LABEL + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Conditional jump. + If true label is present then jump to true label if condition is true else + jump to false label if condition is false + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +if (IC_COND) goto IC_TRUE; +\newline \SpecialChar ~ \SpecialChar ~ +Or +\newline +If (!IC_COND) goto IC_FALSE; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +ADDRESS_OF + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Address of + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = &IC_LEFT(); + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +JUMPTABLE + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_JTCOND IC_JTLABELS + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Jump to list of labels depending on the value of JTCOND + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Switch statement + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +CAST + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RIGHT() IC_LEFT() IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +Cast types + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT = (typeof IC_LEFT) IC_RIGHT; + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +SEND + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_LEFT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +This is used for passing parameters in registers; +\newline +move IC_LEFT to the next + available parameter register. + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +None + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\size footnotesize +RECV + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +IC_RESULT() + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +This is used for receiving parameters passed in registers; +\newline +Move the values + in the next parameter register to IC_RESULT + +\end_inset + + +\begin_inset Text + +\layout Standard + +\size footnotesize +None + +\end_inset + + + + +\begin_inset Text + +\layout Standard + +\shape slanted +\size footnotesize +(some more have been added) + +\end_inset + + +\begin_inset Text + +\layout Standard + + +\end_inset + + +\begin_inset Text + +\layout Standard + + +\end_inset + + +\begin_inset Text + +\layout Standard + +\shape slanted +\size footnotesize +see f.e. + +\family typewriter +gen51Code() +\family default + in +\family typewriter +src/mcs51/gen.c + +\end_inset + + + + +\end_inset + + + +\layout Standard +\begin_inset Note +collapsed true + +\layout Standard +In the original article Figure II was announced to be downloadable on +\shape italic +Circuit Cellar +\shape default +'s web site. + ftp://ftp.circuitcellar.com/pub/Circuit_Cellar/2000/121/dutta.ZIP + +\end_inset + + + +\layout Paragraph* +ICode Example +\begin_inset LatexCommand \index{iCode} + +\end_inset + + + +\layout Standard +This section shows some details of iCode. + The example C code does not do anything useful; it is used as an example + to illustrate the intermediate code generated by the compiler. + +\layout Verse + +\family typewriter +1.\SpecialChar ~ +xdata int * p; +\newline +2.\SpecialChar ~ +int gint; +\newline +3.\SpecialChar ~ +/* This function does nothing useful. + It is used +\newline +4.\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +for the purpose of explaining iCode */ +\newline +5.\SpecialChar ~ +short function (data + int *x) +\newline +6.\SpecialChar ~ +{ +\newline +7.\SpecialChar ~ \SpecialChar ~ -SDCDB print command for data at -\newline -;;\SpecialChar ~ \SpecialChar ~ +short i=10; \SpecialChar ~ \SpecialChar ~ +/* dead initialization eliminated */ +\newline +8.\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +short sum=10; + /* dead initialization eliminated */ +\newline +9.\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +short mul; +\newline +10.\SpecialChar ~ \SpecialChar ~ +int j ; +\newline +11.\SpecialChar ~ \SpecialChar ~ +while (*x) *x++ + = *p++; +\newline +12.\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +sum = 0 ; +\newline +13.\SpecialChar ~ \SpecialChar ~ +mul = 0; +\newline +14.\SpecialChar ~ \SpecialChar ~ +/* compiler detects i,j to be induction + variables */ +\newline +15.\SpecialChar ~ \SpecialChar ~ +for (i = 0, j = 10 ; i < 10 ; i++, j +\family default +- +\begin_inset ERT +status Collapsed + +\layout Standard + + +\backslash +/ + +\end_inset + +- +\family typewriter +) { +\newline +16.\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +sum += i; +\newline +17.\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +mul += i * 3; \SpecialChar ~ \SpecialChar ~ +/* this multiplication remains */ +\newline +18.\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +gint += + j * 3;\SpecialChar ~ \SpecialChar ~ +/* this multiplication changed to addition */ +\newline +19.\SpecialChar ~ \SpecialChar ~ +} +\newline +20.\SpecialChar ~ \SpecialChar ~ +return sum+mul; +\newline +21.\SpecialChar ~ +} + +\layout Standard +In addition to the operands each iCode contains information about the filename + and line it corresponds to in the source file. + The first field in the listing should be interpreted as follows: +\newline + +\shape italic +\size footnotesize +Filename(linenumber: iCode Execution sequence number : ICode hash table + key : loop depth of the iCode). +\shape default +\size default + +\newline +Then follows the human readable form of the ICode operation. + Each operand of this triplet form can be of three basic types a) compiler + generated temporary b) user defined variable c) a constant value. + Note that local variables and parameters are replaced by compiler generated + temporaries. + Live ranges +\begin_inset LatexCommand \index{Live range analysis} + +\end_inset + + are computed only for temporaries (i.e. + live ranges are not computed for global variables). + Registers +\begin_inset LatexCommand \index{Register allocation} + +\end_inset + + are allocated for temporaries only. + Operands are formatted in the following manner: +\newline + +\shape italic +\size footnotesize +Operand Name [lr live-from : live-to ] { type information } [ registers + allocated ]. +\shape default +\size default + +\newline +As mentioned earlier the live ranges are computed in terms of the execution + sequence number of the iCodes, for example +\newline +the iTemp0 is live from (i.e. + first defined in iCode with execution sequence number 3, and is last used + in the iCode with sequence number 5). + For induction variables such as iTemp21 the live range computation extends + the lifetime from the start to the end of the loop. +\newline +The register allocator + used the live range information to allocate registers, the same registers + may be used for different temporaries if their live ranges do not overlap, + for example r0 is allocated to both iTemp6 and to iTemp17 since their live + ranges do not overlap. + In addition the allocator also takes into consideration the type and usage + of a temporary, for example itemp6 is a pointer to near space and is used + as to fetch data from (i.e. + used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0). + Some short lived temporaries are allocated to special registers which have + meaning to the code generator e.g. + iTemp13 is allocated to a pseudo register CC which tells the back end that + the temporary is used only for a conditional jump the code generation makes + use of this information to optimize a compare and jump ICode. +\newline +There are several + loop optimizations +\begin_inset LatexCommand \index{Loop optimization} + +\end_inset + + performed by the compiler. + It can detect induction variables iTemp21(i) and iTemp23(j). + Also note the compiler does selective strength reduction +\begin_inset LatexCommand \index{Strength reduction} + +\end_inset + +, i.e. + the multiplication of an induction variable in line 18 (gint = j * 3) is + changed to addition, a new temporary iTemp17 is allocated and assigned + a initial value, a constant 3 is then added for each iteration of the loop. + The compiler does not change the multiplication +\begin_inset LatexCommand \index{Multiplication} + +\end_inset + + in line 17 however since the processor does support an 8 * 8 bit multiplication. +\newline + +Note the dead code elimination +\begin_inset LatexCommand \index{Dead-code elimination} + +\end_inset + + optimization eliminated the dead assignments in line 7 & 8 to I and sum + respectively. +\newline + + +\layout Standard + +\size footnotesize +Sample.c (5:1:0:0) _entry($9) : + +\layout Standard + +\size footnotesize +Sample.c(5:2:1:0) proc _function [lr0:0]{function short} + +\layout Standard + +\size footnotesize +Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv + +\layout Standard + +\size footnotesize +Sample.c(11:4:53:0) preHeaderLbl0($11) : + +\layout Standard + +\size footnotesize +Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near + * int}[r2] + +\layout Standard + +\size footnotesize +Sample.c(11:6:5:1) _whilecontinue_0($1) : + +\layout Standard + +\size footnotesize +Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * + int}[r0]] + +\layout Standard + +\size footnotesize +Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3) + +\layout Standard + +\size footnotesize +Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far + * int} + +\layout Standard + +\size footnotesize +Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 + {short} + +\layout Standard + +\size footnotesize +Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far + * int}[DPTR]] + +\layout Standard + +\size footnotesize +Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int +}[r2 r3] + +\layout Standard + +\size footnotesize +Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near + * int}[r0] + 0x2 {short} + +\layout Standard + +\size footnotesize +Sample.c(11:16:20:1) goto _whilecontinue_0($1) + +\layout Standard + +\size footnotesize +Sample.c(11:17:21:0)_whilebreak_0($3) : + +\layout Standard + +\size footnotesize +Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short} + +\layout Standard + +\size footnotesize +Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short} + +\layout Standard + +\size footnotesize +Sample.c(15:20:54:0)preHeaderLbl1($13) : + +\layout Standard + +\size footnotesize +Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short} + +\layout Standard + +\size footnotesize +Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int} + +\layout Standard + +\size footnotesize +Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int} + +\layout Standard + +\size footnotesize +Sample.c(15:24:26:1)_forcond_0($4) : + +\layout Standard + +\size footnotesize +Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] + < 0xa {short} + +\layout Standard + +\size footnotesize +Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7) + +\layout Standard + +\size footnotesize +Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] + + ITemp21 [lr21:38]{short}[r4] + +\layout Standard + +\size footnotesize +Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] + * 0x3 {short} + +\layout Standard + +\size footnotesize +Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] + + iTemp15 [lr29:30]{short}[r1] + +\layout Standard + +\size footnotesize +Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 + r0]- 0x3 {short} + +\layout Standard + +\size footnotesize +Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{ +int}[r7 r0] + +\layout Standard + +\size footnotesize +Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + + 0x1 {short} + +\layout Standard + +\size footnotesize +Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 + r6]- 0x1 {short} + +\layout Standard + +\size footnotesize +Sample.c(19:38:47:1) goto _forcond_0($4) + +\layout Standard + +\size footnotesize +Sample.c(19:39:48:0)_forbreak_0($7) : + +\layout Standard + +\size footnotesize +Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2] + + ITemp11 [lr19:40]{short}[r3] + +\layout Standard + +\size footnotesize +Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short} + +\layout Standard + +\size footnotesize +Sample.c(20:42:51:0)_return($8) : + +\layout Standard + +\size footnotesize +Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short} +\size default + +\newline + +\newline +Finally the code generated for this function: +\newline + + +\layout Standard + +\size footnotesize +.area DSEG (DATA) + +\layout Standard + +\size footnotesize +_p:: + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +.ds 2 + +\layout Standard + +\size footnotesize +_gint:: + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +.ds 2 + +\layout Standard + +\size footnotesize +; sample.c 5 + +\layout Standard + +\size footnotesize +; ---------------------------------------------- + +\layout Standard + +\size footnotesize +; function function + +\layout Standard + +\size footnotesize +; ---------------------------------------------- + +\layout Standard + +\size footnotesize +_function: + +\layout Standard + +\size footnotesize +; iTemp0 [lr3:5]{_near * int}[r2] = recv + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r2,dpl + +\layout Standard + +\size footnotesize +; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2] + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov ar0,r2 + +\layout Standard + +\size footnotesize +;_whilecontinue_0($1) : + +\layout Standard + +\size footnotesize +00101$: + +\layout Standard + +\size footnotesize +; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]] + +\layout Standard + +\size footnotesize +; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3) + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov ar2,@r0 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +inc r0 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov ar3,@r0 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +dec r0 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ - buffer point -\newline -;; g\SpecialChar ~ +mov a,r2 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +orl a,r3 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +jz 00103$ + +\layout Standard + +\size footnotesize +00114$: + +\layout Standard + +\size footnotesize +; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov dpl,_p + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov dph,(_p + 1) + +\layout Standard + +\size footnotesize +; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov a,#0x02 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +add a,_p + +\layout Standard + +\size footnotesize \SpecialChar ~ - sdcdbsrc-goto-sdcdb\SpecialChar ~ \SpecialChar ~ +mov _p,a + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +clr a + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +addc a,(_p + 1) + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov (_p + 1),a + +\layout Standard + +\size footnotesize +; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]] + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ -Goto the SDCDB output buffer -\newline -;; t\SpecialChar ~ +movx a,@dptr + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r2,a + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +inc dptr + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +movx a,@dptr + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r3,a + +\layout Standard + +\size footnotesize +; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3] + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov @r0,ar2 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +inc r0 + +\layout Standard + +\size footnotesize \SpecialChar ~ - sdcdbsrc-mode\SpecialChar ~ \SpecialChar ~ +mov @r0,ar3 + +\layout Standard + +\size footnotesize +; iTemp6 [lr5:16]{_near * int}[r0] = + +\layout Standard + +\size footnotesize +; iTemp6 [lr5:16]{_near * int}[r0] + + +\layout Standard + +\size footnotesize +; 0x2 {short} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +inc r0 + +\layout Standard + +\size footnotesize +; goto _whilecontinue_0($1) + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +sjmp 00101$ + +\layout Standard + +\size footnotesize +; _whilebreak_0($3) : + +\layout Standard + +\size footnotesize +00103$: + +\layout Standard + +\size footnotesize +; iTemp2 [lr18:40]{short}[r2] := 0x0 {short} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r2,#0x00 + +\layout Standard + +\size footnotesize +; iTemp11 [lr19:40]{short}[r3] := 0x0 {short} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r3,#0x00 + +\layout Standard + +\size footnotesize +; iTemp21 [lr21:38]{short}[r4] := 0x0 {short} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r4,#0x00 + +\layout Standard + +\size footnotesize +; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r5,#0x0A + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ -Toggles Sdcdbsrc mode (turns it off) -\newline -;; -\newline -;; C-c C-f\SpecialChar ~ +mov r6,#0x00 + +\layout Standard + +\size footnotesize +; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r7,#0x1E + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r0,#0x00 + +\layout Standard + +\size footnotesize +; _forcond_0($4) : + +\layout Standard + +\size footnotesize +00104$: + +\layout Standard + +\size footnotesize +; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short} + +\layout Standard + +\size footnotesize +; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7) + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +clr c + +\layout Standard + +\size footnotesize \SpecialChar ~ - sdcdb-finish-from-src\SpecialChar ~ \SpecialChar ~ +mov a,r4 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +xrl a,#0x80 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +subb a,#0x8a + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ -SDCDB finish command -\newline -;; -\newline -;; C-x SPC\SpecialChar ~ +jnc 00107$ + +\layout Standard + +\size footnotesize +00115$: + +\layout Standard + +\size footnotesize +; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] + + +\layout Standard + +\size footnotesize +; iTemp21 [lr21:38]{short}[r4] + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov a,r4 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +add a,r2 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r2,a + +\layout Standard + +\size footnotesize +; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short} + +\layout Standard + +\size footnotesize \SpecialChar ~ - sdcdb-break\SpecialChar ~ \SpecialChar ~ +mov b,#0x03 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov a,r4 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mul ab + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r1,a + +\layout Standard + +\size footnotesize +; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] + + +\layout Standard + +\size footnotesize +; iTemp15 [lr29:30]{short}[r1] + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +add a,r3 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r3,a + +\layout Standard + +\size footnotesize +; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov a,r7 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +add a,#0xfd + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ -Set break for line with point -\newline -;; ESC t\SpecialChar ~ +mov r7,a + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov a,r0 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +addc a,#0xff + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov r0,a + +\layout Standard + +\size footnotesize +; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0] + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov a,r7 + +\layout Standard + +\size footnotesize \SpecialChar ~ - sdcdbsrc-mode\SpecialChar ~ \SpecialChar ~ +add a,_gint + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov _gint,a + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov a,r0 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +addc a,(_gint + 1) + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov (_gint + 1),a + +\layout Standard + +\size footnotesize +; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +inc r4 + +\layout Standard + +\size footnotesize +; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +dec r5 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ -Toggle Sdcdbsrc mode -\newline -;; ESC m\SpecialChar ~ +cjne r5,#0xff,00104$ + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +dec r6 + +\layout Standard + +\size footnotesize +; goto _forcond_0($4) + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +sjmp 00104$ + +\layout Standard + +\size footnotesize +; _forbreak_0($7) : + +\layout Standard + +\size footnotesize +00107$: + +\layout Standard + +\size footnotesize +; ret iTemp24 [lr40:41]{short} + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +mov a,r3 + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +add a,r2 + +\layout Standard + +\size footnotesize \SpecialChar ~ - sdcdbsrc-srcmode\SpecialChar ~ \SpecialChar ~ +mov dpl,a + +\layout Standard + +\size footnotesize +; _return($8) : + +\layout Standard + +\size footnotesize +00108$: + +\layout Standard + +\size footnotesize \SpecialChar ~ \SpecialChar ~ +ret +\newline + + +\layout Section +A few words about basic block successors, predecessors and dominators + +\layout Standard +Successors are basic blocks +\begin_inset LatexCommand \index{Basic blocks} + +\end_inset + + that might execute after this basic block. +\newline +Predecessors are basic blocks + that might execute before reaching this basic block. +\newline +Dominators are basic + blocks that WILL execute before reaching this basic block. +\newline + + +\layout Standard +[basic block 1] + +\layout Standard +if (something) + +\layout Standard \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ +[basic block 2] + +\layout Standard +else + +\layout Standard \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - Toggle list mode -\newline -;; -\family default +[basic block 3] -\newline +\layout Standard +[basic block 4] +\newline -\layout Section -Other Processors -\layout Subsection +\layout Standard +a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3] -The Z80 and gbz80 port \layout Standard +b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3] -SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80. - The port is incomplete - long support is incomplete (mul, div and mod are - unimplimented), and both float and bitfield support is missing. - Apart from that the code generated is correct. \layout Standard +c) domVect of [BB4] = BB1 ... + here we are not sure if BB2 or BB3 was executed but we are SURE that BB1 + was executed. -As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c. - The stack frame is similar to that generated by the IAR Z80 compiler. - IX is used as the base pointer, HL is used as a temporary register, and - BC and DE are available for holding varibles. - IY is currently unusued. - Return values are stored in HL. - One bad side effect of using IX as the base pointer is that a functions - stack frame is limited to 127 bytes - this will be fixed in a later version. -\layout Section +\layout Chapter +Acknowledgments -Support \layout Standard +\begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who} -SDCC has grown to be a large project. - The compiler alone (without the preprocessor, assembler and linker) is - about 40,000 lines of code (blank stripped). - The open source nature of this project is a key to its continued growth - and support. - You gain the benefit and support of many active software developers and - end users. - Is SDCC perfect? No, that's why we need your help. - The developers take pride in fixing reported bugs. - You can help by reporting the bugs and helping other SDCC users. - There are lots of ways to contribute, and we encourage you to take part - in making SDCC a great software package. -\layout Subsection +\end_inset -Reporting Bugs -\layout Standard -Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd -cc@sdcc.sourceforge.net'. - Bugs will be fixed ASAP. - When reporting a bug, it is very useful to include a small test program - which reproduces the problem. - If you can isolate the problem by looking at the generated assembly code, - this can be very helpful. - Compiling your program with the --dumpall option can sometimes be useful - in locating optimization problems. -\layout Section +\newline -Acknowledgments -\layout Standard +\newline -Sandeep Dutta (sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code generator, - Debugger, AVR port -\newline -Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX & ASLINK. - -\newline -John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for 8051 -\newline -Dmitry S. - Obukhov (dso@usa.net) - malloc & serial i/o routines. - -\newline -Daniel Drotos (drdani@mazsola.iit.uni-miskolc.hu) - for his Freeware simulator -\newline -Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience and support. -\newline -Unknown - for the GNU C - preprocessor. -\newline -Michael Hope - The Z80 and Z80GB port, 186 development -\newline -Kevin Vigor - The DS390 port. -\newline -Johan Knol - Lots of fixes and enhancements, DS390/TINI libs. -\newline -Scott Datallo - The PIC port. -\newline - -\newline - -\emph on +\emph on Thanks to all the other volunteer developers who have helped with coding, testing, web-page creation, distribution sets, etc. You know who you are :-) -\emph default +\emph default + +\newline + +\newline + +\emph on +Also thanks to Sourceforge +\begin_inset LatexCommand \url{http://www.sf.net} + +\end_inset + + which has hosted the project since 1999 and donates significant download + bandwidth and probably more than +\begin_inset ERT +status Collapsed + +\layout Standard + +$10^{13}$ -\newline +\end_inset + +CPU cycles per day. +\newline + +\begin_inset Note +collapsed false \layout Standard +more than 10^13 is an estimate: on my Athlon 2800+ it takes about (0.5+6.5+20) + minutes for (configure+make+regression test), and there is (i386, amd64, + alpha, ppc64, (mingw32), sparc, macosx). + + +\end_inset + + +\layout Standard This document was initially written by Sandeep Dutta + \layout Standard +All product names mentioned herein may be trademarks +\begin_inset LatexCommand \index{Trademarks} -All product names mentioned herein may be trademarks of their respective - companies. +\end_inset + + of their respective companies. -\layout Standard +\layout Section* +Alphabetical index +\layout Standard +To avoid confusion, the installation and building options for SDCC itself + (chapter 2) are not part of the index. + +\layout Standard \begin_inset LatexCommand \printindex{} -\end_inset +\end_inset + \the_end