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 swedish
23 \paperpagestyle default
27 lSDCC Compiler User Guide
31 \begin_inset LatexCommand \tableofcontents{}
46 <pending: tabularise these features, this is unreadeble>
55 is a Free ware, retargettable, optimizing ANSI-C compiler by
59 designed for 8 bit Microprocessors.
60 The current version targets Intel MCS51 based Microprocessors(8051,8052,
61 etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51 variant.
62 It can be retargetted for other microprocessors, support for PIC, AVR and
63 186 is under development.
64 The entire source code for the compiler is distributed under GPL.
65 SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
66 SDCC has extensive language extensions suitable for utilizing various microcont
67 rollers underlying hardware effectively.
68 In addition to the MCU specific optimizations SDCC also does a host of
69 standard optimizations like
71 global sub expression elimination, loop optimizations (loop invariant,
72 strength reduction of induction variables and loop reversing), constant
73 folding & propagation, copy propagation, dead code elimination and jumptables
74 for 'switch' statements.
77 For the back-end SDCC uses a global register allocation scheme which should
78 be well suited for other 8 bit MCUs.
79 The peep hole optimizer uses a rule based substitution mechanism which
81 Supported data-types are
83 char (8 bits, 1 byte), short and int (16 bits, 2 bytes), long (32 bit, 4
91 The compiler also allows
95 to be embedded anywhere in a function.
96 In addition routines developed in assembly can also be called.
97 SDCC also provides an option to report the relative complexity of a function,
98 these functions can then be further optimized, or hand coded in assembly
100 SDCC also comes with a companion source level debugger SDCDB, the debugger
101 currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
102 The latest version can be downloaded from
105 \begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
115 All packages used in this compiler system are
123 ; source code for all the sub-packages (asxxxx assembler/linker, pre-processor)
124 is distributed with the package.
125 This documentation is maintained using a freeware word processor (LyX).
129 This program is free software; you can redistribute it and/or modify it
130 under the terms of the GNU General Public License as published by the Free
131 Software Foundation; either version 2, or (at your option) any later version.
132 This program is distributed in the hope that it will be useful, but WITHOUT
133 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
134 FOR A PARTICULAR PURPOSE.
135 See the GNU General Public License for more details.
136 You should have received a copy of the GNU General Public License along
137 with this program; if not, write to the Free Software Foundation, 59 Temple
138 Place - Suite 330, Boston, MA 02111-1307, USA.
139 In other words, you are welcome to use, share and improve this program.
140 You are forbidden to forbid anyone else to use, share and improve what
142 Help stamp out software-hoarding!
148 <pending: add a link to gnu>
151 Typographic conventions
154 Throughout this manual, we will use the following convention.
155 Commands you have to type in are printed in
163 Code samples are printed in
168 Interesting items and new terms are printed in
173 Pending: compatibilaty with previous versions
176 This version has numerous bug fixes comperated with the previous version.
177 But we also introduced some incompatibilaties with older versions.
178 Not just for the fun of it, but to make the compiler more stable, efficient
186 directory structure (2.7)
188 vararg pars expl int unless casted
190 never had a regextend
192 no --noreparms anymore
202 What do you need before you start installation of SDCC? A computer, and
204 The preferred method of installation is to compile SDCC from source using
206 For Windows some pre-compiled binary distributions are available for your
208 You should have some experience with command line tools and compiler use.
214 The SDCC home page at
215 \begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
219 is a great place to find distribution sets.
220 You can also find links to the user mailing lists that offer help or discuss
221 SDCC with other SDCC users.
222 Web links to other SDCC related sites can also be found here.
223 This document can be found in the DOC directory of the source package as
225 Some of the other tools (simulator and assembler) included with SDCC contain
226 their own documentation and can be found in the source distribution.
227 If you want the latest unreleased software, the complete source package
228 is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
234 Linux/Unix Installation
239 Download the source package, it will be named something like sdcc-2.x.x.tgz.
244 Bring up a command line terminal, such as xterm.
249 Unpack the file using a command like:
252 "tar -xzf sdcc-2.x.x.tgz"
255 , this will create a sub-directory called sdcc with all of the sources.
258 Change directory into the main SDCC directory, for example type:
275 This configures the package for compilation on your system.
289 All of the source packages will compile, this can take a while.
305 This copies the binary executables to the install directories.
313 <pending: is this complete? where is borland, mingw>
319 For installation under Windows you first need to pick between a pre-compiled
320 binary package, or installing the source package along with the Cygwin
322 The binary package is the quickest to install, while the Cygwin package
323 includes all of the open source power tools used to compile the complete
324 SDCC source package in the Windows environment.
325 If you are not familiar with the Unix command line environment, you may
326 want to read the section on additional information for Windows users prior
327 to your initial installation.
328 \layout Subsubsection
330 Windows Install Using a Binary Package
333 Download the binary package and unpack it using your favorite unpacking
334 tool (gunzip, WinZip, etc).
335 This should unpack to a group of sub-directories.
336 An example directory structure after unpacking is: c:
342 bin for the executables, c:
362 lib for the include and libraries.
365 Adjust your environment PATH to include the location of the bin directory.
366 For example, make a setsdcc.bat file with the following: set PATH=c:
375 When you compile with sdcc, you may need to specify the location of the
376 lib and include folders.
377 For example, sdcc -I c:
400 \layout Subsubsection
402 Windows Install Using Cygwin
407 Download and install the cygwin package from the redhat site
410 \begin_inset LatexCommand \htmlurl{http://sources.redhat.com/cygwin/}
417 Currently, this involved downloading a small install program which then
418 automates downloading and installing
424 (a large 80M byte sized dowload for the whole thing)
438 command line terminal from the Cygwin menu.
443 Follow the instructions in the preceding Linux/Unix installation section.
446 Testing out the SDCC Compiler
449 The first thing you should do after installing your SDCC compiler is to
457 at the prompt, and the program should run and tell you the version.
458 If it doesn't run, or gives a message about not finding sdcc program, then
459 you need to check over your installation.
460 Make sure that the sdcc bin directory is in your executable search path
461 defined by the PATH environment setting (see the Trouble-shooting section
463 Make sure that the sdcc program is in the bin folder, if not perhaps something
464 did not install correctly.
470 SDCC binaries are commonly installed in a directory arrangement like this:
479 <lyxtabular version="2" rows="3" columns="2">
480 <features rotate="false" islongtable="false" endhead="0" endfirsthead="0" endfoot="0" endlastfoot="0">
481 <column alignment="left" valignment="top" leftline="true" rightline="false" width="" special="">
482 <column alignment="left" valignment="top" leftline="true" rightline="true" width="" special="">
483 <row topline="true" bottomline="true" newpage="false">
484 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
494 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
501 Holds executables(sdcc, s51, aslink,
509 <row topline="true" bottomline="false" newpage="false">
510 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
517 usr/local/share/sdcc/lib
520 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
533 <row topline="true" bottomline="true" newpage="false">
534 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
541 usr/local/share/sdcc/include
544 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
551 Holds common C header files
565 Make sure the compiler works on a very simple example.
566 Type in the following test.c program using your favorite editor:
577 Compile this using the following command:
585 If all goes well, the compiler will generate a test.asm and test.rel file.
586 Congratulations, you've just compiled your first program with SDCC.
587 We used the -c option to tell SDCC not to link the generated code, just
588 to keep things simple for this step.
596 The next step is to try it with the linker.
604 If all goes well the compiler will link with the libraries and produce
605 a test.ihx output file.
610 (no test.ihx, and the linker generates warnings), then the problem is most
611 likely that sdcc cannot find the
615 usr/local/share/sdcc/lib directory
619 (see the Install trouble-shooting section for suggestions).
627 The final test is to ensure sdcc can use the
631 header files and libraries.
632 Edit test.c and change it to the following:
650 strcpy(str1, "testing");
659 Compile this by typing
666 This should generate a test.ihx output file, and it should give no warnings
667 such as not finding the string.h file.
668 If it cannot find the string.h file, then the problem is that sdcc cannot
669 find the /usr/local/share/sdcc/include directory
673 (see the Install trouble-shooting section for suggestions).
676 Install Trouble-shooting
677 \layout Subsubsection
679 SDCC cannot find libraries or header files.
682 The default installation assumes the libraries and header files are located
684 \begin_inset Quotes eld
687 /usr/local/share/sdcc/lib
688 \begin_inset Quotes erd
692 \begin_inset Quotes eld
695 /usr/local/share/sdcc/include
696 \begin_inset Quotes erd
700 An alternative is to specify these locations as compiler options like this:
706 /usr/local/sdcc/lib/small\SpecialChar ~
708 /usr/local/sdcc/include\SpecialChar ~
713 \layout Subsubsection
715 SDCC does not compile correctly.
718 A thing to try is starting from scratch by unpacking the .tgz source package
719 again in an empty directory.
720 Confure it again and build like:
727 make 2&>1 | tee make.log
734 After this you can review the make.log file to locate the problem.
735 Or a relevant part of this be attached to an email that could be helpful
736 when requesting help from the mailing list.
737 \layout Subsubsection
740 \begin_inset Quotes sld
744 \begin_inset Quotes srd
751 \begin_inset Quotes sld
755 \begin_inset Quotes srd
758 command is a script that analyzes your system and performs some configuration
759 to ensure the source package compiles on your system.
760 It will take a few minutes to run, and will compile a few tests to determine
761 what compiler features are installed.
762 \layout Subsubsection
765 \begin_inset Quotes sld
769 \begin_inset Quotes srd
775 This runs the GNU make tool, which automatically compiles all the source
776 packages into the final installed binary executables.
777 \layout Subsubsection
780 \begin_inset Quotes sld
784 \begin_inset Quotes erd
790 This will install the compiler, other executables and libraries in to the
791 appropriate system directories.
792 The default is to copy the executables to /usr/local/bin and the libraries
793 and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
796 Additional Information for Windows Users
801 <pending: is this up to date?>
807 The standard method of installing on a Unix system involves compiling the
809 This is easily done under Unix, but under Windows it can be a more difficult
811 The Cygwin is a large package to download, and the compilation runs considerabl
812 y slower under Windows due to the overhead of the Cygwin tool set.
813 An alternative is to install a pre-compiled Windows binary package.
814 There are various trade-offs between each of these methods.
818 The Cygwin package allows a Windows user to run a Unix command line interface
819 (bash shell) and also implements a Unix like file system on top of Windows.
820 Included are many of the famous GNU software development tools which can
821 augment the SDCC compiler.This is great if you have some experience with
822 Unix command line tools and file system conventions, if not you may find
823 it easier to start by installing a binary Windows package.
824 The binary packages work with the Windows file system conventions.
825 \layout Subsubsection
827 Getting started with Cygwin
830 SDCC is typically distributed as a tarred/gzipped file (.tgz).
831 This is a packed file similar to a .zip file.
832 Cygwin includes the tools you will need to unpack the SDCC distribution
834 To unpack it, simply follow the instructions under the Linux/Unix install
836 Before you do this you need to learn how to start a cygwin shell and some
837 of the basic commands used to move files, change directory, run commands
839 The change directory command is
843 \begin_inset Quotes eld
847 \begin_inset Quotes erd
853 , the move command is
857 \begin_inset Quotes eld
861 \begin_inset Quotes erd
868 To print the current working directory, type
872 \begin_inset Quotes eld
876 \begin_inset Quotes erd
883 To make a directory, use
887 \begin_inset Quotes eld
891 \begin_inset Quotes erd
900 There are some basic differences between Unix and Windows file systems you
902 When you type in directory paths, Unix and the Cygwin bash prompt uses
903 forward slashes '/' between directories while Windows traditionally uses
907 So when you work at the Cygwin bash prompt, you will need to use the forward
909 Unix does not have a concept of drive letters, such as
910 \begin_inset Quotes eld
914 \begin_inset Quotes eld
917 , instead all files systems attach and appear as directories.
918 \layout Subsubsection
920 Running SDCC as Native Compiled Executables
923 If you use the pre-compiled binaries, the install directories for the libraries
924 and header files may need to be specified on the sdcc command line like
949 if you are running outside of a Unix bash shell.
952 If you have successfully installed and compiled SDCC with the Cygwin package,
953 it is possible to compile into native .exe files by using the additional
954 makefiles included for this purpose.
955 For example, with the Borland 32-bit compiler you would run
958 "make -f Makefile.bcc"
962 A command line version of the Borland 32-bit compiler can be downloaded
963 from the Inprise web site.
966 SDCC on Other Platforms
971 FreeBSD and other non-GNU Unixes
973 - Make sure the GNU make is installed as the default make tool.
976 SDCC has been ported to run under a variety of operating systems and processors.
977 If you can run GNU GCC/make then chances are good SDCC can be compiled
978 and run on your system.
981 Advanced Install Options
985 \begin_inset Quotes eld
989 \begin_inset Quotes erd
992 command has several options.
993 The most commonly used option is --prefix=<directory name>, where <directory
994 name> is the final location for the sdcc executables and libraries, (default
995 location is /usr/local).
996 The installation process will create the following directory structure
997 under the <directory name> specified (if they do not already exist).
1002 bin/ - binary exectables (add to PATH environment variable)
1006 bin/share/sdcc/include/ - include header files
1010 bin/share/sdcc/lib/small/ - Object & library files for small model library
1012 bin/share/sdcc/lib/large/ - Object & library files for large model library
1014 bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390 library
1022 \begin_inset Quotes sld
1025 ./configure --prefix=/usr/local
1026 \begin_inset Quotes erd
1032 will configure the compiler to be installed in directory /usr/local/bin.
1038 SDCC is not just a compiler, but a collection of tools by various developers.
1039 These include linkers, assemblers, simulators and other components.
1040 Here is a summary of some of the components.
1041 Note that the included simulator and assembler have separate documentation
1042 which you can find in the source package in their respective directories.
1043 As SDCC grows to include support for other processors, other packages from
1044 various developers are included and may have their own sets of documentation.
1047 You might want to look at the various executables which are installed in
1049 At the time of this writing, we find the following programs:
1055 <pending: tabularize this>
1071 - The C preprocessor.
1077 - The assembler for 8051 type processors.
1083 - The Z80 and GameBoy Z80 assemblers.
1089 -The linker for 8051 type processors.
1093 link-z80, link-gbz80
1095 - The Z80 and GameBoy Z80 linkers.
1101 - The ucSim 8051 simulator.
1107 - The source debugger.
1113 - A tool to pack Intel hex files.
1117 As development for other processors proceeds, this list will expand to include
1118 executables to support processors like AVR, PIC, etc.
1119 \layout Subsubsection
1124 This is the actual compiler, it in turn uses the c-preprocessor and invokes
1125 the assembler and linkage editor.
1126 \layout Subsubsection
1128 sdcpp (C-Preprocessor)
1131 The preprocessor is a modified version of the GNU preprocessor.
1132 The C preprocessor is used to pull in #include sources, process #ifdef
1133 statements, #defines and so on.
1134 \layout Subsubsection
1136 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 (The Assemblers
1137 and Linkage Editors)
1140 This is retargettable assembler & linkage editor, it was developed by Alan
1142 John Hartman created the version for 8051, and I (Sandeep) have made some
1143 enhancements and bug fixes for it to work properly with the SDCC.
1144 \layout Subsubsection
1149 S51 is a freeware, opensource simulator developed by Daniel Drotos (
1150 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
1155 The simulator is built as part of the build process.
1156 For more information visit Daniel's website at:
1157 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
1162 \layout Subsubsection
1164 sdcdb - Source Level Debugger
1167 Sdcdb is the companion source level debugger.
1168 The current version of the debugger uses Daniel's Simulator S51, but can
1169 be easily changed to use other simulators.
1176 \layout Subsubsection
1178 Single Source File Projects
1181 For single source file 8051 projects the process is very simple.
1182 Compile your programs with the following command
1185 "sdcc sourcefile.c".
1189 This will compile, assemble and link your source file.
1190 Output files are as follows
1194 sourcefile.asm - Assembler source file created by the compiler
1196 sourcefile.lst - Assembler listing file created by the Assembler
1198 sourcefile.rst - Assembler listing file updated with linkedit information,
1199 created by linkage editor
1201 sourcefile.sym - symbol listing for the sourcefile, created by the assembler
1203 sourcefile.rel - Object file created by the assembler, input to Linkage editor
1205 sourcefile.map - The memory map for the load module, created by the Linker
1207 sourcefile.ihx - The load module in Intel hex format (you can select the
1208 Motorola S19 format with --out-fmt-s19)
1210 sourcefile.cdb - An optional file (with --debug) containing debug information
1213 \layout Subsubsection
1215 Projects with Multiple Source Files
1218 SDCC can compile only ONE file at a time.
1219 Let us for example assume that you have a project containing the following
1224 foo1.c (contains some functions)
1226 foo2.c (contains some more functions)
1228 foomain.c (contains more functions and the function main)
1236 The first two files will need to be compiled separately with the commands:
1268 Then compile the source file containing the
1272 function and link the files together with the following command:
1280 foomain.c\SpecialChar ~
1281 foo1.rel\SpecialChar ~
1293 can be separately compiled as well:
1304 sdcc foomain.rel foo1.rel foo2.rel
1311 The file containing the
1326 file specified in the command line, since the linkage editor processes
1327 file in the order they are presented to it.
1328 \layout Subsubsection
1330 Projects with Additional Libraries
1333 Some reusable routines may be compiled into a library, see the documentation
1334 for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
1340 Libraries created in this manner can be included in the command line.
1341 Make sure you include the -L <library-path> option to tell the linker where
1342 to look for these files if they are not in the current directory.
1343 Here is an example, assuming you have the source file
1355 (if that is not the same as your current project):
1362 sdcc foomain.c foolib.lib -L mylib
1373 must be an absolute path name.
1377 The most efficient way to use libraries is to keep seperate modules in seperate
1379 The lib file now should name all the modules.rel files.
1380 For an example see the standard library file
1384 in the directory <installdir>/share/lib/small.
1387 Command Line Options
1388 \layout Subsubsection
1390 Processor Selection Options
1392 \labelwidthstring 00.00.0000
1398 Generate code for the MCS51 (8051) family of processors.
1399 This is the default processor target.
1401 \labelwidthstring 00.00.0000
1407 Generate code for the DS80C390 processor.
1409 \labelwidthstring 00.00.0000
1415 Generate code for the Z80 family of processors.
1417 \labelwidthstring 00.00.0000
1423 Generate code for the GameBoy Z80 processor.
1425 \labelwidthstring 00.00.0000
1431 Generate code for the Atmel AVR processor(In development, not complete).
1433 \labelwidthstring 00.00.0000
1439 Generate code for the PIC 14-bit processors(In development, not complete).
1441 \labelwidthstring 00.00.0000
1447 Generate code for the Toshiba TLCS-900H processor(In development, not complete).
1448 \layout Subsubsection
1450 Preprocessor Options
1452 \labelwidthstring 00.00.0000
1458 The additional location where the pre processor will look for <..h> or
1459 \begin_inset Quotes eld
1463 \begin_inset Quotes erd
1468 \labelwidthstring 00.00.0000
1474 Command line definition of macros.
1475 Passed to the pre processor.
1477 \labelwidthstring 00.00.0000
1483 Tell the preprocessor to output a rule suitable for make describing the
1484 dependencies of each object file.
1485 For each source file, the preprocessor outputs one make-rule whose target
1486 is the object file name for that source file and whose dependencies are
1487 all the files `#include'd in it.
1488 This rule may be a single line or may be continued with `
1490 '-newline if it is long.
1491 The list of rules is printed on standard output instead of the preprocessed
1495 \labelwidthstring 00.00.0000
1501 Tell the preprocessor not to discard comments.
1502 Used with the `-E' option.
1504 \labelwidthstring 00.00.0000
1515 Like `-M' but the output mentions only the user header files included with
1517 \begin_inset Quotes eld
1521 System header files included with `#include <file>' are omitted.
1523 \labelwidthstring 00.00.0000
1529 Assert the answer answer for question, in case it is tested with a preprocessor
1530 conditional such as `#if #question(answer)'.
1531 `-A-' disables the standard assertions that normally describe the target
1534 \labelwidthstring 00.00.0000
1540 (answer) Assert the answer answer for question, in case it is tested with
1541 a preprocessor conditional such as `#if #question(answer)'.
1542 `-A-' disables the standard assertions that normally describe the target
1545 \labelwidthstring 00.00.0000
1551 Undefine macro macro.
1552 `-U' options are evaluated after all `-D' options, but before any `-include'
1553 and `-imacros' options.
1555 \labelwidthstring 00.00.0000
1561 Tell the preprocessor to output only a list of the macro definitions that
1562 are in effect at the end of preprocessing.
1563 Used with the `-E' option.
1565 \labelwidthstring 00.00.0000
1571 Tell the preprocessor to pass all macro definitions into the output, in
1572 their proper sequence in the rest of the output.
1574 \labelwidthstring 00.00.0000
1585 Like `-dD' except that the macro arguments and contents are omitted.
1586 Only `#define name' is included in the output.
1587 \layout Subsubsection
1591 \labelwidthstring 00.00.0000
1601 <absolute path to additional libraries> This option is passed to the linkage
1602 editor's additional libraries search path.
1603 The path name must be absolute.
1604 Additional library files may be specified in the command line.
1605 See section Compiling programs for more details.
1607 \labelwidthstring 00.00.0000
1613 <Value> The start location of the external ram, default value is 0.
1614 The value entered can be in Hexadecimal or Decimal format, e.g.: --xram-loc
1615 0x8000 or --xram-loc 32768.
1617 \labelwidthstring 00.00.0000
1623 <Value> The start location of the code segment, default value 0.
1624 Note when this option is used the interrupt vector table is also relocated
1625 to the given address.
1626 The value entered can be in Hexadecimal or Decimal format, e.g.: --code-loc
1627 0x8000 or --code-loc 32768.
1629 \labelwidthstring 00.00.0000
1635 <Value> The initial value of the stack pointer.
1636 The default value of the stack pointer is 0x07 if only register bank 0
1637 is used, if other register banks are used then the stack pointer is initialized
1638 to the location above the highest register bank used.
1640 if register banks 1 & 2 are used the stack pointer will default to location
1642 The value entered can be in Hexadecimal or Decimal format, eg.
1643 --stack-loc 0x20 or --stack-loc 32.
1644 If all four register banks are used the stack will be placed after the
1645 data segment (equivalent to --stack-after-data)
1647 \labelwidthstring 00.00.0000
1653 This option will cause the stack to be located in the internal ram after
1656 \labelwidthstring 00.00.0000
1662 <Value> The start location of the internal ram data segment, the default
1663 value is 0x30.The value entered can be in Hexadecimal or Decimal format,
1665 --data-loc 0x20 or --data-loc 32.
1667 \labelwidthstring 00.00.0000
1673 <Value> The start location of the indirectly addressable internal ram, default
1675 The value entered can be in Hexadecimal or Decimal format, eg.
1676 --idata-loc 0x88 or --idata-loc 136.
1678 \labelwidthstring 00.00.0000
1687 The linker output (final object code) is in Intel Hex format.
1688 (This is the default option).
1690 \labelwidthstring 00.00.0000
1699 The linker output (final object code) is in Motorola S19 format.
1700 \layout Subsubsection
1704 \labelwidthstring 00.00.0000
1710 Generate code for Large model programs see section Memory Models for more
1712 If this option is used all source files in the project should be compiled
1714 In addition the standard library routines are compiled with small model,
1715 they will need to be recompiled.
1717 \labelwidthstring 00.00.0000
1728 Generate code for Small Model programs see section Memory Models for more
1730 This is the default model.
1731 \layout Subsubsection
1735 \labelwidthstring 00.00.0000
1746 Generate 24-bit flat mode code.
1747 This is the one and only that the ds390 code generator supports right now
1748 and is default when using
1753 See section Memory Models for more details.
1755 \labelwidthstring 00.00.0000
1761 Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
1762 This is the one and only that the ds390 code generator supports right now
1763 and is default when using
1768 In this mode, the stack is located in the lower 1K of the internal RAM,
1769 which is mapped to 0x400000.
1770 Note that the support is incomplete, since it still uses a single byte
1771 as the stack pointer.
1772 This means that only the lower 256 bytes of the potential 1K stack space
1773 will actually be used.
1774 However, this does allow you to reclaim the precious 256 bytes of low RAM
1775 for use for the DATA and IDATA segments.
1776 The compiler will not generate any code to put the processor into 10 bit
1778 It is important to ensure that the processor is in this mode before calling
1779 any re-entrant functions compiled with this option.
1780 In principle, this should work with the
1784 option, but that has not been tested.
1785 It is incompatible with the
1790 It also only makes sense if the processor is in 24 bit contiguous addressing
1793 --model-flat24 option
1796 \layout Subsubsection
1798 Optimization Options
1800 \labelwidthstring 00.00.0000
1806 Will not do global subexpression elimination, this option may be used when
1807 the compiler creates undesirably large stack/data spaces to store compiler
1809 A warning message will be generated when this happens and the compiler
1810 will indicate the number of extra bytes it allocated.
1811 It recommended that this option NOT be used, #pragma\SpecialChar ~
1813 to turn off global subexpression elimination for a given function only.
1815 \labelwidthstring 00.00.0000
1821 Will not do loop invariant optimizations, this may be turned off for reasons
1822 explained for the previous option.
1823 For more details of loop optimizations performed see section Loop Invariants.It
1824 recommended that this option NOT be used, #pragma\SpecialChar ~
1825 NOINVARIANT can be used
1826 to turn off invariant optimizations for a given function only.
1828 \labelwidthstring 00.00.0000
1834 Will not do loop induction optimizations, see section strength reduction
1835 for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
1837 ION can be used to turn off induction optimizations for a given function
1840 \labelwidthstring 00.00.0000
1851 Will not generate boundary condition check when switch statements are implement
1852 ed using jump-tables.
1853 See section Switch Statements for more details.
1854 It is recommended that this option is NOT used, #pragma\SpecialChar ~
1856 used to turn off boundary checking for jump tables for a given function
1859 \labelwidthstring 00.00.0000
1868 Will not do loop reversal optimization.
1869 \layout Subsubsection
1873 \labelwidthstring 00.00.0000
1880 will compile and assemble the source, but will not call the linkage editor.
1882 \labelwidthstring 00.00.0000
1888 Run only the C preprocessor.
1889 Preprocess all the C source files specified and output the results to standard
1892 \labelwidthstring 00.00.0000
1903 All functions in the source file will be compiled as
1908 the parameters and local variables will be allocated on the stack.
1909 see section Parameters and Local Variables for more details.
1910 If this option is used all source files in the project should be compiled
1914 \labelwidthstring 00.00.0000
1920 Uses a pseudo stack in the first 256 bytes in the external ram for allocating
1921 variables and passing parameters.
1922 See section on external stack for more details.
1924 \labelwidthstring 00.00.0000
1928 --callee-saves function1[,function2][,function3]....
1931 The compiler by default uses a caller saves convention for register saving
1932 across function calls, however this can cause unneccessary register pushing
1933 & popping when calling small functions from larger functions.
1934 This option can be used to switch the register saving convention for the
1935 function names specified.
1936 The compiler will not save registers when calling these functions, no extra
1937 code will be generated at the entry & exit for these functions to save
1938 & restore the registers used by these functions, this can SUBSTANTIALLY
1939 reduce code & improve run time performance of the generated code.
1940 In the future the compiler (with interprocedural analysis) will be able
1941 to determine the appropriate scheme to use for each function call.
1942 DO NOT use this option for built-in functions such as _muluint..., if this
1943 option is used for a library function the appropriate library function
1944 needs to be recompiled with the same option.
1945 If the project consists of multiple source files then all the source file
1946 should be compiled with the same --callee-saves option string.
1947 Also see #pragma\SpecialChar ~
1950 \labelwidthstring 00.00.0000
1959 When this option is used the compiler will generate debug information, that
1960 can be used with the SDCDB.
1961 The debug information is collected in a file with .cdb extension.
1962 For more information see documentation for SDCDB.
1964 \labelwidthstring 00.00.0000
1974 This option is obsolete and isn't supported anymore.
1976 \labelwidthstring 00.00.0000
1983 This option is obsolete and isn't supported anymore.
1985 \labelwidthstring 00.00.0000
1991 <filename> This option can be used to use additional rules to be used by
1992 the peep hole optimizer.
1993 See section Peep Hole optimizations for details on how to write these rules.
1995 \labelwidthstring 00.00.0000
2006 Stop after the stage of compilation proper; do not assemble.
2007 The output is an assembler code file for the input file specified.
2009 \labelwidthstring 00.00.0000
2013 -Wa_asmOption[,asmOption]
2016 Pass the asmOption to the assembler.
2018 \labelwidthstring 00.00.0000
2022 -Wl_linkOption[,linkOption]
2025 Pass the linkOption to the linker.
2027 \labelwidthstring 00.00.0000
2036 Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
2037 Note by default these libraries are compiled as non-reentrant.
2038 See section Installation for more details.
2040 \labelwidthstring 00.00.0000
2049 This option will cause the compiler to generate an information message for
2050 each function in the source file.
2051 The message contains some
2055 information about the function.
2056 The number of edges and nodes the compiler detected in the control flow
2057 graph of the function, and most importantly the
2059 cyclomatic complexity
2061 see section on Cyclomatic Complexity for more details.
2063 \labelwidthstring 00.00.0000
2072 Floating point library is compiled as reentrant.See section Installation
2075 \labelwidthstring 00.00.0000
2081 The compiler will not overlay parameters and local variables of any function,
2082 see section Parameters and local variables for more details.
2084 \labelwidthstring 00.00.0000
2090 This option can be used when the code generated is called by a monitor
2092 The compiler will generate a 'ret' upon return from the 'main' function.
2093 The default option is to lock up i.e.
2096 \labelwidthstring 00.00.0000
2102 Disable peep-hole optimization.
2104 \labelwidthstring 00.00.0000
2110 Pass the inline assembler code through the peep hole optimizer.
2111 This can cause unexpected changes to inline assembler code, please go through
2112 the peephole optimizer rules defined in the source file tree '<target>/peeph.def
2113 ' before using this option.
2115 \labelwidthstring 00.00.0000
2121 <Value> Causes the linker to check if the interal ram usage is within limits
2124 \labelwidthstring 00.00.0000
2130 This will prevent the compiler from passing on the default include path
2131 to the preprocessor.
2133 \labelwidthstring 00.00.0000
2139 This will prevent the compiler from passing on the default library path
2142 \labelwidthstring 00.00.0000
2148 Shows the various actions the compiler is performing.
2150 \labelwidthstring 00.00.0000
2156 Shows the actual commands the compiler is executing.
2157 \layout Subsubsection
2159 Intermediate Dump Options
2162 The following options are provided for the purpose of retargetting and debugging
2164 These provided a means to dump the intermediate code (iCode) generated
2165 by the compiler in human readable form at various stages of the compilation
2169 \labelwidthstring 00.00.0000
2175 This option will cause the compiler to dump the intermediate code into
2178 <source filename>.dumpraw
2180 just after the intermediate code has been generated for a function, i.e.
2181 before any optimizations are done.
2182 The basic blocks at this stage ordered in the depth first number, so they
2183 may not be in sequence of execution.
2185 \labelwidthstring 00.00.0000
2191 Will create a dump of iCode's, after global subexpression elimination,
2194 <source filename>.dumpgcse.
2196 \labelwidthstring 00.00.0000
2202 Will create a dump of iCode's, after deadcode elimination, into a file
2205 <source filename>.dumpdeadcode.
2207 \labelwidthstring 00.00.0000
2216 Will create a dump of iCode's, after loop optimizations, into a file named
2219 <source filename>.dumploop.
2221 \labelwidthstring 00.00.0000
2230 Will create a dump of iCode's, after live range analysis, into a file named
2233 <source filename>.dumprange.
2235 \labelwidthstring 00.00.0000
2241 Will dump the life ranges for all symbols.
2243 \labelwidthstring 00.00.0000
2252 Will create a dump of iCode's, after register assignment, into a file named
2255 <source filename>.dumprassgn.
2257 \labelwidthstring 00.00.0000
2263 Will create a dump of the live ranges of iTemp's
2265 \labelwidthstring 00.00.0000
2276 Will cause all the above mentioned dumps to be created.
2279 MCS51/DS390 Storage Class Language Extensions
2282 In addition to the ANSI storage classes SDCC allows the following MCS51
2283 specific storage classes.
2284 \layout Subsubsection
2289 Variables declared with this storage class will be placed in the extern
2295 storage class for Large Memory model, e.g.:
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
2320 \layout Subsubsection
2325 Variables declared with this storage class will be allocated into the indirectly
2326 addressable portion of the internal ram of a 8051, e.g.:
2333 \layout Subsubsection
2338 This is a data-type and a storage class specifier.
2339 When a variable is declared as a bit, it is allocated into the bit addressable
2340 memory of 8051, e.g.:
2347 \layout Subsubsection
2352 Like the bit keyword,
2356 signifies both a data-type and storage class, they are used to describe
2357 the special function registers and special bit variables of a 8051, eg:
2363 sfr at 0x80 P0; /* special function register P0 at location 0x80 */
2365 sbit at 0xd7 CY; /* CY (Carry Flag) */
2371 SDCC allows (via language extensions) pointers to explicitly point to any
2372 of the memory spaces of the 8051.
2373 In addition to the explicit pointers, the compiler also allows a
2377 class of pointers which can be used to point to any of the memory spaces.
2381 Pointer declaration examples:
2390 /* pointer physically in xternal ram pointing to object in internal ram
2393 data unsigned char * xdata p;
2397 /* pointer physically in code rom pointing to data in xdata space */
2399 xdata unsigned char * code p;
2403 /* pointer physically in code space pointing to data in code space */
2405 code unsigned char * code p;
2409 /* the folowing is a generic pointer physically located in xdata space */
2420 Well you get the idea.
2427 For compatibility with the previous version of the compiler, the following
2428 syntax for pointer declaration is still supported but will disappear int
2436 unsigned char _xdata *ucxdp; /* pointer to data in external ram */
2438 unsigned char _data \SpecialChar ~
2439 *ucdp ; /* pointer to data in internal ram */
2441 unsigned char _code \SpecialChar ~
2442 *uccp ; /* pointer to data in R/O code space */
2444 unsigned char _idata *uccp; \SpecialChar ~
2445 /* pointer to upper 128 bytes of ram */
2455 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
2460 These type of pointers can also to be explicitly declared.
2466 unsigned char _generic *ucgp;
2475 The highest order byte of the
2479 pointers contains the data space information.
2480 Assembler support routines are called whenever data is stored or retrieved
2486 These are useful for developing reusable library routines.
2487 Explicitly specifying the pointer type will generate the most efficient
2489 Pointers declared using a mixture of OLD and NEW style could have unpredictable
2493 Parameters & Local Variables
2496 Automatic (local) variables and parameters to functions can either be placed
2497 on the stack or in data-space.
2498 The default action of the compiler is to place these variables in the internal
2499 RAM (for small model) or external RAM (for Large model).
2500 This in fact makes them
2504 so by default functions are non-reentrant.
2507 They can be placed on the stack either by using the
2511 compiler option or by using the
2515 keyword in the function declaration, e.g.:
2524 unsigned char foo(char i) reentrant
2537 Since stack space on 8051 is limited, the
2545 option should be used sparingly.
2546 Note that the reentrant keyword just means that the parameters & local
2547 variables will be allocated to the stack, it
2551 mean that the function is register bank independent.
2555 Local variables can be assigned storage classes and absolute addresses,
2562 unsigned char foo() {
2568 xdata unsigned char i;
2580 data at 0x31 unsiged char j;
2595 In the above example the variable
2599 will be allocated in the external ram,
2603 in bit addressable space and
2612 or when a function is declared as
2616 this can only be done for static variables.
2619 Parameters however are not allowed any storage class, (storage classes for
2620 parameters will be ignored), their allocation is governed by the memory
2621 model in use, and the reentrancy options.
2627 For non-reentrant functions SDCC will try to reduce internal ram space usage
2628 by overlaying parameters and local variables of a function (if possible).
2629 Parameters and local variables of a function will be allocated to an overlayabl
2630 e segment if the function has
2632 no other function calls and the function is non-reentrant and the memory
2636 If an explicit storage class is specified for a local variable, it will
2640 Note that the compiler (not the linkage editor) makes the decision for overlayin
2642 Functions that are called from an interrupt service routine should be preceded
2643 by a #pragma\SpecialChar ~
2644 NOOVERLAY if they are not reentrant.
2647 Also note that the compiler does not do any processing of inline assembler
2648 code, so the compiler might incorrectly assign local variables and parameters
2649 of a function into the overlay segment if the inline assembler code calls
2650 other c-functions that might use the overlay.
2651 In that case the #pragma\SpecialChar ~
2652 NOOVERLAY should be used.
2655 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
2656 tion or division will NOT be overlayed since these are implemented using
2657 external functions, e.g.:
2667 void set_error(unsigned char errcd)
2683 void some_isr () interrupt 2 using 1
2712 In the above example the parameter
2720 would be assigned to the overlayable segment if the #pragma\SpecialChar ~
2722 not present, this could cause unpredictable runtime behavior when called
2724 The #pragma\SpecialChar ~
2725 NOOVERLAY ensures that the parameters and local variables for
2726 the function are NOT overlayed.
2729 Interrupt Service Routines
2732 SDCC allows interrupt service routines to be coded in C, with some extended
2739 void timer_isr (void) interrupt 2 using 1
2752 The number following the
2756 keyword is the interrupt number this routine will service.
2757 The compiler will insert a call to this routine in the interrupt vector
2758 table for the interrupt number specified.
2763 keyword is used to tell the compiler to use the specified register bank
2764 (8051 specific) when generating code for this function.
2765 Note that when some function is called from an interrupt service routine
2766 it should be preceded by a #pragma\SpecialChar ~
2767 NOOVERLAY if it is not reentrant.
2768 A special note here, int (16 bit) and long (32 bit) integer division, multiplic
2769 ation & modulus operations are implemented using external support routines
2770 developed in ANSI-C, if an interrupt service routine needs to do any of
2771 these operations then the support routines (as mentioned in a following
2772 section) will have to be recompiled using the
2776 option and the source file will need to be compiled using the
2783 If you have multiple source files in your project, interrupt service routines
2784 can be present in any of them, but a prototype of the isr MUST be present
2785 or included in the file that contains the function
2792 Interrupt Numbers and the corresponding address & descriptions for the Standard
2793 8051 are listed below.
2794 SDCC will automatically adjust the interrupt vector table to the maximum
2795 interrupt number specified.
2801 \begin_inset Tabular
2802 <lyxtabular version="2" rows="6" columns="3">
2803 <features rotate="false" islongtable="false" endhead="0" endfirsthead="0" endfoot="0" endlastfoot="0">
2804 <column alignment="center" valignment="top" leftline="true" rightline="false" width="" special="">
2805 <column alignment="center" valignment="top" leftline="true" rightline="false" width="" special="">
2806 <column alignment="center" valignment="top" leftline="true" rightline="true" width="" special="">
2807 <row topline="true" bottomline="true" newpage="false">
2808 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2816 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2824 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2833 <row topline="true" bottomline="false" newpage="false">
2834 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2842 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2850 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2859 <row topline="true" bottomline="false" newpage="false">
2860 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2868 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2876 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2885 <row topline="true" bottomline="false" newpage="false">
2886 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2894 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2902 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2911 <row topline="true" bottomline="false" newpage="false">
2912 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2920 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2928 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2937 <row topline="true" bottomline="true" newpage="false">
2938 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2946 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="false" rotate="false" usebox="none" width="" special="">
2954 <cell multicolumn="0" alignment="center" valignment="top" topline="true" bottomline="false" leftline="true" rightline="true" rotate="false" usebox="none" width="" special="">
2971 If the interrupt service routine is defined without
2975 a register bank or with register bank 0 (using 0), the compiler will save
2976 the registers used by itself on the stack upon entry and restore them at
2977 exit, however if such an interrupt service routine calls another function
2978 then the entire register bank will be saved on the stack.
2979 This scheme may be advantageous for small interrupt service routines which
2980 have low register usage.
2983 If the interrupt service routine is defined to be using a specific register
2988 are save and restored, if such an interrupt service routine calls another
2989 function (using another register bank) then the entire register bank of
2990 the called function will be saved on the stack.
2991 This scheme is recommended for larger interrupt service routines.
2994 Calling other functions from an interrupt service routine is not recommended,
2995 avoid it if possible.
2999 Also see the _naked modifier.
3005 A special keyword may be associated with a function declaring it as
3010 SDCC will generate code to disable all interrupts upon entry to a critical
3011 function and enable them back before returning.
3012 Note that nesting critical functions may cause unpredictable results.
3037 The critical attribute maybe used with other attributes like
3045 A special keyword may be associated with a function declaring it as
3054 function modifier attribute prevents the compiler from generating prologue
3055 and epilogue code for that function.
3056 This means that the user is entirely responsible for such things as saving
3057 any registers that may need to be preserved, selecting the proper register
3058 bank, generating the
3062 instruction at the end, etc.
3063 Practically, this means that the contents of the function must be written
3064 in inline assembler.
3065 This is particularly useful for interrupt functions, which can have a large
3066 (and often unnecessary) prologue/epilogue.
3067 For example, compare the code generated by these two functions:
3073 data unsigned char counter;
3075 void simpleInterrupt(void) interrupt 1
3089 void nakedInterrupt(void) interrupt 2 _naked
3122 ; MUST explicitly include ret in _naked function.
3136 For an 8051 target, the generated simpleInterrupt looks like:
3281 whereas nakedInterrupt looks like:
3306 ; MUST explicitly include ret(i) in _naked function.
3312 While there is nothing preventing you from writing C code inside a _naked
3313 function, there are many ways to shoot yourself in the foot doing this,
3314 and is is recommended that you stick to inline assembler.
3317 Functions using private banks
3324 attribute (which tells the compiler to use a register bank other than the
3325 default bank zero) should only be applied to
3329 functions (see note 1 below).
3330 This will in most circumstances make the generated ISR code more efficient
3331 since it will not have to save registers on the stack.
3338 attribute will have no effect on the generated code for a
3342 function (but may occasionally be useful anyway
3343 \begin_float footnote
3346 possible exception: if a function is called ONLY from 'interrupt' functions
3347 using a particular bank, it can be declared with the same 'using' attribute
3348 as the calling 'interrupt' functions.
3349 For instance, if you have several ISRs using bank one, and all of them
3350 call memcpy(), it might make sense to create a specialized version of memcpy()
3351 'using 1', since this would prevent the ISR from having to save bank zero
3352 to the stack on entry and switch to bank zero before calling the function
3358 (pending: I don't think this has been done yet)
3365 function using a non-zero bank will assume that it can trash that register
3366 bank, and will not save it.
3367 Since high-priority interrupts can interrupt low-priority ones on the 8051
3368 and friends, this means that if a high-priority ISR
3372 a particular bank occurs while processing a low-priority ISR
3376 the same bank, terrible and bad things can happen.
3377 To prevent this, no single register bank should be
3381 by both a high priority and a low priority ISR.
3382 This is probably most easily done by having all high priority ISRs use
3383 one bank and all low priority ISRs use another.
3384 If you have an ISR which can change priority at runtime, you're on your
3385 own: I suggest using the default bank zero and taking the small performance
3389 It is most efficient if your ISR calls no other functions.
3390 If your ISR must call other functions, it is most efficient if those functions
3391 use the same bank as the ISR (see note 1 below); the next best is if the
3392 called functions use bank zero.
3393 It is very inefficient to call a function using a different, non-zero bank
3401 Data items can be assigned an absolute address with the
3405 keyword, in addition to a storage class, e.g.:
3411 xdata at 0x8000 unsigned char PORTA_8255 ;
3417 In the above example the PORTA_8255 will be allocated to the location 0x8000
3418 of the external ram.
3419 Note that this feature is provided to give the programmer access to
3423 devices attached to the controller.
3424 The compiler does not actually reserve any space for variables declared
3425 in this way (they are implemented with an equate in the assembler).
3426 Thus it is left to the programmer to make sure there are no overlaps with
3427 other variables that are declared without the absolute address.
3428 The assembler listing file (.lst) and the linker output files (.rst) and
3429 (.map) are a good places to look for such overlaps.
3433 Absolute address can be specified for variables in all storage classes,
3446 The above example will allocate the variable at offset 0x02 in the bit-addressab
3448 There is no real advantage to assigning absolute addresses to variables
3449 in this manner, unless you want strict control over all the variables allocated.
3455 The compiler inserts a call to the C routine
3457 _sdcc__external__startup()
3462 at the start of the CODE area.
3463 This routine is in the runtime library.
3464 By default this routine returns 0, if this routine returns a non-zero value,
3465 the static & global variable initialization will be skipped and the function
3466 main will be invoked Other wise static & global variables will be initialized
3467 before the function main is invoked.
3470 _sdcc__external__startup()
3472 routine to your program to override the default if you need to setup hardware
3473 or perform some other critical operation prior to static & global variable
3477 Inline Assembler Code
3480 SDCC allows the use of in-line assembler with a few restriction as regards
3482 All labels defined within inline assembler code
3490 where nnnn is a number less than 100 (which implies a limit of utmost 100
3491 inline assembler labels
3499 It is strongly recommended that each assembly instruction (including labels)
3500 be placed in a separate line (as the example shows).
3505 command line option is used, the inline assembler code will be passed through
3506 the peephole optimizer.
3507 This might cause some unexpected changes in the inline assembler code.
3508 Please go throught the peephole optimizer rules defined in file
3512 carefully before using this option.
3552 The inline assembler code can contain any valid code understood by the assembler
3553 , this includes any assembler directives and comment lines.
3554 The compiler does not do any validation of the code within the
3564 Inline assembler code cannot reference any C-Labels, however it can reference
3565 labels defined by the inline assembler, e.g.:
3591 ; some assembler code
3611 /* some more c code */
3613 clabel:\SpecialChar ~
3615 /* inline assembler cannot reference this label */
3627 $0003: ;label (can be reference by inline assembler only)
3639 /* some more c code */
3647 In other words inline assembly code can access labels defined in inline
3648 assembly within the scope of the funtion.
3652 The same goes the other way, ie.
3653 labels defines in inline assembly CANNOT be accessed by C statements.
3656 int(16 bit) and long (32 bit) Support
3659 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
3660 multiplication and modulus operations are implemented by support routines.
3661 These support routines are all developed in ANSI-C to facilitate porting
3662 to other MCUs, although some model specific assembler optimations are used.
3663 The following files contain the described routine, all of them can be found
3664 in <installdir>/share/sdcc/lib.
3670 <pending: tabularise this>
3676 _mulsint.c - signed 16 bit multiplication (calls _muluint)
3678 _muluint.c - unsigned 16 bit multiplication
3680 _divsint.c - signed 16 bit division (calls _divuint)
3682 _divuint.c - unsigned 16 bit division
3684 _modsint.c - signed 16 bit modulus (call _moduint)
3686 _moduint.c - unsigned 16 bit modulus
3688 _mulslong.c - signed 32 bit multiplication (calls _mululong)
3690 _mululong.c - unsigned32 bit multiplication
3692 _divslong.c - signed 32 division (calls _divulong)
3694 _divulong.c - unsigned 32 division
3696 _modslong.c - signed 32 bit modulus (calls _modulong)
3698 _modulong.c - unsigned 32 bit modulus
3706 Since they are compiled as
3710 , interrupt service routines should not do any of the above operations.
3711 If this is unavoidable then the above routines will need to be compiled
3716 option, after which the source program will have to be compiled with
3723 Floating Point Support
3726 SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
3727 point support routines are derived from gcc's floatlib.c and consists of
3728 the following routines:
3734 <pending: tabularise this>
3740 _fsadd.c - add floating point numbers
3742 _fssub.c - subtract floating point numbers
3744 _fsdiv.c - divide floating point numbers
3746 _fsmul.c - multiply floating point numbers
3748 _fs2uchar.c - convert floating point to unsigned char
3750 _fs2char.c - convert floating point to signed char
3752 _fs2uint.c - convert floating point to unsigned int
3754 _fs2int.c - convert floating point to signed int
3756 _fs2ulong.c - convert floating point to unsigned long
3758 _fs2long.c - convert floating point to signed long
3760 _uchar2fs.c - convert unsigned char to floating point
3762 _char2fs.c - convert char to floating point number
3764 _uint2fs.c - convert unsigned int to floating point
3766 _int2fs.c - convert int to floating point numbers
3768 _ulong2fs.c - convert unsigned long to floating point number
3770 _long2fs.c - convert long to floating point number
3778 Note if all these routines are used simultaneously the data space might
3780 For serious floating point usage it is strongly recommended that the large
3787 SDCC allows two memory models for MCS51 code, small and large.
3788 Modules compiled with different memory models should
3792 be combined together or the results would be unpredictable.
3793 The library routines supplied with the compiler are compiled as both small
3795 The compiled library modules are contained in seperate directories as small
3796 and large so that you can link to either set.
3800 When the large model is used all variables declared without a storage class
3801 will be allocated into the external ram, this includes all parameters and
3802 local variables (for non-reentrant functions).
3803 When the small model is used variables without storage class are allocated
3804 in the internal ram.
3807 Judicious usage of the processor specific storage classes and the 'reentrant'
3808 function type will yield much more efficient code, than using the large
3810 Several optimizations are disabled when the program is compiled using the
3811 large model, it is therefore strongly recommdended that the small model
3812 be used unless absolutely required.
3818 The only model supported is Flat 24.
3819 This generates code for the 24 bit contiguous addressing mode of the Dallas
3821 In this mode, up to four meg of external RAM or code space can be directly
3823 See the data sheets at www.dalsemi.com for further information on this part.
3827 In older versions of the compiler, this option was used with the MCS51 code
3833 Now, however, the '390 has it's own code generator, selected by the
3842 Note that the compiler does not generate any code to place the processor
3843 into 24 bitmode (although
3847 in the ds390 libraries will do that for you).
3852 , the boot loader or similar code must ensure that the processor is in 24
3853 bit contiguous addressing mode before calling the SDCC startup code.
3861 option, variables will by default be placed into the XDATA segment.
3866 Segments may be placed anywhere in the 4 meg address space using the usual
3868 Note that if any segments are located above 64K, the -r flag must be passed
3869 to the linker to generate the proper segment relocations, and the Intel
3870 HEX output format must be used.
3871 The -r flag can be passed to the linker by using the option
3875 on the sdcc command line.
3876 However, currently the linker can not handle code segments > 64k.
3879 Defines Created by the Compiler
3882 The compiler creates the following #defines.
3885 SDCC - this Symbol is always defined.
3888 SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model used
3892 __mcs51 or __ds390 or __z80, etc - depending on the model used (e.g.
3896 SDCC_STACK_AUTO - this symbol is defined when
3903 SDCC_MODEL_SMALL - when
3910 SDCC_MODEL_LARGE - when
3917 SDCC_USE_XSTACK - when
3924 SDCC_STACK_TENBIT - when
3931 SDCC_MODEL_FLAT24 - when
3944 SDCC performs a host of standard optimizations in addition to some MCU specific
3947 \layout Subsubsection
3949 Sub-expression Elimination
3952 The compiler does local and global common subexpression elimination, e.g.:
3967 will be translated to
3983 Some subexpressions are not as obvious as the above example, e.g.:
3997 In this case the address arithmetic a->b[i] will be computed only once;
3998 the equivalent code in C would be.
4014 The compiler will try to keep these temporary variables in registers.
4015 \layout Subsubsection
4017 Dead-Code Elimination
4032 i = 1; \SpecialChar ~
4037 global = 1;\SpecialChar ~
4050 global = 3;\SpecialChar ~
4065 int global; void f ()
4078 \layout Subsubsection
4139 Note: the dead stores created by this copy propagation will be eliminated
4140 by dead-code elimination.
4141 \layout Subsubsection
4146 Two types of loop optimizations are done by SDCC loop invariant lifting
4147 and strength reduction of loop induction variables.
4148 In addition to the strength reduction the optimizer marks the induction
4149 variables and the register allocator tries to keep the induction variables
4150 in registers for the duration of the loop.
4151 Because of this preference of the register allocator, loop induction optimizati
4152 on causes an increase in register pressure, which may cause unwanted spilling
4153 of other temporary variables into the stack / data space.
4154 The compiler will generate a warning message when it is forced to allocate
4155 extra space either on the stack or data space.
4156 If this extra space allocation is undesirable then induction optimization
4157 can be eliminated either for the entire source file (with --noinduction
4158 option) or for a given function only using #pragma\SpecialChar ~
4169 for (i = 0 ; i < 100 ; i ++)
4187 for (i = 0; i < 100; i++)
4197 As mentioned previously some loop invariants are not as apparent, all static
4198 address computations are also moved out of the loop.
4202 Strength Reduction, this optimization substitutes an expression by a cheaper
4209 for (i=0;i < 100; i++)
4229 for (i=0;i< 100;i++) {
4233 ar[itemp1] = itemp2;
4249 The more expensive multiplication is changed to a less expensive addition.
4250 \layout Subsubsection
4255 This optimization is done to reduce the overhead of checking loop boundaries
4256 for every iteration.
4257 Some simple loops can be reversed and implemented using a
4258 \begin_inset Quotes eld
4261 decrement and jump if not zero
4262 \begin_inset Quotes erd
4266 SDCC checks for the following criterion to determine if a loop is reversible
4267 (note: more sophisticated compilers use data-dependency analysis to make
4268 this determination, SDCC uses a more simple minded analysis).
4271 The 'for' loop is of the form
4277 for (<symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
4287 The <for body> does not contain
4288 \begin_inset Quotes eld
4292 \begin_inset Quotes erd
4296 \begin_inset Quotes erd
4302 All goto's are contained within the loop.
4305 No function calls within the loop.
4308 The loop control variable <sym> is not assigned any value within the loop
4311 The loop control variable does NOT participate in any arithmetic operation
4315 There are NO switch statements in the loop.
4318 Note djnz instruction can be used for 8-bit values
4322 , therefore it is advantageous to declare loop control symbols as
4327 Ofcourse this may not be possible on all situations.
4328 \layout Subsubsection
4330 Algebraic Simplifications
4333 SDCC does numerous algebraic simplifications, the following is a small sub-set
4334 of these optimizations.
4340 i = j + 0 ; /* changed to */ i = j;
4342 i /= 2; /* changed to */ i >>= 1;
4344 i = j - j ; /* changed to */ i = 0;
4346 i = j / 1 ; /* changed to */ i = j;
4352 Note the subexpressions given above are generally introduced by macro expansions
4353 or as a result of copy/constant propagation.
4354 \layout Subsubsection
4359 SDCC changes switch statements to jump tables when the following conditions
4364 The case labels are in numerical sequence, the labels need not be in order,
4365 and the starting number need not be one or zero.
4370 switch(i) {\SpecialChar ~
4477 Both the above switch statements will be implemented using a jump-table.
4480 The number of case labels is at least three, since it takes two conditional
4481 statements to handle the boundary conditions.
4484 The number of case labels is less than 84, since each label takes 3 bytes
4485 and a jump-table can be utmost 256 bytes long.
4489 Switch statements which have gaps in the numeric sequence or those that
4490 have more that 84 case labels can be split into more than one switch statement
4491 for efficient code generation, e.g.:
4529 If the above switch statement is broken down into two switch statements
4563 case 9: \SpecialChar ~
4573 case 12:\SpecialChar ~
4583 then both the switch statements will be implemented using jump-tables whereas
4584 the unmodified switch statement will not be.
4585 \layout Subsubsection
4587 Bit-shifting Operations.
4590 Bit shifting is one of the most frequently used operation in embedded programmin
4592 SDCC tries to implement bit-shift operations in the most efficient way
4608 generates the following code:
4622 In general SDCC will never setup a loop if the shift count is known.
4662 Note that SDCC stores numbers in little-endian format (i.e.
4663 lowest order first).
4664 \layout Subsubsection
4669 A special case of the bit-shift operation is bit rotation, SDCC recognizes
4670 the following expression to be a left bit-rotation:
4681 i = ((i << 1) | (i >> 7));
4689 will generate the following code:
4705 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
4706 ns of this case will also be recognized as bit-rotation, i.e.:
4712 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
4713 \layout Subsubsection
4718 It is frequently required to obtain the highest order bit of an integral
4719 type (long, int, short or char types).
4720 SDCC recognizes the following expression to yield the highest order bit
4721 and generates optimized code for it, e.g.:
4742 hob = (gint >> 15) & 1;
4755 will generate the following code:
4794 000A E5*01\SpecialChar ~
4822 000C 33\SpecialChar ~
4853 000D E4\SpecialChar ~
4884 000E 13\SpecialChar ~
4915 000F F5*02\SpecialChar ~
4945 Variations of this case however will
4950 It is a standard C expression, so I heartily recommend this be the only
4951 way to get the highest order bit, (it is portable).
4952 Of course it will be recognized even if it is embedded in other expressions,
4959 xyz = gint + ((gint >> 15) & 1);
4965 will still be recognized.
4966 \layout Subsubsection
4971 The compiler uses a rule based, pattern matching and re-writing mechanism
4972 for peep-hole optimization.
4977 a peep-hole optimizer by Christopher W.
4978 Fraser (cwfraser@microsoft.com).
4979 A default set of rules are compiled into the compiler, additional rules
4980 may be added with the
4982 --peep-file <filename>
4985 The rule language is best illustrated with examples.
5013 The above rule will change the following assembly sequence:
5043 Note: All occurrences of a
5047 (pattern variable) must denote the same string.
5048 With the above rule, the assembly sequence:
5066 will remain unmodified.
5070 Other special case optimizations may be added by the user (via
5076 some variants of the 8051 MCU allow only
5085 The following two rules will change all
5107 replace { lcall %1 } by { acall %1 }
5109 replace { ljmp %1 } by { ajmp %1 }
5117 inline-assembler code
5119 is also passed through the peep hole optimizer, thus the peephole optimizer
5120 can also be used as an assembly level macro expander.
5121 The rules themselves are MCU dependent whereas the rule language infra-structur
5122 e is MCU independent.
5123 Peephole optimization rules for other MCU can be easily programmed using
5128 The syntax for a rule is as follows:
5134 rule := replace [ restart ] '{' <assembly sequence> '
5172 <assembly sequence> '
5190 '}' [if <functionName> ] '
5198 <assembly sequence> := assembly instruction (each instruction including
5199 labels must be on a separate line).
5203 The optimizer will apply to the rules one by one from the top in the sequence
5204 of their appearance, it will terminate when all rules are exhausted.
5205 If the 'restart' option is specified, then the optimizer will start matching
5206 the rules again from the top, this option for a rule is expensive (performance)
5207 , it is intended to be used in situations where a transformation will trigger
5208 the same rule again.
5209 A good example of this the following rule:
5231 Note that the replace pattern cannot be a blank, but can be a comment line.
5232 Without the 'restart' option only the inner most 'pop' 'push' pair would
5233 be eliminated, i.e.:
5279 the restart option the rule will be applied again to the resulting code
5280 and then all the pop-push pairs will be eliminated to yield:
5294 A conditional function can be attached to a rule.
5295 Attaching rules are somewhat more involved, let me illustrate this with
5316 %2:} if labelInRange
5322 The optimizer does a look-up of a function name table defined in function
5327 in the source file SDCCpeeph.c, with the name
5332 If it finds a corresponding entry the function is called.
5333 Note there can be no parameters specified for these functions, in this
5338 is crucial, since the function
5342 expects to find the label in that particular variable (the hash table containin
5343 g the variable bindings is passed as a parameter).
5344 If you want to code more such functions, take a close look at the function
5345 labelInRange and the calling mechanism in source file SDCCpeeph.c.
5346 I know this whole thing is a little kludgey, but maybe some day we will
5347 have some better means.
5348 If you are looking at this file, you will also see the default rules that
5349 are compiled into the compiler, you can add your own rules in the default
5350 set there if you get tired of specifying the --peep-file option.
5356 <pending: this is as far as I got>
5362 SDCC supports the following #pragma directives.
5363 This directives are applicable only at a function level.
5366 SAVE - this will save all the current options.
5369 RESTORE - will restore the saved options from the last save.
5370 Note that SAVES & RESTOREs cannot be nested.
5371 SDCC uses the same buffer to save the options each time a SAVE is called.
5374 NOGCSE - will stop global subexpression elimination.
5377 NOINDUCTION - will stop loop induction optimizations.
5380 NOJTBOUND - will not generate code for boundary value checking, when switch
5381 statements are turned into jump-tables.
5384 NOOVERLAY - the compiler will not overlay the parameters and local variables
5388 NOLOOPREVERSE - Will not do loop reversal optimization
5391 EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation
5392 of pair of push/pop instruction in ISR function (using interrupt keyword).
5393 The directive should be placed immediately before the ISR function definition
5394 and it affects ALL ISR functions following it.
5395 To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
5396 EXCLUDE\SpecialChar ~
5400 CALLEE-SAVES function1[,function2[,function3...]] - The compiler by default
5401 uses a caller saves convention for register saving across function calls,
5402 however this can cause unneccessary register pushing & popping when calling
5403 small functions from larger functions.
5404 This option can be used to switch the register saving convention for the
5405 function names specified.
5406 The compiler will not save registers when calling these functions, extra
5407 code will be generated at the entry & exit for these functions to save
5408 & restore the registers used by these functions, this can SUBSTANTIALLY
5409 reduce code & improve run time performance of the generated code.
5410 In future the compiler (with interprocedural analysis) will be able to
5411 determine the appropriate scheme to use for each function call.
5412 If --callee-saves command line option is used, the function names specified
5413 in #pragma\SpecialChar ~
5414 CALLEE-SAVES is appended to the list of functions specified inthe
5418 The pragma's are intended to be used to turn-off certain optimizations which
5419 might cause the compiler to generate extra stack / data space to store
5420 compiler generated temporary variables.
5421 This usually happens in large functions.
5422 Pragma directives should be used as shown in the following example, they
5423 are used to control options & optimizations for a given function; pragmas
5424 should be placed before and/or after a function, placing pragma's inside
5425 a function body could have unpredictable results.
5431 #pragma SAVE \SpecialChar ~
5432 /* save the current settings */
5434 #pragma NOGCSE /* turnoff global subexpression elimination */
5436 #pragma NOINDUCTION /* turn off induction optimizations */
5458 #pragma RESTORE /* turn the optimizations back on */
5461 The compiler will generate a warning message when extra space is allocated.
5462 It is strongly recommended that the SAVE and RESTORE pragma's be used when
5463 changing options for a function.
5469 The following library routines are provided for your convenience.
5472 stdio.h - Contains the following functions printf & sprintf these routines
5473 are developed by Martijn van Balen <balen@natlab.research.philips.com>.
5477 %[flags][width][b|B|l|L]type
5490 flags: -\SpecialChar ~
5497 left justify output in specified field width
5522 prefix output with +/- sign if output is signed type
5543 prefix output with a blank if it's a signed positive value
5554 width:\SpecialChar ~
5563 specifies minimum number of characters outputted for numbers
5618 - For numbers, spaces are added on the left when needed.
5648 If width starts with a zero character, zeroes and used
5705 - For strings, spaces are are added on the left or right (when
5734 flag '-' is used) when needed.
5784 byte argument (used by d, u, o, x, X)
5806 long argument (used by d, u, o, x, X)
5850 unsigned decimal number
5875 unsigned octal number
5900 unsigned hexadecimal number (0-9, a-f)
5925 unsigned hexadecimal number (0-9, A-F)
5975 string (generic pointer)
6000 generic pointer (I:data/idata, C:code, X:xdata, P:paged)
6025 float (still to be implemented)
6028 Also contains a very simple version of printf (printf_small).
6029 This simplified version of printf supports only the following formats.
6032 format\SpecialChar ~
6037 output\SpecialChar ~
6053 decimal \SpecialChar ~
6068 decimal\SpecialChar ~
6085 decimal\SpecialChar ~
6102 hexadecimal\SpecialChar ~
6115 hexadecimal\SpecialChar ~
6128 hexadecimal\SpecialChar ~
6200 character\SpecialChar ~
6216 character\SpecialChar ~
6224 The routine is very stack intesive, --stack-after-data parameter should
6225 be used when using this routine, the routine also takes about 1K of code
6227 It also expects an external function named putchar(char) to be present
6228 (this can be changed).
6229 When using the %s format the string / pointer should be cast to a generic
6235 \begin_inset Quotes eld
6238 my str %s, my int %d
6241 \begin_inset Quotes erd
6244 ,(char _generic *)mystr,myint);
6247 stdarg.h - contains definition for the following macros to be used for variable
6248 parameter list, note that a function can have a variable parameter list
6249 if and only if it is 'reentrant'
6253 va_list, va_start, va_arg, va_end.
6257 setjmp.h - contains defintion for ANSI setjmp & longjmp routines.
6258 Note in this case setjmp & longjmp can be used between functions executing
6259 within the same register bank, if long jmp is executed from a function
6260 that is using a different register bank from the function issuing the setjmp
6261 function, the results may be unpredictable.
6262 The jump buffer requires 3 bytes of data (the stack pointer & a 16 byte
6263 return address), and can be placed in any address space.
6266 stdlib.h - contains the following functions.
6274 string.h - contains the following functions.
6278 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn,
6279 strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.
6283 ctype.h - contains the following routines.
6287 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
6288 isxdigit, isalnum, isalpha.
6292 malloc.h - The malloc routines are developed by Dmitry S.
6293 Obukhov (dso@usa.net).
6294 These routines will allocate memory from the external ram.
6295 Here is a description on how to use them (as described by the author).
6309 #define DYNAMIC_MEMORY_SIZE 0x2000
6330 unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
6340 unsigned char xdata * current_buffer;
6401 init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
6415 //Now it's possible to use malloc.
6445 current_buffer = malloc(0x100);
6455 serial.h - Serial IO routines are also developed by Dmitry S.
6456 Obukhov (dso@usa.net).
6457 These routines are interrupt driven with a 256 byte circular buffer, they
6458 also expect external ram to be present.
6459 Please see documentation in file SDCCDIR/sdcc51lib/serial.c.
6460 Note the header file
6461 \begin_inset Quotes eld
6465 \begin_inset Quotes erd
6468 MUST be included in the file containing the 'main' function.
6471 ser.h - Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMi
6472 nds.com> these routines are more compact and faster.
6473 Please see documentation in file SDCCDIR/sdcc51lib/ser.c
6476 ser_ir.h - Another alternate set of serial routines provided by Josef Wolf
6477 <jw@raven.inka.de>, these routines do not use the external ram.
6480 reg51.h - contains register definitions for a standard 8051
6483 float.h - contains min, max and other floating point related stuff.
6486 All library routines are compiled as --model-small, they are all non-reentrant,
6487 if you plan to use the large model or want to make these routines reentrant,
6488 then they will have to be recompiled with the appropriate compiler option.
6491 Have not had time to do the more involved routines like printf, will get
6495 Interfacing with Assembly Routines
6498 Global Registers used for Parameter Passing
6501 By default the compiler uses the global registers
6502 \begin_inset Quotes eld
6506 \begin_inset Quotes erd
6509 to pass the first parameter to a routine, the second parameter onwards
6510 is either allocated on the stack (for reentrant routines or --stack-auto
6511 is used) or in the internal / external ram (depending on the memory model).
6513 \layout Subsubsection
6515 Assembler Routine(non-reentrant)
6518 In the following example the function cfunc calls an assembler routine asm_func,
6519 which takes two parameters.
6522 extern int asm_func(unsigned char, unsigned char);
6528 int c_func (unsigned char i, unsigned char j)
6539 return asm_func(i,j);
6550 return c_func(10,9);
6555 The corresponding assembler function is:-
6565 .globl _asm_func_PARM_2
6585 _asm_func_PARM_2:\SpecialChar ~
6671 Note here that the return values are placed in 'dpl' - One byte return value,
6672 'dpl' LSB & 'dph' MSB for two byte values.
6673 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
6674 b' & 'acc' for four byte values.
6677 The parameter naming convention is _<function_name>_PARM_<n>, where n is
6678 the parameter number starting from 1, and counting from the left.
6679 The first parameter is passed in
6680 \begin_inset Quotes eld
6684 \begin_inset Quotes erd
6687 for One bye parameter,
6688 \begin_inset Quotes eld
6692 \begin_inset Quotes erd
6696 \begin_inset Quotes eld
6700 \begin_inset Quotes erd
6704 \begin_inset Quotes eld
6708 \begin_inset Quotes erd
6711 for four bytes, the varaible name for the second parameter will be _<function_n
6715 Assemble the assembler routine with the following command.
6718 asx8051 -losg asmfunc.asm
6721 Then compile and link the assembler routine to the C source file with the
6725 sdcc cfunc.c asmfunc.rel
6726 \layout Subsubsection
6728 Assembler Routine(reentrant)
6731 In this case the second parameter onwards will be passed on the stack, the
6732 parameters are pushed from right to left i.e.
6733 after the call the left most parameter will be on the top of the stack.
6737 extern int asm_func(unsigned char, unsigned char);
6744 int c_func (unsigned char i, unsigned char j) reentrant
6755 return asm_func(i,j);
6766 return c_func(10,9);
6771 The corresponding assembler routine is.
6946 The compiling and linking procedure remains the same, however note the extra
6947 entry & exit linkage required for the assembler code, _bp is the stack
6948 frame pointer and is used to compute the offset into the stack for parameters
6949 and local variables.
6955 The external stack is located at the start of the external ram segment,
6956 and is 256 bytes in size.
6957 When --xstack option is used to compile the program, the parameters and
6958 local variables of all reentrant functions are allocated in this area.
6959 This option is provided for programs with large stack space requirements.
6960 When used with the --stack-auto option, all parameters and local variables
6961 are allocated on the external stack (note support libraries will need to
6962 be recompiled with the same options).
6965 The compiler outputs the higher order address byte of the external ram segment
6966 into PORT P2, therefore when using the External Stack option, this port
6967 MAY NOT be used by the application program.
6973 Deviations from the compliancy.
6976 functions are not always reentrant.
6979 structures cannot be assigned values directly, cannot be passed as function
6980 parameters or assigned to each other and cannot be a return value from
7001 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
7009 struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
7019 return rets;/* is invalid in SDCC although allowed in ANSI */
7024 'long long' (64 bit integers) not supported.
7027 'double' precision floating point not supported.
7030 integral promotions are suppressed.
7031 What does this mean ? The compiler will not implicitly promote an integer
7032 expression to a higher order integer, exception is an assignment or parameter
7037 No support for setjmp and longjmp (for now).
7040 Old K&R style function declarations are NOT allowed.
7043 foo(i,j) /* this old style of function declarations */
7045 int i,j; /* are valid in ANSI ..
7046 not valid in SDCC */
7056 functions declared as pointers must be dereferenced during the call.
7071 /* has to be called like this */
7075 (*foo)();/* ansi standard allows calls to be made like 'foo()' */
7078 Cyclomatic Complexity
7081 Cyclomatic complexity of a function is defined as the number of independent
7082 paths the program can take during execution of the function.
7083 This is an important number since it defines the number test cases you
7084 have to generate to validate the function.
7085 The accepted industry standard for complexity number is 10, if the cyclomatic
7086 complexity reported by SDCC exceeds 10 you should think about simplification
7087 of the function logic.
7090 Note that the complexity level is not related to the number of lines of
7092 Large functions can have low complexity, and small functions can have large
7094 SDCC uses the following formula to compute the complexity.
7097 complexity = (number of edges in control flow graph) -
7106 (number of nodes in control flow graph) + 2;
7109 Having said that the industry standard is 10, you should be aware that in
7110 some cases it may unavoidable to have a complexity level of less than 10.
7111 For example if you have switch statement with more than 10 case labels,
7112 each case label adds one to the complexity level.
7113 The complexity level is by no means an absolute measure of the algorithmic
7114 complexity of the function, it does however provide a good starting point
7115 for which functions you might look at for further optimization.
7121 Here are a few guide-lines that will help the compiler generate more efficient
7122 code, some of the tips are specific to this compiler others are generally
7123 good programming practice.
7126 Use the smallest data type to represent your data-value.
7127 If it is known in advance that the value is going to be less than 256 then
7128 use a 'char' instead of a 'short' or 'int'.
7131 Use unsigned when it is known in advance that the value is not going to
7133 This helps especially if you are doing division or multiplication.
7136 NEVER jump into a LOOP.
7139 Declare the variables to be local whenever possible, especially loop control
7140 variables (induction).
7143 Since the compiler does not do implicit integral promotion, the programmer
7144 should do an explicit cast when integral promotion is required.
7147 Reducing the size of division, multiplication & modulus operations can reduce
7148 code size substantially.
7149 Take the following code for example.
7153 foobar(unsigned int p1, unsigned char ch)
7161 unsigned char ch1 = p1 % ch ;
7176 For the modulus operation the variable ch will be promoted to unsigned int
7177 first then the modulus operation will be performed (this will lead to a
7178 call to a support routine).
7179 If the code is changed to
7182 foobar(unsigned int p1, unsigned char ch)
7190 unsigned char ch1 = (unsigned char)p1 % ch ;
7205 It would substantially reduce the code generated (future versions of the
7206 compiler will be smart enough to detect such optimization oppurtunities).
7210 Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)
7213 The 8051 family of micro controller have a minimum of 128 bytes of internal
7214 memory which is structured as follows
7217 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
7221 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
7224 - Bytes 30-7F - 60 bytes for general purpose use.
7227 Normally the SDCC compiler will only utilise the first bank of registers,
7228 but it is possible to specify that other banks of registers should be used
7229 in interrupt routines.
7230 By default, the compiler will place the stack after the last bank of used
7232 if the first 2 banks of registers are used, it will position the base of
7233 the internal stack at address 16 (0X10).
7234 This implies that as the stack grows, it will use up the remaining register
7235 banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
7236 general purpose use.
7239 By default, the compiler uses the 60 general purpose bytes to hold "near
7241 The compiler/optimiser may also declare some Local Variables in this area
7246 If any of the 128 bit variables are used, or near data is being used then
7247 care needs to be taken to ensure that the stack does not grow so much that
7248 it starts to over write either your bit variables or "near data".
7249 There is no runtime checking to prevent this from happening.
7252 The amount of stack being used is affected by the use of the "internal stack"
7253 to save registers before a subroutine call is made, - --stack-auto will
7254 declare parameters and local variables on the stack - the number of nested
7258 If you detect that the stack is over writing you data, then the following
7260 --xstack will cause an external stack to be used for saving registers and
7261 (if --stack-auto is being used) storing parameters and local variables.
7262 However this will produce more and code which will be slower to execute.
7266 --stack-loc will allow you specify the start of the stack, i.e.
7267 you could start it after any data in the general purpose area.
7268 However this may waste the memory not used by the register banks and if
7269 the size of the "near data" increases, it may creep into the bottom of
7273 --stack-after-data, similar to the --stack-loc, but it automatically places
7274 the stack after the end of the "near data".
7275 Again this could waste any spare register space.
7278 --data-loc allows you to specify the start address of the near data.
7279 This could be used to move the "near data" further away from the stack
7280 giving it more room to grow.
7281 This will only work if no bit variables are being used and the stack can
7282 grow to use the bit variable space.
7288 If you find that the stack is over writing your bit variables or "near data"
7289 then the approach which best utilised the internal memory is to position
7290 the "near data" after the last bank of used registers or, if you use bit
7291 variables, after the last bit variable by using the --data-loc, e.g.
7292 if two register banks are being used and no data variables, --data-loc
7293 16, and - use the --stack-after-data option.
7296 If bit variables are being used, another method would be to try and squeeze
7297 the data area in the unused register banks if it will fit, and start the
7298 stack after the last bit variable.
7301 Retargetting for other MCUs.
7304 The issues for retargetting the compiler are far too numerous to be covered
7306 What follows is a brief description of each of the seven phases of the
7307 compiler and its MCU dependency.
7310 Parsing the source and building the annotated parse tree.
7311 This phase is largely MCU independent (except for the language extensions).
7312 Syntax & semantic checks are also done in this phase, along with some initial
7313 optimizations like back patching labels and the pattern matching optimizations
7314 like bit-rotation etc.
7317 The second phase involves generating an intermediate code which can be easy
7318 manipulated during the later phases.
7319 This phase is entirely MCU independent.
7320 The intermediate code generation assumes the target machine has unlimited
7321 number of registers, and designates them with the name iTemp.
7322 The compiler can be made to dump a human readable form of the code generated
7323 by using the --dumpraw option.
7326 This phase does the bulk of the standard optimizations and is also MCU independe
7328 This phase can be broken down into several sub-phases.
7332 Break down intermediate code (iCode) into basic blocks.
7335 Do control flow & data flow analysis on the basic blocks.
7338 Do local common subexpression elimination, then global subexpression elimination
7341 dead code elimination
7347 if loop optimizations caused any changes then do 'global subexpression eliminati
7348 on' and 'dead code elimination' again.
7352 This phase determines the live-ranges; by live range I mean those iTemp
7353 variables defined by the compiler that still survive after all the optimization
7355 Live range analysis is essential for register allocation, since these computati
7356 on determines which of these iTemps will be assigned to registers, and for
7360 Phase five is register allocation.
7361 There are two parts to this process.
7365 The first part I call 'register packing' (for lack of a better term).
7366 In this case several MCU specific expression folding is done to reduce
7370 The second part is more MCU independent and deals with allocating registers
7371 to the remaining live ranges.
7372 A lot of MCU specific code does creep into this phase because of the limited
7373 number of index registers available in the 8051.
7377 The Code generation phase is (unhappily), entirely MCU dependent and very
7378 little (if any at all) of this code can be reused for other MCU.
7379 However the scheme for allocating a homogenized assembler operand for each
7380 iCode operand may be reused.
7383 As mentioned in the optimization section the peep-hole optimizer is rule
7384 based system, which can reprogrammed for other MCUs.
7387 SDCDB - Source Level Debugger
7390 SDCC is distributed with a source level debugger.
7391 The debugger uses a command line interface, the command repertoire of the
7392 debugger has been kept as close to gdb (the GNU debugger) as possible.
7393 The configuration and build process is part of the standard compiler installati
7394 on, which also builds and installs the debugger in the target directory
7395 specified during configuration.
7396 The debugger allows you debug BOTH at the C source and at the ASM source
7400 Compiling for Debugging
7403 The --debug option must be specified for all files for which debug information
7405 The complier generates a .cdb file for each of these files.
7406 The linker updates the .cdb file with the address information.
7407 This .cdb is used by the debugger.
7410 How the Debugger Works
7413 When the --debug option is specified the compiler generates extra symbol
7414 information some of which are put into the the assembler source and some
7415 are put into the .cdb file, the linker updates the .cdb file with the address
7416 information for the symbols.
7417 The debugger reads the symbolic information generated by the compiler &
7418 the address information generated by the linker.
7419 It uses the SIMULATOR (Daniel's S51) to execute the program, the program
7420 execution is controlled by the debugger.
7421 When a command is issued for the debugger, it translates it into appropriate
7422 commands for the simulator.
7425 Starting the Debugger
7428 The debugger can be started using the following command line.
7429 (Assume the file you are debugging has
7438 The debugger will look for the following files.
7441 foo.c - the source file.
7444 foo.cdb - the debugger symbol information file.
7447 foo.ihx - the intel hex format object file.
7450 Command Line Options.
7453 --directory=<source file directory> this option can used to specify the
7454 directory search list.
7455 The debugger will look into the directory list specified for source, cdb
7457 The items in the directory list must be separated by ':', e.g.
7458 if the source files can be in the directories /home/src1 and /home/src2,
7459 the --directory option should be --directory=/home/src1:/home/src2.
7460 Note there can be no spaces in the option.
7464 -cd <directory> - change to the <directory>.
7467 -fullname - used by GUI front ends.
7470 -cpu <cpu-type> - this argument is passed to the simulator please see the
7471 simulator docs for details.
7474 -X <Clock frequency > this options is passed to the simulator please see
7475 simulator docs for details.
7478 -s <serial port file> passed to simulator see simulator docs for details.
7481 -S <serial in,out> passed to simulator see simulator docs for details.
7487 As mention earlier the command interface for the debugger has been deliberately
7488 kept as close the GNU debugger gdb, as possible, this will help int integration
7489 with existing graphical user interfaces (like ddd, xxgdb or xemacs) existing
7490 for the GNU debugger.
7491 \layout Subsubsection
7493 break [line | file:line | function | file:function]
7496 Set breakpoint at specified line or function.
7501 sdcdb>break foo.c:100
7505 sdcdb>break foo.c:funcfoo
7506 \layout Subsubsection
7508 clear [line | file:line | function | file:function ]
7511 Clear breakpoint at specified line or function.
7516 sdcdb>clear foo.c:100
7520 sdcdb>clear foo.c:funcfoo
7521 \layout Subsubsection
7526 Continue program being debugged, after breakpoint.
7527 \layout Subsubsection
7532 Execute till the end of the current function.
7533 \layout Subsubsection
7538 Delete breakpoint number 'n'.
7539 If used without any option clear ALL user defined break points.
7540 \layout Subsubsection
7542 info [break | stack | frame | registers ]
7545 info break - list all breakpoints
7548 info stack - show the function call stack.
7551 info frame - show information about the current execution frame.
7554 info registers - show content of all registers.
7555 \layout Subsubsection
7560 Step program until it reaches a different source line.
7561 \layout Subsubsection
7566 Step program, proceeding through subroutine calls.
7567 \layout Subsubsection
7572 Start debugged program.
7573 \layout Subsubsection
7578 Print type information of the variable.
7579 \layout Subsubsection
7584 print value of variable.
7585 \layout Subsubsection
7590 load the given file name.
7591 Note this is an alternate method of loading file for debugging.
7592 \layout Subsubsection
7597 print information about current frame.
7598 \layout Subsubsection
7603 Toggle between C source & assembly source.
7604 \layout Subsubsection
7609 Send the string following '!' to the simulator, the simulator response is
7611 Note the debugger does not interpret the command being sent to the simulator,
7612 so if a command like 'go' is sent the debugger can loose its execution
7613 context and may display incorrect values.
7614 \layout Subsubsection
7621 My name is Bobby Brown"
7624 Interfacing with XEmacs.
7627 Two files are (in emacs lisp) are provided for the interfacing with XEmacs,
7628 sdcdb.el and sdcdbsrc.el.
7629 These two files can be found in the $(prefix)/bin directory after the installat
7631 These files need to be loaded into XEmacs for the interface to work, this
7632 can be done at XEmacs startup time by inserting the following into your
7633 '.xemacs' file (which can be found in your HOME directory) (load-file sdcdbsrc.el
7634 ) [ .xemacs is a lisp file so the () around the command is REQUIRED), the
7635 files can also be loaded dynamically while XEmacs is running, set the environme
7636 nt variable 'EMACSLOADPATH' to the installation bin directory [$(prefix)/bin],
7637 then enter the following command ESC-x load-file sdcdbsrc.
7638 To start the interface enter the following command ESC-x sdcdbsrc, you
7639 will prompted to enter the file name to be debugged.
7643 The command line options that are passed to the simulator directly are bound
7644 to default values in the file sdcdbsrc.el the variables are listed below
7645 these values maybe changed as required.
7648 sdcdbsrc-cpu-type '51
7651 sdcdbsrc-frequency '11059200
7657 The following is a list of key mapping for the debugger interface.
7663 ;; Current Listing ::
7680 binding\SpecialChar ~
7719 -------\SpecialChar ~
7759 sdcdb-next-from-src\SpecialChar ~
7785 sdcdb-back-from-src\SpecialChar ~
7811 sdcdb-cont-from-src\SpecialChar ~
7821 SDCDB continue command
7837 sdcdb-step-from-src\SpecialChar ~
7863 sdcdb-whatis-c-sexp\SpecialChar ~
7873 SDCDB ptypecommand for data at
7933 sdcdbsrc-delete\SpecialChar ~
7947 SDCDB Delete all breakpoints if no arg
7995 given or delete arg (C-u arg x)
8011 sdcdbsrc-frame\SpecialChar ~
8026 SDCDB Display current frame if no arg,
8074 given or display frame arg
8137 sdcdbsrc-goto-sdcdb\SpecialChar ~
8147 Goto the SDCDB output buffer
8163 sdcdb-print-c-sexp\SpecialChar ~
8174 SDCDB print command for data at
8234 sdcdbsrc-goto-sdcdb\SpecialChar ~
8244 Goto the SDCDB output buffer
8260 sdcdbsrc-mode\SpecialChar ~
8276 Toggles Sdcdbsrc mode (turns it off)
8280 ;; C-c C-f\SpecialChar ~
8288 sdcdb-finish-from-src\SpecialChar ~
8296 SDCDB finish command
8300 ;; C-x SPC\SpecialChar ~
8308 sdcdb-break\SpecialChar ~
8326 Set break for line with point
8328 ;; ESC t\SpecialChar ~
8338 sdcdbsrc-mode\SpecialChar ~
8354 Toggle Sdcdbsrc mode
8356 ;; ESC m\SpecialChar ~
8366 sdcdbsrc-srcmode\SpecialChar ~
8388 The Z80 and gbz80 port
8391 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
8392 The port is incomplete - long support is incomplete (mul, div and mod are
8393 unimplimented), and both float and bitfield support is missing, but apart
8394 from that the code generated is correct.
8397 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
8398 The stack frame is similar to that generated by the IAR Z80 compiler.
8399 IX is used as the base pointer, HL is used as a temporary register, and
8400 BC and DE are available for holding varibles.
8401 IY is currently unusued.
8402 Return values are stored in HL.
8403 One bad side effect of using IX as the base pointer is that a functions
8404 stack frame is limited to 127 bytes - this will be fixed in a later version.
8410 SDCC has grown to be large project, the compiler alone (without the Assembler
8411 Package, Preprocessor) is about 40,000 lines of code (blank stripped).
8412 The open source nature of this project is a key to its continued growth
8414 You gain the benefit and support of many active software developers and
8416 Is SDCC perfect? No, that's why we need your help.
8417 The developers take pride in fixing reported bugs.
8418 You can help by reporting the bugs and helping other SDCC users.
8419 There are lots of ways to contribute, and we encourage you to take part
8420 in making SDCC a great software package.
8426 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd
8427 cc@sdcc.sourceforge.net'.
8428 Bugs will be fixed ASAP.
8429 When reporting a bug, it is very useful to include a small test program
8430 which reproduces the problem.
8431 If you can isolate the problem by looking at the generated assembly code,
8432 this can be very helpful.
8433 Compiling your program with the --dumpall option can sometimes be useful
8434 in locating optimization problems.
8440 Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code generator,
8443 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX & ASLINK.
8446 John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for 8051
8449 Obukhov (dso@usa.net) - malloc & serial i/o routines.
8452 Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware simulator
8454 Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience and support.
8456 Unknown - for the GNU C - preprocessor.
8458 Michael Hope - The Z80 and Z80GB port, 186 development
8460 Kevin Vigor - The DS390 port.
8462 Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
8464 Scott Datallo - PIC port.
8466 (Thanks to all the other volunteer developers who have helped with coding,
8467 testing, web-page creation, distribution sets, etc.
8468 You know who you are :-)
8473 This document initially written by Sandeep Dutta
8476 All product names mentioned herein may be trademarks of their respective
8482 \begin_inset LatexCommand \index{}
projects / fw / sdcc / blob