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.
551 (no test.ihx, and the linker generates warnings), then the problem is most
552 likely that sdcc cannot find the
556 usr/local/share/sdcc/lib directory
560 (see the Install trouble-shooting section for suggestions).
565 The final test is to ensure sdcc can use the standard header files and libraries.
566 Edit test.c and change it to the following:
578 \begin_inset Quotes eld
582 \begin_inset Quotes erd
592 Compile this by typing:
593 \begin_inset Quotes eld
597 \begin_inset Quotes erd
601 This should generate a test.ihx output file, and it should give no warnings
602 such as not finding the string.h file.
603 If it cannot find the string.h file, then the problem is that sdcc cannot
604 find the /usr/local/share/sdcc/include directory
608 (see the Install trouble-shooting section for suggestions).
611 Install Trouble-shooting
612 \layout Subsubsection
614 SDCC cannot find libraries or header files.
617 The default installation assumes the libraries and header files are located
619 \begin_inset Quotes eld
622 /usr/local/share/sdcc/lib
623 \begin_inset Quotes erd
627 \begin_inset Quotes eld
630 /usr/local/share/sdcc/include
631 \begin_inset Quotes erd
635 An alternative is to specify these locations as compiler options like this:
636 sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include test.c
637 \layout Subsubsection
639 SDCC does not compile correctly.
642 A things to try is starting from scratch by unpacking the .tgz source package
643 again in an empty directory.
644 Confure it again and build like:
648 \begin_inset Quotes eld
651 make 2&>1 | tee make.log
652 \begin_inset Quotes erd
658 After this you can review the make.log file to locate the problem.
659 Or a relevant part of this be attached to an email that could be helpful
660 when requesting help from the mailing list.
661 \layout Subsubsection
664 \begin_inset Quotes eld
668 \begin_inset Quotes erd
675 \begin_inset Quotes eld
679 \begin_inset Quotes erd
682 command is a script that analyzes your system and performs some configuration
683 to ensure the source package compiles on your system.
684 It will take a few minutes to run, and will compile a few tests to determine
685 what compiler features are installed.
686 \layout Subsubsection
689 \begin_inset Quotes eld
693 \begin_inset Quotes erd
699 This runs the GNU make tool, which automatically compiles all the source
700 packages into the final installed binary executables.
701 \layout Subsubsection
704 \begin_inset Quotes eld
708 \begin_inset Quotes erd
714 This will install the compiler, other executables and libraries in to the
715 appropriate system directories.
716 The default is to copy the executables to /usr/local/bin and the libraries
717 and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
720 Additional Information for Windows Users
723 The standard method of installing on a Unix system involves compiling the
725 This is easily done under Unix, but under Windows it can be a more difficult
727 The Cygwin is a large package to download, and the compilation runs considerabl
728 y slower under Windows due to the overhead of the Cygwin tool set.
729 An alternative is to install a pre-compiled Windows binary package.
730 There are various trade-offs between each of these methods.
734 The Cygwin package allows a Windows user to run a Unix command line interface(ba
735 sh shell) and also implements a Unix like file system on top of Windows.
736 Included are many of the famous GNU software development tools which can
737 augment the SDCC compiler.This is great if you have some experience with
738 Unix command line tools and file system conventions, if not you may find
739 it easier to start by installing a binary Windows package.
740 The binary packages work with the Windows file system conventions.
741 \layout Subsubsection
743 Getting started with Cygwin
746 SDCC is typically distributed as a tarred/gzipped file(.tgz).
747 This is a packed file similar to a .zip file.
748 Cygwin includes the tools you will need to unpack the SDCC distribution(tar
750 To unpack it, simply follow the instructions under the Linux/Unix install
752 Before you do this you need to learn how to start a cygwin shell and some
753 of the basic commands used to move files, change directory, run commands
755 The change directory command is
756 \begin_inset Quotes eld
760 \begin_inset Quotes erd
763 , the move command is
764 \begin_inset Quotes eld
768 \begin_inset Quotes erd
772 To print the current working directory, type
773 \begin_inset Quotes eld
777 \begin_inset Quotes erd
781 To make a directory, use
782 \begin_inset Quotes eld
786 \begin_inset Quotes erd
792 There are some basic differences between Unix and Windows file systems you
794 When you type in directory paths, Unix and the Cygwin bash prompt uses
795 forward slashes '/' between directories while Windows traditionally uses
799 So when you work at the Cygwin bash prompt, you will need to use the forward
801 Unix does not have a concept of drive letters, such as
802 \begin_inset Quotes eld
806 \begin_inset Quotes eld
809 , instead all files systems attach and appear as directories.
810 \layout Subsubsection
812 Running SDCC as Native Compiled Executables
815 If you use the pre-compiled binaries, the install directories for the libraries
816 and header files may need to be specified on the sdcc command line like
835 include test.c if you are running outside of a Unix bash shell.
838 If you have successfully installed and compiled SDCC with the Cygwin package,
839 it is possible to compile into native .exe files by using the additional
840 makefiles included for this purpose.
841 For example, with the Borland 32-bit compiler you would run make -f Makefile.bcc.
842 A command line version of the Borland 32-bit compiler can be downloaded
843 from the Inprise web site.
846 SDCC on Other Platforms
851 FreeBSD and other non-GNU Unixes
853 - Make sure the GNU make is installed as the default make tool.
856 SDCC has been ported to run under a variety of operating systems and processors.
857 If you can run GNU GCC/make then chances are good SDCC can be compiled
858 and run on your system.
861 Advanced Install Options
865 \begin_inset Quotes eld
869 \begin_inset Quotes erd
872 command has several options.
873 The most commonly used option is --prefix=<directory name>, where <directory
874 name> is the final location for the sdcc executables and libraries, (default
875 location is /usr/local).
876 The installation process will create the following directory structure
877 under the <directory name> specified.
881 bin/ - binary exectables (add to PATH environment variable)
898 sdcc/include/ - include header files
923 small/ - Object & library files for small model library
938 large/ - Object & library files for large model library
953 ds390/ - Object & library files forDS80C390 library
963 './configure --prefix=/usr/local
964 \begin_inset Quotes erd
970 will configure the compiler to be installed in directory /usr/local/bin.
976 SDCC is not just a compiler, but a collection of tools by various developers.
977 These include linkers, assemblers, simulators and other components.
978 Here is a summary of some of the components.
979 Note that the included simulator and assembler have separate documentation
980 which you can find in the source package in their respective directories.
981 As SDCC grows to include support for other processors, other packages from
982 various developers are included and may have their own sets of documentation.
985 You might want to look at the various executables which are installed in
987 At the time of this writing, we find the following programs:
1001 -The linker for 8051 type processors.
1008 - The assembler for 8051 type processors.
1015 - The C preprocessor.
1022 - The source debugger.
1029 - The ucSim 8051 simulator.
1036 - The Z80 and GameBoy Z80 linkers.
1043 - The Z80 and GameBoy Z80 assemblers.
1050 - A tool to pack Intel hex files.
1053 As development for other processors proceeds, this list will expand to include
1054 executables to support processors like AVR, PIC, etc.
1055 \layout Subsubsection
1057 cpp ( C-Preprocessor)
1060 The preprocessor is extracted into the directory
1064 , it is a modified version of the GNU preprocessor.
1065 The C preprocessor is used to pull in #include sources, process #ifdef
1066 statements, #defines and so on.
1067 \layout Subsubsection
1069 asxxxx & aslink ( The assembler and Linkage Editor)
1072 This is retargettable assembler & linkage editor, it was developed by Alan
1073 Baldwin, John Hartman created the version for 8051, and I (Sandeep) have
1074 some enhancements and bug fixes for it to work properly with the SDCC.
1075 This component is extracted into the directory
1078 \layout Subsubsection
1083 This is the actual compiler, it in turn uses the c-preprocessor and invokes
1084 the assembler and linkage editors.
1085 All files with the prefix
1089 are part of the compiler and are extracted into the the directory
1092 \layout Subsubsection
1097 s51 is a freeware, opensource simulator developed by Daniel Drotos <drdani@mazso
1098 la.iit.uni-miskolc.hu>.
1099 The executable is built as part of the build process, for more information
1100 visit Daniel's website at <http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51/
1102 \layout Subsubsection
1104 SDCDB - Source Level Debugger
1107 SDCDB is the companion source level debugger .
1108 The current version of the debugger uses Daniel's Simulator S51, but can
1109 be easily changed to use other simulators.
1116 \layout Subsubsection
1118 Single Source File Projects
1121 For single source file 8051 projects the process is very simple.
1122 Compile your programs with the following command
1130 The above command will compile ,assemble and link your source file.
1131 Output files are as follows.
1136 sourcefile.asm - Assembler source file created by the compiler
1141 sourcefile.lst - Assembler listing file created by the Assembler
1146 sourcefile.rst - Assembler listing file updated with linkedit information
1147 , created by linkage editor
1152 sourcefile.sym - symbol listing for the sourcefile, created by the assembler.
1157 sourcefile.rel - Object file created by the assembler, input to Linkage editor.
1162 sourcefile.map - The memory map for the load module, created by the Linker.
1167 sourcefile.ihx - The load module in Intel hex format (you can select the
1168 Motorola S19 format with --out-fmt-s19)
1169 \layout Subsubsection
1171 Projects with Multiple Source Files
1174 SDCC can compile only ONE file at a time.
1175 Let us for example assume that you have a project containing the following
1181 foo1.c ( contains some functions )
1186 foo2.c (contains some more functions)
1191 foomain.c (contains more functions and the function main)
1194 The first two files will need to be compiled separately with the commands
1207 Then compile the source file containing main and link the other files together
1208 with the following command.
1213 sdcc foomain.c foo1.rel foo2.rel
1220 can be separately compiled as well
1230 sdcc foomain.rel foo1.rel foo2.rel
1233 The file containing the main function MUST be the FIRST file specified in
1234 the command line , since the linkage editor processes file in the order
1235 they are presented to it.
1236 \layout Subsubsection
1238 Projects with Additional Libraries
1241 Some reusable routines may be compiled into a library, see the documentation
1242 for the assembler and linkage editor in the directory
1244 SDCCDIR/asxxxx/asxhtm.htm
1246 this describes how to create a
1250 library file, the libraries created in this manner may be included using
1251 the command line, make sure you include the -L <library-path> option to
1252 tell the linker where to look for these files.
1253 Here is an example, assuming you have the source file
1265 ' (if that is not the same as your current project).
1270 sdcc foomain.c foolib.lib -L mylib
1277 ' must be an absolute path name.
1280 The view of the way the linkage editor processes the library files, it is
1281 recommended that you put each source routine in a separate file and combine
1282 them using the .lib file.
1283 For an example see the standard library file 'libsdcc.lib' in the directory
1287 Command Line Options
1288 \layout Subsubsection
1290 Processor Selection Options
1292 \labelwidthstring 00.00.0000
1298 Generate code for the MCS51 (8051) family of processors.
1299 This is the default processor target.
1301 \labelwidthstring 00.00.0000
1307 Generate code for the DS80C390 processor.
1309 \labelwidthstring 00.00.0000
1315 Generate code for the Z80 family of processors.
1317 \labelwidthstring 00.00.0000
1323 Generate code for the GameBoy Z80 processor.
1325 \labelwidthstring 00.00.0000
1331 Generate code for the Atmel AVR processor(In development, not complete).
1333 \labelwidthstring 00.00.0000
1339 Generate code for the PIC 14-bit processors(In development, not complete).
1341 \labelwidthstring 00.00.0000
1347 Generate code for the Toshiba TLCS-900H processor(In development, not complete).
1348 \layout Subsubsection
1350 Path and Define Options
1352 \labelwidthstring 00.00.0000
1360 The additional location where the pre processor will look for <..h> or
1361 \begin_inset Quotes eld
1365 \begin_inset Quotes erd
1370 \labelwidthstring 00.00.0000
1381 <absolute path to additional libraries> This option is passed to the linkage
1382 editor, additional libraries search path.
1383 The path name must be absolute.
1384 Additional library files may be specified in the command line .
1385 See section Compiling programs for more details
1387 \labelwidthstring 00.00.0000
1397 Command line definition of macros.
1398 Passed to the pre processor.
1399 \layout Subsubsection
1403 \labelwidthstring 00.00.0000
1411 Generate code for Large model programs see section Memory Models for more
1413 If this option is used all source files in the project should be compiled
1415 In addition the standard library routines are compiled with small model
1416 , they will need to be recompiled.
1418 \labelwidthstring 00.00.0000
1431 Generate code for Small Model programs see section Memory Models for more
1433 This is the default model.
1435 \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
1598 Generate 24-bit flat mode code.
1599 This is the one and only that the ds390 code generator supports right now
1600 and is default when using -mds390.
1601 See section Memory Models for more details.
1603 \labelwidthstring 00.00.0000
1609 This option generates code for the 10 bit stack mode of the Dallas DS80C390
1611 This is the one and only that the ds390 code generator supports right now
1612 and is default when using -mds390.
1613 In this mode, the stack is located in the lower 1K of the internal RAM,
1614 which is mapped to 0x400000.
1615 Note that the support is incomplete, since it still uses a single byte
1616 as the stack pointer.
1617 This means that only the lower 256 bytes of the potential 1K stack space
1618 will actually be used.
1619 However, this does allow you to reclaim the precious 256 bytes of low RAM
1620 for use for the DATA and IDATA segments.
1621 The compiler will not generate any code to put the processor into 10 bit
1623 It is important to ensure that the processor is in this mode before calling
1624 any re-entrant functions compiled with this option.
1625 In principle, this should work with the --stack-auto option, but that has
1627 It is incompatible with the --xstack option.
1628 It also only makes sense if the processor is in 24 bit contiguous addressing
1629 mode (see the --model-flat24 option).
1630 \layout Subsubsection
1634 \labelwidthstring 00.00.0000
1640 --callee-saves function1[,function2][,function3]....
1645 The compiler by default uses a caller saves convention for register saving
1646 across function calls, however this can cause unneccessary register pushing
1647 & popping when calling small functions from larger functions.
1648 This option can be used to switch the register saving convention for the
1649 function names specified.
1650 The compiler will not save registers when calling these functions, no extra
1651 code will be generated at the entry & exit for these functions to save
1652 & restore the registers used by these functions, this can SUBSTANTIALLY
1653 reduce code & improve run time performance of the generated code.
1654 In the future the compiler (with interprocedural analysis) will be able
1655 to determine the appropriate scheme to use for each function call.
1656 DO NOT use this option for built-in functions such as _muluint..., if this
1657 option is used for a library function the appropriate library function
1658 needs to be recompiled with the same option.
1659 If the project consists of multiple source files then all the source file
1660 should be compiled with the same --callee-saves option string.
1661 Also see Pragma Directive CALLEE-SAVES.
1664 \labelwidthstring 00.00.0000
1672 When this option is used the compiler will generate debug information ,
1673 that can be used with the SDCDB.
1674 The debug information is collected in a file with .cdb extension.
1675 For more information see documentation for SDCDB.
1677 \labelwidthstring 00.00.0000
1688 This option will cause the compiler to define pseudo registers , if this
1689 option is used, all source files in the project should be compiled with
1691 See section Register Extension for more details.
1693 \labelwidthstring 00.00.0000
1704 will compile and assemble the source, but will not call the linkage editor.
1706 \labelwidthstring 00.00.0000
1716 <Value> The start location of the external ram, default value is 0.
1717 The value entered can be in Hexadecimal or Decimal format .eg.
1718 --xram-loc 0x8000 or --xram-loc 32768.
1720 \labelwidthstring 00.00.0000
1730 <Value> The start location of the code segment , default value 0.
1731 Note when this option is used the interrupt vector table is also relocated
1732 to the given address.
1733 The value entered can be in Hexadecimal or Decimal format .eg.
1734 --code-loc 0x8000 or --code-loc 32768.
1736 \labelwidthstring 00.00.0000
1746 <Value> The initial value of the stack pointer.
1747 The default value of the stack pointer is 0x07 if only register bank 0
1748 is used, if other register banks are used then the stack pointer is initialized
1749 to the location above the highest register bank used.
1751 if register banks 1 & 2 are used the stack pointer will default to location
1753 The value entered can be in Hexadecimal or Decimal format .eg.
1754 --stack-loc 0x20 or --stack-loc 32.
1755 If all four register banks are used the stack will be placed after the
1756 data segment (equivalent to --stack-after-data)
1758 \labelwidthstring 00.00.0000
1768 This option will cause the stack to be located in the internal ram after
1771 \labelwidthstring 00.00.0000
1781 <Value> The start location of the internal ram data segment, the default
1782 value is 0x30.The value entered can be in Hexadecimal or Decimal format
1784 --data-loc 0x20 or --data-loc 32.
1786 \labelwidthstring 00.00.0000
1796 <Value> The start location of the indirectly addressable internal ram, default
1798 The value entered can be in Hexadecimal or Decimal format .eg.
1799 --idata-loc 0x88 or --idata-loc 136.
1801 \labelwidthstring 00.00.0000
1811 <filename> This option can be used to use additional rules to be used by
1812 the peep hole optimizer.
1813 See section Peep Hole optimizations for details on how to write these rules.
1815 \labelwidthstring 00.00.0000
1825 Run only the C preprocessor.
1826 Preprocess all the C source files specified and output the results to standard
1829 \labelwidthstring 00.00.0000
1839 Tell the preprocessor to output a rule suitable for make describing the
1840 dependencies of each object file.
1841 For each source file, the preprocessor outputs one make-rule whose target
1842 is the object file name for that source file and whose dependencies are
1843 all the files `#include'd in it.
1844 This rule may be a single line or may be continued with `
1846 '-newline if it is long.
1847 The list of rules is printed on standard output instead of the preprocessed
1851 \labelwidthstring 00.00.0000
1861 Tell the preprocessor not to discard comments.
1862 Used with the `-E' option.
1864 \labelwidthstring 00.00.0000
1874 Like `-M' but the output mentions only the user header files included with
1876 \begin_inset Quotes eld
1880 System header files included with `#include <file>' are omitted.
1882 \labelwidthstring 00.00.0000
1892 Assert the answer answer for question, in case it is tested with a preprocessor
1893 conditional such as `#if #question(answer)'.
1894 `-A-' disables the standard assertions that normally describe the target
1897 \labelwidthstring 00.00.0000
1907 (answer) Assert the answer answer for question, in case it is tested with
1908 a preprocessor conditional such as `#if #question(answer)'.
1909 `-A-' disables the standard assertions that normally describe the target
1912 \labelwidthstring 00.00.0000
1922 Undefine macro macro.
1923 `-U' options are evaluated after all `-D' options, but before any `-include'
1924 and `-imacros' options.
1926 \labelwidthstring 00.00.0000
1936 Tell the preprocessor to output only a list of the macro definitions that
1937 are in effect at the end of preprocessing.
1938 Used with the `-E' option.
1940 \labelwidthstring 00.00.0000
1950 Tell the preprocessor to pass all macro definitions into the output, in
1951 their proper sequence in the rest of the output.
1953 \labelwidthstring 00.00.0000
1963 Like `-dD' except that the macro arguments and contents are omitted.
1964 Only `#define name' is included in the output.
1966 \labelwidthstring 00.00.0000
1976 Stop after the stage of compilation proper; do not assemble.
1977 The output is an assembler code file for the input file specified.
1979 \labelwidthstring 00.00.0000
1984 -Wa_asmOption[,asmOption]
1988 Pass the asmOption to the assembler.
1990 \labelwidthstring 00.00.0000
1995 -Wl_linkOption[,linkOption]
1999 Pass the linkOption to the linker.
2001 \labelwidthstring 00.00.0000
2012 Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
2013 Note by default these libraries are compiled as non-reentrant.
2014 See section Installation for more details.
2016 \labelwidthstring 00.00.0000
2027 This option will cause the compiler to generate an information message for
2028 each function in the source file.
2029 The message contains some
2033 information about the function.
2034 The number of edges and nodes the compiler detected in the control flow
2035 graph of the function, and most importantly the
2037 cyclomatic complexity
2039 see section on Cyclomatic Complexity for more details.
2041 \labelwidthstring 00.00.0000
2052 Floating point library is compiled as reentrant.See section Installation
2055 \labelwidthstring 00.00.0000
2066 The linker output (final object code) is in Intel Hex format.
2067 (This is the default option).
2069 \labelwidthstring 00.00.0000
2080 The linker output (final object code) is in Motorola S19 format.
2082 \labelwidthstring 00.00.0000
2092 The compiler will not overlay parameters and local variables of any function,
2093 see section Parameters and local variables for more details.
2095 \labelwidthstring 00.00.0000
2105 This option can be used when the code generated is called by a monitor
2107 The compiler will generate a 'ret' upon return from the 'main' function.
2108 The default option is to lock up i.e.
2109 generate a 'ljmp .' .
2111 \labelwidthstring 00.00.0000
2121 Disable peep-hole optimization.
2123 \labelwidthstring 00.00.0000
2133 Pass the inline assembler code through the peep hole optimizer.
2134 This can cause unexpected changes to inline assembler code, please go through
2135 the peephole optimizer rules defined in the source file tree '<target>/peeph.def
2136 ' before using this option.
2138 \labelwidthstring 00.00.0000
2148 <Value> Causes the linker to check if the interal ram usage is within limits
2150 \layout Subsubsection
2152 Intermediate Dump Options
2155 The following options are provided for the purpose of retargetting and debugging
2157 These provided a means to dump the intermediate code (iCode) generated
2158 by the compiler in human readable form at various stages of the compilation
2162 \labelwidthstring 00.00.0000
2172 This option will cause the compiler to dump the intermediate code into
2175 <source filename>.dumpraw
2177 just after the intermediate code has been generated for a function, i.e.
2178 before any optimizations are done.
2179 The basic blocks at this stage ordered in the depth first number, so they
2180 may not be in sequence of execution.
2182 \labelwidthstring 00.00.0000
2192 Will create a dump of iCode's, after global subexpression elimination,
2195 <source filename>.dumpgcse.
2197 \labelwidthstring 00.00.0000
2207 Will create a dump of iCode's, after deadcode elimination, into a file
2210 <source filename>.dumpdeadcode.
2212 \labelwidthstring 00.00.0000
2223 Will create a dump of iCode's, after loop optimizations, into a file named
2226 <source filename>.dumploop.
2228 \labelwidthstring 00.00.0000
2239 Will create a dump of iCode's, after live range analysis, into a file named
2242 <source filename>.dumprange.
2244 \labelwidthstring 00.00.0000
2255 Will create a dump of iCode's, after register assignment , into a file named
2258 <source filename>.dumprassgn.
2260 \labelwidthstring 00.00.0000
2262 --dumplrange Will create a dump of the live ranges of iTemp's
2264 \labelwidthstring 00.00.0000
2274 Will cause all the above mentioned dumps to be created.
2277 MCS51/DS390 Storage Class Language Extensions
2280 In addition to the ANSI storage classes SDCC allows the following MCS51
2281 specific storage classes.
2282 \layout Subsubsection
2287 Variables declared with this storage class will be placed in the extern
2293 storage class for Large Memory model .
2301 xdata unsigned char xduc;
2302 \layout Subsubsection
2311 storage class for Small Memory model.
2312 Variables declared with this storage class will be allocated in the internal
2322 \layout Subsubsection
2327 Variables declared with this storage class will be allocated into the indirectly
2328 addressable portion of the internal ram of a 8051 .
2336 \layout Subsubsection
2341 This is a data-type and a storage class specifier.
2342 When a variable is declared as a bit , it is allocated into the bit addressable
2349 \layout Subsubsection
2354 Like the bit keyword,
2358 signifies both a data-type and storage class, they are used to describe
2359 the special function registers and special bit variables of a 8051.
2374 /* special function register P0 at location 0x80 */
2387 SDCC allows (via language extensions) pointers to explicitly point to any
2388 of the memory spaces of the 8051.
2389 In addition to the explicit pointers, the compiler also allows a
2393 class of pointers which can be used to point to any of the memory spaces.
2397 Pointer declaration examples.
2402 /* pointer physically in xternal ram pointing to object in internal ram
2405 data unsigned char * xdata p;
2412 /* pointer physically in code rom pointing to data in xdata space */
2414 xdata unsigned char * code p;
2421 /* pointer physically in code space pointing to data in code space */
2423 code unsigned char * code p;
2427 /* the folowing is a generic pointer physically located in xdata space */
2432 Well you get the idea.
2433 For compatibility with the previous version of the compiler, the following
2434 syntax for pointer declaration is also supported.
2435 Note the above examples will be portable to other commercially available
2441 unsigned char _xdata *ucxdp; /* pointer to data in external ram */
2443 unsigned char _data \SpecialChar ~
2444 *ucdp ; /* pointer to data in internal ram */
2446 unsigned char _code \SpecialChar ~
2447 *uccp ; /* pointer to data in R/O code space */
2449 unsigned char _idata *uccp; \SpecialChar ~
2450 /* pointer to upper 128 bytes of ram */
2453 All unqualified pointers are treated as 3-byte (4-bytes for the ds390) '_generic
2455 These type of pointers can also to be explicitly declared.
2460 unsigned char _generic *ucgp;
2463 The highest order byte of the generic pointers contains the data space informati
2465 Assembler support routines are called whenever data is stored or retrieved
2466 using _generic pointers.
2467 These are useful for developing reusable library routines.
2468 Explicitly specifying the pointer type will generate the most efficient
2470 Pointers declared using a mixture of OLD/NEW style could have unpredictable
2474 Parameters & Local Variables
2477 Automatic (local) variables and parameters to functions can either be placed
2478 on the stack or in data-space.
2479 The default action of the compiler is to place these variables in the internal
2480 RAM ( for small model) or external RAM (for Large model).
2481 They can be placed on the stack either by using the
2485 compiler option or by using the 'reentrant' keyword in the function declaration.
2496 unsigned short foo( short i) reentrant {
2504 Note that when the parameters & local variables are declared in the internal/ext
2505 ernal ram the functions are non-reentrant.
2506 Since stack space on 8051 is limited the
2514 option should be used sparingly.
2515 Note the reentrant keyword just means that the parameters & local variables
2516 will be allocated to the stack, it DOES NOT mean that the function is register
2520 When compiled with the default option (i.e.
2521 non-reentrant ), local variables can be assigned storage classes and absolute
2526 (jwk: pending: this is obsolete and need a rewrite)
2537 unsigned short foo() {
2541 xdata unsigned short i;
2549 data at 0x31 unsiged short j;
2557 In the above example the variable
2561 will be allocated in the external ram,
2565 in bit addressable space and
2570 When compiled with the
2574 or when a function is declared as
2578 local variables cannot be assigned storage classes or absolute addresses.
2581 Parameters however are not allowed any storage class, (storage classes for
2582 parameters will be ignored), their allocation is governed by the memory
2583 model in use , and the reentrancy options.
2589 For non-reentrant functions SDCC will try to reduce internal ram space usage
2590 by overlaying parameters and local variables of a function (if possible).
2591 Parameters and local variables of a function will be allocated to an overlayabl
2592 e segment if the function has
2594 no other function calls and the function is non-reentrant and the memory
2598 If an explicit storage class is specified for a local variable , it will
2602 Note that the compiler (not the linkage editor) makes the decision for overlayin
2604 Functions that are called from an interrupt service routine should be preceded
2605 by a #pragma NOOVERLAY if they are not reentrant Along the same lines the
2606 compiler does not do any processing with the inline assembler code so the
2607 compiler might incorrectly assign local variables and parameters of a function
2608 into the overlay segment if the only function call from a function is from
2609 inline assembler code, it is safe to use the #pragma NOOVERLAY for functions
2610 which call other functions using inline assembler code.
2613 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
2614 tion or division will NOT be overlayed since these are implemented using
2627 void set_error( unsigned short errcd)
2639 void some_isr () interrupt 2 using 1
2660 In the above example the parameter
2668 would be assigned to the overlayable segment (if the #pragma NOOVERLAY
2669 was not present) , this could cause unpredictable runtime behavior.
2670 The pragma NOOVERLAY ensures that the parameters and local variables for
2671 the function are NOT overlayed.
2677 A special keyword may be associated with a function declaring it as '
2682 SDCC will generate code to disable all interrupts upon entry to a critical
2683 function and enable them back before returning .
2684 Note that nesting critical functions may cause unpredictable results.
2705 The critical attribute maybe used with other attributes like
2713 Data items can be assigned an absolute address with the
2717 keyword, in addition to a storage class.
2726 xdata at 0x8000 unsigned char PORTA_8255 ;
2729 In the above example the
2733 will be allocated to the location 0x8000 of the external ram.
2737 Note that is this feature is provided to give the programmer access to
2741 devices attached to the controller.
2742 The compiler does not actually reserve any space for variables declared
2743 in this way (they are implemented with an equate in the assembler), thus
2744 it is left to the programmer to make sure there are no overlaps with other
2745 variables that are declared without the absolute address, the assembler
2746 listing file (.lst) and the linker output files (<filename>.rst) and (<filename>.m
2747 ap) are a good places to look for such overlaps.
2750 Absolute address can be specified for variables in all storage classes.
2763 The above example will allocate the variable at offset 0x02 in the bit-addressab
2765 There is no real advantage to assigning absolute addresses to variables
2766 in this manner , unless you want strict control over all the variables
2770 Interrupt Service Routines
2773 SDCC allows interrupt service routines to be coded in C, with some extended
2779 void timer_isr (void) interrupt 2 using 1
2789 The number following the 'interrupt' keyword is the interrupt number this
2790 routine will service.
2791 The compiler will insert a call to this routine in the interrupt vector
2792 table for the interrupt number specified.
2793 The 'using' keyword is used to tell the compiler to use the specified register
2794 bank (8051 specific) when generating code for this function.
2795 Note that when some function is called from an interrupt service routine
2796 it should be preceded by a #pragma NOOVERLAY (if it is not reentrant) .
2797 A special note here, int (16 bit) and long (32 bit) integer division, multiplic
2798 ation & modulus operations are implemented using external support routines
2799 developed in ANSI-C, if an interrupt service routine needs to do any of
2800 these operations then the support routines (as mentioned in a following
2801 section) will have to recompiled using the --stack-auto option and the
2802 source file will need to be compiled using the --int-long-rent compiler
2806 If you have multiple source files in your project, interrupt service routines
2807 can be present in any of them, but a prototype of the isr MUST be present
2808 in the file that contains the function
2815 Interrupt Numbers and the corresponding address & descriptions for the Standard
2816 8051 are listed below.
2817 SDCC will automatically adjust the interrupt vector table to the maximum
2818 interrupt number specified.
2822 \begin_inset Tabular
2823 <lyxtabular version="2" rows="6" columns="3">
2824 <features rotate="false" islongtable="false" endhead="0" endfirsthead="0" endfoot="0" endlastfoot="0">
2825 <column alignment="center" valignment="top" leftline="true" rightline="false" width="" special="">
2826 <column alignment="center" valignment="top" leftline="true" rightline="false" width="" special="">
2827 <column alignment="center" valignment="top" leftline="true" rightline="true" width="" special="">
2828 <row topline="true" bottomline="true" newpage="false">
2829 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2837 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2845 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2854 <row topline="true" bottomline="false" newpage="false">
2855 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2863 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2871 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2880 <row topline="true" bottomline="false" newpage="false">
2881 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2889 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2897 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2906 <row topline="true" bottomline="false" newpage="false">
2907 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2915 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2923 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2932 <row topline="true" bottomline="false" newpage="false">
2933 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2941 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2949 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2958 <row topline="true" bottomline="true" newpage="false">
2959 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2967 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2975 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2991 If the interrupt service routine is defined without a register bank or with
2992 register bank 0 (using 0), the compiler will save the registers used by
2993 itself on the stack (upon entry and restore them at exit), however if such
2994 an interrupt service routine calls another function then the entire register
2995 bank will be saved on the stack.
2996 This scheme may be advantageous for small interrupt service routines which
2997 have low register usage.
3000 If the interrupt service routine is defined to be using a specific register
3002 \begin_inset Quotes eld
3006 \begin_inset Quotes erd
3010 \begin_inset Quotes erd
3014 \begin_inset Quotes erd
3018 \begin_inset Quotes eld
3022 \begin_inset Quotes erd
3025 are save and restored, if such an interrupt service routine calls another
3026 function (using another register bank) then the entire register bank of
3027 the called function will be saved on the stack.
3028 This scheme is recommended for larger interrupt service routines.
3031 Calling other functions from an interrupt service routine is not recommended
3032 avoid it if possible.
3038 The compiler inserts a jump to the C routine
3040 _sdcc__external__startup()
3042 at the start of the CODE area.
3043 This routine can be found in the file
3045 SDCCDIR/sdcc51lib/_startup.c
3047 , by default this routine returns 0, if this routine returns a non-zero
3048 value , the static & global variable initialization will be skipped and
3049 the function main will be invoked, other wise static & global variables
3050 will be initialized before the function main is invoked.
3053 _sdcc__external__startup()
3055 routine to your program to override the default if you needed to setup
3056 hardware or perform some other critical operation prior to static & global
3057 variable initialization.
3060 Inline Assembler Code
3063 SDCC allows the use of in-line assembler with a few restriction as regards
3065 All labels defined within inline assembler code HAS TO BE of the
3069 where nnnn is a number less than 100 (which implies a limit of utmost 100
3070 inline assembler labels
3075 It is strongly recommended that each assembly instruction (including labels)
3076 be placed in a separate line ( as the example shows).
3083 command line option is used, the inline assembler code will be passed through
3084 the peephole optimizer, this might cause some unexpected changes in the
3085 inline assembler code, please go throught the peephole optimizer rules
3086 defined in file 'SDCCpeeph.def' carefully before using this option.
3117 The inline assembler code can contain any valid code understood by the assembler
3118 (this includes any assembler directives and comment lines ) .
3119 The compiler does not do any validation of the code within the
3128 Inline assembler code cannot reference any C-Labels however it can reference
3129 labels defined by the inline assembler.
3149 ; some assembler code
3158 /* some more c code */
3160 clabel: \SpecialChar ~
3161 /* inline assembler cannot reference this label */
3167 $0003: ;label (can be reference by inline assembler only)
3177 In other words inline assembly code can access labels defined in inline
3179 The same goes the other way, ie.
3180 labels defines in inline assembly CANNOT be accessed by C statements.
3183 int(16 bit) and long (32 bit ) Support
3186 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
3187 multiplication and modulus operations are implemented by support routines.
3188 These support routines are all developed in ANSI-C to facilitate porting
3190 The following files contain the described routine, all of them can be found
3191 in the directory SDCCDIR/sdcc51lib
3196 _mulsint.c - signed 16 bit multiplication (calls _muluint)
3201 _muluint.c - unsigned 16 bit multiplication
3206 _divsint.c - signed 16 bit division (calls _divuint)
3211 _divuint.c - unsigned 16 bit division.
3216 _modsint.c - signed 16 bit modulus (call _moduint)
3221 _moduint.c - unsigned 16 bit modulus.
3226 _mulslong.c - signed 32 bit multiplication (calls _mululong)
3231 _mululong.c - unsigned32 bit multiplication.
3236 _divslong.c - signed 32 division (calls _divulong)
3241 _divulong.c - unsigned 32 division.
3246 _modslong.c - signed 32 bit modulus (calls _modulong).
3251 _modulong.c - unsigned 32 bit modulus.
3254 All these routines are compiled as non-reentrant and small model.
3255 Since they are compiled as non-reentrant, interrupt service routines should
3256 not do any of the above operations, if this unavoidable then the above
3257 routines will need to ne compiled with the --stack-auto option, after which
3258 the source program will have to be compiled with --int-long-rent option.
3261 Floating Point Support
3264 SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
3265 point support routines are derived from gcc's floatlib.c and consists of
3266 the following routines.
3272 _fsadd.c - add floating point numbers.
3277 _fssub.c - subtract floating point numbers
3282 _fsdiv.c - divide floating point numbers
3287 _fsmul.c - multiply floating point numbers
3292 _fs2uchar.c - convert floating point to unsigned char
3297 _fs2char.c - convert floating point to signed char.
3302 _fs2uint.c - convert floating point to unsigned int.
3307 _fs2int.c - convert floating point to signed int.
3312 _fs2ulong.c - convert floating point to unsigned long.
3317 _fs2long.c - convert floating point to signed long.
3322 _uchar2fs.c - convert unsigned char to floating point
3327 _char2fs.c - convert char to floating point number
3332 _uint2fs.c - convert unsigned int to floating point
3337 _int2fs.c - convert int to floating point numbers
3342 _ulong2fs.c - convert unsigned long to floating point number
3347 _long2fs.c - convert long to floating point number.
3350 Note if all these routines are used simultaneously the data space might
3352 For serious floating point usage it is strongly recommended that the Large
3353 model be used (in which case the floating point routines mentioned above
3354 will need to recompiled with the --model-Large option)
3360 SDCC allows two memory models for MCS51 code, small and large.
3361 Modules compiled with different memory models should never be combined
3362 together or the results would be unpredictable.
3363 The library routines supplied with the compiler are compiled as both small
3365 The compiled library modules are contained in seperate directories as small
3366 and large so that you can link to either set.
3367 In general the use of the large model is discouraged.
3370 When the large model is used all variables declared without a storage class
3371 will be allocated into the external ram, this includes all parameters and
3372 local variables (for non-reentrant functions).
3373 When the small model is used variables without storage class are allocated
3374 in the internal ram.
3377 Judicious usage of the processor specific storage classes and the 'reentrant'
3378 function type will yield much more efficient code, than using the large-model.
3379 Several optimizations are disabled when the program is compiled using the
3380 large model, it is therefore strongly recommdended that the small model
3381 be used unless absolutely required.
3384 Flat 24 bit Addressing Model
3387 This option generates code for the 24 bit contiguous addressing mode of
3388 the Dallas DS80C390 part.
3389 In this mode, up to four meg of external RAM or code space can be directly
3391 See the data sheets at www.dalsemi.com for further information on this part.
3394 In older versions of the compiler, this option was used with the MCS51 code
3395 generator (-mmcs51).
3396 Now, however, the '390 has it's own code generator, selected by the -mds390
3398 This code generator currently supports only the flat24 model, but the --model-f
3399 lat24 switch is still required, in case later versions of the code generator
3400 support other models (such as the paged mode of the '390).
3401 The combination of -mmcs51 and --model-flat24 is now depracated.
3404 Note that the compiler does not generate any code to place the processor
3405 into24 bitmode (it defaults to 8051 compatible mode).
3406 Boot loader or similar code must ensure that the processor is in 24 bit
3407 contiguous addressing mode before calling the SDCC startup code.
3410 Like the --model-large option, variables will by default be placed into
3415 Segments may be placed anywhere in the 4 meg address space using the usual
3417 Note that if any segments are located above 64K, the -r flag must be passed
3418 to the linker to generate the proper segment relocations, and the Intel
3419 HEX output format must be used.
3420 The -r flag can be passed to the linker by using the option -Wl-r on the
3424 Defines Created by the Compiler
3427 The compiler creates the following #defines .
3430 SDCC - this Symbol is always defined.
3433 SDCC_STACK_AUTO - this symbol is defined when --stack-auto option is used.
3436 SDCC_MODEL_SMALL - when small model is used.
3439 SDCC_MODEL_LARGE - when --model-large is used.
3442 SDCC_USE_XSTACK - when --xstack option is used.
3451 SDCC performs a a host of standard optimizations in addition to some MCU
3452 specific optimizations.
3454 \layout Subsubsection
3456 Sub-expression Elimination
3463 common subexpression elimination.
3484 will be translated to
3496 Some subexpressions are not as obvious as the above example.
3509 In this case the address arithmetic
3513 will be computed only once; the equivalent code in C would be.
3525 The compiler will try to keep these temporary variables in registers.
3526 \layout Subsubsection
3528 Dead-Code Elimination
3546 i = 1; \SpecialChar ~
3553 global = 1; /* dead store */
3565 global = 3; /* unreachable */
3575 int global; void f ()
3582 global = 2; \SpecialChar ~
3590 \layout Subsubsection
3651 Note: the dead stores created by this copy propagation will be eliminated
3652 by dead-code elimination .
3653 \layout Subsubsection
3658 Two types of loop optimizations are done by SDCC loop invariant lifting
3659 and strength reduction of loop induction variables.In addition to the strength
3660 reduction the optimizer marks the induction variables and the register
3661 allocator tries to keep the induction variables in registers for the duration
3663 Because of this preference of the register allocator , loop induction optimizat
3664 ion causes an increase in register pressure, which may cause unwanted spilling
3665 of other temporary variables into the stack / data space .
3666 The compiler will generate a warning message when it is forced to allocate
3667 extra space either on the stack or data space.
3668 If this extra space allocation is undesirable then induction optimization
3669 can be eliminated either for the entire source file ( with --noinduction
3670 option) or for a given function only (#pragma NOINDUCTION).
3683 for (i = 0 ; i < 100 ; i ++)
3698 for ( i = 0; i < 100; i++ ) f += itemp;
3701 As mentioned previously some loop invariants are not as apparent, all static
3702 address computations are also moved out of the loop.
3707 Strength Reduction :
3710 This optimization substitutes an expression by a cheaper expression.
3718 for (i=0;i < 100; i++) ar[i*5] = i*3;
3730 for (i=0;i< 100;i++) {
3735 ar[itemp1] = itemp2;
3750 The more expensive multiplication is changed to a less expensive addition.
3751 \layout Subsubsection
3756 This optimization is done to reduce the overhead of checking loop boundaries
3757 for every iteration.
3758 Some simple loops can be reversed and implemented using a
3759 \begin_inset Quotes eld
3762 decrement and jump if not zero
3763 \begin_inset Quotes erd
3767 SDCC checks for the following criterion to determine if a loop is reversible
3768 (note: more sophisticated compiers use data-dependency analysis to make
3769 this determination, SDCC uses a more simple minded analysis).
3772 The 'for' loop is of the form
3775 \begin_inset Quotes eld
3778 for ( <symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
3789 \begin_inset Quotes erd
3795 The <for body> does not contain
3796 \begin_inset Quotes eld
3800 \begin_inset Quotes erd
3804 \begin_inset Quotes erd
3810 All goto's are contained within the loop.
3813 No function calls within the loop.
3816 The loop control variable <sym> is not assigned any value within the loop
3819 The loop control variable does NOT participate in any arithmetic operation
3823 There are NO switch statements in the loop.
3826 Note djnz instruction can be used for 8-bit values ONLY, therefore it is
3827 advantageous to declare loop control symbols as either 'char' or 'short',
3828 ofcourse this may not be possible on all situations.
3829 \layout Subsubsection
3831 Algebraic Simplifications
3834 SDCC does numerous algebraic simplifications, the following is a small sub-set
3835 of these optimizations.
3846 i = j + 0 ; /* changed to */ i = j;
3848 i /= 2; /* changed to */ i >>= 1;
3850 i = j - j ; /* changed to */ i = 0;
3852 i = j / 1 ; /* changed to */ i = j;
3855 Note the subexpressions given above are generally introduced by macro expansions
3856 or as a result of copy/constant propagation.
3857 \layout Subsubsection
3862 SDCC changes switch statements to jump tables when the following conditions
3867 The case labels are in numerical sequence , the labels need not be in order,
3868 and the starting number need not be one or zero.
3876 switch(i) {\SpecialChar ~
3980 Both the above switch statements will be implemented using a jump-table.
3983 The number of case labels is at least three, since it takes two conditional
3984 statements to handle the boundary conditions.
3987 The number of case labels is less than 84, since each label takes 3 bytes
3988 and a jump-table can be utmost 256 bytes long.
3992 Switch statements which have gaps in the numeric sequence or those that
3993 have more that 84 case labels can be split into more than one switch statement
3994 for efficient code generation.
4031 If the above switch statement is broken down into two switch statements
4072 then both the switch statements will be implemented using jump-tables whereas
4073 the unmodified switch statement will not be .
4074 \layout Subsubsection
4076 Bit-shifting Operations.
4079 Bit shifting is one of the most frequently used operation in embedded programmin
4081 SDCC tries to implement bit-shift operations in the most efficient way
4103 generates the following code.
4117 In general SDCC will never setup a loop if the shift count is known.
4149 Note that SDCC stores numbers in
4155 \layout Subsubsection
4160 A special case of the bit-shift operation is bit rotation, SDCC recognizes
4161 the following expression to be a left bit-rotation.
4171 i = ( ( i << 1) | ( i >> 7));
4176 will generate the following code.
4188 SDCC uses pattern matching on the parse tree to determine this operation
4189 .Variations of this case will also be recognized as bit-rotation i.e
4191 i = ((i >> 7) | (i << 1));
4193 /* left-bit rotation */
4194 \layout Subsubsection
4199 It is frequently required to obtain the highest order bit of an integral
4200 type (int,long,short or char types).
4201 SDCC recognizes the following expression to yield the highest order bit
4202 and generates optimized code for it.
4224 hob = (gint >> 15) & 1;
4235 Will generate the following code.
4273 000A E5*01\SpecialChar ~
4301 000C 33\SpecialChar ~
4332 000D E4\SpecialChar ~
4363 000E 13\SpecialChar ~
4394 000F F5*02\SpecialChar ~
4421 Variations of this case however will NOT be recognized .
4422 It is a standard C expression , so I heartily recommend this be the only
4423 way to get the highest order bit, (it is portable).
4424 Of course it will be recognized even if it is embedded in other expressions.
4434 xyz = gint + ((gint >> 15) & 1);
4437 will still be recognized.
4438 \layout Subsubsection
4443 The compiler uses a rule based , pattern matching and re-writing mechanism
4444 for peep-hole optimization .
4449 a peep-hole optimizer by Christopher W.
4450 Fraser (cwfraser@microsoft.com).
4451 A default set of rules are compiled into the compiler, additional rules
4452 may be added with the --peep-file <filename> option.
4453 The rule language is best illustrated with examples.
4462 mov a,%1 } by { mov %1,a }
4465 The above rule will the following assembly sequence
4483 Note: All occurrences of a '%n' ( pattern variable ) must denote the same
4485 With the above rule, the assembly sequence
4495 will remain unmodified.
4496 Other special case optimizations may be added by the user (via --peep-file
4498 some variants of the 8051 MCU allow only 'AJMP' and 'ACALL' , the following
4499 two rules will change all 'LJMP' & 'LCALL' to 'AJMP' & 'ACALL'.
4504 replace { lcall %1 } by { acall %1 }
4506 replace { ljmp %1 } by { ajmp %1 }
4509 The inline-assembler' code is also passed through the peep hole optimizer,
4510 thus the peephole optimizer can also be used as an assembly level macro
4512 The rules themselves are MCU dependent whereas the rule language infra-structur
4513 e is MCU independent.
4514 Peephole optimization rules for other MCU can be easily programmed using
4518 The syntax for a rule is as follows ,
4523 rule := replace [ restart ] '{' <assembly sequence> '
4561 <assembly sequence> '
4579 '}' [if <functionName> ] '
4583 <assembly sequence> := assembly instruction (each instruction including
4584 labels must be on a separate line).\SpecialChar ~
4589 The optimizer will apply to the rules one by one from the top in the sequence
4590 of their appearance, it will terminate when all rules are exhausted.
4595 ' option is specified, then the optimizer will start matching the rules
4596 again from the top, this option for a rule is expensive (performance),
4597 it is intended to be used in situations where a transformation will trigger
4598 the same rule again.
4599 A good example of this the following rule.
4615 Note that the replace pattern cannot be a blank, but can be a comment line.
4620 ' option only the inner most 'pop' 'push' pair would be eliminated.
4651 ' option the rule will be applied again to the resulting code and the all
4656 pairs will be eliminated to yield
4666 A conditional function can be attached to a rule.
4667 Attaching rules are somewhat more involved, let me illustrate this with
4687 %2:} if labelInRange
4690 The optimizer does a look-up of a function name table defined in function
4703 ', if it finds a corresponding entry the function is called.
4704 Note there can be no parameters specified for these functions, in this
4709 ' is crucial, since the function
4713 expects to find the label in that particular variable (the hash table containin
4714 g the variable bindings is passed as a parameter).
4715 If you want to code more such functions , take a close look at the function
4720 and the calling mechanism in source file
4725 I know this whole thing is a little kludgey , may be some day we will have
4727 If you are looking at this file, you will also see the default rules that
4728 are compiled into the compiler, you can your own rules in the default set
4729 there if you get tired of specifying the
4739 SDCC supports the following
4744 This directives are applicable only at a function level.
4751 - this will save all the current options .
4758 - will restore the saved options from the last save.
4759 Note that SAVES & RESTOREs cannot be nested.
4760 SDCC uses the same buffer to save the options each time a SAVE is called.
4767 - will stop global subexpression elimination.
4774 - will stop loop induction optimizations .
4781 - will not generate code for boundary value checking , when switch statements
4782 are turned into jump-tables.
4789 - the compiler will not overlay the parameters and local variables of a
4797 - Will not do loop reversal optimization
4802 EXCLUDE NONE | {acc[,b[,dpl[,dph]]]
4804 - The exclude pragma disables generation of pair of push/pop instruction
4805 in ISR function (using interrupt keyword).
4806 The directive should be placed immediately before the ISR function definition
4807 and it affects ALL ISR functions following it.
4808 To enable the normal register saving for ISR functions use
4809 \begin_inset Quotes eld
4812 #pragma EXCLUDE none
4813 \begin_inset Quotes erd
4821 CALLEE-SAVES function1[,function2[,function3...]]
4823 - The compiler by default uses a caller saves convention for register saving
4824 across function calls, however this can cause unneccessary register pushing
4825 & popping when calling small functions from larger functions.
4826 This option can be used to switch the register saving convention for the
4827 function names specified.
4828 The compiler will not save registers when calling these functions, extra
4829 code will be generated at the entry & exit for these functions to save
4830 & restore the registers used by these functions, this can SUBSTANTIALLY
4831 reduce code & improve run time performance of the generated code.
4832 In future the compiler (with interprocedural analysis) will be able to
4833 determine the appropriate scheme to use for each function call.
4834 If --callee-saves command line option is used, the function names specified
4835 in #pragma CALLEE-SAVES is appended to the list of functions specified
4839 The pragma's are intended to be used to turn-off certain optimizations which
4840 might cause the compiler to generate extra stack / data space to store
4841 compiler generated temporary variables.
4842 This usually happens in large functions.
4843 Pragma directives should be used as shown in the following example, they
4844 are used to control options & optimizations for a given function; pragmas
4853 a function, placing pragma's inside a function body could have unpredictable
4864 #pragma SAVE \SpecialChar ~
4865 /* save the current settings */
4867 #pragma NOGCSE /* turnoff global subexpression elimination */
4869 #pragma NOINDUCTION /* turn off induction optimizations */
4891 #pragma RESTORE /* turn the optimizations back on */
4894 The compiler will generate a warning message when extra space is allocated.
4895 It is strongly recommended that the SAVE and RESTORE pragma's be used when
4896 changing options for a function.
4902 The following library routines are provided for your convenience.
4911 - Contains the following functions printf & sprintf these routines are developed
4914 Martijn van Balen <balen@natlab.research.philips.com>.
4920 %[flags][width][b|B|l|L]type
4935 flags: -\SpecialChar ~
4942 left justify output in specified field width
4967 prefix output with +/- sign if output is signed type
4988 prefix output with a blank if it's a signed positive value
4999 width:\SpecialChar ~
5008 specifies minimum number of characters outputted for numbers
5063 - For numbers, spaces are added on the left when needed.
5093 If width starts with a zero character, zeroes and used
5150 - For strings, spaces are are added on the left or right (when
5179 flag '-' is used) when needed.
5229 byte argument (used by d, u, o, x, X)
5251 long argument (used by d, u, o, x, X)
5295 unsigned decimal number
5320 unsigned octal number
5345 unsigned hexadecimal number (0-9, a-f)
5370 unsigned hexadecimal number (0-9, A-F)
5420 string (generic pointer)
5445 generic pointer (I:data/idata, C:code, X:xdata, P:paged)
5470 float (still to be implemented)
5473 Also contains a very simple version of printf (
5478 This simplified version of printf supports only the following formats.
5484 format\SpecialChar ~
5489 output\SpecialChar ~
5513 decimal \SpecialChar ~
5528 decimal\SpecialChar ~
5545 decimal\SpecialChar ~
5562 hexadecimal\SpecialChar ~
5575 hexadecimal\SpecialChar ~
5588 hexadecimal\SpecialChar ~
5660 character\SpecialChar ~
5676 character\SpecialChar ~
5688 , --stack-after-data parameter should be used when using this routine, the
5689 routine also takes about 1K of code space .It also expects an external function
5694 to be present (this can be changed).
5695 When using the %s format the string / pointer should be cast to a generic
5703 \begin_inset Quotes eld
5706 my str %s, my int %d
5709 \begin_inset Quotes erd
5712 ,(char _generic *)mystr,myint);
5721 - contains definition for the following macros to be used for variable parameter
5722 list, note that a function can have a variable parameter list if and only
5723 if it is 'reentrant'
5729 va_list, va_start, va_arg, va_end.
5739 - contains defintion for ANSI
5748 Note in this case setjmp & longjmp can be used between functions executing
5749 within the same register bank, if long jmp is executed from a function
5750 that is using a different register bank from the function issuing the setjmp
5751 function, the results may be unpredictable.
5752 The jump buffer requires 3 bytes of data (the stack pointer & a 16 byte
5753 return address), and can be placed in any address space.
5762 - contains the following functions.
5778 - contains the following functions.
5784 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn,
5785 strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.
5795 - contains the following routines.
5801 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
5802 isxdigit, isalnum, isalpha.
5812 - The malloc routines are developed by Dmitry S.
5813 Obukhov (dso@usa.net).
5814 These routines will allocate memory from the external ram.
5815 Here is a description on how to use them (as described by the author).
5831 #define DYNAMIC_MEMORY_SIZE 0x2000
5852 unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
5862 unsigned char xdata * current_buffer;
5923 init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
5937 //Now it's possible to use malloc.
5967 current_buffer = malloc(0x100);
5983 - Serial IO routines are also developed by Dmitry S.
5984 Obukhov (dso@usa.net).
5985 These routines are interrupt driven with a 256 byte circular buffer, they
5986 also expect external ram to be present.
5987 Please see documentation in file SDCCDIR/sdcc51lib/serial.c .
5988 Note the header file
5989 \begin_inset Quotes eld
5993 \begin_inset Quotes erd
5996 MUST be included in the file containing the 'main' function.
6005 - Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.co
6006 m> these routines are more compact and faster.
6007 Please see documentation in file SDCCDIR/sdcc51lib/ser.c
6016 - Another alternate set of serial routines provided by Josef Wolf <jw@raven.inka.d
6017 e> , these routines do not use the external ram.
6026 - contains register definitions for a standard 8051
6035 - contains register definitions for 80C552.
6044 - contains min, max and other floating point related stuff.
6047 All library routines are compiled as --model-small , they are all non-reentrant,
6048 if you plan to use the large model or want to make these routines reentrant,
6049 then they will have to be recompiled with the appropriate compiler option.
6052 Have not had time to do the more involved routines like printf, will get
6056 Interfacing with Assembly Routines
6059 Global Registers used for Parameter Passing
6062 By default the compiler uses the global registers
6063 \begin_inset Quotes eld
6067 \begin_inset Quotes erd
6070 to pass the first parameter to a routine, the second parameter onwards
6071 is either allocated on the stack (for reentrant routines or --stack-auto
6072 is used) or in the internal / external ram (depending on the memory model).
6074 \layout Subsubsection
6076 Assembler Routine(non-reentrant)
6079 In the following example the function
6083 calls an assembler routine
6087 , which takes two parameters.
6092 extern int asm_func( unsigned short, unsigned short);
6100 int c_func (unsigned short i, unsigned short j)
6111 return asm_func(i,j);
6126 return c_func(10,9);
6131 The corresponding assembler function is:-
6143 .globl _asm_func_PARM_2
6163 _asm_func_PARM_2:\SpecialChar ~
6249 Note here that the return values are placed in 'dpl' - One byte return value,
6250 'dpl' LSB & 'dph' MSB for two byte values.
6251 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
6252 b' & 'acc' for four byte values.
6255 The parameter naming convention is
6257 _<function_name>_PARM_<n>,
6259 where n is the parameter number starting from 1, and counting from the
6261 The first parameter is passed in
6262 \begin_inset Quotes eld
6266 \begin_inset Quotes erd
6269 for One bye parameter,
6270 \begin_inset Quotes eld
6274 \begin_inset Quotes erd
6278 \begin_inset Quotes eld
6282 \begin_inset Quotes erd
6286 \begin_inset Quotes eld
6290 \begin_inset Quotes erd
6297 varaible name for the second parameter will be _<function_name>_PARM_2.
6300 Assemble the assembler routine with the following command.
6303 asx8051 -losg asmfunc.asm
6306 Then compile and link the assembler routine to the C source file with the
6310 sdcc cfunc.c asmfunc.rel
6311 \layout Subsubsection
6313 Assembler Routine(reentrant)
6316 In this case the second parameter onwards will be passed on the stack ,
6317 the parameters are pushed from right to left i.e.
6318 after the call the left most parameter will be on the top of the stack.
6324 extern int asm_func( unsigned short, unsigned short);
6335 int c_func (unsigned short i, unsigned short j) reentrant
6346 return asm_func(i,j);
6361 return c_func(10,9);
6366 The corresponding assembler routine is.
6543 The compiling and linking procedure remains the same, however note the extra
6544 entry & exit linkage required for the assembler code, _bp is the stack
6545 frame pointer and is used to compute the offset into the stack for parameters
6546 and local variables.
6549 With --noregparms Option
6552 When the source is compiled with --noregparms option , space is allocated
6553 for each of the parameters passed to a routine.
6554 \layout Subsubsection
6556 Assembler Routine Non-reentrant
6559 In the following example the function
6563 calls an assembler routine
6567 , which takes two parameters.
6572 extern int asm_func( unsigned short, unsigned short);
6580 int c_func (unsigned short i, unsigned short j)
6591 return asm_func(i,j);
6606 return c_func(10,9);
6611 The corresponding assembler function is:-
6623 .globl _asm_func_PARM_1
6632 .globl _asm_func_PARM_2
6652 _asm_func_PARM_1:\SpecialChar ~
6664 _asm_func_PARM_2:\SpecialChar ~
6750 Note here that the return values are placed in 'dpl' - One byte return value,
6751 'dpl' LSB & 'dph' MSB for two byte values.
6752 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
6753 b' & 'acc' for four byte values.
6756 The parameter naming convention is
6758 _<function_name>_PARM_<n>,
6760 where n is the parameter number starting from 1, and counting from the
6767 left-most parameter name will be _<function_name>_PARM_1.
6770 Assemble the assembler routine with the following command.
6773 asx8051 -losg asmfunc.asm
6776 Then compile and link the assembler routine to the C source file with the
6780 sdcc cfunc.c asmfunc.rel
6781 \layout Subsubsection
6783 Assembler Routine(reentrant)
6786 In this case the parameters will be passed on the stack , the parameters
6787 are pushed from right to left i.e.
6788 after the call the left most parameter will be on the top of the stack.
6794 extern int asm_func( unsigned short, unsigned short);
6805 int c_func (unsigned short i, unsigned short j) reentrant
6816 return asm_func(i,j);
6831 return c_func(10,9);
6836 The corresponding assembler routine is.
7022 The compiling and linking procedure remains the same, however note the extra
7023 entry & exit linkage required for the assembler code, _bp is the stack
7024 frame pointer and is used to compute the offset into the stack for parameters
7025 and local variables.
7031 The external stack is located at the start of the external ram segment ,
7032 and is 256 bytes in size.
7033 When --xstack option is used to compile the program, the parameters and
7034 local variables of all reentrant functions are allocated in this area.
7035 This option is provided for programs with large stack space requirements.
7036 When used with the --stack-auto option, all parameters and local variables
7037 are allocated on the external stack (note support libraries will need to
7038 be recompiled with the same options).
7041 The compiler outputs the higher order address byte of the external ram segment
7042 into PORT P2, therefore when using the External Stack option, this port
7043 MAY NOT be used by the application program.
7049 Deviations from the compliancy.
7052 functions are not always reentrant.
7055 structures cannot be assigned values directly, cannot be passed as function
7056 parameters or assigned to each other and cannot be a return value from
7081 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
7091 struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
7101 return rets;/* is invalid in SDCC although allowed in ANSI */
7106 'long long' (64 bit integers) not supported.
7109 'double' precision floating point not supported.
7112 integral promotions are suppressed.
7113 What does this mean ? The compiler will not implicitly promote an integer
7114 expression to a higher order integer, exception is an assignment or parameter
7130 Old K&R style function declarations are NOT allowed.
7135 foo( i,j) /* this old style of function declarations */
7137 int i,j; /* are valid in ANSI ..
7138 not valid in SDCC */
7148 functions declared as pointers must be dereferenced during the call.
7167 /* has to be called like this */
7171 (*foo)();/* ansi standard allows calls to be made like 'foo()' */
7174 Cyclomatic Complexity
7177 Cyclomatic complexity of a function is defined as the number of independent
7178 paths the program can take during execution of the function.
7179 This is an important number since it defines the number test cases you
7180 have to generate to validate the function .
7181 The accepted industry standard for complexity number is 10, if the cyclomatic
7182 complexity reported by SDCC exceeds 10 you should think about simplification
7183 of the function logic.
7186 Note that the complexity level is not related to the number of lines of
7188 Large functions can have low complexity, and small functions can have large
7190 SDCC uses the following formula to compute the complexity.
7195 complexity = (number of edges in control flow graph) -
7204 (number of nodes in control flow graph) + 2;
7207 Having said that the industry standard is 10, you should be aware that in
7208 some cases it may unavoidable to have a complexity level of less than 10.
7209 For example if you have switch statement with more than 10 case labels,
7210 each case label adds one to the complexity level.
7211 The complexity level is by no means an absolute measure of the algorithmic
7212 complexity of the function, it does however provide a good starting point
7213 for which functions you might look at for further optimization.
7219 Here are a few guide-lines that will help the compiler generate more efficient
7220 code, some of the tips are specific to this compiler others are generally
7221 good programming practice.
7224 Use the smallest data type to represent your data-value.
7225 If it is known in advance that the value is going to be less than 256 then
7226 use a 'short' or 'char' instead of an 'int'.
7229 Use unsigned when it is known in advance that the value is not going to
7231 This helps especially if you are doing division or multiplication.
7234 NEVER jump into a LOOP.
7237 Declare the variables to be local whenever possible, especially loop control
7238 variables (induction).
7241 Since the compiler does not do implicit integral promotion, the programmer
7242 should do an explicit cast when integral promotion is required.
7245 Reducing the size of division , multiplication & modulus operations can
7246 reduce code size substantially.
7247 Take the following code for example.
7253 foobar( unsigned int p1, unsigned char ch)
7261 unsigned char ch1 = p1 % ch ;
7276 For the modulus operation the variable ch will be promoted to unsigned int
7277 first then the modulus operation will be performed (this will lead to a
7278 call to a support routine).
7279 If the code is changed to
7284 foobar( unsigned int p1, unsigned char ch)
7292 unsigned char ch1 = (unsigned char)p1 % ch ;
7307 It would substantially reduce the code generated (future versions of the
7308 compiler will be smart enough to detect such optimization oppurtunities).
7314 Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
7317 The 8051 family of micro controller have a minimum of 128 bytes of internal
7318 memory which is structured as follows
7321 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
7325 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
7328 - Bytes 30-7F - 60 bytes for general purpose use.
7331 Normally the SDCC compiler will only utilise the first bank of registers,
7332 but it is possible to specify that other banks of registers should be used
7333 in interrupt routines.
7334 By default, the compiler will place the stack after the last bank of used
7336 if the first 2 banks of registers are used, it will position the base of
7337 the internal stack at address 16 (0X10).
7338 This implies that as the stack grows, it will use up the remaining register
7339 banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
7340 general purpose use.
7343 By default, the compiler uses the 60 general purpose bytes to hold "near
7345 The compiler/optimiser may also declare some Local Variables in this area
7350 If any of the 128 bit variables are used, or near data is being used then
7351 care needs to be taken to ensure that the stack does not grow so much that
7352 it starts to over write either your bit variables or "near data".
7353 There is no runtime checking to prevent this from happening.
7356 The amount of stack being used is affected by the use of the "internal stack"
7357 to save registers before a subroutine call is made, - --stack-auto will
7358 declare parameters and local variables on the stack - the number of nested
7362 If you detect that the stack is over writing you data, then the following
7364 --xstack will cause an external stack to be used for saving registers and
7365 (if --stack-auto is being used) storing parameters and local variables.
7366 However this will produce more and code which will be slower to execute.
7370 --stack-loc will allow you specify the start of the stack, i.e.
7371 you could start it after any data in the general purpose area.
7372 However this may waste the memory not used by the register banks and if
7373 the size of the "near data" increases, it may creep into the bottom of
7377 --stack-after-data, similar to the --stack-loc, but it automatically places
7378 the stack after the end of the "near data".
7379 Again this could waste any spare register space.
7382 --data-loc allows you to specify the start address of the near data.
7383 This could be used to move the "near data" further away from the stack
7384 giving it more room to grow.
7385 This will only work if no bit variables are being used and the stack can
7386 grow to use the bit variable space.
7392 If you find that the stack is over writing your bit variables or "near data"
7393 then the approach which best utilised the internal memory is to position
7394 the "near data" after the last bank of used registers or, if you use bit
7395 variables, after the last bit variable by using the --data-loc, e.g.
7396 if two register banks are being used and no data variables, --data-loc
7397 16, and - use the --stack-after-data option.
7400 If bit variables are being used, another method would be to try and squeeze
7401 the data area in the unused register banks if it will fit, and start the
7402 stack after the last bit variable.
7405 Retargetting for other MCUs.
7408 The issues for retargetting the compiler are far too numerous to be covered
7410 What follows is a brief description of each of the seven phases of the
7411 compiler and its MCU dependency.
7414 Parsing the source and building the annotated parse tree.
7415 This phase is largely MCU independent (except for the language extensions).
7416 Syntax & semantic checks are also done in this phase , along with some
7417 initial optimizations like back patching labels and the pattern matching
7418 optimizations like bit-rotation etc.
7421 The second phase involves generating an intermediate code which can be easy
7422 manipulated during the later phases.
7423 This phase is entirely MCU independent.
7424 The intermediate code generation assumes the target machine has unlimited
7425 number of registers, and designates them with the name iTemp.
7426 The compiler can be made to dump a human readable form of the code generated
7427 by using the --dumpraw option.
7430 This phase does the bulk of the standard optimizations and is also MCU independe
7432 This phase can be broken down into several sub-phases.
7436 Break down intermediate code (iCode) into basic blocks.
7439 Do control flow & data flow analysis on the basic blocks.
7442 Do local common subexpression elimination, then global subexpression elimination
7445 dead code elimination
7451 if loop optimizations caused any changes then do 'global subexpression eliminati
7452 on' and 'dead code elimination' again.
7456 This phase determines the live-ranges; by live range I mean those iTemp
7457 variables defined by the compiler that still survive after all the optimization
7459 Live range analysis is essential for register allocation, since these computati
7460 on determines which of these iTemps will be assigned to registers, and for
7464 Phase five is register allocation.
7465 There are two parts to this process .
7469 The first part I call 'register packing' (for lack of a better term) .
7470 In this case several MCU specific expression folding is done to reduce
7474 The second part is more MCU independent and deals with allocating registers
7475 to the remaining live ranges.
7476 A lot of MCU specific code does creep into this phase because of the limited
7477 number of index registers available in the 8051.
7481 The Code generation phase is (unhappily), entirely MCU dependent and very
7482 little (if any at all) of this code can be reused for other MCU.
7483 However the scheme for allocating a homogenized assembler operand for each
7484 iCode operand may be reused.
7487 As mentioned in the optimization section the peep-hole optimizer is rule
7488 based system, which can reprogrammed for other MCUs.
7491 SDCDB - Source Level Debugger
7494 SDCC is distributed with a source level debugger.
7495 The debugger uses a command line interface, the command repertoire of the
7496 debugger has been kept as close to gdb ( the GNU debugger) as possible.
7497 The configuration and build process is part of the standard compiler installati
7498 on, which also builds and installs the debugger in the target directory
7499 specified during configuration.
7500 The debugger allows you debug BOTH at the C source and at the ASM source
7504 Compiling for Debugging
7511 option must be specified for all files for which debug information is to
7513 The complier generates a
7517 file for each of these files.
7518 The linker updates the
7522 file with the address information.
7523 This .cdb is used by the debugger .
7526 How the Debugger Works
7533 option is specified the compiler generates extra symbol information some
7534 of which are put into the the assembler source and some are put into the
7535 .cdb file, the linker updates the .cdb file with the address information
7537 The debugger reads the symbolic information generated by the compiler &
7538 the address information generated by the linker.
7539 It uses the SIMULATOR (Daniel's S51) to execute the program, the program
7540 execution is controlled by the debugger.
7541 When a command is issued for the debugger, it translates it into appropriate
7542 commands for the simulator .
7545 Starting the Debugger
7548 The debugger can be started using the following command line.
7549 (Assume the file you are debugging has
7558 The debugger will look for the following files.
7561 foo.c - the source file.
7564 foo.cdb - the debugger symbol information file.
7567 foo.ihx - the intel hex format object file.
7570 Command Line Options.
7573 --directory=<source file directory> this option can used to specify the
7574 directory search list.
7575 The debugger will look into the directory list specified for source , cdb
7577 The items in the directory list must be separated by ':' , e.g.
7578 if the source files can be in the directories /home/src1 and /home/src2,
7579 the --directory option should be --directory=/home/src1:/home/src2 .
7580 Note there can be no spaces in the option.
7584 -cd <directory> - change to the <directory>.
7587 -fullname - used by GUI front ends.
7590 -cpu <cpu-type> - this argument is passed to the simulator please see the
7591 simulator docs for details.
7594 -X <Clock frequency > this options is passed to the simulator please see
7595 simulator docs for details.
7598 -s <serial port file> passed to simulator see simulator docs for details.
7601 -S <serial in,out> passed to simulator see simulator docs for details.
7607 As mention earlier the command interface for the debugger has been deliberately
7608 kept as close the GNU debugger gdb , as possible, this will help int integratio
7609 n with existing graphical user interfaces (like ddd, xxgdb or xemacs) existing
7610 for the GNU debugger.
7611 \layout Subsubsection
7613 break [line | file:line | function | file:function]
7616 Set breakpoint at specified line or function.
7621 sdcdb>break foo.c:100
7625 sdcdb>break foo.c:funcfoo
7626 \layout Subsubsection
7628 clear [line | file:line | function | file:function ]
7631 Clear breakpoint at specified line or function.
7636 sdcdb>clear foo.c:100
7640 sdcdb>clear foo.c:funcfoo
7641 \layout Subsubsection
7646 Continue program being debugged, after breakpoint.
7647 \layout Subsubsection
7652 Execute till the end of the current function.
7653 \layout Subsubsection
7658 Delete breakpoint number 'n'.
7659 If used without any option clear ALL user defined break points.
7660 \layout Subsubsection
7662 info [break | stack | frame | registers ]
7665 info break - list all breakpoints
7668 info stack - show the function call stack.
7671 info frame - show information about the current execution frame.
7674 info registers - show content of all registers.
7675 \layout Subsubsection
7680 Step program until it reaches a different source line.
7681 \layout Subsubsection
7686 Step program, proceeding through subroutine calls.
7687 \layout Subsubsection
7692 Start debugged program.
7693 \layout Subsubsection
7698 Print type information of the variable.
7699 \layout Subsubsection
7704 print value of variable.
7705 \layout Subsubsection
7710 load the given file name.
7711 Note this is an alternate method of loading file for debugging.
7712 \layout Subsubsection
7717 print information about current frame.
7718 \layout Subsubsection
7723 Toggle between C source & assembly source.
7724 \layout Subsubsection
7729 Send the string following '!' to the simulator, the simulator response is
7731 Note the debugger does not interpret the command being sent to the simulator,
7732 so if a command like 'go' is sent the debugger can loose its execution
7733 context and may display incorrect values.
7734 \layout Subsubsection
7741 My name is Bobby Brown"
7744 Interfacing with XEmacs.
7747 Two files are (in emacs lisp) are provided for the interfacing with XEmacs,
7756 These two files can be found in the $(prefix)/bin directory after the installat
7758 These files need to be loaded into XEmacs for the interface to work, this
7759 can be done at XEmacs startup time by inserting the following into your
7764 file (which can be found in your HOME directory)
7766 (load-file sdcdbsrc.el)
7768 [ .xemacs is a lisp file so the () around the command is REQUIRED), the files
7769 can also be loaded dynamically while XEmacs is running, set the environment
7774 to the installation bin directory [$(prefix)/bin], then enter the following
7777 ESC-x load-file sdcdbsrc .
7780 To start the interface enter the following command
7784 , you will prompted to enter the file name to be debugged.
7788 The command line options that are passed to the simulator directly are bound
7789 to default values in the file
7793 the variables are listed below these values maybe changed as required.
7796 sdcdbsrc-cpu-type '51
7799 sdcdbsrc-frequency '11059200
7805 The following is a list of key mapping for the debugger interface.
7813 ;; Current Listing ::
7830 binding\SpecialChar ~
7869 -------\SpecialChar ~
7909 sdcdb-next-from-src\SpecialChar ~
7935 sdcdb-back-from-src\SpecialChar ~
7961 sdcdb-cont-from-src\SpecialChar ~
7971 SDCDB continue command
7987 sdcdb-step-from-src\SpecialChar ~
8013 sdcdb-whatis-c-sexp\SpecialChar ~
8023 SDCDB ptypecommand for data at
8083 sdcdbsrc-delete\SpecialChar ~
8097 SDCDB Delete all breakpoints if no arg
8145 given or delete arg (C-u arg x)
8161 sdcdbsrc-frame\SpecialChar ~
8176 SDCDB Display current frame if no arg,
8224 given or display frame arg
8287 sdcdbsrc-goto-sdcdb\SpecialChar ~
8297 Goto the SDCDB output buffer
8313 sdcdb-print-c-sexp\SpecialChar ~
8324 SDCDB print command for data at
8384 sdcdbsrc-goto-sdcdb\SpecialChar ~
8394 Goto the SDCDB output buffer
8410 sdcdbsrc-mode\SpecialChar ~
8426 Toggles Sdcdbsrc mode (turns it off)
8430 ;; C-c C-f\SpecialChar ~
8438 sdcdb-finish-from-src\SpecialChar ~
8446 SDCDB finish command
8450 ;; C-x SPC\SpecialChar ~
8458 sdcdb-break\SpecialChar ~
8476 Set break for line with point
8478 ;; ESC t\SpecialChar ~
8488 sdcdbsrc-mode\SpecialChar ~
8504 Toggle Sdcdbsrc mode
8506 ;; ESC m\SpecialChar ~
8516 sdcdbsrc-srcmode\SpecialChar ~
8538 The Z80 and gbz80 port
8541 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
8542 The port is incomplete - long support is incomplete (mul, div and mod are
8543 unimplimented), and both float and bitfield support is missing, but apart
8544 from that the code generated is correct.
8547 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
8548 The stack frame is similar to that generated by the IAR Z80 compiler.
8549 IX is used as the base pointer, HL is used as a temporary register, and
8550 BC and DE are available for holding varibles.
8551 IY is currently unusued.
8552 Return values are stored in HL.
8553 One bad side effect of using IX as the base pointer is that a functions
8554 stack frame is limited to 127 bytes - this will be fixed in a later version.
8560 SDCC has grown to be large project, the compiler alone (without the Assembler
8561 Package, Preprocessor) is about 40,000 lines of code (blank stripped).
8562 The open source nature of this project is a key to its continued growth
8564 You gain the benefit and support of many active software developers and
8566 Is SDCC perfect? No, that's why we need your help.
8567 The developers take pride in fixing reported bugs.
8568 You can help by reporting the bugs and helping other SDCC users.
8569 There are lots of ways to contribute, and we encourage you to take part
8570 in making SDCC a great software package.
8576 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd
8577 cc@sdcc.sourceforge.net'.
8578 Bugs will be fixed ASAP.
8579 When reporting a bug, it is very useful to include a small test program
8580 which reproduces the problem.
8581 If you can isolate the problem by looking at the generated assembly code,
8582 this can be very helpful.
8583 Compiling your program with the --dumpall option can sometimes be useful
8584 in locating optimization problems.
8590 Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code generator,
8593 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX & ASLINK.
8596 John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for 8051
8599 Obukhov (dso@usa.net) - malloc & serial i/o routines.
8602 Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware simulator
8604 Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience and support.
8606 Unknown - for the GNU C - preprocessor.
8608 Michael Hope - The Z80 and Z80GB port, 186 development
8610 Kevin Vigor - The DS390 port.
8612 Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
8614 Scott Datallo - PIC port.
8616 (Thanks to all the other volunteer developers who have helped with coding,
8617 testing, web-page creation, distribution sets, etc.
8618 You know who you are :-)
8623 This document initially written by Sandeep Dutta
8626 All product names mentioned herein may be trademarks of their respective
8632 \begin_inset LatexCommand \index{}