1 #LyX 1.1 created this file. For more info see http://www.lyx.org/
14 \paperorientation portrait
17 \paragraph_separation indent
19 \quotes_language english
23 \paperpagestyle default
27 SDCC Compiler User Guide
31 \begin_inset LatexCommand \tableofcontents{}
48 is a Free ware, retargettable, optimizing ANSI-C compiler by
52 designed for 8 bit Microprocessors.
53 The current version targets Intel MCS51 based Microprocessors(8051,8052,
54 etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51 variant.
55 It can be retargetted for other microprocessors, support for PIC, AVR and
56 186 is under development.
57 The entire source code for the compiler is distributed under GPL.
58 SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
59 SDCC has extensive language extensions suitable for utilizing various microcont
60 rollers underlying hardware effectively.
61 In addition to the MCU specific optimizations SDCC also does a host of
62 standard optimizations like
64 global sub expression elimination, loop optimizations (loop invariant,
65 strength reduction of induction variables and loop reversing), constant
66 folding & propagation, copy propagation, dead code elimination and jumptables
67 for 'switch' statements.
70 For the back-end SDCC uses a global register allocation scheme which should
71 be well suited for other 8 bit MCUs.
72 The peep hole optimizer uses a rule based substitution mechanism which
74 Supported data-types are
76 short (8 bits, 1 byte), char (8 bits, 1 byte), int (16 bits, 2 bytes ),
77 long (32 bit, 4 bytes) & float (4 byte IEEE).
80 The compiler also allows
84 to be embedded anywhere in a function.
85 In addition routines developed in assembly can also be called.
86 SDCC also provides an option to report the relative complexity of a function,
87 these functions can then be further optimized, or hand coded in assembly
89 SDCC also comes with a companion source level debugger SDCDB, the debugger
90 currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
91 The latest version can be downloaded from
94 \begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
104 All packages used in this compiler system are
108 (freeware); source code for all the sub-packages (asxxxx assembler/linker,
109 pre-processor) are distributed with the package.
110 This documentation is maintained using a freeware word processor (LyX).
114 This program is free software; you can redistribute it and/or modify it
115 under the terms of the GNU General Public License as published by the Free
116 Software Foundation; either version 2, or (at your option) any later version.
117 This program is distributed in the hope that it will be useful, but WITHOUT
118 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
119 FOR A PARTICULAR PURPOSE.
120 See the GNU General Public License for more details.
121 You should have received a copy of the GNU General Public License along
122 with this program; if not, write to the Free Software Foundation, 59 Temple
123 Place - Suite 330, Boston, MA 02111-1307, USA.
124 In other words, you are welcome to use, share and improve this program.
125 You are forbidden to forbid anyone else to use, share and improve what
127 Help stamp out software-hoarding!
133 What do you need before you start installation of SDCC? A computer, and
135 The preferred method of installation is to compile SDCC from source using
137 For Windows some pre-compiled binary distributions are available for your
139 You should have some experience with command line tools and compiler use.
145 The SDCC home page at
146 \begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
150 is a great place to find distribution sets.
151 You can also find links to the user mailing lists that offer help or discuss
152 SDCC with other SDCC users.
153 Web links to other SDCC related sites can also be found here.
154 This document can be found in the DOC directory of the source package as
156 Some of the other tools(simulator and assembler) included with SDCC contain
157 their own documentation and can be found in the source distribution.
158 If you want the latest unreleased software, the complete source package
159 is available directly by anonymous CVS on www.sourceforge.net.
165 Linux/Unix Installation
170 Download the source package, it will be named something like sdcc-2.x.x.tgz.
175 Bring up a command line terminal, such as xterm.
180 Unpack the file using a command like: tar -xzf sdcc-2.x.x.tgz, this will create
181 a sub-directory called sdcc with all of the sources.
184 Change directory into the main SDCC directory, for example type:
185 \begin_inset Quotes eld
189 \begin_inset Quotes erd
198 \begin_inset Quotes eld
202 \begin_inset Quotes erd
208 This configures the package for compilation on your system.
214 \begin_inset Quotes eld
218 \begin_inset Quotes erd
224 All of the source packages will compile, this can take a while.
230 \begin_inset Quotes eld
234 \begin_inset Quotes erd
244 This copies the binary executables to the install directories.
250 For installation under Windows you first need to pick between a pre-compiled
251 binary package, or installing the source package along with the Cygwin
253 The binary package is the quickest to install, while the Cygwin package
254 includes all of the open source power tools used to compile the complete
255 SDCC source package in the Windows environment.
256 If you are not familiar with the Unix command line environment, you may
257 want to read the section on additional information for Windows users prior
258 to your initial installation.
259 \layout Subsubsection
261 Windows Install Using a Binary Package
264 Download the binary package and unpack it using your favorite unpacking
265 tool(gunzip, WinZip, etc).
266 This should unpack to a group of sub-directories.
267 An example directory structure after unpacking is: c:
273 bin for the executables, c:
293 lib for the include and libraries.
296 Adjust your environment PATH to include the location of the bin directory.
297 For example, make a setsdcc.bat file with the following: set PATH=c:
306 When you compile with sdcc, you may need to specify the location of the
307 lib and include folders.
308 For example, sdcc -I c:
331 \layout Subsubsection
333 Windows Install Using Cygwin
338 Download and install the cygwin package from the redhat site
342 \begin_inset LatexCommand \htmlurl{http://sources.redhat.com/cygwin/}
350 Currently, this involved downloading a small install program which then
351 automates downloading and installing
357 (a large 80M byte sized dowload for the whole thing)
371 command line terminal from the Cygwin menu.
376 Follow the instructions in the preceding Linux/Unix installation section.
379 Testing out the SDCC Compiler
382 The first thing you should do after installing your SDCC compiler is to
385 \begin_inset Quotes eld
389 \begin_inset Quotes erd
392 at the prompt, and the program should run and tell you the version.
393 If it doesn't run, or gives a message about not finding sdcc program, then
394 you need to check over your installation.
395 Make sure that the sdcc bin directory is in your executable search path
396 defined by the PATH environment setting(see the Trouble-shooting section
398 Make sure that the sdcc program is in the bin folder, if not perhaps something
399 did not install correctly.
404 SDCC binaries are commonly installed in a directory arrangement like this:
409 <lyxtabular version="2" rows="3" columns="2">
410 <features rotate="false" islongtable="false" endhead="0" endfirsthead="0" endfoot="0" endlastfoot="0">
411 <column alignment="left" valignment="top" leftline="true" rightline="false" width="" special="">
412 <column alignment="left" valignment="top" leftline="true" rightline="true" width="" special="">
413 <row topline="true" bottomline="true" newpage="false">
414 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
424 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
431 Holds executables(sdcc, s51, aslink,
439 <row topline="true" bottomline="false" newpage="false">
440 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
447 usr/local/share/sdcc/lib
450 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
463 <row topline="true" bottomline="true" newpage="false">
464 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
471 usr/local/share/sdcc/include
474 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
481 Holds common C header files
494 Make sure the compiler works on a very simple example.
495 Type in the following test.c program using your favorite editor:
518 Compile this using the following command:
519 \begin_inset Quotes eld
523 \begin_inset Quotes erd
527 If all goes well, the compiler will generate a test.asm and test.rel file.
528 Congratulations, you've just compiled your first program with SDCC.
529 We used the -c option to tell SDCC not to link the generated code, just
530 to keep things simple for this step.
535 The next step is to try it with the linker.
537 \begin_inset Quotes eld
541 \begin_inset Quotes erd
545 If all goes well the compiler will link with the libraries and produce
546 a test.ihx output file.
547 If this step fails(no test.ihx, and the linker generates warnings), then
548 the problem is most likely that sdcc cannot find the usr/local/share/sdcc/lib
552 directory(see the Install trouble-shooting section for suggestions).
557 The final test is to ensure sdcc can use the standard header files and libraries.
558 Edit test.c and change it to the following:
570 \begin_inset Quotes eld
574 \begin_inset Quotes erd
584 Compile this by typing:
585 \begin_inset Quotes eld
589 \begin_inset Quotes erd
593 This should generate a test.ihx output file, and it should give no warnings
594 such as not finding the string.h file.
595 If it cannot find the string.h file, then the problem is that sdcc cannot
596 find the /usr/local/share/sdcc/include directory(see the Install trouble-shooti
597 ng section for suggestions).
600 Install Trouble-shooting
601 \layout Subsubsection
603 SDCC cannot find libraries or header files.
606 The default installation assumes the libraries and header files are located
608 \begin_inset Quotes eld
611 /usr/local/share/sdcc/lib
612 \begin_inset Quotes erd
616 \begin_inset Quotes eld
619 /usr/local/share/sdcc/include
620 \begin_inset Quotes erd
624 An alternative is to specify these locations as compiler options like this:
625 sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include test.c
626 \layout Subsubsection
628 SDCC does not compile correctly.
631 A few things to try include starting from scratch by unpacking the .tgz source
632 package again in an empty directory.
633 If this doesn't work, you could try downloading a different version.
634 If this doesn't work, you can re-direct the install messages by doing the
638 $./make > dump.txt 2>&1
641 After this you can examine the dump.txt files to locate the problem.
642 Or these messages can be attached to an email that could be helpful when
643 requesting help from the mailing list.
644 \layout Subsubsection
647 \begin_inset Quotes eld
651 \begin_inset Quotes erd
658 \begin_inset Quotes eld
662 \begin_inset Quotes erd
665 command is a script that analyzes your system and performs some configuration
666 to ensure the source package compiles on your system.
667 It will take a few minutes to run, and will compile a few tests to determine
668 what compiler features are installed.
669 \layout Subsubsection
672 \begin_inset Quotes eld
676 \begin_inset Quotes erd
682 This runs the GNU make tool, which automatically compiles all the source
683 packages into the final installed binary executables.
684 \layout Subsubsection
687 \begin_inset Quotes eld
691 \begin_inset Quotes erd
697 This will install the compiler, other executables and libraries in to the
698 appropriate system directories.
699 The default is to copy the executables to /usr/local/bin and the libraries
700 and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
703 Additional Information for Windows Users
706 The standard method of installing on a Unix system involves compiling the
708 This is easily done under Unix, but under Windows it can be a more difficult
710 The Cygwin is a large package to download, and the compilation runs considerabl
711 y slower under Windows due to the overhead of the Cygwin tool set.
712 An alternative is to install a pre-compiled Windows binary package.
713 There are various trade-offs between each of these methods.
717 The Cygwin package allows a Windows user to run a Unix command line interface(ba
718 sh shell) and also implements a Unix like file system on top of Windows.
719 Included are many of the famous GNU software development tools which can
720 augment the SDCC compiler.This is great if you have some experience with
721 Unix command line tools and file system conventions, if not you may find
722 it easier to start by installing a binary Windows package.
723 The binary packages work with the Windows file system conventions.
724 \layout Subsubsection
726 Getting started with Cygwin
729 SDCC is typically distributed as a tarred/gzipped file(.tgz).
730 This is a packed file similar to a .zip file.
731 Cygwin includes the tools you will need to unpack the SDCC distribution(tar
733 To unpack it, simply follow the instructions under the Linux/Unix install
735 Before you do this you need to learn how to start a cygwin shell and some
736 of the basic commands used to move files, change directory, run commands
738 The change directory command is
739 \begin_inset Quotes eld
743 \begin_inset Quotes erd
746 , the move command is
747 \begin_inset Quotes eld
751 \begin_inset Quotes erd
755 To print the current working directory, type
756 \begin_inset Quotes eld
760 \begin_inset Quotes erd
764 To make a directory, use
765 \begin_inset Quotes eld
769 \begin_inset Quotes erd
775 There are some basic differences between Unix and Windows file systems you
777 When you type in directory paths, Unix and the Cygwin bash prompt uses
778 forward slashes '/' between directories while Windows traditionally uses
782 So when you work at the Cygwin bash prompt, you will need to use the forward
784 Unix does not have a concept of drive letters, such as
785 \begin_inset Quotes eld
789 \begin_inset Quotes eld
792 , instead all files systems attach and appear as directories.
793 \layout Subsubsection
795 Running SDCC as Native Compiled Executables
798 If you use the pre-compiled binaries, the install directories for the libraries
799 and header files may need to be specified on the sdcc command line like
818 include test.c if you are running outside of a Unix bash shell.
821 If you have successfully installed and compiled SDCC with the Cygwin package,
822 it is possible to compile into native .exe files by using the additional
823 makefiles included for this purpose.
824 For example, with the Borland 32-bit compiler you would run make -f Makefile.bcc.
825 A command line version of the Borland 32-bit compiler can be downloaded
826 from the Inprise web site.
829 SDCC on Other Platforms
834 FreeBSD and other non-GNU Unixes
836 - Make sure the GNU make is installed as the default make tool.
839 SDCC has been ported to run under a variety of operating systems and processors.
840 If you can run GNU GCC/make then chances are good SDCC can be compiled
841 and run on your system.
844 Advanced Install Options
848 \begin_inset Quotes eld
852 \begin_inset Quotes erd
855 command has several options.
856 The most commonly used option is --prefix=<directory name>, where <directory
857 name> is the final location for the sdcc executables and libraries, (default
858 location is /usr/local).
859 The installation process will create the following directory structure
860 under the <directory name> specified.
864 bin/ - binary exectables (add to PATH environment variable)
881 sdcc/include/ - include header files
906 small/ - Object & library files for small model library
921 large/ - Object & library files for large model library
936 ds390/ - Object & library files forDS80C390 library
946 './configure --prefix=/usr/local
947 \begin_inset Quotes erd
953 will configure the compiler to be installed in directory /usr/local/bin.
959 SDCC is not just a compiler, but a collection of tools by various developers.
960 These include linkers, assemblers, simulators and other components.
961 Here is a summary of some of the components.
962 Note that the included simulator and assembler have separate documentation
963 which you can find in the source package in their respective directories.
964 As SDCC grows to include support for other processors, other packages from
965 various developers are included and may have their own sets of documentation.
968 You might want to look at the various executables which are installed in
970 At the time of this writing, we find the following programs:
984 -The linker for 8051 type processors.
991 - The assembler for 8051 type processors.
998 - The C preprocessor.
1005 - The source debugger.
1012 - The ucSim 8051 simulator.
1019 - The Z80 and GameBoy Z80 linkers.
1026 - The Z80 and GameBoy Z80 assemblers.
1033 - A tool to pack Intel hex files.
1036 As development for other processors proceeds, this list will expand to include
1037 executables to support processors like AVR, PIC, etc.
1038 \layout Subsubsection
1040 cpp ( C-Preprocessor)
1043 The preprocessor is extracted into the directory
1047 , it is a modified version of the GNU preprocessor.
1048 The C preprocessor is used to pull in #include sources, process #ifdef
1049 statements, #defines and so on.
1050 \layout Subsubsection
1052 asxxxx & aslink ( The assembler and Linkage Editor)
1055 This is retargettable assembler & linkage editor, it was developed by Alan
1056 Baldwin, John Hartman created the version for 8051, and I (Sandeep) have
1057 some enhancements and bug fixes for it to work properly with the SDCC.
1058 This component is extracted into the directory
1061 \layout Subsubsection
1066 This is the actual compiler, it in turn uses the c-preprocessor and invokes
1067 the assembler and linkage editors.
1068 All files with the prefix
1072 are part of the compiler and are extracted into the the directory
1075 \layout Subsubsection
1080 s51 is a freeware, opensource simulator developed by Daniel Drotos <drdani@mazso
1081 la.iit.uni-miskolc.hu>.
1082 The executable is built as part of the build process, for more information
1083 visit Daniel's website at <http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51/
1085 \layout Subsubsection
1087 SDCDB - Source Level Debugger
1090 SDCDB is the companion source level debugger .
1091 The current version of the debugger uses Daniel's Simulator S51, but can
1092 be easily changed to use other simulators.
1099 \layout Subsubsection
1101 Single Source File Projects
1104 For single source file 8051 projects the process is very simple.
1105 Compile your programs with the following command
1113 The above command will compile ,assemble and link your source file.
1114 Output files are as follows.
1119 sourcefile.asm - Assembler source file created by the compiler
1124 sourcefile.lst - Assembler listing file created by the Assembler
1129 sourcefile.rst - Assembler listing file updated with linkedit information
1130 , created by linkage editor
1135 sourcefile.sym - symbol listing for the sourcefile, created by the assembler.
1140 sourcefile.rel - Object file created by the assembler, input to Linkage editor.
1145 sourcefile.map - The memory map for the load module, created by the Linker.
1150 sourcefile.<ihx | s19> - The load module : ihx - Intel hex format (default
1151 ), s19 - Motorola S19 format when compiler option --out-fmt-s19 is used.
1152 \layout Subsubsection
1154 Projects with Multiple Source Files
1157 SDCC can compile only ONE file at a time.
1158 Let us for example assume that you have a project containing the following
1164 foo1.c ( contains some functions )
1169 foo2.c (contains some more functions)
1174 foomain.c (contains more functions and the function main)
1177 The first two files will need to be compiled separately with the commands
1190 Then compile the source file containing main and link the other files together
1191 with the following command.
1196 sdcc foomain.c foo1.rel foo2.rel
1203 can be separately compiled as well
1213 sdcc foomain.rel foo1.rel foo2.rel
1216 The file containing the main function MUST be the FIRST file specified in
1217 the command line , since the linkage editor processes file in the order
1218 they are presented to it.
1219 \layout Subsubsection
1221 Projects with Additional Libraries
1224 Some reusable routines may be compiled into a library, see the documentation
1225 for the assembler and linkage editor in the directory
1227 SDCCDIR/asxxxx/asxhtm.htm
1229 this describes how to create a
1233 library file, the libraries created in this manner may be included using
1234 the command line, make sure you include the -L <library-path> option to
1235 tell the linker where to look for these files.
1236 Here is an example, assuming you have the source file
1253 sdcc foomain.c foolib.lib -L mylib
1260 ' must be an absolute path name.
1263 The view of the way the linkage editor processes the library files, it is
1264 recommended that you put each source routine in a separate file and combine
1265 them using the .lib file.
1266 For an example see the standard library file 'libsdcc.lib' in the directory
1270 Command Line Options
1271 \layout Subsubsection
1273 Processor Selection Options
1275 \labelwidthstring 00.00.0000
1281 Generate code for the MCS51 (8051) family of processors.
1282 This is the default processor target.
1284 \labelwidthstring 00.00.0000
1290 Generate code for the DS80C390 processor.
1292 \labelwidthstring 00.00.0000
1298 Generate code for the Z80 family of processors.
1300 \labelwidthstring 00.00.0000
1306 Generate code for the GameBoy Z80 processor.
1308 \labelwidthstring 00.00.0000
1314 Generate code for the Atmel AVR processor(In development, not complete).
1316 \labelwidthstring 00.00.0000
1322 Generate code for the PIC 14-bit processors(In development, not complete).
1324 \labelwidthstring 00.00.0000
1330 Generate code for the Toshiba TLCS-900H processor(In development, not complete).
1331 \layout Subsubsection
1333 Path, Lib and Define Options
1335 \labelwidthstring 00.00.0000
1343 The additional location where the pre processor will look for <..h> or
1344 \begin_inset Quotes eld
1348 \begin_inset Quotes erd
1353 \labelwidthstring 00.00.0000
1363 Command line definition of macros.
1364 Passed to the pre processor.
1366 \labelwidthstring 00.00.0000
1377 <absolute path to additional libraries> This option is passed to the linkage
1378 editor, additional libraries search path.
1379 The path name must be absolute.
1380 Additional library files may be specified in the command line .
1381 See section Compiling programs for more details.
1382 \layout Subsubsection
1386 \labelwidthstring 00.00.0000
1394 Generate code for Large model programs see section Memory Models for more
1396 If this option is used all source files in the project should be compiled
1398 In addition the standard library routines are compiled with small model
1399 , they will need to be recompiled.
1401 \labelwidthstring 00.00.0000
1414 Generate code for Small Model programs see section Memory Models for more
1416 This is the default model.
1418 \labelwidthstring 00.00.0000
1431 Generate code forDS80C390 24-bit flat mode.
1432 See section Memory Models for more details.
1434 \labelwidthstring 00.00.0000
1448 All functions in the source file will be compiled as
1453 the parameters and local variables will be allocated on the stack.
1454 see section Parameters and Local Variables for more details.
1455 If this option is used all source files in the project should be compiled
1459 \labelwidthstring 00.00.0000
1469 Uses a pseudo stack in the first 256 bytes in the external ram for allocating
1470 variables and passing parameters.
1471 See section on external stack for more details.
1472 \layout Subsubsection
1474 Optimization Options
1476 \labelwidthstring 00.00.0000
1486 Will not do global subexpression elimination, this option may be used when
1487 the compiler creates undesirably large stack/data spaces to store compiler
1489 A warning message will be generated when this happens and the compiler
1490 will indicate the number of extra bytes it allocated.
1491 It recommended that this option NOT be used , #pragma NOGCSE can be used
1492 to turn off global subexpression elimination for a given function only.
1494 \labelwidthstring 00.00.0000
1504 Will not do loop invariant optimizations, this may be turned off for reasons
1505 explained for the previous option .
1506 For more details of loop optimizations performed see section Loop Invariants.It
1507 recommended that this option NOT be used , #pragma NOINVARIANT can be used
1508 to turn off invariant optimizations for a given function only.
1510 \labelwidthstring 00.00.0000
1520 Will not do loop induction optimizations, see section Strength reduction
1521 for more details.It recommended that this option NOT be used , #pragma NOINDUCTI
1522 ON can be used to turn off induction optimizations for given function only.
1524 \labelwidthstring 00.00.0000
1534 Will not generate boundary condition check when switch statements are implement
1535 ed using jump-tables.
1536 See section Switch Statements for more details.It recommended that this
1537 option NOT be used , #pragma NOJTBOUND can be used to turn off boundary
1538 checking for jump tables for a given function only.
1540 \labelwidthstring 00.00.0000
1551 Will not do loop reversal optimization
1553 \labelwidthstring 00.00.0000
1563 By default the first parameter is passed using global registers (DPL,DPH,B,ACC).
1564 This option will disable parameter passing using registers.
1565 NOTE: if your program uses the 16/32 bit support routines (for multiplication/d
1566 ivision) these library routines will need to be recompiled with the --noregparms
1568 \layout Subsubsection
1572 \labelwidthstring 00.00.0000
1578 See MCS51 section for description.
1580 \labelwidthstring 00.00.0000
1586 This option generates code for the 10 bit stack mode of the Dallas DS80C390
1588 In this mode, the stack is located in the lower 1K of the internal RAM,
1589 which is mapped to 0x400000.
1590 Note that the support is incomplete, since it still uses a single byte
1591 as the stack pointer.
1592 This means that only the lower 256 bytes of the potential 1K stack space
1593 can actually be used.
1594 However, this does allow you to reclaim the precious 256 bytes of low RAM
1595 for use for the DATA and IDATA segments.
1596 The compiler will not generate any code to put the processor into 10 bit
1598 It is important to ensure that the processor is in this mode before calling
1599 any re-entrant functions compiled with this option.
1600 In principle, this should work with the --stack-auto option, but that has
1602 It is incompatible with the --xstack option.
1603 It also only makes sense if the processor is in 24 bit contiguous addressing
1604 mode (see the --model-flat24 option).
1605 \layout Subsubsection
1609 \labelwidthstring 00.00.0000
1615 --callee-saves function1[,function2][,function3]....
1620 The compiler by default uses a caller saves convention for register saving
1621 across function calls, however this can cause unneccessary register pushing
1622 & popping when calling small functions from larger functions.
1623 This option can be used to switch the register saving convention for the
1624 function names specified.
1625 The compiler will not save registers when calling these functions, extra
1626 code will be generated at the entry & exit for these functions to save
1627 & restore the registers used by these functions, this can SUBSTANTIALLY
1628 reduce code & improve run time performance of the generated code.
1629 In future the compiler (with interprocedural analysis) will be able to
1630 determine the appropriate scheme to use for each function call.
1631 DO NOT use this option for built-in functions such as _muluint..., if this
1632 option is used for a library function the appropriate library function
1633 needs to be recompiled with the same option.
1634 If the project consists of multiple source files then all the source file
1635 should be compiled with the same --callee-saves option string.
1636 Also see Pragma Directive CALLEE-SAVES.
1639 \labelwidthstring 00.00.0000
1647 When this option is used the compiler will generate debug information ,
1648 that can be used with the SDCDB.
1649 The debug information is collected in a file with .cdb extension.
1650 For more information see documentation for SDCDB.
1652 \labelwidthstring 00.00.0000
1663 This option will cause the compiler to define pseudo registers , if this
1664 option is used, all source files in the project should be compiled with
1666 See section Register Extension for more details.
1668 \labelwidthstring 00.00.0000
1679 will compile and assemble the source only, will not call the linkage editor.
1681 \labelwidthstring 00.00.0000
1691 <Value> The start location of the external ram, default value is 0.
1692 The value entered can be in Hexadecimal or Decimal format .eg.
1693 --xram-loc 0x8000 or --xram-loc 32768.
1695 \labelwidthstring 00.00.0000
1705 <Value> The start location of the code segment , default value 0.
1706 Note when this option is used the interrupt vector table is also relocated
1707 to the given address.
1708 The value entered can be in Hexadecimal or Decimal format .eg.
1709 --code-loc 0x8000 or --code-loc 32768.
1711 \labelwidthstring 00.00.0000
1721 <Value> The initial value of the stack pointer.
1722 The default value of the stack pointer is 0x07 if only register bank 0
1723 is used, if other register banks are used then the stack pointer is initialized
1724 to the location above the highest register bank used.
1726 if register banks 1 & 2 are used the stack pointer will default to location
1728 The value entered can be in Hexadecimal or Decimal format .eg.
1729 --stack-loc 0x20 or --stack-loc 32.
1730 If all four register banks are used the stack will be placed after the
1731 data segment (equivalent to --stack-after-data)
1733 \labelwidthstring 00.00.0000
1743 This option will cause the stack to be located in the internal ram after
1746 \labelwidthstring 00.00.0000
1756 <Value> The start location of the internal ram data segment, the default
1757 value is 0x30.The value entered can be in Hexadecimal or Decimal format
1759 --data-loc 0x20 or --data-loc 32.
1761 \labelwidthstring 00.00.0000
1771 <Value> The start location of the indirectly addressable internal ram, default
1773 The value entered can be in Hexadecimal or Decimal format .eg.
1774 --idata-loc 0x88 or --idata-loc 136.
1776 \labelwidthstring 00.00.0000
1786 <filename> This option can be used to use additional rules to be used by
1787 the peep hole optimizer.
1788 See section Peep Hole optimizations for details on how to write these rules.
1790 \labelwidthstring 00.00.0000
1800 Run only the C preprocessor.
1801 Preprocess all the C source files specified and output the results to standard
1804 \labelwidthstring 00.00.0000
1814 Tell the preprocessor to output a rule suitable for make describing the
1815 dependencies of each object file.
1816 For each source file, the preprocessor outputs one make-rule whose target
1817 is the object file name for that source file and whose dependencies are
1818 all the files `#include'd in it.
1819 This rule may be a single line or may be continued with `
1821 '-newline if it is long.
1822 The list of rules is printed on standard output instead of the preprocessed
1826 \labelwidthstring 00.00.0000
1836 Tell the preprocessor not to discard comments.
1837 Used with the `-E' option.
1839 \labelwidthstring 00.00.0000
1849 Like `-M' but the output mentions only the user header files included with
1851 System header files included with `#include <file>' are omitted.
1853 \labelwidthstring 00.00.0000
1863 Assert the answer answer for question, in case it is tested with a preprocessor
1864 conditional such as `#if #question(answer)'.
1865 `-A-' disables the standard assertions that normally describe the target
1868 \labelwidthstring 00.00.0000
1878 (answer) Assert the answer answer for question, in case it is tested with
1879 a preprocessor conditional such as `#if #question(answer)'.
1880 `-A-' disables the standard assertions that normally describe the target
1883 \labelwidthstring 00.00.0000
1893 Undefine macro macro.
1894 `-U' options are evaluated after all `-D' options, but before any `-include'
1895 and `-imacros' options.
1897 \labelwidthstring 00.00.0000
1907 Tell the preprocessor to output only a list of the macro definitions that
1908 are in effect at the end of preprocessing.
1909 Used with the `-E' option.
1911 \labelwidthstring 00.00.0000
1921 Tell the preprocessor to pass all macro definitions into the output, in
1922 their proper sequence in the rest of the output.
1924 \labelwidthstring 00.00.0000
1934 Like `-dD' except that the macro arguments and contents are omitted.
1935 Only `#define name' is included in the output.
1937 \labelwidthstring 00.00.0000
1947 Stop after the stage of compilation proper; do not as- semble.
1948 The output is an assembler code file for the input file specified.
1950 \labelwidthstring 00.00.0000
1955 -Wa_asmOption[,asmOption]
1959 Pass the asmOption to the assembler.
1961 \labelwidthstring 00.00.0000
1966 -Wl_linkOption[,linkOption]
1970 Pass the linkOption to the linker.
1972 \labelwidthstring 00.00.0000
1983 Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
1984 Note by default these libraries are compiled as non-reentrant.
1985 See section Installation for more details.
1987 \labelwidthstring 00.00.0000
1998 This option will cause the compiler to generate an information message for
1999 each function in the source file.
2000 The message contains some
2004 information about the function.
2005 The number of edges and nodes the compiler detected in the control flow
2006 graph of the function, and most importantly the
2008 cyclomatic complexity
2010 see section on Cyclomatic Complexity for more details.
2012 \labelwidthstring 00.00.0000
2023 Floating point library is compiled as reentrant.See section Installation
2026 \labelwidthstring 00.00.0000
2037 The linker output (final object code) is in Intel Hex format.
2038 (This is the default option).
2040 \labelwidthstring 00.00.0000
2051 The linker output (final object code) is in Motorola S19 format.
2053 \labelwidthstring 00.00.0000
2063 The compiler will not overlay parameters and local variables of any function,
2064 see section Parameters and local variables for more details.
2066 \labelwidthstring 00.00.0000
2076 This option can be used when the code generated is called by a monitor
2078 The compiler will generate a 'ret' upon return from the 'main' function.
2079 The default option is to lock up i.e.
2080 generate a 'ljmp .' .
2082 \labelwidthstring 00.00.0000
2092 Disable peep-hole optimization.
2094 \labelwidthstring 00.00.0000
2104 Pass the inline assembler code through the peep hole optimizer.
2105 Can cause unexpected changes to inline assembler code , please go through
2106 the peephole optimizer rules defnied in file 'SDCCpeeph.def' before using
2109 \labelwidthstring 00.00.0000
2119 <Value> Causes the linker to check if the interal ram usage is within limits
2121 \layout Subsubsection
2123 Intermediate Dump Options
2126 The following options are provided for the purpose of retargetting and debugging
2128 These provided a means to dump the intermediate code (iCode) generated
2129 by the compiler in human readable form at various stages of the compilation
2133 \labelwidthstring 00.00.0000
2144 This option will cause the compiler to dump the intermediate code into
2147 <source filename>.dumpraw
2149 just after the intermediate code has been generated for a function , i.e.
2150 before any optimizations are done.
2151 The basic blocks at this stage ordered in the depth first number, so they
2152 may not be in sequence of execution.
2154 \labelwidthstring 00.00.0000
2166 Will create a dump if iCode, after global subexpression elimination, into
2169 <source filename>.dumpgcse.
2171 \labelwidthstring 00.00.0000
2181 .Will create a dump if iCode, after deadcode elimination, into a file named
2184 <source filename>.dumpdeadcode.
2186 \labelwidthstring 00.00.0000
2198 Will create a dump if iCode, after loop optimizations, into a file named
2201 <source filename>.dumploop.
2203 \labelwidthstring 00.00.0000
2215 Will create a dump if iCode, after live range analysis, into a file named
2218 <source filename>.dumprange.
2220 \labelwidthstring 00.00.0000
2232 Will create a dump if iCode, after register assignment , into a file named
2235 <source filename>.dumprassgn.
2237 \labelwidthstring 00.00.0000
2248 Will cause all the above mentioned dumps to be created.
2251 Note that the files created for the dump are appended to each time.
2252 So the files should be deleted manually , before each dump is created.
2256 When reporting bugs, it can be helpful to include these dumps along with
2257 the portion of the code that is causing the problem.
2260 MCS51 Storage Class Language Extensions
2263 In addition to the ANSI storage classes SDCC allows the following MCS51
2264 specific storage classes.
2265 \layout Subsubsection
2270 Variables declared with this storage class will be placed in the extern
2276 storage class for Large Memory model .
2284 xdata unsigned char xduc;
2285 \layout Subsubsection
2294 storage class for Small Memory model.
2295 Variables declared with this storage class will be allocated in the internal
2305 \layout Subsubsection
2310 Variables declared with this storage class will be allocated into the indirectly
2311 addressable portion of the internal ram of a 8051 .
2319 \layout Subsubsection
2324 This is a data-type and a storage class specifier.
2325 When a variable is declared as a bit , it is allocated into the bit addressable
2332 \layout Subsubsection
2337 Like the bit keyword,
2341 signifies both a data-type and storage class, they are used to describe
2342 the special function registers and special bit variables of a 8051.
2357 /* special function register P0 at location 0x80 */
2370 SDCC allows (via language extensions) pointers to explicitly point to any
2371 of the memory spaces of the 8051.
2372 In addition to the explicit pointers, the compiler also allows a
2376 class of pointers which can be used to point to any of the memory spaces.
2380 Pointer declaration examples.
2385 /* pointer physically in xternal ram pointing to object in internal ram
2388 data unsigned char * xdata p;
2395 /* pointer physically in code rom pointing to data in xdata space */
2397 xdata unsigned char * code p;
2404 /* pointer physically in code space pointing to data in code space */
2406 code unsigned char * code p;
2410 /* the folowing is a generic pointer physically located in xdata space */
2415 Well you get the idea.
2416 For compatibility with the previous version of the compiler, the following
2417 syntax for pointer declaration is also supported.
2418 Note the above examples will be portable to other commercially available
2424 unsigned char _xdata *ucxdp; /* pointer to data in external ram */
2426 unsigned char _data \SpecialChar ~
2427 *ucdp ; /* pointer to data in internal ram */
2429 unsigned char _code \SpecialChar ~
2430 *uccp ; /* pointer to data in R/O code space */
2432 unsigned char _idata *uccp; \SpecialChar ~
2433 /* pointer to upper 128 bytes of ram */
2436 All unqualified pointers are treated as 3 - byte '_generic' pointers.
2437 These type of pointers can also to be explicitly declared.
2442 unsigned char _generic *ucgp;
2445 The highest order byte of the generic pointers contains the data space informati
2447 Assembler support routines are called whenever data is stored or retrieved
2448 using _generic pointers.
2449 These are useful for developing reusable library routines.
2450 Explicitly specifying the pointer type will generate the most efficient
2452 Pointers declared using a mixture of OLD/NEW style could have unpredictable
2456 Parameters & Local Variables
2459 Automatic (local) variables and parameters to functions can either be placed
2460 on the stack or in data-space.
2461 The default action of the compiler is to place these variables in the internal
2462 RAM ( for small model) or external RAM (for Large model).
2463 They can be placed on the stack either by using the
2467 compiler option or by using the 'reentrant' keyword in the function declaration.
2478 unsigned short foo( short i) reentrant {
2486 Note that when the parameters & local variables are declared in the internal/ext
2487 ernal ram the functions are non-reentrant.
2488 Since stack space on 8051 is limited the
2496 option should be used sparingly.
2497 Note the reentrant keyword just means that the parameters & local variables
2498 will be allocated to the stack, it DOES NOT mean that the function is register
2502 When compiled with the default option (i.e.
2503 non-reentrant ), local variables can be assigned storage classes and absolute
2516 unsigned short foo() {
2520 xdata unsigned short i;
2528 data at 0x31 unsiged short j;
2536 In the above example the variable
2540 will be allocated in the external ram,
2544 in bit addressable space and
2549 When compiled with the
2553 or when a function is declared as
2557 local variables cannot be assigned storage classes or absolute addresses.
2560 Parameters however are not allowed any storage class, (storage classes for
2561 parameters will be ignored), their allocation is governed by the memory
2562 model in use , and the reentrancy options.
2568 For non-reentrant functions SDCC will try to reduce internal ram space usage
2569 by overlaying parameters and local variables of a function (if possible).
2570 Parameters and local variables of a function will be allocated to an overlayabl
2571 e segment if the function has
2573 no other function calls and the function is non-reentrant and the memory
2577 If an explicit storage class is specified for a local variable , it will
2581 Note that the compiler (not the linkage editor) makes the decision for overlayin
2583 Functions that are called from an interrupt service routine should be preceded
2584 by a #pragma NOOVERLAY if they are not reentrant Along the same lines the
2585 compiler does not do any processing with the inline assembler code so the
2586 compiler might incorrectly assign local variables and parameters of a function
2587 into the overlay segment if the only function call from a function is from
2588 inline assembler code, it is safe to use the #pragma NOOVERLAY for functions
2589 which call other functions using inline assembler code.
2592 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
2593 tion or division will NOT be overlayed since these are implemented using
2606 void set_error( unsigned short errcd)
2618 void some_isr () interrupt 2 using 1
2639 In the above example the parameter
2647 would be assigned to the overlayable segment (if the #pragma NOOVERLAY
2648 was not present) , this could cause unpredictable runtime behavior.
2649 The pragma NOOVERLAY ensures that the parameters and local variables for
2650 the function are NOT overlayed.
2656 A special keyword may be associated with a function declaring it as '
2661 SDCC will generate code to disable all interrupts upon entry to a critical
2662 function and enable them back before returning .
2663 Note that nesting critical functions may cause unpredictable results.
2684 The critical attribute maybe used with other attributes like
2692 Data items can be assigned an absolute address with the
2696 keyword, in addition to a storage class.
2705 xdata at 0x8000 unsigned char PORTA_8255 ;
2708 In the above example the
2712 will be allocated to the location 0x8000 of the external ram.
2716 Note that is this feature is provided to give the programmer access to
2720 devices attached to the controller.
2721 The compiler does not actually reserve any space for variables declared
2722 in this way (they are implemented with an equate in the assembler), thus
2723 it is left to the programmer to make sure there are no overlaps with other
2724 variables that are declared without the absolute address, the assembler
2725 listing file (.lst) and the linker output files (<filename>.rst) and (<filename>.m
2726 ap) are a good places to look for such overlaps.
2729 Absolute address can be specified for variables in all storage classes.
2742 The above example will allocate the variable at offset 0x02 in the bit-addressab
2744 There is no real advantage to assigning absolute addresses to variables
2745 in this manner , unless you want strict control over all the variables
2749 Interrupt Service Routines
2752 SDCC allows interrupt service routines to be coded in C, with some extended
2758 void timer_isr (void) interrupt 2 using 1
2768 The number following the 'interrupt' keyword is the interrupt number this
2769 routine will service.
2770 The compiler will insert a call to this routine in the interrupt vector
2771 table for the interrupt number specified.
2772 The 'using' keyword is used to tell the compiler to use the specified register
2773 bank (8051 specific) when generating code for this function.
2774 Note that when some function is called from an interrupt service routine
2775 it should be preceded by a #pragma NOOVERLAY (if it is not reentrant) .
2776 A special note here, int (16 bit) and long (32 bit) integer division, multiplic
2777 ation & modulus operations are implemented using external support routines
2778 developed in ANSI-C, if an interrupt service routine needs to do any of
2779 these operations then the support routines (as mentioned in a following
2780 section) will have to recompiled using the --stack-auto option and the
2781 source file will need to be compiled using the --int-long-rent compiler
2785 If you have multiple source files in your project, interrupt service routines
2786 can be present in any of them, but a prototype of the isr MUST be present
2787 in the file that contains the function
2794 Interrupt Numbers and the corresponding address & descriptions for the Standard
2795 8051 are listed below.
2796 SDCC will automatically adjust the interrupt vector table to the maximum
2797 interrupt number specified.
2801 \begin_inset Tabular
2802 <lyxtabular version="2" rows="6" columns="3">
2803 <features rotate="false" islongtable="false" endhead="0" endfirsthead="0" endfoot="0" endlastfoot="0">
2804 <column alignment="center" valignment="top" leftline="true" rightline="false" width="" special="">
2805 <column alignment="center" valignment="top" leftline="true" rightline="false" width="" special="">
2806 <column alignment="center" valignment="top" leftline="true" rightline="true" width="" special="">
2807 <row topline="true" bottomline="true" newpage="false">
2808 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2816 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2824 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2833 <row topline="true" bottomline="false" newpage="false">
2834 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2842 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2850 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2859 <row topline="true" bottomline="false" newpage="false">
2860 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2868 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2876 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2885 <row topline="true" bottomline="false" newpage="false">
2886 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2894 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2902 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2911 <row topline="true" bottomline="false" newpage="false">
2912 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2920 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2928 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2937 <row topline="true" bottomline="true" newpage="false">
2938 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2946 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2954 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2970 If the interrupt service routine is defined without a register bank or with
2971 register bank 0 (using 0), the compiler will save the registers used by
2972 itself on the stack (upon entry and restore them at exit), however if such
2973 an interrupt service routine calls another function then the entire register
2974 bank will be saved on the stack.
2975 This scheme may be advantageous for small interrupt service routines which
2976 have low register usage.
2979 If the interrupt service routine is defined to be using a specific register
2981 \begin_inset Quotes eld
2985 \begin_inset Quotes erd
2989 \begin_inset Quotes erd
2993 \begin_inset Quotes erd
2997 \begin_inset Quotes eld
3001 \begin_inset Quotes erd
3004 are save and restored, if such an interrupt service routine calls another
3005 function (using another register bank) then the entire register bank of
3006 the called function will be saved on the stack.
3007 This scheme is recommended for larger interrupt service routines.
3010 Calling other functions from an interrupt service routine is not recommended
3011 avoid it if possible.
3017 The compiler inserts a jump to the C routine
3019 _sdcc__external__startup()
3021 at the start of the CODE area.
3022 This routine can be found in the file
3024 SDCCDIR/sdcc51lib/_startup.c
3026 , by default this routine returns 0, if this routine returns a non-zero
3027 value , the static & global variable initialization will be skipped and
3028 the function main will be invoked, other wise static & global variables
3029 will be initialized before the function main is invoked.
3032 _sdcc__external__startup()
3034 routine to your program to override the default if you needed to setup
3035 hardware or perform some other critical operation prior to static & global
3036 variable initialization.
3039 Inline Assembler Code
3042 SDCC allows the use of in-line assembler with a few restriction as regards
3044 All labels defined within inline assembler code HAS TO BE of the
3048 where nnnn is a number less than 100 (which implies a limit of utmost 100
3049 inline assembler labels
3054 It is strongly recommended that each assembly instruction (including labels)
3055 be placed in a separate line ( as the example shows).
3062 command line option is used, the inline assembler code will be passed through
3063 the peephole optimizer, this might cause some unexpected changes in the
3064 inline assembler code, please go throught the peephole optimizer rules
3065 defined in file 'SDCCpeeph.def' carefully before using this option.
3096 The inline assembler code can contain any valid code understood by the assembler
3097 (this includes any assembler directives and comment lines ) .
3098 The compiler does not do any validation of the code within the
3107 Inline assembler code cannot reference any C-Labels however it can reference
3108 labels defined by the inline assembler.
3128 ; some assembler code
3137 /* some more c code */
3139 clabel: \SpecialChar ~
3140 /* inline assembler cannot reference this label */
3146 $0003: ;label (can be reference by inline assembler only)
3156 In other words inline assembly code can access labels defined in inline
3158 The same goes the other way, ie.
3159 labels defines in inline assembly CANNOT be accessed by C statements.
3162 int(16 bit) and long (32 bit ) Support
3165 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
3166 multiplication and modulus operations are implemented by support routines.
3167 These support routines are all developed in ANSI-C to facilitate porting
3169 The following files contain the described routine, all of them can be found
3170 in the directory SDCCDIR/sdcc51lib
3175 _mulsint.c - signed 16 bit multiplication (calls _muluint)
3180 _muluint.c - unsigned 16 bit multiplication
3185 _divsint.c - signed 16 bit division (calls _divuint)
3190 _divuint.c - unsigned 16 bit division.
3195 _modsint.c - signed 16 bit modulus (call _moduint)
3200 _moduint.c - unsigned 16 bit modulus.
3205 _mulslong.c - signed 32 bit multiplication (calls _mululong)
3210 _mululong.c - unsigned32 bit multiplication.
3215 _divslong.c - signed 32 division (calls _divulong)
3220 _divulong.c - unsigned 32 division.
3225 _modslong.c - signed 32 bit modulus (calls _modulong).
3230 _modulong.c - unsigned 32 bit modulus.
3233 All these routines are compiled as non-reentrant and small model.
3234 Since they are compiled as non-reentrant, interrupt service routines should
3235 not do any of the above operations, if this unavoidable then the above
3236 routines will need to ne compiled with the --stack-auto option, after which
3237 the source program will have to be compiled with --int-long-rent option.
3240 Floating Point Support
3243 SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
3244 point support routines are derived from gcc's floatlib.c and consists of
3245 the following routines.
3251 _fsadd.c - add floating point numbers.
3256 _fssub.c - subtract floating point numbers
3261 _fsdiv.c - divide floating point numbers
3266 _fsmul.c - multiply floating point numbers
3271 _fs2uchar.c - convert floating point to unsigned char
3276 _fs2char.c - convert floating point to signed char.
3281 _fs2uint.c - convert floating point to unsigned int.
3286 _fs2int.c - convert floating point to signed int.
3291 _fs2ulong.c - convert floating point to unsigned long.
3296 _fs2long.c - convert floating point to signed long.
3301 _uchar2fs.c - convert unsigned char to floating point
3306 _char2fs.c - convert char to floating point number
3311 _uint2fs.c - convert unsigned int to floating point
3316 _int2fs.c - convert int to floating point numbers
3321 _ulong2fs.c - convert unsigned long to floating point number
3326 _long2fs.c - convert long to floating point number.
3329 Note if all these routines are used simultaneously the data space might
3331 For serious floating point usage it is strongly recommended that the Large
3332 model be used (in which case the floating point routines mentioned above
3333 will need to recompiled with the --model-Large option)
3339 SDCC allows two memory models for MCS51 code, small and large.
3340 Modules compiled with different memory models should never be combined
3341 together or the results would be unpredictable.
3342 The library routines supplied with the compiler are compiled as both small
3344 The compiled library modules are contained in seperate directories as small
3345 and large so that you can link to either set.
3346 In general the use of the large model is discouraged.
3349 When the large model is used all variables declared without a storage class
3350 will be allocated into the external ram, this includes all parameters and
3351 local variables (for non-reentrant functions).
3352 When the small model is used variables without storage class are allocated
3353 in the internal ram.
3356 Judicious usage of the processor specific storage classes and the 'reentrant'
3357 function type will yield much more efficient code, than using the large-model.
3358 Several optimizations are disabled when the program is compiled using the
3359 large model, it is therefore strongly recommdended that the small model
3360 be used unless absolutely required.
3363 Flat 24 bit Addressing Model
3366 This option generates code for the 24 bit contiguous addressing mode of
3367 the Dallas DS80C390 part.
3368 In this mode, up to four meg of external RAM or code space can be directly
3370 See the data sheets at www.dalsemi.com for further information on this part.
3373 In older versions of the compiler, this option was used with the MCS51 code
3374 generator (-mmcs51).
3375 Now, however, the '390 has it's own code generator, selected by the -mds390
3377 This code generator currently supports only the flat24 model, but the --model-f
3378 lat24 switch is still required, in case later versions of the code generator
3379 support other models (such as the paged mode of the '390).
3380 The combination of -mmcs51 and --model-flat24 is now depracated.
3383 Note that the compiler does not generate any code to place the processor
3384 into24 bitmode (it defaults to 8051 compatible mode).
3385 Boot loader or similar code must ensure that the processor is in 24 bit
3386 contiguous addressing mode before calling the SDCC startup code.
3389 Like the --model-large option, variables will by default be placed into
3394 Segments may be placed anywhere in the 4 meg address space using the usual
3396 Note that if any segments are located above 64K, the -r flag must be passed
3397 to the linker to generate the proper segment relocations, and the Intel
3398 HEX output format must be used.
3399 The -r flag can be passed to the linker by using the option -Wl-r on the
3403 Defines Created by the Compiler
3406 The compiler creates the following #defines .
3409 SDCC - this Symbol is always defined.
3412 SDCC_STACK_AUTO - this symbol is defined when --stack-auto option is used.
3415 SDCC_MODEL_SMALL - when small model is used.
3418 SDCC_MODEL_LARGE - when --model-large is used.
3421 SDCC_USE_XSTACK - when --xstack option is used.
3430 SDCC performs a a host of standard optimizations in addition to some MCU
3431 specific optimizations.
3433 \layout Subsubsection
3435 Sub-expression Elimination
3442 common subexpression elimination.
3463 will be translated to
3475 Some subexpressions are not as obvious as the above example.
3488 In this case the address arithmetic
3492 will be computed only once; the equivalent code in C would be.
3504 The compiler will try to keep these temporary variables in registers.
3505 \layout Subsubsection
3507 Dead-Code Elimination
3525 i = 1; \SpecialChar ~
3532 global = 1; /* dead store */
3544 global = 3; /* unreachable */
3554 int global; void f ()
3561 global = 2; \SpecialChar ~
3569 \layout Subsubsection
3630 Note: the dead stores created by this copy propagation will be eliminated
3631 by dead-code elimination .
3632 \layout Subsubsection
3637 Two types of loop optimizations are done by SDCC loop invariant lifting
3638 and strength reduction of loop induction variables.In addition to the strength
3639 reduction the optimizer marks the induction variables and the register
3640 allocator tries to keep the induction variables in registers for the duration
3642 Because of this preference of the register allocator , loop induction optimizat
3643 ion causes an increase in register pressure, which may cause unwanted spilling
3644 of other temporary variables into the stack / data space .
3645 The compiler will generate a warning message when it is forced to allocate
3646 extra space either on the stack or data space.
3647 If this extra space allocation is undesirable then induction optimization
3648 can be eliminated either for the entire source file ( with --noinduction
3649 option) or for a given function only (#pragma NOINDUCTION).
3662 for (i = 0 ; i < 100 ; i ++)
3677 for ( i = 0; i < 100; i++ ) f += itemp;
3680 As mentioned previously some loop invariants are not as apparent, all static
3681 address computations are also moved out of the loop.
3686 Strength Reduction :
3689 This optimization substitutes an expression by a cheaper expression.
3697 for (i=0;i < 100; i++) ar[i*5] = i*3;
3709 for (i=0;i< 100;i++) {
3714 ar[itemp1] = itemp2;
3729 The more expensive multiplication is changed to a less expensive addition.
3730 \layout Subsubsection
3735 This optimization is done to reduce the overhead of checking loop boundaries
3736 for every iteration.
3737 Some simple loops can be reversed and implemented using a
3738 \begin_inset Quotes eld
3741 decrement and jump if not zero
3742 \begin_inset Quotes erd
3746 SDCC checks for the following criterion to determine if a loop is reversible
3747 (note: more sophisticated compiers use data-dependency analysis to make
3748 this determination, SDCC uses a more simple minded analysis).
3751 The 'for' loop is of the form
3754 \begin_inset Quotes eld
3757 for ( <symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
3768 \begin_inset Quotes erd
3774 The <for body> does not contain
3775 \begin_inset Quotes eld
3779 \begin_inset Quotes erd
3783 \begin_inset Quotes erd
3789 All goto's are contained within the loop.
3792 No function calls within the loop.
3795 The loop control variable <sym> is not assigned any value within the loop
3798 The loop control variable does NOT participate in any arithmetic operation
3802 There are NO switch statements in the loop.
3805 Note djnz instruction can be used for 8-bit values ONLY, therefore it is
3806 advantageous to declare loop control symbols as either 'char' or 'short',
3807 ofcourse this may not be possible on all situations.
3808 \layout Subsubsection
3810 Algebraic Simplifications
3813 SDCC does numerous algebraic simplifications, the following is a small sub-set
3814 of these optimizations.
3825 i = j + 0 ; /* changed to */ i = j;
3827 i /= 2; /* changed to */ i >>= 1;
3829 i = j - j ; /* changed to */ i = 0;
3831 i = j / 1 ; /* changed to */ i = j;
3834 Note the subexpressions given above are generally introduced by macro expansions
3835 or as a result of copy/constant propagation.
3836 \layout Subsubsection
3841 SDCC changes switch statements to jump tables when the following conditions
3846 The case labels are in numerical sequence , the labels need not be in order,
3847 and the starting number need not be one or zero.
3855 switch(i) {\SpecialChar ~
3959 Both the above switch statements will be implemented using a jump-table.
3962 The number of case labels is at least three, since it takes two conditional
3963 statements to handle the boundary conditions.
3966 The number of case labels is less than 84, since each label takes 3 bytes
3967 and a jump-table can be utmost 256 bytes long.
3971 Switch statements which have gaps in the numeric sequence or those that
3972 have more that 84 case labels can be split into more than one switch statement
3973 for efficient code generation.
4010 If the above switch statement is broken down into two switch statements
4051 then both the switch statements will be implemented using jump-tables whereas
4052 the unmodified switch statement will not be .
4053 \layout Subsubsection
4055 Bit-shifting Operations.
4058 Bit shifting is one of the most frequently used operation in embedded programmin
4060 SDCC tries to implement bit-shift operations in the most efficient way
4082 generates the following code.
4096 In general SDCC will never setup a loop if the shift count is known.
4128 Note that SDCC stores numbers in
4134 \layout Subsubsection
4139 A special case of the bit-shift operation is bit rotation, SDCC recognizes
4140 the following expression to be a left bit-rotation.
4150 i = ( ( i << 1) | ( i >> 7));
4155 will generate the following code.
4167 SDCC uses pattern matching on the parse tree to determine this operation
4168 .Variations of this case will also be recognized as bit-rotation i.e
4170 i = ((i >> 7) | (i << 1));
4172 /* left-bit rotation */
4173 \layout Subsubsection
4178 It is frequently required to obtain the highest order bit of an integral
4179 type (int,long,short or char types).
4180 SDCC recognizes the following expression to yield the highest order bit
4181 and generates optimized code for it.
4203 hob = (gint >> 15) & 1;
4214 Will generate the following code.
4252 000A E5*01\SpecialChar ~
4280 000C 33\SpecialChar ~
4311 000D E4\SpecialChar ~
4342 000E 13\SpecialChar ~
4373 000F F5*02\SpecialChar ~
4400 Variations of this case however will NOT be recognized .
4401 It is a standard C expression , so I heartily recommend this be the only
4402 way to get the highest order bit, (it is portable).
4403 Of course it will be recognized even if it is embedded in other expressions.
4413 xyz = gint + ((gint >> 15) & 1);
4416 will still be recognized.
4417 \layout Subsubsection
4422 The compiler uses a rule based , pattern matching and re-writing mechanism
4423 for peep-hole optimization .
4428 a peep-hole optimizer by Christopher W.
4429 Fraser (cwfraser@microsoft.com).
4430 A default set of rules are compiled into the compiler, additional rules
4431 may be added with the --peep-file <filename> option.
4432 The rule language is best illustrated with examples.
4441 mov a,%1 } by { mov %1,a }
4444 The above rule will the following assembly sequence
4462 Note: All occurrences of a '%n' ( pattern variable ) must denote the same
4464 With the above rule, the assembly sequence
4474 will remain unmodified.
4475 Other special case optimizations may be added by the user (via --peep-file
4477 some variants of the 8051 MCU allow only 'AJMP' and 'ACALL' , the following
4478 two rules will change all 'LJMP' & 'LCALL' to 'AJMP' & 'ACALL'.
4483 replace { lcall %1 } by { acall %1 }
4485 replace { ljmp %1 } by { ajmp %1 }
4488 The inline-assembler' code is also passed through the peep hole optimizer,
4489 thus the peephole optimizer can also be used as an assembly level macro
4491 The rules themselves are MCU dependent whereas the rule language infra-structur
4492 e is MCU independent.
4493 Peephole optimization rules for other MCU can be easily programmed using
4497 The syntax for a rule is as follows ,
4502 rule := replace [ restart ] '{' <assembly sequence> '
4540 <assembly sequence> '
4558 '}' [if <functionName> ] '
4562 <assembly sequence> := assembly instruction (each instruction including
4563 labels must be on a separate line).\SpecialChar ~
4568 The optimizer will apply to the rules one by one from the top in the sequence
4569 of their appearance, it will terminate when all rules are exhausted.
4574 ' option is specified, then the optimizer will start matching the rules
4575 again from the top, this option for a rule is expensive (performance),
4576 it is intended to be used in situations where a transformation will trigger
4577 the same rule again.
4578 A good example of this the following rule.
4594 Note that the replace pattern cannot be a blank, but can be a comment line.
4599 ' option only the inner most 'pop' 'push' pair would be eliminated.
4630 ' option the rule will be applied again to the resulting code and the all
4635 pairs will be eliminated to yield
4645 A conditional function can be attached to a rule.
4646 Attaching rules are somewhat more involved, let me illustrate this with
4666 %2:} if labelInRange
4669 The optimizer does a look-up of a function name table defined in function
4682 ', if it finds a corresponding entry the function is called.
4683 Note there can be no parameters specified for these functions, in this
4688 ' is crucial, since the function
4692 expects to find the label in that particular variable (the hash table containin
4693 g the variable bindings is passed as a parameter).
4694 If you want to code more such functions , take a close look at the function
4699 and the calling mechanism in source file
4704 I know this whole thing is a little kludgey , may be some day we will have
4706 If you are looking at this file, you will also see the default rules that
4707 are compiled into the compiler, you can your own rules in the default set
4708 there if you get tired of specifying the
4718 SDCC supports the following
4723 This directives are applicable only at a function level.
4730 - this will save all the current options .
4737 - will restore the saved options from the last save.
4738 Note that SAVES & RESTOREs cannot be nested.
4739 SDCC uses the same buffer to save the options each time a SAVE is called.
4746 - will stop global subexpression elimination.
4753 - will stop loop induction optimizations .
4760 - will not generate code for boundary value checking , when switch statements
4761 are turned into jump-tables.
4768 - the compiler will not overlay the parameters and local variables of a
4776 - Will not do loop reversal optimization
4781 EXCLUDE NONE | {acc[,b[,dpl[,dph]]]
4783 - The exclude pragma disables generation of pair of push/pop instruction
4784 in ISR function (using interrupt keyword).
4785 The directive should be placed immediately before the ISR function definition
4786 and it affects ALL ISR functions following it.
4787 To enable the normal register saving for ISR functions use
4788 \begin_inset Quotes eld
4791 #pragma EXCLUDE none
4792 \begin_inset Quotes erd
4800 CALLEE-SAVES function1[,function2[,function3...]]
4802 - The compiler by default uses a caller saves convention for register saving
4803 across function calls, however this can cause unneccessary register pushing
4804 & popping when calling small functions from larger functions.
4805 This option can be used to switch the register saving convention for the
4806 function names specified.
4807 The compiler will not save registers when calling these functions, extra
4808 code will be generated at the entry & exit for these functions to save
4809 & restore the registers used by these functions, this can SUBSTANTIALLY
4810 reduce code & improve run time performance of the generated code.
4811 In future the compiler (with interprocedural analysis) will be able to
4812 determine the appropriate scheme to use for each function call.
4813 If --callee-saves command line option is used, the function names specified
4814 in #pragma CALLEE-SAVES is appended to the list of functions specified
4818 The pragma's are intended to be used to turn-off certain optimizations which
4819 might cause the compiler to generate extra stack / data space to store
4820 compiler generated temporary variables.
4821 This usually happens in large functions.
4822 Pragma directives should be used as shown in the following example, they
4823 are used to control options & optimizations for a given function; pragmas
4832 a function, placing pragma's inside a function body could have unpredictable
4843 #pragma SAVE \SpecialChar ~
4844 /* save the current settings */
4846 #pragma NOGCSE /* turnoff global subexpression elimination */
4848 #pragma NOINDUCTION /* turn off induction optimizations */
4870 #pragma RESTORE /* turn the optimizations back on */
4873 The compiler will generate a warning message when extra space is allocated.
4874 It is strongly recommended that the SAVE and RESTORE pragma's be used when
4875 changing options for a function.
4881 The following library routines are provided for your convenience.
4890 - Contains the following functions printf & sprintf these routines are developed
4893 Martijn van Balen <balen@natlab.research.philips.com>.
4899 %[flags][width][b|B|l|L]type
4914 flags: -\SpecialChar ~
4921 left justify output in specified field width
4946 prefix output with +/- sign if output is signed type
4967 prefix output with a blank if it's a signed positive value
4978 width:\SpecialChar ~
4987 specifies minimum number of characters outputted for numbers
5042 - For numbers, spaces are added on the left when needed.
5072 If width starts with a zero character, zeroes and used
5129 - For strings, spaces are are added on the left or right (when
5158 flag '-' is used) when needed.
5208 byte argument (used by d, u, o, x, X)
5230 long argument (used by d, u, o, x, X)
5274 unsigned decimal number
5299 unsigned octal number
5324 unsigned hexadecimal number (0-9, a-f)
5349 unsigned hexadecimal number (0-9, A-F)
5399 string (generic pointer)
5424 generic pointer (I:data/idata, C:code, X:xdata, P:paged)
5449 float (still to be implemented)
5452 Also contains a very simple version of printf (
5457 This simplified version of printf supports only the following formats.
5463 format\SpecialChar ~
5468 output\SpecialChar ~
5492 decimal \SpecialChar ~
5507 decimal\SpecialChar ~
5524 decimal\SpecialChar ~
5541 hexadecimal\SpecialChar ~
5554 hexadecimal\SpecialChar ~
5567 hexadecimal\SpecialChar ~
5639 character\SpecialChar ~
5655 character\SpecialChar ~
5667 , --stack-after-data parameter should be used when using this routine, the
5668 routine also takes about 1K of code space .It also expects an external function
5673 to be present (this can be changed).
5674 When using the %s format the string / pointer should be cast to a generic
5682 \begin_inset Quotes eld
5685 my str %s, my int %d
5688 \begin_inset Quotes erd
5691 ,(char _generic *)mystr,myint);
5700 - contains definition for the following macros to be used for variable parameter
5701 list, note that a function can have a variable parameter list if and only
5702 if it is 'reentrant'
5708 va_list, va_start, va_arg, va_end.
5718 - contains defintion for ANSI
5727 Note in this case setjmp & longjmp can be used between functions executing
5728 within the same register bank, if long jmp is executed from a function
5729 that is using a different register bank from the function issuing the setjmp
5730 function, the results may be unpredictable.
5731 The jump buffer requires 3 bytes of data (the stack pointer & a 16 byte
5732 return address), and can be placed in any address space.
5741 - contains the following functions.
5757 - contains the following functions.
5763 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn,
5764 strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.
5774 - contains the following routines.
5780 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
5781 isxdigit, isalnum, isalpha.
5791 - The malloc routines are developed by Dmitry S.
5792 Obukhov (dso@usa.net).
5793 These routines will allocate memory from the external ram.
5794 Here is a description on how to use them (as described by the author).
5810 #define DYNAMIC_MEMORY_SIZE 0x2000
5831 unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
5841 unsigned char xdata * current_buffer;
5902 init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
5916 //Now it's possible to use malloc.
5946 current_buffer = malloc(0x100);
5962 - Serial IO routines are also developed by Dmitry S.
5963 Obukhov (dso@usa.net).
5964 These routines are interrupt driven with a 256 byte circular buffer, they
5965 also expect external ram to be present.
5966 Please see documentation in file SDCCDIR/sdcc51lib/serial.c .
5967 Note the header file
5968 \begin_inset Quotes eld
5972 \begin_inset Quotes erd
5975 MUST be included in the file containing the 'main' function.
5984 - Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.co
5985 m> these routines are more compact and faster.
5986 Please see documentation in file SDCCDIR/sdcc51lib/ser.c
5995 - Another alternate set of serial routines provided by Josef Wolf <jw@raven.inka.d
5996 e> , these routines do not use the external ram.
6005 - contains register definitions for a standard 8051
6014 - contains register definitions for 80C552.
6023 - contains min, max and other floating point related stuff.
6026 All library routines are compiled as --model-small , they are all non-reentrant,
6027 if you plan to use the large model or want to make these routines reentrant,
6028 then they will have to be recompiled with the appropriate compiler option.
6031 Have not had time to do the more involved routines like printf, will get
6035 Interfacing with Assembly Routines
6038 Global Registers used for Parameter Passing
6041 By default the compiler uses the global registers
6042 \begin_inset Quotes eld
6046 \begin_inset Quotes erd
6049 to pass the first parameter to a routine, the second parameter onwards
6050 is either allocated on the stack (for reentrant routines or --stack-auto
6051 is used) or in the internal / external ram (depending on the memory model).
6053 \layout Subsubsection
6055 Assembler Routine(non-reentrant)
6058 In the following example the function
6062 calls an assembler routine
6066 , which takes two parameters.
6071 extern int asm_func( unsigned short, unsigned short);
6079 int c_func (unsigned short i, unsigned short j)
6090 return asm_func(i,j);
6105 return c_func(10,9);
6110 The corresponding assembler function is:-
6122 .globl _asm_func_PARM_2
6142 _asm_func_PARM_2:\SpecialChar ~
6228 Note here that the return values are placed in 'dpl' - One byte return value,
6229 'dpl' LSB & 'dph' MSB for two byte values.
6230 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
6231 b' & 'acc' for four byte values.
6234 The parameter naming convention is
6236 _<function_name>_PARM_<n>,
6238 where n is the parameter number starting from 1, and counting from the
6240 The first parameter is passed in
6241 \begin_inset Quotes eld
6245 \begin_inset Quotes erd
6248 for One bye parameter,
6249 \begin_inset Quotes eld
6253 \begin_inset Quotes erd
6257 \begin_inset Quotes eld
6261 \begin_inset Quotes erd
6265 \begin_inset Quotes eld
6269 \begin_inset Quotes erd
6276 varaible name for the second parameter will be _<function_name>_PARM_2.
6279 Assemble the assembler routine with the following command.
6282 asx8051 -losg asmfunc.asm
6285 Then compile and link the assembler routine to the C source file with the
6289 sdcc cfunc.c asmfunc.rel
6290 \layout Subsubsection
6292 Assembler Routine(reentrant)
6295 In this case the second parameter onwards will be passed on the stack ,
6296 the parameters are pushed from right to left i.e.
6297 after the call the left most parameter will be on the top of the stack.
6303 extern int asm_func( unsigned short, unsigned short);
6314 int c_func (unsigned short i, unsigned short j) reentrant
6325 return asm_func(i,j);
6340 return c_func(10,9);
6345 The corresponding assembler routine is.
6522 The compiling and linking procedure remains the same, however note the extra
6523 entry & exit linkage required for the assembler code, _bp is the stack
6524 frame pointer and is used to compute the offset into the stack for parameters
6525 and local variables.
6528 With --noregparms Option
6531 When the source is compiled with --noregparms option , space is allocated
6532 for each of the parameters passed to a routine.
6533 \layout Subsubsection
6535 Assembler Routine Non-reentrant
6538 In the following example the function
6542 calls an assembler routine
6546 , which takes two parameters.
6551 extern int asm_func( unsigned short, unsigned short);
6559 int c_func (unsigned short i, unsigned short j)
6570 return asm_func(i,j);
6585 return c_func(10,9);
6590 The corresponding assembler function is:-
6602 .globl _asm_func_PARM_1
6611 .globl _asm_func_PARM_2
6631 _asm_func_PARM_1:\SpecialChar ~
6643 _asm_func_PARM_2:\SpecialChar ~
6729 Note here that the return values are placed in 'dpl' - One byte return value,
6730 'dpl' LSB & 'dph' MSB for two byte values.
6731 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
6732 b' & 'acc' for four byte values.
6735 The parameter naming convention is
6737 _<function_name>_PARM_<n>,
6739 where n is the parameter number starting from 1, and counting from the
6746 left-most parameter name will be _<function_name>_PARM_1.
6749 Assemble the assembler routine with the following command.
6752 asx8051 -losg asmfunc.asm
6755 Then compile and link the assembler routine to the C source file with the
6759 sdcc cfunc.c asmfunc.rel
6760 \layout Subsubsection
6762 Assembler Routine(reentrant)
6765 In this case the parameters will be passed on the stack , the parameters
6766 are pushed from right to left i.e.
6767 after the call the left most parameter will be on the top of the stack.
6773 extern int asm_func( unsigned short, unsigned short);
6784 int c_func (unsigned short i, unsigned short j) reentrant
6795 return asm_func(i,j);
6810 return c_func(10,9);
6815 The corresponding assembler routine is.
7001 The compiling and linking procedure remains the same, however note the extra
7002 entry & exit linkage required for the assembler code, _bp is the stack
7003 frame pointer and is used to compute the offset into the stack for parameters
7004 and local variables.
7010 The external stack is located at the start of the external ram segment ,
7011 and is 256 bytes in size.
7012 When --xstack option is used to compile the program, the parameters and
7013 local variables of all reentrant functions are allocated in this area.
7014 This option is provided for programs with large stack space requirements.
7015 When used with the --stack-auto option, all parameters and local variables
7016 are allocated on the external stack (note support libraries will need to
7017 be recompiled with the same options).
7020 The compiler outputs the higher order address byte of the external ram segment
7021 into PORT P2, therefore when using the External Stack option, this port
7022 MAY NOT be used by the application program.
7028 Deviations from the compliancy.
7031 functions are not always reentrant.
7034 structures cannot be assigned values directly, cannot be passed as function
7035 parameters or assigned to each other and cannot be a return value from
7060 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
7070 struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
7080 return rets;/* is invalid in SDCC although allowed in ANSI */
7085 'long long' (64 bit integers) not supported.
7088 'double' precision floating point not supported.
7091 integral promotions are suppressed.
7092 What does this mean ? The compiler will not implicitly promote an integer
7093 expression to a higher order integer, exception is an assignment or parameter
7109 Old K&R style function declarations are NOT allowed.
7114 foo( i,j) /* this old style of function declarations */
7116 int i,j; /* are valid in ANSI ..
7117 not valid in SDCC */
7127 functions declared as pointers must be dereferenced during the call.
7146 /* has to be called like this */
7150 (*foo)();/* ansi standard allows calls to be made like 'foo()' */
7153 Cyclomatic Complexity
7156 Cyclomatic complexity of a function is defined as the number of independent
7157 paths the program can take during execution of the function.
7158 This is an important number since it defines the number test cases you
7159 have to generate to validate the function .
7160 The accepted industry standard for complexity number is 10, if the cyclomatic
7161 complexity reported by SDCC exceeds 10 you should think about simplification
7162 of the function logic.
7165 Note that the complexity level is not related to the number of lines of
7167 Large functions can have low complexity, and small functions can have large
7169 SDCC uses the following formula to compute the complexity.
7174 complexity = (number of edges in control flow graph) -
7183 (number of nodes in control flow graph) + 2;
7186 Having said that the industry standard is 10, you should be aware that in
7187 some cases it may unavoidable to have a complexity level of less than 10.
7188 For example if you have switch statement with more than 10 case labels,
7189 each case label adds one to the complexity level.
7190 The complexity level is by no means an absolute measure of the algorithmic
7191 complexity of the function, it does however provide a good starting point
7192 for which functions you might look at for further optimization.
7198 Here are a few guide-lines that will help the compiler generate more efficient
7199 code, some of the tips are specific to this compiler others are generally
7200 good programming practice.
7203 Use the smallest data type to represent your data-value.
7204 If it is known in advance that the value is going to be less than 256 then
7205 use a 'short' or 'char' instead of an 'int'.
7208 Use unsigned when it is known in advance that the value is not going to
7210 This helps especially if you are doing division or multiplication.
7213 NEVER jump into a LOOP.
7216 Declare the variables to be local whenever possible, especially loop control
7217 variables (induction).
7220 Since the compiler does not do implicit integral promotion, the programmer
7221 should do an explicit cast when integral promotion is required.
7224 Reducing the size of division , multiplication & modulus operations can
7225 reduce code size substantially.
7226 Take the following code for example.
7232 foobar( unsigned int p1, unsigned char ch)
7240 unsigned char ch1 = p1 % ch ;
7255 For the modulus operation the variable ch will be promoted to unsigned int
7256 first then the modulus operation will be performed (this will lead to a
7257 call to a support routine).
7258 If the code is changed to
7263 foobar( unsigned int p1, unsigned char ch)
7271 unsigned char ch1 = (unsigned char)p1 % ch ;
7286 It would substantially reduce the code generated (future versions of the
7287 compiler will be smart enough to detect such optimization oppurtunities).
7293 Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
7296 The 8051 family of micro controller have a minimum of 128 bytes of internal
7297 memory which is structured as follows
7300 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
7304 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
7307 - Bytes 30-7F - 60 bytes for general purpose use.
7310 Normally the SDCC compiler will only utilise the first bank of registers,
7311 but it is possible to specify that other banks of registers should be used
7312 in interrupt routines.
7313 By default, the compiler will place the stack after the last bank of used
7315 if the first 2 banks of registers are used, it will position the base of
7316 the internal stack at address 16 (0X10).
7317 This implies that as the stack grows, it will use up the remaining register
7318 banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
7319 general purpose use.
7322 By default, the compiler uses the 60 general purpose bytes to hold "near
7324 The compiler/optimiser may also declare some Local Variables in this area
7329 If any of the 128 bit variables are used, or near data is being used then
7330 care needs to be taken to ensure that the stack does not grow so much that
7331 it starts to over write either your bit variables or "near data".
7332 There is no runtime checking to prevent this from happening.
7335 The amount of stack being used is affected by the use of the "internal stack"
7336 to save registers before a subroutine call is made, - --stack-auto will
7337 declare parameters and local variables on the stack - the number of nested
7341 If you detect that the stack is over writing you data, then the following
7343 --xstack will cause an external stack to be used for saving registers and
7344 (if --stack-auto is being used) storing parameters and local variables.
7345 However this will produce more and code which will be slower to execute.
7349 --stack-loc will allow you specify the start of the stack, i.e.
7350 you could start it after any data in the general purpose area.
7351 However this may waste the memory not used by the register banks and if
7352 the size of the "near data" increases, it may creep into the bottom of
7356 --stack-after-data, similar to the --stack-loc, but it automatically places
7357 the stack after the end of the "near data".
7358 Again this could waste any spare register space.
7361 --data-loc allows you to specify the start address of the near data.
7362 This could be used to move the "near data" further away from the stack
7363 giving it more room to grow.
7364 This will only work if no bit variables are being used and the stack can
7365 grow to use the bit variable space.
7371 If you find that the stack is over writing your bit variables or "near data"
7372 then the approach which best utilised the internal memory is to position
7373 the "near data" after the last bank of used registers or, if you use bit
7374 variables, after the last bit variable by using the --data-loc, e.g.
7375 if two register banks are being used and no data variables, --data-loc
7376 16, and - use the --stack-after-data option.
7379 If bit variables are being used, another method would be to try and squeeze
7380 the data area in the unused register banks if it will fit, and start the
7381 stack after the last bit variable.
7384 Retargetting for other MCUs.
7387 The issues for retargetting the compiler are far too numerous to be covered
7389 What follows is a brief description of each of the seven phases of the
7390 compiler and its MCU dependency.
7393 Parsing the source and building the annotated parse tree.
7394 This phase is largely MCU independent (except for the language extensions).
7395 Syntax & semantic checks are also done in this phase , along with some
7396 initial optimizations like back patching labels and the pattern matching
7397 optimizations like bit-rotation etc.
7400 The second phase involves generating an intermediate code which can be easy
7401 manipulated during the later phases.
7402 This phase is entirely MCU independent.
7403 The intermediate code generation assumes the target machine has unlimited
7404 number of registers, and designates them with the name iTemp.
7405 The compiler can be made to dump a human readable form of the code generated
7406 by using the --dumpraw option.
7409 This phase does the bulk of the standard optimizations and is also MCU independe
7411 This phase can be broken down into several sub-phases.
7415 Break down intermediate code (iCode) into basic blocks.
7418 Do control flow & data flow analysis on the basic blocks.
7421 Do local common subexpression elimination, then global subexpression elimination
7424 dead code elimination
7430 if loop optimizations caused any changes then do 'global subexpression eliminati
7431 on' and 'dead code elimination' again.
7435 This phase determines the live-ranges; by live range I mean those iTemp
7436 variables defined by the compiler that still survive after all the optimization
7438 Live range analysis is essential for register allocation, since these computati
7439 on determines which of these iTemps will be assigned to registers, and for
7443 Phase five is register allocation.
7444 There are two parts to this process .
7448 The first part I call 'register packing' (for lack of a better term) .
7449 In this case several MCU specific expression folding is done to reduce
7453 The second part is more MCU independent and deals with allocating registers
7454 to the remaining live ranges.
7455 A lot of MCU specific code does creep into this phase because of the limited
7456 number of index registers available in the 8051.
7460 The Code generation phase is (unhappily), entirely MCU dependent and very
7461 little (if any at all) of this code can be reused for other MCU.
7462 However the scheme for allocating a homogenized assembler operand for each
7463 iCode operand may be reused.
7466 As mentioned in the optimization section the peep-hole optimizer is rule
7467 based system, which can reprogrammed for other MCUs.
7470 SDCDB - Source Level Debugger
7473 SDCC is distributed with a source level debugger.
7474 The debugger uses a command line interface, the command repertoire of the
7475 debugger has been kept as close to gdb ( the GNU debugger) as possible.
7476 The configuration and build process is part of the standard compiler installati
7477 on, which also builds and installs the debugger in the target directory
7478 specified during configuration.
7479 The debugger allows you debug BOTH at the C source and at the ASM source
7483 Compiling for Debugging
7490 option must be specified for all files for which debug information is to
7492 The complier generates a
7496 file for each of these files.
7497 The linker updates the
7501 file with the address information.
7502 This .cdb is used by the debugger .
7505 How the Debugger Works
7512 option is specified the compiler generates extra symbol information some
7513 of which are put into the the assembler source and some are put into the
7514 .cdb file, the linker updates the .cdb file with the address information
7516 The debugger reads the symbolic information generated by the compiler &
7517 the address information generated by the linker.
7518 It uses the SIMULATOR (Daniel's S51) to execute the program, the program
7519 execution is controlled by the debugger.
7520 When a command is issued for the debugger, it translates it into appropriate
7521 commands for the simulator .
7524 Starting the Debugger
7527 The debugger can be started using the following command line.
7528 (Assume the file you are debugging has
7537 The debugger will look for the following files.
7540 foo.c - the source file.
7543 foo.cdb - the debugger symbol information file.
7546 foo.ihx - the intel hex format object file.
7549 Command Line Options.
7552 --directory=<source file directory> this option can used to specify the
7553 directory search list.
7554 The debugger will look into the directory list specified for source , cdb
7556 The items in the directory list must be separated by ':' , e.g.
7557 if the source files can be in the directories /home/src1 and /home/src2,
7558 the --directory option should be --directory=/home/src1:/home/src2 .
7559 Note there can be no spaces in the option.
7563 -cd <directory> - change to the <directory>.
7566 -fullname - used by GUI front ends.
7569 -cpu <cpu-type> - this argument is passed to the simulator please see the
7570 simulator docs for details.
7573 -X <Clock frequency > this options is passed to the simulator please see
7574 simulator docs for details.
7577 -s <serial port file> passed to simulator see simulator docs for details.
7580 -S <serial in,out> passed to simulator see simulator docs for details.
7586 As mention earlier the command interface for the debugger has been deliberately
7587 kept as close the GNU debugger gdb , as possible, this will help int integratio
7588 n with existing graphical user interfaces (like ddd, xxgdb or xemacs) existing
7589 for the GNU debugger.
7590 \layout Subsubsection
7592 break [line | file:line | function | file:function]
7595 Set breakpoint at specified line or function.
7600 sdcdb>break foo.c:100
7604 sdcdb>break foo.c:funcfoo
7605 \layout Subsubsection
7607 clear [line | file:line | function | file:function ]
7610 Clear breakpoint at specified line or function.
7615 sdcdb>clear foo.c:100
7619 sdcdb>clear foo.c:funcfoo
7620 \layout Subsubsection
7625 Continue program being debugged, after breakpoint.
7626 \layout Subsubsection
7631 Execute till the end of the current function.
7632 \layout Subsubsection
7637 Delete breakpoint number 'n'.
7638 If used without any option clear ALL user defined break points.
7639 \layout Subsubsection
7641 info [break | stack | frame | registers ]
7644 info break - list all breakpoints
7647 info stack - show the function call stack.
7650 info frame - show information about the current execution frame.
7653 info registers - show content of all registers.
7654 \layout Subsubsection
7659 Step program until it reaches a different source line.
7660 \layout Subsubsection
7665 Step program, proceeding through subroutine calls.
7666 \layout Subsubsection
7671 Start debugged program.
7672 \layout Subsubsection
7677 Print type information of the variable.
7678 \layout Subsubsection
7683 print value of variable.
7684 \layout Subsubsection
7689 load the given file name.
7690 Note this is an alternate method of loading file for debugging.
7691 \layout Subsubsection
7696 print information about current frame.
7697 \layout Subsubsection
7702 Toggle between C source & assembly source.
7703 \layout Subsubsection
7708 Send the string following '!' to the simulator, the simulator response is
7710 Note the debugger does not interpret the command being sent to the simulator,
7711 so if a command like 'go' is sent the debugger can loose its execution
7712 context and may display incorrect values.
7713 \layout Subsubsection
7720 My name is Bobby Brown"
7723 Interfacing with XEmacs.
7726 Two files are (in emacs lisp) are provided for the interfacing with XEmacs,
7735 These two files can be found in the $(prefix)/bin directory after the installat
7737 These files need to be loaded into XEmacs for the interface to work, this
7738 can be done at XEmacs startup time by inserting the following into your
7743 file (which can be found in your HOME directory)
7745 (load-file sdcdbsrc.el)
7747 [ .xemacs is a lisp file so the () around the command is REQUIRED), the files
7748 can also be loaded dynamically while XEmacs is running, set the environment
7753 to the installation bin directory [$(prefix)/bin], then enter the following
7756 ESC-x load-file sdcdbsrc .
7759 To start the interface enter the following command
7763 , you will prompted to enter the file name to be debugged.
7767 The command line options that are passed to the simulator directly are bound
7768 to default values in the file
7772 the variables are listed below these values maybe changed as required.
7775 sdcdbsrc-cpu-type '51
7778 sdcdbsrc-frequency '11059200
7784 The following is a list of key mapping for the debugger interface.
7792 ;; Current Listing ::
7809 binding\SpecialChar ~
7848 -------\SpecialChar ~
7888 sdcdb-next-from-src\SpecialChar ~
7914 sdcdb-back-from-src\SpecialChar ~
7940 sdcdb-cont-from-src\SpecialChar ~
7950 SDCDB continue command
7966 sdcdb-step-from-src\SpecialChar ~
7992 sdcdb-whatis-c-sexp\SpecialChar ~
8002 SDCDB ptypecommand for data at
8062 sdcdbsrc-delete\SpecialChar ~
8076 SDCDB Delete all breakpoints if no arg
8124 given or delete arg (C-u arg x)
8140 sdcdbsrc-frame\SpecialChar ~
8155 SDCDB Display current frame if no arg,
8203 given or display frame arg
8266 sdcdbsrc-goto-sdcdb\SpecialChar ~
8276 Goto the SDCDB output buffer
8292 sdcdb-print-c-sexp\SpecialChar ~
8303 SDCDB print command for data at
8363 sdcdbsrc-goto-sdcdb\SpecialChar ~
8373 Goto the SDCDB output buffer
8389 sdcdbsrc-mode\SpecialChar ~
8405 Toggles Sdcdbsrc mode (turns it off)
8409 ;; C-c C-f\SpecialChar ~
8417 sdcdb-finish-from-src\SpecialChar ~
8425 SDCDB finish command
8429 ;; C-x SPC\SpecialChar ~
8437 sdcdb-break\SpecialChar ~
8455 Set break for line with point
8457 ;; ESC t\SpecialChar ~
8467 sdcdbsrc-mode\SpecialChar ~
8483 Toggle Sdcdbsrc mode
8485 ;; ESC m\SpecialChar ~
8495 sdcdbsrc-srcmode\SpecialChar ~
8517 The Z80 and gbz80 port
8520 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
8521 The port is incomplete - long support is incomplete (mul, div and mod are
8522 unimplimented), and both float and bitfield support is missing, but apart
8523 from that the code generated is correct.
8526 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
8527 The stack frame is similar to that generated by the IAR Z80 compiler.
8528 IX is used as the base pointer, HL is used as a temporary register, and
8529 BC and DE are available for holding varibles.
8530 IY is currently unusued.
8531 Return values are stored in HL.
8532 One bad side effect of using IX as the base pointer is that a functions
8533 stack frame is limited to 127 bytes - this will be fixed in a later version.
8539 SDCC has grown to be large project, the compiler alone (without the Assembler
8540 Package, Preprocessor) is about 40,000 lines of code (blank stripped).
8541 The open source nature of this project is a key to its continued growth
8543 You gain the benefit and support of many active software developers and
8545 Is SDCC perfect? No, that's why we need your help.
8546 The developers take pride in fixing reported bugs.
8547 You can help by reporting the bugs and helping other SDCC users.
8548 There are lots of ways to contribute, and we encourage you to take part
8549 in making SDCC a great software package.
8555 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd
8556 cc@sdcc.sourceforge.net'.
8557 Bugs will be fixed ASAP.
8558 When reporting a bug, it is very useful to include a small test program
8559 which reproduces the problem.
8560 If you can isolate the problem by looking at the generated assembly code,
8561 this can be very helpful.
8562 Compiling your program with the --dumpall option can sometimes be useful
8563 in locating optimization problems.
8569 Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code generator,
8572 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX & ASLINK.
8575 John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for 8051
8578 Obukhov (dso@usa.net) - malloc & serial i/o routines.
8581 Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware simulator
8583 Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience and support.
8585 Unknown - for the GNU C - preprocessor.
8587 Michael Hope - The Z80 and Z80GB port, 186 development
8589 Kevin Vigor - The DS390 port.
8591 Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
8593 Scott Datallo - PIC port.
8595 (Thanks to all the other volunteer developers who have helped with coding,
8596 testing, web-page creation, distribution sets, etc.
8597 You know who you are :-)
8602 This document initially written by Sandeep Dutta
8605 All product names mentioned herein may be trademarks of their respective
8611 \begin_inset LatexCommand \index{}