3 SDCC Compiler User Guide
10 Typographic conventions
11 Compatibility with previous versions
16 Linux/Unix Installation
18 Windows Install Using a Binary Package
19 Windows Install Using Cygwin
20 Testing out the SDCC Compiler
21 Install Trouble-shooting
22 SDCC cannot find libraries or header files.
23 SDCC does not compile correctly.
24 What the ./configure does
26 What the make install command does.
27 Additional Information for Windows Users
28 Getting started with Cygwin
29 Running SDCC as Native Compiled Executables
30 SDCC on Other Platforms
31 Advanced Install Options
34 sdcpp (C-Preprocessor)
35 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 (The Assemblers and Linkage Editors)
37 sdcdb - Source Level Debugger
40 Single Source File Projects
41 Projects with Multiple Source Files
42 Projects with Additional Libraries
44 Processor Selection Options
51 Intermediate Dump Options
52 MCS51/DS390 Storage Class Language Extensions
59 Parameters & Local Variables
61 Interrupt Service Routines
64 Functions using private banks
68 int(16 bit) and long (32 bit) Support
69 Floating Point Support
72 Defines Created by the Compiler
75 Sub-expression Elimination
80 Algebraic Simplifications
82 Bit-shifting Operations.
87 <pending: this is messy and incomplete> Library Routines
88 Interfacing with Assembly Routines
89 Global Registers used for Parameter Passing
90 Assembler Routine(non-reentrant)
91 Assembler Routine(reentrant)
96 Notes on MCS51 memory layout
97 Retargetting for other MCUs.
98 SDCDB - Source Level Debugger
99 Compiling for Debugging
100 How the Debugger Works
101 Starting the Debugger
102 Command Line Options.
104 break [line | file:line | function | file:function]
105 clear [line | file:line | function | file:function ]
109 info [break | stack | frame | registers ]
120 Interfacing with XEmacs.
122 The Z80 and gbz80 port
133 SDCC is a Freeware, 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 DS80C390 variant.
137 It can be retargetted for other microprocessors, support
138 for PIC, AVR and 186 is under development. The entire source
139 code for the compiler is distributed under GPL. SDCC uses
140 ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
141 SDCC has extensive language extensions suitable for utilizing
142 various microcontrollers and underlying hardware effectively.
145 In addition to the MCU specific optimizations SDCC also does
146 a host of standard optimizations like:
148 global sub expression elimination,
150 loop optimizations (loop invariant, strength reduction
151 of induction variables and loop reversing),
153 constant folding & propagation,
157 dead code elimination
159 jumptables for switch statements.
161 For the back-end SDCC uses a global register allocation scheme
162 which should be well suited for other 8 bit MCUs.
164 The peep hole optimizer uses a rule based substitution mechanism
165 which is MCU independent.
167 Supported data-types are:
169 char (8 bits, 1 byte),
171 short and int (16 bits, 2 bytes),
173 long (32 bit, 4 bytes)
177 The compiler also allows inline assembler code to be embedded
178 anywhere in a function. In addition, routines developed
179 in assembly can also be called.
181 SDCC also provides an option (--cyclomatic) to report the
182 relative complexity of a function. These functions can then
183 be further optimized, or hand coded in assembly if needed.
186 SDCC also comes with a companion source level debugger SDCDB,
187 the debugger currently uses ucSim a freeware simulator for
188 8051 and other micro-controllers.
190 The latest version can be downloaded from [http://sdcc.sourceforge.net/].
194 All packages used in this compiler system are opensource
195 and freeware; source code for all the sub-packages (asxxxx
196 assembler/linker, pre-processor) is distributed with the
197 package. This documentation is maintained using a freeware
198 word processor (LyX).
200 This program is free software; you can redistribute it and/or
201 modify it under the terms of the GNU General Public License
202 as published by the Free Software Foundation; either version
203 2, or (at your option) any later version. This program is
204 distributed in the hope that it will be useful, but WITHOUT
205 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
206 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
207 Public License for more details. You should have received
208 a copy of the GNU General Public License along with this
209 program; if not, write to the Free Software Foundation,
210 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
211 In other words, you are welcome to use, share and improve
212 this program. You are forbidden to forbid anyone else to
213 use, share and improve what you give them. Help stamp out
216 Typographic conventions
218 Throughout this manual, we will use the following convention.
219 Commands you have to type in are printed in "sans serif".
220 Code samples are printed in typewriter font. Interesting
221 items and new terms are printed in italicised type.
223 Compatibility with previous versions
225 This version has numerous bug fixes compared with the previous
226 version. But we also introduced some incompatibilities with
227 older versions. Not just for the fun of it, but to make
228 the compiler more stable, efficient and ANSI compliant.
231 short is now equivalent to int (16 bits), it used to be
232 equivalent to char (8 bits)
234 the default directory where include, library and documention
235 files are stored is no in /usr/local/share
237 char type parameters to vararg functions are casted to
238 int unless explicitly casted, e.g.:
240 printf ("%d %c\n", a, (char)a);
241 will push a as an int and as a char resp.
243 option --regextend has been removed
245 option --noreparms has been removed
247 <pending: more incompatibilities?>
251 What do you need before you start installation of SDCC? A
252 computer, and a desire to compute. The preferred method
253 of installation is to compile SDCC from source using GNU
254 gcc and make. For Windows some pre-compiled binary distributions
255 are available for your convenience. You should have some
256 experience with command line tools and compiler use.
260 The SDCC home page at [http://sdcc.sourceforge.net/]
261 is a great place to find distribution sets. You can also
262 find links to the user mailing lists that offer help or
263 discuss SDCC with other SDCC users. Web links to other SDCC
264 related sites can also be found here. This document can
265 be found in the DOC directory of the source package as a
266 text or HTML file. Some of the other tools (simulator and
267 assembler) included with SDCC contain their own documentation
268 and can be found in the source distribution. If you want
269 the latest unreleased software, the complete source package
270 is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
272 Wishes for the future
274 There are (and always will be) some things that could be
275 done. Here are some I can think of:
278 sdcc -c --model-large -o large _atoi.c (where large could
279 be a different basename or a directory)
282 char KernelFunction3(char p) at 0x340;
284 If you can think of some more, please send them to the list.
286 <pending: And then of course a proper index-table>
290 Linux/Unix Installation
292 Download the source package, it will be named something
295 Bring up a command line terminal, such as xterm.
297 Unpack the file using a command like: "tar -xzf sdcc-2.x.x.tgz",
298 this will create a sub-directory called sdcc with all
301 Change directory into the main SDCC directory, for example
304 Type "./configure". This configures the package for compilation
307 Type "make". All of the source packages will compile, this
310 Type "make install" as root. This copies the binary executables,
311 the include files, the libraries and the documentation
312 to the install directories.
316 <pending: is this complete? where is borland, mingw>
318 For installation under Windows you first need to pick between
319 a pre-compiled binary package, or installing the source
320 package along with the Cygwin package. The binary package
321 is the quickest to install, while the Cygwin package includes
322 all of the open source power tools used to compile the complete
323 SDCC source package in the Windows environment. If you are
324 not familiar with the Unix command line environment, you
325 may want to read the section on additional information for
326 Windows users prior to your initial installation.
328 Windows Install Using a Binary Package
330 Download the binary package and unpack it using your favorite
331 unpacking tool (gunzip, WinZip, etc). This should unpack
332 to a group of sub-directories. An example directory structure
333 after unpacking is: c:\usr\local\bin for the executables,
334 c:\usr\local\share\sdcc\include and c:\usr\local\share\sdcc\lib
335 for the include and libraries.
337 Adjust your environment PATH to include the location of
338 the bin directory. For example, make a setsdcc.bat file
339 with the following: set PATH=c:\usr\local\bin;%PATH%
341 When you compile with sdcc, you may need to specify the
342 location of the lib and include folders. For example,
343 sdcc -I c:\usr\local\share\sdcc\include -L c:\usr\local\share\sdcc\lib\small
346 Windows Install Using Cygwin
348 Download and install the cygwin package from the redhat
349 site[http://sources.redhat.com/cygwin/]. Currently,
350 this involved downloading a small install program which
351 then automates downloading and installing selected parts
352 of the package (a large 80M byte sized dowload for the
355 Bring up a Unix/Bash command line terminal from the Cygwin
358 Follow the instructions in the preceding Linux/Unix installation
361 Testing out the SDCC Compiler
363 The first thing you should do after installing your SDCC
364 compiler is to see if it runs. Type "sdcc --version" at
365 the prompt, and the program should run and tell you the
366 version. If it doesn't run, or gives a message about not
367 finding sdcc program, then you need to check over your installation.
368 Make sure that the sdcc bin directory is in your executable
369 search path defined by the PATH environment setting (see
370 the Trouble-shooting section for suggestions). Make sure
371 that the sdcc program is in the bin folder, if not perhaps
372 something did not install correctly.
374 SDCC binaries are commonly installed in a directory arrangement
377 +--------------------------------+-------------------------------------------+
378 | /usr/local/bin | Holds executables(sdcc, s51, aslink, ...) |
379 +--------------------------------+-------------------------------------------+
380 +--------------------------------+-------------------------------------------+
381 | /usr/local/share/sdcc/lib | Holds common C libraries |
382 +--------------------------------+-------------------------------------------+
383 | /usr/local/share/sdcc/include | Holds common C header files |
384 +--------------------------------+-------------------------------------------+
387 Make sure the compiler works on a very simple example. Type
388 in the following test.c program using your favorite editor:
394 Compile this using the following command: "sdcc -c test.c".
395 If all goes well, the compiler will generate a test.asm
396 and test.rel file. Congratulations, you've just compiled
397 your first program with SDCC. We used the -c option to tell
398 SDCC not to link the generated code, just to keep things
399 simple for this step.
401 The next step is to try it with the linker. Type in "sdcc
402 test.c". If all goes well the compiler will link with the
403 libraries and produce a test.ihx output file. If this step
404 fails (no test.ihx, and the linker generates warnings),
405 then the problem is most likely that sdcc cannot find the
406 /usr/local/share/sdcc/lib directory (see the Install trouble-shooting
407 section for suggestions).
409 The final test is to ensure sdcc can use the standard header
410 files and libraries. Edit test.c and change it to the following:
415 strcpy(str1, "testing");
418 Compile this by typing "sdcc test.c". This should generate
419 a test.ihx output file, and it should give no warnings such
420 as not finding the string.h file. If it cannot find the
421 string.h file, then the problem is that sdcc cannot find
422 the /usr/local/share/sdcc/include directory (see the Install
423 trouble-shooting section for suggestions).
425 Install Trouble-shooting
427 SDCC cannot find libraries or header files.
429 The default installation assumes the libraries and header
430 files are located at "/usr/local/share/sdcc/lib"
431 and "/usr/local/share/sdcc/include".
432 An alternative is to specify these locations as compiler
433 options like this: "sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include test.c".
435 SDCC does not compile correctly.
437 A thing to try is starting from scratch by unpacking the
438 .tgz source package again in an empty directory. Confure
439 it again and build like:
441 make 2&>1 | tee make.log
443 After this you can review the make.log file to locate the
444 problem. Or a relevant part of this be attached to an email
445 that could be helpful when requesting help from the mailing
448 What the "./configure"
451 The "./configure" command is a script
452 that analyzes your system and performs some configuration
453 to ensure the source package compiles on your system. It
454 will take a few minutes to run, and will compile a few tests
455 to determine what compiler features are installed.
457 What the "make" does.
459 This runs the GNU make tool, which automatically compiles
460 all the source packages into the final installed binary
463 What the "make install"
466 This will install the compiler, other executables and libraries
467 in to the appropriate system directories. The default is
468 to copy the executables to /usr/local/bin and the libraries
469 and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
471 Additional Information for Windows Users
473 <pending: is this up to date?>
475 The standard method of installing on a Unix system involves
476 compiling the source package. This is easily done under
477 Unix, but under Windows it can be a more difficult process.
478 The Cygwin is a large package to download, and the compilation
479 runs considerably slower under Windows due to the overhead
480 of the Cygwin tool set. An alternative is to install a pre-compiled
481 Windows binary package. There are various trade-offs between
482 each of these methods.
484 The Cygwin package allows a Windows user to run a Unix command
485 line interface (bash shell) and also implements a Unix like
486 file system on top of Windows. Included are many of the
487 famous GNU software development tools which can augment
488 the SDCC compiler.This is great if you have some experience
489 with Unix command line tools and file system conventions,
490 if not you may find it easier to start by installing a binary
491 Windows package. The binary packages work with the Windows
492 file system conventions.
494 Getting started with Cygwin
496 SDCC is typically distributed as a tarred/gzipped file (.tgz).
497 This is a packed file similar to a .zip file. Cygwin includes
498 the tools you will need to unpack the SDCC distribution
499 (tar and gzip). To unpack it, simply follow the instructions
500 under the Linux/Unix install section. Before you do this
501 you need to learn how to start a cygwin shell and some of
502 the basic commands used to move files, change directory,
503 run commands and so on. The change directory command is
504 "cd", the move command is "mv".
505 To print the current working directory, type "pwd".
506 To make a directory, use "mkdir".
508 There are some basic differences between Unix and Windows
509 file systems you should understand. When you type in directory
510 paths, Unix and the Cygwin bash prompt uses forward slashes
511 '/' between directories while Windows traditionally uses
512 '\' backward slashes. So when you work at the Cygwin bash
513 prompt, you will need to use the forward '/' slashes. Unix
514 does not have a concept of drive letters, such as "c:",
515 instead all files systems attach and appear as directories.
517 Running SDCC as Native Compiled Executables
519 If you use the pre-compiled binaries, the install directories
520 for the libraries and header files may need to be specified
521 on the sdcc command line like this: "sdcc -L c:\usr\local\sdcc\lib\small
522 -I c:\usr\local\sdcc\include test.c" if you are running outside
523 of a Unix bash shell.
525 If you have successfully installed and compiled SDCC with
526 the Cygwin package, it is possible to compile into native
527 .exe files by using the additional makefiles included for
528 this purpose. For example, with the Borland 32-bit compiler
529 you would run "make -f Makefile.bcc". A command line version
530 of the Borland 32-bit compiler can be downloaded from the
533 SDCC on Other Platforms
535 FreeBSD and other non-GNU Unixes - Make sure the GNU make
536 is installed as the default make tool.
538 SDCC has been ported to run under a variety of operating
539 systems and processors. If you can run GNU GCC/make then
540 chances are good SDCC can be compiled and run on your
543 Advanced Install Options
545 The "configure" command has several options.
546 The most commonly used option is --prefix=<directory name>,
547 where <directory name> is the final location for the sdcc
548 executables and libraries, (default location is /usr/local).
549 The installation process will create the following directory
550 structure under the <directory name> specified (if they
551 do not already exist).
553 bin/ - binary exectables (add to PATH environment variable)
555 bin/share/sdcc/include/ - include header files
557 bin/share/sdcc/lib/small/ - Object & library files for small
559 bin/share/sdcc/lib/large/ - Object & library files for large
561 bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390
564 The command "./configure --prefix=/usr/local"
565 will configure the compiler to be installed in directory
570 SDCC is not just a compiler, but a collection of tools by
571 various developers. These include linkers, assemblers, simulators
572 and other components. Here is a summary of some of the components.
573 Note that the included simulator and assembler have separate
574 documentation which you can find in the source package in
575 their respective directories. As SDCC grows to include support
576 for other processors, other packages from various developers
577 are included and may have their own sets of documentation.
579 You might want to look at the files which are installed in
580 <installdir>. At the time of this writing, we find the following
587 sdcpp - The C preprocessor.
589 asx8051 - The assembler for 8051 type processors.
591 as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers.
593 aslink -The linker for 8051 type processors.
595 link-z80, link-gbz80 - The Z80 and GameBoy Z80 linkers.
597 s51 - The ucSim 8051 simulator.
599 sdcdb - The source debugger.
601 packihx - A tool to pack Intel hex files.
603 In <installdir>/share/sdcc/include
607 In <installdir>/share/sdcc/lib
609 the sources of the runtime library and the subdirs small
610 large and ds390 with the precompiled relocatables.
612 In <installdir>/share/sdcc/doc
616 As development for other processors proceeds, this list will
617 expand to include executables to support processors like
622 This is the actual compiler, it in turn uses the c-preprocessor
623 and invokes the assembler and linkage editor.
625 sdcpp (C-Preprocessor)
627 The preprocessor is a modified version of the GNU preprocessor.
628 The C preprocessor is used to pull in #include sources,
629 process #ifdef statements, #defines and so on.
631 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80
632 (The Assemblers and Linkage Editors)
634 This is retargettable assembler & linkage editor, it was
635 developed by Alan Baldwin. John Hartman created the version
636 for 8051, and I (Sandeep) have made some enhancements and
637 bug fixes for it to work properly with the SDCC.
641 S51 is a freeware, opensource simulator developed by Daniel
642 Drotos ([mailto:drdani@mazsola.iit.uni-miskolc.hu]).
643 The simulator is built as part of the build process. For
644 more information visit Daniel's website at: [http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51] .
646 sdcdb - Source Level Debugger
648 Sdcdb is the companion source level debugger. The current
649 version of the debugger uses Daniel's Simulator S51, but
650 can be easily changed to use other simulators.
656 Single Source File Projects
658 For single source file 8051 projects the process is very
659 simple. Compile your programs with the following command
660 "sdcc sourcefile.c". This will compile, assemble and link
661 your source file. Output files are as follows
663 sourcefile.asm - Assembler source file created by the compiler
664 sourcefile.lst - Assembler listing file created by the Assembler
665 sourcefile.rst - Assembler listing file updated with linkedit
666 information, created by linkage editor
667 sourcefile.sym - symbol listing for the sourcefile, created
669 sourcefile.rel - Object file created by the assembler, input
671 sourcefile.map - The memory map for the load module, created
673 sourcefile.ihx - The load module in Intel hex format (you
674 can select the Motorola S19 format with --out-fmt-s19)
675 sourcefile.cdb - An optional file (with --debug) containing
679 Projects with Multiple Source Files
681 SDCC can compile only ONE file at a time. Let us for example
682 assume that you have a project containing the following
685 foo1.c (contains some functions)
686 foo2.c (contains some more functions)
687 foomain.c (contains more functions and the function main)
689 The first two files will need to be compiled separately with
695 Then compile the source file containing the main() function
696 and link the files together with the following command:
699 sdcc foomain.c foo1.rel foo2.rel
701 Alternatively, foomain.c can be separately compiled as well:
705 sdcc foomain.rel foo1.rel foo2.rel
707 The file containing the main() function must be the first
708 file specified in the command line, since the linkage editor
709 processes file in the order they are presented to it.
711 Projects with Additional Libraries
713 Some reusable routines may be compiled into a library, see
714 the documentation for the assembler and linkage editor (which
715 are in <installdir>/share/sdcc/doc) for how to create a
716 .lib library file. Libraries created in this manner can
717 be included in the command line. Make sure you include the
718 -L <library-path> option to tell the linker where to look
719 for these files if they are not in the current directory.
720 Here is an example, assuming you have the source file foomain.c
721 and a library foolib.lib in the directory mylib (if that
722 is not the same as your current project):
724 sdcc foomain.c foolib.lib -L mylib
726 Note here that mylib must be an absolute path name.
728 The most efficient way to use libraries is to keep seperate
729 modules in seperate source files. The lib file now should
730 name all the modules.rel files. For an example see the standard
731 library file libsdcc.lib in the directory <installdir>/share/lib/small.
735 Processor Selection Options
737 -mmcs51 Generate code for the MCS51 (8051) family of processors.
738 This is the default processor target.
740 -mds390 Generate code for the DS80C390 processor.
742 -mz80 Generate code for the Z80 family of processors.
744 -mgbz80 Generate code for the GameBoy Z80 processor.
746 -mavr Generate code for the Atmel AVR processor(In development,
749 -mpic14 Generate code for the PIC 14-bit processors(In development,
752 -mtlcs900h Generate code for the Toshiba TLCS-900H processor(In
753 development, not complete).
757 -I<path> The additional location where the pre processor
758 will look for <..h> or "..h"
761 -D<macro[=value]> Command line definition of macros. Passed
762 to the pre processor.
764 -M Tell the preprocessor to output a rule suitable for make
765 describing the dependencies of each object file. For each
766 source file, the preprocessor outputs one make-rule whose
767 target is the object file name for that source file and
768 whose dependencies are all the files `#include'd in it.
769 This rule may be a single line or may be continued with
770 `\'-newline if it is long. The list of rules is printed on
771 standard output instead of the preprocessed C program. `-M'
774 -C Tell the preprocessor not to discard comments. Used with
777 -MM Like `-M' but the output mentions only the user header
778 files included with `#include "file"'.
779 System header files included with `#include <file>' are
782 -Aquestion(answer) Assert the answer answer for question,
783 in case it is tested with a preprocessor conditional such
784 as `#if #question(answer)'. `-A-' disables the standard
785 assertions that normally describe the target machine.
787 -Aquestion (answer) Assert the answer answer for question,
788 in case it is tested with a preprocessor conditional such
789 as `#if #question(answer)'. `-A-' disables the standard
790 assertions that normally describe the target machine.
792 -Umacro Undefine macro macro. `-U' options are evaluated
793 after all `-D' options, but before any `-include' and `-imacros'
796 -dM Tell the preprocessor to output only a list of the macro
797 definitions that are in effect at the end of preprocessing.
798 Used with the `-E' option.
800 -dD Tell the preprocessor to pass all macro definitions into
801 the output, in their proper sequence in the rest of the
804 -dN Like `-dD' except that the macro arguments and contents
805 are omitted. Only `#define name' is included in the output.
809 -L --lib-path <absolute path to additional libraries> This
810 option is passed to the linkage editor's additional libraries
811 search path. The path name must be absolute. Additional
812 library files may be specified in the command line. See
813 section Compiling programs for more details.
815 --xram-loc<Value> The start location of the external ram,
816 default value is 0. The value entered can be in Hexadecimal
817 or Decimal format, e.g.: --xram-loc 0x8000 or --xram-loc
820 --code-loc<Value> The start location of the code segment,
821 default value 0. Note when this option is used the interrupt
822 vector table is also relocated to the given address. The
823 value entered can be in Hexadecimal or Decimal format, e.g.:
824 --code-loc 0x8000 or --code-loc 32768.
826 --stack-loc<Value> The initial value of the stack pointer.
827 The default value of the stack pointer is 0x07 if only register
828 bank 0 is used, if other register banks are used then the
829 stack pointer is initialized to the location above the highest
830 register bank used. eg. if register banks 1 & 2 are used
831 the stack pointer will default to location 0x18. The value
832 entered can be in Hexadecimal or Decimal format, eg. --stack-loc
833 0x20 or --stack-loc 32. If all four register banks are used
834 the stack will be placed after the data segment (equivalent
835 to --stack-after-data)
837 --stack-after-data This option will cause the stack to be
838 located in the internal ram after the data segment.
840 --data-loc<Value> The start location of the internal ram
841 data segment, the default value is 0x30.The value entered
842 can be in Hexadecimal or Decimal format, eg. --data-loc
843 0x20 or --data-loc 32.
845 --idata-loc<Value> The start location of the indirectly addressable
846 internal ram, default value is 0x80. The value entered can
847 be in Hexadecimal or Decimal format, eg. --idata-loc 0x88
850 --out-fmt-ihx The linker output (final object code) is in
851 Intel Hex format. (This is the default option).
853 --out-fmt-s19 The linker output (final object code) is in
858 --model-large Generate code for Large model programs see
859 section Memory Models for more details. If this option is
860 used all source files in the project should be compiled
861 with this option. In addition the standard library routines
862 are compiled with small model, they will need to be recompiled.
864 --model-small Generate code for Small Model programs see
865 section Memory Models for more details. This is the default
870 --model-flat24 Generate 24-bit flat mode code. This is the
871 one and only that the ds390 code generator supports right
872 now and is default when using -mds390. See section Memory
873 Models for more details.
875 --stack-10bit Generate code for the 10 bit stack mode of
876 the Dallas DS80C390 part. This is the one and only that
877 the ds390 code generator supports right now and is default
878 when using -mds390. In this mode, the stack is located in
879 the lower 1K of the internal RAM, which is mapped to 0x400000.
880 Note that the support is incomplete, since it still uses
881 a single byte as the stack pointer. This means that only
882 the lower 256 bytes of the potential 1K stack space will
883 actually be used. However, this does allow you to reclaim
884 the precious 256 bytes of low RAM for use for the DATA and
885 IDATA segments. The compiler will not generate any code
886 to put the processor into 10 bit stack mode. It is important
887 to ensure that the processor is in this mode before calling
888 any re-entrant functions compiled with this option. In principle,
889 this should work with the --stack-auto option, but that
890 has not been tested. It is incompatible with the --xstack
891 option. It also only makes sense if the processor is in
892 24 bit contiguous addressing mode (see the --model-flat24
897 --nogcse Will not do global subexpression elimination, this
898 option may be used when the compiler creates undesirably
899 large stack/data spaces to store compiler temporaries. A
900 warning message will be generated when this happens and
901 the compiler will indicate the number of extra bytes it
902 allocated. It recommended that this option NOT be used,
903 #pragma NOGCSE can be used to turn off global subexpression
904 elimination for a given function only.
906 --noinvariant Will not do loop invariant optimizations, this
907 may be turned off for reasons explained for the previous
908 option. For more details of loop optimizations performed
909 see section Loop Invariants.It recommended that this option
910 NOT be used, #pragma NOINVARIANT can
911 be used to turn off invariant optimizations for a given
914 --noinduction Will not do loop induction optimizations, see
915 section strength reduction for more details.It is recommended
916 that this option is NOT used, #pragma NOINDUCTION
917 can be used to turn off induction optimizations for a given
920 --nojtbound Will not generate boundary condition check when
921 switch statements are implemented using jump-tables. See
922 section Switch Statements for more details. It is recommended
923 that this option is NOT used, #pragma NOJTBOUND
924 can be used to turn off boundary checking for jump tables
925 for a given function only.
927 --noloopreverse Will not do loop reversal optimization.
931 -c --compile-only will compile and assemble the source,
932 but will not call the linkage editor.
934 -E Run only the C preprocessor. Preprocess all the C source
935 files specified and output the results to standard output.
937 --stack-auto All functions in the source file will be compiled
938 as reentrant, i.e. the parameters and local variables will
939 be allocated on the stack. see section Parameters and Local
940 Variables for more details. If this option is used all source
941 files in the project should be compiled with this option.
943 --xstack Uses a pseudo stack in the first 256 bytes in the
944 external ram for allocating variables and passing parameters.
945 See section on external stack for more details.
947 --callee-saves function1[,function2][,function3].... The
948 compiler by default uses a caller saves convention for register
949 saving across function calls, however this can cause unneccessary
950 register pushing & popping when calling small functions
951 from larger functions. This option can be used to switch
952 the register saving convention for the function names specified.
953 The compiler will not save registers when calling these
954 functions, no extra code will be generated at the entry
955 & exit for these functions to save & restore the registers
956 used by these functions, this can SUBSTANTIALLY reduce code
957 & improve run time performance of the generated code. In
958 the future the compiler (with interprocedural analysis)
959 will be able to determine the appropriate scheme to use
960 for each function call. DO NOT use this option for built-in
961 functions such as _muluint..., if this option is used for
962 a library function the appropriate library function needs
963 to be recompiled with the same option. If the project consists
964 of multiple source files then all the source file should
965 be compiled with the same --callee-saves option string.
966 Also see #pragma CALLEE-SAVES.
968 --debug When this option is used the compiler will generate
969 debug information, that can be used with the SDCDB. The
970 debug information is collected in a file with .cdb extension.
971 For more information see documentation for SDCDB.
973 --regextend This option is obsolete and isn't supported
976 --noregparms This option is obsolete and isn't supported
979 --peep-file<filename> This option can be used to use additional
980 rules to be used by the peep hole optimizer. See section
981 Peep Hole optimizations for details on how to write these
984 -S Stop after the stage of compilation proper; do not assemble.
985 The output is an assembler code file for the input file
988 -Wa_asmOption[,asmOption]... Pass the asmOption to the assembler.
990 -Wl_linkOption[,linkOption]... Pass the linkOption to the
993 --int-long-reent Integer (16 bit) and long (32 bit) libraries
994 have been compiled as reentrant. Note by default these libraries
995 are compiled as non-reentrant. See section Installation
998 --cyclomatic This option will cause the compiler to generate
999 an information message for each function in the source file.
1000 The message contains some important information about the
1001 function. The number of edges and nodes the compiler detected
1002 in the control flow graph of the function, and most importantly
1003 the cyclomatic complexity see section on Cyclomatic Complexity
1006 --float-reent Floating point library is compiled as reentrant.See
1007 section Installation for more details.
1009 --nooverlay The compiler will not overlay parameters and
1010 local variables of any function, see section Parameters
1011 and local variables for more details.
1013 --main-return This option can be used when the code generated
1014 is called by a monitor program. The compiler will generate
1015 a 'ret' upon return from the 'main' function. The default
1016 option is to lock up i.e. generate a 'ljmp '.
1018 --no-peep Disable peep-hole optimization.
1020 --peep-asm Pass the inline assembler code through the peep
1021 hole optimizer. This can cause unexpected changes to inline
1022 assembler code, please go through the peephole optimizer
1023 rules defined in the source file tree '<target>/peeph.def'
1024 before using this option.
1026 --iram-size<Value> Causes the linker to check if the interal
1027 ram usage is within limits of the given value.
1029 --nostdincl This will prevent the compiler from passing on
1030 the default include path to the preprocessor.
1032 --nostdlib This will prevent the compiler from passing on
1033 the default library path to the linker.
1035 --verbose Shows the various actions the compiler is performing.
1037 -V Shows the actual commands the compiler is executing.
1039 Intermediate Dump Options
1041 The following options are provided for the purpose of retargetting
1042 and debugging the compiler. These provided a means to dump
1043 the intermediate code (iCode) generated by the compiler
1044 in human readable form at various stages of the compilation
1047 --dumpraw This option will cause the compiler to dump the
1048 intermediate code into a file of named <source filename>.dumpraw
1049 just after the intermediate code has been generated for
1050 a function, i.e. before any optimizations are done. The
1051 basic blocks at this stage ordered in the depth first number,
1052 so they may not be in sequence of execution.
1054 --dumpgcse Will create a dump of iCode's, after global subexpression
1055 elimination, into a file named <source filename>.dumpgcse.
1057 --dumpdeadcode Will create a dump of iCode's, after deadcode
1058 elimination, into a file named <source filename>.dumpdeadcode.
1060 --dumploop Will create a dump of iCode's, after loop optimizations,
1061 into a file named <source filename>.dumploop.
1063 --dumprange Will create a dump of iCode's, after live range
1064 analysis, into a file named <source filename>.dumprange.
1066 --dumlrange Will dump the life ranges for all symbols.
1068 --dumpregassign Will create a dump of iCode's, after register
1069 assignment, into a file named <source filename>.dumprassgn.
1071 --dumplrange Will create a dump of the live ranges of iTemp's
1073 --dumpall Will cause all the above mentioned dumps to be
1076 MCS51/DS390 Storage Class Language Extensions
1078 In addition to the ANSI storage classes SDCC allows the following
1079 MCS51 specific storage classes.
1083 Variables declared with this storage class will be placed
1084 in the extern RAM. This is the default storage class for
1085 Large Memory model, e.g.:
1087 xdata unsigned char xduc;
1091 This is the default storage class for Small Memory model.
1092 Variables declared with this storage class will be allocated
1093 in the internal RAM, e.g.:
1099 Variables declared with this storage class will be allocated
1100 into the indirectly addressable portion of the internal
1101 ram of a 8051, e.g.:
1107 This is a data-type and a storage class specifier. When a
1108 variable is declared as a bit, it is allocated into the
1109 bit addressable memory of 8051, e.g.:
1115 Like the bit keyword, sfr / sbit signifies both a data-type
1116 and storage class, they are used to describe the special
1117 function registers and special bit variables of a 8051,
1120 sfr at 0x80 P0; /* special function register P0 at location
1122 sbit at 0xd7 CY; /* CY (Carry Flag) */
1126 SDCC allows (via language extensions) pointers to explicitly
1127 point to any of the memory spaces of the 8051. In addition
1128 to the explicit pointers, the compiler also allows a _generic
1129 class of pointers which can be used to point to any of the
1132 Pointer declaration examples:
1134 /* pointer physically in xternal ram pointing to object in
1136 data unsigned char * xdata p;
1138 /* pointer physically in code rom pointing to data in xdata
1140 xdata unsigned char * code p;
1142 /* pointer physically in code space pointing to data in code
1144 code unsigned char * code p;
1146 /* the folowing is a generic pointer physically located in
1150 Well you get the idea.
1152 For compatibility with the previous version of the compiler,
1153 the following syntax for pointer declaration is still supported
1154 but will disappear int the near future.
1156 unsigned char _xdata *ucxdp; /* pointer to data in external
1158 unsigned char _data *ucdp ; /* pointer
1159 to data in internal ram */
1160 unsigned char _code *uccp ; /* pointer
1161 to data in R/O code space */
1162 unsigned char _idata *uccp; /*
1163 pointer to upper 128 bytes of ram */
1165 All unqualified pointers are treated as 3-byte (4-byte for
1166 the ds390) generic pointers. These type of pointers can
1167 also to be explicitly declared.
1169 unsigned char _generic *ucgp;
1171 The highest order byte of the generic pointers contains the
1172 data space information. Assembler support routines are called
1173 whenever data is stored or retrieved using generic pointers.
1174 These are useful for developing reusable library routines.
1175 Explicitly specifying the pointer type will generate the
1176 most efficient code. Pointers declared using a mixture of
1177 OLD and NEW style could have unpredictable results.
1179 Parameters & Local Variables
1181 Automatic (local) variables and parameters to functions can
1182 either be placed on the stack or in data-space. The default
1183 action of the compiler is to place these variables in the
1184 internal RAM (for small model) or external RAM (for Large
1185 model). This in fact makes them static so by default functions
1188 They can be placed on the stack either by using the --stack-auto
1189 compiler option or by using the reentrant keyword in the
1190 function declaration, e.g.:
1192 unsigned char foo(char i) reentrant
1197 Since stack space on 8051 is limited, the reentrant keyword
1198 or the --stack-auto option should be used sparingly. Note
1199 that the reentrant keyword just means that the parameters
1200 & local variables will be allocated to the stack, it does
1201 not mean that the function is register bank independent.
1203 Local variables can be assigned storage classes and absolute
1206 unsigned char foo() {
1207 xdata unsigned char i;
1209 data at 0x31 unsiged char j;
1213 In the above example the variable i will be allocated in
1214 the external ram, bvar in bit addressable space and j in
1215 internal ram. When compiled with --stack-auto or when a
1216 function is declared as reentrant this can only be done
1217 for static variables.
1219 Parameters however are not allowed any storage class, (storage
1220 classes for parameters will be ignored), their allocation
1221 is governed by the memory model in use, and the reentrancy
1226 For non-reentrant functions SDCC will try to reduce internal
1227 ram space usage by overlaying parameters and local variables
1228 of a function (if possible). Parameters and local variables
1229 of a function will be allocated to an overlayable segment
1230 if the function has no other function calls and the function
1231 is non-reentrant and the memory model is small. If an explicit
1232 storage class is specified for a local variable, it will
1235 Note that the compiler (not the linkage editor) makes the
1236 decision for overlaying the data items. Functions that are
1237 called from an interrupt service routine should be preceded
1238 by a #pragma NOOVERLAY if they are not reentrant.
1240 Also note that the compiler does not do any processing of
1241 inline assembler code, so the compiler might incorrectly
1242 assign local variables and parameters of a function into
1243 the overlay segment if the inline assembler code calls other
1244 c-functions that might use the overlay. In that case the
1245 #pragma NOOVERLAY should be used.
1247 Parameters and Local variables of functions that contain
1248 16 or 32 bit multiplication or division will NOT be overlayed
1249 since these are implemented using external functions, e.g.:
1253 void set_error(unsigned char errcd)
1259 void some_isr () interrupt 2 using 1
1266 In the above example the parameter errcd for the function
1267 set_error would be assigned to the overlayable segment if
1268 the #pragma NOOVERLAY was not present, this could
1269 cause unpredictable runtime behavior when called from an
1270 ISR. The #pragma NOOVERLAY ensures that
1271 the parameters and local variables for the function are
1274 Interrupt Service Routines
1276 SDCC allows interrupt service routines to be coded in C,
1277 with some extended keywords.
1279 void timer_isr (void) interrupt 2 using 1
1284 The number following the interrupt keyword is the interrupt
1285 number this routine will service. The compiler will insert
1286 a call to this routine in the interrupt vector table for
1287 the interrupt number specified. The using keyword is used
1288 to tell the compiler to use the specified register bank
1289 (8051 specific) when generating code for this function.
1290 Note that when some function is called from an interrupt
1291 service routine it should be preceded by a #pragma NOOVERLAY
1292 if it is not reentrant. A special note here, int (16 bit)
1293 and long (32 bit) integer division, multiplication & modulus
1294 operations are implemented using external support routines
1295 developed in ANSI-C, if an interrupt service routine needs
1296 to do any of these operations then the support routines
1297 (as mentioned in a following section) will have to be recompiled
1298 using the --stack-auto option and the source file will need
1299 to be compiled using the --int-long-rent compiler option.
1301 If you have multiple source files in your project, interrupt
1302 service routines can be present in any of them, but a prototype
1303 of the isr MUST be present or included in the file that
1304 contains the function main.
1306 Interrupt Numbers and the corresponding address & descriptions
1307 for the Standard 8051 are listed below. SDCC will automatically
1308 adjust the interrupt vector table to the maximum interrupt
1312 +--------------+--------------+----------------+
1313 | Interrupt # | Description | Vector Address |
1314 +--------------+--------------+----------------+
1315 +--------------+--------------+----------------+
1316 | 0 | External 0 | 0x0003 |
1317 +--------------+--------------+----------------+
1318 | 1 | Timer 0 | 0x000B |
1319 +--------------+--------------+----------------+
1320 | 2 | External 1 | 0x0013 |
1321 +--------------+--------------+----------------+
1322 | 3 | Timer 1 | 0x001B |
1323 +--------------+--------------+----------------+
1324 | 4 | Serial | 0x0023 |
1325 +--------------+--------------+----------------+
1328 If the interrupt service routine is defined without using
1329 a register bank or with register bank 0 (using 0), the compiler
1330 will save the registers used by itself on the stack upon
1331 entry and restore them at exit, however if such an interrupt
1332 service routine calls another function then the entire register
1333 bank will be saved on the stack. This scheme may be advantageous
1334 for small interrupt service routines which have low register
1337 If the interrupt service routine is defined to be using a
1338 specific register bank then only a, b & dptr are save and
1339 restored, if such an interrupt service routine calls another
1340 function (using another register bank) then the entire register
1341 bank of the called function will be saved on the stack.
1342 This scheme is recommended for larger interrupt service
1345 Calling other functions from an interrupt service routine
1346 is not recommended, avoid it if possible.
1348 Also see the _naked modifier.
1352 A special keyword may be associated with a function declaring
1353 it as critical. SDCC will generate code to disable all interrupts
1354 upon entry to a critical function and enable them back before
1355 returning. Note that nesting critical functions may cause
1356 unpredictable results.
1364 The critical attribute maybe used with other attributes like
1369 A special keyword may be associated with a function declaring
1370 it as _naked. The _naked function modifier attribute prevents
1371 the compiler from generating prologue and epilogue code
1372 for that function. This means that the user is entirely
1373 responsible for such things as saving any registers that
1374 may need to be preserved, selecting the proper register
1375 bank, generating the return instruction at the end, etc.
1376 Practically, this means that the contents of the function
1377 must be written in inline assembler. This is particularly
1378 useful for interrupt functions, which can have a large (and
1379 often unnecessary) prologue/epilogue. For example, compare
1380 the code generated by these two functions:
1382 data unsigned char counter;
1383 void simpleInterrupt(void) interrupt 1
1388 void nakedInterrupt(void) interrupt 2 _naked
1393 MUST explicitly include ret in _naked function.
1397 For an 8051 target, the generated simpleInterrupt looks like:
1414 whereas nakedInterrupt looks like:
1418 reti ; MUST explicitly
1419 include ret(i) in _naked function.
1421 While there is nothing preventing you from writing C code
1422 inside a _naked function, there are many ways to shoot yourself
1423 in the foot doing this, and is is recommended that you stick
1424 to inline assembler.
1426 Functions using private banks
1428 The using attribute (which tells the compiler to use a register
1429 bank other than the default bank zero) should only be applied
1430 to interrupt functions (see note 1 below). This will in
1431 most circumstances make the generated ISR code more efficient
1432 since it will not have to save registers on the stack.
1434 The using attribute will have no effect on the generated
1435 code for a non-interrupt function (but may occasionally
1436 be useful anyway([footnote] possible exception: if a function is called ONLY
1437 from 'interrupt' functions using a particular bank, it can
1438 be declared with the same 'using' attribute as the calling
1439 'interrupt' functions. For instance, if you have several
1440 ISRs using bank one, and all of them call memcpy(), it might
1441 make sense to create a specialized version of memcpy() 'using
1442 1', since this would prevent the ISR from having to save
1443 bank zero to the stack on entry and switch to bank zero
1444 before calling the function) ).
1445 (pending: I don't think this has been done yet)
1447 An interrupt function using a non-zero bank will assume that
1448 it can trash that register bank, and will not save it. Since
1449 high-priority interrupts can interrupt low-priority ones
1450 on the 8051 and friends, this means that if a high-priority
1451 ISR using a particular bank occurs while processing a low-priority
1452 ISR using the same bank, terrible and bad things can happen.
1453 To prevent this, no single register bank should be used
1454 by both a high priority and a low priority ISR. This is
1455 probably most easily done by having all high priority ISRs
1456 use one bank and all low priority ISRs use another. If you
1457 have an ISR which can change priority at runtime, you're
1458 on your own: I suggest using the default bank zero and taking
1459 the small performance hit.
1461 It is most efficient if your ISR calls no other functions.
1462 If your ISR must call other functions, it is most efficient
1463 if those functions use the same bank as the ISR (see note
1464 1 below); the next best is if the called functions use bank
1465 zero. It is very inefficient to call a function using a
1466 different, non-zero bank from an ISR.
1470 Data items can be assigned an absolute address with the at
1471 <address> keyword, in addition to a storage class, e.g.:
1473 xdata at 0x8000 unsigned char PORTA_8255 ;
1475 In the above example the PORTA_8255 will be allocated to
1476 the location 0x8000 of the external ram. Note that this
1477 feature is provided to give the programmer access to memory
1478 mapped devices attached to the controller. The compiler
1479 does not actually reserve any space for variables declared
1480 in this way (they are implemented with an equate in the
1481 assembler). Thus it is left to the programmer to make sure
1482 there are no overlaps with other variables that are declared
1483 without the absolute address. The assembler listing file
1484 (.lst) and the linker output files (.rst) and (.map) are
1485 a good places to look for such overlaps.
1487 Absolute address can be specified for variables in all storage
1492 The above example will allocate the variable at offset 0x02
1493 in the bit-addressable space. There is no real advantage
1494 to assigning absolute addresses to variables in this manner,
1495 unless you want strict control over all the variables allocated.
1499 The compiler inserts a call to the C routine _sdcc__external__startup()
1500 at the start of the CODE area. This routine is in the runtime
1501 library. By default this routine returns 0, if this routine
1502 returns a non-zero value, the static & global variable initialization
1503 will be skipped and the function main will be invoked Other
1504 wise static & global variables will be initialized before
1505 the function main is invoked. You could add a _sdcc__external__startup()
1506 routine to your program to override the default if you need
1507 to setup hardware or perform some other critical operation
1508 prior to static & global variable initialization.
1510 Inline Assembler Code
1512 SDCC allows the use of in-line assembler with a few restriction
1513 as regards labels. All labels defined within inline assembler
1514 code has to be of the form nnnnn$ where nnnn is a number
1515 less than 100 (which implies a limit of utmost 100 inline
1516 assembler labels per function). It is strongly recommended
1517 that each assembly instruction (including labels) be placed
1518 in a separate line (as the example shows). When the --peep-asm
1519 command line option is used, the inline assembler code will
1520 be passed through the peephole optimizer. This might cause
1521 some unexpected changes in the inline assembler code. Please
1522 go throught the peephole optimizer rules defined in file
1523 SDCCpeeph.def carefully before using this option.
1533 The inline assembler code can contain any valid code understood
1534 by the assembler, this includes any assembler directives
1535 and comment lines. The compiler does not do any validation
1536 of the code within the _asm ... _endasm; keyword pair.
1538 Inline assembler code cannot reference any C-Labels, however
1539 it can reference labels defined by the inline assembler,
1545 ; some assembler code
1548 /* some more c code */
1549 clabel: /* inline assembler cannot reference
1552 $0003: ;label (can be reference by inline assembler
1555 /* some more c code */
1558 In other words inline assembly code can access labels defined
1559 in inline assembly within the scope of the funtion.
1561 The same goes the other way, ie. labels defines in inline
1562 assembly CANNOT be accessed by C statements.
1564 int(16 bit) and long (32 bit) Support
1566 For signed & unsigned int (16 bit) and long (32 bit) variables,
1567 division, multiplication and modulus operations are implemented
1568 by support routines. These support routines are all developed
1569 in ANSI-C to facilitate porting to other MCUs, although
1570 some model specific assembler optimations are used. The
1571 following files contain the described routine, all of them
1572 can be found in <installdir>/share/sdcc/lib.
1574 <pending: tabularise this>
1576 _mulsint.c - signed 16 bit multiplication (calls _muluint)
1577 _muluint.c - unsigned 16 bit multiplication
1578 _divsint.c - signed 16 bit division (calls _divuint)
1579 _divuint.c - unsigned 16 bit division
1580 _modsint.c - signed 16 bit modulus (call _moduint)
1581 _moduint.c - unsigned 16 bit modulus
1582 _mulslong.c - signed 32 bit multiplication (calls _mululong)
1583 _mululong.c - unsigned32 bit multiplication
1584 _divslong.c - signed 32 division (calls _divulong)
1585 _divulong.c - unsigned 32 division
1586 _modslong.c - signed 32 bit modulus (calls _modulong)
1587 _modulong.c - unsigned 32 bit modulus
1589 Since they are compiled as non-reentrant, interrupt service
1590 routines should not do any of the above operations. If this
1591 is unavoidable then the above routines will need to be compiled
1592 with the --stack-auto option, after which the source program
1593 will have to be compiled with --int-long-rent option.
1595 Floating Point Support
1597 SDCC supports IEEE (single precision 4bytes) floating point
1598 numbers.The floating point support routines are derived
1599 from gcc's floatlib.c and consists of the following routines:
1601 <pending: tabularise this>
1603 _fsadd.c - add floating point numbers
1604 _fssub.c - subtract floating point numbers
1605 _fsdiv.c - divide floating point numbers
1606 _fsmul.c - multiply floating point numbers
1607 _fs2uchar.c - convert floating point to unsigned char
1608 _fs2char.c - convert floating point to signed char
1609 _fs2uint.c - convert floating point to unsigned int
1610 _fs2int.c - convert floating point to signed int
1611 _fs2ulong.c - convert floating point to unsigned long
1612 _fs2long.c - convert floating point to signed long
1613 _uchar2fs.c - convert unsigned char to floating point
1614 _char2fs.c - convert char to floating point number
1615 _uint2fs.c - convert unsigned int to floating point
1616 _int2fs.c - convert int to floating point numbers
1617 _ulong2fs.c - convert unsigned long to floating point number
1618 _long2fs.c - convert long to floating point number
1620 Note if all these routines are used simultaneously the data
1621 space might overflow. For serious floating point usage it
1622 is strongly recommended that the large model be used.
1626 SDCC allows two memory models for MCS51 code, small and large.
1627 Modules compiled with different memory models should never
1628 be combined together or the results would be unpredictable.
1629 The library routines supplied with the compiler are compiled
1630 as both small and large. The compiled library modules are
1631 contained in seperate directories as small and large so
1632 that you can link to either set.
1634 When the large model is used all variables declared without
1635 a storage class will be allocated into the external ram,
1636 this includes all parameters and local variables (for non-reentrant
1637 functions). When the small model is used variables without
1638 storage class are allocated in the internal ram.
1640 Judicious usage of the processor specific storage classes
1641 and the 'reentrant' function type will yield much more efficient
1642 code, than using the large model. Several optimizations
1643 are disabled when the program is compiled using the large
1644 model, it is therefore strongly recommdended that the small
1645 model be used unless absolutely required.
1649 The only model supported is Flat 24. This generates code
1650 for the 24 bit contiguous addressing mode of the Dallas
1651 DS80C390 part. In this mode, up to four meg of external
1652 RAM or code space can be directly addressed. See the data
1653 sheets at www.dalsemi.com for further information on this
1656 In older versions of the compiler, this option was used with
1657 the MCS51 code generator (-mmcs51). Now, however, the '390
1658 has it's own code generator, selected by the -mds390 switch.
1661 Note that the compiler does not generate any code to place
1662 the processor into 24 bitmode (although tinibios in the
1663 ds390 libraries will do that for you). If you don't use
1664 tinibios, the boot loader or similar code must ensure that
1665 the processor is in 24 bit contiguous addressing mode before
1666 calling the SDCC startup code.
1668 Like the --model-large option, variables will by default
1669 be placed into the XDATA segment.
1671 Segments may be placed anywhere in the 4 meg address space
1672 using the usual --*-loc options. Note that if any segments
1673 are located above 64K, the -r flag must be passed to the
1674 linker to generate the proper segment relocations, and the
1675 Intel HEX output format must be used. The -r flag can be
1676 passed to the linker by using the option -Wl-r on the sdcc
1677 command line. However, currently the linker can not handle
1678 code segments > 64k.
1680 Defines Created by the Compiler
1682 The compiler creates the following #defines.
1684 SDCC - this Symbol is always defined.
1686 SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on
1687 the model used (e.g.: -mds390)
1689 __mcs51 or __ds390 or __z80, etc - depending on the model
1692 SDCC_STACK_AUTO - this symbol is defined when --stack-auto
1695 SDCC_MODEL_SMALL - when --model-small is used.
1697 SDCC_MODEL_LARGE - when --model-large is used.
1699 SDCC_USE_XSTACK - when --xstack option is used.
1701 SDCC_STACK_TENBIT - when -mds390 is used
1703 SDCC_MODEL_FLAT24 - when -mds390 is used
1709 SDCC performs a host of standard optimizations in addition
1710 to some MCU specific optimizations.
1712 Sub-expression Elimination
1714 The compiler does local and global common subexpression elimination,
1720 will be translated to
1726 Some subexpressions are not as obvious as the above example,
1732 In this case the address arithmetic a->b[i] will be computed
1733 only once; the equivalent code in C would be.
1739 The compiler will try to keep these temporary variables in
1742 Dead-Code Elimination
1747 i = 1; /* dead store */
1748 global = 1; /* dead store */
1751 global = 3; /* unreachable */
1756 int global; void f ()
1780 Note: the dead stores created by this copy propagation will
1781 be eliminated by dead-code elimination.
1785 Two types of loop optimizations are done by SDCC loop invariant
1786 lifting and strength reduction of loop induction variables.
1787 In addition to the strength reduction the optimizer marks
1788 the induction variables and the register allocator tries
1789 to keep the induction variables in registers for the duration
1790 of the loop. Because of this preference of the register
1791 allocator, loop induction optimization causes an increase
1792 in register pressure, which may cause unwanted spilling
1793 of other temporary variables into the stack / data space.
1794 The compiler will generate a warning message when it is
1795 forced to allocate extra space either on the stack or data
1796 space. If this extra space allocation is undesirable then
1797 induction optimization can be eliminated either for the
1798 entire source file (with --noinduction option) or for a
1799 given function only using #pragma NOINDUCTION.
1803 for (i = 0 ; i < 100 ; i ++)
1809 for (i = 0; i < 100; i++)
1812 As mentioned previously some loop invariants are not as apparent,
1813 all static address computations are also moved out of the
1816 Strength Reduction, this optimization substitutes an expression
1817 by a cheaper expression:
1819 for (i=0;i < 100; i++)
1826 for (i=0;i< 100;i++) {
1827 ar[itemp1] = itemp2;
1832 The more expensive multiplication is changed to a less expensive
1837 This optimization is done to reduce the overhead of checking
1838 loop boundaries for every iteration. Some simple loops can
1839 be reversed and implemented using a "decrement
1840 and jump if not zero" instruction. SDCC
1841 checks for the following criterion to determine if a loop
1842 is reversible (note: more sophisticated compilers use data-dependency
1843 analysis to make this determination, SDCC uses a more simple
1846 The 'for' loop is of the form
1848 for (<symbol> = <expression> ; <sym> [< | <=] <expression>
1849 ; [<sym>++ | <sym> += 1])
1852 The <for body> does not contain "continue"
1855 All goto's are contained within the loop.
1857 No function calls within the loop.
1859 The loop control variable <sym> is not assigned any value
1862 The loop control variable does NOT participate in any arithmetic
1863 operation within the loop.
1865 There are NO switch statements in the loop.
1867 Note djnz instruction can be used for 8-bit values only,
1868 therefore it is advantageous to declare loop control symbols
1869 as char. Ofcourse this may not be possible on all situations.
1871 Algebraic Simplifications
1873 SDCC does numerous algebraic simplifications, the following
1874 is a small sub-set of these optimizations.
1876 i = j + 0 ; /* changed to */ i = j;
1877 i /= 2; /* changed to */ i >>= 1;
1878 i = j - j ; /* changed to */ i = 0;
1879 i = j / 1 ; /* changed to */ i = j;
1881 Note the subexpressions given above are generally introduced
1882 by macro expansions or as a result of copy/constant propagation.
1886 SDCC changes switch statements to jump tables when the following
1887 conditions are true.
1889 The case labels are in numerical sequence, the labels need
1890 not be in order, and the starting number need not be one
1912 Both the above switch statements will be implemented using
1915 The number of case labels is at least three, since it takes
1916 two conditional statements to handle the boundary conditions.
1918 The number of case labels is less than 84, since each label
1919 takes 3 bytes and a jump-table can be utmost 256 bytes
1922 Switch statements which have gaps in the numeric sequence
1923 or those that have more that 84 case labels can be split
1924 into more than one switch statement for efficient code generation,
1938 If the above switch statement is broken down into two switch
1957 then both the switch statements will be implemented using
1958 jump-tables whereas the unmodified switch statement will
1961 Bit-shifting Operations.
1963 Bit shifting is one of the most frequently used operation
1964 in embedded programming. SDCC tries to implement bit-shift
1965 operations in the most efficient way possible, e.g.:
1972 generates the following code:
1979 In general SDCC will never setup a loop if the shift count
1980 is known. Another example:
1995 Note that SDCC stores numbers in little-endian format (i.e.
1996 lowest order first).
2000 A special case of the bit-shift operation is bit rotation,
2001 SDCC recognizes the following expression to be a left bit-rotation:
2005 i = ((i << 1) | (i >> 7));
2008 will generate the following code:
2014 SDCC uses pattern matching on the parse tree to determine
2015 this operation.Variations of this case will also be recognized
2016 as bit-rotation, i.e.:
2018 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
2022 It is frequently required to obtain the highest order bit
2023 of an integral type (long, int, short or char types). SDCC
2024 recognizes the following expression to yield the highest
2025 order bit and generates optimized code for it, e.g.:
2032 hob = (gint >> 15) & 1;
2036 will generate the following code:
2056 Variations of this case however will not be recognized. It
2057 is a standard C expression, so I heartily recommend this
2058 be the only way to get the highest order bit, (it is portable).
2059 Of course it will be recognized even if it is embedded in
2060 other expressions, e.g.:
2062 xyz = gint + ((gint >> 15) & 1);
2064 will still be recognized.
2068 The compiler uses a rule based, pattern matching and re-writing
2069 mechanism for peep-hole optimization. It is inspired by
2070 copt a peep-hole optimizer by Christopher W. Fraser (cwfraser@microsoft.com).
2071 A default set of rules are compiled into the compiler, additional
2072 rules may be added with the --peep-file <filename> option.
2073 The rule language is best illustrated with examples.
2082 The above rule will change the following assembly sequence:
2091 Note: All occurrences of a %n (pattern variable) must denote
2092 the same string. With the above rule, the assembly sequence:
2097 will remain unmodified.
2099 Other special case optimizations may be added by the user
2100 (via --peep-file option). E.g. some variants of the 8051
2101 MCU allow only ajmp and acall. The following two rules will
2102 change all ljmp and lcall to ajmp and acall
2104 replace { lcall %1 } by { acall %1 }
2105 replace { ljmp %1 } by { ajmp %1 }
2107 The inline-assembler code is also passed through the peep
2108 hole optimizer, thus the peephole optimizer can also be
2109 used as an assembly level macro expander. The rules themselves
2110 are MCU dependent whereas the rule language infra-structure
2111 is MCU independent. Peephole optimization rules for other
2112 MCU can be easily programmed using the rule language.
2114 The syntax for a rule is as follows:
2116 rule := replace [ restart ] '{' <assembly sequence> '\n'
2122 <assembly sequence> '\n'
2124 '}' [if <functionName>
2127 <assembly sequence> := assembly instruction (each instruction
2128 including labels must be on a separate line).
2130 The optimizer will apply to the rules one by one from the
2131 top in the sequence of their appearance, it will terminate
2132 when all rules are exhausted. If the 'restart' option is
2133 specified, then the optimizer will start matching the rules
2134 again from the top, this option for a rule is expensive
2135 (performance), it is intended to be used in situations where
2136 a transformation will trigger the same rule again. A good
2137 example of this the following rule:
2145 Note that the replace pattern cannot be a blank, but can
2146 be a comment line. Without the 'restart' option only the
2147 inner most 'pop' 'push' pair would be eliminated, i.e.:
2160 with the restart option the rule will be applied again to
2161 the resulting code and then all the pop-push pairs will
2162 be eliminated to yield:
2167 A conditional function can be attached to a rule. Attaching
2168 rules are somewhat more involved, let me illustrate this
2179 The optimizer does a look-up of a function name table defined
2180 in function callFuncByName in the source file SDCCpeeph.c,
2181 with the name labelInRange. If it finds a corresponding
2182 entry the function is called. Note there can be no parameters
2183 specified for these functions, in this case the use of %5
2184 is crucial, since the function labelInRange expects to find
2185 the label in that particular variable (the hash table containing
2186 the variable bindings is passed as a parameter). If you
2187 want to code more such functions, take a close look at the
2188 function labelInRange and the calling mechanism in source
2189 file SDCCpeeph.c. I know this whole thing is a little kludgey,
2190 but maybe some day we will have some better means. If you
2191 are looking at this file, you will also see the default
2192 rules that are compiled into the compiler, you can add your
2193 own rules in the default set there if you get tired of specifying
2194 the --peep-file option.
2198 SDCC supports the following #pragma directives. This directives
2199 are applicable only at a function level.
2201 SAVE - this will save all the current options.
2203 RESTORE - will restore the saved options from the last
2204 save. Note that SAVES & RESTOREs cannot be nested. SDCC
2205 uses the same buffer to save the options each time a SAVE
2208 NOGCSE - will stop global subexpression elimination.
2210 NOINDUCTION - will stop loop induction optimizations.
2212 NOJTBOUND - will not generate code for boundary value checking,
2213 when switch statements are turned into jump-tables.
2215 NOOVERLAY - the compiler will not overlay the parameters
2216 and local variables of a function.
2218 NOLOOPREVERSE - Will not do loop reversal optimization
2220 EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma
2221 disables generation of pair of push/pop instruction in
2222 ISR function (using interrupt keyword). The directive
2223 should be placed immediately before the ISR function definition
2224 and it affects ALL ISR functions following it. To enable
2225 the normal register saving for ISR functions use #pragma EXCLUDE none.
2227 CALLEE-SAVES function1[,function2[,function3...]] - The
2228 compiler by default uses a caller saves convention for
2229 register saving across function calls, however this can
2230 cause unneccessary register pushing & popping when calling
2231 small functions from larger functions. This option can
2232 be used to switch the register saving convention for the
2233 function names specified. The compiler will not save registers
2234 when calling these functions, extra code will be generated
2235 at the entry & exit for these functions to save & restore
2236 the registers used by these functions, this can SUBSTANTIALLY
2237 reduce code & improve run time performance of the generated
2238 code. In future the compiler (with interprocedural analysis)
2239 will be able to determine the appropriate scheme to use
2240 for each function call. If --callee-saves command line
2241 option is used, the function names specified in #pragma CALLEE-SAVES
2242 is appended to the list of functions specified inthe command
2245 The pragma's are intended to be used to turn-off certain
2246 optimizations which might cause the compiler to generate
2247 extra stack / data space to store compiler generated temporary
2248 variables. This usually happens in large functions. Pragma
2249 directives should be used as shown in the following example,
2250 they are used to control options & optimizations for a given
2251 function; pragmas should be placed before and/or after a
2252 function, placing pragma's inside a function body could
2253 have unpredictable results.
2255 #pragma SAVE /* save the current settings */
2256 #pragma NOGCSE /* turnoff global subexpression elimination
2258 #pragma NOINDUCTION /* turn off induction optimizations */
2266 #pragma RESTORE /* turn the optimizations back on */
2268 The compiler will generate a warning message when extra space
2269 is allocated. It is strongly recommended that the SAVE and
2270 RESTORE pragma's be used when changing options for a function.
2272 <pending: this is messy and incomplete> Library Routines
2274 The following library routines are provided for your convenience.
2276 stdio.h - Contains the following functions printf & sprintf
2277 these routines are developed by Martijn van Balen <balen@natlab.research.philips.com>.
2279 %[flags][width][b|B|l|L]type
2282 - left justify output
2283 in specified field width
2285 + prefix output with
2286 +/- sign if output is signed type
2288 space prefix output with a blank if
2289 it's a signed positive value
2291 specifies minimum number of characters outputted for numbers
2296 - For numbers, spaces are added on the left when needed.
2299 If width starts with a zero character, zeroes and used
2303 - For strings, spaces are are added on the left or right
2306 flag '-' is used) when needed.
2310 byte argument (used by d, u, o, x, X)
2312 long argument (used by d, u, o, x, X)
2316 u unsigned decimal number
2319 o unsigned octal number
2322 x unsigned hexadecimal
2325 X unsigned hexadecimal
2330 s string (generic pointer)
2333 p generic pointer (I:data/idata,
2334 C:code, X:xdata, P:paged)
2336 f float (still to be
2339 Also contains a very simple version of printf (printf_small).
2340 This simplified version of printf supports only the following
2343 format output type argument-type
2351 %x hexadecimal short/int
2353 %lx hexadecimal long
2355 %hx hexadecimal char
2365 %s character _generic
2368 The routine is very stack intesive, --stack-after-data parameter
2369 should be used when using this routine, the routine also
2370 takes about 1K of code space. It also expects an external
2371 function named putchar(char) to be present (this can be
2372 changed). When using the %s format the string / pointer
2373 should be cast to a generic pointer. eg.
2375 printf_small("my str %s, my int %d\n",(char
2376 _generic *)mystr,myint);
2378 stdarg.h - contains definition for the following macros
2379 to be used for variable parameter list, note that a function
2380 can have a variable parameter list if and only if it is
2383 va_list, va_start, va_arg, va_end.
2385 setjmp.h - contains defintion for ANSI setjmp & longjmp
2386 routines. Note in this case setjmp & longjmp can be used
2387 between functions executing within the same register bank,
2388 if long jmp is executed from a function that is using
2389 a different register bank from the function issuing the
2390 setjmp function, the results may be unpredictable. The
2391 jump buffer requires 3 bytes of data (the stack pointer
2392 & a 16 byte return address), and can be placed in any
2395 stdlib.h - contains the following functions.
2399 string.h - contains the following functions.
2401 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr,
2402 strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok,
2403 memcpy, memcmp, memset.
2405 ctype.h - contains the following routines.
2407 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct,
2408 isspace, isxdigit, isalnum, isalpha.
2410 malloc.h - The malloc routines are developed by Dmitry
2411 S. Obukhov (dso@usa.net). These routines will allocate
2412 memory from the external ram. Here is a description on
2413 how to use them (as described by the author).
2417 #define DYNAMIC_MEMORY_SIZE 0x2000
2421 unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
2424 unsigned char xdata * current_buffer;
2434 init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
2437 //Now it's possible to use malloc.
2441 current_buffer = malloc(0x100);
2444 serial.h - Serial IO routines are also developed by Dmitry
2445 S. Obukhov (dso@usa.net). These routines are interrupt
2446 driven with a 256 byte circular buffer, they also expect
2447 external ram to be present. Please see documentation in
2448 file SDCCDIR/sdcc51lib/serial.c. Note the header file
2449 "serial.h" MUST be included in the file containing
2450 the 'main' function.
2452 ser.h - Alternate serial routine provided by Wolfgang Esslinger
2453 <wolfgang@WiredMinds.com> these routines are more compact
2454 and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
2456 ser_ir.h - Another alternate set of serial routines provided
2457 by Josef Wolf <jw@raven.inka.de>, these routines do not
2458 use the external ram.
2460 reg51.h - contains register definitions for a standard
2463 float.h - contains min, max and other floating point related
2466 All library routines are compiled as --model-small, they
2467 are all non-reentrant, if you plan to use the large model
2468 or want to make these routines reentrant, then they will
2469 have to be recompiled with the appropriate compiler option.
2471 Have not had time to do the more involved routines like printf,
2472 will get to them shortly.
2474 Interfacing with Assembly Routines
2476 Global Registers used for Parameter Passing
2478 The compiler always uses the global registers DPL,DPH,B and
2479 ACC to pass the first parameter to a routine. The second
2480 parameter onwards is either allocated on the stack (for
2481 reentrant routines or if --stack-auto is used) or in the
2482 internal / external ram (depending on the memory model).
2484 Assembler Routine(non-reentrant)
2486 In the following example the function cfunc calls an assembler
2487 routine asm_func, which takes two parameters.
2489 extern int asm_func(unsigned char, unsigned char);
2491 int c_func (unsigned char i, unsigned char j)
2493 return asm_func(i,j);
2498 return c_func(10,9);
2501 The corresponding assembler function is:
2503 .globl _asm_func_PARM_2
2511 add a,_asm_func_PARM_2
2517 Note here that the return values are placed in 'dpl' - One
2518 byte return value, 'dpl' LSB & 'dph' MSB for two byte values.
2519 'dpl', 'dph' and 'b' for three byte values (generic pointers)
2520 and 'dpl','dph','b' & 'acc' for four byte values.
2522 The parameter naming convention is _<function_name>_PARM_<n>,
2523 where n is the parameter number starting from 1, and counting
2524 from the left. The first parameter is passed in "dpl"
2525 for One bye parameter, "dptr"
2526 if two bytes, "b,dptr"
2527 for three bytes and "acc,b,dptr"
2528 for four bytes, the varible name for the second parameter
2529 will be _<function_name>_PARM_2.
2531 Assemble the assembler routine with the following command:
2533 asx8051 -losg asmfunc.asm
2535 Then compile and link the assembler routine to the C source
2536 file with the following command:
2538 sdcc cfunc.c asmfunc.rel
2540 Assembler Routine(reentrant)
2542 In this case the second parameter onwards will be passed
2543 on the stack, the parameters are pushed from right to left
2544 i.e. after the call the left most parameter will be on the
2545 top of the stack. Here is an example:
2547 extern int asm_func(unsigned char, unsigned char);
2549 int c_func (unsigned char i, unsigned char j) reentrant
2551 return asm_func(i,j);
2556 return c_func(10,9);
2559 The corresponding assembler routine is:
2580 The compiling and linking procedure remains the same, however
2581 note the extra entry & exit linkage required for the assembler
2582 code, _bp is the stack frame pointer and is used to compute
2583 the offset into the stack for parameters and local variables.
2587 The external stack is located at the start of the external
2588 ram segment, and is 256 bytes in size. When --xstack option
2589 is used to compile the program, the parameters and local
2590 variables of all reentrant functions are allocated in this
2591 area. This option is provided for programs with large stack
2592 space requirements. When used with the --stack-auto option,
2593 all parameters and local variables are allocated on the
2594 external stack (note support libraries will need to be recompiled
2595 with the same options).
2597 The compiler outputs the higher order address byte of the
2598 external ram segment into PORT P2, therefore when using
2599 the External Stack option, this port MAY NOT be used by
2600 the application program.
2604 Deviations from the compliancy.
2606 functions are not always reentrant.
2608 structures cannot be assigned values directly, cannot be
2609 passed as function parameters or assigned to each other
2610 and cannot be a return value from a function, e.g.:
2617 s1 = s2 ; /* is invalid in SDCC although
2621 struct s foo1 (struct s parms) /* is invalid in SDCC although
2626 return rets;/* is invalid in SDCC although
2630 'long long' (64 bit integers) not supported.
2632 'double' precision floating point not supported.
2634 No support for setjmp and longjmp (for now).
2636 Old K&R style function declarations are NOT allowed.
2638 foo(i,j) /* this old style of function declarations */
2640 int i,j; /* are valid in ANSI but not valid in SDCC */
2646 functions declared as pointers must be dereferenced during
2651 /* has to be called like this */
2652 (*foo)(); /* ansi standard allows calls to be made like
2655 Cyclomatic Complexity
2657 Cyclomatic complexity of a function is defined as the number
2658 of independent paths the program can take during execution
2659 of the function. This is an important number since it defines
2660 the number test cases you have to generate to validate the
2661 function. The accepted industry standard for complexity
2662 number is 10, if the cyclomatic complexity reported by SDCC
2663 exceeds 10 you should think about simplification of the
2664 function logic. Note that the complexity level is not related
2665 to the number of lines of code in a function. Large functions
2666 can have low complexity, and small functions can have large
2669 SDCC uses the following formula to compute the complexity:
2672 complexity = (number of edges in control flow graph) - (number
2673 of nodes in control flow graph) + 2;
2675 Having said that the industry standard is 10, you should
2676 be aware that in some cases it be may unavoidable to have
2677 a complexity level of less than 10. For example if you have
2678 switch statement with more than 10 case labels, each case
2679 label adds one to the complexity level. The complexity level
2680 is by no means an absolute measure of the algorithmic complexity
2681 of the function, it does however provide a good starting
2682 point for which functions you might look at for further
2687 Here are a few guidelines that will help the compiler generate
2688 more efficient code, some of the tips are specific to this
2689 compiler others are generally good programming practice.
2691 Use the smallest data type to represent your data-value.
2692 If it is known in advance that the value is going to be
2693 less than 256 then use a 'char' instead of a 'short' or
2696 Use unsigned when it is known in advance that the value
2697 is not going to be negative. This helps especially if
2698 you are doing division or multiplication.
2700 NEVER jump into a LOOP.
2702 Declare the variables to be local whenever possible, especially
2703 loop control variables (induction).
2705 Since the compiler does not do implicit integral promotion,
2706 the programmer should do an explicit cast when integral
2707 promotion is required.
2709 Reducing the size of division, multiplication & modulus
2710 operations can reduce code size substantially. Take the
2711 following code for example.
2713 foobar(unsigned int p1, unsigned char ch)
2715 unsigned char ch1 = p1 % ch ;
2719 For the modulus operation the variable ch will be promoted
2720 to unsigned int first then the modulus operation will
2721 be performed (this will lead to a call to support routine
2722 _muduint()), and the result will be casted to an int.
2723 If the code is changed to
2725 foobar(unsigned int p1, unsigned char ch)
2727 unsigned char ch1 = (unsigned char)p1 % ch ;
2731 It would substantially reduce the code generated (future
2732 versions of the compiler will be smart enough to detect
2733 such optimization oppurtunities).
2735 Notes on MCS51 memory layout
2737 The 8051 family of micro controller have a minimum of 128
2738 bytes of internal memory which is structured as follows
2740 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers
2742 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
2743 - Bytes 30-7F - 60 bytes for general purpose use.
2745 Normally the SDCC compiler will only utilise the first bank
2746 of registers, but it is possible to specify that other banks
2747 of registers should be used in interrupt routines. By default,
2748 the compiler will place the stack after the last bank of
2749 used registers, i.e. if the first 2 banks of registers are
2750 used, it will position the base of the internal stack at
2751 address 16 (0X10). This implies that as the stack grows,
2752 it will use up the remaining register banks, and the 16
2753 bytes used by the 128 bit variables, and 60 bytes for general
2756 By default, the compiler uses the 60 general purpose bytes
2757 to hold "near data". The compiler/optimiser may also declare
2758 some Local Variables in this area to hold local data.
2760 If any of the 128 bit variables are used, or near data is
2761 being used then care needs to be taken to ensure that the
2762 stack does not grow so much that it starts to over write
2763 either your bit variables or "near data". There is no runtime
2764 checking to prevent this from happening.
2766 The amount of stack being used is affected by the use of
2767 the "internal stack" to save registers before a subroutine
2768 call is made (--stack-auto will declare parameters and local
2769 variables on the stack) and the number of nested subroutines.
2771 If you detect that the stack is over writing you data, then
2772 the following can be done. --xstack will cause an external
2773 stack to be used for saving registers and (if --stack-auto
2774 is being used) storing parameters and local variables. However
2775 this will produce more code which will be slower to execute.
2777 --stack-loc will allow you specify the start of the stack,
2778 i.e. you could start it after any data in the general purpose
2779 area. However this may waste the memory not used by the
2780 register banks and if the size of the "near data" increases,
2781 it may creep into the bottom of the stack.
2783 --stack-after-data, similar to the --stack-loc, but it automatically
2784 places the stack after the end of the "near data". Again
2785 this could waste any spare register space.
2787 --data-loc allows you to specify the start address of the
2788 near data. This could be used to move the "near data" further
2789 away from the stack giving it more room to grow. This will
2790 only work if no bit variables are being used and the stack
2791 can grow to use the bit variable space.
2795 If you find that the stack is over writing your bit variables
2796 or "near data" then the approach which best utilised the
2797 internal memory is to position the "near data" after the
2798 last bank of used registers or, if you use bit variables,
2799 after the last bit variable by using the --data-loc, e.g.
2800 if two register banks are being used and no bit variables,
2801 --data-loc 16, and use the --stack-after-data option.
2803 If bit variables are being used, another method would be
2804 to try and squeeze the data area in the unused register
2805 banks if it will fit, and start the stack after the last
2808 Retargetting for other MCUs.
2810 The issues for retargetting the compiler are far too numerous
2811 to be covered by this document. What follows is a brief
2812 description of each of the seven phases of the compiler
2813 and its MCU dependency.
2815 Parsing the source and building the annotated parse tree.
2816 This phase is largely MCU independent (except for the
2817 language extensions). Syntax & semantic checks are also
2818 done in this phase, along with some initial optimizations
2819 like back patching labels and the pattern matching optimizations
2820 like bit-rotation etc.
2822 The second phase involves generating an intermediate code
2823 which can be easy manipulated during the later phases.
2824 This phase is entirely MCU independent. The intermediate
2825 code generation assumes the target machine has unlimited
2826 number of registers, and designates them with the name
2827 iTemp. The compiler can be made to dump a human readable
2828 form of the code generated by using the --dumpraw option.
2830 This phase does the bulk of the standard optimizations
2831 and is also MCU independent. This phase can be broken
2832 down into several sub-phases:
2834 Break down intermediate code (iCode) into basic blocks.
2835 Do control flow & data flow analysis on the basic blocks.
2836 Do local common subexpression elimination, then global
2837 subexpression elimination
2838 Dead code elimination
2840 If loop optimizations caused any changes then do 'global
2841 subexpression elimination' and 'dead code elimination'
2844 This phase determines the live-ranges; by live range I
2845 mean those iTemp variables defined by the compiler that
2846 still survive after all the optimizations. Live range
2847 analysis is essential for register allocation, since these
2848 computation determines which of these iTemps will be assigned
2849 to registers, and for how long.
2851 Phase five is register allocation. There are two parts
2854 The first part I call 'register packing' (for lack of a
2855 better term). In this case several MCU specific expression
2856 folding is done to reduce register pressure.
2858 The second part is more MCU independent and deals with
2859 allocating registers to the remaining live ranges. A lot
2860 of MCU specific code does creep into this phase because
2861 of the limited number of index registers available in
2864 The Code generation phase is (unhappily), entirely MCU
2865 dependent and very little (if any at all) of this code
2866 can be reused for other MCU. However the scheme for allocating
2867 a homogenized assembler operand for each iCode operand
2870 As mentioned in the optimization section the peep-hole
2871 optimizer is rule based system, which can reprogrammed
2874 SDCDB - Source Level Debugger
2876 SDCC is distributed with a source level debugger. The debugger
2877 uses a command line interface, the command repertoire of
2878 the debugger has been kept as close to gdb (the GNU debugger)
2879 as possible. The configuration and build process is part
2880 of the standard compiler installation, which also builds
2881 and installs the debugger in the target directory specified
2882 during configuration. The debugger allows you debug BOTH
2883 at the C source and at the ASM source level.
2885 Compiling for Debugging
2887 The debug option must be specified for all files
2888 for which debug information is to be generated. The complier
2889 generates a .cdb file for each of these files. The linker
2890 updates the .cdb file with the address information. This
2891 .cdb is used by the debugger.
2893 How the Debugger Works
2895 When the --debug option is specified the compiler generates
2896 extra symbol information some of which are put into the
2897 the assembler source and some are put into the .cdb file,
2898 the linker updates the .cdb file with the address information
2899 for the symbols. The debugger reads the symbolic information
2900 generated by the compiler & the address information generated
2901 by the linker. It uses the SIMULATOR (Daniel's S51) to execute
2902 the program, the program execution is controlled by the
2903 debugger. When a command is issued for the debugger, it
2904 translates it into appropriate commands for the simulator.
2906 Starting the Debugger
2908 The debugger can be started using the following command line.
2909 (Assume the file you are debugging has the file name foo).
2913 The debugger will look for the following files.
2915 foo.c - the source file.
2917 foo.cdb - the debugger symbol information file.
2919 foo.ihx - the intel hex format object file.
2921 Command Line Options.
2923 --directory=<source file directory> this option can used
2924 to specify the directory search list. The debugger will
2925 look into the directory list specified for source, cdb
2926 & ihx files. The items in the directory list must be separated
2927 by ':', e.g. if the source files can be in the directories
2928 /home/src1 and /home/src2, the --directory option should
2929 be --directory=/home/src1:/home/src2. Note there can be
2930 no spaces in the option.
2932 -cd <directory> - change to the <directory>.
2934 -fullname - used by GUI front ends.
2936 -cpu <cpu-type> - this argument is passed to the simulator
2937 please see the simulator docs for details.
2939 -X <Clock frequency > this options is passed to the simulator
2940 please see the simulator docs for details.
2942 -s <serial port file> passed to simulator see the simulator
2945 -S <serial in,out> passed to simulator see the simulator
2950 As mention earlier the command interface for the debugger
2951 has been deliberately kept as close the GNU debugger gdb,
2952 as possible. This will help the integration with existing
2953 graphical user interfaces (like ddd, xxgdb or xemacs) existing
2954 for the GNU debugger.
2956 break [line | file:line | function | file:function]
2958 Set breakpoint at specified line or function:
2961 sdcdb>break foo.c:100
2963 sdcdb>break foo.c:funcfoo
2965 clear [line | file:line | function | file:function ]
2967 Clear breakpoint at specified line or function:
2970 sdcdb>clear foo.c:100
2972 sdcdb>clear foo.c:funcfoo
2976 Continue program being debugged, after breakpoint.
2980 Execute till the end of the current function.
2984 Delete breakpoint number 'n'. If used without any option
2985 clear ALL user defined break points.
2987 info [break | stack | frame | registers ]
2989 info break - list all breakpoints
2991 info stack - show the function call stack.
2993 info frame - show information about the current execution
2996 info registers - show content of all registers.
3000 Step program until it reaches a different source line.
3004 Step program, proceeding through subroutine calls.
3008 Start debugged program.
3012 Print type information of the variable.
3016 print value of variable.
3020 load the given file name. Note this is an alternate method
3021 of loading file for debugging.
3025 print information about current frame.
3029 Toggle between C source & assembly source.
3033 Send the string following '!' to the simulator, the simulator
3034 response is displayed. Note the debugger does not interpret
3035 the command being sent to the simulator, so if a command
3036 like 'go' is sent the debugger can loose its execution context
3037 and may display incorrect values.
3041 "Watch me now. Iam going Down. My name is Bobby Brown"
3043 Interfacing with XEmacs.
3045 Two files (in emacs lisp) are provided for the interfacing
3046 with XEmacs, sdcdb.el and sdcdbsrc.el. These two files can
3047 be found in the $(prefix)/bin directory after the installation
3048 is complete. These files need to be loaded into XEmacs for
3049 the interface to work. This can be done at XEmacs startup
3050 time by inserting the following into your '.xemacs' file
3051 (which can be found in your HOME directory):
3053 (load-file sdcdbsrc.el)
3055 .xemacs is a lisp file so the () around the command is REQUIRED.
3056 The files can also be loaded dynamically while XEmacs is
3057 running, set the environment variable 'EMACSLOADPATH' to
3058 the installation bin directory (<installdir>/bin), then
3059 enter the following command ESC-x load-file sdcdbsrc. To
3060 start the interface enter the following command:
3064 You will prompted to enter the file name to be debugged.
3067 The command line options that are passed to the simulator
3068 directly are bound to default values in the file sdcdbsrc.el.
3069 The variables are listed below, these values maybe changed
3072 sdcdbsrc-cpu-type '51
3074 sdcdbsrc-frequency '11059200
3078 The following is a list of key mapping for the debugger interface.
3081 ;; Current Listing ::
3082 ;;key binding Comment
3084 ;;--- ------- -------
3088 sdcdb-next-from-src SDCDB
3091 sdcdb-back-from-src SDCDB
3094 sdcdb-cont-from-src SDCDB
3097 sdcdb-step-from-src SDCDB
3100 sdcdb-whatis-c-sexp SDCDB
3101 ptypecommand for data at
3105 sdcdbsrc-delete SDCDB
3106 Delete all breakpoints if no arg
3108 or delete arg (C-u arg x)
3110 sdcdbsrc-frame SDCDB
3111 Display current frame if no arg,
3113 or display frame arg
3117 sdcdbsrc-goto-sdcdb Goto
3118 the SDCDB output buffer
3120 sdcdb-print-c-sexp SDCDB
3121 print command for data at
3125 sdcdbsrc-goto-sdcdb Goto
3126 the SDCDB output buffer
3128 sdcdbsrc-mode Toggles
3129 Sdcdbsrc mode (turns it off)
3132 sdcdb-finish-from-src SDCDB
3137 break for line with point
3139 sdcdbsrc-mode Toggle
3149 The Z80 and gbz80 port
3151 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's
3152 Z80-like gbz80. The port is incomplete - long support is
3153 incomplete (mul, div and mod are unimplimented), and both
3154 float and bitfield support is missing. Apart from that the
3155 code generated is correct.
3157 As always, the code is the authoritave reference - see z80/ralloc.c
3158 and z80/gen.c. The stack frame is similar to that generated
3159 by the IAR Z80 compiler. IX is used as the base pointer,
3160 HL is used as a temporary register, and BC and DE are available
3161 for holding varibles. IY is currently unusued. Return values
3162 are stored in HL. One bad side effect of using IX as the
3163 base pointer is that a functions stack frame is limited
3164 to 127 bytes - this will be fixed in a later version.
3168 SDCC has grown to be a large project. The compiler alone
3169 (without the preprocessor, assembler and linker) is about
3170 40,000 lines of code (blank stripped). The open source nature
3171 of this project is a key to its continued growth and support.
3172 You gain the benefit and support of many active software
3173 developers and end users. Is SDCC perfect? No, that's why
3174 we need your help. The developers take pride in fixing reported
3175 bugs. You can help by reporting the bugs and helping other
3176 SDCC users. There are lots of ways to contribute, and we
3177 encourage you to take part in making SDCC a great software
3182 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
3183 or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed
3184 ASAP. When reporting a bug, it is very useful to include
3185 a small test program which reproduces the problem. If you
3186 can isolate the problem by looking at the generated assembly
3187 code, this can be very helpful. Compiling your program with
3188 the --dumpall option can sometimes be useful in locating
3189 optimization problems.
3193 Sandeep Dutta (sandeep.dutta@usa.net) - SDCC, the compiler,
3194 MCS51 code generator, Debugger, AVR port
3195 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version
3197 John Hartman (jhartman@compuserve.com) - Porting ASXXX &
3199 Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
3201 Daniel Drotos (drdani@mazsola.iit.uni-miskolc.hu) - for his
3203 Malini Dutta(malini_dutta@hotmail.com) - my wife for her
3204 patience and support.
3205 Unknown - for the GNU C - preprocessor.
3206 Michael Hope - The Z80 and Z80GB port, 186 development
3207 Kevin Vigor - The DS390 port.
3208 Johan Knol - Lots of fixes and enhancements, DS390/TINI libs.
3209 Scott Datallo - The PIC port.
3211 Thanks to all the other volunteer developers who have helped
3212 with coding, testing, web-page creation, distribution sets,
3213 etc. You know who you are :-)
3216 This document was initially written by Sandeep Dutta
3218 All product names mentioned herein may be trademarks of their
3219 respective companies.