1 #This file was created by <kvigor> Wed Oct 4 16:57:26 2000
2 #LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team
15 \paperorientation portrait
18 \paragraph_separation indent
20 \quotes_language english
24 \paperpagestyle default
28 SDCC Compiler User Guide
31 Sandeep Dutta (sandeep.dutta@usa.net)
37 SDCC is a Free ware , retargettable, optimizing ANSI-C compiler.
38 The current version targets Intel 8051 based MCUs, including the Dallas
39 80C390 variant, as well as the Zilog Z80 family.
40 It can be retargetted for other 8 bit MCUs or PICs.
41 The entire source code for the compiler is distributed under GPL.
42 SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
43 SDCC has extensive MCU (8051) specific language extensions, which lets
44 it utilize the underlying hardware effectively.
45 The front-end (parser) will be enhanced to handle language extensions for
46 other MCUs as and when they are targetted.
47 In addition to the MCU Specific optimizations SDCC also does a host of
48 standard optimizations like
50 global sub expression elimination, loop optimizations (loop invariant,
51 strength reduction of induction variables and loop reversing), constant
52 folding & propagation, copy propagation, dead code elimination and jumptables
53 for 'switch' statements.
56 For the back-end SDCC uses a global register allocation scheme which should
57 be well suited for other 8 bit MCUs , the peep hole optimizer uses a rule
58 based substitution mechanism which is MCU independent.
59 Supported data-types are
61 short (8 bits, 1 byte), char (8 bits, 1 byte), int (16 bits, 2 bytes ),
62 long (32 bit, 4 bytes) & float (4 byte IEEE).
65 The compiler also allows
69 to be embedded anywhere in a function.
70 In addition routines developed in assembly can also be called.
71 SDCC also provides an option to report the relative complexity of a function,
72 these functions can then be further optimized , or hand coded in assembly
74 SDCC also comes with a companion source level debugger SDCDB, the debugger
75 currently uses S51 a freeware simulator for 8051, it can be easily modified
76 to use other simulators.
77 The latest version can be downloaded from
79 http://sdcc.sourceforge.net
82 All packages used in this compiler system are
86 (freeware); source code for all the sub-packages ( asxxxx assembler/linker
91 a conservative garbage collector) are distributed with the package.
92 Documentation was created using a freeware word processor (LyX).
96 This program is free software; you can redistribute it and/or modify it
97 under the terms of the GNU General Public License as published by the Free
98 Software Foundation; either version 2, or (at your option) any later version.
99 This program is distributed in the hope that it will be useful, but WITHOUT
100 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
101 FOR A PARTICULAR PURPOSE.
102 See the GNU General Public License for more details.
103 You should have received a copy of the GNU General Public License along
104 with this program; if not, write to the Free Software Foundation, 59 Temple
105 Place - Suite 330, Boston, MA 02111-1307, USA.
106 In other words, you are welcome to use, share and improve this program.
107 You are forbidden to forbid anyone else to use, share and improve what
109 Help stamp out software-hoarding!
113 \begin_inset LatexCommand \label{Installation}
120 What you need before you start installation of SDCC ? A C Compiler, not
121 just any C Compiler, gcc to be exact, you can get adventurous and try another
122 compiler , I HAVEN'T tried it.
123 GCC is free , and is available for almost all major platforms.
128 you probably already have it, if you are using
134 http://sources.redhat.com/
144 After you have installed
148 you are ready to build the compiler (sorry no binary distributions yet).
149 SDCC is native to Linux but can be ported to any platform on which GCC
151 Extract the source file package (
159 ) into some directory , which we shall refer to as
167 \begin_inset LatexCommand \label{Components}
172 \layout Subsubsection
174 gc ( a conservative garbage collector)
177 SDCC relies on this component to do all the memory management, this excellent
178 package is copyrighted by
180 Jans J Boehm(boehm@sgi.com) and Alan J Demers
182 but can be used with minimum restrictions.
183 The GC source will be extracted into the directory
189 \layout Subsubsection
191 cpp ( C-Preprocessor)
194 The preprocessor is extracted into the directory
198 , it is a modified version of the GNU preprocessor.
199 \layout Subsubsection
201 asxxxx & aslink ( The assembler and Linkage Editor)
204 This is retargettable assembler & linkage editor, it was developed by Alan
205 Baldwin, John Hartman created the version for 8051, and I (Sandeep) have
206 some enhancements and bug fixes for it to work properly with the SDCC.
207 This component is extracted into the directory
210 \layout Subsubsection
215 This is the actual compiler, it uses
219 and invokes the assembler and linkage editor.
220 All files with the prefix
224 are part of the compiler and is extracted into the the directory
227 \layout Subsubsection
232 Version 2.1.8 onwards contains s51 a freeware , opensource simulator developed
233 by Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu>.
234 The executable is built as part of build process, for more information
235 visit Daniel's website at <http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51/
237 \layout Subsubsection
239 SDCDB - Source level Debugger.
242 SDCDB is the companion source level debugger .
243 The current version of the debugger uses Daniel's Simulator S51, but can
244 be easily changed to use other simulators.
247 Installation for Version <= 2.1.7
250 After the package is extracted (
258 , change to the directory where you extracted the package and give the command.
268 shell script, it will compile all the above mentioned components and install
269 the executables into the directory
273 make sure you add this directory to your
277 environment variable.
278 This script will also compile all the support routines ( library routines
280 The support routines are all developed in C and need to be compiled.
283 Installation for Version >= 2.1.8a
286 The distribution method from Version 2.1.8a has been changed to be conforment
288 \begin_inset Quotes eld
292 \begin_inset Quotes erd
296 The source is now distributed as
300 sdcc-<version number>.tar.gz format
304 , instead of the older .zip format.
305 The steps for installation are as follows.
306 \layout Subsubsection
311 This is usually done by the following command
312 \begin_inset Quotes eld
319 gunzip -c sdcc-<version number>.tar.gz | tar -xv -
324 \begin_inset Quotes eld
328 \layout Subsubsection
330 Change to the main source directory (usually sdcc or sdcc-<version number>)
331 \layout Subsubsection
333 Issue command to configure your system
336 The configure command has several options the most commonly used option
337 is --prefix=<directory name>, where <directory name> is the final location
338 for the sdcc executables and libraries, (default location is /usr/local).
339 The installation process will create the following directory structure
340 under the <directory name> specified.
344 bin/ - binary exectables (add to PATH environment variable)
360 sdcc51inc/ - include header files
402 small/ - Object & Library files for small model library
430 large/ - Object & library files for large model library
458 ds390/ - Object & library files forDS80C390 library
470 './configure --prefix=/usr/local
471 \begin_inset Quotes erd
477 will create configure the compiler to be installed in directory /usr/local/bin.
478 \layout Subsubsection
483 After configuration step issue the command
491 \begin_inset Quotes eld
495 \begin_inset Quotes erd
501 This will compile the compiler
502 \layout Subsubsection
505 \begin_inset Quotes eld
509 \begin_inset Quotes erd
515 Will install the compiler and libraries in the appropriate directories.
516 \layout Subsubsection
518 Special Notes for Windows Users.
519 Provided by Michael Jamet[ mjamet@computer.org]
522 Please note: these instructions are valid for Cygwin versions prior to 1.0.
523 If you have Cygwin 1.0 or later, the generic
524 \begin_inset Quotes eld
527 configure/make/make install
528 \begin_inset Quotes erd
531 procedure described above should work as expected from the Cygwin shell.
532 If you have an earlier version of Cygwin, I strongly recommend upgrading.
533 If, however, you insist on using an earlier version, the following instructions
534 should prove helpful.
544 How to install SDCC from source on a Windows 95 or Windows NT 4 system
555 This document describes how to install SDCC on a Win 95 or Win NT 4 system.
561 These instructions probably work for Win 98 as well, but have not been
567 tested on that platform.
578 There are lots of little differences between UNIX and the Win32 Cygnus
584 environment which make porting more difficult than it should be.
591 you want the details, please contact me.
593 Otherwise just follow these
610 Install the Cygnus Software
615 Go to http://sourceware.cygnus.com/cygwin.
617 Cygnus provides a UNIX like
622 environment for Win 32 systems.
624 Download "full.exe" and install.
631 MUST install it on your C drive.
633 "full.exe" contains a shell AND many
638 common UNIX utilities.
650 Download and Extract the Latest SDCC
655 The latest version can be found at
662 www.geocities.com/ResearchTriange/Forum/1353.
668 It can be uncompressed with winzip.
686 There should be an entry in the Start Menu for Cygnus.
694 This gives you a UNIX like environment.
696 FROM THIS POINT ON, DIRECTORIES
701 MUST BE SPECIFIED WITH FORWARD SLASHES (/) NOT THE DOS STYLE BACK
708 ) BECAUSE THIS IS WHAT UNIX EXPECTS.
720 winnt" would be "/winnt" under the shell.
732 Change Directory to Where SDCC was extracted (referred to as INSTALLDIR)
746 If you extracted to a drive OTHER THAN C, the drive
751 must be specified as part of the path.
752 For example, if you extracted to
757 your "g drive", type the following: "cd //g/mydir".
764 to specify the drive.
776 Make Dirs Which are Automatically Made During the UNIX Installation
797 (not a typo, just "bin")
811 mkdir -p /usr/local/bin
818 mkdir -p /usr/local/share
825 mkdir -p /usr/local/share/sdcc51lib
832 mkdir -p /usr/local/share/sdcc51inc
849 (When a path from the root directory is specified WITHOUT a drive, the
857 For example /michael/newuser => c:
873 Add Programs to /bin Expected by the Installation Process
880 - Look at your path: echo $PATH
891 One of the fields is the diretory with the CYGNUS programs.
902 /CYGNUS/CYGWIN~1/H-I586/BIN
914 - cd to the directory found above.
916 You may have to fiddle with the
927 case (upper or lower) here because the PATH is SHOWN as all upper
938 case, but is actually mixed.
940 To help you along, you may type
951 a letter or 2 followed by the escape key.
964 out the remaining letters IF THEY describe a unique directory.
976 If you have problems here, cd one directory and type "ls".
989 is the equivalent of "dir/w".
1001 \protected_separator
1002 - Copy the following:
1006 \protected_separator
1008 \protected_separator
1010 \protected_separator
1015 \protected_separator
1017 \protected_separator
1019 \protected_separator
1024 \protected_separator
1026 \protected_separator
1028 \protected_separator
1033 \protected_separator
1038 \protected_separator
1040 Go back to the INSTALLDIR
1044 \protected_separator
1046 \protected_separator
1051 \protected_separator
1057 \protected_separator
1062 \protected_separator
1064 Run the configure Program
1068 \protected_separator
1070 \protected_separator
1075 \protected_separator
1076 The "./" is important because your current directory is NOT in your path.
1081 \protected_separator
1082 Under DOS, your current directory was implicitly always the first entry
1087 \protected_separator
1093 \protected_separator
1098 \protected_separator
1104 \protected_separator
1106 \protected_separator
1111 \protected_separator
1116 \protected_separator
1117 This process takes quite some time under Win 32.
1122 \protected_separator
1127 \protected_separator
1129 Install the Newly Built Software
1133 \protected_separator
1135 \protected_separator
1140 \protected_separator
1145 \protected_separator
1146 This will partially install the software into the /usr/local directories
1151 \protected_separator
1153 \protected_separator
1154 What it actually doing is copying the .c, .h and
1158 \protected_separator
1159 library files to directories under /usr/local/share.
1164 \protected_separator
1169 \protected_separator
1170 It will NOT be able to install the actual programs (binaries) because
1174 \protected_separator
1175 it does not know programs on Win32 systems have ".exe" extensions.
1180 \protected_separator
1181 For example, it tries to install sdcc instead of sdcc.exe.
1186 \protected_separator
1191 \protected_separator
1192 After the automated part is finished, you must manually copy the binaries:
1197 \protected_separator
1199 \protected_separator
1201 \protected_separator
1202 (This is the bin directory in your INSTALLDIR)
1206 \protected_separator
1208 \protected_separator
1213 \protected_separator
1218 \protected_separator
1220 Make sure /usr/local/bin is in Your PATH
1224 \protected_separator
1231 bin to your path however your Win32 system allows.
1232 \protected_separator
1237 \protected_separator
1238 example you may add it to the PATH statement in autoexec.bat.
1243 \protected_separator
1248 \protected_separator
1250 \protected_separator
1251 If you have any questions send them to me or post them
1255 \protected_separator
1257 \layout Subsubsection
1259 FreeBSD and other non-GNU unixes
1262 Note that the SDCC build environment uses Gnu make.
1263 If this is not the default 'make' on your system, you may need to install
1265 On many systems, Gnu make is installed as 'gmake'.
1269 \begin_inset LatexCommand \label{Compiling}
1276 Single Source file projects.
1277 \begin_inset LatexCommand \label{One Source File}
1284 For single source file projects the process is very simple.
1285 Compile your programs with the following command
1293 The above command will compile ,assemble and link your source file.
1294 Output files are as follows.
1299 sourcefile.asm - Assembler source file created by the compiler
1304 sourcefile.lst - Assembler listing file created by the Assembler
1309 sourcefile.rst - Assembler listing file updated with linkedit information
1310 , created by linkage editor
1315 sourcefile.sym - symbol listing for the sourcefile, created by the assembler.
1320 sourcefile.rel - Object file created by the assembler, input to Linkage editor.
1325 sourcefile.map - The memory map for the load module, created by the Linker.
1330 sourcefile.<ihx | s19> - The load module : ihx - Intel hex format (default
1331 ), s19 - Motorola S19 format when compiler option --out-fmt-s19 is used.
1334 Projects with multiple source files.
1337 SDCC can compile only ONE file at a time.
1338 Let us for example assume that you have a project containing the following
1344 foo1.c ( contains some functions )
1349 foo2.c (contains some more functions)
1354 foomain.c (contains more functions and the function main)
1357 The first two files will need to be compiled separately with the commands
1370 Then compile the source file containing main and link the other files together
1371 with the following command.
1376 sdcc foomain.c foo1.rel foo2.rel
1383 can be separately compiled as well
1393 sdcc foomain.rel foo1.rel foo2.rel
1396 The file containing the main function MUST be the FIRST file specified in
1397 the command line , since the linkage editor processes file in the order
1398 they are presented to it.
1401 Projects with additional libraries.
1404 Some reusable routines may be compiled into a library, see the documentation
1405 for the assembler and linkage editor in the directory
1407 SDCCDIR/asxxxx/asxhtm.htm
1409 this describes how to create a
1413 library file, the libraries created in this manner may be included using
1414 the command line, make sure you include the -L <library-path> option to
1415 tell the linker where to look for these files.
1416 Here is an example, assuming you have the source file
1433 sdcc foomain.c foolib.lib -L mylib
1440 ' must be an absolute path name.
1443 The view of the way the linkage editor processes the library files, it is
1444 recommended that you put each source routine in a separate file and combine
1445 them using the .lib file.
1446 For an example see the standard library file 'libsdcc.lib' in the directory
1450 Command Line options
1451 \begin_inset LatexCommand \label{Command Line Options}
1459 \begin_inset LatexCommand \label{-mmcs51}
1463 Generate code for the MCS51 (8051) family of processors.
1464 This is the default processor target.
1468 \begin_inset LatexCommand \label{-mz80}
1472 Generate code for the Z80 family of processors.
1473 Various other options may not be applicable in this mode.
1482 \begin_inset LatexCommand \label{-mds390}
1486 Generate code for the DS80C390 processor.
1487 Various other options may not be applicable in this mode.
1496 \begin_inset LatexCommand \label{--model-large}
1504 Generate code for Large model programs see section Memory Models for more
1506 If this option is used all source files in the project should be compiled
1508 In addition the standard library routines are compiled with small model
1509 , they will need to be recompiled.
1524 \begin_inset LatexCommand \label{--model-small}
1528 Generate code for Small Model programs see section Memory Models for more
1530 This is the default model.
1545 \begin_inset LatexCommand \ref[--model-flat24]{--model-flat24}
1549 Generate code forDS80C390 24-bit flat mode.
1550 See section Memory Models for more details.
1566 \begin_inset LatexCommand \label{--stack-auto}
1570 All functions in the source file will be compiled as
1575 the parameters and local variables will be allocated on the stack.
1576 see section Parameters and Local Variables for more details.
1577 If this option is used all source files in the project should be compiled
1591 \begin_inset LatexCommand \label{--xstack}
1595 Uses a pseudo stack in the first 256 bytes in the external ram for allocating
1596 variables and passing parameters.
1597 See section on external stack for more details.
1609 \begin_inset LatexCommand \label{--nogcse}
1613 Will not do global subexpression elimination, this option may be used when
1614 the compiler creates undesirably large stack/data spaces to store compiler
1616 A warning message will be generated when this happens and the compiler
1617 will indicate the number of extra bytes it allocated.
1618 It recommended that this option NOT be used , #pragma NOGCSE can be used
1619 to turn off global subexpression elimination for a given function only.
1631 \begin_inset LatexCommand \label{--noinvariant}
1635 Will not do loop invariant optimizations, this may be turned off for reasons
1636 explained for the previous option .
1637 For more details of loop optimizations performed see section Loop Invariants.It
1638 recommended that this option NOT be used , #pragma NOINVARIANT can be used
1639 to turn off invariant optimizations for a given function only.
1651 \begin_inset LatexCommand \label{--noinduction}
1655 Will not do loop induction optimizations, see section Strength reduction
1656 for more details.It recommended that this option NOT be used , #pragma NOINDUCTI
1657 ON can be used to turn off induction optimizations for given function only.
1669 \begin_inset LatexCommand \label{--nojtbound}
1673 Will not generate boundary condition check when switch statements are implement
1674 ed using jump-tables.
1675 See section Switch Statements for more details.It recommended that this
1676 option NOT be used , #pragma NOJTBOUND can be used to turn off boundary
1677 checking for jump tables for a given function only.
1690 \begin_inset LatexCommand \label{--noloopreverse}
1694 Will not do loop reversal optimization
1706 \begin_inset LatexCommand \label{--noregparms}
1710 By default the first parameter is passed using global registers (DPL,DPH,B,ACC).
1711 This option will disable parameter passing using registers.
1712 NOTE: if your program uses the 16/32 bit support routines (for multiplication/d
1713 ivision) these library routines will need to be recompiled with the --noregparms
1721 --callee-saves function1[,function2][,function3]....
1727 \begin_inset LatexCommand \label{--callee-saves}
1731 The compiler by default uses a caller saves convention for register saving
1732 across function calls, however this can cause unneccessary register pushing
1733 & popping when calling small functions from larger functions.
1734 This option can be used to switch the register saving convention for the
1735 function names specified.
1736 The compiler will not save registers when calling these functions, extra
1737 code will be generated at the entry & exit for these functions to save
1738 & restore the registers used by these functions, this can SUBSTANTIALLY
1739 reduce code & improve run time performance of the generated code.
1740 In future the compiler (with interprocedural analysis) will be able to
1741 determine the appropriate scheme to use for each function call.
1742 DO NOT use this option for built-in functions such as _muluint..., if this
1743 option is used for a library function the appropriate library function
1744 needs to be recompiled with the same option.
1745 If the project consists of multiple source files then all the source file
1746 should be compiled with the same --callee-saves option string.
1747 Also see Pragma Directive
1748 \begin_inset LatexCommand \ref{Pragmaa}
1753 \begin_inset LatexCommand \ref{pragma callee-saves}
1767 \begin_inset LatexCommand \label{--debug}
1771 When this option is used the compiler will generate debug information ,
1772 that can be used with the SDCDB.
1773 The debug information is collected in a file with .cdb extension.
1774 For more information see documentation for SDCDB.
1787 \begin_inset LatexCommand \label{--regextend}
1791 This option will cause the compiler to define pseudo registers , if this
1792 option is used, all source files in the project should be compiled with
1794 See section Register Extension for more details.
1807 \begin_inset LatexCommand \label{--compile-only}
1811 will compile and assemble the source only, will not call the linkage editor.
1823 \begin_inset LatexCommand \label{--xram-loc}
1827 <Value> The start location of the external ram, default value is 0.
1828 The value entered can be in Hexadecimal or Decimal format .eg.
1829 --xram-loc 0x8000 or --xram-loc 32768.
1842 \begin_inset LatexCommand \label{--code-loc}
1846 <Value> The start location of the code segment , default value 0.
1847 Note when this option is used the interrupt vector table is also relocated
1848 to the given address.
1849 The value entered can be in Hexadecimal or Decimal format .eg.
1850 --code-loc 0x8000 or --code-loc 32768.
1862 \begin_inset LatexCommand \label{--stack-loc}
1866 <Value> The initial value of the stack pointer.
1867 The default value of the stack pointer is 0x07 if only register bank 0
1868 is used, if other register banks are used then the stack pointer is initialized
1869 to the location above the highest register bank used.
1871 if register banks 1 & 2 are used the stack pointer will default to location
1873 The value entered can be in Hexadecimal or Decimal format .eg.
1874 --stack-loc 0x20 or --stack-loc 32.
1875 If all four register banks are used the stack will be placed after the
1876 data segment (equivalent to --stack-after-data)
1888 \begin_inset LatexCommand \label{--stack-after-data}
1892 This option will cause the stack to be located in the internal ram after
1906 \begin_inset LatexCommand \label{--data-loc}
1910 <Value> The start location of the internal ram data segment, the default
1911 value is 0x30.The value entered can be in Hexadecimal or Decimal format
1913 --data-loc 0x20 or --data-loc 32.
1925 \begin_inset LatexCommand \label{--idata-loc}
1929 <Value> The start location of the indirectly addressable internal ram, default
1931 The value entered can be in Hexadecimal or Decimal format .eg.
1932 --idata-loc 0x88 or --idata-loc 136.
1942 \begin_inset LatexCommand \label{--peep-file}
1949 <filename> This option can be used to use additional rules to be used by
1950 the peep hole optimizer.
1951 See section Peep Hole optimizations for details on how to write these rules.
1964 \begin_inset LatexCommand \label{--lib-path}
1968 <absolute path to additional libraries> This option is passed to the linkage
1969 editor, additional libraries search path.
1970 The path name must be absolute.
1971 Additional library files may be specified in the command line .
1972 See section Compiling programs for more details.
1979 \begin_inset LatexCommand \label{-I}
1986 The additional location where the pre processor will look for <..h> or
1987 \begin_inset Quotes eld
1991 \begin_inset Quotes erd
2006 \begin_inset LatexCommand \label{-D}
2010 Command line definition of macros.
2011 Passed to the pre processor.
2023 \begin_inset LatexCommand \label{-E}
2027 Run only the C preprocessor.
2028 Preprocess all the C source files specified and output the results to standard
2039 \begin_inset LatexCommand \label{-M}
2046 Tell the preprocessor to output a rule suitable for make describing the
2047 dependencies of each object file.
2048 For each source file, the preprocessor outputs one make-rule whose target
2049 is the object file name for that source file and whose dependencies are
2050 all the files `#include'd in it.
2051 This rule may be a single line or may be continued with `
2053 '-newline if it is long.
2054 The list of rules is printed on standard output instead of the preprocessed
2068 \begin_inset LatexCommand \label{-C}
2072 Tell the preprocessor not to discard comments.
2073 Used with the `-E' option.
2085 \begin_inset LatexCommand \label{-MM}
2089 Like `-M' but the output mentions only the user header files included with
2091 System header files included with `#include <file>' are omitted.
2103 \begin_inset LatexCommand \label{-Aquestion(answer)}
2107 Assert the answer answer for question, in case it is tested with a preprocessor
2108 conditional such as `#if #question(answer)'.
2109 `-A-' disables the standard asser- tions that normally describe the target
2122 \begin_inset LatexCommand \label{-Aquestion}
2126 (answer) Assert the answer answer for question, in case it is tested with
2127 a preprocessor conditional such as `#if #question(answer)'.
2128 `-A-' disables the standard assertions that normally describe the target
2141 \begin_inset LatexCommand \label{-Umacro}
2145 Undefine macro macro.
2146 `-U' options are evaluated after all `-D' options, but before any `-include'
2147 and `-imac- ros' options.
2159 \begin_inset LatexCommand \label{-dM}
2163 Tell the preprocessor to output only a list of the mac- ro definitions
2164 that are in effect at the end of prepro- cessing.
2165 Used with the `-E' option.
2177 \begin_inset LatexCommand \label{-dD}
2181 Tell the preprocessor to pass all macro definitions into the output, in
2182 their proper sequence in the rest of the output.
2194 \begin_inset LatexCommand \label{-dN}
2198 Like `-dD' except that the macro arguments and contents are omitted.
2199 Only `#define name' is included in the output.
2211 \begin_inset LatexCommand \label{-S}
2215 Stop after the stage of compilation proper; do not as- semble.
2216 The output is an assembler code file for the input file specified.
2222 -Wa asmOption[,asmOption]
2226 Pass the asmOption to the assembler
2232 -Wl linkOption[,linkOption]
2236 Pass the linkOption to the linker.
2249 \begin_inset LatexCommand \label{--int-long-rent}
2253 Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
2254 Note by default these libraries are compiled as non-reentrant.
2255 See section Installation for more details.
2268 \begin_inset LatexCommand \label{--cyclomatic}
2272 This option will cause the compiler to generate an information message for
2273 each function in the source file.
2274 The message contains some
2278 information about the function.
2279 The number of edges and nodes the compiler detected in the control flow
2280 graph of the function, and most importantly the
2282 cyclomatic complexity
2284 see section on Cyclomatic Complexity for more details.
2297 \begin_inset LatexCommand \label{--float-reent}
2301 Floating point library is compiled as reentrant.See section Installation
2312 \begin_inset LatexCommand \label{--out-fmt-ihx}
2319 The linker output (final object code) is in Intel Hex format.
2320 (This is the default option).
2333 \begin_inset LatexCommand \label{--out-fmt-s19}
2337 The linker output (final object code) is in Motorola S19 format.
2349 \begin_inset LatexCommand \label{--nooverlay}
2353 The compiler will not overlay parameters and local variables of any function,
2354 see section Parameters and local variables for more details.
2366 \begin_inset LatexCommand \label{--main-return}
2370 This option can be used when the code generated is called by a monitor
2372 The compiler will generate a 'ret' upon return from the 'main' function.
2373 The default option is to lock up i.e.
2374 generate a 'ljmp .' .
2386 \begin_inset LatexCommand \label{--no-peep}
2390 Disable peep-hole optimization.
2402 \begin_inset LatexCommand \label{--peep-asm}
2406 Pass the inline assembler code through the peep hole optimizer.
2407 Can cause unexpected changes to inline assembler code , please go through
2408 the peephole optimizer rules defnied in file 'SDCCpeeph.def' before using
2421 \begin_inset LatexCommand \label{--iram-size}
2425 <Value> Causes the linker to check if the interal ram usage is within limits
2429 The following options are provided for the purpose of retargetting and debugging
2431 These provided a means to dump the intermediate code (iCode) generated
2432 by the compiler in human readable form at various stages of the compilation
2446 \begin_inset LatexCommand \label{--dumpraw}
2451 This option will cause the compiler to dump the intermediate code into
2454 <source filename>.dumpraw
2456 just after the intermediate code has been generated for a function , i.e.
2457 before any optimizations are done.
2458 The basic blocks at this stage ordered in the depth first number, so they
2459 may not be in sequence of execution.
2472 \begin_inset LatexCommand \label{--dumpgcse}
2476 Will create a dump if iCode, after global subexpression elimination, into
2479 <source filename>.dumpgcse.
2491 \begin_inset LatexCommand \label{--dumpdeadcode}
2495 .Will create a dump if iCode, after deadcode elimination, into a file named
2498 <source filename>.dumpdeadcode.
2512 \begin_inset LatexCommand \label{--dumploop}
2516 Will create a dump if iCode, after loop optimizations, into a file named
2519 <source filename>.dumploop.
2533 \begin_inset LatexCommand \label{--dump-range}
2537 Will create a dump if iCode, after live range analysis, into a file named
2540 <source filename>.dumprange.
2554 \begin_inset LatexCommand \label{--dumpregassign}
2558 Will create a dump if iCode, after register assignment , into a file named
2561 <source filename>.dumprassgn.
2574 \begin_inset LatexCommand \label{--dumpall}
2578 Will cause all the above mentioned dumps to be created.
2581 Note that the files created for the dump are appended to each time.
2582 So the files should be deleted manually , before each dump is created.
2586 When reporting bugs, it will be very helpful if you could include these
2587 dumps along with the portion of the code that is causing the problem.
2591 \begin_inset LatexCommand \label{Language Extension}
2599 \begin_inset LatexCommand \label{Storage Classes}
2606 In addition to the ANSI storage classes SDCC allows the following 8051 specific
2608 \layout Subsubsection
2611 \begin_inset LatexCommand \label{xdata}
2618 Variables declared with this storage class will be placed in the extern
2624 storage class for Large Memory model .
2632 xdata unsigned char xduc;
2633 \layout Subsubsection
2636 \begin_inset LatexCommand \label{data}
2647 storage class for Small Memory model.
2648 Variables declared with this storage class will be allocated in the internal
2658 \layout Subsubsection
2661 \begin_inset LatexCommand \label{idata}
2668 Variables declared with this storage class will be allocated into the indirectly
2669 addressable portion of the internal ram of a 8051 .
2677 \layout Subsubsection
2680 \begin_inset LatexCommand \label{bit}
2687 This is a data-type and a storage class specifier.
2688 When a variable is declared as a bit , it is allocated into the bit addressable
2695 \layout Subsubsection
2698 \begin_inset LatexCommand \label{sfr / sbit}
2705 Like the bit keyword,
2709 signifies both a data-type and storage class, they are used to describe
2710 the special function registers and special bit variables of a 8051.
2725 /* special function register P0 at location 0x80 */
2736 \begin_inset LatexCommand \label{Optimizations}
2743 SDCC performs a a host of standard optimizations in addition to some MCU
2744 specific optimizations.
2748 Sub-expression elimination
2749 \begin_inset LatexCommand \label{Sub-expression Elimination}
2760 common subexpression elimination.
2781 will be translated to
2793 Some subexpressions are not as obvious as the above example.
2806 In this case the address arithmetic
2810 will be computed only once; the equivalent code in C would be.
2822 The compiler will try to keep these temporary variables in registers.
2825 Dead-Code elimination.
2826 \begin_inset LatexCommand \label{Dead-code elimination}
2843 \protected_separator
2845 \protected_separator
2849 \protected_separator
2851 \protected_separator
2853 \protected_separator
2855 \protected_separator
2857 \protected_separator
2861 \protected_separator
2863 \protected_separator
2864 global = 1; /* dead store */
2867 \protected_separator
2869 \protected_separator
2873 \protected_separator
2875 \protected_separator
2879 \protected_separator
2881 \protected_separator
2882 global = 3; /* unreachable */
2892 int global; void f ()
2895 \protected_separator
2897 \protected_separator
2901 \protected_separator
2903 \protected_separator
2905 \protected_separator
2909 \protected_separator
2916 \begin_inset LatexCommand \label{Copy-Propagation}
2931 \protected_separator
2933 \protected_separator
2935 \protected_separator
2939 \protected_separator
2941 \protected_separator
2943 \protected_separator
2947 \protected_separator
2949 \protected_separator
2951 \protected_separator
2955 \protected_separator
2957 \protected_separator
2959 \protected_separator
2973 \protected_separator
2975 \protected_separator
2979 \protected_separator
2981 \protected_separator
2985 \protected_separator
2987 \protected_separator
2991 \protected_separator
2993 \protected_separator
2999 Note: the dead stores created by this copy propagation will be eliminated
3000 by dead-code elimination .
3004 \begin_inset LatexCommand \label{Loop Optimizations}
3011 Two types of loop optimizations are done by SDCC loop invariant lifting
3012 and strength reduction of loop induction variables.In addition to the strength
3013 reduction the optimizer marks the induction variables and the register
3014 allocator tries to keep the induction variables in registers for the duration
3016 Because of this preference of the register allocator , loop induction optimizat
3017 ion causes an increase in register pressure, which may cause unwanted spilling
3018 of other temporary variables into the stack / data space .
3019 The compiler will generate a warning message when it is forced to allocate
3020 extra space either on the stack or data space.
3021 If this extra space allocation is undesirable then induction optimization
3022 can be eliminated either for the entire source file ( with --noinduction
3023 option) or for a given function only (#pragma NOINDUCTION).
3024 \layout Subsubsection
3027 \begin_inset LatexCommand \label{Loop Invariant}
3039 for (i = 0 ; i < 100 ; i ++)
3042 \protected_separator
3044 \protected_separator
3046 \protected_separator
3057 for ( i = 0; i < 100; i++ ) f += itemp;
3060 As mentioned previously some loop invariants are not as apparent, all static
3061 address computations are also moved out of the loop.
3062 \layout Subsubsection
3064 Strength reduction :
3065 \begin_inset LatexCommand \label{Strength Reduction}
3072 This optimization substitutes an expression by a cheaper expression.
3080 for (i=0;i < 100; i++) ar[i*5] = i*3;
3092 for (i=0;i< 100;i++) {
3095 \protected_separator
3097 \protected_separator
3099 \protected_separator
3100 ar[itemp1] = itemp2;
3103 \protected_separator
3105 \protected_separator
3107 \protected_separator
3111 \protected_separator
3113 \protected_separator
3115 \protected_separator
3121 The more expensive multiplication is changed to a less expensive addition.
3122 \layout Subsubsection
3125 \begin_inset LatexCommand \label{Loop reversing}
3132 This optimization is done to reduce the overhead of checking loop boundaries
3133 for every iteration.
3134 Some simple loops can be reversed and implemented using a
3135 \begin_inset Quotes eld
3138 decrement and jump if not zero
3139 \begin_inset Quotes erd
3143 SDCC checks for the following criterion to determine if a loop is reversible
3144 (note: more sophisticated compiers use data-dependency analysis to make
3145 this determination, SDCC uses a more simple minded analysis).
3148 The 'for' loop is of the form
3151 \begin_inset Quotes eld
3154 for ( <symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
3158 \protected_separator
3160 \protected_separator
3162 \protected_separator
3164 \protected_separator
3166 \protected_separator
3168 \protected_separator
3170 \protected_separator
3172 \begin_inset Quotes erd
3178 The <for body> does not contain
3179 \begin_inset Quotes eld
3183 \begin_inset Quotes erd
3187 \begin_inset Quotes erd
3193 All goto's are contained within the loop.
3196 No function calls within the loop.
3199 The loop control variable <sym> is not assigned any value within the loop
3202 The loop control variable does NOT participate in any arithmetic operation
3206 There are NO switch statements in the loop.
3209 Note djnz instruction can be used for 8-bit values ONLY, therefore it is
3210 advantageous to declare loop control symbols as either 'char' or 'short',
3211 ofcourse this may not be possible on all situations.
3214 Algebraic simplifications:
3215 \begin_inset LatexCommand \label{Algebraic Simplifications}
3222 SDCC does numerous algebraic simplifications, the following is a small sub-set
3223 of these optimizations.
3234 i = j + 0 ; /* changed to */ i = j;
3236 i /= 2; /* changed to */ i >>= 1;
3238 i = j - j ; /* changed to */ i = 0;
3240 i = j / 1 ; /* changed to */ i = j;
3243 Note the subexpressions given above are generally introduced by macro expansions
3244 or as a result of copy/constant propagation.
3247 'switch' statements.
3248 \begin_inset LatexCommand \label{Switch Statement}
3255 SDCC changes switch statements to jump tables when the following conditions
3260 The case labels are in numerical sequence , the labels need not be in order,
3261 and the starting number need not be one or zero.
3270 \protected_separator
3272 \protected_separator
3274 \protected_separator
3276 \protected_separator
3278 \protected_separator
3280 \protected_separator
3282 \protected_separator
3284 \protected_separator
3286 \protected_separator
3288 \protected_separator
3290 \protected_separator
3292 \protected_separator
3294 \protected_separator
3299 \protected_separator
3301 \protected_separator
3303 \protected_separator
3305 \protected_separator
3307 \protected_separator
3309 \protected_separator
3311 \protected_separator
3313 \protected_separator
3315 \protected_separator
3317 \protected_separator
3319 \protected_separator
3321 \protected_separator
3323 \protected_separator
3329 \protected_separator
3331 \protected_separator
3333 \protected_separator
3335 \protected_separator
3337 \protected_separator
3339 \protected_separator
3341 \protected_separator
3343 \protected_separator
3345 \protected_separator
3347 \protected_separator
3349 \protected_separator
3351 \protected_separator
3353 \protected_separator
3359 \protected_separator
3361 \protected_separator
3363 \protected_separator
3365 \protected_separator
3367 \protected_separator
3369 \protected_separator
3371 \protected_separator
3373 \protected_separator
3375 \protected_separator
3377 \protected_separator
3379 \protected_separator
3381 \protected_separator
3383 \protected_separator
3389 \protected_separator
3391 \protected_separator
3393 \protected_separator
3395 \protected_separator
3397 \protected_separator
3399 \protected_separator
3401 \protected_separator
3403 \protected_separator
3405 \protected_separator
3407 \protected_separator
3409 \protected_separator
3411 \protected_separator
3413 \protected_separator
3418 \protected_separator
3420 \protected_separator
3422 \protected_separator
3424 \protected_separator
3426 \protected_separator
3428 \protected_separator
3430 \protected_separator
3432 \protected_separator
3434 \protected_separator
3436 \protected_separator
3438 \protected_separator
3440 \protected_separator
3442 \protected_separator
3444 \protected_separator
3446 \protected_separator
3448 \protected_separator
3450 \protected_separator
3452 \protected_separator
3456 Both the above switch statements will be implemented using a jump-table.
3459 The number of case labels is at least three, since it takes two conditional
3460 statements to handle the boundary conditions.
3463 The number of case labels is less than 84, since each label takes 3 bytes
3464 and a jump-table can be utmost 256 bytes long.
3468 Switch statements which have gaps in the numeric sequence or those that
3469 have more that 84 case labels can be split into more than one switch statement
3470 for efficient code generation.
3507 If the above switch statement is broken down into two switch statements
3548 then both the switch statements will be implemented using jump-tables whereas
3549 the unmodified switch statement will not be .
3552 bit-shifting operations.
3553 \begin_inset LatexCommand \label{bit shifting}
3560 Bit shifting is one of the most frequently used operation in embedded programmin
3562 SDCC tries to implement bit-shift operations in the most efficient way
3584 generates the following code.
3598 In general SDCC will never setup a loop if the shift count is known.
3630 Note that SDCC stores numbers in
3636 \layout Subsubsection
3639 \begin_inset LatexCommand \label{bit rotation}
3646 A special case of the bit-shift operation is bit rotation, SDCC recognizes
3647 the following expression to be a left bit-rotation.
3657 i = ( ( i << 1) | ( i >> 7));
3662 will generate the following code.
3674 SDCC uses pattern matching on the parse tree to determine this operation
3675 .Variations of this case will also be recognized as bit-rotation i.e
3677 i = ((i >> 7) | (i << 1));
3679 /* left-bit rotation */
3683 \begin_inset LatexCommand \label{Highest Order Bit}
3690 It is frequently required to obtain the highest order bit of an integral
3691 type (int,long,short or char types).
3692 SDCC recognizes the following expression to yield the highest order bit
3693 and generates optimized code for it.
3707 \protected_separator
3709 \protected_separator
3711 \protected_separator
3716 \protected_separator
3718 \protected_separator
3720 \protected_separator
3721 hob = (gint >> 15) & 1;
3724 \protected_separator
3726 \protected_separator
3728 \protected_separator
3735 Will generate the following code.
3741 \protected_separator
3743 \protected_separator
3745 \protected_separator
3747 \protected_separator
3749 \protected_separator
3751 \protected_separator
3753 \protected_separator
3755 \protected_separator
3757 \protected_separator
3759 \protected_separator
3761 \protected_separator
3763 \protected_separator
3765 \protected_separator
3767 \protected_separator
3769 \protected_separator
3771 \protected_separator
3773 \protected_separator
3775 \protected_separator
3777 \protected_separator
3779 \protected_separator
3781 \protected_separator
3783 \protected_separator
3785 \protected_separator
3787 \protected_separator
3789 \protected_separator
3791 \protected_separator
3793 \protected_separator
3795 \protected_separator
3797 \protected_separator
3801 \protected_separator
3803 \protected_separator
3805 \protected_separator
3807 \protected_separator
3809 \protected_separator
3811 \protected_separator
3813 \protected_separator
3815 \protected_separator
3817 \protected_separator
3819 \protected_separator
3821 \protected_separator
3823 \protected_separator
3825 \protected_separator
3827 \protected_separator
3829 \protected_separator
3831 \protected_separator
3833 \protected_separator
3835 \protected_separator
3837 \protected_separator
3839 \protected_separator
3841 \protected_separator
3843 \protected_separator
3845 \protected_separator
3847 \protected_separator
3849 \protected_separator
3851 \protected_separator
3855 \protected_separator
3857 \protected_separator
3859 \protected_separator
3861 \protected_separator
3863 \protected_separator
3865 \protected_separator
3867 \protected_separator
3869 \protected_separator
3871 \protected_separator
3873 \protected_separator
3875 \protected_separator
3877 \protected_separator
3879 \protected_separator
3881 \protected_separator
3883 \protected_separator
3885 \protected_separator
3887 \protected_separator
3889 \protected_separator
3891 \protected_separator
3893 \protected_separator
3895 \protected_separator
3897 \protected_separator
3899 \protected_separator
3901 \protected_separator
3903 \protected_separator
3905 \protected_separator
3907 \protected_separator
3909 \protected_separator
3911 \protected_separator
3915 \protected_separator
3917 \protected_separator
3919 \protected_separator
3921 \protected_separator
3923 \protected_separator
3925 \protected_separator
3927 \protected_separator
3929 \protected_separator
3931 \protected_separator
3933 \protected_separator
3935 \protected_separator
3937 \protected_separator
3939 \protected_separator
3941 \protected_separator
3943 \protected_separator
3945 \protected_separator
3947 \protected_separator
3949 \protected_separator
3951 \protected_separator
3953 \protected_separator
3955 \protected_separator
3957 \protected_separator
3959 \protected_separator
3961 \protected_separator
3963 \protected_separator
3965 \protected_separator
3967 \protected_separator
3969 \protected_separator
3971 \protected_separator
3975 \protected_separator
3977 \protected_separator
3979 \protected_separator
3981 \protected_separator
3983 \protected_separator
3985 \protected_separator
3987 \protected_separator
3989 \protected_separator
3991 \protected_separator
3993 \protected_separator
3995 \protected_separator
3997 \protected_separator
3999 \protected_separator
4001 \protected_separator
4003 \protected_separator
4005 \protected_separator
4007 \protected_separator
4009 \protected_separator
4011 \protected_separator
4013 \protected_separator
4015 \protected_separator
4017 \protected_separator
4019 \protected_separator
4021 \protected_separator
4023 \protected_separator
4025 \protected_separator
4027 \protected_separator
4029 \protected_separator
4031 \protected_separator
4035 \protected_separator
4037 \protected_separator
4039 \protected_separator
4041 \protected_separator
4043 \protected_separator
4045 \protected_separator
4047 \protected_separator
4049 \protected_separator
4051 \protected_separator
4053 \protected_separator
4055 \protected_separator
4057 \protected_separator
4059 \protected_separator
4061 \protected_separator
4063 \protected_separator
4065 \protected_separator
4067 \protected_separator
4069 \protected_separator
4071 \protected_separator
4073 \protected_separator
4075 \protected_separator
4077 \protected_separator
4079 \protected_separator
4081 \protected_separator
4083 \protected_separator
4085 \protected_separator
4089 Variations of this case however will NOT be recognized .
4090 It is a standard C expression , so I heartily recommend this be the only
4091 way to get the highest order bit, (it is portable).
4092 Of course it will be recognized even if it is embedded in other expressions.
4102 xyz = gint + ((gint >> 15) & 1);
4105 will still be recognized.
4108 Peep-hole optimizer.
4109 \begin_inset LatexCommand \label{Peep-Hole}
4116 The compiler uses a rule based , pattern matching and re-writing mechanism
4117 for peep-hole optimization .
4122 a peep-hole optimizer by Christopher W.
4123 Fraser (cwfraser@microsoft.com).
4124 A default set of rules are compiled into the compiler, additional rules
4125 may be added with the --peep-file <filename> option.
4126 The rule language is best illustrated with examples.
4135 mov a,%1 } by { mov %1,a }
4138 The above rule will the following assembly sequence
4156 Note: All occurrences of a '%n' ( pattern variable ) must denote the same
4158 With the above rule, the assembly sequence
4168 will remain unmodified.
4169 Other special case optimizations may be added by the user (via --peep-file
4171 some variants of the 8051 MCU allow only 'AJMP' and 'ACALL' , the following
4172 two rules will change all 'LJMP' & 'LCALL' to 'AJMP' & 'ACALL'.
4177 replace { lcall %1 } by { acall %1 }
4179 replace { ljmp %1 } by { ajmp %1 }
4182 The inline-assembler' code is also passed through the peep hole optimizer,
4183 thus the peephole optimizer can also be used as an assembly level macro
4185 The rules themselves are MCU dependent whereas the rule language infra-structur
4186 e is MCU independent.
4187 Peephole optimization rules for other MCU can be easily programmed using
4191 The syntax for a rule is as follows ,
4196 rule := replace [ restart ] '{' <assembly sequence> '
4201 \protected_separator
4203 \protected_separator
4205 \protected_separator
4207 \protected_separator
4209 \protected_separator
4211 \protected_separator
4213 \protected_separator
4215 \protected_separator
4217 \protected_separator
4219 \protected_separator
4221 \protected_separator
4223 \protected_separator
4225 \protected_separator
4227 \protected_separator
4233 \protected_separator
4235 \protected_separator
4237 \protected_separator
4239 \protected_separator
4241 \protected_separator
4243 \protected_separator
4245 \protected_separator
4247 \protected_separator
4249 \protected_separator
4251 \protected_separator
4253 \protected_separator
4255 \protected_separator
4257 \protected_separator
4259 \protected_separator
4261 \protected_separator
4263 \protected_separator
4264 <assembly sequence> '
4269 \protected_separator
4271 \protected_separator
4273 \protected_separator
4275 \protected_separator
4277 \protected_separator
4279 \protected_separator
4281 \protected_separator
4283 \protected_separator
4285 \protected_separator
4287 \protected_separator
4289 \protected_separator
4291 \protected_separator
4293 \protected_separator
4295 \protected_separator
4296 '}' [if <functionName> ] '
4300 <assembly sequence> := assembly instruction (each instruction including
4301 labels must be on a separate line).
4302 \protected_separator
4304 \protected_separator
4308 The optimizer will apply to the rules one by one from the top in the sequence
4309 of their appearance, it will terminate when all rules are exhausted.
4314 ' option is specified, then the optimizer will start matching the rules
4315 again from the top, this option for a rule is expensive (performance),
4316 it is intended to be used in situations where a transformation will trigger
4317 the same rule again.
4318 A good example of this the following rule.
4334 Note that the replace pattern cannot be a blank, but can be a comment line.
4339 ' option only the inner most 'pop' 'push' pair would be eliminated.
4370 ' option the rule will be applied again to the resulting code and the all
4375 pairs will be eliminated to yield
4385 A conditional function can be attached to a rule.
4386 Attaching rules are somewhat more involved, let me illustrate this with
4395 \protected_separator
4397 \protected_separator
4399 \protected_separator
4405 \protected_separator
4407 \protected_separator
4409 \protected_separator
4412 %2:} if labelInRange
4415 The optimizer does a look-up of a function name table defined in function
4428 ', if it finds a corresponding entry the function is called.
4429 Note there can be no parameters specified for these functions, in this
4434 ' is crucial, since the function
4438 expects to find the label in that particular variable (the hash table containin
4439 g the variable bindings is passed as a parameter).
4440 If you want to code more such functions , take a close look at the function
4445 and the calling mechanism in source file
4450 I know this whole thing is a little kludgey , may be some day we will have
4452 If you are looking at this file, you will also see the default rules that
4453 are compiled into the compiler, you can your own rules in the default set
4454 there if you get tired of specifying the
4462 \begin_inset LatexCommand \label{Pointers}
4469 SDCC allows (via language extensions) pointers to explicitly point to any
4470 of the memory spaces of the 8051.
4471 In addition to the explicit pointers, the compiler also allows a
4475 class of pointers which can be used to point to any of the memory spaces.
4479 Pointer declaration examples.
4484 /* pointer physically in xternal ram pointing to object in internal ram
4487 data unsigned char * xdata p;
4494 /* pointer physically in code rom pointing to data in xdata space */
4496 xdata unsigned char * code p;
4503 /* pointer physically in code space pointing to data in code space */
4505 code unsigned char * code p;
4509 /* the folowing is a generic pointer physically located in xdata space */
4514 Well you get the idea.
4515 For compatibility with the previous version of the compiler, the following
4516 syntax for pointer declaration is also supported.
4517 Note the above examples will be portable to other commercially available
4523 unsigned char _xdata *ucxdp; /* pointer to data in external ram */
4526 \protected_separator
4527 *ucdp ; /* pointer to data in internal ram */
4530 \protected_separator
4531 *uccp ; /* pointer to data in R/O code space */
4533 unsigned char _idata *uccp;
4534 \protected_separator
4535 /* pointer to upper 128 bytes of ram */
4538 All unqualified pointers are treated as 3 - byte '_generic' pointers.
4539 These type of pointers can also to be explicitly declared.
4544 unsigned char _generic *ucgp;
4547 The highest order byte of the generic pointers contains the data space informati
4549 Assembler support routines are called whenever data is stored or retrieved
4550 using _generic pointers.
4551 These are useful for developing reusable library routines.
4552 Explicitly specifying the pointer type will generate the most efficient
4554 Pointers declared using a mixture of OLD/NEW style could have unpredictable
4558 Parameters & Local Variables
4559 \begin_inset LatexCommand \label{Auto Variables}
4566 Automatic (local) variables and parameters to functions can either be placed
4567 on the stack or in data-space.
4568 The default action of the compiler is to place these variables in the internal
4569 RAM ( for small model) or external RAM (for Large model).
4570 They can be placed on the stack either by using the
4574 compiler option or by using the 'reentrant' keyword in the function declaration.
4585 unsigned short foo( short i) reentrant {
4593 Note that when the parameters & local variables are declared in the internal/ext
4594 ernal ram the functions are non-reentrant.
4595 Since stack space on 8051 is limited the
4603 option should be used sparingly.
4604 Note the reentrant keyword just means that the parameters & local variables
4605 will be allocated to the stack, it DOES NOT mean that the function is register
4609 When compiled with the default option (i.e.
4610 non-reentrant ), local variables can be assigned storage classes and absolute
4623 unsigned short foo() {
4626 \protected_separator
4628 \protected_separator
4629 xdata unsigned short i;
4632 \protected_separator
4634 \protected_separator
4638 \protected_separator
4640 \protected_separator
4641 data at 0x31 unsiged short j;
4649 In the above example the variable
4653 will be allocated in the external ram,
4657 in bit addressable space and
4662 When compiled with the
4666 or when a function is declared as
4670 local variables cannot be assigned storage classes or absolute addresses.
4673 Parameters however are not allowed any storage class, (storage classes for
4674 parameters will be ignored), their allocation is governed by the memory
4675 model in use , and the reentrancy options.
4679 \begin_inset LatexCommand \label{Overlaying}
4686 For non-reentrant functions SDCC will try to reduce internal ram space usage
4687 by overlaying parameters and local variables of a function (if possible).
4688 Parameters and local variables of a function will be allocated to an overlayabl
4689 e segment if the function has
4691 no other function calls and the function is non-reentrant and the memory
4695 If an explicit storage class is specified for a local variable , it will
4699 Note that the compiler (not the linkage editor) makes the decision for overlayin
4701 Functions that are called from an interrupt service routine should be preceded
4702 by a #pragma NOOVERLAY if they are not reentrant Along the same lines the
4703 compiler does not do any processing with the inline assembler code so the
4704 compiler might incorrectly assign local variables and parameters of a function
4705 into the overlay segment if the only function call from a function is from
4706 inline assembler code, it is safe to use the #pragma NOOVERLAY for functions
4707 which call other functions using inline assembler code.
4710 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
4711 tion or division will NOT be overlayed since these are implemented using
4724 void set_error( unsigned short errcd)
4729 \protected_separator
4731 \protected_separator
4738 void some_isr () interrupt 2 using 1
4743 \protected_separator
4745 \protected_separator
4750 \protected_separator
4752 \protected_separator
4756 \protected_separator
4758 \protected_separator
4765 In the above example the parameter
4773 would be assigned to the overlayable segment (if the #pragma NOOVERLAY
4774 was not present) , this could cause unpredictable runtime behavior.
4775 The pragma NOOVERLAY ensures that the parameters and local variables for
4776 the function are NOT overlayed.
4780 \begin_inset LatexCommand \label{Critical}
4787 A special keyword may be associated with a function declaring it as '
4792 SDCC will generate code to disable all interrupts upon entry to a critical
4793 function and enable them back before returning .
4794 Note that nesting critical functions may cause unpredictable results.
4815 The critical attribute maybe used with other attributes like
4820 Absolute addressing.
4821 \begin_inset LatexCommand \label{Absolute Addressing}
4828 Data items can be assigned an absolute address with the
4832 keyword, in addition to a storage class.
4841 xdata at 0x8000 unsigned char PORTA_8255 ;
4844 In the above example the
4848 will be allocated to the location 0x8000 of the external ram.
4852 Note that is this feature is provided to give the programmer access to
4856 devices attached to the controller.
4857 The compiler does not actually reserve any space for variables declared
4858 in this way (they are implemented with an equate in the assembler), thus
4859 it is left to the programmer to make sure there are no overlaps with other
4860 variables that are declared without the absolute address, the assembler
4861 listing file (.lst) and the linker output files (<filename>.rst) and (<filename>.m
4862 ap) are a good places to look for such overlaps.
4865 Absolute address can be specified for variables in all storage classes.
4878 The above example will allocate the variable at offset 0x02 in the bit-addressab
4880 There is no real advantage to assigning absolute addresses to variables
4881 in this manner , unless you want strict control over all the variables
4885 Interrupt Service Routines
4886 \begin_inset LatexCommand \label{Interrupt Service Rouines}
4893 SDCC allows interrupt service routines to be coded in C, with some extended
4899 void timer_isr (void) interrupt 2 using 1
4909 The number following the 'interrupt' keyword is the interrupt number this
4910 routine will service.
4911 The compiler will insert a call to this routine in the interrupt vector
4912 table for the interrupt number specified.
4913 The 'using' keyword is used to tell the compiler to use the specified register
4914 bank (8051 specific) when generating code for this function.
4915 Note that when some function is called from an interrupt service routine
4916 it should be preceded by a #pragma NOOVERLAY (if it is not reentrant) .
4917 A special note here, int (16 bit) and long (32 bit) integer division, multiplic
4918 ation & modulus operations are implemented using external support routines
4919 developed in ANSI-C, if an interrupt service routine needs to do any of
4920 these operations then the support routines (as mentioned in a following
4921 section) will have to recompiled using the --stack-auto option and the
4922 source file will need to be compiled using the --int-long-rent compiler
4926 If you have multiple source files in your project, interrupt service routines
4927 can be present in any of them, but a prototype of the isr MUST be present
4928 in the file that contains the function
4935 Interrupt Numbers and the corresponding address & descriptions for the Standard
4936 8051 are listed below.
4937 SDCC will automatically adjust the interrupt vector table to the maximum
4938 interrupt number specified.
4942 \protected_separator
4944 \protected_separator
4946 \protected_separator
4948 \protected_separator
4950 \protected_separator
4952 \protected_separator
4954 \protected_separator
4956 \protected_separator
4958 \protected_separator
4960 \protected_separator
4962 \protected_separator
4964 \protected_separator
4966 \protected_separator
4968 \protected_separator
4970 \protected_separator
4972 \protected_separator
4974 \protected_separator
4976 \protected_separator
4980 \protected_separator
4982 \protected_separator
4984 \protected_separator
4986 \protected_separator
4988 \protected_separator
4990 \protected_separator
4992 \protected_separator
4994 \protected_separator
4996 \protected_separator
4998 \protected_separator
5000 \protected_separator
5002 \protected_separator
5004 \protected_separator
5006 \protected_separator
5008 \protected_separator
5010 \protected_separator
5012 \protected_separator
5014 \protected_separator
5016 \protected_separator
5018 \protected_separator
5020 \protected_separator
5022 \protected_separator
5024 \protected_separator
5026 \protected_separator
5028 \protected_separator
5030 \protected_separator
5032 \protected_separator
5034 \protected_separator
5036 \protected_separator
5038 \protected_separator
5042 \protected_separator
5044 \protected_separator
5046 \protected_separator
5048 \protected_separator
5050 \protected_separator
5052 \protected_separator
5054 \protected_separator
5056 \protected_separator
5058 \protected_separator
5060 \protected_separator
5062 \protected_separator
5064 \protected_separator
5066 \protected_separator
5068 \protected_separator
5070 \protected_separator
5072 \protected_separator
5074 \protected_separator
5076 \protected_separator
5078 \protected_separator
5080 \protected_separator
5082 \protected_separator
5084 \protected_separator
5086 \protected_separator
5088 \protected_separator
5090 \protected_separator
5092 \protected_separator
5094 \protected_separator
5096 \protected_separator
5098 \protected_separator
5100 \protected_separator
5102 \protected_separator
5104 \protected_separator
5106 \protected_separator
5110 \protected_separator
5112 \protected_separator
5114 \protected_separator
5116 \protected_separator
5118 \protected_separator
5120 \protected_separator
5122 \protected_separator
5124 \protected_separator
5126 \protected_separator
5128 \protected_separator
5130 \protected_separator
5132 \protected_separator
5134 \protected_separator
5136 \protected_separator
5138 \protected_separator
5140 \protected_separator
5142 \protected_separator
5144 \protected_separator
5146 \protected_separator
5148 \protected_separator
5150 \protected_separator
5152 \protected_separator
5154 \protected_separator
5156 \protected_separator
5158 \protected_separator
5160 \protected_separator
5162 \protected_separator
5164 \protected_separator
5166 \protected_separator
5168 \protected_separator
5172 \protected_separator
5174 \protected_separator
5176 \protected_separator
5178 \protected_separator
5180 \protected_separator
5182 \protected_separator
5184 \protected_separator
5186 \protected_separator
5188 \protected_separator
5190 \protected_separator
5192 \protected_separator
5194 \protected_separator
5196 \protected_separator
5198 \protected_separator
5200 \protected_separator
5202 \protected_separator
5204 \protected_separator
5206 \protected_separator
5208 \protected_separator
5210 \protected_separator
5212 \protected_separator
5214 \protected_separator
5216 \protected_separator
5218 \protected_separator
5220 \protected_separator
5222 \protected_separator
5224 \protected_separator
5226 \protected_separator
5228 \protected_separator
5230 \protected_separator
5232 \protected_separator
5234 \protected_separator
5238 \protected_separator
5240 \protected_separator
5242 \protected_separator
5244 \protected_separator
5246 \protected_separator
5248 \protected_separator
5250 \protected_separator
5252 \protected_separator
5254 \protected_separator
5256 \protected_separator
5258 \protected_separator
5260 \protected_separator
5262 \protected_separator
5264 \protected_separator
5266 \protected_separator
5268 \protected_separator
5270 \protected_separator
5272 \protected_separator
5274 \protected_separator
5276 \protected_separator
5278 \protected_separator
5280 \protected_separator
5282 \protected_separator
5284 \protected_separator
5286 \protected_separator
5288 \protected_separator
5290 \protected_separator
5292 \protected_separator
5294 \protected_separator
5296 \protected_separator
5298 \protected_separator
5300 \protected_separator
5302 \protected_separator
5306 If the interrupt service routine is defined without a register bank or with
5307 register bank 0 (using 0), the compiler will save the registers used by
5308 itself on the stack (upon entry and restore them at exit), however if such
5309 an interrupt service routine calls another function then the entire register
5310 bank will be saved on the stack.
5311 This scheme may be advantageous for small interrupt service routines which
5312 have low register usage.
5315 If the interrupt service routine is defined to be using a specific register
5317 \begin_inset Quotes eld
5321 \begin_inset Quotes erd
5325 \begin_inset Quotes erd
5329 \begin_inset Quotes erd
5333 \begin_inset Quotes eld
5337 \begin_inset Quotes erd
5340 are save and restored, if such an interrupt service routine calls another
5341 function (using another register bank) then the entire register bank of
5342 the called function will be saved on the stack.
5343 This scheme is recommended for larger interrupt service routines.
5346 Calling other functions from an interrupt service routine is not recommended
5347 avoid it if possible.
5351 \begin_inset LatexCommand \label{Startup}
5358 The compiler inserts a jump to the C routine
5360 _sdcc__external__startup()
5362 at the start of the CODE area.
5363 This routine can be found in the file
5365 SDCCDIR/sdcc51lib/_startup.c
5367 , by default this routine returns 0, if this routine returns a non-zero
5368 value , the static & global variable initialization will be skipped and
5369 the function main will be invoked, other wise static & global variables
5370 will be initialized before the function main is invoked.
5373 Inline assembler code.
5374 \begin_inset LatexCommand \label{Inline}
5381 SDCC allows the use of in-line assembler with a few restriction as regards
5383 All labels defined within inline assembler code HAS TO BE of the
5387 where nnnn is a number less than 100 (which implies a limit of utmost 100
5388 inline assembler labels
5393 It is strongly recommended that each assembly instruction (including labels)
5394 be placed in a separate line ( as the example shows).
5401 command line option is used, the inline assembler code will be passed through
5402 the peephole optimizer, this might cause some unexpected changes in the
5403 inline assembler code, please go throught the peephole optimizer rules
5404 defined in file 'SDCCpeeph.def' carefully before using this option.
5417 \protected_separator
5419 \protected_separator
5421 \protected_separator
5423 \protected_separator
5425 \protected_separator
5431 \protected_separator
5433 \protected_separator
5435 \protected_separator
5437 \protected_separator
5439 \protected_separator
5445 The inline assembler code can contain any valid code understood by the assembler
5446 (this includes any assembler directives and comment lines ) .
5447 The compiler does not do any validation of the code within the
5456 Inline assembler code cannot reference any C-Labels however it can reference
5457 labels defined by the inline assembler.
5475 \protected_separator
5477 \protected_separator
5479 \protected_separator
5480 ; some assembler code
5483 \protected_separator
5485 \protected_separator
5491 /* some more c code */
5494 \protected_separator
5495 /* inline assembler cannot reference this label */
5500 \protected_separator
5502 \protected_separator
5503 $0003: ;label (can be reference by inline assembler only)
5513 In other words inline assembly code can access labels defined in inline
5515 The same goes the other way, ie.
5516 labels defines in inline assembly CANNOT be accessed by C statements.
5519 int (16 bit) and long (32 bit ) support.
5520 \begin_inset LatexCommand \label{int and long}
5527 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
5528 multiplication and modulus operations are implemented by support routines.
5529 These support routines are all developed in ANSI-C to facilitate porting
5531 The following files contain the described routine, all of them can be found
5532 in the directory SDCCDIR/sdcc51lib
5537 _mulsint.c - signed 16 bit multiplication (calls _muluint)
5542 _muluint.c - unsigned 16 bit multiplication
5547 _divsint.c - signed 16 bit division (calls _divuint)
5552 _divuint.c - unsigned 16 bit division.
5557 _modsint.c - signed 16 bit modulus (call _moduint)
5562 _moduint.c - unsigned 16 bit modulus.
5567 _mulslong.c - signed 32 bit multiplication (calls _mululong)
5572 _mululong.c - unsigned32 bit multiplication.
5577 _divslong.c - signed 32 division (calls _divulong)
5582 _divulong.c - unsigned 32 division.
5587 _modslong.c - signed 32 bit modulus (calls _modulong).
5592 _modulong.c - unsigned 32 bit modulus.
5595 All these routines are compiled as non-reentrant and small model.
5596 Since they are compiled as non-reentrant, interrupt service routines should
5597 not do any of the above operations, if this unavoidable then the above
5598 routines will need to ne compiled with the --stack-auto option, after which
5599 the source program will have to be compiled with --int-long-rent option.
5602 Floating point support
5603 \begin_inset LatexCommand \label{Float}
5610 SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
5611 point support routines are derived from gcc's floatlib.c and consists of
5612 the following routines.
5618 _fsadd.c - add floating point numbers.
5623 _fssub.c - subtract floating point numbers
5628 _fsdiv.c - divide floating point numbers
5633 _fsmul.c - multiply floating point numbers
5638 _fs2uchar.c - convert floating point to unsigned char
5643 _fs2char.c - convert floating point to signed char.
5648 _fs2uint.c - convert floating point to unsigned int.
5653 _fs2int.c - convert floating point to signed int.
5658 _fs2ulong.c - convert floating point to unsigned long.
5663 _fs2long.c - convert floating point to signed long.
5668 _uchar2fs.c - convert unsigned char to floating point
5673 _char2fs.c - convert char to floating point number
5678 _uint2fs.c - convert unsigned int to floating point
5683 _int2fs.c - convert int to floating point numbers
5688 _ulong2fs.c - convert unsigned long to floating point number
5693 _long2fs.c - convert long to floating point number.
5696 Note if all these routines are used simultaneously the data space might
5698 For serious floating point usage it is strongly recommended that the Large
5699 model be used (in which case the floating point routines mentioned above
5700 will need to recompiled with the --model-Large option)
5704 \begin_inset LatexCommand \label{Memory Models}
5711 SDCC allows two memory models for MCS51 code.
5712 Modules compiled with different memory models should be combined together,
5713 the results would be unpredictable.
5714 The support routines supplied with the compiler are compiled in small-model
5715 by default, and will need to be recompiled using the large model if the
5716 large model is used.
5717 In general the use of the large model is discouraged.
5720 When the large model is used all variables declared without a storage class
5721 will be allocated into the external ram, this includes all parameters and
5722 local variables (for non-reentrant functions).
5723 When the small model is used variables without storage class are allocated
5724 in the internal ram.
5727 Judicious usage of the processor specific storage classes and the 'reentrant'
5728 function type will yield much more efficient code, than using the large-model.
5729 Several optimizations are disabled when the program is compiled using the
5730 large model, it is therefore strongly recommdended that the small model
5731 be used unless absolutely required.
5734 Flat 24 bit addressing model.
5735 \begin_inset LatexCommand \label{--model-flat24}
5742 This option generates code for the 24 bit contiguous addressing mode of
5743 the Dallas DS80C390 part.
5744 In this mode, up to four meg of external RAM or code space can be directly
5746 See the data sheets at www.dalsemi.com for further information on this part.
5749 In older versions of the compiler, this option was used with the MCS51 code
5750 generator (-mmcs51).
5751 Now, however, the '390 has it's own code generator, selected by the -mds390
5753 This code generator currently supports only the flat24 model, but the --model-f
5754 lat24 switch is still required, in case later versions of the code generator
5755 support other models (such as the paged mode of the '390).
5756 The combination of -mmcs51 and --model-flat24 is now depracated.
5759 Note that the compiler does not generate any code to place the processor
5760 into24 bitmode (it defaults to 8051 compatible mode).
5761 Boot loader or similar code must ensure that the processor is in 24 bit
5762 contiguous addressing mode before calling the SDCC startup code.
5765 Like the --model-large option, variables will by default be placed into
5770 Segments may be placed anywhere in the 4 meg address space using the usual
5772 Note that if any segments are located above 64K, the -r flag must be passed
5773 to the linker to generate the proper segment relocations, and the Intel
5774 HEX output format must be used.
5775 The -r flag can be passed to the linker by using the option -Wl-r on the
5782 This option generates code for the 10 bit stack mode of the Dallas DS80C390
5784 In this mode, the stack is located in the lower 1K of the internal RAM,
5785 which is mapped to 0x400000.
5788 With this option, sdcc will generate the proper addressing for stack variables.
5791 Note that the support is incomplete, since it still uses a single byte as
5793 This means that only the lower 256 bytes of the potential 1K stack space
5794 can actually be used.
5795 However, this does allow you to reclaim the precious 256 bytes of low RAM
5796 for use for the DATA and IDATA segments.
5799 The compiler will not generate any code to put the processor into 10 bit
5801 It is important to ensure that the processor is in this mode before calling
5802 any re-entrant functions compiled with this option.
5805 In principle, this should work with the --stack-auto option, but that has
5807 It is incompatible with the --xstack option.
5808 It also only makes sense if the processor is in 24 bit contiguous addressing
5809 mode (see the --model-flat24 option).
5812 Defines created by the compiler.
5813 \begin_inset LatexCommand \label{Defines.}
5820 The compiler creates the following #defines .
5823 SDCC - this Symbol is always defined.
5826 SDCC_STACK_AUTO - this symbol is defined when --stack-auto option is used.
5829 SDCC_MODEL_SMALL - when small model is used.
5832 SDCC_MODEL_LARGE - when --model-large is used.
5835 SDCC_USE_XSTACK - when --xstack option is used.
5839 \begin_inset LatexCommand \label{Pragmaa}
5846 SDCC supports the following
5851 This directives are applicable only at a function level.
5859 \begin_inset LatexCommand \label{pragma save}
5863 - this will save all the current options .
5871 \begin_inset LatexCommand \label{pragma restore}
5875 - will restore the saved options from the last save.
5876 Note that SAVES & RESTOREs cannot be nested.
5877 SDCC uses the same buffer to save the options each time a SAVE is called.
5885 \begin_inset LatexCommand \label{pragma nogcse}
5889 - will stop global subexpression elimination.
5897 \begin_inset LatexCommand \label{pragma noinduction}
5901 - will stop loop induction optimizations .
5909 \begin_inset LatexCommand \label{pragma nojtbound}
5913 - will not generate code for boundary value checking , when switch statements
5914 are turned into jump-tables.
5922 \begin_inset LatexCommand \label{pragma nooverlay}
5926 - the compiler will not overlay the parameters and local variables of a
5935 \begin_inset LatexCommand \label{pragma noloopreverse}
5939 - Will not do loop reversal optimization
5944 EXCLUDE NONE | {acc[,b[,dpl[,dph]]]
5947 \begin_inset LatexCommand \label{pragma exclude}
5951 - The exclude pragma disables generation of pair of push/pop instruction
5952 in ISR function (using interrupt keyword).
5953 The directive should be placed immediately before the ISR function definition
5954 and it affects ALL ISR functions following it.
5955 To enable the normal register saving for ISR functions use
5956 \begin_inset Quotes eld
5959 #pragma EXCLUDE none
5960 \begin_inset Quotes erd
5968 CALLEE-SAVES function1[,function2[,function3...]]
5971 \begin_inset LatexCommand \label{pragma callee-saves}
5975 - The compiler by default uses a caller saves convention for register saving
5976 across function calls, however this can cause unneccessary register pushing
5977 & popping when calling small functions from larger functions.
5978 This option can be used to switch the register saving convention for the
5979 function names specified.
5980 The compiler will not save registers when calling these functions, extra
5981 code will be generated at the entry & exit for these functions to save
5982 & restore the registers used by these functions, this can SUBSTANTIALLY
5983 reduce code & improve run time performance of the generated code.
5984 In future the compiler (with interprocedural analysis) will be able to
5985 determine the appropriate scheme to use for each function call.
5987 \begin_inset LatexCommand \ref{--callee-saves}
5991 command line option is used, the function names specified in #pragma CALLEE-SAV
5992 ES is appended to the list of functions specified inthe command line.
5995 The pragma's are intended to be used to turn-off certain optimizations which
5996 might cause the compiler to generate extra stack / data space to store
5997 compiler generated temporary variables.
5998 This usually happens in large functions.
5999 Pragma directives should be used as shown in the following example, they
6000 are used to control options & optimizations for a given function; pragmas
6009 a function, placing pragma's inside a function body could have unpredictable
6021 \protected_separator
6022 /* save the current settings */
6024 #pragma NOGCSE /* turnoff global subexpression elimination */
6026 #pragma NOINDUCTION /* turn off induction optimizations */
6033 \protected_separator
6035 \protected_separator
6040 \protected_separator
6042 \protected_separator
6046 \protected_separator
6048 \protected_separator
6054 #pragma RESTORE /* turn the optimizations back on */
6057 The compiler will generate a warning message when extra space is allocated.
6058 It is strongly recommended that the SAVE and RESTORE pragma's be used when
6059 changing options for a function.
6063 \begin_inset LatexCommand \label{Library}
6070 The following library routines are provided for your convenience.
6079 - Contains the following functions printf & sprintf these routines are developed
6082 Martijn van Balen <balen@natlab.research.philips.com>.
6088 %[flags][width][b|B|l|L]type
6094 \protected_separator
6096 \protected_separator
6098 \protected_separator
6100 \protected_separator
6102 \protected_separator
6104 \protected_separator
6106 \protected_separator
6108 \protected_separator
6110 \protected_separator
6112 \protected_separator
6114 \protected_separator
6116 \protected_separator
6118 \protected_separator
6120 \protected_separator
6122 \protected_separator
6124 \protected_separator
6126 \protected_separator
6127 left justify output in specified field width
6130 \protected_separator
6132 \protected_separator
6134 \protected_separator
6136 \protected_separator
6138 \protected_separator
6140 \protected_separator
6142 \protected_separator
6144 \protected_separator
6146 \protected_separator
6148 \protected_separator
6150 \protected_separator
6152 \protected_separator
6154 \protected_separator
6156 \protected_separator
6158 \protected_separator
6160 \protected_separator
6162 \protected_separator
6164 \protected_separator
6166 \protected_separator
6168 \protected_separator
6170 \protected_separator
6172 \protected_separator
6174 \protected_separator
6175 prefix output with +/- sign if output is signed type
6178 \protected_separator
6180 \protected_separator
6182 \protected_separator
6184 \protected_separator
6186 \protected_separator
6188 \protected_separator
6190 \protected_separator
6192 \protected_separator
6194 \protected_separator
6196 \protected_separator
6198 \protected_separator
6200 \protected_separator
6202 \protected_separator
6204 \protected_separator
6206 \protected_separator
6208 \protected_separator
6210 \protected_separator
6212 \protected_separator
6214 \protected_separator
6215 prefix output with a blank if it's a signed positive value
6218 \protected_separator
6220 \protected_separator
6222 \protected_separator
6224 \protected_separator
6226 \protected_separator
6228 \protected_separator
6230 \protected_separator
6232 \protected_separator
6234 \protected_separator
6236 \protected_separator
6238 \protected_separator
6240 \protected_separator
6242 \protected_separator
6244 \protected_separator
6246 \protected_separator
6248 \protected_separator
6250 \protected_separator
6252 \protected_separator
6253 specifies minimum number of characters outputted for numbers
6256 \protected_separator
6258 \protected_separator
6260 \protected_separator
6262 \protected_separator
6264 \protected_separator
6266 \protected_separator
6268 \protected_separator
6270 \protected_separator
6272 \protected_separator
6274 \protected_separator
6276 \protected_separator
6278 \protected_separator
6280 \protected_separator
6282 \protected_separator
6284 \protected_separator
6286 \protected_separator
6288 \protected_separator
6290 \protected_separator
6292 \protected_separator
6294 \protected_separator
6296 \protected_separator
6298 \protected_separator
6300 \protected_separator
6302 \protected_separator
6304 \protected_separator
6309 \protected_separator
6311 \protected_separator
6313 \protected_separator
6315 \protected_separator
6317 \protected_separator
6319 \protected_separator
6321 \protected_separator
6323 \protected_separator
6325 \protected_separator
6327 \protected_separator
6329 \protected_separator
6331 \protected_separator
6333 \protected_separator
6335 \protected_separator
6337 \protected_separator
6339 \protected_separator
6341 \protected_separator
6343 \protected_separator
6345 \protected_separator
6347 \protected_separator
6349 \protected_separator
6351 \protected_separator
6353 \protected_separator
6355 \protected_separator
6357 \protected_separator
6358 - For numbers, spaces are added on the left when needed.
6362 \protected_separator
6364 \protected_separator
6366 \protected_separator
6368 \protected_separator
6370 \protected_separator
6372 \protected_separator
6374 \protected_separator
6376 \protected_separator
6378 \protected_separator
6380 \protected_separator
6382 \protected_separator
6384 \protected_separator
6386 \protected_separator
6388 \protected_separator
6390 \protected_separator
6392 \protected_separator
6394 \protected_separator
6396 \protected_separator
6398 \protected_separator
6400 \protected_separator
6402 \protected_separator
6404 \protected_separator
6406 \protected_separator
6408 \protected_separator
6410 \protected_separator
6412 \protected_separator
6414 \protected_separator
6415 If width starts with a zero character, zeroes and used
6418 \protected_separator
6420 \protected_separator
6422 \protected_separator
6424 \protected_separator
6426 \protected_separator
6428 \protected_separator
6430 \protected_separator
6432 \protected_separator
6434 \protected_separator
6436 \protected_separator
6438 \protected_separator
6440 \protected_separator
6442 \protected_separator
6444 \protected_separator
6446 \protected_separator
6448 \protected_separator
6450 \protected_separator
6452 \protected_separator
6454 \protected_separator
6456 \protected_separator
6458 \protected_separator
6460 \protected_separator
6462 \protected_separator
6464 \protected_separator
6466 \protected_separator
6468 \protected_separator
6470 \protected_separator
6475 \protected_separator
6477 \protected_separator
6479 \protected_separator
6481 \protected_separator
6483 \protected_separator
6485 \protected_separator
6487 \protected_separator
6489 \protected_separator
6491 \protected_separator
6493 \protected_separator
6495 \protected_separator
6497 \protected_separator
6499 \protected_separator
6501 \protected_separator
6503 \protected_separator
6505 \protected_separator
6507 \protected_separator
6509 \protected_separator
6511 \protected_separator
6513 \protected_separator
6515 \protected_separator
6517 \protected_separator
6519 \protected_separator
6521 \protected_separator
6523 \protected_separator
6524 - For strings, spaces are are added on the left or right (when
6527 \protected_separator
6529 \protected_separator
6531 \protected_separator
6533 \protected_separator
6535 \protected_separator
6537 \protected_separator
6539 \protected_separator
6541 \protected_separator
6543 \protected_separator
6545 \protected_separator
6547 \protected_separator
6549 \protected_separator
6551 \protected_separator
6553 \protected_separator
6555 \protected_separator
6557 \protected_separator
6559 \protected_separator
6561 \protected_separator
6563 \protected_separator
6565 \protected_separator
6567 \protected_separator
6569 \protected_separator
6571 \protected_separator
6573 \protected_separator
6575 \protected_separator
6577 \protected_separator
6579 \protected_separator
6580 flag '-' is used) when needed.
6584 \protected_separator
6586 \protected_separator
6588 \protected_separator
6590 \protected_separator
6592 \protected_separator
6594 \protected_separator
6596 \protected_separator
6598 \protected_separator
6600 \protected_separator
6602 \protected_separator
6604 \protected_separator
6606 \protected_separator
6608 \protected_separator
6610 \protected_separator
6612 \protected_separator
6614 \protected_separator
6616 \protected_separator
6618 \protected_separator
6620 \protected_separator
6622 \protected_separator
6624 \protected_separator
6626 \protected_separator
6628 \protected_separator
6630 \protected_separator
6632 \protected_separator
6636 \protected_separator
6638 \protected_separator
6640 \protected_separator
6642 \protected_separator
6644 \protected_separator
6646 \protected_separator
6648 \protected_separator
6650 \protected_separator
6652 \protected_separator
6654 \protected_separator
6656 \protected_separator
6658 \protected_separator
6660 \protected_separator
6662 \protected_separator
6664 \protected_separator
6666 \protected_separator
6668 \protected_separator
6670 \protected_separator
6672 \protected_separator
6674 \protected_separator
6675 byte argument (used by d, u, o, x, X)
6678 \protected_separator
6680 \protected_separator
6682 \protected_separator
6684 \protected_separator
6686 \protected_separator
6688 \protected_separator
6690 \protected_separator
6692 \protected_separator
6694 \protected_separator
6696 \protected_separator
6698 \protected_separator
6700 \protected_separator
6702 \protected_separator
6704 \protected_separator
6706 \protected_separator
6708 \protected_separator
6710 \protected_separator
6712 \protected_separator
6714 \protected_separator
6716 \protected_separator
6717 long argument (used by d, u, o, x, X)
6720 \protected_separator
6722 \protected_separator
6724 \protected_separator
6726 \protected_separator
6728 \protected_separator
6730 \protected_separator
6732 \protected_separator
6734 \protected_separator
6736 \protected_separator
6738 \protected_separator
6740 \protected_separator
6742 \protected_separator
6744 \protected_separator
6746 \protected_separator
6748 \protected_separator
6750 \protected_separator
6752 \protected_separator
6756 \protected_separator
6758 \protected_separator
6760 \protected_separator
6762 \protected_separator
6764 \protected_separator
6766 \protected_separator
6768 \protected_separator
6770 \protected_separator
6772 \protected_separator
6774 \protected_separator
6776 \protected_separator
6778 \protected_separator
6780 \protected_separator
6782 \protected_separator
6784 \protected_separator
6786 \protected_separator
6788 \protected_separator
6790 \protected_separator
6792 \protected_separator
6794 \protected_separator
6796 \protected_separator
6798 \protected_separator
6800 \protected_separator
6801 unsigned decimal number
6804 \protected_separator
6806 \protected_separator
6808 \protected_separator
6810 \protected_separator
6812 \protected_separator
6814 \protected_separator
6816 \protected_separator
6818 \protected_separator
6820 \protected_separator
6822 \protected_separator
6824 \protected_separator
6826 \protected_separator
6828 \protected_separator
6830 \protected_separator
6832 \protected_separator
6834 \protected_separator
6836 \protected_separator
6838 \protected_separator
6840 \protected_separator
6842 \protected_separator
6844 \protected_separator
6846 \protected_separator
6848 \protected_separator
6849 unsigned octal number
6852 \protected_separator
6854 \protected_separator
6856 \protected_separator
6858 \protected_separator
6860 \protected_separator
6862 \protected_separator
6864 \protected_separator
6866 \protected_separator
6868 \protected_separator
6870 \protected_separator
6872 \protected_separator
6874 \protected_separator
6876 \protected_separator
6878 \protected_separator
6880 \protected_separator
6882 \protected_separator
6884 \protected_separator
6886 \protected_separator
6888 \protected_separator
6890 \protected_separator
6892 \protected_separator
6894 \protected_separator
6896 \protected_separator
6897 unsigned hexadecimal number (0-9, a-f)
6900 \protected_separator
6902 \protected_separator
6904 \protected_separator
6906 \protected_separator
6908 \protected_separator
6910 \protected_separator
6912 \protected_separator
6914 \protected_separator
6916 \protected_separator
6918 \protected_separator
6920 \protected_separator
6922 \protected_separator
6924 \protected_separator
6926 \protected_separator
6928 \protected_separator
6930 \protected_separator
6932 \protected_separator
6934 \protected_separator
6936 \protected_separator
6938 \protected_separator
6940 \protected_separator
6942 \protected_separator
6944 \protected_separator
6945 unsigned hexadecimal number (0-9, A-F)
6948 \protected_separator
6950 \protected_separator
6952 \protected_separator
6954 \protected_separator
6956 \protected_separator
6958 \protected_separator
6960 \protected_separator
6962 \protected_separator
6964 \protected_separator
6966 \protected_separator
6968 \protected_separator
6970 \protected_separator
6972 \protected_separator
6974 \protected_separator
6976 \protected_separator
6978 \protected_separator
6980 \protected_separator
6982 \protected_separator
6984 \protected_separator
6986 \protected_separator
6988 \protected_separator
6990 \protected_separator
6992 \protected_separator
6996 \protected_separator
6998 \protected_separator
7000 \protected_separator
7002 \protected_separator
7004 \protected_separator
7006 \protected_separator
7008 \protected_separator
7010 \protected_separator
7012 \protected_separator
7014 \protected_separator
7016 \protected_separator
7018 \protected_separator
7020 \protected_separator
7022 \protected_separator
7024 \protected_separator
7026 \protected_separator
7028 \protected_separator
7030 \protected_separator
7032 \protected_separator
7034 \protected_separator
7036 \protected_separator
7038 \protected_separator
7040 \protected_separator
7041 string (generic pointer)
7044 \protected_separator
7046 \protected_separator
7048 \protected_separator
7050 \protected_separator
7052 \protected_separator
7054 \protected_separator
7056 \protected_separator
7058 \protected_separator
7060 \protected_separator
7062 \protected_separator
7064 \protected_separator
7066 \protected_separator
7068 \protected_separator
7070 \protected_separator
7072 \protected_separator
7074 \protected_separator
7076 \protected_separator
7078 \protected_separator
7080 \protected_separator
7082 \protected_separator
7084 \protected_separator
7086 \protected_separator
7088 \protected_separator
7089 generic pointer (I:data/idata, C:code, X:xdata, P:paged)
7092 \protected_separator
7094 \protected_separator
7096 \protected_separator
7098 \protected_separator
7100 \protected_separator
7102 \protected_separator
7104 \protected_separator
7106 \protected_separator
7108 \protected_separator
7110 \protected_separator
7112 \protected_separator
7114 \protected_separator
7116 \protected_separator
7118 \protected_separator
7120 \protected_separator
7122 \protected_separator
7124 \protected_separator
7126 \protected_separator
7128 \protected_separator
7130 \protected_separator
7132 \protected_separator
7134 \protected_separator
7136 \protected_separator
7137 float (still to be implemented)
7140 Also contains a very simple version of printf (
7145 This simplified version of printf supports only the following formats.
7152 \protected_separator
7154 \protected_separator
7156 \protected_separator
7158 \protected_separator
7160 \protected_separator
7162 \protected_separator
7164 \protected_separator
7166 \protected_separator
7168 \protected_separator
7170 \protected_separator
7172 \protected_separator
7184 \protected_separator
7186 \protected_separator
7188 \protected_separator
7190 \protected_separator
7192 \protected_separator
7194 \protected_separator
7196 \protected_separator
7198 \protected_separator
7200 \protected_separator
7202 \protected_separator
7204 \protected_separator
7206 \protected_separator
7208 \protected_separator
7212 \protected_separator
7214 \protected_separator
7216 \protected_separator
7218 \protected_separator
7220 \protected_separator
7222 \protected_separator
7224 \protected_separator
7226 \protected_separator
7228 \protected_separator
7230 \protected_separator
7232 \protected_separator
7234 \protected_separator
7236 \protected_separator
7238 \protected_separator
7240 \protected_separator
7244 \protected_separator
7246 \protected_separator
7248 \protected_separator
7250 \protected_separator
7252 \protected_separator
7254 \protected_separator
7256 \protected_separator
7258 \protected_separator
7260 \protected_separator
7262 \protected_separator
7264 \protected_separator
7266 \protected_separator
7268 \protected_separator
7270 \protected_separator
7272 \protected_separator
7276 \protected_separator
7278 \protected_separator
7280 \protected_separator
7282 \protected_separator
7284 \protected_separator
7286 \protected_separator
7288 \protected_separator
7290 \protected_separator
7292 \protected_separator
7294 \protected_separator
7296 \protected_separator
7298 \protected_separator
7302 \protected_separator
7304 \protected_separator
7306 \protected_separator
7308 \protected_separator
7310 \protected_separator
7312 \protected_separator
7314 \protected_separator
7316 \protected_separator
7318 \protected_separator
7320 \protected_separator
7322 \protected_separator
7326 \protected_separator
7328 \protected_separator
7330 \protected_separator
7332 \protected_separator
7334 \protected_separator
7336 \protected_separator
7338 \protected_separator
7340 \protected_separator
7342 \protected_separator
7344 \protected_separator
7346 \protected_separator
7350 \protected_separator
7352 \protected_separator
7354 \protected_separator
7356 \protected_separator
7358 \protected_separator
7360 \protected_separator
7362 \protected_separator
7364 \protected_separator
7366 \protected_separator
7368 \protected_separator
7370 \protected_separator
7372 \protected_separator
7374 \protected_separator
7376 \protected_separator
7378 \protected_separator
7380 \protected_separator
7382 \protected_separator
7384 \protected_separator
7388 \protected_separator
7390 \protected_separator
7392 \protected_separator
7394 \protected_separator
7396 \protected_separator
7398 \protected_separator
7400 \protected_separator
7402 \protected_separator
7404 \protected_separator
7406 \protected_separator
7408 \protected_separator
7410 \protected_separator
7412 \protected_separator
7414 \protected_separator
7416 \protected_separator
7418 \protected_separator
7420 \protected_separator
7424 \protected_separator
7426 \protected_separator
7428 \protected_separator
7430 \protected_separator
7432 \protected_separator
7434 \protected_separator
7436 \protected_separator
7438 \protected_separator
7440 \protected_separator
7442 \protected_separator
7444 \protected_separator
7446 \protected_separator
7448 \protected_separator
7450 \protected_separator
7452 \protected_separator
7454 \protected_separator
7456 \protected_separator
7460 \protected_separator
7462 \protected_separator
7464 \protected_separator
7466 \protected_separator
7468 \protected_separator
7470 \protected_separator
7472 \protected_separator
7474 \protected_separator
7476 \protected_separator
7478 \protected_separator
7480 \protected_separator
7482 \protected_separator
7484 \protected_separator
7486 \protected_separator
7490 \protected_separator
7492 \protected_separator
7494 \protected_separator
7496 \protected_separator
7498 \protected_separator
7500 \protected_separator
7502 \protected_separator
7504 \protected_separator
7506 \protected_separator
7508 \protected_separator
7510 \protected_separator
7512 \protected_separator
7514 \protected_separator
7522 , --stack-after-data parameter should be used when using this routine, the
7523 routine also takes about 1K of code space .It also expects an external function
7528 to be present (this can be changed).
7529 When using the %s format the string / pointer should be cast to a generic
7537 \begin_inset Quotes eld
7540 my str %s, my int %d
7543 \begin_inset Quotes erd
7546 ,(char _generic *)mystr,myint);
7555 - contains definition for the following macros to be used for variable parameter
7556 list, note that a function can have a variable parameter list if and only
7557 if it is 'reentrant'
7563 va_list, va_start, va_arg, va_end.
7573 - contains defintion for ANSI
7582 Note in this case setjmp & longjmp can be used between functions executing
7583 within the same register bank, if long jmp is executed from a function
7584 that is using a different register bank from the function issuing the setjmp
7585 function, the results may be unpredictable.
7586 The jump buffer requires 3 bytes of data (the stack pointer & a 16 byte
7587 return address), and can be placed in any address space.
7596 - contains the following functions.
7612 - contains the following functions.
7618 strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn,
7619 strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.
7629 - contains the following routines.
7635 iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
7636 isxdigit, isalnum, isalpha.
7646 - The malloc routines are developed by Dmitry S.
7647 Obukhov (dso@usa.net).
7648 These routines will allocate memory from the external ram.
7649 Here is a description on how to use them (as described by the author).
7658 \protected_separator
7660 \protected_separator
7662 \protected_separator
7664 \protected_separator
7666 \protected_separator
7668 \protected_separator
7670 \protected_separator
7672 \protected_separator
7673 #define DYNAMIC_MEMORY_SIZE 0x2000
7676 \protected_separator
7678 \protected_separator
7680 \protected_separator
7682 \protected_separator
7684 \protected_separator
7686 \protected_separator
7688 \protected_separator
7690 \protected_separator
7695 \protected_separator
7697 \protected_separator
7699 \protected_separator
7701 \protected_separator
7703 \protected_separator
7705 \protected_separator
7707 \protected_separator
7709 \protected_separator
7710 unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
7713 \protected_separator
7715 \protected_separator
7717 \protected_separator
7719 \protected_separator
7721 \protected_separator
7723 \protected_separator
7725 \protected_separator
7727 \protected_separator
7728 unsigned char xdata * current_buffer;
7731 \protected_separator
7733 \protected_separator
7735 \protected_separator
7737 \protected_separator
7739 \protected_separator
7741 \protected_separator
7743 \protected_separator
7745 \protected_separator
7750 \protected_separator
7752 \protected_separator
7754 \protected_separator
7756 \protected_separator
7758 \protected_separator
7760 \protected_separator
7762 \protected_separator
7764 \protected_separator
7768 \protected_separator
7770 \protected_separator
7772 \protected_separator
7774 \protected_separator
7776 \protected_separator
7778 \protected_separator
7780 \protected_separator
7782 \protected_separator
7786 \protected_separator
7788 \protected_separator
7790 \protected_separator
7792 \protected_separator
7794 \protected_separator
7796 \protected_separator
7798 \protected_separator
7800 \protected_separator
7802 \protected_separator
7804 \protected_separator
7806 \protected_separator
7808 \protected_separator
7813 \protected_separator
7815 \protected_separator
7817 \protected_separator
7819 \protected_separator
7821 \protected_separator
7823 \protected_separator
7825 \protected_separator
7827 \protected_separator
7829 \protected_separator
7831 \protected_separator
7833 \protected_separator
7835 \protected_separator
7837 \protected_separator
7838 init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
7841 \protected_separator
7843 \protected_separator
7845 \protected_separator
7847 \protected_separator
7849 \protected_separator
7851 \protected_separator
7853 \protected_separator
7855 \protected_separator
7857 \protected_separator
7859 \protected_separator
7861 \protected_separator
7863 \protected_separator
7864 //Now it's possible to use malloc.
7868 \protected_separator
7870 \protected_separator
7872 \protected_separator
7874 \protected_separator
7876 \protected_separator
7878 \protected_separator
7880 \protected_separator
7882 \protected_separator
7884 \protected_separator
7886 \protected_separator
7888 \protected_separator
7890 \protected_separator
7895 \protected_separator
7897 \protected_separator
7899 \protected_separator
7901 \protected_separator
7903 \protected_separator
7905 \protected_separator
7907 \protected_separator
7909 \protected_separator
7911 \protected_separator
7913 \protected_separator
7915 \protected_separator
7917 \protected_separator
7918 current_buffer = malloc(0x100);
7921 \protected_separator
7923 \protected_separator
7925 \protected_separator
7927 \protected_separator
7938 - Serial IO routines are also developed by Dmitry S.
7939 Obukhov (dso@usa.net).
7940 These routines are interrupt driven with a 256 byte circular buffer, they
7941 also expect external ram to be present.
7942 Please see documentation in file SDCCDIR/sdcc51lib/serial.c .
7943 Note the header file
7944 \begin_inset Quotes eld
7948 \begin_inset Quotes erd
7951 MUST be included in the file containing the 'main' function.
7960 - Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.co
7961 m> these routines are more compact and faster.
7962 Please see documentation in file SDCCDIR/sdcc51lib/ser.c
7971 - Another alternate set of serial routines provided by Josef Wolf <jw@raven.inka.d
7972 e> , these routines do not use the external ram.
7981 - contains register definitions for a standard 8051
7990 - contains register definitions for 80C552.
7999 - contains min, max and other floating point related stuff.
8002 All library routines are compiled as --model-small , they are all non-reentrant,
8003 if you plan to use the large model or want to make these routines reentrant,
8004 then they will have to be recompiled with the appropriate compiler option.
8007 Have not had time to do the more involved routines like printf, will get
8011 Interfacing with assembly routines.
8012 \begin_inset LatexCommand \label{Interface_asm}
8019 Global registers used for parameter passing.
8022 By default the compiler uses the global registers
8023 \begin_inset Quotes eld
8027 \begin_inset Quotes erd
8030 to pass the first parameter to a routine, the second parameter onwards
8031 is either allocated on the stack (for reentrant routines or --stack-auto
8032 is used) or in the internal / external ram (depending on the memory model).
8034 \layout Subsubsection
8036 Assembler routine non-reentrant
8039 In the following example the function
8043 calls an assembler routine
8047 , which takes two parameters.
8052 extern int asm_func( unsigned short, unsigned short);
8058 \protected_separator
8061 int c_func (unsigned short i, unsigned short j)
8066 \protected_separator
8068 \protected_separator
8070 \protected_separator
8072 \protected_separator
8074 \protected_separator
8076 \protected_separator
8078 \protected_separator
8079 return asm_func(i,j);
8092 \protected_separator
8094 \protected_separator
8096 \protected_separator
8097 return c_func(10,9);
8102 The corresponding assembler function is:-
8108 \protected_separator
8110 \protected_separator
8112 \protected_separator
8114 \protected_separator
8116 \protected_separator
8118 \protected_separator
8120 \protected_separator
8121 .globl _asm_func_PARM_2
8124 \protected_separator
8126 \protected_separator
8128 \protected_separator
8130 \protected_separator
8132 \protected_separator
8134 \protected_separator
8136 \protected_separator
8140 \protected_separator
8142 \protected_separator
8144 \protected_separator
8146 \protected_separator
8148 \protected_separator
8150 \protected_separator
8152 \protected_separator
8156 \protected_separator
8158 \protected_separator
8160 \protected_separator
8162 \protected_separator
8164 \protected_separator
8166 \protected_separator
8168 \protected_separator
8170 \protected_separator
8172 \protected_separator
8174 \protected_separator
8176 \protected_separator
8180 \protected_separator
8182 \protected_separator
8184 \protected_separator
8186 \protected_separator
8188 \protected_separator
8190 \protected_separator
8192 \protected_separator
8198 \protected_separator
8200 \protected_separator
8202 \protected_separator
8204 \protected_separator
8206 \protected_separator
8208 \protected_separator
8210 \protected_separator
8212 \protected_separator
8214 \protected_separator
8216 \protected_separator
8218 \protected_separator
8222 \protected_separator
8224 \protected_separator
8226 \protected_separator
8228 \protected_separator
8230 \protected_separator
8232 \protected_separator
8234 \protected_separator
8236 \protected_separator
8238 \protected_separator
8240 \protected_separator
8242 \protected_separator
8246 \protected_separator
8248 \protected_separator
8250 \protected_separator
8252 \protected_separator
8254 \protected_separator
8256 \protected_separator
8258 \protected_separator
8260 \protected_separator
8262 \protected_separator
8264 \protected_separator
8266 \protected_separator
8270 \protected_separator
8272 \protected_separator
8274 \protected_separator
8276 \protected_separator
8278 \protected_separator
8280 \protected_separator
8282 \protected_separator
8284 \protected_separator
8286 \protected_separator
8288 \protected_separator
8290 \protected_separator
8294 \protected_separator
8296 \protected_separator
8298 \protected_separator
8300 \protected_separator
8302 \protected_separator
8304 \protected_separator
8306 \protected_separator
8310 Note here that the return values are placed in 'dpl' - One byte return value,
8311 'dpl' LSB & 'dph' MSB for two byte values.
8312 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
8313 b' & 'acc' for four byte values.
8316 The parameter naming convention is
8318 _<function_name>_PARM_<n>,
8320 where n is the parameter number starting from 1, and counting from the
8322 The first parameter is passed in
8323 \begin_inset Quotes eld
8327 \begin_inset Quotes erd
8330 for One bye parameter,
8331 \begin_inset Quotes eld
8335 \begin_inset Quotes erd
8339 \begin_inset Quotes eld
8343 \begin_inset Quotes erd
8347 \begin_inset Quotes eld
8351 \begin_inset Quotes erd
8358 varaible name for the second parameter will be _<function_name>_PARM_2.
8361 Assemble the assembler routine with the following command.
8364 asx8051 -losg asmfunc.asm
8367 Then compile and link the assembler routine to the C source file with the
8371 sdcc cfunc.c asmfunc.rel
8372 \layout Subsubsection
8374 Assembler routine is reentrant
8377 In this case the second parameter onwards will be passed on the stack ,
8378 the parameters are pushed from right to left i.e.
8379 after the call the left most parameter will be on the top of the stack.
8385 extern int asm_func( unsigned short, unsigned short);
8391 \protected_separator
8397 int c_func (unsigned short i, unsigned short j) reentrant
8402 \protected_separator
8404 \protected_separator
8406 \protected_separator
8408 \protected_separator
8410 \protected_separator
8412 \protected_separator
8414 \protected_separator
8415 return asm_func(i,j);
8428 \protected_separator
8430 \protected_separator
8432 \protected_separator
8433 return c_func(10,9);
8438 The corresponding assembler routine is.
8444 \protected_separator
8446 \protected_separator
8448 \protected_separator
8450 \protected_separator
8452 \protected_separator
8454 \protected_separator
8456 \protected_separator
8462 \protected_separator
8464 \protected_separator
8466 \protected_separator
8468 \protected_separator
8470 \protected_separator
8472 \protected_separator
8474 \protected_separator
8476 \protected_separator
8480 \protected_separator
8482 \protected_separator
8484 \protected_separator
8486 \protected_separator
8488 \protected_separator
8490 \protected_separator
8492 \protected_separator
8494 \protected_separator
8498 \protected_separator
8500 \protected_separator
8502 \protected_separator
8504 \protected_separator
8506 \protected_separator
8508 \protected_separator
8510 \protected_separator
8512 \protected_separator
8514 \protected_separator
8518 \protected_separator
8520 \protected_separator
8522 \protected_separator
8524 \protected_separator
8526 \protected_separator
8528 \protected_separator
8530 \protected_separator
8532 \protected_separator
8536 \protected_separator
8538 \protected_separator
8540 \protected_separator
8542 \protected_separator
8544 \protected_separator
8546 \protected_separator
8548 \protected_separator
8550 \protected_separator
8554 \protected_separator
8556 \protected_separator
8558 \protected_separator
8560 \protected_separator
8562 \protected_separator
8564 \protected_separator
8566 \protected_separator
8568 \protected_separator
8572 \protected_separator
8574 \protected_separator
8576 \protected_separator
8578 \protected_separator
8580 \protected_separator
8582 \protected_separator
8584 \protected_separator
8586 \protected_separator
8590 \protected_separator
8592 \protected_separator
8594 \protected_separator
8596 \protected_separator
8598 \protected_separator
8600 \protected_separator
8602 \protected_separator
8604 \protected_separator
8608 \protected_separator
8610 \protected_separator
8612 \protected_separator
8614 \protected_separator
8616 \protected_separator
8618 \protected_separator
8620 \protected_separator
8622 \protected_separator
8626 \protected_separator
8628 \protected_separator
8630 \protected_separator
8632 \protected_separator
8634 \protected_separator
8636 \protected_separator
8638 \protected_separator
8640 \protected_separator
8644 \protected_separator
8646 \protected_separator
8648 \protected_separator
8650 \protected_separator
8652 \protected_separator
8654 \protected_separator
8656 \protected_separator
8658 \protected_separator
8662 \protected_separator
8664 \protected_separator
8666 \protected_separator
8668 \protected_separator
8670 \protected_separator
8672 \protected_separator
8674 \protected_separator
8676 \protected_separator
8680 \protected_separator
8682 \protected_separator
8684 \protected_separator
8686 \protected_separator
8688 \protected_separator
8690 \protected_separator
8692 \protected_separator
8694 \protected_separator
8698 \protected_separator
8700 \protected_separator
8702 \protected_separator
8704 \protected_separator
8706 \protected_separator
8708 \protected_separator
8710 \protected_separator
8712 \protected_separator
8716 \protected_separator
8718 \protected_separator
8720 \protected_separator
8722 \protected_separator
8724 \protected_separator
8726 \protected_separator
8728 \protected_separator
8730 \protected_separator
8734 \protected_separator
8736 \protected_separator
8738 \protected_separator
8740 \protected_separator
8742 \protected_separator
8744 \protected_separator
8746 \protected_separator
8750 The compiling and linking procedure remains the same, however note the extra
8751 entry & exit linkage required for the assembler code, _bp is the stack
8752 frame pointer and is used to compute the offset into the stack for parameters
8753 and local variables.
8756 With --noregparms option.
8759 When the source is compiled with --noregparms option , space is allocated
8760 for each of the parameters passed to a routine.
8761 \layout Subsubsection
8763 Assembler routine non-reentrant.
8766 In the following example the function
8770 calls an assembler routine
8774 , which takes two parameters.
8779 extern int asm_func( unsigned short, unsigned short);
8785 \protected_separator
8788 int c_func (unsigned short i, unsigned short j)
8793 \protected_separator
8795 \protected_separator
8797 \protected_separator
8799 \protected_separator
8801 \protected_separator
8803 \protected_separator
8805 \protected_separator
8806 return asm_func(i,j);
8819 \protected_separator
8821 \protected_separator
8823 \protected_separator
8824 return c_func(10,9);
8829 The corresponding assembler function is:-
8835 \protected_separator
8837 \protected_separator
8839 \protected_separator
8841 \protected_separator
8843 \protected_separator
8845 \protected_separator
8847 \protected_separator
8848 .globl _asm_func_PARM_1
8851 \protected_separator
8853 \protected_separator
8855 \protected_separator
8857 \protected_separator
8859 \protected_separator
8861 \protected_separator
8863 \protected_separator
8864 .globl _asm_func_PARM_2
8867 \protected_separator
8869 \protected_separator
8871 \protected_separator
8873 \protected_separator
8875 \protected_separator
8877 \protected_separator
8879 \protected_separator
8883 \protected_separator
8885 \protected_separator
8887 \protected_separator
8889 \protected_separator
8891 \protected_separator
8893 \protected_separator
8895 \protected_separator
8899 \protected_separator
8901 \protected_separator
8903 \protected_separator
8905 \protected_separator
8907 \protected_separator
8909 \protected_separator
8911 \protected_separator
8913 \protected_separator
8915 \protected_separator
8917 \protected_separator
8921 \protected_separator
8923 \protected_separator
8925 \protected_separator
8927 \protected_separator
8929 \protected_separator
8931 \protected_separator
8933 \protected_separator
8935 \protected_separator
8937 \protected_separator
8939 \protected_separator
8941 \protected_separator
8945 \protected_separator
8947 \protected_separator
8949 \protected_separator
8951 \protected_separator
8953 \protected_separator
8955 \protected_separator
8957 \protected_separator
8963 \protected_separator
8965 \protected_separator
8967 \protected_separator
8969 \protected_separator
8971 \protected_separator
8973 \protected_separator
8975 \protected_separator
8977 \protected_separator
8979 \protected_separator
8981 \protected_separator
8983 \protected_separator
8987 \protected_separator
8989 \protected_separator
8991 \protected_separator
8993 \protected_separator
8995 \protected_separator
8997 \protected_separator
8999 \protected_separator
9001 \protected_separator
9003 \protected_separator
9005 \protected_separator
9007 \protected_separator
9011 \protected_separator
9013 \protected_separator
9015 \protected_separator
9017 \protected_separator
9019 \protected_separator
9021 \protected_separator
9023 \protected_separator
9025 \protected_separator
9027 \protected_separator
9029 \protected_separator
9031 \protected_separator
9035 \protected_separator
9037 \protected_separator
9039 \protected_separator
9041 \protected_separator
9043 \protected_separator
9045 \protected_separator
9047 \protected_separator
9049 \protected_separator
9051 \protected_separator
9053 \protected_separator
9055 \protected_separator
9059 \protected_separator
9061 \protected_separator
9063 \protected_separator
9065 \protected_separator
9067 \protected_separator
9069 \protected_separator
9071 \protected_separator
9075 Note here that the return values are placed in 'dpl' - One byte return value,
9076 'dpl' LSB & 'dph' MSB for two byte values.
9077 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
9078 b' & 'acc' for four byte values.
9081 The parameter naming convention is
9083 _<function_name>_PARM_<n>,
9085 where n is the parameter number starting from 1, and counting from the
9092 left-most parameter name will be _<function_name>_PARM_1.
9095 Assemble the assembler routine with the following command.
9098 asx8051 -losg asmfunc.asm
9101 Then compile and link the assembler routine to the C source file with the
9105 sdcc cfunc.c asmfunc.rel
9106 \layout Subsubsection
9108 Assembler routine is reentrant.
9111 In this case the parameters will be passed on the stack , the parameters
9112 are pushed from right to left i.e.
9113 after the call the left most parameter will be on the top of the stack.
9119 extern int asm_func( unsigned short, unsigned short);
9125 \protected_separator
9131 int c_func (unsigned short i, unsigned short j) reentrant
9136 \protected_separator
9138 \protected_separator
9140 \protected_separator
9142 \protected_separator
9144 \protected_separator
9146 \protected_separator
9148 \protected_separator
9149 return asm_func(i,j);
9162 \protected_separator
9164 \protected_separator
9166 \protected_separator
9167 return c_func(10,9);
9172 The corresponding assembler routine is.
9178 \protected_separator
9180 \protected_separator
9182 \protected_separator
9184 \protected_separator
9186 \protected_separator
9188 \protected_separator
9190 \protected_separator
9196 \protected_separator
9198 \protected_separator
9200 \protected_separator
9202 \protected_separator
9204 \protected_separator
9206 \protected_separator
9208 \protected_separator
9210 \protected_separator
9214 \protected_separator
9216 \protected_separator
9218 \protected_separator
9220 \protected_separator
9222 \protected_separator
9224 \protected_separator
9226 \protected_separator
9228 \protected_separator
9232 \protected_separator
9234 \protected_separator
9236 \protected_separator
9238 \protected_separator
9240 \protected_separator
9242 \protected_separator
9244 \protected_separator
9246 \protected_separator
9250 \protected_separator
9252 \protected_separator
9254 \protected_separator
9256 \protected_separator
9258 \protected_separator
9260 \protected_separator
9262 \protected_separator
9264 \protected_separator
9268 \protected_separator
9270 \protected_separator
9272 \protected_separator
9274 \protected_separator
9276 \protected_separator
9278 \protected_separator
9280 \protected_separator
9282 \protected_separator
9286 \protected_separator
9288 \protected_separator
9290 \protected_separator
9292 \protected_separator
9294 \protected_separator
9296 \protected_separator
9298 \protected_separator
9300 \protected_separator
9304 \protected_separator
9306 \protected_separator
9308 \protected_separator
9310 \protected_separator
9312 \protected_separator
9314 \protected_separator
9316 \protected_separator
9318 \protected_separator
9322 \protected_separator
9324 \protected_separator
9326 \protected_separator
9328 \protected_separator
9330 \protected_separator
9332 \protected_separator
9334 \protected_separator
9336 \protected_separator
9340 \protected_separator
9342 \protected_separator
9344 \protected_separator
9346 \protected_separator
9348 \protected_separator
9350 \protected_separator
9352 \protected_separator
9354 \protected_separator
9358 \protected_separator
9360 \protected_separator
9362 \protected_separator
9364 \protected_separator
9366 \protected_separator
9368 \protected_separator
9370 \protected_separator
9372 \protected_separator
9376 \protected_separator
9378 \protected_separator
9380 \protected_separator
9382 \protected_separator
9384 \protected_separator
9386 \protected_separator
9388 \protected_separator
9390 \protected_separator
9394 \protected_separator
9396 \protected_separator
9398 \protected_separator
9400 \protected_separator
9402 \protected_separator
9404 \protected_separator
9406 \protected_separator
9408 \protected_separator
9412 \protected_separator
9414 \protected_separator
9416 \protected_separator
9418 \protected_separator
9420 \protected_separator
9422 \protected_separator
9424 \protected_separator
9426 \protected_separator
9430 \protected_separator
9432 \protected_separator
9434 \protected_separator
9436 \protected_separator
9438 \protected_separator
9440 \protected_separator
9442 \protected_separator
9444 \protected_separator
9448 \protected_separator
9450 \protected_separator
9452 \protected_separator
9454 \protected_separator
9456 \protected_separator
9458 \protected_separator
9460 \protected_separator
9462 \protected_separator
9466 \protected_separator
9468 \protected_separator
9470 \protected_separator
9472 \protected_separator
9474 \protected_separator
9476 \protected_separator
9478 \protected_separator
9480 \protected_separator
9484 \protected_separator
9486 \protected_separator
9488 \protected_separator
9490 \protected_separator
9492 \protected_separator
9494 \protected_separator
9496 \protected_separator
9500 The compiling and linking procedure remains the same, however note the extra
9501 entry & exit linkage required for the assembler code, _bp is the stack
9502 frame pointer and is used to compute the offset into the stack for parameters
9503 and local variables.
9507 \begin_inset LatexCommand \label{xstack}
9514 The external stack is located at the start of the external ram segment ,
9515 and is 256 bytes in size.
9516 When --xstack option is used to compile the program , the parameters and
9517 local variables of all reentrant functions are allocated in this area.
9518 This option is provided for programs with large stack space requirements.
9519 When used with the --stack-auto option, all parameters and local variables
9520 are allocated on the external stack (note support libraries will need to
9521 be recompiled with the same options).
9524 The compiler outputs the higher order address byte of the external ram segment
9525 into PORT P2, therefore when using the External Stack option, this port
9526 MAY NOT be used by the application program.
9530 \begin_inset LatexCommand \label{ANSI_Compliance}
9537 Deviations from the compliancy.
9540 functions are not always reentrant.
9543 structures cannot be assigned values directly, cannot be passed as function
9544 parameters or assigned to each other and cannot be a return value from
9569 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
9579 struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
9589 return rets;/* is invalid in SDCC although allowed in ANSI */
9594 'long long' (64 bit integers) not supported.
9597 'double' precision floating point not supported.
9600 integral promotions are suppressed.
9601 What does this mean ? The compiler will not implicitly promote an integer
9602 expression to a higher order integer, exception is an assignment or parameter
9618 Old K&R style function declarations are NOT allowed.
9623 foo( i,j) /* this old style of function declarations */
9625 int i,j; /* are valid in ANSI ..
9626 not valid in SDCC */
9636 functions declared as pointers must be dereferenced during the call.
9649 \protected_separator
9651 \protected_separator
9656 \protected_separator
9658 \protected_separator
9659 /* has to be called like this */
9662 \protected_separator
9664 \protected_separator
9665 (*foo)();/* ansi standard allows calls to be made like 'foo()' */
9668 Cyclomatic Complexity
9669 \begin_inset LatexCommand \label{Cyclomatic}
9676 Cyclomatic complexity of a function is defined as the number of independent
9677 paths the program can take during execution of the function.
9678 This is an important number since it defines the number test cases you
9679 have to generate to validate the function .
9680 The accepted industry standard for complexity number is 10, if the cyclomatic
9681 complexity reported by SDCC exceeds 10 you should think about simplification
9682 of the function logic.
9685 Note that the complexity level is not related to the number of lines of
9687 Large functions can have low complexity, and small functions can have large
9689 SDCC uses the following formula to compute the complexity.
9694 complexity = (number of edges in control flow graph) -
9697 \protected_separator
9699 \protected_separator
9701 \protected_separator
9703 \protected_separator
9705 \protected_separator
9707 \protected_separator
9709 \protected_separator
9710 (number of nodes in control flow graph) + 2;
9713 Having said that the industry standard is 10, you should be aware that in
9714 some cases it may unavoidable to have a complexity level of less than 10.
9715 For example if you have switch statement with more than 10 case labels,
9716 each case label adds one to the complexity level.
9717 The complexity level is by no means an absolute measure of the algorithmic
9718 complexity of the function, it does however provide a good starting point
9719 for which functions you might look at for further optimization.
9723 \begin_inset LatexCommand \label{Tips}
9730 Here are a few guide-lines that will help the compiler generate more efficient
9731 code, some of the tips are specific to this compiler others are generally
9732 good programming practice.
9735 Use the smallest data type to represent your data-value.
9736 If it is known in advance that the value is going to be less than 256 then
9737 use a 'short' or 'char' instead of an 'int'.
9740 Use unsigned when it is known in advance that the value is not going to
9742 This helps especially if you are doing division or multiplication.
9745 NEVER jump into a LOOP.
9748 Declare the variables to be local whenever possible, especially loop control
9749 variables (induction).
9752 Since the compiler does not do implicit integral promotion, the programmer
9753 should do an explicit cast when integral promotion is required.
9756 Reducing the size of division , multiplication & modulus operations can
9757 reduce code size substantially.
9758 Take the following code for example.
9764 foobar( unsigned int p1, unsigned char ch)
9769 \protected_separator
9771 \protected_separator
9773 \protected_separator
9775 \protected_separator
9776 unsigned char ch1 = p1 % ch ;
9779 \protected_separator
9781 \protected_separator
9783 \protected_separator
9785 \protected_separator
9787 \protected_separator
9789 \protected_separator
9791 \protected_separator
9793 \protected_separator
9799 For the modulus operation the variable ch will be promoted to unsigned int
9800 first then the modulus operation will be performed (this will lead to a
9801 call to a support routine).
9802 If the code is changed to
9807 foobar( unsigned int p1, unsigned char ch)
9812 \protected_separator
9814 \protected_separator
9816 \protected_separator
9818 \protected_separator
9819 unsigned char ch1 = (unsigned char)p1 % ch ;
9822 \protected_separator
9824 \protected_separator
9826 \protected_separator
9828 \protected_separator
9830 \protected_separator
9832 \protected_separator
9834 \protected_separator
9836 \protected_separator
9842 It would substantially reduce the code generated (future versions of the
9843 compiler will be smart enough to detect such optimization oppurtunities).
9849 Notes from an USER ( Trefor@magera.freeserve.co.uk )
9852 The 8051 family of micro controller have a minimum of 128 bytes of internal
9853 memory which is structured as follows
9856 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
9860 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
9863 - Bytes 30-7F - 60 bytes for general purpose use.
9866 Normally the SDCC compiler will only utilise the first bank of registers,
9867 but it is possible to specify that other banks of registers should be used
9868 in interrupt routines.
9869 By default, the compiler will place the stack after the last bank of used
9871 if the first 2 banks of registers are used, it will position the base of
9872 the internal stack at address 16 (0X10).
9873 This implies that as the stack grows, it will use up the remaining register
9874 banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
9875 general purpose use.
9878 By default, the compiler uses the 60 general purpose bytes to hold "near
9880 The compiler/optimiser may also declare some Local Variables in this area
9885 If any of the 128 bit variables are used, or near data is being used then
9886 care needs to be taken to ensure that the stack does not grow so much that
9887 it starts to over write either your bit variables or "near data".
9888 There is no runtime checking to prevent this from happening.
9891 The amount of stack being used is affected by the use of the "internal stack"
9892 to save registers before a subroutine call is made, - --stack-auto will
9893 declare parameters and local variables on the stack - the number of nested
9897 If you detect that the stack is over writing you data, then the following
9899 --xstack will cause an external stack to be used for saving registers and
9900 (if --stack-auto is being used) storing parameters and local variables.
9901 However this will produce more and code which will be slower to execute.
9905 --stack-loc will allow you specify the start of the stack, i.e.
9906 you could start it after any data in the general purpose area.
9907 However this may waste the memory not used by the register banks and if
9908 the size of the "near data" increases, it may creep into the bottom of
9912 --stack-after-data, similar to the --stack-loc, but it automatically places
9913 the stack after the end of the "near data".
9914 Again this could waste any spare register space.
9917 --data-loc allows you to specify the start address of the near data.
9918 This could be used to move the "near data" further away from the stack
9919 giving it more room to grow.
9920 This will only work if no bit variables are being used and the stack can
9921 grow to use the bit variable space.
9927 If you find that the stack is over writing your bit variables or "near data"
9928 then the approach which best utilised the internal memory is to position
9929 the "near data" after the last bank of used registers or, if you use bit
9930 variables, after the last bit variable by using the --data-loc, e.g.
9931 if two register banks are being used and no data variables, --data-loc
9932 16, and - use the --stack-after-data option.
9935 If bit variables are being used, another method would be to try and squeeze
9936 the data area in the unused register banks if it will fit, and start the
9937 stack after the last bit variable.
9940 Retargetting for other MCUs.
9941 \begin_inset LatexCommand \label{Retargetting}
9948 The issues for retargetting the compiler are far too numerous to be covered
9950 What follows is a brief description of each of the seven phases of the
9951 compiler and its MCU dependency.
9954 Parsing the source and building the annotated parse tree.
9955 This phase is largely MCU independent (except for the language extensions).
9956 Syntax & semantic checks are also done in this phase , along with some
9957 initial optimizations like back patching labels and the pattern matching
9958 optimizations like bit-rotation etc.
9961 The second phase involves generating an intermediate code which can be easy
9962 manipulated during the later phases.
9963 This phase is entirely MCU independent.
9964 The intermediate code generation assumes the target machine has unlimited
9965 number of registers, and designates them with the name iTemp.
9966 The compiler can be made to dump a human readable form of the code generated
9967 by using the --dumpraw option.
9970 This phase does the bulk of the standard optimizations and is also MCU independe
9972 This phase can be broken down into several sub-phases.
9976 Break down intermediate code (iCode) into basic blocks.
9979 Do control flow & data flow analysis on the basic blocks.
9982 Do local common subexpression elimination, then global subexpression elimination
9985 dead code elimination
9991 if loop optimizations caused any changes then do 'global subexpression eliminati
9992 on' and 'dead code elimination' again.
9996 This phase determines the live-ranges; by live range I mean those iTemp
9997 variables defined by the compiler that still survive after all the optimization
9999 Live range analysis is essential for register allocation, since these computati
10000 on determines which of these iTemps will be assigned to registers, and for
10004 Phase five is register allocation.
10005 There are two parts to this process .
10009 The first part I call 'register packing' (for lack of a better term) .
10010 In this case several MCU specific expression folding is done to reduce
10014 The second part is more MCU independent and deals with allocating registers
10015 to the remaining live ranges.
10016 A lot of MCU specific code does creep into this phase because of the limited
10017 number of index registers available in the 8051.
10021 The Code generation phase is (unhappily), entirely MCU dependent and very
10022 little (if any at all) of this code can be reused for other MCU.
10023 However the scheme for allocating a homogenized assembler operand for each
10024 iCode operand may be reused.
10027 As mentioned in the optimization section the peep-hole optimizer is rule
10028 based system, which can reprogrammed for other MCUs.
10032 \begin_inset LatexCommand \label{Bugs}
10039 Shoot of an email to 'sandeep.dutta@usa.net', as a matter of principle I always
10040 reply to all email's sent to me.
10041 Bugs will be fixed ASAP.
10042 When reporting a bug , it is useful to include a small snippet of code
10043 that is causing the problem, if possible compile your program with the
10044 --dumpall option and send the dump files along with the bug report.
10047 SDCDB - Source level debugger.
10050 SDCC is distributed with a source level debugger.
10051 The debugger uses a command line interface, the command repertoire of the
10052 debugger has been kept as close to gdb ( the GNU debugger) as possible.
10053 The configuration and build process of the compiler see Installation
10054 \begin_inset LatexCommand \ref{Installation}
10058 also builds and installs the debugger in the target directory specified
10059 during configuration.
10060 The debugger allows you debug BOTH at the C source and at the ASM source
10064 Compiling for debugging.
10071 option must be specified for all files for which debug information is to
10073 The complier generates a
10077 file for each of these files.
10078 The linker updates the
10082 file with the address information.
10083 This .cdb is used by the debugger .
10086 How the debugger works.
10093 option is specified the compiler generates extra symbol information some
10094 of which are put into the the assembler source and some are put into the
10095 .cdb file, the linker updates the .cdb file with the address information
10097 The debugger reads the symbolic information generated by the compiler &
10098 the address information generated by the linker.
10099 It uses the SIMULATOR (Daniel's S51) to execute the program, the program
10100 execution is controlled by the debugger.
10101 When a command is issued for the debugger, it translates it into appropriate
10102 commands for the simulator .
10105 Starting the debugger.
10108 The debugger can be started using the following command line.
10109 (Assume the file you are debugging has
10112 the file name foo).
10118 The debugger will look for the following files.
10121 foo.c - the source file.
10124 foo.cdb - the debugger symbol information file.
10127 foo.ihx - the intel hex format object file.
10130 Command line options.
10133 --directory=<source file directory> this option can used to specify the
10134 directory search list.
10135 The debugger will look into the directory list specified for source , cdb
10137 The items in the directory list must be separated by ':' , e.g.
10138 if the source files can be in the directories /home/src1 and /home/src2,
10139 the --directory option should be --directory=/home/src1:/home/src2 .
10140 Note there can be no spaces in the option.
10144 -cd <directory> - change to the <directory>.
10147 -fullname - used by GUI front ends.
10150 -cpu <cpu-type> - this argument is passed to the simulator please see the
10151 simulator docs for details.
10154 -X <Clock frequency > this options is passed to the simulator please see
10155 simulator docs for details.
10158 -s <serial port file> passed to simulator see simulator docs for details.
10161 -S <serial in,out> passed to simulator see simulator docs for details.
10167 As mention earlier the command interface for the debugger has been deliberately
10168 kept as close the GNU debugger gdb , as possible, this will help int integratio
10169 n with existing graphical user interfaces (like ddd, xxgdb or xemacs) existing
10170 for the GNU debugger.
10171 \layout Subsubsection
10173 break [line | file:line | function | file:function]
10176 Set breakpoint at specified line or function.
10181 sdcdb>break foo.c:100
10183 sdcdb>break funcfoo
10185 sdcdb>break foo.c:funcfoo
10186 \layout Subsubsection
10188 clear [line | file:line | function | file:function ]
10191 Clear breakpoint at specified line or function.
10196 sdcdb>clear foo.c:100
10198 sdcdb>clear funcfoo
10200 sdcdb>clear foo.c:funcfoo
10201 \layout Subsubsection
10206 Continue program being debugged, after breakpoint.
10207 \layout Subsubsection
10212 Execute till the end of the current function.
10213 \layout Subsubsection
10218 Delete breakpoint number 'n'.
10219 If used without any option clear ALL user defined break points.
10220 \layout Subsubsection
10222 info [break | stack | frame | registers ]
10225 info break - list all breakpoints
10228 info stack - show the function call stack.
10231 info frame - show information about the current execution frame.
10234 info registers - show content of all registers.
10235 \layout Subsubsection
10240 Step program until it reaches a different source line.
10241 \layout Subsubsection
10246 Step program, proceeding through subroutine calls.
10247 \layout Subsubsection
10252 Start debugged program.
10253 \layout Subsubsection
10258 Print type information of the variable.
10259 \layout Subsubsection
10264 print value of variable.
10265 \layout Subsubsection
10270 load the given file name.
10271 Note this is an alternate method of loading file for debugging.
10272 \layout Subsubsection
10277 print information about current frame.
10278 \layout Subsubsection
10283 Toggle between C source & assembly source.
10284 \layout Subsubsection
10286 ! simulator command
10289 Send the string following '!' to the simulator, the simulator response is
10291 Note the debugger does not interpret the command being sent to the simulator,
10292 so if a command like 'go' is sent the debugger can loose its execution
10293 context and may display incorrect values.
10294 \layout Subsubsection
10301 My name is Bobby Brown"
10304 Interfacing with XEmacs.
10307 Two files are (in emacs lisp) are provided for the interfacing with XEmacs,
10316 These two files can be found in the $(prefix)/bin directory after the installat
10318 These files need to be loaded into XEmacs for the interface to work, this
10319 can be done at XEmacs startup time by inserting the following into your
10324 file (which can be found in your HOME directory)
10326 (load-file sdcdbsrc.el)
10328 [ .xemacs is a lisp file so the () around the command is REQUIRED), the files
10329 can also be loaded dynamically while XEmacs is running, set the environment
10334 to the installation bin directory [$(prefix)/bin], then enter the following
10337 ESC-x load-file sdcdbsrc .
10340 To start the interface enter the following command
10344 , you will prompted to enter the file name to be debugged.
10348 The command line options that are passed to the simulator directly are bound
10349 to default values in the file
10353 the variables are listed below these values maybe changed as required.
10356 sdcdbsrc-cpu-type '51
10359 sdcdbsrc-frequency '11059200
10362 sdcdbsrc-serial nil
10365 The following is a list of key mapping for the debugger interface.
10369 \protected_separator
10374 ;; Current Listing ::
10377 \protected_separator
10379 \protected_separator
10381 \protected_separator
10383 \protected_separator
10385 \protected_separator
10387 \protected_separator
10389 \protected_separator
10391 \protected_separator
10393 \protected_separator
10395 \protected_separator
10397 \protected_separator
10399 \protected_separator
10401 \protected_separator
10403 \protected_separator
10405 \protected_separator
10407 \protected_separator
10409 \protected_separator
10411 \protected_separator
10413 \protected_separator
10415 \protected_separator
10417 \protected_separator
10419 \protected_separator
10421 \protected_separator
10423 \protected_separator
10425 \protected_separator
10427 \protected_separator
10429 \protected_separator
10431 \protected_separator
10433 \protected_separator
10435 \protected_separator
10437 \protected_separator
10439 \protected_separator
10441 \protected_separator
10443 \protected_separator
10445 \protected_separator
10447 \protected_separator
10449 \protected_separator
10453 \protected_separator
10455 \protected_separator
10457 \protected_separator
10459 \protected_separator
10461 \protected_separator
10463 \protected_separator
10465 \protected_separator
10467 \protected_separator
10469 \protected_separator
10471 \protected_separator
10473 \protected_separator
10475 \protected_separator
10477 \protected_separator
10479 \protected_separator
10481 \protected_separator
10483 \protected_separator
10485 \protected_separator
10487 \protected_separator
10489 \protected_separator
10491 \protected_separator
10493 \protected_separator
10495 \protected_separator
10497 \protected_separator
10499 \protected_separator
10501 \protected_separator
10503 \protected_separator
10505 \protected_separator
10507 \protected_separator
10509 \protected_separator
10511 \protected_separator
10513 \protected_separator
10515 \protected_separator
10517 \protected_separator
10519 \protected_separator
10521 \protected_separator
10523 \protected_separator
10525 \protected_separator
10531 \protected_separator
10533 \protected_separator
10535 \protected_separator
10537 \protected_separator
10539 \protected_separator
10541 \protected_separator
10543 \protected_separator
10545 \protected_separator
10547 \protected_separator
10549 \protected_separator
10551 \protected_separator
10553 \protected_separator
10555 \protected_separator
10557 \protected_separator
10558 sdcdb-next-from-src
10559 \protected_separator
10561 \protected_separator
10563 \protected_separator
10565 \protected_separator
10567 \protected_separator
10569 \protected_separator
10571 \protected_separator
10573 \protected_separator
10575 \protected_separator
10577 \protected_separator
10581 \protected_separator
10583 \protected_separator
10585 \protected_separator
10587 \protected_separator
10589 \protected_separator
10591 \protected_separator
10593 \protected_separator
10595 \protected_separator
10597 \protected_separator
10599 \protected_separator
10601 \protected_separator
10603 \protected_separator
10605 \protected_separator
10607 \protected_separator
10608 sdcdb-back-from-src
10609 \protected_separator
10611 \protected_separator
10613 \protected_separator
10615 \protected_separator
10617 \protected_separator
10619 \protected_separator
10621 \protected_separator
10623 \protected_separator
10625 \protected_separator
10627 \protected_separator
10631 \protected_separator
10633 \protected_separator
10635 \protected_separator
10637 \protected_separator
10639 \protected_separator
10641 \protected_separator
10643 \protected_separator
10645 \protected_separator
10647 \protected_separator
10649 \protected_separator
10651 \protected_separator
10653 \protected_separator
10655 \protected_separator
10657 \protected_separator
10658 sdcdb-cont-from-src
10659 \protected_separator
10661 \protected_separator
10663 \protected_separator
10665 \protected_separator
10667 \protected_separator
10669 \protected_separator
10671 \protected_separator
10673 \protected_separator
10675 \protected_separator
10677 \protected_separator
10678 SDCDB continue command
10681 \protected_separator
10683 \protected_separator
10685 \protected_separator
10687 \protected_separator
10689 \protected_separator
10691 \protected_separator
10693 \protected_separator
10695 \protected_separator
10697 \protected_separator
10699 \protected_separator
10701 \protected_separator
10703 \protected_separator
10705 \protected_separator
10707 \protected_separator
10708 sdcdb-step-from-src
10709 \protected_separator
10711 \protected_separator
10713 \protected_separator
10715 \protected_separator
10717 \protected_separator
10719 \protected_separator
10721 \protected_separator
10723 \protected_separator
10725 \protected_separator
10727 \protected_separator
10731 \protected_separator
10733 \protected_separator
10735 \protected_separator
10737 \protected_separator
10739 \protected_separator
10741 \protected_separator
10743 \protected_separator
10745 \protected_separator
10747 \protected_separator
10749 \protected_separator
10751 \protected_separator
10753 \protected_separator
10755 \protected_separator
10757 \protected_separator
10758 sdcdb-whatis-c-sexp
10759 \protected_separator
10761 \protected_separator
10763 \protected_separator
10765 \protected_separator
10767 \protected_separator
10769 \protected_separator
10771 \protected_separator
10773 \protected_separator
10775 \protected_separator
10777 \protected_separator
10778 SDCDB ptypecommand for data at
10781 \protected_separator
10783 \protected_separator
10785 \protected_separator
10787 \protected_separator
10789 \protected_separator
10791 \protected_separator
10793 \protected_separator
10795 \protected_separator
10797 \protected_separator
10799 \protected_separator
10801 \protected_separator
10803 \protected_separator
10805 \protected_separator
10807 \protected_separator
10809 \protected_separator
10811 \protected_separator
10813 \protected_separator
10815 \protected_separator
10817 \protected_separator
10819 \protected_separator
10821 \protected_separator
10823 \protected_separator
10825 \protected_separator
10827 \protected_separator
10829 \protected_separator
10831 \protected_separator
10833 \protected_separator
10835 \protected_separator
10837 \protected_separator
10839 \protected_separator
10841 \protected_separator
10843 \protected_separator
10845 \protected_separator
10847 \protected_separator
10849 \protected_separator
10851 \protected_separator
10853 \protected_separator
10855 \protected_separator
10857 \protected_separator
10859 \protected_separator
10861 \protected_separator
10863 \protected_separator
10867 \protected_separator
10869 \protected_separator
10871 \protected_separator
10873 \protected_separator
10875 \protected_separator
10877 \protected_separator
10879 \protected_separator
10881 \protected_separator
10883 \protected_separator
10885 \protected_separator
10887 \protected_separator
10889 \protected_separator
10891 \protected_separator
10893 \protected_separator
10895 \protected_separator
10897 \protected_separator
10899 \protected_separator
10901 \protected_separator
10903 \protected_separator
10905 \protected_separator
10907 \protected_separator
10909 \protected_separator
10911 \protected_separator
10913 \protected_separator
10915 \protected_separator
10917 \protected_separator
10919 \protected_separator
10921 \protected_separator
10922 SDCDB Delete all breakpoints if no arg
10925 \protected_separator
10927 \protected_separator
10929 \protected_separator
10931 \protected_separator
10933 \protected_separator
10935 \protected_separator
10937 \protected_separator
10939 \protected_separator
10941 \protected_separator
10943 \protected_separator
10945 \protected_separator
10947 \protected_separator
10949 \protected_separator
10951 \protected_separator
10953 \protected_separator
10955 \protected_separator
10957 \protected_separator
10959 \protected_separator
10961 \protected_separator
10963 \protected_separator
10965 \protected_separator
10967 \protected_separator
10969 \protected_separator
10971 \protected_separator
10973 \protected_separator
10975 \protected_separator
10977 \protected_separator
10979 \protected_separator
10981 \protected_separator
10983 \protected_separator
10985 \protected_separator
10987 \protected_separator
10989 \protected_separator
10991 \protected_separator
10993 \protected_separator
10995 \protected_separator
10997 \protected_separator
10999 \protected_separator
11001 \protected_separator
11003 \protected_separator
11005 \protected_separator
11007 \protected_separator
11009 \protected_separator
11011 \protected_separator
11013 \protected_separator
11015 \protected_separator
11016 given or delete arg (C-u arg x)
11019 \protected_separator
11021 \protected_separator
11023 \protected_separator
11025 \protected_separator
11027 \protected_separator
11029 \protected_separator
11031 \protected_separator
11033 \protected_separator
11035 \protected_separator
11037 \protected_separator
11039 \protected_separator
11041 \protected_separator
11043 \protected_separator
11045 \protected_separator
11047 \protected_separator
11049 \protected_separator
11051 \protected_separator
11053 \protected_separator
11055 \protected_separator
11057 \protected_separator
11059 \protected_separator
11061 \protected_separator
11063 \protected_separator
11065 \protected_separator
11067 \protected_separator
11069 \protected_separator
11071 \protected_separator
11073 \protected_separator
11075 \protected_separator
11076 SDCDB Display current frame if no arg,
11079 \protected_separator
11081 \protected_separator
11083 \protected_separator
11085 \protected_separator
11087 \protected_separator
11089 \protected_separator
11091 \protected_separator
11093 \protected_separator
11095 \protected_separator
11097 \protected_separator
11099 \protected_separator
11101 \protected_separator
11103 \protected_separator
11105 \protected_separator
11107 \protected_separator
11109 \protected_separator
11111 \protected_separator
11113 \protected_separator
11115 \protected_separator
11117 \protected_separator
11119 \protected_separator
11121 \protected_separator
11123 \protected_separator
11125 \protected_separator
11127 \protected_separator
11129 \protected_separator
11131 \protected_separator
11133 \protected_separator
11135 \protected_separator
11137 \protected_separator
11139 \protected_separator
11141 \protected_separator
11143 \protected_separator
11145 \protected_separator
11147 \protected_separator
11149 \protected_separator
11151 \protected_separator
11153 \protected_separator
11155 \protected_separator
11157 \protected_separator
11159 \protected_separator
11161 \protected_separator
11163 \protected_separator
11165 \protected_separator
11167 \protected_separator
11169 \protected_separator
11170 given or display frame arg
11173 \protected_separator
11175 \protected_separator
11177 \protected_separator
11179 \protected_separator
11181 \protected_separator
11183 \protected_separator
11185 \protected_separator
11187 \protected_separator
11189 \protected_separator
11191 \protected_separator
11193 \protected_separator
11195 \protected_separator
11197 \protected_separator
11199 \protected_separator
11201 \protected_separator
11203 \protected_separator
11205 \protected_separator
11207 \protected_separator
11209 \protected_separator
11211 \protected_separator
11213 \protected_separator
11215 \protected_separator
11217 \protected_separator
11219 \protected_separator
11221 \protected_separator
11223 \protected_separator
11225 \protected_separator
11227 \protected_separator
11229 \protected_separator
11231 \protected_separator
11233 \protected_separator
11235 \protected_separator
11237 \protected_separator
11239 \protected_separator
11241 \protected_separator
11243 \protected_separator
11245 \protected_separator
11247 \protected_separator
11249 \protected_separator
11251 \protected_separator
11253 \protected_separator
11255 \protected_separator
11257 \protected_separator
11259 \protected_separator
11261 \protected_separator
11265 \protected_separator
11267 \protected_separator
11269 \protected_separator
11271 \protected_separator
11273 \protected_separator
11275 \protected_separator
11277 \protected_separator
11279 \protected_separator
11281 \protected_separator
11283 \protected_separator
11285 \protected_separator
11287 \protected_separator
11289 \protected_separator
11291 \protected_separator
11292 sdcdbsrc-goto-sdcdb
11293 \protected_separator
11295 \protected_separator
11297 \protected_separator
11299 \protected_separator
11301 \protected_separator
11303 \protected_separator
11305 \protected_separator
11307 \protected_separator
11309 \protected_separator
11311 \protected_separator
11312 Goto the SDCDB output buffer
11315 \protected_separator
11317 \protected_separator
11319 \protected_separator
11321 \protected_separator
11323 \protected_separator
11325 \protected_separator
11327 \protected_separator
11329 \protected_separator
11331 \protected_separator
11333 \protected_separator
11335 \protected_separator
11337 \protected_separator
11339 \protected_separator
11341 \protected_separator
11343 \protected_separator
11345 \protected_separator
11347 \protected_separator
11349 \protected_separator
11351 \protected_separator
11353 \protected_separator
11355 \protected_separator
11357 \protected_separator
11359 \protected_separator
11361 \protected_separator
11363 \protected_separator
11364 SDCDB print command for data at
11367 \protected_separator
11369 \protected_separator
11371 \protected_separator
11373 \protected_separator
11375 \protected_separator
11377 \protected_separator
11379 \protected_separator
11381 \protected_separator
11383 \protected_separator
11385 \protected_separator
11387 \protected_separator
11389 \protected_separator
11391 \protected_separator
11393 \protected_separator
11395 \protected_separator
11397 \protected_separator
11399 \protected_separator
11401 \protected_separator
11403 \protected_separator
11405 \protected_separator
11407 \protected_separator
11409 \protected_separator
11411 \protected_separator
11413 \protected_separator
11415 \protected_separator
11417 \protected_separator
11419 \protected_separator
11421 \protected_separator
11423 \protected_separator
11425 \protected_separator
11427 \protected_separator
11429 \protected_separator
11431 \protected_separator
11433 \protected_separator
11435 \protected_separator
11437 \protected_separator
11439 \protected_separator
11441 \protected_separator
11443 \protected_separator
11445 \protected_separator
11447 \protected_separator
11449 \protected_separator
11453 \protected_separator
11455 \protected_separator
11457 \protected_separator
11459 \protected_separator
11461 \protected_separator
11463 \protected_separator
11465 \protected_separator
11467 \protected_separator
11469 \protected_separator
11471 \protected_separator
11473 \protected_separator
11475 \protected_separator
11477 \protected_separator
11479 \protected_separator
11480 sdcdbsrc-goto-sdcdb
11481 \protected_separator
11483 \protected_separator
11485 \protected_separator
11487 \protected_separator
11489 \protected_separator
11491 \protected_separator
11493 \protected_separator
11495 \protected_separator
11497 \protected_separator
11499 \protected_separator
11500 Goto the SDCDB output buffer
11503 \protected_separator
11505 \protected_separator
11507 \protected_separator
11509 \protected_separator
11511 \protected_separator
11513 \protected_separator
11515 \protected_separator
11517 \protected_separator
11519 \protected_separator
11521 \protected_separator
11523 \protected_separator
11525 \protected_separator
11527 \protected_separator
11529 \protected_separator
11531 \protected_separator
11533 \protected_separator
11535 \protected_separator
11537 \protected_separator
11539 \protected_separator
11541 \protected_separator
11543 \protected_separator
11545 \protected_separator
11547 \protected_separator
11549 \protected_separator
11551 \protected_separator
11553 \protected_separator
11555 \protected_separator
11557 \protected_separator
11559 \protected_separator
11561 \protected_separator
11562 Toggles Sdcdbsrc mode (turns it off)
11567 \protected_separator
11569 \protected_separator
11571 \protected_separator
11573 \protected_separator
11575 \protected_separator
11577 \protected_separator
11579 \protected_separator
11581 \protected_separator
11582 sdcdb-finish-from-src
11583 \protected_separator
11585 \protected_separator
11587 \protected_separator
11589 \protected_separator
11591 \protected_separator
11593 \protected_separator
11595 \protected_separator
11597 \protected_separator
11598 SDCDB finish command
11603 \protected_separator
11605 \protected_separator
11607 \protected_separator
11609 \protected_separator
11611 \protected_separator
11613 \protected_separator
11615 \protected_separator
11617 \protected_separator
11619 \protected_separator
11621 \protected_separator
11623 \protected_separator
11625 \protected_separator
11627 \protected_separator
11629 \protected_separator
11631 \protected_separator
11633 \protected_separator
11635 \protected_separator
11637 \protected_separator
11639 \protected_separator
11641 \protected_separator
11643 \protected_separator
11645 \protected_separator
11647 \protected_separator
11649 \protected_separator
11651 \protected_separator
11653 \protected_separator
11654 Set break for line with point
11657 \protected_separator
11659 \protected_separator
11661 \protected_separator
11663 \protected_separator
11665 \protected_separator
11667 \protected_separator
11669 \protected_separator
11671 \protected_separator
11673 \protected_separator
11675 \protected_separator
11677 \protected_separator
11679 \protected_separator
11681 \protected_separator
11683 \protected_separator
11685 \protected_separator
11687 \protected_separator
11689 \protected_separator
11691 \protected_separator
11693 \protected_separator
11695 \protected_separator
11697 \protected_separator
11699 \protected_separator
11701 \protected_separator
11703 \protected_separator
11705 \protected_separator
11707 \protected_separator
11708 Toggle Sdcdbsrc mode
11711 \protected_separator
11713 \protected_separator
11715 \protected_separator
11717 \protected_separator
11719 \protected_separator
11721 \protected_separator
11723 \protected_separator
11725 \protected_separator
11727 \protected_separator
11729 \protected_separator
11731 \protected_separator
11733 \protected_separator
11735 \protected_separator
11737 \protected_separator
11739 \protected_separator
11741 \protected_separator
11743 \protected_separator
11745 \protected_separator
11747 \protected_separator
11749 \protected_separator
11751 \protected_separator
11753 \protected_separator
11762 \begin_inset LatexCommand \label{Conclusion}
11769 SDCC is a large project , the compiler alone (without the Assembler Package
11770 , Preprocessor & garbage collector) is about 40,000 lines of code (blank
11772 As with any project of this size there are bound to be bugs, I am more
11773 than willing to work to fix these bugs , of course all the source code
11774 is included with the package.
11778 Where does it go from here ? I am planning to target the Atmel AVR 8-bit
11779 MCUs which seems to have a lot of users.
11780 I am also planning to include an alias analysis system with this compiler
11781 (it does not currently have one).
11785 \begin_inset LatexCommand \label{Acknowledgements}
11792 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX & ASLINK.
11796 John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for 8051
11800 Obukhov (dso@usa.net) - malloc & serial i/o routines.
11804 Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware simulator
11807 Jans J Boehm(boehm@sgi.com) and Alan J Demers - Conservative garbage collector
11811 Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience and support.
11814 Unknown - for the GNU C - preprocessor.
11817 Appendix A: The Z80 and gbz80 port
11820 2.2.0 can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
11821 The port is incomplete - long support is incomplete (mul, div and mod are
11822 unimplimented), and both float and bitfield support is missing, but apart
11823 from that the code generated is correct.
11826 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
11827 The stack frame is similar to that generated by the IAR Z80 compiler.
11828 IX is used as the base pointer, HL is used as a temporary register, and
11829 BC and DE are available for holding varibles.
11830 IY is currently unusued.
11831 Return values are stored in HL.
11832 One bad side effect of using IX as the base pointer is that a functions
11833 stack frame is limited to 127 bytes - this will be fixed in a later version.bc
11840 \begin_inset LatexCommand \index{}
projects / fw / sdcc / blob