1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2 "http://www.w3.org/TR/REC-html40/loose.dtd">
4 <meta name="GENERATOR" content="TtH 3.01">
5 <style type="text/css"><!--
6 td div.comp { margin-top: -0.6ex; margin-bottom: -1ex;}
7 td div.comb { margin-top: -0.6ex; margin-bottom: -.6ex;}
8 td div.hrcomp { line-height: 0.9; margin-top: -0.8ex; margin-bottom: -1ex;}
9 td div.norm {line-height:normal;}
10 span.roman {font-family: serif; font-style: normal; font-weight: normal;}
11 span.overacc2 {position: relative; left: .8em; top: -1.2ex;}
12 span.overacc1 {position: relative; left: .6em; top: -1.2ex;} --></style>
15 <title> lSDCC Compiler User Guide</title>
17 <h1 align="center">lSDCC Compiler User Guide </h1>
20 <h2><a name="tth_sEc1">
21 1</a> Introduction</h2>
24 <h3><a name="tth_sEc1.1">
25 1.1</a> About SDCC</h3>
28 <b>SDCC</b> is a Free ware, retargettable, optimizing ANSI-C compiler
29 by <b>Sandeep Dutta</b> designed for 8 bit Microprocessors. The
30 current version targets Intel MCS51 based Microprocessors(8051,8052,
31 etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51 variant. It
32 can be retargetted for other microprocessors, support for PIC, AVR
33 and 186 is under development. The entire source code for the compiler
34 is distributed under GPL. SDCC uses ASXXXX & ASLINK, a Freeware,
35 retargettable assembler & linker. SDCC has extensive language extensions
36 suitable for utilizing various microcontrollers underlying hardware
37 effectively. In addition to the MCU specific optimizations SDCC also
38 does a host of standard optimizations like <em>global sub expression
39 elimination, loop optimizations (loop invariant, strength reduction
40 of induction variables and loop reversing), constant folding & propagation,
41 copy propagation, dead code elimination and jumptables for 'switch'
42 statements.</em> For the back-end SDCC uses a global register allocation
43 scheme which should be well suited for other 8 bit MCUs. The peep
44 hole optimizer uses a rule based substitution mechanism which is MCU
45 dependent. Supported data-types are <em>char (8 bits, 1 byte), short
46 and int (16 bits, 2 bytes), long (32 bit, 4 bytes)</em> and <em>float
47 (4 byte IEEE).</em> The compiler also allows <em>inline assembler code</em>
48 to be embedded anywhere in a function. In addition routines developed
49 in assembly can also be called. SDCC also provides an option to report
50 the relative complexity of a function, these functions can then be
51 further optimized, or hand coded in assembly if needed. SDCC also
52 comes with a companion source level debugger SDCDB, the debugger currently
53 uses ucSim a freeware simulator for 8051 and other micro-controllers.
54 The latest version can be downloaded from <b><a href="http://sdcc.sourceforge.net/"><tt>http://sdcc.sourceforge.net/</tt></a>
58 <h3><a name="tth_sEc1.2">
59 1.2</a> Open Source</h3>
62 All packages used in this compiler system are <em>opensource</em> (freeware);
63 source code for all the sub-packages (asxxxx assembler/linker, pre-processor)
64 are distributed with the package. This documentation is maintained
65 using a freeware word processor (LY<!--hbox-->X).
68 This program is free software; you can redistribute it and/or modify
69 it under the terms of the GNU General Public License as published
70 by the Free Software Foundation; either version 2, or (at your option)
71 any later version. This program is distributed in the hope that it
72 will be useful, but WITHOUT ANY WARRANTY; without even the implied
73 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
74 the GNU General Public License for more details. You should have received
75 a copy of the GNU General Public License along with this program;
76 if not, write to the Free Software Foundation, 59 Temple Place - Suite
77 330, Boston, MA 02111-1307, USA. In other words, you are welcome to
78 use, share and improve this program. You are forbidden to forbid anyone
79 else to use, share and improve what you give them. Help stamp out
83 <h3><a name="tth_sEc1.3">
84 1.3</a> Typographic conventions</h3>
87 Throughout this manual, we will use the following convention. Commands
88 you have to type in are printed in <font face="helvetica"><b>"sans
89 serif"</b></font><font face="helvetica">.</font> Code samples are printed in <tt>typewriter
90 font.</tt> Interesting items and new terms are printed in <em>italicised
94 <h3><a name="tth_sEc1.4">
95 1.4</a> System Requirements</h3>
98 What do you need before you start installation of SDCC? A computer,
99 and a desire to compute. The preferred method of installation is to
100 compile SDCC from source using GNU GCC and make. For Windows some
101 pre-compiled binary distributions are available for your convenience.
102 You should have some experience with command line tools and compiler
106 <h3><a name="tth_sEc1.5">
107 1.5</a> Other Resources</h3>
110 The SDCC home page at <a href="http://sdcc.sourceforge.net/"><tt>http://sdcc.sourceforge.net/</tt></a> is a great
111 place to find distribution sets. You can also find links to the user
112 mailing lists that offer help or discuss SDCC with other SDCC users.
113 Web links to other SDCC related sites can also be found here. This
114 document can be found in the DOC directory of the source package as
115 a text or HTML file. Some of the other tools (simulator and assembler)
116 included with SDCC contain their own documentation and can be found
117 in the source distribution. If you want the latest unreleased software,
118 the complete source package is available directly by anonymous CVS
119 on cvs.sdcc.sourceforge.net.
122 <h2><a name="tth_sEc2">
123 2</a> Installation</h2>
126 <h3><a name="tth_sEc2.1">
127 2.1</a> Linux/Unix Installation</h3>
132 <li> Download the source package, it will be named something like sdcc-2.x.x.tgz.</li>
134 <li> Bring up a command line terminal, such as xterm.</li>
136 <li> Unpack the file using a command like: <font face="helvetica"><b>"tar
137 -xzf sdcc-2.x.x.tgz"</b></font>, this will create a sub-directory
138 called sdcc with all of the sources.</li>
140 <li> Change directory into the main SDCC directory, for example type: <font face="helvetica"><b>"cd
141 sdcc"</b></font><font face="helvetica">.</font></li>
143 <li> Type <font face="helvetica"><b>"./configure"</b></font>. This configures
144 the package for compilation on your system.</li>
146 <li> Type <font face="helvetica"><b>"make"</b></font>. All of the source
147 packages will compile, this can take a while.</li>
149 <li> Type <font face="helvetica"><b>"make install"</b></font> as root. This
150 copies the binary executables to the install directories.</li>
154 <h3><a name="tth_sEc2.2">
155 2.2</a> Windows Installation</h3>
158 For installation under Windows you first need to pick between a pre-compiled
159 binary package, or installing the source package along with the Cygwin
160 package. The binary package is the quickest to install, while the
161 Cygwin package includes all of the open source power tools used to
162 compile the complete SDCC source package in the Windows environment.
163 If you are not familiar with the Unix command line environment, you
164 may want to read the section on additional information for Windows
165 users prior to your initial installation.
168 <h4><a name="tth_sEc2.2.1">
169 2.2.1</a> Windows Install Using a Binary Package</h4>
174 <li> Download the binary package and unpack it using your favorite unpacking
175 tool (gunzip, WinZip, etc). This should unpack to a group of sub-directories.
176 An example directory structure after unpacking is: c:usrlocalbin
177 for the executables, c:usrlocalsharesdccinclude
178 and c:usrlocalsharesdcclib
179 for the include and libraries.</li>
181 <li> Adjust your environment PATH to include the location of the bin directory.
182 For example, make a setsdcc.bat file with the following: set PATH=c:usrlocalbin;%PATH%</li>
184 <li> When you compile with sdcc, you may need to specify the location of
185 the lib and include folders. For example, sdcc -I c:usrlocalsharesdccinclude
186 -L c:usrlocalsharesdcclibsmall
191 <h4><a name="tth_sEc2.2.2">
192 2.2.2</a> Windows Install Using Cygwin</h4>
197 <li> Download and install the cygwin package from the redhat site<a href="http://sources.redhat.com/cygwin/"><tt>http://sources.redhat.com/cygwin/</tt></a>.
198 Currently, this involved downloading a small install program which
199 then automates downloading and installing selected parts of the package
200 (a large 80M byte sized dowload for the whole thing).</li>
202 <li> Bring up a Unix/Bash command line terminal from the Cygwin menu.</li>
204 <li> Follow the instructions in the preceding Linux/Unix installation section.</li>
208 <h3><a name="tth_sEc2.3">
209 2.3</a> Testing out the SDCC Compiler</h3>
212 The first thing you should do after installing your SDCC compiler
213 is to see if it runs. Type <font face="helvetica"><b>"sdcc -version"</b></font>
214 at the prompt, and the program should run and tell you the version.
215 If it doesn't run, or gives a message about not finding sdcc program,
216 then you need to check over your installation. Make sure that the
217 sdcc bin directory is in your executable search path defined by the
218 PATH environment setting (see the Trouble-shooting section for suggestions).
219 Make sure that the sdcc program is in the bin folder, if not perhaps
220 something did not install correctly.<br />
222 SDCC binaries are commonly installed in a directory arrangement like
228 <tr><td>/usr/local/bin</td><td>Holds executables(sdcc, s51, aslink, ...)</td></tr><tr><td>
229 <tr><td>/usr/local/share/sdcc/lib </td><td>Holds common C libraries</td></tr>
230 <tr><td>/usr/local/share/sdcc/include</td><td>Holds common C header files</td></tr></table>
233 Make sure the compiler works on a very simple example. Type in the
234 following test.c program using your favorite editor:<br />
236 Compile this using the following command: <font face="helvetica"><b>"sdcc
237 -c test.c"</b></font> If all goes well, the compiler will generate
238 a test.asm and test.rel file. Congratulations, you've just compiled
239 your first program with SDCC. We used the -c option to tell SDCC not
240 to link the generated code, just to keep things simple for this step.<br />
242 The next step is to try it with the linker. Type in <font face="helvetica"><b>"sdcc
243 test.c"</b></font>. If all goes well the compiler will link with the
244 libraries and produce a test.ihx output file. If this step fails (no
245 test.ihx, and the linker generates warnings), then the problem is
246 most likely that sdcc cannot find the /usr/local/share/sdcc/lib directory
247 (see the Install trouble-shooting section for suggestions).<br />
249 The final test is to ensure sdcc can use the standard header files
250 and libraries. Edit test.c and change it to the following:<br />
252 #include <string.h><br />
254 <tt>char str1[10];</tt> <br />
255 <tt> strcpy(str1, "testing");</tt> <br />
256 <tt>}</tt> <br />
257 <tt></tt> <br />
258 Compile this by typing <font face="helvetica"><b>"sdcc test.c"</b></font>.
259 This should generate a test.ihx output file, and it should give no
260 warnings such as not finding the string.h file. If it cannot find
261 the string.h file, then the problem is that sdcc cannot find the /usr/local/share/sdcc/include
262 directory (see the Install trouble-shooting section for suggestions).
265 <h3><a name="tth_sEc2.4">
266 2.4</a> Install Trouble-shooting</h3>
269 <h4><a name="tth_sEc2.4.1">
270 2.4.1</a> SDCC cannot find libraries or header files.</h4>
273 The default installation assumes the libraries and header files are
274 located at ``/usr/local/share/sdcc/lib'' and ``/usr/local/share/sdcc/include''.
275 An alternative is to specify these locations as compiler options like
276 this: <font face="helvetica"><b>"sdcc -L /usr/local/sdcc/lib/small
277 -I /usr/local/sdcc/include test.c"</b></font>.
280 <h4><a name="tth_sEc2.4.2">
281 2.4.2</a> SDCC does not compile correctly.</h4>
284 A thing to try is starting from scratch by unpacking the .tgz source
285 package again in an empty directory. Confure it again and build like:<br />
287 <font face="helvetica"><b>make 2&>1 | tee make.log</b></font><br />
289 After this you can review the make.log file to locate the problem.
290 Or a relevant part of this be attached to an email that could be helpful
291 when requesting help from the mailing list.
294 <h4><a name="tth_sEc2.4.3">
295 2.4.3</a> What the ''./configure'' does</h4>
298 The ''./configure'' command is a script that analyzes your system
299 and performs some configuration to ensure the source package compiles
300 on your system. It will take a few minutes to run, and will compile
301 a few tests to determine what compiler features are installed.
304 <h4><a name="tth_sEc2.4.4">
305 2.4.4</a> What the ''make'' does.</h4>
308 This runs the GNU make tool, which automatically compiles all the
309 source packages into the final installed binary executables.
312 <h4><a name="tth_sEc2.4.5">
313 2.4.5</a> What the ''make install'' command does.</h4>
316 This will install the compiler, other executables and libraries in
317 to the appropriate system directories. The default is to copy the
318 executables to /usr/local/bin and the libraries and header files to
319 /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
322 <h3><a name="tth_sEc2.5">
323 2.5</a> Additional Information for Windows Users</h3>
326 The standard method of installing on a Unix system involves compiling
327 the source package. This is easily done under Unix, but under Windows
328 it can be a more difficult process. The Cygwin is a large package
329 to download, and the compilation runs considerably slower under Windows
330 due to the overhead of the Cygwin tool set. An alternative is to install
331 a pre-compiled Windows binary package. There are various trade-offs
332 between each of these methods.
335 The Cygwin package allows a Windows user to run a Unix command line
336 interface (bash shell) and also implements a Unix like file system
337 on top of Windows. Included are many of the famous GNU software development
338 tools which can augment the SDCC compiler.This is great if you have
339 some experience with Unix command line tools and file system conventions,
340 if not you may find it easier to start by installing a binary Windows
341 package. The binary packages work with the Windows file system conventions.
344 <h4><a name="tth_sEc2.5.1">
345 2.5.1</a> Getting started with Cygwin</h4>
348 SDCC is typically distributed as a tarred/gzipped file (.tgz). This
349 is a packed file similar to a .zip file. Cygwin includes the tools
350 you will need to unpack the SDCC distribution (tar and gzip). To unpack
351 it, simply follow the instructions under the Linux/Unix install section.
352 Before you do this you need to learn how to start a cygwin shell and
353 some of the basic commands used to move files, change directory, run
354 commands and so on. The change directory command is <font face="helvetica"><b>``cd''</b></font>,
355 the move command is <font face="helvetica"><b>``mv''</b></font>. To print the current
356 working directory, type <font face="helvetica"><b>``pwd''</b></font>. To make a directory,
357 use <font face="helvetica"><b>``mkdir''</b></font>.
360 There are some basic differences between Unix and Windows file systems
361 you should understand. When you type in directory paths, Unix and
362 the Cygwin bash prompt uses forward slashes '/' between directories
363 while Windows traditionally uses '' backward slashes.
364 So when you work at the Cygwin bash prompt, you will need to use the
365 forward '/' slashes. Unix does not have a concept of drive letters,
366 such as ``c:``, instead all files systems attach and appear
370 <h4><a name="tth_sEc2.5.2">
371 2.5.2</a> Running SDCC as Native Compiled Executables</h4>
374 If you use the pre-compiled binaries, the install directories for
375 the libraries and header files may need to be specified on the sdcc
376 command line like this: <font face="helvetica"><b>"sdcc -L c:usrlocalsdcclibsmall
377 -I c:usrlocalsdccinclude
378 test.c"</b></font> if you are running outside of a Unix bash shell.
381 If you have successfully installed and compiled SDCC with the Cygwin
382 package, it is possible to compile into native .exe files by using
383 the additional makefiles included for this purpose. For example, with
384 the Borland 32-bit compiler you would run <font face="helvetica"><b>"make
385 -f Makefile.bcc"</b></font>. A command line version of the Borland
386 32-bit compiler can be downloaded from the Inprise web site.
389 <h3><a name="tth_sEc2.6">
390 2.6</a> SDCC on Other Platforms</h3>
395 <li> <b>FreeBSD and other non-GNU Unixes</b> - Make sure the GNU make
396 is installed as the default make tool.</li>
398 <li> SDCC has been ported to run under a variety of operating systems and
399 processors. If you can run GNU GCC/make then chances are good SDCC
400 can be compiled and run on your system.</li>
404 <h3><a name="tth_sEc2.7">
405 2.7</a> Advanced Install Options</h3>
408 The ``configure'' command has several options. The most commonly
409 used option is -prefix=<directory name>, where <directory name> is
410 the final location for the sdcc executables and libraries, (default
411 location is /usr/local). The installation process will create the
412 following directory structure under the <directory name> specified
413 (if they do not already exist). <br />
415 bin/ - binary exectables (add to PATH environment variable)<br />
417 bin/share/sdcc/include/ - include header files<br />
418 bin/share/sdcc/lib/<br />
419 bin/share/sdcc/lib/small/ - Object & library files for small model
421 bin/share/sdcc/lib/large/ - Object & library files for large model
423 bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390 library<br />
425 The command <font face="helvetica"><b>''./configure -prefix=/usr/local''</b></font>
426 will configure the compiler to be installed in directory /usr/local/bin.
429 <h3><a name="tth_sEc2.8">
430 2.8</a> Components of SDCC</h3>
433 SDCC is not just a compiler, but a collection of tools by various
434 developers. These include linkers, assemblers, simulators and other
435 components. Here is a summary of some of the components. Note that
436 the included simulator and assembler have separate documentation which
437 you can find in the source package in their respective directories.
438 As SDCC grows to include support for other processors, other packages
439 from various developers are included and may have their own sets of
443 You might want to look at the various executables which are installed
444 in the bin directory. At the time of this writing, we find the following
447 <b>sdcc</b> - The compiler.<br />
448 <b>sdcpp</b> - The C preprocessor.<br />
449 <b>asx8051</b> - The assembler for 8051 type processors.<br />
450 <b>as-z80, as-gbz80</b> - The Z80 and GameBoy Z80 assemblers.<br />
451 <b>aslink</b> -The linker for 8051 type processors.<br />
452 <b>link-z80, link-gbz80</b> - The Z80 and GameBoy Z80 linkers.<br />
453 <b>s51</b> - The ucSim 8051 simulator.<br />
454 <b>sdcdb</b> - The source debugger.<br />
455 <b>packihx</b> - A tool to pack Intel hex files.<br />
457 As development for other processors proceeds, this list will expand
458 to include executables to support processors like AVR, PIC, etc.
461 <h4><a name="tth_sEc2.8.1">
462 2.8.1</a> sdcc - The Compiler</h4>
465 This is the actual compiler, it in turn uses the c-preprocessor and
466 invokes the assembler and linkage editor.
469 <h4><a name="tth_sEc2.8.2">
470 2.8.2</a> sdcpp (C-Preprocessor)</h4>
473 The preprocessor is a modified version of the GNU preprocessor. The
474 C preprocessor is used to pull in #include sources, process #ifdef
475 statements, #defines and so on.
478 <h4><a name="tth_sEc2.8.3">
479 2.8.3</a> asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 (The Assemblers
480 and Linkage Editors)</h4>
483 This is retargettable assembler & linkage editor, it was developed
484 by Alan Baldwin. John Hartman created the version for 8051, and I
485 (Sandeep) have made some enhancements and bug fixes for it to work
486 properly with the SDCC.
489 <h4><a name="tth_sEc2.8.4">
490 2.8.4</a> s51 - Simulator</h4>
493 S51 is a freeware, opensource simulator developed by Daniel Drotos
494 (<a href="mailto:drdani@mazsola.iit.uni-miskolc.hu"><tt>mailto:drdani@mazsola.iit.uni-miskolc.hu</tt></a>). The simulator is
495 built as part of the build process. For more information visit Daniel's
496 website at: <a href="http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51"><tt>http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51</tt></a>
500 <h4><a name="tth_sEc2.8.5">
501 2.8.5</a> sdcdb - Source Level Debugger</h4>
504 Sdcdb is the companion source level debugger. The current version
505 of the debugger uses Daniel's Simulator S51, but can be easily changed
506 to use other simulators.
509 <h2><a name="tth_sEc3">
510 3</a> Using SDCC</h2>
513 <h3><a name="tth_sEc3.1">
514 3.1</a> Compiling</h3>
517 <h4><a name="tth_sEc3.1.1">
518 3.1.1</a> Single Source File Projects</h4>
521 For single source file 8051 projects the process is very simple. Compile
522 your programs with the following command <font face="helvetica"><b>"sdcc
523 sourcefile.c".</b></font> This will compile, assemble and link your
524 source file. Output files are as follows<br />
527 sourcefile.asm - Assembler source file created by the compiler
530 sourcefile.lst - Assembler listing file created by the Assembler
533 sourcefile.rst - Assembler listing file updated with linkedit information,
534 created by linkage editor
537 sourcefile.sym - symbol listing for the sourcefile, created by the
541 sourcefile.rel - Object file created by the assembler, input to Linkage
545 sourcefile.map - The memory map for the load module, created by the
549 sourcefile.ihx - The load module in Intel hex format (you can select
550 the Motorola S19 format with -out-fmt-s19)
553 sourcefile.cdb - An optional file (with -debug) containing debug
557 <h4><a name="tth_sEc3.1.2">
558 3.1.2</a> Projects with Multiple Source Files</h4>
561 SDCC can compile only ONE file at a time. Let us for example assume
562 that you have a project containing the following files:<br />
564 foo1.c (contains some functions)<br />
565 foo2.c (contains some more functions)<br />
566 foomain.c (contains more functions and the function main)<br />
567 <font size="-2"></font><br />
568 The first two files will need to be compiled separately with the commands:
569 <font size="-2"></font><br />
571 <font face="helvetica"><b>sdcc -c foo1.c</b></font><font size="-2"></font><br />
572 <font face="helvetica"><b>sdcc -c foo2.c</b></font><br />
574 Then compile the source file containing the <em>main()</em> function
575 and link the files together with the following command: <br />
577 <font face="helvetica"><b>sdcc foomain.c foo1.rel foo2.rel</b></font><br />
579 Alternatively, <em>foomain.c</em> can be separately compiled as well:
580 <font face="helvetica"><b></b></font><br />
581 <font face="helvetica"><b></b></font><br />
582 <font face="helvetica"><b>sdcc -c foomain.c</b></font><br />
583 <font face="helvetica"><b>sdcc foomain.rel foo1.rel foo2.rel</b></font><br />
584 <font face="helvetica"><b></b></font><br />
585 The file containing the <em>main()</em> function <em></em> <font size="-2">MUST</font>
586 be the <font size="-2">FIRST</font> file specified in the command line, since the
587 linkage editor processes file in the order they are presented to it.
590 <h4><a name="tth_sEc3.1.3">
591 3.1.3</a> Projects with Additional Libraries</h4>
594 Some reusable routines may be compiled into a library, see the documentation
595 for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
596 for how to create a <em>.lib</em> library file. Libraries created in
597 this manner can be included in the command line. Make sure you include
598 the -L <library-path> option to tell the linker where to look for
599 these files if they are not in the current directory. Here is an example,
600 assuming you have the source file <em>foomain.c</em> and a library <em>foolib.lib</em>
601 in the directory <em>mylib</em> (if that is not the same as your current
604 <font face="helvetica"><b>sdcc foomain.c foolib.lib -L mylib</b></font><br />
605 <font face="helvetica"><b></b></font><br />
606 Note here that <em>mylib</em> must be an absolute path name.<br />
608 The most efficient way to use libraries is to keep seperate modules
609 in seperate source files. The lib file now should name all the modules.rel
610 files. For an example see the standard library file <em>libsdcc.lib</em>
611 in the directory <installdir>/share/lib/small.
614 <h3><a name="tth_sEc3.2">
615 3.2</a> Command Line Options</h3>
618 <h4><a name="tth_sEc3.2.1">
619 3.2.1</a> Processor Selection Options</h4>
623 <dl compact="compact">
628 <dt><b><b>-mmcs51</b></b></dt>
629 <dd>Generate code for the MCS51 (8051) family of processors.
630 This is the default processor target.</dd>
631 <dt><b><b>-mds390</b></b></dt>
632 <dd>Generate code for the DS80C390 processor.</dd>
633 <dt><b><b>-mz80</b></b></dt>
634 <dd>Generate code for the Z80 family of processors.</dd>
635 <dt><b><b>-mgbz80</b></b></dt>
636 <dd>Generate code for the GameBoy Z80 processor.</dd>
637 <dt><b><b>-mavr</b></b></dt>
638 <dd>Generate code for the Atmel AVR processor(In development,
640 <dt><b><b>-mpic14</b></b></dt>
641 <dd>Generate code for the PIC 14-bit processors(In development,
643 <dt><b><b>-mtlcs900h</b></b></dt>
644 <dd>Generate code for the Toshiba TLCS-900H processor(In
645 development, not complete).
650 <h4><a name="tth_sEc3.2.2">
651 3.2.2</a> Preprocessor Options</h4>
655 <dl compact="compact">
660 <dt><b><b>-I<path></b></b></dt>
661 <dd>The additional location where the pre processor
662 will look for <..h> or ``..h'' files.</dd>
663 <dt><b><b>-D<macro[=value]></b></b></dt>
664 <dd>Command line definition of macros.
665 Passed to the pre processor.</dd>
666 <dt><b><b>-M</b></b></dt>
667 <dd>Tell the preprocessor to output a rule suitable for make
668 describing the dependencies of each object file. For each source file,
669 the preprocessor outputs one make-rule whose target is the object
670 file name for that source file and whose dependencies are all the
671 files `#include'd in it. This rule may be a single line or may be
672 continued with `'-newline if it is long. The list
673 of rules is printed on standard output instead of the preprocessed
674 C program. `-M' implies `-E'.</dd>
675 <dt><b><b>-C</b></b></dt>
676 <dd>Tell the preprocessor not to discard comments. Used with
677 the `-E' option.</dd>
678 <dt><b><b>-MM</b></b></dt>
679 <dd>Like `-M' but the output mentions only the user header
680 files included with `#include ``file"'. System header
681 files included with `#include <file>' are omitted.</dd>
682 <dt><b><b>-Aquestion(answer)</b></b></dt>
683 <dd>Assert the answer answer for question,
684 in case it is tested with a preprocessor conditional such as `#if
685 #question(answer)'. `-A-' disables the standard assertions that normally
686 describe the target machine.</dd>
687 <dt><b><b>-Aquestion</b></b></dt>
688 <dd>(answer) Assert the answer answer for question,
689 in case it is tested with a preprocessor conditional such as `#if
690 #question(answer)'. `-A-' disables the standard assertions that normally
691 describe the target machine.</dd>
692 <dt><b><b>-Umacro</b></b></dt>
693 <dd>Undefine macro macro. `-U' options are evaluated
694 after all `-D' options, but before any `-include' and `-imacros' options.</dd>
695 <dt><b><b>-dM</b></b></dt>
696 <dd>Tell the preprocessor to output only a list of the macro
697 definitions that are in effect at the end of preprocessing. Used with
698 the `-E' option.</dd>
699 <dt><b><b>-dD</b></b></dt>
700 <dd>Tell the preprocessor to pass all macro definitions
701 into the output, in their proper sequence in the rest of the output.</dd>
702 <dt><b><b>-dN</b></b></dt>
703 <dd>Like `-dD' except that the macro arguments and contents
704 are omitted. Only `#define name' is included in the output.
709 <h4><a name="tth_sEc3.2.3">
710 3.2.3</a> Linker Options</h4>
714 <dl compact="compact">
719 <dt><b><b>-L -lib-path</b></b></dt>
720 <dd><absolute path to additional libraries> This
721 option is passed to the linkage editor's additional libraries search
722 path. The path name must be absolute. Additional library files may
723 be specified in the command line. See section Compiling programs for
725 <dt><b><b>-xram-loc</b><Value></b></dt>
726 <dd>The start location of the external ram,
727 default value is 0. The value entered can be in Hexadecimal or Decimal
728 format, e.g.: -xram-loc 0x8000 or -xram-loc 32768.</dd>
729 <dt><b><b>-code-loc</b><Value></b></dt>
730 <dd>The start location of the code segment,
731 default value 0. Note when this option is used the interrupt vector
732 table is also relocated to the given address. The value entered can
733 be in Hexadecimal or Decimal format, e.g.: -code-loc 0x8000 or -code-loc
735 <dt><b><b>-stack-loc</b><Value></b></dt>
736 <dd>The initial value of the stack pointer.
737 The default value of the stack pointer is 0x07 if only register bank
738 0 is used, if other register banks are used then the stack pointer
739 is initialized to the location above the highest register bank used.
740 eg. if register banks 1 & 2 are used the stack pointer will default
741 to location 0x18. The value entered can be in Hexadecimal or Decimal
742 format, eg. -stack-loc 0x20 or -stack-loc 32. If all four register
743 banks are used the stack will be placed after the data segment (equivalent
744 to -stack-after-data)</dd>
745 <dt><b><b>-stack-after-data</b></b></dt>
746 <dd>This option will cause the stack to be
747 located in the internal ram after the data segment.</dd>
748 <dt><b><b>-data-loc</b><Value></b></dt>
749 <dd>The start location of the internal ram
750 data segment, the default value is 0x30.The value entered can be in
751 Hexadecimal or Decimal format, eg. -data-loc 0x20 or -data-loc 32.</dd>
752 <dt><b><b>-idata-loc</b><Value></b></dt>
753 <dd>The start location of the indirectly
754 addressable internal ram, default value is 0x80. The value entered
755 can be in Hexadecimal or Decimal format, eg. -idata-loc 0x88 or -idata-loc
757 <dt><b><b>-out-fmt-ihx</b></b></dt>
758 <dd>The linker output (final object code) is in
759 Intel Hex format. (This is the default option).</dd>
760 <dt><b><b>-out-fmt-s19</b></b></dt>
761 <dd>The linker output (final object code) is in
767 <h4><a name="tth_sEc3.2.4">
768 3.2.4</a> MCS51 Options</h4>
772 <dl compact="compact">
777 <dt><b><b>-model-large</b></b></dt>
778 <dd>Generate code for Large model programs see
779 section Memory Models for more details. If this option is used all
780 source files in the project should be compiled with this option. In
781 addition the standard library routines are compiled with small model,
782 they will need to be recompiled.</dd>
783 <dt><b><b>-model-small</b></b></dt>
784 <dd>Generate code for Small Model programs see
785 section Memory Models for more details. This is the default model.
790 <h4><a name="tth_sEc3.2.5">
791 3.2.5</a> DS390 Options</h4>
795 <dl compact="compact">
800 <dt><b><b>-model-flat24</b></b></dt>
801 <dd>Generate 24-bit flat mode code. This is the
802 one and only that the ds390 code generator supports right now and
803 is default when using <em>-mds390</em>. See section Memory Models for
805 <dt><b><b>-stack-10bit</b></b></dt>
806 <dd>Generate code for the 10 bit stack mode of
807 the Dallas DS80C390 part. This is the one and only that the ds390
808 code generator supports right now and is default when using <em>-mds390</em>.
809 In this mode, the stack is located in the lower 1K of the internal
810 RAM, which is mapped to 0x400000. Note that the support is incomplete,
811 since it still uses a single byte as the stack pointer. This means
812 that only the lower 256 bytes of the potential 1K stack space will
813 actually be used. However, this does allow you to reclaim the precious
814 256 bytes of low RAM for use for the DATA and IDATA segments. The
815 compiler will not generate any code to put the processor into 10 bit
816 stack mode. It is important to ensure that the processor is in this
817 mode before calling any re-entrant functions compiled with this option.
818 In principle, this should work with the <em>-stack-auto</em> option,
819 but that has not been tested. It is incompatible with the <em>-xstack</em>
820 option. It also only makes sense if the processor is in 24 bit contiguous
821 addressing mode (see the <em>-model-flat24 option</em>).
826 <h4><a name="tth_sEc3.2.6">
827 3.2.6</a> Optimization Options</h4>
831 <dl compact="compact">
836 <dt><b><b>-nogcse</b></b></dt>
837 <dd>Will not do global subexpression elimination, this
838 option may be used when the compiler creates undesirably large stack/data
839 spaces to store compiler temporaries. A warning message will be generated
840 when this happens and the compiler will indicate the number of extra
841 bytes it allocated. It recommended that this option NOT be used, #pragma
842 NOGCSE can be used to turn off global subexpression elimination for
843 a given function only.</dd>
844 <dt><b><b>-noinvariant</b></b></dt>
845 <dd>Will not do loop invariant optimizations,
846 this may be turned off for reasons explained for the previous option.
847 For more details of loop optimizations performed see section Loop
848 Invariants.It recommended that this option NOT be used, #pragma NOINVARIANT
849 can be used to turn off invariant optimizations for a given function
851 <dt><b><b>-noinduction</b></b></dt>
852 <dd>Will not do loop induction optimizations,
853 see section strength reduction for more details.It is recommended
854 that this option is NOT used, #pragma NOINDUCTION can be used to
855 turn off induction optimizations for a given function only.</dd>
856 <dt><b><b>-nojtbound</b></b></dt>
857 <dd> Will not generate boundary condition check
858 when switch statements are implemented using jump-tables. See section
859 Switch Statements for more details. It is recommended that this option
860 is NOT used, #pragma NOJTBOUND can be used to turn off boundary checking
861 for jump tables for a given function only.</dd>
862 <dt><b><b>-noloopreverse</b></b></dt>
863 <dd>Will not do loop reversal optimization.
868 <h4><a name="tth_sEc3.2.7">
869 3.2.7</a> Other Options</h4>
873 <dl compact="compact">
878 <dt><b><b>-c -compile-only</b></b></dt>
879 <dd>will compile and assemble the source,
880 but will not call the linkage editor.</dd>
881 <dt><b><b>-E</b></b></dt>
882 <dd>Run only the C preprocessor. Preprocess all the C source
883 files specified and output the results to standard output.</dd>
884 <dt><b><b>-stack-auto</b></b></dt>
885 <dd>All functions in the source file will be compiled
886 as <em>reentrant</em>, i.e. the parameters and local variables will
887 be allocated on the stack. see section Parameters and Local Variables
888 for more details. If this option is used all source files in the project
889 should be compiled with this option.</dd>
890 <dt><b><b>-xstack</b></b></dt>
891 <dd>Uses a pseudo stack in the first 256 bytes in the
892 external ram for allocating variables and passing parameters. See
893 section on external stack for more details.</dd>
894 <dt><b><b>-callee-saves</b></b></dt>
895 <dd><b>function1[,function2][,function3]....</b>
896 The compiler by default uses a caller saves convention for register
897 saving across function calls, however this can cause unneccessary
898 register pushing & popping when calling small functions from larger
899 functions. This option can be used to switch the register saving convention
900 for the function names specified. The compiler will not save registers
901 when calling these functions, no extra code will be generated at the
902 entry & exit for these functions to save & restore the registers
903 used by these functions, this can SUBSTANTIALLY reduce code & improve
904 run time performance of the generated code. In the future the compiler
905 (with interprocedural analysis) will be able to determine the appropriate
906 scheme to use for each function call. DO NOT use this option for built-in
907 functions such as _muluint..., if this option is used for a library
908 function the appropriate library function needs to be recompiled with
909 the same option. If the project consists of multiple source files
910 then all the source file should be compiled with the same -callee-saves
911 option string. Also see Pragma Directive CALLEE-SAVES.</dd>
912 <dt><b><b>-debug</b></b></dt>
913 <dd>When this option is used the compiler will generate
914 debug information, that can be used with the SDCDB. The debug information
915 is collected in a file with .cdb extension. For more information see
916 documentation for SDCDB.</dd>
917 <dt><b><b><em>-regextend</em></b></b></dt>
918 <dd> <em>This option is obsolete and isn't
919 supported anymore.</em></dd>
920 <dt><b><b><em>-noregparms</em></b></b></dt>
921 <dd><em>This option is obsolete and isn't
922 supported anymore.</em></dd>
923 <dt><b><b>-peep-file</b><filename></b></dt>
924 <dd>This option can be used to use additional
925 rules to be used by the peep hole optimizer. See section Peep Hole
926 optimizations for details on how to write these rules.</dd>
927 <dt><b><b>-S</b></b></dt>
928 <dd>Stop after the stage of compilation proper; do not assemble.
929 The output is an assembler code file for the input file specified.</dd>
930 <dt><b><b>-Wa_asmOption[,asmOption]</b>...</b></dt>
931 <dd>Pass the asmOption to
933 <dt><b><b>-Wl_linkOption[,linkOption]</b>...</b></dt>
934 <dd>Pass the linkOption
936 <dt><b><b>-int-long-reent</b></b></dt>
937 <dd> Integer (16 bit) and long (32 bit) libraries
938 have been compiled as reentrant. Note by default these libraries are
939 compiled as non-reentrant. See section Installation for more details.</dd>
940 <dt><b><b>-cyclomatic</b></b></dt>
941 <dd>This option will cause the compiler to generate
942 an information message for each function in the source file. The message
943 contains some <em>important</em> information about the function. The
944 number of edges and nodes the compiler detected in the control flow
945 graph of the function, and most importantly the <em>cyclomatic complexity</em>
946 see section on Cyclomatic Complexity for more details.</dd>
947 <dt><b><b>-float-reent</b></b></dt>
948 <dd> Floating point library is compiled as reentrant.See
949 section Installation for more details.</dd>
950 <dt><b><b>-nooverlay</b></b></dt>
951 <dd> The compiler will not overlay parameters and
952 local variables of any function, see section Parameters and local
953 variables for more details.</dd>
954 <dt><b><b>-main-return</b></b></dt>
955 <dd>This option can be used when the code generated
956 is called by a monitor program. The compiler will generate a 'ret'
957 upon return from the 'main' function. The default option is to lock
958 up i.e. generate a 'ljmp '.</dd>
959 <dt><b><b>-no-peep</b></b></dt>
960 <dd> Disable peep-hole optimization.</dd>
961 <dt><b><b>-peep-asm</b></b></dt>
962 <dd> Pass the inline assembler code through the peep
963 hole optimizer. This can cause unexpected changes to inline assembler
964 code, please go through the peephole optimizer rules defined in the
965 source file tree '<target>/peeph.def' before using this option.</dd>
966 <dt><b><b>-iram-size</b><Value></b></dt>
967 <dd>Causes the linker to check if the interal
968 ram usage is within limits of the given value.</dd>
969 <dt><b><b>-nostdincl</b></b></dt>
970 <dd>This will prevent the compiler from passing
971 on the default include path to the preprocessor.</dd>
972 <dt><b><b>-nostdlib</b></b></dt>
973 <dd>This will prevent the compiler from passing on
974 the default library path to the linker.</dd>
975 <dt><b><b>-verbose</b></b></dt>
976 <dd>Shows the various actions the compiler is performing.</dd>
977 <dt><b><b>-V</b></b></dt>
978 <dd>Shows the actual commands the compiler is executing.
983 <h4><a name="tth_sEc3.2.8">
984 3.2.8</a> Intermediate Dump Options</h4>
987 The following options are provided for the purpose of retargetting
988 and debugging the compiler. These provided a means to dump the intermediate
989 code (iCode) generated by the compiler in human readable form at various
990 stages of the compilation process.
994 <dl compact="compact">
999 <dt><b><b>-dumpraw</b></b></dt>
1000 <dd>This option will cause the compiler to dump the
1001 intermediate code into a file of named <em><source filename>.dumpraw</em>
1002 just after the intermediate code has been generated for a function,
1003 i.e. before any optimizations are done. The basic blocks at this stage
1004 ordered in the depth first number, so they may not be in sequence
1006 <dt><b><b>-dumpgcse</b></b></dt>
1007 <dd>Will create a dump of iCode's, after global subexpression
1008 elimination, into a file named <em><source filename>.dumpgcse.</em></dd>
1009 <dt><b><b>-dumpdeadcode</b></b></dt>
1010 <dd>Will create a dump of iCode's, after deadcode
1011 elimination, into a file named <em><source filename>.dumpdeadcode.</em></dd>
1012 <dt><b><b>-dumploop</b></b></dt>
1013 <dd>Will create a dump of iCode's, after loop optimizations,
1014 into a file named <em><source filename>.dumploop.</em></dd>
1015 <dt><b><b>-dumprange</b></b></dt>
1016 <dd>Will create a dump of iCode's, after live range
1017 analysis, into a file named <em><source filename>.dumprange.</em></dd>
1018 <dt><b><b>-dumlrange</b></b></dt>
1019 <dd>Will dump the life ranges for all symbols.</dd>
1020 <dt><b><b>-dumpregassign</b></b></dt>
1021 <dd>Will create a dump of iCode's, after register
1022 assignment, into a file named <em><source filename>.dumprassgn.</em></dd>
1023 <dt><b><b>-dumplrange</b></b></dt>
1024 <dd>Will create a dump of the live ranges of iTemp's</dd>
1025 <dt><b><b>-dumpall</b></b></dt>
1026 <dd>Will cause all the above mentioned dumps to be
1032 <h3><a name="tth_sEc3.3">
1033 3.3</a> MCS51/DS390 Storage Class Language Extensions</h3>
1036 In addition to the ANSI storage classes SDCC allows the following
1037 MCS51 specific storage classes.
1040 <h4><a name="tth_sEc3.3.1">
1041 3.3.1</a> xdata</h4>
1044 Variables declared with this storage class will be placed in the extern
1045 RAM. This is the <b>default</b> storage class for Large Memory model,
1048 <tt>xdata unsigned char xduc;</tt>
1051 <h4><a name="tth_sEc3.3.2">
1052 3.3.2</a> data</h4>
1055 This is the <b>default</b> storage class for Small Memory model.
1056 Variables declared with this storage class will be allocated in the
1057 internal RAM, e.g.:<br />
1059 <tt>data int iramdata;</tt>
1062 <h4><a name="tth_sEc3.3.3">
1063 3.3.3</a> idata</h4>
1066 Variables declared with this storage class will be allocated into
1067 the indirectly addressable portion of the internal ram of a 8051,
1070 <tt>idata int idi;</tt>
1073 <h4><a name="tth_sEc3.3.4">
1074 3.3.4</a> bit</h4>
1077 This is a data-type and a storage class specifier. When a variable
1078 is declared as a bit, it is allocated into the bit addressable memory
1079 of 8051, e.g.:<br />
1084 <h4><a name="tth_sEc3.3.5">
1085 3.3.5</a> sfr / sbit</h4>
1088 Like the bit keyword, <em>sfr / sbit</em> signifies both a data-type
1089 and storage class, they are used to describe the special function
1090 registers and special bit variables of a 8051, eg:<br />
1092 <tt>sfr at 0x80 P0; /* special function register P0 at location
1093 0x80 */</tt> <br />
1094 <tt>sbit at 0xd7 CY; /* CY (Carry Flag) */</tt>
1097 <h3><a name="tth_sEc3.4">
1098 3.4</a> Pointers</h3>
1101 SDCC allows (via language extensions) pointers to explicitly point
1102 to any of the memory spaces of the 8051. In addition to the explicit
1103 pointers, the compiler also allows a <em>_generic</em> class of pointers
1104 which can be used to point to any of the memory spaces.<br />
1106 Pointer declaration examples:<br />
1107 <font size="-1"></font><br />
1108 <tt>/* pointer physically in xternal ram pointing to object
1109 in internal ram */ </tt> <br />
1110 <tt>data unsigned char * xdata p;</tt> <br />
1111 <tt></tt> <br />
1112 <tt>/* pointer physically in code rom pointing to data in xdata
1113 space */ </tt> <br />
1114 <tt>xdata unsigned char * code p;</tt> <br />
1115 <tt></tt> <br />
1116 <tt>/* pointer physically in code space pointing to data in
1117 code space */ </tt> <br />
1118 <tt>code unsigned char * code p;</tt> <br />
1119 <tt></tt> <br />
1120 <tt>/* the folowing is a generic pointer physically located
1121 in xdata space */</tt> <br />
1122 <tt>char * xdata p;</tt><font size="-1"></font><br />
1123 <font size="-1"></font><br />
1124 Well you get the idea. <br />
1126 <em>For compatibility with the previous version of the compiler,
1127 the following syntax for pointer declaration is still supported but
1128 will disappear int the near future. </em><br />
1130 <tt><em>unsigned char _xdata *ucxdp; /* pointer to data
1131 in external ram */ </em></tt> <br />
1132 <tt><em>unsigned char _data *ucdp ; /* pointer to data
1133 in internal ram */ </em></tt> <br />
1134 <tt><em>unsigned char _code *uccp ; /* pointer to data
1135 in R/O code space */</em></tt> <br />
1136 <tt><em>unsigned char _idata *uccp; /* pointer to upper
1137 128 bytes of ram */</em></tt><font size="-1"></font><br />
1138 <font size="-1"></font><br />
1139 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
1140 <em>generic</em> pointers. These type of pointers can also to be explicitly
1143 <tt>unsigned char _generic *ucgp;</tt><font size="-1"></font><br />
1144 <font size="-1"></font><br />
1145 The highest order byte of the <em>generic</em> pointers contains the
1146 data space information. Assembler support routines are called whenever
1147 data is stored or retrieved using <em>generic</em> pointers. These are
1148 useful for developing reusable library routines. Explicitly specifying
1149 the pointer type will generate the most efficient code. Pointers declared
1150 using a mixture of OLD and NEW style could have unpredictable results.
1153 <h3><a name="tth_sEc3.5">
1154 3.5</a> Parameters & Local Variables</h3>
1157 Automatic (local) variables and parameters to functions can either
1158 be placed on the stack or in data-space. The default action of the
1159 compiler is to place these variables in the internal RAM (for small
1160 model) or external RAM (for Large model). This in fact makes them
1161 <em>static</em> so by default functions are non-reentrant.
1164 They can be placed on the stack either by using the <em>-stack-auto</em>
1165 compiler option or by using the <em>reentrant</em> keyword in the function
1166 declaration, e.g.:<br />
1167 <font size="-1"></font><br />
1168 <tt>unsigned char foo(char i) reentrant </tt> <br />
1169 <tt>{ </tt> <br />
1170 <tt>... </tt> <br />
1171 <tt>}</tt> <br />
1173 Since stack space on 8051 is limited, the <em>reentrant</em> keyword
1174 or the <em>-stack-auto</em> option should be used sparingly. Note that
1175 the reentrant keyword just means that the parameters & local variables
1176 will be allocated to the stack, it <em>does not</em> mean that the function
1177 is register bank independent.<br />
1179 Local variables can be assigned storage classes and absolute addresses,
1182 <tt>unsigned char foo() {</tt> <br />
1183 <tt> xdata unsigned char i;</tt> <br />
1184 <tt> bit bvar;</tt> <br />
1185 <tt> data at 0x31 unsiged char j;</tt> <br />
1186 <tt> ... </tt> <br />
1187 <tt>}</tt> <br />
1188 <tt></tt> <br />
1189 In the above example the variable <em>i</em> will be allocated in the
1190 external ram, <em>bvar</em> in bit addressable space and <em>j</em> in
1191 internal ram. When compiled with <em>-stack-auto</em> or when a function
1192 is declared as <em>reentrant</em> this can only be done for static variables.
1195 Parameters however are not allowed any storage class, (storage classes
1196 for parameters will be ignored), their allocation is governed by the
1197 memory model in use, and the reentrancy options.
1200 <h3><a name="tth_sEc3.6">
1201 3.6</a> Overlaying</h3>
1204 For non-reentrant functions SDCC will try to reduce internal ram space
1205 usage by overlaying parameters and local variables of a function (if
1206 possible). Parameters and local variables of a function will be allocated
1207 to an overlayable segment if the function has <em>no other function
1208 calls and the function is non-reentrant and the memory model is small.</em>
1209 If an explicit storage class is specified for a local variable, it
1210 will NOT be overlayed.
1213 Note that the compiler (not the linkage editor) makes the decision
1214 for overlaying the data items. Functions that are called from an interrupt
1215 service routine should be preceded by a #pragma NOOVERLAY if they
1219 Also note that the compiler does not do any processing of inline assembler
1220 code, so the compiler might incorrectly assign local variables and
1221 parameters of a function into the overlay segment if the inline assembler
1222 code calls other c-functions that might use the overlay. In that case
1223 the #pragma NOOVERLAY should be used.
1226 Parameters and Local variables of functions that contain 16 or 32
1227 bit multiplication or division will NOT be overlayed since these are
1228 implemented using external functions, e.g.:<br />
1230 <tt>#pragma SAVE </tt> <br />
1231 <tt>#pragma NOOVERLAY </tt> <br />
1232 <tt>void set_error(unsigned char errcd) </tt> <br />
1233 <tt>{</tt> <br />
1234 <tt> P3 = errcd;</tt> <br />
1235 <tt>} </tt> <br />
1236 <tt>#pragma RESTORE </tt> <br />
1237 <tt></tt> <br />
1238 <tt>void some_isr () interrupt 2 using 1 </tt> <br />
1239 <tt>{</tt> <br />
1240 <tt> ...</tt> <br />
1241 <tt> set_error(10);</tt> <br />
1242 <tt> ... </tt> <br />
1243 <tt>}</tt> <br />
1244 <tt></tt> <br />
1245 In the above example the parameter <em>errcd</em> for the function <em>set_error</em>
1246 would be assigned to the overlayable segment if the #pragma NOOVERLAY
1247 was not present, this could cause unpredictable runtime behavior when
1248 called from an ISR. The #pragma NOOVERLAY ensures that the parameters
1249 and local variables for the function are NOT overlayed.
1252 <h3><a name="tth_sEc3.7">
1253 3.7</a> Interrupt Service Routines</h3>
1256 SDCC allows interrupt service routines to be coded in C, with some
1257 extended keywords.<br />
1259 <tt>void timer_isr (void) interrupt 2 using 1 </tt> <br />
1260 <tt>{ </tt> <br />
1261 <tt>.. </tt> <br />
1262 <tt>}</tt> <br />
1263 <tt></tt> <br />
1264 The number following the <em>interrupt</em> keyword is the interrupt
1265 number this routine will service. The compiler will insert a call
1266 to this routine in the interrupt vector table for the interrupt number
1267 specified. The <em>using</em> keyword is used to tell the compiler to
1268 use the specified register bank (8051 specific) when generating code
1269 for this function. Note that when some function is called from an
1270 interrupt service routine it should be preceded by a <em>#pragma
1271 NOOVERLAY</em> if it is not reentrant. A special note here, int (16 bit)
1272 and long (32 bit) integer division, multiplication & modulus operations
1273 are implemented using external support routines developed in ANSI-C,
1274 if an interrupt service routine needs to do any of these operations
1275 then the support routines (as mentioned in a following section) will
1276 have to be recompiled using the <em>-stack-auto</em> option and the
1277 source file will need to be compiled using the <em>-int-long-ren</em>t
1281 If you have multiple source files in your project, interrupt service
1282 routines can be present in any of them, but a prototype of the isr
1283 MUST be present or included in the file that contains the function
1287 Interrupt Numbers and the corresponding address & descriptions for
1288 the Standard 8051 are listed below. SDCC will automatically adjust
1289 the interrupt vector table to the maximum interrupt number specified.<br />
1294 <tr><td align="center">Interrupt #</td><td align="center">Description</td><td align="center">Vector Address</td></tr><tr><td>
1295 <tr><td align="center">0</td><td align="center">External 0</td><td align="center">0x0003</td></tr>
1296 <tr><td align="center">1</td><td align="center">Timer 0</td><td align="center">0x000B</td></tr>
1297 <tr><td align="center">2</td><td align="center">External 1</td><td align="center">0x0013</td></tr>
1298 <tr><td align="center">3</td><td align="center">Timer 1</td><td align="center">0x001B</td></tr>
1299 <tr><td align="center">4</td><td align="center">Serial</td><td align="center">0x0023</td></tr></table>
1302 If the interrupt service routine is defined without <em>using</em> a
1303 register bank or with register bank 0 (using 0), the compiler will
1304 save the registers used by itself on the stack upon entry and restore
1305 them at exit, however if such an interrupt service routine calls another
1306 function then the entire register bank will be saved on the stack.
1307 This scheme may be advantageous for small interrupt service routines
1308 which have low register usage.
1311 If the interrupt service routine is defined to be using a specific
1312 register bank then only <em>a, b & dptr</em> are save and restored,
1313 if such an interrupt service routine calls another function (using
1314 another register bank) then the entire register bank of the called
1315 function will be saved on the stack. This scheme is recommended for
1316 larger interrupt service routines.
1319 Calling other functions from an interrupt service routine is not recommended,
1320 avoid it if possible.<br />
1322 Also see the _naked modifier.
1325 <h3><a name="tth_sEc3.8">
1326 3.8</a> Critical Functions</h3>
1329 A special keyword may be associated with a function declaring it as
1330 <em>critical</em>. SDCC will generate code to disable all interrupts
1331 upon entry to a critical function and enable them back before returning.
1332 Note that nesting critical functions may cause unpredictable results.<br />
1333 <font size="-1"></font><br />
1334 <tt>int foo () critical </tt> <br />
1335 <tt>{ </tt> <br />
1336 <tt>... </tt> <br />
1337 <tt>... </tt> <br />
1338 <tt>}</tt> <br />
1340 The critical attribute maybe used with other attributes like <em>reentrant.</em>
1343 <h3><a name="tth_sEc3.9">
1344 3.9</a> Naked Functions</h3>
1347 A special keyword may be associated with a function declaring it as
1348 <em>_naked.</em> The <em>_naked</em> function modifier attribute prevents
1349 the compiler from generating prologue and epilogue code for that function.
1350 This means that the user is entirely responsible for such things as
1351 saving any registers that may need to be preserved, selecting the
1352 proper register bank, generating the <em>return</em> instruction at
1353 the end, etc. Practically, this means that the contents of the function
1354 must be written in inline assembler. This is particularly useful for
1355 interrupt functions, which can have a large (and often unnecessary)
1356 prologue/epilogue. For example, compare the code generated by these
1357 two functions:<br />
1359 <tt>data unsigned char counter;</tt> <br />
1360 <tt>void simpleInterrupt(void) interrupt 1</tt> <br />
1361 <tt>{</tt> <br />
1362 <tt> counter++;</tt> <br />
1363 <tt>}</tt> <br />
1364 <tt></tt> <br />
1365 <tt>void nakedInterrupt(void) interrupt 2 _naked</tt> <br />
1366 <tt>{</tt> <br />
1367 <tt> _asm</tt> <br />
1368 <tt> inc _counter</tt> <br />
1369 <tt> reti ; MUST explicitly include ret in _naked
1370 function.</tt> <br />
1371 <tt> _endasm;</tt> <br />
1374 For an 8051 target, the generated simpleInterrupt looks like:<br />
1376 <tt>_simpleIterrupt:</tt> <br />
1377 <tt> push acc</tt> <br />
1378 <tt> push b</tt> <br />
1379 <tt> push dpl</tt> <br />
1380 <tt> push dph</tt> <br />
1381 <tt> push psw</tt> <br />
1382 <tt> mov psw,#0x00</tt> <br />
1383 <tt> inc _counter</tt> <br />
1384 <tt> pop psw</tt> <br />
1385 <tt> pop dph</tt> <br />
1386 <tt> pop dpl</tt> <br />
1387 <tt> pop b</tt> <br />
1388 <tt> pop acc</tt> <br />
1389 <tt> reti</tt><br />
1391 whereas nakedInterrupt looks like:<br />
1393 <tt>_nakedInterrupt:</tt> <br />
1394 <tt> inc _counter</tt> <br />
1395 <tt> reti ; MUST explicitly include ret(i) in _naked
1396 function.</tt><br />
1398 While there is nothing preventing you from writing C code inside a
1399 _naked function, there are many ways to shoot yourself in the foot
1400 doing this, and is is recommended that you stick to inline assembler.
1403 <h3><a name="tth_sEc3.10">
1404 3.10</a> Functions using private banks</h3>
1407 The <em>using</em> attribute (which tells the compiler to use a register
1408 bank other than the default bank zero) should only be applied to <em>interrupt</em>
1409 functions (see note 1 below). This will in most circumstances make
1410 the generated ISR code more efficient since it will not have to save
1411 registers on the stack.
1414 The <em>using</em> attribute will have no effect on the generated code
1415 for a <em>non-interrupt</em> function (but may occasionally be useful
1416 anyway<a href="#tthFtNtAAB" name="tthFrefAAB"><sup>1</sup></a>).<br />
1417 <em>(pending: I don't think this has been done yet)</em>
1420 An <em>interrupt</em> function using a non-zero bank will assume that
1421 it can trash that register bank, and will not save it. Since high-priority
1422 interrupts can interrupt low-priority ones on the 8051 and friends,
1423 this means that if a high-priority ISR <em>using</em> a particular bank
1424 occurs while processing a low-priority ISR <em>using</em> the same bank,
1425 terrible and bad things can happen. To prevent this, no single register
1426 bank should be <em>used</em> by both a high priority and a low priority
1427 ISR. This is probably most easily done by having all high priority
1428 ISRs use one bank and all low priority ISRs use another. If you have
1429 an ISR which can change priority at runtime, you're on your own: I
1430 suggest using the default bank zero and taking the small performance
1434 It is most efficient if your ISR calls no other functions. If your
1435 ISR must call other functions, it is most efficient if those functions
1436 use the same bank as the ISR (see note 1 below); the next best is
1437 if the called functions use bank zero. It is very inefficient to call
1438 a function using a different, non-zero bank from an ISR.
1441 <h3><a name="tth_sEc3.11">
1442 3.11</a> Absolute Addressing</h3>
1445 Data items can be assigned an absolute address with the <em>at <address></em>
1446 keyword, in addition to a storage class, e.g.:<br />
1448 <tt>xdata at 0x8000 unsigned char PORTA_8255 ;</tt> <br />
1450 In the above example the PORTA_8255 will be allocated to the location
1451 0x8000 of the external ram. Note that this feature is provided to
1452 give the programmer access to <em>memory mapped</em> devices attached
1453 to the controller. The compiler does not actually reserve any space
1454 for variables declared in this way (they are implemented with an equate
1455 in the assembler). Thus it is left to the programmer to make sure
1456 there are no overlaps with other variables that are declared without
1457 the absolute address. The assembler listing file (.lst) and the linker
1458 output files (.rst) and (.map) are a good places to look for such
1461 Absolute address can be specified for variables in all storage classes,
1464 <tt>bit at 0x02 bvar;</tt> <br />
1465 <tt></tt> <br />
1466 The above example will allocate the variable at offset 0x02 in the
1467 bit-addressable space. There is no real advantage to assigning absolute
1468 addresses to variables in this manner, unless you want strict control
1469 over all the variables allocated.
1472 <h3><a name="tth_sEc3.12">
1473 3.12</a> Startup Code</h3>
1476 The compiler inserts a call to the C routine <em>_sdcc__external__startup()</em>
1477 at the start of the CODE area. This routine is in the runtime library.
1478 By default this routine returns 0, if this routine returns a non-zero
1479 value, the static & global variable initialization will be skipped
1480 and the function main will be invoked Other wise static & global
1481 variables will be initialized before the function main is invoked.
1482 You could add a <em>_sdcc__external__startup()</em> routine to
1483 your program to override the default if you need to setup hardware
1484 or perform some other critical operation prior to static & global
1485 variable initialization.
1488 <h3><a name="tth_sEc3.13">
1489 3.13</a> Inline Assembler Code</h3>
1492 SDCC allows the use of in-line assembler with a few restriction as
1493 regards labels. All labels defined within inline assembler code <em>has
1494 to be</em> of the form <em>nnnnn$</em> where nnnn is a number less than
1495 100 (which implies a limit of utmost 100 inline assembler labels <em>per
1496 function</em> ). It is strongly recommended that each assembly
1497 instruction (including labels) be placed in a separate line (as the
1498 example shows). When the <em>-peep-asm</em> command line option is
1499 used, the inline assembler code will be passed through the peephole
1500 optimizer. This might cause some unexpected changes in the inline
1501 assembler code. Please go throught the peephole optimizer rules defined
1502 in file <em>SDCCpeeph.def</em> carefully before using this option.<br />
1504 <tt>_asm </tt> <br />
1505 <tt> mov b,#10 </tt> <br />
1506 <tt>00001$: </tt> <br />
1507 <tt> djnz b,00001$ </tt> <br />
1508 <tt>_endasm ;</tt><font size="-1"></font><br />
1509 <font size="-1"></font><br />
1510 The inline assembler code can contain any valid code understood by
1511 the assembler, this includes any assembler directives and comment
1512 lines. The compiler does not do any validation of the code within
1513 the <tt>_asm ... _endasm;</tt> keyword pair. <br />
1515 Inline assembler code cannot reference any C-Labels, however it can
1516 reference labels defined by the inline assembler, e.g.:<br />
1518 <tt>foo() { </tt> <br />
1519 <tt> /* some c code */ </tt> <br />
1520 <tt> _asm </tt> <br />
1521 <tt> ; some assembler code </tt> <br />
1522 <tt> ljmp $0003 </tt> <br />
1523 <tt> _endasm; </tt> <br />
1524 <tt> /* some more c code */ </tt> <br />
1525 <tt>clabel: /* inline assembler cannot reference this label
1526 */ </tt> <br />
1527 <tt> _asm</tt> <br />
1528 <tt> $0003: ;label (can be reference by inline assembler
1529 only) </tt> <br />
1530 <tt> _endasm ; </tt> <br />
1531 <tt> /* some more c code */</tt> <br />
1532 <tt>}</tt> <br />
1533 <tt></tt> <br />
1534 In other words inline assembly code can access labels defined in inline
1535 assembly within the scope of the funtion.
1538 The same goes the other way, ie. labels defines in inline assembly
1539 CANNOT be accessed by C statements.
1542 <h3><a name="tth_sEc3.14">
1543 3.14</a> int(16 bit) and long (32 bit) Support</h3>
1546 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
1547 multiplication and modulus operations are implemented by support routines.
1548 These support routines are all developed in ANSI-C to facilitate porting
1549 to other MCUs, although some model specific assembler optimations
1550 are used. The following files contain the described routine, all of
1551 them can be found in <installdir>/share/sdcc/lib.<br />
1553 _mulsint.c - signed 16 bit multiplication (calls _muluint)<br />
1554 _muluint.c - unsigned 16 bit multiplication<br />
1555 _divsint.c - signed 16 bit division (calls _divuint)<br />
1556 _divuint.c - unsigned 16 bit division<br />
1557 _modsint.c - signed 16 bit modulus (call _moduint)<br />
1558 _moduint.c - unsigned 16 bit modulus<br />
1559 _mulslong.c - signed 32 bit multiplication (calls _mululong)<br />
1560 _mululong.c - unsigned32 bit multiplication<br />
1561 _divslong.c - signed 32 division (calls _divulong)<br />
1562 _divulong.c - unsigned 32 division<br />
1563 _modslong.c - signed 32 bit modulus (calls _modulong)<br />
1564 _modulong.c - unsigned 32 bit modulus <font size="-2"></font><br />
1565 <font size="-2"></font><br />
1566 Since they are compiled as <em>non-reentrant</em>, interrupt service
1567 routines should not do any of the above operations. If this is unavoidable
1568 then the above routines will need to be compiled with the <em>-stack-auto</em>
1569 option, after which the source program will have to be compiled with
1570 <em>-int-long-rent</em> option.
1573 <h3><a name="tth_sEc3.15">
1574 3.15</a> Floating Point Support</h3>
1577 SDCC supports IEEE (single precision 4bytes) floating point numbers.The
1578 floating point support routines are derived from gcc's floatlib.c
1579 and consists of the following routines:<br />
1581 _fsadd.c - add floating point numbers<br />
1582 _fssub.c - subtract floating point numbers<br />
1583 _fsdiv.c - divide floating point numbers<br />
1584 _fsmul.c - multiply floating point numbers<br />
1585 _fs2uchar.c - convert floating point to unsigned char<br />
1586 _fs2char.c - convert floating point to signed char<br />
1587 _fs2uint.c - convert floating point to unsigned int<br />
1588 _fs2int.c - convert floating point to signed int<br />
1589 _fs2ulong.c - convert floating point to unsigned long<br />
1590 _fs2long.c - convert floating point to signed long<br />
1591 _uchar2fs.c - convert unsigned char to floating point<br />
1592 _char2fs.c - convert char to floating point number<br />
1593 _uint2fs.c - convert unsigned int to floating point<br />
1594 _int2fs.c - convert int to floating point numbers<br />
1595 _ulong2fs.c - convert unsigned long to floating point number<br />
1596 _long2fs.c - convert long to floating point number<font size="-2"></font><br />
1597 <font size="-2"></font><br />
1598 Note if all these routines are used simultaneously the data space
1599 might overflow. For serious floating point usage it is strongly recommended
1600 that the large model be used.
1603 <h3><a name="tth_sEc3.16">
1604 3.16</a> MCS51 Memory Models</h3>
1607 SDCC allows two memory models for MCS51 code, small and large. Modules
1608 compiled with different memory models should <em>never</em> be combined
1609 together or the results would be unpredictable. The library routines
1610 supplied with the compiler are compiled as both small and large. The
1611 compiled library modules are contained in seperate directories as
1612 small and large so that you can link to either set.
1615 When the large model is used all variables declared without a storage
1616 class will be allocated into the external ram, this includes all parameters
1617 and local variables (for non-reentrant functions). When the small
1618 model is used variables without storage class are allocated in the
1622 Judicious usage of the processor specific storage classes and the
1623 'reentrant' function type will yield much more efficient code, than
1624 using the large model. Several optimizations are disabled when the
1625 program is compiled using the large model, it is therefore strongly
1626 recommdended that the small model be used unless absolutely required.
1629 <h3><a name="tth_sEc3.17">
1630 3.17</a> DS390 Memory Models</h3>
1633 The only model supported is Flat 24. This generates code for the 24
1634 bit contiguous addressing mode of the Dallas DS80C390 part. In this
1635 mode, up to four meg of external RAM or code space can be directly
1636 addressed. See the data sheets at www.dalsemi.com for further information
1639 In older versions of the compiler, this option was used with the MCS51
1640 code generator (<em>-mmcs51</em>). Now, however, the '390 has it's own
1641 code generator, selected by the <em>-mds390</em> switch. <br />
1643 Note that the compiler does not generate any code to place the processor
1644 into 24 bitmode (although <em>tinibios</em> in the ds390 libraries will
1645 do that for you). If you don't use <em>tinibios</em>, the boot loader
1646 or similar code must ensure that the processor is in 24 bit contiguous
1647 addressing mode before calling the SDCC startup code.<br />
1649 Like the <em>-model-large</em> option, variables will by default be
1650 placed into the XDATA segment. <br />
1652 Segments may be placed anywhere in the 4 meg address space using the
1653 usual -*-loc options. Note that if any segments are located above
1654 64K, the -r flag must be passed to the linker to generate the proper
1655 segment relocations, and the Intel HEX output format must be used.
1656 The -r flag can be passed to the linker by using the option <em>-Wl-r</em>
1657 on the sdcc command line. However, currently the linker can not handle
1658 code segments > 64k.
1661 <h3><a name="tth_sEc3.18">
1662 3.18</a> Defines Created by the Compiler</h3>
1665 The compiler creates the following #defines.
1670 <li> SDCC - this Symbol is always defined.</li>
1672 <li> SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model
1673 used (e.g.: -mds390)</li>
1675 <li> __mcs51 or __ds390 or __z80, etc - depending on the model used
1678 <li> SDCC_STACK_AUTO - this symbol is defined when <em>-stack-auto</em>
1679 option is used.</li>
1681 <li> SDCC_MODEL_SMALL - when <em>-model-small</em> is used.</li>
1683 <li> SDCC_MODEL_LARGE - when <em>-model-large</em> is used.</li>
1685 <li> SDCC_USE_XSTACK - when <em>-xstack</em> option is used.</li>
1687 <li> SDCC_STACK_TENBIT - when <em>-mds390</em> is used</li>
1689 <li> SDCC_MODEL_FLAT24 - when <em>-mds390</em> is used</li>
1693 <h2><a name="tth_sEc4">
1694 4</a> SDCC Technical Data</h2>
1697 <h3><a name="tth_sEc4.1">
1698 4.1</a> Optimizations</h3>
1701 SDCC performs a host of standard optimizations in addition to some
1702 MCU specific optimizations.
1705 <h4><a name="tth_sEc4.1.1">
1706 4.1.1</a> Sub-expression Elimination</h4>
1709 The compiler does local and global common subexpression elimination,
1712 <tt>i = x + y + 1; </tt> <br />
1713 <tt>j = x + y;</tt><br />
1715 will be translated to<br />
1717 <tt>iTemp = x + y </tt> <br />
1718 <tt>i = iTemp + 1 </tt> <br />
1719 <tt>j = iTemp</tt> <br />
1721 Some subexpressions are not as obvious as the above example, e.g.:<br />
1723 <tt>a->b[i].c = 10; </tt> <br />
1724 <tt>a->b[i].d = 11;</tt><br />
1726 In this case the address arithmetic a->b[i] will be computed only
1727 once; the equivalent code in C would be.<br />
1729 <tt>iTemp = a->b[i]; </tt> <br />
1730 <tt>iTemp.c = 10; </tt> <br />
1731 <tt>iTemp.d = 11;</tt><br />
1733 The compiler will try to keep these temporary variables in registers.
1736 <h4><a name="tth_sEc4.1.2">
1737 4.1.2</a> Dead-Code Elimination</h4>
1740 <tt>int global; </tt> <br />
1741 <tt>void f () { </tt> <br />
1742 <tt> int i; </tt> <br />
1743 <tt> i = 1; /* dead store */ </tt> <br />
1744 <tt> global = 1; /* dead store */ </tt> <br />
1745 <tt> global = 2; </tt> <br />
1746 <tt> return; </tt> <br />
1747 <tt> global = 3; /* unreachable */ </tt> <br />
1750 will be changed to<br />
1752 <tt>int global; void f () </tt> <br />
1753 <tt>{</tt> <br />
1754 <tt> global = 2; </tt> <br />
1755 <tt> return; </tt> <br />
1759 <h4><a name="tth_sEc4.1.3">
1760 4.1.3</a> Copy-Propagation</h4>
1763 <tt>int f() { </tt> <br />
1764 <tt> int i, j; </tt> <br />
1765 <tt> i = 10; </tt> <br />
1766 <tt> j = i; </tt> <br />
1767 <tt> return j; </tt> <br />
1770 will be changed to <br />
1772 <tt>int f() { </tt> <br />
1773 <tt> int i,j; </tt> <br />
1774 <tt> i = 10; </tt> <br />
1775 <tt> j = 10; </tt> <br />
1776 <tt> return 10; </tt> <br />
1777 <tt>}</tt> <br />
1778 <tt></tt> <br />
1779 Note: the dead stores created by this copy propagation will be eliminated
1780 by dead-code elimination.
1783 <h4><a name="tth_sEc4.1.4">
1784 4.1.4</a> Loop Optimizations</h4>
1787 Two types of loop optimizations are done by SDCC loop invariant lifting
1788 and strength reduction of loop induction variables. In addition to
1789 the strength reduction the optimizer marks the induction variables
1790 and the register allocator tries to keep the induction variables in
1791 registers for the duration of the loop. Because of this preference
1792 of the register allocator, loop induction optimization causes an increase
1793 in register pressure, which may cause unwanted spilling of other temporary
1794 variables into the stack / data space. The compiler will generate
1795 a warning message when it is forced to allocate extra space either
1796 on the stack or data space. If this extra space allocation is undesirable
1797 then induction optimization can be eliminated either for the entire
1798 source file (with -noinduction option) or for a given function only
1799 (#pragma NOINDUCTION).<br />
1801 Loop Invariant:<br />
1803 <tt>for (i = 0 ; i < 100 ; i ++) </tt> <br />
1804 <tt> f += k + l;</tt><br />
1808 <tt>itemp = k + l; </tt> <br />
1809 <tt>for (i = 0; i < 100; i++) </tt> <br />
1810 <tt> f += itemp;</tt><br />
1812 As mentioned previously some loop invariants are not as apparent,
1813 all static address computations are also moved out of the loop.<br />
1815 Strength Reduction, this optimization substitutes an expression by
1816 a cheaper expression:<br />
1818 <tt>for (i=0;i < 100; i++)</tt> <br />
1819 <tt> ar[i*5] = i*3;</tt><br />
1823 <tt>itemp1 = 0; </tt> <br />
1824 <tt>itemp2 = 0; </tt> <br />
1825 <tt>for (i=0;i< 100;i++) { </tt> <br />
1826 <tt> ar[itemp1] = itemp2; </tt> <br />
1827 <tt> itemp1 += 5; </tt> <br />
1828 <tt> itemp2 += 3; </tt> <br />
1831 The more expensive multiplication is changed to a less expensive addition.
1834 <h4><a name="tth_sEc4.1.5">
1835 4.1.5</a> Loop Reversing</h4>
1838 This optimization is done to reduce the overhead of checking loop
1839 boundaries for every iteration. Some simple loops can be reversed
1840 and implemented using a ``decrement and jump if not zero'' instruction.
1841 SDCC checks for the following criterion to determine if a loop is
1842 reversible (note: more sophisticated compilers use data-dependency
1843 analysis to make this determination, SDCC uses a more simple minded
1849 <li> The 'for' loop is of the form <br />
1851 <tt>for (<symbol> = <expression> ; <sym> [< | <=] <expression>
1852 ; [<sym>++ | <sym> += 1])</tt> <br />
1853 <tt> <for body></tt></li>
1855 <li> The <for body> does not contain ``continue'' or 'break''.</li>
1857 <li> All goto's are contained within the loop.</li>
1859 <li> No function calls within the loop.</li>
1861 <li> The loop control variable <sym> is not assigned any value within the
1864 <li> The loop control variable does NOT participate in any arithmetic operation
1865 within the loop.</li>
1867 <li> There are NO switch statements in the loop.</li>
1869 Note djnz instruction can be used for 8-bit values <em>only</em>, therefore
1870 it is advantageous to declare loop control symbols as <em>char</em>.
1871 Ofcourse this may not be possible on all situations.
1874 <h4><a name="tth_sEc4.1.6">
1875 4.1.6</a> Algebraic Simplifications</h4>
1878 SDCC does numerous algebraic simplifications, the following is a small
1879 sub-set of these optimizations.<br />
1881 <tt>i = j + 0 ; /* changed to */ i = j; </tt> <br />
1882 <tt>i /= 2; /* changed to */ i > >= 1; </tt> <br />
1883 <tt>i = j - j ; /* changed to */ i = 0; </tt> <br />
1884 <tt>i = j / 1 ; /* changed to */ i = j;</tt><br />
1886 Note the subexpressions given above are generally introduced by macro
1887 expansions or as a result of copy/constant propagation.
1890 <h4><a name="tth_sEc4.1.7">
1891 4.1.7</a> 'switch' Statements</h4>
1894 SDCC changes switch statements to jump tables when the following conditions
1900 <li> The case labels are in numerical sequence, the labels need not be
1901 in order, and the starting number need not be one or zero.</li>
1903 <tt>switch(i) { switch (i)
1905 <tt>case 4:... case 1: ... </tt> <br />
1906 <tt>case 5:... case 2: ... </tt> <br />
1907 <tt>case 3:... case 3: ... </tt> <br />
1908 <tt>case 6:... case 4: ... </tt> <br />
1909 <tt>} }</tt> <br />
1910 <tt></tt> <br />
1911 Both the above switch statements will be implemented using a jump-table.
1916 <li> The number of case labels is at least three, since it takes two conditional
1917 statements to handle the boundary conditions.</li>
1919 <li> The number of case labels is less than 84, since each label takes
1920 3 bytes and a jump-table can be utmost 256 bytes long.</li>
1922 Switch statements which have gaps in the numeric sequence or those
1923 that have more that 84 case labels can be split into more than one
1924 switch statement for efficient code generation, e.g.:<br />
1926 <tt>switch (i) { </tt> <br />
1927 <tt>case 1: ... </tt> <br />
1928 <tt>case 2: ... </tt> <br />
1929 <tt>case 3: ... </tt> <br />
1930 <tt>case 4: ... </tt> <br />
1931 <tt>case 9: ... </tt> <br />
1932 <tt>case 10: ... </tt> <br />
1933 <tt>case 11: ... </tt> <br />
1934 <tt>case 12: ... </tt> <br />
1937 If the above switch statement is broken down into two switch statements<br />
1939 <tt>switch (i) { </tt> <br />
1940 <tt>case 1: ... </tt> <br />
1941 <tt>case 2: ... </tt> <br />
1942 <tt>case 3: ... </tt> <br />
1943 <tt>case 4: ... </tt> <br />
1944 <tt>}</tt> <br />
1945 <tt></tt> <br />
1946 and<tt></tt> <br />
1947 <tt></tt> <br />
1948 <tt>switch (i) { </tt> <br />
1949 <tt>case 9: ... </tt> <br />
1950 <tt>case 10: ... </tt> <br />
1951 <tt>case 11: ... </tt> <br />
1952 <tt>case 12: ... </tt> <br />
1953 <tt>}</tt> <br />
1954 <tt></tt> <br />
1955 then both the switch statements will be implemented using jump-tables
1956 whereas the unmodified switch statement will not be.
1959 <h4><a name="tth_sEc4.1.8">
1960 4.1.8</a> Bit-shifting Operations.</h4>
1963 Bit shifting is one of the most frequently used operation in embedded
1964 programming. SDCC tries to implement bit-shift operations in the most
1965 efficient way possible, e.g.:<br />
1967 unsigned char i;<br />
1969 i> >= 4; <br />
1972 generates the following code:<br />
1979 In general SDCC will never setup a loop if the shift count is known.
1980 Another example:<br />
1982 <tt>unsigned int i; </tt> <br />
1983 <tt>... </tt> <br />
1984 <tt>i > >= 9; </tt> <br />
1987 will generate:<br />
1989 <tt>mov a,(_i + 1) </tt> <br />
1990 <tt>mov (_i + 1),#0x00 </tt> <br />
1991 <tt>clr c </tt> <br />
1992 <tt>rrc a </tt> <br />
1993 <tt>mov _i,a</tt><br />
1995 Note that SDCC stores numbers in little-endian format (i.e. lowest
1999 <h4><a name="tth_sEc4.1.9">
2000 4.1.9</a> Bit-rotation</h4>
2003 A special case of the bit-shift operation is bit rotation, SDCC recognizes
2004 the following expression to be a left bit-rotation:<br />
2006 <tt>unsigned char i; </tt> <br />
2007 <tt>... </tt> <br />
2008 <tt>i = ((i < < 1) | (i > >
2012 will generate the following code:<br />
2014 <tt>mov a,_i </tt> <br />
2015 <tt>rl a </tt> <br />
2016 <tt>mov _i,a</tt><br />
2018 SDCC uses pattern matching on the parse tree to determine this operation.Variations
2019 of this case will also be recognized as bit-rotation, i.e.: <br />
2021 <tt>i = ((i > > 7) | (i < <
2022 1)); /* left-bit rotation */</tt>
2025 <h4><a name="tth_sEc4.1.10">
2026 4.1.10</a> Highest Order Bit</h4>
2029 It is frequently required to obtain the highest order bit of an integral
2030 type (long, int, short or char types). SDCC recognizes the following
2031 expression to yield the highest order bit and generates optimized
2032 code for it, e.g.:<br />
2034 <tt>unsigned int gint; </tt> <br />
2035 <tt></tt> <br />
2036 <tt>foo () { </tt> <br />
2037 <tt>unsigned char hob; </tt> <br />
2038 <tt> ... </tt> <br />
2039 <tt> hob = (gint > > 15) & 1; </tt> <br />
2040 <tt> .. </tt> <br />
2043 will generate the following code:<br />
2044 <tt></tt> <br />
2045 <tt> 61
2046 ; hob.c 7 </tt> <br />
2047 <tt> 000A E5*01 62
2048 mov a,(_gint + 1) </tt> <br />
2049 <tt> 000C 33 63
2050 rlc a </tt> <br />
2051 <tt> 000D E4 64
2052 clr a </tt> <br />
2053 <tt> 000E 13 65
2054 rrc a </tt> <br />
2055 <tt> 000F F5*02 66
2056 mov _foo_hob_1_1,a</tt> <br />
2057 <tt></tt> <br />
2058 Variations of this case however will <em>not</em> be recognized. It
2059 is a standard C expression, so I heartily recommend this be the only
2060 way to get the highest order bit, (it is portable). Of course it will
2061 be recognized even if it is embedded in other expressions, e.g.:<br />
2063 <tt>xyz = gint + ((gint > > 15) & 1);</tt><br />
2065 will still be recognized.
2068 <h4><a name="tth_sEc4.1.11">
2069 4.1.11</a> Peep-hole Optimizer</h4>
2072 The compiler uses a rule based, pattern matching and re-writing mechanism
2073 for peep-hole optimization. It is inspired by <em>copt</em> a peep-hole
2074 optimizer by Christopher W. Fraser (cwfraser@microsoft.com). A default
2075 set of rules are compiled into the compiler, additional rules may
2076 be added with the <em>-peep-file <filename></em> option. The rule language
2077 is best illustrated with examples.<br />
2079 <tt>replace { </tt> <br />
2080 <tt> mov %1,a </tt> <br />
2081 <tt> mov a,%1</tt> <br />
2082 <tt>} by {</tt> <br />
2083 <tt> mov %1,a</tt> <br />
2086 The above rule will change the following assembly sequence:<br />
2088 <tt> mov r1,a </tt> <br />
2089 <tt> mov a,r1</tt><br />
2093 <tt>mov r1,a</tt><br />
2095 Note: All occurrences of a <em>%n</em> (pattern variable) must denote
2096 the same string. With the above rule, the assembly sequence:<br />
2098 <tt> mov r1,a </tt> <br />
2099 <tt> mov a,r2</tt><br />
2101 will remain unmodified.<br />
2103 Other special case optimizations may be added by the user (via <em>-peep-file
2104 option</em>). E.g. some variants of the 8051 MCU allow only <tt>ajmp</tt>
2105 and <tt>acall</tt>. The following two rules will change all <tt>ljmp</tt>
2106 and <tt>lcall</tt> to <tt>ajmp</tt> and <tt>acall</tt><br />
2108 <tt>replace { lcall %1 } by { acall %1 } </tt> <br />
2109 <tt>replace { ljmp %1 } by { ajmp %1 }</tt><br />
2111 The <em>inline-assembler code</em> is also passed through the peep hole
2112 optimizer, thus the peephole optimizer can also be used as an assembly
2113 level macro expander. The rules themselves are MCU dependent whereas
2114 the rule language infra-structure is MCU independent. Peephole optimization
2115 rules for other MCU can be easily programmed using the rule language.<br />
2117 The syntax for a rule is as follows:<br />
2119 <tt>rule := replace [ restart ] '{' <assembly sequence> 'n'
2121 <tt> '}' by '{' 'n'
2123 <tt> <assembly
2124 sequence> 'n' </tt> <br />
2125 <tt> '}' [if <functionName>
2126 ] 'n' </tt> <br />
2128 <assembly sequence> := assembly instruction (each instruction including
2129 labels must be on a separate line).<br />
2131 The optimizer will apply to the rules one by one from the top in the
2132 sequence of their appearance, it will terminate when all rules are
2133 exhausted. If the 'restart' option is specified, then the optimizer
2134 will start matching the rules again from the top, this option for
2135 a rule is expensive (performance), it is intended to be used in situations
2136 where a transformation will trigger the same rule again. A good example
2137 of this the following rule:<br />
2139 replace restart { <br />
2140 pop %1 <br />
2141 push %1 } by { <br />
2142 ; nop <br />
2145 Note that the replace pattern cannot be a blank, but can be a comment
2146 line. Without the 'restart' option only the inner most 'pop' 'push'
2147 pair would be eliminated, i.e.:<br />
2149 <tt> pop ar1 </tt> <br />
2150 <tt> pop ar2 </tt> <br />
2151 <tt> push ar2 </tt> <br />
2152 <tt> push ar1</tt><br />
2154 would result in:<br />
2156 <tt>pop ar1 </tt> <br />
2157 <tt>; nop </tt> <br />
2158 <tt>push ar1</tt><br />
2160 <em>with</em> the restart option the rule will be applied again to the
2161 resulting code and then all the pop-push pairs will be eliminated
2164 <tt>; nop </tt> <br />
2165 <tt>; nop</tt><br />
2167 A conditional function can be attached to a rule. Attaching rules
2168 are somewhat more involved, let me illustrate this with an example.<br />
2170 <tt>replace { </tt> <br />
2171 <tt> ljmp %5 </tt> <br />
2172 <tt>%2:} by { </tt> <br />
2173 <tt> sjmp %5 </tt> <br />
2174 <tt>%2:} if labelInRange</tt><br />
2176 The optimizer does a look-up of a function name table defined in function
2177 <em>callFuncByName</em> in the source file SDCCpeeph.c, with the name
2178 <em>labelInRange</em>. If it finds a corresponding entry the function
2179 is called. Note there can be no parameters specified for these functions,
2180 in this case the use of <em>%5</em> is crucial, since the function
2181 <em>labelInRange</em> expects to find the label in that particular variable
2182 (the hash table containing the variable bindings is passed as a parameter).
2183 If you want to code more such functions, take a close look at the
2184 function labelInRange and the calling mechanism in source file SDCCpeeph.c.
2185 I know this whole thing is a little kludgey, but maybe some day we
2186 will have some better means. If you are looking at this file, you
2187 will also see the default rules that are compiled into the compiler,
2188 you can add your own rules in the default set there if you get tired
2189 of specifying the -peep-file option.
2192 <h3><a name="tth_sEc4.2">
2193 4.2</a> Pragmas</h3>
2196 SDCC supports the following #pragma directives. This directives are
2197 applicable only at a function level.
2202 <li> SAVE - this will save all the current options.</li>
2204 <li> RESTORE - will restore the saved options from the last save. Note
2205 that SAVES & RESTOREs cannot be nested. SDCC uses the same buffer
2206 to save the options each time a SAVE is called.</li>
2208 <li> NOGCSE - will stop global subexpression elimination.</li>
2210 <li> NOINDUCTION - will stop loop induction optimizations.</li>
2212 <li> NOJTBOUND - will not generate code for boundary value checking, when
2213 switch statements are turned into jump-tables.</li>
2215 <li> NOOVERLAY - the compiler will not overlay the parameters and local
2216 variables of a function.</li>
2218 <li> NOLOOPREVERSE - Will not do loop reversal optimization</li>
2220 <li> EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma
2221 disables generation of pair of push/pop instruction in ISR function
2222 (using interrupt keyword). The directive should be placed immediately
2223 before the ISR function definition and it affects ALL ISR functions
2224 following it. To enable the normal register saving for ISR functions
2225 use ``#pragma EXCLUDE none''</li>
2227 <li> CALLEE-SAVES function1[,function2[,function3...]] - The compiler
2228 by default uses a caller saves convention for register saving across
2229 function calls, however this can cause unneccessary register pushing
2230 & popping when calling small functions from larger functions. This
2231 option can be used to switch the register saving convention for the
2232 function names specified. The compiler will not save registers when
2233 calling these functions, extra code will be generated at the entry
2234 & exit for these functions to save & restore the registers used
2235 by these functions, this can SUBSTANTIALLY reduce code & improve
2236 run time performance of the generated code. In future the compiler
2237 (with interprocedural analysis) will be able to determine the appropriate
2238 scheme to use for each function call. If -callee-saves command line
2239 option is used, the function names specified in #pragma CALLEE-SAVES
2240 is appended to the list of functions specified inthe command line.</li>
2242 The pragma's are intended to be used to turn-off certain optimizations
2243 which might cause the compiler to generate extra stack / data space
2244 to store compiler generated temporary variables. This usually happens
2245 in large functions. Pragma directives should be used as shown in the
2246 following example, they are used to control options & optimizations
2247 for a given function; pragmas should be placed before and/or after
2248 a function, placing pragma's inside a function body could have unpredictable
2255 #pragma SAVE /* save the current settings */ <br />
2256 #pragma NOGCSE /* turnoff global subexpression elimination */
2258 #pragma NOINDUCTION /* turn off induction optimizations */ <br />
2261 ... <br />
2262 /* large code */ <br />
2263 ... <br />
2265 #pragma RESTORE /* turn the optimizations back on */
2268 The compiler will generate a warning message when extra space is allocated.
2269 It is strongly recommended that the SAVE and RESTORE pragma's be used
2270 when changing options for a function.
2273 <h3><a name="tth_sEc4.3">
2274 4.3</a> Library Routines</h3>
2277 The following library routines are provided for your convenience.
2280 stdio.h - Contains the following functions printf & sprintf these
2281 routines are developed by Martijn van Balen <balen@natlab.research.philips.com>.
2284 %[flags][width][b|B|l|L]type
2287 flags: - left justify output in
2288 specified field width <br />
2289 + prefix output with
2290 +/- sign if output is signed type <br />
2291 space prefix output with a
2292 blank if it's a signed positive value <br />
2293 width: specifies minimum number
2294 of characters outputted for numbers <br />
2295 or strings. <br />
2296 - For numbers,
2297 spaces are added on the left when needed. <br />
2298 If width starts
2299 with a zero character, zeroes and used <br />
2300 instead of
2302 - For strings,
2303 spaces are are added on the left or right (when <br />
2304 flag '-' is
2305 used) when needed. <br />
2306 <br />
2307 b/B: byte argument (used
2308 by d, u, o, x, X) <br />
2309 l/L: long argument (used
2310 by d, u, o, x, X)<br />
2311 type: d decimal number <br />
2312 u unsigned decimal
2314 o unsigned octal number
2316 x unsigned hexadecimal
2317 number (0-9, a-f) <br />
2318 X unsigned hexadecimal
2319 number (0-9, A-F) <br />
2320 c character <br />
2321 s string (generic pointer)
2323 p generic pointer (I:data/idata,
2324 C:code, X:xdata, P:paged) <br />
2325 f float (still to be
2329 Also contains a very simple version of printf (printf_small). This
2330 simplified version of printf supports only the following formats.
2333 format output type argument-type <br />
2334 %d decimal short/int <br />
2335 %ld decimal long <br />
2336 %hd decimal char <br />
2337 %x hexadecimal short/int <br />
2338 %lx hexadecimal long <br />
2339 %hx hexadecimal char <br />
2340 %o octal short/int <br />
2341 %lo octal long <br />
2342 %ho octal char <br />
2343 %c character char <br />
2344 %s character _generic pointer
2347 The routine is very stack intesive, -stack-after-data parameter should
2348 be used when using this routine, the routine also takes about 1K of
2349 code space. It also expects an external function named putchar(char)
2350 to be present (this can be changed). When using the %s format the
2351 string / pointer should be cast to a generic pointer. eg.
2354 printf_small(``my str %s, my int %dn'',(char
2355 _generic *)mystr,myint);
2360 <li> stdarg.h - contains definition for the following macros to be used
2361 for variable parameter list, note that a function can have a variable
2362 parameter list if and only if it is 'reentrant'
2365 va_list, va_start, va_arg, va_end.</li>
2367 <li> setjmp.h - contains defintion for ANSI setjmp & longjmp routines.
2368 Note in this case setjmp & longjmp can be used between functions
2369 executing within the same register bank, if long jmp is executed from
2370 a function that is using a different register bank from the function
2371 issuing the setjmp function, the results may be unpredictable. The
2372 jump buffer requires 3 bytes of data (the stack pointer & a 16 byte
2373 return address), and can be placed in any address space.</li>
2375 <li> stdlib.h - contains the following functions.
2380 <li> string.h - contains the following functions.
2383 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr,
2384 strspn, strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp,
2387 <li> ctype.h - contains the following routines.
2390 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
2391 isxdigit, isalnum, isalpha.</li>
2393 <li> malloc.h - The malloc routines are developed by Dmitry S. Obukhov
2394 (dso@usa.net). These routines will allocate memory from the external
2395 ram. Here is a description on how to use them (as described by the
2400 // #define DYNAMIC_MEMORY_SIZE 0x2000 <br />
2401 // ..... <br />
2402 // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
2404 // unsigned char xdata * current_buffer; <br />
2405 // ..... <br />
2406 // void main(void) <br />
2407 // { <br />
2408 // ... <br />
2409 // init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
2411 // //Now it's possible to use malloc. <br />
2412 // ... <br />
2413 // current_buffer = malloc(0x100); <br />
2414 //</li>
2416 <li> serial.h - Serial IO routines are also developed by Dmitry S. Obukhov
2417 (dso@usa.net). These routines are interrupt driven with a 256 byte
2418 circular buffer, they also expect external ram to be present. Please
2419 see documentation in file SDCCDIR/sdcc51lib/serial.c. Note the header
2420 file ``serial.h'' MUST be included in the file containing the
2421 'main' function.</li>
2423 <li> ser.h - Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.com>
2424 these routines are more compact and faster. Please see documentation
2425 in file SDCCDIR/sdcc51lib/ser.c</li>
2427 <li> ser_ir.h - Another alternate set of serial routines provided by Josef
2428 Wolf <jw@raven.inka.de>, these routines do not use the external ram.</li>
2430 <li> reg51.h - contains register definitions for a standard 8051</li>
2432 <li> float.h - contains min, max and other floating point related stuff.</li>
2434 All library routines are compiled as -model-small, they are all non-reentrant,
2435 if you plan to use the large model or want to make these routines
2436 reentrant, then they will have to be recompiled with the appropriate
2440 Have not had time to do the more involved routines like printf, will
2441 get to them shortly.
2444 <h3><a name="tth_sEc4.4">
2445 4.4</a> Interfacing with Assembly Routines</h3>
2448 <h3><a name="tth_sEc4.5">
2449 4.5</a> Global Registers used for Parameter Passing</h3>
2452 By default the compiler uses the global registers ``DPL,DPH,B,ACC''
2453 to pass the first parameter to a routine, the second parameter onwards
2454 is either allocated on the stack (for reentrant routines or -stack-auto
2455 is used) or in the internal / external ram (depending on the memory
2459 <h4><a name="tth_sEc4.5.1">
2460 4.5.1</a> Assembler Routine(non-reentrant)</h4>
2463 In the following example the function cfunc calls an assembler routine
2464 asm_func, which takes two parameters.
2467 extern int asm_func(unsigned char, unsigned char);
2471 int c_func (unsigned char i, unsigned char j) <br />
2473 return asm_func(i,j); <br />
2477 return c_func(10,9); <br />
2481 The corresponding assembler function is:-
2484 .globl _asm_func_PARM_2 <br />
2485 .globl _asm_func <br />
2486 .area OSEG <br />
2487 _asm_func_PARM_2: .ds 1 <br />
2488 .area CSEG <br />
2490 mov a,dpl <br />
2491 add a,_asm_func_PARM_2 <br />
2492 mov dpl,a <br />
2493 mov dpl,#0x00 <br />
2494 ret
2497 Note here that the return values are placed in 'dpl' - One byte return
2498 value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and
2499 'b' for three byte values (generic pointers) and 'dpl','dph','b' &
2500 'acc' for four byte values.
2503 The parameter naming convention is _<function_name>_PARM_<n>,
2504 where n is the parameter number starting from 1, and counting from
2505 the left. The first parameter is passed in ``dpl'' for One bye
2506 parameter, ``dptr'' if two bytes, ``b,dptr'' for three bytes
2507 and ``acc,b,dptr'' for four bytes, the varaible name for the second
2508 parameter will be _<function_name>_PARM_2.
2511 Assemble the assembler routine with the following command.
2514 asx8051 -losg asmfunc.asm
2517 Then compile and link the assembler routine to the C source file with
2518 the following command,
2521 sdcc cfunc.c asmfunc.rel
2524 <h4><a name="tth_sEc4.5.2">
2525 4.5.2</a> Assembler Routine(reentrant)</h4>
2528 In this case the second parameter onwards will be passed on the stack,
2529 the parameters are pushed from right to left i.e. after the call the
2530 left most parameter will be on the top of the stack. Here is an example.
2533 extern int asm_func(unsigned char, unsigned char);
2539 int c_func (unsigned char i, unsigned char j) reentrant <br />
2541 return asm_func(i,j); <br />
2545 return c_func(10,9); <br />
2549 The corresponding assembler routine is.
2552 .globl _asm_func <br />
2554 push _bp <br />
2555 mov _bp,sp <br />
2556 mov r2,dpl<br />
2557 mov a,_bp <br />
2558 clr c <br />
2559 add a,#0xfd <br />
2560 mov r0,a <br />
2561 add a,#0xfc<br />
2562 mov r1,a <br />
2563 mov a,@r0 <br />
2564 add a,r2<br />
2565 mov dpl,a <br />
2566 mov dph,#0x00 <br />
2567 mov sp,_bp <br />
2568 pop _bp <br />
2569 ret
2572 The compiling and linking procedure remains the same, however note
2573 the extra entry & exit linkage required for the assembler code, _bp
2574 is the stack frame pointer and is used to compute the offset into
2575 the stack for parameters and local variables.
2578 <h3><a name="tth_sEc4.6">
2579 4.6</a> External Stack</h3>
2582 The external stack is located at the start of the external ram segment,
2583 and is 256 bytes in size. When -xstack option is used to compile
2584 the program, the parameters and local variables of all reentrant functions
2585 are allocated in this area. This option is provided for programs with
2586 large stack space requirements. When used with the -stack-auto option,
2587 all parameters and local variables are allocated on the external stack
2588 (note support libraries will need to be recompiled with the same options).
2591 The compiler outputs the higher order address byte of the external
2592 ram segment into PORT P2, therefore when using the External Stack
2593 option, this port MAY NOT be used by the application program.
2596 <h3><a name="tth_sEc4.7">
2597 4.7</a> ANSI-Compliance</h3>
2600 Deviations from the compliancy.
2605 <li> functions are not always reentrant.</li>
2607 <li> structures cannot be assigned values directly, cannot be passed as
2608 function parameters or assigned to each other and cannot be a return
2609 value from a function.
2614 struct s { ... }; <br />
2615 struct s s1, s2; <br />
2619 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ <br />
2624 struct s foo1 (struct s parms) /* is invalid in SDCC although allowed
2627 struct s rets; <br />
2629 return rets;/* is invalid in SDCC although allowed in ANSI */
2636 <li> 'long long' (64 bit integers) not supported.</li>
2638 <li> 'double' precision floating point not supported.</li>
2640 <li> integral promotions are suppressed. What does this mean ? The compiler
2641 will not implicitly promote an integer expression to a higher order
2642 integer, exception is an assignment or parameter passing.</li>
2644 <li> No support for setjmp and longjmp (for now).</li>
2646 <li> Old K&R style function declarations are NOT allowed.</li>
2648 foo(i,j) /* this old style of function declarations */ <br />
2649 int i,j; /* are valid in ANSI .. not valid in SDCC */ <br />
2657 <li> functions declared as pointers must be dereferenced during the call.
2662 ... <br />
2663 /* has to be called like this */ <br />
2664 (*foo)();/* ansi standard allows calls to be made like 'foo()'
2668 <h3><a name="tth_sEc4.8">
2669 4.8</a> Cyclomatic Complexity</h3>
2672 Cyclomatic complexity of a function is defined as the number of independent
2673 paths the program can take during execution of the function. This
2674 is an important number since it defines the number test cases you
2675 have to generate to validate the function. The accepted industry standard
2676 for complexity number is 10, if the cyclomatic complexity reported
2677 by SDCC exceeds 10 you should think about simplification of the function
2681 Note that the complexity level is not related to the number of lines
2682 of code in a function. Large functions can have low complexity, and
2683 small functions can have large complexity levels. SDCC uses the following
2684 formula to compute the complexity.
2687 complexity = (number of edges in control flow graph) - <br />
2688 (number of nodes in control flow graph) + 2;
2691 Having said that the industry standard is 10, you should be aware
2692 that in some cases it may unavoidable to have a complexity level of
2693 less than 10. For example if you have switch statement with more than
2694 10 case labels, each case label adds one to the complexity level.
2695 The complexity level is by no means an absolute measure of the algorithmic
2696 complexity of the function, it does however provide a good starting
2697 point for which functions you might look at for further optimization.
2700 <h2><a name="tth_sEc5">
2701 5</a> TIPS</h2>
2704 Here are a few guide-lines that will help the compiler generate more
2705 efficient code, some of the tips are specific to this compiler others
2706 are generally good programming practice.
2711 <li> Use the smallest data type to represent your data-value. If it is
2712 known in advance that the value is going to be less than 256 then
2713 use a 'char' instead of a 'short' or 'int'.</li>
2715 <li> Use unsigned when it is known in advance that the value is not going
2716 to be negative. This helps especially if you are doing division or
2717 multiplication.</li>
2719 <li> NEVER jump into a LOOP.</li>
2721 <li> Declare the variables to be local whenever possible, especially loop
2722 control variables (induction).</li>
2724 <li> Since the compiler does not do implicit integral promotion, the programmer
2725 should do an explicit cast when integral promotion is required.</li>
2727 <li> Reducing the size of division, multiplication & modulus operations
2728 can reduce code size substantially. Take the following code for example.
2731 foobar(unsigned int p1, unsigned char ch)<br />
2733 unsigned char ch1 = p1 % ch ;<br />
2734 .... <br />
2738 For the modulus operation the variable ch will be promoted to unsigned
2739 int first then the modulus operation will be performed (this will
2740 lead to a call to a support routine). If the code is changed to
2743 foobar(unsigned int p1, unsigned char ch)<br />
2745 unsigned char ch1 = (unsigned char)p1 % ch ;<br />
2746 .... <br />
2750 It would substantially reduce the code generated (future versions
2751 of the compiler will be smart enough to detect such optimization oppurtunities).</li>
2753 Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
2756 The 8051 family of micro controller have a minimum of 128 bytes of
2757 internal memory which is structured as follows
2760 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7
2764 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
2767 - Bytes 30-7F - 60 bytes for general purpose use.
2770 Normally the SDCC compiler will only utilise the first bank of registers,
2771 but it is possible to specify that other banks of registers should
2772 be used in interrupt routines. By default, the compiler will place
2773 the stack after the last bank of used registers, i.e. if the first
2774 2 banks of registers are used, it will position the base of the internal
2775 stack at address 16 (0X10). This implies that as the stack grows,
2776 it will use up the remaining register banks, and the 16 bytes used
2777 by the 128 bit variables, and 60 bytes for general purpose use.
2780 By default, the compiler uses the 60 general purpose bytes to hold
2781 "near data". The compiler/optimiser may also declare
2782 some Local Variables in this area to hold local data.
2785 If any of the 128 bit variables are used, or near data is being used
2786 then care needs to be taken to ensure that the stack does not grow
2787 so much that it starts to over write either your bit variables or
2788 "near data". There is no runtime checking to prevent
2789 this from happening.
2792 The amount of stack being used is affected by the use of the "internal
2793 stack" to save registers before a subroutine call is made,
2794 - -stack-auto will declare parameters and local variables on the
2795 stack - the number of nested subroutines.
2798 If you detect that the stack is over writing you data, then the following
2799 can be done. -xstack will cause an external stack to be used for
2800 saving registers and (if -stack-auto is being used) storing parameters
2801 and local variables. However this will produce more and code which
2802 will be slower to execute.
2805 -stack-loc will allow you specify the start of the stack, i.e. you
2806 could start it after any data in the general purpose area. However
2807 this may waste the memory not used by the register banks and if the
2808 size of the "near data" increases, it may creep
2809 into the bottom of the stack.
2812 -stack-after-data, similar to the -stack-loc, but it automatically
2813 places the stack after the end of the "near data".
2814 Again this could waste any spare register space.
2817 -data-loc allows you to specify the start address of the near data.
2818 This could be used to move the "near data" further
2819 away from the stack giving it more room to grow. This will only work
2820 if no bit variables are being used and the stack can grow to use the
2827 If you find that the stack is over writing your bit variables or "near
2828 data" then the approach which best utilised the internal
2829 memory is to position the "near data" after the
2830 last bank of used registers or, if you use bit variables, after the
2831 last bit variable by using the -data-loc, e.g. if two register banks
2832 are being used and no data variables, -data-loc 16, and - use the
2833 -stack-after-data option.
2836 If bit variables are being used, another method would be to try and
2837 squeeze the data area in the unused register banks if it will fit,
2838 and start the stack after the last bit variable.
2841 <h2><a name="tth_sEc6">
2842 6</a> Retargetting for other MCUs.</h2>
2845 The issues for retargetting the compiler are far too numerous to be
2846 covered by this document. What follows is a brief description of each
2847 of the seven phases of the compiler and its MCU dependency.
2852 <li> Parsing the source and building the annotated parse tree. This phase
2853 is largely MCU independent (except for the language extensions). Syntax
2854 & semantic checks are also done in this phase, along with some initial
2855 optimizations like back patching labels and the pattern matching optimizations
2856 like bit-rotation etc.</li>
2858 <li> The second phase involves generating an intermediate code which can
2859 be easy manipulated during the later phases. This phase is entirely
2860 MCU independent. The intermediate code generation assumes the target
2861 machine has unlimited number of registers, and designates them with
2862 the name iTemp. The compiler can be made to dump a human readable
2863 form of the code generated by using the -dumpraw option.</li>
2865 <li> This phase does the bulk of the standard optimizations and is also
2866 MCU independent. This phase can be broken down into several sub-phases.
2871 <li> Break down intermediate code (iCode) into basic blocks.</li>
2873 <li> Do control flow & data flow analysis on the basic blocks.</li>
2875 <li> Do local common subexpression elimination, then global subexpression
2878 <li> dead code elimination</li>
2880 <li> loop optimizations</li>
2882 <li> if loop optimizations caused any changes then do 'global subexpression
2883 elimination' and 'dead code elimination' again.</li>
2886 <li> This phase determines the live-ranges; by live range I mean those
2887 iTemp variables defined by the compiler that still survive after all
2888 the optimizations. Live range analysis is essential for register allocation,
2889 since these computation determines which of these iTemps will be assigned
2890 to registers, and for how long.</li>
2892 <li> Phase five is register allocation. There are two parts to this process.
2897 <li> The first part I call 'register packing' (for lack of a better term).
2898 In this case several MCU specific expression folding is done to reduce
2899 register pressure.</li>
2901 <li> The second part is more MCU independent and deals with allocating
2902 registers to the remaining live ranges. A lot of MCU specific code
2903 does creep into this phase because of the limited number of index
2904 registers available in the 8051.</li>
2907 <li> The Code generation phase is (unhappily), entirely MCU dependent and
2908 very little (if any at all) of this code can be reused for other MCU.
2909 However the scheme for allocating a homogenized assembler operand
2910 for each iCode operand may be reused.</li>
2912 <li> As mentioned in the optimization section the peep-hole optimizer is
2913 rule based system, which can reprogrammed for other MCUs.</li>
2917 <h2><a name="tth_sEc7">
2918 7</a> SDCDB - Source Level Debugger</h2>
2921 SDCC is distributed with a source level debugger. The debugger uses
2922 a command line interface, the command repertoire of the debugger has
2923 been kept as close to gdb (the GNU debugger) as possible. The configuration
2924 and build process is part of the standard compiler installation, which
2925 also builds and installs the debugger in the target directory specified
2926 during configuration. The debugger allows you debug BOTH at the C
2927 source and at the ASM source level.
2930 <h3><a name="tth_sEc7.1">
2931 7.1</a> Compiling for Debugging</h3>
2934 The -debug option must be specified for all files for which debug
2935 information is to be generated. The complier generates a .cdb file
2936 for each of these files. The linker updates the .cdb file with the
2937 address information. This .cdb is used by the debugger.
2940 <h3><a name="tth_sEc7.2">
2941 7.2</a> How the Debugger Works</h3>
2944 When the -debug option is specified the compiler generates extra
2945 symbol information some of which are put into the the assembler source
2946 and some are put into the .cdb file, the linker updates the .cdb file
2947 with the address information for the symbols. The debugger reads the
2948 symbolic information generated by the compiler & the address information
2949 generated by the linker. It uses the SIMULATOR (Daniel's S51) to execute
2950 the program, the program execution is controlled by the debugger.
2951 When a command is issued for the debugger, it translates it into appropriate
2952 commands for the simulator.
2955 <h3><a name="tth_sEc7.3">
2956 7.3</a> Starting the Debugger</h3>
2959 The debugger can be started using the following command line. (Assume
2960 the file you are debugging has
2969 The debugger will look for the following files.
2974 <li> foo.c - the source file.</li>
2976 <li> foo.cdb - the debugger symbol information file.</li>
2978 <li> foo.ihx - the intel hex format object file.</li>
2982 <h3><a name="tth_sEc7.4">
2983 7.4</a> Command Line Options.</h3>
2988 <li> -directory=<source file directory> this option can used to specify
2989 the directory search list. The debugger will look into the directory
2990 list specified for source, cdb & ihx files. The items in the directory
2991 list must be separated by ':', e.g. if the source files can be in
2992 the directories /home/src1 and /home/src2, the -directory option
2993 should be -directory=/home/src1:/home/src2. Note there can be no
2994 spaces in the option.</li>
2996 <li> -cd <directory> - change to the <directory>.</li>
2998 <li> -fullname - used by GUI front ends.</li>
3000 <li> -cpu <cpu-type> - this argument is passed to the simulator please
3001 see the simulator docs for details.</li>
3003 <li> -X <Clock frequency > this options is passed to the simulator please
3004 see simulator docs for details.</li>
3006 <li> -s <serial port file> passed to simulator see simulator docs for details.</li>
3008 <li> -S <serial in,out> passed to simulator see simulator docs for details.</li>
3012 <h3><a name="tth_sEc7.5">
3013 7.5</a> Debugger Commands.</h3>
3016 As mention earlier the command interface for the debugger has been
3017 deliberately kept as close the GNU debugger gdb, as possible, this
3018 will help int integration with existing graphical user interfaces
3019 (like ddd, xxgdb or xemacs) existing for the GNU debugger.
3022 <h4><a name="tth_sEc7.5.1">
3023 7.5.1</a> break [line | file:line | function | file:function]</h4>
3026 Set breakpoint at specified line or function.
3029 sdcdb>break 100 <br />
3030 sdcdb>break foo.c:100<br />
3031 sdcdb>break funcfoo<br />
3032 sdcdb>break foo.c:funcfoo
3035 <h4><a name="tth_sEc7.5.2">
3036 7.5.2</a> clear [line | file:line | function | file:function ]</h4>
3039 Clear breakpoint at specified line or function.
3042 sdcdb>clear 100<br />
3043 sdcdb>clear foo.c:100<br />
3044 sdcdb>clear funcfoo<br />
3045 sdcdb>clear foo.c:funcfoo
3048 <h4><a name="tth_sEc7.5.3">
3049 7.5.3</a> continue</h4>
3052 Continue program being debugged, after breakpoint.
3055 <h4><a name="tth_sEc7.5.4">
3056 7.5.4</a> finish</h4>
3059 Execute till the end of the current function.
3062 <h4><a name="tth_sEc7.5.5">
3063 7.5.5</a> delete [n]</h4>
3066 Delete breakpoint number 'n'. If used without any option clear ALL
3067 user defined break points.
3070 <h4><a name="tth_sEc7.5.6">
3071 7.5.6</a> info [break | stack | frame | registers ]</h4>
3076 <li> info break - list all breakpoints</li>
3078 <li> info stack - show the function call stack.</li>
3080 <li> info frame - show information about the current execution frame.</li>
3082 <li> info registers - show content of all registers.</li>
3086 <h4><a name="tth_sEc7.5.7">
3087 7.5.7</a> step</h4>
3090 Step program until it reaches a different source line.
3093 <h4><a name="tth_sEc7.5.8">
3094 7.5.8</a> next</h4>
3097 Step program, proceeding through subroutine calls.
3100 <h4><a name="tth_sEc7.5.9">
3101 7.5.9</a> run</h4>
3104 Start debugged program.
3107 <h4><a name="tth_sEc7.5.10">
3108 7.5.10</a> ptype variable </h4>
3111 Print type information of the variable.
3114 <h4><a name="tth_sEc7.5.11">
3115 7.5.11</a> print variable</h4>
3118 print value of variable.
3121 <h4><a name="tth_sEc7.5.12">
3122 7.5.12</a> file filename</h4>
3125 load the given file name. Note this is an alternate method of loading
3129 <h4><a name="tth_sEc7.5.13">
3130 7.5.13</a> frame</h4>
3133 print information about current frame.
3136 <h4><a name="tth_sEc7.5.14">
3137 7.5.14</a> set srcmode</h4>
3140 Toggle between C source & assembly source.
3143 <h4><a name="tth_sEc7.5.15">
3144 7.5.15</a> ! simulator command</h4>
3147 Send the string following '!' to the simulator, the simulator response
3148 is displayed. Note the debugger does not interpret the command being
3149 sent to the simulator, so if a command like 'go' is sent the debugger
3150 can loose its execution context and may display incorrect values.
3153 <h4><a name="tth_sEc7.5.16">
3154 7.5.16</a> quit.</h4>
3157 "Watch me now. Iam going Down. My name is Bobby Brown"
3160 <h3><a name="tth_sEc7.6">
3161 7.6</a> Interfacing with XEmacs.</h3>
3164 Two files are (in emacs lisp) are provided for the interfacing with
3165 XEmacs, sdcdb.el and sdcdbsrc.el. These two files can be found in
3166 the $(prefix)/bin directory after the installation is complete. These
3167 files need to be loaded into XEmacs for the interface to work, this
3168 can be done at XEmacs startup time by inserting the following into
3169 your '.xemacs' file (which can be found in your HOME directory) (load-file
3170 sdcdbsrc.el) [ .xemacs is a lisp file so the () around the command
3171 is REQUIRED), the files can also be loaded dynamically while XEmacs
3172 is running, set the environment variable 'EMACSLOADPATH' to the installation
3173 bin directory [$(prefix)/bin], then enter the following command
3174 ESC-x load-file sdcdbsrc. To start the interface enter the following
3175 command ESC-x sdcdbsrc, you will prompted to enter the file name to
3179 The command line options that are passed to the simulator directly
3180 are bound to default values in the file sdcdbsrc.el the variables
3181 are listed below these values maybe changed as required.
3186 <li> sdcdbsrc-cpu-type '51</li>
3188 <li> sdcdbsrc-frequency '11059200</li>
3190 <li> sdcdbsrc-serial nil</li>
3192 The following is a list of key mapping for the debugger interface.
3196 ;; Current Listing :: <br />
3197 ;;key binding Comment
3199 ;;- --- ---
3202 ;; n sdcdb-next-from-src SDCDB
3204 ;; b sdcdb-back-from-src SDCDB
3206 ;; c sdcdb-cont-from-src SDCDB
3207 continue command<br />
3208 ;; s sdcdb-step-from-src SDCDB
3210 ;; ? sdcdb-whatis-c-sexp SDCDB
3211 ptypecommand for data at <br />
3212 ;;
3214 ;; x sdcdbsrc-delete SDCDB
3215 Delete all breakpoints if no arg <br />
3216 ;; given
3217 or delete arg (C-u arg x) <br />
3218 ;; m sdcdbsrc-frame SDCDB
3219 Display current frame if no arg, <br />
3220 ;; given
3221 or display frame arg <br />
3222 ;; buffer
3224 ;; ! sdcdbsrc-goto-sdcdb Goto
3225 the SDCDB output buffer <br />
3226 ;; p sdcdb-print-c-sexp SDCDB
3227 print command for data at <br />
3228 ;;
3230 ;; g sdcdbsrc-goto-sdcdb Goto
3231 the SDCDB output buffer <br />
3232 ;; t sdcdbsrc-mode Toggles
3233 Sdcdbsrc mode (turns it off) <br />
3235 ;; C-c C-f sdcdb-finish-from-src SDCDB
3236 finish command <br />
3238 ;; C-x SPC sdcdb-break Set
3239 break for line with point <br />
3240 ;; ESC t sdcdbsrc-mode Toggle
3241 Sdcdbsrc mode <br />
3242 ;; ESC m sdcdbsrc-srcmode
3243 Toggle list mode <br />
3247 <h2><a name="tth_sEc8">
3248 8</a> Other Processors</h2>
3251 <h3><a name="tth_sEc8.1">
3252 8.1</a> The Z80 and gbz80 port</h3>
3255 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like
3256 gbz80. The port is incomplete - long support is incomplete (mul, div
3257 and mod are unimplimented), and both float and bitfield support is
3258 missing, but apart from that the code generated is correct.
3261 As always, the code is the authoritave reference - see z80/ralloc.c
3262 and z80/gen.c. The stack frame is similar to that generated by the
3263 IAR Z80 compiler. IX is used as the base pointer, HL is used as a
3264 temporary register, and BC and DE are available for holding varibles.
3265 IY is currently unusued. Return values are stored in HL. One bad side
3266 effect of using IX as the base pointer is that a functions stack frame
3267 is limited to 127 bytes - this will be fixed in a later version.
3270 <h2><a name="tth_sEc9">
3271 9</a> Support</h2>
3274 SDCC has grown to be large project, the compiler alone (without the
3275 Assembler Package, Preprocessor) is about 40,000 lines of code (blank
3276 stripped). The open source nature of this project is a key to its
3277 continued growth and support. You gain the benefit and support of
3278 many active software developers and end users. Is SDCC perfect? No,
3279 that's why we need your help. The developers take pride in fixing
3280 reported bugs. You can help by reporting the bugs and helping other
3281 SDCC users. There are lots of ways to contribute, and we encourage
3282 you to take part in making SDCC a great software package.
3285 <h3><a name="tth_sEc9.1">
3286 9.1</a> Reporting Bugs</h3>
3289 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
3290 or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed ASAP. When
3291 reporting a bug, it is very useful to include a small test program
3292 which reproduces the problem. If you can isolate the problem by looking
3293 at the generated assembly code, this can be very helpful. Compiling
3294 your program with the -dumpall option can sometimes be useful in
3295 locating optimization problems.
3298 <h3><a name="tth_sEc9.2">
3299 9.2</a> Acknowledgments</h3>
3302 Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code
3303 generator, Debugger, AVR port<br />
3304 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX
3305 & ASLINK. <br />
3306 John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for
3308 Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines. <br />
3309 Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware
3311 Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience
3313 Unknown - for the GNU C - preprocessor.<br />
3314 Michael Hope - The Z80 and Z80GB port, 186 development<br />
3315 Kevin Vigor - The DS390 port.<br />
3316 Johan Knol - DS390/TINI libs, lots of fixes and enhancements.<br />
3317 Scott Datallo - PIC port.<br />
3318 (Thanks to all the other volunteer developers who have helped with
3319 coding, testing, web-page creation, distribution sets, etc. You know
3320 who you are :-)<br />
3323 This document initially written by Sandeep Dutta
3326 All product names mentioned herein may be trademarks of their respective
3330 <hr /><h3>Footnotes:</h3>
3333 <a name="tthFtNtAAB"></a><a href="#tthFrefAAB"><sup>1</sup></a>possible exception: if a function is called ONLY from 'interrupt'
3334 functions using a particular bank, it can be declared with the same
3335 'using' attribute as the calling 'interrupt' functions. For instance,
3336 if you have several ISRs using bank one, and all of them call memcpy(),
3337 it might make sense to create a specialized version of memcpy() 'using
3338 1', since this would prevent the ISR from having to save bank zero
3339 to the stack on entry and switch to bank zero before calling the function
3341 <br /><br /><hr /><small>File translated from
3342 T<sub><font size="-1">E</font></sub>X
3343 by <a href="http://hutchinson.belmont.ma.us/tth/">
3344 T<sub><font size="-1">T</font></sub>H</a>,
3345 version 3.01.<br />On 5 Jul 2001, 17:34.</small>
projects / fw / sdcc / blob