1 <!doctype linuxdoc system>
3 <!-- LinuxDoc file was created by LyX 1.0 (C) 1995-1999 by <sandeep> Sun Mar 26 12:40:33 2000
7 <title>SDCC Compiler User Guide
9 <author>Sandeep Dutta (sandeep.dutta@usa.net)
12 <p>SDCC is a Free ware , retargettable, optimizing ANSI-C compiler. The current
13 version targets Intel 8051 based MCUs, it can be retargetted for other 8 bit
14 MCUs or PICs. The entire source code for the compiler is distributed under
15 GPL. SDCC used ASXXXX & ASLINK a Free ware, retargettable assembler &
16 linker. SDCC has extensive MCU (8051) specific language extensions, which lets
17 it utilize the underlying hardware effectively. The front-end (parser) will
18 be enhanced to handle language extensions for other MCUs as and when they are
19 targetted. In addition to the MCU Specific optimizations SDCC also does a host
20 of standard optimizations like global sub expression elimination, loop optimizations
21 (loop invariant, strength reduction of induction variables and loop reversing),
22 constant folding & propagation, copy propagation, dead code elimination
23 and jumptables for 'switch' statements. For the back-end SDCC uses a global
24 register allocation scheme which should be well suited for other 8 bit MCUs
25 , the peep hole optimizer uses a rule based substitution mechanism which is
26 MCU independent. Supported data-types are short (8 bits, 1 byte), char (8 bits,
27 1 byte), int (16 bits, 2 bytes ), long (32 bit, 4 bytes) & float (4 byte
28 IEEE). The compiler also allows inline assembler code to be embedded anywhere
29 in a function. In addition routines developed in assembly can also be called.
30 SDCC also provides an option to report the relative complexity of a function,
31 these functions can then be further optimized , or hand coded in assembly if
32 need be. SDCC also comes with a companion source level debugger SDCDB, the
33 debugger currently uses S51 a freeware simulator for 8051, it can be easily
34 modified to use other simulators. The latest version can be downloaded from
35 <bf>http://www.geocities.com/ResearchTriangle/Forum/1353</bf>
37 <p>All packages used in this compiler system are opensource (freeware); source
38 code for all the sub-packages ( asxxxx assembler/linker , pre-processor and
39 gc a conservative garbage collector) are distributed with the package. Documentation
40 was created using a freeware word processor (LyX).
42 <p>This program is free software; you can redistribute it and/or modify it
43 under the terms of the GNU General Public License as published by the Free
44 Software Foundation; either version 2, or (at your option) any later version.
45 This program is distributed in the hope that it will be useful, but WITHOUT
46 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
47 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
48 You should have received a copy of the GNU General Public License along with
49 this program; if not, write to the Free Software Foundation, 59 Temple Place
50 - Suite 330, Boston, MA 02111-1307, USA. In other words, you are welcome to
51 use, share and improve this program. You are forbidden to forbid anyone else
52 to use, share and improve what you give them. Help stamp out software-hoarding!
55 <sect>Installation <label id="Installation" >
56 <p>What you need before you start installation of SDCC ? A C Compiler, not
57 just any C Compiler, gcc to be exact, you can get adventurous and try another
58 compiler , I HAVEN'T tried it. GCC is free , and is available for almost all
59 major platforms, if you are using linux you probably already have it, if you
60 are using Windows 95/NT go to www.cygnus.com and download CYGWIN32 you will
61 need the full development version of their tool (full.exe), follow their instructions
62 for installation (this is also free and is very easy to install), Windows 95/NT
63 users be aware that the compiler runs substantially slower on the Windows platform,
66 <p>After you have installed gcc you are ready to build the compiler (sorry
67 no binary distributions yet). SDCC is native to Linux but can be ported to
68 any platform on which GCC is available . Extract the source file package (.zip
69 or .tar.gz) into some directory , which we shall refer to as SDCCDIR from now
72 <sect1>Components of SDCC<label id="Components" >
73 <sect2>gc ( a conservative garbage collector)
74 <p>SDCC relies on this component to do all the memory management, this excellent
75 package is copyrighted by Jans J Boehm(boehm@sgi.com) and Alan J Demers but
76 can be used with minimum restrictions. The GC source will be extracted into
77 the directory SDCCDIR/gc.
79 <sect2>cpp ( C-Preprocessor)
80 <p>The preprocessor is extracted into the directory SDCCDIR/cpp, it is a modified
81 version of the GNU preprocessor.
83 <sect2>asxxxx & aslink ( The assembler and Linkage Editor)
84 <p>This is retargettable assembler & linkage editor, it was developed
85 by Alan Baldwin, John Hartman created the version for 8051, and I (Sandeep)
86 have some enhancements and bug fixes for it to work properly with the SDCC.
87 This component is extracted into the directory SDCCDIR/asxxxx.
89 <sect2>SDCC - The compiler.
90 <p>This is the actual compiler, it uses gc and invokes the assembler and linkage
91 editor. All files with the prefix SDCC are part of the compiler and is extracted
92 into the the directory SDCCDIR.
94 <sect2>S51 - Simulator
95 <p>Version 2.1.8 onwards contains s51 a freeware , opensource simulator developed
96 by Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu>. The executable
97 is built as part of build process, for more information visit Daniel's website
98 at <http://mazsola.iit.uni-miskolc.hu/˜drdani/embedded/s51/>.
100 <sect2>SDCDB - Source level Debugger.
101 <p>SDCDB is the companion source level debugger . The current version of the
102 debugger uses Daniel's Simulator S51, but can be easily changed to use other
105 <sect1>Installation for Version <= 2.1.7
106 <p>After the package is extracted (Windows 95/NT users start CYGWIN shell),
107 change to the directory where you extracted the package and give the command.
112 <p>This is a bash shell script, it will compile all the above mentioned components
113 and install the executables into the directory SDCCDIR/bin make sure you add
114 this directory to your PATH environment variable. This script will also compile
115 all the support routines ( library routines ) using SDCC. The support routines
116 are all developed in C and need to be compiled.
118 <sect1>Installation for Version >= 2.1.8a
119 <p>The distribution method from Version 2.1.8a has been changed to be conforment
120 with the "autoconf" utility. The source is now distributed as <bf>sdcc-<version
121 number>.tar.gz format</bf> , instead of the older .zip format. The steps for
122 installation are as follows.
124 <sect2>Unpack the sources.
125 <p>This is usually done by the following command "<bf>gunzip -c sdcc-<version
126 number>.tar.gz | tar -xv -</bf>"
128 <sect2>Change to the main source directory (usually sdcc or sdcc-<version number>)
129 <sect2>Issue command to configure your system
130 <p>The configure command has several options the most commonly used option
131 is --prefix=<directory name>, where <directory name> is the final
132 location for the sdcc executables and libraries, (default location is /usr/local).
133 The installation process will create the following directory structure under
134 the <directory name> specified.
137 <verb>bin/ - binary exectables (add to PATH environment variable)
140 - include header files
142 small/ - Object &
143 Library files for small model library
144 large/ - Object & library
145 files for large model library
149 <p><bf>'./configure --prefix=/usr/local" </bf>
151 <p>will create configure the compiler to be installed in directory /usr/local/bin.
154 <p>After configuration step issue the command
158 <p>This will compile the compiler
160 <sect2>"make install"
161 <p>Will install the compiler and libraries in the appropriate directories.
163 <sect2>Special Notes for Windows Users. Provided by Michael Jamet[ mjamet@computer.org]
167 <p> How to install SDCC from source on a Windows 95 or Windows NT 4 system
172 <p> This document describes how to install SDCC on a Win 95 or Win NT 4 system.
175 <p> These instructions probably work for Win 98 as well, but have not been
178 <p> tested on that platform.
182 <p> There are lots of little differences between UNIX and the Win32 Cygnus
185 <p> environment which make porting more difficult than it should be. If
188 <p> you want the details, please contact me. Otherwise just follow these
195 <p> 1. Install the Cygnus Software
197 <p> Go to http://sourceware.cygnus.com/cygwin. Cygnus provides a UNIX like
200 <p> environment for Win 32 systems. Download &dquot;full.exe&dquot; and
203 <p> MUST install it on your C drive. &dquot;full.exe&dquot; contains a shell
206 <p> common UNIX utilities.
210 <p> 2. Download and Extract the Latest SDCC
212 <p> The latest version can be found at
214 <p> www.geocities.com/ResearchTriange/Forum/1353.
216 <p> It can be uncompressed with winzip.
220 <p> 3. Start a Cygnus Shell
222 <p> There should be an entry in the Start Menu for Cygnus. Invoke the shell.
225 <p> This gives you a UNIX like environment. FROM THIS POINT ON, DIRECTORIES
228 <p> MUST BE SPECIFIED WITH FORWARD SLASHES (/) NOT THE DOS STYLE BACK
230 <p> SLASHES (\) BECAUSE THIS IS WHAT UNIX EXPECTS. -
232 <p> ex. &dquot;\winnt&dquot; would be &dquot;/winnt&dquot; under the
237 <p> 4. Change Directory to Where SDCC was extracted (referred to as INSTALLDIR)
242 <p> ex. cd /sdcc218Da. If you extracted to a drive OTHER THAN C, the drive
245 <p> must be specified as part of the path. For example, if you extracted
248 <p> your &dquot;g drive&dquot;, type the following: &dquot;cd //g/mydir&dquot;.
249 You must use &dquot;//&dquot;
251 <p> to specify the drive.
255 <p> 5. Make Dirs Which are Automatically Made During the UNIX Installation
258 <p> From the INSTALLDIR,
262 <p> mkdir -p bin (not a typo, just &dquot;bin&dquot;)
266 <p> mkdir -p /usr/local/bin
268 <p> mkdir -p /usr/local/share
270 <p> mkdir -p /usr/local/share/sdcc51lib
272 <p> mkdir -p /usr/local/share/sdcc51inc
278 <p> (When a path from the root directory is specified WITHOUT a drive, the
281 <p> drive defaults to c. For example /michael/newuser => c:\michael\newuser)
286 <p> 6. Add Programs to /bin Expected by the Installation Process
288 <p> - Look at your path: echo $PATH
290 <p> One of the fields is the diretory with the CYGNUS programs.
292 <p> ex. /CYGNUS/CYGWIN˜1/H-I586/BIN
296 <p> - cd to the directory found above. You may have to fiddle with the
299 <p> case (upper or lower) here because the PATH is SHOWN as all upper
302 <p> case, but is actually mixed. To help you along, you may type
304 <p> a letter or 2 followed by the escape key. The shell will fill
306 <p> out the remaining letters IF THEY describe a unique directory.
308 <p> If you have problems here, cd one directory and type &dquot;ls&dquot;.
311 <p> is the equivalent of &dquot;dir/w&dquot;.
315 <p> - Copy the following:
325 <p> 7. Go back to the INSTALLDIR
329 <p> ex. cd //d/sdcc218Da
333 <p> 8. Run the configure Program
337 <p> The &dquot;./&dquot; is important because your current directory is NOT
340 <p> Under DOS, your current directory was implicitly always the first entry
353 <p> This process takes quite some time under Win 32.
357 <p> 10. Install the Newly Built Software
363 <p> This will partially install the software into the /usr/local directories
366 <p> created in step 5. What it actually doing is copying the .c, .h and
369 <p> library files to directories under /usr/local/share.
373 <p> It will NOT be able to install the actual programs (binaries) because
376 <p> it does not know programs on Win32 systems have &dquot;.exe&dquot; extensions.
379 <p> For example, it tries to install sdcc instead of sdcc.exe.
383 <p> After the automated part is finished, you must manually copy the binaries:
386 <p> cd bin (This is the bin directory in your INSTALLDIR)
388 <p> cp * /usr/local/bin
392 <p> 11. Make sure /usr/local/bin is in Your PATH
394 <p> You may add c:\usr\local\bin to your path however your
395 Win32 system allows. For
397 <p> example you may add it to the PATH statement in autoexec.bat.
401 <p> Good luck. If you have any questions send them to me or post them
405 <sect>Compiling.<label id="Compiling" >
406 <sect1>Single Source file projects.<label id="One Source File" >
407 <p>For single source file projects the process is very simple. Compile your
408 programs with the following command
411 <verb>sdcc sourcefile.c
413 <p>The above command will compile ,assemble and link your source file. Output
414 files are as follows.
418 <item>sourcefile.asm - Assembler source file created by the compiler
419 <item>sourcefile.lst - Assembler listing file created by the Assembler
420 <item>sourcefile.rst - Assembler listing file updated with linkedit information
421 , created by linkage editor
422 <item>sourcefile.sym - symbol listing for the sourcefile, created by the assembler.
423 <item>sourcefile.rel - Object file created by the assembler, input to Linkage
425 <item>sourcefile.map - The memory map for the load module, created by the Linker.
426 <item>sourcefile.<ihx | s19> - The load module : ihx - Intel hex format
427 (default ), s19 - Motorola S19 format when compiler option --out-fmt-s19 is
430 <sect1>Projects with multiple source files.
431 <p>SDCC can compile only ONE file at a time. Let us for example assume that
432 you have a project containing the following files.
435 <verb>foo1.c ( contains some functions )foo2.c (contains some more functions)foomain.c (contains more functions and the function main)
437 <p>The first two files will need to be compiled separately with the commands
440 <verb>sdcc -c foo1.csdcc -c foo2.c
442 <p>Then compile the source file containing main and link the other files together
443 with the following command.
446 <verb>sdcc foomain.c foo1.rel foo2.rel
448 <p>Alternatively foomain.c can be separately compiled as well
451 <verb>sdcc -c foomain.c sdcc foomain.rel foo1.rel foo2.rel
453 <p>The file containing the main function MUST be the FIRST file specified
454 in the command line , since the linkage editor processes file in the order
455 they are presented to it.
457 <sect1>Projects with additional libraries.
458 <p>Some reusable routines may be compiled into a library, see the documentation
459 for the assembler and linkage editor in the directory SDCCDIR/asxxxx/asxhtm.htm
460 this describes how to create a .lib library file, the libraries created in
461 this manner may be included using the command line, make sure you include the
462 -L <library-path> option to tell the linker where to look for these files.
463 Here is an example, assuming you have the source file 'foomain.c' and a library
464 'foolib.lib' in the directory 'mylib'.
467 <verb>sdcc foomain.c foolib.lib -L mylib
469 <p>Note here that 'mylib' must be an absolute path name.
471 <p>The view of the way the linkage editor processes the library files, it
472 is recommended that you put each source routine in a separate file and combine
473 them using the .lib file. For an example see the standard library file 'libsdcc.lib'
474 in the directory SDCCDIR/sdcc51lib.
476 <sect>Command Line options<label id="Command Line Options" >
479 <item><bf>--model-large<label id="--model-large" ></bf> Generate code for Large model programs see section Memory
480 Models for more details. If this option is used all source files in the project
481 should be compiled with this option. In addition the standard library routines
482 are compiled with small model , they will need to be recompiled.
483 <item><bf>--model-small</bf> <label id="--model-small" >Generate code for Small Model programs see section Memory
484 Models for more details. This is the default model.
485 <item><bf>--model-flat24</bf> <ref id="--model-flat24" name="--model-flat24" >Generate code for Small Model programs see section Memory
486 Models for more details. This is the default model.
487 <item><bf>--stack-auto</bf> <label id="--stack-auto" >All functions in the source file will be compiled as reentrant,
488 i.e. the parameters and local variables will be allocated on the stack. see
489 section Parameters and Local Variables for more details. If this option is
490 used all source files in the project should be compiled with this option.
491 <item><bf>--xstack</bf><label id="--xstack" > Uses a pseudo stack in the first 256 bytes in the external ram
492 for allocating variables and passing parameters. See section on external stack
494 <item><bf>--nogcse</bf><label id="--nogcse" > Will not do global subexpression elimination, this option may
495 be used when the compiler creates undesirably large stack/data spaces to store
496 compiler temporaries. A warning message will be generated when this happens
497 and the compiler will indicate the number of extra bytes it allocated. It recommended
498 that this option NOT be used , #pragma NOGCSE can be used to turn off global
499 subexpression elimination for a given function only.
500 <item><bf>--noinvariant</bf><label id="--noinvariant" > Will not do loop invariant optimizations, this may be turned
501 off for reasons explained for the previous option . For more details of loop
502 optimizations performed see section Loop Invariants.It recommended that this
503 option NOT be used , #pragma NOINVARIANT can be used to turn off invariant
504 optimizations for a given function only.
505 <item><bf>--noinduction</bf><label id="--noinduction" > Will not do loop induction optimizations, see section Strength
506 reduction for more details.It recommended that this option NOT be used , #pragma
507 NOINDUCTION can be used to turn off induction optimizations for given function
509 <item><bf>--nojtbound </bf><label id="--nojtbound" > Will not generate boundary condition check when switch statements
510 are implemented using jump-tables. See section Switch Statements for more details.It
511 recommended that this option NOT be used , #pragma NOJTBOUND can be used
512 to turn off boundary checking for jump tables for a given function only.
513 <item><bf>--noloopreverse</bf> <label id="--noloopreverse" >Will not do loop reversal optimization
514 <item><bf>--noregparms</bf><label id="--noregparms" > By default the first parameter is passed using global registers
515 (DPL,DPH,B,ACC). This option will disable parameter passing using registers.
516 NOTE: if your program uses the 16/32 bit support routines (for multiplication/division)
517 these library routines will need to be recompiled with the --noregparms option
519 <item><bf>--callee-saves function1[,function2][,function3]....</bf>
520 <label id="--callee-saves" >The compiler by default uses a caller saves convention for register saving
521 across function calls, however this can cause unneccessary register pushing
522 & popping when calling small functions from larger functions. This option
523 can be used to switch the register saving convention for the function names
524 specified. The compiler will not save registers when calling these functions,
525 extra code will be generated at the entry & exit for these functions to
526 save & restore the registers used by these functions, this can SUBSTANTIALLY
527 reduce code & improve run time performance of the generated code. In future
528 the compiler (with interprocedural analysis) will be able to determine the
529 appropriate scheme to use for each function call. DO NOT use this option for
530 built-in functions such as _muluint..., if this option is used for a library
531 function the appropriate library function needs to be recompiled with the same
532 option. If the project consists of multiple source files then all the source
533 file should be compiled with the same --callee-saves option string. Also see
534 Pragma Directive<ref id="Pragmaa" name="" > CALLEE-SAVES.<ref id="pragma callee-saves" name="" > .
535 <item><bf>--debug </bf><label id="--debug" >When this option is used the compiler will generate debug information
536 , that can be used with the SDCDB. The debug information is collected in a
537 file with .cdb extension. For more information see documentation for SDCDB.
538 <item><bf>--regextend </bf><label id="--regextend" > This option will cause the compiler to define pseudo registers
539 , if this option is used, all source files in the project should be compiled
540 with this option. See section Register Extension for more details.
541 <item><bf>--compile-only</bf>(-c) <label id="--compile-only" > will compile and assemble the source only, will not
542 call the linkage editor.
543 <item><bf>--xram-loc </bf><label id="--xram-loc" ><Value> The start location of the external ram, default
544 value is 0. The value entered can be in Hexadecimal or Decimal format .eg.
545 --xram-loc 0x8000 or --xram-loc 32768.
546 <item><bf>--code-loc </bf><label id="--code-loc" ><Value> The start location of the code segment , default
547 value 0. Note when this option is used the interrupt vector table is also relocated
548 to the given address. The value entered can be in Hexadecimal or Decimal format
549 .eg. --code-loc 0x8000 or --code-loc 32768.
550 <item><bf>--stack-loc</bf><label id="--stack-loc" ><Value> The initial value of the stack pointer. The default
551 value of the stack pointer is 0x07 if only register bank 0 is used, if other
552 register banks are used then the stack pointer is initialized to the location
553 above the highest register bank used. eg. if register banks 1 & 2 are used
554 the stack pointer will default to location 0x18. The value entered can be in
555 Hexadecimal or Decimal format .eg. --stack-loc 0x20 or --stack-loc 32. If all
556 four register banks are used the stack will be placed after the data segment
557 (equivalent to --stack-after-data)
558 <item><bf>--stack-after-data</bf><label id="--stack-after-data" >This option will cause the stack to be located in the
559 internal ram after the data segment.
560 <item><bf>--data-loc</bf> <label id="--data-loc" ><Value> The start location of the internal ram data segment,
561 the default value is 0x30.The value entered can be in Hexadecimal or Decimal
562 format .eg. --data-loc 0x20 or --data-loc 32.
563 <item><bf>--idata-loc</bf><label id="--idata-loc" ><Value> The start location of the indirectly addressable
564 internal ram, default value is 0x80. The value entered can be in Hexadecimal
565 or Decimal format .eg. --idata-loc 0x88 or --idata-loc 136.
566 <item><bf>--peep-file<label id="--peep-file" > </bf><filename> This option can be used to use additional
567 rules to be used by the peep hole optimizer. See section Peep Hole optimizations
568 for details on how to write these rules.
569 <item><bf>--lib-path (-L) </bf><label id="--lib-path" ><absolute path to additional libraries> This option
570 is passed to the linkage editor, additional libraries search path. The path
571 name must be absolute. Additional library files may be specified in the command
572 line . See section Compiling programs for more details.
573 <item><bf>-I <path><label id="-I" ></bf> The additional location where the pre processor will look
574 for <..h> or "..h" files.
575 <item><bf>-D<macro[=value]></bf> <label id="-D" >Command line definition of macros. Passed
576 to the pre processor.
577 <item><bf>-E</bf><label id="-E" > Run only the C preprocessor. Preprocess all the C source files specified
578 and output the results to standard output.
579 <item><bf>-M<label id="-M" ></bf> Tell the preprocessor to output a rule suitable for make describing
580 the dependencies of each object file. For each source file, the preprocessor
581 outputs one make-rule whose target is the object file name for that source
582 file and whose dependencies are all the files `#include'd in it. This rule
583 may be a single line or may be continued with `\'-newline if it is long.
584 The list of rules is printed on standard output instead of the preprocessed
585 C program. `-M' implies `-E'.
586 <item><bf>-C</bf> <label id="-C" >Tell the preprocessor not to discard comments. Used with the `-E' option.
587 <item><bf>-MM </bf><label id="-MM" >Like `-M' but the output mentions only the user header files included
588 with `#include file&dquot;'. System header files included with `#include
589 <file>' are omitted.
590 <item><bf>-Aquestion(answer)</bf><label id="-Aquestion(answer)" > Assert the answer answer for question, in case it is
591 tested with a preprocessor conditional such as `#if #question(answer)'.
592 `-A-' disables the standard asser- tions that normally describe the target
594 <item><bf>-Aquestion</bf><label id="-Aquestion" > (answer) Assert the answer answer for question, in case it is
595 tested with a preprocessor conditional such as `#if #question(answer)'.
596 `-A-' disables the standard assertions that normally describe the target machine.
597 <item><bf>-Umacro</bf><label id="-Umacro" > Undefine macro macro. `-U' options are evaluated after all `-D'
598 options, but before any `-include' and `-imac- ros' options.
599 <item><bf>-dM</bf><label id="-dM" > Tell the preprocessor to output only a list of the mac- ro definitions
600 that are in effect at the end of prepro- cessing. Used with the `-E' option.
601 <item><bf>-dD</bf> <label id="-dD" >Tell the preprocessor to pass all macro definitions into the output,
602 in their proper sequence in the rest of the output.
603 <item><bf>-dN </bf><label id="-dN" >Like `-dD' except that the macro arguments and contents are omitted.
604 Only `#define name' is included in the output.
605 <item><bf>-S </bf><label id="-S" >Stop after the stage of compilation proper; do not as- semble. The output
606 is an assembler code file for the input file specified.
607 <item><bf>-Wa asmOption[,asmOption]</bf>... Pass the asmOption to the assembler
608 <item><bf>-Wl linkOption[,linkOption]</bf> .. Pass the linkOption to the linker.
609 <item><bf>--int-long-reent</bf> <label id="--int-long-rent" > Integer (16 bit) and long (32 bit) libraries have been
610 compiled as reentrant. Note by default these libraries are compiled as non-reentrant.
611 See section Installation for more details.
612 <item><bf>--cyclomatic </bf><label id="--cyclomatic" >This option will cause the compiler to generate an information
613 message for each function in the source file. The message contains some important
614 information about the function. The number of edges and nodes the compiler
615 detected in the control flow graph of the function, and most importantly the
616 cyclomatic complexity see section on Cyclomatic Complexity for more details.
617 <item><bf>--float-reent </bf><label id="--float-reent" > Floating point library is compiled as reentrant.See section
618 Installation for more details.
619 <item><bf>--out-fmt-ihx<label id="--out-fmt-ihx" > </bf>The linker output (final object code) is in Intel Hex format.
620 (This is the default option).
621 <item><bf>--out-fmt-s19 </bf><label id="--out-fmt-s19" >The linker output (final object code) is in Motorola S19
623 <item><bf>--nooverlay</bf> <label id="--nooverlay" > The compiler will not overlay parameters and local variables
624 of any function, see section Parameters and local variables for more details.
625 <item><bf>--main-return</bf><label id="--main-return" > This option can be used when the code generated is called
626 by a monitor program. The compiler will generate a 'ret' upon return from the
627 'main' function. The default option is to lock up i.e. generate a 'ljmp .'
629 <item><bf>--no-peep</bf> <label id="--no-peep" > Disable peep-hole optimization.
630 <item><bf>--peep-asm</bf> <label id="--peep-asm" > Pass the inline assembler code through the peep hole optimizer.
631 Can cause unexpected changes to inline assembler code , please go through the
632 peephole optimizer rules defnied in file 'SDCCpeeph.def' before using this
634 <item><bf>--iram-size</bf><label id="--iram-size" > <Value> Causes the linker to check if the interal ram
635 usage is within limits of the given value.
637 <p>The following options are provided for the purpose of retargetting and
638 debugging the compiler . These provided a means to dump the intermediate code
639 (iCode) generated by the compiler in human readable form at various stages
640 of the compilation process.
644 <item><bf>--dumpraw </bf><label id="--dumpraw" >. This option will cause the compiler to dump the intermediate
645 code into a file of named <source filename>.dumpraw just after the intermediate
646 code has been generated for a function , i.e. before any optimizations are
647 done. The basic blocks at this stage ordered in the depth first number, so
648 they may not be in sequence of execution.
649 <item><bf>--dumpgcse</bf>.<label id="--dumpgcse" > Will create a dump if iCode, after global subexpression elimination,
650 into a file named <source filename>.dumpgcse.
651 <item><bf>--dumpdeadcode </bf><label id="--dumpdeadcode" >.Will create a dump if iCode, after deadcode elimination,
652 into a file named <source filename>.dumpdeadcode.
653 <item><bf>--dumploop.</bf> <label id="--dumploop" >Will create a dump if iCode, after loop optimizations, into
654 a file named <source filename>.dumploop.
655 <item><bf>--dumprange.</bf> <label id="--dump-range" >Will create a dump if iCode, after live range analysis, into
656 a file named <source filename>.dumprange.
657 <item><bf>--dumpregassign. </bf><label id="--dumpregassign" >Will create a dump if iCode, after register assignment
658 , into a file named <source filename>.dumprassgn.
659 <item><bf>--dumpall. </bf><label id="--dumpall" >Will cause all the above mentioned dumps to be created.
661 <p>Note that the files created for the dump are appended to each time. So
662 the files should be deleted manually , before each dump is created.
664 <p>When reporting bugs, it will be very helpful if you could include these
665 dumps along with the portion of the code that is causing the problem.
667 <sect>Language Extensions<label id="Language Extension" >
668 <sect1>Storage Classes.<label id="Storage Classes" >
669 <p>In addition to the ANSI storage classes SDCC allows the following 8051
670 specific storage classes.
672 <sect2>xdata.<label id="xdata" >
673 <p>Variables declared with this storage class will be placed in the extern
674 RAM. This is the <bf>default</bf> storage class for Large Memory model .
676 <p>eg. xdata unsigned char xduc;
678 <sect2>data<label id="data" >
679 <p>This is the <bf>default</bf> storage class for Small Memory model. Variables declared
680 with this storage class will be allocated in the internal RAM.
682 <p>eg. data int iramdata;
684 <sect2>idata<label id="idata" >
685 <p>Variables declared with this storage class will be allocated into the indirectly
686 addressable portion of the internal ram of a 8051 .
690 <sect2>bit<label id="bit" >
691 <p>This is a data-type and a storage class specifier. When a variable is declared
692 as a bit , it is allocated into the bit addressable memory of 8051.
696 <sect2>sfr / sbit<label id="sfr / sbit" >
697 <p>Like the bit keyword, sfr / sbit signifies both a data-type and storage
698 class, they are used to describe the special function registers and special
699 bit variables of a 8051.
703 <p>sfr at 0x80 P0; /* special function register P0 at location 0x80 */
705 <p>sbit at 0xd7 CY; /* CY (Carry Flag) */
707 <sect>Optimizations<label id="Optimizations" >
708 <p>SDCC performs a a host of standard optimizations in addition to some MCU
709 specific optimizations.
711 <sect1>Sub-expression elimination<label id="Sub-expression Elimination" >
712 <p>The compiler does local and global common subexpression elimination.
720 <p>will be translated to
727 <p>Some subexpressions are not as obvious as the above example.
732 <verb>a->b[i].c = 10;
733 a->b[i].d = 11;
735 <p>In this case the address arithmetic a->b[i] will be computed
736 only once; the equivalent code in C would be.
739 <verb>iTemp = a->b[i];
743 <p>The compiler will try to keep these temporary variables in registers.
745 <sect1>Dead-Code elimination.<label id="Dead-code elimination" >
752 i = 1; /* dead store */
754 = 1; /* dead store */
757 global = 3; /* unreachable
761 <p>will be changed to
764 <verb>int global; void f ()
770 <sect1>Copy-Propagation:<label id="Copy-Propagation" >
781 <p>will be changed to
792 <p>Note: the dead stores created by this copy propagation will be eliminated
793 by dead-code elimination .
795 <sect1>Loop optimizations<label id="Loop Optimizations" >
796 <p>Two types of loop optimizations are done by SDCC loop invariant lifting
797 and strength reduction of loop induction variables.In addition to the strength
798 reduction the optimizer marks the induction variables and the register allocator
799 tries to keep the induction variables in registers for the duration of the
800 loop. Because of this preference of the register allocator , loop induction
801 optimization causes an increase in register pressure, which may cause unwanted
802 spilling of other temporary variables into the stack / data space . The compiler
803 will generate a warning message when it is forced to allocate extra space either
804 on the stack or data space. If this extra space allocation is undesirable then
805 induction optimization can be eliminated either for the entire source file
806 ( with --noinduction option) or for a given function only (#pragma NOINDUCTION).
808 <sect2>Loop Invariant:<label id="Loop Invariant" >
812 <verb>for (i = 0 ; i < 100 ; i ++)
819 for ( i = 0; i < 100; i++ ) f += itemp;
821 <p>As mentioned previously some loop invariants are not as apparent, all static
822 address computations are also moved out of the loop.
824 <sect2>Strength reduction :<label id="Strength Reduction" >
825 <p>This optimization substitutes an expression by a cheaper expression.
830 <verb>for (i=0;i < 100; i++) ar[i*5] = i*3;
837 for (i=0;i< 100;i++) {
844 <p>The more expensive multiplication is changed to a less expensive addition.
846 <sect2>Loop reversing:<label id="Loop reversing" >
847 <p>This optimization is done to reduce the overhead of checking loop boundaries
848 for every iteration. Some simple loops can be reversed and implemented using
849 a "decrement and jump if not zero" instruction. SDCC checks for the following
850 criterion to determine if a loop is reversible (note: more sophisticated compiers
851 use data-dependency analysis to make this determination, SDCC uses a more simple
856 <item>The 'for' loop is of the form
857 "for ( <symbol> = <expression>
858 ; <sym> [< | <=] <expression> ; [<sym>++
859 | <sym> += 1])
861 <item>The <for body> does not contain "continue" or 'break".
862 <item>All goto's are contained within the loop.
863 <item>No function calls within the loop.
864 <item>The loop control variable <sym> is not assigned any value within
866 <item>The loop control variable does NOT participate in any arithmetic operation
868 <item>There are NO switch statements in the loop.
870 <p>Note djnz instruction can be used for 8-bit values ONLY, therefore it is
871 advantageous to declare loop control symbols as either 'char' or 'short', ofcourse
872 this may not be possible on all situations.
874 <sect1>Algebraic simplifications:<label id="Algebraic Simplifications" >
875 <p>SDCC does numerous algebraic simplifications, the following is a small
876 sub-set of these optimizations.
880 i = j + 0 ; /* changed to */ i = j;
881 i /= 2; /* changed to */ i >>=
883 i = j - j ; /* changed to */ i = 0;
884 i = j / 1 ; /* changed to */ i = j;
886 <p>Note the subexpressions given above are generally introduced by macro expansions
887 or as a result of copy/constant propagation.
889 <sect1>'switch' statements.<label id="Switch Statement" >
890 <p>SDCC changes switch statements to jump tables when the following conditions
895 <item>The case labels are in numerical sequence , the labels need not be in order,
896 and the starting number need not be one or zero.
901 <verb>switch(i) { switch (i) {
906 case 3:... case 3: ...
911 <p>Both the above switch statements will be implemented using a jump-table.
915 <item>The number of case labels is at least three, since it takes two conditional
916 statements to handle the boundary conditions.
917 <item>The number of case labels is less than 84, since each label takes 3 bytes
918 and a jump-table can be utmost 256 bytes long.
920 <p>Switch statements which have gaps in the numeric sequence or those that
921 have more that 84 case labels can be split into more than one switch statement
922 for efficient code generation.
927 <verb>switch (i) {
939 <p>If the above switch statement is broken down into two switch statements
942 <verb>switch (i) {
947 }switch (i) {
955 <p>then both the switch statements will be implemented using jump-tables whereas
956 the unmodified switch statement will not be .
958 <sect1>bit-shifting operations.<label id="bit shifting" >
959 <p>Bit shifting is one of the most frequently used operation in embedded programming
960 . SDCC tries to implement bit-shift operations in the most efficient way possible.
965 <verb>unsigned short i;...
969 <p>generates the following code.
977 <p>In general SDCC will never setup a loop if the shift count is known. Another
981 <verb>unsigned int i;
990 mov (_i + 1),#0x00
995 <p>Note that SDCC stores numbers in little-endian format (i.e. lowest order
998 <sect2>Bit-rotation:<label id="bit rotation" >
999 <p>A special case of the bit-shift operation is bit rotation, SDCC recognizes
1000 the following expression to be a left bit-rotation.
1003 <verb>unsigned char i;
1005 i = ( ( i << 1) | ( i >> 7));
1008 <p>will generate the following code.
1015 <p>SDCC uses pattern matching on the parse tree to determine this operation
1016 .Variations of this case will also be recognized as bit-rotation i.e i = ((i
1017 >> 7) | (i << 1)); /* left-bit rotation */
1019 <sect1>Highest Order Bit.<label id="Highest Order Bit" >
1020 <p>It is frequently required to obtain the highest order bit of an integral
1021 type (int,long,short or char types). SDCC recognizes the following expression
1022 to yield the highest order bit and generates optimized code for it.
1031 = (gint >> 15) & 1;
1035 <p>Will generate the following code.
1040 62 mov a,(_gint + 1)
1046 000F F5*02 66 mov _foo_hob_1_1,a
1048 <p>Variations of this case however will NOT be recognized . It is a standard
1049 C expression , so I heartily recommend this be the only way to get the highest
1050 order bit, (it is portable). Of course it will be recognized even if it is
1051 embedded in other expressions.
1054 <verb>eg.xyz = gint + ((gint >> 15) & 1);
1056 <p>will still be recognized.
1058 <sect1>Peep-hole optimizer.<label id="Peep-Hole" >
1059 <p>The compiler uses a rule based , pattern matching and re-writing mechanism
1060 for peep-hole optimization . It is inspired by 'copt' a peep-hole optimizer
1061 by Christopher W. Fraser (cwfraser@microsoft.com). A default set of rules are
1062 compiled into the compiler, additional rules may be added with the --peep-file
1063 <filename> option. The rule language is best illustrated with examples.
1066 <verb>replace {
1068 mov a,%1 } by { mov %1,a
1071 <p>The above rule will the following assembly sequence
1082 <p>Note: All occurrences of a '%n' ( pattern variable ) must denote
1083 the same string. With the above rule, the assembly sequence
1089 <p>will remain unmodified. Other special case optimizations may be added by
1090 the user (via --peep-file option), eg. some variants of the 8051 MCU allow
1091 only 'AJMP' and 'ACALL' , the following two rules will change all 'LJMP' &
1092 'LCALL' to 'AJMP' & 'ACALL'.
1095 <verb>replace { lcall %1 } by { acall %1 }
1097 replace { ljmp %1 } by { ajmp %1 }
1099 <p>The inline-assembler' code is also passed through the peep hole optimizer,
1100 thus the peephole optimizer can also be used as an assembly level macro expander.
1101 The rules themselves are MCU dependent whereas the rule language infra-structure
1102 is MCU independent. Peephole optimization rules for other MCU can be easily
1103 programmed using the rule language.
1105 <p>The syntax for a rule is as follows ,
1108 <verb>rule := replace [ restart ] '{' <assembly sequence>
1110 '}' by '{' '\n'
1112 <assembly sequence> '\n'
1114 '}' [if <functionName> ] '\n'
1116 sequence> := assembly instruction (each instruction including labels must
1117 be on a separate line).
1119 <p>The optimizer will apply to the rules one by one from the top in the sequence
1120 of their appearance, it will terminate when all rules are exhausted. If the
1121 'restart' option is specified, then the optimizer will start matching the rules
1122 again from the top, this option for a rule is expensive (performance), it is
1123 intended to be used in situations where a transformation will trigger the same
1124 rule again. A good example of this the following rule.
1127 <verb>replace restart {
1129 push %1 } by {
1134 <p>Note that the replace pattern cannot be a blank, but can be a comment line.
1135 Without the 'restart' option only the inner most 'pop' 'push' pair would be
1151 <p>with the 'restart' option the rule will be applied again to the resulting
1152 code and the all the 'pop' 'push' pairs will be eliminated to yield
1158 <p>A conditional function can be attached to a rule. Attaching rules are somewhat
1159 more involved, let me illustrate this with an example.
1162 <verb>replace {
1164 %2:} by {
1167 %2:} if labelInRange
1169 <p>The optimizer does a look-up of a function name table defined in function
1170 'callFuncByName' in the source file SDCCpeeph.c , with the name 'labelInRange',
1171 if it finds a corresponding entry the function is called. Note there can be
1172 no parameters specified for these functions, in this case the use of '%5'
1173 is crucial, since the function labelInRange expects to find the label in that
1174 particular variable (the hash table containing the variable bindings is passed
1175 as a parameter). If you want to code more such functions , take a close look
1176 at the function labelInRange and the calling mechanism in source file SDCCpeeph.c.
1177 I know this whole thing is a little kludgey , may be some day we will have
1178 some better means. If you are looking at this file, you will also see the default
1179 rules that are compiled into the compiler, you can your own rules in the default
1180 set there if you get tired of specifying the --peep-file option.
1182 <sect>Pointers<label id="Pointers" >
1183 <p>SDCC allows (via language extensions) pointers to explicitly point to any
1184 of the memory spaces of the 8051. In addition to the explicit pointers, the
1185 compiler also allows a _generic class of pointers which can be used to point
1186 to any of the memory spaces.
1188 <p>Pointer declaration examples.
1191 <verb>/* pointer physically in xternal ram pointing to object in internal ram
1193 data unsigned char * xdata p;
1194 /* pointer physically in code rom pointing to data in xdata space */
1196 unsigned char * code p;
1197 /* pointer physically in code space pointing to data in code space */
1199 unsigned char * code p;
1201 /* the folowing is a generic pointer physically located
1205 <p>Well you get the idea. For compatibility with the previous version of the
1206 compiler, the following syntax for pointer declaration is also supported. Note
1207 the above examples will be portable to other commercially available compilers.
1210 <verb>unsigned char _xdata *ucxdp; /* pointer to data in external ram */
1212 char _data *ucdp ; /* pointer to data in internal ram */
1214 *uccp ; /* pointer to data in R/O code space */
1215 unsigned char _idata *uccp;
1216 /* pointer to upper 128 bytes of ram */
1218 <p>All unqualified pointers are treated as 3 - byte '_generic' pointers. These
1219 type of pointers can also to be explicitly declared.
1222 <verb>unsigned char _generic *ucgp;
1224 <p>The highest order byte of the generic pointers contains the data space
1225 information. Assembler support routines are called whenever data is stored
1226 or retrieved using _generic pointers. These are useful for developing reusable
1227 library routines. Explicitly specifying the pointer type will generate the
1228 most efficient code. Pointers declared using a mixture of OLD/NEW style could
1229 have unpredictable results.
1231 <sect>Parameters & Local Variables<label id="Auto Variables" >
1232 <p>Automatic (local) variables and parameters to functions can either be placed
1233 on the stack or in data-space. The default action of the compiler is to place
1234 these variables in the internal RAM ( for small model) or external RAM (for
1235 Large model). They can be placed on the stack either by using the --stack-auto
1236 compiler option or by using the 'reentrant' keyword in the function declaration.
1241 <verb>unsigned short foo( short i) reentrant {
1245 <p>Note that when the parameters & local variables are declared in the
1246 internal/external ram the functions are non-reentrant. Since stack space on
1247 8051 is limited the 'reentrant' keyword or the --stack-auto option should be
1248 used sparingly. Note the reentrant keyword just means that the parameters &
1249 local variables will be allocated to the stack, it DOES NOT mean that the function
1250 is register bank independent.
1252 <p>When compiled with the default option (i.e. non-reentrant ), local variables
1253 can be assigned storage classes and absolute addresses.
1258 <verb>unsigned short foo() {
1259 xdata unsigned short i;
1262 data at 0x31 unsiged short j;
1266 <p>In the above example the variable i will be allocated in the external ram,
1267 bvar in bit addressable space and j in internal ram. When compiled with the
1268 --stack-auto or when a function is declared as 'reentrant' local variables
1269 cannot be assigned storage classes or absolute addresses.
1271 <p>Parameters however are not allowed any storage class, (storage classes
1272 for parameters will be ignored), their allocation is governed by the memory
1273 model in use , and the reentrancy options.
1275 <sect1>Overlaying<label id="Overlaying" >
1276 <p>For non-reentrant functions SDCC will try to reduce internal ram space
1277 usage by overlaying parameters and local variables of a function (if possible).
1278 Parameters and local variables of a function will be allocated to an overlayable
1279 segment if the function has no other function calls and the function is non-reentrant
1280 and the memory model is small. If an explicit storage class is specified for
1281 a local variable , it will NOT be overplayed.
1283 <p>Note that the compiler (not the linkage editor) makes the decision for
1284 overlaying the data items. Functions that are called from an interrupt service
1285 routine should be preceded by a #pragma NOOVERLAY if they are not reentrant
1286 Along the same lines the compiler does not do any processing with the inline
1287 assembler code so the compiler might incorrectly assign local variables and
1288 parameters of a function into the overlay segment if the only function call
1289 from a function is from inline assembler code, it is safe to use the #pragma
1290 NOOVERLAY for functions which call other functions using inline assembler code.
1292 <p>Parameters and Local variables of functions that contain 16 or 32 bit multiplication
1293 or division will NOT be overlayed since these are implemented using external
1299 <verb>#pragma SAVE
1300 #pragma NOOVERLAY
1301 void set_error( unsigned short
1308 () interrupt 2 using 1
1315 <p>In the above example the parameter errcd for the function set_error would
1316 be assigned to the overlayable segment (if the #pragma NOOVERLAY was not
1317 present) , this could cause unpredictable runtime behavior. The pragma NOOVERLAY
1318 ensures that the parameters and local variables for the function are NOT overlayed.
1320 <sect>critical Functions.<label id="Critical" >
1321 <p>A special keyword may be associated with a function declaring it as 'critical'.
1322 SDCC will generate code to disable all interrupts upon entry to a critical
1323 function and enable them back before returning . Note that nesting critical
1324 functions may cause unpredictable results.
1329 <verb>int foo () critical
1335 <p>The critical attribute maybe used with other attributes like reentrant.
1337 <sect>Absolute addressing.<label id="Absolute Addressing" >
1338 <p>Data items can be assigned an absolute address with the at <address>
1339 keyword, in addition to a storage class.
1342 <verb>eg. xdata at 0x8000 unsigned char PORTA_8255 ;
1344 <p>In the above example the PORTA_8255 will be allocated to the location 0x8000
1345 of the external ram.
1347 <p>Note that is this feature is provided to give the programmer access to
1348 memory mapped devices attached to the controller. The compiler does not actually
1349 reserve any space for variables declared in this way (they are implemented
1350 with an equate in the assembler), thus it is left to the programmer to make
1351 sure there are no overlaps with other variables that are declared without the
1352 absolute address, the assembler listing file (.lst) and the linker output files
1353 (<filename>.rst) and (<filename>.map) are a good places to look
1356 <p>Absolute address can be specified for variables in all storage classes.
1359 <verb>eg.bit at 0x02 bvar;
1361 <p>The above example will allocate the variable at offset 0x02 in the bit-addressable
1362 space. There is no real advantage to assigning absolute addresses to variables
1363 in this manner , unless you want strict control over all the variables allocated.
1365 <sect>Interrupt Service Routines<label id="Interrupt Service Rouines" >
1366 <p>SDCC allows interrupt service routines to be coded in C, with some extended
1370 <verb>void timer_isr (void) interrupt 2 using 1
1375 <p>The number following the 'interrupt' keyword is the interrupt number this
1376 routine will service. The compiler will insert a call to this routine in the
1377 interrupt vector table for the interrupt number specified. The 'using' keyword
1378 is used to tell the compiler to use the specified register bank (8051 specific)
1379 when generating code for this function. Note that when some function is called
1380 from an interrupt service routine it should be preceded by a #pragma NOOVERLAY
1381 (if it is not reentrant) . A special note here, int (16 bit) and long (32 bit)
1382 integer division, multiplication & modulus operations are implemented using
1383 external support routines developed in ANSI-C, if an interrupt service routine
1384 needs to do any of these operations then the support routines (as mentioned
1385 in a following section) will have to recompiled using the --stack-auto option
1386 and the source file will need to be compiled using the --int-long-rent compiler
1389 <p>If you have multiple source files in your project, interrupt service routines
1390 can be present in any of them, but a prototype of the isr MUST be present in
1391 the file that contains the function 'main'.
1393 <p>Interrupt Numbers and the corresponding address & descriptions for
1394 the Standard 8051 are listed below. SDCC will automatically adjust the interrupt
1395 vector table to the maximum interrupt number specified.
1398 <verb>Interrupt # Description Vector Address
1408 <p>If the interrupt service routine is defined without a register bank or
1409 with register bank 0 (using 0), the compiler will save the registers used by
1410 itself on the stack (upon entry and restore them at exit), however if such
1411 an interrupt service routine calls another function then the entire register
1412 bank will be saved on the stack. This scheme may be advantageous for small
1413 interrupt service routines which have low register usage.
1415 <p>If the interrupt service routine is defined to be using a specific register
1416 bank then only "a","b" & "dptr" are save and restored, if such an interrupt service
1417 routine calls another function (using another register bank) then the entire
1418 register bank of the called function will be saved on the stack. This scheme
1419 is recommended for larger interrupt service routines.
1421 <p>Calling other functions from an interrupt service routine is not recommended
1422 avoid it if possible.
1424 <sect>Startup Code<label id="Startup" >
1425 <p>The compiler inserts a jump to the C routine <bf>_sdcc__external__startup()
1426 </bf>at the start of the CODE area. This routine can be found in the file <bf>SDCCDIR/sdcc51lib/_startup.c</bf>
1427 , by default this routine returns 0, if this routine returns a non-zero value
1428 , the static & global variable initialization will be skipped and the function
1429 main will be invoked, other wise static & global variables will be initialized
1430 before the function main is invoked.
1432 <sect>Inline assembler code.<label id="Inline" >
1433 <p>SDCC allows the use of in-line assembler with a few restriction as regards
1434 labels. All labels defined within inline assembler code HAS TO BE of the form
1435 nnnnn$ where nnnn is a number less than 100 (which implies a limit of
1436 utmost 100 inline assembler labels per function). It is strongly recommended
1437 that each assembly instruction (including labels) be placed in a separate line
1438 ( as the example shows). When the <bf>--peep-asm</bf> command line option is used, the
1439 inline assembler code will be passed through the peephole optimizer, this might
1440 cause some unexpected changes in the inline assembler code, please go throught
1441 the peephole optimizer rules defined in file 'SDCCpeeph.def' carefully before
1448 djnz b,00001$
1452 <p>The inline assembler code can contain any valid code understood by the
1453 assembler (this includes any assembler directives and comment lines ) . The
1454 compiler does not do any validation of the code within the _asm ... _endasm;
1457 <p>Inline assembler code cannot reference any C-Labels however it can reference
1458 labels defined by the inline assembler.
1461 <verb>egfoo() {
1462 ... /* some c code */
1464 ; some assembler code
1468 ... /* some more c code */
1470 assembler cannot reference this label */
1472 $0003: ;label (can
1473 be reference by inline assembler only)
1478 <p>In other words inline assembly code can access labels defined in inline
1479 assembly. The same goes the other way, ie. labels defines in inline assembly
1480 CANNOT be accessed by C statements.
1482 <sect>int (16 bit) and long (32 bit ) support.<label id="int and long" >
1483 <p>For signed & unsigned int (16 bit) and long (32 bit) variables, division,
1484 multiplication and modulus operations are implemented by support routines.
1485 These support routines are all developed in ANSI-C to facilitate porting to
1486 other MCUs. The following files contain the described routine, all of them
1487 can be found in the directory SDCCDIR/sdcc51lib
1491 <item>_mulsint.c - signed 16 bit multiplication (calls _muluint)
1492 <item>_muluint.c - unsigned 16 bit multiplication
1493 <item>_divsint.c - signed 16 bit division (calls _divuint)
1494 <item>_divuint.c - unsigned 16 bit division.
1495 <item>_modsint.c - signed 16 bit modulus (call _moduint)
1496 <item>_moduint.c - unsigned 16 bit modulus.
1497 <item>_mulslong.c - signed 32 bit multiplication (calls _mululong)
1498 <item>_mululong.c - unsigned32 bit multiplication.
1499 <item>_divslong.c - signed 32 division (calls _divulong)
1500 <item>_divulong.c - unsigned 32 division.
1501 <item>_modslong.c - signed 32 bit modulus (calls _modulong).
1502 <item>_modulong.c - unsigned 32 bit modulus.
1504 <p>All these routines are compiled as non-reentrant and small model. Since
1505 they are compiled as non-reentrant, interrupt service routines should not do
1506 any of the above operations, if this unavoidable then the above routines will
1507 need to ne compiled with the --stack-auto option, after which the source program
1508 will have to be compiled with --int-long-rent option.
1510 <sect>Floating point support<label id="Float" >
1511 <p>SDCC supports IEEE (single precision 4bytes) floating point numbers.The
1512 floating point support routines are derived from gcc's floatlib.c and consists
1513 of the following routines.
1517 <item>_fsadd.c - add floating point numbers.
1518 <item>_fssub.c - subtract floating point numbers
1519 <item>_fsdiv.c - divide floating point numbers
1520 <item>_fsmul.c - multiply floating point numbers
1521 <item>_fs2uchar.c - convert floating point to unsigned char
1522 <item>_fs2char.c - convert floating point to signed char.
1523 <item>_fs2uint.c - convert floating point to unsigned int.
1524 <item>_fs2int.c - convert floating point to signed int.
1525 <item>_fs2ulong.c - convert floating point to unsigned long.
1526 <item>_fs2long.c - convert floating point to signed long.
1527 <item>_uchar2fs.c - convert unsigned char to floating point
1528 <item>_char2fs.c - convert char to floating point number
1529 <item>_uint2fs.c - convert unsigned int to floating point
1530 <item>_int2fs.c - convert int to floating point numbers
1531 <item>_ulong2fs.c - convert unsigned long to floating point number
1532 <item>_long2fs.c - convert long to floating point number.
1534 <p>Note if all these routines are used simultaneously the data space might
1535 overflow. For serious floating point usage it is strongly recommended that
1536 the Large model be used (in which case the floating point routines mentioned
1537 above will need to recompiled with the --model-Large option)
1539 <sect>Memory Models<label id="Memory Models" >
1540 <p>SDCC allows two memory models, modules compiled with different memory models
1541 should be combined together, the results would be unpredictable. The support
1542 routines supplied with the compiler are compiled in small-model by default,
1543 and will need to be recompiled using the large model if the large model is
1544 used. In general the use of the large model is discouraged.
1546 <p>When the large model is used all variables declared without a storage class
1547 will be allocated into the external ram, this includes all parameters and local
1548 variables (for non-reentrant functions). When the small model is used variables
1549 without storage class are allocated in the internal ram.
1551 <p>Judicious usage of the processor specific storage classes and the 'reentrant'
1552 function type will yield much more efficient code, than using the large-model.
1553 Several optimizations are disabled when the program is compiled using the large
1554 model, it is therefore strongly recommdended that the small model be used unless
1555 absolutely required.
1557 <sect>Flat 24 bit addressing model.<label id="--model-flat24" >
1558 <p>This option generates code for the 24 bit contiguous addressing mode of
1559 the Dallas DS80C390 part. In this mode, up to four meg of external RAM or code
1560 space can be directly addressed. See the data sheets at www.dalsemi.com for
1561 further information on this part.
1563 <p>Note that the compiler does not generate any code to place the processor
1564 into this mode (it defaults to 8051 compatible mode). Boot loader or similar
1565 code must ensure that the processor is in 24 bit contiguous addressing mode
1566 before calling the SDCC startup code.
1568 <p>Like the --model-large option, variables will by default be placed into
1569 the XDATA segment. However, a current limitation is that the compiler will
1570 spill variables into the DATA segment when it runs out of registers. This means
1571 that compiling complex code can rapidly fill up the DATA segment. This limitation
1572 is being worked on, and should be addressed in the next release of sdcc.
1574 <p>Segments may be placed anywhere in the 4 meg address space using the usual
1575 --*-loc options. Note that if any segments are located above 64K, the -r flag
1576 must be passed to the linker to generate the proper segment relocations, and
1577 the Intel HEX output format must be used. The -r flag can be passed to the
1578 linker by using the option -Wl-r on the sdcc command line.
1582 <p>This option generates code for the 10 bit stack mode of the Dallas DS80C390
1583 part. In this mode, the stack is located in the lower 1K of the internal RAM,
1584 which is mapped to 0x400000.
1586 <p>With this option, sdcc will generate the proper addressing for stack variables.
1588 <p>Note that the support is incomplete, since it still uses a single byte
1589 as the stack pointer. This means that only the lower 256 bytes of the potential
1590 1K stack space can actually be used. However, this does allow you to reclaim
1591 the precious 256 bytes of low RAM for use for the DATA and IDATA segments.
1593 <p>The compiler will not generate any code to put the processor into 10 bit
1594 stack mode. It is important to ensure that the processor is in this mode before
1595 calling any re-entrant functions compiled with this option.
1597 <p>In principle, this should work with the --stack-auto option, but that has
1598 not been tested. It is incompatible with the --xstack option. It also only
1599 makes sense if the processor is in 24 bit contiguous addressing mode (see the
1600 --model-flat24 option).
1602 <sect>Defines created by the compiler.<label id="Defines." >
1603 <p>The compiler creates the following #defines .
1607 <item>SDCC - this Symbol is always defined.
1608 <item>SDCC_STACK_AUTO - this symbol is defined when --stack-auto option is used.
1609 <item>SDCC_MODEL_SMALL - when small model is used.
1610 <item>SDCC_MODEL_LARGE - when --model-large is used.
1611 <item>SDCC_USE_XSTACK - when --xstack option is used.
1613 <sect>Pragmas<label id="Pragmaa" >
1614 <p>SDCC supports the following #pragma directives. This directives are
1615 applicable only at a function level.
1619 <item><bf>SAVE</bf><label id="pragma save" > - this will save all the current options .
1620 <item><bf>RESTORE </bf><label id="pragma restore" >- will restore the saved options from the last save. Note that
1621 SAVES & RESTOREs cannot be nested. SDCC uses the same buffer to save the
1622 options each time a SAVE is called.
1623 <item><bf>NOGCSE</bf><label id="pragma nogcse" > - will stop global subexpression elimination.
1624 <item><bf>NOINDUCTION</bf> <label id="pragma noinduction" >- will stop loop induction optimizations .
1625 <item><bf>NOJTBOUND</bf> <label id="pragma nojtbound" >- will not generate code for boundary value checking , when switch
1626 statements are turned into jump-tables.
1627 <item><bf>NOOVERLAY </bf><label id="pragma nooverlay" >- the compiler will not overlay the parameters and local variables
1629 <item><bf>NOLOOPREVERSE</bf> <label id="pragma noloopreverse" >- Will not do loop reversal optimization
1630 <item><bf>EXCLUDE NONE | {acc[,b[,dpl[,dph]]]</bf><label id="pragma exclude" >
1631 - The exclude pragma disables generation of pair of push/pop instruction in
1632 ISR function (using interrupt keyword). The directive should be placed immediately
1633 before the ISR function definition and it affects ALL ISR functions following
1634 it. To enable the normal register saving for ISR functions use "#pragma
1636 <item><bf>CALLEE-SAVES function1[,function2[,function3...]]</bf><label id="pragma callee-saves" > -
1637 The compiler by default uses a caller saves convention for register saving
1638 across function calls, however this can cause unneccessary register pushing
1639 & popping when calling small functions from larger functions. This option
1640 can be used to switch the register saving convention for the function names
1641 specified. The compiler will not save registers when calling these functions,
1642 extra code will be generated at the entry & exit for these functions to
1643 save & restore the registers used by these functions, this can SUBSTANTIALLY
1644 reduce code & improve run time performance of the generated code. In future
1645 the compiler (with interprocedural analysis) will be able to determine the
1646 appropriate scheme to use for each function call. If --callee-saves<ref id="--callee-saves" name="" > command
1647 line option is used, the function names specified in #pragma CALLEE-SAVES
1648 is appended to the list of functions specified inthe command line.
1650 <p>The pragma's are intended to be used to turn-off certain optimizations
1651 which might cause the compiler to generate extra stack / data space to store
1652 compiler generated temporary variables. This usually happens in large functions.
1653 Pragma directives should be used as shown in the following example, they are
1654 used to control options & optimizations for a given function; pragmas should
1655 be placed before and/or after a function, placing pragma's inside a function
1656 body could have unpredictable results.
1659 <verb>eg#pragma SAVE /* save the current settings */
1661 /* turnoff global subexpression elimination */
1662 #pragma NOINDUCTION /*
1663 turn off induction optimizations */
1671 #pragma RESTORE /* turn the optimizations back
1674 <p>The compiler will generate a warning message when extra space is allocated.
1675 It is strongly recommended that the SAVE and RESTORE pragma's be used when
1676 changing options for a function.
1678 <sect>Library routines.<label id="Library" >
1679 <p>The following library routines are provided for your convenience.
1681 <p><bf>stdio.h </bf>- Contains the following functions printf & sprintf these routines
1682 are developed by Martijn van Balen <balen@natlab.research.philips.com>.
1686 <verb>%[flags][width][b|B|l|L]type flags: - left justify output in specified field width
1688 + prefix output with +/- sign if output is signed
1690 space prefix output with a blank if it's a signed
1692 width: specifies minimum number of characters
1693 outputted for numbers
1696 - For numbers, spaces are added on the left when needed.
1698 If width starts with a zero character, zeroes and used
1701 - For strings, spaces are are
1702 added on the left or right (when
1707 (used by d, u, o, x, X)
1708 l/L: long argument (used by d,
1710 type: d decimal number
1712 unsigned decimal number
1713 o unsigned octal number
1715 x unsigned hexadecimal number (0-9, a-f)
1717 unsigned hexadecimal number (0-9, A-F)
1720 s string (generic pointer)
1722 generic pointer (I:data/idata, C:code, X:xdata, P:paged)
1724 f float (still to be implemented)
1726 <p>Also contains a very simple version of printf (<bf>printf_small</bf>). This simplified
1727 version of printf supports only the following formats.
1730 <verb>format output type argument-type <bf>
1731 </bf>%d decimal
1733 %ld decimal long
1734 %hd decimal short/char
1736 %x hexadecimal int
1737 %lx hexadecimal long
1739 %hx hexadecimal short/char
1742 %lo octal long
1743 %ho octal short/char
1745 %c character char/short
1746 %s character _generic
1748 <p><tt>The routine is </tt><tt><bf>very stack intesive </bf>, --stack-after-data parameter should
1749 be used when using this routine, the routine also takes about 1K of code space
1750 .It also expects an external function named putchar(char ) to be present (this
1751 can be changed). When using the %s format the string / pointer should
1752 be cast to a generic pointer. eg.</tt>
1754 <verb>printf_small("my str %s, my int %d\n",(char _generic *)mystr,myint);
1759 <item><bf>stdarg.h </bf>- contains definition for the following macros to be used for
1760 variable parameter list, note that a function can have a variable parameter
1761 list if and only if it is 'reentrant'
1762 <p>va_list, va_start, va_arg, va_end.
1764 <item><bf>setjmp.h </bf>- contains defintion for ANSI<bf> setjmp </bf>& <bf>longjmp</bf> routines. Note
1765 in this case setjmp & longjmp can be used between functions executing within
1766 the same register bank, if long jmp is executed from a function that is using
1767 a different register bank from the function issuing the setjmp function, the
1768 results may be unpredictable. The jump buffer requires 3 bytes of data (the
1769 stack pointer & a 16 byte return address), and can be placed in any address
1771 <item><bf>stdlib.h</bf> - contains the following functions.
1774 <item><bf>string.h </bf>- contains the following functions.
1775 <p>strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn,
1776 strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.
1778 <item><bf>ctype.h</bf> - contains the following routines.
1779 <p>iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
1780 isxdigit, isalnum, isalpha.
1782 <item><bf>malloc.h</bf> - The malloc routines are developed by Dmitry S. Obukhov (dso@usa.net).
1783 These routines will allocate memory from the external ram. Here is a description
1784 on how to use them (as described by the author).
1786 // #define DYNAMIC_MEMORY_SIZE 0x2000
1789 // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
1791 // unsigned char xdata * current_buffer;
1798 init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
1800 //Now it's possible to use malloc.
1806 <item><bf>serial.h</bf> - Serial IO routines are also developed by Dmitry S. Obukhov (dso@usa.net).
1807 These routines are interrupt driven with a 256 byte circular buffer, they also
1808 expect external ram to be present. Please see documentation in file SDCCDIR/sdcc51lib/serial.c
1809 . Note the header file "serial.h" MUST be included in the file containing the
1811 <item><bf>ser.h </bf>- Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.com>
1812 these routines are more compact and faster. Please see documentation in file
1813 SDCCDIR/sdcc51lib/ser.c
1814 <item><bf>ser_ir.h </bf>- Another alternate set of serial routines provided by Josef Wolf
1815 <jw@raven.inka.de> , these routines do not use the external ram.
1816 <item><bf>reg51.h</bf> - contains register definitions for a standard 8051
1817 <item><bf>reg552.h </bf>- contains register definitions for 80C552.
1818 <item><bf>float.h</bf> - contains min, max and other floating point related stuff.
1820 <p>All library routines are compiled as --model-small , they are all non-reentrant,
1821 if you plan to use the large model or want to make these routines reentrant,
1822 then they will have to be recompiled with the appropriate compiler option.
1824 <p>Have not had time to do the more involved routines like printf, will get
1827 <sect>Interfacing with assembly routines.<label id="Interface_asm" >
1828 <sect1>Global registers used for parameter passing.
1829 <p>By default the compiler uses the global registers "DPL,DPH,B,ACC" to pass
1830 the first parameter to a routine, the second parameter onwards is either allocated
1831 on the stack (for reentrant routines or --stack-auto is used) or in the internal
1832 / external ram (depending on the memory model).
1834 <sect2>Assembler routine non-reentrant
1835 <p>In the following example the function<bf> cfunc</bf> calls an assembler routine
1836 <bf>asm_func</bf>, which takes two parameters.
1838 <p>extern int asm_func( unsigned short, unsigned short);
1842 int c_func (unsigned short i, unsigned short j)
1849 return c_func(10,9);
1852 <p>The corresponding assembler function is:-
1855 <verb> .globl _asm_func_PARM_2
1859 _asm_func_PARM_2: .ds 1
1864 add a,_asm_func_PARM_2
1870 <p>Note here that the return values are placed in 'dpl' - One byte return
1871 value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and 'b'
1872 for three byte values (generic pointers) and 'dpl','dph','b' & 'acc' for
1875 <p>The parameter naming convention is <bf>_<function_name>_PARM_<n>,</bf>
1876 where n is the parameter number starting from 1, and counting from the left.
1877 The first parameter is passed in "dpl" for One bye parameter, "dptr" if two bytes,
1878 "b,dptr" for three bytes and "acc,b,dptr" for four bytes, the <tt></tt><tt><bf>varaible name for
1879 the second parameter will be _<function_name>_PARM_2.</bf></tt>
1881 <p>Assemble the assembler routine with the following command.
1884 <verb>asx8051 -losg asmfunc.asm
1886 <p>Then compile and link the assembler routine to the C source file with the
1890 <verb>sdcc cfunc.c asmfunc.rel
1892 <sect2>Assembler routine is reentrant
1893 <p>In this case the second parameter onwards will be passed on the stack ,
1894 the parameters are pushed from right to left i.e. after the call the left most
1895 parameter will be on the top of the stack. Here is an example.
1897 <p>extern int asm_func( unsigned short, unsigned short);
1900 <verb> int c_func (unsigned short i, unsigned short j) reentrant
1903 return asm_func(i,j);
1907 return c_func(10,9);
1911 <p>The corresponding assembler routine is.
1914 <verb> .globl _asm_func
1937 <p>The compiling and linking procedure remains the same, however note the
1938 extra entry & exit linkage required for the assembler code, _bp is the
1939 stack frame pointer and is used to compute the offset into the stack for parameters
1940 and local variables.
1942 <sect1>With --noregparms option.
1943 <p>When the source is compiled with --noregparms option , space is allocated
1944 for each of the parameters passed to a routine.
1946 <sect2>Assembler routine non-reentrant.
1947 <p>In the following example the function<bf> cfunc</bf> calls an assembler routine
1948 <bf>asm_func</bf>, which takes two parameters.
1951 <verb>extern int asm_func( unsigned short, unsigned short);
1952 int c_func (unsigned short i, unsigned short j)
1959 return c_func(10,9);
1962 <p>The corresponding assembler function is:-
1965 <verb> .globl _asm_func_PARM_1
1966 .globl _asm_func_PARM_2
1970 _asm_func_PARM_1: .ds 1
1975 mov a,_asm_func_PARM_1
1977 add a,_asm_func_PARM_2
1983 <p>Note here that the return values are placed in 'dpl' - One byte return
1984 value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and 'b'
1985 for three byte values (generic pointers) and 'dpl','dph','b' & 'acc' for
1988 <p>The parameter naming convention is <bf>_<function_name>_PARM_<n>,</bf>
1989 where n is the parameter number starting from 1, and counting from the left.
1990 i.e. the <tt></tt><tt><bf>left-most parameter name will be _<function_name>_PARM_1.
1993 <p>Assemble the assembler routine with the following command.
1996 <verb>asx8051 -losg asmfunc.asm
1998 <p>Then compile and link the assembler routine to the C source file with the
2002 <verb>sdcc cfunc.c asmfunc.rel
2004 <sect2>Assembler routine is reentrant.
2005 <p>In this case the parameters will be passed on the stack , the parameters
2006 are pushed from right to left i.e. after the call the left most parameter will
2007 be on the top of the stack. Here is an example.
2009 <p>extern int asm_func( unsigned short, unsigned short);
2012 <verb> int c_func (unsigned short i, unsigned short j) reentrant
2015 return asm_func(i,j);
2019 return c_func(10,9);
2023 <p>The corresponding assembler routine is.
2026 <verb> .globl _asm_func
2050 <p>The compiling and linking procedure remains the same, however note the
2051 extra entry & exit linkage required for the assembler code, _bp is the
2052 stack frame pointer and is used to compute the offset into the stack for parameters
2053 and local variables.
2055 <sect>External Stack.<label id="xstack" >
2056 <p>The external stack is located at the start of the external ram segment
2057 , and is 256 bytes in size. When --xstack option is used to compile the program
2058 , the parameters and local variables of all reentrant functions are allocated
2059 in this area. This option is provided for programs with large stack space requirements.
2060 When used with the --stack-auto option, all parameters and local variables
2061 are allocated on the external stack (note support libraries will need to be
2062 recompiled with the same options).
2064 <p>The compiler outputs the higher order address byte of the external ram
2065 segment into PORT P2, therefore when using the External Stack option, this
2066 port MAY NOT be used by the application program.
2068 <sect>ANSI-Compliance.<label id="ANSI_Compliance" >
2069 <p>Deviations from the compliancy.
2073 <item>functions are not always reentrant.
2074 <item>structures cannot be assigned values directly, cannot be passed as function
2075 parameters or assigned to each other and cannot be a return value from a function.
2080 <verb>struct s { ... };
2086 s2 ; /* is invalid in SDCC although allowed in ANSI */
2088 }struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
2093 return rets;/* is invalid in SDCC although
2099 <item>'long long' (64 bit integers) not supported.
2100 <item>'double' precision floating point not supported.
2101 <item>integral promotions are suppressed. What does this mean ? The compiler
2102 will not implicitly promote an integer expression to a higher order integer,
2103 exception is an assignment or parameter passing.
2104 <item>No support for setjmp and longjmp (for now).
2105 <item>Old K&R style function declarations are NOT allowed.
2108 <verb>foo( i,j) /* this old style of function declarations */
2110 valid in ANSI .. not valid in SDCC */
2117 <item>functions declared as pointers must be dereferenced during the call.
2123 /* has to be called like this */
2124 (*foo)();/* ansi standard
2125 allows calls to be made like 'foo()' */
2127 <sect>Cyclomatic Complexity<label id="Cyclomatic" >
2128 <p>Cyclomatic complexity of a function is defined as the number of independent
2129 paths the program can take during execution of the function. This is an important
2130 number since it defines the number test cases you have to generate to validate
2131 the function . The accepted industry standard for complexity number is 10,
2132 if the cyclomatic complexity reported by SDCC exceeds 10 you should think about
2133 simplification of the function logic.
2135 <p>Note that the complexity level is not related to the number of lines of
2136 code in a function. Large functions can have low complexity, and small functions
2137 can have large complexity levels. SDCC uses the following formula to compute
2141 <verb>complexity = (number of edges in control flow graph) -
2143 of nodes in control flow graph) + 2;
2145 <p>Having said that the industry standard is 10, you should be aware that
2146 in some cases it may unavoidable to have a complexity level of less than 10.
2147 For example if you have switch statement with more than 10 case labels, each
2148 case label adds one to the complexity level. The complexity level is by no
2149 means an absolute measure of the algorithmic complexity of the function, it
2150 does however provide a good starting point for which functions you might look
2151 at for further optimization.
2153 <sect>TIPS<label id="Tips" >
2154 <p>Here are a few guide-lines that will help the compiler generate more efficient
2155 code, some of the tips are specific to this compiler others are generally good
2156 programming practice.
2160 <item>Use the smallest data type to represent your data-value. If it is known
2161 in advance that the value is going to be less than 256 then use a 'short' or
2162 'char' instead of an 'int'.
2163 <item>Use unsigned when it is known in advance that the value is not going to
2164 be negative. This helps especially if you are doing division or multiplication.
2165 <item>NEVER jump into a LOOP.
2166 <item>Declare the variables to be local whenever possible, especially loop control
2167 variables (induction).
2168 <item>Since the compiler does not do implicit integral promotion, the programmer
2169 should do an explicit cast when integral promotion is required.
2170 <item>Reducing the size of division , multiplication & modulus operations
2171 can reduce code size substantially. Take the following code for example.
2172 <verb>foobar( unsigned int p1, unsigned char ch)
2179 <p>For the modulus operation the variable ch will be promoted to unsigned
2180 int first then the modulus operation will be performed (this will lead to a
2181 call to a support routine). If the code is changed to
2183 <verb>foobar( unsigned int p1, unsigned char ch)
2186 = (unsigned char)p1 % ch ;
2190 <p>It would substantially reduce the code generated (future versions of the
2191 compiler will be smart enough to detect such optimization oppurtunities).
2194 <p><bf>Notes from an USER ( Trefor@magera.freeserve.co.uk )</bf>
2196 <p>The 8051 family of micro controller have a minimum of 128 bytes of internal
2197 memory which is structured as follows
2199 <p>- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
2202 <p>- Bytes 20-2F - 16 bytes to hold 128 bit variables and
2204 <p>- Bytes 30-7F - 60 bytes for general purpose use.
2206 <p>Normally the SDCC compiler will only utilise the first bank of registers,
2207 but it is possible to specify that other banks of registers should be used
2208 in interrupt routines. By default, the compiler will place the stack after
2209 the last bank of used registers, i.e. if the first 2 banks of registers are
2210 used, it will position the base of the internal stack at address 16 (0X10).
2211 This implies that as the stack grows, it will use up the remaining register
2212 banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for general
2215 <p>By default, the compiler uses the 60 general purpose bytes to hold &dquot;near
2216 data&dquot;. The compiler/optimiser may also declare some Local Variables in
2217 this area to hold local data.
2219 <p>If any of the 128 bit variables are used, or near data is being used then
2220 care needs to be taken to ensure that the stack does not grow so much that
2221 it starts to over write either your bit variables or &dquot;near data&dquot;.
2222 There is no runtime checking to prevent this from happening.
2224 <p>The amount of stack being used is affected by the use of the &dquot;internal
2225 stack&dquot; to save registers before a subroutine call is made, - --stack-auto
2226 will declare parameters and local variables on the stack - the number of nested
2229 <p>If you detect that the stack is over writing you data, then the following
2230 can be done. --xstack will cause an external stack to be used for saving registers
2231 and (if --stack-auto is being used) storing parameters and local variables.
2232 However this will produce more and code which will be slower to execute.
2234 <p>--stack-loc will allow you specify the start of the stack, i.e. you could
2235 start it after any data in the general purpose area. However this may waste
2236 the memory not used by the register banks and if the size of the &dquot;near
2237 data&dquot; increases, it may creep into the bottom of the stack.
2239 <p>--stack-after-data, similar to the --stack-loc, but it automatically places
2240 the stack after the end of the &dquot;near data&dquot;. Again this could waste
2241 any spare register space.
2243 <p>--data-loc allows you to specify the start address of the near data. This
2244 could be used to move the &dquot;near data&dquot; further away from the stack
2245 giving it more room to grow. This will only work if no bit variables are being
2246 used and the stack can grow to use the bit variable space.
2250 <p>If you find that the stack is over writing your bit variables or &dquot;near
2251 data&dquot; then the approach which best utilised the internal memory is to
2252 position the &dquot;near data&dquot; after the last bank of used registers
2253 or, if you use bit variables, after the last bit variable by using the --data-loc,
2254 e.g. if two register banks are being used and no data variables, --data-loc
2255 16, and - use the --stack-after-data option.
2257 <p>If bit variables are being used, another method would be to try and squeeze
2258 the data area in the unused register banks if it will fit, and start the stack
2259 after the last bit variable.
2261 <sect>Retargetting for other MCUs.<label id="Retargetting" >
2262 <p>The issues for retargetting the compiler are far too numerous to be covered
2263 by this document. What follows is a brief description of each of the seven
2264 phases of the compiler and its MCU dependency.
2268 <item>Parsing the source and building the annotated parse tree. This phase is
2269 largely MCU independent (except for the language extensions). Syntax &
2270 semantic checks are also done in this phase , along with some initial optimizations
2271 like back patching labels and the pattern matching optimizations like bit-rotation
2273 <item>The second phase involves generating an intermediate code which can be
2274 easy manipulated during the later phases. This phase is entirely MCU independent.
2275 The intermediate code generation assumes the target machine has unlimited number
2276 of registers, and designates them with the name iTemp. The compiler can be
2277 made to dump a human readable form of the code generated by using the --dumpraw
2279 <item>This phase does the bulk of the standard optimizations and is also MCU
2280 independent. This phase can be broken down into several sub-phases.
2282 <item>Break down intermediate code (iCode) into basic blocks.
2283 <item>Do control flow & data flow analysis on the basic blocks.
2284 <item>Do local common subexpression elimination, then global subexpression elimination
2285 <item>dead code elimination
2286 <item>loop optimizations
2287 <item>if loop optimizations caused any changes then do 'global subexpression
2288 elimination' and 'dead code elimination' again.
2290 <item>This phase determines the live-ranges; by live range I mean those iTemp
2291 variables defined by the compiler that still survive after all the optimizations.
2292 Live range analysis is essential for register allocation, since these computation
2293 determines which of these iTemps will be assigned to registers, and for how
2295 <item>Phase five is register allocation. There are two parts to this process
2298 <item>The first part I call 'register packing' (for lack of a better term) .
2299 In this case several MCU specific expression folding is done to reduce register
2301 <item>The second part is more MCU independent and deals with allocating registers
2302 to the remaining live ranges. A lot of MCU specific code does creep into this
2303 phase because of the limited number of index registers available in the 8051.
2305 <item>The Code generation phase is (unhappily), entirely MCU dependent and very
2306 little (if any at all) of this code can be reused for other MCU. However the
2307 scheme for allocating a homogenized assembler operand for each iCode operand
2309 <item>As mentioned in the optimization section the peep-hole optimizer is rule
2310 based system, which can reprogrammed for other MCUs.
2312 <sect>Reporting Bugs<label id="Bugs" >
2313 <p>Shoot of an email to 'sandeep.dutta@usa.net', as a matter of principle
2314 I always reply to all email's sent to me. Bugs will be fixed ASAP. When reporting
2315 a bug , it is useful to include a small snippet of code that is causing the
2316 problem, if possible compile your program with the --dumpall option and send
2317 the dump files along with the bug report.
2319 <sect>SDCDB - Source level debugger.
2320 <p>SDCC is distributed with a source level debugger. The debugger uses a command
2321 line interface, the command repertoire of the debugger has been kept as close
2322 to gdb ( the GNU debugger) as possible. The configuration and build process
2323 of the compiler see Installation <ref id="Installation" name="" > also builds and installs the debugger in
2324 the target directory specified during configuration. The debugger allows you
2325 debug BOTH at the C source and at the ASM source level.
2327 <sect1>Compiling for debugging.
2328 <p>The --debug option must be specified for all files for which debug information
2329 is to be generated. The complier generates a .cdb file for each of these files.
2330 The linker updates the .cdb file with the address information. This .cdb is
2331 used by the debugger .
2333 <sect1>How the debugger works.
2334 <p>When the --debug option is specified the compiler generates extra symbol
2335 information some of which are put into the the assembler source and some are
2336 put into the .cdb file, the linker updates the .cdb file with the address information
2337 for the symbols. The debugger reads the symbolic information generated by the
2338 compiler & the address information generated by the linker. It uses the
2339 SIMULATOR (Daniel's S51) to execute the program, the program execution is controlled
2340 by the debugger. When a command is issued for the debugger, it translates it
2341 into appropriate commands for the simulator .
2343 <sect1>Starting the debugger.
2344 <p>The debugger can be started using the following command line. (Assume the
2345 file you are debugging has
2347 <p>the file name foo).
2352 <p>The debugger will look for the following files.
2356 <item>foo.c - the source file.
2357 <item>foo.cdb - the debugger symbol information file.
2358 <item>foo.ihx - the intel hex format object file.
2360 <sect1>Command line options.
2363 <item>--directory=<source file directory> this option can used to specify
2364 the directory search list. The debugger will look into the directory list specified
2365 for source , cdb & ihx files. The items in the directory list must be separated
2366 by ':' , e.g. if the source files can be in the directories /home/src1 and
2367 /home/src2, the --directory option should be --directory=/home/src1:/home/src2
2368 . Note there can be no spaces in the option.
2369 <item>-cd <directory> - change to the <directory>.
2370 <item>-fullname - used by GUI front ends.
2371 <item>-cpu <cpu-type> - this argument is passed to the simulator please
2372 see the simulator docs for details.
2373 <item>-X <Clock frequency > this options is passed to the simulator please
2374 see simulator docs for details.
2375 <item>-s <serial port file> passed to simulator see simulator docs for
2377 <item>-S <serial in,out> passed to simulator see simulator docs for details.
2379 <sect1>Debugger Commands.
2380 <p>As mention earlier the command interface for the debugger has been deliberately
2381 kept as close the GNU debugger gdb , as possible, this will help int integration
2382 with existing graphical user interfaces (like ddd, xxgdb or xemacs) existing
2383 for the GNU debugger.
2385 <sect2>break [line | file:line | function | file:function]
2386 <p>Set breakpoint at specified line or function.
2389 <verb>sdcdb>break 100
2390 sdcdb>break foo.c:100
2391 sdcdb>break funcfoo
2395 <sect2>clear [line | file:line | function | file:function ]
2396 <p>Clear breakpoint at specified line or function.
2399 <verb>sdcdb>clear 100
2400 sdcdb>clear foo.c:100
2401 sdcdb>clear funcfoo
2406 <p>Continue program being debugged, after breakpoint.
2409 <p>Execute till the end of the current function.
2411 <sect2>delete [n]
2412 <p>Delete breakpoint number 'n'. If used without any option clear ALL user
2413 defined break points.
2415 <sect2>info [break | stack | frame | registers ]
2418 <item>info break - list all breakpoints
2419 <item>info stack - show the function call stack.
2420 <item>info frame - show information about the current execution frame.
2421 <item>info registers - show content of all registers.
2424 <p>Step program until it reaches a different source line.
2427 <p>Step program, proceeding through subroutine calls.
2430 <p>Start debugged program.
2432 <sect2>ptype variable
2433 <p>Print type information of the variable.
2435 <sect2>print variable
2436 <p>print value of variable.
2438 <sect2>file filename
2439 <p>load the given file name. Note this is an alternate method of loading file
2443 <p>print information about current frame.
2446 <p>Toggle between C source & assembly source.
2448 <sect2>! simulator command
2449 <p>Send the string following '!' to the simulator, the simulator response
2450 is displayed. Note the debugger does not interpret the command being sent to
2451 the simulator, so if a command like 'go' is sent the debugger can loose its
2452 execution context and may display incorrect values.
2455 <p>&dquot;Watch me now. Iam going Down. My name is Bobby Brown&dquot;
2457 <sect1>Interfacing with XEmacs.
2458 <p>Two files are (in emacs lisp) are provided for the interfacing with XEmacs,
2459 sdcdb.el and sdcdbsrc.el. These two files can be found in the $(prefix)/bin
2460 directory after the installation is complete. These files need to be loaded
2461 into XEmacs for the interface to work, this can be done at XEmacs startup time
2462 by inserting the following into your '.xemacs' file (which can be found in
2463 your HOME directory) (load-file sdcdbsrc.el) [ .xemacs is a lisp file
2464 so the () around the command is REQUIRED), the files can also be loaded dynamically
2465 while XEmacs is running, set the environment variable 'EMACSLOADPATH' to the
2466 installation bin directory [$(prefix)/bin], then enter the
2467 following command ESC-x load-file sdcdbsrc . To start the interface enter the
2468 following command ESC-x sdcdbsrc , you will prompted to enter the file name
2471 <p>The command line options that are passed to the simulator directly are
2472 bound to default values in the file sdcdbsrc.el the variables are listed below
2473 these values maybe changed as required.
2477 <item>sdcdbsrc-cpu-type '51
2478 <item>sdcdbsrc-frequency '11059200
2479 <item>sdcdbsrc-serial nil
2481 <p>The following is a list of key mapping for the debugger interface.
2485 ;; Current Listing ::
2486 ;;key binding Comment
2488 ;;--- ------- -------
2491 sdcdb-next-from-src SDCDB next command
2492 ;; b sdcdb-back-from-src SDCDB
2494 ;; c sdcdb-cont-from-src SDCDB continue
2496 ;; s sdcdb-step-from-src SDCDB step command
2498 ;; ? sdcdb-whatis-c-sexp SDCDB ptypecommand for data
2502 sdcdbsrc-delete SDCDB Delete all breakpoints if no arg
2504 or delete arg (C-u arg x)
2505 ;; m sdcdbsrc-frame SDCDB
2506 Display current frame if no arg,
2508 or display frame arg
2511 ;; ! sdcdbsrc-goto-sdcdb Goto the SDCDB output
2513 ;; p sdcdb-print-c-sexp SDCDB print command
2517 g sdcdbsrc-goto-sdcdb Goto the SDCDB output buffer
2519 t sdcdbsrc-mode Toggles Sdcdbsrc mode (turns it
2522 ;; C-c C-f sdcdb-finish-from-src SDCDB finish command
2525 ;; C-x SPC sdcdb-break Set break for line with
2527 ;; ESC t sdcdbsrc-mode Toggle Sdcdbsrc mode
2529 ;; ESC m sdcdbsrc-srcmode Toggle list mode
2533 <sect>Conclusion<label id="Conclusion" >
2534 <p>SDCC is a large project , the compiler alone (without the Assembler Package
2535 , Preprocessor & garbage collector) is about 40,000 lines of code (blank
2536 stripped). As with any project of this size there are bound to be bugs, I am
2537 more than willing to work to fix these bugs , of course all the source code
2538 is included with the package.
2540 <p>Where does it go from here ? I am planning to target the Atmel AVR 8-bit
2541 MCUs which seems to have a lot of users. I am also planning to include an alias
2542 analysis system with this compiler (it does not currently have one).
2544 <sect>Acknowledgments<label id="Acknowledgements" >
2545 <p>Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX &
2548 <p>John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for
2551 <p>Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
2553 <p>Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware
2556 <p>Jans J Boehm(boehm@sgi.com) and Alan J Demers - Conservative garbage collector
2559 <p>Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience and support.
2561 <p>Unknown - for the GNU C - preprocessor.
2563 <sect>Appendix A: The Z80 and gbz80 port
2564 <p>2.2.0 can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like
2565 gbz80. The port is incomplete - long support is incomplete (mul, div and mod
2566 are unimplimented), and both float and bitfield support is missing, but apart
2567 from that the code generated is correct.
2569 <p>As always, the code is the authoritave reference - see z80/ralloc.c and
2570 z80/gen.c. The stack frame is similar to that generated by the IAR Z80 compiler.
2571 IX is used as the base pointer, HL is used as a temporary register, and BC
2572 and DE are available for holding varibles. IY is currently unusued. Return
2573 values are stored in HL. One bad side effect of using IX as the base pointer
2574 is that a functions stack frame is limited to 127 bytes - this will be fixed
2575 in a later version.bc