1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
3 <!--Converted with LaTeX2HTML 99.1 release (March 30, 1999)
4 original version by: Nikos Drakos, CBLU, University of Leeds
5 * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6 * with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
10 <TITLE>SDCC Compiler User Guide</TITLE>
11 <META NAME="description" CONTENT="SDCC Compiler User Guide">
12 <META NAME="keywords" CONTENT="SDCCUdoc">
13 <META NAME="resource-type" CONTENT="document">
14 <META NAME="distribution" CONTENT="global">
16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17 <META NAME="Generator" CONTENT="LaTeX2HTML v99.1 release">
18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
20 <LINK REL="STYLESHEET" HREF="SDCCUdoc.css">
25 <!--Navigation Panel-->
26 <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_group"
27 SRC="/home/johan/latex2html/icons.gif/next_group_motif_gr.gif">
28 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
29 SRC="/home/johan/latex2html/icons.gif/up_motif_gr.gif">
30 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
31 SRC="/home/johan/latex2html/icons.gif/previous_motif_gr.gif">
35 <!--End of Navigation Panel-->
41 <H1 ALIGN="CENTER">SDCC Compiler User Guide</H1>
44 <H2><A NAME="SECTION00010000000000000000">
47 <!--Table of Contents-->
50 <LI><A NAME="tex2html124"
51 HREF="SDCCUdoc.html">Contents</A>
52 <LI><A NAME="tex2html125"
53 HREF="SDCCUdoc.html#SECTION00020000000000000000">1. Introduction</A>
55 <LI><A NAME="tex2html126"
56 HREF="SDCCUdoc.html#SECTION00021000000000000000">1.1 About SDCC</A>
57 <LI><A NAME="tex2html127"
58 HREF="SDCCUdoc.html#SECTION00022000000000000000">1.2 Open Source</A>
59 <LI><A NAME="tex2html128"
60 HREF="SDCCUdoc.html#SECTION00023000000000000000">1.3 Typographic conventions</A>
61 <LI><A NAME="tex2html129"
62 HREF="SDCCUdoc.html#SECTION00024000000000000000">1.4 Compatibility with previous versions</A>
63 <LI><A NAME="tex2html130"
64 HREF="SDCCUdoc.html#SECTION00025000000000000000">1.5 System Requirements</A>
65 <LI><A NAME="tex2html131"
66 HREF="SDCCUdoc.html#SECTION00026000000000000000">1.6 Other Resources</A>
67 <LI><A NAME="tex2html132"
68 HREF="SDCCUdoc.html#SECTION00027000000000000000">1.7 Wishes for the future</A>
70 <LI><A NAME="tex2html133"
71 HREF="SDCCUdoc.html#SECTION00030000000000000000">2. Installation</A>
73 <LI><A NAME="tex2html134"
74 HREF="SDCCUdoc.html#SECTION00031000000000000000">2.1 Linux/Unix Installation</A>
75 <LI><A NAME="tex2html135"
76 HREF="SDCCUdoc.html#SECTION00032000000000000000">2.2 Windows Installation</A>
77 <LI><A NAME="tex2html136"
78 HREF="SDCCUdoc.html#SECTION00033000000000000000">2.3 Testing out the SDCC Compiler</A>
79 <LI><A NAME="tex2html137"
80 HREF="SDCCUdoc.html#SECTION00034000000000000000">2.4 Install Trouble-shooting</A>
81 <LI><A NAME="tex2html138"
82 HREF="SDCCUdoc.html#SECTION00035000000000000000">2.5 Additional Information for Windows Users</A>
83 <LI><A NAME="tex2html139"
84 HREF="SDCCUdoc.html#SECTION00036000000000000000">2.6 SDCC on Other Platforms</A>
85 <LI><A NAME="tex2html140"
86 HREF="SDCCUdoc.html#SECTION00037000000000000000">2.7 Advanced Install Options</A>
87 <LI><A NAME="tex2html141"
88 HREF="SDCCUdoc.html#SECTION00038000000000000000">2.8 Components of SDCC</A>
90 <LI><A NAME="tex2html142"
91 HREF="SDCCUdoc.html#SECTION00040000000000000000">3. Using SDCC</A>
93 <LI><A NAME="tex2html143"
94 HREF="SDCCUdoc.html#SECTION00041000000000000000">3.1 Compiling</A>
95 <LI><A NAME="tex2html144"
96 HREF="SDCCUdoc.html#SECTION00042000000000000000">3.2 Command Line Options</A>
97 <LI><A NAME="tex2html145"
98 HREF="SDCCUdoc.html#SECTION00043000000000000000">3.3 MCS51/DS390 Storage Class Language Extensions</A>
99 <LI><A NAME="tex2html146"
100 HREF="SDCCUdoc.html#SECTION00044000000000000000">3.4 Pointers</A>
101 <LI><A NAME="tex2html147"
102 HREF="SDCCUdoc.html#SECTION00045000000000000000">3.5 Parameters & Local Variables</A>
103 <LI><A NAME="tex2html148"
104 HREF="SDCCUdoc.html#SECTION00046000000000000000">3.6 Overlaying</A>
105 <LI><A NAME="tex2html149"
106 HREF="SDCCUdoc.html#SECTION00047000000000000000">3.7 Interrupt Service Routines</A>
107 <LI><A NAME="tex2html150"
108 HREF="SDCCUdoc.html#SECTION00048000000000000000">3.8 Critical Functions</A>
109 <LI><A NAME="tex2html151"
110 HREF="SDCCUdoc.html#SECTION00049000000000000000">3.9 Naked Functions</A>
111 <LI><A NAME="tex2html152"
112 HREF="SDCCUdoc.html#SECTION000410000000000000000">3.10 Functions using private banks</A>
113 <LI><A NAME="tex2html153"
114 HREF="SDCCUdoc.html#SECTION000411000000000000000">3.11 Absolute Addressing</A>
115 <LI><A NAME="tex2html154"
116 HREF="SDCCUdoc.html#SECTION000412000000000000000">3.12 Startup Code</A>
117 <LI><A NAME="tex2html155"
118 HREF="SDCCUdoc.html#SECTION000413000000000000000">3.13 Inline Assembler Code</A>
119 <LI><A NAME="tex2html156"
120 HREF="SDCCUdoc.html#SECTION000414000000000000000">3.14 int(16 bit) and long (32 bit) Support</A>
121 <LI><A NAME="tex2html157"
122 HREF="SDCCUdoc.html#SECTION000415000000000000000">3.15 Floating Point Support</A>
123 <LI><A NAME="tex2html158"
124 HREF="SDCCUdoc.html#SECTION000416000000000000000">3.16 MCS51 Memory Models</A>
125 <LI><A NAME="tex2html159"
126 HREF="SDCCUdoc.html#SECTION000417000000000000000">3.17 DS390 Memory Models</A>
127 <LI><A NAME="tex2html160"
128 HREF="SDCCUdoc.html#SECTION000418000000000000000">3.18 Defines Created by the Compiler</A>
130 <LI><A NAME="tex2html161"
131 HREF="SDCCUdoc.html#SECTION00050000000000000000">4. SDCC Technical Data</A>
133 <LI><A NAME="tex2html162"
134 HREF="SDCCUdoc.html#SECTION00051000000000000000">4.1 Optimizations</A>
135 <LI><A NAME="tex2html163"
136 HREF="SDCCUdoc.html#SECTION00052000000000000000">4.2 Pragmas</A>
137 <LI><A NAME="tex2html164"
138 HREF="SDCCUdoc.html#SECTION00053000000000000000">4.3 <pending: this is messy and incomplete> Library Routines</A>
139 <LI><A NAME="tex2html165"
140 HREF="SDCCUdoc.html#SECTION00054000000000000000">4.4 Interfacing with Assembly Routines</A>
141 <LI><A NAME="tex2html166"
142 HREF="SDCCUdoc.html#SECTION00055000000000000000">4.5 External Stack</A>
143 <LI><A NAME="tex2html167"
144 HREF="SDCCUdoc.html#SECTION00056000000000000000">4.6 ANSI-Compliance</A>
145 <LI><A NAME="tex2html168"
146 HREF="SDCCUdoc.html#SECTION00057000000000000000">4.7 Cyclomatic Complexity</A>
148 <LI><A NAME="tex2html169"
149 HREF="SDCCUdoc.html#SECTION00060000000000000000">5. TIPS</A>
151 <LI><A NAME="tex2html170"
152 HREF="SDCCUdoc.html#SECTION00061000000000000000">5.1 Notes on MCS51 memory layout</A>
154 <LI><A NAME="tex2html171"
155 HREF="SDCCUdoc.html#SECTION00070000000000000000">6. Retargetting for other MCUs.</A>
156 <LI><A NAME="tex2html172"
157 HREF="SDCCUdoc.html#SECTION00080000000000000000">7. SDCDB - Source Level Debugger</A>
159 <LI><A NAME="tex2html173"
160 HREF="SDCCUdoc.html#SECTION00081000000000000000">7.1 Compiling for Debugging</A>
161 <LI><A NAME="tex2html174"
162 HREF="SDCCUdoc.html#SECTION00082000000000000000">7.2 How the Debugger Works</A>
163 <LI><A NAME="tex2html175"
164 HREF="SDCCUdoc.html#SECTION00083000000000000000">7.3 Starting the Debugger</A>
165 <LI><A NAME="tex2html176"
166 HREF="SDCCUdoc.html#SECTION00084000000000000000">7.4 Command Line Options.</A>
167 <LI><A NAME="tex2html177"
168 HREF="SDCCUdoc.html#SECTION00085000000000000000">7.5 Debugger Commands.</A>
169 <LI><A NAME="tex2html178"
170 HREF="SDCCUdoc.html#SECTION00086000000000000000">7.6 Interfacing with XEmacs.</A>
172 <LI><A NAME="tex2html179"
173 HREF="SDCCUdoc.html#SECTION00090000000000000000">8. Other Processors</A>
175 <LI><A NAME="tex2html180"
176 HREF="SDCCUdoc.html#SECTION00091000000000000000">8.1 The Z80 and gbz80 port</A>
178 <LI><A NAME="tex2html181"
179 HREF="SDCCUdoc.html#SECTION000100000000000000000">9. Support</A>
181 <LI><A NAME="tex2html182"
182 HREF="SDCCUdoc.html#SECTION000101000000000000000">9.1 Reporting Bugs</A>
184 <LI><A NAME="tex2html183"
185 HREF="SDCCUdoc.html#SECTION000110000000000000000">10. Acknowledgments</A>
186 <LI><A NAME="tex2html184"
187 HREF="SDCCUdoc.html#SECTION000120000000000000000">Index</A>
189 <!--End of Table of Contents-->
193 <H1><A NAME="SECTION00020000000000000000">
199 <H2><A NAME="SECTION00021000000000000000">
205 <B>SDCC</B> is a Freeware, retargettable, optimizing ANSI-C compiler
206 by <B>Sandeep Dutta</B> designed for 8 bit Microprocessors. The
207 current version targets Intel MCS51 based Microprocessors(8051,8052,
208 etc), Zilog Z80 based MCUs, and the Dallas DS80C390 variant. It can
209 be retargetted for other microprocessors, support for PIC, AVR and
210 186 is under development. The entire source code for the compiler
211 is distributed under GPL. SDCC uses ASXXXX & ASLINK, a Freeware,
212 retargettable assembler & linker. SDCC has extensive language extensions
213 suitable for utilizing various microcontrollers and underlying hardware
218 In addition to the MCU specific optimizations SDCC also does a host
219 of standard optimizations like:
224 <LI>global sub expression elimination, </LI>
225 <LI>loop optimizations (loop invariant, strength reduction of induction
226 variables and loop reversing), </LI>
227 <LI>constant folding & propagation, </LI>
228 <LI>copy propagation, </LI>
229 <LI>dead code elimination </LI>
230 <LI>jumptables for <I>switch</I> statements.</LI>
232 For the back-end SDCC uses a global register allocation scheme which
233 should be well suited for other 8 bit MCUs.
237 The peep hole optimizer uses a rule based substitution mechanism which
242 Supported data-types are:
247 <LI>char (8 bits, 1 byte), </LI>
248 <LI>short and int (16 bits, 2 bytes), </LI>
249 <LI>long (32 bit, 4 bytes)</LI>
250 <LI>float (4 byte IEEE). </LI>
252 The compiler also allows <I>inline assembler code</I> to be embedded
253 anywhere in a function. In addition, routines developed in assembly
258 SDCC also provides an option (-cyclomatic) to report the relative
259 complexity of a function. These functions can then be further optimized,
260 or hand coded in assembly if needed.
264 SDCC also comes with a companion source level debugger SDCDB, the
265 debugger currently uses ucSim a freeware simulator for 8051 and other
270 The latest version can be downloaded from http://sdcc.sourceforge.net/<B>.</B>
274 <H2><A NAME="SECTION00022000000000000000">
279 All packages used in this compiler system are <I>opensource</I> and
280 <I>freeware</I>; source code for all the sub-packages (asxxxx assembler/linker,
281 pre-processor) is distributed with the package. This documentation
282 is maintained using a freeware word processor (LYX).
285 This program is free software; you can redistribute it and/or modify
286 it under the terms of the GNU General Public License as published
287 by the Free Software Foundation; either version 2, or (at your option)
288 any later version. This program is distributed in the hope that it
289 will be useful, but WITHOUT ANY WARRANTY; without even the implied
290 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
291 the GNU General Public License for more details. You should have received
292 a copy of the GNU General Public License along with this program;
293 if not, write to the Free Software Foundation, 59 Temple Place - Suite
294 330, Boston, MA 02111-1307, USA. In other words, you are welcome to
295 use, share and improve this program. You are forbidden to forbid anyone
296 else to use, share and improve what you give them. Help stamp out
301 <H2><A NAME="SECTION00023000000000000000">
302 1.3 Typographic conventions</A>
306 Throughout this manual, we will use the following convention. Commands
307 you have to type in are printed in <I><B>"sans
308 serif"</B></I><I>.</I> Code samples are printed in <TT>typewriter
309 font.</TT> Interesting items and new terms are printed in <I>italicised
314 <H2><A NAME="SECTION00024000000000000000">
315 1.4 Compatibility with previous versions</A>
319 This version has numerous bug fixes compared with the previous version.
320 But we also introduced some incompatibilities with older versions.
321 Not just for the fun of it, but to make the compiler more stable,
322 efficient and ANSI compliant.
328 <LI>short is now equivalent to int (16 bits), it used to be equivalent
329 to char (8 bits)</LI>
330 <LI>the default directory where include, library and documention files
331 are stored is no in /usr/local/share</LI>
332 <LI>char type parameters to vararg functions are casted to int unless
333 explicitly casted, e.g.:
335 <TT> char a=3;</TT>
337 <TT> printf ("%d %c\n",
340 will push a as an int and as a char resp.</LI>
341 <LI>option -regextend has been removed</LI>
342 <LI>option -noreparms has been removed</LI>
344 <I><pending: more incompatibilities?></I>
348 <H2><A NAME="SECTION00025000000000000000">
349 1.5 System Requirements</A>
353 What do you need before you start installation of SDCC? A computer,
354 and a desire to compute. The preferred method of installation is to
355 compile SDCC from source using GNU gcc and make. For Windows some
356 pre-compiled binary distributions are available for your convenience.
357 You should have some experience with command line tools and compiler
362 <H2><A NAME="SECTION00026000000000000000">
363 1.6 Other Resources</A>
367 The SDCC home page at http://sdcc.sourceforge.net/ is a great
368 place to find distribution sets. You can also find links to the user
369 mailing lists that offer help or discuss SDCC with other SDCC users.
370 Web links to other SDCC related sites can also be found here. This
371 document can be found in the DOC directory of the source package as
372 a text or HTML file. Some of the other tools (simulator and assembler)
373 included with SDCC contain their own documentation and can be found
374 in the source distribution. If you want the latest unreleased software,
375 the complete source package is available directly by anonymous CVS
376 on cvs.sdcc.sourceforge.net.
380 <H2><A NAME="SECTION00027000000000000000">
381 1.7 Wishes for the future</A>
385 There are (and always will be) some things that could be done. Here
386 are some I can think of:
391 <I><B>sdcc -c -model-large -o large _atoi.c</B></I> (where large
392 could be a different basename or a directory)
397 <TT>char KernelFunction3(char p) at 0x340;</TT>
400 If you can think of some more, please send them to the list.
404 <I><pending: And then of course a proper index-table<A NAME="67"></A>></I>
408 <H1><A NAME="SECTION00030000000000000000">
414 <H2><A NAME="SECTION00031000000000000000">
415 2.1 Linux/Unix Installation</A>
421 <LI>Download the source package, it will be named something like sdcc-2.x.x.tgz.</LI>
422 <LI>Bring up a command line terminal, such as xterm.</LI>
423 <LI>Unpack the file using a command like: <I><B>"tar
424 -xzf sdcc-2.x.x.tgz</B></I>", this will create a sub-directory
425 called sdcc with all of the sources.</LI>
426 <LI>Change directory into the main SDCC directory, for example type: <I><B>"cd
427 sdcc</B></I><I>".</I></LI>
428 <LI>Type <I><B>"./configure</B></I>". This configures
429 the package for compilation on your system.</LI>
430 <LI>Type <I><B>"make</B></I>". All of the source
431 packages will compile, this can take a while.</LI>
432 <LI>Type <I><B>"make install"</B></I> as root. This
433 copies the binary executables, the include files, the libraries and
434 the documentation to the install directories.</LI>
439 <H2><A NAME="SECTION00032000000000000000">
440 2.2 Windows Installation</A>
445 <I><pending: is this complete? where is borland, mingw></I>
448 For installation under Windows you first need to pick between a pre-compiled
449 binary package, or installing the source package along with the Cygwin
450 package. The binary package is the quickest to install, while the
451 Cygwin package includes all of the open source power tools used to
452 compile the complete SDCC source package in the Windows environment.
453 If you are not familiar with the Unix command line environment, you
454 may want to read the section on additional information for Windows
455 users prior to your initial installation.
459 <H3><A NAME="SECTION00032100000000000000">
460 2.2.1 Windows Install Using a Binary Package</A>
466 <LI>Download the binary package and unpack it using your favorite unpacking
467 tool (gunzip, WinZip, etc). This should unpack to a group of sub-directories.
468 An example directory structure after unpacking is: c:\usr\local\bin
469 for the executables, c:\usr\local\share\sdcc\include
470 and c:\usr\local\share\sdcc\lib
471 for the include and libraries.</LI>
472 <LI>Adjust your environment PATH to include the location of the bin directory.
473 For example, make a setsdcc.bat file with the following: set PATH=c:\usr\local\bin;%PATH%</LI>
474 <LI>When you compile with sdcc, you may need to specify the location of
475 the lib and include folders. For example, sdcc -I c:\usr\local\share\sdcc\include
476 -L c:\usr\local\share\sdcc\lib\small
482 <H3><A NAME="SECTION00032200000000000000">
483 2.2.2 Windows Install Using Cygwin</A>
489 <LI>Download and install the cygwin package from the redhat site http://sources.redhat.com/cygwin/.
490 Currently, this involved downloading a small install program which
491 then automates downloading and installing selected parts of the package
492 (a large 80M byte sized dowload for the whole thing). </LI>
493 <LI>Bring up a Unix/Bash command line terminal from the Cygwin menu.</LI>
494 <LI>Follow the instructions in the preceding Linux/Unix installation section.</LI>
499 <H2><A NAME="SECTION00033000000000000000">
500 2.3 Testing out the SDCC Compiler</A>
504 The first thing you should do after installing your SDCC compiler
505 is to see if it runs. Type <I><B>"sdcc -version"</B></I>
506 at the prompt, and the program should run and tell you the version.
507 If it doesn't run, or gives a message about not finding sdcc program,
508 then you need to check over your installation. Make sure that the
509 sdcc bin directory is in your executable search path defined by the
510 PATH environment setting (see the Trouble-shooting section for suggestions).
511 Make sure that the sdcc program is in the bin folder, if not perhaps
512 something did not install correctly.
516 SDCC binaries are commonly installed in a directory arrangement like
521 <TABLE CELLPADDING=3 BORDER="1">
522 <TR><TD ALIGN="LEFT">/usr/local/bin</TD>
523 <TD ALIGN="LEFT">Holds executables(sdcc, s51, aslink, ...)</TD>
525 <TR><TD ALIGN="LEFT">/usr/local/share/sdcc/lib</TD>
526 <TD ALIGN="LEFT">Holds common C libraries</TD>
528 <TR><TD ALIGN="LEFT">/usr/local/share/sdcc/include</TD>
529 <TD ALIGN="LEFT">Holds common C header files</TD>
535 Make sure the compiler works on a very simple example. Type in the
536 following test.c program using your favorite editor:
539 <TT>int test(int t) {</TT>
541 <TT> return t+3;</TT>
546 Compile this using the following command: <I><B>"sdcc
547 -c test.c".</B></I> If all goes well, the compiler will generate
548 a test.asm and test.rel file. Congratulations, you've just compiled
549 your first program with SDCC. We used the -c option to tell SDCC not
550 to link the generated code, just to keep things simple for this step.
554 The next step is to try it with the linker. Type in <I><B>"sdcc
555 test.c</B></I>". If all goes well the compiler will link with the
556 libraries and produce a test.ihx output file. If this step fails (no
557 test.ihx, and the linker generates warnings), then the problem is
558 most likely that sdcc cannot find the /usr/local/share/sdcc/lib directory
559 (see the Install trouble-shooting section for suggestions).
563 The final test is to ensure sdcc can use the standard header files
564 and libraries. Edit test.c and change it to the following:
568 #include <string.h>
572 <TT>char str1[10];</TT>
574 <TT> strcpy(str1, "testing");</TT>
579 Compile this by typing <I><B>"sdcc test.c"</B></I>.
580 This should generate a test.ihx output file, and it should give no
581 warnings such as not finding the string.h file. If it cannot find
582 the string.h file, then the problem is that sdcc cannot find the /usr/local/share/sdcc/include
583 directory (see the Install trouble-shooting section for suggestions).
587 <H2><A NAME="SECTION00034000000000000000">
588 2.4 Install Trouble-shooting</A>
593 <H3><A NAME="SECTION00034100000000000000">
594 2.4.1 SDCC cannot find libraries or header files.</A>
598 The default installation assumes the libraries and header files are
599 located at ``/usr/local/share/sdcc/lib'' and ``/usr/local/share/sdcc/include''.
600 An alternative is to specify these locations as compiler options like
601 this: <I><B>"sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include test.c"</B></I>.
605 <H3><A NAME="SECTION00034200000000000000">
606 2.4.2 SDCC does not compile correctly.</A>
610 A thing to try is starting from scratch by unpacking the .tgz source
611 package again in an empty directory. Confure it again and build like:
615 <I><B>make 2SPMamp;>1 | tee make.log</B></I>
619 After this you can review the make.log file to locate the problem.
620 Or a relevant part of this be attached to an email that could be helpful
621 when requesting help from the mailing list.
625 <H3><A NAME="SECTION00034300000000000000">
626 2.4.3 What the ''./configure'' does</A>
630 The ''./configure'' command is a script that analyzes your system
631 and performs some configuration to ensure the source package compiles
632 on your system. It will take a few minutes to run, and will compile
633 a few tests to determine what compiler features are installed.
637 <H3><A NAME="SECTION00034400000000000000">
638 2.4.4 What the ''make'' does.</A>
642 This runs the GNU make tool, which automatically compiles all the
643 source packages into the final installed binary executables.
647 <H3><A NAME="SECTION00034500000000000000">
648 2.4.5 What the ''make install'' command does.</A>
652 This will install the compiler, other executables and libraries in
653 to the appropriate system directories. The default is to copy the
654 executables to /usr/local/bin and the libraries and header files to
655 /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
659 <H2><A NAME="SECTION00035000000000000000">
660 2.5 Additional Information for Windows Users</A>
665 <I><pending: is this up to date?></I>
668 The standard method of installing on a Unix system involves compiling
669 the source package. This is easily done under Unix, but under Windows
670 it can be a more difficult process. The Cygwin is a large package
671 to download, and the compilation runs considerably slower under Windows
672 due to the overhead of the Cygwin tool set. An alternative is to install
673 a pre-compiled Windows binary package. There are various trade-offs
674 between each of these methods.
677 The Cygwin package allows a Windows user to run a Unix command line
678 interface (bash shell) and also implements a Unix like file system
679 on top of Windows. Included are many of the famous GNU software development
680 tools which can augment the SDCC compiler.This is great if you have
681 some experience with Unix command line tools and file system conventions,
682 if not you may find it easier to start by installing a binary Windows
683 package. The binary packages work with the Windows file system conventions.
687 <H3><A NAME="SECTION00035100000000000000">
688 2.5.1 Getting started with Cygwin</A>
692 SDCC is typically distributed as a tarred/gzipped file (.tgz). This
693 is a packed file similar to a .zip file. Cygwin includes the tools
694 you will need to unpack the SDCC distribution (tar and gzip). To unpack
695 it, simply follow the instructions under the Linux/Unix install section.
696 Before you do this you need to learn how to start a cygwin shell and
697 some of the basic commands used to move files, change directory, run
698 commands and so on. The change directory command is <I><B>``cd''</B></I>,
699 the move command is <I><B>``mv''</B></I>. To print the current
700 working directory, type <I><B>``pwd''</B></I>. To make a directory,
701 use <I><B>``mkdir''</B></I>.
704 There are some basic differences between Unix and Windows file systems
705 you should understand. When you type in directory paths, Unix and
706 the Cygwin bash prompt uses forward slashes '/' between directories
707 while Windows traditionally uses '\' backward slashes.
708 So when you work at the Cygwin bash prompt, you will need to use the
709 forward '/' slashes. Unix does not have a concept of drive letters,
710 such as ``c:``, instead all files systems attach and appear
715 <H3><A NAME="SECTION00035200000000000000">
716 2.5.2 Running SDCC as Native Compiled Executables</A>
720 If you use the pre-compiled binaries, the install directories for
721 the libraries and header files may need to be specified on the sdcc
722 command line like this: <I><B>"sdcc -L c:\usr\local\sdcc\lib\small
723 -I c:\usr\local\sdcc\include
724 test.c"</B></I> if you are running outside of a Unix bash shell.
727 If you have successfully installed and compiled SDCC with the Cygwin
728 package, it is possible to compile into native .exe files by using
729 the additional makefiles included for this purpose. For example, with
730 the Borland 32-bit compiler you would run <I><B>"make
731 -f Makefile.bcc"</B></I>. A command line version of the Borland
732 32-bit compiler can be downloaded from the Inprise web site.
736 <H2><A NAME="SECTION00036000000000000000">
737 2.6 SDCC on Other Platforms</A>
743 <LI><B>FreeBSD and other non-GNU Unixes</B> - Make sure the GNU make
744 is installed as the default make tool.</LI>
745 <LI>SDCC has been ported to run under a variety of operating systems and
746 processors. If you can run GNU GCC/make then chances are good SDCC
747 can be compiled and run on your system.</LI>
752 <H2><A NAME="SECTION00037000000000000000">
753 2.7 Advanced Install Options</A>
757 The ``configure'' command has several options. The most commonly
758 used option is -prefix=<directory name>, where <directory name> is
759 the final location for the sdcc executables and libraries, (default
760 location is /usr/local). The installation process will create the
761 following directory structure under the <directory name> specified
762 (if they do not already exist).
766 bin/ - binary exectables (add to PATH environment variable)
770 bin/share/sdcc/include/ - include header files
774 bin/share/sdcc/lib/small/ - Object & library files for small model
777 bin/share/sdcc/lib/large/ - Object & library files for large model
780 bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390 library
784 The command <I><B>''./configure -prefix=/usr/local''</B></I>
785 will configure the compiler to be installed in directory /usr/local.
789 <H2><A NAME="SECTION00038000000000000000">
790 2.8 Components of SDCC</A>
794 SDCC is not just a compiler, but a collection of tools by various
795 developers. These include linkers, assemblers, simulators and other
796 components. Here is a summary of some of the components. Note that
797 the included simulator and assembler have separate documentation which
798 you can find in the source package in their respective directories.
799 As SDCC grows to include support for other processors, other packages
800 from various developers are included and may have their own sets of
805 You might want to look at the files which are installed in <installdir>.
806 At the time of this writing, we find the following programs:
810 In <installdir>/bin:
815 <LI>sdcc - The compiler.</LI>
816 <LI>sdcpp - The C preprocessor.</LI>
817 <LI>asx8051 - The assembler for 8051 type processors.</LI>
818 <LI>as-z80<B>,</B> as-gbz80 - The Z80 and GameBoy Z80 assemblers.</LI>
819 <LI>aslink -The linker for 8051 type processors.</LI>
820 <LI>link-z80<B>,</B> link-gbz80 - The Z80 and GameBoy Z80 linkers.</LI>
821 <LI>s51 - The ucSim 8051 simulator.</LI>
822 <LI>sdcdb - The source debugger.</LI>
823 <LI>packihx - A tool to pack Intel hex files.</LI>
825 In <installdir>/share/sdcc/include
830 <LI>the include files</LI>
832 In <installdir>/share/sdcc/lib
837 <LI>the sources of the runtime library and the subdirs small large and
838 ds390 with the precompiled relocatables.</LI>
840 In <installdir>/share/sdcc/doc
845 <LI>the documentation</LI>
847 As development for other processors proceeds, this list will expand
848 to include executables to support processors like AVR, PIC, etc.
852 <H3><A NAME="SECTION00038100000000000000">
853 2.8.1 sdcc - The Compiler</A>
857 This is the actual compiler, it in turn uses the c-preprocessor and
858 invokes the assembler and linkage editor.
862 <H3><A NAME="SECTION00038200000000000000">
863 2.8.2 sdcpp (C-Preprocessor)</A>
867 The preprocessor is a modified version of the GNU preprocessor. The
868 C preprocessor is used to pull in #include sources, process #ifdef
869 statements, #defines and so on.
873 <H3><A NAME="SECTION00038300000000000000">
874 2.8.3 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 (The Assemblers
875 and Linkage Editors)</A>
879 This is retargettable assembler & linkage editor, it was developed
880 by Alan Baldwin. John Hartman created the version for 8051, and I
881 (Sandeep) have made some enhancements and bug fixes for it to work
882 properly with the SDCC.
886 <H3><A NAME="SECTION00038400000000000000">
887 2.8.4 s51 - Simulator</A>
891 S51 is a freeware, opensource simulator developed by Daniel Drotos
892 ( mailto:drdani@mazsola.iit.uni-miskolc.hu). The simulator is
893 built as part of the build process. For more information visit Daniel's
894 website at: http://mazsola.iit.uni-miskolc.hu/ drdani/embedded/s51
899 <H3><A NAME="SECTION00038500000000000000">
900 2.8.5 sdcdb - Source Level Debugger</A>
904 Sdcdb is the companion source level debugger. The current version
905 of the debugger uses Daniel's Simulator S51, but can be easily changed
906 to use other simulators.
910 <H1><A NAME="SECTION00040000000000000000">
916 <H2><A NAME="SECTION00041000000000000000">
922 <H3><A NAME="SECTION00041100000000000000">
923 3.1.1 Single Source File Projects</A>
927 For single source file 8051 projects the process is very simple. Compile
928 your programs with the following command <I><B>"sdcc
929 sourcefile.c".</B></I> This will compile, assemble and link your
930 source file. Output files are as follows
934 sourcefile.asm - Assembler source file created by the compiler
936 sourcefile.lst - Assembler listing file created by the Assembler
938 sourcefile.rst - Assembler listing file updated with linkedit information,
939 created by linkage editor
941 sourcefile.sym - symbol listing for the sourcefile, created by the
944 sourcefile.rel - Object file created by the assembler, input to Linkage
947 sourcefile.map - The memory map for the load module, created by the
950 sourcefile.ihx - The load module in Intel hex format (you can select
951 the Motorola S19 format with -out-fmt-s19)
953 sourcefile.cdb - An optional file (with -debug) containing debug
959 <H3><A NAME="SECTION00041200000000000000">
960 3.1.2 Projects with Multiple Source Files</A>
964 SDCC can compile only ONE file at a time. Let us for example assume
965 that you have a project containing the following files:
969 foo1.c (contains some functions)
971 foo2.c (contains some more functions)
973 foomain.c (contains more functions and the function main)
977 The first two files will need to be compiled separately with the commands:
982 <I><B>sdcc -c foo1.c</B></I>
984 <I><B>sdcc -c foo2.c</B></I>
988 Then compile the source file containing the <I>main()</I> function
989 and link the files together with the following command:
993 <I><B>sdcc foomain.c foo1.rel foo2.rel</B></I>
997 Alternatively, <I>foomain.c</I> can be separately compiled as well:
1000 <I><B>sdcc -c foomain.c</B></I>
1002 <I><B>sdcc foomain.rel foo1.rel foo2.rel</B></I>
1005 The file containing the <I>main()</I> function <SMALL>MUST</SMALL>
1006 be the <SMALL>FIRST</SMALL> file specified in the command line, since the
1007 linkage editor processes file in the order they are presented to it.
1011 <H3><A NAME="SECTION00041300000000000000">
1012 3.1.3 Projects with Additional Libraries</A>
1016 Some reusable routines may be compiled into a library, see the documentation
1017 for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
1018 for how to create a <I>.lib</I> library file. Libraries created in
1019 this manner can be included in the command line. Make sure you include
1020 the -L <library-path> option to tell the linker where to look for
1021 these files if they are not in the current directory. Here is an example,
1022 assuming you have the source file <I>foomain.c</I> and a library <I>foolib.lib</I>
1023 in the directory <I>mylib</I> (if that is not the same as your current
1028 <I><B>sdcc foomain.c foolib.lib -L mylib</B></I>
1031 Note here that <I>mylib</I> must be an absolute path name.
1035 The most efficient way to use libraries is to keep seperate modules
1036 in seperate source files. The lib file now should name all the modules.rel
1037 files. For an example see the standard library file <I>libsdcc.lib</I>
1038 in the directory <installdir>/share/lib/small.
1042 <H2><A NAME="SECTION00042000000000000000">
1043 3.2 Command Line Options</A>
1048 <H3><A NAME="SECTION00042100000000000000">
1049 3.2.1 Processor Selection Options</A>
1055 <LI>[<B>-mmcs51</B>]Generate code for the MCS51 (8051) family of processors.
1056 This is the default processor target.</LI>
1057 <LI>[<B>-mds390</B>]Generate code for the DS80C390 processor.</LI>
1058 <LI>[<B>-mz80</B>]Generate code for the Z80 family of processors.</LI>
1059 <LI>[<B>-mgbz80</B>]Generate code for the GameBoy Z80 processor.</LI>
1060 <LI>[<B>-mavr</B>]Generate code for the Atmel AVR processor(In development,
1062 <LI>[<B>-mpic14</B>]Generate code for the PIC 14-bit processors(In development,
1064 <LI>[<B>-mtlcs900h</B>]Generate code for the Toshiba TLCS-900H processor(In
1065 development, not complete).</LI>
1069 <H3><A NAME="SECTION00042200000000000000">
1070 3.2.2 Preprocessor Options</A>
1076 <LI>[<B>-I<path></B>]The additional location where the pre processor
1077 will look for <..h> or ``..h'' files.</LI>
1078 <LI>[<B>-D<macro[=value]></B>]Command line definition of macros.
1079 Passed to the pre processor.</LI>
1080 <LI>[<B>-M</B>]Tell the preprocessor to output a rule suitable for make
1081 describing the dependencies of each object file. For each source file,
1082 the preprocessor outputs one make-rule whose target is the object
1083 file name for that source file and whose dependencies are all the
1084 files `#include'd in it. This rule may be a single line or may be
1085 continued with `\'-newline if it is long. The list
1086 of rules is printed on standard output instead of the preprocessed
1087 C program. `-M' implies `-E'.</LI>
1088 <LI>[<B>-C</B>]Tell the preprocessor not to discard comments. Used with
1089 the `-E' option.</LI>
1090 <LI>[<B>-MM</B>]Like `-M' but the output mentions only the user header
1091 files included with `#include ``file"'. System header
1092 files included with `#include <file>' are omitted.</LI>
1093 <LI>[<B>-Aquestion(answer)</B>]Assert the answer answer for question,
1094 in case it is tested with a preprocessor conditional such as `#if
1095 #question(answer)'. `-A-' disables the standard assertions that normally
1096 describe the target machine.</LI>
1097 <LI>[<B>-Aquestion</B>](answer) Assert the answer answer for question,
1098 in case it is tested with a preprocessor conditional such as `#if
1099 #question(answer)'. `-A-' disables the standard assertions that normally
1100 describe the target machine.</LI>
1101 <LI>[<B>-Umacro</B>]Undefine macro macro. `-U' options are evaluated
1102 after all `-D' options, but before any `-include' and `-imacros' options.</LI>
1103 <LI>[<B>-dM</B>]Tell the preprocessor to output only a list of the macro
1104 definitions that are in effect at the end of preprocessing. Used with
1105 the `-E' option.</LI>
1106 <LI>[<B>-dD</B>]Tell the preprocessor to pass all macro definitions
1107 into the output, in their proper sequence in the rest of the output.</LI>
1108 <LI>[<B>-dN</B>]Like `-dD' except that the macro arguments and contents
1109 are omitted. Only `#define name' is included in the output.</LI>
1113 <H3><A NAME="SECTION00042300000000000000">
1114 3.2.3 Linker Options</A>
1120 <LI>[<B>-L -lib-path</B>]<absolute path to additional libraries> This
1121 option is passed to the linkage editor's additional libraries search
1122 path. The path name must be absolute. Additional library files may
1123 be specified in the command line. See section Compiling programs for
1125 <LI>[<B>-xram-loc</B><Value>]The start location of the external ram,
1126 default value is 0. The value entered can be in Hexadecimal or Decimal
1127 format, e.g.: -xram-loc 0x8000 or -xram-loc 32768.</LI>
1128 <LI>[<B>-code-loc</B><Value>]The start location of the code segment,
1129 default value 0. Note when this option is used the interrupt vector
1130 table is also relocated to the given address. The value entered can
1131 be in Hexadecimal or Decimal format, e.g.: -code-loc 0x8000 or -code-loc
1133 <LI>[<B>-stack-loc</B><Value>]The initial value of the stack pointer.
1134 The default value of the stack pointer is 0x07 if only register bank
1135 0 is used, if other register banks are used then the stack pointer
1136 is initialized to the location above the highest register bank used.
1137 eg. if register banks 1 & 2 are used the stack pointer will default
1138 to location 0x18. The value entered can be in Hexadecimal or Decimal
1139 format, eg. -stack-loc 0x20 or -stack-loc 32. If all four register
1140 banks are used the stack will be placed after the data segment (equivalent
1141 to -stack-after-data)</LI>
1142 <LI>[<B>-stack-after-data</B>]This option will cause the stack to be
1143 located in the internal ram after the data segment.</LI>
1144 <LI>[<B>-data-loc</B><Value>]The start location of the internal ram
1145 data segment, the default value is 0x30.The value entered can be in
1146 Hexadecimal or Decimal format, eg. -data-loc 0x20 or -data-loc 32.</LI>
1147 <LI>[<B>-idata-loc</B><Value>]The start location of the indirectly
1148 addressable internal ram, default value is 0x80. The value entered
1149 can be in Hexadecimal or Decimal format, eg. -idata-loc 0x88 or -idata-loc
1151 <LI>[<B>-out-fmt-ihx</B>]The linker output (final object code) is in
1152 Intel Hex format. (This is the default option).</LI>
1153 <LI>[<B>-out-fmt-s19</B>]The linker output (final object code) is in
1154 Motorola S19 format.</LI>
1158 <H3><A NAME="SECTION00042400000000000000">
1159 3.2.4 MCS51 Options</A>
1165 <LI>[<B>-model-large</B>]Generate code for Large model programs see
1166 section Memory Models for more details. If this option is used all
1167 source files in the project should be compiled with this option. In
1168 addition the standard library routines are compiled with small model,
1169 they will need to be recompiled.</LI>
1170 <LI>[<B>-model-small</B>]Generate code for Small Model programs see
1171 section Memory Models for more details. This is the default model.</LI>
1175 <H3><A NAME="SECTION00042500000000000000">
1176 3.2.5 DS390 Options</A>
1182 <LI>[<B>-model-flat24</B>]Generate 24-bit flat mode code. This is the
1183 one and only that the ds390 code generator supports right now and
1184 is default when using <I>-mds390</I>. See section Memory Models for
1186 <LI>[<B>-stack-10bit</B>]Generate code for the 10 bit stack mode of
1187 the Dallas DS80C390 part. This is the one and only that the ds390
1188 code generator supports right now and is default when using <I>-mds390</I>.
1189 In this mode, the stack is located in the lower 1K of the internal
1190 RAM, which is mapped to 0x400000. Note that the support is incomplete,
1191 since it still uses a single byte as the stack pointer. This means
1192 that only the lower 256 bytes of the potential 1K stack space will
1193 actually be used. However, this does allow you to reclaim the precious
1194 256 bytes of low RAM for use for the DATA and IDATA segments. The
1195 compiler will not generate any code to put the processor into 10 bit
1196 stack mode. It is important to ensure that the processor is in this
1197 mode before calling any re-entrant functions compiled with this option.
1198 In principle, this should work with the <I>-stack-auto</I> option,
1199 but that has not been tested. It is incompatible with the <I>-xstack</I>
1200 option. It also only makes sense if the processor is in 24 bit contiguous
1201 addressing mode (see the <I>-model-flat24 option</I>).</LI>
1205 <H3><A NAME="SECTION00042600000000000000">
1206 3.2.6 Optimization Options</A>
1212 <LI>[<B>-nogcse</B>]Will not do global subexpression elimination, this
1213 option may be used when the compiler creates undesirably large stack/data
1214 spaces to store compiler temporaries. A warning message will be generated
1215 when this happens and the compiler will indicate the number of extra
1216 bytes it allocated. It recommended that this option NOT be used, #pragma NOGCSE
1217 can be used to turn off global subexpression elimination for a given
1219 <LI>[<B>-noinvariant</B>]Will not do loop invariant optimizations,
1220 this may be turned off for reasons explained for the previous option.
1221 For more details of loop optimizations performed see section Loop
1222 Invariants.It recommended that this option NOT be used, #pragma NOINVARIANT
1223 can be used to turn off invariant optimizations for a given function
1225 <LI>[<B>-noinduction</B>]Will not do loop induction optimizations,
1226 see section strength reduction for more details.It is recommended
1227 that this option is NOT used, #pragma NOINDUCTION can be used to
1228 turn off induction optimizations for a given function only.</LI>
1229 <LI>[<B>-nojtbound</B>] Will not generate boundary condition check
1230 when switch statements are implemented using jump-tables. See section
1231 Switch Statements for more details. It is recommended that this option
1232 is NOT used, #pragma NOJTBOUND can be used to turn off boundary
1233 checking for jump tables for a given function only.</LI>
1234 <LI>[<B>-noloopreverse</B>]Will not do loop reversal optimization.</LI>
1238 <H3><A NAME="SECTION00042700000000000000">
1239 3.2.7 Other Options</A>
1245 <LI>[<B>-c -compile-only</B>]will compile and assemble the source,
1246 but will not call the linkage editor.</LI>
1247 <LI>[<B>-E</B>]Run only the C preprocessor. Preprocess all the C source
1248 files specified and output the results to standard output.</LI>
1249 <LI>[<B>-stack-auto</B>]All functions in the source file will be compiled
1250 as <I>reentrant</I>, i.e. the parameters and local variables will
1251 be allocated on the stack. see section Parameters and Local Variables
1252 for more details. If this option is used all source files in the project
1253 should be compiled with this option. </LI>
1254 <LI>[<B>-xstack</B>]Uses a pseudo stack in the first 256 bytes in the
1255 external ram for allocating variables and passing parameters. See
1256 section on external stack for more details.</LI>
1257 <LI>[<B>-callee-saves</B>]<B>function1[,function2][,function3]....</B>
1258 The compiler by default uses a caller saves convention for register
1259 saving across function calls, however this can cause unneccessary
1260 register pushing & popping when calling small functions from larger
1261 functions. This option can be used to switch the register saving convention
1262 for the function names specified. The compiler will not save registers
1263 when calling these functions, no extra code will be generated at the
1264 entry & exit for these functions to save & restore the registers
1265 used by these functions, this can SUBSTANTIALLY reduce code & improve
1266 run time performance of the generated code. In the future the compiler
1267 (with interprocedural analysis) will be able to determine the appropriate
1268 scheme to use for each function call. DO NOT use this option for built-in
1269 functions such as _muluint..., if this option is used for a library
1270 function the appropriate library function needs to be recompiled with
1271 the same option. If the project consists of multiple source files
1272 then all the source file should be compiled with the same -callee-saves
1273 option string. Also see #pragma CALLEE-SAVES.</LI>
1274 <LI>[<B>-debug</B>]When this option is used the compiler will generate
1275 debug information, that can be used with the SDCDB. The debug information
1276 is collected in a file with .cdb extension. For more information see
1277 documentation for SDCDB.</LI>
1278 <LI>[<B><I>-regextend</I></B>] <I>This option is obsolete and isn't
1279 supported anymore.</I></LI>
1280 <LI>[<B><I>-noregparms</I></B>]<I>This option is obsolete and isn't
1281 supported anymore.</I></LI>
1282 <LI>[<B>-peep-file</B><filename>]This option can be used to use additional
1283 rules to be used by the peep hole optimizer. See section Peep Hole
1284 optimizations for details on how to write these rules.</LI>
1285 <LI>[<B>-S</B>]Stop after the stage of compilation proper; do not assemble.
1286 The output is an assembler code file for the input file specified.</LI>
1287 <LI>[<B>-Wa_asmOption[,asmOption]</B>...]Pass the asmOption to
1289 <LI>[<B>-Wl_linkOption[,linkOption]</B>...]Pass the linkOption
1291 <LI>[<B>-int-long-reent</B>] Integer (16 bit) and long (32 bit) libraries
1292 have been compiled as reentrant. Note by default these libraries are
1293 compiled as non-reentrant. See section Installation for more details.</LI>
1294 <LI>[<B>-cyclomatic</B>]This option will cause the compiler to generate
1295 an information message for each function in the source file. The message
1296 contains some <I>important</I> information about the function. The
1297 number of edges and nodes the compiler detected in the control flow
1298 graph of the function, and most importantly the <I>cyclomatic complexity</I>
1299 see section on Cyclomatic Complexity for more details.</LI>
1300 <LI>[<B>-float-reent</B>] Floating point library is compiled as reentrant.See
1301 section Installation for more details.</LI>
1302 <LI>[<B>-nooverlay</B>] The compiler will not overlay parameters and
1303 local variables of any function, see section Parameters and local
1304 variables for more details.</LI>
1305 <LI>[<B>-main-return</B>]This option can be used when the code generated
1306 is called by a monitor program. The compiler will generate a 'ret'
1307 upon return from the 'main' function. The default option is to lock
1308 up i.e. generate a 'ljmp '.</LI>
1309 <LI>[<B>-no-peep</B>] Disable peep-hole optimization.</LI>
1310 <LI>[<B>-peep-asm</B>] Pass the inline assembler code through the peep
1311 hole optimizer. This can cause unexpected changes to inline assembler
1312 code, please go through the peephole optimizer rules defined in the
1313 source file tree '<target>/peeph.def' before using this option.</LI>
1314 <LI>[<B>-iram-size</B><Value>]Causes the linker to check if the interal
1315 ram usage is within limits of the given value.</LI>
1316 <LI>[<B>-nostdincl</B>]This will prevent the compiler from passing
1317 on the default include path to the preprocessor.</LI>
1318 <LI>[<B>-nostdlib</B>]This will prevent the compiler from passing on
1319 the default library path to the linker.</LI>
1320 <LI>[<B>-verbose</B>]Shows the various actions the compiler is performing.</LI>
1321 <LI>[<B>-V</B>]Shows the actual commands the compiler is executing.</LI>
1325 <H3><A NAME="SECTION00042800000000000000">
1326 3.2.8 Intermediate Dump Options</A>
1330 The following options are provided for the purpose of retargetting
1331 and debugging the compiler. These provided a means to dump the intermediate
1332 code (iCode) generated by the compiler in human readable form at various
1333 stages of the compilation process.
1338 <LI>[<B>-dumpraw</B>]This option will cause the compiler to dump the
1339 intermediate code into a file of named <I><source filename>.dumpraw</I>
1340 just after the intermediate code has been generated for a function,
1341 i.e. before any optimizations are done. The basic blocks at this stage
1342 ordered in the depth first number, so they may not be in sequence
1344 <LI>[<B>-dumpgcse</B>]Will create a dump of iCode's, after global subexpression
1345 elimination, into a file named <I><source filename>.dumpgcse.</I></LI>
1346 <LI>[<B>-dumpdeadcode</B>]Will create a dump of iCode's, after deadcode
1347 elimination, into a file named <I><source filename>.dumpdeadcode.</I></LI>
1348 <LI>[<B>-dumploop</B>]Will create a dump of iCode's, after loop optimizations,
1349 into a file named <I><source filename>.dumploop.</I></LI>
1350 <LI>[<B>-dumprange</B>]Will create a dump of iCode's, after live range
1351 analysis, into a file named <I><source filename>.dumprange.</I></LI>
1352 <LI>[<B>-dumlrange</B>]Will dump the life ranges for all symbols.</LI>
1353 <LI>[<B>-dumpregassign</B>]Will create a dump of iCode's, after register
1354 assignment, into a file named <I><source filename>.dumprassgn.</I></LI>
1355 <LI>[<B>-dumplrange</B>]Will create a dump of the live ranges of iTemp's</LI>
1356 <LI>[<B>-dumpall</B>]Will cause all the above mentioned dumps to be
1361 <H2><A NAME="SECTION00043000000000000000">
1362 3.3 MCS51/DS390 Storage Class Language Extensions</A>
1366 In addition to the ANSI storage classes SDCC allows the following
1367 MCS51 specific storage classes.
1371 <H3><A NAME="SECTION00043100000000000000">
1376 Variables declared with this storage class will be placed in the extern
1377 RAM. This is the <B>default</B> storage class for Large Memory model,
1382 <TT>xdata unsigned char xduc;</TT>
1386 <H3><A NAME="SECTION00043200000000000000">
1391 This is the <B>default</B> storage class for Small Memory model.
1392 Variables declared with this storage class will be allocated in the
1397 <TT>data int iramdata;</TT>
1401 <H3><A NAME="SECTION00043300000000000000">
1406 Variables declared with this storage class will be allocated into
1407 the indirectly addressable portion of the internal ram of a 8051,
1412 <TT>idata int idi;</TT>
1416 <H3><A NAME="SECTION00043400000000000000">
1421 This is a data-type and a storage class specifier. When a variable
1422 is declared as a bit, it is allocated into the bit addressable memory
1431 <H3><A NAME="SECTION00043500000000000000">
1432 3.3.5 sfr / sbit</A>
1436 Like the bit keyword, <I>sfr / sbit</I> signifies both a data-type
1437 and storage class, they are used to describe the special function
1438 registers and special bit variables of a 8051, eg:
1442 <TT>sfr at 0x80 P0; /* special function register P0 at location
1445 <TT>sbit at 0xd7 CY; /* CY (Carry Flag) */</TT>
1449 <H2><A NAME="SECTION00044000000000000000">
1454 SDCC allows (via language extensions) pointers to explicitly point
1455 to any of the memory spaces of the 8051. In addition to the explicit
1456 pointers, the compiler also allows a <I>_generic</I> class of pointers
1457 which can be used to point to any of the memory spaces.
1461 Pointer declaration examples:
1465 <TT>/* pointer physically in xternal ram pointing to object
1466 in internal ram */ </TT>
1468 <TT>data unsigned char * xdata p;</TT>
1471 <TT>/* pointer physically in code rom pointing to data in xdata
1472 space */ </TT>
1474 <TT>xdata unsigned char * code p;</TT>
1477 <TT>/* pointer physically in code space pointing to data in
1478 code space */ </TT>
1480 <TT>code unsigned char * code p;</TT>
1483 <TT>/* the folowing is a generic pointer physically located
1484 in xdata space */</TT>
1486 <TT>char * xdata p;</TT>
1490 Well you get the idea.
1494 <I>For compatibility with the previous version of the compiler,
1495 the following syntax for pointer declaration is still supported but
1496 will disappear int the near future. </I>
1499 <TT><I>unsigned char _xdata *ucxdp; /* pointer to data
1500 in external ram */ </I></TT>
1502 <TT><I>unsigned char _data *ucdp ; /* pointer to data
1503 in internal ram */ </I></TT>
1505 <TT><I>unsigned char _code *uccp ; /* pointer to data
1506 in R/O code space */</I></TT>
1508 <TT><I>unsigned char _idata *uccp; /* pointer to upper
1509 128 bytes of ram */</I></TT>
1513 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
1514 <I>generic</I> pointers. These type of pointers can also to be explicitly
1519 <TT>unsigned char _generic *ucgp;</TT>
1523 The highest order byte of the <I>generic</I> pointers contains the
1524 data space information. Assembler support routines are called whenever
1525 data is stored or retrieved using <I>generic</I> pointers. These are
1526 useful for developing reusable library routines. Explicitly specifying
1527 the pointer type will generate the most efficient code. Pointers declared
1528 using a mixture of OLD and NEW style could have unpredictable results.
1532 <H2><A NAME="SECTION00045000000000000000">
1533 3.5 Parameters & Local Variables</A>
1537 Automatic (local) variables and parameters to functions can either
1538 be placed on the stack or in data-space. The default action of the
1539 compiler is to place these variables in the internal RAM (for small
1540 model) or external RAM (for Large model). This in fact makes them
1541 <I>static</I> so by default functions are non-reentrant.
1544 They can be placed on the stack either by using the <I>-stack-auto</I>
1545 compiler option or by using the <I>reentrant</I> keyword in the function
1550 <TT>unsigned char foo(char i) reentrant </TT>
1560 Since stack space on 8051 is limited, the <I>reentrant</I> keyword
1561 or the <I>-stack-auto</I> option should be used sparingly. Note that
1562 the reentrant keyword just means that the parameters & local variables
1563 will be allocated to the stack, it <I>does not</I> mean that the function
1564 is register bank independent.
1568 Local variables can be assigned storage classes and absolute addresses,
1573 <TT>unsigned char foo() {</TT>
1575 <TT> xdata unsigned char i;</TT>
1577 <TT> bit bvar;</TT>
1579 <TT> data at 0x31 unsiged char j;</TT>
1581 <TT> ... </TT>
1586 In the above example the variable <I>i</I> will be allocated in the
1587 external ram, <I>bvar</I> in bit addressable space and <I>j</I> in
1588 internal ram. When compiled with <I>-stack-auto</I> or when a function
1589 is declared as <I>reentrant</I> this can only be done for static variables.
1592 Parameters however are not allowed any storage class, (storage classes
1593 for parameters will be ignored), their allocation is governed by the
1594 memory model in use, and the reentrancy options.
1598 <H2><A NAME="SECTION00046000000000000000">
1603 For non-reentrant functions SDCC will try to reduce internal ram space
1604 usage by overlaying parameters and local variables of a function (if
1605 possible). Parameters and local variables of a function will be allocated
1606 to an overlayable segment if the function has <I>no other function
1607 calls and the function is non-reentrant and the memory model is small.</I>
1608 If an explicit storage class is specified for a local variable, it
1609 will NOT be overlayed.
1612 Note that the compiler (not the linkage editor) makes the decision
1613 for overlaying the data items. Functions that are called from an interrupt
1614 service routine should be preceded by a #pragma NOOVERLAY if they
1618 Also note that the compiler does not do any processing of inline assembler
1619 code, so the compiler might incorrectly assign local variables and
1620 parameters of a function into the overlay segment if the inline assembler
1621 code calls other c-functions that might use the overlay. In that case
1622 the #pragma NOOVERLAY should be used.
1625 Parameters and Local variables of functions that contain 16 or 32
1626 bit multiplication or division will NOT be overlayed since these are
1627 implemented using external functions, e.g.:
1631 <TT>#pragma SAVE </TT>
1633 <TT>#pragma NOOVERLAY </TT>
1635 <TT>void set_error(unsigned char errcd) </TT>
1639 <TT> P3 = errcd;</TT>
1643 <TT>#pragma RESTORE </TT>
1646 <TT>void some_isr () interrupt 2 using 1 </TT>
1650 <TT> ...</TT>
1652 <TT> set_error(10);</TT>
1654 <TT> ... </TT>
1659 In the above example the parameter <I>errcd</I> for the function <I>set_error</I>
1660 would be assigned to the overlayable segment if the #pragma NOOVERLAY
1661 was not present, this could cause unpredictable runtime behavior when
1662 called from an ISR. The #pragma NOOVERLAY ensures that the parameters
1663 and local variables for the function are NOT overlayed.
1667 <H2><A NAME="SECTION00047000000000000000">
1668 3.7 Interrupt Service Routines</A>
1672 SDCC allows interrupt service routines to be coded in C, with some
1677 <TT>void timer_isr (void) interrupt 2 using 1 </TT>
1686 The number following the <I>interrupt</I> keyword is the interrupt
1687 number this routine will service. The compiler will insert a call
1688 to this routine in the interrupt vector table for the interrupt number
1689 specified. The <I>using</I> keyword is used to tell the compiler to
1690 use the specified register bank (8051 specific) when generating code
1691 for this function. Note that when some function is called from an
1692 interrupt service routine it should be preceded by a #pragma NOOVERLAY
1693 if it is not reentrant. A special note here, int (16 bit) and long
1694 (32 bit) integer division, multiplication & modulus operations are
1695 implemented using external support routines developed in ANSI-C, if
1696 an interrupt service routine needs to do any of these operations then
1697 the support routines (as mentioned in a following section) will have
1698 to be recompiled using the <I>-stack-auto</I> option and the source
1699 file will need to be compiled using the <I>-int-long-ren</I>t compiler
1703 If you have multiple source files in your project, interrupt service
1704 routines can be present in any of them, but a prototype of the isr
1705 MUST be present or included in the file that contains the function
1709 Interrupt Numbers and the corresponding address & descriptions for
1710 the Standard 8051 are listed below. SDCC will automatically adjust
1711 the interrupt vector table to the maximum interrupt number specified.
1716 <TABLE CELLPADDING=3 BORDER="1">
1717 <TR><TD ALIGN="CENTER">Interrupt #</TD>
1718 <TD ALIGN="CENTER">Description</TD>
1719 <TD ALIGN="CENTER">Vector Address</TD>
1721 <TR><TD ALIGN="CENTER">0</TD>
1722 <TD ALIGN="CENTER">External 0</TD>
1723 <TD ALIGN="CENTER">0x0003</TD>
1725 <TR><TD ALIGN="CENTER">1</TD>
1726 <TD ALIGN="CENTER">Timer 0</TD>
1727 <TD ALIGN="CENTER">0x000B</TD>
1729 <TR><TD ALIGN="CENTER">2</TD>
1730 <TD ALIGN="CENTER">External 1</TD>
1731 <TD ALIGN="CENTER">0x0013</TD>
1733 <TR><TD ALIGN="CENTER">3</TD>
1734 <TD ALIGN="CENTER">Timer 1</TD>
1735 <TD ALIGN="CENTER">0x001B</TD>
1737 <TR><TD ALIGN="CENTER">4</TD>
1738 <TD ALIGN="CENTER">Serial</TD>
1739 <TD ALIGN="CENTER">0x0023</TD>
1745 If the interrupt service routine is defined without <I>using</I> a
1746 register bank or with register bank 0 (using 0), the compiler will
1747 save the registers used by itself on the stack upon entry and restore
1748 them at exit, however if such an interrupt service routine calls another
1749 function then the entire register bank will be saved on the stack.
1750 This scheme may be advantageous for small interrupt service routines
1751 which have low register usage.
1754 If the interrupt service routine is defined to be using a specific
1755 register bank then only <I>a, b & dptr</I> are save and restored,
1756 if such an interrupt service routine calls another function (using
1757 another register bank) then the entire register bank of the called
1758 function will be saved on the stack. This scheme is recommended for
1759 larger interrupt service routines.
1762 Calling other functions from an interrupt service routine is not recommended,
1763 avoid it if possible.
1767 Also see the _naked modifier.
1771 <H2><A NAME="SECTION00048000000000000000">
1772 3.8 Critical Functions</A>
1776 A special keyword may be associated with a function declaring it as
1777 <I>critical</I>. SDCC will generate code to disable all interrupts
1778 upon entry to a critical function and enable them back before returning.
1779 Note that nesting critical functions may cause unpredictable results.
1783 <TT>int foo () critical </TT>
1795 The critical attribute maybe used with other attributes like <I>reentrant.</I>
1799 <H2><A NAME="SECTION00049000000000000000">
1800 3.9 Naked Functions</A>
1804 A special keyword may be associated with a function declaring it as
1805 <I>_naked.</I> The <I>_naked</I> function modifier attribute prevents
1806 the compiler from generating prologue and epilogue code for that function.
1807 This means that the user is entirely responsible for such things as
1808 saving any registers that may need to be preserved, selecting the
1809 proper register bank, generating the <I>return</I> instruction at
1810 the end, etc. Practically, this means that the contents of the function
1811 must be written in inline assembler. This is particularly useful for
1812 interrupt functions, which can have a large (and often unnecessary)
1813 prologue/epilogue. For example, compare the code generated by these
1818 <TT>data unsigned char counter;</TT>
1820 <TT>void simpleInterrupt(void) interrupt 1</TT>
1824 <TT> counter++;</TT>
1829 <TT>void nakedInterrupt(void) interrupt 2 _naked</TT>
1833 <TT> _asm</TT>
1835 <TT> inc _counter</TT>
1837 <TT> reti ; MUST explicitly include ret in _naked
1838 function.</TT>
1840 <TT> _endasm;</TT>
1846 For an 8051 target, the generated simpleInterrupt looks like:
1850 <TT>_simpleIterrupt:</TT>
1852 <TT> push acc</TT>
1854 <TT> push b</TT>
1856 <TT> push dpl</TT>
1858 <TT> push dph</TT>
1860 <TT> push psw</TT>
1862 <TT> mov psw,#0x00</TT>
1864 <TT> inc _counter</TT>
1866 <TT> pop psw</TT>
1868 <TT> pop dph</TT>
1870 <TT> pop dpl</TT>
1872 <TT> pop b</TT>
1874 <TT> pop acc</TT>
1876 <TT> reti</TT>
1880 whereas nakedInterrupt looks like:
1884 <TT>_nakedInterrupt:</TT>
1886 <TT> inc _counter</TT>
1888 <TT> reti ; MUST explicitly include ret(i) in _naked
1893 While there is nothing preventing you from writing C code inside a
1894 _naked function, there are many ways to shoot yourself in the foot
1895 doing this, and is is recommended that you stick to inline assembler.
1899 <H2><A NAME="SECTION000410000000000000000">
1900 3.10 Functions using private banks</A>
1904 The <I>using</I> attribute (which tells the compiler to use a register
1905 bank other than the default bank zero) should only be applied to <I>interrupt</I>
1906 functions (see note 1 below). This will in most circumstances make
1907 the generated ISR code more efficient since it will not have to save
1908 registers on the stack.
1911 The <I>using</I> attribute will have no effect on the generated code
1912 for a <I>non-interrupt</I> function (but may occasionally be useful
1913 anyway<A NAME="tex2html1"
1914 HREF="#foot530"><SUP>1</SUP></A>).
1916 <I>(pending: I don't think this has been done yet)</I>
1919 An <I>interrupt</I> function using a non-zero bank will assume that
1920 it can trash that register bank, and will not save it. Since high-priority
1921 interrupts can interrupt low-priority ones on the 8051 and friends,
1922 this means that if a high-priority ISR <I>using</I> a particular bank
1923 occurs while processing a low-priority ISR <I>using</I> the same bank,
1924 terrible and bad things can happen. To prevent this, no single register
1925 bank should be <I>used</I> by both a high priority and a low priority
1926 ISR. This is probably most easily done by having all high priority
1927 ISRs use one bank and all low priority ISRs use another. If you have
1928 an ISR which can change priority at runtime, you're on your own: I
1929 suggest using the default bank zero and taking the small performance
1933 It is most efficient if your ISR calls no other functions. If your
1934 ISR must call other functions, it is most efficient if those functions
1935 use the same bank as the ISR (see note 1 below); the next best is
1936 if the called functions use bank zero. It is very inefficient to call
1937 a function using a different, non-zero bank from an ISR.
1941 <H2><A NAME="SECTION000411000000000000000">
1942 3.11 Absolute Addressing</A>
1946 Data items can be assigned an absolute address with the <I>at <address></I>
1947 keyword, in addition to a storage class, e.g.:
1951 <TT>xdata at 0x8000 unsigned char PORTA_8255 ;</TT>
1955 In the above example the PORTA_8255 will be allocated to the location
1956 0x8000 of the external ram. Note that this feature is provided to
1957 give the programmer access to <I>memory mapped</I> devices attached
1958 to the controller. The compiler does not actually reserve any space
1959 for variables declared in this way (they are implemented with an equate
1960 in the assembler). Thus it is left to the programmer to make sure
1961 there are no overlaps with other variables that are declared without
1962 the absolute address. The assembler listing file (.lst) and the linker
1963 output files (.rst) and (.map) are a good places to look for such
1968 Absolute address can be specified for variables in all storage classes,
1973 <TT>bit at 0x02 bvar;</TT>
1976 The above example will allocate the variable at offset 0x02 in the
1977 bit-addressable space. There is no real advantage to assigning absolute
1978 addresses to variables in this manner, unless you want strict control
1979 over all the variables allocated.
1983 <H2><A NAME="SECTION000412000000000000000">
1984 3.12 Startup Code</A>
1988 The compiler inserts a call to the C routine <I>_sdcc__external__startup()</I>
1989 at the start of the CODE area. This routine is in the runtime library.
1990 By default this routine returns 0, if this routine returns a non-zero
1991 value, the static & global variable initialization will be skipped
1992 and the function main will be invoked Other wise static & global
1993 variables will be initialized before the function main is invoked.
1994 You could add a <I>_sdcc__external__startup()</I> routine to
1995 your program to override the default if you need to setup hardware
1996 or perform some other critical operation prior to static & global
1997 variable initialization.
2001 <H2><A NAME="SECTION000413000000000000000">
2002 3.13 Inline Assembler Code</A>
2006 SDCC allows the use of in-line assembler with a few restriction as
2007 regards labels. All labels defined within inline assembler code <I>has
2008 to be</I> of the form <I>nnnnn$</I> where nnnn is a number less than
2009 100 (which implies a limit of utmost 100 inline assembler labels <I>per
2010 function</I>). It is strongly recommended that each assembly
2011 instruction (including labels) be placed in a separate line (as the
2012 example shows). When the <I>-peep-asm</I> command line option is
2013 used, the inline assembler code will be passed through the peephole
2014 optimizer. This might cause some unexpected changes in the inline
2015 assembler code. Please go throught the peephole optimizer rules defined
2016 in file <I>SDCCpeeph.def</I> carefully before using this option.
2020 <TT>_asm </TT>
2022 <TT> mov b,#10 </TT>
2024 <TT>00001$: </TT>
2026 <TT> djnz b,00001$ </TT>
2032 The inline assembler code can contain any valid code understood by
2033 the assembler, this includes any assembler directives and comment
2034 lines. The compiler does not do any validation of the code within
2035 the <TT>_asm ... _endasm;</TT> keyword pair.
2039 Inline assembler code cannot reference any C-Labels, however it can
2040 reference labels defined by the inline assembler, e.g.:
2044 <TT>foo() { </TT>
2046 <TT> /* some c code */ </TT>
2048 <TT> _asm </TT>
2050 <TT> ; some assembler code </TT>
2052 <TT> ljmp $0003 </TT>
2054 <TT> _endasm; </TT>
2056 <TT> /* some more c code */ </TT>
2058 <TT>clabel: /* inline assembler cannot reference this label
2061 <TT> _asm</TT>
2063 <TT> $0003: ;label (can be reference by inline assembler
2066 <TT> _endasm ; </TT>
2068 <TT> /* some more c code */</TT>
2073 In other words inline assembly code can access labels defined in inline
2074 assembly within the scope of the funtion.
2077 The same goes the other way, ie. labels defines in inline assembly
2078 CANNOT be accessed by C statements.
2082 <H2><A NAME="SECTION000414000000000000000">
2083 3.14 int(16 bit) and long (32 bit) Support</A>
2087 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
2088 multiplication and modulus operations are implemented by support routines.
2089 These support routines are all developed in ANSI-C to facilitate porting
2090 to other MCUs, although some model specific assembler optimations
2091 are used. The following files contain the described routine, all of
2092 them can be found in <installdir>/share/sdcc/lib.
2096 <I><pending: tabularise this></I>
2100 _mulsint.c - signed 16 bit multiplication (calls _muluint)
2102 _muluint.c - unsigned 16 bit multiplication
2104 _divsint.c - signed 16 bit division (calls _divuint)
2106 _divuint.c - unsigned 16 bit division
2108 _modsint.c - signed 16 bit modulus (call _moduint)
2110 _moduint.c - unsigned 16 bit modulus
2112 _mulslong.c - signed 32 bit multiplication (calls _mululong)
2114 _mululong.c - unsigned32 bit multiplication
2116 _divslong.c - signed 32 division (calls _divulong)
2118 _divulong.c - unsigned 32 division
2120 _modslong.c - signed 32 bit modulus (calls _modulong)
2122 _modulong.c - unsigned 32 bit modulus
2126 Since they are compiled as <I>non-reentrant</I>, interrupt service
2127 routines should not do any of the above operations. If this is unavoidable
2128 then the above routines will need to be compiled with the <I>-stack-auto</I>
2129 option, after which the source program will have to be compiled with
2130 <I>-int-long-rent</I> option.
2134 <H2><A NAME="SECTION000415000000000000000">
2135 3.15 Floating Point Support</A>
2139 SDCC supports IEEE (single precision 4bytes) floating point numbers.The
2140 floating point support routines are derived from gcc's floatlib.c
2141 and consists of the following routines:
2145 <I><pending: tabularise this></I>
2149 _fsadd.c - add floating point numbers
2151 _fssub.c - subtract floating point numbers
2153 _fsdiv.c - divide floating point numbers
2155 _fsmul.c - multiply floating point numbers
2157 _fs2uchar.c - convert floating point to unsigned char
2159 _fs2char.c - convert floating point to signed char
2161 _fs2uint.c - convert floating point to unsigned int
2163 _fs2int.c - convert floating point to signed int
2165 _fs2ulong.c - convert floating point to unsigned long
2167 _fs2long.c - convert floating point to signed long
2169 _uchar2fs.c - convert unsigned char to floating point
2171 _char2fs.c - convert char to floating point number
2173 _uint2fs.c - convert unsigned int to floating point
2175 _int2fs.c - convert int to floating point numbers
2177 _ulong2fs.c - convert unsigned long to floating point number
2179 _long2fs.c - convert long to floating point number
2183 Note if all these routines are used simultaneously the data space
2184 might overflow. For serious floating point usage it is strongly recommended
2185 that the large model be used.
2189 <H2><A NAME="SECTION000416000000000000000">
2190 3.16 MCS51 Memory Models</A>
2194 SDCC allows two memory models for MCS51 code, small and large. Modules
2195 compiled with different memory models should <I>never</I> be combined
2196 together or the results would be unpredictable. The library routines
2197 supplied with the compiler are compiled as both small and large. The
2198 compiled library modules are contained in seperate directories as
2199 small and large so that you can link to either set.
2202 When the large model is used all variables declared without a storage
2203 class will be allocated into the external ram, this includes all parameters
2204 and local variables (for non-reentrant functions). When the small
2205 model is used variables without storage class are allocated in the
2209 Judicious usage of the processor specific storage classes and the
2210 'reentrant' function type will yield much more efficient code, than
2211 using the large model. Several optimizations are disabled when the
2212 program is compiled using the large model, it is therefore strongly
2213 recommdended that the small model be used unless absolutely required.
2217 <H2><A NAME="SECTION000417000000000000000">
2218 3.17 DS390 Memory Models</A>
2222 The only model supported is Flat 24. This generates code for the 24
2223 bit contiguous addressing mode of the Dallas DS80C390 part. In this
2224 mode, up to four meg of external RAM or code space can be directly
2225 addressed. See the data sheets at www.dalsemi.com for further information
2230 In older versions of the compiler, this option was used with the MCS51
2231 code generator (<I>-mmcs51</I>). Now, however, the '390 has it's own
2232 code generator, selected by the <I>-mds390</I> switch.
2236 Note that the compiler does not generate any code to place the processor
2237 into 24 bitmode (although <I>tinibios</I> in the ds390 libraries will
2238 do that for you). If you don't use <I>tinibios</I>, the boot loader
2239 or similar code must ensure that the processor is in 24 bit contiguous
2240 addressing mode before calling the SDCC startup code.
2244 Like the <I>-model-large</I> option, variables will by default be
2245 placed into the XDATA segment.
2249 Segments may be placed anywhere in the 4 meg address space using the
2250 usual -*-loc options. Note that if any segments are located above
2251 64K, the -r flag must be passed to the linker to generate the proper
2252 segment relocations, and the Intel HEX output format must be used.
2253 The -r flag can be passed to the linker by using the option <I>-Wl-r</I>
2254 on the sdcc command line. However, currently the linker can not handle
2255 code segments > 64k.
2259 <H2><A NAME="SECTION000418000000000000000">
2260 3.18 Defines Created by the Compiler</A>
2264 The compiler creates the following #defines.
2269 <LI>SDCC - this Symbol is always defined.</LI>
2270 <LI>SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model
2271 used (e.g.: -mds390)</LI>
2272 <LI>__mcs51 or __ds390 or __z80, etc - depending on the model used
2274 <LI>SDCC_STACK_AUTO - this symbol is defined when <I>-stack-auto</I>
2275 option is used.</LI>
2276 <LI>SDCC_MODEL_SMALL - when <I>-model-small</I> is used.</LI>
2277 <LI>SDCC_MODEL_LARGE - when <I>-model-large</I> is used.</LI>
2278 <LI>SDCC_USE_XSTACK - when <I>-xstack</I> option is used.</LI>
2279 <LI>SDCC_STACK_TENBIT - when <I>-mds390</I> is used</LI>
2280 <LI>SDCC_MODEL_FLAT24 - when <I>-mds390</I> is used</LI>
2285 <H1><A NAME="SECTION00050000000000000000">
2286 4. SDCC Technical Data</A>
2291 <H2><A NAME="SECTION00051000000000000000">
2292 4.1 Optimizations</A>
2296 SDCC performs a host of standard optimizations in addition to some
2297 MCU specific optimizations.
2301 <H3><A NAME="SECTION00051100000000000000">
2302 4.1.1 Sub-expression Elimination</A>
2306 The compiler does local and global common subexpression elimination,
2311 <TT>i = x + y + 1; </TT>
2317 will be translated to
2321 <TT>iTemp = x + y </TT>
2323 <TT>i = iTemp + 1 </TT>
2325 <TT>j = iTemp</TT>
2329 Some subexpressions are not as obvious as the above example, e.g.:
2333 <TT>a->b[i].c = 10; </TT>
2335 <TT>a->b[i].d = 11;</TT>
2339 In this case the address arithmetic a->b[i] will be computed only
2340 once; the equivalent code in C would be.
2344 <TT>iTemp = a->b[i]; </TT>
2346 <TT>iTemp.c = 10; </TT>
2348 <TT>iTemp.d = 11;</TT>
2352 The compiler will try to keep these temporary variables in registers.
2356 <H3><A NAME="SECTION00051200000000000000">
2357 4.1.2 Dead-Code Elimination</A>
2362 <TT>int global; </TT>
2364 <TT>void f () { </TT>
2366 <TT> int i; </TT>
2368 <TT> i = 1; /* dead store */ </TT>
2370 <TT> global = 1; /* dead store */ </TT>
2372 <TT> global = 2; </TT>
2374 <TT> return; </TT>
2376 <TT> global = 3; /* unreachable */ </TT>
2386 <TT>int global; void f () </TT>
2390 <TT> global = 2; </TT>
2392 <TT> return; </TT>
2398 <H3><A NAME="SECTION00051300000000000000">
2399 4.1.3 Copy-Propagation</A>
2404 <TT>int f() { </TT>
2406 <TT> int i, j; </TT>
2408 <TT> i = 10; </TT>
2410 <TT> j = i; </TT>
2412 <TT> return j; </TT>
2422 <TT>int f() { </TT>
2424 <TT> int i,j; </TT>
2426 <TT> i = 10; </TT>
2428 <TT> j = 10; </TT>
2430 <TT> return 10; </TT>
2435 Note: the dead stores created by this copy propagation will be eliminated
2436 by dead-code elimination.
2440 <H3><A NAME="SECTION00051400000000000000">
2441 4.1.4 Loop Optimizations</A>
2445 Two types of loop optimizations are done by SDCC loop invariant lifting
2446 and strength reduction of loop induction variables. In addition to
2447 the strength reduction the optimizer marks the induction variables
2448 and the register allocator tries to keep the induction variables in
2449 registers for the duration of the loop. Because of this preference
2450 of the register allocator, loop induction optimization causes an increase
2451 in register pressure, which may cause unwanted spilling of other temporary
2452 variables into the stack / data space. The compiler will generate
2453 a warning message when it is forced to allocate extra space either
2454 on the stack or data space. If this extra space allocation is undesirable
2455 then induction optimization can be eliminated either for the entire
2456 source file (with -noinduction option) or for a given function only
2457 using #pragma NOINDUCTION.
2465 <TT>for (i = 0 ; i < 100 ; i ++) </TT>
2467 <TT> f += k + l;</TT>
2475 <TT>itemp = k + l; </TT>
2477 <TT>for (i = 0; i < 100; i++) </TT>
2479 <TT> f += itemp;</TT>
2483 As mentioned previously some loop invariants are not as apparent,
2484 all static address computations are also moved out of the loop.
2488 Strength Reduction, this optimization substitutes an expression by
2489 a cheaper expression:
2493 <TT>for (i=0;i < 100; i++)</TT>
2495 <TT> ar[i*5] = i*3;</TT>
2503 <TT>itemp1 = 0; </TT>
2505 <TT>itemp2 = 0; </TT>
2507 <TT>for (i=0;i< 100;i++) { </TT>
2509 <TT> ar[itemp1] = itemp2; </TT>
2511 <TT> itemp1 += 5; </TT>
2513 <TT> itemp2 += 3; </TT>
2519 The more expensive multiplication is changed to a less expensive addition.
2523 <H3><A NAME="SECTION00051500000000000000">
2524 4.1.5 Loop Reversing</A>
2528 This optimization is done to reduce the overhead of checking loop
2529 boundaries for every iteration. Some simple loops can be reversed
2530 and implemented using a ``decrement and jump if not zero'' instruction.
2531 SDCC checks for the following criterion to determine if a loop is
2532 reversible (note: more sophisticated compilers use data-dependency
2533 analysis to make this determination, SDCC uses a more simple minded
2539 <LI>The 'for' loop is of the form
2543 <TT>for (<symbol> = <expression> ; <sym> [< | <=] <expression>
2544 ; [<sym>++ | <sym> += 1])</TT>
2546 <TT> <for body></TT></LI>
2547 <LI>The <for body> does not contain ``continue'' or 'break''.</LI>
2548 <LI>All goto's are contained within the loop.</LI>
2549 <LI>No function calls within the loop.</LI>
2550 <LI>The loop control variable <sym> is not assigned any value within the
2552 <LI>The loop control variable does NOT participate in any arithmetic operation
2553 within the loop.</LI>
2554 <LI>There are NO switch statements in the loop.</LI>
2556 Note djnz instruction can be used for 8-bit values <I>only</I>, therefore
2557 it is advantageous to declare loop control symbols as <I>char</I>.
2558 Ofcourse this may not be possible on all situations.
2562 <H3><A NAME="SECTION00051600000000000000">
2563 4.1.6 Algebraic Simplifications</A>
2567 SDCC does numerous algebraic simplifications, the following is a small
2568 sub-set of these optimizations.
2572 <TT>i = j + 0 ; /* changed to */ i = j; </TT>
2574 <TT>i /= 2; /* changed to */ i >>= 1; </TT>
2576 <TT>i = j - j ; /* changed to */ i = 0; </TT>
2578 <TT>i = j / 1 ; /* changed to */ i = j;</TT>
2582 Note the subexpressions given above are generally introduced by macro
2583 expansions or as a result of copy/constant propagation.
2587 <H3><A NAME="SECTION00051700000000000000">
2588 4.1.7 'switch' Statements</A>
2592 SDCC changes switch statements to jump tables when the following conditions
2598 <LI>The case labels are in numerical sequence, the labels need not be
2599 in order, and the starting number need not be one or zero.
2603 <TT>switch(i) { switch (i)
2606 <TT>case 4:... case 1: ... </TT>
2608 <TT>case 5:... case 2: ... </TT>
2610 <TT>case 3:... case 3: ... </TT>
2612 <TT>case 6:... case 4: ... </TT>
2614 <TT>} }</TT>
2617 Both the above switch statements will be implemented using a jump-table.</LI>
2618 <LI>The number of case labels is at least three, since it takes two conditional
2619 statements to handle the boundary conditions.</LI>
2620 <LI>The number of case labels is less than 84, since each label takes
2621 3 bytes and a jump-table can be utmost 256 bytes long. </LI>
2623 Switch statements which have gaps in the numeric sequence or those
2624 that have more that 84 case labels can be split into more than one
2625 switch statement for efficient code generation, e.g.:
2629 <TT>switch (i) { </TT>
2631 <TT>case 1: ... </TT>
2633 <TT>case 2: ... </TT>
2635 <TT>case 3: ... </TT>
2637 <TT>case 4: ... </TT>
2639 <TT>case 9: ... </TT>
2641 <TT>case 10: ... </TT>
2643 <TT>case 11: ... </TT>
2645 <TT>case 12: ... </TT>
2651 If the above switch statement is broken down into two switch statements
2655 <TT>switch (i) { </TT>
2657 <TT>case 1: ... </TT>
2659 <TT>case 2: ... </TT>
2661 <TT>case 3: ... </TT>
2663 <TT>case 4: ... </TT>
2671 <TT>switch (i) { </TT>
2673 <TT>case 9: ... </TT>
2675 <TT>case 10: ... </TT>
2677 <TT>case 11: ... </TT>
2679 <TT>case 12: ... </TT>
2684 then both the switch statements will be implemented using jump-tables
2685 whereas the unmodified switch statement will not be.
2689 <H3><A NAME="SECTION00051800000000000000">
2690 4.1.8 Bit-shifting Operations.</A>
2694 Bit shifting is one of the most frequently used operation in embedded
2695 programming. SDCC tries to implement bit-shift operations in the most
2696 efficient way possible, e.g.:
2699 <TT>unsigned char i;</TT>
2703 <TT>i>>= 4; </TT>
2709 generates the following code:
2712 <TT>mov a,_i </TT>
2714 <TT>swap a </TT>
2716 <TT>anl a,#0x0f </TT>
2722 In general SDCC will never setup a loop if the shift count is known.
2727 <TT>unsigned int i; </TT>
2731 <TT>i >>= 9; </TT>
2741 <TT>mov a,(_i + 1) </TT>
2743 <TT>mov (_i + 1),#0x00 </TT>
2745 <TT>clr c </TT>
2747 <TT>rrc a </TT>
2753 Note that SDCC stores numbers in little-endian format (i.e. lowest
2758 <H3><A NAME="SECTION00051900000000000000">
2759 4.1.9 Bit-rotation</A>
2763 A special case of the bit-shift operation is bit rotation, SDCC recognizes
2764 the following expression to be a left bit-rotation:
2768 <TT>unsigned char i; </TT>
2772 <TT>i = ((i << 1) | (i >>
2779 will generate the following code:
2783 <TT>mov a,_i </TT>
2785 <TT>rl a </TT>
2791 SDCC uses pattern matching on the parse tree to determine this operation.Variations
2792 of this case will also be recognized as bit-rotation, i.e.:
2796 <TT>i = ((i >> 7) | (i <<
2797 1)); /* left-bit rotation */</TT>
2801 <H3><A NAME="SECTION000511000000000000000">
2802 4.1.10 Highest Order Bit</A>
2806 It is frequently required to obtain the highest order bit of an integral
2807 type (long, int, short or char types). SDCC recognizes the following
2808 expression to yield the highest order bit and generates optimized
2813 <TT>unsigned int gint; </TT>
2816 <TT>foo () { </TT>
2818 <TT>unsigned char hob; </TT>
2820 <TT> ... </TT>
2822 <TT> hob = (gint >> 15) & 1; </TT>
2824 <TT> .. </TT>
2830 will generate the following code:
2833 <TT> 61
2834 ; hob.c 7 </TT>
2836 <TT> 000A E5*01 62
2837 mov a,(_gint + 1) </TT>
2839 <TT> 000C 33 63
2840 rlc a </TT>
2842 <TT> 000D E4 64
2843 clr a </TT>
2845 <TT> 000E 13 65
2846 rrc a </TT>
2848 <TT> 000F F5*02 66
2849 mov _foo_hob_1_1,a</TT>
2852 Variations of this case however will <I>not</I> be recognized. It
2853 is a standard C expression, so I heartily recommend this be the only
2854 way to get the highest order bit, (it is portable). Of course it will
2855 be recognized even if it is embedded in other expressions, e.g.:
2859 <TT>xyz = gint + ((gint >> 15) & 1);</TT>
2863 will still be recognized.
2867 <H3><A NAME="SECTION000511100000000000000">
2868 4.1.11 Peep-hole Optimizer</A>
2872 The compiler uses a rule based, pattern matching and re-writing mechanism
2873 for peep-hole optimization. It is inspired by <I>copt</I> a peep-hole
2874 optimizer by Christopher W. Fraser (cwfraser@microsoft.com). A default
2875 set of rules are compiled into the compiler, additional rules may
2876 be added with the <I>-peep-file <filename></I> option. The rule language
2877 is best illustrated with examples.
2881 <TT>replace { </TT>
2883 <TT> mov %1,a </TT>
2885 <TT> mov a,%1</TT>
2887 <TT>} by {</TT>
2889 <TT> mov %1,a</TT>
2895 The above rule will change the following assembly sequence:
2899 <TT> mov r1,a </TT>
2901 <TT> mov a,r1</TT>
2913 Note: All occurrences of a <I>%n</I> (pattern variable) must denote
2914 the same string. With the above rule, the assembly sequence:
2918 <TT> mov r1,a </TT>
2920 <TT> mov a,r2</TT>
2924 will remain unmodified.
2928 Other special case optimizations may be added by the user (via <I>-peep-file
2929 option</I>). E.g. some variants of the 8051 MCU allow only <TT>ajmp</TT>
2930 and <TT>acall</TT>. The following two rules will change all <TT>ljmp</TT>
2931 and <TT>lcall</TT> to <TT>ajmp</TT> and <TT>acall</TT>
2935 <TT>replace { lcall %1 } by { acall %1 } </TT>
2937 <TT>replace { ljmp %1 } by { ajmp %1 }</TT>
2941 The <I>inline-assembler code</I> is also passed through the peep hole
2942 optimizer, thus the peephole optimizer can also be used as an assembly
2943 level macro expander. The rules themselves are MCU dependent whereas
2944 the rule language infra-structure is MCU independent. Peephole optimization
2945 rules for other MCU can be easily programmed using the rule language.
2949 The syntax for a rule is as follows:
2953 <TT>rule := replace [ restart ] '{' <assembly sequence> '\n'
2956 <TT> '}' by '{' '\n'
2959 <TT> <assembly
2960 sequence> '\n' </TT>
2962 <TT> '}' [if <functionName>
2963 ] '\n' </TT>
2967 <assembly sequence> := assembly instruction (each instruction including
2968 labels must be on a separate line).
2972 The optimizer will apply to the rules one by one from the top in the
2973 sequence of their appearance, it will terminate when all rules are
2974 exhausted. If the 'restart' option is specified, then the optimizer
2975 will start matching the rules again from the top, this option for
2976 a rule is expensive (performance), it is intended to be used in situations
2977 where a transformation will trigger the same rule again. A good example
2978 of this the following rule:
2982 <TT>replace restart { </TT>
2984 <TT> pop %1 </TT>
2986 <TT> push %1 } by { </TT>
2988 <TT> ; nop </TT>
2994 Note that the replace pattern cannot be a blank, but can be a comment
2995 line. Without the 'restart' option only the inner most 'pop' 'push'
2996 pair would be eliminated, i.e.:
3000 <TT> pop ar1 </TT>
3002 <TT> pop ar2 </TT>
3004 <TT> push ar2 </TT>
3006 <TT> push ar1</TT>
3014 <TT> pop ar1 </TT>
3016 <TT> ; nop </TT>
3018 <TT> push ar1</TT>
3022 <I>with</I> the restart option the rule will be applied again to the
3023 resulting code and then all the pop-push pairs will be eliminated
3028 <TT> ; nop </TT>
3030 <TT> ; nop</TT>
3034 A conditional function can be attached to a rule. Attaching rules
3035 are somewhat more involved, let me illustrate this with an example.
3039 <TT>replace { </TT>
3041 <TT> ljmp %5 </TT>
3045 <TT>} by { </TT>
3047 <TT> sjmp %5 </TT>
3051 <TT>} if labelInRange</TT>
3055 The optimizer does a look-up of a function name table defined in function
3056 <I>callFuncByName</I> in the source file SDCCpeeph.c, with the name
3057 <I>labelInRange</I>. If it finds a corresponding entry the function
3058 is called. Note there can be no parameters specified for these functions,
3059 in this case the use of <I>%5</I> is crucial, since the function
3060 <I>labelInRange</I> expects to find the label in that particular variable
3061 (the hash table containing the variable bindings is passed as a parameter).
3062 If you want to code more such functions, take a close look at the
3063 function labelInRange and the calling mechanism in source file SDCCpeeph.c.
3064 I know this whole thing is a little kludgey, but maybe some day we
3065 will have some better means. If you are looking at this file, you
3066 will also see the default rules that are compiled into the compiler,
3067 you can add your own rules in the default set there if you get tired
3068 of specifying the -peep-file option.
3072 <H2><A NAME="SECTION00052000000000000000">
3077 SDCC supports the following #pragma directives. This directives are
3078 applicable only at a function level.
3083 <LI>SAVE - this will save all the current options.</LI>
3084 <LI>RESTORE - will restore the saved options from the last save. Note
3085 that SAVES & RESTOREs cannot be nested. SDCC uses the same buffer
3086 to save the options each time a SAVE is called.</LI>
3087 <LI>NOGCSE - will stop global subexpression elimination.</LI>
3088 <LI>NOINDUCTION - will stop loop induction optimizations.</LI>
3089 <LI>NOJTBOUND - will not generate code for boundary value checking, when
3090 switch statements are turned into jump-tables.</LI>
3091 <LI>NOOVERLAY - the compiler will not overlay the parameters and local
3092 variables of a function.</LI>
3093 <LI>NOLOOPREVERSE - Will not do loop reversal optimization</LI>
3094 <LI>EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma
3095 disables generation of pair of push/pop instruction in ISR function
3096 (using interrupt keyword). The directive should be placed immediately
3097 before the ISR function definition and it affects ALL ISR functions
3098 following it. To enable the normal register saving for ISR functions
3099 use #pragma EXCLUDE none.</LI>
3100 <LI>CALLEE-SAVES function1[,function2[,function3...]] - The compiler
3101 by default uses a caller saves convention for register saving across
3102 function calls, however this can cause unneccessary register pushing
3103 & popping when calling small functions from larger functions. This
3104 option can be used to switch the register saving convention for the
3105 function names specified. The compiler will not save registers when
3106 calling these functions, extra code will be generated at the entry
3107 & exit for these functions to save & restore the registers used
3108 by these functions, this can SUBSTANTIALLY reduce code & improve
3109 run time performance of the generated code. In future the compiler
3110 (with interprocedural analysis) will be able to determine the appropriate
3111 scheme to use for each function call. If -callee-saves command line
3112 option is used, the function names specified in #pragma CALLEE-SAVES
3113 is appended to the list of functions specified inthe command line.</LI>
3115 The pragma's are intended to be used to turn-off certain optimizations
3116 which might cause the compiler to generate extra stack / data space
3117 to store compiler generated temporary variables. This usually happens
3118 in large functions. Pragma directives should be used as shown in the
3119 following example, they are used to control options & optimizations
3120 for a given function; pragmas should be placed before and/or after
3121 a function, placing pragma's inside a function body could have unpredictable
3126 <TT>#pragma SAVE /* save the current settings */ </TT>
3128 <TT>#pragma NOGCSE /* turnoff global subexpression elimination
3131 <TT>#pragma NOINDUCTION /* turn off induction optimizations
3134 <TT>int foo () </TT>
3138 <TT> ... </TT>
3140 <TT> /* large code */ </TT>
3142 <TT> ... </TT>
3146 <TT>#pragma RESTORE /* turn the optimizations back on */</TT>
3150 The compiler will generate a warning message when extra space is allocated.
3151 It is strongly recommended that the SAVE and RESTORE pragma's be used
3152 when changing options for a function.
3156 <H2><A NAME="SECTION00053000000000000000">
3157 4.3 <I><pending: this is messy and incomplete></I> Library Routines</A>
3161 The following library routines are provided for your convenience.
3164 stdio.h - Contains the following functions printf & sprintf these
3165 routines are developed by Martijn van Balen <balen@natlab.research.philips.com>.
3169 %[flags][width][b|B|l|L]type
3173 flags: - left justify output in
3174 specified field width
3176 + prefix output with
3177 +/- sign if output is signed type
3179 space prefix output with a
3180 blank if it's a signed positive value
3182 width: specifies minimum number
3183 of characters outputted for numbers
3185 or strings.
3187 - For numbers,
3188 spaces are added on the left when needed.
3190 If width starts
3191 with a zero character, zeroes and used
3193 instead of
3196 - For strings,
3197 spaces are are added on the left or right (when
3199 flag '-' is
3202
3204 b/B: byte argument (used
3207 l/L: long argument (used
3210 type: d decimal number
3212 u unsigned decimal
3215 o unsigned octal number
3218 x unsigned hexadecimal
3221 X unsigned hexadecimal
3224 c character
3226 s string (generic pointer)
3229 p generic pointer (I:data/idata,
3230 C:code, X:xdata, P:paged)
3232 f float (still to be
3236 Also contains a very simple version of printf (printf_small). This
3237 simplified version of printf supports only the following formats.
3240 format output type argument-type
3242 %d decimal short/int
3244 %ld decimal long
3246 %hd decimal char
3248 %x hexadecimal short/int
3250 %lx hexadecimal long
3252 %hx hexadecimal char
3254 %o octal short/int
3256 %lo octal long
3258 %ho octal char
3260 %c character char
3262 %s character _generic pointer
3265 The routine is very stack intesive, -stack-after-data parameter should
3266 be used when using this routine, the routine also takes about 1K of
3267 code space. It also expects an external function named putchar(char)
3268 to be present (this can be changed). When using the %s format the
3269 string / pointer should be cast to a generic pointer. eg.
3272 printf_small(``my str %s, my int %d\n'',(char
3273 _generic *)mystr,myint);
3278 <LI>stdarg.h - contains definition for the following macros to be used
3279 for variable parameter list, note that a function can have a variable
3280 parameter list if and only if it is 'reentrant'
3283 va_list, va_start, va_arg, va_end.
3287 <LI>setjmp.h - contains defintion for ANSI setjmp & longjmp routines.
3288 Note in this case setjmp & longjmp can be used between functions
3289 executing within the same register bank, if long jmp is executed from
3290 a function that is using a different register bank from the function
3291 issuing the setjmp function, the results may be unpredictable. The
3292 jump buffer requires 3 bytes of data (the stack pointer & a 16 byte
3293 return address), and can be placed in any address space.</LI>
3294 <LI>stdlib.h - contains the following functions.
3301 <LI>string.h - contains the following functions.
3304 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr,
3305 strspn, strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp,
3310 <LI>ctype.h - contains the following routines.
3313 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
3314 isxdigit, isalnum, isalpha.
3318 <LI>malloc.h - The malloc routines are developed by Dmitry S. Obukhov
3319 (dso@usa.net). These routines will allocate memory from the external
3320 ram. Here is a description on how to use them (as described by the
3327 // #define DYNAMIC_MEMORY_SIZE 0x2000
3329 // .....
3331 // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
3334 // unsigned char xdata * current_buffer;
3336 // .....
3338 // void main(void)
3340 // {
3342 // ...
3344 // init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
3347 // //Now it's possible to use malloc.
3349 // ...
3351 // current_buffer = malloc(0x100);
3353 //
3357 <LI>serial.h - Serial IO routines are also developed by Dmitry S. Obukhov
3358 (dso@usa.net). These routines are interrupt driven with a 256 byte
3359 circular buffer, they also expect external ram to be present. Please
3360 see documentation in file SDCCDIR/sdcc51lib/serial.c. Note the header
3361 file ``serial.h'' MUST be included in the file containing the
3362 'main' function.</LI>
3363 <LI>ser.h - Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.com>
3364 these routines are more compact and faster. Please see documentation
3365 in file SDCCDIR/sdcc51lib/ser.c</LI>
3366 <LI>ser_ir.h - Another alternate set of serial routines provided by Josef
3367 Wolf <jw@raven.inka.de>, these routines do not use the external ram.</LI>
3368 <LI>reg51.h - contains register definitions for a standard 8051</LI>
3369 <LI>float.h - contains min, max and other floating point related stuff.</LI>
3371 All library routines are compiled as -model-small, they are all non-reentrant,
3372 if you plan to use the large model or want to make these routines
3373 reentrant, then they will have to be recompiled with the appropriate
3377 Have not had time to do the more involved routines like printf, will
3378 get to them shortly.
3382 <H2><A NAME="SECTION00054000000000000000">
3383 4.4 Interfacing with Assembly Routines</A>
3388 <H3><A NAME="SECTION00054100000000000000">
3389 4.4.1 Global Registers used for Parameter Passing</A>
3393 The compiler always uses the global registers <I>DPL,DPH,B</I> and
3394 <I>ACC</I> to pass the first parameter to a routine. The second parameter
3395 onwards is either allocated on the stack (for reentrant routines or
3396 if -stack-auto is used) or in the internal / external ram (depending
3397 on the memory model).
3401 <H3><A NAME="SECTION00054200000000000000">
3402 4.4.2 Assembler Routine(non-reentrant)</A>
3406 In the following example the function cfunc calls an assembler routine
3407 asm_func, which takes two parameters.
3411 <TT>extern int asm_func(unsigned char, unsigned char);</TT>
3414 <TT>int c_func (unsigned char i, unsigned char j)</TT>
3418 <TT> return asm_func(i,j);</TT>
3423 <TT>int main()</TT>
3427 <TT> return c_func(10,9);</TT>
3432 The corresponding assembler function is:
3436 <TT>.globl _asm_func_PARM_2 </TT>
3438 <TT> .globl _asm_func </TT>
3440 <TT> .area OSEG </TT>
3442 <TT>_asm_func_PARM_2:</TT>
3444 <TT> .ds 1 </TT>
3446 <TT> .area CSEG </TT>
3448 <TT>_asm_func: </TT>
3450 <TT> mov a,dpl </TT>
3452 <TT> add a,_asm_func_PARM_2 </TT>
3454 <TT> mov dpl,a </TT>
3456 <TT> mov dpl,#0x00 </TT>
3458 <TT> ret</TT>
3461 Note here that the return values are placed in 'dpl' - One byte return
3462 value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and
3463 'b' for three byte values (generic pointers) and 'dpl','dph','b' &
3464 'acc' for four byte values.
3467 The parameter naming convention is _<function_name>_PARM_<n>,
3468 where n is the parameter number starting from 1, and counting from
3469 the left. The first parameter is passed in ``dpl'' for One bye
3470 parameter, ``dptr'' if two bytes, ``b,dptr'' for three bytes
3471 and ``acc,b,dptr'' for four bytes, the varible name for the second
3472 parameter will be _<function_name>_PARM_2.
3476 Assemble the assembler routine with the following command:
3480 <I><B>asx8051 -losg asmfunc.asm</B></I>
3483 Then compile and link the assembler routine to the C source file with
3484 the following command:
3488 <I><B>sdcc cfunc.c asmfunc.rel</B></I>
3492 <H3><A NAME="SECTION00054300000000000000">
3493 4.4.3 Assembler Routine(reentrant)</A>
3497 In this case the second parameter onwards will be passed on the stack,
3498 the parameters are pushed from right to left i.e. after the call the
3499 left most parameter will be on the top of the stack. Here is an example:
3503 <TT>extern int asm_func(unsigned char, unsigned char);</TT>
3506 <TT>int c_func (unsigned char i, unsigned char j) reentrant </TT>
3510 <TT> return asm_func(i,j); </TT>
3515 <TT>int main() </TT>
3519 <TT> return c_func(10,9); </TT>
3525 The corresponding assembler routine is:
3529 <TT>.globl _asm_func </TT>
3531 <TT>_asm_func: </TT>
3533 <TT> push _bp </TT>
3535 <TT> mov _bp,sp </TT>
3537 <TT> mov r2,dpl</TT>
3539 <TT> mov a,_bp </TT>
3541 <TT> clr c </TT>
3543 <TT> add a,#0xfd </TT>
3545 <TT> mov r0,a </TT>
3547 <TT> add a,#0xfc</TT>
3549 <TT> mov r1,a </TT>
3551 <TT> mov a,@r0 </TT>
3553 <TT> add a,r2</TT>
3555 <TT> mov dpl,a </TT>
3557 <TT> mov dph,#0x00 </TT>
3559 <TT> mov sp,_bp </TT>
3561 <TT> pop _bp </TT>
3563 <TT> ret</TT>
3566 The compiling and linking procedure remains the same, however note
3567 the extra entry & exit linkage required for the assembler code, _bp
3568 is the stack frame pointer and is used to compute the offset into
3569 the stack for parameters and local variables.
3573 <H2><A NAME="SECTION00055000000000000000">
3574 4.5 External Stack</A>
3578 The external stack is located at the start of the external ram segment,
3579 and is 256 bytes in size. When -xstack option is used to compile
3580 the program, the parameters and local variables of all reentrant functions
3581 are allocated in this area. This option is provided for programs with
3582 large stack space requirements. When used with the -stack-auto option,
3583 all parameters and local variables are allocated on the external stack
3584 (note support libraries will need to be recompiled with the same options).
3587 The compiler outputs the higher order address byte of the external
3588 ram segment into PORT P2, therefore when using the External Stack
3589 option, this port MAY NOT be used by the application program.
3593 <H2><A NAME="SECTION00056000000000000000">
3594 4.6 ANSI-Compliance</A>
3598 Deviations from the compliancy.
3603 <LI>functions are not always reentrant.</LI>
3604 <LI>structures cannot be assigned values directly, cannot be passed as
3605 function parameters or assigned to each other and cannot be a return
3606 value from a function, e.g.:
3609 <TT>struct s { ... }; </TT>
3611 <TT>struct s s1, s2; </TT>
3613 <TT>foo() </TT>
3617 <TT> ... </TT>
3619 <TT> s1 = s2 ; /* is invalid in SDCC although allowed
3620 in ANSI */ </TT>
3622 <TT> ... </TT>
3626 <TT>struct s foo1 (struct s parms) /* is invalid in SDCC although
3627 allowed in ANSI */ </TT>
3631 <TT> struct s rets; </TT>
3633 <TT> ... </TT>
3635 <TT> return rets;/* is invalid in SDCC although allowed
3636 in ANSI */ </TT>
3639 <LI>'long long' (64 bit integers) not supported.</LI>
3640 <LI>'double' precision floating point not supported.</LI>
3641 <LI>No support for setjmp and longjmp (for now).</LI>
3642 <LI>Old K&R style function declarations are NOT allowed.
3645 <TT>foo(i,j) /* this old style of function declarations */
3648 <TT>int i,j; /* are valid in ANSI but not valid in SDCC */
3653 <TT> ... </TT>
3656 <LI>functions declared as pointers must be dereferenced during the call.
3659 <TT>int (*foo)();</TT>
3663 <TT>/* has to be called like this */ </TT>
3665 <TT>(*foo)(); /* ansi standard allows calls to be made like
3666 'foo()' */</TT></LI>
3671 <H2><A NAME="SECTION00057000000000000000">
3672 4.7 Cyclomatic Complexity</A>
3676 Cyclomatic complexity of a function is defined as the number of independent
3677 paths the program can take during execution of the function. This
3678 is an important number since it defines the number test cases you
3679 have to generate to validate the function. The accepted industry standard
3680 for complexity number is 10, if the cyclomatic complexity reported
3681 by SDCC exceeds 10 you should think about simplification of the function
3682 logic. Note that the complexity level is not related to the number
3683 of lines of code in a function. Large functions can have low complexity,
3684 and small functions can have large complexity levels.
3688 SDCC uses the following formula to compute the complexity:
3692 complexity = (number of edges in control flow graph) - (number of
3693 nodes in control flow graph) + 2;
3697 Having said that the industry standard is 10, you should be aware
3698 that in some cases it be may unavoidable to have a complexity level
3699 of less than 10. For example if you have switch statement with more
3700 than 10 case labels, each case label adds one to the complexity level.
3701 The complexity level is by no means an absolute measure of the algorithmic
3702 complexity of the function, it does however provide a good starting
3703 point for which functions you might look at for further optimization.
3707 <H1><A NAME="SECTION00060000000000000000">
3712 Here are a few guidelines that will help the compiler generate more
3713 efficient code, some of the tips are specific to this compiler others
3714 are generally good programming practice.
3719 <LI>Use the smallest data type to represent your data-value. If it is
3720 known in advance that the value is going to be less than 256 then
3721 use a 'char' instead of a 'short' or 'int'.</LI>
3722 <LI>Use unsigned when it is known in advance that the value is not going
3723 to be negative. This helps especially if you are doing division or
3724 multiplication.</LI>
3725 <LI>NEVER jump into a LOOP.</LI>
3726 <LI>Declare the variables to be local whenever possible, especially loop
3727 control variables (induction).</LI>
3728 <LI>Since the compiler does not do implicit integral promotion, the programmer
3729 should do an explicit cast when integral promotion is required.</LI>
3730 <LI>Reducing the size of division, multiplication & modulus operations
3731 can reduce code size substantially. Take the following code for example.
3734 <TT>foobar(unsigned int p1, unsigned char ch)</TT>
3738 <TT> unsigned char ch1 = p1 % ch ;</TT>
3740 <TT> .... </TT>
3746 For the modulus operation the variable ch will be promoted to unsigned
3747 int first then the modulus operation will be performed (this will
3748 lead to a call to support routine _muduint()), and the result will
3749 be casted to an int. If the code is changed to
3752 <TT>foobar(unsigned int p1, unsigned char ch)</TT>
3756 <TT> unsigned char ch1 = (unsigned char)p1 % ch ;</TT>
3758 <TT> .... </TT>
3764 It would substantially reduce the code generated (future versions
3765 of the compiler will be smart enough to detect such optimization oppurtunities).</LI>
3770 <H2><A NAME="SECTION00061000000000000000">
3771 5.1 Notes on MCS51 memory layout</A>
3775 The 8051 family of micro controller have a minimum of 128 bytes of
3776 internal memory which is structured as follows
3780 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7
3783 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
3785 - Bytes 30-7F - 60 bytes for general purpose use.
3789 Normally the SDCC compiler will only utilise the first bank of registers,
3790 but it is possible to specify that other banks of registers should
3791 be used in interrupt routines. By default, the compiler will place
3792 the stack after the last bank of used registers, i.e. if the first
3793 2 banks of registers are used, it will position the base of the internal
3794 stack at address 16 (0X10). This implies that as the stack grows,
3795 it will use up the remaining register banks, and the 16 bytes used
3796 by the 128 bit variables, and 60 bytes for general purpose use.
3799 By default, the compiler uses the 60 general purpose bytes to hold
3800 "near data". The compiler/optimiser may also declare
3801 some Local Variables in this area to hold local data.
3804 If any of the 128 bit variables are used, or near data is being used
3805 then care needs to be taken to ensure that the stack does not grow
3806 so much that it starts to over write either your bit variables or
3807 "near data". There is no runtime checking to prevent
3808 this from happening.
3811 The amount of stack being used is affected by the use of the "internal
3812 stack" to save registers before a subroutine call is made
3813 (-stack-auto will declare parameters and local variables on the stack)
3814 and the number of nested subroutines.
3817 If you detect that the stack is over writing you data, then the following
3818 can be done. -xstack will cause an external stack to be used for
3819 saving registers and (if -stack-auto is being used) storing parameters
3820 and local variables. However this will produce more code which will
3821 be slower to execute.
3825 -stack-loc will allow you specify the start of the stack, i.e. you
3826 could start it after any data in the general purpose area. However
3827 this may waste the memory not used by the register banks and if the
3828 size of the "near data" increases, it may creep
3829 into the bottom of the stack.
3833 -stack-after-data, similar to the -stack-loc, but it automatically
3834 places the stack after the end of the "near data".
3835 Again this could waste any spare register space.
3839 -data-loc allows you to specify the start address of the near data.
3840 This could be used to move the "near data" further
3841 away from the stack giving it more room to grow. This will only work
3842 if no bit variables are being used and the stack can grow to use the
3851 If you find that the stack is over writing your bit variables or "near
3852 data" then the approach which best utilised the internal
3853 memory is to position the "near data" after the
3854 last bank of used registers or, if you use bit variables, after the
3855 last bit variable by using the -data-loc, e.g. if two register banks
3856 are being used and no bit variables, -data-loc 16, and use the -stack-after-data
3860 If bit variables are being used, another method would be to try and
3861 squeeze the data area in the unused register banks if it will fit,
3862 and start the stack after the last bit variable.
3866 <H1><A NAME="SECTION00070000000000000000">
3867 6. Retargetting for other MCUs.</A>
3871 The issues for retargetting the compiler are far too numerous to be
3872 covered by this document. What follows is a brief description of each
3873 of the seven phases of the compiler and its MCU dependency.
3878 <LI>Parsing the source and building the annotated parse tree. This phase
3879 is largely MCU independent (except for the language extensions). Syntax
3880 & semantic checks are also done in this phase, along with some initial
3881 optimizations like back patching labels and the pattern matching optimizations
3882 like bit-rotation etc.</LI>
3883 <LI>The second phase involves generating an intermediate code which can
3884 be easy manipulated during the later phases. This phase is entirely
3885 MCU independent. The intermediate code generation assumes the target
3886 machine has unlimited number of registers, and designates them with
3887 the name iTemp. The compiler can be made to dump a human readable
3888 form of the code generated by using the -dumpraw option.</LI>
3889 <LI>This phase does the bulk of the standard optimizations and is also
3890 MCU independent. This phase can be broken down into several sub-phases:
3894 Break down intermediate code (iCode) into basic blocks.
3896 Do control flow & data flow analysis on the basic blocks.
3898 Do local common subexpression elimination, then global subexpression
3901 Dead code elimination
3905 If loop optimizations caused any changes then do 'global subexpression
3906 elimination' and 'dead code elimination' again.</LI>
3907 <LI>This phase determines the live-ranges; by live range I mean those
3908 iTemp variables defined by the compiler that still survive after all
3909 the optimizations. Live range analysis is essential for register allocation,
3910 since these computation determines which of these iTemps will be assigned
3911 to registers, and for how long.</LI>
3912 <LI>Phase five is register allocation. There are two parts to this process.
3916 The first part I call 'register packing' (for lack of a better term).
3917 In this case several MCU specific expression folding is done to reduce
3922 The second part is more MCU independent and deals with allocating
3923 registers to the remaining live ranges. A lot of MCU specific code
3924 does creep into this phase because of the limited number of index
3925 registers available in the 8051.</LI>
3926 <LI>The Code generation phase is (unhappily), entirely MCU dependent and
3927 very little (if any at all) of this code can be reused for other MCU.
3928 However the scheme for allocating a homogenized assembler operand
3929 for each iCode operand may be reused.</LI>
3930 <LI>As mentioned in the optimization section the peep-hole optimizer is
3931 rule based system, which can reprogrammed for other MCUs.</LI>
3936 <H1><A NAME="SECTION00080000000000000000">
3937 7. SDCDB - Source Level Debugger</A>
3941 SDCC is distributed with a source level debugger. The debugger uses
3942 a command line interface, the command repertoire of the debugger has
3943 been kept as close to gdb (the GNU debugger) as possible. The configuration
3944 and build process is part of the standard compiler installation, which
3945 also builds and installs the debugger in the target directory specified
3946 during configuration. The debugger allows you debug BOTH at the C
3947 source and at the ASM source level.
3951 <H2><A NAME="SECTION00081000000000000000">
3952 7.1 Compiling for Debugging</A>
3956 The debug option must be specified for all files for which debug
3957 information is to be generated. The complier generates a .cdb file
3958 for each of these files. The linker updates the .cdb file with the
3959 address information. This .cdb is used by the debugger.
3963 <H2><A NAME="SECTION00082000000000000000">
3964 7.2 How the Debugger Works</A>
3968 When the -debug option is specified the compiler generates extra
3969 symbol information some of which are put into the the assembler source
3970 and some are put into the .cdb file, the linker updates the .cdb file
3971 with the address information for the symbols. The debugger reads the
3972 symbolic information generated by the compiler & the address information
3973 generated by the linker. It uses the SIMULATOR (Daniel's S51) to execute
3974 the program, the program execution is controlled by the debugger.
3975 When a command is issued for the debugger, it translates it into appropriate
3976 commands for the simulator.
3980 <H2><A NAME="SECTION00083000000000000000">
3981 7.3 Starting the Debugger</A>
3985 The debugger can be started using the following command line. (Assume
3986 the file you are debugging has the file name foo).
3990 <I><B>sdcdb foo</B></I>
3994 The debugger will look for the following files.
3999 <LI>foo.c - the source file.</LI>
4000 <LI>foo.cdb - the debugger symbol information file.</LI>
4001 <LI>foo.ihx - the intel hex format object file.</LI>
4006 <H2><A NAME="SECTION00084000000000000000">
4007 7.4 Command Line Options.</A>
4013 <LI>-directory=<source file directory> this option can used to specify
4014 the directory search list. The debugger will look into the directory
4015 list specified for source, cdb & ihx files. The items in the directory
4016 list must be separated by ':', e.g. if the source files can be in
4017 the directories /home/src1 and /home/src2, the -directory option
4018 should be -directory=/home/src1:/home/src2. Note there can be no
4019 spaces in the option. </LI>
4020 <LI>-cd <directory> - change to the <directory>.</LI>
4021 <LI>-fullname - used by GUI front ends.</LI>
4022 <LI>-cpu <cpu-type> - this argument is passed to the simulator please
4023 see the simulator docs for details.</LI>
4024 <LI>-X <Clock frequency > this options is passed to the simulator please
4025 see the simulator docs for details.</LI>
4026 <LI>-s <serial port file> passed to simulator see the simulator docs for
4028 <LI>-S <serial in,out> passed to simulator see the simulator docs for
4034 <H2><A NAME="SECTION00085000000000000000">
4035 7.5 Debugger Commands.</A>
4039 As mention earlier the command interface for the debugger has been
4040 deliberately kept as close the GNU debugger gdb, as possible. This
4041 will help the integration with existing graphical user interfaces
4042 (like ddd, xxgdb or xemacs) existing for the GNU debugger.
4046 <H3><A NAME="SECTION00085100000000000000">
4047 7.5.1 break [line | file:line | function | file:function]</A>
4051 Set breakpoint at specified line or function:
4055 <I><B>sdcdb>break 100 </B></I>
4057 <I><B>sdcdb>break foo.c:100</B></I>
4059 <I><B>sdcdb>break funcfoo</B></I>
4061 <I><B>sdcdb>break foo.c:funcfoo</B></I>
4065 <H3><A NAME="SECTION00085200000000000000">
4066 7.5.2 clear [line | file:line | function | file:function ]</A>
4070 Clear breakpoint at specified line or function:
4074 <I><B>sdcdb>clear 100</B></I>
4076 <I><B>sdcdb>clear foo.c:100</B></I>
4078 <I><B>sdcdb>clear funcfoo</B></I>
4080 <I><B>sdcdb>clear foo.c:funcfoo</B></I>
4084 <H3><A NAME="SECTION00085300000000000000">
4089 Continue program being debugged, after breakpoint.
4093 <H3><A NAME="SECTION00085400000000000000">
4098 Execute till the end of the current function.
4102 <H3><A NAME="SECTION00085500000000000000">
4103 7.5.5 delete [n]</A>
4107 Delete breakpoint number 'n'. If used without any option clear ALL
4108 user defined break points.
4112 <H3><A NAME="SECTION00085600000000000000">
4113 7.5.6 info [break | stack | frame | registers ]</A>
4119 <LI>info break - list all breakpoints</LI>
4120 <LI>info stack - show the function call stack.</LI>
4121 <LI>info frame - show information about the current execution frame.</LI>
4122 <LI>info registers - show content of all registers.</LI>
4127 <H3><A NAME="SECTION00085700000000000000">
4132 Step program until it reaches a different source line.
4136 <H3><A NAME="SECTION00085800000000000000">
4141 Step program, proceeding through subroutine calls.
4145 <H3><A NAME="SECTION00085900000000000000">
4150 Start debugged program.
4154 <H3><A NAME="SECTION000851000000000000000">
4155 7.5.10 ptype variable </A>
4159 Print type information of the variable.
4163 <H3><A NAME="SECTION000851100000000000000">
4164 7.5.11 print variable</A>
4168 print value of variable.
4172 <H3><A NAME="SECTION000851200000000000000">
4173 7.5.12 file filename</A>
4177 load the given file name. Note this is an alternate method of loading
4182 <H3><A NAME="SECTION000851300000000000000">
4187 print information about current frame.
4191 <H3><A NAME="SECTION000851400000000000000">
4192 7.5.14 set srcmode</A>
4196 Toggle between C source & assembly source.
4200 <H3><A NAME="SECTION000851500000000000000">
4201 7.5.15 ! simulator command</A>
4205 Send the string following '!' to the simulator, the simulator response
4206 is displayed. Note the debugger does not interpret the command being
4207 sent to the simulator, so if a command like 'go' is sent the debugger
4208 can loose its execution context and may display incorrect values.
4212 <H3><A NAME="SECTION000851600000000000000">
4218 "Watch me now. Iam going Down. My name is Bobby Brown"
4222 <H2><A NAME="SECTION00086000000000000000">
4223 7.6 Interfacing with XEmacs.</A>
4227 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
4228 sdcdb.el and sdcdbsrc.el. These two files can be found in the $(prefix)/bin
4229 directory after the installation is complete. These files need to
4230 be loaded into XEmacs for the interface to work. This can be done
4231 at XEmacs startup time by inserting the following into your '.xemacs'
4232 file (which can be found in your HOME directory):
4236 <TT>(load-file sdcdbsrc.el)</TT>
4240 .xemacs is a lisp file so the () around the command is REQUIRED. The
4241 files can also be loaded dynamically while XEmacs is running, set
4242 the environment variable 'EMACSLOADPATH' to the installation bin directory
4243 (<installdir>/bin), then enter the following command ESC-x load-file
4244 sdcdbsrc. To start the interface enter the following command:
4248 <I><B>ESC-x sdcdbsrc</B></I>
4252 You will prompted to enter the file name to be debugged.
4256 The command line options that are passed to the simulator directly
4257 are bound to default values in the file sdcdbsrc.el. The variables
4258 are listed below, these values maybe changed as required.
4263 <LI>sdcdbsrc-cpu-type '51</LI>
4264 <LI>sdcdbsrc-frequency '11059200</LI>
4265 <LI>sdcdbsrc-serial nil</LI>
4267 The following is a list of key mapping for the debugger interface.
4273 <TT>;; Current Listing :: </TT>
4275 <TT>;;key binding Comment
4278 <TT>;;-- ---- ----
4283 <TT>;; n sdcdb-next-from-src SDCDB
4284 next command </TT>
4286 <TT>;; b sdcdb-back-from-src SDCDB
4287 back command </TT>
4289 <TT>;; c sdcdb-cont-from-src SDCDB
4290 continue command</TT>
4292 <TT>;; s sdcdb-step-from-src SDCDB
4293 step command </TT>
4295 <TT>;; ? sdcdb-whatis-c-sexp SDCDB
4296 ptypecommand for data at </TT>
4298 <TT>;;
4299 buffer point </TT>
4301 <TT>;; x sdcdbsrc-delete SDCDB
4302 Delete all breakpoints if no arg </TT>
4304 <TT>;; given
4305 or delete arg (C-u arg x) </TT>
4307 <TT>;; m sdcdbsrc-frame SDCDB
4308 Display current frame if no arg, </TT>
4310 <TT>;; given
4311 or display frame arg </TT>
4313 <TT>;; buffer
4316 <TT>;; ! sdcdbsrc-goto-sdcdb Goto
4317 the SDCDB output buffer </TT>
4319 <TT>;; p sdcdb-print-c-sexp SDCDB
4320 print command for data at </TT>
4322 <TT>;;
4323 buffer point </TT>
4325 <TT>;; g sdcdbsrc-goto-sdcdb Goto
4326 the SDCDB output buffer </TT>
4328 <TT>;; t sdcdbsrc-mode Toggles
4329 Sdcdbsrc mode (turns it off) </TT>
4333 <TT>;; C-c C-f sdcdb-finish-from-src SDCDB
4334 finish command </TT>
4338 <TT>;; C-x SPC sdcdb-break Set
4339 break for line with point </TT>
4341 <TT>;; ESC t sdcdbsrc-mode Toggle
4342 Sdcdbsrc mode </TT>
4344 <TT>;; ESC m sdcdbsrc-srcmode
4345 Toggle list mode </TT>
4352 <H1><A NAME="SECTION00090000000000000000">
4353 8. Other Processors</A>
4358 <H2><A NAME="SECTION00091000000000000000">
4359 8.1 The Z80 and gbz80 port</A>
4363 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like
4364 gbz80. The port is incomplete - long support is incomplete (mul, div
4365 and mod are unimplimented), and both float and bitfield support is
4366 missing. Apart from that the code generated is correct.
4369 As always, the code is the authoritave reference - see z80/ralloc.c
4370 and z80/gen.c. The stack frame is similar to that generated by the
4371 IAR Z80 compiler. IX is used as the base pointer, HL is used as a
4372 temporary register, and BC and DE are available for holding varibles.
4373 IY is currently unusued. Return values are stored in HL. One bad side
4374 effect of using IX as the base pointer is that a functions stack frame
4375 is limited to 127 bytes - this will be fixed in a later version.
4379 <H1><A NAME="SECTION000100000000000000000">
4384 SDCC has grown to be a large project. The compiler alone (without
4385 the preprocessor, assembler and linker) is about 40,000 lines of code
4386 (blank stripped). The open source nature of this project is a key
4387 to its continued growth and support. You gain the benefit and support
4388 of many active software developers and end users. Is SDCC perfect?
4389 No, that's why we need your help. The developers take pride in fixing
4390 reported bugs. You can help by reporting the bugs and helping other
4391 SDCC users. There are lots of ways to contribute, and we encourage
4392 you to take part in making SDCC a great software package.
4396 <H2><A NAME="SECTION000101000000000000000">
4397 9.1 Reporting Bugs</A>
4401 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
4402 or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed ASAP. When
4403 reporting a bug, it is very useful to include a small test program
4404 which reproduces the problem. If you can isolate the problem by looking
4405 at the generated assembly code, this can be very helpful. Compiling
4406 your program with the -dumpall option can sometimes be useful in
4407 locating optimization problems.
4411 <H1><A NAME="SECTION000110000000000000000">
4412 10. Acknowledgments</A>
4416 Sandeep Dutta (sandeep.dutta@usa.net) - SDCC, the compiler, MCS51
4417 code generator, Debugger, AVR port
4419 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX
4422 John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for
4425 Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
4427 Daniel Drotos (drdani@mazsola.iit.uni-miskolc.hu) - for his Freeware
4430 Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience
4433 Unknown - for the GNU C - preprocessor.
4435 Michael Hope - The Z80 and Z80GB port, 186 development
4437 Kevin Vigor - The DS390 port.
4439 Johan Knol - Lots of fixes and enhancements, DS390/TINI libs.
4441 Scott Datallo - The PIC port.
4445 <I>Thanks to all the other volunteer developers who have helped
4446 with coding, testing, web-page creation, distribution sets, etc. You
4447 know who you are :-)</I>
4451 This document was initially written by Sandeep Dutta
4454 All product names mentioned herein may be trademarks of their respective
4460 <H2><A NAME="SECTION000120000000000000000">
4463 <DT><STRONG>index</STRONG>
4464 <DD><A HREF="SDCCUdoc.html#67">1.7 Wishes for the</A>
4468 <H1><A NAME="SECTION000130000000000000000">
4469 About this document ...</A>
4471 <STRONG>SDCC Compiler User Guide</STRONG><P>
4472 This document was generated using the
4473 <A HREF="http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 99.1 release (March 30, 1999)
4475 Copyright © 1993, 1994, 1995, 1996,
4476 <A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>,
4477 Computer Based Learning Unit, University of Leeds.
4479 Copyright © 1997, 1998, 1999,
4480 <A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>,
4481 Mathematics Department, Macquarie University, Sydney.
4483 The command line arguments were: <BR>
4484 <STRONG>latex2html</STRONG> <TT>-split 0 -show_section_numbers -dir fullhtml SDCCUdoc</TT>
4486 The translation was initiated by Johan Knol on 2001-07-07
4487 <BR><HR><H4>Footnotes</H4>
4489 <DT><A NAME="foot530">...
4490 anyway</A><A NAME="foot530"
4491 HREF="SDCCUdoc.html#tex2html1"><SUP>1</SUP></A>
4492 <DD>possible exception: if a function is called ONLY from 'interrupt'
4493 functions using a particular bank, it can be declared with the same
4494 'using' attribute as the calling 'interrupt' functions. For instance,
4495 if you have several ISRs using bank one, and all of them call memcpy(),
4496 it might make sense to create a specialized version of memcpy() 'using
4497 1', since this would prevent the ISR from having to save bank zero
4498 to the stack on entry and switch to bank zero before calling the function
4502 <!--Navigation Panel-->
4503 <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_group"
4504 SRC="/home/johan/latex2html/icons.gif/next_group_motif_gr.gif">
4505 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
4506 SRC="/home/johan/latex2html/icons.gif/up_motif_gr.gif">
4507 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
4508 SRC="/home/johan/latex2html/icons.gif/previous_motif_gr.gif">
4510 <!--End of Navigation Panel-->
4513 <BR><I>2001-07-07</I>
projects / fw / sdcc / blob