3 SDCC Compiler User Guide
10 1.3 System Requirements
13 2.1 Linux/Unix Installation
14 2.2 Windows Installation
15 2.2.1 Windows Install Using a Binary Package
16 2.2.2 Windows Install Using Cygwin
17 2.3 Testing out the SDCC Compiler
18 2.4 Install Trouble-shooting
19 2.4.1 SDCC cannot find libraries or header files.
20 2.4.2 SDCC does not compile correctly.
21 2.4.3 What the ./configure does
22 2.4.4 What the make does.
23 2.4.5 What the make install command does.
24 2.5 Additional Information for Windows Users
25 2.5.1 Getting started with Cygwin
26 2.5.2 Running SDCC as Native Compiled Executables
27 2.6 SDCC on Other Platforms
28 2.7 Advanced Install Options
29 2.8 Components of SDCC
30 2.8.1 cpp ( C-Preprocessor)
31 2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)
32 2.8.3 SDCC - The compiler
34 2.8.5 SDCDB - Source Level Debugger
37 3.1.1 Single Source File Projects
38 3.1.2 Projects with Multiple Source Files
39 3.1.3 Projects with Additional Libraries
40 3.2 Command Line Options
41 3.2.1 Processor Selection Options
42 3.2.2 Preprocessor Options
45 3.2.5 Optimization Options
48 3.2.8 Intermediate Dump Options
49 3.3 MCS51/DS390 Storage Class Language Extensions
56 3.5 Parameters & Local Variables
58 3.7 Interrupt Service Routines
59 3.8 Critical Functions
61 3.10 Functions using private banks
62 3.11 Absolute Addressing
64 3.13 Inline Assembler Code
65 3.14 int(16 bit) and long (32 bit ) Support
66 3.15 Floating Point Support
67 3.16 MCS51 Memory Models
68 3.17 Flat 24 bit Addressing Model
69 3.18 Defines Created by the Compiler
72 4.1.1 Sub-expression Elimination
73 4.1.2 Dead-Code Elimination
74 4.1.3 Copy-Propagation
75 4.1.4 Loop Optimizations
77 4.1.6 Algebraic Simplifications
78 4.1.7 'switch' Statements
79 4.1.8 Bit-shifting Operations.
81 4.1.10 Highest Order Bit
82 4.1.11 Peep-hole Optimizer
85 4.4 Interfacing with Assembly Routines
86 4.5 Global Registers used for Parameter Passing
87 4.5.1 Assembler Routine(non-reentrant)
88 4.5.2 Assembler Routine(reentrant)
91 4.8 Cyclomatic Complexity
93 6 Retargetting for other MCUs.
94 7 SDCDB - Source Level Debugger
95 7.1 Compiling for Debugging
96 7.2 How the Debugger Works
97 7.3 Starting the Debugger
98 7.4 Command Line Options.
99 7.5 Debugger Commands.
100 7.5.1 break [line | file:line | function | file:function]
101 7.5.2 clear [line | file:line | function | file:function ]
105 7.5.6 info [break | stack | frame | registers ]
109 7.5.10 ptype variable
110 7.5.11 print variable
114 7.5.15 ! simulator command
116 7.6 Interfacing with XEmacs.
118 8.1 The Z80 and gbz80 port
129 SDCC is a Free ware, retargettable, optimizing ANSI-C compiler
130 by Sandeep Dutta designed for 8 bit Microprocessors. The
131 current version targets Intel MCS51 based Microprocessors(8051,8052,
132 etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51
133 variant. It can be retargetted for other microprocessors,
134 support for PIC, AVR and 186 is under development. The entire
135 source code for the compiler is distributed under GPL. SDCC
136 uses ASXXXX & ASLINK, a Freeware, retargettable assembler
137 & linker. SDCC has extensive language extensions suitable
138 for utilizing various microcontrollers underlying hardware
139 effectively. In addition to the MCU specific optimizations
140 SDCC also does a host of standard optimizations like global
141 sub expression elimination, loop optimizations (loop invariant,
142 strength reduction of induction variables and loop reversing),
143 constant folding & propagation, copy propagation, dead code
144 elimination and jumptables for 'switch' statements. For
145 the back-end SDCC uses a global register allocation scheme
146 which should be well suited for other 8 bit MCUs. The peep
147 hole optimizer uses a rule based substitution mechanism
148 which is MCU dependent. Supported data-types are char (8
149 bits, 1 byte), short and int (16 bits, 2 bytes ), long (32
150 bit, 4 bytes) and float (4 byte IEEE). The compiler also
151 allows inline assembler code to be embedded anywhere in
152 a function. In addition routines developed in assembly can
153 also be called. SDCC also provides an option to report the
154 relative complexity of a function, these functions can then
155 be further optimized, or hand coded in assembly if needed.
156 SDCC also comes with a companion source level debugger SDCDB,
157 the debugger currently uses ucSim a freeware simulator for
158 8051 and other micro-controllers. The latest version can
159 be downloaded from [http://sdcc.sourceforge.net/].
163 All packages used in this compiler system are opensource(freeware);
164 source code for all the sub-packages (asxxxx assembler/linker,
165 pre-processor) are distributed with the package. This documentation
166 is maintained using a freeware word processor (LyX).
168 This program is free software; you can redistribute it and/or
169 modify it under the terms of the GNU General Public License
170 as published by the Free Software Foundation; either version
171 2, or (at your option) any later version. This program is
172 distributed in the hope that it will be useful, but WITHOUT
173 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
174 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
175 Public License for more details. You should have received
176 a copy of the GNU General Public License along with this
177 program; if not, write to the Free Software Foundation,
178 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
179 In other words, you are welcome to use, share and improve
180 this program. You are forbidden to forbid anyone else to
181 use, share and improve what you give them. Help stamp out
184 1.3 System Requirements
186 What do you need before you start installation of SDCC? A
187 computer, and a desire to compute. The preferred method
188 of installation is to compile SDCC from source using GNU
189 GCC and make. For Windows some pre-compiled binary distributions
190 are available for your convenience. You should have some
191 experience with command line tools and compiler use.
195 The SDCC home page at [http://sdcc.sourceforge.net/]
196 is a great place to find distribution sets. You can also
197 find links to the user mailing lists that offer help or
198 discuss SDCC with other SDCC users. Web links to other SDCC
199 related sites can also be found here. This document can
200 be found in the DOC directory of the source package as a
201 text or HTML file. Some of the other tools (simulator and
202 assembler) included with SDCC contain their own documentation
203 and can be found in the source distribution. If you want
204 the latest unreleased software, the complete source package
205 is available directly by anonymous CVS on www.sourceforge.net.
209 2.1 Linux/Unix Installation
211 1. Download the source package, it will be named something
214 2. Bring up a command line terminal, such as xterm.
216 3. Unpack the file using a command like: tar -xzf sdcc-2.x.x.tgz,
217 this will create a sub-directory called sdcc with all
220 4. Change directory into the main SDCC directory, for example
223 5. Type "./configure". This configures
224 the package for compilation on your system.
226 6. Type "make". All of the source packages
227 will compile, this can take a while.
229 7. Type "make install" as root.
230 This copies the binary executables to the install directories.
232 2.2 Windows Installation
234 For installation under Windows you first need to pick between
235 a pre-compiled binary package, or installing the source
236 package along with the Cygwin package. The binary package
237 is the quickest to install, while the Cygwin package includes
238 all of the open source power tools used to compile the complete
239 SDCC source package in the Windows environment. If you are
240 not familiar with the Unix command line environment, you
241 may want to read the section on additional information for
242 Windows users prior to your initial installation.
244 2.2.1 Windows Install Using a Binary Package
246 1. Download the binary package and unpack it using your favorite
247 unpacking tool(gunzip, WinZip, etc). This should unpack
248 to a group of sub-directories. An example directory structure
249 after unpacking is: c:\usr\local\bin for the executables,
250 c:\usr\local\share\sdcc\include and c:\usr\local\share\sdcc\lib
251 for the include and libraries.
253 2. Adjust your environment PATH to include the location of
254 the bin directory. For example, make a setsdcc.bat file
255 with the following: set PATH=c:\usr\local\bin;%PATH%
257 3. When you compile with sdcc, you may need to specify the
258 location of the lib and include folders. For example,
259 sdcc -I c:\usr\local\share\sdcc\include -L c:\usr\local\share\sdcc\lib\small
262 2.2.2 Windows Install Using Cygwin
264 1. Download and install the cygwin package from the redhat
265 site[http://sources.redhat.com/cygwin/]. Currently,
266 this involved downloading a small install program which
267 then automates downloading and installing selected parts
268 of the package(a large 80M byte sized dowload for the
271 2. Bring up a Unix/Bash command line terminal from the Cygwin
274 3. Follow the instructions in the preceding Linux/Unix installation
277 2.3 Testing out the SDCC Compiler
279 The first thing you should do after installing your SDCC
280 compiler is to see if it runs. Type "sdcc
281 --version" at the prompt, and the program should
282 run and tell you the version. If it doesn't run, or gives
283 a message about not finding sdcc program, then you need
284 to check over your installation. Make sure that the sdcc
285 bin directory is in your executable search path defined
286 by the PATH environment setting (see the Trouble-shooting
287 section for suggestions). Make sure that the sdcc program
288 is in the bin folder, if not perhaps something did not install
291 SDCC binaries are commonly installed in a directory arrangement
295 +--------------------------------+-------------------------------------------+
296 | /usr/local/bin | Holds executables(sdcc, s51, aslink, ...) |
297 +--------------------------------+-------------------------------------------+
298 +--------------------------------+-------------------------------------------+
299 | /usr/local/share/sdcc/lib | Holds common C libraries |
300 +--------------------------------+-------------------------------------------+
301 | /usr/local/share/sdcc/include | Holds common C header files |
302 +--------------------------------+-------------------------------------------+
305 Make sure the compiler works on a very simple example. Type
306 in the following test.c program using your favorite editor:
319 Compile this using the following command: "sdcc
320 -c test.c". If all goes well, the compiler will
321 generate a test.asm and test.rel file. Congratulations,
322 you've just compiled your first program with SDCC. We used
323 the -c option to tell SDCC not to link the generated code,
324 just to keep things simple for this step.
326 The next step is to try it with the linker. Type in "sdcc
327 test.c". If all goes well the compiler will link with
328 the libraries and produce a test.ihx output file. If this
329 step fails (no test.ihx, and the linker generates warnings),
330 then the problem is most likely that sdcc cannot find the
331 /usr/local/share/sdcc/lib directory (see the Install trouble-shooting
332 section for suggestions).
334 The final test is to ensure sdcc can use the standard header
335 files and libraries. Edit test.c and change it to the following:
343 strcpy(str1, "testing");
348 Compile this by typing: "sdcc test.c".
349 This should generate a test.ihx output file, and it should
350 give no warnings such as not finding the string.h file.
351 If it cannot find the string.h file, then the problem is
352 that sdcc cannot find the /usr/local/share/sdcc/include
353 directory (see the Install trouble-shooting section for
356 2.4 Install Trouble-shooting
358 2.4.1 SDCC cannot find libraries or header files.
360 The default installation assumes the libraries and header
361 files are located at "/usr/local/share/sdcc/lib"
362 and "/usr/local/share/sdcc/include".
363 An alternative is to specify these locations as compiler
364 options like this: sdcc -L /usr/local/sdcc/lib/small -I
365 /usr/local/sdcc/include test.c
367 2.4.2 SDCC does not compile correctly.
369 A thing to try is starting from scratch by unpacking the
370 .tgz source package again in an empty directory. Confure
371 it again and build like:
373 "make 2&>1 | tee make.log"
375 After this you can review the make.log file to locate the
376 problem. Or a relevant part of this be attached to an email
377 that could be helpful when requesting help from the mailing
380 2.4.3 What the "./configure"
383 The "./configure" command is a script
384 that analyzes your system and performs some configuration
385 to ensure the source package compiles on your system. It
386 will take a few minutes to run, and will compile a few tests
387 to determine what compiler features are installed.
389 2.4.4 What the "make" does.
391 This runs the GNU make tool, which automatically compiles
392 all the source packages into the final installed binary
395 2.4.5 What the "make install"
398 This will install the compiler, other executables and libraries
399 in to the appropriate system directories. The default is
400 to copy the executables to /usr/local/bin and the libraries
401 and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
403 2.5 Additional Information for Windows Users
405 The standard method of installing on a Unix system involves
406 compiling the source package. This is easily done under
407 Unix, but under Windows it can be a more difficult process.
408 The Cygwin is a large package to download, and the compilation
409 runs considerably slower under Windows due to the overhead
410 of the Cygwin tool set. An alternative is to install a pre-compiled
411 Windows binary package. There are various trade-offs between
412 each of these methods.
414 The Cygwin package allows a Windows user to run a Unix command
415 line interface(bash shell) and also implements a Unix like
416 file system on top of Windows. Included are many of the
417 famous GNU software development tools which can augment
418 the SDCC compiler.This is great if you have some experience
419 with Unix command line tools and file system conventions,
420 if not you may find it easier to start by installing a binary
421 Windows package. The binary packages work with the Windows
422 file system conventions.
424 2.5.1 Getting started with Cygwin
426 SDCC is typically distributed as a tarred/gzipped file(.tgz).
427 This is a packed file similar to a .zip file. Cygwin includes
428 the tools you will need to unpack the SDCC distribution(tar
429 and gzip). To unpack it, simply follow the instructions
430 under the Linux/Unix install section. Before you do this
431 you need to learn how to start a cygwin shell and some of
432 the basic commands used to move files, change directory,
433 run commands and so on. The change directory command is
434 "cd", the move command is "mv".
435 To print the current working directory, type "pwd".
436 To make a directory, use "mkdir".
438 There are some basic differences between Unix and Windows
439 file systems you should understand. When you type in directory
440 paths, Unix and the Cygwin bash prompt uses forward slashes
441 '/' between directories while Windows traditionally uses
442 '\' backward slashes. So when you work at the Cygwin bash
443 prompt, you will need to use the forward '/' slashes. Unix
444 does not have a concept of drive letters, such as "c:",
445 instead all files systems attach and appear as directories.
447 2.5.2 Running SDCC as Native Compiled Executables
449 If you use the pre-compiled binaries, the install directories
450 for the libraries and header files may need to be specified
451 on the sdcc command line like this: sdcc -L c:\usr\local\sdcc\lib\small
452 -I c:\usr\local\sdcc\include test.c if you are running outside
453 of a Unix bash shell.
455 If you have successfully installed and compiled SDCC with
456 the Cygwin package, it is possible to compile into native
457 .exe files by using the additional makefiles included for
458 this purpose. For example, with the Borland 32-bit compiler
459 you would run make -f Makefile.bcc. A command line version
460 of the Borland 32-bit compiler can be downloaded from the
463 2.6 SDCC on Other Platforms
465 * FreeBSD and other non-GNU Unixes - Make sure the GNU make
466 is installed as the default make tool.
468 * SDCC has been ported to run under a variety of operating
469 systems and processors. If you can run GNU GCC/make then
470 chances are good SDCC can be compiled and run on your
473 2.7 Advanced Install Options
475 The "configure" command has several options.
476 The most commonly used option is --prefix=<directory name>,
477 where <directory name> is the final location for the sdcc
478 executables and libraries, (default location is /usr/local).
479 The installation process will create the following directory
480 structure under the <directory name> specified.
482 bin/ - binary exectables (add to PATH environment variable)
485 sdcc/include/ - include
489 - Object & library files for small model library
491 - Object & library files for large model library
493 - Object & library files forDS80C390 library
497 './configure --prefix=/usr/local"
499 will configure the compiler to be installed in directory
502 2.8 Components of SDCC
504 SDCC is not just a compiler, but a collection of tools by
505 various developers. These include linkers, assemblers, simulators
506 and other components. Here is a summary of some of the components.
507 Note that the included simulator and assembler have separate
508 documentation which you can find in the source package in
509 their respective directories. As SDCC grows to include support
510 for other processors, other packages from various developers
511 are included and may have their own sets of documentation.
513 You might want to look at the various executables which are
514 installed in the bin directory. At the time of this writing,
515 we find the following programs:
519 aslink -The linker for 8051 type processors.
521 asx8051 - The assembler for 8051 type processors.
523 sdcpp - The C preprocessor.
525 sdcpd - The source debugger.
527 s51 - The ucSim 8051 simulator.
529 linkz80, linkgbz80 - The Z80 and GameBoy Z80 linkers.
531 as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers.
533 packihx - A tool to pack Intel hex files.
535 As development for other processors proceeds, this list will
536 expand to include executables to support processors like
539 2.8.1 cpp ( C-Preprocessor)
541 The preprocessor is extracted into the directory SDCCDIR/cpp,
542 it is a modified version of the GNU preprocessor. The C
543 preprocessor is used to pull in #include sources, process
544 #ifdef statements, #defines and so on.
546 2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)
548 This is retargettable assembler & linkage editor, it was
549 developed by Alan Baldwin, John Hartman created the version
550 for 8051, and I (Sandeep) have some enhancements and bug
551 fixes for it to work properly with the SDCC. This component
552 is extracted into the directory SDCCDIR/asxxxx.
554 2.8.3 SDCC - The compiler
556 This is the actual compiler, it in turn uses the c-preprocessor
557 and invokes the assembler and linkage editors. All files
558 with the prefix SDCC are part of the compiler and are extracted
559 into the the directory SDCCDIR.
561 2.8.4 S51 - Simulator
563 s51 is a freeware, opensource simulator developed by Daniel
564 Drotos <drdani@mazsola.iit.uni-miskolc.hu>. The executable
565 is built as part of the build process, for more information
566 visit Daniel's website at <http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51/>.
568 2.8.5 SDCDB - Source Level Debugger
570 SDCDB is the companion source level debugger. The current
571 version of the debugger uses Daniel's Simulator S51, but
572 can be easily changed to use other simulators.
578 3.1.1 Single Source File Projects
580 For single source file 8051 projects the process is very
581 simple. Compile your programs with the following command
585 The above command will compile ,assemble and link your source
586 file. Output files are as follows.
588 * sourcefile.asm - Assembler source file created by the compiler
590 * sourcefile.lst - Assembler listing file created by the
593 * sourcefile.rst - Assembler listing file updated with linkedit
594 information , created by linkage editor
596 * sourcefile.sym - symbol listing for the sourcefile, created
599 * sourcefile.rel - Object file created by the assembler,
600 input to Linkage editor.
602 * sourcefile.map - The memory map for the load module, created
605 * sourcefile.ihx - The load module in Intel hex format (you
606 can select the Motorola S19 format with --out-fmt-s19)
608 * sourcefile.cdb - An optional file (with --debug) containing
611 3.1.2 Projects with Multiple Source Files
613 SDCC can compile only ONE file at a time. Let us for example
614 assume that you have a project containing the following
617 foo1.c ( contains some functions )
619 foo2.c (contains some more functions)
621 foomain.c (contains more functions and the function main)
623 The first two files will need to be compiled separately with
630 Then compile the source file containing main and link the
631 other files together with the following command.
633 sdcc foomain.c foo1.rel foo2.rel
635 Alternatively foomain.c can be separately compiled as well
639 sdcc foomain.rel foo1.rel foo2.rel
641 The file containing the main function MUST be the FIRST file
642 specified in the command line , since the linkage editor
643 processes file in the order they are presented to it.
645 3.1.3 Projects with Additional Libraries
647 Some reusable routines may be compiled into a library, see
648 the documentation for the assembler and linkage editor in
649 the directory SDCCDIR/asxxxx/asxhtm.htm this describes how
650 to create a .lib library file, the libraries created in
651 this manner may be included using the command line, make
652 sure you include the -L <library-path> option to tell the
653 linker where to look for these files. Here is an example,
654 assuming you have the source file 'foomain.c' and a library
655 'foolib.lib' in the directory 'mylib' (if that is not the
656 same as your current project).
658 sdcc foomain.c foolib.lib -L mylib
660 Note here that 'mylib' must be an absolute path name.
662 The view of the way the linkage editor processes the library
663 files, it is recommended that you put each source routine
664 in a separate file and combine them using the .lib file.
665 For an example see the standard library file 'libsdcc.lib'
666 in the directory SDCCDIR/sdcc51lib.
668 3.2 Command Line Options
670 3.2.1 Processor Selection Options
672 -mmcs51 Generate code for the MCS51 (8051) family of processors.
673 This is the default processor target.
675 -mds390 Generate code for the DS80C390 processor.
677 -mz80 Generate code for the Z80 family of processors.
679 -mgbz80 Generate code for the GameBoy Z80 processor.
681 -mavr Generate code for the Atmel AVR processor(In development,
684 -mpic14 Generate code for the PIC 14-bit processors(In development,
687 -mtlcs900h Generate code for the Toshiba TLCS-900H processor(In
688 development, not complete).
690 3.2.2 Preprocessor Options
692 -I<path> The additional location where the pre processor
693 will look for <..h> or "..h"
696 -D<macro[=value]> Command line definition of macros. Passed
697 to the pre processor.
699 --compile-only(-c) will compile and assemble the source,
700 but will not call the linkage editor.
704 --lib-path(-L) <absolute path to additional libraries> This
705 option is passed to the linkage editor's additional libraries
706 search path. The path name must be absolute. Additional
707 library files may be specified in the command line. See
708 section Compiling programs for more details.
710 --xram-loc<Value> The start location of the external ram,
711 default value is 0. The value entered can be in Hexadecimal
712 or Decimal format, e.g.: --xram-loc 0x8000 or --xram-loc
715 --code-loc<Value> The start location of the code segment
716 , default value 0. Note when this option is used the interrupt
717 vector table is also relocated to the given address. The
718 value entered can be in Hexadecimal or Decimal format, e.g.:
719 --code-loc 0x8000 or --code-loc 32768.
721 --stack-loc<Value> The initial value of the stack pointer.
722 The default value of the stack pointer is 0x07 if only register
723 bank 0 is used, if other register banks are used then the
724 stack pointer is initialized to the location above the highest
725 register bank used. eg. if register banks 1 & 2 are used
726 the stack pointer will default to location 0x18. The value
727 entered can be in Hexadecimal or Decimal format, eg. --stack-loc
728 0x20 or --stack-loc 32. If all four register banks are used
729 the stack will be placed after the data segment (equivalent
730 to --stack-after-data)
732 --stack-after-data This option will cause the stack to be
733 located in the internal ram after the data segment.
735 --data-loc<Value> The start location of the internal ram
736 data segment, the default value is 0x30.The value entered
737 can be in Hexadecimal or Decimal format, eg. --data-loc
738 0x20 or --data-loc 32.
740 --idata-loc<Value> The start location of the indirectly addressable
741 internal ram, default value is 0x80. The value entered can
742 be in Hexadecimal or Decimal format, eg. --idata-loc 0x88
747 --model-large Generate code for Large model programs see
748 section Memory Models for more details. If this option is
749 used all source files in the project should be compiled
750 with this option. In addition the standard library routines
751 are compiled with small model , they will need to be recompiled.
753 --model-small Generate code for Small Model programs see
754 section Memory Models for more details. This is the default
757 --stack-auto All functions in the source file will be compiled
758 as reentrant, i.e. the parameters and local variables will
759 be allocated on the stack. see section Parameters and Local
760 Variables for more details. If this option is used all source
761 files in the project should be compiled with this option.
763 --xstack Uses a pseudo stack in the first 256 bytes in the
764 external ram for allocating variables and passing parameters.
765 See section on external stack for more details.
767 3.2.5 Optimization Options
769 --nogcse Will not do global subexpression elimination, this
770 option may be used when the compiler creates undesirably
771 large stack/data spaces to store compiler temporaries. A
772 warning message will be generated when this happens and
773 the compiler will indicate the number of extra bytes it
774 allocated. It recommended that this option NOT be used ,
775 #pragma NOGCSE can be used to turn off global subexpression
776 elimination for a given function only.
778 --noinvariant Will not do loop invariant optimizations, this
779 may be turned off for reasons explained for the previous
780 option. For more details of loop optimizations performed
781 see section Loop Invariants.It recommended that this option
782 NOT be used , #pragma NOINVARIANT can be used to turn off
783 invariant optimizations for a given function only.
785 --noinduction Will not do loop induction optimizations, see
786 section Strength reduction for more details.It recommended
787 that this option NOT be used , #pragma NOINDUCTION can be
788 used to turn off induction optimizations for given function
791 --nojtbound Will not generate boundary condition check when
792 switch statements are implemented using jump-tables. See
793 section Switch Statements for more details.It recommended
794 that this option NOT be used , #pragma NOJTBOUND can be
795 used to turn off boundary checking for jump tables for a
798 --noloopreverse Will not do loop reversal optimization
802 --stack-auto See MCS51 section for description.
804 --model-flat24 Generate 24-bit flat mode code. This is the
805 one and only that the ds390 code generator supports right
806 now and is default when using -mds390. See section Memory
807 Models for more details.
809 --stack-10bit This option generates code for the 10 bit stack
810 mode of the Dallas DS80C390 part. This is the one and only
811 that the ds390 code generator supports right now and is
812 default when using -mds390. In this mode, the stack is located
813 in the lower 1K of the internal RAM, which is mapped to
814 0x400000. Note that the support is incomplete, since it
815 still uses a single byte as the stack pointer. This means
816 that only the lower 256 bytes of the potential 1K stack
817 space will actually be used. However, this does allow you
818 to reclaim the precious 256 bytes of low RAM for use for
819 the DATA and IDATA segments. The compiler will not generate
820 any code to put the processor into 10 bit stack mode. It
821 is important to ensure that the processor is in this mode
822 before calling any re-entrant functions compiled with this
823 option. In principle, this should work with the --stack-auto
824 option, but that has not been tested. It is incompatible
825 with the --xstack option. It also only makes sense if the
826 processor is in 24 bit contiguous addressing mode (see the
827 --model-flat24 option).
831 --callee-saves function1[,function2][,function3].... The
832 compiler by default uses a caller saves convention for register
833 saving across function calls, however this can cause unneccessary
834 register pushing & popping when calling small functions
835 from larger functions. This option can be used to switch
836 the register saving convention for the function names specified.
837 The compiler will not save registers when calling these
838 functions, no extra code will be generated at the entry
839 & exit for these functions to save & restore the registers
840 used by these functions, this can SUBSTANTIALLY reduce code
841 & improve run time performance of the generated code. In
842 the future the compiler (with interprocedural analysis)
843 will be able to determine the appropriate scheme to use
844 for each function call. DO NOT use this option for built-in
845 functions such as _muluint..., if this option is used for
846 a library function the appropriate library function needs
847 to be recompiled with the same option. If the project consists
848 of multiple source files then all the source file should
849 be compiled with the same --callee-saves option string.
850 Also see Pragma Directive CALLEE-SAVES.
852 --debug When this option is used the compiler will generate
853 debug information , that can be used with the SDCDB. The
854 debug information is collected in a file with .cdb extension.
855 For more information see documentation for SDCDB.
857 --regextend This option will cause the compiler to define
858 pseudo registers , if this option is used, all source files
859 in the project should be compiled with this option. See
860 section Register Extension for more details.
862 --peep-file<filename> This option can be used to use additional
863 rules to be used by the peep hole optimizer. See section
864 Peep Hole optimizations for details on how to write these
867 -E Run only the C preprocessor. Preprocess all the C source
868 files specified and output the results to standard output.
870 -M Tell the preprocessor to output a rule suitable for make
871 describing the dependencies of each object file. For each
872 source file, the preprocessor outputs one make-rule whose
873 target is the object file name for that source file and
874 whose dependencies are all the files `#include'd in it.
875 This rule may be a single line or may be continued with
876 `\'-newline if it is long. The list of rules is printed on
877 standard output instead of the preprocessed C program. `-M'
880 -C Tell the preprocessor not to discard comments. Used with
883 -MM Like `-M' but the output mentions only the user header
884 files included with `#include "file"'.
885 System header files included with `#include <file>' are
888 -Aquestion(answer) Assert the answer answer for question,
889 in case it is tested with a preprocessor conditional such
890 as `#if #question(answer)'. `-A-' disables the standard
891 assertions that normally describe the target machine.
893 -Aquestion (answer) Assert the answer answer for question,
894 in case it is tested with a preprocessor conditional such
895 as `#if #question(answer)'. `-A-' disables the standard
896 assertions that normally describe the target machine.
898 -Umacro Undefine macro macro. `-U' options are evaluated
899 after all `-D' options, but before any `-include' and `-imacros'
902 -dM Tell the preprocessor to output only a list of the macro
903 definitions that are in effect at the end of preprocessing.
904 Used with the `-E' option.
906 -dD Tell the preprocessor to pass all macro definitions into
907 the output, in their proper sequence in the rest of the
910 -dN Like `-dD' except that the macro arguments and contents
911 are omitted. Only `#define name' is included in the output.
913 -S Stop after the stage of compilation proper; do not assemble.
914 The output is an assembler code file for the input file
917 -Wa_asmOption[,asmOption]... Pass the asmOption to the assembler.
919 -Wl_linkOption[,linkOption]... Pass the linkOption to the
922 --int-long-reent Integer (16 bit) and long (32 bit) libraries
923 have been compiled as reentrant. Note by default these libraries
924 are compiled as non-reentrant. See section Installation
927 --cyclomatic This option will cause the compiler to generate
928 an information message for each function in the source file.
929 The message contains some important information about the
930 function. The number of edges and nodes the compiler detected
931 in the control flow graph of the function, and most importantly
932 the cyclomatic complexity see section on Cyclomatic Complexity
935 --float-reent Floating point library is compiled as reentrant.See
936 section Installation for more details.
938 --out-fmt-ihx The linker output (final object code) is in
939 Intel Hex format. (This is the default option).
941 --out-fmt-s19 The linker output (final object code) is in
944 --nooverlay The compiler will not overlay parameters and
945 local variables of any function, see section Parameters
946 and local variables for more details.
948 --main-return This option can be used when the code generated
949 is called by a monitor program. The compiler will generate
950 a 'ret' upon return from the 'main' function. The default
951 option is to lock up i.e. generate a 'ljmp '.
953 --no-peep Disable peep-hole optimization.
955 --peep-asm Pass the inline assembler code through the peep
956 hole optimizer. This can cause unexpected changes to inline
957 assembler code, please go through the peephole optimizer
958 rules defined in the source file tree '<target>/peeph.def'
959 before using this option.
961 --iram-size<Value> Causes the linker to check if the interal
962 ram usage is within limits of the given value.
964 3.2.8 Intermediate Dump Options
966 The following options are provided for the purpose of retargetting
967 and debugging the compiler. These provided a means to dump
968 the intermediate code (iCode) generated by the compiler
969 in human readable form at various stages of the compilation
972 --dumpraw This option will cause the compiler to dump the
973 intermediate code into a file of named <source filename>.dumpraw
974 just after the intermediate code has been generated for
975 a function, i.e. before any optimizations are done. The
976 basic blocks at this stage ordered in the depth first number,
977 so they may not be in sequence of execution.
979 --dumpgcse Will create a dump of iCode's, after global subexpression
980 elimination, into a file named <source filename>.dumpgcse.
982 --dumpdeadcode Will create a dump of iCode's, after deadcode
983 elimination, into a file named <source filename>.dumpdeadcode.
985 --dumploop Will create a dump of iCode's, after loop optimizations,
986 into a file named <source filename>.dumploop.
988 --dumprange Will create a dump of iCode's, after live range
989 analysis, into a file named <source filename>.dumprange.
991 --dumlrange Will dump the life ranges for all symbols
993 --dumpregassign Will create a dump of iCode's, after register
994 assignment , into a file named <source filename>.dumprassgn.
996 --dumplrange Will create a dump of the live ranges of iTemp's
998 --dumpall Will cause all the above mentioned dumps to be
1001 3.3 MCS51/DS390 Storage Class Language Extensions
1003 In addition to the ANSI storage classes SDCC allows the following
1004 MCS51 specific storage classes.
1008 Variables declared with this storage class will be placed
1009 in the extern RAM. This is the default storage class for
1010 Large Memory model, e.g.:
1012 xdata unsigned char xduc;
1016 This is the default storage class for Small Memory model.
1017 Variables declared with this storage class will be allocated
1018 in the internal RAM, e.g.:
1024 Variables declared with this storage class will be allocated
1025 into the indirectly addressable portion of the internal
1026 ram of a 8051, e.g.:
1032 This is a data-type and a storage class specifier. When a
1033 variable is declared as a bit , it is allocated into the
1034 bit addressable memory of 8051, e.g.:
1040 Like the bit keyword, sfr / sbit signifies both a data-type
1041 and storage class, they are used to describe the special
1042 function registers and special bit variables of a 8051,
1045 sfr at 0x80 P0; /* special function register P0 at location
1047 sbit at 0xd7 CY; /* CY (Carry Flag) */
1051 SDCC allows (via language extensions) pointers to explicitly
1052 point to any of the memory spaces of the 8051. In addition
1053 to the explicit pointers, the compiler also allows a _generic
1054 class of pointers which can be used to point to any of the
1057 Pointer declaration examples.
1059 /* pointer physically in xternal ram pointing to object in
1061 data unsigned char * xdata p;
1063 /* pointer physically in code rom pointing to data in xdata
1065 xdata unsigned char * code p;
1067 /* pointer physically in code space pointing to data in code
1069 code unsigned char * code p;
1071 /* the folowing is a generic pointer physically located in
1075 Well you get the idea. For compatibility with the previous
1076 version of the compiler, the following syntax for pointer
1077 declaration is still supported but will disappear int the
1080 unsigned char _xdata *ucxdp; /* pointer to data in external
1082 unsigned char _data *ucdp ; /* pointer
1083 to data in internal ram */
1084 unsigned char _code *uccp ; /* pointer
1085 to data in R/O code space */
1086 unsigned char _idata *uccp; /*
1087 pointer to upper 128 bytes of ram */
1089 All unqualified pointers are treated as 3-byte (4-byte for
1090 the ds390) '_generic' pointers. These type of pointers can
1091 also to be explicitly declared.
1093 unsigned char _generic *ucgp;
1095 The highest order byte of the generic pointers contains the
1096 data space information. Assembler support routines are called
1097 whenever data is stored or retrieved using _generic pointers.
1098 These are useful for developing reusable library routines.
1099 Explicitly specifying the pointer type will generate the
1100 most efficient code. Pointers declared using a mixture of
1101 OLD/NEW style could have unpredictable results.
1103 3.5 Parameters & Local Variables
1105 Automatic (local) variables and parameters to functions can
1106 either be placed on the stack or in data-space. The default
1107 action of the compiler is to place these variables in the
1108 internal RAM ( for small model) or external RAM (for Large
1109 model). They can be placed on the stack either by using
1110 the --stack-auto compiler option or by using the 'reentrant'
1111 keyword in the function declaration, e.g.:
1113 unsigned char foo( char i) reentrant
1118 Note that when the parameters & local variables are declared
1119 in the internal/external ram the functions are non-reentrant.
1120 Since stack space on 8051 is limited the 'reentrant' keyword
1121 or the --stack-auto option should be used sparingly. Note
1122 the reentrant keyword just means that the parameters & local
1123 variables will be allocated to the stack, it DOES NOT mean
1124 that the function is register bank independent.
1126 When compiled with the default option (i.e. non-reentrant
1127 ), local variables can be assigned storage classes and absolute
1128 addresses, e.g.: (jwk: pending: this is obsolete and need
1131 unsigned char foo() {
1133 xdata unsigned char i;
1137 data at 0x31 unsiged char j;
1142 In the above example the variable i will be allocated in
1143 the external ram, bvar in bit addressable space and j in
1144 internal ram. When compiled with the --stack-auto or when
1145 a function is declared as 'reentrant' local variables cannot
1146 be assigned storage classes or absolute addresses.
1148 Parameters however are not allowed any storage class, (storage
1149 classes for parameters will be ignored), their allocation
1150 is governed by the memory model in use , and the reentrancy
1155 For non-reentrant functions SDCC will try to reduce internal
1156 ram space usage by overlaying parameters and local variables
1157 of a function (if possible). Parameters and local variables
1158 of a function will be allocated to an overlayable segment
1159 if the function has no other function calls and the function
1160 is non-reentrant and the memory model is small. If an explicit
1161 storage class is specified for a local variable , it will
1164 Note that the compiler (not the linkage editor) makes the
1165 decision for overlaying the data items. Functions that are
1166 called from an interrupt service routine should be preceded
1167 by a #pragma NOOVERLAY if they are not reentrant Along the
1168 same lines the compiler does not do any processing with
1169 the inline assembler code so the compiler might incorrectly
1170 assign local variables and parameters of a function into
1171 the overlay segment if the only function call from a function
1172 is from inline assembler code, it is safe to use the #pragma
1173 NOOVERLAY for functions which call other functions using
1174 inline assembler code.
1176 Parameters and Local variables of functions that contain
1177 16 or 32 bit multiplication or division will NOT be overlayed
1178 since these are implemented using external functions, e.g.:
1182 void set_error( unsigned char errcd)
1188 void some_isr () interrupt 2 using 1
1198 In the above example the parameter errcd for the function
1199 set_error would be assigned to the overlayable segment (if
1200 the #pragma NOOVERLAY was not present) , this could cause
1201 unpredictable runtime behavior when called from an ISR.
1202 The pragma NOOVERLAY ensures that the parameters and local
1203 variables for the function are NOT overlayed.
1205 3.7 Interrupt Service Routines
1207 SDCC allows interrupt service routines to be coded in C,
1208 with some extended keywords.
1210 void timer_isr (void) interrupt 2 using 1
1215 The number following the 'interrupt' keyword is the interrupt
1216 number this routine will service. The compiler will insert
1217 a call to this routine in the interrupt vector table for
1218 the interrupt number specified. The 'using' keyword is used
1219 to tell the compiler to use the specified register bank
1220 (8051 specific) when generating code for this function.
1221 Note that when some function is called from an interrupt
1222 service routine it should be preceded by a #pragma NOOVERLAY
1223 (if it is not reentrant). A special note here, int (16 bit)
1224 and long (32 bit) integer division, multiplication & modulus
1225 operations are implemented using external support routines
1226 developed in ANSI-C, if an interrupt service routine needs
1227 to do any of these operations then the support routines
1228 (as mentioned in a following section) will have to recompiled
1229 using the --stack-auto option and the source file will need
1230 to be compiled using the --int-long-rent compiler option.
1232 If you have multiple source files in your project, interrupt
1233 service routines can be present in any of them, but a prototype
1234 of the isr MUST be present in the file that contains the
1237 Interrupt Numbers and the corresponding address & descriptions
1238 for the Standard 8051 are listed below. SDCC will automatically
1239 adjust the interrupt vector table to the maximum interrupt
1243 +--------------+--------------+----------------+
1244 | Interrupt # | Description | Vector Address |
1245 +--------------+--------------+----------------+
1246 +--------------+--------------+----------------+
1247 | 0 | External 0 | 0x0003 |
1248 +--------------+--------------+----------------+
1249 | 1 | Timer 0 | 0x000B |
1250 +--------------+--------------+----------------+
1251 | 2 | External 1 | 0x0013 |
1252 +--------------+--------------+----------------+
1253 | 3 | Timer 1 | 0x001B |
1254 +--------------+--------------+----------------+
1255 | 4 | Serial | 0x0023 |
1256 +--------------+--------------+----------------+
1260 If the interrupt service routine is defined without 'using'
1261 a register bank or with register bank 0 (using 0), the compiler
1262 will save the registers used by itself on the stack (upon
1263 entry and restore them at exit), however if such an interrupt
1264 service routine calls another function then the entire register
1265 bank will be saved on the stack. This scheme may be advantageous
1266 for small interrupt service routines which have low register
1269 If the interrupt service routine is defined to be using a
1270 specific register bank then only "a","b"
1271 & "dptr" are save and restored, if such an interrupt
1272 service routine calls another function (using another register
1273 bank) then the entire register bank of the called function
1274 will be saved on the stack. This scheme is recommended for
1275 larger interrupt service routines.
1277 Calling other functions from an interrupt service routine
1278 is not recommended avoid it if possible.
1280 3.8 Critical Functions
1282 A special keyword may be associated with a function declaring
1283 it as 'critical'. SDCC will generate code to disable all
1284 interrupts upon entry to a critical function and enable
1285 them back before returning. Note that nesting critical functions
1286 may cause unpredictable results.
1296 The critical attribute maybe used with other attributes like
1301 A special keyword may be associated with a function declaring
1302 it as '_naked'. The '_naked' function modifier attribute
1303 prevents the compiler from generating prologue and epilogue
1304 code for that function. This means that the user is entirely
1305 responsible for such things as saving any registers that
1306 may need to be preserved, selecting the proper register
1307 bank, generating the 'return' instruction at the end, etc.
1308 Practically, this means that the contents of the function
1309 must be written in inline assembler. This is particularly
1310 useful for interrupt functions, which can have a large (and
1311 often unnecessary) prologue/epilogue. For example, compare
1312 the code generated by these two functions:
1314 data unsigned char counter;
1315 void simpleIterrupt(void) interrupt 1
1321 void nakedInterrupt(void) interrupt 2 _naked
1329 ; MUST explicitly include ret in _naked function.
1334 For an 8051 target, the generated simpleInterrupt looks like:
1364 whereas nakedInterrupt looks like:
1371 ; MUST explicitly include ret(i) in _naked function.
1373 While there is nothing preventing you from writing C code
1374 inside a _naked function, there are many ways to shoot yourself
1375 in the foot doing this, and is is recommended that you stick
1376 to inline assembler.
1378 3.10 Functions using private banks
1380 The 'using' attribute (which tells the compiler to use a
1381 register bank other than the default bank zero) should only
1382 be applied to 'interrupt' functions (see note A below).
1383 This will in most circumstances make the generated ISR code
1384 more efficient since it will not have to save registers
1387 The 'using' attribute will have no effect on the generated
1388 code for a non-'interrupt' function (but may occasionally
1389 be useful anyway([footnote] possible exception: if a function is called ONLY
1390 from 'interrupt' functions using a particular bank, it can
1391 be declared with the same 'using' attribute as the calling
1392 'interrupt' functions. For instance, if you have several
1393 ISRs using bank one, and all of them call memcpy(), it might
1394 make sense to create a specialized version of memcpy() 'using
1395 1', since this would prevent the ISR from having to save
1396 bank zero to the stack on entry and switch to bank zero
1397 before calling the function) ).
1398 (jwk: todo: I don't think this has been done yet)
1400 An 'interrupt' function using a non-zero bank will assume
1401 that it can trash that register bank, and will not save
1402 it. Since high-priority interrupts can interrupt low-priority
1403 ones on the 8051 and friends, this means that if a high-priority
1404 ISR 'using' a particular bank occurs while processing a
1405 low-priority ISR 'using' the same bank, terrible and bad
1406 things can happen. To prevent this, no single register bank
1407 should be 'used' by both a high priority and a low priority
1408 ISR. This is probably most easily done by having all high
1409 priority ISRs use one bank and all low priority ISRs use
1410 another. If you have an ISR which can change priority at
1411 runtime, you're on your own: I suggest using the default
1412 bank zero and taking the small performance hit.
1414 It is most efficient if your ISR calls no other functions.
1415 If your ISR must call other functions, it is most efficient
1416 if those functions use the same bank as the ISR (see note
1417 A below); the next best is if the called functions use bank
1418 zero. It is very inefficient to call a function using a
1419 different, non-zero bank from an ISR.
1421 3.11 Absolute Addressing
1423 Data items can be assigned an absolute address with the at
1424 <address> keyword, in addition to a storage class.
1428 xdata at 0x8000 unsigned char PORTA_8255 ;
1430 In the above example the PORTA_8255 will be allocated to
1431 the location 0x8000 of the external ram.
1433 Note that is this feature is provided to give the programmer
1434 access to memory mapped devices attached to the controller.
1435 The compiler does not actually reserve any space for variables
1436 declared in this way (they are implemented with an equate
1437 in the assembler), thus it is left to the programmer to
1438 make sure there are no overlaps with other variables that
1439 are declared without the absolute address, the assembler
1440 listing file (.lst) and the linker output files (<filename>.rst)
1441 and (<filename>.map) are a good places to look for such
1444 Absolute address can be specified for variables in all storage
1451 The above example will allocate the variable at offset 0x02
1452 in the bit-addressable space. There is no real advantage
1453 to assigning absolute addresses to variables in this manner
1454 , unless you want strict control over all the variables
1459 The compiler inserts a jump to the C routine _sdcc__external__startup()
1460 at the start of the CODE area. This routine can be found
1461 in the file SDCCDIR/sdcc51lib/_startup.c, by default this
1462 routine returns 0, if this routine returns a non-zero value
1463 , the static & global variable initialization will be skipped
1464 and the function main will be invoked, other wise static
1465 & global variables will be initialized before the function
1466 main is invoked. You could add a _sdcc__external__startup()
1467 routine to your program to override the default if you needed
1468 to setup hardware or perform some other critical operation
1469 prior to static & global variable initialization.
1471 3.13 Inline Assembler Code
1473 SDCC allows the use of in-line assembler with a few restriction
1474 as regards labels. All labels defined within inline assembler
1475 code HAS TO BE of the form nnnnn$ where nnnn is a number
1476 less than 100 (which implies a limit of utmost 100 inline
1477 assembler labels per function). It is strongly recommended
1478 that each assembly instruction (including labels) be placed
1479 in a separate line ( as the example shows). When the --peep-asm
1480 command line option is used, the inline assembler code will
1481 be passed through the peephole optimizer, this might cause
1482 some unexpected changes in the inline assembler code, please
1483 go throught the peephole optimizer rules defined in file
1484 'SDCCpeeph.def' carefully before using this option.
1494 The inline assembler code can contain any valid code understood
1495 by the assembler (this includes any assembler directives
1496 and comment lines). The compiler does not do any validation
1497 of the code within the _asm ... _endasm; keyword pair.
1499 Inline assembler code cannot reference any C-Labels however
1500 it can reference labels defined by the inline assembler.
1505 ... /* some c code */
1507 ; some assembler code
1510 ... /* some more c code */
1511 clabel: /* inline assembler cannot reference this
1514 $0003: ;label (can be reference by inline assembler
1520 In other words inline assembly code can access labels defined
1521 in inline assembly. The same goes the other way, ie. labels
1522 defines in inline assembly CANNOT be accessed by C statements.
1524 3.14 int(16 bit) and long (32 bit ) Support
1526 For signed & unsigned int (16 bit) and long (32 bit) variables,
1527 division, multiplication and modulus operations are implemented
1528 by support routines. These support routines are all developed
1529 in ANSI-C to facilitate porting to other MCUs. The following
1530 files contain the described routine, all of them can be
1531 found in the directory SDCCDIR/sdcc51lib
1533 * _mulsint.c - signed 16 bit multiplication (calls _muluint)
1535 * _muluint.c - unsigned 16 bit multiplication
1537 * _divsint.c - signed 16 bit division (calls _divuint)
1539 * _divuint.c - unsigned 16 bit division.
1541 * _modsint.c - signed 16 bit modulus (call _moduint)
1543 * _moduint.c - unsigned 16 bit modulus.
1545 * _mulslong.c - signed 32 bit multiplication (calls _mululong)
1547 * _mululong.c - unsigned32 bit multiplication.
1549 * _divslong.c - signed 32 division (calls _divulong)
1551 * _divulong.c - unsigned 32 division.
1553 * _modslong.c - signed 32 bit modulus (calls _modulong).
1555 * _modulong.c - unsigned 32 bit modulus.
1557 All these routines are compiled as non-reentrant and small
1558 model. Since they are compiled as non-reentrant, interrupt
1559 service routines should not do any of the above operations,
1560 if this unavoidable then the above routines will need to
1561 ne compiled with the --stack-auto option, after which the
1562 source program will have to be compiled with --int-long-rent
1565 3.15 Floating Point Support
1567 SDCC supports IEEE (single precision 4bytes) floating point
1568 numbers.The floating point support routines are derived
1569 from gcc's floatlib.c and consists of the following routines.
1571 * _fsadd.c - add floating point numbers.
1573 * _fssub.c - subtract floating point numbers
1575 * _fsdiv.c - divide floating point numbers
1577 * _fsmul.c - multiply floating point numbers
1579 * _fs2uchar.c - convert floating point to unsigned char
1581 * _fs2char.c - convert floating point to signed char.
1583 * _fs2uint.c - convert floating point to unsigned int.
1585 * _fs2int.c - convert floating point to signed int.
1587 * _fs2ulong.c - convert floating point to unsigned long.
1589 * _fs2long.c - convert floating point to signed long.
1591 * _uchar2fs.c - convert unsigned char to floating point
1593 * _char2fs.c - convert char to floating point number
1595 * _uint2fs.c - convert unsigned int to floating point
1597 * _int2fs.c - convert int to floating point numbers
1599 * _ulong2fs.c - convert unsigned long to floating point number
1601 * _long2fs.c - convert long to floating point number.
1603 Note if all these routines are used simultaneously the data
1604 space might overflow. For serious floating point usage it
1605 is strongly recommended that the Large model be used (in
1606 which case the floating point routines mentioned above will
1607 need to recompiled with the --model-Large option)
1609 3.16 MCS51 Memory Models
1611 SDCC allows two memory models for MCS51 code, small and large.
1612 Modules compiled with different memory models should never
1613 be combined together or the results would be unpredictable.
1614 The library routines supplied with the compiler are compiled
1615 as both small and large. The compiled library modules are
1616 contained in seperate directories as small and large so
1617 that you can link to either set. In general the use of the
1618 large model is discouraged.
1620 When the large model is used all variables declared without
1621 a storage class will be allocated into the external ram,
1622 this includes all parameters and local variables (for non-reentrant
1623 functions). When the small model is used variables without
1624 storage class are allocated in the internal ram.
1626 Judicious usage of the processor specific storage classes
1627 and the 'reentrant' function type will yield much more efficient
1628 code, than using the large-model. Several optimizations
1629 are disabled when the program is compiled using the large
1630 model, it is therefore strongly recommdended that the small
1631 model be used unless absolutely required.
1633 3.17 Flat 24 bit Addressing Model
1635 This option generates code for the 24 bit contiguous addressing
1636 mode of the Dallas DS80C390 part. In this mode, up to four
1637 meg of external RAM or code space can be directly addressed.
1638 See the data sheets at www.dalsemi.com for further information
1641 In older versions of the compiler, this option was used with
1642 the MCS51 code generator (-mmcs51). Now, however, the '390
1643 has it's own code generator, selected by the -mds390 switch.
1644 This code generator currently supports only the flat24 model,
1645 but the --model-flat24 switch is still required, in case
1646 later versions of the code generator support other models
1647 (such as the paged mode of the '390). The combination of
1648 -mmcs51 and --model-flat24 is now depracated.
1650 Note that the compiler does not generate any code to place
1651 the processor into24 bitmode (it defaults to 8051 compatible
1652 mode). Boot loader or similar code must ensure that the
1653 processor is in 24 bit contiguous addressing mode before
1654 calling the SDCC startup code.
1656 Like the --model-large option, variables will by default
1657 be placed into the XDATA segment.
1659 Segments may be placed anywhere in the 4 meg address space
1660 using the usual --*-loc options. Note that if any segments
1661 are located above 64K, the -r flag must be passed to the
1662 linker to generate the proper segment relocations, and the
1663 Intel HEX output format must be used. The -r flag can be
1664 passed to the linker by using the option -Wl-r on the sdcc
1667 3.18 Defines Created by the Compiler
1669 The compiler creates the following #defines.
1671 * SDCC - this Symbol is always defined.
1673 * SDCC_STACK_AUTO - this symbol is defined when --stack-auto
1676 * SDCC_MODEL_SMALL - when small model is used.
1678 * SDCC_MODEL_LARGE - when --model-large is used.
1680 * SDCC_USE_XSTACK - when --xstack option is used.
1682 4 SDCC Technical Data
1686 SDCC performs a a host of standard optimizations in addition
1687 to some MCU specific optimizations.
1689 4.1.1 Sub-expression Elimination
1691 The compiler does local and global common subexpression elimination.
1698 will be translated to
1704 Some subexpressions are not as obvious as the above example.
1711 In this case the address arithmetic a->b[i] will be computed
1712 only once; the equivalent code in C would be.
1718 The compiler will try to keep these temporary variables in
1721 4.1.2 Dead-Code Elimination
1728 i = 1; /* dead store
1730 global = 1; /* dead store */
1733 global = 3; /* unreachable */
1738 int global; void f ()
1744 4.1.3 Copy-Propagation
1764 Note: the dead stores created by this copy propagation will
1765 be eliminated by dead-code elimination.
1767 4.1.4 Loop Optimizations
1769 Two types of loop optimizations are done by SDCC loop invariant
1770 lifting and strength reduction of loop induction variables.In
1771 addition to the strength reduction the optimizer marks the
1772 induction variables and the register allocator tries to
1773 keep the induction variables in registers for the duration
1774 of the loop. Because of this preference of the register
1775 allocator , loop induction optimization causes an increase
1776 in register pressure, which may cause unwanted spilling
1777 of other temporary variables into the stack / data space.
1778 The compiler will generate a warning message when it is
1779 forced to allocate extra space either on the stack or data
1780 space. If this extra space allocation is undesirable then
1781 induction optimization can be eliminated either for the
1782 entire source file ( with --noinduction option) or for a
1783 given function only (#pragma NOINDUCTION).
1789 for (i = 0 ; i < 100 ; i ++)
1795 for ( i = 0; i < 100; i++ ) f += itemp;
1797 As mentioned previously some loop invariants are not as apparent,
1798 all static address computations are also moved out of the
1801 * Strength Reduction :
1803 This optimization substitutes an expression by a cheaper
1808 for (i=0;i < 100; i++) ar[i*5] = i*3;
1814 for (i=0;i< 100;i++) {
1815 ar[itemp1] = itemp2;
1820 The more expensive multiplication is changed to a less expensive
1823 4.1.5 Loop Reversing:
1825 This optimization is done to reduce the overhead of checking
1826 loop boundaries for every iteration. Some simple loops can
1827 be reversed and implemented using a "decrement
1828 and jump if not zero" instruction. SDCC
1829 checks for the following criterion to determine if a loop
1830 is reversible (note: more sophisticated compiers use data-dependency
1831 analysis to make this determination, SDCC uses a more simple
1834 * The 'for' loop is of the form
1835 "for ( <symbol> = <expression> ; <sym> [< | <=] <expression>
1836 ; [<sym>++ | <sym> += 1])
1839 * The <for body> does not contain "continue"
1842 * All goto's are contained within the loop.
1844 * No function calls within the loop.
1846 * The loop control variable <sym> is not assigned any value
1849 * The loop control variable does NOT participate in any arithmetic
1850 operation within the loop.
1852 * There are NO switch statements in the loop.
1854 Note djnz instruction can be used for 8-bit values ONLY,
1855 therefore it is advantageous to declare loop control symbols
1856 as either 'char', ofcourse this may not be possible on all
1859 4.1.6 Algebraic Simplifications
1861 SDCC does numerous algebraic simplifications, the following
1862 is a small sub-set of these optimizations.
1865 i = j + 0 ; /* changed to */ i = j;
1866 i /= 2; /* changed to */ i >>= 1;
1867 i = j - j ; /* changed to */ i = 0;
1868 i = j / 1 ; /* changed to */ i = j;
1870 Note the subexpressions given above are generally introduced
1871 by macro expansions or as a result of copy/constant propagation.
1873 4.1.7 'switch' Statements
1875 SDCC changes switch statements to jump tables when the following
1876 conditions are true.
1878 * The case labels are in numerical sequence , the labels
1879 need not be in order, and the starting number need not
1903 Both the above switch statements will be implemented using
1906 * The number of case labels is at least three, since it takes
1907 two conditional statements to handle the boundary conditions.
1909 * The number of case labels is less than 84, since each label
1910 takes 3 bytes and a jump-table can be utmost 256 bytes
1913 Switch statements which have gaps in the numeric sequence
1914 or those that have more that 84 case labels can be split
1915 into more than one switch statement for efficient code generation.
1930 If the above switch statement is broken down into two switch
1947 then both the switch statements will be implemented using
1948 jump-tables whereas the unmodified switch statement will
1951 4.1.8 Bit-shifting Operations.
1953 Bit shifting is one of the most frequently used operation
1954 in embedded programming. SDCC tries to implement bit-shift
1955 operations in the most efficient way possible.
1965 generates the following code.
1972 In general SDCC will never setup a loop if the shift count
1973 is known. Another example
1988 Note that SDCC stores numbers in little-endian format (i.e.
1993 A special case of the bit-shift operation is bit rotation,
1994 SDCC recognizes the following expression to be a left bit-rotation.
1998 i = ( ( i << 1) | ( i >> 7));
2001 will generate the following code.
2007 SDCC uses pattern matching on the parse tree to determine
2008 this operation.Variations of this case will also be recognized
2009 as bit-rotation i.e i = ((i >> 7) | (i << 1)); /* left-bit
2012 4.1.10 Highest Order Bit
2014 It is frequently required to obtain the highest order bit
2015 of an integral type (long, int, short or char types). SDCC
2016 recognizes the following expression to yield the highest
2017 order bit and generates optimized code for it.
2024 hob = (gint >> 15) & 1;
2028 Will generate the following code.
2048 Variations of this case however will NOT be recognized. It
2049 is a standard C expression , so I heartily recommend this
2050 be the only way to get the highest order bit, (it is portable).
2051 Of course it will be recognized even if it is embedded in
2056 xyz = gint + ((gint >> 15) & 1);
2058 will still be recognized.
2060 4.1.11 Peep-hole Optimizer
2062 The compiler uses a rule based , pattern matching and re-writing
2063 mechanism for peep-hole optimization. It is inspired by
2064 'copt' a peep-hole optimizer by Christopher W. Fraser (cwfraser@microsoft.com).
2065 A default set of rules are compiled into the compiler, additional
2066 rules may be added with the --peep-file <filename> option.
2067 The rule language is best illustrated with examples.
2071 mov a,%1 } by { mov %1,a }
2073 The above rule will the following assembly sequence
2082 Note: All occurrences of a '%n' ( pattern variable ) must
2083 denote the same string. With the above rule, the assembly
2089 will remain unmodified. Other special case optimizations
2090 may be added by the user (via --peep-file option), eg. some
2091 variants of the 8051 MCU allow only 'AJMP' and 'ACALL' ,
2092 the following two rules will change all 'LJMP' & 'LCALL'
2093 to 'AJMP' & 'ACALL'.
2095 replace { lcall %1 } by { acall %1 }
2096 replace { ljmp %1 } by { ajmp %1 }
2098 The inline-assembler' code is also passed through the peep
2099 hole optimizer, thus the peephole optimizer can also be
2100 used as an assembly level macro expander. The rules themselves
2101 are MCU dependent whereas the rule language infra-structure
2102 is MCU independent. Peephole optimization rules for other
2103 MCU can be easily programmed using the rule language.
2105 The syntax for a rule is as follows ,
2107 rule := replace [ restart ] '{' <assembly sequence> '\n'
2113 <assembly sequence> '\n'
2115 '}' [if <functionName>
2117 <assembly sequence> := assembly instruction (each instruction
2118 including labels must be on a separate line).
2120 The optimizer will apply to the rules one by one from the
2121 top in the sequence of their appearance, it will terminate
2122 when all rules are exhausted. If the 'restart' option is
2123 specified, then the optimizer will start matching the rules
2124 again from the top, this option for a rule is expensive
2125 (performance), it is intended to be used in situations where
2126 a transformation will trigger the same rule again. A good
2127 example of this the following rule.
2135 Note that the replace pattern cannot be a blank, but can
2136 be a comment line. Without the 'restart' option only the
2137 inner most 'pop' 'push' pair would be eliminated. i.e.
2150 with the 'restart' option the rule will be applied again
2151 to the resulting code and the all the 'pop' 'push' pairs
2152 will be eliminated to yield
2157 A conditional function can be attached to a rule. Attaching
2158 rules are somewhat more involved, let me illustrate this
2165 %2:} if labelInRange
2167 The optimizer does a look-up of a function name table defined
2168 in function 'callFuncByName' in the source file SDCCpeeph.c
2169 , with the name 'labelInRange', if it finds a corresponding
2170 entry the function is called. Note there can be no parameters
2171 specified for these functions, in this case the use of '%5'
2172 is crucial, since the function labelInRange expects to find
2173 the label in that particular variable (the hash table containing
2174 the variable bindings is passed as a parameter). If you
2175 want to code more such functions , take a close look at
2176 the function labelInRange and the calling mechanism in source
2177 file SDCCpeeph.c. I know this whole thing is a little kludgey
2178 , may be some day we will have some better means. If you
2179 are looking at this file, you will also see the default
2180 rules that are compiled into the compiler, you can your
2181 own rules in the default set there if you get tired of specifying
2182 the --peep-file option.
2186 SDCC supports the following #pragma directives. This directives
2187 are applicable only at a function level.
2189 * SAVE - this will save all the current options.
2191 * RESTORE - will restore the saved options from the last
2192 save. Note that SAVES & RESTOREs cannot be nested. SDCC
2193 uses the same buffer to save the options each time a SAVE
2196 * NOGCSE - will stop global subexpression elimination.
2198 * NOINDUCTION - will stop loop induction optimizations.
2200 * NOJTBOUND - will not generate code for boundary value checking
2201 , when switch statements are turned into jump-tables.
2203 * NOOVERLAY - the compiler will not overlay the parameters
2204 and local variables of a function.
2206 * NOLOOPREVERSE - Will not do loop reversal optimization
2208 * EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma
2209 disables generation of pair of push/pop instruction in
2210 ISR function (using interrupt keyword). The directive
2211 should be placed immediately before the ISR function definition
2212 and it affects ALL ISR functions following it. To enable
2213 the normal register saving for ISR functions use "#pragma
2216 * CALLEE-SAVES function1[,function2[,function3...]] - The
2217 compiler by default uses a caller saves convention for
2218 register saving across function calls, however this can
2219 cause unneccessary register pushing & popping when calling
2220 small functions from larger functions. This option can
2221 be used to switch the register saving convention for the
2222 function names specified. The compiler will not save registers
2223 when calling these functions, extra code will be generated
2224 at the entry & exit for these functions to save & restore
2225 the registers used by these functions, this can SUBSTANTIALLY
2226 reduce code & improve run time performance of the generated
2227 code. In future the compiler (with interprocedural analysis)
2228 will be able to determine the appropriate scheme to use
2229 for each function call. If --callee-saves command line
2230 option is used, the function names specified in #pragma
2231 CALLEE-SAVES is appended to the list of functions specified
2234 The pragma's are intended to be used to turn-off certain
2235 optimizations which might cause the compiler to generate
2236 extra stack / data space to store compiler generated temporary
2237 variables. This usually happens in large functions. Pragma
2238 directives should be used as shown in the following example,
2239 they are used to control options & optimizations for a given
2240 function; pragmas should be placed before and/or after a
2241 function, placing pragma's inside a function body could
2242 have unpredictable results.
2246 #pragma SAVE /* save the current settings
2248 #pragma NOGCSE /* turnoff global subexpression elimination
2250 #pragma NOINDUCTION /* turn off induction optimizations */
2258 #pragma RESTORE /* turn the optimizations back on */
2260 The compiler will generate a warning message when extra space
2261 is allocated. It is strongly recommended that the SAVE and
2262 RESTORE pragma's be used when changing options for a function.
2264 4.3 Library Routines
2266 The following library routines are provided for your convenience.
2268 stdio.h - Contains the following functions printf & sprintf
2269 these routines are developed by Martijn van Balen <balen@natlab.research.philips.com>.
2271 %[flags][width][b|B|l|L]type
2274 - left justify output
2275 in specified field width
2277 + prefix output with
2278 +/- sign if output is signed type
2280 space prefix output with a blank if
2281 it's a signed positive value
2283 specifies minimum number of characters outputted for numbers
2288 - For numbers, spaces are added on the left when needed.
2291 If width starts with a zero character, zeroes and used
2295 - For strings, spaces are are added on the left or right
2298 flag '-' is used) when needed.
2302 byte argument (used by d, u, o, x, X)
2304 long argument (used by d, u, o, x, X)
2308 u unsigned decimal number
2311 o unsigned octal number
2314 x unsigned hexadecimal
2317 X unsigned hexadecimal
2322 s string (generic pointer)
2325 p generic pointer (I:data/idata,
2326 C:code, X:xdata, P:paged)
2328 f float (still to be
2331 Also contains a very simple version of printf (printf_small).
2332 This simplified version of printf supports only the following
2335 format output type argument-type
2343 %x hexadecimal short/int
2345 %lx hexadecimal long
2347 %hx hexadecimal char
2357 %s character _generic
2360 The routine is very stack intesive , --stack-after-data parameter
2361 should be used when using this routine, the routine also
2362 takes about 1K of code space. It also expects an external
2363 function named putchar(char ) to be present (this can be
2364 changed). When using the %s format the string / pointer
2365 should be cast to a generic pointer. eg.
2367 printf_small("my str %s, my int %d\n",(char
2368 _generic *)mystr,myint);
2370 * stdarg.h - contains definition for the following macros
2371 to be used for variable parameter list, note that a function
2372 can have a variable parameter list if and only if it is
2375 va_list, va_start, va_arg, va_end.
2377 * setjmp.h - contains defintion for ANSI setjmp & longjmp
2378 routines. Note in this case setjmp & longjmp can be used
2379 between functions executing within the same register bank,
2380 if long jmp is executed from a function that is using
2381 a different register bank from the function issuing the
2382 setjmp function, the results may be unpredictable. The
2383 jump buffer requires 3 bytes of data (the stack pointer
2384 & a 16 byte return address), and can be placed in any
2387 * stdlib.h - contains the following functions.
2391 * string.h - contains the following functions.
2393 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr,
2394 strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok,
2395 memcpy, memcmp, memset.
2397 * ctype.h - contains the following routines.
2399 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct,
2400 isspace, isxdigit, isalnum, isalpha.
2402 * malloc.h - The malloc routines are developed by Dmitry
2403 S. Obukhov (dso@usa.net). These routines will allocate
2404 memory from the external ram. Here is a description on
2405 how to use them (as described by the author).
2409 #define DYNAMIC_MEMORY_SIZE 0x2000
2413 unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
2416 unsigned char xdata * current_buffer;
2426 init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
2429 //Now it's possible to use malloc.
2433 current_buffer = malloc(0x100);
2436 * serial.h - Serial IO routines are also developed by Dmitry
2437 S. Obukhov (dso@usa.net). These routines are interrupt
2438 driven with a 256 byte circular buffer, they also expect
2439 external ram to be present. Please see documentation in
2440 file SDCCDIR/sdcc51lib/serial.c. Note the header file
2441 "serial.h" MUST be included in the file containing
2442 the 'main' function.
2444 * ser.h - Alternate serial routine provided by Wolfgang Esslinger
2445 <wolfgang@WiredMinds.com> these routines are more compact
2446 and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
2448 * ser_ir.h - Another alternate set of serial routines provided
2449 by Josef Wolf <jw@raven.inka.de> , these routines do not
2450 use the external ram.
2452 * reg51.h - contains register definitions for a standard
2455 * float.h - contains min, max and other floating point related
2458 All library routines are compiled as --model-small , they
2459 are all non-reentrant, if you plan to use the large model
2460 or want to make these routines reentrant, then they will
2461 have to be recompiled with the appropriate compiler option.
2463 Have not had time to do the more involved routines like printf,
2464 will get to them shortly.
2466 4.4 Interfacing with Assembly Routines
2468 4.5 Global Registers used for Parameter Passing
2470 By default the compiler uses the global registers "DPL,DPH,B,ACC"
2471 to pass the first parameter to a routine, the second parameter
2472 onwards is either allocated on the stack (for reentrant
2473 routines or --stack-auto is used) or in the internal / external
2474 ram (depending on the memory model).
2476 4.5.1 Assembler Routine(non-reentrant)
2478 In the following example the function cfunc calls an assembler
2479 routine asm_func, which takes two parameters.
2481 extern int asm_func( unsigned char, unsigned char);
2484 int c_func (unsigned char i, unsigned char j)
2486 return asm_func(i,j);
2490 return c_func(10,9);
2493 The corresponding assembler function is:-
2495 .globl _asm_func_PARM_2
2512 Note here that the return values are placed in 'dpl' - One
2513 byte return value, 'dpl' LSB & 'dph' MSB for two byte values.
2514 'dpl', 'dph' and 'b' for three byte values (generic pointers)
2515 and 'dpl','dph','b' & 'acc' for four byte values.
2517 The parameter naming convention is _<function_name>_PARM_<n>,
2518 where n is the parameter number starting from 1, and counting
2519 from the left. The first parameter is passed in "dpl"
2520 for One bye parameter, "dptr"
2521 if two bytes, "b,dptr"
2522 for three bytes and "acc,b,dptr"
2523 for four bytes, the varaible name for the second parameter
2524 will be _<function_name>_PARM_2.
2526 Assemble the assembler routine with the following command.
2528 asx8051 -losg asmfunc.asm
2530 Then compile and link the assembler routine to the C source
2531 file with the following command,
2533 sdcc cfunc.c asmfunc.rel
2535 4.5.2 Assembler Routine(reentrant)
2537 In this case the second parameter onwards will be passed
2538 on the stack , the parameters are pushed from right to left
2539 i.e. after the call the left most parameter will be on the
2540 top of the stack. Here is an example.
2542 extern int asm_func( unsigned char, unsigned char);
2546 int c_func (unsigned char i, unsigned char j) reentrant
2548 return asm_func(i,j);
2552 return c_func(10,9);
2555 The corresponding assembler routine is.
2576 The compiling and linking procedure remains the same, however
2577 note the extra entry & exit linkage required for the assembler
2578 code, _bp is the stack frame pointer and is used to compute
2579 the offset into the stack for parameters and local variables.
2583 The external stack is located at the start of the external
2584 ram segment , and is 256 bytes in size. When --xstack option
2585 is used to compile the program, the parameters and local
2586 variables of all reentrant functions are allocated in this
2587 area. This option is provided for programs with large stack
2588 space requirements. When used with the --stack-auto option,
2589 all parameters and local variables are allocated on the
2590 external stack (note support libraries will need to be recompiled
2591 with the same options).
2593 The compiler outputs the higher order address byte of the
2594 external ram segment into PORT P2, therefore when using
2595 the External Stack option, this port MAY NOT be used by
2596 the application program.
2600 Deviations from the compliancy.
2602 1. functions are not always reentrant.
2604 2. structures cannot be assigned values directly, cannot be
2605 passed as function parameters or assigned to each other
2606 and cannot be a return value from a function.
2615 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI
2620 struct s foo1 (struct s parms) /* is invalid in SDCC although
2625 return rets;/* is invalid in SDCC although allowed in ANSI
2629 1. 'long long' (64 bit integers) not supported.
2631 2. 'double' precision floating point not supported.
2633 3. integral promotions are suppressed. What does this mean
2634 ? The compiler will not implicitly promote an integer
2635 expression to a higher order integer, exception is an
2636 assignment or parameter passing.
2638 4. No support for setjmp and longjmp (for now).
2640 5. Old K&R style function declarations are NOT allowed.
2642 foo( i,j) /* this old style of function declarations */
2643 int i,j; /* are valid in ANSI .. not valid in SDCC */
2648 1. functions declared as pointers must be dereferenced during
2654 /* has to be called like this */
2655 (*foo)();/* ansi standard allows calls to be made like
2658 4.8 Cyclomatic Complexity
2660 Cyclomatic complexity of a function is defined as the number
2661 of independent paths the program can take during execution
2662 of the function. This is an important number since it defines
2663 the number test cases you have to generate to validate the
2664 function. The accepted industry standard for complexity
2665 number is 10, if the cyclomatic complexity reported by SDCC
2666 exceeds 10 you should think about simplification of the
2669 Note that the complexity level is not related to the number
2670 of lines of code in a function. Large functions can have
2671 low complexity, and small functions can have large complexity
2672 levels. SDCC uses the following formula to compute the complexity.
2674 complexity = (number of edges in control flow graph) -
2676 of nodes in control flow graph) + 2;
2678 Having said that the industry standard is 10, you should
2679 be aware that in some cases it may unavoidable to have a
2680 complexity level of less than 10. For example if you have
2681 switch statement with more than 10 case labels, each case
2682 label adds one to the complexity level. The complexity level
2683 is by no means an absolute measure of the algorithmic complexity
2684 of the function, it does however provide a good starting
2685 point for which functions you might look at for further
2690 Here are a few guide-lines that will help the compiler generate
2691 more efficient code, some of the tips are specific to this
2692 compiler others are generally good programming practice.
2694 * Use the smallest data type to represent your data-value.
2695 If it is known in advance that the value is going to be
2696 less than 256 then use a 'char' instead of a 'short' or
2699 * Use unsigned when it is known in advance that the value
2700 is not going to be negative. This helps especially if
2701 you are doing division or multiplication.
2703 * NEVER jump into a LOOP.
2705 * Declare the variables to be local whenever possible, especially
2706 loop control variables (induction).
2708 * Since the compiler does not do implicit integral promotion,
2709 the programmer should do an explicit cast when integral
2710 promotion is required.
2712 * Reducing the size of division , multiplication & modulus
2713 operations can reduce code size substantially. Take the
2714 following code for example.
2716 foobar( unsigned int p1, unsigned char ch)
2718 unsigned char ch1 = p1 % ch ;
2722 For the modulus operation the variable ch will be promoted
2723 to unsigned int first then the modulus operation will
2724 be performed (this will lead to a call to a support routine).
2725 If the code is changed to
2727 foobar( unsigned int p1, unsigned char ch)
2729 unsigned char ch1 = (unsigned char)p1
2734 It would substantially reduce the code generated (future
2735 versions of the compiler will be smart enough to detect
2736 such optimization oppurtunities).
2738 Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
2740 The 8051 family of micro controller have a minimum of 128
2741 bytes of internal memory which is structured as follows
2743 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers
2746 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
2748 - Bytes 30-7F - 60 bytes for general purpose use.
2750 Normally the SDCC compiler will only utilise the first bank
2751 of registers, but it is possible to specify that other banks
2752 of registers should be used in interrupt routines. By default,
2753 the compiler will place the stack after the last bank of
2754 used registers, i.e. if the first 2 banks of registers are
2755 used, it will position the base of the internal stack at
2756 address 16 (0X10). This implies that as the stack grows,
2757 it will use up the remaining register banks, and the 16
2758 bytes used by the 128 bit variables, and 60 bytes for general
2761 By default, the compiler uses the 60 general purpose bytes
2762 to hold "near data". The compiler/optimiser may also declare
2763 some Local Variables in this area to hold local data.
2765 If any of the 128 bit variables are used, or near data is
2766 being used then care needs to be taken to ensure that the
2767 stack does not grow so much that it starts to over write
2768 either your bit variables or "near data". There is no runtime
2769 checking to prevent this from happening.
2771 The amount of stack being used is affected by the use of
2772 the "internal stack" to save registers before a subroutine
2773 call is made, - --stack-auto will declare parameters and
2774 local variables on the stack - the number of nested subroutines.
2776 If you detect that the stack is over writing you data, then
2777 the following can be done. --xstack will cause an external
2778 stack to be used for saving registers and (if --stack-auto
2779 is being used) storing parameters and local variables. However
2780 this will produce more and code which will be slower to
2783 --stack-loc will allow you specify the start of the stack,
2784 i.e. you could start it after any data in the general purpose
2785 area. However this may waste the memory not used by the
2786 register banks and if the size of the "near data" increases,
2787 it may creep into the bottom of the stack.
2789 --stack-after-data, similar to the --stack-loc, but it automatically
2790 places the stack after the end of the "near data". Again
2791 this could waste any spare register space.
2793 --data-loc allows you to specify the start address of the
2794 near data. This could be used to move the "near data" further
2795 away from the stack giving it more room to grow. This will
2796 only work if no bit variables are being used and the stack
2797 can grow to use the bit variable space.
2801 If you find that the stack is over writing your bit variables
2802 or "near data" then the approach which best utilised the
2803 internal memory is to position the "near data" after the
2804 last bank of used registers or, if you use bit variables,
2805 after the last bit variable by using the --data-loc, e.g.
2806 if two register banks are being used and no data variables,
2807 --data-loc 16, and - use the --stack-after-data option.
2809 If bit variables are being used, another method would be
2810 to try and squeeze the data area in the unused register
2811 banks if it will fit, and start the stack after the last
2814 6 Retargetting for other MCUs.
2816 The issues for retargetting the compiler are far too numerous
2817 to be covered by this document. What follows is a brief
2818 description of each of the seven phases of the compiler
2819 and its MCU dependency.
2821 1. Parsing the source and building the annotated parse tree.
2822 This phase is largely MCU independent (except for the
2823 language extensions). Syntax & semantic checks are also
2824 done in this phase , along with some initial optimizations
2825 like back patching labels and the pattern matching optimizations
2826 like bit-rotation etc.
2828 2. The second phase involves generating an intermediate code
2829 which can be easy manipulated during the later phases.
2830 This phase is entirely MCU independent. The intermediate
2831 code generation assumes the target machine has unlimited
2832 number of registers, and designates them with the name
2833 iTemp. The compiler can be made to dump a human readable
2834 form of the code generated by using the --dumpraw option.
2836 3. This phase does the bulk of the standard optimizations
2837 and is also MCU independent. This phase can be broken
2838 down into several sub-phases.
2840 * Break down intermediate code (iCode) into basic blocks.
2842 * Do control flow & data flow analysis on the basic blocks.
2844 * Do local common subexpression elimination, then global
2845 subexpression elimination
2847 * dead code elimination
2849 * loop optimizations
2851 * if loop optimizations caused any changes then do 'global
2852 subexpression elimination' and 'dead code elimination'
2855 4. This phase determines the live-ranges; by live range I
2856 mean those iTemp variables defined by the compiler that
2857 still survive after all the optimizations. Live range
2858 analysis is essential for register allocation, since these
2859 computation determines which of these iTemps will be assigned
2860 to registers, and for how long.
2862 5. Phase five is register allocation. There are two parts
2865 (a) The first part I call 'register packing' (for lack of
2866 a better term). In this case several MCU specific expression
2867 folding is done to reduce register pressure.
2869 (b) The second part is more MCU independent and deals with
2870 allocating registers to the remaining live ranges. A
2871 lot of MCU specific code does creep into this phase
2872 because of the limited number of index registers available
2875 6. The Code generation phase is (unhappily), entirely MCU
2876 dependent and very little (if any at all) of this code
2877 can be reused for other MCU. However the scheme for allocating
2878 a homogenized assembler operand for each iCode operand
2881 7. As mentioned in the optimization section the peep-hole
2882 optimizer is rule based system, which can reprogrammed
2885 7 SDCDB - Source Level Debugger
2887 SDCC is distributed with a source level debugger. The debugger
2888 uses a command line interface, the command repertoire of
2889 the debugger has been kept as close to gdb ( the GNU debugger)
2890 as possible. The configuration and build process is part
2891 of the standard compiler installation, which also builds
2892 and installs the debugger in the target directory specified
2893 during configuration. The debugger allows you debug BOTH
2894 at the C source and at the ASM source level.
2896 7.1 Compiling for Debugging
2898 The --debug option must be specified for all files for which
2899 debug information is to be generated. The complier generates
2900 a .cdb file for each of these files. The linker updates
2901 the .cdb file with the address information. This .cdb is
2902 used by the debugger.
2904 7.2 How the Debugger Works
2906 When the --debug option is specified the compiler generates
2907 extra symbol information some of which are put into the
2908 the assembler source and some are put into the .cdb file,
2909 the linker updates the .cdb file with the address information
2910 for the symbols. The debugger reads the symbolic information
2911 generated by the compiler & the address information generated
2912 by the linker. It uses the SIMULATOR (Daniel's S51) to execute
2913 the program, the program execution is controlled by the
2914 debugger. When a command is issued for the debugger, it
2915 translates it into appropriate commands for the simulator.
2917 7.3 Starting the Debugger
2919 The debugger can be started using the following command line.
2920 (Assume the file you are debugging has
2926 The debugger will look for the following files.
2928 1. foo.c - the source file.
2930 2. foo.cdb - the debugger symbol information file.
2932 3. foo.ihx - the intel hex format object file.
2934 7.4 Command Line Options.
2936 * --directory=<source file directory> this option can used
2937 to specify the directory search list. The debugger will
2938 look into the directory list specified for source , cdb
2939 & ihx files. The items in the directory list must be separated
2940 by ':' , e.g. if the source files can be in the directories
2941 /home/src1 and /home/src2, the --directory option should
2942 be --directory=/home/src1:/home/src2. Note there can be
2943 no spaces in the option.
2945 * -cd <directory> - change to the <directory>.
2947 * -fullname - used by GUI front ends.
2949 * -cpu <cpu-type> - this argument is passed to the simulator
2950 please see the simulator docs for details.
2952 * -X <Clock frequency > this options is passed to the simulator
2953 please see simulator docs for details.
2955 * -s <serial port file> passed to simulator see simulator
2958 * -S <serial in,out> passed to simulator see simulator docs
2961 7.5 Debugger Commands.
2963 As mention earlier the command interface for the debugger
2964 has been deliberately kept as close the GNU debugger gdb
2965 , as possible, this will help int integration with existing
2966 graphical user interfaces (like ddd, xxgdb or xemacs) existing
2967 for the GNU debugger.
2969 7.5.1 break [line | file:line | function | file:function]
2971 Set breakpoint at specified line or function.
2974 sdcdb>break foo.c:100
2976 sdcdb>break foo.c:funcfoo
2978 7.5.2 clear [line | file:line | function | file:function ]
2980 Clear breakpoint at specified line or function.
2983 sdcdb>clear foo.c:100
2985 sdcdb>clear foo.c:funcfoo
2989 Continue program being debugged, after breakpoint.
2993 Execute till the end of the current function.
2997 Delete breakpoint number 'n'. If used without any option
2998 clear ALL user defined break points.
3000 7.5.6 info [break | stack | frame | registers ]
3002 * info break - list all breakpoints
3004 * info stack - show the function call stack.
3006 * info frame - show information about the current execution
3009 * info registers - show content of all registers.
3013 Step program until it reaches a different source line.
3017 Step program, proceeding through subroutine calls.
3021 Start debugged program.
3023 7.5.10 ptype variable
3025 Print type information of the variable.
3027 7.5.11 print variable
3029 print value of variable.
3031 7.5.12 file filename
3033 load the given file name. Note this is an alternate method
3034 of loading file for debugging.
3038 print information about current frame.
3042 Toggle between C source & assembly source.
3044 7.5.15 ! simulator command
3046 Send the string following '!' to the simulator, the simulator
3047 response is displayed. Note the debugger does not interpret
3048 the command being sent to the simulator, so if a command
3049 like 'go' is sent the debugger can loose its execution context
3050 and may display incorrect values.
3054 "Watch me now. Iam going Down. My name is Bobby Brown"
3056 7.6 Interfacing with XEmacs.
3058 Two files are (in emacs lisp) are provided for the interfacing
3059 with XEmacs, sdcdb.el and sdcdbsrc.el. These two files can
3060 be found in the $(prefix)/bin directory after the installation
3061 is complete. These files need to be loaded into XEmacs for
3062 the interface to work, this can be done at XEmacs startup
3063 time by inserting the following into your '.xemacs' file
3064 (which can be found in your HOME directory) (load-file sdcdbsrc.el)
3065 [ .xemacs is a lisp file so the () around the command is
3066 REQUIRED), the files can also be loaded dynamically while
3067 XEmacs is running, set the environment variable 'EMACSLOADPATH'
3068 to the installation bin directory [$(prefix)/bin], then
3069 enter the following command ESC-x load-file sdcdbsrc. To
3070 start the interface enter the following command ESC-x sdcdbsrc
3071 , you will prompted to enter the file name to be debugged.
3073 The command line options that are passed to the simulator
3074 directly are bound to default values in the file sdcdbsrc.el
3075 the variables are listed below these values maybe changed
3078 * sdcdbsrc-cpu-type '51
3080 * sdcdbsrc-frequency '11059200
3082 * sdcdbsrc-serial nil
3084 The following is a list of key mapping for the debugger interface.
3087 ;; Current Listing ::
3088 ;;key binding Comment
3090 ;;--- ------- -------
3094 sdcdb-next-from-src SDCDB
3097 sdcdb-back-from-src SDCDB
3100 sdcdb-cont-from-src SDCDB
3103 sdcdb-step-from-src SDCDB
3106 sdcdb-whatis-c-sexp SDCDB
3107 ptypecommand for data at
3111 sdcdbsrc-delete SDCDB
3112 Delete all breakpoints if no arg
3114 or delete arg (C-u arg x)
3116 sdcdbsrc-frame SDCDB
3117 Display current frame if no arg,
3119 or display frame arg
3123 sdcdbsrc-goto-sdcdb Goto
3124 the SDCDB output buffer
3126 sdcdb-print-c-sexp SDCDB
3127 print command for data at
3131 sdcdbsrc-goto-sdcdb Goto
3132 the SDCDB output buffer
3134 sdcdbsrc-mode Toggles
3135 Sdcdbsrc mode (turns it off)
3138 sdcdb-finish-from-src SDCDB
3143 break for line with point
3145 sdcdbsrc-mode Toggle
3155 8.1 The Z80 and gbz80 port
3157 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's
3158 Z80-like gbz80. The port is incomplete - long support is
3159 incomplete (mul, div and mod are unimplimented), and both
3160 float and bitfield support is missing, but apart from that
3161 the code generated is correct.
3163 As always, the code is the authoritave reference - see z80/ralloc.c
3164 and z80/gen.c. The stack frame is similar to that generated
3165 by the IAR Z80 compiler. IX is used as the base pointer,
3166 HL is used as a temporary register, and BC and DE are available
3167 for holding varibles. IY is currently unusued. Return values
3168 are stored in HL. One bad side effect of using IX as the
3169 base pointer is that a functions stack frame is limited
3170 to 127 bytes - this will be fixed in a later version.
3174 SDCC has grown to be large project, the compiler alone (without
3175 the Assembler Package, Preprocessor) is about 40,000 lines
3176 of code (blank stripped). The open source nature of this
3177 project is a key to its continued growth and support. You
3178 gain the benefit and support of many active software developers
3179 and end users. Is SDCC perfect? No, that's why we need your
3180 help. The developers take pride in fixing reported bugs.
3181 You can help by reporting the bugs and helping other SDCC
3182 users. There are lots of ways to contribute, and we encourage
3183 you to take part in making SDCC a great software package.
3187 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
3188 or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed
3189 ASAP. When reporting a bug, it is very useful to include
3190 a small test program which reproduces the problem. If you
3191 can isolate the problem by looking at the generated assembly
3192 code, this can be very helpful. Compiling your program with
3193 the --dumpall option can sometimes be useful in locating
3194 optimization problems.
3198 Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler,
3199 MCS51 code generator, Debugger, AVR port
3200 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version
3202 John Hartman (jhartman@compuserve.com) - Porting ASXXX &
3204 Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
3206 Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his
3208 Malini Dutta(malini_dutta@hotmail.com) - my wife for her
3209 patience and support.
3210 Unknown - for the GNU C - preprocessor.
3211 Michael Hope - The Z80 and Z80GB port, 186 development
3212 Kevin Vigor - The DS390 port.
3213 Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
3214 Scott Datallo - PIC port.
3215 (Thanks to all the other volunteer developers who have helped
3216 with coding, testing, web-page creation, distribution sets,
3217 etc. You know who you are :-)
3220 This document initially written by Sandeep Dutta
3222 All product names mentioned herein may be trademarks of their
3223 respective companies.