3 SDCC Compiler User Guide
10 1.3 System Requirements
13 2.1 Linux/Unix Installation
14 2.2 Windows Installation
15 2.2.1 Windows Install Using a Binary Package
16 2.2.2 Windows Install Using Cygwin
17 2.3 Testing out the SDCC Compiler
18 2.4 Install Trouble-shooting
19 2.4.1 SDCC cannot find libraries or header files.
20 2.4.2 SDCC does not compile correctly.
21 2.4.3 What the ./configure does
22 2.4.4 What the make does.
23 2.4.5 What the make install command does.
24 2.5 Additional Information for Windows Users
25 2.5.1 Getting started with Cygwin
26 2.5.2 Running SDCC as Native Compiled Executables
27 2.6 SDCC on Other Platforms
28 2.7 Advanced Install Options
29 2.8 Components of SDCC
30 2.8.1 cpp ( C-Preprocessor)
31 2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)
32 2.8.3 SDCC - The compiler
34 2.8.5 SDCDB - Source Level Debugger
37 3.1.1 Single Source File Projects
38 3.1.2 Projects with Multiple Source Files
39 3.1.3 Projects with Additional Libraries
40 3.2 Command Line Options
41 3.2.1 Processor Selection Options
42 3.2.2 Path, Lib and Define Options
44 3.2.4 Optimization Options
47 3.2.7 Intermediate Dump Options
48 3.3 MCS51 Storage Class Language Extensions
55 3.5 Parameters & Local Variables
57 3.7 Critical Functions
58 3.8 Absolute Addressing
59 3.9 Interrupt Service Routines
61 3.11 Inline Assembler Code
62 3.12 int(16 bit) and long (32 bit ) Support
63 3.13 Floating Point Support
64 3.14 MCS51 Memory Models
65 3.15 Flat 24 bit Addressing Model
66 3.16 Defines Created by the Compiler
69 4.1.1 Sub-expression Elimination
70 4.1.2 Dead-Code Elimination
71 4.1.3 Copy-Propagation
72 4.1.4 Loop Optimizations
74 4.1.6 Algebraic Simplifications
75 4.1.7 'switch' Statements
76 4.1.8 Bit-shifting Operations.
78 4.1.10 Highest Order Bit
79 4.1.11 Peep-hole Optimizer
82 4.4 Interfacing with Assembly Routines
83 4.5 Global Registers used for Parameter Passing
84 4.5.1 Assembler Routine(non-reentrant)
85 4.5.2 Assembler Routine(reentrant)
86 4.6 With --noregparms Option
87 4.6.1 Assembler Routine Non-reentrant
88 4.6.2 Assembler Routine(reentrant)
91 4.9 Cyclomatic Complexity
93 6 Retargetting for other MCUs.
94 7 SDCDB - Source Level Debugger
95 7.1 Compiling for Debugging
96 7.2 How the Debugger Works
97 7.3 Starting the Debugger
98 7.4 Command Line Options.
99 7.5 Debugger Commands.
100 7.5.1 break [line | file:line | function | file:function]
101 7.5.2 clear [line | file:line | function | file:function ]
105 7.5.6 info [break | stack | frame | registers ]
109 7.5.10 ptype variable
110 7.5.11 print variable
114 7.5.15 ! simulator command
116 7.6 Interfacing with XEmacs.
118 8.1 The Z80 and gbz80 port
129 SDCC is a Free ware, retargettable, optimizing ANSI-C compiler
130 by Sandeep Dutta designed for 8 bit Microprocessors. The
131 current version targets Intel MCS51 based Microprocessors(8051,8052,
132 etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51
133 variant. It can be retargetted for other microprocessors,
134 support for PIC, AVR and 186 is under development. The entire
135 source code for the compiler is distributed under GPL. SDCC
136 uses ASXXXX & ASLINK, a Freeware, retargettable assembler
137 & linker. SDCC has extensive language extensions suitable
138 for utilizing various microcontrollers underlying hardware
139 effectively. In addition to the MCU specific optimizations
140 SDCC also does a host of standard optimizations like global
141 sub expression elimination, loop optimizations (loop invariant,
142 strength reduction of induction variables and loop reversing),
143 constant folding & propagation, copy propagation, dead code
144 elimination and jumptables for 'switch' statements. For
145 the back-end SDCC uses a global register allocation scheme
146 which should be well suited for other 8 bit MCUs. The peep
147 hole optimizer uses a rule based substitution mechanism
148 which is MCU independent. Supported data-types are short
149 (8 bits, 1 byte), char (8 bits, 1 byte), int (16 bits, 2
150 bytes ), long (32 bit, 4 bytes) & float (4 byte IEEE). The
151 compiler also allows inline assembler code to be embedded
152 anywhere in a function. In addition routines developed in
153 assembly can also be called. SDCC also provides an option
154 to report the relative complexity of a function, these functions
155 can then be further optimized, or hand coded in assembly
156 if need be. SDCC also comes with a companion source level
157 debugger SDCDB, the debugger currently uses ucSim a freeware
158 simulator for 8051 and other micro-controllers. The latest
159 version can be downloaded from [http://sdcc.sourceforge.net/].
163 All packages used in this compiler system are opensource(freeware);
164 source code for all the sub-packages (asxxxx assembler/linker,
165 pre-processor) are distributed with the package. This documentation
166 is maintained using a freeware word processor (LyX).
168 This program is free software; you can redistribute it and/or
169 modify it under the terms of the GNU General Public License
170 as published by the Free Software Foundation; either version
171 2, or (at your option) any later version. This program is
172 distributed in the hope that it will be useful, but WITHOUT
173 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
174 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
175 Public License for more details. You should have received
176 a copy of the GNU General Public License along with this
177 program; if not, write to the Free Software Foundation,
178 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
179 In other words, you are welcome to use, share and improve
180 this program. You are forbidden to forbid anyone else to
181 use, share and improve what you give them. Help stamp out
184 1.3 System Requirements
186 What do you need before you start installation of SDCC? A
187 computer, and a desire to compute. The preferred method
188 of installation is to compile SDCC from source using GNU
189 GCC and make. For Windows some pre-compiled binary distributions
190 are available for your convenience. You should have some
191 experience with command line tools and compiler use.
195 The SDCC home page at [http://sdcc.sourceforge.net/]
196 is a great place to find distribution sets. You can also
197 find links to the user mailing lists that offer help or
198 discuss SDCC with other SDCC users. Web links to other SDCC
199 related sites can also be found here. This document can
200 be found in the DOC directory of the source package as a
201 text or HTML file. Some of the other tools(simulator and
202 assembler) included with SDCC contain their own documentation
203 and can be found in the source distribution. If you want
204 the latest unreleased software, the complete source package
205 is available directly by anonymous CVS on www.sourceforge.net.
209 2.1 Linux/Unix Installation
211 1. Download the source package, it will be named something
214 2. Bring up a command line terminal, such as xterm.
216 3. Unpack the file using a command like: tar -xzf sdcc-2.x.x.tgz,
217 this will create a sub-directory called sdcc with all
220 4. Change directory into the main SDCC directory, for example
223 5. Type "./configure". This configures
224 the package for compilation on your system.
226 6. Type "make". All of the source packages
227 will compile, this can take a while.
229 7. Type "make install" as root.
230 This copies the binary executables to the install directories.
232 2.2 Windows Installation
234 For installation under Windows you first need to pick between
235 a pre-compiled binary package, or installing the source
236 package along with the Cygwin package. The binary package
237 is the quickest to install, while the Cygwin package includes
238 all of the open source power tools used to compile the complete
239 SDCC source package in the Windows environment. If you are
240 not familiar with the Unix command line environment, you
241 may want to read the section on additional information for
242 Windows users prior to your initial installation.
244 2.2.1 Windows Install Using a Binary Package
246 1. Download the binary package and unpack it using your favorite
247 unpacking tool(gunzip, WinZip, etc). This should unpack
248 to a group of sub-directories. An example directory structure
249 after unpacking is: c:\usr\local\bin for the executables,
250 c:\usr\local\share\sdcc\include and c:\usr\local\share\sdcc\lib
251 for the include and libraries.
253 2. Adjust your environment PATH to include the location of
254 the bin directory. For example, make a setsdcc.bat file
255 with the following: set PATH=c:\usr\local\bin;%PATH%
257 3. When you compile with sdcc, you may need to specify the
258 location of the lib and include folders. For example,
259 sdcc -I c:\usr\local\share\sdcc\include -L c:\usr\local\share\sdcc\lib\small
262 2.2.2 Windows Install Using Cygwin
264 1. Download and install the cygwin package from the redhat
265 site[http://sources.redhat.com/cygwin/]. Currently,
266 this involved downloading a small install program which
267 then automates downloading and installing selected parts
268 of the package(a large 80M byte sized dowload for the
271 2. Bring up a Unix/Bash command line terminal from the Cygwin
274 3. Follow the instructions in the preceding Linux/Unix installation
277 2.3 Testing out the SDCC Compiler
279 The first thing you should do after installing your SDCC
280 compiler is to see if it runs. Type "sdcc
281 --version" at the prompt, and the program should
282 run and tell you the version. If it doesn't run, or gives
283 a message about not finding sdcc program, then you need
284 to check over your installation. Make sure that the sdcc
285 bin directory is in your executable search path defined
286 by the PATH environment setting(see the Trouble-shooting
287 section for suggestions). Make sure that the sdcc program
288 is in the bin folder, if not perhaps something did not install
291 SDCC binaries are commonly installed in a directory arrangement
294 +--------------------------------+-------------------------------------------+
295 | /usr/local/bin | Holds executables(sdcc, s51, aslink, ...) |
296 +--------------------------------+-------------------------------------------+
297 +--------------------------------+-------------------------------------------+
298 | /usr/local/share/sdcc/lib | Holds common C libraries |
299 +--------------------------------+-------------------------------------------+
300 | /usr/local/share/sdcc/include | Holds common C header files |
301 +--------------------------------+-------------------------------------------+
304 Make sure the compiler works on a very simple example. Type
305 in the following test.c program using your favorite editor:
314 Compile this using the following command: "sdcc
315 -c test.c". If all goes well, the compiler will
316 generate a test.asm and test.rel file. Congratulations,
317 you've just compiled your first program with SDCC. We used
318 the -c option to tell SDCC not to link the generated code,
319 just to keep things simple for this step.
321 The next step is to try it with the linker. Type in "sdcc
322 test.c". If all goes well the compiler will link with
323 the libraries and produce a test.ihx output file. If this
324 step fails(no test.ihx, and the linker generates warnings),
325 then the problem is most likely that sdcc cannot find the
326 usr/local/share/sdcc/lib/small directory(see the Install
327 trouble-shooting section for suggestions).
329 The final test is to ensure sdcc can use the standard header
330 files and libraries. Edit test.c and change it to the following:
335 strcpy(str1, "testing");
338 Compile this by typing: "sdcc test.c".
339 This should generate a test.ihx output file, and it should
340 give no warnings such as not finding the string.h file.
341 If it cannot find the string.h file, then the problem is
342 that sdcc cannot find the /usr/local/share/sdcc/include
343 directory(see the Install trouble-shooting section for suggestions).
345 2.4 Install Trouble-shooting
347 2.4.1 SDCC cannot find libraries or header files.
349 The default installation assumes the libraries and header
350 files are located at "/usr/local/share/sdcc/lib"
351 and "/usr/local/share/sdcc/include".
352 An alternative is to specify these locations as compiler
353 options like this: sdcc -L /usr/local/sdcc/lib/small -I
354 /usr/local/sdcc/include test.c
356 2.4.2 SDCC does not compile correctly.
358 A few things to try include starting from scratch by unpacking
359 the .tgz source package again in an empty directory. If
360 this doesn't work, you could try downloading a different
361 version. If this doesn't work, you can re-direct the install
362 messages by doing the following:
364 $./make > dump.txt 2>&1
366 After this you can examine the dump.txt files to locate the
367 problem. Or these messages can be attached to an email that
368 could be helpful when requesting help from the mailing list.
370 2.4.3 What the "./configure"
373 The "./configure" command is a script
374 that analyzes your system and performs some configuration
375 to ensure the source package compiles on your system. It
376 will take a few minutes to run, and will compile a few tests
377 to determine what compiler features are installed.
379 2.4.4 What the "make" does.
381 This runs the GNU make tool, which automatically compiles
382 all the source packages into the final installed binary
385 2.4.5 What the "make install"
388 This will install the compiler, other executables and libraries
389 in to the appropriate system directories. The default is
390 to copy the executables to /usr/local/bin and the libraries
391 and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
393 2.5 Additional Information for Windows Users
395 The standard method of installing on a Unix system involves
396 compiling the source package. This is easily done under
397 Unix, but under Windows it can be a more difficult process.
398 The Cygwin is a large package to download, and the compilation
399 runs considerably slower under Windows due to the overhead
400 of the Cygwin tool set. An alternative is to install a pre-compiled
401 Windows binary package. There are various trade-offs between
402 each of these methods.
404 The Cygwin package allows a Windows user to run a Unix command
405 line interface(bash shell) and also implements a Unix like
406 file system on top of Windows. Included are many of the
407 famous GNU software development tools which can augment
408 the SDCC compiler.This is great if you have some experience
409 with Unix command line tools and file system conventions,
410 if not you may find it easier to start by installing a binary
411 Windows package. The binary packages work with the Windows
412 file system conventions.
414 2.5.1 Getting started with Cygwin
416 SDCC is typically distributed as a tarred/gzipped file(.tgz).
417 This is a packed file similar to a .zip file. Cygwin includes
418 the tools you will need to unpack the SDCC distribution(tar
419 and gzip). To unpack it, simply follow the instructions
420 under the Linux/Unix install section. Before you do this
421 you need to learn how to start a cygwin shell and some of
422 the basic commands used to move files, change directory,
423 run commands and so on. The change directory command is
424 "cd", the move command is "mv".
425 To print the current working directory, type "pwd".
426 To make a directory, use "mkdir".
428 There are some basic differences between Unix and Windows
429 file systems you should understand. When you type in directory
430 paths, Unix and the Cygwin bash prompt uses forward slashes
431 '/' between directories while Windows traditionally uses
432 '\' backward slashes. So when you work at the Cygwin bash
433 prompt, you will need to use the forward '/' slashes. Unix
434 does not have a concept of drive letters, such as "c:",
435 instead all files systems attach and appear as directories.
437 2.5.2 Running SDCC as Native Compiled Executables
439 If you use the pre-compiled binaries, the install directories
440 for the libraries and header files may need to be specified
441 on the sdcc command line like this: sdcc -L c:\usr\local\sdcc\lib\small
442 -I c:\usr\local\sdcc\include test.c if you are running outside
443 of a Unix bash shell.
445 If you have successfully installed and compiled SDCC with
446 the Cygwin package, it is possible to compile into native
447 .exe files by using the additional makefiles included for
448 this purpose. For example, with the Borland 32-bit compiler
449 you would run make -f Makefile.bcc. A command line version
450 of the Borland 32-bit compiler can be downloaded from the
453 2.6 SDCC on Other Platforms
455 * FreeBSD and other non-GNU Unixes - Make sure the GNU make
456 is installed as the default make tool.
458 * SDCC has been ported to run under a variety of operating
459 systems and processors. If you can run GNU GCC/make then
460 chances are good SDCC can be compiled and run on your
463 2.7 Advanced Install Options
465 The "configure" command has several options.
466 The most commonly used option is --prefix=<directory name>,
467 where <directory name> is the final location for the sdcc
468 executables and libraries, (default location is /usr/local).
469 The installation process will create the following directory
470 structure under the <directory name> specified.
472 bin/ - binary exectables (add to PATH environment variable)
475 sdcc/include/ - include
479 - Object & library files for small model library
481 - Object & library files for large model library
483 - Object & library files forDS80C390 library
487 './configure --prefix=/usr/local"
489 will configure the compiler to be installed in directory
492 2.8 Components of SDCC
494 SDCC is not just a compiler, but a collection of tools by
495 various developers. These include linkers, assemblers, simulators
496 and other components. Here is a summary of some of the components.
497 Note that the included simulator and assembler have separate
498 documentation which you can find in the source package in
499 their respective directories. As SDCC grows to include support
500 for other processors, other packages from various developers
501 are included and may have their own sets of documentation.
503 You might want to look at the various executables which are
504 installed in the bin directory. At the time of this writing,
505 we find the following programs:
509 aslink -The linker for 8051 type processors.
511 asx8051 - The assembler for 8051 type processors.
513 sdcpp - The C preprocessor.
515 sdcpd - The source debugger.
517 s51 - The ucSim 8051 simulator.
519 linkz80, linkgbz80 - The Z80 and GameBoy Z80 linkers.
521 as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers.
523 packihx - A tool to pack Intel hex files.
525 As development for other processors proceeds, this list will
526 expand to include executables to support processors like
529 2.8.1 cpp ( C-Preprocessor)
531 The preprocessor is extracted into the directory SDCCDIR/cpp,
532 it is a modified version of the GNU preprocessor. The C
533 preprocessor is used to pull in #include sources, process
534 #ifdef statements, #defines and so on.
536 2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)
538 This is retargettable assembler & linkage editor, it was
539 developed by Alan Baldwin, John Hartman created the version
540 for 8051, and I (Sandeep) have some enhancements and bug
541 fixes for it to work properly with the SDCC. This component
542 is extracted into the directory SDCCDIR/asxxxx.
544 2.8.3 SDCC - The compiler
546 This is the actual compiler, it in turn uses the c-preprocessor
547 and invokes the assembler and linkage editors. All files
548 with the prefix SDCC are part of the compiler and are extracted
549 into the the directory SDCCDIR.
551 2.8.4 S51 - Simulator
553 s51 is a freeware, opensource simulator developed by Daniel
554 Drotos <drdani@mazsola.iit.uni-miskolc.hu>. The executable
555 is built as part of the build process, for more information
556 visit Daniel's website at <http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51/>.
558 2.8.5 SDCDB - Source Level Debugger
560 SDCDB is the companion source level debugger . The current
561 version of the debugger uses Daniel's Simulator S51, but
562 can be easily changed to use other simulators.
568 3.1.1 Single Source File Projects
570 For single source file 8051 projects the process is very
571 simple. Compile your programs with the following command
575 The above command will compile ,assemble and link your source
576 file. Output files are as follows.
578 * sourcefile.asm - Assembler source file created by the compiler
580 * sourcefile.lst - Assembler listing file created by the
583 * sourcefile.rst - Assembler listing file updated with linkedit
584 information , created by linkage editor
586 * sourcefile.sym - symbol listing for the sourcefile, created
589 * sourcefile.rel - Object file created by the assembler,
590 input to Linkage editor.
592 * sourcefile.map - The memory map for the load module, created
595 * sourcefile.<ihx | s19> - The load module : ihx - Intel
596 hex format (default ), s19 - Motorola S19 format when
597 compiler option --out-fmt-s19 is used.
599 3.1.2 Projects with Multiple Source Files
601 SDCC can compile only ONE file at a time. Let us for example
602 assume that you have a project containing the following
605 foo1.c ( contains some functions )
607 foo2.c (contains some more functions)
609 foomain.c (contains more functions and the function main)
611 The first two files will need to be compiled separately with
618 Then compile the source file containing main and link the
619 other files together with the following command.
621 sdcc foomain.c foo1.rel foo2.rel
623 Alternatively foomain.c can be separately compiled as well
627 sdcc foomain.rel foo1.rel foo2.rel
629 The file containing the main function MUST be the FIRST file
630 specified in the command line , since the linkage editor
631 processes file in the order they are presented to it.
633 3.1.3 Projects with Additional Libraries
635 Some reusable routines may be compiled into a library, see
636 the documentation for the assembler and linkage editor in
637 the directory SDCCDIR/asxxxx/asxhtm.htm this describes how
638 to create a .lib library file, the libraries created in
639 this manner may be included using the command line, make
640 sure you include the -L <library-path> option to tell the
641 linker where to look for these files. Here is an example,
642 assuming you have the source file 'foomain.c' and a library
643 'foolib.lib' in the directory 'mylib'.
645 sdcc foomain.c foolib.lib -L mylib
647 Note here that 'mylib' must be an absolute path name.
649 The view of the way the linkage editor processes the library
650 files, it is recommended that you put each source routine
651 in a separate file and combine them using the .lib file.
652 For an example see the standard library file 'libsdcc.lib'
653 in the directory SDCCDIR/sdcc51lib.
655 3.2 Command Line Options
657 3.2.1 Processor Selection Options
659 -mmcs51 Generate code for the MCS51 (8051) family of processors.
660 This is the default processor target.
662 -mds390 Generate code for the DS80C390 processor.
664 -mz80 Generate code for the Z80 family of processors.
666 -mgbz80 Generate code for the GameBoy Z80 processor.
668 -mavr Generate code for the Atmel AVR processor(In development,
671 -mpic14 Generate code for the PIC 14-bit processors(In development,
674 -mtlcs900h Generate code for the Toshiba TLCS-900H processor(In
675 development, not complete).
677 3.2.2 Path, Lib and Define Options
679 -I<path> The additional location where the pre processor
680 will look for <..h> or "..h"
683 -D<macro[=value]> Command line definition of macros. Passed
684 to the pre processor.
686 --lib-path(-L) <absolute path to additional libraries> This
687 option is passed to the linkage editor, additional libraries
688 search path. The path name must be absolute. Additional
689 library files may be specified in the command line . See
690 section Compiling programs for more details.
694 --model-large Generate code for Large model programs see
695 section Memory Models for more details. If this option is
696 used all source files in the project should be compiled
697 with this option. In addition the standard library routines
698 are compiled with small model , they will need to be recompiled.
700 --model-small Generate code for Small Model programs see
701 section Memory Models for more details. This is the default
704 --model-flat24 Generate code forDS80C390 24-bit flat mode.
705 See section Memory Models for more details.
707 --stack-auto All functions in the source file will be compiled
708 as reentrant, i.e. the parameters and local variables will
709 be allocated on the stack. see section Parameters and Local
710 Variables for more details. If this option is used all source
711 files in the project should be compiled with this option.
713 --xstack Uses a pseudo stack in the first 256 bytes in the
714 external ram for allocating variables and passing parameters.
715 See section on external stack for more details.
717 3.2.4 Optimization Options
719 --nogcse Will not do global subexpression elimination, this
720 option may be used when the compiler creates undesirably
721 large stack/data spaces to store compiler temporaries. A
722 warning message will be generated when this happens and
723 the compiler will indicate the number of extra bytes it
724 allocated. It recommended that this option NOT be used ,
725 #pragma NOGCSE can be used to turn off global subexpression
726 elimination for a given function only.
728 --noinvariant Will not do loop invariant optimizations, this
729 may be turned off for reasons explained for the previous
730 option . For more details of loop optimizations performed
731 see section Loop Invariants.It recommended that this option
732 NOT be used , #pragma NOINVARIANT can be used to turn off
733 invariant optimizations for a given function only.
735 --noinduction Will not do loop induction optimizations, see
736 section Strength reduction for more details.It recommended
737 that this option NOT be used , #pragma NOINDUCTION can be
738 used to turn off induction optimizations for given function
741 --nojtbound Will not generate boundary condition check when
742 switch statements are implemented using jump-tables. See
743 section Switch Statements for more details.It recommended
744 that this option NOT be used , #pragma NOJTBOUND can be
745 used to turn off boundary checking for jump tables for a
748 --noloopreverse Will not do loop reversal optimization
750 --noregparms By default the first parameter is passed using
751 global registers (DPL,DPH,B,ACC). This option will disable
752 parameter passing using registers. NOTE: if your program
753 uses the 16/32 bit support routines (for multiplication/division)
754 these library routines will need to be recompiled with the
755 --noregparms option as well.
759 --stack-auto See MCS51 section for description.
761 --stack-10bit This option generates code for the 10 bit stack
762 mode of the Dallas DS80C390 part. In this mode, the stack
763 is located in the lower 1K of the internal RAM, which is
764 mapped to 0x400000. Note that the support is incomplete,
765 since it still uses a single byte as the stack pointer.
766 This means that only the lower 256 bytes of the potential
767 1K stack space can actually be used. However, this does
768 allow you to reclaim the precious 256 bytes of low RAM for
769 use for the DATA and IDATA segments. The compiler will not
770 generate any code to put the processor into 10 bit stack
771 mode. It is important to ensure that the processor is in
772 this mode before calling any re-entrant functions compiled
773 with this option. In principle, this should work with the
774 --stack-auto option, but that has not been tested. It is
775 incompatible with the --xstack option. It also only makes
776 sense if the processor is in 24 bit contiguous addressing
777 mode (see the --model-flat24 option).
781 --callee-saves function1[,function2][,function3].... The
782 compiler by default uses a caller saves convention for register
783 saving across function calls, however this can cause unneccessary
784 register pushing & popping when calling small functions
785 from larger functions. This option can be used to switch
786 the register saving convention for the function names specified.
787 The compiler will not save registers when calling these
788 functions, extra code will be generated at the entry & exit
789 for these functions to save & restore the registers used
790 by these functions, this can SUBSTANTIALLY reduce code &
791 improve run time performance of the generated code. In future
792 the compiler (with interprocedural analysis) will be able
793 to determine the appropriate scheme to use for each function
794 call. DO NOT use this option for built-in functions such
795 as _muluint..., if this option is used for a library function
796 the appropriate library function needs to be recompiled
797 with the same option. If the project consists of multiple
798 source files then all the source file should be compiled
799 with the same --callee-saves option string. Also see Pragma
800 Directive CALLEE-SAVES. .
802 --debug When this option is used the compiler will generate
803 debug information , that can be used with the SDCDB. The
804 debug information is collected in a file with .cdb extension.
805 For more information see documentation for SDCDB.
807 --regextend This option will cause the compiler to define
808 pseudo registers , if this option is used, all source files
809 in the project should be compiled with this option. See
810 section Register Extension for more details.
812 --compile-only(-c) will compile and assemble the source
813 only, will not call the linkage editor.
815 --xram-loc<Value> The start location of the external ram,
816 default value is 0. The value entered can be in Hexadecimal
817 or Decimal format .eg. --xram-loc 0x8000 or --xram-loc 32768.
819 --code-loc<Value> The start location of the code segment
820 , default value 0. Note when this option is used the interrupt
821 vector table is also relocated to the given address. The
822 value entered can be in Hexadecimal or Decimal format .eg.
823 --code-loc 0x8000 or --code-loc 32768.
825 --stack-loc<Value> The initial value of the stack pointer.
826 The default value of the stack pointer is 0x07 if only register
827 bank 0 is used, if other register banks are used then the
828 stack pointer is initialized to the location above the highest
829 register bank used. eg. if register banks 1 & 2 are used
830 the stack pointer will default to location 0x18. The value
831 entered can be in Hexadecimal or Decimal format .eg. --stack-loc
832 0x20 or --stack-loc 32. If all four register banks are used
833 the stack will be placed after the data segment (equivalent
834 to --stack-after-data)
836 --stack-after-data This option will cause the stack to be
837 located in the internal ram after the data segment.
839 --data-loc<Value> The start location of the internal ram
840 data segment, the default value is 0x30.The value entered
841 can be in Hexadecimal or Decimal format .eg. --data-loc
842 0x20 or --data-loc 32.
844 --idata-loc<Value> The start location of the indirectly addressable
845 internal ram, default value is 0x80. The value entered can
846 be in Hexadecimal or Decimal format .eg. --idata-loc 0x88
849 --peep-file<filename> This option can be used to use additional
850 rules to be used by the peep hole optimizer. See section
851 Peep Hole optimizations for details on how to write these
854 -E Run only the C preprocessor. Preprocess all the C source
855 files specified and output the results to standard output.
857 -M Tell the preprocessor to output a rule suitable for make
858 describing the dependencies of each object file. For each
859 source file, the preprocessor outputs one make-rule whose
860 target is the object file name for that source file and
861 whose dependencies are all the files `#include'd in it.
862 This rule may be a single line or may be continued with
863 `\'-newline if it is long. The list of rules is printed on
864 standard output instead of the preprocessed C program. `-M'
867 -C Tell the preprocessor not to discard comments. Used with
870 -MM Like `-M' but the output mentions only the user header
871 files included with `#include file"'. System header files
872 included with `#include <file>' are omitted.
874 -Aquestion(answer) Assert the answer answer for question,
875 in case it is tested with a preprocessor conditional such
876 as `#if #question(answer)'. `-A-' disables the standard
877 assertions that normally describe the target machine.
879 -Aquestion (answer) Assert the answer answer for question,
880 in case it is tested with a preprocessor conditional such
881 as `#if #question(answer)'. `-A-' disables the standard
882 assertions that normally describe the target machine.
884 -Umacro Undefine macro macro. `-U' options are evaluated
885 after all `-D' options, but before any `-include' and `-imacros'
888 -dM Tell the preprocessor to output only a list of the macro
889 definitions that are in effect at the end of preprocessing.
890 Used with the `-E' option.
892 -dD Tell the preprocessor to pass all macro definitions into
893 the output, in their proper sequence in the rest of the
896 -dN Like `-dD' except that the macro arguments and contents
897 are omitted. Only `#define name' is included in the output.
899 -S Stop after the stage of compilation proper; do not as-
900 semble. The output is an assembler code file for the input
903 -Wa_asmOption[,asmOption]... Pass the asmOption to the assembler.
905 -Wl_linkOption[,linkOption] .. Pass the linkOption to the
908 --int-long-reent Integer (16 bit) and long (32 bit) libraries
909 have been compiled as reentrant. Note by default these libraries
910 are compiled as non-reentrant. See section Installation
913 --cyclomatic This option will cause the compiler to generate
914 an information message for each function in the source file.
915 The message contains some important information about the
916 function. The number of edges and nodes the compiler detected
917 in the control flow graph of the function, and most importantly
918 the cyclomatic complexity see section on Cyclomatic Complexity
921 --float-reent Floating point library is compiled as reentrant.See
922 section Installation for more details.
924 --out-fmt-ihx The linker output (final object code) is in
925 Intel Hex format. (This is the default option).
927 --out-fmt-s19 The linker output (final object code) is in
930 --nooverlay The compiler will not overlay parameters and
931 local variables of any function, see section Parameters
932 and local variables for more details.
934 --main-return This option can be used when the code generated
935 is called by a monitor program. The compiler will generate
936 a 'ret' upon return from the 'main' function. The default
937 option is to lock up i.e. generate a 'ljmp .' .
939 --no-peep Disable peep-hole optimization.
941 --peep-asm Pass the inline assembler code through the peep
942 hole optimizer. Can cause unexpected changes to inline assembler
943 code , please go through the peephole optimizer rules defnied
944 in file 'SDCCpeeph.def' before using this option.
946 --iram-size<Value> Causes the linker to check if the interal
947 ram usage is within limits of the given value.
949 3.2.7 Intermediate Dump Options
951 The following options are provided for the purpose of retargetting
952 and debugging the compiler . These provided a means to dump
953 the intermediate code (iCode) generated by the compiler
954 in human readable form at various stages of the compilation
957 --dumpraw . This option will cause the compiler to dump the
958 intermediate code into a file of named <source filename>.dumpraw
959 just after the intermediate code has been generated for
960 a function , i.e. before any optimizations are done. The
961 basic blocks at this stage ordered in the depth first number,
962 so they may not be in sequence of execution.
964 --dumpgcse. Will create a dump if iCode, after global subexpression
965 elimination, into a file named <source filename>.dumpgcse.
967 --dumpdeadcode .Will create a dump if iCode, after deadcode
968 elimination, into a file named <source filename>.dumpdeadcode.
970 --dumploop. Will create a dump if iCode, after loop optimizations,
971 into a file named <source filename>.dumploop.
973 --dumprange. Will create a dump if iCode, after live range
974 analysis, into a file named <source filename>.dumprange.
976 --dumpregassign. Will create a dump if iCode, after register
977 assignment , into a file named <source filename>.dumprassgn.
979 --dumpall. Will cause all the above mentioned dumps to be
982 Note that the files created for the dump are appended to
983 each time. So the files should be deleted manually , before
984 each dump is created.
986 When reporting bugs, it can be helpful to include these dumps
987 along with the portion of the code that is causing the problem.
989 3.3 MCS51 Storage Class Language Extensions
991 In addition to the ANSI storage classes SDCC allows the following
992 MCS51 specific storage classes.
996 Variables declared with this storage class will be placed
997 in the extern RAM. This is the default storage class for
1000 eg. xdata unsigned char xduc;
1004 This is the default storage class for Small Memory model.
1005 Variables declared with this storage class will be allocated
1006 in the internal RAM.
1008 eg. data int iramdata;
1012 Variables declared with this storage class will be allocated
1013 into the indirectly addressable portion of the internal
1020 This is a data-type and a storage class specifier. When a
1021 variable is declared as a bit , it is allocated into the
1022 bit addressable memory of 8051.
1028 Like the bit keyword, sfr / sbit signifies both a data-type
1029 and storage class, they are used to describe the special
1030 function registers and special bit variables of a 8051.
1034 sfr at 0x80 P0; /* special function register P0 at location
1037 sbit at 0xd7 CY; /* CY (Carry Flag) */
1041 SDCC allows (via language extensions) pointers to explicitly
1042 point to any of the memory spaces of the 8051. In addition
1043 to the explicit pointers, the compiler also allows a _generic
1044 class of pointers which can be used to point to any of the
1047 Pointer declaration examples.
1049 /* pointer physically in xternal ram pointing to object in
1051 data unsigned char * xdata p;
1054 /* pointer physically in code rom pointing to data in xdata
1056 xdata unsigned char * code p;
1059 /* pointer physically in code space pointing to data in code
1061 code unsigned char * code p;
1063 /* the folowing is a generic pointer physically located in
1067 Well you get the idea. For compatibility with the previous
1068 version of the compiler, the following syntax for pointer
1069 declaration is also supported. Note the above examples will
1070 be portable to other commercially available compilers.
1072 unsigned char _xdata *ucxdp; /* pointer to data in external
1074 unsigned char _data *ucdp ; /* pointer
1075 to data in internal ram */
1076 unsigned char _code *uccp ; /* pointer
1077 to data in R/O code space */
1078 unsigned char _idata *uccp; /*
1079 pointer to upper 128 bytes of ram */
1081 All unqualified pointers are treated as 3 - byte '_generic'
1082 pointers. These type of pointers can also to be explicitly
1085 unsigned char _generic *ucgp;
1087 The highest order byte of the generic pointers contains the
1088 data space information. Assembler support routines are called
1089 whenever data is stored or retrieved using _generic pointers.
1090 These are useful for developing reusable library routines.
1091 Explicitly specifying the pointer type will generate the
1092 most efficient code. Pointers declared using a mixture of
1093 OLD/NEW style could have unpredictable results.
1095 3.5 Parameters & Local Variables
1097 Automatic (local) variables and parameters to functions can
1098 either be placed on the stack or in data-space. The default
1099 action of the compiler is to place these variables in the
1100 internal RAM ( for small model) or external RAM (for Large
1101 model). They can be placed on the stack either by using
1102 the --stack-auto compiler option or by using the 'reentrant'
1103 keyword in the function declaration.
1107 unsigned short foo( short i) reentrant {
1111 Note that when the parameters & local variables are declared
1112 in the internal/external ram the functions are non-reentrant.
1113 Since stack space on 8051 is limited the 'reentrant' keyword
1114 or the --stack-auto option should be used sparingly. Note
1115 the reentrant keyword just means that the parameters & local
1116 variables will be allocated to the stack, it DOES NOT mean
1117 that the function is register bank independent.
1119 When compiled with the default option (i.e. non-reentrant
1120 ), local variables can be assigned storage classes and absolute
1125 unsigned short foo() {
1126 xdata unsigned short i;
1128 data at 0x31 unsiged short j;
1132 In the above example the variable i will be allocated in
1133 the external ram, bvar in bit addressable space and j in
1134 internal ram. When compiled with the --stack-auto or when
1135 a function is declared as 'reentrant' local variables cannot
1136 be assigned storage classes or absolute addresses.
1138 Parameters however are not allowed any storage class, (storage
1139 classes for parameters will be ignored), their allocation
1140 is governed by the memory model in use , and the reentrancy
1145 For non-reentrant functions SDCC will try to reduce internal
1146 ram space usage by overlaying parameters and local variables
1147 of a function (if possible). Parameters and local variables
1148 of a function will be allocated to an overlayable segment
1149 if the function has no other function calls and the function
1150 is non-reentrant and the memory model is small. If an explicit
1151 storage class is specified for a local variable , it will
1154 Note that the compiler (not the linkage editor) makes the
1155 decision for overlaying the data items. Functions that are
1156 called from an interrupt service routine should be preceded
1157 by a #pragma NOOVERLAY if they are not reentrant Along the
1158 same lines the compiler does not do any processing with
1159 the inline assembler code so the compiler might incorrectly
1160 assign local variables and parameters of a function into
1161 the overlay segment if the only function call from a function
1162 is from inline assembler code, it is safe to use the #pragma
1163 NOOVERLAY for functions which call other functions using
1164 inline assembler code.
1166 Parameters and Local variables of functions that contain
1167 16 or 32 bit multiplication or division will NOT be overlayed
1168 since these are implemented using external functions.
1174 void set_error( unsigned short errcd)
1179 void some_isr () interrupt 2 using 1
1186 In the above example the parameter errcd for the function
1187 set_error would be assigned to the overlayable segment (if
1188 the #pragma NOOVERLAY was not present) , this could cause
1189 unpredictable runtime behavior. The pragma NOOVERLAY ensures
1190 that the parameters and local variables for the function
1193 3.7 Critical Functions
1195 A special keyword may be associated with a function declaring
1196 it as 'critical'. SDCC will generate code to disable all
1197 interrupts upon entry to a critical function and enable
1198 them back before returning . Note that nesting critical
1199 functions may cause unpredictable results.
1209 The critical attribute maybe used with other attributes like
1212 3.8 Absolute Addressing
1214 Data items can be assigned an absolute address with the at
1215 <address> keyword, in addition to a storage class.
1219 xdata at 0x8000 unsigned char PORTA_8255 ;
1221 In the above example the PORTA_8255 will be allocated to
1222 the location 0x8000 of the external ram.
1224 Note that is this feature is provided to give the programmer
1225 access to memory mapped devices attached to the controller.
1226 The compiler does not actually reserve any space for variables
1227 declared in this way (they are implemented with an equate
1228 in the assembler), thus it is left to the programmer to
1229 make sure there are no overlaps with other variables that
1230 are declared without the absolute address, the assembler
1231 listing file (.lst) and the linker output files (<filename>.rst)
1232 and (<filename>.map) are a good places to look for such
1235 Absolute address can be specified for variables in all storage
1242 The above example will allocate the variable at offset 0x02
1243 in the bit-addressable space. There is no real advantage
1244 to assigning absolute addresses to variables in this manner
1245 , unless you want strict control over all the variables
1248 3.9 Interrupt Service Routines
1250 SDCC allows interrupt service routines to be coded in C,
1251 with some extended keywords.
1253 void timer_isr (void) interrupt 2 using 1
1258 The number following the 'interrupt' keyword is the interrupt
1259 number this routine will service. The compiler will insert
1260 a call to this routine in the interrupt vector table for
1261 the interrupt number specified. The 'using' keyword is used
1262 to tell the compiler to use the specified register bank
1263 (8051 specific) when generating code for this function.
1264 Note that when some function is called from an interrupt
1265 service routine it should be preceded by a #pragma NOOVERLAY
1266 (if it is not reentrant) . A special note here, int (16
1267 bit) and long (32 bit) integer division, multiplication
1268 & modulus operations are implemented using external support
1269 routines developed in ANSI-C, if an interrupt service routine
1270 needs to do any of these operations then the support routines
1271 (as mentioned in a following section) will have to recompiled
1272 using the --stack-auto option and the source file will need
1273 to be compiled using the --int-long-rent compiler option.
1275 If you have multiple source files in your project, interrupt
1276 service routines can be present in any of them, but a prototype
1277 of the isr MUST be present in the file that contains the
1280 Interrupt Numbers and the corresponding address & descriptions
1281 for the Standard 8051 are listed below. SDCC will automatically
1282 adjust the interrupt vector table to the maximum interrupt
1285 +--------------+--------------+----------------+
1286 | Interrupt # | Description | Vector Address |
1287 +--------------+--------------+----------------+
1288 +--------------+--------------+----------------+
1289 | 0 | External 0 | 0x0003 |
1290 +--------------+--------------+----------------+
1291 | 1 | Timer 0 | 0x000B |
1292 +--------------+--------------+----------------+
1293 | 2 | External 1 | 0x0013 |
1294 +--------------+--------------+----------------+
1295 | 3 | Timer 1 | 0x001B |
1296 +--------------+--------------+----------------+
1297 | 4 | Serial | 0x0023 |
1298 +--------------+--------------+----------------+
1301 If the interrupt service routine is defined without a register
1302 bank or with register bank 0 (using 0), the compiler will
1303 save the registers used by itself on the stack (upon entry
1304 and restore them at exit), however if such an interrupt
1305 service routine calls another function then the entire register
1306 bank will be saved on the stack. This scheme may be advantageous
1307 for small interrupt service routines which have low register
1310 If the interrupt service routine is defined to be using a
1311 specific register bank then only "a","b"
1312 & "dptr" are save and restored, if such an interrupt
1313 service routine calls another function (using another register
1314 bank) then the entire register bank of the called function
1315 will be saved on the stack. This scheme is recommended for
1316 larger interrupt service routines.
1318 Calling other functions from an interrupt service routine
1319 is not recommended avoid it if possible.
1323 The compiler inserts a jump to the C routine _sdcc__external__startup()
1324 at the start of the CODE area. This routine can be found
1325 in the file SDCCDIR/sdcc51lib/_startup.c, by default this
1326 routine returns 0, if this routine returns a non-zero value
1327 , the static & global variable initialization will be skipped
1328 and the function main will be invoked, other wise static
1329 & global variables will be initialized before the function
1330 main is invoked. You could add a _sdcc__external__startup()
1331 routine to your program to override the default if you needed
1332 to setup hardware or perform some other critical operation
1333 prior to static & global variable initialization.
1335 3.11 Inline Assembler Code
1337 SDCC allows the use of in-line assembler with a few restriction
1338 as regards labels. All labels defined within inline assembler
1339 code HAS TO BE of the form nnnnn$ where nnnn is a number
1340 less than 100 (which implies a limit of utmost 100 inline
1341 assembler labels per function). It is strongly recommended
1342 that each assembly instruction (including labels) be placed
1343 in a separate line ( as the example shows). When the --peep-asm
1344 command line option is used, the inline assembler code will
1345 be passed through the peephole optimizer, this might cause
1346 some unexpected changes in the inline assembler code, please
1347 go throught the peephole optimizer rules defined in file
1348 'SDCCpeeph.def' carefully before using this option.
1358 The inline assembler code can contain any valid code understood
1359 by the assembler (this includes any assembler directives
1360 and comment lines ) . The compiler does not do any validation
1361 of the code within the _asm ... _endasm; keyword pair.
1363 Inline assembler code cannot reference any C-Labels however
1364 it can reference labels defined by the inline assembler.
1369 ... /* some c code */
1371 ; some assembler code
1374 ... /* some more c code */
1375 clabel: /* inline assembler cannot reference this
1378 $0003: ;label (can be reference by inline assembler
1384 In other words inline assembly code can access labels defined
1385 in inline assembly. The same goes the other way, ie. labels
1386 defines in inline assembly CANNOT be accessed by C statements.
1388 3.12 int(16 bit) and long (32 bit ) Support
1390 For signed & unsigned int (16 bit) and long (32 bit) variables,
1391 division, multiplication and modulus operations are implemented
1392 by support routines. These support routines are all developed
1393 in ANSI-C to facilitate porting to other MCUs. The following
1394 files contain the described routine, all of them can be
1395 found in the directory SDCCDIR/sdcc51lib
1397 * _mulsint.c - signed 16 bit multiplication (calls _muluint)
1399 * _muluint.c - unsigned 16 bit multiplication
1401 * _divsint.c - signed 16 bit division (calls _divuint)
1403 * _divuint.c - unsigned 16 bit division.
1405 * _modsint.c - signed 16 bit modulus (call _moduint)
1407 * _moduint.c - unsigned 16 bit modulus.
1409 * _mulslong.c - signed 32 bit multiplication (calls _mululong)
1411 * _mululong.c - unsigned32 bit multiplication.
1413 * _divslong.c - signed 32 division (calls _divulong)
1415 * _divulong.c - unsigned 32 division.
1417 * _modslong.c - signed 32 bit modulus (calls _modulong).
1419 * _modulong.c - unsigned 32 bit modulus.
1421 All these routines are compiled as non-reentrant and small
1422 model. Since they are compiled as non-reentrant, interrupt
1423 service routines should not do any of the above operations,
1424 if this unavoidable then the above routines will need to
1425 ne compiled with the --stack-auto option, after which the
1426 source program will have to be compiled with --int-long-rent
1429 3.13 Floating Point Support
1431 SDCC supports IEEE (single precision 4bytes) floating point
1432 numbers.The floating point support routines are derived
1433 from gcc's floatlib.c and consists of the following routines.
1435 * _fsadd.c - add floating point numbers.
1437 * _fssub.c - subtract floating point numbers
1439 * _fsdiv.c - divide floating point numbers
1441 * _fsmul.c - multiply floating point numbers
1443 * _fs2uchar.c - convert floating point to unsigned char
1445 * _fs2char.c - convert floating point to signed char.
1447 * _fs2uint.c - convert floating point to unsigned int.
1449 * _fs2int.c - convert floating point to signed int.
1451 * _fs2ulong.c - convert floating point to unsigned long.
1453 * _fs2long.c - convert floating point to signed long.
1455 * _uchar2fs.c - convert unsigned char to floating point
1457 * _char2fs.c - convert char to floating point number
1459 * _uint2fs.c - convert unsigned int to floating point
1461 * _int2fs.c - convert int to floating point numbers
1463 * _ulong2fs.c - convert unsigned long to floating point number
1465 * _long2fs.c - convert long to floating point number.
1467 Note if all these routines are used simultaneously the data
1468 space might overflow. For serious floating point usage it
1469 is strongly recommended that the Large model be used (in
1470 which case the floating point routines mentioned above will
1471 need to recompiled with the --model-Large option)
1473 3.14 MCS51 Memory Models
1475 SDCC allows two memory models for MCS51 code, small and large.
1476 Modules compiled with different memory models should never
1477 be combined together or the results would be unpredictable.
1478 The library routines supplied with the compiler are compiled
1479 as both small and large. The compiled library modules are
1480 contained in seperate directories as small and large so
1481 that you can link to either set. In general the use of the
1482 large model is discouraged.
1484 When the large model is used all variables declared without
1485 a storage class will be allocated into the external ram,
1486 this includes all parameters and local variables (for non-reentrant
1487 functions). When the small model is used variables without
1488 storage class are allocated in the internal ram.
1490 Judicious usage of the processor specific storage classes
1491 and the 'reentrant' function type will yield much more efficient
1492 code, than using the large-model. Several optimizations
1493 are disabled when the program is compiled using the large
1494 model, it is therefore strongly recommdended that the small
1495 model be used unless absolutely required.
1497 3.15 Flat 24 bit Addressing Model
1499 This option generates code for the 24 bit contiguous addressing
1500 mode of the Dallas DS80C390 part. In this mode, up to four
1501 meg of external RAM or code space can be directly addressed.
1502 See the data sheets at www.dalsemi.com for further information
1505 In older versions of the compiler, this option was used with
1506 the MCS51 code generator (-mmcs51). Now, however, the '390
1507 has it's own code generator, selected by the -mds390 switch.
1508 This code generator currently supports only the flat24 model,
1509 but the --model-flat24 switch is still required, in case
1510 later versions of the code generator support other models
1511 (such as the paged mode of the '390). The combination of
1512 -mmcs51 and --model-flat24 is now depracated.
1514 Note that the compiler does not generate any code to place
1515 the processor into24 bitmode (it defaults to 8051 compatible
1516 mode). Boot loader or similar code must ensure that the
1517 processor is in 24 bit contiguous addressing mode before
1518 calling the SDCC startup code.
1520 Like the --model-large option, variables will by default
1521 be placed into the XDATA segment.
1523 Segments may be placed anywhere in the 4 meg address space
1524 using the usual --*-loc options. Note that if any segments
1525 are located above 64K, the -r flag must be passed to the
1526 linker to generate the proper segment relocations, and the
1527 Intel HEX output format must be used. The -r flag can be
1528 passed to the linker by using the option -Wl-r on the sdcc
1531 3.16 Defines Created by the Compiler
1533 The compiler creates the following #defines .
1535 * SDCC - this Symbol is always defined.
1537 * SDCC_STACK_AUTO - this symbol is defined when --stack-auto
1540 * SDCC_MODEL_SMALL - when small model is used.
1542 * SDCC_MODEL_LARGE - when --model-large is used.
1544 * SDCC_USE_XSTACK - when --xstack option is used.
1546 4 SDCC Technical Data
1550 SDCC performs a a host of standard optimizations in addition
1551 to some MCU specific optimizations.
1553 4.1.1 Sub-expression Elimination
1555 The compiler does local and global common subexpression elimination.
1562 will be translated to
1568 Some subexpressions are not as obvious as the above example.
1575 In this case the address arithmetic a->b[i] will be computed
1576 only once; the equivalent code in C would be.
1582 The compiler will try to keep these temporary variables in
1585 4.1.2 Dead-Code Elimination
1592 i = 1; /* dead store
1594 global = 1; /* dead store */
1597 global = 3; /* unreachable */
1602 int global; void f ()
1608 4.1.3 Copy-Propagation
1628 Note: the dead stores created by this copy propagation will
1629 be eliminated by dead-code elimination .
1631 4.1.4 Loop Optimizations
1633 Two types of loop optimizations are done by SDCC loop invariant
1634 lifting and strength reduction of loop induction variables.In
1635 addition to the strength reduction the optimizer marks the
1636 induction variables and the register allocator tries to
1637 keep the induction variables in registers for the duration
1638 of the loop. Because of this preference of the register
1639 allocator , loop induction optimization causes an increase
1640 in register pressure, which may cause unwanted spilling
1641 of other temporary variables into the stack / data space
1642 . The compiler will generate a warning message when it is
1643 forced to allocate extra space either on the stack or data
1644 space. If this extra space allocation is undesirable then
1645 induction optimization can be eliminated either for the
1646 entire source file ( with --noinduction option) or for a
1647 given function only (#pragma NOINDUCTION).
1653 for (i = 0 ; i < 100 ; i ++)
1659 for ( i = 0; i < 100; i++ ) f += itemp;
1661 As mentioned previously some loop invariants are not as apparent,
1662 all static address computations are also moved out of the
1665 * Strength Reduction :
1667 This optimization substitutes an expression by a cheaper
1672 for (i=0;i < 100; i++) ar[i*5] = i*3;
1678 for (i=0;i< 100;i++) {
1679 ar[itemp1] = itemp2;
1684 The more expensive multiplication is changed to a less expensive
1687 4.1.5 Loop Reversing:
1689 This optimization is done to reduce the overhead of checking
1690 loop boundaries for every iteration. Some simple loops can
1691 be reversed and implemented using a "decrement
1692 and jump if not zero" instruction. SDCC
1693 checks for the following criterion to determine if a loop
1694 is reversible (note: more sophisticated compiers use data-dependency
1695 analysis to make this determination, SDCC uses a more simple
1698 * The 'for' loop is of the form
1699 "for ( <symbol> = <expression> ; <sym> [< | <=] <expression>
1700 ; [<sym>++ | <sym> += 1])
1703 * The <for body> does not contain "continue"
1706 * All goto's are contained within the loop.
1708 * No function calls within the loop.
1710 * The loop control variable <sym> is not assigned any value
1713 * The loop control variable does NOT participate in any arithmetic
1714 operation within the loop.
1716 * There are NO switch statements in the loop.
1718 Note djnz instruction can be used for 8-bit values ONLY,
1719 therefore it is advantageous to declare loop control symbols
1720 as either 'char' or 'short', ofcourse this may not be possible
1723 4.1.6 Algebraic Simplifications
1725 SDCC does numerous algebraic simplifications, the following
1726 is a small sub-set of these optimizations.
1729 i = j + 0 ; /* changed to */ i = j;
1730 i /= 2; /* changed to */ i >>= 1;
1731 i = j - j ; /* changed to */ i = 0;
1732 i = j / 1 ; /* changed to */ i = j;
1734 Note the subexpressions given above are generally introduced
1735 by macro expansions or as a result of copy/constant propagation.
1737 4.1.7 'switch' Statements
1739 SDCC changes switch statements to jump tables when the following
1740 conditions are true.
1742 * The case labels are in numerical sequence , the labels
1743 need not be in order, and the starting number need not
1767 Both the above switch statements will be implemented using
1770 * The number of case labels is at least three, since it takes
1771 two conditional statements to handle the boundary conditions.
1773 * The number of case labels is less than 84, since each label
1774 takes 3 bytes and a jump-table can be utmost 256 bytes
1777 Switch statements which have gaps in the numeric sequence
1778 or those that have more that 84 case labels can be split
1779 into more than one switch statement for efficient code generation.
1794 If the above switch statement is broken down into two switch
1811 then both the switch statements will be implemented using
1812 jump-tables whereas the unmodified switch statement will
1815 4.1.8 Bit-shifting Operations.
1817 Bit shifting is one of the most frequently used operation
1818 in embedded programming . SDCC tries to implement bit-shift
1819 operations in the most efficient way possible.
1829 generates the following code.
1836 In general SDCC will never setup a loop if the shift count
1837 is known. Another example
1852 Note that SDCC stores numbers in little-endian format (i.e.
1857 A special case of the bit-shift operation is bit rotation,
1858 SDCC recognizes the following expression to be a left bit-rotation.
1862 i = ( ( i << 1) | ( i >> 7));
1865 will generate the following code.
1871 SDCC uses pattern matching on the parse tree to determine
1872 this operation .Variations of this case will also be recognized
1873 as bit-rotation i.e i = ((i >> 7) | (i << 1)); /* left-bit
1876 4.1.10 Highest Order Bit
1878 It is frequently required to obtain the highest order bit
1879 of an integral type (int,long,short or char types). SDCC
1880 recognizes the following expression to yield the highest
1881 order bit and generates optimized code for it.
1888 hob = (gint >> 15) & 1;
1892 Will generate the following code.
1912 Variations of this case however will NOT be recognized .
1913 It is a standard C expression , so I heartily recommend
1914 this be the only way to get the highest order bit, (it is
1915 portable). Of course it will be recognized even if it is
1916 embedded in other expressions.
1920 xyz = gint + ((gint >> 15) & 1);
1922 will still be recognized.
1924 4.1.11 Peep-hole Optimizer
1926 The compiler uses a rule based , pattern matching and re-writing
1927 mechanism for peep-hole optimization . It is inspired by
1928 'copt' a peep-hole optimizer by Christopher W. Fraser (cwfraser@microsoft.com).
1929 A default set of rules are compiled into the compiler, additional
1930 rules may be added with the --peep-file <filename> option.
1931 The rule language is best illustrated with examples.
1935 mov a,%1 } by { mov %1,a }
1937 The above rule will the following assembly sequence
1946 Note: All occurrences of a '%n' ( pattern variable ) must
1947 denote the same string. With the above rule, the assembly
1953 will remain unmodified. Other special case optimizations
1954 may be added by the user (via --peep-file option), eg. some
1955 variants of the 8051 MCU allow only 'AJMP' and 'ACALL' ,
1956 the following two rules will change all 'LJMP' & 'LCALL'
1957 to 'AJMP' & 'ACALL'.
1959 replace { lcall %1 } by { acall %1 }
1960 replace { ljmp %1 } by { ajmp %1 }
1962 The inline-assembler' code is also passed through the peep
1963 hole optimizer, thus the peephole optimizer can also be
1964 used as an assembly level macro expander. The rules themselves
1965 are MCU dependent whereas the rule language infra-structure
1966 is MCU independent. Peephole optimization rules for other
1967 MCU can be easily programmed using the rule language.
1969 The syntax for a rule is as follows ,
1971 rule := replace [ restart ] '{' <assembly sequence> '\n'
1977 <assembly sequence> '\n'
1979 '}' [if <functionName>
1981 <assembly sequence> := assembly instruction (each instruction
1982 including labels must be on a separate line).
1984 The optimizer will apply to the rules one by one from the
1985 top in the sequence of their appearance, it will terminate
1986 when all rules are exhausted. If the 'restart' option is
1987 specified, then the optimizer will start matching the rules
1988 again from the top, this option for a rule is expensive
1989 (performance), it is intended to be used in situations where
1990 a transformation will trigger the same rule again. A good
1991 example of this the following rule.
1999 Note that the replace pattern cannot be a blank, but can
2000 be a comment line. Without the 'restart' option only the
2001 inner most 'pop' 'push' pair would be eliminated. i.e.
2014 with the 'restart' option the rule will be applied again
2015 to the resulting code and the all the 'pop' 'push' pairs
2016 will be eliminated to yield
2021 A conditional function can be attached to a rule. Attaching
2022 rules are somewhat more involved, let me illustrate this
2029 %2:} if labelInRange
2031 The optimizer does a look-up of a function name table defined
2032 in function 'callFuncByName' in the source file SDCCpeeph.c
2033 , with the name 'labelInRange', if it finds a corresponding
2034 entry the function is called. Note there can be no parameters
2035 specified for these functions, in this case the use of '%5'
2036 is crucial, since the function labelInRange expects to find
2037 the label in that particular variable (the hash table containing
2038 the variable bindings is passed as a parameter). If you
2039 want to code more such functions , take a close look at
2040 the function labelInRange and the calling mechanism in source
2041 file SDCCpeeph.c. I know this whole thing is a little kludgey
2042 , may be some day we will have some better means. If you
2043 are looking at this file, you will also see the default
2044 rules that are compiled into the compiler, you can your
2045 own rules in the default set there if you get tired of specifying
2046 the --peep-file option.
2050 SDCC supports the following #pragma directives. This directives
2051 are applicable only at a function level.
2053 * SAVE - this will save all the current options .
2055 * RESTORE - will restore the saved options from the last
2056 save. Note that SAVES & RESTOREs cannot be nested. SDCC
2057 uses the same buffer to save the options each time a SAVE
2060 * NOGCSE - will stop global subexpression elimination.
2062 * NOINDUCTION - will stop loop induction optimizations .
2064 * NOJTBOUND - will not generate code for boundary value checking
2065 , when switch statements are turned into jump-tables.
2067 * NOOVERLAY - the compiler will not overlay the parameters
2068 and local variables of a function.
2070 * NOLOOPREVERSE - Will not do loop reversal optimization
2072 * EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma
2073 disables generation of pair of push/pop instruction in
2074 ISR function (using interrupt keyword). The directive
2075 should be placed immediately before the ISR function definition
2076 and it affects ALL ISR functions following it. To enable
2077 the normal register saving for ISR functions use "#pragma
2080 * CALLEE-SAVES function1[,function2[,function3...]] - The
2081 compiler by default uses a caller saves convention for
2082 register saving across function calls, however this can
2083 cause unneccessary register pushing & popping when calling
2084 small functions from larger functions. This option can
2085 be used to switch the register saving convention for the
2086 function names specified. The compiler will not save registers
2087 when calling these functions, extra code will be generated
2088 at the entry & exit for these functions to save & restore
2089 the registers used by these functions, this can SUBSTANTIALLY
2090 reduce code & improve run time performance of the generated
2091 code. In future the compiler (with interprocedural analysis)
2092 will be able to determine the appropriate scheme to use
2093 for each function call. If --callee-saves command line
2094 option is used, the function names specified in #pragma
2095 CALLEE-SAVES is appended to the list of functions specified
2098 The pragma's are intended to be used to turn-off certain
2099 optimizations which might cause the compiler to generate
2100 extra stack / data space to store compiler generated temporary
2101 variables. This usually happens in large functions. Pragma
2102 directives should be used as shown in the following example,
2103 they are used to control options & optimizations for a given
2104 function; pragmas should be placed before and/or after a
2105 function, placing pragma's inside a function body could
2106 have unpredictable results.
2110 #pragma SAVE /* save the current settings
2112 #pragma NOGCSE /* turnoff global subexpression elimination
2114 #pragma NOINDUCTION /* turn off induction optimizations */
2122 #pragma RESTORE /* turn the optimizations back on */
2124 The compiler will generate a warning message when extra space
2125 is allocated. It is strongly recommended that the SAVE and
2126 RESTORE pragma's be used when changing options for a function.
2128 4.3 Library Routines
2130 The following library routines are provided for your convenience.
2132 stdio.h - Contains the following functions printf & sprintf
2133 these routines are developed by Martijn van Balen <balen@natlab.research.philips.com>.
2135 %[flags][width][b|B|l|L]type
2138 - left justify output
2139 in specified field width
2141 + prefix output with
2142 +/- sign if output is signed type
2144 space prefix output with a blank if
2145 it's a signed positive value
2147 specifies minimum number of characters outputted for numbers
2152 - For numbers, spaces are added on the left when needed.
2155 If width starts with a zero character, zeroes and used
2159 - For strings, spaces are are added on the left or right
2162 flag '-' is used) when needed.
2166 byte argument (used by d, u, o, x, X)
2168 long argument (used by d, u, o, x, X)
2172 u unsigned decimal number
2175 o unsigned octal number
2178 x unsigned hexadecimal
2181 X unsigned hexadecimal
2186 s string (generic pointer)
2189 p generic pointer (I:data/idata,
2190 C:code, X:xdata, P:paged)
2192 f float (still to be
2195 Also contains a very simple version of printf (printf_small).
2196 This simplified version of printf supports only the following
2199 format output type argument-type
2205 %hd decimal short/char
2209 %lx hexadecimal long
2211 %hx hexadecimal short/char
2217 %ho octal short/char
2219 %c character char/short
2221 %s character _generic
2224 The routine is very stack intesive , --stack-after-data parameter
2225 should be used when using this routine, the routine also
2226 takes about 1K of code space .It also expects an external
2227 function named putchar(char ) to be present (this can be
2228 changed). When using the %s format the string / pointer
2229 should be cast to a generic pointer. eg.
2231 printf_small("my str %s, my int %d\n",(char
2232 _generic *)mystr,myint);
2234 * stdarg.h - contains definition for the following macros
2235 to be used for variable parameter list, note that a function
2236 can have a variable parameter list if and only if it is
2239 va_list, va_start, va_arg, va_end.
2241 * setjmp.h - contains defintion for ANSI setjmp & longjmp
2242 routines. Note in this case setjmp & longjmp can be used
2243 between functions executing within the same register bank,
2244 if long jmp is executed from a function that is using
2245 a different register bank from the function issuing the
2246 setjmp function, the results may be unpredictable. The
2247 jump buffer requires 3 bytes of data (the stack pointer
2248 & a 16 byte return address), and can be placed in any
2251 * stdlib.h - contains the following functions.
2255 * string.h - contains the following functions.
2257 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr,
2258 strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok,
2259 memcpy, memcmp, memset.
2261 * ctype.h - contains the following routines.
2263 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct,
2264 isspace, isxdigit, isalnum, isalpha.
2266 * malloc.h - The malloc routines are developed by Dmitry
2267 S. Obukhov (dso@usa.net). These routines will allocate
2268 memory from the external ram. Here is a description on
2269 how to use them (as described by the author).
2273 #define DYNAMIC_MEMORY_SIZE 0x2000
2277 unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
2280 unsigned char xdata * current_buffer;
2290 init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
2293 //Now it's possible to use malloc.
2297 current_buffer = malloc(0x100);
2300 * serial.h - Serial IO routines are also developed by Dmitry
2301 S. Obukhov (dso@usa.net). These routines are interrupt
2302 driven with a 256 byte circular buffer, they also expect
2303 external ram to be present. Please see documentation in
2304 file SDCCDIR/sdcc51lib/serial.c . Note the header file
2305 "serial.h" MUST be included in the file containing
2306 the 'main' function.
2308 * ser.h - Alternate serial routine provided by Wolfgang Esslinger
2309 <wolfgang@WiredMinds.com> these routines are more compact
2310 and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
2312 * ser_ir.h - Another alternate set of serial routines provided
2313 by Josef Wolf <jw@raven.inka.de> , these routines do not
2314 use the external ram.
2316 * reg51.h - contains register definitions for a standard
2319 * reg552.h - contains register definitions for 80C552.
2321 * float.h - contains min, max and other floating point related
2324 All library routines are compiled as --model-small , they
2325 are all non-reentrant, if you plan to use the large model
2326 or want to make these routines reentrant, then they will
2327 have to be recompiled with the appropriate compiler option.
2329 Have not had time to do the more involved routines like printf,
2330 will get to them shortly.
2332 4.4 Interfacing with Assembly Routines
2334 4.5 Global Registers used for Parameter Passing
2336 By default the compiler uses the global registers "DPL,DPH,B,ACC"
2337 to pass the first parameter to a routine, the second parameter
2338 onwards is either allocated on the stack (for reentrant
2339 routines or --stack-auto is used) or in the internal / external
2340 ram (depending on the memory model).
2342 4.5.1 Assembler Routine(non-reentrant)
2344 In the following example the function cfunc calls an assembler
2345 routine asm_func, which takes two parameters.
2347 extern int asm_func( unsigned short, unsigned short);
2350 int c_func (unsigned short i, unsigned short j)
2352 return asm_func(i,j);
2356 return c_func(10,9);
2359 The corresponding assembler function is:-
2361 .globl _asm_func_PARM_2
2378 Note here that the return values are placed in 'dpl' - One
2379 byte return value, 'dpl' LSB & 'dph' MSB for two byte values.
2380 'dpl', 'dph' and 'b' for three byte values (generic pointers)
2381 and 'dpl','dph','b' & 'acc' for four byte values.
2383 The parameter naming convention is _<function_name>_PARM_<n>,
2384 where n is the parameter number starting from 1, and counting
2385 from the left. The first parameter is passed in "dpl"
2386 for One bye parameter, "dptr"
2387 if two bytes, "b,dptr"
2388 for three bytes and "acc,b,dptr"
2389 for four bytes, the varaible name for the second parameter
2390 will be _<function_name>_PARM_2.
2392 Assemble the assembler routine with the following command.
2394 asx8051 -losg asmfunc.asm
2396 Then compile and link the assembler routine to the C source
2397 file with the following command,
2399 sdcc cfunc.c asmfunc.rel
2401 4.5.2 Assembler Routine(reentrant)
2403 In this case the second parameter onwards will be passed
2404 on the stack , the parameters are pushed from right to left
2405 i.e. after the call the left most parameter will be on the
2406 top of the stack. Here is an example.
2408 extern int asm_func( unsigned short, unsigned short);
2412 int c_func (unsigned short i, unsigned short j) reentrant
2415 return asm_func(i,j);
2419 return c_func(10,9);
2422 The corresponding assembler routine is.
2443 The compiling and linking procedure remains the same, however
2444 note the extra entry & exit linkage required for the assembler
2445 code, _bp is the stack frame pointer and is used to compute
2446 the offset into the stack for parameters and local variables.
2448 4.6 With --noregparms Option
2450 When the source is compiled with --noregparms option , space
2451 is allocated for each of the parameters passed to a routine.
2453 4.6.1 Assembler Routine Non-reentrant
2455 In the following example the function cfunc calls an assembler
2456 routine asm_func, which takes two parameters.
2458 extern int asm_func( unsigned short, unsigned short);
2461 int c_func (unsigned short i, unsigned short j)
2463 return asm_func(i,j);
2467 return c_func(10,9);
2470 The corresponding assembler function is:-
2472 .globl _asm_func_PARM_1
2473 .globl _asm_func_PARM_2
2492 Note here that the return values are placed in 'dpl' - One
2493 byte return value, 'dpl' LSB & 'dph' MSB for two byte values.
2494 'dpl', 'dph' and 'b' for three byte values (generic pointers)
2495 and 'dpl','dph','b' & 'acc' for four byte values.
2497 The parameter naming convention is _<function_name>_PARM_<n>,
2498 where n is the parameter number starting from 1, and counting
2499 from the left. i.e. the left-most parameter name will be
2500 _<function_name>_PARM_1.
2502 Assemble the assembler routine with the following command.
2504 asx8051 -losg asmfunc.asm
2506 Then compile and link the assembler routine to the C source
2507 file with the following command,
2509 sdcc cfunc.c asmfunc.rel
2511 4.6.2 Assembler Routine(reentrant)
2513 In this case the parameters will be passed on the stack ,
2514 the parameters are pushed from right to left i.e. after
2515 the call the left most parameter will be on the top of the
2516 stack. Here is an example.
2518 extern int asm_func( unsigned short, unsigned short);
2522 int c_func (unsigned short i, unsigned short j) reentrant
2525 return asm_func(i,j);
2529 return c_func(10,9);
2532 The corresponding assembler routine is.
2554 The compiling and linking procedure remains the same, however
2555 note the extra entry & exit linkage required for the assembler
2556 code, _bp is the stack frame pointer and is used to compute
2557 the offset into the stack for parameters and local variables.
2561 The external stack is located at the start of the external
2562 ram segment , and is 256 bytes in size. When --xstack option
2563 is used to compile the program, the parameters and local
2564 variables of all reentrant functions are allocated in this
2565 area. This option is provided for programs with large stack
2566 space requirements. When used with the --stack-auto option,
2567 all parameters and local variables are allocated on the
2568 external stack (note support libraries will need to be recompiled
2569 with the same options).
2571 The compiler outputs the higher order address byte of the
2572 external ram segment into PORT P2, therefore when using
2573 the External Stack option, this port MAY NOT be used by
2574 the application program.
2578 Deviations from the compliancy.
2580 1. functions are not always reentrant.
2582 2. structures cannot be assigned values directly, cannot be
2583 passed as function parameters or assigned to each other
2584 and cannot be a return value from a function.
2593 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI
2598 struct s foo1 (struct s parms) /* is invalid in SDCC although
2603 return rets;/* is invalid in SDCC although allowed in ANSI
2607 1. 'long long' (64 bit integers) not supported.
2609 2. 'double' precision floating point not supported.
2611 3. integral promotions are suppressed. What does this mean
2612 ? The compiler will not implicitly promote an integer
2613 expression to a higher order integer, exception is an
2614 assignment or parameter passing.
2616 4. No support for setjmp and longjmp (for now).
2618 5. Old K&R style function declarations are NOT allowed.
2620 foo( i,j) /* this old style of function declarations */
2621 int i,j; /* are valid in ANSI .. not valid in SDCC */
2626 1. functions declared as pointers must be dereferenced during
2632 /* has to be called like this */
2633 (*foo)();/* ansi standard allows calls to be made like
2636 4.9 Cyclomatic Complexity
2638 Cyclomatic complexity of a function is defined as the number
2639 of independent paths the program can take during execution
2640 of the function. This is an important number since it defines
2641 the number test cases you have to generate to validate the
2642 function . The accepted industry standard for complexity
2643 number is 10, if the cyclomatic complexity reported by SDCC
2644 exceeds 10 you should think about simplification of the
2647 Note that the complexity level is not related to the number
2648 of lines of code in a function. Large functions can have
2649 low complexity, and small functions can have large complexity
2650 levels. SDCC uses the following formula to compute the complexity.
2652 complexity = (number of edges in control flow graph) -
2654 of nodes in control flow graph) + 2;
2656 Having said that the industry standard is 10, you should
2657 be aware that in some cases it may unavoidable to have a
2658 complexity level of less than 10. For example if you have
2659 switch statement with more than 10 case labels, each case
2660 label adds one to the complexity level. The complexity level
2661 is by no means an absolute measure of the algorithmic complexity
2662 of the function, it does however provide a good starting
2663 point for which functions you might look at for further
2668 Here are a few guide-lines that will help the compiler generate
2669 more efficient code, some of the tips are specific to this
2670 compiler others are generally good programming practice.
2672 * Use the smallest data type to represent your data-value.
2673 If it is known in advance that the value is going to be
2674 less than 256 then use a 'short' or 'char' instead of
2677 * Use unsigned when it is known in advance that the value
2678 is not going to be negative. This helps especially if
2679 you are doing division or multiplication.
2681 * NEVER jump into a LOOP.
2683 * Declare the variables to be local whenever possible, especially
2684 loop control variables (induction).
2686 * Since the compiler does not do implicit integral promotion,
2687 the programmer should do an explicit cast when integral
2688 promotion is required.
2690 * Reducing the size of division , multiplication & modulus
2691 operations can reduce code size substantially. Take the
2692 following code for example.
2694 foobar( unsigned int p1, unsigned char ch)
2696 unsigned char ch1 = p1 % ch ;
2700 For the modulus operation the variable ch will be promoted
2701 to unsigned int first then the modulus operation will
2702 be performed (this will lead to a call to a support routine).
2703 If the code is changed to
2705 foobar( unsigned int p1, unsigned char ch)
2707 unsigned char ch1 = (unsigned char)p1
2712 It would substantially reduce the code generated (future
2713 versions of the compiler will be smart enough to detect
2714 such optimization oppurtunities).
2716 Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
2718 The 8051 family of micro controller have a minimum of 128
2719 bytes of internal memory which is structured as follows
2721 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers
2724 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
2726 - Bytes 30-7F - 60 bytes for general purpose use.
2728 Normally the SDCC compiler will only utilise the first bank
2729 of registers, but it is possible to specify that other banks
2730 of registers should be used in interrupt routines. By default,
2731 the compiler will place the stack after the last bank of
2732 used registers, i.e. if the first 2 banks of registers are
2733 used, it will position the base of the internal stack at
2734 address 16 (0X10). This implies that as the stack grows,
2735 it will use up the remaining register banks, and the 16
2736 bytes used by the 128 bit variables, and 60 bytes for general
2739 By default, the compiler uses the 60 general purpose bytes
2740 to hold "near data". The compiler/optimiser may also declare
2741 some Local Variables in this area to hold local data.
2743 If any of the 128 bit variables are used, or near data is
2744 being used then care needs to be taken to ensure that the
2745 stack does not grow so much that it starts to over write
2746 either your bit variables or "near data". There is no runtime
2747 checking to prevent this from happening.
2749 The amount of stack being used is affected by the use of
2750 the "internal stack" to save registers before a subroutine
2751 call is made, - --stack-auto will declare parameters and
2752 local variables on the stack - the number of nested subroutines.
2754 If you detect that the stack is over writing you data, then
2755 the following can be done. --xstack will cause an external
2756 stack to be used for saving registers and (if --stack-auto
2757 is being used) storing parameters and local variables. However
2758 this will produce more and code which will be slower to
2761 --stack-loc will allow you specify the start of the stack,
2762 i.e. you could start it after any data in the general purpose
2763 area. However this may waste the memory not used by the
2764 register banks and if the size of the "near data" increases,
2765 it may creep into the bottom of the stack.
2767 --stack-after-data, similar to the --stack-loc, but it automatically
2768 places the stack after the end of the "near data". Again
2769 this could waste any spare register space.
2771 --data-loc allows you to specify the start address of the
2772 near data. This could be used to move the "near data" further
2773 away from the stack giving it more room to grow. This will
2774 only work if no bit variables are being used and the stack
2775 can grow to use the bit variable space.
2779 If you find that the stack is over writing your bit variables
2780 or "near data" then the approach which best utilised the
2781 internal memory is to position the "near data" after the
2782 last bank of used registers or, if you use bit variables,
2783 after the last bit variable by using the --data-loc, e.g.
2784 if two register banks are being used and no data variables,
2785 --data-loc 16, and - use the --stack-after-data option.
2787 If bit variables are being used, another method would be
2788 to try and squeeze the data area in the unused register
2789 banks if it will fit, and start the stack after the last
2792 6 Retargetting for other MCUs.
2794 The issues for retargetting the compiler are far too numerous
2795 to be covered by this document. What follows is a brief
2796 description of each of the seven phases of the compiler
2797 and its MCU dependency.
2799 1. Parsing the source and building the annotated parse tree.
2800 This phase is largely MCU independent (except for the
2801 language extensions). Syntax & semantic checks are also
2802 done in this phase , along with some initial optimizations
2803 like back patching labels and the pattern matching optimizations
2804 like bit-rotation etc.
2806 2. The second phase involves generating an intermediate code
2807 which can be easy manipulated during the later phases.
2808 This phase is entirely MCU independent. The intermediate
2809 code generation assumes the target machine has unlimited
2810 number of registers, and designates them with the name
2811 iTemp. The compiler can be made to dump a human readable
2812 form of the code generated by using the --dumpraw option.
2814 3. This phase does the bulk of the standard optimizations
2815 and is also MCU independent. This phase can be broken
2816 down into several sub-phases.
2818 * Break down intermediate code (iCode) into basic blocks.
2820 * Do control flow & data flow analysis on the basic blocks.
2822 * Do local common subexpression elimination, then global
2823 subexpression elimination
2825 * dead code elimination
2827 * loop optimizations
2829 * if loop optimizations caused any changes then do 'global
2830 subexpression elimination' and 'dead code elimination'
2833 4. This phase determines the live-ranges; by live range I
2834 mean those iTemp variables defined by the compiler that
2835 still survive after all the optimizations. Live range
2836 analysis is essential for register allocation, since these
2837 computation determines which of these iTemps will be assigned
2838 to registers, and for how long.
2840 5. Phase five is register allocation. There are two parts
2843 (a) The first part I call 'register packing' (for lack of
2844 a better term) . In this case several MCU specific expression
2845 folding is done to reduce register pressure.
2847 (b) The second part is more MCU independent and deals with
2848 allocating registers to the remaining live ranges. A
2849 lot of MCU specific code does creep into this phase
2850 because of the limited number of index registers available
2853 6. The Code generation phase is (unhappily), entirely MCU
2854 dependent and very little (if any at all) of this code
2855 can be reused for other MCU. However the scheme for allocating
2856 a homogenized assembler operand for each iCode operand
2859 7. As mentioned in the optimization section the peep-hole
2860 optimizer is rule based system, which can reprogrammed
2863 7 SDCDB - Source Level Debugger
2865 SDCC is distributed with a source level debugger. The debugger
2866 uses a command line interface, the command repertoire of
2867 the debugger has been kept as close to gdb ( the GNU debugger)
2868 as possible. The configuration and build process is part
2869 of the standard compiler installation, which also builds
2870 and installs the debugger in the target directory specified
2871 during configuration. The debugger allows you debug BOTH
2872 at the C source and at the ASM source level.
2874 7.1 Compiling for Debugging
2876 The --debug option must be specified for all files for which
2877 debug information is to be generated. The complier generates
2878 a .cdb file for each of these files. The linker updates
2879 the .cdb file with the address information. This .cdb is
2880 used by the debugger .
2882 7.2 How the Debugger Works
2884 When the --debug option is specified the compiler generates
2885 extra symbol information some of which are put into the
2886 the assembler source and some are put into the .cdb file,
2887 the linker updates the .cdb file with the address information
2888 for the symbols. The debugger reads the symbolic information
2889 generated by the compiler & the address information generated
2890 by the linker. It uses the SIMULATOR (Daniel's S51) to execute
2891 the program, the program execution is controlled by the
2892 debugger. When a command is issued for the debugger, it
2893 translates it into appropriate commands for the simulator .
2895 7.3 Starting the Debugger
2897 The debugger can be started using the following command line.
2898 (Assume the file you are debugging has
2904 The debugger will look for the following files.
2906 1. foo.c - the source file.
2908 2. foo.cdb - the debugger symbol information file.
2910 3. foo.ihx - the intel hex format object file.
2912 7.4 Command Line Options.
2914 * --directory=<source file directory> this option can used
2915 to specify the directory search list. The debugger will
2916 look into the directory list specified for source , cdb
2917 & ihx files. The items in the directory list must be separated
2918 by ':' , e.g. if the source files can be in the directories
2919 /home/src1 and /home/src2, the --directory option should
2920 be --directory=/home/src1:/home/src2 . Note there can
2921 be no spaces in the option.
2923 * -cd <directory> - change to the <directory>.
2925 * -fullname - used by GUI front ends.
2927 * -cpu <cpu-type> - this argument is passed to the simulator
2928 please see the simulator docs for details.
2930 * -X <Clock frequency > this options is passed to the simulator
2931 please see simulator docs for details.
2933 * -s <serial port file> passed to simulator see simulator
2936 * -S <serial in,out> passed to simulator see simulator docs
2939 7.5 Debugger Commands.
2941 As mention earlier the command interface for the debugger
2942 has been deliberately kept as close the GNU debugger gdb
2943 , as possible, this will help int integration with existing
2944 graphical user interfaces (like ddd, xxgdb or xemacs) existing
2945 for the GNU debugger.
2947 7.5.1 break [line | file:line | function | file:function]
2949 Set breakpoint at specified line or function.
2952 sdcdb>break foo.c:100
2954 sdcdb>break foo.c:funcfoo
2956 7.5.2 clear [line | file:line | function | file:function ]
2958 Clear breakpoint at specified line or function.
2961 sdcdb>clear foo.c:100
2963 sdcdb>clear foo.c:funcfoo
2967 Continue program being debugged, after breakpoint.
2971 Execute till the end of the current function.
2975 Delete breakpoint number 'n'. If used without any option
2976 clear ALL user defined break points.
2978 7.5.6 info [break | stack | frame | registers ]
2980 * info break - list all breakpoints
2982 * info stack - show the function call stack.
2984 * info frame - show information about the current execution
2987 * info registers - show content of all registers.
2991 Step program until it reaches a different source line.
2995 Step program, proceeding through subroutine calls.
2999 Start debugged program.
3001 7.5.10 ptype variable
3003 Print type information of the variable.
3005 7.5.11 print variable
3007 print value of variable.
3009 7.5.12 file filename
3011 load the given file name. Note this is an alternate method
3012 of loading file for debugging.
3016 print information about current frame.
3020 Toggle between C source & assembly source.
3022 7.5.15 ! simulator command
3024 Send the string following '!' to the simulator, the simulator
3025 response is displayed. Note the debugger does not interpret
3026 the command being sent to the simulator, so if a command
3027 like 'go' is sent the debugger can loose its execution context
3028 and may display incorrect values.
3032 "Watch me now. Iam going Down. My name is Bobby Brown"
3034 7.6 Interfacing with XEmacs.
3036 Two files are (in emacs lisp) are provided for the interfacing
3037 with XEmacs, sdcdb.el and sdcdbsrc.el. These two files can
3038 be found in the $(prefix)/bin directory after the installation
3039 is complete. These files need to be loaded into XEmacs for
3040 the interface to work, this can be done at XEmacs startup
3041 time by inserting the following into your '.xemacs' file
3042 (which can be found in your HOME directory) (load-file sdcdbsrc.el)
3043 [ .xemacs is a lisp file so the () around the command is
3044 REQUIRED), the files can also be loaded dynamically while
3045 XEmacs is running, set the environment variable 'EMACSLOADPATH'
3046 to the installation bin directory [$(prefix)/bin], then
3047 enter the following command ESC-x load-file sdcdbsrc . To
3048 start the interface enter the following command ESC-x sdcdbsrc
3049 , you will prompted to enter the file name to be debugged.
3051 The command line options that are passed to the simulator
3052 directly are bound to default values in the file sdcdbsrc.el
3053 the variables are listed below these values maybe changed
3056 * sdcdbsrc-cpu-type '51
3058 * sdcdbsrc-frequency '11059200
3060 * sdcdbsrc-serial nil
3062 The following is a list of key mapping for the debugger interface.
3065 ;; Current Listing ::
3066 ;;key binding Comment
3068 ;;--- ------- -------
3072 sdcdb-next-from-src SDCDB
3075 sdcdb-back-from-src SDCDB
3078 sdcdb-cont-from-src SDCDB
3081 sdcdb-step-from-src SDCDB
3084 sdcdb-whatis-c-sexp SDCDB
3085 ptypecommand for data at
3089 sdcdbsrc-delete SDCDB
3090 Delete all breakpoints if no arg
3092 or delete arg (C-u arg x)
3094 sdcdbsrc-frame SDCDB
3095 Display current frame if no arg,
3097 or display frame arg
3101 sdcdbsrc-goto-sdcdb Goto
3102 the SDCDB output buffer
3104 sdcdb-print-c-sexp SDCDB
3105 print command for data at
3109 sdcdbsrc-goto-sdcdb Goto
3110 the SDCDB output buffer
3112 sdcdbsrc-mode Toggles
3113 Sdcdbsrc mode (turns it off)
3116 sdcdb-finish-from-src SDCDB
3121 break for line with point
3123 sdcdbsrc-mode Toggle
3133 8.1 The Z80 and gbz80 port
3135 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's
3136 Z80-like gbz80. The port is incomplete - long support is
3137 incomplete (mul, div and mod are unimplimented), and both
3138 float and bitfield support is missing, but apart from that
3139 the code generated is correct.
3141 As always, the code is the authoritave reference - see z80/ralloc.c
3142 and z80/gen.c. The stack frame is similar to that generated
3143 by the IAR Z80 compiler. IX is used as the base pointer,
3144 HL is used as a temporary register, and BC and DE are available
3145 for holding varibles. IY is currently unusued. Return values
3146 are stored in HL. One bad side effect of using IX as the
3147 base pointer is that a functions stack frame is limited
3148 to 127 bytes - this will be fixed in a later version.
3152 SDCC has grown to be large project, the compiler alone (without
3153 the Assembler Package, Preprocessor) is about 40,000 lines
3154 of code (blank stripped). The open source nature of this
3155 project is a key to its continued growth and support. You
3156 gain the benefit and support of many active software developers
3157 and end users. Is SDCC perfect? No, that's why we need your
3158 help. The developers take pride in fixing reported bugs.
3159 You can help by reporting the bugs and helping other SDCC
3160 users. There are lots of ways to contribute, and we encourage
3161 you to take part in making SDCC a great software package.
3165 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
3166 or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed
3167 ASAP. When reporting a bug, it is very useful to include
3168 a small test program which reproduces the problem. If you
3169 can isolate the problem by looking at the generated assembly
3170 code, this can be very helpful. Compiling your program with
3171 the --dumpall option can sometimes be useful in locating
3172 optimization problems.
3176 Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler,
3177 MCS51 code generator, Debugger, AVR port
3178 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version
3180 John Hartman (jhartman@compuserve.com) - Porting ASXXX &
3182 Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
3184 Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his
3186 Malini Dutta(malini_dutta@hotmail.com) - my wife for her
3187 patience and support.
3188 Unknown - for the GNU C - preprocessor.
3189 Michael Hope - The Z80 and Z80GB port, 186 development
3190 Kevin Vigor - The DS390 port.
3191 Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
3192 Scott Datallo - PIC port.
3193 (Thanks to all the other volunteer developers who have helped
3194 with coding, testing, web-page creation, distribution sets,
3195 etc. You know who you are :-)
3198 This document initially written by Sandeep Dutta
3200 All product names mentioned herein may be trademarks of their
3201 respective companies.