3 lSDCC Compiler User Guide
10 1.3 Typographic conventions
11 1.4 Pending: compatibilaty with previous versions
12 1.5 System Requirements
15 2.1 Linux/Unix Installation
16 2.2 Windows Installation
17 2.2.1 Windows Install Using a Binary Package
18 2.2.2 Windows Install Using Cygwin
19 2.3 Testing out the SDCC Compiler
20 2.4 Install Trouble-shooting
21 2.4.1 SDCC cannot find libraries or header files.
22 2.4.2 SDCC does not compile correctly.
23 2.4.3 What the ./configure does
24 2.4.4 What the make does.
25 2.4.5 What the make install command does.
26 2.5 Additional Information for Windows Users
27 2.5.1 Getting started with Cygwin
28 2.5.2 Running SDCC as Native Compiled Executables
29 2.6 SDCC on Other Platforms
30 2.7 Advanced Install Options
31 2.8 Components of SDCC
32 2.8.1 sdcc - The Compiler
33 2.8.2 sdcpp (C-Preprocessor)
34 2.8.3 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 (The Assemblers and Linkage Editors)
36 2.8.5 sdcdb - Source Level Debugger
39 3.1.1 Single Source File Projects
40 3.1.2 Projects with Multiple Source Files
41 3.1.3 Projects with Additional Libraries
42 3.2 Command Line Options
43 3.2.1 Processor Selection Options
44 3.2.2 Preprocessor Options
48 3.2.6 Optimization Options
50 3.2.8 Intermediate Dump Options
51 3.3 MCS51/DS390 Storage Class Language Extensions
58 3.5 Parameters & Local Variables
60 3.7 Interrupt Service Routines
61 3.8 Critical Functions
63 3.10 Functions using private banks
64 3.11 Absolute Addressing
66 3.13 Inline Assembler Code
67 3.14 int(16 bit) and long (32 bit) Support
68 3.15 Floating Point Support
69 3.16 MCS51 Memory Models
70 3.17 DS390 Memory Models
71 3.18 Defines Created by the Compiler
74 4.1.1 Sub-expression Elimination
75 4.1.2 Dead-Code Elimination
76 4.1.3 Copy-Propagation
77 4.1.4 Loop Optimizations
79 4.1.6 Algebraic Simplifications
80 4.1.7 'switch' Statements
81 4.1.8 Bit-shifting Operations.
83 4.1.10 Highest Order Bit
84 4.1.11 Peep-hole Optimizer
87 4.4 Interfacing with Assembly Routines
88 4.5 Global Registers used for Parameter Passing
89 4.5.1 Assembler Routine(non-reentrant)
90 4.5.2 Assembler Routine(reentrant)
93 4.8 Cyclomatic Complexity
95 6 Retargetting for other MCUs.
96 7 SDCDB - Source Level Debugger
97 7.1 Compiling for Debugging
98 7.2 How the Debugger Works
99 7.3 Starting the Debugger
100 7.4 Command Line Options.
101 7.5 Debugger Commands.
102 7.5.1 break [line | file:line | function | file:function]
103 7.5.2 clear [line | file:line | function | file:function ]
107 7.5.6 info [break | stack | frame | registers ]
111 7.5.10 ptype variable
112 7.5.11 print variable
116 7.5.15 ! simulator command
118 7.6 Interfacing with XEmacs.
120 8.1 The Z80 and gbz80 port
131 <pending: tabularise these features, this is unreadeble>
133 SDCC is a Free ware, retargettable, optimizing ANSI-C compiler
134 by Sandeep Dutta designed for 8 bit Microprocessors. The
135 current version targets Intel MCS51 based Microprocessors(8051,8052,
136 etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51
137 variant. It can be retargetted for other microprocessors,
138 support for PIC, AVR and 186 is under development. The entire
139 source code for the compiler is distributed under GPL. SDCC
140 uses ASXXXX & ASLINK, a Freeware, retargettable assembler
141 & linker. SDCC has extensive language extensions suitable
142 for utilizing various microcontrollers underlying hardware
143 effectively. In addition to the MCU specific optimizations
144 SDCC also does a host of standard optimizations like global
145 sub expression elimination, loop optimizations (loop invariant,
146 strength reduction of induction variables and loop reversing),
147 constant folding & propagation, copy propagation, dead code
148 elimination and jumptables for 'switch' statements. For
149 the back-end SDCC uses a global register allocation scheme
150 which should be well suited for other 8 bit MCUs. The peep
151 hole optimizer uses a rule based substitution mechanism
152 which is MCU dependent. Supported data-types are char (8
153 bits, 1 byte), short and int (16 bits, 2 bytes), long (32
154 bit, 4 bytes) and float (4 byte IEEE). The compiler also
155 allows inline assembler code to be embedded anywhere in
156 a function. In addition routines developed in assembly can
157 also be called. SDCC also provides an option to report the
158 relative complexity of a function, these functions can then
159 be further optimized, or hand coded in assembly if needed.
160 SDCC also comes with a companion source level debugger SDCDB,
161 the debugger currently uses ucSim a freeware simulator for
162 8051 and other micro-controllers. The latest version can
163 be downloaded from [http://sdcc.sourceforge.net/] .
167 All packages used in this compiler system are opensource
168 and freeware; source code for all the sub-packages (asxxxx
169 assembler/linker, pre-processor) is distributed with the
170 package. This documentation is maintained using a freeware
171 word processor (LyX).
173 This program is free software; you can redistribute it and/or
174 modify it under the terms of the GNU General Public License
175 as published by the Free Software Foundation; either version
176 2, or (at your option) any later version. This program is
177 distributed in the hope that it will be useful, but WITHOUT
178 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
179 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
180 Public License for more details. You should have received
181 a copy of the GNU General Public License along with this
182 program; if not, write to the Free Software Foundation,
183 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
184 In other words, you are welcome to use, share and improve
185 this program. You are forbidden to forbid anyone else to
186 use, share and improve what you give them. Help stamp out
189 <pending: add a link to gnu>
191 1.3 Typographic conventions
193 Throughout this manual, we will use the following convention.
194 Commands you have to type in are printed in "sans serif".
195 Code samples are printed in typewriter font. Interesting
196 items and new terms are printed in italicised type.
198 1.4 Pending: compatibilaty with previous versions
200 This version has numerous bug fixes comperated with the previous
201 version. But we also introduced some incompatibilaties with
202 older versions. Not just for the fun of it, but to make
203 the compiler more stable, efficient and ANSI compliant.
207 directory structure (2.7)
208 vararg pars expl int unless casted
209 never had a regextend
210 no --noreparms anymore
214 1.5 System Requirements
216 What do you need before you start installation of SDCC? A
217 computer, and a desire to compute. The preferred method
218 of installation is to compile SDCC from source using GNU
219 GCC and make. For Windows some pre-compiled binary distributions
220 are available for your convenience. You should have some
221 experience with command line tools and compiler use.
225 The SDCC home page at [http://sdcc.sourceforge.net/]
226 is a great place to find distribution sets. You can also
227 find links to the user mailing lists that offer help or
228 discuss SDCC with other SDCC users. Web links to other SDCC
229 related sites can also be found here. This document can
230 be found in the DOC directory of the source package as a
231 text or HTML file. Some of the other tools (simulator and
232 assembler) included with SDCC contain their own documentation
233 and can be found in the source distribution. If you want
234 the latest unreleased software, the complete source package
235 is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
239 2.1 Linux/Unix Installation
241 1. Download the source package, it will be named something
244 2. Bring up a command line terminal, such as xterm.
246 3. Unpack the file using a command like: "tar -xzf sdcc-2.x.x.tgz",
247 this will create a sub-directory called sdcc with all
250 4. Change directory into the main SDCC directory, for example
253 5. Type "./configure". This configures the package for compilation
256 6. Type "make". All of the source packages will compile, this
259 7. Type "make install" as root. This copies the binary executables
260 to the install directories.
262 2.2 Windows Installation
264 <pending: is this complete? where is borland, mingw>
266 For installation under Windows you first need to pick between
267 a pre-compiled binary package, or installing the source
268 package along with the Cygwin package. The binary package
269 is the quickest to install, while the Cygwin package includes
270 all of the open source power tools used to compile the complete
271 SDCC source package in the Windows environment. If you are
272 not familiar with the Unix command line environment, you
273 may want to read the section on additional information for
274 Windows users prior to your initial installation.
276 2.2.1 Windows Install Using a Binary Package
278 1. Download the binary package and unpack it using your favorite
279 unpacking tool (gunzip, WinZip, etc). This should unpack
280 to a group of sub-directories. An example directory structure
281 after unpacking is: c:\usr\local\bin for the executables,
282 c:\usr\local\share\sdcc\include and c:\usr\local\share\sdcc\lib
283 for the include and libraries.
285 2. Adjust your environment PATH to include the location of
286 the bin directory. For example, make a setsdcc.bat file
287 with the following: set PATH=c:\usr\local\bin;%PATH%
289 3. When you compile with sdcc, you may need to specify the
290 location of the lib and include folders. For example,
291 sdcc -I c:\usr\local\share\sdcc\include -L c:\usr\local\share\sdcc\lib\small
294 2.2.2 Windows Install Using Cygwin
296 1. Download and install the cygwin package from the redhat
297 site[http://sources.redhat.com/cygwin/]. Currently,
298 this involved downloading a small install program which
299 then automates downloading and installing selected parts
300 of the package (a large 80M byte sized dowload for the
303 2. Bring up a Unix/Bash command line terminal from the Cygwin
306 3. Follow the instructions in the preceding Linux/Unix installation
309 2.3 Testing out the SDCC Compiler
311 The first thing you should do after installing your SDCC
312 compiler is to see if it runs. Type "sdcc --version" at
313 the prompt, and the program should run and tell you the
314 version. If it doesn't run, or gives a message about not
315 finding sdcc program, then you need to check over your installation.
316 Make sure that the sdcc bin directory is in your executable
317 search path defined by the PATH environment setting (see
318 the Trouble-shooting section for suggestions). Make sure
319 that the sdcc program is in the bin folder, if not perhaps
320 something did not install correctly.
322 SDCC binaries are commonly installed in a directory arrangement
326 +--------------------------------+-------------------------------------------+
327 | /usr/local/bin | Holds executables(sdcc, s51, aslink, ...) |
328 +--------------------------------+-------------------------------------------+
329 +--------------------------------+-------------------------------------------+
330 | /usr/local/share/sdcc/lib | Holds common C libraries |
331 +--------------------------------+-------------------------------------------+
332 | /usr/local/share/sdcc/include | Holds common C header files |
333 +--------------------------------+-------------------------------------------+
336 Make sure the compiler works on a very simple example. Type
337 in the following test.c program using your favorite editor:
339 Compile this using the following command: "sdcc -c test.c"
340 If all goes well, the compiler will generate a test.asm
341 and test.rel file. Congratulations, you've just compiled
342 your first program with SDCC. We used the -c option to tell
343 SDCC not to link the generated code, just to keep things
344 simple for this step.
346 The next step is to try it with the linker. Type in "sdcc
347 test.c". If all goes well the compiler will link with the
348 libraries and produce a test.ihx output file. If this step
349 fails (no test.ihx, and the linker generates warnings),
350 then the problem is most likely that sdcc cannot find the
351 /usr/local/share/sdcc/lib directory (see the Install trouble-shooting
352 section for suggestions).
354 The final test is to ensure sdcc can use the standard header
355 files and libraries. Edit test.c and change it to the following:
360 strcpy(str1, "testing");
363 Compile this by typing "sdcc test.c". This should generate
364 a test.ihx output file, and it should give no warnings such
365 as not finding the string.h file. If it cannot find the
366 string.h file, then the problem is that sdcc cannot find
367 the /usr/local/share/sdcc/include directory (see the Install
368 trouble-shooting section for suggestions).
370 2.4 Install Trouble-shooting
372 2.4.1 SDCC cannot find libraries or header files.
374 The default installation assumes the libraries and header
375 files are located at "/usr/local/share/sdcc/lib"
376 and "/usr/local/share/sdcc/include".
377 An alternative is to specify these locations as compiler
378 options like this: "sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include test.c".
380 2.4.2 SDCC does not compile correctly.
382 A thing to try is starting from scratch by unpacking the
383 .tgz source package again in an empty directory. Confure
384 it again and build like:
386 make 2&>1 | tee make.log
388 After this you can review the make.log file to locate the
389 problem. Or a relevant part of this be attached to an email
390 that could be helpful when requesting help from the mailing
393 2.4.3 What the "./configure"
396 The "./configure" command is a script
397 that analyzes your system and performs some configuration
398 to ensure the source package compiles on your system. It
399 will take a few minutes to run, and will compile a few tests
400 to determine what compiler features are installed.
402 2.4.4 What the "make" does.
404 This runs the GNU make tool, which automatically compiles
405 all the source packages into the final installed binary
408 2.4.5 What the "make install"
411 This will install the compiler, other executables and libraries
412 in to the appropriate system directories. The default is
413 to copy the executables to /usr/local/bin and the libraries
414 and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
416 2.5 Additional Information for Windows Users
418 <pending: is this up to date?>
420 The standard method of installing on a Unix system involves
421 compiling the source package. This is easily done under
422 Unix, but under Windows it can be a more difficult process.
423 The Cygwin is a large package to download, and the compilation
424 runs considerably slower under Windows due to the overhead
425 of the Cygwin tool set. An alternative is to install a pre-compiled
426 Windows binary package. There are various trade-offs between
427 each of these methods.
429 The Cygwin package allows a Windows user to run a Unix command
430 line interface (bash shell) and also implements a Unix like
431 file system on top of Windows. Included are many of the
432 famous GNU software development tools which can augment
433 the SDCC compiler.This is great if you have some experience
434 with Unix command line tools and file system conventions,
435 if not you may find it easier to start by installing a binary
436 Windows package. The binary packages work with the Windows
437 file system conventions.
439 2.5.1 Getting started with Cygwin
441 SDCC is typically distributed as a tarred/gzipped file (.tgz).
442 This is a packed file similar to a .zip file. Cygwin includes
443 the tools you will need to unpack the SDCC distribution
444 (tar and gzip). To unpack it, simply follow the instructions
445 under the Linux/Unix install section. Before you do this
446 you need to learn how to start a cygwin shell and some of
447 the basic commands used to move files, change directory,
448 run commands and so on. The change directory command is
449 "cd", the move command is "mv".
450 To print the current working directory, type "pwd".
451 To make a directory, use "mkdir".
453 There are some basic differences between Unix and Windows
454 file systems you should understand. When you type in directory
455 paths, Unix and the Cygwin bash prompt uses forward slashes
456 '/' between directories while Windows traditionally uses
457 '\' backward slashes. So when you work at the Cygwin bash
458 prompt, you will need to use the forward '/' slashes. Unix
459 does not have a concept of drive letters, such as "c:",
460 instead all files systems attach and appear as directories.
462 2.5.2 Running SDCC as Native Compiled Executables
464 If you use the pre-compiled binaries, the install directories
465 for the libraries and header files may need to be specified
466 on the sdcc command line like this: "sdcc -L c:\usr\local\sdcc\lib\small
467 -I c:\usr\local\sdcc\include test.c" if you are running outside
468 of a Unix bash shell.
470 If you have successfully installed and compiled SDCC with
471 the Cygwin package, it is possible to compile into native
472 .exe files by using the additional makefiles included for
473 this purpose. For example, with the Borland 32-bit compiler
474 you would run "make -f Makefile.bcc". A command line version
475 of the Borland 32-bit compiler can be downloaded from the
478 2.6 SDCC on Other Platforms
480 * FreeBSD and other non-GNU Unixes - Make sure the GNU make
481 is installed as the default make tool.
483 * SDCC has been ported to run under a variety of operating
484 systems and processors. If you can run GNU GCC/make then
485 chances are good SDCC can be compiled and run on your
488 2.7 Advanced Install Options
490 The "configure" command has several options.
491 The most commonly used option is --prefix=<directory name>,
492 where <directory name> is the final location for the sdcc
493 executables and libraries, (default location is /usr/local).
494 The installation process will create the following directory
495 structure under the <directory name> specified (if they
496 do not already exist).
498 bin/ - binary exectables (add to PATH environment variable)
500 bin/share/sdcc/include/ - include header files
502 bin/share/sdcc/lib/small/ - Object & library files for small
504 bin/share/sdcc/lib/large/ - Object & library files for large
506 bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390
509 The command "./configure --prefix=/usr/local"
510 will configure the compiler to be installed in directory
513 2.8 Components of SDCC
515 SDCC is not just a compiler, but a collection of tools by
516 various developers. These include linkers, assemblers, simulators
517 and other components. Here is a summary of some of the components.
518 Note that the included simulator and assembler have separate
519 documentation which you can find in the source package in
520 their respective directories. As SDCC grows to include support
521 for other processors, other packages from various developers
522 are included and may have their own sets of documentation.
524 You might want to look at the various executables which are
525 installed in the bin directory. At the time of this writing,
526 we find the following programs:
528 <pending: tabularize this>
531 sdcpp - The C preprocessor.
532 asx8051 - The assembler for 8051 type processors.
533 as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers.
534 aslink -The linker for 8051 type processors.
535 link-z80, link-gbz80 - The Z80 and GameBoy Z80 linkers.
536 s51 - The ucSim 8051 simulator.
537 sdcdb - The source debugger.
538 packihx - A tool to pack Intel hex files.
540 As development for other processors proceeds, this list will
541 expand to include executables to support processors like
544 2.8.1 sdcc - The Compiler
546 This is the actual compiler, it in turn uses the c-preprocessor
547 and invokes the assembler and linkage editor.
549 2.8.2 sdcpp (C-Preprocessor)
551 The preprocessor is a modified version of the GNU preprocessor.
552 The C preprocessor is used to pull in #include sources,
553 process #ifdef statements, #defines and so on.
555 2.8.3 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80
556 (The Assemblers and Linkage Editors)
558 This is retargettable assembler & linkage editor, it was
559 developed by Alan Baldwin. John Hartman created the version
560 for 8051, and I (Sandeep) have made some enhancements and
561 bug fixes for it to work properly with the SDCC.
563 2.8.4 s51 - Simulator
565 S51 is a freeware, opensource simulator developed by Daniel
566 Drotos ([mailto:drdani@mazsola.iit.uni-miskolc.hu]).
567 The simulator is built as part of the build process. For
568 more information visit Daniel's website at: [http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51] .
570 2.8.5 sdcdb - Source Level Debugger
572 Sdcdb is the companion source level debugger. The current
573 version of the debugger uses Daniel's Simulator S51, but
574 can be easily changed to use other simulators.
580 3.1.1 Single Source File Projects
582 For single source file 8051 projects the process is very
583 simple. Compile your programs with the following command
584 "sdcc sourcefile.c". This will compile, assemble and link
585 your source file. Output files are as follows
587 sourcefile.asm - Assembler source file created by the compiler
588 sourcefile.lst - Assembler listing file created by the Assembler
589 sourcefile.rst - Assembler listing file updated with linkedit
590 information, created by linkage editor
591 sourcefile.sym - symbol listing for the sourcefile, created
593 sourcefile.rel - Object file created by the assembler, input
595 sourcefile.map - The memory map for the load module, created
597 sourcefile.ihx - The load module in Intel hex format (you
598 can select the Motorola S19 format with --out-fmt-s19)
599 sourcefile.cdb - An optional file (with --debug) containing
603 3.1.2 Projects with Multiple Source Files
605 SDCC can compile only ONE file at a time. Let us for example
606 assume that you have a project containing the following
609 foo1.c (contains some functions)
610 foo2.c (contains some more functions)
611 foomain.c (contains more functions and the function main)
613 The first two files will need to be compiled separately with
619 Then compile the source file containing the main() function
620 and link the files together with the following command:
623 sdcc foomain.c foo1.rel foo2.rel
625 Alternatively, foomain.c can be separately compiled as well:
629 sdcc foomain.rel foo1.rel foo2.rel
631 The file containing the main() function must be the first
632 file specified in the command line, since the linkage editor
633 processes file in the order they are presented to it.
635 3.1.3 Projects with Additional Libraries
637 Some reusable routines may be compiled into a library, see
638 the documentation for the assembler and linkage editor (which
639 are in <installdir>/share/sdcc/doc) for how to create a
640 .lib library file. Libraries created in this manner can
641 be included in the command line. Make sure you include the
642 -L <library-path> option to tell the linker where to look
643 for these files if they are not in the current directory.
644 Here is an example, assuming you have the source file foomain.c
645 and a library foolib.lib in the directory mylib (if that
646 is not the same as your current project):
648 sdcc foomain.c foolib.lib -L mylib
650 Note here that mylib must be an absolute path name.
652 The most efficient way to use libraries is to keep seperate
653 modules in seperate source files. The lib file now should
654 name all the modules.rel files. For an example see the standard
655 library file libsdcc.lib in the directory <installdir>/share/lib/small.
657 3.2 Command Line Options
659 3.2.1 Processor Selection Options
661 -mmcs51 Generate code for the MCS51 (8051) family of processors.
662 This is the default processor target.
664 -mds390 Generate code for the DS80C390 processor.
666 -mz80 Generate code for the Z80 family of processors.
668 -mgbz80 Generate code for the GameBoy Z80 processor.
670 -mavr Generate code for the Atmel AVR processor(In development,
673 -mpic14 Generate code for the PIC 14-bit processors(In development,
676 -mtlcs900h Generate code for the Toshiba TLCS-900H processor(In
677 development, not complete).
679 3.2.2 Preprocessor Options
681 -I<path> The additional location where the pre processor
682 will look for <..h> or "..h"
685 -D<macro[=value]> Command line definition of macros. Passed
686 to the pre processor.
688 -M Tell the preprocessor to output a rule suitable for make
689 describing the dependencies of each object file. For each
690 source file, the preprocessor outputs one make-rule whose
691 target is the object file name for that source file and
692 whose dependencies are all the files `#include'd in it.
693 This rule may be a single line or may be continued with
694 `\'-newline if it is long. The list of rules is printed on
695 standard output instead of the preprocessed C program. `-M'
698 -C Tell the preprocessor not to discard comments. Used with
701 -MM Like `-M' but the output mentions only the user header
702 files included with `#include "file"'.
703 System header files included with `#include <file>' are
706 -Aquestion(answer) Assert the answer answer for question,
707 in case it is tested with a preprocessor conditional such
708 as `#if #question(answer)'. `-A-' disables the standard
709 assertions that normally describe the target machine.
711 -Aquestion (answer) Assert the answer answer for question,
712 in case it is tested with a preprocessor conditional such
713 as `#if #question(answer)'. `-A-' disables the standard
714 assertions that normally describe the target machine.
716 -Umacro Undefine macro macro. `-U' options are evaluated
717 after all `-D' options, but before any `-include' and `-imacros'
720 -dM Tell the preprocessor to output only a list of the macro
721 definitions that are in effect at the end of preprocessing.
722 Used with the `-E' option.
724 -dD Tell the preprocessor to pass all macro definitions into
725 the output, in their proper sequence in the rest of the
728 -dN Like `-dD' except that the macro arguments and contents
729 are omitted. Only `#define name' is included in the output.
733 -L --lib-path <absolute path to additional libraries> This
734 option is passed to the linkage editor's additional libraries
735 search path. The path name must be absolute. Additional
736 library files may be specified in the command line. See
737 section Compiling programs for more details.
739 --xram-loc<Value> The start location of the external ram,
740 default value is 0. The value entered can be in Hexadecimal
741 or Decimal format, e.g.: --xram-loc 0x8000 or --xram-loc
744 --code-loc<Value> The start location of the code segment,
745 default value 0. Note when this option is used the interrupt
746 vector table is also relocated to the given address. The
747 value entered can be in Hexadecimal or Decimal format, e.g.:
748 --code-loc 0x8000 or --code-loc 32768.
750 --stack-loc<Value> The initial value of the stack pointer.
751 The default value of the stack pointer is 0x07 if only register
752 bank 0 is used, if other register banks are used then the
753 stack pointer is initialized to the location above the highest
754 register bank used. eg. if register banks 1 & 2 are used
755 the stack pointer will default to location 0x18. The value
756 entered can be in Hexadecimal or Decimal format, eg. --stack-loc
757 0x20 or --stack-loc 32. If all four register banks are used
758 the stack will be placed after the data segment (equivalent
759 to --stack-after-data)
761 --stack-after-data This option will cause the stack to be
762 located in the internal ram after the data segment.
764 --data-loc<Value> The start location of the internal ram
765 data segment, the default value is 0x30.The value entered
766 can be in Hexadecimal or Decimal format, eg. --data-loc
767 0x20 or --data-loc 32.
769 --idata-loc<Value> The start location of the indirectly addressable
770 internal ram, default value is 0x80. The value entered can
771 be in Hexadecimal or Decimal format, eg. --idata-loc 0x88
774 --out-fmt-ihx The linker output (final object code) is in
775 Intel Hex format. (This is the default option).
777 --out-fmt-s19 The linker output (final object code) is in
782 --model-large Generate code for Large model programs see
783 section Memory Models for more details. If this option is
784 used all source files in the project should be compiled
785 with this option. In addition the standard library routines
786 are compiled with small model, they will need to be recompiled.
788 --model-small Generate code for Small Model programs see
789 section Memory Models for more details. This is the default
794 --model-flat24 Generate 24-bit flat mode code. This is the
795 one and only that the ds390 code generator supports right
796 now and is default when using -mds390. See section Memory
797 Models for more details.
799 --stack-10bit Generate code for the 10 bit stack mode of
800 the Dallas DS80C390 part. This is the one and only that
801 the ds390 code generator supports right now and is default
802 when using -mds390. In this mode, the stack is located in
803 the lower 1K of the internal RAM, which is mapped to 0x400000.
804 Note that the support is incomplete, since it still uses
805 a single byte as the stack pointer. This means that only
806 the lower 256 bytes of the potential 1K stack space will
807 actually be used. However, this does allow you to reclaim
808 the precious 256 bytes of low RAM for use for the DATA and
809 IDATA segments. The compiler will not generate any code
810 to put the processor into 10 bit stack mode. It is important
811 to ensure that the processor is in this mode before calling
812 any re-entrant functions compiled with this option. In principle,
813 this should work with the --stack-auto option, but that
814 has not been tested. It is incompatible with the --xstack
815 option. It also only makes sense if the processor is in
816 24 bit contiguous addressing mode (see the --model-flat24
819 3.2.6 Optimization Options
821 --nogcse Will not do global subexpression elimination, this
822 option may be used when the compiler creates undesirably
823 large stack/data spaces to store compiler temporaries. A
824 warning message will be generated when this happens and
825 the compiler will indicate the number of extra bytes it
826 allocated. It recommended that this option NOT be used,
827 #pragma NOGCSE can be used to turn off global subexpression
828 elimination for a given function only.
830 --noinvariant Will not do loop invariant optimizations, this
831 may be turned off for reasons explained for the previous
832 option. For more details of loop optimizations performed
833 see section Loop Invariants.It recommended that this option
834 NOT be used, #pragma NOINVARIANT can
835 be used to turn off invariant optimizations for a given
838 --noinduction Will not do loop induction optimizations, see
839 section strength reduction for more details.It is recommended
840 that this option is NOT used, #pragma NOINDUCTION
841 can be used to turn off induction optimizations for a given
844 --nojtbound Will not generate boundary condition check when
845 switch statements are implemented using jump-tables. See
846 section Switch Statements for more details. It is recommended
847 that this option is NOT used, #pragma NOJTBOUND
848 can be used to turn off boundary checking for jump tables
849 for a given function only.
851 --noloopreverse Will not do loop reversal optimization.
855 -c --compile-only will compile and assemble the source,
856 but will not call the linkage editor.
858 -E Run only the C preprocessor. Preprocess all the C source
859 files specified and output the results to standard output.
861 --stack-auto All functions in the source file will be compiled
862 as reentrant, i.e. the parameters and local variables will
863 be allocated on the stack. see section Parameters and Local
864 Variables for more details. If this option is used all source
865 files in the project should be compiled with this option.
867 --xstack Uses a pseudo stack in the first 256 bytes in the
868 external ram for allocating variables and passing parameters.
869 See section on external stack for more details.
871 --callee-saves function1[,function2][,function3].... The
872 compiler by default uses a caller saves convention for register
873 saving across function calls, however this can cause unneccessary
874 register pushing & popping when calling small functions
875 from larger functions. This option can be used to switch
876 the register saving convention for the function names specified.
877 The compiler will not save registers when calling these
878 functions, no extra code will be generated at the entry
879 & exit for these functions to save & restore the registers
880 used by these functions, this can SUBSTANTIALLY reduce code
881 & improve run time performance of the generated code. In
882 the future the compiler (with interprocedural analysis)
883 will be able to determine the appropriate scheme to use
884 for each function call. DO NOT use this option for built-in
885 functions such as _muluint..., if this option is used for
886 a library function the appropriate library function needs
887 to be recompiled with the same option. If the project consists
888 of multiple source files then all the source file should
889 be compiled with the same --callee-saves option string.
890 Also see #pragma CALLEE-SAVES.
892 --debug When this option is used the compiler will generate
893 debug information, that can be used with the SDCDB. The
894 debug information is collected in a file with .cdb extension.
895 For more information see documentation for SDCDB.
897 --regextend This option is obsolete and isn't supported
900 --noregparms This option is obsolete and isn't supported
903 --peep-file<filename> This option can be used to use additional
904 rules to be used by the peep hole optimizer. See section
905 Peep Hole optimizations for details on how to write these
908 -S Stop after the stage of compilation proper; do not assemble.
909 The output is an assembler code file for the input file
912 -Wa_asmOption[,asmOption]... Pass the asmOption to the assembler.
914 -Wl_linkOption[,linkOption]... Pass the linkOption to the
917 --int-long-reent Integer (16 bit) and long (32 bit) libraries
918 have been compiled as reentrant. Note by default these libraries
919 are compiled as non-reentrant. See section Installation
922 --cyclomatic This option will cause the compiler to generate
923 an information message for each function in the source file.
924 The message contains some important information about the
925 function. The number of edges and nodes the compiler detected
926 in the control flow graph of the function, and most importantly
927 the cyclomatic complexity see section on Cyclomatic Complexity
930 --float-reent Floating point library is compiled as reentrant.See
931 section Installation for more details.
933 --nooverlay The compiler will not overlay parameters and
934 local variables of any function, see section Parameters
935 and local variables for more details.
937 --main-return This option can be used when the code generated
938 is called by a monitor program. The compiler will generate
939 a 'ret' upon return from the 'main' function. The default
940 option is to lock up i.e. generate a 'ljmp '.
942 --no-peep Disable peep-hole optimization.
944 --peep-asm Pass the inline assembler code through the peep
945 hole optimizer. This can cause unexpected changes to inline
946 assembler code, please go through the peephole optimizer
947 rules defined in the source file tree '<target>/peeph.def'
948 before using this option.
950 --iram-size<Value> Causes the linker to check if the interal
951 ram usage is within limits of the given value.
953 --nostdincl This will prevent the compiler from passing on
954 the default include path to the preprocessor.
956 --nostdlib This will prevent the compiler from passing on
957 the default library path to the linker.
959 --verbose Shows the various actions the compiler is performing.
961 -V Shows the actual commands the compiler is executing.
963 3.2.8 Intermediate Dump Options
965 The following options are provided for the purpose of retargetting
966 and debugging the compiler. These provided a means to dump
967 the intermediate code (iCode) generated by the compiler
968 in human readable form at various stages of the compilation
971 --dumpraw This option will cause the compiler to dump the
972 intermediate code into a file of named <source filename>.dumpraw
973 just after the intermediate code has been generated for
974 a function, i.e. before any optimizations are done. The
975 basic blocks at this stage ordered in the depth first number,
976 so they may not be in sequence of execution.
978 --dumpgcse Will create a dump of iCode's, after global subexpression
979 elimination, into a file named <source filename>.dumpgcse.
981 --dumpdeadcode Will create a dump of iCode's, after deadcode
982 elimination, into a file named <source filename>.dumpdeadcode.
984 --dumploop Will create a dump of iCode's, after loop optimizations,
985 into a file named <source filename>.dumploop.
987 --dumprange Will create a dump of iCode's, after live range
988 analysis, into a file named <source filename>.dumprange.
990 --dumlrange Will dump the life ranges for all symbols.
992 --dumpregassign Will create a dump of iCode's, after register
993 assignment, into a file named <source filename>.dumprassgn.
995 --dumplrange Will create a dump of the live ranges of iTemp's
997 --dumpall Will cause all the above mentioned dumps to be
1000 3.3 MCS51/DS390 Storage Class Language Extensions
1002 In addition to the ANSI storage classes SDCC allows the following
1003 MCS51 specific storage classes.
1007 Variables declared with this storage class will be placed
1008 in the extern RAM. This is the default storage class for
1009 Large Memory model, e.g.:
1011 xdata unsigned char xduc;
1015 This is the default storage class for Small Memory model.
1016 Variables declared with this storage class will be allocated
1017 in the internal RAM, e.g.:
1023 Variables declared with this storage class will be allocated
1024 into the indirectly addressable portion of the internal
1025 ram of a 8051, e.g.:
1031 This is a data-type and a storage class specifier. When a
1032 variable is declared as a bit, it is allocated into the
1033 bit addressable memory of 8051, e.g.:
1039 Like the bit keyword, sfr / sbit signifies both a data-type
1040 and storage class, they are used to describe the special
1041 function registers and special bit variables of a 8051,
1044 sfr at 0x80 P0; /* special function register P0 at location
1046 sbit at 0xd7 CY; /* CY (Carry Flag) */
1050 SDCC allows (via language extensions) pointers to explicitly
1051 point to any of the memory spaces of the 8051. In addition
1052 to the explicit pointers, the compiler also allows a _generic
1053 class of pointers which can be used to point to any of the
1056 Pointer declaration examples:
1058 /* pointer physically in xternal ram pointing to object in
1060 data unsigned char * xdata p;
1062 /* pointer physically in code rom pointing to data in xdata
1064 xdata unsigned char * code p;
1066 /* pointer physically in code space pointing to data in code
1068 code unsigned char * code p;
1070 /* the folowing is a generic pointer physically located in
1074 Well you get the idea.
1076 For compatibility with the previous version of the compiler,
1077 the following syntax for pointer declaration is still supported
1078 but will disappear int the near future.
1080 unsigned char _xdata *ucxdp; /* pointer to data in external
1082 unsigned char _data *ucdp ; /* pointer
1083 to data in internal ram */
1084 unsigned char _code *uccp ; /* pointer
1085 to data in R/O code space */
1086 unsigned char _idata *uccp; /*
1087 pointer to upper 128 bytes of ram */
1089 All unqualified pointers are treated as 3-byte (4-byte for
1090 the ds390) generic pointers. These type of pointers can
1091 also to be explicitly declared.
1093 unsigned char _generic *ucgp;
1095 The highest order byte of the generic pointers contains the
1096 data space information. Assembler support routines are called
1097 whenever data is stored or retrieved using generic pointers.
1098 These are useful for developing reusable library routines.
1099 Explicitly specifying the pointer type will generate the
1100 most efficient code. Pointers declared using a mixture of
1101 OLD and NEW style could have unpredictable results.
1103 3.5 Parameters & Local Variables
1105 Automatic (local) variables and parameters to functions can
1106 either be placed on the stack or in data-space. The default
1107 action of the compiler is to place these variables in the
1108 internal RAM (for small model) or external RAM (for Large
1109 model). This in fact makes them static so by default functions
1112 They can be placed on the stack either by using the --stack-auto
1113 compiler option or by using the reentrant keyword in the
1114 function declaration, e.g.:
1116 unsigned char foo(char i) reentrant
1121 Since stack space on 8051 is limited, the reentrant keyword
1122 or the --stack-auto option should be used sparingly. Note
1123 that the reentrant keyword just means that the parameters
1124 & local variables will be allocated to the stack, it does
1125 not mean that the function is register bank independent.
1127 Local variables can be assigned storage classes and absolute
1130 unsigned char foo() {
1131 xdata unsigned char i;
1133 data at 0x31 unsiged char j;
1137 In the above example the variable i will be allocated in
1138 the external ram, bvar in bit addressable space and j in
1139 internal ram. When compiled with --stack-auto or when a
1140 function is declared as reentrant this can only be done
1141 for static variables.
1143 Parameters however are not allowed any storage class, (storage
1144 classes for parameters will be ignored), their allocation
1145 is governed by the memory model in use, and the reentrancy
1150 For non-reentrant functions SDCC will try to reduce internal
1151 ram space usage by overlaying parameters and local variables
1152 of a function (if possible). Parameters and local variables
1153 of a function will be allocated to an overlayable segment
1154 if the function has no other function calls and the function
1155 is non-reentrant and the memory model is small. If an explicit
1156 storage class is specified for a local variable, it will
1159 Note that the compiler (not the linkage editor) makes the
1160 decision for overlaying the data items. Functions that are
1161 called from an interrupt service routine should be preceded
1162 by a #pragma NOOVERLAY if they are not reentrant.
1164 Also note that the compiler does not do any processing of
1165 inline assembler code, so the compiler might incorrectly
1166 assign local variables and parameters of a function into
1167 the overlay segment if the inline assembler code calls other
1168 c-functions that might use the overlay. In that case the
1169 #pragma NOOVERLAY should be used.
1171 Parameters and Local variables of functions that contain
1172 16 or 32 bit multiplication or division will NOT be overlayed
1173 since these are implemented using external functions, e.g.:
1177 void set_error(unsigned char errcd)
1183 void some_isr () interrupt 2 using 1
1190 In the above example the parameter errcd for the function
1191 set_error would be assigned to the overlayable segment if
1192 the #pragma NOOVERLAY was not present, this could
1193 cause unpredictable runtime behavior when called from an
1194 ISR. The #pragma NOOVERLAY ensures that
1195 the parameters and local variables for the function are
1198 3.7 Interrupt Service Routines
1200 SDCC allows interrupt service routines to be coded in C,
1201 with some extended keywords.
1203 void timer_isr (void) interrupt 2 using 1
1208 The number following the interrupt keyword is the interrupt
1209 number this routine will service. The compiler will insert
1210 a call to this routine in the interrupt vector table for
1211 the interrupt number specified. The using keyword is used
1212 to tell the compiler to use the specified register bank
1213 (8051 specific) when generating code for this function.
1214 Note that when some function is called from an interrupt
1215 service routine it should be preceded by a #pragma NOOVERLAY
1216 if it is not reentrant. A special note here, int (16 bit)
1217 and long (32 bit) integer division, multiplication & modulus
1218 operations are implemented using external support routines
1219 developed in ANSI-C, if an interrupt service routine needs
1220 to do any of these operations then the support routines
1221 (as mentioned in a following section) will have to be recompiled
1222 using the --stack-auto option and the source file will need
1223 to be compiled using the --int-long-rent compiler option.
1225 If you have multiple source files in your project, interrupt
1226 service routines can be present in any of them, but a prototype
1227 of the isr MUST be present or included in the file that
1228 contains the function main.
1230 Interrupt Numbers and the corresponding address & descriptions
1231 for the Standard 8051 are listed below. SDCC will automatically
1232 adjust the interrupt vector table to the maximum interrupt
1236 +--------------+--------------+----------------+
1237 | Interrupt # | Description | Vector Address |
1238 +--------------+--------------+----------------+
1239 +--------------+--------------+----------------+
1240 | 0 | External 0 | 0x0003 |
1241 +--------------+--------------+----------------+
1242 | 1 | Timer 0 | 0x000B |
1243 +--------------+--------------+----------------+
1244 | 2 | External 1 | 0x0013 |
1245 +--------------+--------------+----------------+
1246 | 3 | Timer 1 | 0x001B |
1247 +--------------+--------------+----------------+
1248 | 4 | Serial | 0x0023 |
1249 +--------------+--------------+----------------+
1252 If the interrupt service routine is defined without using
1253 a register bank or with register bank 0 (using 0), the compiler
1254 will save the registers used by itself on the stack upon
1255 entry and restore them at exit, however if such an interrupt
1256 service routine calls another function then the entire register
1257 bank will be saved on the stack. This scheme may be advantageous
1258 for small interrupt service routines which have low register
1261 If the interrupt service routine is defined to be using a
1262 specific register bank then only a, b & dptr are save and
1263 restored, if such an interrupt service routine calls another
1264 function (using another register bank) then the entire register
1265 bank of the called function will be saved on the stack.
1266 This scheme is recommended for larger interrupt service
1269 Calling other functions from an interrupt service routine
1270 is not recommended, avoid it if possible.
1272 Also see the _naked modifier.
1274 3.8 Critical Functions
1276 A special keyword may be associated with a function declaring
1277 it as critical. SDCC will generate code to disable all interrupts
1278 upon entry to a critical function and enable them back before
1279 returning. Note that nesting critical functions may cause
1280 unpredictable results.
1288 The critical attribute maybe used with other attributes like
1293 A special keyword may be associated with a function declaring
1294 it as _naked. The _naked function modifier attribute prevents
1295 the compiler from generating prologue and epilogue code
1296 for that function. This means that the user is entirely
1297 responsible for such things as saving any registers that
1298 may need to be preserved, selecting the proper register
1299 bank, generating the return instruction at the end, etc.
1300 Practically, this means that the contents of the function
1301 must be written in inline assembler. This is particularly
1302 useful for interrupt functions, which can have a large (and
1303 often unnecessary) prologue/epilogue. For example, compare
1304 the code generated by these two functions:
1306 data unsigned char counter;
1307 void simpleInterrupt(void) interrupt 1
1312 void nakedInterrupt(void) interrupt 2 _naked
1317 MUST explicitly include ret in _naked function.
1321 For an 8051 target, the generated simpleInterrupt looks like:
1338 whereas nakedInterrupt looks like:
1342 reti ; MUST explicitly
1343 include ret(i) in _naked function.
1345 While there is nothing preventing you from writing C code
1346 inside a _naked function, there are many ways to shoot yourself
1347 in the foot doing this, and is is recommended that you stick
1348 to inline assembler.
1350 3.10 Functions using private banks
1352 The using attribute (which tells the compiler to use a register
1353 bank other than the default bank zero) should only be applied
1354 to interrupt functions (see note 1 below). This will in
1355 most circumstances make the generated ISR code more efficient
1356 since it will not have to save registers on the stack.
1358 The using attribute will have no effect on the generated
1359 code for a non-interrupt function (but may occasionally
1360 be useful anyway([footnote] possible exception: if a function is called ONLY
1361 from 'interrupt' functions using a particular bank, it can
1362 be declared with the same 'using' attribute as the calling
1363 'interrupt' functions. For instance, if you have several
1364 ISRs using bank one, and all of them call memcpy(), it might
1365 make sense to create a specialized version of memcpy() 'using
1366 1', since this would prevent the ISR from having to save
1367 bank zero to the stack on entry and switch to bank zero
1368 before calling the function) ).
1369 (pending: I don't think this has been done yet)
1371 An interrupt function using a non-zero bank will assume that
1372 it can trash that register bank, and will not save it. Since
1373 high-priority interrupts can interrupt low-priority ones
1374 on the 8051 and friends, this means that if a high-priority
1375 ISR using a particular bank occurs while processing a low-priority
1376 ISR using the same bank, terrible and bad things can happen.
1377 To prevent this, no single register bank should be used
1378 by both a high priority and a low priority ISR. This is
1379 probably most easily done by having all high priority ISRs
1380 use one bank and all low priority ISRs use another. If you
1381 have an ISR which can change priority at runtime, you're
1382 on your own: I suggest using the default bank zero and taking
1383 the small performance hit.
1385 It is most efficient if your ISR calls no other functions.
1386 If your ISR must call other functions, it is most efficient
1387 if those functions use the same bank as the ISR (see note
1388 1 below); the next best is if the called functions use bank
1389 zero. It is very inefficient to call a function using a
1390 different, non-zero bank from an ISR.
1392 3.11 Absolute Addressing
1394 Data items can be assigned an absolute address with the at
1395 <address> keyword, in addition to a storage class, e.g.:
1397 xdata at 0x8000 unsigned char PORTA_8255 ;
1399 In the above example the PORTA_8255 will be allocated to
1400 the location 0x8000 of the external ram. Note that this
1401 feature is provided to give the programmer access to memory
1402 mapped devices attached to the controller. The compiler
1403 does not actually reserve any space for variables declared
1404 in this way (they are implemented with an equate in the
1405 assembler). Thus it is left to the programmer to make sure
1406 there are no overlaps with other variables that are declared
1407 without the absolute address. The assembler listing file
1408 (.lst) and the linker output files (.rst) and (.map) are
1409 a good places to look for such overlaps.
1411 Absolute address can be specified for variables in all storage
1416 The above example will allocate the variable at offset 0x02
1417 in the bit-addressable space. There is no real advantage
1418 to assigning absolute addresses to variables in this manner,
1419 unless you want strict control over all the variables allocated.
1423 The compiler inserts a call to the C routine _sdcc__external__startup()
1424 at the start of the CODE area. This routine is in the runtime
1425 library. By default this routine returns 0, if this routine
1426 returns a non-zero value, the static & global variable initialization
1427 will be skipped and the function main will be invoked Other
1428 wise static & global variables will be initialized before
1429 the function main is invoked. You could add a _sdcc__external__startup()
1430 routine to your program to override the default if you need
1431 to setup hardware or perform some other critical operation
1432 prior to static & global variable initialization.
1434 3.13 Inline Assembler Code
1436 SDCC allows the use of in-line assembler with a few restriction
1437 as regards labels. All labels defined within inline assembler
1438 code has to be of the form nnnnn$ where nnnn is a number
1439 less than 100 (which implies a limit of utmost 100 inline
1440 assembler labels per function). It is strongly recommended
1441 that each assembly instruction (including labels) be placed
1442 in a separate line (as the example shows). When the --peep-asm
1443 command line option is used, the inline assembler code will
1444 be passed through the peephole optimizer. This might cause
1445 some unexpected changes in the inline assembler code. Please
1446 go throught the peephole optimizer rules defined in file
1447 SDCCpeeph.def carefully before using this option.
1457 The inline assembler code can contain any valid code understood
1458 by the assembler, this includes any assembler directives
1459 and comment lines. The compiler does not do any validation
1460 of the code within the _asm ... _endasm; keyword pair.
1462 Inline assembler code cannot reference any C-Labels, however
1463 it can reference labels defined by the inline assembler,
1469 ; some assembler code
1472 /* some more c code */
1473 clabel: /* inline assembler cannot reference
1476 $0003: ;label (can be reference by inline assembler
1479 /* some more c code */
1482 In other words inline assembly code can access labels defined
1483 in inline assembly within the scope of the funtion.
1485 The same goes the other way, ie. labels defines in inline
1486 assembly CANNOT be accessed by C statements.
1488 3.14 int(16 bit) and long (32 bit) Support
1490 For signed & unsigned int (16 bit) and long (32 bit) variables,
1491 division, multiplication and modulus operations are implemented
1492 by support routines. These support routines are all developed
1493 in ANSI-C to facilitate porting to other MCUs, although
1494 some model specific assembler optimations are used. The
1495 following files contain the described routine, all of them
1496 can be found in <installdir>/share/sdcc/lib.
1498 <pending: tabularise this>
1500 _mulsint.c - signed 16 bit multiplication (calls _muluint)
1501 _muluint.c - unsigned 16 bit multiplication
1502 _divsint.c - signed 16 bit division (calls _divuint)
1503 _divuint.c - unsigned 16 bit division
1504 _modsint.c - signed 16 bit modulus (call _moduint)
1505 _moduint.c - unsigned 16 bit modulus
1506 _mulslong.c - signed 32 bit multiplication (calls _mululong)
1507 _mululong.c - unsigned32 bit multiplication
1508 _divslong.c - signed 32 division (calls _divulong)
1509 _divulong.c - unsigned 32 division
1510 _modslong.c - signed 32 bit modulus (calls _modulong)
1511 _modulong.c - unsigned 32 bit modulus
1513 Since they are compiled as non-reentrant, interrupt service
1514 routines should not do any of the above operations. If this
1515 is unavoidable then the above routines will need to be compiled
1516 with the --stack-auto option, after which the source program
1517 will have to be compiled with --int-long-rent option.
1519 3.15 Floating Point Support
1521 SDCC supports IEEE (single precision 4bytes) floating point
1522 numbers.The floating point support routines are derived
1523 from gcc's floatlib.c and consists of the following routines:
1525 <pending: tabularise this>
1527 _fsadd.c - add floating point numbers
1528 _fssub.c - subtract floating point numbers
1529 _fsdiv.c - divide floating point numbers
1530 _fsmul.c - multiply floating point numbers
1531 _fs2uchar.c - convert floating point to unsigned char
1532 _fs2char.c - convert floating point to signed char
1533 _fs2uint.c - convert floating point to unsigned int
1534 _fs2int.c - convert floating point to signed int
1535 _fs2ulong.c - convert floating point to unsigned long
1536 _fs2long.c - convert floating point to signed long
1537 _uchar2fs.c - convert unsigned char to floating point
1538 _char2fs.c - convert char to floating point number
1539 _uint2fs.c - convert unsigned int to floating point
1540 _int2fs.c - convert int to floating point numbers
1541 _ulong2fs.c - convert unsigned long to floating point number
1542 _long2fs.c - convert long to floating point number
1544 Note if all these routines are used simultaneously the data
1545 space might overflow. For serious floating point usage it
1546 is strongly recommended that the large model be used.
1548 3.16 MCS51 Memory Models
1550 SDCC allows two memory models for MCS51 code, small and large.
1551 Modules compiled with different memory models should never
1552 be combined together or the results would be unpredictable.
1553 The library routines supplied with the compiler are compiled
1554 as both small and large. The compiled library modules are
1555 contained in seperate directories as small and large so
1556 that you can link to either set.
1558 When the large model is used all variables declared without
1559 a storage class will be allocated into the external ram,
1560 this includes all parameters and local variables (for non-reentrant
1561 functions). When the small model is used variables without
1562 storage class are allocated in the internal ram.
1564 Judicious usage of the processor specific storage classes
1565 and the 'reentrant' function type will yield much more efficient
1566 code, than using the large model. Several optimizations
1567 are disabled when the program is compiled using the large
1568 model, it is therefore strongly recommdended that the small
1569 model be used unless absolutely required.
1571 3.17 DS390 Memory Models
1573 The only model supported is Flat 24. This generates code
1574 for the 24 bit contiguous addressing mode of the Dallas
1575 DS80C390 part. In this mode, up to four meg of external
1576 RAM or code space can be directly addressed. See the data
1577 sheets at www.dalsemi.com for further information on this
1580 In older versions of the compiler, this option was used with
1581 the MCS51 code generator (-mmcs51). Now, however, the '390
1582 has it's own code generator, selected by the -mds390 switch.
1585 Note that the compiler does not generate any code to place
1586 the processor into 24 bitmode (although tinibios in the
1587 ds390 libraries will do that for you). If you don't use
1588 tinibios, the boot loader or similar code must ensure that
1589 the processor is in 24 bit contiguous addressing mode before
1590 calling the SDCC startup code.
1592 Like the --model-large option, variables will by default
1593 be placed into the XDATA segment.
1595 Segments may be placed anywhere in the 4 meg address space
1596 using the usual --*-loc options. Note that if any segments
1597 are located above 64K, the -r flag must be passed to the
1598 linker to generate the proper segment relocations, and the
1599 Intel HEX output format must be used. The -r flag can be
1600 passed to the linker by using the option -Wl-r on the sdcc
1601 command line. However, currently the linker can not handle
1602 code segments > 64k.
1604 3.18 Defines Created by the Compiler
1606 The compiler creates the following #defines.
1608 * SDCC - this Symbol is always defined.
1610 * SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on
1611 the model used (e.g.: -mds390)
1613 * __mcs51 or __ds390 or __z80, etc - depending on the model
1616 * SDCC_STACK_AUTO - this symbol is defined when --stack-auto
1619 * SDCC_MODEL_SMALL - when --model-small is used.
1621 * SDCC_MODEL_LARGE - when --model-large is used.
1623 * SDCC_USE_XSTACK - when --xstack option is used.
1625 * SDCC_STACK_TENBIT - when -mds390 is used
1627 * SDCC_MODEL_FLAT24 - when -mds390 is used
1629 4 SDCC Technical Data
1633 SDCC performs a host of standard optimizations in addition
1634 to some MCU specific optimizations.
1636 4.1.1 Sub-expression Elimination
1638 The compiler does local and global common subexpression elimination,
1644 will be translated to
1650 Some subexpressions are not as obvious as the above example,
1656 In this case the address arithmetic a->b[i] will be computed
1657 only once; the equivalent code in C would be.
1663 The compiler will try to keep these temporary variables in
1666 4.1.2 Dead-Code Elimination
1671 i = 1; /* dead store */
1672 global = 1; /* dead store */
1675 global = 3; /* unreachable */
1680 int global; void f ()
1686 4.1.3 Copy-Propagation
1704 Note: the dead stores created by this copy propagation will
1705 be eliminated by dead-code elimination.
1707 4.1.4 Loop Optimizations
1709 Two types of loop optimizations are done by SDCC loop invariant
1710 lifting and strength reduction of loop induction variables.
1711 In addition to the strength reduction the optimizer marks
1712 the induction variables and the register allocator tries
1713 to keep the induction variables in registers for the duration
1714 of the loop. Because of this preference of the register
1715 allocator, loop induction optimization causes an increase
1716 in register pressure, which may cause unwanted spilling
1717 of other temporary variables into the stack / data space.
1718 The compiler will generate a warning message when it is
1719 forced to allocate extra space either on the stack or data
1720 space. If this extra space allocation is undesirable then
1721 induction optimization can be eliminated either for the
1722 entire source file (with --noinduction option) or for a
1723 given function only using #pragma NOINDUCTION.
1727 for (i = 0 ; i < 100 ; i ++)
1733 for (i = 0; i < 100; i++)
1736 As mentioned previously some loop invariants are not as apparent,
1737 all static address computations are also moved out of the
1740 Strength Reduction, this optimization substitutes an expression
1741 by a cheaper expression:
1743 for (i=0;i < 100; i++)
1750 for (i=0;i< 100;i++) {
1751 ar[itemp1] = itemp2;
1756 The more expensive multiplication is changed to a less expensive
1759 4.1.5 Loop Reversing
1761 This optimization is done to reduce the overhead of checking
1762 loop boundaries for every iteration. Some simple loops can
1763 be reversed and implemented using a "decrement
1764 and jump if not zero" instruction. SDCC
1765 checks for the following criterion to determine if a loop
1766 is reversible (note: more sophisticated compilers use data-dependency
1767 analysis to make this determination, SDCC uses a more simple
1770 * The 'for' loop is of the form
1772 for (<symbol> = <expression> ; <sym> [< | <=] <expression>
1773 ; [<sym>++ | <sym> += 1])
1776 * The <for body> does not contain "continue"
1779 * All goto's are contained within the loop.
1781 * No function calls within the loop.
1783 * The loop control variable <sym> is not assigned any value
1786 * The loop control variable does NOT participate in any arithmetic
1787 operation within the loop.
1789 * There are NO switch statements in the loop.
1791 Note djnz instruction can be used for 8-bit values only,
1792 therefore it is advantageous to declare loop control symbols
1793 as char. Ofcourse this may not be possible on all situations.
1795 4.1.6 Algebraic Simplifications
1797 SDCC does numerous algebraic simplifications, the following
1798 is a small sub-set of these optimizations.
1800 i = j + 0 ; /* changed to */ i = j;
1801 i /= 2; /* changed to */ i >>= 1;
1802 i = j - j ; /* changed to */ i = 0;
1803 i = j / 1 ; /* changed to */ i = j;
1805 Note the subexpressions given above are generally introduced
1806 by macro expansions or as a result of copy/constant propagation.
1808 4.1.7 'switch' Statements
1810 SDCC changes switch statements to jump tables when the following
1811 conditions are true.
1813 * The case labels are in numerical sequence, the labels need
1814 not be in order, and the starting number need not be one
1836 Both the above switch statements will be implemented using
1839 * The number of case labels is at least three, since it takes
1840 two conditional statements to handle the boundary conditions.
1842 * The number of case labels is less than 84, since each label
1843 takes 3 bytes and a jump-table can be utmost 256 bytes
1846 Switch statements which have gaps in the numeric sequence
1847 or those that have more that 84 case labels can be split
1848 into more than one switch statement for efficient code generation,
1862 If the above switch statement is broken down into two switch
1881 then both the switch statements will be implemented using
1882 jump-tables whereas the unmodified switch statement will
1885 4.1.8 Bit-shifting Operations.
1887 Bit shifting is one of the most frequently used operation
1888 in embedded programming. SDCC tries to implement bit-shift
1889 operations in the most efficient way possible, e.g.:
1896 generates the following code:
1903 In general SDCC will never setup a loop if the shift count
1904 is known. Another example:
1919 Note that SDCC stores numbers in little-endian format (i.e.
1920 lowest order first).
1924 A special case of the bit-shift operation is bit rotation,
1925 SDCC recognizes the following expression to be a left bit-rotation:
1929 i = ((i << 1) | (i >> 7));
1932 will generate the following code:
1938 SDCC uses pattern matching on the parse tree to determine
1939 this operation.Variations of this case will also be recognized
1940 as bit-rotation, i.e.:
1942 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
1944 4.1.10 Highest Order Bit
1946 It is frequently required to obtain the highest order bit
1947 of an integral type (long, int, short or char types). SDCC
1948 recognizes the following expression to yield the highest
1949 order bit and generates optimized code for it, e.g.:
1956 hob = (gint >> 15) & 1;
1960 will generate the following code:
1980 Variations of this case however will not be recognized. It
1981 is a standard C expression, so I heartily recommend this
1982 be the only way to get the highest order bit, (it is portable).
1983 Of course it will be recognized even if it is embedded in
1984 other expressions, e.g.:
1986 xyz = gint + ((gint >> 15) & 1);
1988 will still be recognized.
1990 4.1.11 Peep-hole Optimizer
1992 The compiler uses a rule based, pattern matching and re-writing
1993 mechanism for peep-hole optimization. It is inspired by
1994 copt a peep-hole optimizer by Christopher W. Fraser (cwfraser@microsoft.com).
1995 A default set of rules are compiled into the compiler, additional
1996 rules may be added with the --peep-file <filename> option.
1997 The rule language is best illustrated with examples.
2006 The above rule will change the following assembly sequence:
2015 Note: All occurrences of a %n (pattern variable) must denote
2016 the same string. With the above rule, the assembly sequence:
2021 will remain unmodified.
2023 Other special case optimizations may be added by the user
2024 (via --peep-file option). E.g. some variants of the 8051
2025 MCU allow only ajmp and acall. The following two rules will
2026 change all ljmp and lcall to ajmp and acall
2028 replace { lcall %1 } by { acall %1 }
2029 replace { ljmp %1 } by { ajmp %1 }
2031 The inline-assembler code is also passed through the peep
2032 hole optimizer, thus the peephole optimizer can also be
2033 used as an assembly level macro expander. The rules themselves
2034 are MCU dependent whereas the rule language infra-structure
2035 is MCU independent. Peephole optimization rules for other
2036 MCU can be easily programmed using the rule language.
2038 The syntax for a rule is as follows:
2040 rule := replace [ restart ] '{' <assembly sequence> '\n'
2046 <assembly sequence> '\n'
2048 '}' [if <functionName>
2051 <assembly sequence> := assembly instruction (each instruction
2052 including labels must be on a separate line).
2054 The optimizer will apply to the rules one by one from the
2055 top in the sequence of their appearance, it will terminate
2056 when all rules are exhausted. If the 'restart' option is
2057 specified, then the optimizer will start matching the rules
2058 again from the top, this option for a rule is expensive
2059 (performance), it is intended to be used in situations where
2060 a transformation will trigger the same rule again. A good
2061 example of this the following rule:
2069 Note that the replace pattern cannot be a blank, but can
2070 be a comment line. Without the 'restart' option only the
2071 inner most 'pop' 'push' pair would be eliminated, i.e.:
2084 with the restart option the rule will be applied again to
2085 the resulting code and then all the pop-push pairs will
2086 be eliminated to yield:
2091 A conditional function can be attached to a rule. Attaching
2092 rules are somewhat more involved, let me illustrate this
2099 %2:} if labelInRange
2101 The optimizer does a look-up of a function name table defined
2102 in function callFuncByName in the source file SDCCpeeph.c,
2103 with the name labelInRange. If it finds a corresponding
2104 entry the function is called. Note there can be no parameters
2105 specified for these functions, in this case the use of %5
2106 is crucial, since the function labelInRange expects to find
2107 the label in that particular variable (the hash table containing
2108 the variable bindings is passed as a parameter). If you
2109 want to code more such functions, take a close look at the
2110 function labelInRange and the calling mechanism in source
2111 file SDCCpeeph.c. I know this whole thing is a little kludgey,
2112 but maybe some day we will have some better means. If you
2113 are looking at this file, you will also see the default
2114 rules that are compiled into the compiler, you can add your
2115 own rules in the default set there if you get tired of specifying
2116 the --peep-file option.
2118 <pending: this is as far as I got>
2122 SDCC supports the following #pragma directives. This directives
2123 are applicable only at a function level.
2125 * SAVE - this will save all the current options.
2127 * RESTORE - will restore the saved options from the last
2128 save. Note that SAVES & RESTOREs cannot be nested. SDCC
2129 uses the same buffer to save the options each time a SAVE
2132 * NOGCSE - will stop global subexpression elimination.
2134 * NOINDUCTION - will stop loop induction optimizations.
2136 * NOJTBOUND - will not generate code for boundary value checking,
2137 when switch statements are turned into jump-tables.
2139 * NOOVERLAY - the compiler will not overlay the parameters
2140 and local variables of a function.
2142 * NOLOOPREVERSE - Will not do loop reversal optimization
2144 * EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma
2145 disables generation of pair of push/pop instruction in
2146 ISR function (using interrupt keyword). The directive
2147 should be placed immediately before the ISR function definition
2148 and it affects ALL ISR functions following it. To enable
2149 the normal register saving for ISR functions use #pragma EXCLUDE none.
2151 * CALLEE-SAVES function1[,function2[,function3...]] - The
2152 compiler by default uses a caller saves convention for
2153 register saving across function calls, however this can
2154 cause unneccessary register pushing & popping when calling
2155 small functions from larger functions. This option can
2156 be used to switch the register saving convention for the
2157 function names specified. The compiler will not save registers
2158 when calling these functions, extra code will be generated
2159 at the entry & exit for these functions to save & restore
2160 the registers used by these functions, this can SUBSTANTIALLY
2161 reduce code & improve run time performance of the generated
2162 code. In future the compiler (with interprocedural analysis)
2163 will be able to determine the appropriate scheme to use
2164 for each function call. If --callee-saves command line
2165 option is used, the function names specified in #pragma CALLEE-SAVES
2166 is appended to the list of functions specified inthe command
2169 The pragma's are intended to be used to turn-off certain
2170 optimizations which might cause the compiler to generate
2171 extra stack / data space to store compiler generated temporary
2172 variables. This usually happens in large functions. Pragma
2173 directives should be used as shown in the following example,
2174 they are used to control options & optimizations for a given
2175 function; pragmas should be placed before and/or after a
2176 function, placing pragma's inside a function body could
2177 have unpredictable results.
2181 #pragma SAVE /* save the current settings
2183 #pragma NOGCSE /* turnoff global subexpression elimination
2185 #pragma NOINDUCTION /* turn off induction optimizations */
2193 #pragma RESTORE /* turn the optimizations back on */
2195 The compiler will generate a warning message when extra space
2196 is allocated. It is strongly recommended that the SAVE and
2197 RESTORE pragma's be used when changing options for a function.
2199 4.3 Library Routines
2201 The following library routines are provided for your convenience.
2203 stdio.h - Contains the following functions printf & sprintf
2204 these routines are developed by Martijn van Balen <balen@natlab.research.philips.com>.
2206 %[flags][width][b|B|l|L]type
2209 - left justify output
2210 in specified field width
2212 + prefix output with
2213 +/- sign if output is signed type
2215 space prefix output with a blank if
2216 it's a signed positive value
2218 specifies minimum number of characters outputted for numbers
2223 - For numbers, spaces are added on the left when needed.
2226 If width starts with a zero character, zeroes and used
2230 - For strings, spaces are are added on the left or right
2233 flag '-' is used) when needed.
2237 byte argument (used by d, u, o, x, X)
2239 long argument (used by d, u, o, x, X)
2243 u unsigned decimal number
2246 o unsigned octal number
2249 x unsigned hexadecimal
2252 X unsigned hexadecimal
2257 s string (generic pointer)
2260 p generic pointer (I:data/idata,
2261 C:code, X:xdata, P:paged)
2263 f float (still to be
2266 Also contains a very simple version of printf (printf_small).
2267 This simplified version of printf supports only the following
2270 format output type argument-type
2278 %x hexadecimal short/int
2280 %lx hexadecimal long
2282 %hx hexadecimal char
2292 %s character _generic
2295 The routine is very stack intesive, --stack-after-data parameter
2296 should be used when using this routine, the routine also
2297 takes about 1K of code space. It also expects an external
2298 function named putchar(char) to be present (this can be
2299 changed). When using the %s format the string / pointer
2300 should be cast to a generic pointer. eg.
2302 printf_small("my str %s, my int %d\n",(char
2303 _generic *)mystr,myint);
2305 * stdarg.h - contains definition for the following macros
2306 to be used for variable parameter list, note that a function
2307 can have a variable parameter list if and only if it is
2310 va_list, va_start, va_arg, va_end.
2312 * setjmp.h - contains defintion for ANSI setjmp & longjmp
2313 routines. Note in this case setjmp & longjmp can be used
2314 between functions executing within the same register bank,
2315 if long jmp is executed from a function that is using
2316 a different register bank from the function issuing the
2317 setjmp function, the results may be unpredictable. The
2318 jump buffer requires 3 bytes of data (the stack pointer
2319 & a 16 byte return address), and can be placed in any
2322 * stdlib.h - contains the following functions.
2326 * string.h - contains the following functions.
2328 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr,
2329 strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok,
2330 memcpy, memcmp, memset.
2332 * ctype.h - contains the following routines.
2334 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct,
2335 isspace, isxdigit, isalnum, isalpha.
2337 * malloc.h - The malloc routines are developed by Dmitry
2338 S. Obukhov (dso@usa.net). These routines will allocate
2339 memory from the external ram. Here is a description on
2340 how to use them (as described by the author).
2344 #define DYNAMIC_MEMORY_SIZE 0x2000
2348 unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
2351 unsigned char xdata * current_buffer;
2361 init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
2364 //Now it's possible to use malloc.
2368 current_buffer = malloc(0x100);
2371 * serial.h - Serial IO routines are also developed by Dmitry
2372 S. Obukhov (dso@usa.net). These routines are interrupt
2373 driven with a 256 byte circular buffer, they also expect
2374 external ram to be present. Please see documentation in
2375 file SDCCDIR/sdcc51lib/serial.c. Note the header file
2376 "serial.h" MUST be included in the file containing
2377 the 'main' function.
2379 * ser.h - Alternate serial routine provided by Wolfgang Esslinger
2380 <wolfgang@WiredMinds.com> these routines are more compact
2381 and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
2383 * ser_ir.h - Another alternate set of serial routines provided
2384 by Josef Wolf <jw@raven.inka.de>, these routines do not
2385 use the external ram.
2387 * reg51.h - contains register definitions for a standard
2390 * float.h - contains min, max and other floating point related
2393 All library routines are compiled as --model-small, they
2394 are all non-reentrant, if you plan to use the large model
2395 or want to make these routines reentrant, then they will
2396 have to be recompiled with the appropriate compiler option.
2398 Have not had time to do the more involved routines like printf,
2399 will get to them shortly.
2401 4.4 Interfacing with Assembly Routines
2403 4.5 Global Registers used for Parameter Passing
2405 By default the compiler uses the global registers "DPL,DPH,B,ACC"
2406 to pass the first parameter to a routine, the second parameter
2407 onwards is either allocated on the stack (for reentrant
2408 routines or --stack-auto is used) or in the internal / external
2409 ram (depending on the memory model).
2411 4.5.1 Assembler Routine(non-reentrant)
2413 In the following example the function cfunc calls an assembler
2414 routine asm_func, which takes two parameters.
2416 extern int asm_func(unsigned char, unsigned char);
2419 int c_func (unsigned char i, unsigned char j)
2421 return asm_func(i,j);
2425 return c_func(10,9);
2428 The corresponding assembler function is:-
2430 .globl _asm_func_PARM_2
2447 Note here that the return values are placed in 'dpl' - One
2448 byte return value, 'dpl' LSB & 'dph' MSB for two byte values.
2449 'dpl', 'dph' and 'b' for three byte values (generic pointers)
2450 and 'dpl','dph','b' & 'acc' for four byte values.
2452 The parameter naming convention is _<function_name>_PARM_<n>,
2453 where n is the parameter number starting from 1, and counting
2454 from the left. The first parameter is passed in "dpl"
2455 for One bye parameter, "dptr"
2456 if two bytes, "b,dptr"
2457 for three bytes and "acc,b,dptr"
2458 for four bytes, the varaible name for the second parameter
2459 will be _<function_name>_PARM_2.
2461 Assemble the assembler routine with the following command.
2463 asx8051 -losg asmfunc.asm
2465 Then compile and link the assembler routine to the C source
2466 file with the following command,
2468 sdcc cfunc.c asmfunc.rel
2470 4.5.2 Assembler Routine(reentrant)
2472 In this case the second parameter onwards will be passed
2473 on the stack, the parameters are pushed from right to left
2474 i.e. after the call the left most parameter will be on the
2475 top of the stack. Here is an example.
2477 extern int asm_func(unsigned char, unsigned char);
2481 int c_func (unsigned char i, unsigned char j) reentrant
2483 return asm_func(i,j);
2487 return c_func(10,9);
2490 The corresponding assembler routine is.
2511 The compiling and linking procedure remains the same, however
2512 note the extra entry & exit linkage required for the assembler
2513 code, _bp is the stack frame pointer and is used to compute
2514 the offset into the stack for parameters and local variables.
2518 The external stack is located at the start of the external
2519 ram segment, and is 256 bytes in size. When --xstack option
2520 is used to compile the program, the parameters and local
2521 variables of all reentrant functions are allocated in this
2522 area. This option is provided for programs with large stack
2523 space requirements. When used with the --stack-auto option,
2524 all parameters and local variables are allocated on the
2525 external stack (note support libraries will need to be recompiled
2526 with the same options).
2528 The compiler outputs the higher order address byte of the
2529 external ram segment into PORT P2, therefore when using
2530 the External Stack option, this port MAY NOT be used by
2531 the application program.
2535 Deviations from the compliancy.
2537 1. functions are not always reentrant.
2539 2. structures cannot be assigned values directly, cannot be
2540 passed as function parameters or assigned to each other
2541 and cannot be a return value from a function.
2550 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI
2555 struct s foo1 (struct s parms) /* is invalid in SDCC although
2560 return rets;/* is invalid in SDCC although allowed in ANSI
2564 1. 'long long' (64 bit integers) not supported.
2566 2. 'double' precision floating point not supported.
2568 3. integral promotions are suppressed. What does this mean
2569 ? The compiler will not implicitly promote an integer
2570 expression to a higher order integer, exception is an
2571 assignment or parameter passing.
2573 4. No support for setjmp and longjmp (for now).
2575 5. Old K&R style function declarations are NOT allowed.
2577 foo(i,j) /* this old style of function declarations */
2578 int i,j; /* are valid in ANSI .. not valid in SDCC */
2583 1. functions declared as pointers must be dereferenced during
2589 /* has to be called like this */
2590 (*foo)();/* ansi standard allows calls to be made like
2593 4.8 Cyclomatic Complexity
2595 Cyclomatic complexity of a function is defined as the number
2596 of independent paths the program can take during execution
2597 of the function. This is an important number since it defines
2598 the number test cases you have to generate to validate the
2599 function. The accepted industry standard for complexity
2600 number is 10, if the cyclomatic complexity reported by SDCC
2601 exceeds 10 you should think about simplification of the
2604 Note that the complexity level is not related to the number
2605 of lines of code in a function. Large functions can have
2606 low complexity, and small functions can have large complexity
2607 levels. SDCC uses the following formula to compute the complexity.
2609 complexity = (number of edges in control flow graph) -
2611 of nodes in control flow graph) + 2;
2613 Having said that the industry standard is 10, you should
2614 be aware that in some cases it may unavoidable to have a
2615 complexity level of less than 10. For example if you have
2616 switch statement with more than 10 case labels, each case
2617 label adds one to the complexity level. The complexity level
2618 is by no means an absolute measure of the algorithmic complexity
2619 of the function, it does however provide a good starting
2620 point for which functions you might look at for further
2625 Here are a few guide-lines that will help the compiler generate
2626 more efficient code, some of the tips are specific to this
2627 compiler others are generally good programming practice.
2629 * Use the smallest data type to represent your data-value.
2630 If it is known in advance that the value is going to be
2631 less than 256 then use a 'char' instead of a 'short' or
2634 * Use unsigned when it is known in advance that the value
2635 is not going to be negative. This helps especially if
2636 you are doing division or multiplication.
2638 * NEVER jump into a LOOP.
2640 * Declare the variables to be local whenever possible, especially
2641 loop control variables (induction).
2643 * Since the compiler does not do implicit integral promotion,
2644 the programmer should do an explicit cast when integral
2645 promotion is required.
2647 * Reducing the size of division, multiplication & modulus
2648 operations can reduce code size substantially. Take the
2649 following code for example.
2651 foobar(unsigned int p1, unsigned char ch)
2653 unsigned char ch1 = p1 % ch ;
2657 For the modulus operation the variable ch will be promoted
2658 to unsigned int first then the modulus operation will
2659 be performed (this will lead to a call to a support routine).
2660 If the code is changed to
2662 foobar(unsigned int p1, unsigned char ch)
2664 unsigned char ch1 = (unsigned char)p1
2669 It would substantially reduce the code generated (future
2670 versions of the compiler will be smart enough to detect
2671 such optimization oppurtunities).
2673 Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
2675 The 8051 family of micro controller have a minimum of 128
2676 bytes of internal memory which is structured as follows
2678 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers
2681 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
2683 - Bytes 30-7F - 60 bytes for general purpose use.
2685 Normally the SDCC compiler will only utilise the first bank
2686 of registers, but it is possible to specify that other banks
2687 of registers should be used in interrupt routines. By default,
2688 the compiler will place the stack after the last bank of
2689 used registers, i.e. if the first 2 banks of registers are
2690 used, it will position the base of the internal stack at
2691 address 16 (0X10). This implies that as the stack grows,
2692 it will use up the remaining register banks, and the 16
2693 bytes used by the 128 bit variables, and 60 bytes for general
2696 By default, the compiler uses the 60 general purpose bytes
2697 to hold "near data". The compiler/optimiser may also declare
2698 some Local Variables in this area to hold local data.
2700 If any of the 128 bit variables are used, or near data is
2701 being used then care needs to be taken to ensure that the
2702 stack does not grow so much that it starts to over write
2703 either your bit variables or "near data". There is no runtime
2704 checking to prevent this from happening.
2706 The amount of stack being used is affected by the use of
2707 the "internal stack" to save registers before a subroutine
2708 call is made, - --stack-auto will declare parameters and
2709 local variables on the stack - the number of nested subroutines.
2711 If you detect that the stack is over writing you data, then
2712 the following can be done. --xstack will cause an external
2713 stack to be used for saving registers and (if --stack-auto
2714 is being used) storing parameters and local variables. However
2715 this will produce more and code which will be slower to
2718 --stack-loc will allow you specify the start of the stack,
2719 i.e. you could start it after any data in the general purpose
2720 area. However this may waste the memory not used by the
2721 register banks and if the size of the "near data" increases,
2722 it may creep into the bottom of the stack.
2724 --stack-after-data, similar to the --stack-loc, but it automatically
2725 places the stack after the end of the "near data". Again
2726 this could waste any spare register space.
2728 --data-loc allows you to specify the start address of the
2729 near data. This could be used to move the "near data" further
2730 away from the stack giving it more room to grow. This will
2731 only work if no bit variables are being used and the stack
2732 can grow to use the bit variable space.
2736 If you find that the stack is over writing your bit variables
2737 or "near data" then the approach which best utilised the
2738 internal memory is to position the "near data" after the
2739 last bank of used registers or, if you use bit variables,
2740 after the last bit variable by using the --data-loc, e.g.
2741 if two register banks are being used and no data variables,
2742 --data-loc 16, and - use the --stack-after-data option.
2744 If bit variables are being used, another method would be
2745 to try and squeeze the data area in the unused register
2746 banks if it will fit, and start the stack after the last
2749 6 Retargetting for other MCUs.
2751 The issues for retargetting the compiler are far too numerous
2752 to be covered by this document. What follows is a brief
2753 description of each of the seven phases of the compiler
2754 and its MCU dependency.
2756 1. Parsing the source and building the annotated parse tree.
2757 This phase is largely MCU independent (except for the
2758 language extensions). Syntax & semantic checks are also
2759 done in this phase, along with some initial optimizations
2760 like back patching labels and the pattern matching optimizations
2761 like bit-rotation etc.
2763 2. The second phase involves generating an intermediate code
2764 which can be easy manipulated during the later phases.
2765 This phase is entirely MCU independent. The intermediate
2766 code generation assumes the target machine has unlimited
2767 number of registers, and designates them with the name
2768 iTemp. The compiler can be made to dump a human readable
2769 form of the code generated by using the --dumpraw option.
2771 3. This phase does the bulk of the standard optimizations
2772 and is also MCU independent. This phase can be broken
2773 down into several sub-phases.
2775 * Break down intermediate code (iCode) into basic blocks.
2777 * Do control flow & data flow analysis on the basic blocks.
2779 * Do local common subexpression elimination, then global
2780 subexpression elimination
2782 * dead code elimination
2784 * loop optimizations
2786 * if loop optimizations caused any changes then do 'global
2787 subexpression elimination' and 'dead code elimination'
2790 4. This phase determines the live-ranges; by live range I
2791 mean those iTemp variables defined by the compiler that
2792 still survive after all the optimizations. Live range
2793 analysis is essential for register allocation, since these
2794 computation determines which of these iTemps will be assigned
2795 to registers, and for how long.
2797 5. Phase five is register allocation. There are two parts
2800 (a) The first part I call 'register packing' (for lack of
2801 a better term). In this case several MCU specific expression
2802 folding is done to reduce register pressure.
2804 (b) The second part is more MCU independent and deals with
2805 allocating registers to the remaining live ranges. A
2806 lot of MCU specific code does creep into this phase
2807 because of the limited number of index registers available
2810 6. The Code generation phase is (unhappily), entirely MCU
2811 dependent and very little (if any at all) of this code
2812 can be reused for other MCU. However the scheme for allocating
2813 a homogenized assembler operand for each iCode operand
2816 7. As mentioned in the optimization section the peep-hole
2817 optimizer is rule based system, which can reprogrammed
2820 7 SDCDB - Source Level Debugger
2822 SDCC is distributed with a source level debugger. The debugger
2823 uses a command line interface, the command repertoire of
2824 the debugger has been kept as close to gdb (the GNU debugger)
2825 as possible. The configuration and build process is part
2826 of the standard compiler installation, which also builds
2827 and installs the debugger in the target directory specified
2828 during configuration. The debugger allows you debug BOTH
2829 at the C source and at the ASM source level.
2831 7.1 Compiling for Debugging
2833 The --debug option must be specified for all files for which
2834 debug information is to be generated. The complier generates
2835 a .cdb file for each of these files. The linker updates
2836 the .cdb file with the address information. This .cdb is
2837 used by the debugger.
2839 7.2 How the Debugger Works
2841 When the --debug option is specified the compiler generates
2842 extra symbol information some of which are put into the
2843 the assembler source and some are put into the .cdb file,
2844 the linker updates the .cdb file with the address information
2845 for the symbols. The debugger reads the symbolic information
2846 generated by the compiler & the address information generated
2847 by the linker. It uses the SIMULATOR (Daniel's S51) to execute
2848 the program, the program execution is controlled by the
2849 debugger. When a command is issued for the debugger, it
2850 translates it into appropriate commands for the simulator.
2852 7.3 Starting the Debugger
2854 The debugger can be started using the following command line.
2855 (Assume the file you are debugging has
2861 The debugger will look for the following files.
2863 1. foo.c - the source file.
2865 2. foo.cdb - the debugger symbol information file.
2867 3. foo.ihx - the intel hex format object file.
2869 7.4 Command Line Options.
2871 * --directory=<source file directory> this option can used
2872 to specify the directory search list. The debugger will
2873 look into the directory list specified for source, cdb
2874 & ihx files. The items in the directory list must be separated
2875 by ':', e.g. if the source files can be in the directories
2876 /home/src1 and /home/src2, the --directory option should
2877 be --directory=/home/src1:/home/src2. Note there can be
2878 no spaces in the option.
2880 * -cd <directory> - change to the <directory>.
2882 * -fullname - used by GUI front ends.
2884 * -cpu <cpu-type> - this argument is passed to the simulator
2885 please see the simulator docs for details.
2887 * -X <Clock frequency > this options is passed to the simulator
2888 please see simulator docs for details.
2890 * -s <serial port file> passed to simulator see simulator
2893 * -S <serial in,out> passed to simulator see simulator docs
2896 7.5 Debugger Commands.
2898 As mention earlier the command interface for the debugger
2899 has been deliberately kept as close the GNU debugger gdb,
2900 as possible, this will help int integration with existing
2901 graphical user interfaces (like ddd, xxgdb or xemacs) existing
2902 for the GNU debugger.
2904 7.5.1 break [line | file:line | function | file:function]
2906 Set breakpoint at specified line or function.
2909 sdcdb>break foo.c:100
2911 sdcdb>break foo.c:funcfoo
2913 7.5.2 clear [line | file:line | function | file:function ]
2915 Clear breakpoint at specified line or function.
2918 sdcdb>clear foo.c:100
2920 sdcdb>clear foo.c:funcfoo
2924 Continue program being debugged, after breakpoint.
2928 Execute till the end of the current function.
2932 Delete breakpoint number 'n'. If used without any option
2933 clear ALL user defined break points.
2935 7.5.6 info [break | stack | frame | registers ]
2937 * info break - list all breakpoints
2939 * info stack - show the function call stack.
2941 * info frame - show information about the current execution
2944 * info registers - show content of all registers.
2948 Step program until it reaches a different source line.
2952 Step program, proceeding through subroutine calls.
2956 Start debugged program.
2958 7.5.10 ptype variable
2960 Print type information of the variable.
2962 7.5.11 print variable
2964 print value of variable.
2966 7.5.12 file filename
2968 load the given file name. Note this is an alternate method
2969 of loading file for debugging.
2973 print information about current frame.
2977 Toggle between C source & assembly source.
2979 7.5.15 ! simulator command
2981 Send the string following '!' to the simulator, the simulator
2982 response is displayed. Note the debugger does not interpret
2983 the command being sent to the simulator, so if a command
2984 like 'go' is sent the debugger can loose its execution context
2985 and may display incorrect values.
2989 "Watch me now. Iam going Down. My name is Bobby Brown"
2991 7.6 Interfacing with XEmacs.
2993 Two files are (in emacs lisp) are provided for the interfacing
2994 with XEmacs, sdcdb.el and sdcdbsrc.el. These two files can
2995 be found in the $(prefix)/bin directory after the installation
2996 is complete. These files need to be loaded into XEmacs for
2997 the interface to work, this can be done at XEmacs startup
2998 time by inserting the following into your '.xemacs' file
2999 (which can be found in your HOME directory) (load-file sdcdbsrc.el)
3000 [ .xemacs is a lisp file so the () around the command is
3001 REQUIRED), the files can also be loaded dynamically while
3002 XEmacs is running, set the environment variable 'EMACSLOADPATH'
3003 to the installation bin directory [$(prefix)/bin], then
3004 enter the following command ESC-x load-file sdcdbsrc. To
3005 start the interface enter the following command ESC-x sdcdbsrc,
3006 you will prompted to enter the file name to be debugged.
3008 The command line options that are passed to the simulator
3009 directly are bound to default values in the file sdcdbsrc.el
3010 the variables are listed below these values maybe changed
3013 * sdcdbsrc-cpu-type '51
3015 * sdcdbsrc-frequency '11059200
3017 * sdcdbsrc-serial nil
3019 The following is a list of key mapping for the debugger interface.
3022 ;; Current Listing ::
3023 ;;key binding Comment
3025 ;;--- ------- -------
3029 sdcdb-next-from-src SDCDB
3032 sdcdb-back-from-src SDCDB
3035 sdcdb-cont-from-src SDCDB
3038 sdcdb-step-from-src SDCDB
3041 sdcdb-whatis-c-sexp SDCDB
3042 ptypecommand for data at
3046 sdcdbsrc-delete SDCDB
3047 Delete all breakpoints if no arg
3049 or delete arg (C-u arg x)
3051 sdcdbsrc-frame SDCDB
3052 Display current frame if no arg,
3054 or display frame arg
3058 sdcdbsrc-goto-sdcdb Goto
3059 the SDCDB output buffer
3061 sdcdb-print-c-sexp SDCDB
3062 print command for data at
3066 sdcdbsrc-goto-sdcdb Goto
3067 the SDCDB output buffer
3069 sdcdbsrc-mode Toggles
3070 Sdcdbsrc mode (turns it off)
3073 sdcdb-finish-from-src SDCDB
3078 break for line with point
3080 sdcdbsrc-mode Toggle
3090 8.1 The Z80 and gbz80 port
3092 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's
3093 Z80-like gbz80. The port is incomplete - long support is
3094 incomplete (mul, div and mod are unimplimented), and both
3095 float and bitfield support is missing, but apart from that
3096 the code generated is correct.
3098 As always, the code is the authoritave reference - see z80/ralloc.c
3099 and z80/gen.c. The stack frame is similar to that generated
3100 by the IAR Z80 compiler. IX is used as the base pointer,
3101 HL is used as a temporary register, and BC and DE are available
3102 for holding varibles. IY is currently unusued. Return values
3103 are stored in HL. One bad side effect of using IX as the
3104 base pointer is that a functions stack frame is limited
3105 to 127 bytes - this will be fixed in a later version.
3109 SDCC has grown to be large project, the compiler alone (without
3110 the Assembler Package, Preprocessor) is about 40,000 lines
3111 of code (blank stripped). The open source nature of this
3112 project is a key to its continued growth and support. You
3113 gain the benefit and support of many active software developers
3114 and end users. Is SDCC perfect? No, that's why we need your
3115 help. The developers take pride in fixing reported bugs.
3116 You can help by reporting the bugs and helping other SDCC
3117 users. There are lots of ways to contribute, and we encourage
3118 you to take part in making SDCC a great software package.
3122 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
3123 or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed
3124 ASAP. When reporting a bug, it is very useful to include
3125 a small test program which reproduces the problem. If you
3126 can isolate the problem by looking at the generated assembly
3127 code, this can be very helpful. Compiling your program with
3128 the --dumpall option can sometimes be useful in locating
3129 optimization problems.
3133 Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler,
3134 MCS51 code generator, Debugger, AVR port
3135 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version
3137 John Hartman (jhartman@compuserve.com) - Porting ASXXX &
3139 Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
3141 Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his
3143 Malini Dutta(malini_dutta@hotmail.com) - my wife for her
3144 patience and support.
3145 Unknown - for the GNU C - preprocessor.
3146 Michael Hope - The Z80 and Z80GB port, 186 development
3147 Kevin Vigor - The DS390 port.
3148 Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
3149 Scott Datallo - PIC port.
3150 (Thanks to all the other volunteer developers who have helped
3151 with coding, testing, web-page creation, distribution sets,
3152 etc. You know who you are :-)
3155 This document initially written by Sandeep Dutta
3157 All product names mentioned herein may be trademarks of their
3158 respective companies.