1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
3 <!--Converted with LaTeX2HTML 2K.1beta (1.47)
4 original version by: Nikos Drakos, CBLU, University of Leeds
5 * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6 * with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
10 <TITLE>SDCC Compiler User Guide</TITLE>
11 <META NAME="description" CONTENT="SDCC Compiler User Guide">
12 <META NAME="keywords" CONTENT="SDCCUdoc">
13 <META NAME="resource-type" CONTENT="document">
14 <META NAME="distribution" CONTENT="global">
16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17 <META NAME="Generator" CONTENT="LaTeX2HTML v2K.1beta">
18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
20 <LINK REL="STYLESHEET" HREF="SDCCUdoc.css">
25 <!--Navigation Panel-->
26 <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
27 SRC="file:/usr/share/latex2html/icons/nx_grp_g.png">
28 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
29 SRC="file:/usr/share/latex2html/icons/up_g.png">
30 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
31 SRC="file:/usr/share/latex2html/icons/prev_g.png">
35 <!--End of Navigation Panel-->
40 <H1 ALIGN="CENTER">SDCC Compiler User Guide</H1>
43 <H2><A NAME="SECTION00010000000000000000">
46 <!--Table of Contents-->
49 <LI><A NAME="tex2html119"
50 HREF="SDCCUdoc.html">1 Introduction</A>
52 <LI><A NAME="tex2html120"
53 HREF="#SECTION00021000000000000000">1.1 About SDCC</A>
54 <LI><A NAME="tex2html121"
55 HREF="#SECTION00022000000000000000">1.2 Open Source</A>
56 <LI><A NAME="tex2html122"
57 HREF="#SECTION00023000000000000000">1.3 System Requirements</A>
58 <LI><A NAME="tex2html123"
59 HREF="#SECTION00024000000000000000">1.4 Other Resources</A>
62 <LI><A NAME="tex2html124"
63 HREF="#SECTION00030000000000000000">2 Installation</A>
65 <LI><A NAME="tex2html125"
66 HREF="#SECTION00031000000000000000">2.1 Linux/Unix Installation</A>
67 <LI><A NAME="tex2html126"
68 HREF="#SECTION00032000000000000000">2.2 Windows Installation</A>
69 <LI><A NAME="tex2html127"
70 HREF="#SECTION00033000000000000000">2.3 Testing out the SDCC Compiler</A>
71 <LI><A NAME="tex2html128"
72 HREF="#SECTION00034000000000000000">2.4 Install Trouble-shooting</A>
73 <LI><A NAME="tex2html129"
74 HREF="#SECTION00035000000000000000">2.5 Additional Information for Windows Users</A>
75 <LI><A NAME="tex2html130"
76 HREF="#SECTION00036000000000000000">2.6 SDCC on Other Platforms</A>
77 <LI><A NAME="tex2html131"
78 HREF="#SECTION00037000000000000000">2.7 Advanced Install Options</A>
79 <LI><A NAME="tex2html132"
80 HREF="#SECTION00038000000000000000">2.8 Components of SDCC</A>
83 <LI><A NAME="tex2html133"
84 HREF="#SECTION00040000000000000000">3 Using SDCC</A>
86 <LI><A NAME="tex2html134"
87 HREF="#SECTION00041000000000000000">3.1 Compiling</A>
88 <LI><A NAME="tex2html135"
89 HREF="#SECTION00042000000000000000">3.2 Command Line Options</A>
90 <LI><A NAME="tex2html136"
91 HREF="#SECTION00043000000000000000">3.3 MCS51 Storage Class Language Extensions</A>
92 <LI><A NAME="tex2html137"
93 HREF="#SECTION00044000000000000000">3.4 Pointers</A>
94 <LI><A NAME="tex2html138"
95 HREF="#SECTION00045000000000000000">3.5 Parameters & Local Variables</A>
96 <LI><A NAME="tex2html139"
97 HREF="#SECTION00046000000000000000">3.6 Overlaying</A>
98 <LI><A NAME="tex2html140"
99 HREF="#SECTION00047000000000000000">3.7 Critical Functions</A>
100 <LI><A NAME="tex2html141"
101 HREF="#SECTION00048000000000000000">3.8 Absolute Addressing</A>
102 <LI><A NAME="tex2html142"
103 HREF="#SECTION00049000000000000000">3.9 Interrupt Service Routines</A>
104 <LI><A NAME="tex2html143"
105 HREF="#SECTION000410000000000000000">3.10 Startup Code</A>
106 <LI><A NAME="tex2html144"
107 HREF="#SECTION000411000000000000000">3.11 Inline Assembler Code</A>
108 <LI><A NAME="tex2html145"
109 HREF="#SECTION000412000000000000000">3.12 int(16 bit) and long (32 bit ) Support</A>
110 <LI><A NAME="tex2html146"
111 HREF="#SECTION000413000000000000000">3.13 Floating Point Support</A>
112 <LI><A NAME="tex2html147"
113 HREF="#SECTION000414000000000000000">3.14 MCS51 Memory Models</A>
114 <LI><A NAME="tex2html148"
115 HREF="#SECTION000415000000000000000">3.15 Flat 24 bit Addressing Model</A>
116 <LI><A NAME="tex2html149"
117 HREF="#SECTION000416000000000000000">3.16 Defines Created by the Compiler</A>
120 <LI><A NAME="tex2html150"
121 HREF="#SECTION00050000000000000000">4 SDCC Technical Data</A>
123 <LI><A NAME="tex2html151"
124 HREF="#SECTION00051000000000000000">4.1 Optimizations</A>
125 <LI><A NAME="tex2html152"
126 HREF="#SECTION00052000000000000000">4.2 Pragmas</A>
127 <LI><A NAME="tex2html153"
128 HREF="#SECTION00053000000000000000">4.3 Library Routines</A>
129 <LI><A NAME="tex2html154"
130 HREF="#SECTION00054000000000000000">4.4 Interfacing with Assembly Routines</A>
131 <LI><A NAME="tex2html155"
132 HREF="#SECTION00055000000000000000">4.5 Global Registers used for Parameter Passing</A>
133 <LI><A NAME="tex2html156"
134 HREF="#SECTION00056000000000000000">4.6 With -noregparms Option</A>
135 <LI><A NAME="tex2html157"
136 HREF="#SECTION00057000000000000000">4.7 External Stack</A>
137 <LI><A NAME="tex2html158"
138 HREF="#SECTION00058000000000000000">4.8 ANSI-Compliance</A>
139 <LI><A NAME="tex2html159"
140 HREF="#SECTION00059000000000000000">4.9 Cyclomatic Complexity</A>
143 <LI><A NAME="tex2html160"
144 HREF="#SECTION00060000000000000000">5 TIPS</A>
145 <LI><A NAME="tex2html161"
146 HREF="#SECTION00070000000000000000">6 Retargetting for other MCUs.</A>
147 <LI><A NAME="tex2html162"
148 HREF="#SECTION00080000000000000000">7 SDCDB - Source Level Debugger</A>
150 <LI><A NAME="tex2html163"
151 HREF="#SECTION00081000000000000000">7.1 Compiling for Debugging</A>
152 <LI><A NAME="tex2html164"
153 HREF="#SECTION00082000000000000000">7.2 How the Debugger Works</A>
154 <LI><A NAME="tex2html165"
155 HREF="#SECTION00083000000000000000">7.3 Starting the Debugger</A>
156 <LI><A NAME="tex2html166"
157 HREF="#SECTION00084000000000000000">7.4 Command Line Options.</A>
158 <LI><A NAME="tex2html167"
159 HREF="#SECTION00085000000000000000">7.5 Debugger Commands.</A>
160 <LI><A NAME="tex2html168"
161 HREF="#SECTION00086000000000000000">7.6 Interfacing with XEmacs.</A>
164 <LI><A NAME="tex2html169"
165 HREF="#SECTION00090000000000000000">8 Other Processors</A>
167 <LI><A NAME="tex2html170"
168 HREF="#SECTION00091000000000000000">8.1 The Z80 and gbz80 port</A>
171 <LI><A NAME="tex2html171"
172 HREF="#SECTION000100000000000000000">9 Support</A>
174 <LI><A NAME="tex2html172"
175 HREF="#SECTION000101000000000000000">9.1 Reporting Bugs</A>
176 <LI><A NAME="tex2html173"
177 HREF="#SECTION000102000000000000000">9.2 Acknowledgments</A>
180 <LI><A NAME="tex2html174"
181 HREF="#SECTION000110000000000000000">About this document ...</A>
183 <!--End of Table of Contents-->
187 <H1><A NAME="SECTION00020000000000000000">
193 <H2><A NAME="SECTION00021000000000000000">
198 <B>SDCC</B> is a Free ware, retargettable, optimizing ANSI-C compiler
199 by <B>Sandeep Dutta</B> designed for 8 bit Microprocessors. The
200 current version targets Intel MCS51 based Microprocessors(8051,8052,
201 etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51 variant. It
202 can be retargetted for other microprocessors, support for PIC, AVR
203 and 186 is under development. The entire source code for the compiler
204 is distributed under GPL. SDCC uses ASXXXX & ASLINK, a Freeware,
205 retargettable assembler & linker. SDCC has extensive language extensions
206 suitable for utilizing various microcontrollers underlying hardware
207 effectively. In addition to the MCU specific optimizations SDCC also
208 does a host of standard optimizations like <I>global sub expression
209 elimination, loop optimizations (loop invariant, strength reduction
210 of induction variables and loop reversing), constant folding & propagation,
211 copy propagation, dead code elimination and jumptables for 'switch'
212 statements.</I> For the back-end SDCC uses a global register allocation
213 scheme which should be well suited for other 8 bit MCUs. The peep
214 hole optimizer uses a rule based substitution mechanism which is MCU
215 independent. Supported data-types are <I>short (8 bits, 1 byte),
216 char (8 bits, 1 byte), int (16 bits, 2 bytes ), long (32 bit, 4 bytes)
217 & float (4 byte IEEE).</I> The compiler also allows <I>inline assembler
218 code</I> to be embedded anywhere in a function. In addition routines
219 developed in assembly can also be called. SDCC also provides an option
220 to report the relative complexity of a function, these functions can
221 then be further optimized, or hand coded in assembly if need be. SDCC
222 also comes with a companion source level debugger SDCDB, the debugger
223 currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
224 The latest version can be downloaded from <B>http://sdcc.sourceforge.net/.</B>
228 <H2><A NAME="SECTION00022000000000000000">
233 All packages used in this compiler system are <I>opensource</I>(freeware);
234 source code for all the sub-packages (asxxxx assembler/linker, pre-processor)
235 are distributed with the package. This documentation is maintained
236 using a freeware word processor (LYX).
239 This program is free software; you can redistribute it and/or modify
240 it under the terms of the GNU General Public License as published
241 by the Free Software Foundation; either version 2, or (at your option)
242 any later version. This program is distributed in the hope that it
243 will be useful, but WITHOUT ANY WARRANTY; without even the implied
244 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
245 the GNU General Public License for more details. You should have received
246 a copy of the GNU General Public License along with this program;
247 if not, write to the Free Software Foundation, 59 Temple Place - Suite
248 330, Boston, MA 02111-1307, USA. In other words, you are welcome to
249 use, share and improve this program. You are forbidden to forbid anyone
250 else to use, share and improve what you give them. Help stamp out
255 <H2><A NAME="SECTION00023000000000000000">
256 1.3 System Requirements</A>
260 What do you need before you start installation of SDCC? A computer,
261 and a desire to compute. The preferred method of installation is to
262 compile SDCC from source using GNU GCC and make. For Windows some
263 pre-compiled binary distributions are available for your convenience.
264 You should have some experience with command line tools and compiler
269 <H2><A NAME="SECTION00024000000000000000">
270 1.4 Other Resources</A>
274 The SDCC home page at http://sdcc.sourceforge.net/ is a great
275 place to find distribution sets. You can also find links to the user
276 mailing lists that offer help or discuss SDCC with other SDCC users.
277 Web links to other SDCC related sites can also be found here. This
278 document can be found in the DOC directory of the source package as
279 a text or HTML file. Some of the other tools(simulator and assembler)
280 included with SDCC contain their own documentation and can be found
281 in the source distribution. If you want the latest unreleased software,
282 the complete source package is available directly by anonymous CVS
283 on www.sourceforge.net.
287 <H1><A NAME="SECTION00030000000000000000">
293 <H2><A NAME="SECTION00031000000000000000">
294 2.1 Linux/Unix Installation</A>
300 <LI>Download the source package, it will be named something like sdcc-2.x.x.tgz.
302 <LI>Bring up a command line terminal, such as xterm.
304 <LI>Unpack the file using a command like: tar -xzf sdcc-2.x.x.tgz, this
305 will create a sub-directory called sdcc with all of the sources.
307 <LI>Change directory into the main SDCC directory, for example type: ``cd
310 <LI>Type ``./configure''. This configures the package for compilation
313 <LI>Type ``make''. All of the source packages will compile, this can
316 <LI>Type ``make install'' as root. This copies the binary executables
317 to the install directories.
323 <H2><A NAME="SECTION00032000000000000000">
324 2.2 Windows Installation</A>
328 For installation under Windows you first need to pick between a pre-compiled
329 binary package, or installing the source package along with the Cygwin
330 package. The binary package is the quickest to install, while the
331 Cygwin package includes all of the open source power tools used to
332 compile the complete SDCC source package in the Windows environment.
333 If you are not familiar with the Unix command line environment, you
334 may want to read the section on additional information for Windows
335 users prior to your initial installation.
339 <H3><A NAME="SECTION00032100000000000000">
340 2.2.1 Windows Install Using a Binary Package</A>
346 <LI>Download the binary package and unpack it using your favorite unpacking
347 tool(gunzip, WinZip, etc). This should unpack to a group of sub-directories.
348 An example directory structure after unpacking is: c:\usr\local\bin
349 for the executables, c:\usr\local\share\sdcc\include
350 and c:\usr\local\share\sdcc\lib
351 for the include and libraries.
353 <LI>Adjust your environment PATH to include the location of the bin directory.
354 For example, make a setsdcc.bat file with the following: set PATH=c:\usr\local\bin;%PATH%
356 <LI>When you compile with sdcc, you may need to specify the location of
357 the lib and include folders. For example, sdcc -I c:\usr\local\share\sdcc\include
358 -L c:\usr\local\share\sdcc\lib\small
365 <H3><A NAME="SECTION00032200000000000000">
366 2.2.2 Windows Install Using Cygwin</A>
372 <LI>Download and install the cygwin package from the redhat site<I>http://sources.redhat.com/cygwin/</I>.
373 Currently, this involved downloading a small install program which
374 then automates downloading and installing selected parts of the package(a
375 large 80M byte sized dowload for the whole thing).
377 <LI>Bring up a Unix/Bash command line terminal from the Cygwin menu.
379 <LI>Follow the instructions in the preceding Linux/Unix installation section.
385 <H2><A NAME="SECTION00033000000000000000">
386 2.3 Testing out the SDCC Compiler</A>
390 The first thing you should do after installing your SDCC compiler
391 is to see if it runs. Type ``sdcc -version'' at the prompt, and
392 the program should run and tell you the version. If it doesn't run,
393 or gives a message about not finding sdcc program, then you need to
394 check over your installation. Make sure that the sdcc bin directory
395 is in your executable search path defined by the PATH environment
396 setting(see the Trouble-shooting section for suggestions). Make sure
397 that the sdcc program is in the bin folder, if not perhaps something
398 did not install correctly.
401 SDCC binaries are commonly installed in a directory arrangement like
405 <TABLE CELLPADDING=3 BORDER="1">
406 <TR><TD ALIGN="LEFT">/usr/local/bin</TD>
407 <TD ALIGN="LEFT">Holds executables(sdcc, s51, aslink, ...)</TD>
409 <TR><TD ALIGN="LEFT">/usr/local/share/sdcc/lib</TD>
410 <TD ALIGN="LEFT">Holds common C libraries</TD>
412 <TR><TD ALIGN="LEFT">/usr/local/share/sdcc/include</TD>
413 <TD ALIGN="LEFT">Holds common C header files</TD>
418 Make sure the compiler works on a very simple example. Type in the
419 following test.c program using your favorite editor:
429 Compile this using the following command: ``sdcc -c test.c''.
430 If all goes well, the compiler will generate a test.asm and test.rel
431 file. Congratulations, you've just compiled your first program with
432 SDCC. We used the -c option to tell SDCC not to link the generated
433 code, just to keep things simple for this step.
436 The next step is to try it with the linker. Type in ``sdcc test.c''.
437 If all goes well the compiler will link with the libraries and produce
438 a test.ihx output file. If this step fails(no test.ihx, and the linker
439 generates warnings), then the problem is most likely that sdcc cannot
440 find the usr/local/share/sdcc/lib/small directory(see the Install
441 trouble-shooting section for suggestions).
444 The final test is to ensure sdcc can use the standard header files
445 and libraries. Edit test.c and change it to the following:
448 <I>#include <string.h></I>
450 <BR><I>{ char str1[10];</I>
451 <BR><I>strcpy(str1, ``testing'');</I>
455 Compile this by typing: ``sdcc test.c''. This should generate
456 a test.ihx output file, and it should give no warnings such as not
457 finding the string.h file. If it cannot find the string.h file, then
458 the problem is that sdcc cannot find the /usr/local/share/sdcc/include
459 directory(see the Install trouble-shooting section for suggestions).
463 <H2><A NAME="SECTION00034000000000000000">
464 2.4 Install Trouble-shooting</A>
469 <H3><A NAME="SECTION00034100000000000000">
470 2.4.1 SDCC cannot find libraries or header files.</A>
474 The default installation assumes the libraries and header files are
475 located at ``/usr/local/share/sdcc/lib'' and ``/usr/local/share/sdcc/include''.
476 An alternative is to specify these locations as compiler options like
477 this: sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include
482 <H3><A NAME="SECTION00034200000000000000">
483 2.4.2 SDCC does not compile correctly.</A>
487 A few things to try include starting from scratch by unpacking the
488 .tgz source package again in an empty directory. If this doesn't work,
489 you could try downloading a different version. If this doesn't work,
490 you can re-direct the install messages by doing the following:
493 $./make > dump.txt 2>&1
496 After this you can examine the dump.txt files to locate the problem.
497 Or these messages can be attached to an email that could be helpful
498 when requesting help from the mailing list.
502 <H3><A NAME="SECTION00034300000000000000">
503 2.4.3 What the ``./configure'' does</A>
507 The ``./configure'' command is a script that analyzes your system
508 and performs some configuration to ensure the source package compiles
509 on your system. It will take a few minutes to run, and will compile
510 a few tests to determine what compiler features are installed.
514 <H3><A NAME="SECTION00034400000000000000">
515 2.4.4 What the ``make'' does.</A>
519 This runs the GNU make tool, which automatically compiles all the
520 source packages into the final installed binary executables.
524 <H3><A NAME="SECTION00034500000000000000">
525 2.4.5 What the ``make install'' command does.</A>
529 This will install the compiler, other executables and libraries in
530 to the appropriate system directories. The default is to copy the
531 executables to /usr/local/bin and the libraries and header files to
532 /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
536 <H2><A NAME="SECTION00035000000000000000">
537 2.5 Additional Information for Windows Users</A>
541 The standard method of installing on a Unix system involves compiling
542 the source package. This is easily done under Unix, but under Windows
543 it can be a more difficult process. The Cygwin is a large package
544 to download, and the compilation runs considerably slower under Windows
545 due to the overhead of the Cygwin tool set. An alternative is to install
546 a pre-compiled Windows binary package. There are various trade-offs
547 between each of these methods.
550 The Cygwin package allows a Windows user to run a Unix command line
551 interface(bash shell) and also implements a Unix like file system
552 on top of Windows. Included are many of the famous GNU software development
553 tools which can augment the SDCC compiler.This is great if you have
554 some experience with Unix command line tools and file system conventions,
555 if not you may find it easier to start by installing a binary Windows
556 package. The binary packages work with the Windows file system conventions.
560 <H3><A NAME="SECTION00035100000000000000">
561 2.5.1 Getting started with Cygwin</A>
565 SDCC is typically distributed as a tarred/gzipped file(.tgz). This
566 is a packed file similar to a .zip file. Cygwin includes the tools
567 you will need to unpack the SDCC distribution(tar and gzip). To unpack
568 it, simply follow the instructions under the Linux/Unix install section.
569 Before you do this you need to learn how to start a cygwin shell and
570 some of the basic commands used to move files, change directory, run
571 commands and so on. The change directory command is ``cd'', the
572 move command is ``mv''. To print the current working directory,
573 type ``pwd''. To make a directory, use ``mkdir''.
576 There are some basic differences between Unix and Windows file systems
577 you should understand. When you type in directory paths, Unix and
578 the Cygwin bash prompt uses forward slashes '/' between directories
579 while Windows traditionally uses '\' backward slashes.
580 So when you work at the Cygwin bash prompt, you will need to use the
581 forward '/' slashes. Unix does not have a concept of drive letters,
582 such as ``c:``, instead all files systems attach and appear
587 <H3><A NAME="SECTION00035200000000000000">
588 2.5.2 Running SDCC as Native Compiled Executables</A>
592 If you use the pre-compiled binaries, the install directories for
593 the libraries and header files may need to be specified on the sdcc
594 command line like this: sdcc -L c:\usr\local\sdcc\lib\small
595 -I c:\usr\local\sdcc\include
596 test.c if you are running outside of a Unix bash shell.
599 If you have successfully installed and compiled SDCC with the Cygwin
600 package, it is possible to compile into native .exe files by using
601 the additional makefiles included for this purpose. For example, with
602 the Borland 32-bit compiler you would run make -f Makefile.bcc. A
603 command line version of the Borland 32-bit compiler can be downloaded
604 from the Inprise web site.
608 <H2><A NAME="SECTION00036000000000000000">
609 2.6 SDCC on Other Platforms</A>
615 <LI><B>FreeBSD and other non-GNU Unixes</B> - Make sure the GNU make
616 is installed as the default make tool.
618 <LI>SDCC has been ported to run under a variety of operating systems and
619 processors. If you can run GNU GCC/make then chances are good SDCC
620 can be compiled and run on your system.
626 <H2><A NAME="SECTION00037000000000000000">
627 2.7 Advanced Install Options</A>
631 The ``configure'' command has several options. The most commonly
632 used option is -prefix=<directory name>, where <directory name> is
633 the final location for the sdcc executables and libraries, (default
634 location is /usr/local). The installation process will create the
635 following directory structure under the <directory name> specified.
638 bin/ - binary exectables (add to PATH environment variable)
639 <BR> share/
640 <BR> sdcc/include/ - include header files
641 <BR> sdcc/lib/ -
642 <BR> small/ - Object & library files for small
644 <BR> large/ - Object & library files for large
646 <BR> ds390/ - Object & library files forDS80C390
653 <B><U><FONT SIZE="+1">'./configure -prefix=/usr/local'' </FONT></U></B>
658 will configure the compiler to be installed in directory /usr/local/bin.
662 <H2><A NAME="SECTION00038000000000000000">
663 2.8 Components of SDCC</A>
667 SDCC is not just a compiler, but a collection of tools by various
668 developers. These include linkers, assemblers, simulators and other
669 components. Here is a summary of some of the components. Note that
670 the included simulator and assembler have separate documentation which
671 you can find in the source package in their respective directories.
672 As SDCC grows to include support for other processors, other packages
673 from various developers are included and may have their own sets of
677 You might want to look at the various executables which are installed
678 in the bin directory. At the time of this writing, we find the following
682 <B>sdcc</B> - The compiler.
685 <B>aslink</B> -The linker for 8051 type processors.
688 <B>asx8051</B> - The assembler for 8051 type processors.
691 <B>sdcpp</B> - The C preprocessor.
694 <B>sdcpd</B> - The source debugger.
697 <B>s51</B> - The ucSim 8051 simulator.
700 <B>linkz80, linkgbz80</B> - The Z80 and GameBoy Z80 linkers.
703 <B>as-z80, as-gbz80</B> - The Z80 and GameBoy Z80 assemblers.
706 <B>packihx</B> - A tool to pack Intel hex files.
709 As development for other processors proceeds, this list will expand
710 to include executables to support processors like AVR, PIC, etc.
714 <H3><A NAME="SECTION00038100000000000000">
715 2.8.1 cpp ( C-Preprocessor)</A>
719 The preprocessor is extracted into the directory <I>SDCCDIR/cpp</I>,
720 it is a modified version of the GNU preprocessor. The C preprocessor
721 is used to pull in #include sources, process #ifdef statements,
726 <H3><A NAME="SECTION00038200000000000000">
727 2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)</A>
731 This is retargettable assembler & linkage editor, it was developed
732 by Alan Baldwin, John Hartman created the version for 8051, and I
733 (Sandeep) have some enhancements and bug fixes for it to work properly
734 with the SDCC. This component is extracted into the directory <I>SDCCDIR/asxxxx.</I>
738 <H3><A NAME="SECTION00038300000000000000">
739 2.8.3 SDCC - The compiler</A>
743 This is the actual compiler, it in turn uses the c-preprocessor and
744 invokes the assembler and linkage editors. All files with the prefix
745 <I>SDCC</I> are part of the compiler and are extracted into the the
746 directory <I>SDCCDIR.</I>
750 <H3><A NAME="SECTION00038400000000000000">
751 2.8.4 S51 - Simulator</A>
755 s51 is a freeware, opensource simulator developed by Daniel Drotos
756 <drdani@mazsola.iit.uni-miskolc.hu>. The executable is built as part
757 of the build process, for more information visit Daniel's website
758 at <http://mazsola.iit.uni-miskolc.hu/drdani/embedded/s51/>.
762 <H3><A NAME="SECTION00038500000000000000">
763 2.8.5 SDCDB - Source Level Debugger</A>
767 SDCDB is the companion source level debugger . The current version
768 of the debugger uses Daniel's Simulator S51, but can be easily changed
769 to use other simulators.
773 <H1><A NAME="SECTION00040000000000000000">
779 <H2><A NAME="SECTION00041000000000000000">
785 <H3><A NAME="SECTION00041100000000000000">
786 3.1.1 Single Source File Projects</A>
790 For single source file 8051 projects the process is very simple. Compile
791 your programs with the following command
794 <FONT SIZE="-1">sdcc sourcefile.c</FONT>
799 The above command will compile ,assemble and link your source file.
800 Output files are as follows.
805 <LI><FONT SIZE="-1">sourcefile.asm - Assembler source file created by the
810 <LI><FONT SIZE="-1">sourcefile.lst - Assembler listing file created by
815 <LI><FONT SIZE="-1">sourcefile.rst - Assembler listing file updated with
816 linkedit information , created by linkage editor</FONT>
820 <LI><FONT SIZE="-1">sourcefile.sym - symbol listing for the sourcefile,
821 created by the assembler.</FONT>
825 <LI><FONT SIZE="-1">sourcefile.rel - Object file created by the assembler,
826 input to Linkage editor.</FONT>
830 <LI><FONT SIZE="-1">sourcefile.map - The memory map for the load module,
831 created by the Linker.</FONT>
835 <LI><FONT SIZE="-1">sourcefile.<ihx | s19> - The load module : ihx - Intel
836 hex format (default ), s19 - Motorola S19 format when compiler option
837 -out-fmt-s19 is used.</FONT>
845 <H3><A NAME="SECTION00041200000000000000">
846 3.1.2 Projects with Multiple Source Files</A>
850 SDCC can compile only ONE file at a time. Let us for example assume
851 that you have a project containing the following files.
854 <FONT SIZE="-1">foo1.c ( contains some functions )</FONT>
859 <FONT SIZE="-1">foo2.c (contains some more functions)</FONT>
864 <FONT SIZE="-1">foomain.c (contains more functions and the function
870 The first two files will need to be compiled separately with the commands
873 <FONT SIZE="-1">sdcc -c foo1.c</FONT>
878 <FONT SIZE="-1">sdcc -c foo2.c</FONT>
883 Then compile the source file containing main and link the other files
884 together with the following command.
887 <FONT SIZE="-1">sdcc foomain.c foo1.rel foo2.rel</FONT>
892 Alternatively <I>foomain.c</I> can be separately compiled as well
895 <FONT SIZE="-1">sdcc -c foomain.c </FONT>
900 <FONT SIZE="-1">sdcc foomain.rel foo1.rel foo2.rel</FONT>
905 The file containing the main function MUST be the FIRST file specified
906 in the command line , since the linkage editor processes file in the
907 order they are presented to it.
911 <H3><A NAME="SECTION00041300000000000000">
912 3.1.3 Projects with Additional Libraries</A>
916 Some reusable routines may be compiled into a library, see the documentation
917 for the assembler and linkage editor in the directory <I>SDCCDIR/asxxxx/asxhtm.htm</I>
918 this describes how to create a <I>.lib</I> library file, the libraries
919 created in this manner may be included using the command line, make
920 sure you include the -L <library-path> option to tell the linker where
921 to look for these files. Here is an example, assuming you have the
922 source file <I>'foomain.c</I>' and a library <I>'foolib.lib'</I> in
923 the directory <I>'mylib'</I>.
926 <FONT SIZE="-1">sdcc foomain.c foolib.lib -L mylib</FONT>
931 Note here that <I>'mylib</I>' must be an absolute path name.
934 The view of the way the linkage editor processes the library files,
935 it is recommended that you put each source routine in a separate file
936 and combine them using the .lib file. For an example see the standard
937 library file 'libsdcc.lib' in the directory SDCCDIR/sdcc51lib.
941 <H2><A NAME="SECTION00042000000000000000">
942 3.2 Command Line Options</A>
947 <H3><A NAME="SECTION00042100000000000000">
948 3.2.1 Processor Selection Options</A>
954 <LI>[<B>-mmcs51</B>]Generate code for the MCS51 (8051) family of processors.
955 This is the default processor target.
957 <LI>[<B>-mds390</B>]Generate code for the DS80C390 processor.
959 <LI>[<B>-mz80</B>]Generate code for the Z80 family of processors.
961 <LI>[<B>-mgbz80</B>]Generate code for the GameBoy Z80 processor.
963 <LI>[<B>-mavr</B>]Generate code for the Atmel AVR processor(In development,
966 <LI>[<B>-mpic14</B>]Generate code for the PIC 14-bit processors(In development,
969 <LI>[<B>-mtlcs900h</B>]Generate code for the Toshiba TLCS-900H processor(In
970 development, not complete).
975 <H3><A NAME="SECTION00042200000000000000">
976 3.2.2 Path, Lib and Define Options</A>
982 <LI>[<B><U>-I<path></U></B>] The additional location where the pre
983 processor will look for <..h> or ``..h'' files.
985 <LI>[<B><U><FONT SIZE="+1">-D<macro[=value]></FONT></U></B>]Command line definition
986 of macros. Passed to the pre processor.
988 <LI>[<B><U><FONT SIZE="+1">-lib-path(-L)</FONT></U></B>]<absolute path to additional
989 libraries> This option is passed to the linkage editor, additional
990 libraries search path. The path name must be absolute. Additional
991 library files may be specified in the command line . See section Compiling
992 programs for more details.
997 <H3><A NAME="SECTION00042300000000000000">
998 3.2.3 MCS51 Options</A>
1004 <LI>[<B><FONT SIZE="+1">-model-large</FONT></B>]Generate code for Large model programs
1005 see section Memory Models for more details. If this option is used
1006 all source files in the project should be compiled with this option.
1007 In addition the standard library routines are compiled with small
1008 model , they will need to be recompiled.
1010 <LI>[<B><U><FONT SIZE="+1">-model-small</FONT></U></B>]Generate code for Small
1011 Model programs see section Memory Models for more details. This is
1014 <LI>[<B><U><FONT SIZE="+1">-model-flat24</FONT></U></B>]Generate code forDS80C390
1015 24-bit flat mode. See section Memory Models for more details.
1017 <LI>[<B><U><FONT SIZE="+1">-stack-</FONT></U></B><B><I><U><FONT SIZE="+1">auto</FONT></U></I></B>]All
1018 functions in the source file will be compiled as <I>reentrant</I>,
1019 i.e. the parameters and local variables will be allocated on the stack.
1020 see section Parameters and Local Variables for more details. If this
1021 option is used all source files in the project should be compiled
1024 <LI>[<B><U><FONT SIZE="+1">-xstack</FONT></U></B>]Uses a pseudo stack in the first
1025 256 bytes in the external ram for allocating variables and passing
1026 parameters. See section on external stack for more details.
1031 <H3><A NAME="SECTION00042400000000000000">
1032 3.2.4 Optimization Options</A>
1038 <LI>[<B><U><FONT SIZE="+1">-nogcse</FONT></U></B>]Will not do global subexpression
1039 elimination, this option may be used when the compiler creates undesirably
1040 large stack/data spaces to store compiler temporaries. A warning message
1041 will be generated when this happens and the compiler will indicate
1042 the number of extra bytes it allocated. It recommended that this option
1043 NOT be used , #pragma NOGCSE can be used to turn off global subexpression
1044 elimination for a given function only.
1046 <LI>[<B><U><FONT SIZE="+1">-noinvariant</FONT></U></B>]Will not do loop invariant
1047 optimizations, this may be turned off for reasons explained for the
1048 previous option . For more details of loop optimizations performed
1049 see section Loop Invariants.It recommended that this option NOT be
1050 used , #pragma NOINVARIANT can be used to turn off invariant optimizations
1051 for a given function only.
1053 <LI>[<B><U><FONT SIZE="+1">-noinduction</FONT></U></B>]Will not do loop induction
1054 optimizations, see section Strength reduction for more details.It
1055 recommended that this option NOT be used , #pragma NOINDUCTION can
1056 be used to turn off induction optimizations for given function only.
1058 <LI>[<B><U><FONT SIZE="+1">-nojtbound</FONT></U></B>] Will not generate boundary
1059 condition check when switch statements are implemented using jump-tables.
1060 See section Switch Statements for more details.It recommended that
1061 this option NOT be used , #pragma NOJTBOUND can be used to turn off
1062 boundary checking for jump tables for a given function only.
1064 <LI>[<B><U><FONT SIZE="+1">-noloopreverse</FONT></U></B>]Will not do loop reversal
1067 <LI>[<B><U><FONT SIZE="+1">-noregparms</FONT></U></B>]By default the first parameter
1068 is passed using global registers (DPL,DPH,B,ACC). This option will
1069 disable parameter passing using registers. NOTE: if your program uses
1070 the 16/32 bit support routines (for multiplication/division) these
1071 library routines will need to be recompiled with the -noregparms
1077 <H3><A NAME="SECTION00042500000000000000">
1078 3.2.5 DS390 Options</A>
1084 <LI>[<B>-stack-auto</B>]See MCS51 section for description.
1086 <LI>[<B>-stack-10bit</B>]This option generates code for the 10 bit
1087 stack mode of the Dallas DS80C390 part. In this mode, the stack is
1088 located in the lower 1K of the internal RAM, which is mapped to 0x400000.
1089 Note that the support is incomplete, since it still uses a single
1090 byte as the stack pointer. This means that only the lower 256 bytes
1091 of the potential 1K stack space can actually be used. However, this
1092 does allow you to reclaim the precious 256 bytes of low RAM for use
1093 for the DATA and IDATA segments. The compiler will not generate any
1094 code to put the processor into 10 bit stack mode. It is important
1095 to ensure that the processor is in this mode before calling any re-entrant
1096 functions compiled with this option. In principle, this should work
1097 with the -stack-auto option, but that has not been tested. It is
1098 incompatible with the -xstack option. It also only makes sense if
1099 the processor is in 24 bit contiguous addressing mode (see the -model-flat24
1105 <H3><A NAME="SECTION00042600000000000000">
1106 3.2.6 Other Options</A>
1112 <LI>[<B><U><FONT SIZE="+1">-callee-saves</FONT></U></B>]<B><U><FONT SIZE="+1">function1[,function2][,function3]....</FONT></U></B>
1113 The compiler by default uses a caller saves convention for register
1114 saving across function calls, however this can cause unneccessary
1115 register pushing & popping when calling small functions from larger
1116 functions. This option can be used to switch the register saving convention
1117 for the function names specified. The compiler will not save registers
1118 when calling these functions, extra code will be generated at the
1119 entry & exit for these functions to save & restore the registers
1120 used by these functions, this can SUBSTANTIALLY reduce code & improve
1121 run time performance of the generated code. In future the compiler
1122 (with interprocedural analysis) will be able to determine the appropriate
1123 scheme to use for each function call. DO NOT use this option for built-in
1124 functions such as _muluint..., if this option is used for a library
1125 function the appropriate library function needs to be recompiled with
1126 the same option. If the project consists of multiple source files
1127 then all the source file should be compiled with the same -callee-saves
1128 option string. Also see Pragma Directive CALLEE-SAVES. .
1130 <LI>[<B><U>-debug</U></B>]When this option is used the compiler
1131 will generate debug information , that can be used with the SDCDB.
1132 The debug information is collected in a file with .cdb extension.
1133 For more information see documentation for SDCDB.
1135 <LI>[<B><U><FONT SIZE="+1">-regextend</FONT></U></B>] This option will cause the
1136 compiler to define pseudo registers , if this option is used, all
1137 source files in the project should be compiled with this option. See
1138 section Register Extension for more details.
1140 <LI>[<B><U><FONT SIZE="+1">-compile-only</FONT></U></B><FONT SIZE="+1">(-c)</FONT>] will compile
1141 and assemble the source only, will not call the linkage editor.
1143 <LI>[<B><U><FONT SIZE="+1">-xram-loc</FONT></U></B><Value>]The start location of
1144 the external ram, default value is 0. The value entered can be in
1145 Hexadecimal or Decimal format .eg. -xram-loc 0x8000 or -xram-loc
1148 <LI>[<B><U><FONT SIZE="+1">-code-loc</FONT></U></B><Value>]The start location of
1149 the code segment , default value 0. Note when this option is used
1150 the interrupt vector table is also relocated to the given address.
1151 The value entered can be in Hexadecimal or Decimal format .eg. -code-loc
1152 0x8000 or -code-loc 32768.
1154 <LI>[<B><U><FONT SIZE="+1">-stack-loc</FONT></U></B><Value>]The initial value of
1155 the stack pointer. The default value of the stack pointer is 0x07
1156 if only register bank 0 is used, if other register banks are used
1157 then the stack pointer is initialized to the location above the highest
1158 register bank used. eg. if register banks 1 & 2 are used the stack
1159 pointer will default to location 0x18. The value entered can be in
1160 Hexadecimal or Decimal format .eg. -stack-loc 0x20 or -stack-loc
1161 32. If all four register banks are used the stack will be placed after
1162 the data segment (equivalent to -stack-after-data)
1164 <LI>[<B><U><FONT SIZE="+1">-stack-after-data</FONT></U></B>]This option will cause
1165 the stack to be located in the internal ram after the data segment.
1167 <LI>[<B><U><FONT SIZE="+1">-data-loc</FONT></U></B><Value>]The start location of
1168 the internal ram data segment, the default value is 0x30.The value
1169 entered can be in Hexadecimal or Decimal format .eg. -data-loc 0x20
1172 <LI>[<B><U><FONT SIZE="+1">-idata-loc</FONT></U></B><Value>]The start location
1173 of the indirectly addressable internal ram, default value is 0x80.
1174 The value entered can be in Hexadecimal or Decimal format .eg. -idata-loc
1175 0x88 or -idata-loc 136.
1177 <LI>[<B><U><FONT SIZE="+1">-peep-file</FONT></U></B><filename>]This option can
1178 be used to use additional rules to be used by the peep hole optimizer.
1179 See section Peep Hole optimizations for details on how to write these
1182 <LI>[<B><U><FONT SIZE="+1">-E</FONT></U></B>]Run only the C preprocessor. Preprocess
1183 all the C source files specified and output the results to standard
1186 <LI>[<B><U><FONT SIZE="+1">-M</FONT></U></B>]Tell the preprocessor to output a rule
1187 suitable for make describing the dependencies of each object file.
1188 For each source file, the preprocessor outputs one make-rule whose
1189 target is the object file name for that source file and whose dependencies
1190 are all the files `#include'd in it. This rule may be a single line
1191 or may be continued with `\'-newline if it is long.
1192 The list of rules is printed on standard output instead of the preprocessed
1193 C program. `-M' implies `-E'.
1195 <LI>[<B><U><FONT SIZE="+1">-C</FONT></U></B>]Tell the preprocessor not to discard
1196 comments. Used with the `-E' option.
1198 <LI>[<B><U><FONT SIZE="+1">-MM</FONT></U></B>]Like `-M' but the output mentions
1199 only the user header files included with `#include file"'.
1200 System header files included with `#include <file>' are omitted.
1202 <LI>[<B><U><FONT SIZE="+1">-Aquestion(answer)</FONT></U></B>]Assert the answer answer
1203 for question, in case it is tested with a preprocessor conditional
1204 such as `#if #question(answer)'. `-A-' disables the standard assertions
1205 that normally describe the target machine.
1207 <LI>[<B><U><FONT SIZE="+1">-Aquestion</FONT></U></B>](answer) Assert the answer
1208 answer for question, in case it is tested with a preprocessor conditional
1209 such as `#if #question(answer)'. `-A-' disables the standard assertions
1210 that normally describe the target machine.
1212 <LI>[<B><U><FONT SIZE="+1">-Umacro</FONT></U></B>]Undefine macro macro. `-U' options
1213 are evaluated after all `-D' options, but before any `-include' and
1216 <LI>[<B><U><FONT SIZE="+1">-dM</FONT></U></B>]Tell the preprocessor to output only
1217 a list of the macro definitions that are in effect at the end of preprocessing.
1218 Used with the `-E' option.
1220 <LI>[<B><U><FONT SIZE="+1">-dD</FONT></U></B>]Tell the preprocessor to pass all
1221 macro definitions into the output, in their proper sequence in the
1224 <LI>[<B><U><FONT SIZE="+1">-dN</FONT></U></B>]Like `-dD' except that the macro arguments
1225 and contents are omitted. Only `#define name' is included in the
1228 <LI>[<B><U><FONT SIZE="+1">-S</FONT></U></B>]Stop after the stage of compilation
1229 proper; do not as- semble. The output is an assembler code file for
1230 the input file specified.
1232 <LI>[<B><U>-Wa_asmOption[,asmOption]</U></B>...]Pass the asmOption
1235 <LI>[<B><U>-Wl_linkOption[,linkOption]</U></B>].. Pass the
1236 linkOption to the linker.
1238 <LI>[<B><U><FONT SIZE="+1">-int-long-reent</FONT></U></B>] Integer (16 bit) and
1239 long (32 bit) libraries have been compiled as reentrant. Note by default
1240 these libraries are compiled as non-reentrant. See section Installation
1243 <LI>[<B><U><FONT SIZE="+1">-cyclomatic</FONT></U></B>]This option will cause the
1244 compiler to generate an information message for each function in the
1245 source file. The message contains some <I>important</I> information
1246 about the function. The number of edges and nodes the compiler detected
1247 in the control flow graph of the function, and most importantly the
1248 <I>cyclomatic complexity</I> see section on Cyclomatic Complexity
1251 <LI>[<B><U><FONT SIZE="+1">-float-reent</FONT></U></B>] Floating point library
1252 is compiled as reentrant.See section Installation for more details.
1254 <LI>[<B><U><FONT SIZE="+1">-out-fmt-ihx</FONT></U></B>]The linker output (final
1255 object code) is in Intel Hex format. (This is the default option).
1257 <LI>[<B><U><FONT SIZE="+1">-out-fmt-s19</FONT></U></B>]The linker output (final
1258 object code) is in Motorola S19 format.
1260 <LI>[<B><U><FONT SIZE="+1">-nooverlay</FONT></U></B>] The compiler will not overlay
1261 parameters and local variables of any function, see section Parameters
1262 and local variables for more details.
1264 <LI>[<B><U><FONT SIZE="+1">-main-return</FONT></U></B>]This option can be used
1265 when the code generated is called by a monitor program. The compiler
1266 will generate a 'ret' upon return from the 'main' function. The default
1267 option is to lock up i.e. generate a 'ljmp .' .
1269 <LI>[<B><U><FONT SIZE="+1">-no-peep</FONT></U></B>] Disable peep-hole optimization.
1271 <LI>[<B><U><FONT SIZE="+1">-peep-asm</FONT></U></B>] Pass the inline assembler
1272 code through the peep hole optimizer. Can cause unexpected changes
1273 to inline assembler code , please go through the peephole optimizer
1274 rules defnied in file 'SDCCpeeph.def' before using this option.
1276 <LI>[<B><U><FONT SIZE="+1">-iram-size</FONT></U></B><Value>]Causes the linker to
1277 check if the interal ram usage is within limits of the given value.
1282 <H3><A NAME="SECTION00042700000000000000">
1283 3.2.7 Intermediate Dump Options</A>
1287 The following options are provided for the purpose of retargetting
1288 and debugging the compiler . These provided a means to dump the intermediate
1289 code (iCode) generated by the compiler in human readable form at various
1290 stages of the compilation process.
1295 <LI>[<B><U><FONT SIZE="+1">-dumpraw</FONT></U></B>]. This option will cause the
1296 compiler to dump the intermediate code into a file of named <I><source
1297 filename>.dumpraw</I> just after the intermediate code has been generated
1298 for a function , i.e. before any optimizations are done. The basic
1299 blocks at this stage ordered in the depth first number, so they may
1300 not be in sequence of execution.
1302 <LI>[<B><U><FONT SIZE="+1">-dumpgcse</FONT></U></B><FONT SIZE="+1">.</FONT>]Will create a dump
1303 if iCode, after global subexpression elimination, into a file named
1304 <I><source filename>.dumpgcse.</I>
1306 <LI>[<B><U><FONT SIZE="+1">-dumpdeadcode</FONT></U></B>].Will create a dump if
1307 iCode, after deadcode elimination, into a file named <I><source
1308 filename>.dumpdeadcode.</I>
1310 <LI>[<B><U><FONT SIZE="+1">-dumploop.</FONT></U></B>]Will create a dump if iCode,
1311 after loop optimizations, into a file named <I><source filename>.dumploop.</I>
1313 <LI>[<B><U><FONT SIZE="+1">-dumprange.</FONT></U></B>]Will create a dump if iCode,
1314 after live range analysis, into a file named <I><source filename>.dumprange.</I>
1316 <LI>[<B><U><FONT SIZE="+1">-dumpregassign.</FONT></U></B>]Will create a dump if
1317 iCode, after register assignment , into a file named <I><source
1318 filename>.dumprassgn.</I>
1320 <LI>[<B><U><FONT SIZE="+1">-dumpall.</FONT></U></B>]Will cause all the above mentioned
1321 dumps to be created.
1323 </UL>Note that the files created for the dump are appended to each time.
1324 So the files should be deleted manually , before each dump is created.
1327 When reporting bugs, it can be helpful to include these dumps along
1328 with the portion of the code that is causing the problem.
1332 <H2><A NAME="SECTION00043000000000000000">
1333 3.3 MCS51 Storage Class Language Extensions</A>
1337 In addition to the ANSI storage classes SDCC allows the following
1338 MCS51 specific storage classes.
1342 <H3><A NAME="SECTION00043100000000000000">
1347 Variables declared with this storage class will be placed in the extern
1348 RAM. This is the <B>default</B> storage class for Large Memory model
1352 <FONT SIZE="-1">eg.</FONT> <I><FONT SIZE="-1">xdata unsigned char xduc;</FONT></I>
1358 <H3><A NAME="SECTION00043200000000000000">
1363 This is the <B>default</B> storage class for Small Memory model.
1364 Variables declared with this storage class will be allocated in the
1368 <FONT SIZE="-1">eg.</FONT> <I><FONT SIZE="-1">data int iramdata;</FONT></I>
1374 <H3><A NAME="SECTION00043300000000000000">
1379 Variables declared with this storage class will be allocated into
1380 the indirectly addressable portion of the internal ram of a 8051 .
1383 <FONT SIZE="-1">eg.</FONT><I><FONT SIZE="-1">idata int idi;</FONT></I>
1389 <H3><A NAME="SECTION00043400000000000000">
1394 This is a data-type and a storage class specifier. When a variable
1395 is declared as a bit , it is allocated into the bit addressable memory
1399 eg.<I>bit iFlag;</I>
1403 <H3><A NAME="SECTION00043500000000000000">
1404 3.3.5 sfr / sbit</A>
1408 Like the bit keyword, <I>sfr / sbit</I> signifies both a data-type
1409 and storage class, they are used to describe the special function
1410 registers and special bit variables of a 8051.
1416 <I>sfr at 0x80 P0;</I> /* <SMALL>SPECIAL FUNCTION REGISTER </SMALL>P0 <SMALL>AT
1417 LOCATION 0X80 </SMALL>*/
1420 <I>sbit at 0xd7 CY; /*</I> <I>CY (C<SMALL>ARRY </SMALL>F<SMALL>LAG) </SMALL>*/</I>
1424 <H2><A NAME="SECTION00044000000000000000">
1429 SDCC allows (via language extensions) pointers to explicitly point
1430 to any of the memory spaces of the 8051. In addition to the explicit
1431 pointers, the compiler also allows a <I>_generic</I> class of pointers
1432 which can be used to point to any of the memory spaces.
1435 Pointer declaration examples.
1438 <FONT SIZE="-1">/* pointer physically in xternal ram pointing to object
1439 in internal ram */ </FONT>
1440 <BR><FONT SIZE="-1">data unsigned char * xdata p;</FONT>
1446 <FONT SIZE="-1">/* pointer physically in code rom pointing to data in xdata
1448 <BR><FONT SIZE="-1">xdata unsigned char * code p;</FONT>
1454 <FONT SIZE="-1">/* pointer physically in code space pointing to data in
1455 code space */ </FONT>
1456 <BR><FONT SIZE="-1">code unsigned char * code p;</FONT>
1458 <BR><FONT SIZE="-1">/* the folowing is a generic pointer physically located
1459 in xdata space */</FONT>
1460 <BR><FONT SIZE="-1">char * xdata p;</FONT>
1465 Well you get the idea. For compatibility with the previous version
1466 of the compiler, the following syntax for pointer declaration is also
1467 supported. Note the above examples will be portable to other commercially
1468 available compilers.
1471 <FONT SIZE="-1">unsigned char _xdata *ucxdp; /* pointer to data in external
1473 <BR><FONT SIZE="-1">unsigned char _data *ucdp ; /* pointer to data in internal
1475 <BR><FONT SIZE="-1">unsigned char _code *uccp ; /* pointer to data in R/O
1476 code space */</FONT>
1477 <BR><FONT SIZE="-1">unsigned char _idata *uccp; /* pointer to upper 128
1478 bytes of ram */</FONT>
1483 All unqualified pointers are treated as 3 - byte '_generic' pointers.
1484 These type of pointers can also to be explicitly declared.
1487 <FONT SIZE="-1">unsigned char _generic *ucgp;</FONT>
1492 The highest order byte of the generic pointers contains the data space
1493 information. Assembler support routines are called whenever data is
1494 stored or retrieved using _generic pointers. These are useful for
1495 developing reusable library routines. Explicitly specifying the pointer
1496 type will generate the most efficient code. Pointers declared using
1497 a mixture of OLD/NEW style could have unpredictable results.
1501 <H2><A NAME="SECTION00045000000000000000">
1502 3.5 Parameters & Local Variables</A>
1506 Automatic (local) variables and parameters to functions can either
1507 be placed on the stack or in data-space. The default action of the
1508 compiler is to place these variables in the internal RAM ( for small
1509 model) or external RAM (for Large model). They can be placed on the
1510 stack either by using the <I>-stack-auto</I> compiler option or by
1511 using the 'reentrant' keyword in the function declaration.
1514 <TT><FONT SIZE="-2">eg</FONT></TT>
1519 <FONT SIZE="-1">unsigned short foo( short i) reentrant { </FONT>
1520 <BR><FONT SIZE="-1">... </FONT>
1521 <BR><FONT SIZE="-1">}</FONT>
1526 Note that when the parameters & local variables are declared in the
1527 internal/external ram the functions are non-reentrant. Since stack
1528 space on 8051 is limited the <I>'reentrant'</I> keyword or the <I>-stack-auto</I>
1529 option should be used sparingly. Note the reentrant keyword just means
1530 that the parameters & local variables will be allocated to the stack,
1531 it DOES NOT mean that the function is register bank independent.
1534 When compiled with the default option (i.e. non-reentrant ), local
1535 variables can be assigned storage classes and absolute addresses.
1538 <TT><FONT SIZE="-2">eg</FONT></TT>
1543 <FONT SIZE="-1">unsigned short foo() { </FONT>
1544 <BR><FONT SIZE="-1"> xdata unsigned short i; </FONT>
1545 <BR><FONT SIZE="-1"> bit bvar; </FONT>
1546 <BR><FONT SIZE="-1"> data at 0x31 unsiged short j; </FONT>
1547 <BR><FONT SIZE="-1">... </FONT>
1548 <BR><FONT SIZE="-1">}</FONT>
1553 In the above example the variable <I>i</I> will be allocated in the
1554 external ram, <I>bvar</I> in bit addressable space and <I>j</I> in
1555 internal ram. When compiled with the <I>-stack-auto</I> or when a
1556 function is declared as <I>'reentrant'</I> local variables cannot
1557 be assigned storage classes or absolute addresses.
1560 Parameters however are not allowed any storage class, (storage classes
1561 for parameters will be ignored), their allocation is governed by the
1562 memory model in use , and the reentrancy options.
1566 <H2><A NAME="SECTION00046000000000000000">
1571 For non-reentrant functions SDCC will try to reduce internal ram space
1572 usage by overlaying parameters and local variables of a function (if
1573 possible). Parameters and local variables of a function will be allocated
1574 to an overlayable segment if the function has <I>no other function
1575 calls and the function is non-reentrant and the memory model is small.</I>
1576 If an explicit storage class is specified for a local variable , it
1577 will NOT be overplayed.
1580 Note that the compiler (not the linkage editor) makes the decision
1581 for overlaying the data items. Functions that are called from an interrupt
1582 service routine should be preceded by a #pragma NOOVERLAY if they
1583 are not reentrant Along the same lines the compiler does not do any
1584 processing with the inline assembler code so the compiler might incorrectly
1585 assign local variables and parameters of a function into the overlay
1586 segment if the only function call from a function is from inline assembler
1587 code, it is safe to use the #pragma NOOVERLAY for functions which
1588 call other functions using inline assembler code.
1591 Parameters and Local variables of functions that contain 16 or 32
1592 bit multiplication or division will NOT be overlayed since these are
1593 implemented using external functions.
1599 <FONT SIZE="-1">#pragma SAVE </FONT>
1600 <BR><FONT SIZE="-1">#pragma NOOVERLAY </FONT>
1601 <BR><FONT SIZE="-1">void set_error( unsigned short errcd) </FONT>
1602 <BR><FONT SIZE="-1">{ </FONT>
1603 <BR><FONT SIZE="-1"> P3 = errcd; </FONT>
1604 <BR><FONT SIZE="-1">} </FONT>
1605 <BR><FONT SIZE="-1">#pragma RESTORE </FONT>
1606 <BR><FONT SIZE="-1">void some_isr () interrupt 2 using 1 </FONT>
1607 <BR><FONT SIZE="-1">{ </FONT>
1608 <BR><FONT SIZE="-1"> ... </FONT>
1609 <BR><FONT SIZE="-1"> set_error(10); </FONT>
1610 <BR><FONT SIZE="-1"> ... </FONT>
1611 <BR><FONT SIZE="-1">}</FONT>
1616 In the above example the parameter <I>errcd</I> for the function <I>set_error</I>
1617 would be assigned to the overlayable segment (if the #pragma NOOVERLAY
1618 was not present) , this could cause unpredictable runtime behavior.
1619 The pragma NOOVERLAY ensures that the parameters and local variables
1620 for the function are NOT overlayed.
1624 <H2><A NAME="SECTION00047000000000000000">
1625 3.7 Critical Functions</A>
1629 A special keyword may be associated with a function declaring it as
1630 '<I>critical</I>'. SDCC will generate code to disable all interrupts
1631 upon entry to a critical function and enable them back before returning
1632 . Note that nesting critical functions may cause unpredictable results.
1638 <FONT SIZE="-1">int foo () critical </FONT>
1639 <BR><FONT SIZE="-1">{ </FONT>
1640 <BR><FONT SIZE="-1">... </FONT>
1641 <BR><FONT SIZE="-1">... </FONT>
1642 <BR><FONT SIZE="-1">}</FONT>
1647 The critical attribute maybe used with other attributes like <I>reentrant.</I>
1651 <H2><A NAME="SECTION00048000000000000000">
1652 3.8 Absolute Addressing</A>
1656 Data items can be assigned an absolute address with the <I>at <address></I>
1657 keyword, in addition to a storage class.
1663 <FONT SIZE="-1">xdata at 0x8000 unsigned char PORTA_8255 ;</FONT>
1668 In the above example the <I>PORTA_8255</I> will be allocated to the
1669 location 0x8000 of the external ram.
1672 Note that is this feature is provided to give the programmer access
1673 to <I>memory mapped</I> devices attached to the controller. The compiler
1674 does not actually reserve any space for variables declared in this
1675 way (they are implemented with an equate in the assembler), thus it
1676 is left to the programmer to make sure there are no overlaps with
1677 other variables that are declared without the absolute address, the
1678 assembler listing file (.lst) and the linker output files (<filename>.rst)
1679 and (<filename>.map) are a good places to look for such overlaps.
1682 Absolute address can be specified for variables in all storage classes.
1685 <FONT SIZE="-1">eg.</FONT>
1690 <FONT SIZE="-1">bit at 0x02 bvar;</FONT>
1695 The above example will allocate the variable at offset 0x02 in the
1696 bit-addressable space. There is no real advantage to assigning absolute
1697 addresses to variables in this manner , unless you want strict control
1698 over all the variables allocated.
1702 <H2><A NAME="SECTION00049000000000000000">
1703 3.9 Interrupt Service Routines</A>
1707 SDCC allows interrupt service routines to be coded in C, with some
1711 <FONT SIZE="-1">void timer_isr (void) interrupt 2 using 1 </FONT>
1712 <BR><FONT SIZE="-1">{ </FONT>
1713 <BR><FONT SIZE="-1">.. </FONT>
1714 <BR><FONT SIZE="-1">}</FONT>
1719 The number following the 'interrupt' keyword is the interrupt number
1720 this routine will service. The compiler will insert a call to this
1721 routine in the interrupt vector table for the interrupt number specified.
1722 The 'using' keyword is used to tell the compiler to use the specified
1723 register bank (8051 specific) when generating code for this function.
1724 Note that when some function is called from an interrupt service routine
1725 it should be preceded by a #pragma NOOVERLAY (if it is not reentrant)
1726 . A special note here, int (16 bit) and long (32 bit) integer division,
1727 multiplication & modulus operations are implemented using external
1728 support routines developed in ANSI-C, if an interrupt service routine
1729 needs to do any of these operations then the support routines (as
1730 mentioned in a following section) will have to recompiled using the
1731 -stack-auto option and the source file will need to be compiled using
1732 the -int-long-rent compiler option.
1735 If you have multiple source files in your project, interrupt service
1736 routines can be present in any of them, but a prototype of the isr
1737 MUST be present in the file that contains the function <I>'main'</I>.
1740 Interrupt Numbers and the corresponding address & descriptions for
1741 the Standard 8051 are listed below. SDCC will automatically adjust
1742 the interrupt vector table to the maximum interrupt number specified.
1745 <TABLE CELLPADDING=3 BORDER="1">
1746 <TR><TD ALIGN="CENTER">Interrupt #</TD>
1747 <TD ALIGN="CENTER">Description</TD>
1748 <TD ALIGN="CENTER">Vector Address</TD>
1750 <TR><TD ALIGN="CENTER">0</TD>
1751 <TD ALIGN="CENTER">External 0</TD>
1752 <TD ALIGN="CENTER">0x0003</TD>
1754 <TR><TD ALIGN="CENTER">1</TD>
1755 <TD ALIGN="CENTER">Timer 0</TD>
1756 <TD ALIGN="CENTER">0x000B</TD>
1758 <TR><TD ALIGN="CENTER">2</TD>
1759 <TD ALIGN="CENTER">External 1</TD>
1760 <TD ALIGN="CENTER">0x0013</TD>
1762 <TR><TD ALIGN="CENTER">3</TD>
1763 <TD ALIGN="CENTER">Timer 1</TD>
1764 <TD ALIGN="CENTER">0x001B</TD>
1766 <TR><TD ALIGN="CENTER">4</TD>
1767 <TD ALIGN="CENTER">Serial</TD>
1768 <TD ALIGN="CENTER">0x0023</TD>
1773 If the interrupt service routine is defined without a register bank
1774 or with register bank 0 (using 0), the compiler will save the registers
1775 used by itself on the stack (upon entry and restore them at exit),
1776 however if such an interrupt service routine calls another function
1777 then the entire register bank will be saved on the stack. This scheme
1778 may be advantageous for small interrupt service routines which have
1782 If the interrupt service routine is defined to be using a specific
1783 register bank then only ``a'',''b'' & ``dptr'' are save
1784 and restored, if such an interrupt service routine calls another function
1785 (using another register bank) then the entire register bank of the
1786 called function will be saved on the stack. This scheme is recommended
1787 for larger interrupt service routines.
1790 Calling other functions from an interrupt service routine is not recommended
1791 avoid it if possible.
1795 <H2><A NAME="SECTION000410000000000000000">
1796 3.10 Startup Code</A>
1800 The compiler inserts a jump to the C routine <B>_sdcc__external__startup()</B>
1801 at the start of the CODE area. This routine can be found in the file
1802 <B>SDCCDIR/sdcc51lib/_startup.c</B>, by default this routine returns
1803 0, if this routine returns a non-zero value , the static & global
1804 variable initialization will be skipped and the function main will
1805 be invoked, other wise static & global variables will be initialized
1806 before the function main is invoked. You could add a <B>_sdcc__external__startup()</B>
1807 routine to your program to override the default if you needed to setup
1808 hardware or perform some other critical operation prior to static
1809 & global variable initialization.
1813 <H2><A NAME="SECTION000411000000000000000">
1814 3.11 Inline Assembler Code</A>
1818 SDCC allows the use of in-line assembler with a few restriction as
1819 regards labels. All labels defined within inline assembler code HAS
1820 TO BE of the <I>form nnnnn$</I> where nnnn is a number less than
1821 100 (which implies a limit of utmost 100 inline assembler labels <SMALL>PER
1822 FUNCTION)</SMALL>. It is strongly recommended that each assembly instruction
1823 (including labels) be placed in a separate line ( as the example shows).
1824 When the <B><U>-peep-asm</U></B> command line option is used,
1825 the inline assembler code will be passed through the peephole optimizer,
1826 this might cause some unexpected changes in the inline assembler code,
1827 please go throught the peephole optimizer rules defined in file 'SDCCpeeph.def'
1828 carefully before using this option.
1831 <FONT SIZE="-1">eg</FONT>
1836 <FONT SIZE="-1">_asm </FONT>
1837 <BR><FONT SIZE="-1"> mov b,#10 </FONT>
1838 <BR><FONT SIZE="-1">00001$: </FONT>
1839 <BR><FONT SIZE="-1"> djnz b,00001$ </FONT>
1840 <BR><FONT SIZE="-1">_endasm ;</FONT>
1845 The inline assembler code can contain any valid code understood by
1846 the assembler (this includes any assembler directives and comment
1847 lines ) . The compiler does not do any validation of the code within
1848 the <I>_asm ... _endasm;</I> keyword pair.
1851 Inline assembler code cannot reference any C-Labels however it can
1852 reference labels defined by the inline assembler.
1855 <FONT SIZE="-1">eg</FONT>
1860 <FONT SIZE="-1">foo() { </FONT>
1861 <BR><FONT SIZE="-1">... /* some c code */ </FONT>
1862 <BR><FONT SIZE="-1">_asm </FONT>
1863 <BR><FONT SIZE="-1"> ; some assembler code </FONT>
1864 <BR><FONT SIZE="-1"> ljmp $0003 </FONT>
1865 <BR><FONT SIZE="-1">_endasm ; </FONT>
1866 <BR><FONT SIZE="-1">... /* some more c code */ </FONT>
1867 <BR><FONT SIZE="-1">clabel: /* inline assembler cannot reference this label
1869 <BR><FONT SIZE="-1">_asm </FONT>
1870 <BR><FONT SIZE="-1"> $0003: ;label (can be reference by inline assembler
1872 <BR><FONT SIZE="-1">_endasm ; </FONT>
1873 <BR><FONT SIZE="-1">... </FONT>
1874 <BR><FONT SIZE="-1">}</FONT>
1879 In other words inline assembly code can access labels defined in inline
1880 assembly. The same goes the other way, ie. labels defines in inline
1881 assembly CANNOT be accessed by C statements.
1885 <H2><A NAME="SECTION000412000000000000000">
1886 3.12 int(16 bit) and long (32 bit ) Support</A>
1890 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
1891 multiplication and modulus operations are implemented by support routines.
1892 These support routines are all developed in ANSI-C to facilitate porting
1893 to other MCUs. The following files contain the described routine,
1894 all of them can be found in the directory SDCCDIR/sdcc51lib
1899 <LI><FONT SIZE="-1">_mulsint.c - signed 16 bit multiplication (calls _muluint)</FONT>
1903 <LI><FONT SIZE="-1">_muluint.c - unsigned 16 bit multiplication</FONT>
1907 <LI><FONT SIZE="-1">_divsint.c - signed 16 bit division (calls _divuint)</FONT>
1911 <LI><FONT SIZE="-1">_divuint.c - unsigned 16 bit division.</FONT>
1915 <LI><FONT SIZE="-1">_modsint.c - signed 16 bit modulus (call _moduint)</FONT>
1919 <LI><FONT SIZE="-1">_moduint.c - unsigned 16 bit modulus.</FONT>
1923 <LI><FONT SIZE="-1">_mulslong.c - signed 32 bit multiplication (calls
1928 <LI><FONT SIZE="-1">_mululong.c - unsigned32 bit multiplication.</FONT>
1932 <LI><FONT SIZE="-1">_divslong.c - signed 32 division (calls _divulong)</FONT>
1936 <LI><FONT SIZE="-1">_divulong.c - unsigned 32 division.</FONT>
1940 <LI><FONT SIZE="-1">_modslong.c - signed 32 bit modulus (calls _modulong).</FONT>
1944 <LI><FONT SIZE="-1">_modulong.c - unsigned 32 bit modulus.</FONT>
1949 All these routines are compiled as non-reentrant and small model.
1950 Since they are compiled as non-reentrant, interrupt service routines
1951 should not do any of the above operations, if this unavoidable then
1952 the above routines will need to ne compiled with the -stack-auto
1953 option, after which the source program will have to be compiled with
1954 -int-long-rent option.
1958 <H2><A NAME="SECTION000413000000000000000">
1959 3.13 Floating Point Support</A>
1963 SDCC supports IEEE (single precision 4bytes) floating point numbers.The
1964 floating point support routines are derived from gcc's floatlib.c
1965 and consists of the following routines.
1970 <LI><FONT SIZE="-1">_fsadd.c - add floating point numbers.</FONT>
1974 <LI><FONT SIZE="-1">_fssub.c - subtract floating point numbers</FONT>
1978 <LI><FONT SIZE="-1">_fsdiv.c - divide floating point numbers</FONT>
1982 <LI><FONT SIZE="-1">_fsmul.c - multiply floating point numbers</FONT>
1986 <LI><FONT SIZE="-1">_fs2uchar.c - convert floating point to unsigned char</FONT>
1990 <LI><FONT SIZE="-1">_fs2char.c - convert floating point to signed char.</FONT>
1994 <LI><FONT SIZE="-1">_fs2uint.c - convert floating point to unsigned int.</FONT>
1998 <LI><FONT SIZE="-1">_fs2int.c - convert floating point to signed int.</FONT>
2002 <LI><FONT SIZE="-1">_fs2ulong.c - convert floating point to unsigned long.</FONT>
2006 <LI><FONT SIZE="-1">_fs2long.c - convert floating point to signed long.</FONT>
2010 <LI><FONT SIZE="-1">_uchar2fs.c - convert unsigned char to floating point</FONT>
2014 <LI><FONT SIZE="-1">_char2fs.c - convert char to floating point number</FONT>
2018 <LI><FONT SIZE="-1">_uint2fs.c - convert unsigned int to floating point</FONT>
2022 <LI><FONT SIZE="-1">_int2fs.c - convert int to floating point numbers</FONT>
2026 <LI><FONT SIZE="-1">_ulong2fs.c - convert unsigned long to floating point
2031 <LI><FONT SIZE="-1">_long2fs.c - convert long to floating point number.</FONT>
2036 Note if all these routines are used simultaneously the data space
2037 might overflow. For serious floating point usage it is strongly recommended
2038 that the Large model be used (in which case the floating point routines
2039 mentioned above will need to recompiled with the -model-Large option)
2043 <H2><A NAME="SECTION000414000000000000000">
2044 3.14 MCS51 Memory Models</A>
2048 SDCC allows two memory models for MCS51 code, small and large. Modules
2049 compiled with different memory models should never be combined together
2050 or the results would be unpredictable. The library routines supplied
2051 with the compiler are compiled as both small and large. The compiled
2052 library modules are contained in seperate directories as small and
2053 large so that you can link to either set. In general the use of the
2054 large model is discouraged.
2057 When the large model is used all variables declared without a storage
2058 class will be allocated into the external ram, this includes all parameters
2059 and local variables (for non-reentrant functions). When the small
2060 model is used variables without storage class are allocated in the
2064 Judicious usage of the processor specific storage classes and the
2065 'reentrant' function type will yield much more efficient code, than
2066 using the large-model. Several optimizations are disabled when the
2067 program is compiled using the large model, it is therefore strongly
2068 recommdended that the small model be used unless absolutely required.
2072 <H2><A NAME="SECTION000415000000000000000">
2073 3.15 Flat 24 bit Addressing Model</A>
2077 This option generates code for the 24 bit contiguous addressing mode
2078 of the Dallas DS80C390 part. In this mode, up to four meg of external
2079 RAM or code space can be directly addressed. See the data sheets at
2080 www.dalsemi.com for further information on this part.
2083 In older versions of the compiler, this option was used with the MCS51
2084 code generator (-mmcs51). Now, however, the '390 has it's own code
2085 generator, selected by the -mds390 switch. This code generator currently
2086 supports only the flat24 model, but the -model-flat24 switch is still
2087 required, in case later versions of the code generator support other
2088 models (such as the paged mode of the '390). The combination of -mmcs51
2089 and -model-flat24 is now depracated.
2092 Note that the compiler does not generate any code to place the processor
2093 into24 bitmode (it defaults to 8051 compatible mode). Boot loader
2094 or similar code must ensure that the processor is in 24 bit contiguous
2095 addressing mode before calling the SDCC startup code.
2098 Like the -model-large option, variables will by default be placed
2099 into the XDATA segment.
2102 Segments may be placed anywhere in the 4 meg address space using the
2103 usual -*-loc options. Note that if any segments are located above
2104 64K, the -r flag must be passed to the linker to generate the proper
2105 segment relocations, and the Intel HEX output format must be used.
2106 The -r flag can be passed to the linker by using the option -Wl-r
2107 on the sdcc command line.
2111 <H2><A NAME="SECTION000416000000000000000">
2112 3.16 Defines Created by the Compiler</A>
2116 The compiler creates the following #defines .
2121 <LI>SDCC - this Symbol is always defined.
2123 <LI>SDCC_STACK_AUTO - this symbol is defined when -stack-auto option
2126 <LI>SDCC_MODEL_SMALL - when small model is used.
2128 <LI>SDCC_MODEL_LARGE - when -model-large is used.
2130 <LI>SDCC_USE_XSTACK - when -xstack option is used.
2136 <H1><A NAME="SECTION00050000000000000000">
2137 4 SDCC Technical Data</A>
2142 <H2><A NAME="SECTION00051000000000000000">
2143 4.1 Optimizations</A>
2147 SDCC performs a a host of standard optimizations in addition to some
2148 MCU specific optimizations.
2152 <H3><A NAME="SECTION00051100000000000000">
2153 4.1.1 Sub-expression Elimination</A>
2157 The compiler does <I>local and global</I> common subexpression elimination.
2160 <TT><FONT SIZE="-2">eg. </FONT></TT>
2165 <FONT SIZE="-1">i = x + y + 1;</FONT>
2167 j <FONT SIZE="-1">= x + y;</FONT>
2172 will be translated to
2175 <FONT SIZE="-1">iTemp = x + y </FONT>
2176 <BR><FONT SIZE="-1">i = iTemp + 1 </FONT>
2177 <BR><FONT SIZE="-1">j = iTemp</FONT>
2182 Some subexpressions are not as obvious as the above example.
2188 <FONT SIZE="-1">a->b[i].c = 10; </FONT>
2189 <BR><FONT SIZE="-1">a->b[i].d = 11;</FONT>
2194 In this case the address arithmetic <I>a->b[i]</I> will be computed
2195 only once; the equivalent code in C would be.
2198 <FONT SIZE="-1">iTemp = a->b[i]; </FONT>
2199 <BR><FONT SIZE="-1">iTemp.c = 10; </FONT>
2200 <BR><FONT SIZE="-1">iTemp.d = 11;</FONT>
2205 The compiler will try to keep these temporary variables in registers.
2209 <H3><A NAME="SECTION00051200000000000000">
2210 4.1.2 Dead-Code Elimination</A>
2217 <FONT SIZE="-1">int global; </FONT>
2218 <BR><FONT SIZE="-1">void f () { </FONT>
2219 <BR><FONT SIZE="-1"> int i; </FONT>
2220 <BR><FONT SIZE="-1"> i = 1; /* dead store */ </FONT>
2221 <BR><FONT SIZE="-1"> global = 1; /* dead store */ </FONT>
2222 <BR><FONT SIZE="-1"> global = 2; </FONT>
2223 <BR><FONT SIZE="-1"> return; </FONT>
2224 <BR><FONT SIZE="-1"> global = 3; /* unreachable */ </FONT>
2225 <BR><FONT SIZE="-1">}</FONT>
2233 <FONT SIZE="-1">int global; void f () </FONT>
2234 <BR><FONT SIZE="-1">{ </FONT>
2235 <BR><FONT SIZE="-1"> global = 2; </FONT>
2236 <BR><FONT SIZE="-1"> return; </FONT>
2237 <BR><FONT SIZE="-1">}</FONT>
2243 <H3><A NAME="SECTION00051300000000000000">
2244 4.1.3 Copy-Propagation</A>
2251 <FONT SIZE="-1">int f() { </FONT>
2252 <BR><FONT SIZE="-1"> int i, j; </FONT>
2253 <BR><FONT SIZE="-1"> i = 10; </FONT>
2254 <BR><FONT SIZE="-1"> j = i; </FONT>
2255 <BR><FONT SIZE="-1"> return j; </FONT>
2256 <BR><FONT SIZE="-1">}</FONT>
2264 <FONT SIZE="-1">int f() { </FONT>
2265 <BR><FONT SIZE="-1"> int i,j; </FONT>
2266 <BR><FONT SIZE="-1"> i = 10; </FONT>
2267 <BR><FONT SIZE="-1"> j = 10; </FONT>
2268 <BR><FONT SIZE="-1"> return 10; </FONT>
2269 <BR><FONT SIZE="-1">}</FONT>
2274 Note: the dead stores created by this copy propagation will be eliminated
2275 by dead-code elimination .
2279 <H3><A NAME="SECTION00051400000000000000">
2280 4.1.4 Loop Optimizations</A>
2284 Two types of loop optimizations are done by SDCC loop invariant lifting
2285 and strength reduction of loop induction variables.In addition to
2286 the strength reduction the optimizer marks the induction variables
2287 and the register allocator tries to keep the induction variables in
2288 registers for the duration of the loop. Because of this preference
2289 of the register allocator , loop induction optimization causes an
2290 increase in register pressure, which may cause unwanted spilling of
2291 other temporary variables into the stack / data space . The compiler
2292 will generate a warning message when it is forced to allocate extra
2293 space either on the stack or data space. If this extra space allocation
2294 is undesirable then induction optimization can be eliminated either
2295 for the entire source file ( with -noinduction option) or for a given
2296 function only (#pragma NOINDUCTION).
2301 <LI><B>Loop Invariant:</B>
2307 <FONT SIZE="-1">for (i = 0 ; i < 100 ; i ++) </FONT>
2308 <BR><FONT SIZE="-1"> f += k + l;</FONT>
2316 <FONT SIZE="-1">itemp = k + l; </FONT>
2317 <BR><FONT SIZE="-1">for ( i = 0; i < 100; i++ ) f += itemp;</FONT>
2322 As mentioned previously some loop invariants are not as apparent,
2323 all static address computations are also moved out of the loop.
2328 <LI><B>Strength Reduction :</B>
2331 This optimization substitutes an expression by a cheaper expression.
2337 <FONT SIZE="-1">for (i=0;i < 100; i++) ar[i*5] = i*3;</FONT>
2345 <FONT SIZE="-1">itemp1 = 0; </FONT>
2346 <BR><FONT SIZE="-1">itemp2 = 0; </FONT>
2347 <BR><FONT SIZE="-1">for (i=0;i< 100;i++) { </FONT>
2348 <BR><FONT SIZE="-1"> ar[itemp1] = itemp2; </FONT>
2349 <BR><FONT SIZE="-1"> itemp1 += 5; </FONT>
2350 <BR><FONT SIZE="-1"> itemp2 += 3; </FONT>
2351 <BR><FONT SIZE="-1">}</FONT>
2356 The more expensive multiplication is changed to a less expensive addition.
2360 <H3><A NAME="SECTION00051500000000000000">
2361 4.1.5 Loop Reversing:</A>
2365 This optimization is done to reduce the overhead of checking loop
2366 boundaries for every iteration. Some simple loops can be reversed
2367 and implemented using a ``decrement and jump if not zero'' instruction.
2368 SDCC checks for the following criterion to determine if a loop is
2369 reversible (note: more sophisticated compiers use data-dependency
2370 analysis to make this determination, SDCC uses a more simple minded
2376 <LI>The 'for' loop is of the form
2377 <BR>``for ( <symbol> = <expression> ; <sym> [< | <=] <expression>
2378 ; [<sym>++ | <sym> += 1])
2379 <BR> <for body>''
2381 <LI>The <for body> does not contain ``continue'' or 'break''.
2383 <LI>All goto's are contained within the loop.
2385 <LI>No function calls within the loop.
2387 <LI>The loop control variable <sym> is not assigned any value within the
2390 <LI>The loop control variable does NOT participate in any arithmetic operation
2393 <LI>There are NO switch statements in the loop.
2396 Note djnz instruction can be used for 8-bit values ONLY, therefore
2397 it is advantageous to declare loop control symbols as either 'char'
2398 or 'short', ofcourse this may not be possible on all situations.
2402 <H3><A NAME="SECTION00051600000000000000">
2403 4.1.6 Algebraic Simplifications</A>
2407 SDCC does numerous algebraic simplifications, the following is a small
2408 sub-set of these optimizations.
2411 <FONT SIZE="-1">eg</FONT> <I></I>
2412 <BR><FONT SIZE="-1">i = j + 0 ; /* changed to */ i = j; </FONT>
2413 <BR><FONT SIZE="-1">i /= 2; /* changed to */ i >>= 1; </FONT>
2414 <BR><FONT SIZE="-1">i = j - j ; /* changed to */ i = 0; </FONT>
2415 <BR><FONT SIZE="-1">i = j / 1 ; /* changed to */ i = j;</FONT>
2420 Note the subexpressions given above are generally introduced by macro
2421 expansions or as a result of copy/constant propagation.
2425 <H3><A NAME="SECTION00051700000000000000">
2426 4.1.7 'switch' Statements</A>
2430 SDCC changes switch statements to jump tables when the following conditions
2436 <LI>The case labels are in numerical sequence , the labels need not be
2437 in order, and the starting number need not be one or zero.
2443 <FONT SIZE="-1">switch(i) { switch (i)
2445 <BR><FONT SIZE="-1">case 4:... case 1: ...
2447 <BR><FONT SIZE="-1">case 5:... case 2: ...
2449 <BR><FONT SIZE="-1">case 3:... case 3: ...
2451 <BR><FONT SIZE="-1">case 6:... case 4: ...
2453 <BR><FONT SIZE="-1">} }</FONT>
2458 Both the above switch statements will be implemented using a jump-table.
2463 <LI>The number of case labels is at least three, since it takes two conditional
2464 statements to handle the boundary conditions.
2466 <LI>The number of case labels is less than 84, since each label takes
2467 3 bytes and a jump-table can be utmost 256 bytes long.
2470 Switch statements which have gaps in the numeric sequence or those
2471 that have more that 84 case labels can be split into more than one
2472 switch statement for efficient code generation.
2478 <FONT SIZE="-1">switch (i) { </FONT>
2479 <BR><FONT SIZE="-1">case 1: ... </FONT>
2480 <BR><FONT SIZE="-1">case 2: ... </FONT>
2481 <BR><FONT SIZE="-1">case 3: ... </FONT>
2482 <BR><FONT SIZE="-1">case 4: ... </FONT>
2483 <BR><FONT SIZE="-1">case 9: ... </FONT>
2484 <BR><FONT SIZE="-1">case 10: ... </FONT>
2485 <BR><FONT SIZE="-1">case 11: ... </FONT>
2486 <BR><FONT SIZE="-1">case 12: ... </FONT>
2487 <BR><FONT SIZE="-1">}</FONT>
2492 If the above switch statement is broken down into two switch statements
2495 <FONT SIZE="-1">switch (i) { </FONT>
2496 <BR><FONT SIZE="-1">case 1: ... </FONT>
2497 <BR><FONT SIZE="-1">case 2: ... </FONT>
2498 <BR><FONT SIZE="-1">case 3: ... </FONT>
2499 <BR><FONT SIZE="-1">case 4: ... </FONT>
2500 <BR><FONT SIZE="-1">}</FONT>
2505 <FONT SIZE="-1">switch (i) { </FONT>
2506 <BR><FONT SIZE="-1">case 9: ... </FONT>
2507 <BR><FONT SIZE="-1">case 10: ... </FONT>
2508 <BR><FONT SIZE="-1">case 11: ... </FONT>
2509 <BR><FONT SIZE="-1">case 12:... </FONT>
2510 <BR><FONT SIZE="-1">}</FONT>
2515 then both the switch statements will be implemented using jump-tables
2516 whereas the unmodified switch statement will not be .
2520 <H3><A NAME="SECTION00051800000000000000">
2521 4.1.8 Bit-shifting Operations.</A>
2525 Bit shifting is one of the most frequently used operation in embedded
2526 programming . SDCC tries to implement bit-shift operations in the
2527 most efficient way possible.
2533 <FONT SIZE="-1">unsigned short i;</FONT>
2538 <FONT SIZE="-1">... </FONT>
2539 <BR><FONT SIZE="-1">i>>= 4; </FONT>
2540 <BR><FONT SIZE="-1">..</FONT>
2545 generates the following code.
2548 <FONT SIZE="-1">mov a,_i </FONT>
2549 <BR><FONT SIZE="-1">swap a </FONT>
2550 <BR><FONT SIZE="-1">anl a,#0x0f </FONT>
2551 <BR><FONT SIZE="-1">mov _i,a</FONT>
2556 In general SDCC will never setup a loop if the shift count is known.
2560 <FONT SIZE="-1">unsigned int i; </FONT>
2561 <BR><FONT SIZE="-1">... </FONT>
2562 <BR><FONT SIZE="-1">i >>= 9; </FONT>
2563 <BR><FONT SIZE="-1">...</FONT>
2571 <FONT SIZE="-1">mov a,(_i + 1) </FONT>
2572 <BR><FONT SIZE="-1">mov (_i + 1),#0x00 </FONT>
2573 <BR><FONT SIZE="-1">clr c </FONT>
2574 <BR><FONT SIZE="-1">rrc a </FONT>
2575 <BR><FONT SIZE="-1">mov _i,a</FONT>
2580 Note that SDCC stores numbers in <SMALL>LITTLE-ENDIAN</SMALL> format (i.e.
2585 <H3><A NAME="SECTION00051900000000000000">
2586 4.1.9 Bit-rotation</A>
2590 A special case of the bit-shift operation is bit rotation, SDCC recognizes
2591 the following expression to be a left bit-rotation.
2594 <FONT SIZE="-1">unsigned char i; </FONT>
2595 <BR><FONT SIZE="-1">... </FONT>
2596 <BR><FONT SIZE="-1">i = ( ( i << 1) | ( i >>
2598 <BR><FONT SIZE="-1">...</FONT>
2603 will generate the following code.
2606 <FONT SIZE="-1">mov a,_i </FONT>
2607 <BR><FONT SIZE="-1">rl a </FONT>
2608 <BR><FONT SIZE="-1">mov _i,a</FONT>
2613 SDCC uses pattern matching on the parse tree to determine this operation
2614 .Variations of this case will also be recognized as bit-rotation i.e
2615 <I>i = ((i >> 7) | (i <<
2616 1));</I> /* left-bit rotation */
2620 <H3><A NAME="SECTION000511000000000000000">
2621 4.1.10 Highest Order Bit</A>
2625 It is frequently required to obtain the highest order bit of an integral
2626 type (int,long,short or char types). SDCC recognizes the following
2627 expression to yield the highest order bit and generates optimized
2631 <FONT SIZE="-1">eg </FONT>
2632 <BR><FONT SIZE="-1">unsigned int gint; </FONT>
2633 <BR><FONT SIZE="-1">foo () { </FONT>
2634 <BR><FONT SIZE="-1">unsigned char hob; </FONT>
2635 <BR><FONT SIZE="-1"> ... </FONT>
2636 <BR><FONT SIZE="-1"> hob = (gint >> 15) & 1; </FONT>
2637 <BR><FONT SIZE="-1"> .. </FONT>
2638 <BR><FONT SIZE="-1">}</FONT>
2643 Will generate the following code.
2646 <FONT SIZE="-1"> 61
2647 ; hob.c 7 </FONT>
2648 <BR><FONT SIZE="-1"> 000A E5*01 62
2649 mov a,(_gint + 1) </FONT>
2650 <BR><FONT SIZE="-1"> 000C 33 63
2652 <BR><FONT SIZE="-1"> 000D E4 64
2654 <BR><FONT SIZE="-1"> 000E 13 65
2656 <BR><FONT SIZE="-1"> 000F F5*02 66
2657 mov _foo_hob_1_1,a</FONT>
2662 Variations of this case however will NOT be recognized . It is a standard
2663 C expression , so I heartily recommend this be the only way to get
2664 the highest order bit, (it is portable). Of course it will be recognized
2665 even if it is embedded in other expressions.
2668 <FONT SIZE="-1">eg.</FONT>
2673 <FONT SIZE="-1">xyz = gint + ((gint >> 15) & 1);</FONT>
2678 will still be recognized.
2682 <H3><A NAME="SECTION000511100000000000000">
2683 4.1.11 Peep-hole Optimizer</A>
2687 The compiler uses a rule based , pattern matching and re-writing mechanism
2688 for peep-hole optimization . It is inspired by '<I>copt'</I> a peep-hole
2689 optimizer by Christopher W. Fraser (cwfraser@microsoft.com). A default
2690 set of rules are compiled into the compiler, additional rules may
2691 be added with the -peep-file <filename> option. The rule language
2692 is best illustrated with examples.
2695 <FONT SIZE="-1">replace { </FONT>
2696 <BR><FONT SIZE="-1">mov %1,a </FONT>
2697 <BR><FONT SIZE="-1">mov a,%1 } by { mov %1,a }</FONT>
2702 The above rule will the following assembly sequence
2705 <FONT SIZE="-1">mov r1,a </FONT>
2706 <BR><FONT SIZE="-1">mov a,r1</FONT>
2714 <FONT SIZE="-1">mov r1,a</FONT>
2719 Note: All occurrences of a '%n' ( pattern variable ) must denote
2720 the same string. With the above rule, the assembly sequence
2723 <FONT SIZE="-1">mov r1,a </FONT>
2724 <BR><FONT SIZE="-1">mov a,r2</FONT>
2729 will remain unmodified. Other special case optimizations may be added
2730 by the user (via -peep-file option), eg. some variants of the 8051
2731 MCU allow only 'AJMP' and 'ACALL' , the following two rules will change
2732 all 'LJMP' & 'LCALL' to 'AJMP' & 'ACALL'.
2735 <FONT SIZE="-1">replace { lcall %1 } by { acall %1 } </FONT>
2736 <BR><FONT SIZE="-1">replace { ljmp %1 } by { ajmp %1 }</FONT>
2741 The inline-assembler' code is also passed through the peep hole optimizer,
2742 thus the peephole optimizer can also be used as an assembly level
2743 macro expander. The rules themselves are MCU dependent whereas the
2744 rule language infra-structure is MCU independent. Peephole optimization
2745 rules for other MCU can be easily programmed using the rule language.
2748 The syntax for a rule is as follows ,
2751 <FONT SIZE="-1">rule := replace [ restart ] '{' <assembly sequence> '\n'
2753 <BR><FONT SIZE="-1"> '}' by '{' '\n'
2755 <BR><FONT SIZE="-1"> <assembly
2756 sequence> '\n' </FONT>
2757 <BR><FONT SIZE="-1"> '}' [if <functionName>
2759 <BR><FONT SIZE="-1"><assembly sequence> := assembly instruction (each instruction
2760 including labels must be on a separate line). </FONT>
2765 The optimizer will apply to the rules one by one from the top in the
2766 sequence of their appearance, it will terminate when all rules are
2767 exhausted. If the '<I>restart</I>' option is specified, then the optimizer
2768 will start matching the rules again from the top, this option for
2769 a rule is expensive (performance), it is intended to be used in situations
2770 where a transformation will trigger the same rule again. A good example
2771 of this the following rule.
2774 <FONT SIZE="-1">replace restart { </FONT>
2775 <BR><FONT SIZE="-1">pop %1 </FONT>
2776 <BR><FONT SIZE="-1">push %1 } by { </FONT>
2777 <BR><FONT SIZE="-1">; nop </FONT>
2778 <BR><FONT SIZE="-1">}</FONT>
2783 Note that the replace pattern cannot be a blank, but can be a comment
2784 line. Without the '<I>restart</I>' option only the inner most 'pop'
2785 'push' pair would be eliminated. i.e.
2788 <FONT SIZE="-1">pop ar1 </FONT>
2789 <BR><FONT SIZE="-1">pop ar2 </FONT>
2790 <BR><FONT SIZE="-1">push ar2 </FONT>
2791 <BR><FONT SIZE="-1">push ar1</FONT>
2799 <FONT SIZE="-1">pop ar1 </FONT>
2800 <BR><FONT SIZE="-1">; nop </FONT>
2801 <BR><FONT SIZE="-1">push ar1</FONT>
2806 with the '<I>restart</I>' option the rule will be applied again to
2807 the resulting code and the all the '<I>pop' 'push'</I> pairs will
2808 be eliminated to yield
2811 <FONT SIZE="-1">; nop </FONT>
2812 <BR><FONT SIZE="-1">; nop</FONT>
2817 A conditional function can be attached to a rule. Attaching rules
2818 are somewhat more involved, let me illustrate this with an example.
2821 <FONT SIZE="-1">replace { </FONT>
2822 <BR><FONT SIZE="-1"> ljmp %5 </FONT>
2823 <BR><FONT SIZE="-1">%2:} by { </FONT>
2824 <BR><FONT SIZE="-1"> sjmp %5 </FONT>
2825 <BR><FONT SIZE="-1">%2:} if labelInRange</FONT>
2830 The optimizer does a look-up of a function name table defined in function
2831 '<I>callFuncByName'</I> in the source file <I>SDCCpeeph.c</I> , with
2832 the name <I>'labelInRange</I>', if it finds a corresponding entry
2833 the function is called. Note there can be no parameters specified
2834 for these functions, in this case the use of <I>'%5</I>' is crucial,
2835 since the function <I>labelInRange</I> expects to find the label in
2836 that particular variable (the hash table containing the variable bindings
2837 is passed as a parameter). If you want to code more such functions
2838 , take a close look at the function <I>labelInRange</I> and the calling
2839 mechanism in source file <I>SDCCpeeph.c</I>. I know this whole thing
2840 is a little kludgey , may be some day we will have some better means.
2841 If you are looking at this file, you will also see the default rules
2842 that are compiled into the compiler, you can your own rules in the
2843 default set there if you get tired of specifying the <I>-peep-file</I>
2848 <H2><A NAME="SECTION00052000000000000000">
2853 SDCC supports the following <I>#pragma</I> directives. This directives
2854 are applicable only at a function level.
2859 <LI><B>SAVE</B> - this will save all the current options .
2861 <LI><B>RESTORE</B> - will restore the saved options from the last save.
2862 Note that SAVES & RESTOREs cannot be nested. SDCC uses the same buffer
2863 to save the options each time a SAVE is called.
2865 <LI><B>NOGCSE</B> - will stop global subexpression elimination.
2867 <LI><B>NOINDUCTION</B> - will stop loop induction optimizations .
2869 <LI><B>NOJTBOUND</B> - will not generate code for boundary value checking
2870 , when switch statements are turned into jump-tables.
2872 <LI><B>NOOVERLAY</B> - the compiler will not overlay the parameters
2873 and local variables of a function.
2875 <LI><B>NOLOOPREVERSE</B> - Will not do loop reversal optimization
2877 <LI><B>EXCLUDE NONE | {acc[,b[,dpl[,dph]]]</B> - The exclude
2878 pragma disables generation of pair of push/pop instruction in ISR
2879 function (using interrupt keyword). The directive should be placed
2880 immediately before the ISR function definition and it affects ALL
2881 ISR functions following it. To enable the normal register saving for
2882 ISR functions use ``#pragma EXCLUDE none''
2884 <LI><B>CALLEE-SAVES function1[,function2[,function3...]]</B>
2885 - The compiler by default uses a caller saves convention for register
2886 saving across function calls, however this can cause unneccessary
2887 register pushing & popping when calling small functions from larger
2888 functions. This option can be used to switch the register saving convention
2889 for the function names specified. The compiler will not save registers
2890 when calling these functions, extra code will be generated at the
2891 entry & exit for these functions to save & restore the registers
2892 used by these functions, this can SUBSTANTIALLY reduce code & improve
2893 run time performance of the generated code. In future the compiler
2894 (with interprocedural analysis) will be able to determine the appropriate
2895 scheme to use for each function call. If -callee-saves command line
2896 option is used, the function names specified in #pragma CALLEE-SAVES
2897 is appended to the list of functions specified inthe command line.
2900 The pragma's are intended to be used to turn-off certain optimizations
2901 which might cause the compiler to generate extra stack / data space
2902 to store compiler generated temporary variables. This usually happens
2903 in large functions. Pragma directives should be used as shown in the
2904 following example, they are used to control options & optimizations
2905 for a given function; pragmas should be placed <SMALL>BEFORE</SMALL> and/or
2906 <SMALL>AFTER</SMALL> a function, placing pragma's inside a function body
2907 could have unpredictable results.
2910 <FONT SIZE="-2">eg</FONT>
2915 <FONT SIZE="-2">#pragma SAVE /* save the current settings */
2917 <BR><FONT SIZE="-2">#pragma NOGCSE /* turnoff global subexpression elimination
2919 <BR><FONT SIZE="-2">#pragma NOINDUCTION /* turn off induction optimizations
2921 <BR><FONT SIZE="-2">int foo () </FONT>
2922 <BR><FONT SIZE="-2">{ </FONT>
2923 <BR><FONT SIZE="-2"> ... </FONT>
2924 <BR><FONT SIZE="-2"> /* large code */ </FONT>
2925 <BR><FONT SIZE="-2"> ... </FONT>
2926 <BR><FONT SIZE="-2">} </FONT>
2927 <BR><FONT SIZE="-2">#pragma RESTORE /* turn the optimizations back on
2933 The compiler will generate a warning message when extra space is allocated.
2934 It is strongly recommended that the SAVE and RESTORE pragma's be used
2935 when changing options for a function.
2939 <H2><A NAME="SECTION00053000000000000000">
2940 4.3 Library Routines</A>
2944 The following library routines are provided for your convenience.
2947 <B><FONT SIZE="+1">stdio.h</FONT></B> - Contains the following functions printf
2948 & sprintf these routines are developed by <I>Martijn van Balen
2949 <balen@natlab.research.philips.com>. </I>
2952 <FONT SIZE="-2">%[flags][width][b|B|l|L]type</FONT>
2957 <FONT SIZE="-2"> flags: - left justify
2958 output in specified field width </FONT>
2959 <BR><FONT SIZE="-2"> + prefix
2960 output with +/- sign if output is signed type </FONT>
2961 <BR><FONT SIZE="-2"> space prefix output
2962 with a blank if it's a signed positive value </FONT>
2963 <BR><FONT SIZE="-2"> width: specifies
2964 minimum number of characters outputted for numbers </FONT>
2965 <BR><FONT SIZE="-2"> or
2967 <BR><FONT SIZE="-2"> -
2968 For numbers, spaces are added on the left when needed. </FONT>
2969 <BR><FONT SIZE="-2">
2970 If width starts with a zero character, zeroes and used </FONT>
2971 <BR><FONT SIZE="-2">
2972 instead of spaces. </FONT>
2973 <BR><FONT SIZE="-2"> -
2974 For strings, spaces are are added on the left or right (when </FONT>
2975 <BR><FONT SIZE="-2">
2976 flag '-' is used) when needed. </FONT>
2977 <BR><FONT SIZE="-2"> </FONT>
2978 <BR><FONT SIZE="-2"> b/B: byte argument
2979 (used by d, u, o, x, X) </FONT>
2980 <BR><FONT SIZE="-2"> l/L: long argument
2981 (used by d, u, o, x, X)</FONT>
2982 <BR><FONT SIZE="-2"> type: d decimal number
2984 <BR><FONT SIZE="-2"> u unsigned
2985 decimal number </FONT>
2986 <BR><FONT SIZE="-2"> o unsigned
2987 octal number </FONT>
2988 <BR><FONT SIZE="-2"> x unsigned
2989 hexadecimal number (0-9, a-f) </FONT>
2990 <BR><FONT SIZE="-2"> X unsigned
2991 hexadecimal number (0-9, A-F) </FONT>
2992 <BR><FONT SIZE="-2"> c character
2994 <BR><FONT SIZE="-2"> s string
2995 (generic pointer) </FONT>
2996 <BR><FONT SIZE="-2"> p generic
2997 pointer (I:data/idata, C:code, X:xdata, P:paged) </FONT>
2998 <BR><FONT SIZE="-2"> f float
2999 (still to be implemented)</FONT>
3004 Also contains a very simple version of printf (<B>printf_small</B>).
3005 This simplified version of printf supports only the following formats.
3008 <U><FONT SIZE="-2">format output type argument-type</FONT></U>
3009 <BR><FONT SIZE="-2">%d decimal int </FONT>
3010 <BR><FONT SIZE="-2">%ld decimal long </FONT>
3011 <BR><FONT SIZE="-2">%hd decimal short/char </FONT>
3012 <BR><FONT SIZE="-2">%x hexadecimal int </FONT>
3013 <BR><FONT SIZE="-2">%lx hexadecimal long </FONT>
3014 <BR><FONT SIZE="-2">%hx hexadecimal short/char </FONT>
3015 <BR><FONT SIZE="-2">%o octal int </FONT>
3016 <BR><FONT SIZE="-2">%lo octal long </FONT>
3017 <BR><FONT SIZE="-2">%ho octal short/char
3019 <BR><FONT SIZE="-2">%c character char/short </FONT>
3020 <BR><FONT SIZE="-2">%s character _generic pointer</FONT>
3025 The routine is <B>very stack intesive</B> , -stack-after-data parameter
3026 should be used when using this routine, the routine also takes about
3027 1K of code space .It also expects an external function named <I>putchar(char
3028 )</I> to be present (this can be changed). When using the %s format
3029 the string / pointer should be cast to a generic pointer. eg.
3032 <FONT SIZE="-2">printf_small(``my str %s, my int %d\n'',(char
3033 _generic *)mystr,myint);</FONT>
3040 <LI><B><FONT SIZE="+1">stdarg.h</FONT></B> - contains definition for the following macros
3041 to be used for variable parameter list, note that a function can have
3042 a variable parameter list if and only if it is 'reentrant'
3045 <FONT SIZE="-1">va_list, va_start, va_arg, va_end.</FONT>
3051 <LI><B><FONT SIZE="+1">setjmp.h</FONT></B> - contains defintion for ANSI <B>setjmp</B>
3052 & <B>longjmp</B> routines. Note in this case setjmp & longjmp
3053 can be used between functions executing within the same register bank,
3054 if long jmp is executed from a function that is using a different
3055 register bank from the function issuing the setjmp function, the results
3056 may be unpredictable. The jump buffer requires 3 bytes of data (the
3057 stack pointer & a 16 byte return address), and can be placed in any
3060 <LI><B><FONT SIZE="+1">stdlib.h</FONT></B> - contains the following functions.
3063 <FONT SIZE="-1">atoi, atol.</FONT>
3069 <LI><B><FONT SIZE="+1">string.h</FONT></B> - contains the following functions.
3072 <FONT SIZE="-1">strcpy, strncpy, strcat, strncat, strcmp, strncmp,
3073 strchr, strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok,
3074 memcpy, memcmp, memset.</FONT>
3080 <LI><B><FONT SIZE="+1">ctype.h</FONT></B> - contains the following routines.
3083 <FONT SIZE="-1">iscntrl, isdigit, isgraph, islower, isupper, isprint,
3084 ispunct, isspace, isxdigit, isalnum, isalpha.</FONT>
3090 <LI><B><FONT SIZE="+1">malloc.h</FONT></B> - The malloc routines are developed by Dmitry
3091 S. Obukhov (dso@usa.net). These routines will allocate memory from
3092 the external ram. Here is a description on how to use them (as described
3096 <FONT SIZE="-2">//Example: </FONT>
3097 <BR><FONT SIZE="-2"> // #define DYNAMIC_MEMORY_SIZE 0x2000
3099 <BR><FONT SIZE="-2"> // ..... </FONT>
3100 <BR><FONT SIZE="-2"> // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
3102 <BR><FONT SIZE="-2"> // unsigned char xdata * current_buffer;
3104 <BR><FONT SIZE="-2"> // ..... </FONT>
3105 <BR><FONT SIZE="-2"> // void main(void) </FONT>
3106 <BR><FONT SIZE="-2"> // { </FONT>
3107 <BR><FONT SIZE="-2"> // ... </FONT>
3108 <BR><FONT SIZE="-2"> // init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
3110 <BR><FONT SIZE="-2"> // //Now it's possible to use
3112 <BR><FONT SIZE="-2"> // ... </FONT>
3113 <BR><FONT SIZE="-2"> // current_buffer = malloc(0x100);
3115 <BR><FONT SIZE="-2"> //</FONT>
3121 <LI><B><FONT SIZE="+1">serial.h</FONT></B> - Serial IO routines are also developed by
3122 Dmitry S. Obukhov (dso@usa.net). These routines are interrupt driven
3123 with a 256 byte circular buffer, they also expect external ram to
3124 be present. Please see documentation in file SDCCDIR/sdcc51lib/serial.c
3125 . Note the header file ``serial.h'' MUST be included in the file
3126 containing the 'main' function.
3128 <LI><B><FONT SIZE="+1">ser.h</FONT></B> - Alternate serial routine provided by Wolfgang
3129 Esslinger <wolfgang@WiredMinds.com> these routines are more compact
3130 and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
3132 <LI><B><FONT SIZE="+1">ser_ir.h</FONT></B> - Another alternate set of serial routines
3133 provided by Josef Wolf <jw@raven.inka.de> , these routines do not
3134 use the external ram.
3136 <LI><B><FONT SIZE="+1">reg51.h</FONT></B> - contains register definitions for a standard
3139 <LI><B><FONT SIZE="+1">reg552.h</FONT></B> - contains register definitions for 80C552.
3141 <LI><B><FONT SIZE="+1">float.h</FONT></B> - contains min, max and other floating point
3145 All library routines are compiled as -model-small , they are all
3146 non-reentrant, if you plan to use the large model or want to make
3147 these routines reentrant, then they will have to be recompiled with
3148 the appropriate compiler option.
3151 Have not had time to do the more involved routines like printf, will
3152 get to them shortly.
3156 <H2><A NAME="SECTION00054000000000000000">
3157 4.4 Interfacing with Assembly Routines</A>
3162 <H2><A NAME="SECTION00055000000000000000">
3163 4.5 Global Registers used for Parameter Passing</A>
3167 By default the compiler uses the global registers ``DPL,DPH,B,ACC''
3168 to pass the first parameter to a routine, the second parameter onwards
3169 is either allocated on the stack (for reentrant routines or -stack-auto
3170 is used) or in the internal / external ram (depending on the memory
3175 <H3><A NAME="SECTION00055100000000000000">
3176 4.5.1 Assembler Routine(non-reentrant)</A>
3180 In the following example the function <B>cfunc</B> calls an assembler
3181 routine <B>asm_func</B>, which takes two parameters.
3184 <FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
3189 <FONT SIZE="-1"> </FONT>
3190 <BR><FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) </FONT>
3191 <BR><FONT SIZE="-1">{ </FONT>
3192 <BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
3193 <BR><FONT SIZE="-1">}</FONT>
3194 <BR><FONT SIZE="-2">int main() </FONT>
3195 <BR><FONT SIZE="-2">{ </FONT>
3196 <BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
3197 <BR><FONT SIZE="-2">}</FONT>
3202 The corresponding assembler function is:-
3205 <FONT SIZE="-2"> .globl _asm_func_PARM_2 </FONT>
3206 <BR><FONT SIZE="-2"> .globl _asm_func </FONT>
3207 <BR><FONT SIZE="-2"> .area OSEG </FONT>
3208 <BR><FONT SIZE="-2">_asm_func_PARM_2: .ds 1 </FONT>
3209 <BR><FONT SIZE="-2"> .area CSEG </FONT>
3210 <BR><FONT SIZE="-2">_asm_func: </FONT>
3211 <BR><FONT SIZE="-2"> mov a,dpl </FONT>
3212 <BR><FONT SIZE="-2"> add a,_asm_func_PARM_2 </FONT>
3213 <BR><FONT SIZE="-2"> mov dpl,a </FONT>
3214 <BR><FONT SIZE="-2"> mov dpl,#0x00 </FONT>
3215 <BR><FONT SIZE="-2"> ret</FONT>
3220 Note here that the return values are placed in 'dpl' - One byte return
3221 value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and
3222 'b' for three byte values (generic pointers) and 'dpl','dph','b' &
3223 'acc' for four byte values.
3226 The parameter naming convention is <B>_<function_name>_PARM_<n>,</B>
3227 where n is the parameter number starting from 1, and counting from
3228 the left. The first parameter is passed in ``dpl'' for One bye
3229 parameter, ``dptr'' if two bytes, ``b,dptr'' for three bytes
3230 and ``acc,b,dptr'' for four bytes, the <TT><B><FONT SIZE="-1">varaible
3231 name for the second parameter will be _<function_name>_PARM_2.</FONT></B></TT>
3236 Assemble the assembler routine with the following command.
3239 asx8051 -losg asmfunc.asm
3242 Then compile and link the assembler routine to the C source file with
3243 the following command,
3246 sdcc cfunc.c asmfunc.rel
3250 <H3><A NAME="SECTION00055200000000000000">
3251 4.5.2 Assembler Routine(reentrant)</A>
3255 In this case the second parameter onwards will be passed on the stack
3256 , the parameters are pushed from right to left i.e. after the call
3257 the left most parameter will be on the top of the stack. Here is an
3261 <FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
3266 <FONT SIZE="-1"> </FONT>
3271 <FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) reentrant
3273 <BR><FONT SIZE="-1">{ </FONT>
3274 <BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
3275 <BR><FONT SIZE="-1">}</FONT>
3276 <BR><FONT SIZE="-2">int main() </FONT>
3277 <BR><FONT SIZE="-2">{ </FONT>
3278 <BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
3279 <BR><FONT SIZE="-2">}</FONT>
3284 The corresponding assembler routine is.
3287 <FONT SIZE="-2"> .globl _asm_func </FONT>
3288 <BR><FONT SIZE="-2">_asm_func: </FONT>
3289 <BR><FONT SIZE="-2"> push _bp </FONT>
3290 <BR><FONT SIZE="-2"> mov _bp,sp </FONT>
3291 <BR><FONT SIZE="-2"> mov r2,dpl</FONT>
3292 <BR><FONT SIZE="-2"> mov a,_bp </FONT>
3293 <BR><FONT SIZE="-2"> clr c </FONT>
3294 <BR><FONT SIZE="-2"> add a,#0xfd </FONT>
3295 <BR><FONT SIZE="-2"> mov r0,a </FONT>
3296 <BR><FONT SIZE="-2"> add a,#0xfc</FONT>
3297 <BR><FONT SIZE="-2"> mov r1,a </FONT>
3298 <BR><FONT SIZE="-2"> mov a,@r0 </FONT>
3299 <BR><FONT SIZE="-2"> add a,r2</FONT>
3300 <BR><FONT SIZE="-2"> mov dpl,a </FONT>
3301 <BR><FONT SIZE="-2"> mov dph,#0x00 </FONT>
3302 <BR><FONT SIZE="-2"> mov sp,_bp </FONT>
3303 <BR><FONT SIZE="-2"> pop _bp </FONT>
3304 <BR><FONT SIZE="-2"> ret</FONT>
3309 The compiling and linking procedure remains the same, however note
3310 the extra entry & exit linkage required for the assembler code, _bp
3311 is the stack frame pointer and is used to compute the offset into
3312 the stack for parameters and local variables.
3316 <H2><A NAME="SECTION00056000000000000000">
3317 4.6 With -noregparms Option</A>
3321 When the source is compiled with -noregparms option , space is allocated
3322 for each of the parameters passed to a routine.
3326 <H3><A NAME="SECTION00056100000000000000">
3327 4.6.1 Assembler Routine Non-reentrant</A>
3331 In the following example the function <B>cfunc</B> calls an assembler
3332 routine <B>asm_func</B>, which takes two parameters.
3335 <FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
3340 <FONT SIZE="-1"> </FONT>
3341 <BR><FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) </FONT>
3342 <BR><FONT SIZE="-1">{ </FONT>
3343 <BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
3344 <BR><FONT SIZE="-1">}</FONT>
3345 <BR><FONT SIZE="-2">int main() </FONT>
3346 <BR><FONT SIZE="-2">{ </FONT>
3347 <BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
3348 <BR><FONT SIZE="-2">}</FONT>
3353 The corresponding assembler function is:-
3356 <FONT SIZE="-2"> .globl _asm_func_PARM_1 </FONT>
3357 <BR><FONT SIZE="-2"> .globl _asm_func_PARM_2 </FONT>
3358 <BR><FONT SIZE="-2"> .globl _asm_func </FONT>
3359 <BR><FONT SIZE="-2"> .area OSEG </FONT>
3360 <BR><FONT SIZE="-2">_asm_func_PARM_1: .ds 1 </FONT>
3361 <BR><FONT SIZE="-2">_asm_func_PARM_2: .ds 1 </FONT>
3362 <BR><FONT SIZE="-2"> .area CSEG </FONT>
3363 <BR><FONT SIZE="-2">_asm_func: </FONT>
3364 <BR><FONT SIZE="-2"> mov a,_asm_func_PARM_1 </FONT>
3365 <BR><FONT SIZE="-2"> add a,_asm_func_PARM_2 </FONT>
3366 <BR><FONT SIZE="-2"> mov dpl,a </FONT>
3367 <BR><FONT SIZE="-2"> mov dpl,#0x00 </FONT>
3368 <BR><FONT SIZE="-2"> ret</FONT>
3373 Note here that the return values are placed in 'dpl' - One byte return
3374 value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and
3375 'b' for three byte values (generic pointers) and 'dpl','dph','b' &
3376 'acc' for four byte values.
3379 The parameter naming convention is <B>_<function_name>_PARM_<n>,</B>
3380 where n is the parameter number starting from 1, and counting from
3381 the left. i.e. the <TT><B><FONT SIZE="-1">left-most parameter
3382 name will be _<function_name>_PARM_1.</FONT></B></TT>
3387 Assemble the assembler routine with the following command.
3390 asx8051 -losg asmfunc.asm
3393 Then compile and link the assembler routine to the C source file with
3394 the following command,
3397 sdcc cfunc.c asmfunc.rel
3401 <H3><A NAME="SECTION00056200000000000000">
3402 4.6.2 Assembler Routine(reentrant)</A>
3406 In this case the parameters will be passed on the stack , the parameters
3407 are pushed from right to left i.e. after the call the left most parameter
3408 will be on the top of the stack. Here is an example.
3411 <FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
3416 <FONT SIZE="-1"> </FONT>
3421 <FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) reentrant
3423 <BR><FONT SIZE="-1">{ </FONT>
3424 <BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
3425 <BR><FONT SIZE="-1">}</FONT>
3426 <BR><FONT SIZE="-2">int main() </FONT>
3427 <BR><FONT SIZE="-2">{ </FONT>
3428 <BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
3429 <BR><FONT SIZE="-2">}</FONT>
3434 The corresponding assembler routine is.
3437 <FONT SIZE="-2"> .globl _asm_func </FONT>
3438 <BR><FONT SIZE="-2">_asm_func: </FONT>
3439 <BR><FONT SIZE="-2"> push _bp </FONT>
3440 <BR><FONT SIZE="-2"> mov _bp,sp </FONT>
3441 <BR><FONT SIZE="-2"> mov a,_bp </FONT>
3442 <BR><FONT SIZE="-2"> clr c </FONT>
3443 <BR><FONT SIZE="-2"> add a,#0xfd </FONT>
3444 <BR><FONT SIZE="-2"> mov r0,a </FONT>
3445 <BR><FONT SIZE="-2"> mov a,_bp </FONT>
3446 <BR><FONT SIZE="-2"> clr c </FONT>
3447 <BR><FONT SIZE="-2"> add a,#0xfc </FONT>
3448 <BR><FONT SIZE="-2"> mov r1,a </FONT>
3449 <BR><FONT SIZE="-2"> mov a,@r0 </FONT>
3450 <BR><FONT SIZE="-2"> add a,@r1 </FONT>
3451 <BR><FONT SIZE="-2"> mov dpl,a </FONT>
3452 <BR><FONT SIZE="-2"> mov dph,#0x00 </FONT>
3453 <BR><FONT SIZE="-2"> mov sp,_bp </FONT>
3454 <BR><FONT SIZE="-2"> pop _bp </FONT>
3455 <BR><FONT SIZE="-2"> ret</FONT>
3460 The compiling and linking procedure remains the same, however note
3461 the extra entry & exit linkage required for the assembler code, _bp
3462 is the stack frame pointer and is used to compute the offset into
3463 the stack for parameters and local variables.
3467 <H2><A NAME="SECTION00057000000000000000">
3468 4.7 External Stack</A>
3472 The external stack is located at the start of the external ram segment
3473 , and is 256 bytes in size. When -xstack option is used to compile
3474 the program, the parameters and local variables of all reentrant functions
3475 are allocated in this area. This option is provided for programs with
3476 large stack space requirements. When used with the -stack-auto option,
3477 all parameters and local variables are allocated on the external stack
3478 (note support libraries will need to be recompiled with the same options).
3481 The compiler outputs the higher order address byte of the external
3482 ram segment into PORT P2, therefore when using the External Stack
3483 option, this port MAY NOT be used by the application program.
3487 <H2><A NAME="SECTION00058000000000000000">
3488 4.8 ANSI-Compliance</A>
3492 Deviations from the compliancy.
3497 <LI>functions are not always reentrant.
3499 <LI>structures cannot be assigned values directly, cannot be passed as
3500 function parameters or assigned to each other and cannot be a return
3501 value from a function.
3504 <FONT SIZE="-1">eg</FONT>
3511 <FONT SIZE="-1">struct s { ... }; </FONT>
3512 <BR><FONT SIZE="-1">struct s s1, s2; </FONT>
3513 <BR><FONT SIZE="-1">foo() </FONT>
3514 <BR><FONT SIZE="-1">{ </FONT>
3515 <BR><FONT SIZE="-1">... </FONT>
3516 <BR><FONT SIZE="-1">s1 = s2 ; /* is invalid in SDCC although allowed in ANSI
3518 <BR><FONT SIZE="-1">... </FONT>
3519 <BR><FONT SIZE="-1">}</FONT>
3524 <FONT SIZE="-1">struct s foo1 (struct s parms) /* is invalid in SDCC although
3525 allowed in ANSI */ </FONT>
3526 <BR><FONT SIZE="-1">{ </FONT>
3527 <BR><FONT SIZE="-1">struct s rets; </FONT>
3528 <BR><FONT SIZE="-1">... </FONT>
3529 <BR><FONT SIZE="-1">return rets;/* is invalid in SDCC although allowed in ANSI
3531 <BR><FONT SIZE="-1">}</FONT>
3538 <LI>'long long' (64 bit integers) not supported.
3540 <LI>'double' precision floating point not supported.
3542 <LI>integral promotions are suppressed. What does this mean ? The compiler
3543 will not implicitly promote an integer expression to a higher order
3544 integer, exception is an assignment or parameter passing.
3546 <LI>No support for <I>setjmp</I> and <I>longjmp</I> (for now).
3548 <LI>Old K&R style function declarations are NOT allowed.
3551 <FONT SIZE="-1">foo( i,j) /* this old style of function declarations
3553 <BR><FONT SIZE="-1">int i,j; /* are valid in ANSI .. not valid in SDCC
3555 <BR><FONT SIZE="-1">{ </FONT>
3556 <BR><FONT SIZE="-1">... </FONT>
3557 <BR><FONT SIZE="-1">}</FONT>
3564 <LI>functions declared as pointers must be dereferenced during the call.
3567 <FONT SIZE="-1">int (*foo)();</FONT>
3574 <FONT SIZE="-1"> ... </FONT>
3575 <BR><FONT SIZE="-1"> /* has to be called like this */ </FONT>
3576 <BR><FONT SIZE="-1"> (*foo)();/* ansi standard allows calls to be made
3577 like 'foo()' */</FONT>
3583 <H2><A NAME="SECTION00059000000000000000">
3584 4.9 Cyclomatic Complexity</A>
3588 Cyclomatic complexity of a function is defined as the number of independent
3589 paths the program can take during execution of the function. This
3590 is an important number since it defines the number test cases you
3591 have to generate to validate the function . The accepted industry
3592 standard for complexity number is 10, if the cyclomatic complexity
3593 reported by SDCC exceeds 10 you should think about simplification
3594 of the function logic.
3597 Note that the complexity level is not related to the number of lines
3598 of code in a function. Large functions can have low complexity, and
3599 small functions can have large complexity levels. SDCC uses the following
3600 formula to compute the complexity.
3603 <FONT SIZE="-1">complexity = (number of edges in control flow graph) - </FONT>
3604 <BR><FONT SIZE="-1"> (number of nodes in control flow graph)
3610 Having said that the industry standard is 10, you should be aware
3611 that in some cases it may unavoidable to have a complexity level of
3612 less than 10. For example if you have switch statement with more than
3613 10 case labels, each case label adds one to the complexity level.
3614 The complexity level is by no means an absolute measure of the algorithmic
3615 complexity of the function, it does however provide a good starting
3616 point for which functions you might look at for further optimization.
3620 <H1><A NAME="SECTION00060000000000000000">
3625 Here are a few guide-lines that will help the compiler generate more
3626 efficient code, some of the tips are specific to this compiler others
3627 are generally good programming practice.
3632 <LI>Use the smallest data type to represent your data-value. If it is
3633 known in advance that the value is going to be less than 256 then
3634 use a 'short' or 'char' instead of an 'int'.
3636 <LI>Use unsigned when it is known in advance that the value is not going
3637 to be negative. This helps especially if you are doing division or
3640 <LI>NEVER jump into a LOOP.
3642 <LI>Declare the variables to be local whenever possible, especially loop
3643 control variables (induction).
3645 <LI>Since the compiler does not do implicit integral promotion, the programmer
3646 should do an explicit cast when integral promotion is required.
3648 <LI>Reducing the size of division , multiplication & modulus operations
3649 can reduce code size substantially. Take the following code for example.
3652 <FONT SIZE="-1">foobar( unsigned int p1, unsigned char ch)</FONT>
3653 <BR><FONT SIZE="-1">{</FONT>
3654 <BR><FONT SIZE="-1"> unsigned char ch1 = p1 % ch ;</FONT>
3655 <BR><FONT SIZE="-1"> .... </FONT>
3656 <BR><FONT SIZE="-1">}</FONT>
3661 For the modulus operation the variable ch will be promoted to unsigned
3662 int first then the modulus operation will be performed (this will
3663 lead to a call to a support routine). If the code is changed to
3666 <FONT SIZE="-1">foobar( unsigned int p1, unsigned char ch)</FONT>
3667 <BR><FONT SIZE="-1">{</FONT>
3668 <BR><FONT SIZE="-1"> unsigned char ch1 = (unsigned char)p1 % ch
3670 <BR><FONT SIZE="-1"> .... </FONT>
3671 <BR><FONT SIZE="-1">}</FONT>
3676 It would substantially reduce the code generated (future versions
3677 of the compiler will be smart enough to detect such optimization oppurtunities).
3682 <B>Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)</B>
3685 The 8051 family of micro controller have a minimum of 128 bytes of
3686 internal memory which is structured as follows
3689 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7
3693 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
3696 - Bytes 30-7F - 60 bytes for general purpose use.
3699 Normally the SDCC compiler will only utilise the first bank of registers,
3700 but it is possible to specify that other banks of registers should
3701 be used in interrupt routines. By default, the compiler will place
3702 the stack after the last bank of used registers, i.e. if the first
3703 2 banks of registers are used, it will position the base of the internal
3704 stack at address 16 (0X10). This implies that as the stack grows,
3705 it will use up the remaining register banks, and the 16 bytes used
3706 by the 128 bit variables, and 60 bytes for general purpose use.
3709 By default, the compiler uses the 60 general purpose bytes to hold
3710 "near data". The compiler/optimiser may also declare
3711 some Local Variables in this area to hold local data.
3714 If any of the 128 bit variables are used, or near data is being used
3715 then care needs to be taken to ensure that the stack does not grow
3716 so much that it starts to over write either your bit variables or
3717 "near data". There is no runtime checking to prevent
3718 this from happening.
3721 The amount of stack being used is affected by the use of the "internal
3722 stack" to save registers before a subroutine call is made,
3723 - -stack-auto will declare parameters and local variables on the
3724 stack - the number of nested subroutines.
3727 If you detect that the stack is over writing you data, then the following
3728 can be done. -xstack will cause an external stack to be used for
3729 saving registers and (if -stack-auto is being used) storing parameters
3730 and local variables. However this will produce more and code which
3731 will be slower to execute.
3734 -stack-loc will allow you specify the start of the stack, i.e. you
3735 could start it after any data in the general purpose area. However
3736 this may waste the memory not used by the register banks and if the
3737 size of the "near data" increases, it may creep
3738 into the bottom of the stack.
3741 -stack-after-data, similar to the -stack-loc, but it automatically
3742 places the stack after the end of the "near data".
3743 Again this could waste any spare register space.
3746 -data-loc allows you to specify the start address of the near data.
3747 This could be used to move the "near data" further
3748 away from the stack giving it more room to grow. This will only work
3749 if no bit variables are being used and the stack can grow to use the
3756 If you find that the stack is over writing your bit variables or "near
3757 data" then the approach which best utilised the internal
3758 memory is to position the "near data" after the
3759 last bank of used registers or, if you use bit variables, after the
3760 last bit variable by using the -data-loc, e.g. if two register banks
3761 are being used and no data variables, -data-loc 16, and - use the
3762 -stack-after-data option.
3765 If bit variables are being used, another method would be to try and
3766 squeeze the data area in the unused register banks if it will fit,
3767 and start the stack after the last bit variable.
3771 <H1><A NAME="SECTION00070000000000000000">
3772 6 Retargetting for other MCUs.</A>
3776 The issues for retargetting the compiler are far too numerous to be
3777 covered by this document. What follows is a brief description of each
3778 of the seven phases of the compiler and its MCU dependency.
3783 <LI>Parsing the source and building the annotated parse tree. This phase
3784 is largely MCU independent (except for the language extensions). Syntax
3785 & semantic checks are also done in this phase , along with some initial
3786 optimizations like back patching labels and the pattern matching optimizations
3787 like bit-rotation etc.
3789 <LI>The second phase involves generating an intermediate code which can
3790 be easy manipulated during the later phases. This phase is entirely
3791 MCU independent. The intermediate code generation assumes the target
3792 machine has unlimited number of registers, and designates them with
3793 the name iTemp. The compiler can be made to dump a human readable
3794 form of the code generated by using the -dumpraw option.
3796 <LI>This phase does the bulk of the standard optimizations and is also
3797 MCU independent. This phase can be broken down into several sub-phases.
3802 <LI>Break down intermediate code (iCode) into basic blocks.
3804 <LI>Do control flow & data flow analysis on the basic blocks.
3806 <LI>Do local common subexpression elimination, then global subexpression
3809 <LI>dead code elimination
3811 <LI>loop optimizations
3813 <LI>if loop optimizations caused any changes then do 'global subexpression
3814 elimination' and 'dead code elimination' again.
3818 <LI>This phase determines the live-ranges; by live range I mean those
3819 iTemp variables defined by the compiler that still survive after all
3820 the optimizations. Live range analysis is essential for register allocation,
3821 since these computation determines which of these iTemps will be assigned
3822 to registers, and for how long.
3824 <LI>Phase five is register allocation. There are two parts to this process
3830 <LI>The first part I call 'register packing' (for lack of a better term)
3831 . In this case several MCU specific expression folding is done to
3832 reduce register pressure.
3834 <LI>The second part is more MCU independent and deals with allocating
3835 registers to the remaining live ranges. A lot of MCU specific code
3836 does creep into this phase because of the limited number of index
3837 registers available in the 8051.
3841 <LI>The Code generation phase is (unhappily), entirely MCU dependent and
3842 very little (if any at all) of this code can be reused for other MCU.
3843 However the scheme for allocating a homogenized assembler operand
3844 for each iCode operand may be reused.
3846 <LI>As mentioned in the optimization section the peep-hole optimizer is
3847 rule based system, which can reprogrammed for other MCUs.
3853 <H1><A NAME="SECTION00080000000000000000">
3854 7 SDCDB - Source Level Debugger</A>
3858 SDCC is distributed with a source level debugger. The debugger uses
3859 a command line interface, the command repertoire of the debugger has
3860 been kept as close to gdb ( the GNU debugger) as possible. The configuration
3861 and build process is part of the standard compiler installation, which
3862 also builds and installs the debugger in the target directory specified
3863 during configuration. The debugger allows you debug BOTH at the C
3864 source and at the ASM source level.
3868 <H2><A NAME="SECTION00081000000000000000">
3869 7.1 Compiling for Debugging</A>
3873 The <I>-debug</I> option must be specified for all files for which
3874 debug information is to be generated. The complier generates a <I>.cdb</I>
3875 file for each of these files. The linker updates the <I>.cdb</I> file
3876 with the address information. This .cdb is used by the debugger .
3880 <H2><A NAME="SECTION00082000000000000000">
3881 7.2 How the Debugger Works</A>
3885 When the <I>-debug</I> option is specified the compiler generates
3886 extra symbol information some of which are put into the the assembler
3887 source and some are put into the .cdb file, the linker updates the
3888 .cdb file with the address information for the symbols. The debugger
3889 reads the symbolic information generated by the compiler & the address
3890 information generated by the linker. It uses the SIMULATOR (Daniel's
3891 S51) to execute the program, the program execution is controlled by
3892 the debugger. When a command is issued for the debugger, it translates
3893 it into appropriate commands for the simulator .
3897 <H2><A NAME="SECTION00083000000000000000">
3898 7.3 Starting the Debugger</A>
3902 The debugger can be started using the following command line. (Assume
3903 the file you are debugging has
3912 The debugger will look for the following files.
3917 <LI>foo.c - the source file.
3919 <LI>foo.cdb - the debugger symbol information file.
3921 <LI>foo.ihx - the intel hex format object file.
3927 <H2><A NAME="SECTION00084000000000000000">
3928 7.4 Command Line Options.</A>
3934 <LI>-directory=<source file directory> this option can used to specify
3935 the directory search list. The debugger will look into the directory
3936 list specified for source , cdb & ihx files. The items in the directory
3937 list must be separated by ':' , e.g. if the source files can be in
3938 the directories /home/src1 and /home/src2, the -directory option
3939 should be -directory=/home/src1:/home/src2 . Note there can be no
3940 spaces in the option.
3942 <LI>-cd <directory> - change to the <directory>.
3944 <LI>-fullname - used by GUI front ends.
3946 <LI>-cpu <cpu-type> - this argument is passed to the simulator please
3947 see the simulator docs for details.
3949 <LI>-X <Clock frequency > this options is passed to the simulator please
3950 see simulator docs for details.
3952 <LI>-s <serial port file> passed to simulator see simulator docs for details.
3954 <LI>-S <serial in,out> passed to simulator see simulator docs for details.
3960 <H2><A NAME="SECTION00085000000000000000">
3961 7.5 Debugger Commands.</A>
3965 As mention earlier the command interface for the debugger has been
3966 deliberately kept as close the GNU debugger gdb , as possible, this
3967 will help int integration with existing graphical user interfaces
3968 (like ddd, xxgdb or xemacs) existing for the GNU debugger.
3972 <H3><A NAME="SECTION00085100000000000000">
3973 7.5.1 break [line | file:line | function | file:function]</A>
3977 Set breakpoint at specified line or function.
3982 sdcdb>break foo.c:100
3984 sdcdb>break funcfoo
3986 sdcdb>break foo.c:funcfoo
3990 <H3><A NAME="SECTION00085200000000000000">
3991 7.5.2 clear [line | file:line | function | file:function ]</A>
3995 Clear breakpoint at specified line or function.
4000 sdcdb>clear foo.c:100
4002 sdcdb>clear funcfoo
4004 sdcdb>clear foo.c:funcfoo
4008 <H3><A NAME="SECTION00085300000000000000">
4013 Continue program being debugged, after breakpoint.
4017 <H3><A NAME="SECTION00085400000000000000">
4022 Execute till the end of the current function.
4026 <H3><A NAME="SECTION00085500000000000000">
4027 7.5.5 delete [n]</A>
4031 Delete breakpoint number 'n'. If used without any option clear ALL
4032 user defined break points.
4036 <H3><A NAME="SECTION00085600000000000000">
4037 7.5.6 info [break | stack | frame | registers ]</A>
4043 <LI>info break - list all breakpoints
4045 <LI>info stack - show the function call stack.
4047 <LI>info frame - show information about the current execution frame.
4049 <LI>info registers - show content of all registers.
4055 <H3><A NAME="SECTION00085700000000000000">
4060 Step program until it reaches a different source line.
4064 <H3><A NAME="SECTION00085800000000000000">
4069 Step program, proceeding through subroutine calls.
4073 <H3><A NAME="SECTION00085900000000000000">
4078 Start debugged program.
4082 <H3><A NAME="SECTION000851000000000000000">
4083 7.5.10 ptype variable </A>
4087 Print type information of the variable.
4091 <H3><A NAME="SECTION000851100000000000000">
4092 7.5.11 print variable</A>
4096 print value of variable.
4100 <H3><A NAME="SECTION000851200000000000000">
4101 7.5.12 file filename</A>
4105 load the given file name. Note this is an alternate method of loading
4110 <H3><A NAME="SECTION000851300000000000000">
4115 print information about current frame.
4119 <H3><A NAME="SECTION000851400000000000000">
4120 7.5.14 set srcmode</A>
4124 Toggle between C source & assembly source.
4128 <H3><A NAME="SECTION000851500000000000000">
4129 7.5.15 ! simulator command</A>
4133 Send the string following '!' to the simulator, the simulator response
4134 is displayed. Note the debugger does not interpret the command being
4135 sent to the simulator, so if a command like 'go' is sent the debugger
4136 can loose its execution context and may display incorrect values.
4140 <H3><A NAME="SECTION000851600000000000000">
4145 "Watch me now. Iam going Down. My name is Bobby Brown"
4149 <H2><A NAME="SECTION00086000000000000000">
4150 7.6 Interfacing with XEmacs.</A>
4154 Two files are (in emacs lisp) are provided for the interfacing with
4155 XEmacs, <I>sdcdb.el</I> and <I>sdcdbsrc.el</I>. These two files can
4156 be found in the $(prefix)/bin directory after the installation is
4157 complete. These files need to be loaded into XEmacs for the interface
4158 to work, this can be done at XEmacs startup time by inserting the
4159 following into your <I>'.xemacs'</I> file (which can be found in your
4160 HOME directory) <I>(load-file sdcdbsrc.el)</I> [ .xemacs is a lisp
4161 file so the () around the command is REQUIRED), the files can also
4162 be loaded dynamically while XEmacs is running, set the environment
4163 variable <I>'EMACSLOADPATH'</I> to the installation bin directory
4164 [$(prefix)/bin], then enter the following command <I>ESC-x
4165 load-file sdcdbsrc .</I> To start the interface enter the following command
4166 <I>ESC-x sdcdbsrc</I> , you will prompted to enter the file name to
4170 The command line options that are passed to the simulator directly
4171 are bound to default values in the file <I>sdcdbsrc.el</I> the variables
4172 are listed below these values maybe changed as required.
4177 <LI>sdcdbsrc-cpu-type '51
4179 <LI>sdcdbsrc-frequency '11059200
4181 <LI>sdcdbsrc-serial nil
4184 The following is a list of key mapping for the debugger interface.
4188 <BR><FONT SIZE="-2">;; Current Listing :: </FONT>
4189 <BR><FONT SIZE="-2">;;key binding Comment
4191 <BR><FONT SIZE="-2">;;-- ---- ----
4193 <BR><FONT SIZE="-2">;; </FONT>
4194 <BR><FONT SIZE="-2">;; n sdcdb-next-from-src SDCDB
4195 next command </FONT>
4196 <BR><FONT SIZE="-2">;; b sdcdb-back-from-src SDCDB
4197 back command </FONT>
4198 <BR><FONT SIZE="-2">;; c sdcdb-cont-from-src SDCDB
4199 continue command</FONT>
4200 <BR><FONT SIZE="-2">;; s sdcdb-step-from-src SDCDB
4201 step command </FONT>
4202 <BR><FONT SIZE="-2">;; ? sdcdb-whatis-c-sexp SDCDB
4203 ptypecommand for data at </FONT>
4204 <BR><FONT SIZE="-2">;;
4205 buffer point </FONT>
4206 <BR><FONT SIZE="-2">;; x sdcdbsrc-delete SDCDB
4207 Delete all breakpoints if no arg </FONT>
4208 <BR><FONT SIZE="-2">;; given
4209 or delete arg (C-u arg x) </FONT>
4210 <BR><FONT SIZE="-2">;; m sdcdbsrc-frame SDCDB
4211 Display current frame if no arg, </FONT>
4212 <BR><FONT SIZE="-2">;; given
4213 or display frame arg </FONT>
4214 <BR><FONT SIZE="-2">;; buffer
4216 <BR><FONT SIZE="-2">;; ! sdcdbsrc-goto-sdcdb Goto
4217 the SDCDB output buffer </FONT>
4218 <BR><FONT SIZE="-2">;; p sdcdb-print-c-sexp SDCDB
4219 print command for data at </FONT>
4220 <BR><FONT SIZE="-2">;;
4221 buffer point </FONT>
4222 <BR><FONT SIZE="-2">;; g sdcdbsrc-goto-sdcdb Goto
4223 the SDCDB output buffer </FONT>
4224 <BR><FONT SIZE="-2">;; t sdcdbsrc-mode Toggles
4225 Sdcdbsrc mode (turns it off) </FONT>
4226 <BR><FONT SIZE="-2">;; </FONT>
4227 <BR><FONT SIZE="-2">;; C-c C-f sdcdb-finish-from-src SDCDB
4228 finish command </FONT>
4229 <BR><FONT SIZE="-2">;; </FONT>
4230 <BR><FONT SIZE="-2">;; C-x SPC sdcdb-break Set
4231 break for line with point </FONT>
4232 <BR><FONT SIZE="-2">;; ESC t sdcdbsrc-mode Toggle
4233 Sdcdbsrc mode </FONT>
4234 <BR><FONT SIZE="-2">;; ESC m sdcdbsrc-srcmode
4235 Toggle list mode </FONT>
4236 <BR><FONT SIZE="-2">;; </FONT>
4243 <H1><A NAME="SECTION00090000000000000000">
4244 8 Other Processors</A>
4249 <H2><A NAME="SECTION00091000000000000000">
4250 8.1 The Z80 and gbz80 port</A>
4254 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like
4255 gbz80. The port is incomplete - long support is incomplete (mul, div
4256 and mod are unimplimented), and both float and bitfield support is
4257 missing, but apart from that the code generated is correct.
4260 As always, the code is the authoritave reference - see z80/ralloc.c
4261 and z80/gen.c. The stack frame is similar to that generated by the
4262 IAR Z80 compiler. IX is used as the base pointer, HL is used as a
4263 temporary register, and BC and DE are available for holding varibles.
4264 IY is currently unusued. Return values are stored in HL. One bad side
4265 effect of using IX as the base pointer is that a functions stack frame
4266 is limited to 127 bytes - this will be fixed in a later version.
4270 <H1><A NAME="SECTION000100000000000000000">
4275 SDCC has grown to be large project, the compiler alone (without the
4276 Assembler Package, Preprocessor) is about 40,000 lines of code (blank
4277 stripped). The open source nature of this project is a key to its
4278 continued growth and support. You gain the benefit and support of
4279 many active software developers and end users. Is SDCC perfect? No,
4280 that's why we need your help. The developers take pride in fixing
4281 reported bugs. You can help by reporting the bugs and helping other
4282 SDCC users. There are lots of ways to contribute, and we encourage
4283 you to take part in making SDCC a great software package.
4287 <H2><A NAME="SECTION000101000000000000000">
4288 9.1 Reporting Bugs</A>
4292 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
4293 or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed ASAP. When
4294 reporting a bug, it is very useful to include a small test program
4295 which reproduces the problem. If you can isolate the problem by looking
4296 at the generated assembly code, this can be very helpful. Compiling
4297 your program with the -dumpall option can sometimes be useful in
4298 locating optimization problems.
4302 <H2><A NAME="SECTION000102000000000000000">
4303 9.2 Acknowledgments</A>
4307 Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code
4308 generator, Debugger, AVR port
4310 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX
4313 John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for
4316 Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
4318 Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware
4321 Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience
4324 Unknown - for the GNU C - preprocessor.
4326 Michael Hope - The Z80 and Z80GB port, 186 development
4328 Kevin Vigor - The DS390 port.
4330 Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
4332 Scott Datallo - PIC port.
4333 <BR>(Thanks to all the other volunteer developers who have helped with
4334 coding, testing, web-page creation, distribution sets, etc. You know
4338 This document initially written by Sandeep Dutta
4341 All product names mentioned herein may be trademarks of their respective
4347 <H1><A NAME="SECTION000110000000000000000">
4348 About this document ...</A>
4350 <STRONG>SDCC Compiler User Guide</STRONG><P>
4351 This document was generated using the
4352 <A HREF="http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2K.1beta (1.47)
4354 Copyright © 1993, 1994, 1995, 1996,
4355 <A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>,
4356 Computer Based Learning Unit, University of Leeds.
4358 Copyright © 1997, 1998, 1999,
4359 <A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>,
4360 Mathematics Department, Macquarie University, Sydney.
4362 The command line arguments were: <BR>
4363 <STRONG>latex2html</STRONG> <TT>-no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir72816uWRHo/lyx_tmpbuf7281E6F6dg/SDCCUdoc.tex</TT>
4365 The translation was initiated by Karl Bongers on 2001-07-02<HR>
4366 <!--Navigation Panel-->
4367 <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
4368 SRC="file:/usr/share/latex2html/icons/nx_grp_g.png">
4369 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
4370 SRC="file:/usr/share/latex2html/icons/up_g.png">
4371 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
4372 SRC="file:/usr/share/latex2html/icons/prev_g.png">
4374 <!--End of Navigation Panel-->