1 #LyX 1.5.7 created this file. For more info see http://www.lyx.org/
7 \pdfoptionpdfminorversion=3
9 pdftitle={SDCC Compiler User Guide},
10 pdfauthor={SDCC development team},
11 pdfsubject={installation, user manual},
12 pdfkeywords={68hc08 8032 8051 ansi c compiler assembler CPU DS390 embedded development free Floating Point Arithmetic Freescale GPL HC08 inline Intel ISO/IEC 9899:1990 Linux MAC OS X manual Maxim mcs51 Microchip microcontroller open source PIC Unix Windows Z80 Zilog},
13 pdfpagemode=UseOutlines,
15 linkcolor=blue] {hyperref}
19 \emergencystretch=30pt
24 \inputencoding default
27 \font_typewriter courier
28 \font_default_family default
34 \paperfontsize default
36 \papersize letterpaper
42 \paperorientation portrait
49 \paragraph_separation indent
51 \quotes_language swedish
55 \tracking_changes false
63 \begin_layout Standard
64 \begin_inset Note Note
67 \begin_layout Standard
68 Please note: double dashed longoptions (e.g.
69 --version) are written this way: -
73 \begin_layout Standard
85 \begin_layout Standard
87 three consecutive dashes would otherwise result in a long resp.
91 \begin_layout Standard
92 Architecture specific stuff (like memory models, code examples) should maybe
96 \begin_layout Standard
97 into separate sections/chapters/appendices (it is hard to document PIC or
101 \begin_layout Standard
102 a 8051 centered document) - for now simply add.
111 SDCC Compiler User Guide
126 \begin_layout Standard
127 \begin_inset Note Note
130 \begin_layout Standard
131 The above strings enclosed in $ are automatically updated by Subversion
139 \begin_layout Standard
140 \begin_inset LatexCommand tableofcontents
147 \begin_layout Chapter
151 \begin_layout Section
155 \begin_layout Standard
176 ompiler) is free open source, retargettable, optimizing ANSI-C compiler
181 designed for 8 bit Microprocessors.
182 The current version targets Intel MCS51 based Microprocessors (8031, 8032,
184 \begin_inset LatexCommand index
185 name "8031, 8032, 8051, 8052, mcs51 CPU"
189 , etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
190 Zilog Z80 based MCUs.
191 It can be retargeted for other microprocessors, support for Microchip PIC,
192 Atmel AVR is under development.
193 The entire source code for the compiler is distributed under GPL.
195 \begin_inset LatexCommand index
196 name "asXXXX (as-gbz80, as-hc08, asx8051, as-z80)"
201 \begin_inset LatexCommand index
206 , an open source retargetable assembler & linker.
207 SDCC has extensive language extensions suitable for utilizing various microcont
208 rollers and underlying hardware effectively.
213 In addition to the MCU specific optimizations SDCC also does a host of
214 standard optimizations like:
217 \begin_layout Itemize
218 global sub expression elimination,
221 \begin_layout Itemize
222 loop optimizations (loop invariant, strength reduction of induction variables
226 \begin_layout Itemize
227 constant folding & propagation,
230 \begin_layout Itemize
234 \begin_layout Itemize
235 dead code elimination
238 \begin_layout Itemize
246 \begin_layout Standard
247 For the back-end SDCC uses a global register allocation scheme which should
248 be well suited for other 8 bit MCUs.
253 The peep hole optimizer uses a rule based substitution mechanism which
259 Supported data-types are:
262 \begin_layout Standard
264 <lyxtabular version="3" rows="8" columns="5">
266 <column alignment="center" valignment="top" leftline="true" width="0">
267 <column alignment="center" valignment="top" leftline="true" width="0">
268 <column alignment="center" valignment="top" leftline="true" width="0">
269 <column alignment="center" valignment="top" leftline="true" width="0">
270 <column alignment="block" valignment="top" leftline="true" rightline="true" width="20text%">
271 <row topline="true" bottomline="true">
272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
275 \begin_layout Standard
281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
284 \begin_layout Standard
290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
293 \begin_layout Standard
299 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
302 \begin_layout Standard
308 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
311 \begin_layout Standard
319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
322 \begin_layout Standard
328 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
331 \begin_layout Standard
337 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
340 \begin_layout Standard
346 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
349 \begin_layout Standard
355 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
358 \begin_layout Standard
366 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
369 \begin_layout Standard
375 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
378 \begin_layout Standard
384 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
387 \begin_layout Standard
393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
396 \begin_layout Standard
402 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
405 \begin_layout Standard
413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
416 \begin_layout Standard
422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
425 \begin_layout Standard
431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
434 \begin_layout Standard
440 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
443 \begin_layout Standard
449 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
452 \begin_layout Standard
460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
463 \begin_layout Standard
469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
472 \begin_layout Standard
478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
481 \begin_layout Standard
487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
490 \begin_layout Standard
496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
499 \begin_layout Standard
506 <row topline="true" bottomline="true">
507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
510 \begin_layout Standard
516 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
519 \begin_layout Standard
525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
528 \begin_layout Standard
534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
537 \begin_layout Standard
538 -2.147.483.648, +2.147.483.647
543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
546 \begin_layout Standard
553 <row topline="true" bottomline="true">
554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
557 \begin_layout Standard
563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
566 \begin_layout Standard
572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
575 \begin_layout Standard
581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
584 \begin_layout Standard
590 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
593 \begin_layout Standard
609 <row topline="true" bottomline="true">
610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
613 \begin_layout Standard
619 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
622 \begin_layout Standard
628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
631 \begin_layout Standard
637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
640 \begin_layout Standard
646 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
649 \begin_layout Standard
662 The compiler also allows
664 inline assembler code
666 to be embedded anywhere in a function.
667 In addition, routines developed in assembly can also be called.
672 provides an option (-
676 \begin_layout Standard
685 -cyclomatic) to report the relative complexity of a function.
686 These functions can then be further optimized, or hand coded in assembly
692 SDCC also comes with a companion source level debugger SDCDB.
693 The debugger currently uses ucSim, a free open source simulator for 8051
694 and other micro-controllers.
698 The latest SDCC version can be downloaded from
700 \begin_inset LatexCommand url
701 target "http://sdcc.sourceforge.net/snap.php"
708 Please note: the compiler will probably always be some steps ahead of this
713 \begin_inset LatexCommand index
714 name "Status of documentation"
722 \begin_layout Standard
723 Obviously this has pros and cons
731 \begin_layout Section
735 \begin_layout Standard
736 All packages used in this compiler system are
744 ; source code for all the sub-packages (pre-processor, assemblers, linkers
745 etc.) is distributed with the package.
746 This documentation is maintained using a free open source word processor
749 This program is free software; you can redistribute it and/or modify
750 it under the terms of the GNU General Public License
751 \begin_inset LatexCommand index
752 name "GNU General Public License, GPL"
756 as published by the Free Software Foundation; either version 2, or (at
757 your option) any later version.
758 This program is distributed in the hope that it will be useful, but WITHOUT
759 ANY WARRANTY; without even the implied warranty
760 \begin_inset LatexCommand index
765 of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
766 See the GNU General Public License for more details.
767 You should have received a copy of the GNU General Public License along
768 with this program; if not, write to the Free Software Foundation, 59 Temple
769 Place - Suite 330, Boston, MA 02111-1307, USA.
770 In other words, you are welcome to use, share and improve this program.
771 You are forbidden to forbid anyone else to use, share and improve what
773 Help stamp out software-hoarding!
776 \begin_layout Section
777 Typographic conventions
778 \begin_inset LatexCommand index
779 name "Typographic conventions"
786 \begin_layout Standard
787 Throughout this manual, we will use the following convention.
788 Commands you have to type in are printed in
796 Code samples are printed in
801 Interesting items and new terms are printed in
806 \begin_layout Section
808 \begin_inset LatexCommand label
809 name "sec:Compatibility-with-previous"
813 with previous versions
814 \begin_inset LatexCommand index
815 name "Compatibility with previous versions"
822 \begin_layout Standard
823 Newer versions have usually numerous bug fixes compared with the previous
825 But we also sometimes introduce some incompatibilities with older versions.
826 Not just for the fun of it, but to make the compiler more stable, efficient
828 \begin_inset LatexCommand index
829 name "ANSI-compliance"
834 \begin_inset LatexCommand ref
835 reference "sub:ANSI-Compliance"
839 for ANSI-Compliance).
841 \begin_inset Note Note
844 \begin_layout Standard
845 It would be fine to add to each item, in which version was it changed.
855 \begin_layout Itemize
856 short is now equivalent to int (16 bits), it used to be equivalent to char
857 (8 bits) which is not ANSI compliant.
858 To maintain compatibility, old programs may be compiled using the -
862 \begin_layout Standard
871 -short-is-8bits commandline option (see
872 \begin_inset LatexCommand vref
873 reference "lyx:--short-is-8bits"
880 \begin_layout Itemize
881 the default directory for gcc-builds where include, library and documentation
882 files are stored is now in /usr/local/share.
885 \begin_layout Itemize
886 char type parameters to vararg
887 \begin_inset LatexCommand index
888 name "vararg, va\\_arg"
892 functions are casted to int unless explicitly casted and
898 \begin_layout Standard
908 \begin_inset LatexCommand index
921 \begin_layout Standard
931 \begin_inset LatexCommand index
938 command line option are not defined
939 \begin_inset Marginal
942 \begin_layout Standard
967 will push a as an int and as a char resp if
973 \begin_layout Standard
983 \begin_inset LatexCommand index
996 \begin_layout Standard
1006 \begin_inset LatexCommand index
1013 command line options are not defined,
1015 will push a as two ints if
1021 \begin_layout Standard
1031 \begin_inset LatexCommand index
1044 \begin_layout Standard
1054 \begin_inset LatexCommand index
1061 command line option is defined.
1064 \begin_layout Itemize
1069 \begin_layout Standard
1078 -regextend has been removed.
1081 \begin_layout Itemize
1086 \begin_layout Standard
1095 -noregparms has been removed.
1098 \begin_layout Itemize
1103 \begin_layout Standard
1112 -stack-after-data has been removed.
1115 \begin_layout Itemize
1117 \begin_inset LatexCommand index
1123 \begin_inset LatexCommand index
1129 \begin_inset LatexCommand index
1134 types now consistently behave like the C99 _Bool type with respect to type
1136 \begin_inset LatexCommand index
1137 name "type conversion"
1142 \begin_inset LatexCommand index
1143 name "type promotion"
1148 The most common incompatibility resulting from this change is related to
1150 \begin_inset LatexCommand index
1166 \begin_inset LatexCommand index
1167 name "\\~\\/ Operator"
1171 b; /* equivalent to b=1 instead of toggling b */
1172 \begin_inset Marginal
1175 \begin_layout Standard
1188 b = !b; /* toggles b */
1192 In previous versions, both forms would have toggled the bit.
1195 \begin_layout Itemize
1196 in older versions, the preprocessor was always called with
1202 \begin_layout Standard
1212 \begin_inset LatexCommand index
1225 \begin_layout Standard
1237 This is no longer true, and can cause compilation failures on code built
1244 \begin_layout Standard
1254 \begin_inset LatexCommand index
1261 but using c99 preprocessor features, such as one-line (//) comments
1264 \begin_layout Itemize
1265 in versions older then 2.8.4 the pic16 *printf() and printf_tiny() library
1266 functions supported undocumented and not standard compliant 'b' binary
1267 format specifier ("%b", "%hb" and "%lb").
1268 The 'b' specifier is now disabled by default.
1269 It can be enabled by defining BINARY_SPECIFIER macro in files device/lib/pic16/
1270 libc/stdio/vfprintf.c and device/lib/pic16/libc/stdio/printf_tiny.c and recompilin
1274 \begin_layout Itemize
1275 in versions older then 2.8.5 the unnamed bitfield structure members participated
1276 in initialization, which is not conforming with ISO/IEC 9899:1999 standard
1277 (see section Section 6.7.8 Initialization, clause 9)
1281 Old behavior, before
1317 /* s.a = 1, s.b = 3 */
1358 /* s.a = 1, s.b = 2 */
1361 \begin_layout Section
1365 \begin_layout Standard
1366 What do you need before you start installation of SDCC? A computer, and
1367 a desire to compute.
1368 The preferred method of installation is to compile SDCC from source using
1370 For Windows some pre-compiled binary distributions are available for your
1372 You should have some experience with command line tools and compiler use.
1375 \begin_layout Section
1379 \begin_layout Standard
1380 The SDCC home page at
1381 \begin_inset LatexCommand url
1382 target "http://sdcc.sourceforge.net/"
1386 is a great place to find distribution sets.
1387 You can also find links to the user mailing lists that offer help or discuss
1388 SDCC with other SDCC users.
1389 Web links to other SDCC related sites can also be found here.
1390 This document can be found in the DOC directory of the source package as
1391 a text or HTML file.
1392 A pdf version of this document is available at
1393 \begin_inset LatexCommand url
1394 target "http://sdcc.sourceforge.net/doc/sdccman.pdf"
1399 Some of the other tools (simulator and assembler) included with SDCC contain
1400 their own documentation and can be found in the source distribution.
1401 If you want the latest unreleased software, the complete source package
1402 is available directly from Subversion on https://sdcc.svn.sourceforge.net/svnroot/
1406 \begin_layout Section
1407 Wishes for the future
1410 \begin_layout Standard
1411 There are (and always will be) some things that could be done.
1412 Here are some I can think of:
1417 \begin_layout Standard
1420 char KernelFunction3(char p) at 0x340;
1425 \begin_layout Standard
1429 \begin_inset LatexCommand index
1430 name "code banking (limited support)"
1440 If you can think of some more, please see the section
1441 \begin_inset LatexCommand ref
1442 reference "sub:Requesting-Features"
1446 about filing feature requests
1447 \begin_inset LatexCommand index
1448 name "Requesting features"
1453 \begin_inset LatexCommand index
1454 name "Feature request"
1463 \begin_layout Chapter
1465 \begin_inset LatexCommand index
1473 \begin_layout Standard
1474 For most users it is sufficient to skip to either section
1475 \begin_inset LatexCommand ref
1476 reference "sub:Building-SDCC-on-Linux"
1481 \begin_inset LatexCommand ref
1482 reference "sub:Windows-Install"
1487 More detailed instructions follow below.
1490 \begin_layout Section
1492 \begin_inset LatexCommand index
1493 name "Options SDCC configuration"
1500 \begin_layout Standard
1501 The install paths, search paths and other options are defined when running
1503 The defaults can be overridden by:
1507 \labelwidthstring 00.00.0000
1512 \begin_layout Standard
1521 -prefix see table below
1525 \labelwidthstring 00.00.0000
1530 \begin_layout Standard
1539 -exec_prefix see table below
1543 \labelwidthstring 00.00.0000
1548 \begin_layout Standard
1557 -bindir see table below
1561 \labelwidthstring 00.00.0000
1566 \begin_layout Standard
1575 -datadir see table below
1579 \labelwidthstring 00.00.0000
1584 \begin_layout Standard
1593 -datarootdir see table below
1599 \labelwidthstring 00.00.0000
1602 docdir environment variable, see table below
1606 \labelwidthstring 00.00.0000
1609 include_dir_suffix environment variable, see table below
1613 \labelwidthstring 00.00.0000
1616 lib_dir_suffix environment variable, see table below
1620 \labelwidthstring 00.00.0000
1623 sdccconf_h_dir_separator environment variable, either / or
1628 This character will only be used in sdccconf.h; don't forget it's a C-header,
1629 therefore a double-backslash is needed there.
1635 \labelwidthstring 00.00.0000
1640 \begin_layout Standard
1649 -disable-mcs51-port Excludes the Intel mcs51 port
1653 \labelwidthstring 00.00.0000
1658 \begin_layout Standard
1667 -disable-gbz80-port Excludes the Gameboy gbz80 port
1671 \labelwidthstring 00.00.0000
1676 \begin_layout Standard
1685 -disable-z80-port Excludes the z80 port
1689 \labelwidthstring 00.00.0000
1694 \begin_layout Standard
1703 -disable-avr-port Excludes the AVR port
1707 \labelwidthstring 00.00.0000
1712 \begin_layout Standard
1721 -disable-ds390-port Excludes the DS390 port
1725 \labelwidthstring 00.00.0000
1730 \begin_layout Standard
1739 -disable-hc08-port Excludes the HC08 port
1743 \labelwidthstring 00.00.0000
1748 \begin_layout Standard
1757 -disable-pic-port Excludes the PIC14 port
1761 \labelwidthstring 00.00.0000
1766 \begin_layout Standard
1775 -disable-pic16-port Excludes the PIC16 port
1779 \labelwidthstring 00.00.0000
1784 \begin_layout Standard
1793 -disable-xa51-port Excludes the XA51 port
1797 \labelwidthstring 00.00.0000
1802 \begin_layout Standard
1811 -disable-ucsim Disables configuring and building of ucsim
1815 \labelwidthstring 00.00.0000
1820 \begin_layout Standard
1829 -disable-device-lib Disables automatically building device libraries
1833 \labelwidthstring 00.00.0000
1838 \begin_layout Standard
1847 -disable-packihx Disables building packihx
1853 \labelwidthstring 00.00.0000
1858 \begin_layout Standard
1867 -enable-doc Build pdf, html and txt files from the lyx sources
1871 \labelwidthstring 00.00.0000
1876 \begin_layout Standard
1885 -enable-libgc Use the Bohem memory allocator.
1886 Lower runtime footprint.
1890 \labelwidthstring 00.00.0000
1895 \begin_layout Standard
1904 -without-ccache Do not use ccache even if available
1907 \begin_layout Standard
1908 Furthermore the environment variables CC, CFLAGS, ...
1909 the tools and their arguments can be influenced.
1910 Please see `configure -
1914 \begin_layout Standard
1923 -help' and the man/info pages of `configure' for details.
1928 standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB, STD_FP_LIB, STD_DS390_LI
1929 B, STD_XA51_LIB and the environment variables SDCC_DIR_NAME, SDCC_INCLUDE_NAME,
1930 SDCC_LIB_NAME are defined by `configure' too.
1931 At the moment it's not possible to change the default settings (it was
1932 simply never required).
1936 These configure options are compiled into the binaries,
1937 and can only be changed by rerunning 'configure' and recompiling SDCC.
1938 The configure options are written in
1942 to distinguish them from run time environment variables (see section search
1948 \begin_inset Quotes sld
1952 \begin_inset Quotes srd
1955 are used by the SDCC team to build the official Win32 binaries.
1956 The SDCC team uses Mingw32 to build the official Windows binaries, because
1960 \begin_layout Enumerate
1964 \begin_layout Enumerate
1965 a gcc compiler and last but not least
1968 \begin_layout Enumerate
1969 the binaries can be built by cross compiling on SDCC Distributed Compile
1973 \begin_layout Standard
1974 See the examples, how to pass the Win32 settings to 'configure'.
1975 The other Win32 builds using Borland, VC or whatever don't use 'configure',
1976 but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
1986 \begin_layout Standard
1988 \begin_inset Tabular
1989 <lyxtabular version="3" rows="9" columns="3">
1991 <column alignment="block" valignment="top" leftline="true" width="0in">
1992 <column alignment="block" valignment="top" leftline="true" width="0in">
1993 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1994 <row topline="true" bottomline="true">
1995 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1998 \begin_layout Standard
2004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2007 \begin_layout Standard
2013 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2016 \begin_layout Standard
2023 <row topline="true">
2024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2027 \begin_layout Standard
2035 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2038 \begin_layout Standard
2044 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2047 \begin_layout Standard
2056 <row topline="true">
2057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2060 \begin_layout Standard
2068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2071 \begin_layout Standard
2079 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2082 \begin_layout Standard
2091 <row topline="true">
2092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2095 \begin_layout Standard
2103 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2106 \begin_layout Standard
2116 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2119 \begin_layout Standard
2132 <row topline="true">
2133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2136 \begin_layout Standard
2144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2147 \begin_layout Standard
2155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2158 \begin_layout Standard
2167 <row topline="true">
2168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2171 \begin_layout Standard
2179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2182 \begin_layout Standard
2192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2195 \begin_layout Standard
2204 <row topline="true">
2205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2208 \begin_layout Standard
2216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2219 \begin_layout Standard
2229 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2232 \begin_layout Standard
2245 <row topline="true">
2246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2249 \begin_layout Standard
2257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2260 \begin_layout Standard
2266 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2269 \begin_layout Standard
2276 <row topline="true" bottomline="true">
2277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2280 \begin_layout Standard
2288 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2291 \begin_layout Standard
2297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2300 \begin_layout Standard
2316 \begin_layout Standard
2318 'configure' also computes relative paths.
2319 This is needed for full relocatability of a binary package and to complete
2320 search paths (see section search paths below):
2325 \begin_layout Standard
2327 \begin_inset Tabular
2328 <lyxtabular version="3" rows="4" columns="3">
2330 <column alignment="block" valignment="top" leftline="true" width="0in">
2331 <column alignment="block" valignment="top" leftline="true" width="0in">
2332 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2333 <row topline="true" bottomline="true">
2334 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2337 \begin_layout Standard
2343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2346 \begin_layout Standard
2352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2355 \begin_layout Standard
2362 <row topline="true" bottomline="true">
2363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2366 \begin_layout Standard
2374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2377 \begin_layout Standard
2383 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2386 \begin_layout Standard
2393 <row bottomline="true">
2394 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2397 \begin_layout Standard
2405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2408 \begin_layout Standard
2414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2417 \begin_layout Standard
2424 <row bottomline="true">
2425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2428 \begin_layout Standard
2436 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2439 \begin_layout Standard
2445 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2448 \begin_layout Standard
2464 \begin_layout Standard
2469 \begin_layout LyX-Code
2476 \begin_layout Standard
2486 \begin_inset Quotes srd
2490 \begin_inset Quotes srd
2497 \begin_layout Standard
2507 \begin_inset Quotes srd
2511 \begin_inset Quotes srd
2520 \begin_layout Standard
2533 \begin_layout Standard
2545 \begin_layout Standard
2546 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
2550 \begin_layout LyX-Code
2556 \begin_inset Quotes srd
2559 i586-mingw32msvc-gcc
2560 \begin_inset Quotes srd
2564 \begin_inset Quotes srd
2567 i586-mingw32msvc-g++
2568 \begin_inset Quotes srd
2576 \begin_inset Quotes srd
2579 i586-mingw32msvc-ranlib
2580 \begin_inset Quotes srd
2588 \begin_inset Quotes srd
2591 i586-mingw32msvc-strip
2592 \begin_inset Quotes srd
2603 \begin_layout Standard
2613 \begin_inset Quotes srd
2617 \begin_inset Quotes srd
2628 \begin_layout Standard
2638 \begin_inset Quotes srd
2642 \begin_inset Quotes srd
2650 \begin_inset Quotes srd
2656 \begin_inset Quotes srd
2664 \begin_inset Quotes srd
2668 \begin_inset Quotes srd
2676 \begin_inset Quotes srd
2680 \begin_inset Quotes srd
2687 sdccconf_h_dir_separator=
2688 \begin_inset Quotes srd
2700 \begin_inset Quotes srd
2711 \begin_layout Standard
2728 \begin_layout Standard
2737 -host=i586-mingw32msvc
2745 \begin_layout Standard
2754 -build=unknown-unknown-linux-gnu
2757 \begin_layout Standard
2759 \begin_inset Quotes sld
2763 \begin_inset Quotes srd
2766 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
2770 \begin_layout LyX-Code
2779 \begin_layout Standard
2789 \begin_inset Quotes srd
2793 \begin_inset Quotes srd
2804 \begin_layout Standard
2814 \begin_inset Quotes srd
2818 \begin_inset Quotes srd
2826 \begin_inset Quotes srd
2832 \begin_inset Quotes srd
2840 \begin_inset Quotes srd
2844 \begin_inset Quotes srd
2852 \begin_inset Quotes srd
2856 \begin_inset Quotes srd
2863 sdccconf_h_dir_separator=
2864 \begin_inset Quotes srd
2876 \begin_inset Quotes srd
2884 \begin_inset Quotes srd
2888 \begin_inset Quotes srd
2896 \begin_inset Quotes srd
2900 \begin_inset Quotes srd
2906 \begin_layout Standard
2907 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
2912 \begin_layout Standard
2921 -C' turns on caching, which gives a little bit extra speed.
2922 However if options are changed, it can be necessary to delete the config.cache
2926 \begin_layout Section
2928 \begin_inset LatexCommand label
2929 name "sub:Install-paths"
2934 \begin_inset LatexCommand index
2935 name "Install paths"
2942 \begin_layout Standard
2943 \begin_inset VSpace medskip
2949 \begin_layout Standard
2951 \begin_inset Tabular
2952 <lyxtabular version="3" rows="5" columns="4">
2954 <column alignment="left" valignment="top" leftline="true" width="0">
2955 <column alignment="left" valignment="top" leftline="true" width="0">
2956 <column alignment="left" valignment="top" leftline="true" width="0">
2957 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
2958 <row topline="true" bottomline="true">
2959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2962 \begin_layout Standard
2970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2973 \begin_layout Standard
2981 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2984 \begin_layout Standard
2992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2995 \begin_layout Standard
3004 <row topline="true">
3005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3008 \begin_layout Standard
3014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3017 \begin_layout Standard
3025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3028 \begin_layout Standard
3034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3037 \begin_layout Standard
3048 <row topline="true">
3049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3052 \begin_layout Standard
3058 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3061 \begin_layout Standard
3064 $DATADIR/ $INCLUDE_DIR_SUFFIX
3069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3072 \begin_layout Standard
3073 /usr/local/share/sdcc/include
3078 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3081 \begin_layout Standard
3092 <row topline="true">
3093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3096 \begin_layout Standard
3102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3105 \begin_layout Standard
3108 $DATADIR/$LIB_DIR_SUFFIX
3113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3116 \begin_layout Standard
3117 /usr/local/share/sdcc/lib
3122 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3125 \begin_layout Standard
3136 <row topline="true" bottomline="true">
3137 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3140 \begin_layout Standard
3146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3149 \begin_layout Standard
3157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3160 \begin_layout Standard
3161 /usr/local/share/sdcc/doc
3166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3169 \begin_layout Standard
3190 *compiler, preprocessor, assembler, and linker
3196 is auto-appended by the compiler, e.g.
3197 small, large, z80, ds390 etc
3200 \begin_layout Standard
3202 The install paths can still be changed during `make install' with e.g.:
3205 \begin_layout LyX-Code
3206 make install prefix=$(HOME)/local/sdcc
3209 \begin_layout Standard
3210 Of course this doesn't change the search paths compiled into the binaries.
3215 r the install path can be changed by defining DESTDIR
3216 \begin_inset LatexCommand index
3224 \begin_layout LyX-Code
3225 make install DESTDIR=$(HOME)/sdcc.rpm/
3228 \begin_layout Standard
3229 Please note that DESTDIR must have a trailing slash!
3232 \begin_layout Section
3234 \begin_inset LatexCommand label
3235 name "sub:Search-Paths"
3240 \begin_inset LatexCommand index
3248 \begin_layout Standard
3249 Some search paths or parts of them are determined by configure variables
3254 , see section above).
3255 Further search paths are determined by environment variables during runtime.
3258 The paths searched when running the compiler are as follows (the first
3264 Binary files (preprocessor, assembler and linker)
3269 \begin_layout Standard
3271 \begin_inset Tabular
3272 <lyxtabular version="3" rows="4" columns="3">
3274 <column alignment="block" valignment="top" leftline="true" width="0in">
3275 <column alignment="block" valignment="top" leftline="true" width="0in">
3276 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
3277 <row topline="true" bottomline="true">
3278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3281 \begin_layout Standard
3287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3290 \begin_layout Standard
3296 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3299 \begin_layout Standard
3306 <row topline="true">
3307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3310 \begin_layout Standard
3318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3321 \begin_layout Standard
3327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3330 \begin_layout Standard
3339 <row topline="true">
3340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3343 \begin_layout Standard
3344 Path of argv[0] (if available)
3349 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3352 \begin_layout Standard
3358 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3361 \begin_layout Standard
3368 <row topline="true" bottomline="true">
3369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3372 \begin_layout Standard
3378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3381 \begin_layout Standard
3387 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3390 \begin_layout Standard
3406 \begin_layout Standard
3414 \begin_layout Standard
3416 \begin_inset Tabular
3417 <lyxtabular version="3" rows="6" columns="3">
3419 <column alignment="block" valignment="top" leftline="true" width="1.5in">
3420 <column alignment="block" valignment="top" leftline="true" width="1.5in">
3421 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
3422 <row topline="true" bottomline="true">
3423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3426 \begin_layout Standard
3432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3435 \begin_layout Standard
3441 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3444 \begin_layout Standard
3451 <row topline="true">
3452 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3455 \begin_layout Standard
3460 \begin_layout Standard
3474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3477 \begin_layout Standard
3482 \begin_layout Standard
3496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3499 \begin_layout Standard
3504 \begin_layout Standard
3519 <row topline="true">
3520 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3523 \begin_layout Standard
3529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3532 \begin_layout Standard
3538 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3541 \begin_layout Standard
3548 <row topline="true">
3549 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3552 \begin_layout Standard
3564 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3567 \begin_layout Standard
3577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3580 \begin_layout Standard
3589 <row topline="true">
3590 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3593 \begin_layout Standard
3609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3612 \begin_layout Standard
3660 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3663 \begin_layout Standard
3674 <row topline="true" bottomline="true">
3675 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3678 \begin_layout Standard
3692 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3695 \begin_layout Standard
3696 /usr/local/share/sdcc/
3703 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3706 \begin_layout Standard
3722 \begin_layout Standard
3728 \begin_layout Standard
3737 -nostdinc disables the last two search paths.
3747 \begin_layout Standard
3748 With the exception of
3749 \begin_inset Quotes sld
3756 \begin_layout Standard
3766 \begin_inset Quotes srd
3773 is auto-appended by the compiler (e.g.
3774 small, large, z80, ds390 etc.).
3780 \begin_layout Standard
3782 \begin_inset Tabular
3783 <lyxtabular version="3" rows="6" columns="3">
3785 <column alignment="block" valignment="top" leftline="true" width="1.7in">
3786 <column alignment="block" valignment="top" leftline="true" width="1.2in">
3787 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
3788 <row topline="true" bottomline="true">
3789 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3792 \begin_layout Standard
3798 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3801 \begin_layout Standard
3807 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3810 \begin_layout Standard
3817 <row topline="true">
3818 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3821 \begin_layout Standard
3826 \begin_layout Standard
3840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3843 \begin_layout Standard
3848 \begin_layout Standard
3862 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3865 \begin_layout Standard
3870 \begin_layout Standard
3885 <row topline="true">
3886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3889 \begin_layout Standard
3899 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3902 \begin_layout Standard
3912 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3915 \begin_layout Standard
3928 <row topline="true">
3929 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3932 \begin_layout Standard
3939 $LIB_DIR_SUFFIX/<model>
3944 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3947 \begin_layout Standard
3959 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3962 \begin_layout Standard
3977 <row topline="true">
3978 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3981 \begin_layout Standard
3992 $LIB_DIR_SUFFIX/<model>
3997 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4000 \begin_layout Standard
4051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4054 \begin_layout Standard
4108 <row topline="true" bottomline="true">
4109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4112 \begin_layout Standard
4117 $LIB_DIR_SUFFIX/<model>
4122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4125 \begin_layout Standard
4126 /usr/local/share/sdcc/
4135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4138 \begin_layout Standard
4154 \begin_layout Standard
4155 \begin_inset Note Note
4158 \begin_layout Standard
4159 Don't delete any of the stray spaces in the table above without checking
4160 the HTML output (last line)!
4168 \begin_layout Standard
4176 \begin_layout Standard
4185 -nostdlib disables the last two search paths.
4188 \begin_layout Section
4190 \begin_inset LatexCommand index
4191 name "Building SDCC"
4198 \begin_layout Subsection
4199 Building SDCC on Linux
4200 \begin_inset LatexCommand label
4201 name "sub:Building-SDCC-on-Linux"
4208 \begin_layout Enumerate
4211 Download the source package
4213 either from the SDCC Subversion repository or from snapshot builds
4215 , it will be named something like sdcc
4226 \begin_inset LatexCommand url
4227 target "http://sdcc.sourceforge.net/snap.php"
4234 \begin_layout Enumerate
4237 Bring up a command line terminal, such as xterm.
4240 \begin_layout Enumerate
4243 Unpack the file using a command like:
4248 "tar -xvzf sdcc-src-yyyymmdd-rrrr.tar.bz2
4249 \begin_inset Quotes srd
4255 , this will create a sub-directory called sdcc with all of the sources.
4258 \begin_layout Enumerate
4259 Change directory into the main SDCC directory, for example type:
4267 \begin_layout Enumerate
4279 This configures the package for compilation on your system.
4282 \begin_layout Enumerate
4298 All of the source packages will compile, this can take a while.
4301 \begin_layout Enumerate
4317 This copies the binary executables, the include files, the libraries and
4318 the documentation to the install directories.
4319 Proceed with section
4320 \begin_inset LatexCommand ref
4321 reference "sec:Testing-the-SDCC"
4328 \begin_layout Subsection
4329 Building SDCC on Mac OS X
4332 \begin_layout Standard
4333 Follow the instruction for Linux.
4337 On Mac OS X 10.2.x it was reported, that the
4338 default gcc (version 3.1 20020420 (prerelease)) fails to compile SDCC.
4339 Fortunately there's also gcc 2.9.x installed, which works fine.
4340 This compiler can be selected by running 'configure' with:
4343 \begin_layout LyX-Code
4344 ./configure CC=gcc2 CXX=g++2
4347 \begin_layout Standard
4348 Universal (ppc and i386) binaries can be produced on Mac OS X 10.4.x with
4350 Run 'configure' with:
4353 \begin_layout LyX-Code
4359 \begin_layout LyX-Code
4360 LDFLAGS="-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch
4366 \begin_layout LyX-Code
4367 CXXFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch
4373 \begin_layout LyX-Code
4374 CFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc"
4377 \begin_layout Subsection
4378 Cross compiling SDCC on Linux for Windows
4381 \begin_layout Standard
4382 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
4383 See section 'Configure Options'.
4386 \begin_layout Subsection
4387 Building SDCC using Cygwin and Mingw32
4390 \begin_layout Standard
4391 For building and installing a Cygwin executable follow the instructions
4397 \begin_inset Quotes sld
4401 \begin_inset Quotes srd
4404 Win32-binary can be built, which will not need the Cygwin-DLL.
4405 For the necessary 'configure' options see section 'configure options' or
4406 the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
4411 Cygwin on Windows download setup.exe from
4412 \begin_inset LatexCommand url
4413 name "www.cygwin.com"
4414 target "http://www.cygwin.com/"
4420 \begin_inset Quotes sld
4423 default text file type
4424 \begin_inset Quotes srd
4428 \begin_inset Quotes sld
4432 \begin_inset Quotes srd
4435 and download/install at least the following packages.
4436 Some packages are selected by default, others will be automatically selected
4437 because of dependencies with the manually selected packages.
4438 Never deselect these packages!
4441 \begin_layout Itemize
4445 \begin_layout Itemize
4449 \begin_layout Itemize
4450 gcc ; version 3.x is fine, no need to use the old 2.9x
4453 \begin_layout Itemize
4454 binutils ; selected with gcc
4457 \begin_layout Itemize
4461 \begin_layout Itemize
4462 rxvt ; a nice console, which makes life much easier under windoze (see below)
4465 \begin_layout Itemize
4466 man ; not really needed for building SDCC, but you'll miss it sooner or
4470 \begin_layout Itemize
4471 less ; not really needed for building SDCC, but you'll miss it sooner or
4475 \begin_layout Itemize
4476 svn ; only if you use Subversion access
4479 \begin_layout Standard
4480 If you want to develop something you'll need:
4483 \begin_layout Itemize
4484 python ; for the regression tests
4487 \begin_layout Itemize
4488 gdb ; the gnu debugger, together with the nice GUI
4489 \begin_inset Quotes sld
4493 \begin_inset Quotes srd
4499 \begin_layout Itemize
4500 openssh ; to access the CF or commit changes
4503 \begin_layout Itemize
4504 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
4505 use autoconf-stable!
4508 \begin_layout Standard
4509 rxvt is a nice console with history.
4510 Replace in your cygwin.bat the line
4513 \begin_layout LyX-Code
4518 \begin_layout Standard
4530 \begin_layout Standard
4534 \begin_layout LyX-Code
4535 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
4538 \begin_layout LyX-Code
4539 -bg black -fg white -geometry 100x65 -e bash -
4543 \begin_layout Standard
4555 \begin_layout Standard
4556 Text selected with the mouse is automatically copied to the clipboard, pasting
4557 works with shift-insert.
4561 The other good tip is to make sure you have no //c/-styl
4562 e paths anywhere, use /cygdrive/c/ instead.
4563 Using // invokes a network lookup which is very slow.
4565 \begin_inset Quotes sld
4569 \begin_inset Quotes srd
4572 is too long, you can change it with e.g.
4575 \begin_layout LyX-Code
4579 \begin_layout Standard
4580 SDCC sources use the unix line ending LF.
4581 Life is much easier, if you store the source tree on a drive which is mounted
4583 And use an editor which can handle LF-only line endings.
4584 Make sure not to commit files with windows line endings.
4585 The tabulator spacing
4586 \begin_inset LatexCommand index
4587 name "tabulator spacing (8 columns)"
4591 used in the project is 8.
4592 Although a tabulator spacing of 8 is a sensible choice for programmers
4593 (it's a power of 2 and allows to display 8/16 bit signed variables without
4594 loosing columns) the plan is to move towards using only spaces in the source.
4597 \begin_layout Subsection
4598 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
4601 \begin_layout Standard
4604 Download the source package
4606 either from the SDCC Subversion repository or from the
4607 \begin_inset LatexCommand url
4608 name "snapshot builds"
4609 target "http://sdcc.sourceforge.net/snap.php"
4615 , it will be named something like sdcc
4619 -yyyymmdd-rrrr.tar.bz2.
4622 SDCC is distributed with all the projects, workspaces, and files you need
4623 to build it using Visual C++ 6.0/NET (except for SDCDB and ucSim).
4624 The workspace name is 'sdcc.dsw'.
4625 Please note that as it is now, all the executables are created in a folder
4629 Once built you need to copy the executables from sdcc
4633 bin before running SDCC.
4638 WARNING: Visual studio is very picky with line terminations; it expects
4639 the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
4640 When using the Subversion repository it's easiest to configure the svn
4641 client to convert automatically for you.
4642 If however you are getting a message such as "This makefile was not generated
4643 by Developer Studio etc.
4645 \begin_inset Quotes srd
4648 when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
4649 need to convert the Unix style line endings to DOS style line endings.
4650 To do so you can use the
4651 \begin_inset Quotes sld
4655 \begin_inset Quotes srd
4658 utility freely available on the internet.
4659 Doug Hawkins reported in the sdcc-user list that this works:
4667 SDCC> unix2dos sdcc.dsw
4673 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
4677 In order to build SDCC with MSVC
4678 you need win32 executables of bison.exe, flex.exe, and gawk.exe.
4679 One good place to get them is
4680 \begin_inset LatexCommand url
4682 target "http://unxutils.sourceforge.net"
4690 Download the file UnxUtils
4691 \begin_inset LatexCommand index
4697 Now you have to install the utilities and setup MSVC so it can locate the
4699 Here there are two alternatives (choose one!):
4702 \begin_layout Enumerate
4707 a) Extract UnxUtils.zip to your C:
4709 hard disk PRESERVING the original paths, otherwise bison won't work.
4710 (If you are using WinZip make certain that 'Use folder names' is selected)
4715 In the Visual C++ IDE click Tools, Options, select the Directory tab, in
4716 'Show directories for:' select 'Executable files', and in the directories
4717 window add a new path: 'C:
4727 (As a side effect, you get a bunch of Unix utilities that
4728 could be useful, such as diff and patch.)
4731 \begin_layout Enumerate
4736 This one avoids extracting a bunch of files you may not
4737 use, but requires some extra work:
4741 a) Create a directory were to put the
4742 tools needed, or use a directory already present.
4749 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and
4750 gawk.exe to such directory WITHOUT preserving the original paths.
4751 (If you are using WinZip make certain that 'Use folder names' is not selected)
4756 ) Rename bison.exe to '_bison.exe'.
4760 d) Create a batch file 'bison.bat' in 'C:
4764 ' and add these lines:
4784 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
4788 Steps 'c' and 'd' are needed
4789 because bison requires by default that the files 'bison.simple' and 'bison.hairy'
4790 reside in some weird Unix directory, '/usr/local/share/' I think.
4791 So it is necessary to tell bison where those files are located if they
4792 are not in such directory.
4793 That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
4798 ) In the Visual C++ IDE click Tools, Options, select the Directory tab,
4799 in 'Show directories for:' select 'Executable files', and in the directories
4800 window add a new path: 'c:
4803 Note that you can use any other path instead of 'c:
4805 util', even the path where the Visual C++ tools are, probably: 'C:
4809 Microsoft Visual Studio
4814 So you don't have to execute step 'e' :)
4817 \begin_layout Standard
4819 Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
4820 the executables from sdcc
4824 bin, and you can compile using SDCC.
4827 \begin_layout Subsection
4828 Building SDCC Using Borland
4831 \begin_layout Enumerate
4832 From the sdcc directory, run the command "make -f Makefile.bcc".
4833 This should regenerate all the .exe files in the bin directory except for
4837 \begin_layout Enumerate
4838 If you modify any source files and need to rebuild, be aware that the dependenci
4839 es may not be correctly calculated.
4840 The safest option is to delete all .obj files and run the build again.
4841 From a Cygwin BASH prompt, this can easily be done with the command (be
4842 sure you are in the sdcc directory):
4852 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
4854 ) -print -exec rm {}
4863 or on Windows NT/2000/XP from the command prompt with the command:
4870 del /s *.obj *.lib *.rul
4873 from the sdcc directory.
4876 \begin_layout Subsection
4877 Windows Install Using a ZIP Package
4880 \begin_layout Enumerate
4881 Download the binary zip package from
4882 \begin_inset LatexCommand url
4883 target "http://sdcc.sf.net/snap.php"
4887 and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
4888 This should unpack to a group of sub-directories.
4889 An example directory structure after unpacking the mingw32 package is:
4894 bin for the executables, c:
4902 lib for the include and libraries.
4905 \begin_layout Enumerate
4906 Adjust your environment variable PATH to include the location of the bin
4907 directory or start sdcc using the full path.
4910 \begin_layout Subsection
4911 Windows Install Using the Setup Program
4912 \begin_inset LatexCommand label
4913 name "sub:Windows-Install"
4920 \begin_layout Standard
4921 Download the setup program
4923 sdcc-x.y.z-setup.exe
4925 for an official release from
4928 \begin_inset LatexCommand url
4929 target "http://sf.net/project/showfiles.php?group_id=599"
4933 or a setup program for one of the snapshots
4935 sdcc-yyyymmdd-xxxx-setup.exe
4938 \begin_inset LatexCommand url
4939 target "http://sdcc.sf.net/snap.php"
4944 A windows typical installer will guide you through the installation process.
4947 \begin_layout Subsection
4949 \begin_inset LatexCommand index
4957 \begin_layout Standard
4958 SDCC supports the VPATH feature provided by configure and make.
4959 It allows to separate the source and build trees.
4963 \begin_layout Standard
4990 \begin_layout Standard
4993 tar -xzf sdcc.src.tar.gz\InsetSpace ~
4994 # extract source to directory sdcc
4997 \begin_layout Standard
5000 mkdir sdcc.build\InsetSpace ~
5009 # put output in sdcc.build
5012 \begin_layout Standard
5018 \begin_layout Standard
5021 ../sdcc/configure\InsetSpace ~
5029 # configure is doing all the magic!
5032 \begin_layout Standard
5038 \begin_layout Standard
5044 will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
5045 It automagically computes the variables srcdir, top_srcdir and top_buildir
5051 the generated files will be in ~/sdcc.build, while the source files stay
5054 This is not only usefull for building different binaries, e.g.
5055 when cross compiling.
5056 It also gives you a much better overview in the source tree when all the
5057 generated files are not scattered between the source files.
5058 And the best thing is: if you want to change a file you can leave the original
5059 file untouched in the source directory.
5060 Simply copy it to the build directory, edit it, enter `make clean', `rm
5061 Makefile.dep' and `make'.
5066 will do the rest for you!
5069 \begin_layout Section
5070 Building the Documentation
5073 \begin_layout Standard
5078 \begin_layout Standard
5087 -enable-doc to the configure arguments to build the documentation together
5088 with all the other stuff.
5089 You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
5090 dvips and makeindex) to get the job done.
5091 Another possibility is to change to the doc directory and to type
5095 \begin_inset Quotes srd
5099 \begin_inset Quotes srd
5106 You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
5109 \begin_inset LatexCommand url
5110 target "http://www.lyx.org"
5114 as editor is straightforward.
5115 Prebuilt documentation in html and pdf format is available from
5116 \begin_inset LatexCommand url
5117 target "http://sdcc.sf.net/snap.php"
5124 \begin_layout Section
5125 Reading the Documentation
5126 \begin_inset LatexCommand index
5127 name "Documentation"
5134 \begin_layout Standard
5135 Currently reading the document in pdf format is recommended, as for unknown
5136 reason the hyperlinks are working there whereas in the html version they
5141 \begin_layout Standard
5142 If you should know why please drop us a note
5150 You'll find the pdf version
5151 \begin_inset LatexCommand index
5152 name "PDF version of this document"
5157 \begin_inset LatexCommand url
5158 target "http://sdcc.sf.net/doc/sdccman.pdf"
5166 \begin_inset LatexCommand index
5167 name "HTML version of this document"
5172 \begin_inset LatexCommand url
5173 target "http://sdcc.sf.net/doc/sdccman.html/index.html"
5179 This documentation is in some aspects different from a commercial documentation:
5183 \begin_layout Itemize
5184 It tries to document SDCC for several processor architectures in one document
5185 (commercially these probably would be separate documents/products).
5187 \begin_inset LatexCommand index
5188 name "Status of documentation"
5192 currently matches SDCC for mcs51 and DS390 best and does give too few informati
5194 Z80, PIC14, PIC16 and HC08.
5197 \begin_layout Itemize
5198 There are many references pointing away from this documentation.
5199 Don't let this distract you.
5201 was a reference like
5202 \begin_inset LatexCommand url
5203 target "http://www.opencores.org"
5207 together with a statement
5208 \begin_inset Quotes sld
5211 some processors which are targetted by SDCC can be implemented in a
5228 \begin_inset LatexCommand index
5229 name "FPGA (field programmable gate array)"
5234 \begin_inset Quotes srd
5238 \begin_inset LatexCommand url
5239 target "http://sf.net/projects/fpgac"
5244 \begin_inset LatexCommand index
5245 name "FpgaC ((subset of) C to FPGA compiler)"
5250 \begin_inset Quotes sld
5253 have you ever heard of an open source compiler that compiles a subset of
5255 \begin_inset Quotes srd
5258 we expect you to have a quick look there and come back.
5259 If you read this you are on the right track.
5262 \begin_layout Itemize
5263 Some sections attribute more space to problems, restrictions and warnings
5264 than to the solution.
5267 \begin_layout Itemize
5268 The installation section and the section about the debugger is intimidating.
5271 \begin_layout Itemize
5272 There are still lots of typos and there are more different writing styles
5276 \begin_layout Section
5277 Testing the SDCC Compiler
5278 \begin_inset LatexCommand label
5279 name "sec:Testing-the-SDCC"
5286 \begin_layout Standard
5287 The first thing you should do after installing your SDCC compiler is to
5296 \begin_layout Standard
5306 \begin_inset LatexCommand index
5314 at the prompt, and the program should run and output its version like:
5319 SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
5323 \begin_layout Standard
5324 If it doesn't run, or gives a message about not finding sdcc program, then
5325 you need to check over your installation.
5326 Make sure that the sdcc bin directory is in your executable search path
5327 defined by the PATH environment setting (
5332 \begin_inset LatexCommand ref
5333 reference "sub:Install-Trouble-shooting"
5340 Install trouble-shooting for suggestions
5343 Make sure that the sdcc program is in the bin folder, if not perhaps something
5344 did not install correctly.
5352 is commonly installed as described in section
5353 \begin_inset Quotes sld
5356 Install and search paths
5357 \begin_inset Quotes srd
5366 Make sure the compiler works on a very simple example.
5367 Type in the following test.c program using your favorite
5392 \begin_layout Standard
5395 Compile this using the following command:
5406 If all goes well, the compiler will generate a test.asm and test.rel file.
5407 Congratulations, you've just compiled your first program with SDCC.
5408 We used the -c option to tell SDCC not to link the generated code, just
5409 to keep things simple for this step.
5417 The next step is to try it with the linker.
5429 If all goes well the compiler will link with the libraries and produce
5430 a test.ihx output file.
5435 (no test.ihx, and the linker generates warnings), then the problem is most
5444 usr/local/share/sdcc/lib directory
5451 \begin_inset LatexCommand ref
5452 reference "sub:Install-Trouble-shooting"
5459 Install trouble-shooting for suggestions).
5467 The final test is to ensure
5475 header files and libraries.
5476 Edit test.c and change it to the following:
5494 strcpy(str1, "testing");
5499 \begin_layout Standard
5502 Compile this by typing
5511 This should generate a test.ihx output file, and it should give no warnings
5512 such as not finding the string.h file.
5513 If it cannot find the string.h file, then the problem is that
5517 cannot find the /usr/local/share/sdcc/include directory
5524 \begin_inset LatexCommand ref
5525 reference "sub:Install-Trouble-shooting"
5532 Install trouble-shooting section for suggestions).
5541 \begin_layout Standard
5553 \begin_inset LatexCommand index
5554 name "-\\/-print-search-dirs"
5558 to find exactly where SDCC is looking for the include and lib files.
5561 \begin_layout Section
5562 Install Trouble-shooting
5563 \begin_inset LatexCommand label
5564 name "sub:Install-Trouble-shooting"
5569 \begin_inset LatexCommand index
5570 name "Install trouble-shooting"
5577 \begin_layout Subsection
5578 If SDCC does not build correctly
5581 \begin_layout Standard
5582 A thing to try is starting from scratch by unpacking the .tgz source package
5583 again in an empty directory.
5591 ./configure 2>&1 | tee configure.log
5605 make 2>&1 | tee make.log
5612 If anything goes wrong, you can review the log files to locate the problem.
5613 Or a relevant part of this can be attached to an email that could be helpful
5614 when requesting help from the mailing list.
5617 \begin_layout Subsection
5619 \begin_inset Quotes sld
5623 \begin_inset Quotes srd
5629 \begin_layout Standard
5631 \begin_inset Quotes sld
5635 \begin_inset Quotes srd
5638 command is a script that analyzes your system and performs some configuration
5639 to ensure the source package compiles on your system.
5640 It will take a few minutes to run, and will compile a few tests to determine
5641 what compiler features are installed.
5644 \begin_layout Subsection
5646 \begin_inset Quotes sld
5650 \begin_inset Quotes srd
5656 \begin_layout Standard
5657 This runs the GNU make tool, which automatically compiles all the source
5658 packages into the final installed binary executables.
5661 \begin_layout Subsection
5663 \begin_inset Quotes sld
5667 \begin_inset Quotes erd
5673 \begin_layout Standard
5674 This will install the compiler, other executables libraries and include
5675 files into the appropriate directories.
5677 \begin_inset LatexCommand ref
5678 reference "sub:Install-paths"
5684 \begin_inset LatexCommand ref
5685 reference "sub:Search-Paths"
5690 about install and search paths.
5692 On most systems you will need super-user privilege
5696 \begin_layout Section
5700 \begin_layout Standard
5701 SDCC is not just a compiler, but a collection of tools by various developers.
5702 These include linkers, assemblers, simulators and other components.
5703 Here is a summary of some of the components.
5704 Note that the included simulator and assembler have separate documentation
5705 which you can find in the source package in their respective directories.
5706 As SDCC grows to include support for other processors, other packages from
5707 various developers are included and may have their own sets of documentation.
5712 might want to look at the files which are installed in <installdir>.
5713 At the time of this writing, we find the following programs for gcc-builds:
5718 In <installdir>/bin:
5721 \begin_layout Itemize
5722 sdcc - The compiler.
5725 \begin_layout Itemize
5726 sdcpp - The C preprocessor.
5729 \begin_layout Itemize
5730 asx8051 - The assembler for 8051 type processors.
5733 \begin_layout Itemize
5738 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
5741 \begin_layout Itemize
5742 aslink -The linker for 8051 type processors.
5745 \begin_layout Itemize
5750 link-gbz80 - The Z80 and GameBoy Z80 linkers.
5753 \begin_layout Itemize
5754 s51 - The ucSim 8051 simulator.
5757 \begin_layout Itemize
5758 sdcdb - The source debugger.
5761 \begin_layout Itemize
5762 packihx - A tool to pack (compress) Intel hex files.
5765 \begin_layout Standard
5766 In <installdir>/share/sdcc/include
5769 \begin_layout Itemize
5773 \begin_layout Standard
5774 In <installdir>/share/sdcc/lib
5777 \begin_layout Itemize
5778 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
5782 \begin_layout Standard
5783 In <installdir>/share/sdcc/doc
5786 \begin_layout Itemize
5790 \begin_layout Standard
5791 As development for other processors proceeds, this list will expand to include
5792 executables to support processors like AVR, PIC, etc.
5795 \begin_layout Subsection
5799 \begin_layout Standard
5800 This is the actual compiler, it in turn uses the c-preprocessor and invokes
5801 the assembler and linkage editor.
5804 \begin_layout Subsection
5805 sdcpp - The C-Preprocessor
5808 \begin_layout Standard
5810 \begin_inset LatexCommand index
5811 name "sdcpp (preprocessor)"
5815 is a modified version of the GNU cpp
5816 \begin_inset LatexCommand index
5817 name "cpp|see{sdcpp}"
5822 \begin_inset LatexCommand url
5823 target "http://gcc.gnu.org/"
5828 The C preprocessor is used to pull in #include sources, process #ifdef
5829 statements, #defines and so on.
5832 \begin_layout Subsection
5841 - The Assemblers and Linkage Editors
5844 \begin_layout Standard
5845 This is retargettable assembler & linkage editor, it was developed by Alan
5847 John Hartman created the version for 8051, and I (Sandeep) have made some
5848 enhancements and bug fixes for it to work properly with SDCC.
5851 \begin_layout Subsection
5855 \begin_layout Standard
5857 \begin_inset LatexCommand index
5862 is a free open source simulator developed by Daniel Drotos.
5863 The simulator is built as part of the build process.
5864 For more information visit Daniel's web site at:
5865 \begin_inset LatexCommand url
5866 target "http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51"
5871 It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
5875 \begin_layout Subsection
5876 sdcdb - Source Level Debugger
5879 \begin_layout Standard
5881 \begin_inset LatexCommand index
5882 name "SDCDB (debugger)"
5886 is the companion source level debugger.
5887 More about SDCDB in section
5888 \begin_inset LatexCommand ref
5889 reference "cha:Debugging-with-SDCDB"
5894 The current version of the debugger uses Daniel's Simulator S51
5895 \begin_inset LatexCommand index
5900 , but can be easily changed to use other simulators.
5903 \begin_layout Chapter
5907 \begin_layout Section
5911 \begin_layout Subsection
5912 Single Source File Projects
5915 \begin_layout Standard
5916 For single source file 8051 projects the process is very simple.
5917 Compile your programs with the following command
5920 "sdcc sourcefile.c".
5924 This will compile, assemble and link your source file.
5925 Output files are as follows:
5928 \begin_layout Itemize
5930 \begin_inset LatexCommand index
5936 \begin_inset LatexCommand index
5937 name "Assembler source"
5941 file created by the compiler
5944 \begin_layout Itemize
5946 \begin_inset LatexCommand index
5952 \begin_inset LatexCommand index
5953 name "Assembler listing"
5957 file created by the Assembler
5960 \begin_layout Itemize
5962 \begin_inset LatexCommand index
5968 \begin_inset LatexCommand index
5969 name "Assembler listing"
5973 file updated with linkedit information, created by linkage editor
5976 \begin_layout Itemize
5978 \begin_inset LatexCommand index
5984 \begin_inset LatexCommand index
5985 name "Symbol listing"
5989 for the sourcefile, created by the assembler
5992 \begin_layout Itemize
5994 \begin_inset LatexCommand index
6000 \begin_inset LatexCommand index
6006 \begin_inset LatexCommand index
6011 created by the assembler, input to Linkage editor
6014 \begin_layout Itemize
6016 \begin_inset LatexCommand index
6022 \begin_inset LatexCommand index
6027 for the load module, created by the Linker
6030 \begin_layout Itemize
6032 \begin_inset LatexCommand index
6037 - A file with a summary of the memory usage
6040 \begin_layout Itemize
6042 \begin_inset LatexCommand index
6047 - The load module in Intel hex format
6048 \begin_inset LatexCommand index
6049 name "Intel hex format"
6053 (you can select the Motorola S19 format
6054 \begin_inset LatexCommand index
6055 name "Motorola S19 format"
6063 \begin_layout Standard
6073 \begin_inset LatexCommand index
6074 name "-\\/-out-fmt-s19"
6079 If you need another format you might want to use
6086 \begin_inset LatexCommand index
6087 name "objdump (tool)"
6098 \begin_inset LatexCommand index
6099 name "srecord (bin, hex, ... tool)"
6104 \begin_inset Note Note
6107 \begin_layout Standard
6114 \begin_inset LatexCommand vref
6115 reference "sub:Postprocessing-the-Intel"
6120 Both formats are documented in the documentation of srecord
6121 \begin_inset LatexCommand index
6122 name "srecord (bin, hex, ... tool)"
6129 \begin_layout Itemize
6131 \begin_inset LatexCommand index
6136 - An intermediate file containing debug information needed to create the
6141 \begin_layout Standard
6151 \begin_inset LatexCommand index
6159 \begin_layout Itemize
6161 \begin_inset LatexCommand index
6166 - An optional file (with -
6170 \begin_layout Standard
6179 -debug) containing debug information.
6180 The format is documented in cdbfileformat.pdf
6183 \begin_layout Itemize
6186 \begin_inset LatexCommand index
6187 name "<file> (no extension)"
6191 An optional AOMF or AOMF51
6192 \begin_inset LatexCommand index
6198 \begin_inset LatexCommand label
6203 file containing debug information (generated with option -
6207 \begin_layout Standard
6233 ormat is a subformat of the OMF51 format and is commonly used by third party
6235 \begin_inset LatexCommand index
6240 , simulators, emulators).
6243 \begin_layout Itemize
6245 \begin_inset LatexCommand index
6250 - Dump file to debug the compiler it self (generated with option -
6254 \begin_layout Standard
6263 -dumpall) (see section
6264 \begin_inset LatexCommand ref
6265 reference "sub:Intermediate-Dump-Options"
6271 \begin_inset LatexCommand ref
6272 reference "sub:The-anatomy-of"
6278 \begin_inset Quotes sld
6281 Anatomy of the compiler
6282 \begin_inset Quotes srd
6288 \begin_layout Subsection
6289 Postprocessing the Intel Hex
6290 \begin_inset LatexCommand index
6291 name "Intel hex format"
6296 \begin_inset LatexCommand label
6297 name "sub:Postprocessing-the-Intel"
6304 \begin_layout Standard
6305 In most cases this won't be needed but the Intel Hex file
6306 \begin_inset LatexCommand index
6311 which is generated by SDCC might include lines of varying length and the
6312 addresses within the file are not guaranteed to be strictly ascending.
6313 If your toolchain or a bootloader does not like this you can use the tool
6319 \begin_inset LatexCommand index
6320 name "packihx (tool)"
6324 which is part of the SDCC distribution:
6331 packihx sourcefile.ihx >sourcefile.hex
6338 The separately available
6343 \begin_inset LatexCommand index
6344 name "srecord (bin, hex, ... tool)"
6348 package additionally allows to set undefined locations to a predefined
6349 value, to insert checksums
6350 \begin_inset LatexCommand index
6355 of various flavours (crc, add, xor) and to perform other manipulations
6356 (convert, split, crop, offset, ...).
6364 srec_cat\InsetSpace ~
6366 sourcefile.ihx -intel\InsetSpace ~
6368 -o sourcefile.hex -intel
6375 An example for a more complex command line
6379 \begin_layout Standard
6380 the command backfills
6381 \begin_inset LatexCommand index
6382 name "backfill unused memory"
6386 unused memory with 0x12 and the overall 16 bit sum of the complete 64 kByte
6388 If the program counter on an mcs51 runs wild the backfill pattern 0x12
6389 will be interpreted as an
6397 (where an emergency routine could sit).
6410 srec_cat\InsetSpace ~
6411 sourcefile.ihx -intel\InsetSpace ~
6413 -fill 0x12 0x0000 0xfffe\InsetSpace ~
6414 -little-endian-checksum-nega
6415 tive 0xfffe 0x02 0x02\InsetSpace ~
6417 -o sourcefile.hex -intel
6426 The srecord package is available at
6427 \begin_inset LatexCommand url
6428 target "http://sf.net/projects/srecord"
6435 \begin_layout Subsection
6436 Projects with Multiple Source Files
6439 \begin_layout Standard
6440 SDCC can compile only ONE file at a time.
6441 Let us for example assume that you have a project containing the following
6446 foo1.c (contains some functions)
6448 foo2.c (contains some more functions)
6451 n.c (contains more functions and the function main)
6459 The first two files will need to be compiled separately with the commands:
6491 Then compile the source file containing the
6496 \begin_inset LatexCommand index
6501 the files together with the following command:
6509 foomain.c\InsetSpace ~
6510 foo1.rel\InsetSpace ~
6515 \begin_inset LatexCommand index
6528 can be separately compiled as well:
6539 sdcc foomain.rel foo1.rel foo2.rel
6546 The file containing the
6558 file specified in the command line, since the linkage editor processes
6559 file in the order they are presented to it.
6560 The linker is invoked from SDCC using a script file with extension .lnk
6561 \begin_inset LatexCommand index
6567 You can view this file to troubleshoot linking problems such as those arising
6568 from missing libraries.
6571 \begin_layout Subsection
6572 Projects with Additional Libraries
6573 \begin_inset LatexCommand index
6581 \begin_layout Standard
6582 Some reusable routines may be compiled into a library, see the documentation
6583 for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
6587 \begin_inset LatexCommand index
6595 Libraries created in this manner can be included in the command line.
6596 Make sure you include the -L <library-path> option to tell the linker where
6597 to look for these files if they are not in the current directory.
6598 Here is an example, assuming you have the source file
6610 (if that is not the same as your current project):
6617 sdcc foomain.c foolib.lib -L mylib
6628 must be an absolute path name.
6632 The most efficient way to use libraries is
6633 to keep separate modules in separate source files.
6634 The lib file now should name all the modules.rel
6635 \begin_inset LatexCommand index
6641 For an example see the standard library file
6645 in the directory <installdir>/share/lib/small.
6648 \begin_layout Subsection
6649 Using sdcclib to Create and Manage Libraries
6650 \begin_inset LatexCommand index
6658 \begin_layout Standard
6659 Alternatively, instead of having a .rel file for each entry on the library
6660 file as described in the preceding section, sdcclib can be used to embed
6661 all the modules belonging to such library in the library file itself.
6662 This results in a larger library file, but it greatly reduces the number
6663 of disk files accessed by the linker.
6664 Additionally, the packed library file contains an index of all include
6665 modules and symbols that significantly speeds up the linking process.
6666 To display a list of options supported by sdcclib type:
6671 \begin_layout Standard
6676 \begin_inset LatexCommand index
6688 To create a new library file, start by compiling all the required modules.
6694 \begin_layout Standard
6701 \begin_layout Standard
6708 \begin_layout Standard
6715 \begin_layout Standard
6722 \begin_layout Standard
6731 \begin_layout Standard
6732 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
6734 The next step is to add the .rel files to the library file:
6739 \begin_layout Standard
6743 sdcclib libint.lib _divsint.rel
6746 \begin_inset LatexCommand index
6754 \begin_layout Standard
6758 sdcclib libint.lib _divuint.rel
6761 \begin_layout Standard
6765 sdcclib libint.lib _modsint.rel
6768 \begin_layout Standard
6772 sdcclib libint.lib _moduint.rel
6775 \begin_layout Standard
6779 sdcclib libint.lib _mulint.rel
6787 \begin_layout Standard
6796 \begin_layout Standard
6800 sdcclib libint.lib _divsint.rel _divuint.rel _modsint.rel _moduint.rel _mulint.rel
6808 \begin_layout Standard
6809 If the file already exists in the library, it will be replaced.
6810 If a list of .rel files is available, you can tell sdcclib to add those
6812 For example, if the file 'myliblist.txt' contains
6820 \begin_layout Standard
6827 \begin_layout Standard
6834 \begin_layout Standard
6841 \begin_layout Standard
6848 \begin_layout Standard
6860 \begin_layout Standard
6869 \begin_layout Standard
6873 sdcclib -l libint.lib myliblist.txt
6881 \begin_layout Standard
6882 Additionally, you can instruct sdcclib to compiles the files before adding
6883 them to the library.
6884 This is achieved using the environment variables SDCCLIB_CC and/or SDCCLIB_AS.
6893 \begin_layout Standard
6897 set SDCCLIB_CC=sdcc -c
6900 \begin_layout Standard
6904 sdcclib -l libint.lib myliblist.txt
6912 \begin_layout Standard
6913 To see what modules and symbols are included in the library, options -s
6914 and -m are available.
6922 sdcclib -s libint.lib
6925 \begin_inset LatexCommand index
6938 \begin_layout Standard
6944 \begin_layout Standard
6950 \begin_layout Standard
6958 \begin_layout Standard
6964 \begin_layout Standard
6970 \begin_layout Standard
6976 \begin_layout Standard
6982 \begin_layout Standard
6990 \begin_layout Standard
6996 \begin_layout Standard
7002 \begin_layout Standard
7010 \begin_layout Standard
7016 \begin_layout Standard
7022 \begin_layout Standard
7028 \begin_layout Standard
7036 \begin_layout Standard
7042 \begin_layout Standard
7053 \begin_layout Standard
7054 If the source files are compiled using -
7058 \begin_layout Standard
7068 \begin_inset LatexCommand index
7073 , the corresponding debug information file .adb will be include in the library
7075 The library files created with sdcclib are plain text files, so they can
7076 be viewed with a text editor.
7077 It is not recommended to modify a library file created with sdcclib using
7078 a text editor, as there are file indexes numbers located across the file
7079 used by the linker to quickly locate the required module to link.
7080 Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
7081 it can be safely deleted, since all the information required for linking
7082 is embedded in the library file itself.
7083 Library files created using sdcclib are used as described in the preceding
7085 \begin_inset VSpace bigskip
7091 \begin_layout Section
7092 Command Line Options
7093 \begin_inset LatexCommand index
7094 name "Command Line Options"
7099 \begin_inset LatexCommand label
7100 name "sec:Command-Line-Options"
7107 \begin_layout Subsection
7108 Processor Selection Options
7109 \begin_inset LatexCommand index
7110 name "Options processor selection"
7115 \begin_inset LatexCommand index
7116 name "Processor selection options"
7124 \labelwidthstring 00.00.0000
7128 \begin_inset LatexCommand index
7135 Generate code for the Intel MCS51
7136 \begin_inset LatexCommand index
7141 family of processors.
7142 This is the default processor target.
7146 \labelwidthstring 00.00.0000
7150 \begin_inset LatexCommand index
7157 Generate code for the Dallas DS80C390
7158 \begin_inset LatexCommand index
7167 \labelwidthstring 00.00.0000
7171 \begin_inset LatexCommand index
7178 Generate code for the Dallas DS80C400
7179 \begin_inset LatexCommand index
7188 \labelwidthstring 00.00.0000
7192 \begin_inset LatexCommand index
7199 Generate code for the Freescale/Motorola HC08
7200 \begin_inset LatexCommand index
7205 family of processors.
7209 \labelwidthstring 00.00.0000
7213 \begin_inset LatexCommand index
7220 Generate code for the Zilog Z80
7221 \begin_inset LatexCommand index
7226 family of processors.
7230 \labelwidthstring 00.00.0000
7234 \begin_inset LatexCommand index
7241 Generate code for the GameBoy Z80
7242 \begin_inset LatexCommand index
7243 name "gbz80 (GameBoy Z80)"
7247 processor (Not actively maintained).
7251 \labelwidthstring 00.00.0000
7255 \begin_inset LatexCommand index
7262 Generate code for the Atmel AVR
7263 \begin_inset LatexCommand index
7268 processor (Not maintained, not complete).
7269 AVR users should probably have a look at winavr
7270 \begin_inset LatexCommand url
7271 target "http://sourceforge.net/projects/winavr"
7276 \begin_inset LatexCommand url
7277 target "http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index"
7281 , which is based on AVR-port of the gcc compiler.
7284 \begin_layout Standard
7285 \begin_inset Note Note
7288 \begin_layout Standard
7289 I think it is fair to direct users there for now.
7290 Open source is also about avoiding unnecessary work .
7291 But I didn't find the 'official' link.
7300 \labelwidthstring 00.00.0000
7304 \begin_inset LatexCommand index
7311 Generate code for the Microchip PIC 14
7312 \begin_inset LatexCommand index
7317 -bit processors (p16f84 and variants.
7318 In development, not complete).
7321 \begin_layout Standard
7322 \begin_inset Note Note
7325 \begin_layout Standard
7326 p16f627 p16f628 p16f84 p16f873 p16f877?
7335 \labelwidthstring 00.00.0000
7339 \begin_inset LatexCommand index
7346 Generate code for the Microchip PIC 16
7347 \begin_inset LatexCommand index
7352 -bit processors (p18f452 and variants.
7353 In development, not complete).
7357 \labelwidthstring 00.00.0000
7362 Generate code for the Toshiba TLCS-900H
7363 \begin_inset LatexCommand index
7368 processor (Not maintained, not complete).
7372 \labelwidthstring 00.00.0000
7376 \begin_inset LatexCommand index
7383 Generate code for the Phillips XA51
7384 \begin_inset LatexCommand index
7389 processor (Not maintained, not complete).
7392 \begin_layout Standard
7393 \begin_inset VSpace bigskip
7399 \begin_layout Subsection
7400 Preprocessor Options
7401 \begin_inset LatexCommand index
7402 name "Options preprocessor"
7407 \begin_inset LatexCommand index
7408 name "Preprocessor options"
7413 \begin_inset LatexCommand index
7414 name "sdcpp (preprocessor)"
7422 \labelwidthstring 00.00.0000
7426 \begin_inset LatexCommand index
7433 The additional location where the preprocessor will look for <..h> or
7434 \begin_inset Quotes eld
7438 \begin_inset Quotes erd
7445 \labelwidthstring 00.00.0000
7449 \begin_inset LatexCommand index
7450 name "-D<macro[=value]>"
7456 Command line definition of macros.
7457 Passed to the preprocessor.
7461 \labelwidthstring 00.00.0000
7465 \begin_inset LatexCommand index
7472 Tell the preprocessor to output a rule suitable for make describing the
7473 dependencies of each object file.
7474 For each source file, the preprocessor outputs one make-rule whose target
7475 is the object file name for that source file and whose dependencies are
7476 all the files `#include'd in it.
7477 This rule may be a single line or may be continued with `
7479 '-newline if it is long.
7480 The list of rules is printed on standard output instead of the preprocessed
7483 \begin_inset LatexCommand index
7492 \labelwidthstring 00.00.0000
7496 \begin_inset LatexCommand index
7503 Tell the preprocessor not to discard comments.
7504 Used with the `-E' option.
7508 \labelwidthstring 00.00.0000
7512 \begin_inset LatexCommand index
7522 Like `-M' but the output mentions only the user header files included with
7524 \begin_inset Quotes eld
7528 System header files included with `#include <file>' are omitted.
7532 \labelwidthstring 00.00.0000
7536 \begin_inset LatexCommand index
7537 name "-Aquestion(answer)"
7543 Assert the answer answer for question, in case it is tested with a preprocessor
7544 conditional such as `#if #question(answer)'.
7545 `-A-' disables the standard assertions that normally describe the target
7550 \labelwidthstring 00.00.0000
7554 \begin_inset LatexCommand index
7561 Undefine macro macro.
7562 `-U' options are evaluated after all `-D' options, but before any `-include'
7563 and `-imacros' options.
7567 \labelwidthstring 00.00.0000
7571 \begin_inset LatexCommand index
7578 Tell the preprocessor to output only a list of the macro definitions that
7579 are in effect at the end of preprocessing.
7580 Used with the `-E' option.
7584 \labelwidthstring 00.00.0000
7588 \begin_inset LatexCommand index
7595 Tell the preprocessor to pass all macro definitions into the output, in
7596 their proper sequence in the rest of the output.
7600 \labelwidthstring 00.00.0000
7604 \begin_inset LatexCommand index
7614 Like `-dD' except that the macro arguments and contents are omitted.
7615 Only `#define name' is included in the output.
7619 \labelwidthstring 00.00.0000
7622 -pedantic-parse-number
7623 \begin_inset LatexCommand index
7629 \begin_inset LatexCommand index
7630 name "-pedantic-parse-number"
7638 \begin_inset LatexCommand label
7639 name "lyx:-pedantic-parse-number"
7648 Pedantic parse numbers so that situations like 0xfe-LO_B(3) are parsed properly
7649 and the macro LO_B(3) gets expanded.
7650 See also #pragma pedantic_parse_number
7651 \begin_inset LatexCommand vpageref
7652 reference "ite:pedantic_parse_number"
7657 \begin_inset LatexCommand ref
7658 reference "sec:Pragmas"
7664 Note: this functionality is not in conformance with C99 standard!
7668 \labelwidthstring 00.00.0000
7672 preprocessorOption[,preprocessorOption]
7675 \begin_inset LatexCommand index
7676 name "-Wp preprocessorOption[,preprocessorOption]"
7681 Pass the preprocessorOption to the preprocessor
7686 \begin_inset LatexCommand index
7687 name "sdcpp (preprocessor)"
7692 SDCC uses an adapted version of the preprocessor
7696 of the GNU Compiler Collection
7697 \begin_inset LatexCommand index
7698 name "gcc (GNU Compiler Collection)"
7707 \begin_inset LatexCommand url
7708 target "http://gcc.gnu.org/"
7712 ), if you need more dedicated options please refer to the GCC\InsetSpace ~
7717 \begin_inset LatexCommand htmlurl
7718 target "http://www.gnu.org/software/gcc/onlinedocs/"
7725 \begin_layout Standard
7726 \begin_inset VSpace bigskip
7732 \begin_layout Subsection
7734 \begin_inset LatexCommand index
7735 name "Options linker"
7740 \begin_inset LatexCommand index
7741 name "Linker options"
7749 \labelwidthstring 00.00.0000
7759 \begin_layout Standard
7771 \begin_inset LatexCommand index
7772 name "-\\/-lib-path <path>"
7777 \begin_inset LatexCommand index
7778 name "-L -\\/-lib-path"
7785 <absolute path to additional libraries> This option is passed to the linkage
7786 editor's additional libraries
7787 \begin_inset LatexCommand index
7793 The path name must be absolute.
7794 Additional library files may be specified in the command line.
7795 See section Compiling programs for more details.
7799 \labelwidthstring 00.00.0000
7806 \begin_layout Standard
7818 \begin_inset LatexCommand index
7819 name "-\\/-xram-loc <Value>"
7824 <Value> The start location of the external ram
7825 \begin_inset LatexCommand index
7826 name "xdata (mcs51, ds390 storage class)"
7830 , default value is 0.
7831 The value entered can be in Hexadecimal or Decimal format, e.g.: -
7835 \begin_layout Standard
7844 -xram-loc 0x8000 or -
7848 \begin_layout Standard
7861 \labelwidthstring 00.00.0000
7868 \begin_layout Standard
7880 \begin_inset LatexCommand index
7881 name "-\\/-code-loc <Value>"
7886 <Value> The start location of the code
7887 \begin_inset LatexCommand index
7892 segment, default value 0.
7893 Note when this option is used the interrupt vector table
7894 \begin_inset LatexCommand index
7895 name "interrupt vector table"
7899 is also relocated to the given address.
7900 The value entered can be in Hexadecimal or Decimal format, e.g.: -
7904 \begin_layout Standard
7913 -code-loc 0x8000 or -
7917 \begin_layout Standard
7930 \labelwidthstring 00.00.0000
7937 \begin_layout Standard
7949 \begin_inset LatexCommand index
7950 name "-\\/-stack-loc <Value>"
7955 <Value> By default the stack
7956 \begin_inset LatexCommand index
7961 is placed after the data segment.
7962 Using this option the stack can be placed anywhere in the internal memory
7964 The value entered can be in Hexadecimal or Decimal format, e.g.
7969 \begin_layout Standard
7978 -stack-loc 0x20 or -
7982 \begin_layout Standard
7992 Since the sp register is incremented before a push or call, the initial
7993 sp will be set to one byte prior the provided value.
7994 The provided value should not overlap any other memory areas such as used
7995 register banks or the data segment and with enough space for the current
8003 \begin_layout Standard
8016 \begin_inset LatexCommand index
8017 name "-\\/-pack-iram"
8021 option (which is now a default setting) will override this setting, so
8022 you should also specify the
8028 \begin_layout Standard
8041 \begin_inset LatexCommand index
8042 name "-\\/-no-pack-iram"
8046 option if you need to manually place the stack.
8050 \labelwidthstring 00.00.0000
8057 \begin_layout Standard
8069 \begin_inset LatexCommand index
8070 name "-\\/-xstack-loc <Value>"
8075 <Value> By default the external stack
8076 \begin_inset LatexCommand index
8081 is placed after the pdata
8082 \begin_inset LatexCommand index
8083 name "pdata (mcs51, ds390 storage class)"
8088 Using this option the xstack can be placed anywhere in the external memory
8090 The value entered can be in Hexadecimal or Decimal format, e.g.
8095 \begin_layout Standard
8104 -xstack-loc 0x8000 or -
8108 \begin_layout Standard
8118 The provided value should not overlap any other memory areas such as the
8119 pdata or xdata segment and with enough space for the current application.
8123 \labelwidthstring 00.00.0000
8130 \begin_layout Standard
8142 \begin_inset LatexCommand index
8143 name "-\\/-data-loc <Value>"
8148 <Value> The start location of the internal ram data
8149 \begin_inset LatexCommand index
8150 name "data (mcs51, ds390 storage class)"
8155 The value entered can be in Hexadecimal or Decimal format, eg.
8160 \begin_layout Standard
8173 \begin_layout Standard
8183 (By default, the start location of the internal ram data segment is set
8184 as low as possible in memory, taking into account the used register banks
8185 and the bit segment at address 0x20.
8186 For example if register banks 0 and 1 are used without bit variables, the
8187 data segment will be set, if -
8191 \begin_layout Standard
8200 -data-loc is not used, to location 0x10.)
8204 \labelwidthstring 00.00.0000
8211 \begin_layout Standard
8223 \begin_inset LatexCommand index
8224 name "-\\/-idata-loc <Value>"
8229 <Value> The start location of the indirectly addressable internal ram
8230 \begin_inset LatexCommand index
8231 name "idata (mcs51, ds390 storage class)"
8235 of the 8051, default value is 0x80.
8236 The value entered can be in Hexadecimal or Decimal format, eg.
8241 \begin_layout Standard
8250 -idata-loc 0x88 or -
8254 \begin_layout Standard
8267 \labelwidthstring 00.00.0000
8274 \begin_layout Standard
8286 <Value> The start location of the bit
8287 \begin_inset LatexCommand index
8292 addressable internal ram of the 8051.
8298 Instead an option can be passed directly to the linker: -Wl\InsetSpace ~
8303 \labelwidthstring 00.00.0000
8310 \begin_layout Standard
8320 \begin_inset LatexCommand index
8321 name "-\\/-out-fmt-ihx"
8327 The linker output (final object code) is in Intel Hex format.
8328 \begin_inset LatexCommand index
8329 name "Intel hex format"
8333 This is the default option.
8334 The format itself is documented in the documentation of srecord
8335 \begin_inset LatexCommand index
8336 name "srecord (bin, hex, ... tool)"
8344 \labelwidthstring 00.00.0000
8351 \begin_layout Standard
8361 \begin_inset LatexCommand index
8362 name "-\\/-out-fmt-s19"
8368 The linker output (final object code) is in Motorola S19 format
8369 \begin_inset LatexCommand index
8370 name "Motorola S19 format"
8375 The format itself is documented in the documentation of srecord.
8379 \labelwidthstring 00.00.0000
8386 \begin_layout Standard
8396 \begin_inset LatexCommand index
8397 name "-\\/-out-fmt-s19"
8402 \begin_inset LatexCommand index
8403 name "HC08!Options!-\\/-out-fmt-elf"
8409 The linker output (final object code) is in ELF format
8410 \begin_inset LatexCommand index
8416 (Currently only supported for the HC08
8417 \begin_inset LatexCommand index
8426 \labelwidthstring 00.00.0000
8430 linkOption[,linkOption]
8433 \begin_inset LatexCommand index
8434 name "-Wl linkOption[,linkOption]"
8439 \begin_inset LatexCommand label
8440 name "lyx:-Wl option"
8445 Pass the linkOption to the linker.
8446 If a bootloader is used an option like
8447 \begin_inset Quotes sld
8452 \begin_inset Quotes srd
8455 would be typical to set the start of the code segment.
8456 Either use the double quotes around this option or use no space (e.g.
8458 See also #pragma constseg and #pragma codeseg in section
8459 \begin_inset LatexCommand ref
8460 reference "sec:Pragmas"
8465 File sdcc/as/doc/asxhtm.html has more on linker options.
8468 \begin_layout Standard
8469 \begin_inset VSpace bigskip
8475 \begin_layout Subsection
8477 \begin_inset LatexCommand index
8478 name "Options MCS51"
8483 \begin_inset LatexCommand index
8484 name "MCS51 options"
8492 \labelwidthstring 00.00.0000
8499 \begin_layout Standard
8509 \begin_inset LatexCommand index
8510 name "-\\/-model-small"
8519 Generate code for Small Model programs, see section Memory Models for more
8521 This is the default model.
8525 \labelwidthstring 00.00.0000
8532 \begin_layout Standard
8542 \begin_inset LatexCommand index
8543 name "-\\/-model-medium"
8549 Generate code for Medium model programs, see section Memory Models for
8551 If this option is used all source files in the project have to be compiled
8553 It must also be used when invoking the linker.
8557 \labelwidthstring 00.00.0000
8564 \begin_layout Standard
8574 \begin_inset LatexCommand index
8575 name "-\\/-model-large"
8581 Generate code for Large model programs, see section Memory Models for more
8583 If this option is used all source files in the project have to be compiled
8585 It must also be used when invoking the linker.
8589 \labelwidthstring 00.00.0000
8596 \begin_layout Standard
8606 \begin_inset LatexCommand index
8613 Uses a pseudo stack in the pdata
8614 \begin_inset LatexCommand index
8615 name "pdata (mcs51, ds390 storage class)"
8619 area (usually the first 256 bytes in the external ram) for allocating variables
8620 and passing parameters.
8622 \begin_inset LatexCommand ref
8623 reference "sub:External-Stack"
8628 External Stack for more details.
8632 \labelwidthstring 00.00.0000
8639 \begin_layout Standard
8652 \begin_inset LatexCommand index
8653 name "-\\/-iram-size <Value>"
8657 Causes the linker to check if the internal ram usage is within limits of
8662 \labelwidthstring 00.00.0000
8669 \begin_layout Standard
8682 \begin_inset LatexCommand index
8683 name "-\\/-xram-size <Value>"
8687 Causes the linker to check if the external ram usage is within limits of
8692 \labelwidthstring 00.00.0000
8699 \begin_layout Standard
8712 \begin_inset LatexCommand index
8713 name "-\\/-code-size <Value>"
8717 Causes the linker to check if the code memory usage is within limits of
8722 \labelwidthstring 00.00.0000
8729 \begin_layout Standard
8742 \begin_inset LatexCommand index
8743 name "-\\/-stack-size <Value>"
8747 Causes the linker to check if there is at minimum <Value> bytes for stack.
8751 \labelwidthstring 00.00.0000
8758 \begin_layout Standard
8771 \begin_inset LatexCommand index
8772 name "-\\/-pack-iram"
8776 Causes the linker to use unused register banks for data variables and pack
8777 data, idata and stack together.
8778 This is the default now.
8782 \labelwidthstring 00.00.0000
8789 \begin_layout Standard
8802 \begin_inset LatexCommand index
8803 name "-\\/-no-pack-iram"
8807 Causes the linker to use old style for allocating memory areas.
8811 \labelwidthstring 00.00.0000
8818 \begin_layout Standard
8831 \begin_inset LatexCommand index
8832 name "-\\/-acall-ajmp"
8836 Replaces the three byte instructions lcall/ljmp with the two byte instructions
8838 Only use this option if your code is in the same 2k block of memory.
8839 You may need to use this option for some 8051 derivatives which lack the
8840 lcall/ljmp instructions..
8843 \begin_layout Standard
8844 \begin_inset VSpace bigskip
8850 \begin_layout Subsection
8851 DS390 / DS400 Options
8852 \begin_inset LatexCommand index
8853 name "Options DS390"
8858 \begin_inset LatexCommand index
8867 \labelwidthstring 00.00.0000
8874 \begin_layout Standard
8886 \begin_inset LatexCommand index
8887 name "DS390!Options!-\\/-model-flat24"
8895 Generate 24-bit flat mode code.
8896 This is the one and only that the ds390 code generator supports right now
8897 and is default when using
8902 See section Memory Models for more details.
8906 \labelwidthstring 00.00.0000
8913 \begin_layout Standard
8923 \begin_inset LatexCommand index
8924 name "DS390!Options!-\\/-protect-sp-update"
8930 disable interrupts during ESP:SP updates.
8934 \labelwidthstring 00.00.0000
8941 \begin_layout Standard
8953 \begin_inset LatexCommand index
8954 name "DS390!Options!-\\/-stack-10bit"
8958 Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
8959 This is the one and only that the ds390 code generator supports right now
8960 and is default when using
8965 In this mode, the stack is located in the lower 1K of the internal RAM,
8966 which is mapped to 0x400000.
8967 Note that the support is incomplete, since it still uses a single byte
8968 as the stack pointer.
8969 This means that only the lower 256 bytes of the potential 1K stack space
8970 will actually be used.
8971 However, this does allow you to reclaim the precious 256 bytes of low RAM
8972 for use for the DATA and IDATA segments.
8973 The compiler will not generate any code to put the processor into 10 bit
8975 It is important to ensure that the processor is in this mode before calling
8976 any re-entrant functions compiled with this option.
8977 In principle, this should work with the
8983 \begin_layout Standard
8993 \begin_inset LatexCommand index
8994 name "-\\/-stack-auto"
9000 option, but that has not been tested.
9001 It is incompatible with the
9007 \begin_layout Standard
9017 \begin_inset LatexCommand index
9025 It also only makes sense if the processor is in 24 bit contiguous addressing
9032 \begin_layout Standard
9041 -model-flat24 option
9046 \begin_inset Note Note
9050 \labelwidthstring 00.00.0000
9057 \begin_layout Standard
9066 -stack-8-bit - switches off the 10-bit mode
9075 \labelwidthstring 00.00.0000
9082 \begin_layout Standard
9092 \begin_inset LatexCommand index
9093 name "DS390!Options!-\\/-stack-probe"
9099 insert call to function __stack_probe at each function prologue.
9103 \labelwidthstring 00.00.0000
9110 \begin_layout Standard
9120 \begin_inset LatexCommand index
9121 name "DS390!Options!-\\/-tini-libid"
9127 <nnnn> LibraryID used in -mTININative.
9132 \labelwidthstring 00.00.0000
9139 \begin_layout Standard
9149 \begin_inset LatexCommand index
9150 name "DS390!Options!-\\/-use-accelerator"
9156 generate code for DS390 Arithmetic Accelerator.
9160 \begin_layout Standard
9161 \begin_inset VSpace bigskip
9167 \begin_layout Subsection
9169 \begin_inset LatexCommand index
9175 \begin_inset LatexCommand index
9184 \labelwidthstring 00.00.0000
9191 \begin_layout Standard
9203 \begin_inset LatexCommand index
9204 name "Z80!Options!-\\/-callee-saves-bc"
9212 Force a called function to always save BC.
9216 \labelwidthstring 00.00.0000
9223 \begin_layout Standard
9235 \begin_inset LatexCommand index
9236 name "Z80!Options!-\\/-no-std-crt0"
9240 When linking, skip the standard crt0.o object file.
9241 You must provide your own crt0.o for your system when linking.
9245 \labelwidthstring 00.00.0000
9252 \begin_layout Standard
9264 \begin_inset LatexCommand index
9265 name "Z80!Options!-\\/-portmode=<Value>"
9269 Determinate PORT I/O mode (<Value> is z80 or z180).
9273 \labelwidthstring 00.00.0000
9280 \begin_layout Standard
9292 \begin_inset LatexCommand index
9293 name "Z80!Options!-\\/-asm=<Value>"
9297 Define assembler name (<Value> is rgbds, asxxxx, isas or z80asm).
9301 \labelwidthstring 00.00.0000
9308 \begin_layout Standard
9321 \begin_inset LatexCommand index
9322 name "Z80!Options!-\\/-codeseg <Value>"
9326 Use <Value> for the code segment name.
9330 \labelwidthstring 00.00.0000
9337 \begin_layout Standard
9350 \begin_inset LatexCommand index
9351 name "Z80!Options!-\\/-constseg <Value>"
9355 Use <Value> for the const segment name.
9359 \labelwidthstring 00.00.0000
9360 \begin_inset VSpace bigskip
9366 \begin_layout Subsection
9368 \begin_inset LatexCommand index
9369 name "Options GBZ80"
9374 \begin_inset LatexCommand index
9383 \labelwidthstring 00.00.0000
9390 \begin_layout Standard
9402 \begin_inset LatexCommand index
9403 name "GBZ80!Options!-\\/-callee-saves-bc"
9411 Force a called function to always save BC.
9415 \labelwidthstring 00.00.0000
9422 \begin_layout Standard
9434 \begin_inset LatexCommand index
9435 name "Z80!Options!-\\/-no-std-crt0"
9439 When linking, skip the standard crt0.o object file.
9440 You must provide your own crt0.o for your system when linking.
9444 \labelwidthstring 00.00.0000
9451 \begin_inset LatexCommand index
9452 name "GBZ80!Options!-bo <Num>"
9456 Use code bank <Num>.
9460 \labelwidthstring 00.00.0000
9467 \begin_inset LatexCommand index
9468 name "GBZ80!Options!-ba <Num>"
9472 Use data bank <Num>.
9476 \labelwidthstring 00.00.0000
9483 \begin_layout Standard
9496 \begin_inset LatexCommand index
9497 name "GBZ80!Options!-\\/-codeseg <Value>"
9501 Use <Value> for the code segment name.
9505 \labelwidthstring 00.00.0000
9512 \begin_layout Standard
9525 \begin_inset LatexCommand index
9526 name "GBZ80!Options!-\\/-constseg <Value>"
9530 Use <Value> for the const segment name.
9533 \begin_layout Standard
9534 \begin_inset VSpace bigskip
9540 \begin_layout Subsection
9541 Optimization Options
9542 \begin_inset LatexCommand index
9543 name "Options optimization"
9548 \begin_inset LatexCommand index
9549 name "Optimization options"
9557 \labelwidthstring 00.00.0000
9564 \begin_layout Standard
9574 \begin_inset LatexCommand index
9581 Will not do global subexpression elimination, this option may be used when
9582 the compiler creates undesirably large stack/data spaces to store compiler
9592 \begin_inset LatexCommand index
9593 name "sloc (spill location)"
9598 A warning message will be generated when this happens and the compiler
9599 will indicate the number of extra bytes it allocated.
9600 It is recommended that this option NOT be used, #pragma\InsetSpace ~
9602 \begin_inset LatexCommand index
9603 name "\\#pragma nogcse"
9607 can be used to turn off global subexpression elimination
9608 \begin_inset LatexCommand index
9609 name "Subexpression elimination"
9613 for a given function only.
9617 \labelwidthstring 00.00.0000
9624 \begin_layout Standard
9634 \begin_inset LatexCommand index
9635 name "-\\/-noinvariant"
9641 Will not do loop invariant optimizations, this may be turned off for reasons
9642 explained for the previous option.
9643 For more details of loop optimizations performed see Loop Invariants in
9645 \begin_inset LatexCommand ref
9646 reference "sub:Loop-Optimizations"
9651 It is recommended that this option NOT be used, #pragma\InsetSpace ~
9653 \begin_inset LatexCommand index
9654 name "\\#pragma noinvariant"
9658 can be used to turn off invariant optimizations for a given function only.
9662 \labelwidthstring 00.00.0000
9669 \begin_layout Standard
9679 \begin_inset LatexCommand index
9680 name "-\\/-noinduction"
9686 Will not do loop induction optimizations, see section strength reduction
9688 It is recommended that this option is NOT used, #pragma\InsetSpace ~
9690 \begin_inset LatexCommand index
9691 name "\\#pragma noinduction"
9695 can be used to turn off induction optimizations for a given function only.
9699 \labelwidthstring 00.00.0000
9706 \begin_layout Standard
9716 \begin_inset LatexCommand index
9717 name "-\\/-nojtbound"
9726 Will not generate boundary condition check when switch statements
9727 \begin_inset LatexCommand index
9728 name "switch statement"
9732 are implemented using jump-tables.
9734 \begin_inset LatexCommand ref
9735 reference "sub:'switch'-Statements"
9740 Switch Statements for more details.
9741 It is recommended that this option is NOT used, #pragma\InsetSpace ~
9743 \begin_inset LatexCommand index
9744 name "\\#pragma nojtbound"
9748 can be used to turn off boundary checking for jump tables for a given function
9753 \labelwidthstring 00.00.0000
9760 \begin_layout Standard
9770 \begin_inset LatexCommand index
9771 name "-\\/-noloopreverse"
9780 Will not do loop reversal
9781 \begin_inset LatexCommand index
9782 name "Loop reversing"
9790 \labelwidthstring 00.00.0000
9795 \begin_layout Standard
9809 \begin_inset LatexCommand index
9810 name "-\\/-nolabelopt "
9814 Will not optimize labels (makes the dumpfiles more readable).
9818 \labelwidthstring 00.00.0000
9825 \begin_layout Standard
9835 \begin_inset LatexCommand index
9836 name "-\\/-no-xinit-opt"
9842 Will not memcpy initialized data from code space into xdata space.
9843 This saves a few bytes in code space if you don't have initialized data
9844 \begin_inset LatexCommand index
9845 name "Variable initialization"
9853 \labelwidthstring 00.00.0000
9860 \begin_layout Standard
9870 \begin_inset LatexCommand index
9871 name "-\\/-nooverlay"
9877 The compiler will not overlay parameters and local variables of any function,
9878 see section Parameters and local variables for more details.
9882 \labelwidthstring 00.00.0000
9889 \begin_layout Standard
9899 \begin_inset LatexCommand index
9906 Disable peep-hole optimization with built-in rules.
9910 \labelwidthstring 00.00.0000
9917 \begin_layout Standard
9929 \begin_inset LatexCommand index
9930 name "-\\/-peep-file"
9935 <filename> This option can be used to use additional rules to be used by
9936 the peep hole optimizer.
9938 \begin_inset LatexCommand ref
9939 reference "sub:Peephole-Optimizer"
9944 Peep Hole optimizations for details on how to write these rules.
9948 \labelwidthstring 00.00.0000
9955 \begin_layout Standard
9965 \begin_inset LatexCommand index
9966 name "-\\/-peep-asm"
9972 Pass the inline assembler code through the peep hole optimizer.
9973 This can cause unexpected changes to inline assembler code, please go through
9974 the peephole optimizer
9975 \begin_inset LatexCommand index
9976 name "Peephole optimizer"
9980 rules defined in the source file tree '<target>/peeph.def' before using
9985 \labelwidthstring 00.00.0000
9992 \begin_layout Standard
10002 \begin_inset LatexCommand index
10003 name "-\\/-opt-code-speed"
10009 The compiler will optimize code generation towards fast code, possibly
10010 at the expense of code size.
10014 \labelwidthstring 00.00.0000
10021 \begin_layout Standard
10031 \begin_inset LatexCommand index
10032 name "-\\/-opt-code-size"
10038 The compiler will optimize code generation towards compact code, possibly
10039 at the expense of code speed.
10042 \begin_layout Standard
10043 \begin_inset VSpace bigskip
10049 \begin_layout Subsection
10051 \begin_inset LatexCommand index
10052 name "Options other"
10060 \labelwidthstring 00.00.0000
10068 \begin_layout Standard
10078 \begin_inset LatexCommand index
10079 name "-\\/-compile-only"
10084 \begin_inset LatexCommand index
10085 name "-c -\\/-compile-only"
10091 will compile and assemble the source, but will not call the linkage editor.
10095 \labelwidthstring 00.00.0000
10104 \begin_layout Standard
10116 \begin_inset LatexCommand index
10123 reads the preprocessed source from standard input and compiles it.
10124 The file name for the assembler output must be specified using the -o option.
10128 \labelwidthstring 00.00.0000
10132 \begin_inset LatexCommand index
10139 Run only the C preprocessor.
10140 Preprocess all the C source files specified and output the results to standard
10145 \labelwidthstring 00.00.0000
10150 \begin_inset LatexCommand index
10151 name "-o <path/file>"
10157 The output path where everything will be placed or the file name used for
10158 all generated output files.
10159 If the parameter is a path, it must have a trailing slash (or backslash
10160 for the Windows binaries) to be recognized as a path.
10161 Note for Windows users: if the path contains spaces, it should be surrounded
10163 The trailing backslash should be doubled in order to prevent escaping the
10164 final quote, for example:
10167 \begin_inset Quotes sld
10181 \begin_inset Quotes srd
10186 or put after the final quote, for example:
10189 \begin_inset Quotes sld
10199 \begin_inset Quotes srd
10207 The path using slashes for directory delimiters can be used too, for example:
10211 \begin_inset Quotes sld
10214 F:/Projects/test3/output 1/
10215 \begin_inset Quotes srd
10224 \labelwidthstring 00.00.0000
10231 \begin_layout Standard
10241 \begin_inset LatexCommand index
10242 name "-\\/-stack-auto"
10251 All functions in the source file will be compiled as
10256 \begin_inset LatexCommand index
10262 the parameters and local variables will be allocated on the stack
10263 \begin_inset LatexCommand index
10270 \begin_inset LatexCommand ref
10271 reference "sec:Parameters-and-Local-Variables"
10275 Parameters and Local Variables for more details.
10276 If this option is used all source files in the project should be compiled
10278 It automatically implies -
10284 \begin_layout Standard
10295 -int-long-reent and -
10301 \begin_layout Standard
10317 \labelwidthstring 00.00.0000
10324 \begin_layout Standard
10334 \begin_inset LatexCommand index
10335 name "-\\/-callee-saves"
10340 \begin_inset LatexCommand label
10341 name "lyx:--callee-saves-function1[,function2][,function3]..."
10345 function1[,function2][,function3]....
10348 The compiler by default uses a caller saves convention for register saving
10349 across function calls, however this can cause unnecessary register pushing
10350 and popping when calling small functions from larger functions.
10351 This option can be used to switch the register saving convention for the
10352 function names specified.
10353 The compiler will not save registers when calling these functions, no extra
10354 code will be generated at the entry and exit (function prologue
10357 \begin_inset LatexCommand index
10358 name "function prologue"
10367 \begin_inset LatexCommand index
10368 name "function epilogue"
10374 ) for these functions to save and restore the registers used by these functions,
10375 this can SUBSTANTIALLY reduce code and improve run time performance of
10376 the generated code.
10377 In the future the compiler (with inter procedural analysis) will be able
10378 to determine the appropriate scheme to use for each function call.
10379 DO NOT use this option for built-in functions such as _mulint..., if this
10380 option is used for a library function the appropriate library function
10381 needs to be recompiled with the same option.
10382 If the project consists of multiple source files then all the source file
10383 should be compiled with the same -
10387 \begin_layout Standard
10396 -callee-saves option string.
10397 Also see #pragma\InsetSpace ~
10399 \begin_inset LatexCommand index
10400 name "\\#pragma callee\\_saves"
10405 \begin_inset LatexCommand vpageref
10406 reference "ite:callee_saves-function1[,function2[,function3...]]--"
10414 \labelwidthstring 00.00.0000
10421 \begin_layout Standard
10431 \begin_inset LatexCommand index
10432 name "-\\/-all-callee-saves"
10442 \begin_layout Standard
10451 -callee-saves will be applied to all functions by default.
10455 \labelwidthstring 00.00.0000
10462 \begin_layout Standard
10472 \begin_inset LatexCommand index
10479 When this option is used the compiler will generate debug information.
10480 The debug information collected in a file with .cdb extension can be used
10482 For more information see documentation for SDCDB.
10483 Another file with no extension contains debug information in AOMF or AOMF51
10484 \begin_inset LatexCommand index
10485 name "AOMF, AOMF51"
10489 format which is commonly used by third party tools.
10493 \labelwidthstring 00.00.0000
10497 \begin_inset LatexCommand index
10507 Stop after the stage of compilation proper; do not assemble.
10508 The output is an assembler code file for the input file specified.
10512 \labelwidthstring 00.00.0000
10519 \begin_layout Standard
10529 \begin_inset LatexCommand index
10530 name "-\\/-int-long-reent"
10536 Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
10537 Note by default these libraries are compiled as non-reentrant.
10538 See section Installation for more details.
10542 \labelwidthstring 00.00.0000
10549 \begin_layout Standard
10559 \begin_inset LatexCommand index
10560 name "-\\/-cyclomatic"
10566 This option will cause the compiler to generate an information message for
10567 each function in the source file.
10568 The message contains some
10572 information about the function.
10573 The number of edges and nodes the compiler detected in the control flow
10574 graph of the function, and most importantly the
10576 cyclomatic complexity
10577 \begin_inset LatexCommand index
10578 name "Cyclomatic complexity"
10584 see section on Cyclomatic Complexity for more details.
10588 \labelwidthstring 00.00.0000
10595 \begin_layout Standard
10605 \begin_inset LatexCommand index
10606 name "-\\/-float-reent"
10612 Floating point library is compiled as reentrant
10613 \begin_inset LatexCommand index
10619 See section Installation for more details.
10623 \labelwidthstring 00.00.0000
10630 \begin_layout Standard
10640 \begin_inset LatexCommand index
10641 name "-\\/-funsigned-char"
10647 The default signedness for every type is
10652 In some embedded environments the default signedness of
10661 To set the signess for characters to unsigned, use the option -
10667 \begin_layout Standard
10679 If this option is set and no signedness keyword (unsigned/signed) is given,
10680 a char will be signed.
10681 All other types are unaffected.
10685 \labelwidthstring 00.00.0000
10692 \begin_layout Standard
10702 \begin_inset LatexCommand index
10703 name "-\\/-main-return"
10709 This option can be used if the code generated is called by a monitor program
10710 or if the main routine includes an endless loop.
10711 This option results in slightly smaller code and saves two bytes of stack
10713 The return from the 'main'
10714 \begin_inset LatexCommand index
10719 function will return to the function calling main.
10720 The default setting is to lock up i.e.
10729 \labelwidthstring 00.00.0000
10736 \begin_layout Standard
10746 \begin_inset LatexCommand index
10747 name "-\\/-nostdinc"
10753 This will prevent the compiler from passing on the default include path
10754 to the preprocessor.
10758 \labelwidthstring 00.00.0000
10765 \begin_layout Standard
10775 \begin_inset LatexCommand index
10776 name "-\\/-nostdlib"
10782 This will prevent the compiler from passing on the default library
10783 \begin_inset LatexCommand index
10788 path to the linker.
10792 \labelwidthstring 00.00.0000
10799 \begin_layout Standard
10809 \begin_inset LatexCommand index
10810 name "-\\/-verbose"
10816 Shows the various actions the compiler is performing.
10820 \labelwidthstring 00.00.0000
10824 \begin_inset LatexCommand index
10831 Shows the actual commands the compiler is executing.
10835 \labelwidthstring 00.00.0000
10842 \begin_layout Standard
10852 \begin_inset LatexCommand index
10853 name "-\\/-no-c-code-in-asm"
10859 Hides your ugly and inefficient c-code from the asm file, so you can always
10860 blame the compiler :)
10864 \labelwidthstring 00.00.0000
10871 \begin_layout Standard
10881 \begin_inset LatexCommand index
10882 name "-\\/-no-gen-comments"
10888 Include code generator and peep-hole comments in the generated asm files.
10892 \labelwidthstring 00.00.0000
10899 \begin_layout Standard
10909 \begin_inset LatexCommand index
10910 name "-\\/-no-peep-comments"
10916 Don't include peep-hole comments in the generated asm files even if -
10922 \begin_layout Standard
10933 -fverbose-asm option is specified.
10937 \labelwidthstring 00.00.0000
10944 \begin_layout Standard
10954 \begin_inset LatexCommand index
10955 name "-\\/-i-code-in-asm"
10961 Include i-codes in the asm file.
10962 Sounds like noise but is most helpful for debugging the compiler itself.
10966 \labelwidthstring 00.00.0000
10973 \begin_layout Standard
10983 \begin_inset LatexCommand index
10989 \begin_inset LatexCommand index
10990 name "-\\/-less-pedantic"
10997 \begin_inset LatexCommand label
10998 name "lyx:--less-pedantic"
11002 Disable some of the more pedantic warnings
11003 \begin_inset LatexCommand index
11009 For more details, see the less_pedantic pragma
11010 \begin_inset LatexCommand vpageref
11011 reference "ite:less_pedantic"
11019 \labelwidthstring 00.00.0000
11026 \begin_layout Standard
11035 -disable-warning\InsetSpace ~
11037 \begin_inset LatexCommand index
11038 name "-\\/-disable-warning"
11044 Disable specific warning with number <nnnn>.
11048 \labelwidthstring 00.00.0000
11055 \begin_layout Standard
11065 \begin_inset LatexCommand index
11072 Treat all warnings as errors.
11076 \labelwidthstring 00.00.0000
11083 \begin_layout Standard
11093 \begin_inset LatexCommand index
11094 name "-\\/-print-search-dirs"
11100 Display the directories in the compiler's search path
11104 \labelwidthstring 00.00.0000
11111 \begin_layout Standard
11121 \begin_inset LatexCommand index
11128 Display errors and warnings using MSVC style, so you can use SDCC with
11129 the visual studio IDE
11130 \begin_inset LatexCommand index
11136 With SDCC both offering a GCC-like (the default) and a MSVC-like
11137 \begin_inset LatexCommand index
11138 name "MSVC output style"
11142 output style, integration into most programming editors should be straightforwa
11147 \labelwidthstring 00.00.0000
11154 \begin_layout Standard
11164 \begin_inset LatexCommand index
11165 name "-\\/-use-stdout"
11171 Send errors and warnings to stdout instead of stderr.
11175 \labelwidthstring 00.00.0000
11179 asmOption[,asmOption]
11182 \begin_inset LatexCommand index
11183 name "-Wa asmOption[,asmOption]"
11188 Pass the asmOption to the assembler
11189 \begin_inset LatexCommand index
11190 name "Options assembler"
11195 \begin_inset LatexCommand index
11196 name "Assembler options"
11201 See file sdcc/as/doc/asxhtm.html for assembler options.cd
11205 \labelwidthstring 00.00.0000
11212 \begin_layout Standard
11222 \begin_inset LatexCommand index
11223 name "-\\/-std-sdcc89"
11229 Generally follow the C89 standard, but allow SDCC features that conflict
11230 with the standard (default).
11234 \labelwidthstring 00.00.0000
11241 \begin_layout Standard
11251 \begin_inset LatexCommand index
11252 name "-\\/-std-c89"
11258 Follow the C89 standard and disable SDCC features that conflict with the
11263 \labelwidthstring 00.00.0000
11270 \begin_layout Standard
11280 \begin_inset LatexCommand index
11281 name "-\\/-std-sdcc99"
11287 Generally follow the C99 standard, but allow SDCC features that conflict
11288 with the standard (incomplete support).
11292 \labelwidthstring 00.00.0000
11299 \begin_layout Standard
11309 \begin_inset LatexCommand index
11310 name "-\\/-std-sdcc99"
11316 Follow the C99 standard and disable SDCC features that conflict with the
11317 standard (incomplete support).
11321 \labelwidthstring 00.00.0000
11328 \begin_layout Standard
11340 \begin_inset LatexCommand index
11341 name "-\\/-codeseg <Value>"
11346 \begin_inset LatexCommand label
11347 name "lyx:-codeseg"
11352 <Name> The name to be used for the code
11353 \begin_inset LatexCommand index
11358 segment, default CSEG.
11359 This is useful if you need to tell the compiler to put the code in a special
11360 segment so you can later on tell the linker to put this segment in a special
11362 Can be used for instance when using bank switching to put the code in a
11367 \labelwidthstring 00.00.0000
11374 \begin_layout Standard
11386 \begin_inset LatexCommand index
11387 name "-\\/-constseg <Value>"
11392 <Name> The name to be used for the const
11393 \begin_inset LatexCommand index
11398 segment, default CONST.
11399 This is useful if you need to tell the compiler to put the const data in
11400 a special segment so you can later on tell the linker to put this segment
11401 in a special place in memory.
11402 Can be used for instance when using bank switching to put the const data
11407 \labelwidthstring 00.00.0000
11414 \begin_layout Standard
11423 -fdollars-in-identifiers
11424 \begin_inset LatexCommand index
11425 name "-\\/-fdollars-in-identifiers"
11431 Permit '$' as an identifier character.
11435 \labelwidthstring 00.00.0000
11442 \begin_layout Standard
11454 \begin_inset LatexCommand index
11455 name "-\\/-more-pedantic"
11460 \begin_inset LatexCommand index
11471 a SDCC compiler option but if you want
11475 warnings you can use a separate tool dedicated to syntax checking like
11477 \begin_inset LatexCommand label
11478 name "lyx:more-pedantic-SPLINT"
11483 \begin_inset LatexCommand index
11484 name "lint (syntax checking tool)"
11489 \begin_inset LatexCommand url
11490 target "http://www.splint.org"
11495 To make your source files parseable by splint you will have to include
11501 \begin_inset LatexCommand index
11502 name "splint (syntax checking tool)"
11506 in your source file and add brackets around extended keywords (like
11509 \begin_inset Quotes sld
11522 \begin_inset Quotes srd
11530 \begin_inset Quotes sld
11533 __interrupt\InsetSpace ~
11535 \begin_inset Quotes srd
11543 Splint has an excellent on line manual at
11544 \begin_inset LatexCommand url
11545 target "http://www.splint.org/manual/"
11549 and it's capabilities go beyond pure syntax checking.
11550 You'll need to tell splint the location of SDCC's include files so a typical
11551 command line could look like this:
11555 splint\InsetSpace ~
11557 /usr/local/share/sdcc/include/mcs51/\InsetSpace ~
11563 \labelwidthstring 00.00.0000
11570 \begin_layout Standard
11582 \begin_inset LatexCommand index
11583 name "-\\/-short-is-8bits"
11588 \begin_inset LatexCommand label
11589 name "lyx:--short-is-8bits"
11593 Treat short as 8-bit (for backward compatibility with older versions of
11594 compiler - see section
11595 \begin_inset LatexCommand ref
11596 reference "sec:Compatibility-with-previous"
11603 \begin_layout Standard
11604 \begin_inset VSpace bigskip
11610 \begin_layout Subsection
11611 Intermediate Dump Options
11612 \begin_inset LatexCommand label
11613 name "sub:Intermediate-Dump-Options"
11618 \begin_inset LatexCommand index
11619 name "Options intermediate dump"
11624 \begin_inset LatexCommand index
11625 name "Intermediate dump options"
11632 \begin_layout Standard
11633 The following options are provided for the purpose of retargetting and debugging
11635 They provide a means to dump the intermediate code (iCode
11636 \begin_inset LatexCommand index
11641 ) generated by the compiler in human readable form at various stages of
11642 the compilation process.
11643 More on iCodes see chapter
11644 \begin_inset LatexCommand ref
11645 reference "sub:The-anatomy-of"
11650 \begin_inset Quotes srd
11653 The anatomy of the compiler
11654 \begin_inset Quotes srd
11661 \labelwidthstring 00.00.0000
11668 \begin_layout Standard
11678 \begin_inset LatexCommand index
11679 name "-\\/-dumpraw"
11685 This option will cause the compiler to dump the intermediate code into
11688 <source filename>.dumpraw
11690 just after the intermediate code has been generated for a function, i.e.
11691 before any optimizations are done.
11693 \begin_inset LatexCommand index
11694 name "Basic blocks"
11698 at this stage ordered in the depth first number, so they may not be in
11699 sequence of execution.
11703 \labelwidthstring 00.00.0000
11710 \begin_layout Standard
11720 \begin_inset LatexCommand index
11721 name "-\\/-dumpgcse"
11727 Will create a dump of iCodes, after global subexpression elimination
11728 \begin_inset LatexCommand index
11729 name "Global subexpression elimination"
11733 , into a file named
11735 <source filename>.dumpgcse.
11739 \labelwidthstring 00.00.0000
11746 \begin_layout Standard
11756 \begin_inset LatexCommand index
11757 name "-\\/-dumpdeadcode"
11763 Will create a dump of iCodes, after deadcode elimination
11764 \begin_inset LatexCommand index
11765 name "Dead-code elimination"
11769 , into a file named
11771 <source filename>.dumpdeadcode.
11775 \labelwidthstring 00.00.0000
11782 \begin_layout Standard
11792 \begin_inset LatexCommand index
11793 name "-\\/-dumploop"
11802 Will create a dump of iCodes, after loop optimizations
11803 \begin_inset LatexCommand index
11804 name "Loop optimization"
11808 , into a file named
11810 <source filename>.dumploop.
11814 \labelwidthstring 00.00.0000
11821 \begin_layout Standard
11831 \begin_inset LatexCommand index
11832 name "-\\/-dumprange"
11841 Will create a dump of iCodes, after live range analysis
11842 \begin_inset LatexCommand index
11843 name "Live range analysis"
11847 , into a file named
11849 <source filename>.dumprange.
11853 \labelwidthstring 00.00.0000
11860 \begin_layout Standard
11870 \begin_inset LatexCommand index
11871 name "-\\/-dumlrange"
11877 Will dump the life ranges
11878 \begin_inset LatexCommand index
11879 name "Live range analysis"
11887 \labelwidthstring 00.00.0000
11894 \begin_layout Standard
11904 \begin_inset LatexCommand index
11905 name "-\\/-dumpregassign"
11911 Will create a dump of iCodes, after register assignment
11912 \begin_inset LatexCommand index
11913 name "Register assignment"
11917 , into a file named
11919 <source filename>.dumprassgn.
11923 \labelwidthstring 00.00.0000
11930 \begin_layout Standard
11940 \begin_inset LatexCommand index
11941 name "-\\/-dumplrange"
11947 Will create a dump of the live ranges of iTemp's
11951 \labelwidthstring 00.00.0000
11958 \begin_layout Standard
11968 \begin_inset LatexCommand index
11969 name "-\\/-dumpall"
11978 Will cause all the above mentioned dumps to be created.
11981 \begin_layout Standard
11982 \begin_inset VSpace bigskip
11988 \begin_layout Subsection
11989 Redirecting output on Windows Shells
11992 \begin_layout Standard
11993 By default SDCC writes its error messages to
11994 \begin_inset Quotes sld
11998 \begin_inset Quotes srd
12002 To force all messages to
12003 \begin_inset Quotes sld
12007 \begin_inset Quotes srd
12019 \begin_layout Standard
12034 \begin_inset LatexCommand index
12035 name "-\\/-use-stdout"
12040 Additionally, if you happen to have visual studio installed in your windows
12041 machine, you can use it to compile your sources using a custom build and
12048 \begin_layout Standard
12060 \begin_inset LatexCommand index
12066 Something like this should work:
12085 \begin_layout Standard
12104 \begin_layout Standard
12116 -model-large -c $(InputPath)
12119 \begin_inset VSpace bigskip
12125 \begin_layout Section
12126 Environment variables
12127 \begin_inset LatexCommand index
12128 name "Environment variables"
12135 \begin_layout Standard
12136 SDCC recognizes the following environment variables:
12140 \labelwidthstring 00.00.0000
12144 \begin_inset LatexCommand index
12145 name "SDCC\\_LEAVE\\_SIGNALS"
12151 SDCC installs a signal handler
12152 \begin_inset LatexCommand index
12153 name "signal handler"
12157 to be able to delete temporary files after an user break (^C) or an exception.
12158 If this environment variable is set, SDCC won't install the signal handler
12159 in order to be able to debug SDCC.
12163 \labelwidthstring 00.00.0000
12169 \begin_inset LatexCommand index
12170 name "TMP, TEMP, TMPDIR"
12176 Path, where temporary files will be created.
12177 The order of the variables is the search order.
12178 In a standard *nix environment these variables are not set, and there's
12179 no need to set them.
12180 On Windows it's recommended to set one of them.
12184 \labelwidthstring 00.00.0000
12188 \begin_inset LatexCommand index
12196 \begin_inset LatexCommand ref
12197 reference "sub:Install-paths"
12203 \begin_inset Quotes sld
12207 \begin_inset Quotes srd
12214 \labelwidthstring 00.00.0000
12218 \begin_inset LatexCommand index
12219 name "SDCC\\_INCLUDE"
12226 \begin_inset LatexCommand ref
12227 reference "sub:Search-Paths"
12233 \begin_inset Quotes sld
12237 \begin_inset Quotes srd
12244 \labelwidthstring 00.00.0000
12248 \begin_inset LatexCommand index
12256 \begin_inset LatexCommand ref
12257 reference "sub:Search-Paths"
12263 \begin_inset Quotes sld
12267 \begin_inset Quotes srd
12273 \begin_layout Standard
12274 There are some more environment variables recognized by SDCC, but these
12275 are solely used for debugging purposes.
12276 They can change or disappear very quickly, and will never be documented.
12277 \begin_inset VSpace bigskip
12283 \begin_layout Section
12284 Storage Class Language Extensions
12287 \begin_layout Subsection
12288 MCS51/DS390 Storage Class
12289 \begin_inset LatexCommand index
12290 name "Storage class"
12294 Language Extensions
12297 \begin_layout Standard
12298 In addition to the ANSI storage classes SDCC allows the following MCS51
12299 specific storage classes:
12302 \begin_layout Subsubsection
12304 \begin_inset LatexCommand index
12305 name "data (mcs51, ds390 storage class)"
12310 \begin_inset LatexCommand index
12311 name "\\_\\_data (mcs51, ds390 storage class)"
12316 \begin_inset LatexCommand index
12317 name "near (storage class)"
12322 \begin_inset LatexCommand index
12323 name "\\_\\_near (storage class)"
12330 \begin_layout Standard
12335 storage class for the Small Memory model (
12343 or the more ANSI-C compliant forms
12351 can be used synonymously).
12352 Variables declared with this storage class will be allocated in the directly
12353 addressable portion of the internal RAM of a 8051, e.g.:
12356 \begin_layout Verse
12359 __data unsigned char test_data;
12362 \begin_layout Standard
12363 Writing 0x01 to this variable generates the assembly code:
12366 \begin_layout Verse
12369 75*00 01\InsetSpace ~
12377 \begin_layout Subsubsection
12379 \begin_inset LatexCommand index
12380 name "xdata (mcs51, ds390 storage class)"
12385 \begin_inset LatexCommand index
12386 name "\\_\\_xdata (mcs51, ds390 storage class)"
12391 \begin_inset LatexCommand index
12392 name "far (storage class)"
12397 \begin_inset LatexCommand index
12398 name "\\_\\_far (storage class)"
12405 \begin_layout Standard
12406 Variables declared with this storage class will be placed in the external
12412 storage class for the Large Memory model, e.g.:
12415 \begin_layout Verse
12418 __xdata unsigned char test_xdata;
12421 \begin_layout Standard
12422 Writing 0x01 to this variable generates the assembly code:
12425 \begin_layout Verse
12428 90s00r00\InsetSpace ~
12459 \begin_layout Subsubsection
12461 \begin_inset LatexCommand index
12462 name "idata (mcs51, ds390 storage class)"
12467 \begin_inset LatexCommand index
12468 name "\\_\\_idata (mcs51, ds390 storage class)"
12475 \begin_layout Standard
12476 Variables declared with this storage class will be allocated into the indirectly
12477 addressable portion of the internal ram of a 8051, e.g.:
12480 \begin_layout Verse
12483 __idata unsigned char test_idata;
12486 \begin_layout Standard
12487 Writing 0x01 to this variable generates the assembly code:
12490 \begin_layout Verse
12517 \begin_layout Standard
12518 Please note, the first 128 byte of idata physically access the same RAM
12519 as the data memory.
12520 The original 8051 had 128 byte idata memory, nowadays most devices have
12521 256 byte idata memory.
12523 \begin_inset LatexCommand index
12528 is located in idata memory.
12531 \begin_layout Subsubsection
12533 \begin_inset LatexCommand index
12534 name "pdata (mcs51, ds390 storage class)"
12539 \begin_inset LatexCommand index
12540 name "\\_\\_pdata (mcs51, ds390 storage class)"
12547 \begin_layout Standard
12548 Paged xdata access is just as straightforward as using the other addressing
12550 It is typically located at the start of xdata and has a maximum size of
12552 The following example writes 0x01 to the pdata variable.
12553 Please note, pdata access physically accesses xdata memory.
12554 The high byte of the address is determined by port P2
12555 \begin_inset LatexCommand index
12556 name "P2 (mcs51 sfr)"
12560 (or in case of some 8051 variants by a separate Special Function Register,
12562 \begin_inset LatexCommand ref
12563 reference "sub:MCS51-variants"
12572 storage class for the Medium Memory model, e.g.:
12575 \begin_layout Verse
12578 __pdata unsigned char test_pdata;
12581 \begin_layout Standard
12582 Writing 0x01 to this variable generates the assembly code:
12585 \begin_layout Verse
12594 mov r0,#_test_pdata
12616 \begin_layout Standard
12621 \begin_layout Standard
12631 \begin_inset LatexCommand index
12636 option is used the pdata memory area is followed by the xstack memory area
12637 and the sum of their sizes is limited to 256 bytes.
12640 \begin_layout Subsubsection
12642 \begin_inset LatexCommand index
12648 \begin_inset LatexCommand index
12656 \begin_layout Standard
12657 'Variables' declared with this storage class will be placed in the code
12661 \begin_layout Verse
12664 __code unsigned char test_code;
12667 \begin_layout Standard
12668 Read access to this variable generates the assembly code:
12671 \begin_layout Verse
12674 90s00r6F\InsetSpace ~
12677 mov dptr,#_test_code
12702 \begin_layout Standard
12707 indexed arrays of characters in code memory can be accessed efficiently:
12710 \begin_layout Verse
12713 __code char test_array[] = {'c','h','e','a','p'};
12716 \begin_layout Standard
12717 Read access to this array using an 8-bit unsigned index generates the assembly
12721 \begin_layout Verse
12733 \begin_layout Verse
12736 90s00r41\InsetSpace ~
12739 mov dptr,#_test_array
12742 \begin_layout Verse
12757 \begin_layout Subsubsection
12759 \begin_inset LatexCommand index
12765 \begin_inset LatexCommand index
12773 \begin_layout Standard
12774 This is a data-type and a storage class specifier.
12775 When a variable is declared as a bit, it is allocated into the bit addressable
12776 memory of 8051, e.g.:
12779 \begin_layout Verse
12785 \begin_layout Standard
12786 Writing 1 to this variable generates the assembly code:
12789 \begin_layout Verse
12803 \begin_layout Standard
12804 The bit addressable memory consists of 128 bits which are located from 0x20
12805 to 0x2f in data memory.
12808 Apart from this 8051 specific storage class most architectures support
12810 \begin_inset LatexCommand index
12819 \begin_layout Standard
12820 Not really meant as examples, but nevertheless showing what bitfields are
12821 about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
12827 In accordance with ISO/IEC 9899 bits and bitfields without an explicit
12828 signed modifier are implemented as unsigned.
12831 \begin_layout Subsubsection
12833 \begin_inset LatexCommand index
12839 \begin_inset LatexCommand index
12845 \begin_inset LatexCommand index
12851 \begin_inset LatexCommand index
12857 \begin_inset LatexCommand index
12863 \begin_inset LatexCommand index
12869 \begin_inset LatexCommand index
12875 \begin_inset LatexCommand index
12883 \begin_layout Standard
12884 Like the bit keyword,
12886 sfr / sfr16 / sfr32 / sbit
12888 signify both a data-type and storage class, they are used to describe the
12909 variables of a 8051, eg:
12912 \begin_layout Verse
12916 \begin_inset LatexCommand index
12922 \begin_inset LatexCommand index
12927 (0x80) P0;\InsetSpace ~
12928 /* special function register P0 at location 0x80 */
12933 special function register combination for timer 0
12937 with the high byte at
12938 location 0x8C and the low byte at location 0x8A */
12940 __sfr16 __at (0x8C8A)
12946 \begin_inset LatexCommand index
12952 \begin_inset LatexCommand index
12957 (0xd7) CY;\InsetSpace ~
12959 \begin_inset LatexCommand index
12965 \begin_inset LatexCommand index
12973 \begin_layout Standard
12974 Special function registers which are located on an address dividable by
12975 8 are bit-addressable, an
12979 addresses a specific bit within these sfr.
12981 16 Bit and 32 bit special function
12982 register combinations which require a certain access order are better not
12992 Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
12993 this is not guaranteed.
12998 \begin_layout Standard
12999 Please note, if you use a header file which was written for another compiler
13000 then the sfr / sfr16 / sfr32 / sbit Storage Class extensions will most
13006 Specifically the syntax
13009 sfr P0 = 0x80;\InsetSpace ~
13016 by SDCC to an assignment of 0x80 to a variable called P0
13019 \begin_inset Marginal
13022 \begin_layout Standard
13036 Nevertheless it is possible to write header files
13037 \begin_inset LatexCommand index
13038 name "Header files"
13043 \begin_inset LatexCommand index
13044 name "Include files"
13048 which can be shared among different compilers (see section
13049 \begin_inset LatexCommand ref
13050 reference "sec:Porting-code-to-other-compilers"
13058 \begin_layout Subsubsection
13060 \begin_inset LatexCommand index
13065 to MCS51/DS390 specific memory spaces
13068 \begin_layout Standard
13069 SDCC allows (via language extensions) pointers to explicitly point to any
13070 of the memory spaces
13071 \begin_inset LatexCommand index
13072 name "Memory model"
13077 In addition to the explicit pointers, the compiler uses (by default) generic
13078 pointers which can be used to point to any of the memory spaces.
13083 declaration examples:
13086 \begin_layout Verse
13089 /* pointer physically in internal ram pointing to object in external ram
13092 __xdata unsigned char * __data p;
13096 /* pointer physically in external ram
13097 pointing to object in internal ram */
13099 __data unsigned char * __xdata p;
13104 pointer physically in code rom pointing to data in xdata space */
13107 unsigned char * __code p;
13111 /* pointer physically in code space pointing to
13112 data in code space */
13114 __code unsigned char * __code p;
13119 physically located in xdata space */
13121 unsigned char * __xdata p;
13126 pointer physically located in default memory space */
13133 the following is a function pointer
13134 \begin_inset LatexCommand index
13135 name "function pointer"
13139 physically located in data space */
13141 char (* __data fp)(void);
13144 \begin_layout Standard
13145 Well you get the idea.
13150 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
13163 The highest order byte of the
13167 pointers contains the data space information.
13168 Assembler support routines are called whenever data is stored or retrieved
13174 These are useful for developing reusable library
13175 \begin_inset LatexCommand index
13181 Explicitly specifying the pointer
13182 \begin_inset LatexCommand index
13187 type will generate the most efficient code.
13190 \begin_layout Subsubsection
13191 Notes on MCS51 memory
13192 \begin_inset LatexCommand index
13193 name "MCS51 memory"
13200 \begin_layout Standard
13201 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
13202 RAM memory which is structured as follows:
13206 - Bytes 00-1F - 32 bytes to hold
13207 up to 4 banks of the registers R0 to R7,
13209 - Bytes 20-2F - 16 bytes to hold
13211 \begin_inset LatexCommand index
13218 - Bytes 30-7F - 80 bytes for general purpose use.
13223 \begin_layout Standard
13224 Additionally some members of the MCS51 family may have up to 128 bytes of
13225 additional, indirectly addressable, internal RAM memory (
13230 \begin_inset LatexCommand index
13231 name "idata (mcs51, ds390 storage class)"
13236 \begin_inset LatexCommand index
13237 name "\\_\\_idata (mcs51, ds390 storage class)"
13242 Furthermore, some chips may have some built in external memory (
13247 \begin_inset LatexCommand index
13248 name "xdata (mcs51, ds390 storage class)"
13253 \begin_inset LatexCommand index
13254 name "\\_\\_xdata (mcs51, ds390 storage class)"
13258 ) which should not be confused with the internal, directly addressable RAM
13264 \begin_inset LatexCommand index
13265 name "data (mcs51, ds390 storage class)"
13270 \begin_inset LatexCommand index
13271 name "\\_\\_data (mcs51, ds390 storage class)"
13276 Sometimes this built in
13280 memory has to be activated before using it (you can probably find this
13281 information on the datasheet of the microcontroller your are using, see
13283 \begin_inset LatexCommand ref
13284 reference "sub:Startup-Code"
13292 \begin_layout Standard
13293 Normally SDCC will only use the first bank
13294 \begin_inset LatexCommand index
13295 name "register bank (mcs51, ds390)"
13299 of registers (register bank 0), but it is possible to specify that other
13300 banks of registers (keyword
13307 \begin_inset LatexCommand index
13308 name "using (mcs51, ds390 register bank)"
13313 \begin_inset LatexCommand index
13314 name "\\_\\_using (mcs51, ds390 register bank)"
13320 ) should be used for example in interrupt
13321 \begin_inset LatexCommand index
13327 \begin_inset LatexCommand index
13328 name "\\_\\_interrupt"
13333 By default, the compiler will place the stack after the last byte of allocated
13334 memory for variables.
13335 For example, if the first 2 banks of registers are used, and only four
13340 variables, it will position the base of the internal stack at address 20
13342 This implies that as the stack
13343 \begin_inset LatexCommand index
13348 grows, it will use up the remaining register banks, and the 16 bytes used
13349 by the 128 bit variables, and 80 bytes for general purpose use.
13350 If any bit variables are used, the data variables will be placed in unused
13351 register banks and after the byte holding the last bit variable.
13352 For example, if register banks 0 and 1 are used, and there are 9 bit variables
13357 variables will be placed starting from address 0x10 to 0x20 and continue
13363 \begin_layout Standard
13373 \begin_inset LatexCommand index
13374 name "-\\/-data-loc <Value>"
13378 to specify the start address of the
13386 \begin_layout Standard
13396 \begin_inset LatexCommand index
13397 name "-\\/-iram-size <Value>"
13401 to specify the size of the total internal RAM (
13415 \begin_layout Standard
13416 By default the 8051 linker will place the stack after the last byte of (i)data
13422 \begin_layout Standard
13432 \begin_inset LatexCommand index
13433 name "-\\/-stack-loc <Value>"
13437 allows you to specify the start of the stack, i.e.
13438 you could start it after any data in the general purpose area.
13439 If your microcontroller has additional indirectly addressable internal
13444 ) you can place the stack on it.
13445 You may also need to use -
13449 \begin_layout Standard
13459 \begin_inset LatexCommand index
13460 name "-\\/-xdata-loc<Value>"
13464 to set the start address of the external RAM (
13472 \begin_layout Standard
13482 \begin_inset LatexCommand index
13483 name "-\\/-xram-size <Value>"
13487 to specify its size.
13488 Same goes for the code memory, using -
13492 \begin_layout Standard
13502 \begin_inset LatexCommand index
13503 name "-\\/-code-loc <Value>"
13511 \begin_layout Standard
13521 \begin_inset LatexCommand index
13522 name "-\\/-code-size <Value>"
13527 If in doubt, don't specify any options and see if the resulting memory
13528 layout is appropriate, then you can adjust it.
13531 \begin_layout Standard
13532 The linker generates two files with memory allocation information.
13533 The first, with extension .map
13534 \begin_inset LatexCommand index
13539 shows all the variables and segments.
13540 The second with extension .mem
13541 \begin_inset LatexCommand index
13546 shows the final memory layout.
13547 The linker will complain either if memory segments overlap, there is not
13548 enough memory, or there is not enough space for stack.
13549 If you get any linking warnings and/or errors related to stack or segments
13550 allocation, take a look at either the .map or .mem files to find out what
13552 The .mem file may even suggest a solution to the problem.
13553 \begin_inset VSpace bigskip
13559 \begin_layout Subsection
13560 Z80/Z180 Storage Class
13561 \begin_inset LatexCommand index
13562 name "Z80!Storage class"
13566 Language Extensions
13569 \begin_layout Subsubsection
13571 \begin_inset LatexCommand index
13577 \begin_inset LatexCommand index
13582 (in/out to 8-bit addresses)
13585 \begin_layout Standard
13587 \begin_inset LatexCommand index
13592 family has separate address spaces for memory and
13602 \begin_inset LatexCommand index
13603 name "I/O memory (Z80, Z180)"
13608 \begin_inset LatexCommand index
13609 name "Z80!I/O memory"
13614 \begin_inset LatexCommand index
13615 name "Z180!I/O memory"
13619 is accessed with special instructions, e.g.:
13622 \begin_layout Verse
13625 sfr at 0x78 IoPort;\InsetSpace ~
13627 /* define a var in I/O space at 78h called IoPort */
13631 \begin_layout Standard
13632 Writing 0x01 to this variable generates the assembly code:
13635 \begin_layout Verse
13655 \begin_layout Subsubsection
13657 \begin_inset LatexCommand index
13663 \begin_inset LatexCommand index
13668 (in/out to 16-bit addresses)
13671 \begin_layout Standard
13676 is used to support 16 bit addresses in I/O memory e.g.:
13679 \begin_layout Verse
13683 \begin_inset LatexCommand index
13689 \begin_inset LatexCommand index
13697 \begin_layout Standard
13698 Writing 0x01 to this variable generates the assembly code:
13701 \begin_layout Verse
13704 01 23 01\InsetSpace ~
13726 \begin_layout Subsubsection
13728 \begin_inset LatexCommand index
13734 \begin_inset LatexCommand index
13739 (in0/out0 to 8 bit addresses on Z180
13740 \begin_inset LatexCommand index
13746 \begin_inset LatexCommand index
13747 name "HD64180 (see Z180)"
13754 \begin_layout Standard
13755 The compiler option -
13759 \begin_layout Standard
13769 \begin_inset LatexCommand index
13770 name "Z180!Options!-\\/-portmode"
13774 =180 (80) and a compiler #pragma\InsetSpace ~
13776 \begin_inset LatexCommand index
13777 name "Z180!Pragmas!\\#pragma portmode"
13781 z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
13791 If you include the file z180.h this will be set automatically.
13792 \begin_inset VSpace bigskip
13798 \begin_layout Subsection
13800 \begin_inset LatexCommand index
13801 name "HC08!Storage class"
13805 Language Extensions
13808 \begin_layout Subsubsection
13810 \begin_inset LatexCommand index
13811 name "data (hc08 storage class)"
13816 \begin_inset LatexCommand index
13817 name "\\_\\_data (hc08 storage class)"
13824 \begin_layout Standard
13825 The data storage class declares a variable that resides in the first 256
13826 bytes of memory (the direct page).
13828 \begin_inset LatexCommand index
13833 is most efficient at accessing variables (especially pointers) stored here.
13836 \begin_layout Subsubsection
13838 \begin_inset LatexCommand index
13839 name "xdata (hc08 storage class)"
13844 \begin_inset LatexCommand index
13845 name "\\_\\_xdata (hc08 storage class)"
13852 \begin_layout Standard
13853 The xdata storage class declares a variable that can reside anywhere in
13855 This is the default if no storage class is specified.
13857 \begin_inset VSpace bigskip
13863 \begin_layout Section
13864 Other SDCC language extensions
13865 \begin_inset LatexCommand index
13866 name "Other SDCC language extensions"
13873 \begin_layout Subsection
13877 \begin_layout Standard
13878 SDCC supports the use of binary constants, such as 0b01100010.
13879 This feature is only enabled when the compiler is invoked using --std-sdccxx.
13882 \begin_layout Standard
13883 \begin_inset VSpace bigskip
13889 \begin_layout Section
13890 Absolute Addressing
13891 \begin_inset LatexCommand index
13892 name "Absolute addressing"
13899 \begin_layout Standard
13900 Data items can be assigned an absolute address with the
13903 \begin_inset LatexCommand index
13909 \begin_inset LatexCommand index
13916 keyword, in addition to a storage class, e.g.:
13919 \begin_layout Verse
13923 \begin_inset LatexCommand index
13924 name "xdata (mcs51, ds390 storage class)"
13929 \begin_inset LatexCommand index
13930 name "\\_\\_xdata (mcs51, ds390 storage class)"
13935 \begin_inset LatexCommand index
13941 \begin_inset LatexCommand index
13946 0x7ffe unsigned int chksum;
13949 \begin_layout Standard
13950 or, better conforming to ISO/IEC 9899 C:
13953 \begin_layout Verse
13956 __xdata __at (0x7ffe) unsigned int chksum;
13959 \begin_layout Standard
13960 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
13961 of the external ram.
13966 reserve any space for variables declared in this way
13967 \begin_inset Marginal
13970 \begin_layout Standard
13979 (they are implemented with an equate in the assembler).
13980 Thus it is left to the programmer to make sure there are no overlaps with
13981 other variables that are declared without the absolute address.
13982 The assembler listing file (.lst
13983 \begin_inset LatexCommand index
13988 ) and the linker output files (.rst
13989 \begin_inset LatexCommand index
13995 \begin_inset LatexCommand index
14000 ) are good places to look for such overlaps.
14003 \begin_layout Standard
14004 If however you provide an initializer
14005 \begin_inset LatexCommand index
14006 name "Variable initialization"
14010 actual memory allocation will take place and overlaps will be detected
14015 \begin_layout Verse
14018 __code __at (0x7ff0) char Id[5] =
14019 \begin_inset Quotes sld
14023 \begin_inset Quotes srd
14029 \begin_layout Standard
14030 In the above example the variable Id will be located from 0x7ff0 to 0x7ff4
14034 \begin_layout Standard
14035 In case of memory mapped I/O devices the keyword
14039 has to be used to tell the compiler that accesses might not be removed:
14042 \begin_layout Verse
14046 \begin_inset LatexCommand index
14052 \begin_inset LatexCommand index
14053 name "xdata (mcs51, ds390 storage class)"
14058 \begin_inset LatexCommand index
14063 (0x8000) unsigned char PORTA_8255;
14066 \begin_layout Standard
14067 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
14072 \begin_inset LatexCommand index
14073 name "Aligned array"
14080 starts at a block (256 byte) boundary
14081 \begin_inset LatexCommand index
14082 name "block boundary"
14087 \begin_inset LatexCommand ref
14088 reference "sub:A-Step-by Assembler Introduction"
14094 Absolute addresses can be specified for variables in all
14095 storage classes, e.g.:
14098 \begin_layout Verse
14102 \begin_inset LatexCommand index
14108 \begin_inset LatexCommand index
14116 \begin_layout Standard
14117 The above example will allocate the variable at offset 0x02 in the bit-addressab
14119 There is no real advantage to assigning absolute addresses to variables
14120 in this manner, unless you want strict control over all the variables allocated.
14121 One possible use would be to write hardware portable code.
14122 For example, if you have a routine that uses one or more of the microcontroller
14123 I/O pins, and such pins are different for two different hardwares, you
14124 can declare the I/O pins in your routine using:
14127 \begin_layout Verse
14131 \begin_inset LatexCommand index
14136 __bit MOSI;\InsetSpace ~
14140 /* master out, slave in */
14142 extern volatile __bit MISO;\InsetSpace ~
14149 extern volatile __bit MCLK;\InsetSpace ~
14158 Output of a byte on a 3-wire serial bus.
14163 If needed adapt polarity of clock,
14164 polarity of data and bit order
14169 unsigned char spi_io(unsigned char out_byte)
14194 MOSI = out_byte & 0x80;
14225 /* _asm nop _endasm; */\InsetSpace ~
14233 /* for slow peripherals */
14285 \begin_layout Standard
14286 Then, someplace in the code for the first hardware you would use
14289 \begin_layout Verse
14293 \begin_inset LatexCommand index
14299 \begin_inset LatexCommand index
14304 (0x80) MOSI;\InsetSpace ~
14308 /* I/O port 0, bit 0 */
14310 __bit __at (0x81) MISO;\InsetSpace ~
14317 __bit __at (0x82) MCLK;\InsetSpace ~
14321 /* I/O port 0, bit 2 */
14324 \begin_layout Standard
14325 Similarly, for the second hardware you would use
14328 \begin_layout Verse
14331 __bit __at (0x83) MOSI;\InsetSpace ~
14335 /* I/O port 0, bit 3 */
14337 __bit __at (0x91) MISO;\InsetSpace ~
14342 I/O port 1, bit 1 */
14345 \begin_inset LatexCommand index
14350 __at (0x92) MCLK;\InsetSpace ~
14354 /* I/O port 1, bit 2 */
14357 \begin_layout Standard
14358 and you can use the same hardware dependent routine without changes, as
14359 for example in a library.
14360 This is somehow similar to sbit, but only one absolute address has to be
14361 specified in the whole project.
14362 \begin_inset VSpace bigskip
14368 \begin_layout Section
14370 \begin_inset LatexCommand index
14376 \begin_inset LatexCommand index
14377 name "function parameter"
14382 \begin_inset LatexCommand index
14383 name "local variables"
14388 \begin_inset LatexCommand label
14389 name "sec:Parameters-and-Local-Variables"
14396 \begin_layout Standard
14397 Automatic (local) variables and parameters to functions can either be placed
14398 on the stack or in data-space.
14399 The default action of the compiler is to place these variables in the internal
14400 RAM (for small model) or external RAM (for medium or large model).
14401 This in fact makes them similar to
14404 \begin_inset LatexCommand index
14411 so by default functions are non-reentrant
14412 \begin_inset LatexCommand index
14422 They can be placed on the stack
14423 \begin_inset LatexCommand index
14434 \begin_layout Standard
14444 \begin_inset LatexCommand index
14445 name "-\\/-stack-auto"
14453 #pragma\InsetSpace ~
14457 \begin_inset LatexCommand index
14458 name "\\#pragma stackauto"
14465 \begin_inset LatexCommand index
14472 keyword in the function declaration, e.g.:
14475 \begin_layout Verse
14478 unsigned char foo(char i) __reentrant
14492 \begin_layout Standard
14493 Since stack space on 8051 is limited, the
14503 \begin_layout Standard
14514 option should be used sparingly.
14515 Note that the reentrant keyword just means that the parameters & local
14516 variables will be allocated to the stack, it
14520 mean that the function is register bank
14521 \begin_inset LatexCommand index
14522 name "register bank (mcs51, ds390)"
14531 \begin_inset LatexCommand index
14532 name "local variables"
14536 can be assigned storage classes and absolute
14537 \begin_inset LatexCommand index
14538 name "Absolute addressing"
14545 \begin_layout Verse
14548 unsigned char foo()
14556 __xdata unsigned char i;
14569 \begin_inset LatexCommand index
14574 (0x31) unsigned char j;
14586 \begin_layout Standard
14587 In the above example the variable
14591 will be allocated in the external ram,
14595 in bit addressable space and
14606 \begin_layout Standard
14617 or when a function is declared as
14621 this should only be done for static variables.
14624 \begin_layout Standard
14626 \begin_inset LatexCommand index
14627 name "function parameter"
14631 however are not allowed any storage class
14632 \begin_inset LatexCommand index
14633 name "Storage class"
14637 , (storage classes for parameters will be ignored), their allocation is
14638 governed by the memory model in use, and the reentrancy options.
14641 \begin_layout Standard
14642 It is however allowed to use bit parameters in reentrant functions and also
14643 non-static local bit variables are supported.
14644 Efficient use is limited to 8 semi-bitregisters in bit space.
14645 They are pushed and popped to stack
14646 \begin_inset LatexCommand index
14651 as a single byte just like the normal registers.
14654 \begin_layout Section
14656 \begin_inset LatexCommand label
14657 name "sub:Overlaying"
14662 \begin_inset LatexCommand index
14670 \begin_layout Standard
14672 \begin_inset LatexCommand index
14677 functions SDCC will try to reduce internal ram space usage by overlaying
14678 parameters and local variables of a function (if possible).
14679 Parameters and local variables
14680 \begin_inset LatexCommand index
14681 name "local variables"
14685 of a function will be allocated to an overlayable segment if the function
14688 no other function calls and the function is non-reentrant and the memory
14690 \begin_inset LatexCommand index
14691 name "Memory model"
14698 If an explicit storage class
14699 \begin_inset LatexCommand index
14700 name "Storage class"
14704 is specified for a local variable, it will NOT be overlaid.
14707 \begin_layout Standard
14708 Note that the compiler (not the linkage editor) makes the decision for overlayin
14710 Functions that are called from an interrupt service routine
14711 \begin_inset Marginal
14714 \begin_layout Standard
14722 should be preceded by a #pragma\InsetSpace ~
14724 \begin_inset LatexCommand index
14725 name "\\#pragma nooverlay"
14729 if they are not reentrant.
14732 \begin_layout Standard
14733 Also note that the compiler does not do any processing of inline assembler
14734 code, so the compiler might incorrectly assign local variables and parameters
14735 of a function into the overlay segment if the inline assembler code calls
14736 other c-functions that might use the overlay.
14737 In that case the #pragma\InsetSpace ~
14738 nooverlay should be used.
14741 \begin_layout Standard
14742 Parameters and local variables of functions that contain 16 or 32 bit multiplica
14744 \begin_inset LatexCommand index
14745 name "Multiplication"
14750 \begin_inset LatexCommand index
14755 will NOT be overlaid since these are implemented using external functions,
14759 \begin_layout Verse
14765 \begin_inset LatexCommand index
14766 name "\\#pragma nooverlay"
14772 void set_error(unsigned char errcd)
14789 some_isr () __interrupt
14790 \begin_inset LatexCommand index
14821 \begin_layout Standard
14822 In the above example the parameter
14830 would be assigned to the overlayable segment if the #pragma\InsetSpace ~
14832 not present, this could cause unpredictable runtime behavior when called
14833 from an interrupt service routine.
14834 The #pragma\InsetSpace ~
14835 nooverlay ensures that the parameters and local variables for
14836 the function are NOT overlaid.
14837 \begin_inset VSpace bigskip
14843 \begin_layout Section
14844 Interrupt Service Routines
14845 \begin_inset LatexCommand label
14846 name "sub:Interrupt-Service-Routines"
14853 \begin_layout Subsection
14854 General Information
14857 \begin_layout Standard
14870 outines to be coded in C, with some extended keywords.
14873 \begin_layout Verse
14876 void timer_isr (void) __interrupt (1) __using (1)
14890 \begin_layout Standard
14891 The optional number following the
14894 \begin_inset LatexCommand index
14900 \begin_inset LatexCommand index
14901 name "\\_\\_interrupt"
14907 keyword is the interrupt number this routine will service.
14908 When present, the compiler will insert a call to this routine in the interrupt
14910 \begin_inset LatexCommand index
14911 name "interrupt vector table"
14915 for the interrupt number specified.
14916 If you have multiple source files in your project, interrupt service routines
14917 can be present in any of them, but a prototype of the isr MUST be present
14918 or included in the file that contains the function
14923 The optional (8051 specific) keyword
14926 \begin_inset LatexCommand index
14927 name "using (mcs51, ds390 register bank)"
14932 \begin_inset LatexCommand index
14933 name "\\_\\_using (mcs51, ds390 register bank)"
14939 can be used to tell the compiler to use the specified register bank when
14940 generating code for this function.
14943 Interrupt service routines open the door for some very interesting bugs:
14946 \begin_layout Subsubsection
14947 \begin_inset LatexCommand label
14948 name "sub:Common-interrupt-pitfall-volatile"
14952 Common interrupt pitfall: variable not declared
14957 \begin_layout Standard
14958 If an interrupt service routine changes variables which are accessed by
14959 other functions these variables have to be declared
14964 \begin_inset LatexCommand index
14971 \begin_inset LatexCommand url
14972 target "http://en.wikipedia.org/wiki/Volatile_variable"
14979 \begin_layout Subsubsection
14980 \begin_inset LatexCommand label
14981 name "sub:Common-interrupt-pitfall-non-atomic"
14985 Common interrupt pitfall:
14990 \begin_layout Standard
14991 If the access to these variables is not
14994 \begin_inset LatexCommand index
15002 the processor needs more than one instruction for the access and could
15003 be interrupted while accessing the variable) the interrupt must be disabled
15004 during the access to avoid inconsistent data.
15007 Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
15008 and should be protected by disabling interrupts.
15009 You're not automatically on the safe side if you use 8 bit variables though.
15010 We need an example here: f.e.
15011 on the 8051 the harmless looking
15012 \begin_inset Quotes srd
15022 \begin_inset Quotes sld
15031 \begin_inset Quotes srd
15041 \begin_inset Quotes sld
15044 from within an interrupt routine might get lost if the interrupt occurs
15047 \begin_inset Quotes sld
15052 counter\InsetSpace ~
15057 \begin_inset Quotes srd
15060 is not atomic on the 8051 even if
15064 is located in data memory.
15066 Bugs like these are hard to reproduce and can
15067 cause a lot of trouble.
15071 \begin_layout Subsubsection
15072 \begin_inset LatexCommand label
15073 name "sub:Common-interrupt-pitfall-stack-overflow"
15077 Common interrupt pitfall:
15082 \begin_layout Standard
15083 The return address and the registers used in the interrupt service routine
15084 are saved on the stack
15085 \begin_inset LatexCommand index
15090 so there must be sufficient stack space.
15091 If there isn't variables or registers (or even the return address itself)
15098 \begin_inset LatexCommand index
15099 name "stack overflow"
15103 is most likely to happen if the interrupt occurs during the
15104 \begin_inset Quotes sld
15108 \begin_inset Quotes srd
15111 subroutine when the stack is already in use for f.e.
15112 many return addresses.
15115 \begin_layout Subsubsection
15116 \begin_inset LatexCommand label
15117 name "sub:Common-interrupt-pitfall-non-reentrant"
15121 Common interrupt pitfall:
15123 use of non-reentrant functions
15126 \begin_layout Standard
15127 A special note here, int (16 bit) and long (32 bit) integer division
15128 \begin_inset LatexCommand index
15134 \begin_inset LatexCommand index
15135 name "Multiplication"
15140 \begin_inset LatexCommand index
15146 \begin_inset LatexCommand index
15147 name "Floating point support"
15151 operations are implemented using external support routines.
15152 If an interrupt service routine needs to do any of these operations then
15153 the support routines (as mentioned in a following section) will have to
15154 be recompiled using the
15160 \begin_layout Standard
15170 \begin_inset LatexCommand index
15171 name "-\\/-stack-auto"
15177 option and the source file will need to be compiled using the
15183 \begin_layout Standard
15195 \begin_inset LatexCommand index
15196 name "-\\/-int-long-reent"
15203 Note, the type promotion
15204 \begin_inset LatexCommand index
15205 name "type promotion"
15209 required by ANSI C can cause 16 bit routines to be used
15210 \begin_inset Marginal
15213 \begin_layout Standard
15222 without the programmer being aware of it.
15227 (unsigned char)(tail-1)
15232 within the if clause in section
15233 \begin_inset LatexCommand ref
15234 reference "sub:A-Step-by Assembler Introduction"
15241 \begin_layout Standard
15242 Calling other functions from an interrupt service routine is not recommended,
15243 avoid it if possible.
15244 Note that when some function is called from an interrupt service routine
15245 it should be preceded by a #pragma\InsetSpace ~
15247 \begin_inset LatexCommand index
15248 name "\\#pragma nooverlay"
15252 if it is not reentrant.
15253 Furthermore nonreentrant functions should not be called from the main program
15254 while the interrupt service routine might be active.
15255 They also must not be called from low priority interrupt service routines
15256 while a high priority interrupt service routine might be active.
15257 You could use semaphores or make the function
15261 if all parameters are passed in registers.
15264 \begin_inset LatexCommand ref
15265 reference "sub:Overlaying"
15270 about Overlaying and section
15271 \begin_inset LatexCommand ref
15272 reference "sub:Functions-using-private-banks"
15277 about Functions using private register banks.
15278 \begin_inset VSpace bigskip
15284 \begin_layout Subsection
15285 MCS51/DS390 Interrupt Service Routines
15288 \begin_layout Standard
15290 \begin_inset LatexCommand index
15295 numbers and the corresponding address & descriptions for the Standard 8051/8052
15297 SDCC will automatically adjust the
15298 \begin_inset LatexCommand index
15299 name "interrupt vector table"
15303 to the maximum interrupt number specified.
15308 \begin_layout Standard
15310 \begin_inset Tabular
15311 <lyxtabular version="3" rows="9" columns="3">
15313 <column alignment="center" valignment="top" leftline="true" width="0in">
15314 <column alignment="left" valignment="top" leftline="true" width="0in">
15315 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
15316 <row topline="true" bottomline="true">
15317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15320 \begin_layout Standard
15326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15329 \begin_layout Standard
15335 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15338 \begin_layout Standard
15345 <row topline="true">
15346 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15349 \begin_layout Standard
15355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15358 \begin_layout Standard
15364 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15367 \begin_layout Standard
15374 <row topline="true">
15375 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15378 \begin_layout Standard
15384 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15387 \begin_layout Standard
15393 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15396 \begin_layout Standard
15403 <row topline="true">
15404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15407 \begin_layout Standard
15413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15416 \begin_layout Standard
15422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15425 \begin_layout Standard
15432 <row topline="true">
15433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15436 \begin_layout Standard
15442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15445 \begin_layout Standard
15451 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15454 \begin_layout Standard
15461 <row topline="true">
15462 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15465 \begin_layout Standard
15471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15474 \begin_layout Standard
15480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15483 \begin_layout Standard
15490 <row topline="true">
15491 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15494 \begin_layout Standard
15500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15503 \begin_layout Standard
15509 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15512 \begin_layout Standard
15519 <row topline="true">
15520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15523 \begin_layout Standard
15529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15532 \begin_layout Standard
15538 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15541 \begin_layout Standard
15548 <row topline="true" bottomline="true">
15549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15552 \begin_layout Standard
15558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15561 \begin_layout Standard
15567 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15570 \begin_layout Standard
15586 \begin_layout Standard
15587 If the interrupt service routine is defined without
15590 \begin_inset LatexCommand index
15591 name "using (mcs51, ds390 register bank)"
15596 \begin_inset LatexCommand index
15597 name "\\_\\_using (mcs51, ds390 register bank)"
15603 a register bank or with register bank 0 (
15607 0), the compiler will save the registers used by itself on the stack upon
15608 entry and restore them at exit, however if such an interrupt service routine
15609 calls another function then the entire register bank will be saved on the
15611 This scheme may be advantageous for small interrupt service routines which
15612 have low register usage.
15615 \begin_layout Standard
15616 If the interrupt service routine is defined to be using a specific register
15621 & psw are saved and restored, if such an interrupt service routine calls
15622 another function (using another register bank) then the entire register
15623 bank of the called function will be saved on the stack
15624 \begin_inset LatexCommand index
15630 This scheme is recommended for larger interrupt service routines.
15631 \begin_inset VSpace bigskip
15637 \begin_layout Subsection
15639 \begin_inset LatexCommand index
15644 Interrupt Service Routines
15647 \begin_layout Standard
15648 Since the number of interrupts
15649 \begin_inset LatexCommand index
15650 name "HC08!interrupt"
15654 available is chip specific and the interrupt vector table always ends at
15655 the last byte of memory, the interrupt numbers corresponds to the interrupt
15656 vectors in reverse order of address.
15657 For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
15658 2 will use the interrupt vector at 0xfffa, and so on.
15659 However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
15660 this way; instead see section
15661 \begin_inset LatexCommand ref
15662 reference "sub:Startup-Code"
15666 for details on customizing startup.
15667 \begin_inset VSpace bigskip
15673 \begin_layout Subsection
15674 Z80 Interrupt Service Routines
15677 \begin_layout Standard
15679 \begin_inset LatexCommand index
15684 uses several different methods for determining the correct interrupt
15685 \begin_inset LatexCommand index
15686 name "Z80!interrupt"
15690 vector depending on the hardware implementation.
15691 Therefore, SDCC ignores the optional interrupt number and does not attempt
15692 to generate an interrupt vector table.
15695 \begin_layout Standard
15696 By default, SDCC generates code for a maskable interrupt, which uses a RETI
15697 instruction to return from the interrupt.
15698 To write an interrupt handler for the non-maskable interrupt, which needs
15699 a RETN instruction instead, add the
15706 \begin_layout Verse
15709 void nmi_isr (void) critical interrupt
15723 \begin_layout Standard
15724 However if you need to create a non-interruptable interrupt service routine
15725 you would also require the
15730 To distinguish between this and an nmi_isr you must provide an interrupt
15732 \begin_inset VSpace bigskip
15738 \begin_layout Section
15739 Enabling and Disabling Interrupts
15742 \begin_layout Subsection
15743 Critical Functions and Critical Statements
15746 \begin_layout Standard
15747 A special keyword may be associated with a block or a function declaring
15753 SDCC will generate code to disable all interrupts
15754 \begin_inset LatexCommand index
15759 upon entry to a critical function and restore the interrupt enable to the
15760 previous state before returning.
15761 Nesting critical functions will need one additional byte on the stack
15762 \begin_inset LatexCommand index
15770 \begin_layout Verse
15773 int foo () __critical
15774 \begin_inset LatexCommand index
15780 \begin_inset LatexCommand index
15781 name "\\_\\_critical"
15806 \begin_layout Standard
15807 The critical attribute maybe used with other attributes like
15817 may also be used to disable interrupts more locally:
15820 \begin_layout Verse
15826 \begin_layout Standard
15827 More than one statement could have been included in the block.
15830 \begin_layout Subsection
15831 Enabling and Disabling Interrupts directly
15834 \begin_layout Standard
15836 \begin_inset LatexCommand index
15841 can also be disabled and enabled directly (8051):
15844 \begin_layout Verse
15847 EA = 0;\InsetSpace ~
15873 \begin_layout Verse
15909 \begin_layout Verse
15912 EA = 1;\InsetSpace ~
15941 \begin_layout Verse
15980 \begin_layout Standard
15981 On other architectures which have separate opcodes for enabling and disabling
15982 interrupts you might want to make use of defines with inline assembly
15983 \begin_inset LatexCommand index
15984 name "Assembler routines"
15989 \begin_inset LatexCommand index
15990 name "HC08!interrupt"
15997 \begin_layout Verse
16001 \begin_inset LatexCommand index
16011 \begin_inset LatexCommand index
16019 \begin_layout Verse
16022 #define SEI _asm\InsetSpace ~
16029 \begin_layout Verse
16035 \begin_layout Standard
16036 Note: it is sometimes sufficient to disable only a specific interrupt source
16038 a timer or serial interrupt by manipulating an
16041 \begin_inset LatexCommand index
16042 name "interrupt mask"
16052 \begin_layout Standard
16053 Usually the time during which interrupts are disabled should be kept as
16055 This minimizes both
16060 \begin_inset LatexCommand index
16061 name "interrupt latency"
16065 (the time between the occurrence of the interrupt and the execution of
16066 the first code in the interrupt routine) and
16071 \begin_inset LatexCommand index
16072 name "interrupt jitter"
16076 (the difference between the shortest and the longest interrupt latency).
16077 These really are something different, f.e.
16078 a serial interrupt has to be served before its buffer overruns so it cares
16079 for the maximum interrupt latency, whereas it does not care about jitter.
16080 On a loudspeaker driven via a digital to analog converter which is fed
16081 by an interrupt a latency of a few milliseconds might be tolerable, whereas
16082 a much smaller jitter will be very audible.
16085 \begin_layout Standard
16086 You can reenable interrupts within an interrupt routine and on some architecture
16087 s you can make use of two (or more) levels of
16089 interrupt priorities
16092 \begin_inset LatexCommand index
16093 name "interrupt priority"
16098 On some architectures which don't support interrupt priorities these can
16099 be implemented by manipulating the interrupt mask and reenabling interrupts
16100 within the interrupt routine.
16101 Check there is sufficient space on the stack
16102 \begin_inset LatexCommand index
16107 and don't add complexity unless you have to.
16111 \begin_layout Subsection
16113 \begin_inset LatexCommand index
16118 locking (mcs51/ds390)
16121 \begin_layout Standard
16122 Some architectures (mcs51/ds390) have an atomic
16123 \begin_inset LatexCommand index
16128 bit test and clear instruction.
16129 These type of instructions are typically used in preemptive multitasking
16130 systems, where a routine f.e.
16131 claims the use of a data structure ('acquires a lock
16132 \begin_inset LatexCommand index
16137 on it'), makes some modifications and then releases the lock when the data
16138 structure is consistent again.
16139 The instruction may also be used if interrupt and non-interrupt code have
16140 to compete for a resource.
16141 With the atomic bit test and clear instruction interrupts
16142 \begin_inset LatexCommand index
16147 don't have to be disabled for the locking operation.
16151 \begin_layout Standard
16152 SDCC generates this instruction if the source follows this pattern:
16155 \begin_layout Verse
16159 \begin_inset LatexCommand index
16164 bit resource_is_free;
16168 if (resource_is_free)
16178 resource_is_free=0;
16191 resource_is_free=1;
16198 \begin_layout Standard
16199 Note, mcs51 and ds390 support only an atomic
16200 \begin_inset LatexCommand index
16209 instruction (as opposed to atomic bit test and
16214 \begin_layout Section
16215 Functions using private register banks
16216 \begin_inset LatexCommand label
16217 name "sub:Functions-using-private-banks"
16224 \begin_layout Standard
16225 Some architectures have support for quickly changing register sets.
16226 SDCC supports this feature with the
16229 \begin_inset LatexCommand index
16230 name "using (mcs51, ds390 register bank)"
16235 \begin_inset LatexCommand index
16236 name "\\_\\_using (mcs51, ds390 register bank)"
16242 attribute (which tells the compiler to use a register bank
16243 \begin_inset LatexCommand index
16244 name "register bank (mcs51, ds390)"
16248 other than the default bank zero).
16249 It should only be applied to
16252 \begin_inset LatexCommand index
16259 functions (see footnote below).
16260 This will in most circumstances make the generated ISR code more efficient
16261 since it will not have to save registers on the stack.
16264 \begin_layout Standard
16269 attribute will have no effect on the generated code for a
16273 function (but may occasionally be useful anyway
16277 \begin_layout Standard
16278 possible exception: if a function is called ONLY from 'interrupt' functions
16279 using a particular bank, it can be declared with the same 'using' attribute
16280 as the calling 'interrupt' functions.
16281 For instance, if you have several ISRs using bank one, and all of them
16282 call memcpy(), it might make sense to create a specialized version of memcpy()
16283 'using 1', since this would prevent the ISR from having to save bank zero
16284 to the stack on entry and switch to bank zero before calling the function
16293 (pending: Note, nowadays the
16297 attribute has an effect on
16301 the generated code for a
16312 \begin_layout Standard
16317 function using a non-zero bank will assume that it can trash that register
16318 bank, and will not save it.
16319 Since high-priority interrupts
16320 \begin_inset LatexCommand index
16326 \begin_inset LatexCommand index
16327 name "interrupt priority"
16331 can interrupt low-priority ones on the 8051 and friends, this means that
16332 if a high-priority ISR
16336 a particular bank occurs while processing a low-priority ISR
16340 the same bank, terrible and bad things can happen.
16341 To prevent this, no single register bank should be
16345 by both a high priority and a low priority ISR.
16346 This is probably most easily done by having all high priority ISRs use
16347 one bank and all low priority ISRs use another.
16348 If you have an ISR which can change priority at runtime, you're on your
16349 own: I suggest using the default bank zero and taking the small performance
16353 \begin_layout Standard
16354 It is most efficient if your ISR calls no other functions.
16355 If your ISR must call other functions, it is most efficient if those functions
16356 use the same bank as the ISR (see note 1 below); the next best is if the
16357 called functions use bank zero.
16358 It is very inefficient to call a function using a different, non-zero bank
16361 \begin_inset VSpace bigskip
16367 \begin_layout Section
16369 \begin_inset LatexCommand label
16370 name "sub:Startup-Code"
16375 \begin_inset LatexCommand index
16376 name "Startup code"
16383 \begin_layout Subsection
16384 MCS51/DS390 Startup Code
16387 \begin_layout Standard
16388 The compiler triggers the linker to link certain initialization modules
16389 from the runtime library
16390 \begin_inset LatexCommand index
16391 name "Runtime library"
16395 called crt<something>.
16396 Only the necessary ones are linked, for instance crtxstack.asm (GSINIT1,
16397 GSINIT5) is not linked unless the -
16403 \begin_layout Standard
16414 -xstack option is used.
16415 These modules are highly entangled by the use of special segments/areas,
16416 but a common layout is shown below:
16419 \begin_layout Verse
16427 \begin_layout Verse
16451 ljmp __sdcc_gsinit_startup
16454 \begin_layout Verse
16462 \begin_layout Verse
16474 .area GSINIT0 (CODE)
16476 __sdcc_gsinit_startup::
16486 mov sp,#__start__stack - 1
16489 \begin_layout Verse
16497 \begin_layout Verse
16509 .area GSINIT1 (CODE)
16511 __sdcc_init_xstack::
16513 ; Need to initialize in GSINIT1 in
16514 case the user's __sdcc_external_startup uses the xstack.
16524 mov __XPAGE,#(__start__x
16535 mov _spx,#__start__xstack
16538 \begin_layout Verse
16546 \begin_layout Verse
16558 .area GSINIT2 (CODE)
16568 lcall __sdcc_external_startup
16588 jz __sdcc_init_data
16599 __sdcc_program_startup
16604 \begin_layout Verse
16612 \begin_layout Verse
16624 .area GSINIT3 (CODE)
16677 mov r2,#((l_XINIT+255) >> 8)
16708 __XPAGE,#(s_XISEG >> 8)
16710 00001$:\InsetSpace ~
16774 00002$:\InsetSpace ~
16801 \begin_layout Verse
16809 \begin_layout Verse
16821 .area GSINIT4 (CODE)
16823 __mcs51_genRAMCLEAR::
16845 00004$:\InsetSpace ~
16859 ; _mcs51_genRAMCLEAR() end
16862 \begin_layout Verse
16870 \begin_layout Verse
16882 .area GSINIT4 (CODE)
16884 __mcs51_genXRAMCLEAR::
16945 mov __XPAGE,#(s_PSEG >> 8)
16957 00005$:\InsetSpace ~
17032 mov r1,#((l_XSEG + 255) >> 8)
17054 00007$:\InsetSpace ~
17091 \begin_layout Verse
17099 \begin_layout Verse
17111 .area GSINIT5 (CODE)
17113 ; Need to initialize in GSINIT5 because __mcs51_genXINIT
17116 ; and __mcs51_genRAMCLEAR modifies _spx.
17126 mov __XPAGE,#(__start__x
17137 mov _spx,#__start__xstack
17140 \begin_layout Verse
17145 (application modules)
17148 \begin_layout Verse
17160 .area GSINIT (CODE)
17163 \begin_layout Verse
17171 \begin_layout Verse
17183 .area GSFINAL (CODE)
17193 ljmp __sdcc_program_startup
17195 ;---------------------------------
17196 -----------------------
17200 ;--------------------------------------------------
17223 __sdcc_program_startup:
17236 return from main will lock up
17249 \begin_layout Standard
17250 One of these modules (crtstart.asm) contains a call to the C routine
17252 _sdcc_external_startup()
17253 \begin_inset LatexCommand index
17254 name "\\_sdcc\\_external\\_startup()"
17260 at the start of the CODE area.
17261 This routine is also in the runtime library
17262 \begin_inset LatexCommand index
17263 name "Runtime library"
17267 and returns 0 by default.
17268 If this routine returns a non-zero value, the static & global variable
17269 initialization will be skipped and the function main will be invoked.
17270 Otherwise static & global variables will be initialized before the function
17274 _sdcc_external_startup()
17276 routine to your program to override the default if you need to setup hardware
17277 or perform some other critical operation prior to static & global variable
17279 \begin_inset LatexCommand index
17280 name "Variable initialization"
17285 On some mcs51 variants xdata
17286 \begin_inset LatexCommand index
17287 name "xdata (mcs51, ds390 storage class)"
17291 memory has to be explicitly enabled before it can be accessed or if the
17293 \begin_inset LatexCommand index
17298 needs to be disabled, this is the place to do it.
17299 The startup code clears all internal data memory, 256 bytes by default,
17300 but from 0 to n-1 if
17306 \begin_layout Standard
17316 \begin_inset LatexCommand index
17317 name "-\\/-iram-size <Value>"
17324 (recommended for Chipcon CC1010).
17327 \begin_layout Standard
17328 See also the compiler options
17334 \begin_layout Standard
17350 \begin_inset LatexCommand index
17351 name "-\\/-no-xinit-opt"
17361 \begin_layout Standard
17373 \begin_inset LatexCommand index
17374 name "-\\/-main-return"
17379 \begin_inset LatexCommand ref
17380 reference "sub:MCS51-variants"
17384 about MCS51-variants.
17389 \begin_layout Standard
17390 While these initialization modules are meant as generic startup code there
17391 might be the need for customization.
17392 Let's assume the return value of
17394 _sdcc_external_startup()
17400 should not be checked (or
17402 _sdcc_external_startup()
17404 should not be called at all).
17405 The recommended way would be to copy
17411 \begin_inset LatexCommand url
17412 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/device/lib/mcs51/crtstart.asm"
17416 ) into the source directory, adapt it there, then assemble it with
17422 \begin_layout Standard
17423 \begin_inset Quotes sld
17427 \begin_inset Quotes srd
17430 are the assembler options used in
17431 \begin_inset LatexCommand url
17432 target "http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/lib/mcs51/Makefile.in?view=markup "
17443 and when linking your project explicitly specify
17448 As a bonus a listing of the relocated object file
17455 \begin_layout Standard
17456 \begin_inset VSpace bigskip
17462 \begin_layout Subsection
17466 \begin_layout Standard
17468 \begin_inset LatexCommand index
17473 startup code follows the same scheme as the MCS51 startup code.
17474 \begin_inset VSpace bigskip
17480 \begin_layout Subsection
17484 \begin_layout Standard
17486 \begin_inset LatexCommand index
17491 the startup code is inserted by linking with crt0.o which is generated from
17492 sdcc/device/lib/z80/crt0.s.
17493 If you need a different startup code you can use the compiler option
17502 \begin_layout Standard
17517 \begin_inset LatexCommand index
17518 name "-\\/-no-std-crt0"
17522 and provide your own crt0.o.
17524 \begin_inset VSpace bigskip
17530 \begin_layout Section
17531 Inline Assembler Code
17532 \begin_inset LatexCommand index
17533 name "Assembler routines"
17540 \begin_layout Subsection
17541 A Step by Step Introduction
17542 \begin_inset LatexCommand label
17543 name "sub:A-Step-by Assembler Introduction"
17550 \begin_layout Standard
17551 Starting from a small snippet of c-code this example shows for the MCS51
17552 how to use inline assembly, access variables, a function parameter and
17553 an array in xdata memory.
17554 The example uses an MCS51 here but is easily adapted for other architectures.
17555 This is a buffer routine which should be optimized:
17558 \begin_layout Verse
17562 unsigned char __far
17563 \begin_inset LatexCommand index
17564 name "far (storage class)"
17569 \begin_inset LatexCommand index
17570 name "\\_\\_far (storage class)"
17575 \begin_inset LatexCommand index
17581 \begin_inset LatexCommand index
17586 (0x7f00) buf[0x100];
17587 \begin_inset LatexCommand index
17588 name "Aligned array"
17594 unsigned char head, tail;\InsetSpace ~
17612 \begin_inset LatexCommand index
17665 \begin_inset LatexCommand ref
17666 reference "sub:Common-interrupt-pitfall-volatile"
17684 void to_buffer( unsigned char c )
17692 if( head != (unsigned char)(tail-1)
17705 \begin_inset LatexCommand index
17706 name "promotion to signed int"
17711 \begin_inset LatexCommand index
17712 name "type promotion"
17717 \begin_inset Marginal
17720 \begin_layout Standard
17739 buf[ head++ ] = c;\InsetSpace ~
17755 /* access to a 256 byte aligned array */
17760 \begin_layout Standard
17761 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
17762 then a corresponding buffer.asm file is generated.
17763 We define a new function
17767 in file buffer.c in which we cut and paste the generated code, removing
17768 unwanted comments and some ':'.
17770 \begin_inset Quotes sld
17778 \begin_inset Quotes srd
17782 \begin_inset Quotes sld
17790 \begin_inset Quotes srd
17797 \begin_layout Standard
17798 Note, that the single underscore form (_asm and _endasm) are not C99-compatible,
17799 and for C-99 compatibility, the double-underscore form (__asm and __endasm)
17801 The latter is also used in the library functions.
17806 to the beginning and the end of the function body:
17809 \begin_layout Verse
17813 /* With a cut and paste from the .asm file, we have something to start with.
17819 function is not yet OK! (registers aren't saved) */
17821 void to_buffer_asm(
17831 \begin_inset LatexCommand index
17837 \begin_inset LatexCommand index
17852 ;buffer.c if( head != (unsigned char)(tail-1) ) \InsetSpace ~
17864 \begin_inset LatexCommand index
17865 name "promotion to signed int"
17870 \begin_inset LatexCommand index
17871 name "type promotion"
17924 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
17925 \begin_inset LatexCommand index
17926 name "Aligned array"
17992 \begin_inset LatexCommand index
17998 \begin_inset LatexCommand index
17999 name "\\_\\_endasm"
18008 \begin_layout Standard
18009 The new file buffer.c should compile with only one warning about the unreferenced
18010 function argument 'c'.
18011 Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
18012 (1) and finally have:
18015 \begin_layout Verse
18019 unsigned char __far __at(0x7f00) buf[0x100];
18021 unsigned char head, tail;
18032 void to_buffer( unsigned char c )
18041 head != (unsigned char)(tail-1) )
18070 c; // to avoid warning: unreferenced function argument
18077 \begin_inset LatexCommand index
18083 \begin_inset LatexCommand index
18098 ; save used registers here.
18109 ; If we were still using r2,r3 we would have to push them here.
18112 ; if( head != (unsigned char)(tail-1) )
18156 could do an ANL a,#0x0f here to use a smaller buffer (see below)
18192 a,dpl \InsetSpace ~
18199 ; dpl holds lower byte of function argument
18211 dpl,_head \InsetSpace ~
18214 ; buf is 0x100 byte aligned so head can be used directly
18257 ; we could do an ANL _head,#0x0f here to use a
18258 smaller buffer (see above)
18270 ; restore used registers here
18277 \begin_inset LatexCommand index
18283 \begin_inset LatexCommand index
18284 name "\\_\\_endasm"
18295 \begin_layout Standard
18296 The inline assembler code can contain any valid code understood by the assembler
18297 , this includes any assembler directives and comment lines.
18298 The assembler does not like some characters like ':' or ''' in comments.
18299 You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
18300 \begin_inset LatexCommand index
18301 name "asXXXX (as-gbz80, as-hc08, asx8051, as-z80)"
18306 \begin_inset LatexCommand index
18307 name "Assembler documentation"
18312 \begin_inset LatexCommand url
18313 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html"
18321 \begin_layout Standard
18322 The compiler does not do any validation of the code within the
18325 \begin_inset LatexCommand index
18331 \begin_inset LatexCommand index
18340 \begin_inset LatexCommand index
18346 \begin_inset LatexCommand index
18347 name "\\_\\_endasm"
18356 Specifically it will not know which registers are used and thus register
18358 \begin_inset LatexCommand index
18363 has to be done manually.
18367 \begin_layout Standard
18368 It is recommended that each assembly instruction (including labels) be placed
18369 in a separate line (as the example shows).
18374 \begin_layout Standard
18386 \begin_inset LatexCommand index
18387 name "-\\/-peep-asm"
18393 command line option is used, the inline assembler code will be passed through
18394 the peephole optimizer
18395 \begin_inset LatexCommand index
18396 name "Peephole optimizer"
18401 There are only a few (if any) cases where this option makes sense, it might
18402 cause some unexpected changes in the inline assembler code.
18403 Please go through the peephole optimizer rules defined in file
18407 before using this option.
18410 \begin_layout Subsection
18412 \begin_inset LatexCommand label
18413 name "sub:Naked-Functions"
18418 \begin_inset LatexCommand index
18419 name "Naked functions"
18426 \begin_layout Standard
18427 A special keyword may be associated with a function declaring it as
18430 \begin_inset LatexCommand index
18436 \begin_inset LatexCommand index
18448 function modifier attribute prevents the compiler from generating prologue
18449 \begin_inset LatexCommand index
18450 name "function prologue"
18455 \begin_inset LatexCommand index
18456 name "function epilogue"
18460 code for that function.
18461 This means that the user is entirely responsible for such things as saving
18462 any registers that may need to be preserved, selecting the proper register
18463 bank, generating the
18467 instruction at the end, etc.
18468 Practically, this means that the contents of the function must be written
18469 in inline assembler.
18470 This is particularly useful for interrupt functions, which can have a large
18471 (and often unnecessary) prologue/epilogue.
18472 For example, compare the code generated by these two functions:
18475 \begin_layout Verse
18479 \begin_inset LatexCommand index
18484 data unsigned char counter;
18488 void simpleInterrupt(void) __interrupt
18489 \begin_inset LatexCommand index
18495 \begin_inset LatexCommand index
18496 name "\\_\\_interrupt"
18514 void nakedInterrupt(void) __interrupt (2) __naked
18523 \begin_inset LatexCommand index
18529 \begin_inset LatexCommand index
18547 _counter ; does not change flags, no need to save psw
18560 include ret or reti in _naked function.
18567 \begin_inset LatexCommand index
18573 \begin_inset LatexCommand index
18574 name "\\_\\_endasm"
18583 \begin_layout Standard
18584 For an 8051 target, the generated simpleInterrupt looks like:
18587 \begin_layout Verse
18600 example, recent versions of SDCC generate
18612 code for simpleInterrupt() and nakedInterrupt()!
18753 \begin_layout Standard
18754 whereas nakedInterrupt looks like:
18757 \begin_layout Verse
18770 _counter ; does not change flags, no need to save psw
18789 MUST explicitly include ret or reti in _naked function
18792 \begin_layout Standard
18793 The related directive #pragma exclude
18794 \begin_inset LatexCommand index
18795 name "\\#pragma exclude"
18799 allows a more fine grained control over pushing & popping
18800 \begin_inset LatexCommand index
18808 \begin_layout Standard
18809 While there is nothing preventing you from writing C code inside a
18813 function, there are many ways to shoot yourself in the foot doing this,
18814 and it is recommended that you stick to inline assembler.
18817 \begin_layout Subsection
18818 Use of Labels within Inline Assembler
18821 \begin_layout Standard
18822 SDCC allows the use of in-line assembler with a few restrictions regarding
18824 All labels defined within inline assembler code have to be of the form
18829 where nnnnn is a number less than 100 (which implies a limit of utmost
18830 100 inline assembler labels
18841 \begin_layout Standard
18842 This is a slightly more stringent rule than absolutely necessary, but stays
18843 always on the safe side.
18844 Labels in the form of nnnnn$ are local labels in the assembler, locality
18845 of which is confined within two labels of the standard form.
18846 The compiler uses the same form for labels within a function (but starting
18847 from nnnnn=00100); and places always a standard label at the beginning
18848 of a function, thus limiting the locality of labels within the scope of
18850 So, if the inline assembler part would be embedded into C-code, an improperly
18851 placed non-local label in the assembler would break up the reference space
18852 for labels created by the compiler for the C-code, leading to an assembling
18856 \begin_layout Standard
18857 The numeric part of local labels does not need to have 5 digits (although
18858 this is the form of labels output by the compiler), any valid integer will
18860 Please refer to the assemblers documentation for further details.
18868 \begin_layout Verse
18872 \begin_inset LatexCommand index
18878 \begin_inset LatexCommand index
18909 \begin_inset LatexCommand index
18915 \begin_inset LatexCommand index
18916 name "\\_\\_endasm"
18923 \begin_layout Standard
18924 Inline assembler code cannot reference any C-labels, however it can reference
18926 \begin_inset LatexCommand index
18931 defined by the inline assembler, e.g.:
18934 \begin_layout Verse
18957 ; some assembler code
18978 /* some more c code */
18980 clabel:\InsetSpace ~
18982 /* inline assembler cannot reference this
18987 \begin_layout Standard
18992 is translated by the compiler into a local label, so the locality of labels
18993 within the function is not broken.
19010 0003$: ;label (can be referenced by inline assembler only)
19017 \begin_inset LatexCommand index
19023 \begin_inset LatexCommand index
19024 name "\\_\\_endasm"
19034 /* some more c code */
19039 \begin_layout Standard
19040 In other words inline assembly code can access labels defined in inline
19041 assembly within the scope of the function.
19042 The same goes the other way, i.e.
19043 labels defines in inline assembly can not be accessed by C statements.
19046 \begin_layout Section
19047 Interfacing with Assembler Code
19048 \begin_inset LatexCommand index
19049 name "Assembler routines"
19056 \begin_layout Subsection
19057 Global Registers used for Parameter Passing
19058 \begin_inset LatexCommand index
19059 name "Parameter passing"
19066 \begin_layout Standard
19067 The compiler always uses the global registers
19070 \begin_inset LatexCommand index
19071 name "DPTR, DPH, DPL"
19076 \begin_inset LatexCommand index
19082 \begin_inset LatexCommand index
19083 name "B (mcs51, ds390 register)"
19092 \begin_inset LatexCommand index
19093 name "ACC (mcs51, ds390 register)"
19099 to pass the first (non-bit) parameter to a function, and also to pass the
19101 \begin_inset LatexCommand index
19102 name "return value"
19106 of function; according to the following scheme: one byte return value in
19111 , two byte value in
19120 three byte values (generic pointers) in
19132 , and four byte values in
19150 \begin_inset LatexCommand index
19151 name "generic pointer"
19155 contain type of accessed memory in
19176 \begin_inset Note Note
19179 \begin_layout Standard
19180 This might not be the case of certain memory models (medium???)
19188 \begin_layout Standard
19189 The second parameter onwards is either allocated on the stack (for reentrant
19194 \begin_layout Standard
19203 -stack-auto is used) or in data/xdata memory (depending on the memory model).
19206 \begin_layout Standard
19207 Bit parameters are passed in a virtual register called 'bits' in bit-addressable
19208 space for reentrant functions or allocated directly in bit memory otherwise.
19211 \begin_layout Standard
19212 Functions (with two or more parameters or bit parameters) that are called
19213 through function pointers
19214 \begin_inset LatexCommand index
19215 name "function pointers"
19219 must therefor be reentrant so the compiler knows how to pass the parameters.
19222 \begin_layout Subsection
19226 \begin_layout Standard
19227 Unless the called function is declared as
19232 \begin_inset LatexCommand index
19241 \begin_layout Standard
19251 \begin_inset LatexCommand index
19252 name "-\\/-callee-saves"
19260 \begin_layout Standard
19269 -all-callee-saves command line option or the corresponding callee_saves
19270 pragma are used, the caller will save the registers (
19274 ) around the call, so the called function can destroy they content freely.
19277 \begin_layout Standard
19278 If the called function is not declared as
19282 , the caller will swap register banks around the call, if caller and callee
19283 use different register banks (having them defined by the
19291 \begin_layout Standard
19292 The called function can also use
19308 observing that they are used for parameter/return value passing.
19311 \begin_layout Subsection
19312 Assembler Routine (non-reentrant)
19315 \begin_layout Standard
19316 In the following example
19317 \begin_inset LatexCommand index
19323 \begin_inset LatexCommand index
19324 name "Assembler routines (non-reentrant)"
19328 the function c_func calls an assembler routine asm_func, which takes two
19330 \begin_inset LatexCommand index
19331 name "function parameter"
19338 \begin_layout Verse
19341 extern int asm_func(unsigned char, unsigned char);
19345 int c_func (unsigned char
19346 i, unsigned char j)
19354 return asm_func(i,j);
19368 return c_func(10,9);
19373 \begin_layout Standard
19374 The corresponding assembler function is:
19377 \begin_layout Verse
19380 .globl _asm_func_PARM_2
19482 \begin_inset LatexCommand index
19483 name "DPTR, DPH, DPL"
19500 \begin_layout Standard
19501 The parameter naming convention is _<function_name>_PARM_<n>, where n is
19502 the parameter number starting from 1, and counting from the left.
19503 The first parameter is passed in
19519 according to the description above.
19520 The variable name for the second parameter will be _<function_name>_PARM_2.
19525 ble the assembler routine with the following command:
19532 asx8051 -losg asmfunc.asm
19539 Then compile and link the assembler routine to the C source file with the
19547 sdcc cfunc.c asmfunc.rel
19550 \begin_layout Subsection
19551 Assembler Routine (reentrant)
19554 \begin_layout Standard
19556 \begin_inset LatexCommand index
19562 \begin_inset LatexCommand index
19563 name "Assembler routines (reentrant)"
19567 the second parameter
19568 \begin_inset LatexCommand index
19569 name "function parameter"
19573 onwards will be passed on the stack, the parameters are pushed from right
19575 before the call the second leftmost parameter will be on the top of the
19576 stack (the leftmost parameter is passed in registers).
19577 Here is an example:
19580 \begin_layout Verse
19583 extern int asm_func(unsigned char, unsigned char, unsigned char) reentrant;
19588 c_func (unsigned char i, unsigned char j, unsigned char k) reentrant
19597 return asm_func(i,j,k);
19611 return c_func(10,9,8);
19616 \begin_layout Standard
19617 The corresponding (unoptimized) assembler routine is:
19620 \begin_layout Verse
19640 _bp,sp\InsetSpace ~
19646 ;stack contains: _bp, return
19647 address, second parameter, third parameter
19671 a,#0xfd\InsetSpace ~
19677 pointer to the second parameter
19701 a,#0xfc\InsetSpace ~
19707 to the rightmost parameter
19748 result (= sum of all three parameters)
19763 ;return value goes into dptr
19797 \begin_layout Standard
19798 The compiling and linking procedure remains the same, however note the extra
19799 entry & exit linkage required for the assembler code, _bp is the stack
19800 frame pointer and is used to compute the offset into the stack for parameters
19801 and local variables.
19802 \begin_inset VSpace bigskip
19808 \begin_layout Section
19810 \begin_inset LatexCommand index
19811 name "int (16 bit)"
19816 \begin_inset LatexCommand index
19817 name "long (32 bit)"
19824 \begin_layout Standard
19825 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
19826 multiplication and modulus operations are implemented by support routines.
19827 These support routines are all developed in ANSI-C to facilitate porting
19828 to other MCUs, although some model specific assembler optimizations are
19830 The following files contain the described routines, all of them can be
19831 found in <installdir>/share/sdcc/lib.
19836 \begin_layout Standard
19838 \begin_inset Tabular
19839 <lyxtabular version="3" rows="11" columns="2">
19841 <column alignment="left" valignment="top" leftline="true" width="0">
19842 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
19843 <row topline="true" bottomline="true">
19844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19847 \begin_layout Standard
19855 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19858 \begin_layout Standard
19867 <row topline="true">
19868 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19871 \begin_layout Standard
19877 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19880 \begin_layout Standard
19881 16 bit multiplication
19887 <row topline="true">
19888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19891 \begin_layout Standard
19897 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19900 \begin_layout Standard
19901 signed 16 bit division (calls _divuint)
19907 <row topline="true">
19908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19911 \begin_layout Standard
19917 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19920 \begin_layout Standard
19921 unsigned 16 bit division
19927 <row topline="true">
19928 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19931 \begin_layout Standard
19937 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19940 \begin_layout Standard
19941 signed 16 bit modulus (calls _moduint)
19947 <row topline="true">
19948 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19951 \begin_layout Standard
19957 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19960 \begin_layout Standard
19961 unsigned 16 bit modulus
19967 <row topline="true">
19968 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19971 \begin_layout Standard
19977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19980 \begin_layout Standard
19981 32 bit multiplication
19987 <row topline="true">
19988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19991 \begin_layout Standard
19997 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20000 \begin_layout Standard
20001 signed 32 division (calls _divulong)
20007 <row topline="true">
20008 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20011 \begin_layout Standard
20017 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20020 \begin_layout Standard
20021 unsigned 32 division
20027 <row topline="true">
20028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20031 \begin_layout Standard
20037 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20040 \begin_layout Standard
20041 signed 32 bit modulus (calls _modulong)
20047 <row topline="true" bottomline="true">
20048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20051 \begin_layout Standard
20057 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20060 \begin_layout Standard
20061 unsigned 32 bit modulus
20076 \begin_layout Standard
20077 Since they are compiled as
20082 \begin_inset LatexCommand index
20088 \begin_inset LatexCommand index
20093 service routines should not do any of the above operations.
20094 If this is unavoidable then the above routines will need to be compiled
20101 \begin_layout Standard
20111 \begin_inset LatexCommand index
20112 name "-\\/-stack-auto"
20118 option, after which the source program will have to be compiled with
20124 \begin_layout Standard
20134 \begin_inset LatexCommand index
20135 name "-\\/-int-long-reent"
20142 Notice that you don't have to call these routines directly.
20143 The compiler will use them automatically every time an integer operation
20147 \begin_layout Section
20148 Floating Point Support
20149 \begin_inset LatexCommand index
20150 name "Floating point support"
20157 \begin_layout Standard
20158 SDCC supports IEEE (single precision 4 bytes) floating point numbers.
20159 The floating point support routines are derived from gcc's floatlib.c and
20160 consist of the following routines:
20165 \begin_layout Standard
20169 \begin_inset Tabular
20170 <lyxtabular version="3" rows="17" columns="2">
20172 <column alignment="left" valignment="top" leftline="true" width="0">
20173 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
20174 <row topline="true" bottomline="true">
20175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20178 \begin_layout Standard
20193 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20196 \begin_layout Standard
20203 <row topline="true">
20204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20207 \begin_layout Standard
20222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20225 \begin_layout Standard
20235 add floating point numbers
20241 <row topline="true">
20242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20245 \begin_layout Standard
20260 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20263 \begin_layout Standard
20273 subtract floating point numbers
20279 <row topline="true">
20280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20283 \begin_layout Standard
20298 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20301 \begin_layout Standard
20311 divide floating point numbers
20317 <row topline="true">
20318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20321 \begin_layout Standard
20336 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20339 \begin_layout Standard
20349 multiply floating point numbers
20355 <row topline="true">
20356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20359 \begin_layout Standard
20374 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20377 \begin_layout Standard
20387 convert floating point to unsigned char
20393 <row topline="true">
20394 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20397 \begin_layout Standard
20412 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20415 \begin_layout Standard
20425 convert floating point to signed char
20431 <row topline="true">
20432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20435 \begin_layout Standard
20450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20453 \begin_layout Standard
20463 convert floating point to unsigned int
20469 <row topline="true">
20470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20473 \begin_layout Standard
20488 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20491 \begin_layout Standard
20501 convert floating point to signed int
20507 <row topline="true">
20508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20511 \begin_layout Standard
20534 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20537 \begin_layout Standard
20547 convert floating point to unsigned long
20553 <row topline="true">
20554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20557 \begin_layout Standard
20572 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20575 \begin_layout Standard
20585 convert floating point to signed long
20591 <row topline="true">
20592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20595 \begin_layout Standard
20610 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20613 \begin_layout Standard
20623 convert unsigned char to floating point
20629 <row topline="true">
20630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20633 \begin_layout Standard
20648 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20651 \begin_layout Standard
20661 convert char to floating point number
20667 <row topline="true">
20668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20671 \begin_layout Standard
20686 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20689 \begin_layout Standard
20699 convert unsigned int to floating point
20705 <row topline="true">
20706 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20709 \begin_layout Standard
20724 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20727 \begin_layout Standard
20737 convert int to floating point numbers
20743 <row topline="true">
20744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20747 \begin_layout Standard
20762 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20765 \begin_layout Standard
20775 convert unsigned long to floating point number
20781 <row topline="true" bottomline="true">
20782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20785 \begin_layout Standard
20800 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20803 \begin_layout Standard
20813 convert long to floating point number
20828 \begin_layout Standard
20829 These support routines are developed in ANSI-C so there is room for space
20830 and speed improvement
20834 \begin_layout Standard
20835 These floating point routines (
20839 sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
20846 Note if all these routines are used simultaneously the data space might
20848 For serious floating point usage the large model might be needed.
20849 Also notice that you don't have to call this routines directly.
20850 The compiler will use them automatically every time a floating point operation
20852 \begin_inset VSpace bigskip
20858 \begin_layout Section
20860 \begin_inset LatexCommand index
20868 \begin_layout Standard
20871 <pending: this is messy and incomplete - a little more information is in
20872 sdcc/doc/libdoc.txt
20877 \begin_layout Subsection
20878 Compiler support routines (_gptrget, _mulint etc.)
20881 \begin_layout Subsection
20882 Stdclib functions (puts, printf, strcat etc.)
20885 \begin_layout Subsubsection
20889 \begin_layout Paragraph
20890 getchar(), putchar()
20893 \begin_layout Standard
20894 \begin_inset LatexCommand index
20899 As usual on embedded systems you have to provide your own
20902 \begin_inset LatexCommand index
20912 \begin_inset LatexCommand index
20920 SDCC does not know whether the system connects to a serial line with or
20921 without handshake, LCD, keyboard or other device.
20935 You'll find examples for serial routines f.e.
20936 in sdcc/device/lib.
20937 For the mcs51 this minimalistic polling
20941 routine might be a start:
20944 \begin_layout Verse
20947 void putchar (char c) {
20953 while (!TI)\InsetSpace ~
20956 /* assumes UART is initialized */
20984 \begin_layout Paragraph
20988 \begin_layout Standard
20992 \begin_inset LatexCommand index
21003 does not support float (except on ds390).
21004 To enable this recompile it with the option
21010 \begin_layout Standard
21020 \begin_inset LatexCommand index
21021 name "USE\\_FLOATS"
21027 on the command line.
21034 \begin_layout Standard
21044 \begin_inset LatexCommand index
21045 name "-\\/-model-large"
21051 for the mcs51 port, since this uses a lot of memory.
21054 \begin_layout Standard
21055 If you're short on code memory you might want to use
21058 \begin_inset LatexCommand index
21059 name "printf\\_small()"
21074 For the mcs51 there additionally are assembly versions
21077 \begin_inset LatexCommand index
21078 name "printf\\_tiny() (mcs51)"
21084 (subset of printf using less than 270 bytes) and
21087 \begin_inset LatexCommand index
21088 name "printf\\_fast() (mcs51)"
21097 \begin_inset LatexCommand index
21098 name "printf\\_fast\\_f() (mcs51)"
21104 (floating-point aware version of printf_fast) which should fit the requirements
21105 of many embedded systems (printf_fast() can be customized by unsetting
21110 support long variables and field widths).
21111 Be sure to use only one of these printf options within a project.
21116 \begin_layout Standard
21117 Feature matrix of different
21124 \begin_layout Standard
21125 \begin_inset Tabular
21126 <lyxtabular version="3" rows="14" columns="7">
21127 <features islongtable="true">
21128 <column alignment="left" valignment="middle" leftline="true" width="14col%">
21129 <column alignment="center" valignment="top" leftline="true" width="0">
21130 <column alignment="center" valignment="top" leftline="true" width="12col%">
21131 <column alignment="center" valignment="top" leftline="true" width="10col%">
21132 <column alignment="center" valignment="top" leftline="true" width="0">
21133 <column alignment="center" valignment="top" leftline="true" rightline="true" width="12col%">
21134 <column alignment="center" valignment="top" rightline="true" width="0">
21135 <row topline="true" bottomline="true" endhead="true">
21136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21139 \begin_layout Standard
21148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21151 \begin_layout Standard
21153 \begin_inset LatexCommand index
21163 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21166 \begin_layout Standard
21174 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21177 \begin_layout Standard
21183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21186 \begin_layout Standard
21192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21195 \begin_layout Standard
21201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21204 \begin_layout Standard
21211 <row topline="true" endhead="true">
21212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21215 \begin_layout Standard
21221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21224 \begin_layout Standard
21232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21235 \begin_layout Standard
21243 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21246 \begin_layout Standard
21254 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21257 \begin_layout Standard
21265 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21268 \begin_layout Standard
21276 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21279 \begin_layout Standard
21288 <row topline="true" endhead="true">
21289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21292 \begin_layout Standard
21293 \begin_inset Quotes sld
21297 \begin_inset Quotes srd
21303 \begin_layout Standard
21309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21312 \begin_layout Standard
21318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21321 \begin_layout Standard
21327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21330 \begin_layout Standard
21336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21339 \begin_layout Standard
21345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21348 \begin_layout Standard
21354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21357 \begin_layout Standard
21364 <row topline="true" endhead="true">
21365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21368 \begin_layout Standard
21372 \begin_layout Standard
21378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21381 \begin_layout Standard
21387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21390 \begin_layout Standard
21396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21399 \begin_layout Standard
21400 0.45k / 0.47k (+ _ltoa)
21405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21408 \begin_layout Standard
21414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21417 \begin_layout Standard
21423 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21426 \begin_layout Standard
21433 <row topline="true">
21434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21437 \begin_layout Standard
21443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21446 \begin_layout Standard
21456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21459 \begin_layout Standard
21506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21509 \begin_layout Standard
21548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21551 \begin_layout Standard
21557 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21560 \begin_layout Standard
21566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21569 \begin_layout Standard
21576 <row topline="true">
21577 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21580 \begin_layout Standard
21581 long (32 bit) support
21586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21589 \begin_layout Standard
21595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21598 \begin_layout Standard
21604 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21607 \begin_layout Standard
21613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21616 \begin_layout Standard
21622 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21625 \begin_layout Standard
21640 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21643 \begin_layout Standard
21650 <row topline="true">
21651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21654 \begin_layout Standard
21655 byte arguments on stack
21660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21663 \begin_layout Standard
21669 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21672 \begin_layout Standard
21678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21681 \begin_layout Standard
21687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21690 \begin_layout Standard
21696 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21699 \begin_layout Standard
21705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21708 \begin_layout Standard
21715 <row topline="true">
21716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21719 \begin_layout Standard
21721 \begin_inset LatexCommand index
21722 name "Floating point support"
21731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21734 \begin_layout Standard
21740 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21743 \begin_layout Standard
21749 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21752 \begin_layout Standard
21758 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21761 \begin_layout Standard
21767 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21770 \begin_layout Standard
21775 \begin_layout Standard
21776 Range limited to +/- 4294967040, precision limited to 8 digits past decimal
21786 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21789 \begin_layout Standard
21796 <row topline="true">
21797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21800 \begin_layout Standard
21801 float formats %e %g
21806 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21809 \begin_layout Standard
21815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21818 \begin_layout Standard
21824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21827 \begin_layout Standard
21833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21836 \begin_layout Standard
21842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21845 \begin_layout Standard
21851 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21854 \begin_layout Standard
21861 <row topline="true" bottomline="true">
21862 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21865 \begin_layout Standard
21871 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21874 \begin_layout Standard
21880 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21883 \begin_layout Standard
21889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21892 \begin_layout Standard
21898 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21901 \begin_layout Standard
21907 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21910 \begin_layout Standard
21916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21919 \begin_layout Standard
21926 <row bottomline="true">
21927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21930 \begin_layout Standard
21935 \begin_layout Standard
21936 Execution time of printf("%s%c%s%c%c%c", "Hello", ' ', "World", '!', '
21940 n'); standard 8051 @ 22.1184 MHz, empty putchar()
21948 \begin_layout Standard
21954 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21957 \begin_layout Standard
21963 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21966 \begin_layout Standard
21972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21975 \begin_layout Standard
21981 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21984 \begin_layout Standard
21990 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21993 \begin_layout Standard
21999 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22002 \begin_layout Standard
22009 <row bottomline="true">
22010 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22013 \begin_layout Standard
22018 \begin_layout Standard
22019 Execution time of printf("%d", -12345); standard 8051 @ 22.1184 MHz, empty
22028 \begin_layout Standard
22034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22037 \begin_layout Standard
22043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22046 \begin_layout Standard
22052 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22055 \begin_layout Standard
22061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22064 \begin_layout Standard
22070 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22073 \begin_layout Standard
22079 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22082 \begin_layout Standard
22087 \begin_layout Standard
22088 printf_tiny integer speed is data dependent, worst case is 0.33 ms
22099 <row bottomline="true">
22100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22103 \begin_layout Standard
22108 \begin_layout Standard
22109 Execution time of printf("%ld", -123456789); standard 8051 @ 22.1184 MHz,
22118 \begin_layout Standard
22124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22127 \begin_layout Standard
22133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22136 \begin_layout Standard
22142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22145 \begin_layout Standard
22151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22154 \begin_layout Standard
22160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22163 \begin_layout Standard
22169 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22172 \begin_layout Standard
22179 <row bottomline="true">
22180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22183 \begin_layout Standard
22188 \begin_layout Standard
22189 Execution time of printf("%.3f", -12345.678); standard 8051 @ 22.1184 MHz,
22198 \begin_layout Standard
22204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22207 \begin_layout Standard
22213 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22216 \begin_layout Standard
22222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22225 \begin_layout Standard
22231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22234 \begin_layout Standard
22240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22243 \begin_layout Standard
22249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22252 \begin_layout Standard
22266 \begin_layout Subsubsection
22268 \begin_inset LatexCommand index
22276 \begin_layout Standard
22277 As of SDCC 2.6.2 you no longer need to call an initialization routine before
22278 using dynamic memory allocation
22279 \begin_inset LatexCommand index
22280 name "dynamic memory allocation (malloc)"
22285 \begin_inset LatexCommand index
22286 name "heap (malloc)"
22290 space of 1024 bytes is provided for malloc to allocate memory from.
22291 If you need a different heap size you need to recompile _heap.c with the
22292 required size defined in HEAP_SIZE.
22293 It is recommended to make a copy of this file into your project directory
22294 and compile it there with:
22297 \begin_layout Verse
22300 sdcc -c _heap.c -D HEAD_SIZE=2048
22303 \begin_layout Standard
22304 And then link it with:
22307 \begin_layout Verse
22310 sdcc main.rel _heap.rel
22313 \begin_layout Subsection
22314 Math functions (sinf, powf, sqrtf etc.)
22317 \begin_layout Subsubsection
22321 \begin_layout Standard
22322 See definitions in file <math.h>.
22325 \begin_layout Subsection
22329 \begin_layout Standard
22331 \begin_inset LatexCommand index
22336 included in SDCC should have a license at least as liberal as the GNU Lesser
22337 General Public License
22338 \begin_inset LatexCommand index
22339 name "GNU Lesser General Public License, LGPL"
22350 \begin_layout Standard
22351 \begin_inset Note Note
22354 \begin_layout Standard
22355 license statements for the libraries are missing.
22356 sdcc/device/lib/ser_ir.c
22359 \begin_layout Standard
22361 come with a GPL (as opposed to LGPL) License - this will not be liberal
22362 enough for many embedded programmers.
22370 \begin_layout Standard
22371 If you have ported some library or want to share experience about some code
22373 falls into any of these categories Busses (I
22374 \begin_inset Formula $^{\textrm{2}}$
22377 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
22378 cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
22379 Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
22380 \begin_inset LatexCommand url
22381 target "http://sourceforge.net/mail/?group_id=599"
22386 would certainly like to hear about it.
22389 \begin_layout Standard
22390 Programmers coding for embedded systems are not especially famous for being
22391 enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
22392 e these references are very valuable.
22393 Let's help to create a climate where information is shared.
22394 \begin_inset VSpace bigskip
22400 \begin_layout Section
22404 \begin_layout Subsection
22405 MCS51 Memory Models
22406 \begin_inset LatexCommand index
22407 name "Memory model"
22412 \begin_inset LatexCommand index
22413 name "MCS51 memory model"
22420 \begin_layout Subsubsection
22421 Small, Medium and Large
22424 \begin_layout Standard
22425 SDCC allows three memory models for MCS51 code,
22434 Modules compiled with different memory models should
22438 be combined together or the results would be unpredictable.
22439 The library routines supplied with the compiler are compiled as small,
22441 The compiled library modules are contained in separate directories as small,
22442 medium and large so that you can link to the appropriate set.
22445 \begin_layout Standard
22446 When the medium or large model is used all variables declared without a
22447 storage class will be allocated into the external ram, this includes all
22448 parameters and local variables (for non-reentrant
22449 \begin_inset LatexCommand index
22455 When the small model is used variables without storage class are allocated
22456 in the internal ram.
22459 \begin_layout Standard
22460 Judicious usage of the processor specific storage classes
22461 \begin_inset LatexCommand index
22462 name "Storage class"
22466 and the 'reentrant' function type will yield much more efficient code,
22467 than using the large model.
22468 Several optimizations are disabled when the program is compiled using the
22469 large model, it is therefore recommended that the small model be used unless
22470 absolutely required.
22473 \begin_layout Subsubsection
22475 \begin_inset LatexCommand label
22476 name "sub:External-Stack"
22481 \begin_inset LatexCommand index
22487 \begin_inset LatexCommand index
22488 name "External stack (mcs51)"
22495 \begin_layout Standard
22496 The external stack (-
22500 \begin_layout Standard
22510 \begin_inset LatexCommand index
22515 ) is located in pdata
22516 \begin_inset LatexCommand index
22517 name "pdata (mcs51, ds390 storage class)"
22521 memory (usually at the start of the external ram segment) and uses all
22522 unused space in pdata (max.
22528 \begin_layout Standard
22537 -xstack option is used to compile the program, the parameters and local
22539 \begin_inset LatexCommand index
22540 name "local variables"
22544 of all reentrant functions are allocated in this area.
22545 This option is provided for programs with large stack space requirements.
22546 When used with the -
22550 \begin_layout Standard
22560 \begin_inset LatexCommand index
22561 name "-\\/-stack-auto"
22565 option, all parameters and local variables are allocated on the external
22566 stack (note: support libraries will need to be recompiled with the same
22568 There is a predefined target in the library makefile).
22571 \begin_layout Standard
22572 The compiler outputs the higher order address byte of the external ram segment
22574 \begin_inset LatexCommand index
22575 name "P2 (mcs51 sfr)"
22580 \begin_inset LatexCommand ref
22581 reference "sub:MCS51-variants"
22585 ), therefore when using the External Stack option, this port
22589 be used by the application program.
22592 \begin_layout Subsection
22594 \begin_inset LatexCommand index
22595 name "Memory model"
22600 \begin_inset LatexCommand index
22601 name "DS390 memory model"
22608 \begin_layout Standard
22609 The only model supported is Flat 24
22610 \begin_inset LatexCommand index
22611 name "Flat 24 (DS390 memory model)"
22616 This generates code for the 24 bit contiguous addressing mode of the Dallas
22618 In this mode, up to four meg of external RAM or code space can be directly
22620 See the data sheets at www.dalsemi.com for further information on this part.
22625 that the compiler does not generate any code to place the processor into
22626 24 bitmode (although
22630 in the ds390 libraries will do that for you).
22636 \begin_inset LatexCommand index
22637 name "Tinibios (DS390)"
22641 , the boot loader or similar code must ensure that the processor is in 24
22642 bit contiguous addressing mode before calling the SDCC startup code.
22653 \begin_layout Standard
22664 option, variables will by default be placed into the XDATA segment.
22669 Segments may be placed anywhere in the 4 meg address space using the usual
22674 \begin_layout Standard
22684 Note that if any segments are located above 64K, the -r flag must be passed
22685 to the linker to generate the proper segment relocations, and the Intel
22686 HEX output format must be used.
22687 The -r flag can be passed to the linker by using the option
22691 on the SDCC command line.
22692 However, currently the linker can not handle code segments > 64k.
22695 \begin_layout Section
22697 \begin_inset LatexCommand label
22703 \begin_inset LatexCommand index
22711 \begin_layout Standard
22712 Pragmas are used to turn on and/or off certain compiler options.
22713 Some of them are closely related to corresponding command-line options
22715 \begin_inset LatexCommand vref
22716 reference "sec:Command-Line-Options"
22722 Pragmas should be placed before and/or after a function, placing pragmas
22723 inside a function body could have unpredictable results.
22728 following #pragma directives:
22731 \begin_layout Itemize
22737 \begin_inset LatexCommand index
22738 name "\\#pragma save"
22742 - this will save most current options to the save/restore stack.
22743 See #pragma\InsetSpace ~
22747 \begin_layout Itemize
22753 \begin_inset LatexCommand index
22754 name "\\#pragma restore"
22758 - will restore saved options from the last save.
22759 saves & restores can be nested.
22760 SDCC uses a save/restore stack: save pushes current options to the stack,
22761 restore pulls current options from the stack.
22762 See #pragma\InsetSpace ~
22768 \begin_layout Itemize
22774 \begin_inset LatexCommand index
22775 name "\\#pragma callee\\_saves"
22780 \begin_inset LatexCommand index
22781 name "function prologue"
22785 function1[,function2[,function3...]]
22786 \begin_inset LatexCommand label
22787 name "ite:callee_saves-function1[,function2[,function3...]]--"
22791 - The compiler by default uses a caller saves convention for register saving
22792 across function calls, however this can cause unnecessary register pushing
22794 \begin_inset LatexCommand index
22799 when calling small functions from larger functions.
22800 This option can be used to switch off the register saving convention for
22801 the function names specified.
22802 The compiler will not save registers when calling these functions, extra
22803 code need to be manually inserted at the entry and exit for these functions
22804 to save and restore the registers used by these functions, this can SUBSTANTIAL
22805 LY reduce code and improve run time performance of the generated code.
22806 In the future the compiler (with inter procedural analysis) may be able
22807 to determine the appropriate scheme to use for each function call.
22812 \begin_layout Standard
22821 -callee-saves command line option is used (see page
22822 \begin_inset LatexCommand vpageref
22823 reference "lyx:--callee-saves-function1[,function2][,function3]..."
22827 ), the function names specified in #pragma\InsetSpace ~
22829 \begin_inset LatexCommand index
22830 name "\\#pragma callee\\_saves"
22834 is appended to the list of functions specified in the command line.
22837 \begin_layout Itemize
22843 \begin_inset LatexCommand index
22844 name "\\#pragma exclude"
22848 none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
22849 of pairs of push/pop
22850 \begin_inset LatexCommand index
22860 \begin_inset LatexCommand index
22874 The directive should be placed immediately before the ISR function definition
22875 and it affects ALL ISR functions following it.
22876 To enable the normal register saving for ISR functions use #pragma\InsetSpace ~
22877 exclude\InsetSpace ~
22879 \begin_inset LatexCommand index
22880 name "\\#pragma exclude"
22885 See also the related keyword _naked
22886 \begin_inset LatexCommand index
22892 \begin_inset LatexCommand index
22900 \begin_layout Itemize
22906 \begin_inset LatexCommand index
22912 \begin_inset LatexCommand index
22913 name "\\#pragma less\\_pedantic"
22918 \begin_inset LatexCommand label
22919 name "ite:less_pedantic"
22923 - the compiler will not warn you anymore for obvious mistakes, you're on
22925 See also the command line option -
22929 \begin_layout Standard
22939 \begin_inset LatexCommand vpageref
22940 reference "lyx:--less-pedantic"
22947 More specifically, the following warnings will be disabled:
22949 comparison is always [true/false] due to limited range of data type
22953 overflow in implicit constant conversion
22955 (158); [the (in)famous]
22957 conditional flow changed by optimizer: so said EVELYN the modified DOG
22961 function '[function name]' must return value
22966 Furthermore, warnings of less importance (of PEDANTIC and INFO warning
22967 level) are disabled, too, namely:
22970 \begin_inset Note Note
22973 \begin_layout Standard
22974 dunno what comes here - this warning appears to be unused altogether
22983 [left/right] shifting more than size of object changed to zero
22991 integer overflow in expression
22995 unmatched #pragma save and #pragma restore
22999 comparison of 'signed char' with 'unsigned char' requires promotion to int
23003 ISO C90 does not support flexible array members
23007 extended stack by [number] bytes for compiler temp(s) :in function '[function\InsetSpace ~
23011 \begin_inset Note Note
23014 \begin_layout Standard
23015 appears to be always blank - what was supposed to be here?
23024 function '[function name]', # edges [number] , # nodes [number] , cyclomatic
23025 complexity [number]
23030 \begin_layout Itemize
23036 \begin_inset LatexCommand index
23037 name "\\#pragma disable\\_warning"
23041 - the compiler will not warn you anymore about warning number <nnnn>.
23044 \begin_layout Itemize
23050 \begin_inset LatexCommand index
23051 name "\\#pragma nogcse"
23055 - will stop global common subexpression elimination.
23058 \begin_layout Itemize
23064 \begin_inset LatexCommand index
23065 name "\\#pragma noinduction"
23069 - will stop loop induction optimizations.
23072 \begin_layout Itemize
23078 \begin_inset LatexCommand index
23079 name "\\#pragma noinvariant"
23083 - will not do loop invariant optimizations.
23084 For more details see Loop Invariants in section
23085 \begin_inset LatexCommand ref
23086 reference "sub:Loop-Optimizations"
23093 \begin_layout Itemize
23099 \begin_inset LatexCommand index
23100 name "\\#pragma noiv"
23104 - Do not generate interrupt
23105 \begin_inset LatexCommand index
23111 \begin_inset LatexCommand index
23112 name "interrupt vector table"
23116 entries for all ISR functions defined after the pragma.
23117 This is useful in cases where the interrupt vector table must be defined
23118 manually, or when there is a secondary, manually defined interrupt vector
23120 for the autovector feature of the Cypress EZ-USB FX2).
23121 More elegantly this can be achieved by omitting the optional interrupt
23122 number after the interrupt keyword, see section
23123 \begin_inset LatexCommand ref
23124 reference "sub:Interrupt-Service-Routines"
23132 \begin_layout Itemize
23138 \begin_inset LatexCommand index
23139 name "\\#pragma nojtbound"
23143 - will not generate code for boundary value checking, when switch statements
23144 are turned into jump-tables (dangerous).
23145 For more details see section
23146 \begin_inset LatexCommand ref
23147 reference "sub:'switch'-Statements"
23154 \begin_layout Itemize
23160 \begin_inset LatexCommand index
23161 name "\\#pragma noloopreverse"
23165 - Will not do loop reversal optimization
23168 \begin_layout Itemize
23174 \begin_inset LatexCommand index
23175 name "\\#pragma nooverlay"
23179 - the compiler will not overlay the parameters and local variables of a
23183 \begin_layout Itemize
23189 \begin_inset LatexCommand index
23190 name "\\#pragma stackauto"
23198 \begin_layout Standard
23208 \begin_inset LatexCommand index
23209 name "-\\/-stack-auto"
23214 \begin_inset LatexCommand ref
23215 reference "sec:Parameters-and-Local-Variables"
23219 Parameters and Local Variables.
23222 \begin_layout Itemize
23228 \begin_inset LatexCommand index
23229 name "\\#pragma opt\\_code\\_speed"
23233 - The compiler will optimize code generation towards fast code, possibly
23234 at the expense of code size.
23235 Currently this has little effect.
23238 \begin_layout Itemize
23244 \begin_inset LatexCommand index
23245 name "\\#pragma opt\\_code\\_size"
23249 - The compiler will optimize code generation towards compact code, possibly
23250 at the expense of code speed.
23251 Currently this has little effect.
23254 \begin_layout Itemize
23260 \begin_inset LatexCommand index
23261 name "\\#pragma opt\\_code\\_balanced"
23265 - The compiler will attempt to generate code that is both compact and fast,
23266 as long as meeting one goal is not a detriment to the other (this is the
23271 \begin_layout Itemize
23277 \begin_inset LatexCommand index
23278 name "\\#pragma std\\_sdcc89"
23282 - Generally follow the C89 standard, but allow SDCC features that conflict
23283 with the standard (default).
23286 \begin_layout Itemize
23292 \begin_inset LatexCommand index
23293 name "\\#pragma std\\_c89"
23297 - Follow the C89 standard and disable SDCC features that conflict with the
23301 \begin_layout Itemize
23307 \begin_inset LatexCommand index
23308 name "\\#pragma std\\_sdcc99"
23312 - Generally follow the C99 standard, but allow SDCC features that conflict
23313 with the standard (incomplete support).
23316 \begin_layout Itemize
23322 \begin_inset LatexCommand index
23323 name "\\#pragma std\\_c99"
23327 - Follow the C99 standard and disable SDCC features that conflict with the
23328 standard (incomplete support).
23331 \begin_layout Itemize
23337 \begin_inset LatexCommand index
23338 name "\\#pragma codeseg"
23342 - Use this name (max.
23343 8 characters) for the code segment.
23348 \begin_layout Standard
23360 \begin_layout Itemize
23366 \begin_inset LatexCommand index
23367 name "\\#pragma constseg"
23371 - Use this name (max.
23372 8 characters) for the const segment.
23377 \begin_layout Standard
23389 \begin_layout Standard
23390 The preprocessor SDCPP
23391 \begin_inset LatexCommand index
23392 name "sdcpp (preprocessor)"
23396 supports the following #pragma directives:
23399 \begin_layout Itemize
23402 pedantic_parse_number
23405 \begin_inset LatexCommand index
23411 \begin_inset LatexCommand index
23412 name "\\#pragma pedantic\\_parse\\_number"
23417 \begin_inset LatexCommand label
23418 name "ite:pedantic_parse_number"
23422 - Pedantic parse numbers so that situations like 0xfe-LO_B(3) are parsed
23423 properly and the macro LO_B(3) gets expanded.
23429 \begin_layout Standard
23438 -pedantic-parse-number command line option
23439 \begin_inset LatexCommand vpageref
23440 reference "lyx:-pedantic-parse-number"
23447 Below is an example on how to use this pragma.
23450 Note: this functionality is not in conformance with standard!
23453 \begin_layout Verse
23456 #pragma pedantic_parse_number +
23457 \begin_inset LatexCommand index
23458 name "\\#pragma pedantic\\_parse\\_number"
23466 #define LO_B(x) ((x) & 0xff)
23470 unsigned char foo(void)
23477 unsigned char c=0xfe-LO_B(3)
23492 \begin_layout Itemize
23498 \begin_inset LatexCommand index
23499 name "\\#pragma preproc\\_asm"
23503 (+ | -) - switch _asm _endasm block preprocessing on / off.
23505 You use this pragma to define multilines of assembly code.
23506 This will prevent the preprocessor from changing the formatting required
23508 Below is an example on how to use this pragma.
23511 \begin_layout Verse
23514 #pragma preproc_asm -
23515 \begin_inset LatexCommand index
23516 name "\\#pragma preproc\\_asm"
23522 #define MYDELAY _asm
23527 nop ;my assembly comment...
23541 #pragma preproc_asm
23572 \begin_layout Itemize
23578 \begin_inset LatexCommand index
23579 name "\\#pragma sdcc\\_hash"
23583 (+ | -) - Allow "naked" hash in macro definition, for example:
23587 #define DIR_LO(x) #(x & 0xff)
23592 Below is an example on how to use this pragma.
23595 \begin_layout Verse
23598 #pragma preproc_asm +
23600 #pragma sdcc_hash +
23601 \begin_inset LatexCommand index
23602 name "\\#pragma sdcc\\_hash"
23617 mov R6_B3, #(x & 0xff)
23624 mov R7_B3, #((x >> 8) & 0xff)
23648 \begin_layout Standard
23649 Some of the pragmas are intended to be used to turn-on or off certain optimizati
23650 ons which might cause the compiler to generate extra stack and/or data space
23651 to store compiler generated temporary variables.
23652 This usually happens in large functions.
23653 Pragma directives should be used as shown in the following example, they
23654 are used to control options and optimizations for a given function.
23658 \begin_layout Verse
23662 \begin_inset LatexCommand index
23663 name "\\#pragma save"
23674 /* save the current settings */
23677 \begin_inset LatexCommand index
23678 name "\\#pragma nogcse"
23687 /* turnoff global subexpression elimination */
23689 #pragma noinduction
23690 \begin_inset LatexCommand index
23691 name "\\#pragma noinduction"
23695 /* turn off induction optimizations */
23718 \begin_inset LatexCommand index
23719 name "\\#pragma restore"
23723 /* turn the optimizations back on */
23726 \begin_layout Standard
23727 The compiler will generate a warning message when extra space is allocated.
23728 It is strongly recommended that the save and restore pragmas be used when
23729 changing options for a function.
23738 \begin_layout Section
23739 Defines Created by the Compiler
23742 \begin_layout Standard
23743 The compiler creates the following #defines
23744 \begin_inset LatexCommand index
23750 \begin_inset LatexCommand index
23751 name "Defines created by the compiler"
23760 \begin_layout Standard
23761 \begin_inset Tabular
23762 <lyxtabular version="3" rows="15" columns="2">
23764 <column alignment="left" valignment="top" leftline="true" width="3in">
23765 <column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
23766 <row topline="true" bottomline="true">
23767 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23770 \begin_layout Standard
23778 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23781 \begin_layout Standard
23790 <row topline="true">
23791 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23794 \begin_layout Standard
23796 \begin_inset LatexCommand index
23806 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23809 \begin_layout Standard
23811 Since version 2.5.6 the version number as an int (ex.
23818 <row topline="true">
23819 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23822 \begin_layout Standard
23824 \begin_inset LatexCommand index
23825 name "SDCC\\_mcs51"
23830 \begin_inset LatexCommand index
23831 name "SDCC\\_ds390"
23836 \begin_inset LatexCommand index
23846 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23849 \begin_layout Standard
23850 depending on the model used (e.g.: -mds390)
23856 <row topline="true">
23857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23860 \begin_layout Standard
23862 \begin_inset LatexCommand index
23868 \begin_inset LatexCommand index
23874 \begin_inset LatexCommand index
23880 \begin_inset LatexCommand index
23890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23893 \begin_layout Standard
23894 depending on the model used (e.g.
23901 <row topline="true">
23902 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23905 \begin_layout Standard
23907 \begin_inset LatexCommand index
23908 name "SDCC\\_STACK\\_AUTO"
23917 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23920 \begin_layout Standard
23927 \begin_layout Standard
23944 <row topline="true">
23945 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23948 \begin_layout Standard
23950 \begin_inset LatexCommand index
23951 name "SDCC\\_MODEL\\_SMALL"
23960 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23963 \begin_layout Standard
23970 \begin_layout Standard
23987 <row topline="true">
23988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23991 \begin_layout Standard
23993 \begin_inset LatexCommand index
23994 name "SDCC\\_MODEL\\_MEDIUM"
24003 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24006 \begin_layout Standard
24013 \begin_layout Standard
24030 <row topline="true">
24031 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24034 \begin_layout Standard
24036 \begin_inset LatexCommand index
24037 name "SDCC\\_MODEL\\_LARGE"
24046 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24049 \begin_layout Standard
24056 \begin_layout Standard
24073 <row topline="true">
24074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24077 \begin_layout Standard
24079 \begin_inset LatexCommand index
24080 name "SDCC\\_USE\\_XSTACK"
24089 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24092 \begin_layout Standard
24099 \begin_layout Standard
24116 <row topline="true">
24117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24120 \begin_layout Standard
24122 \begin_inset LatexCommand index
24123 name "SDCC\\_STACK\\_TENBIT"
24132 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24135 \begin_layout Standard
24146 <row topline="true">
24147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24150 \begin_layout Standard
24152 \begin_inset LatexCommand index
24153 name "SDCC\\_MODEL\\_FLAT24"
24162 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24165 \begin_layout Standard
24176 <row topline="true">
24177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24180 \begin_layout Standard
24182 \begin_inset LatexCommand index
24183 name "SDCC\\_REVISION"
24192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24195 \begin_layout Standard
24197 SDCC svn revision number
24203 <row topline="true">
24204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24207 \begin_layout Standard
24208 SDCC_PARMS_IN_BANK1
24209 \begin_inset LatexCommand index
24210 name "SDCC\\_PARMS\\_IN\\_BANK1"
24219 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24222 \begin_layout Standard
24229 \begin_layout Standard
24246 <row topline="true">
24247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24250 \begin_layout Standard
24252 \begin_inset LatexCommand index
24253 name "SDCC\\_MODEL\\_FLAT24"
24262 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24265 \begin_layout Standard
24272 \begin_layout Standard
24289 <row topline="true" bottomline="true">
24290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24293 \begin_layout Standard
24294 SDCC_INT_LONG_REENT
24295 \begin_inset LatexCommand index
24296 name "SDCC\\_INT\\_LONG\\_REENT"
24305 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24308 \begin_layout Standard
24315 \begin_layout Standard
24339 \begin_layout Chapter
24340 Notes on supported Processors
24343 \begin_layout Section
24345 \begin_inset LatexCommand label
24346 name "sub:MCS51-variants"
24351 \begin_inset LatexCommand index
24352 name "MCS51 variants"
24359 \begin_layout Standard
24360 MCS51 processors are available from many vendors and come in many different
24362 While they might differ considerably in respect to Special Function Registers
24363 the core MCS51 is usually not modified or is kept compatible.
24367 \begin_layout Subsection
24368 pdata access by SFR
24371 \begin_layout Standard
24372 With the upcome of devices with internal xdata and flash memory devices
24374 \begin_inset LatexCommand index
24375 name "P2 (mcs51 sfr)"
24379 as dedicated I/O port is becoming more popular.
24380 Switching the high byte for pdata
24381 \begin_inset LatexCommand index
24382 name "pdata (mcs51, ds390 storage class)"
24386 access which was formerly done by port P2 is then achieved by a Special
24388 \begin_inset LatexCommand index
24394 In well-established MCS51 tradition the address of this
24398 is where the chip designers decided to put it.
24399 Needless to say that they didn't agree on a common name either.
24400 So that the startup code can correctly initialize xdata variables, you
24401 should define an sfr with the name _XPAGE
24404 \begin_inset LatexCommand index
24405 name "\\_XPAGE (mcs51)"
24411 at the appropriate location if the default, port P2, is not used for this.
24415 \begin_layout Verse
24418 __sfr __at (0x85) _XPAGE; /* Ramtron VRS51 family a.k.a.
24422 \begin_layout Verse
24425 __sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family, Texas Instruments (Chipcon)
24430 \begin_layout Verse
24433 __sfr __at (0x91) _XPAGE; /* Infineon (Siemens) C500 family a.k.a.
24437 \begin_layout Verse
24440 __sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
24444 \begin_layout Verse
24447 __sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
24451 \begin_layout Standard
24452 For more exotic implementations further customizations may be needed.
24454 \begin_inset LatexCommand ref
24455 reference "sub:Startup-Code"
24459 for other possibilities.
24462 \begin_layout Subsection
24463 Other Features available by SFR
24466 \begin_layout Standard
24467 Some MCS51 variants offer features like Double DPTR
24468 \begin_inset LatexCommand index
24473 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
24474 These are currently not used for the MCS51 port.
24475 If you absolutely need them you can fall back to inline assembly or submit
24479 \begin_layout Subsection
24483 \begin_layout Standard
24485 \begin_inset LatexCommand index
24486 name "Bankswitching"
24492 \begin_inset LatexCommand index
24493 name "code banking"
24497 ) is a technique to increase the code space above the 64k limit of the 8051.
24500 \begin_layout Subsubsection
24504 \begin_layout Standard
24505 \begin_inset Tabular
24506 <lyxtabular version="3" rows="3" columns="4">
24508 <column alignment="center" valignment="top" width="0">
24509 <column alignment="center" valignment="top" leftline="true" width="0">
24510 <column alignment="center" valignment="top" leftline="true" width="0">
24511 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
24512 <row topline="true" bottomline="true">
24513 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
24516 \begin_layout Standard
24522 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24525 \begin_layout Standard
24531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24534 \begin_layout Standard
24540 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24543 \begin_layout Standard
24550 <row topline="true" bottomline="true">
24551 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
24554 \begin_layout Standard
24560 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24563 \begin_layout Standard
24569 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
24572 \begin_layout Standard
24578 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24581 \begin_layout Standard
24589 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
24592 \begin_layout Standard
24593 SiLabs C8051F120 example
24598 <cell multicolumn="2" alignment="center" valignment="top" usebox="none">
24601 \begin_layout Standard
24607 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24610 \begin_layout Standard
24616 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24619 \begin_layout Standard
24634 Usually the hardware uses some sfr (an output port or an internal sfr) to
24635 select a bank and put it in the banked area of the memory map.
24636 The selected bank usually becomes active immediately upon assignment to
24637 this sfr and when running inside a bank it will switch out this code it
24638 is currently running.
24639 Therefor you cannot jump or call directly from one bank to another and
24640 need to use a so-called trampoline in the common area.
24641 For SDCC an example trampoline is in crtbank.asm and you may need to change
24642 it to your 8051 derivative or schematic.
24643 The presented code is written for the C8051F120.
24647 When calling a banked function
24648 SDCC will put the LSB of the functions address in register R0, the MSB
24649 in R1 and the bank in R2 and then call this trampoline
24654 The current selected bank is saved on the stack, the new bank is selected
24655 and an indirect jump is made.
24656 When the banked function returns it jumps to
24660 which restores the previous bank and returns to the caller.
24663 \begin_layout Subsubsection
24667 \begin_layout Standard
24668 When writing banked software using SDCC you need to use some special keywords
24670 You also need to take over a bit of work from the linker.
24674 To create a function
24675 that can be called from another bank it requires the keyword
24680 \begin_inset LatexCommand index
24686 The caller must see this in the prototype of the callee and the callee
24687 needs it for a proper return.
24688 Called functions within the same bank as the caller do not need the
24692 keyword nor do functions in the common area.
24693 Beware: SDCC does not know or check if functions are in the same bank.
24694 This is your responsibility!
24698 Normally all functions you write end up in
24700 If you want a function explicitly to reside in the common area put it in
24702 This applies for instance to interrupt service routines as they should
24706 \begin_layout Standard
24707 Functions that need to be in a switched bank must be put in a named segment.
24708 The name can be mostly anything up to eight characters (e.g.
24710 To do this you either use -
24714 \begin_layout Standard
24723 -codeseg BANK1 (See
24724 \begin_inset LatexCommand ref
24725 reference "lyx:-codeseg"
24729 ) on the command line when compiling or #pragma codeseg BANK1 (See
24730 \begin_inset LatexCommand ref
24731 reference "sec:Pragmas"
24735 ) at the top of the C source file.
24736 The segment name always applies to the whole source file and generated
24737 object so functions for different banks need to be defined in different
24742 When linking your objects you need to tell the linker where
24743 to put your segments.
24744 To do this you use the following command line option to SDCC: -Wl-b BANK1=0x180
24746 \begin_inset LatexCommand ref
24747 reference "lyx:-Wl option"
24752 This sets the virtual start address of this segment.
24753 It sets the banknumber to 0x01 and maps the bank to 0x8000 and up.
24754 The linker will not check for overflows, again this is your responsibility.
24757 \begin_layout Standard
24758 \begin_inset VSpace bigskip
24764 \begin_layout Section
24768 \begin_layout Standard
24770 \begin_inset LatexCommand index
24776 \begin_inset LatexCommand index
24781 microcontroller has a rich set of peripherals.
24782 In its built-in ROM library it includes functions to access some of the
24783 features, among them is a TCP stack with IP4 and IP6 support.
24784 Library headers (currently in beta status) and other files are provided
24788 \begin_inset LatexCommand url
24789 target "ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html"
24795 \begin_inset VSpace bigskip
24801 \begin_layout Section
24802 The Z80 and gbz80 port
24805 \begin_layout Standard
24806 SDCC can target both the Zilog Z80
24807 \begin_inset LatexCommand index
24812 and the Nintendo Gameboy's Z80-like gbz80
24813 \begin_inset LatexCommand index
24814 name "gbz80 (GameBoy Z80)"
24819 The Z80 port is passed through the same
24822 \begin_inset LatexCommand index
24823 name "Regression test"
24830 \begin_inset LatexCommand ref
24831 reference "sec:Quality-control"
24835 ) as the MCS51 and DS390 ports, so floating point support, support for long
24836 variables and bitfield support is fine.
24837 See mailing lists and forums about interrupt routines.
24840 \begin_layout Standard
24841 As always, the code is the authoritative reference - see z80/ralloc.c and
24844 \begin_inset LatexCommand index
24849 frame is similar to that generated by the IAR Z80 compiler.
24850 IX is used as the base pointer, HL and IY are used as a temporary registers,
24851 and BC and DE are available for holding variables.
24853 \begin_inset LatexCommand index
24854 name "Z80!return value"
24858 for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
24860 The gbz80 port use the same set of registers for the return values, but
24861 in a different order of significance: E (one byte), DE (two bytes), or
24863 \begin_inset VSpace bigskip
24869 \begin_layout Section
24873 \begin_layout Standard
24874 The port to the Freescale/Motorola HC08
24875 \begin_inset LatexCommand index
24880 family has been added in October 2003, and is still undergoing some basic
24882 The code generator is complete, but the register allocation is still quite
24884 Some of the SDCC's standard C library functions have embedded non-HC08
24885 inline assembly and so are not yet usable.
24888 \begin_layout Standard
24889 The HC08 port passes the regression test suite (see section
24890 \begin_inset LatexCommand ref
24891 reference "sec:Quality-control"
24896 \begin_inset VSpace bigskip
24902 \begin_layout Section
24904 \begin_inset LatexCommand index
24912 \begin_layout Standard
24913 The PIC14 port adds support for Microchip
24914 \begin_inset LatexCommand index
24920 \begin_inset Formula $^{\text{TM}}$
24924 \begin_inset LatexCommand index
24930 \begin_inset Formula $^{\text{TM}}$
24933 MCUs with 14 bit wide instructions.
24934 This port is not yet mature and still lacks many features.
24935 However, it can work for simple code.
24938 \begin_layout Standard
24940 Currently supported devices include:
24943 \begin_layout Standard
24944 12F: 629, 635, 675, 683
24947 \begin_layout Standard
24951 \begin_layout Standard
24955 \begin_layout Standard
24956 16C: 62, 620, 620a, 621, 621a, 622, 622a, 63a, 65b
24959 \begin_layout Standard
24960 16C: 71, 710, 711, 715, 717, 72, 73b, 745, 74b, 765, 770, 771, 773, 774,
24964 \begin_layout Standard
24968 \begin_layout Standard
24969 16CR: 620a, 73, 74, 76, 77
24972 \begin_layout Standard
24973 16F: 616, 627, 627a, 628, 628a, 630, 636, 639, 648, 648a, 676, 684, 685,
24977 \begin_layout Standard
24978 16F: 716, 72, 73, 737, 74, 747, 76, 767, 77, 777, 785
24981 \begin_layout Standard
24982 16F: 818, 819, 84, 84a, 87, 870, 871, 872, 873, 873a, 874, 874a, 876, 876a,
24983 877, 877a, 88, 886, 887
24986 \begin_layout Standard
24987 16F: 913, 914, 916, 917, 946
24990 \begin_layout Standard
24994 \begin_layout Standard
24996 An up-to-date list of currently supported devices can be obtained via
24998 sdcc -mpic14 -phelp foo.c
25000 (foo.c must exist...).
25003 \begin_layout Subsection
25005 \begin_inset LatexCommand index
25006 name "code page (pic14)"
25011 \begin_inset LatexCommand index
25012 name "Memory bank (pic14)"
25019 \begin_layout Standard
25020 The linker organizes allocation for the code page and RAM banks.
25021 It does not have intimate knowledge of the code flow.
25022 It will put all the code section of a single .asm file into a single code
25024 In order to make use of multiple code pages, separate asm files must be
25026 The compiler assigns all
25030 functions of a single .c file into the same code page.
25034 To get the best results,
25035 follow these guidelines:
25038 \begin_layout Enumerate
25039 Make local functions static, as non static functions require code page selection
25042 Due to the way sdcc handles functions, place called functions prior
25043 to calling functions in the file wherever possible: Otherwise sdcc will
25044 insert unnecessary pagesel directives around the call, believing that the
25045 called function is externally defined.
25048 \begin_layout Enumerate
25049 For devices that have multiple code pages it is more efficient to use the
25050 same number of files as pages: Use up to 4 separate .c files for the 16F877,
25051 but only 2 files for the 16F874.
25052 This way the linker can put the code for each file into different code
25053 pages and there will be less page selection overhead.
25056 \begin_layout Enumerate
25057 And as for any 8 bit micro (especially for PIC14 as they have a very simple
25058 instruction set), use `unsigned char' wherever possible instead of `int'.
25061 \begin_layout Subsection
25062 Adding New Devices to the Port
25065 \begin_layout Standard
25066 Adding support for a new 14
25070 \begin_layout Standard
25079 bit PIC MCU requires the following steps:
25082 \begin_layout Enumerate
25083 Create a new device description.
25085 Each device is described in two files: pic16f*.h
25087 These files primarily define SFRs, structs to access their bits, and symbolic
25088 configuration options.
25089 Both files can be generated from gputils' .inc files using the perl script
25092 support/scripts/inc2h.pl
25095 This file also contains further instructions on how to proceed.
25098 \begin_layout Enumerate
25099 Copy the .h file into SDCC's include path and either add the .c file to your
25100 project or copy it to
25102 device/lib/pic/libdev
25105 Afterwards, rebuild and install the libraries.
25108 \begin_layout Enumerate
25109 Edit pic14devices.txt in SDCC's include path (
25111 device/include/pic/
25113 in the source tree or
25115 /usr/local/share/sdcc/include/pic
25117 after installation).
25119 You need to add a device specification here to make
25120 the memory layout (code banks, RAM, aliased memory regions, ...) known to
25122 Probably you can copy and modify an existing entry.
25123 The file format is documented at the top of the file.
25126 \begin_layout Subsection
25130 \begin_layout Standard
25131 For the interrupt function, use the keyword `__interrupt'
25132 \begin_inset LatexCommand index
25133 name "PIC14!interrupt"
25137 with level number of 0 (PIC14 only has 1 interrupt so this number is only
25138 there to avoid a syntax error - it ought to be fixed).
25142 \begin_layout Verse
25145 void Intr(void) __interrupt 0
25151 T0IF = 0; /* Clear timer interrupt */
25156 \begin_layout Subsection
25157 Linking and Assembling
25160 \begin_layout Standard
25161 For assembling you can use either GPUTILS'
25162 \begin_inset LatexCommand index
25163 name "gputils (pic tools)"
25167 gpasm.exe or MPLAB's mpasmwin.exe.
25168 GPUTILS are available from
25169 \begin_inset LatexCommand url
25170 target "http://sourceforge.net/projects/gputils"
25175 For linking you can use either GPUTILS' gplink or MPLAB's mplink.exe.
25176 If you use MPLAB and an interrupt function then the linker script file
25177 vectors section will need to be enlarged to link with mplink.
25188 \begin_layout Verse
25201 sdcc -V -mpic14 -p16f877 -c $<
25205 $(PRJ).hex: $(OBJS)
25215 gplink -m -s $(PRJ).lkr
25216 -o $(PRJ).hex $(OBJS) libsdcc.lib
25219 \begin_layout Standard
25227 \begin_layout Verse
25240 sdcc -S -V -mpic14 -p16f877 $<
25250 mpasmwin /q /o $*.asm
25254 $(PRJ).hex: $(OBJS)
25265 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
25268 \begin_layout Standard
25269 Please note that indentations within a
25273 have to be done with a tabulator character.
25276 \begin_layout Subsection
25277 Command-Line Options
25280 \begin_layout Standard
25281 Besides the switches common to all SDCC backends, the PIC14 port accepts
25282 the following options (for an updated list see sdcc -
25286 \begin_layout Standard
25298 \begin_layout Description
25303 \begin_layout Standard
25313 \begin_inset LatexCommand index
25314 name "PIC14!Options!-\\/-debug-extra"
25318 emit debug info in assembly output
25321 \begin_layout Description
25326 \begin_layout Standard
25336 \begin_inset LatexCommand index
25337 name "PIC14!Options!-\\/-no-pcode-opt"
25341 disable (slightly faulty) optimization on pCode
25344 \begin_layout Description
25349 \begin_layout Standard
25359 \begin_inset LatexCommand index
25360 name "PIC14!Options!-\\/-stack-loc"
25364 sets the lowest address of the argument passing stack (defaults to a suitably
25365 large shared databank to reduce BANKSEL overhead)
25368 \begin_layout Description
25373 \begin_layout Standard
25383 \begin_inset LatexCommand index
25384 name "PIC14!Options!-\\/-stack-size"
25388 sets the size if the argument passing stack (default: 16, minimum: 4)
25391 \begin_layout Subsection
25392 Environment Variables
25395 \begin_layout Standard
25396 The PIC14 port recognizes the following environment variables:
25399 \begin_layout Description
25400 SDCC_PIC14_SPLIT_LOCALS If set and not empty, sdcc will allocate each temporary
25401 register (the ones called r0xNNNN) in a section of its own.
25402 By default (if this variable is unset), sdcc tries to cluster registers
25403 in sections in order to reduce the BANKSEL overhead when accessing them.
25406 \begin_layout Subsection
25410 \begin_layout Standard
25411 The PIC14 library currently only contains support routines required by the
25412 compiler to implement multiplication, division, and floating point support.
25413 No libc-like replacement is available at the moment, though many of the
25414 common sdcc library sources (in
25418 ) should also compile with the PIC14 port.
25421 \begin_layout Subsubsection
25422 error: missing definition for symbol ``__gptrget1''
25425 \begin_layout Standard
25426 The PIC14 port uses library routines to provide more complex operations
25427 like multiplication, division/modulus and (generic) pointer dereferencing.
25428 In order to add these routines to your project, you must link with PIC14's
25434 For single source file projects this is done automatically, more complex
25439 to the linker's arguments.
25440 Make sure you also add an include path for the library (using the -I switch
25444 \begin_layout Subsubsection
25445 Processor mismatch in file ``XXX''.
25448 \begin_layout Standard
25449 This warning can usually be ignored due to the very good compatibility amongst
25454 \begin_layout Standard
25464 \begin_inset LatexCommand index
25472 \begin_layout Standard
25473 You might also consider recompiling the library for your specific device
25474 by changing the ARCH=p16f877 (default target) entry in
25476 device/lib/pic/Makefile.in
25480 device/lib/pic/Makefile
25482 to reflect your device.
25483 This might even improve performance for smaller devices as unnecessary
25484 BANKSELs might be removed.
25487 \begin_layout Subsection
25491 \begin_layout Subsubsection
25495 \begin_layout Standard
25496 Functions with variable argument lists (like printf) are not yet supported.
25497 Similarly, taking the address of the first argument passed into a function
25498 does not work: It is currently passed in WREG and has no address...
25501 \begin_layout Subsubsection
25502 Regression tests fail
25505 \begin_layout Standard
25506 Though the small subset of regression tests in src/regression passes, SDCC
25507 regression test suite does not, indicating that there are still major bugs
25509 However, many smaller projects have successfully used SDCC in the past...
25512 \begin_layout Standard
25520 \begin_layout Section
25522 \begin_inset LatexCommand index
25530 \begin_layout Standard
25531 The PIC16 port adds support for Microchip
25532 \begin_inset LatexCommand index
25538 \begin_inset Formula $^{\text{TM}}$
25542 \begin_inset LatexCommand index
25548 \begin_inset Formula $^{\text{TM}}$
25551 MCUs with 16 bit wide instructions.
25552 Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx
25553 ; devices supported by the port include:
25556 \begin_layout Standard
25557 18F: 242, 248, 252, 258, 442, 448, 452, 458
25560 \begin_layout Standard
25564 \begin_layout Standard
25565 18F: 2220, 2221, 2320, 2321, 2331, 2410, 2420, 2423, 2431, 2450, 2455, 2480,
25569 \begin_layout Standard
25570 18F: (2510,) 2515, 2520, 2523, 2525, 2550, 2580, 2585, 25j10, 2610, 2620,
25574 \begin_layout Standard
25575 18F: 4220, 4221, 4320, 4321, 4331, 4410, 4420, 4423, 4431, 4450, 4455, 4480,
25579 \begin_layout Standard
25580 18F: 4510, 4515, 4520, 4523, 4525, 4550, 4580, 4585, 45j10, 4610, 4620,
25584 \begin_layout Standard
25585 18F: 6520, 6585, 6620, 6680, 66j60, 66j65, 6720, 67j60
25588 \begin_layout Standard
25589 18F: 8520, 8585, 8620, 8680, 86j60, 86j65, 8720, 87j60
25592 \begin_layout Standard
25593 18F: 96j60, 96j65, 97j60
25596 \begin_layout Standard
25598 An up-to-date list of supported devices is also available via '
25600 sdcc -mpic16 -plist
25605 \begin_layout Subsection
25609 \begin_layout Standard
25610 PIC16 port supports the standard command line arguments as supposed, with
25611 the exception of certain cases that will be mentioned in the following
25615 \begin_layout Description
25620 \begin_layout Standard
25630 \begin_inset LatexCommand index
25631 name "PIC16!Options!-\\/-callee-saves"
25639 \begin_layout Standard
25651 \begin_layout Description
25656 \begin_layout Standard
25665 -fommit-frame-pointer
25666 \begin_inset LatexCommand index
25667 name "PIC16!Options!-\\/-fommit-frame-pointer"
25671 Frame pointer will be omitted when the function uses no local variables.
25674 \begin_layout Subsection
25675 Port Specific Options
25676 \begin_inset LatexCommand index
25677 name "Options PIC16"
25684 \begin_layout Standard
25685 The port specific options appear after the global options in the sdcc -
25689 \begin_layout Standard
25701 \begin_layout Subsubsection
25702 Code Generation Options
25705 \begin_layout Standard
25706 These options influence the generated assembler code.
25709 \begin_layout Description
25714 \begin_layout Standard
25723 -pstack-model=[model] Used in conjunction with the command above.
25724 Defines the stack model to be used, valid stack models are:
25729 \labelwidthstring 00.00.0000
25734 Selects small stack model.
25735 8 bit stack and frame pointers.
25736 Supports 256 bytes stack size.
25740 \labelwidthstring 00.00.0000
25745 Selects large stack model.
25746 16 bit stack and frame pointers.
25747 Supports 65536 bytes stack size.
25751 \begin_layout Description
25756 \begin_layout Standard
25765 -pno-banksel Do not generate BANKSEL assembler directives.
25768 \begin_layout Description
25773 \begin_layout Standard
25782 -extended Enable extended instruction set/literal offset addressing mode.
25786 \begin_layout Subsubsection
25787 Optimization Options
25790 \begin_layout Description
25795 \begin_layout Standard
25804 -obanksel=n Set optimization level for inserting BANKSELs.
25811 \labelwidthstring 00.00.0000
25816 \labelwidthstring 00.00.0000
25817 1 checks previous used register and if it is the same then does not emit
25818 BANKSEL, accounts only for labels.
25822 \labelwidthstring 00.00.0000
25823 2 tries to check the location of (even different) symbols and removes BANKSELs
25824 if they are in the same bank.
25829 Important: There might be problems if the linker script has data sections
25830 across bank borders!
25834 \begin_layout Description
25839 \begin_layout Standard
25848 -denable-peeps Force the usage of peepholes.
25852 \begin_layout Description
25857 \begin_layout Standard
25866 -no-optimize-goto Do not use (conditional) BRA instead of GOTO.
25869 \begin_layout Description
25874 \begin_layout Standard
25883 -optimize-cmp Try to optimize some compares.
25886 \begin_layout Description
25891 \begin_layout Standard
25900 -optimize-df Analyze the dataflow of the generated code and improve it.
25903 \begin_layout Subsubsection
25907 \begin_layout Description
25912 \begin_layout Standard
25921 -asm= Sets the full path and name of an external assembler to call.
25924 \begin_layout Description
25929 \begin_layout Standard
25939 \begin_inset LatexCommand index
25944 compatibility option.
25945 Currently only suppresses special gpasm directives.
25948 \begin_layout Subsubsection
25952 \begin_layout Description
25957 \begin_layout Standard
25966 -link= Sets the full path and name of an external linker to call.
25969 \begin_layout Description
25974 \begin_layout Standard
25983 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
25984 unitialized data variables with [kword].
25985 Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
25988 \begin_layout Description
25993 \begin_layout Standard
26002 -ivt-loc=n Place the interrupt vector table at address
26007 Useful for bootloaders.
26010 \begin_layout Description
26015 \begin_layout Standard
26024 -nodefaultlibs Do not link default libraries when linking.
26027 \begin_layout Description
26032 \begin_layout Standard
26041 -use-crt= Use a custom run-time module instead of the defaults.
26044 \begin_layout Description
26049 \begin_layout Standard
26058 -no-crt Don't link the default run-time modules
26061 \begin_layout Subsubsection
26065 \begin_layout Standard
26066 Debugging options enable extra debugging information in the output files.
26069 \begin_layout Description
26074 \begin_layout Standard
26083 -debug-xtra Similar to -
26087 \begin_layout Standard
26097 \begin_inset LatexCommand index
26102 , but dumps more information.
26105 \begin_layout Description
26110 \begin_layout Standard
26119 -debug-ralloc Force register allocator to dump <source>.d file with debugging
26121 <source> is the name of the file being compiled.
26124 \begin_layout Description
26129 \begin_layout Standard
26138 -pcode-verbose Enable pcode debugging information in translation.
26141 \begin_layout Description
26146 \begin_layout Standard
26155 -calltree Dump call tree in .calltree file.
26158 \begin_layout Description
26163 \begin_layout Standard
26172 -gstack Trace push/pops for stack pointer overflow.
26175 \begin_layout Subsection
26176 Environment Variables
26179 \begin_layout Standard
26180 There is a number of environmental variables that can be used when running
26181 SDCC to enable certain optimizations or force a specific program behaviour.
26182 these variables are primarily for debugging purposes so they can be enabled/dis
26186 \begin_layout Standard
26187 Currently there is only two such variables available:
26190 \begin_layout Description
26191 OPTIMIZE_BITFIELD_POINTER_GET When this variable exists, reading of structure
26192 bitfields is optimized by directly loading FSR0 with the address of the
26193 bitfield structure.
26194 Normally SDCC will cast the bitfield structure to a bitfield pointer and
26196 This step saves data ram and code space for functions that make heavy use
26198 (i.e., 80 bytes of code space are saved when compiling malloc.c with this
26203 \begin_layout Description
26204 NO_REG_OPT Do not perform pCode registers optimization.
26205 This should be used for debugging purposes.
26206 If bugs in the pcode optimizer are found, users can benefit from temporarily
26207 disabling the optimizer until the bug is fixed.
26210 \begin_layout Subsection
26211 Preprocessor Macros
26214 \begin_layout Standard
26216 \begin_inset LatexCommand index
26221 port defines the following preprocessor macros while translating a source.
26224 \begin_layout Standard
26226 \begin_inset Tabular
26227 <lyxtabular version="3" rows="6" columns="2">
26229 <column alignment="center" valignment="top" leftline="true" width="0">
26230 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26231 <row topline="true" bottomline="true">
26232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26235 \begin_layout Standard
26241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26244 \begin_layout Standard
26251 <row topline="true">
26252 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26255 \begin_layout Standard
26261 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26264 \begin_layout Standard
26265 Port identification
26271 <row topline="true">
26272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26275 \begin_layout Standard
26280 \begin_layout Standard
26294 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26297 \begin_layout Standard
26298 Port identification (same as above)
26304 <row topline="true">
26305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26308 \begin_layout Standard
26314 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26317 \begin_layout Standard
26318 MCU Identification.
26323 is the microcontrol identification number, i.e.
26330 <row topline="true">
26331 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26334 \begin_layout Standard
26339 \begin_layout Standard
26353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26356 \begin_layout Standard
26357 MCU Identification (same as above)
26363 <row topline="true" bottomline="true">
26364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26367 \begin_layout Standard
26373 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26376 \begin_layout Standard
26377 nnn = SMALL or LARGE respectively according to the stack model used
26390 \begin_layout Standard
26392 In addition the following macros are defined when calling assembler:
26395 \begin_layout Standard
26397 \begin_inset Tabular
26398 <lyxtabular version="3" rows="4" columns="2">
26400 <column alignment="center" valignment="top" leftline="true" width="0">
26401 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26402 <row topline="true" bottomline="true">
26403 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26406 \begin_layout Standard
26412 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26415 \begin_layout Standard
26422 <row topline="true">
26423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26426 \begin_layout Standard
26432 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26435 \begin_layout Standard
26436 MCU Identification.
26441 is the microcontrol identification number, i.e.
26448 <row topline="true">
26449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26452 \begin_layout Standard
26458 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26461 \begin_layout Standard
26462 nnn = SMALL or LARGE respectively according to the memory model used for
26469 <row topline="true" bottomline="true">
26470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26473 \begin_layout Standard
26479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26482 \begin_layout Standard
26483 nnn = SMALL or LARGE respectively according to the stack model used
26496 \begin_layout Subsection
26500 \begin_layout Standard
26502 \begin_inset LatexCommand index
26507 port uses the following directories for searching header files and libraries.
26510 \begin_layout Standard
26512 \begin_inset Tabular
26513 <lyxtabular version="3" rows="3" columns="4">
26515 <column alignment="center" valignment="top" leftline="true" width="0">
26516 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26517 <column alignment="center" valignment="top" width="0">
26518 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26519 <row topline="true" bottomline="true">
26520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26523 \begin_layout Standard
26529 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26532 \begin_layout Standard
26538 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26541 \begin_layout Standard
26547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26550 \begin_layout Standard
26557 <row topline="true">
26558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26561 \begin_layout Standard
26562 PREFIX/sdcc/include/pic16
26567 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26570 \begin_layout Standard
26571 PIC16 specific headers
26576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26579 \begin_layout Standard
26585 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26588 \begin_layout Standard
26595 <row topline="true" bottomline="true">
26596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26599 \begin_layout Standard
26600 PREFIX/sdcc/lib/pic16
26605 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26608 \begin_layout Standard
26609 PIC16 specific libraries
26614 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26617 \begin_layout Standard
26623 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26626 \begin_layout Standard
26640 \begin_layout Subsection
26642 \begin_inset LatexCommand label
26643 name "sub:PIC16_Pragmas"
26650 \begin_layout Standard
26652 \begin_inset LatexCommand index
26657 port currently supports the following pragmas:
26660 \begin_layout Description
26662 \begin_inset LatexCommand index
26663 name "PIC16!Pragmas!\\#pragma stack"
26667 This forces the code generator to initialize the stack & frame pointers
26668 at a specific address.
26669 This is an ad hoc solution for cases where no STACK directive is available
26670 in the linker script or gplink is not instructed to create a stack section.
26673 stack pragma should be used only once in a project.
26674 Multiple pragmas may result in indeterminate behaviour of the program.
26678 \begin_layout Standard
26679 The old format (ie.
26680 #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
26681 cross page boundaries (or even exceed the available data RAM) and crash
26683 Make sure that stack does not cross page boundaries when using the SMALL
26691 The format is as follows:
26696 \begin_layout LyX-Code
26697 #pragma stack bottom_address [stack_size]
26702 \begin_layout Standard
26707 is the lower bound of the stack section.
26708 The stack pointer initially will point at address (bottom_address+stack_size-1).
26711 \begin_layout LyX-Code
26715 \begin_layout LyX-Code
26719 \begin_layout LyX-Code
26720 /* initializes stack of 100 bytes at RAM address 0x200 */
26723 \begin_layout LyX-Code
26724 #pragma stack 0x200 100
26727 \begin_layout Standard
26728 If the stack_size field is omitted then a stack is created with the default
26730 This size might be enough for most programs, but its not enough for operations
26731 with deep function nesting or excessive stack usage.
26734 \begin_layout Description
26736 \begin_inset LatexCommand index
26737 name "PIC16!Pragmas!\\#pragma code"
26741 Force a function to a static FLASH address.
26744 \begin_layout LyX-Code
26748 \begin_layout LyX-Code
26752 \begin_layout LyX-Code
26753 /* place function test_func at 0x4000 */
26756 \begin_layout LyX-Code
26757 #pragma code test_func 0x4000
26760 \begin_layout LyX-Code
26764 \begin_layout Description
26765 library instructs the linker to use a library module.
26770 \begin_layout LyX-Code
26771 #pragma library module_name
26774 \begin_layout Standard
26779 can be any library or object file (including its path).
26780 Note that there are four reserved keywords which have special meaning.
26784 \begin_layout Standard
26786 \begin_inset Tabular
26787 <lyxtabular version="3" rows="6" columns="3">
26789 <column alignment="center" valignment="top" leftline="true" width="0">
26790 <column alignment="block" valignment="top" leftline="true" width="20page%">
26791 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
26792 <row topline="true" bottomline="true">
26793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26796 \begin_layout Standard
26802 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26805 \begin_layout Standard
26811 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26814 \begin_layout Standard
26821 <row topline="true">
26822 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26825 \begin_layout Standard
26833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26836 \begin_layout Standard
26837 ignore all library pragmas
26842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26845 \begin_layout Standard
26854 <row topline="true">
26855 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26858 \begin_layout Standard
26866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26869 \begin_layout Standard
26875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26878 \begin_layout Standard
26889 <row topline="true">
26890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26893 \begin_layout Standard
26901 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26904 \begin_layout Standard
26905 link the Math libarary
26910 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26913 \begin_layout Standard
26924 <row topline="true">
26925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26928 \begin_layout Standard
26936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26939 \begin_layout Standard
26940 link the I/O library
26945 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26948 \begin_layout Standard
26959 <row topline="true" bottomline="true">
26960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26963 \begin_layout Standard
26971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26974 \begin_layout Standard
26975 link the debug library
26980 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26983 \begin_layout Standard
27000 * is the device number, i.e.
27001 452 for PIC18F452 MCU.
27004 \begin_layout Standard
27006 This feature allows for linking with specific libraries without having to
27007 explicit name them in the command line.
27012 keyword will reject all modules specified by the library pragma.
27015 \begin_layout Description
27016 udata The pragma udata instructs the compiler to emit code so that linker
27017 will place a variable at a specific memory bank.
27020 \begin_layout LyX-Code
27024 \begin_layout LyX-Code
27028 \begin_layout LyX-Code
27029 /* places variable foo at bank2 */
27032 \begin_layout LyX-Code
27033 #pragma udata bank2 foo
27036 \begin_layout LyX-Code
27040 \begin_layout Standard
27041 In order for this pragma to work extra SECTION directives should be added
27042 in the .lkr script.
27043 In the following example a sample .lkr file is shown:
27046 \begin_layout LyX-Code
27050 \begin_layout LyX-Code
27051 // Sample linker script for the PIC18F452 processor
27054 \begin_layout LyX-Code
27058 \begin_layout LyX-Code
27059 CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED
27062 \begin_layout LyX-Code
27063 CODEPAGE NAME=page START=0x2A END=0x7FFF
27066 \begin_layout LyX-Code
27067 CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED
27070 \begin_layout LyX-Code
27071 CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED
27074 \begin_layout LyX-Code
27075 CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED
27078 \begin_layout LyX-Code
27079 CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED
27082 \begin_layout LyX-Code
27083 ACCESSBANK NAME=accessram START=0x0 END=0x7F
27086 \begin_layout LyX-Code
27090 \begin_layout LyX-Code
27091 DATABANK NAME=gpr0 START=0x80 END=0xFF
27094 \begin_layout LyX-Code
27095 DATABANK NAME=gpr1 START=0x100 END=0x1FF
27098 \begin_layout LyX-Code
27099 DATABANK NAME=gpr2 START=0x200 END=0x2FF
27102 \begin_layout LyX-Code
27103 DATABANK NAME=gpr3 START=0x300 END=0x3FF
27106 \begin_layout LyX-Code
27107 DATABANK NAME=gpr4 START=0x400 END=0x4FF
27110 \begin_layout LyX-Code
27111 DATABANK NAME=gpr5 START=0x500 END=0x5FF
27114 \begin_layout LyX-Code
27115 ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED
27118 \begin_layout LyX-Code
27122 \begin_layout LyX-Code
27123 SECTION NAME=CONFIG ROM=config
27126 \begin_layout LyX-Code
27130 \begin_layout LyX-Code
27131 SECTION NAME=bank0 RAM=gpr0 # these SECTION directives
27134 \begin_layout LyX-Code
27135 SECTION NAME=bank1 RAM=gpr1 # should be added to link
27138 \begin_layout LyX-Code
27139 SECTION NAME=bank2 RAM=gpr2 # section name 'bank?' with
27142 \begin_layout LyX-Code
27143 SECTION NAME=bank3 RAM=gpr3 # a specific DATABANK name
27146 \begin_layout LyX-Code
27147 SECTION NAME=bank4 RAM=gpr4
27150 \begin_layout LyX-Code
27151 SECTION NAME=bank5 RAM=gpr5
27154 \begin_layout Standard
27155 The linker will recognise the section name set in the pragma statement and
27156 will position the variable at the memory bank set with the RAM field at
27157 the SECTION line in the linker script file.
27160 \begin_layout Subsection
27162 \begin_inset LatexCommand label
27163 name "sub:PIC16_Header-Files"
27170 \begin_layout Standard
27171 There is one main header file
27172 \begin_inset LatexCommand index
27173 name "PIC16!Header files"
27177 that can be included to the source files using the pic16
27178 \begin_inset LatexCommand index
27189 This header file contains the definitions for the processor special registers,
27190 so it is necessary if the source accesses them.
27191 It can be included by adding the following line in the beginning of the
27195 \begin_layout LyX-Code
27196 #include <pic18fregs.h>
27199 \begin_layout Standard
27200 The specific microcontroller is selected within the pic18fregs.h automatically,
27201 so the same source can be used with a variety of devices.
27204 \begin_layout Subsection
27206 \begin_inset LatexCommand label
27207 name "sub:pic16Libraries"
27214 \begin_layout Standard
27216 \begin_inset LatexCommand index
27217 name "PIC16!Libraries"
27222 \begin_inset LatexCommand index
27227 port depends on are the microcontroller device libraries which contain
27228 the symbol definitions for the microcontroller special function registers.
27229 These libraries have the format pic18fxxxx.lib, where
27233 is the microcontroller identification number.
27234 The specific library is selected automatically by the compiler at link
27235 stage according to the selected device.
27238 \begin_layout Standard
27240 Libraries are created with gplib which is part of the gputils package
27241 \begin_inset LatexCommand url
27242 target "http://sourceforge.net/projects/gputils"
27249 \begin_layout Subsubsection*
27250 Building the libraries
27253 \begin_layout Standard
27254 Before using SDCC/pic16 there are some libraries that need to be compiled.
27255 This process is done automatically if gputils are found at SDCC's compile
27257 Should you require to rebuild the pic16 libraries manually, these are the
27258 steps required to do so under Linux or Mac OS X (cygwin might work as well,
27262 \begin_layout LyX-Code
27263 cd device/lib/pic16
27266 \begin_layout LyX-Code
27270 \begin_layout LyX-Code
27274 \begin_layout LyX-Code
27278 \begin_layout LyX-Code
27279 su -c 'make install' # install the libraries, you need the root password
27282 \begin_layout LyX-Code
27286 \begin_layout Standard
27287 If you need to install the headers too, do:
27290 \begin_layout LyX-Code
27294 \begin_layout LyX-Code
27295 su -c 'make install' # install the headers, you need the root password
27298 \begin_layout Subsection
27299 Adding New Devices to the Port
27302 \begin_layout Standard
27303 Adding support for a new 16
27307 \begin_layout Standard
27316 bit PIC MCU requires the following steps:
27319 \begin_layout Enumerate
27320 Create picDEVICE.c and picDEVICE.h from pDEVICE.inc using
27324 perl /path/to/sdcc/support/scripts/inc2h-pic16.pl /path/to/gputils/header/pDEVICE.
27328 \begin_layout Enumerate
27331 mv picDEVICE.h /path/to/sdcc/device/include/pic16
27334 \begin_layout Enumerate
27337 mv picDEVICE.c /path/to/sdcc/device/lib/pic16/libdev
27340 \begin_layout Enumerate
27343 /path/to/sdcc/device/lib/pic16/pics.all
27347 Note: No 18f prefix here!
27350 \begin_layout Enumerate
27353 /path/to/sdcc/device/include/pic16/adc.h
27357 Add the new devices to the correct ADC style class (depending on the number
27364 if the device does not offer any ADC at all.
27367 \begin_layout Enumerate
27370 /path/to/sdcc/device/include/pic16/pic18fregs.h
27374 The file format is self-explanatory, just add
27378 #elif defined(picDEVICE)
27384 \begin_layout Standard
27395 include <picDEVICE.h>
27399 at the right place (keep the file sorted, please).
27402 \begin_layout Enumerate
27405 /path/to/sdcc/device/include/pic16devices.txt
27409 Copy and modify an existing entry or create a new one and insert it at the
27410 correct place (keep the file sorted, please).
27413 \begin_layout Enumerate
27416 /path/to/sdcc/device/lib/pic16/libdev/Makefile.am
27420 Copy an existing entry and adjust the device name.
27423 \begin_layout Enumerate
27426 /path/to/sdcc/device/lib/pic16/libio/Makefile.am
27430 Copy the record from the 18f2220 and adjust the device name.
27433 does not offer ADC, I
27434 \begin_inset Formula $^{\text{2}}$
27437 C, and/or (E)USART functionality as assumed by the library, remove the lines
27453 \begin_layout Enumerate
27472 /path/to/sdcc/device/lib/pic16
27477 \begin_layout Enumerate
27478 Recompile the pic16 libraries as described in
27479 \begin_inset LatexCommand ref
27480 reference "sub:pic16Libraries"
27487 \begin_layout Subsection
27491 \begin_layout Standard
27492 The following memory models are supported by the PIC16 port:
27495 \begin_layout Itemize
27499 \begin_layout Itemize
27503 \begin_layout Standard
27504 Memory model affects the default size of pointers within the source.
27505 The sizes are shown in the next table:
27508 \begin_layout Standard
27510 \begin_inset Tabular
27511 <lyxtabular version="3" rows="3" columns="3">
27513 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27514 <column alignment="center" valignment="top" leftline="true" width="0">
27515 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27516 <row topline="true" bottomline="true">
27517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27520 \begin_layout Standard
27521 Pointer sizes according to memory model
27526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27529 \begin_layout Standard
27535 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27538 \begin_layout Standard
27545 <row topline="true" bottomline="true">
27546 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27549 \begin_layout Standard
27555 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27558 \begin_layout Standard
27564 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27567 \begin_layout Standard
27574 <row topline="true" bottomline="true">
27575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27578 \begin_layout Standard
27584 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
27587 \begin_layout Standard
27593 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27596 \begin_layout Standard
27610 \begin_layout Standard
27611 It is advisable that all sources within a project are compiled with the
27613 If one wants to override the default memory model, this can be done by
27614 declaring a pointer as
27623 Far selects large memory model's pointers, while near selects small memory
27627 \begin_layout Standard
27628 The standard device libraries (see
27629 \begin_inset LatexCommand ref
27630 reference "sub:PIC16_Header-Files"
27634 ) contain no reference to pointers, so they can be used with both memory
27638 \begin_layout Subsection
27642 \begin_layout Standard
27644 \begin_inset LatexCommand index
27649 implementation for the PIC16 port uses two indirect registers, FSR1 and
27653 \begin_layout Description
27654 FSR1 is assigned as stack pointer
27657 \begin_layout Description
27658 FSR2 is assigned as frame pointer
27661 \begin_layout Standard
27662 The following stack models are supported by the PIC16 port
27665 \begin_layout Itemize
27673 \begin_layout Itemize
27681 \begin_layout Standard
27686 model means that only the FSRxL byte is used to access stack and frame,
27693 uses both FSRxL and FSRxH registers.
27694 The following table shows the stack/frame pointers sizes according to stack
27695 model and the maximum space they can address:
27698 \begin_layout Standard
27700 \begin_inset Tabular
27701 <lyxtabular version="3" rows="3" columns="3">
27703 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27704 <column alignment="center" valignment="top" leftline="true" width="0">
27705 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27706 <row topline="true" bottomline="true">
27707 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27710 \begin_layout Standard
27711 Stack & Frame pointer sizes according to stack model
27716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27719 \begin_layout Standard
27725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27728 \begin_layout Standard
27735 <row topline="true">
27736 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27739 \begin_layout Standard
27745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27748 \begin_layout Standard
27754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27757 \begin_layout Standard
27764 <row topline="true" bottomline="true">
27765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27768 \begin_layout Standard
27774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27777 \begin_layout Standard
27783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27786 \begin_layout Standard
27800 \begin_layout Standard
27806 stack model is currently not working properly throughout the code generator.
27807 So its use is not advised.
27808 Also there are some other points that need special care:
27813 \begin_layout Enumerate
27814 Do not create stack sections with size more than one physical bank (that
27818 \begin_layout Enumerate
27819 Stack sections should no cross physical bank limits (i.e.
27820 #pragma stack 0x50 0x100)
27823 \begin_layout Standard
27824 These limitations are caused by the fact that only FSRxL is modified when
27825 using SMALL stack model, so no more than 256 bytes of stack can be used.
27826 This problem will disappear after LARGE model is fully implemented.
27829 \begin_layout Subsection
27833 \begin_layout Standard
27834 In addition to the standard SDCC function keywords, PIC16
27835 \begin_inset LatexCommand index
27840 port makes available two more:
27843 \begin_layout Description
27845 \begin_inset LatexCommand index
27846 name "PIC16!wparam"
27850 Use the WREG to pass one byte of the first function argument.
27851 This improves speed but you may not use this for functions with arguments
27852 that are called via function pointers, otherwise the first byte of the
27853 first parameter will get lost.
27857 \begin_layout LyX-Code
27858 void func_wparam(int a) wparam
27861 \begin_layout LyX-Code
27865 \begin_layout LyX-Code
27866 /* WREG hold the lower part of a */
27869 \begin_layout LyX-Code
27870 /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
27874 \begin_layout LyX-Code
27878 \begin_layout LyX-Code
27882 \begin_layout Description
27884 \begin_inset LatexCommand index
27885 name "PIC16!shadowregs"
27889 When entering/exiting an ISR, it is possible to take advantage of the PIC18F
27890 hardware shadow registers which hold the values of WREG, STATUS and BSR
27892 This can be done by adding the keyword
27900 keyword in the function's header.
27903 \begin_layout LyX-Code
27904 void isr_shadow(void) shadowregs interrupt 1
27907 \begin_layout LyX-Code
27911 \begin_layout LyX-Code
27915 \begin_layout LyX-Code
27919 \begin_layout Standard
27924 instructs the code generator not to store/restore WREG, STATUS, BSR when
27925 entering/exiting the ISR.
27928 \begin_layout Subsection
27929 Function return values
27932 \begin_layout Standard
27933 Return values from functions are placed to the appropriate registers following
27934 a modified Microchip policy optimized for SDCC.
27935 The following table shows these registers:
27938 \begin_layout Standard
27940 \begin_inset Tabular
27941 <lyxtabular version="3" rows="6" columns="2">
27943 <column alignment="center" valignment="top" leftline="true" width="0">
27944 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27945 <row topline="true" bottomline="true">
27946 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27949 \begin_layout Standard
27955 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27958 \begin_layout Standard
27959 destination register
27965 <row topline="true">
27966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27969 \begin_layout Standard
27975 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27978 \begin_layout Standard
27985 <row topline="true">
27986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27989 \begin_layout Standard
27995 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27998 \begin_layout Standard
28005 <row topline="true">
28006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28009 \begin_layout Standard
28015 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28018 \begin_layout Standard
28025 <row topline="true">
28026 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28029 \begin_layout Standard
28035 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28038 \begin_layout Standard
28039 FSR0L:PRODH:PRODL:WREG
28045 <row topline="true" bottomline="true">
28046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28049 \begin_layout Standard
28055 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28058 \begin_layout Standard
28059 on stack, FSR0 points to the beginning
28072 \begin_layout Subsection
28076 \begin_layout Standard
28078 \begin_inset LatexCommand index
28079 name "PIC16!interrupt"
28083 service routine (ISR) is declared using the
28090 \begin_layout LyX-Code
28091 void isr(void) interrupt
28096 \begin_layout LyX-Code
28100 \begin_layout LyX-Code
28104 \begin_layout LyX-Code
28108 \begin_layout Standard
28113 is the interrupt number, which for PIC18F devices can be:
28116 \begin_layout Standard
28118 \begin_inset Tabular
28119 <lyxtabular version="3" rows="4" columns="3">
28121 <column alignment="center" valignment="top" leftline="true" width="0">
28122 <column alignment="center" valignment="top" leftline="true" width="0">
28123 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28124 <row topline="true" bottomline="true">
28125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28128 \begin_layout Standard
28136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28139 \begin_layout Standard
28145 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28148 \begin_layout Standard
28149 Interrupt Vector Address
28155 <row topline="true">
28156 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28159 \begin_layout Standard
28165 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28168 \begin_layout Standard
28174 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28177 \begin_layout Standard
28184 <row topline="true">
28185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28188 \begin_layout Standard
28203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28206 \begin_layout Standard
28216 HIGH priority interrupts
28221 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28224 \begin_layout Standard
28231 <row topline="true" bottomline="true">
28232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28235 \begin_layout Standard
28241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28244 \begin_layout Standard
28245 LOW priority interrupts
28250 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28253 \begin_layout Standard
28267 \begin_layout Standard
28268 When generating assembly code for ISR the code generator places a
28274 Interrupt Vector Address
28276 which points at the generated ISR.
28277 This single GOTO instruction is part of an automatically generated
28279 interrupt entry point
28282 The actuall ISR code is placed as normally would in the code space.
28283 Upon interrupt request, the GOTO instruction is executed which jumps to
28285 When declaring interrupt functions as _naked this GOTO instruction is
28290 The whole interrupt functions is therefore placed at the Interrupt Vector
28291 Address of the specific interrupt.
28292 This is not a problem for the LOW priority interrupts, but it is a problem
28293 for the RESET and the HIGH priority interrupts because code may be written
28294 at the next interrupt's vector address and cause indeterminate program
28295 behaviour if that interrupt is raised.
28299 \begin_layout Standard
28300 This is not a problem when
28303 \begin_layout Enumerate
28304 this is a HIGH interrupt ISR and LOW interrupts are
28311 \begin_layout Enumerate
28312 when the ISR is small enough not to reach the next interrupt's vector address.
28320 \begin_layout Standard
28326 This way a function is generated similar to an ISR, but it is not assigned
28330 \begin_layout Standard
28331 When entering an interrupt, currently the PIC16
28332 \begin_inset LatexCommand index
28337 port automatically saves the following registers:
28340 \begin_layout Itemize
28344 \begin_layout Itemize
28348 \begin_layout Itemize
28352 \begin_layout Itemize
28353 PROD (PRODL and PRODH)
28356 \begin_layout Itemize
28357 FSR0 (FSR0L and FSR0H)
28360 \begin_layout Standard
28361 These registers are restored upon return from the interrupt routine.
28365 \begin_layout Standard
28366 NOTE that when the _naked attribute is specified for an interrupt routine,
28367 then NO registers are stored or restored.
28375 \begin_layout Subsection
28379 \begin_layout Standard
28380 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
28381 There are 3 types of generic pointers currently implemented data, code
28382 and eeprom pointers.
28383 They are differentiated by the value of the 7th and 6th bits of the upper
28387 \begin_layout Standard
28389 \begin_inset Tabular
28390 <lyxtabular version="3" rows="5" columns="5">
28392 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28393 <column alignment="center" valignment="top" width="0">
28394 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28395 <column alignment="center" valignment="top" width="0">
28396 <column alignment="left" valignment="top" rightline="true" width="0">
28397 <row topline="true" bottomline="true">
28398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28401 \begin_layout Standard
28407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28410 \begin_layout Standard
28416 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28419 \begin_layout Standard
28425 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28428 \begin_layout Standard
28429 rest of the pointer
28434 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28437 \begin_layout Standard
28444 <row topline="true" bottomline="true">
28445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28448 \begin_layout Standard
28454 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28457 \begin_layout Standard
28463 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28466 \begin_layout Standard
28472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28475 \begin_layout Standard
28480 uuuuuu uuuuxxxx xxxxxxxx
28485 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28488 \begin_layout Standard
28489 a 12-bit data pointer in data RAM memory
28495 <row bottomline="true">
28496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28499 \begin_layout Standard
28505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28508 \begin_layout Standard
28514 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28517 \begin_layout Standard
28523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28526 \begin_layout Standard
28531 uxxxxx xxxxxxxx xxxxxxxx
28536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28539 \begin_layout Standard
28540 a 21-bit code pointer in FLASH memory
28546 <row bottomline="true">
28547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28550 \begin_layout Standard
28556 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28559 \begin_layout Standard
28565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28568 \begin_layout Standard
28574 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28577 \begin_layout Standard
28582 uuuuuu uuuuuuxx xxxxxxxx
28587 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28590 \begin_layout Standard
28591 a 10-bit eeprom pointer in EEPROM memory
28597 <row bottomline="true">
28598 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28601 \begin_layout Standard
28607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28610 \begin_layout Standard
28616 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28619 \begin_layout Standard
28625 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28628 \begin_layout Standard
28633 xxxxxx xxxxxxxx xxxxxxxx
28638 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28641 \begin_layout Standard
28642 unimplemented pointer type
28655 \begin_layout Standard
28657 Generic pointer are read and written with a set of library functions which
28658 read/write 1, 2, 3, 4 bytes.
28661 \begin_layout Subsection
28665 \begin_layout Subsubsection
28666 Standard I/O Streams
28669 \begin_layout Standard
28674 the type FILE is defined as:
28677 \begin_layout LyX-Code
28678 typedef char * FILE;
28681 \begin_layout Standard
28682 This type is the stream type implemented I/O in the PIC18F devices.
28683 Also the standard input and output streams are declared in stdio.h:
28686 \begin_layout LyX-Code
28687 extern FILE * stdin;
28690 \begin_layout LyX-Code
28691 extern FILE * stdout;
28694 \begin_layout Standard
28695 The FILE type is actually a generic pointer which defines one more type
28696 of generic pointers, the
28701 This new type has the format:
28704 \begin_layout Standard
28707 \begin_inset Tabular
28708 <lyxtabular version="3" rows="2" columns="7">
28710 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28711 <column alignment="center" valignment="top" width="0">
28712 <column alignment="center" valignment="top" leftline="true" width="0">
28713 <column alignment="center" valignment="top" leftline="true" width="0">
28714 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28715 <column alignment="center" valignment="top" width="0">
28716 <column alignment="left" valignment="top" rightline="true" width="0">
28717 <row topline="true" bottomline="true">
28718 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28721 \begin_layout Standard
28727 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28730 \begin_layout Standard
28736 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28739 \begin_layout Standard
28745 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28748 \begin_layout Standard
28754 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28757 \begin_layout Standard
28763 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28766 \begin_layout Standard
28767 rest of the pointer
28772 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28775 \begin_layout Standard
28782 <row topline="true" bottomline="true">
28783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28786 \begin_layout Standard
28792 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28795 \begin_layout Standard
28801 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28804 \begin_layout Standard
28810 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28813 \begin_layout Standard
28819 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28822 \begin_layout Standard
28828 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28831 \begin_layout Standard
28841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28844 \begin_layout Standard
28845 upper byte high nubble is 0x2n, the rest are zeroes
28858 \begin_layout Standard
28860 Currently implemented there are 3 types of streams defined:
28863 \begin_layout Standard
28866 \begin_inset Tabular
28867 <lyxtabular version="3" rows="4" columns="4">
28869 <column alignment="center" valignment="top" leftline="true" width="0">
28870 <column alignment="center" valignment="top" leftline="true" width="0">
28871 <column alignment="center" valignment="top" leftline="true" width="0">
28872 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28873 <row topline="true" bottomline="true">
28874 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28877 \begin_layout Standard
28883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28886 \begin_layout Standard
28892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28895 \begin_layout Standard
28901 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28904 \begin_layout Standard
28911 <row topline="true">
28912 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28915 \begin_layout Standard
28921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28924 \begin_layout Standard
28932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28935 \begin_layout Standard
28941 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28944 \begin_layout Standard
28945 Writes/Reads characters via the USART peripheral
28951 <row topline="true">
28952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28955 \begin_layout Standard
28961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28964 \begin_layout Standard
28972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28975 \begin_layout Standard
28981 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28984 \begin_layout Standard
28985 Writes/Reads characters via the MSSP peripheral
28991 <row topline="true" bottomline="true">
28992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28995 \begin_layout Standard
29001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29004 \begin_layout Standard
29012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29015 \begin_layout Standard
29021 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29024 \begin_layout Standard
29025 Writes/Reads characters via used defined functions
29038 \begin_layout Standard
29040 The stream identifiers are declared as macros in the stdio.h header.
29043 \begin_layout Standard
29045 In the libc library there exist the functions that are used to write to
29046 each of the above streams.
29050 \begin_layout Description
29055 \begin_layout Standard
29064 _stream_usart_putchar writes a character at the USART stream
29067 \begin_layout Description
29072 \begin_layout Standard
29081 _stream_mssp_putchar writes a character at the MSSP stream
29084 \begin_layout Description
29085 putchar dummy function.
29086 This writes a character to a user specified manner.
29089 \begin_layout Standard
29090 In order to increase performance
29094 is declared in stdio.h as having its parameter in WREG (it has the wparam
29096 In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
29097 in a user-friendly way.
29102 is the name of the variable that holds the character to print.
29103 An example follows:
29106 \begin_layout LyX-Code
29107 #include <pic18fregs.h>
29116 \begin_layout LyX-Code
29120 \begin_layout LyX-Code
29121 PORTA = c; /* dump character c to PORTA */
29124 \begin_layout LyX-Code
29132 \begin_layout LyX-Code
29136 \begin_layout LyX-Code
29137 stdout = STREAM_USER; /* this is not necessary, since stdout points
29140 \begin_layout LyX-Code
29141 * by default to STREAM_USER */
29144 \begin_layout LyX-Code
29146 \begin_inset Quotes sld
29149 This is a printf test
29152 \begin_inset Quotes srd
29158 \begin_layout LyX-Code
29162 \begin_layout LyX-Code
29166 \begin_layout Subsubsection
29170 \begin_layout Standard
29171 PIC16 contains an implementation of the printf-family of functions.
29172 There exist the following functions:
29175 \begin_layout LyX-Code
29176 extern unsigned int sprintf(char *buf, char *fmt, ...);
29179 \begin_layout LyX-Code
29180 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
29183 \begin_layout LyX-Code
29187 \begin_layout LyX-Code
29188 extern unsigned int printf(char *fmt, ...);
29191 \begin_layout LyX-Code
29192 extern unsigned int vprintf(char *fmt, va_lista ap);
29195 \begin_layout LyX-Code
29199 \begin_layout LyX-Code
29200 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
29203 \begin_layout LyX-Code
29204 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
29207 \begin_layout Standard
29208 For sprintf and vsprintf
29212 should normally be a data pointer where the resulting string will be placed.
29213 No range checking is done so the user should allocate the necessary buffer.
29214 For fprintf and vfprintf
29218 should be a stream pointer (i.e.
29219 stdout, STREAM_MSSP, etc...).
29222 \begin_layout Subsubsection
29226 \begin_layout Standard
29227 The PIC18F family of microcontrollers supports a number of interrupt sources.
29228 A list of these interrupts is shown in the following table:
29231 \begin_layout Standard
29233 \begin_inset Tabular
29234 <lyxtabular version="3" rows="11" columns="4">
29236 <column alignment="left" valignment="top" leftline="true" width="0">
29237 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
29238 <column alignment="left" valignment="top" leftline="true" width="0">
29239 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
29240 <row topline="true" bottomline="true">
29241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29244 \begin_layout Standard
29250 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29253 \begin_layout Standard
29259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29262 \begin_layout Standard
29268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29271 \begin_layout Standard
29278 <row topline="true">
29279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29282 \begin_layout Standard
29288 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29291 \begin_layout Standard
29292 PORTB change interrupt
29297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29300 \begin_layout Standard
29306 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29309 \begin_layout Standard
29310 EEPROM/FLASH write complete interrupt
29316 <row topline="true">
29317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29320 \begin_layout Standard
29326 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29329 \begin_layout Standard
29330 INT0 external interrupt
29335 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29338 \begin_layout Standard
29344 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29347 \begin_layout Standard
29348 Bus collision interrupt
29354 <row topline="true">
29355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29358 \begin_layout Standard
29364 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29367 \begin_layout Standard
29368 INT1 external interrupt
29373 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29376 \begin_layout Standard
29382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29385 \begin_layout Standard
29386 Low voltage detect interrupt
29392 <row topline="true">
29393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29396 \begin_layout Standard
29402 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29405 \begin_layout Standard
29406 INT2 external interrupt
29411 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29414 \begin_layout Standard
29420 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29423 \begin_layout Standard
29424 Parallel slave port interrupt
29430 <row topline="true">
29431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29434 \begin_layout Standard
29440 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29443 \begin_layout Standard
29444 CCP1 module interrupt
29449 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29452 \begin_layout Standard
29458 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29461 \begin_layout Standard
29462 AD convertion complete interrupt
29468 <row topline="true">
29469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29472 \begin_layout Standard
29478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29481 \begin_layout Standard
29482 CCP2 module interrupt
29487 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29490 \begin_layout Standard
29496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29499 \begin_layout Standard
29500 USART receive interrupt
29506 <row topline="true">
29507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29510 \begin_layout Standard
29516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29519 \begin_layout Standard
29520 TMR0 overflow interrupt
29525 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29528 \begin_layout Standard
29534 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29537 \begin_layout Standard
29538 USART transmit interrupt
29544 <row topline="true">
29545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29548 \begin_layout Standard
29554 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29557 \begin_layout Standard
29558 TMR1 overflow interrupt
29563 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29566 \begin_layout Standard
29572 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29575 \begin_layout Standard
29576 SSP receive/transmit interrupt
29582 <row topline="true">
29583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29586 \begin_layout Standard
29592 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29595 \begin_layout Standard
29596 TMR2 matches PR2 interrupt
29601 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29604 \begin_layout Standard
29610 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29613 \begin_layout Standard
29620 <row topline="true" bottomline="true">
29621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29624 \begin_layout Standard
29630 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29633 \begin_layout Standard
29634 TMR3 overflow interrupt
29639 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29642 \begin_layout Standard
29648 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29651 \begin_layout Standard
29665 \begin_layout Standard
29667 The prototypes for these names are defined in the header file
29674 \begin_layout Standard
29676 In order to simplify signal handling, a number of macros is provided:
29680 \labelwidthstring 00.00.0000
29681 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
29682 high priority interrupts.
29687 is the function name to use.
29691 \labelwidthstring 00.00.0000
29692 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
29693 low priority interrupt.
29698 is the function name to use.
29702 \labelwidthstring 00.00.0000
29703 DEF_HANDLER(sig,handler) define a handler for signal
29709 \labelwidthstring 00.00.0000
29710 END_DEF end the declaration of the dispatch table.
29713 \begin_layout Standard
29714 Additionally there are two more macros to simplify the declaration of the
29719 \labelwidthstring 00.00.0000
29722 SIGHANDLER(handler)
29724 this declares the function prototype for the
29732 \labelwidthstring 00.00.0000
29733 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
29736 \begin_layout Standard
29737 An example of using the macros above is shown below:
29740 \begin_layout LyX-Code
29741 #include <pic18fregs.h>
29744 \begin_layout LyX-Code
29745 #include <signal.h>
29749 DEF_INTHIGH(high_int)
29752 \begin_layout LyX-Code
29753 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
29756 \begin_layout LyX-Code
29757 DEF_HANDLER(SIG_BCOL, _bcol_handler)
29760 \begin_layout LyX-Code
29765 SIGHANDLER(_tmr0_handler)
29768 \begin_layout LyX-Code
29772 \begin_layout LyX-Code
29773 /* action to be taken when timer 0 overflows */
29776 \begin_layout LyX-Code
29781 SIGHANDLERNAKED(_bcol_handler)
29784 \begin_layout LyX-Code
29788 \begin_layout LyX-Code
29792 \begin_layout LyX-Code
29793 /* action to be taken when bus collision occurs */
29796 \begin_layout LyX-Code
29800 \begin_layout LyX-Code
29804 \begin_layout LyX-Code
29808 \begin_layout Standard
29813 Special care should be taken when using the above scheme:
29816 \begin_layout Itemize
29817 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
29820 \begin_layout Itemize
29821 when declaring SIGHANDLERNAKED handler never forget to use
29825 for proper returning.
29828 \begin_layout Subsection
29832 \begin_layout Standard
29833 Here you can find some general tips for compiling programs with SDCC/pic16.
29836 \begin_layout Subsubsection
29840 \begin_layout Standard
29842 \begin_inset LatexCommand index
29847 size (that is 64 bytes) probably is enough for many programs.
29848 One must take care that when there are many levels of function nesting,
29849 or there is excessive usage of stack, its size should be extended.
29850 An example of such a case is the printf/sprintf family of functions.
29851 If you encounter problems like not being able to print integers, then you
29852 need to set the stack size around the maximum (256 for small stack model).
29853 The following diagram shows what happens when calling printf to print an
29857 \begin_layout LyX-Code
29858 printf () --> ltoa () --> ultoa () --> divschar ()
29861 \begin_layout Standard
29862 It is should be understood that stack is easily consumed when calling complicate
29864 Using command line arguments like -
29868 \begin_layout Standard
29877 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
29879 Other ways to reduce stack usage may exist.
29882 \begin_layout Subsection
29886 \begin_layout Subsubsection
29887 Extended Instruction Set
29890 \begin_layout Standard
29891 The PIC16 port emits code which is incompatible with the extended instruction
29892 set available with many newer devices.
29893 Make sure to always explicitly disable it, usually using
29896 \begin_layout Standard
29899 static __code char __at(__CONFIG4L) conf4l = /* more flags & */ _XINST_OFF_4L;
29902 \begin_layout Standard
29904 Some devices (namely 18f2455, 18f2550, 18f4455, and 18f4550) use _ENHCPU_OFF_4L
29905 instead of _XINST_OFF_4L.
29908 \begin_layout Subsubsection
29912 \begin_layout Standard
29913 The PIC16 port currently passes most but not all of the tests in SDCC's
29915 \begin_inset LatexCommand index
29916 name "Regression test (PIC16)"
29921 \begin_inset LatexCommand ref
29922 reference "sec:Quality-control"
29926 ), thus no automatic regression tests are currently performed for the PIC16
29930 \begin_layout Chapter
29934 \begin_layout Standard
29935 There are several approaches to debugging your code.
29936 This chapter is meant to show your options and to give detail on some of
29941 When writing your code:
29944 \begin_layout Itemize
29945 write your code with debugging in mind (avoid duplicating code, put conceptually
29946 similar variables into structs, use structured code, have strategic points
29947 within your code where all variables are consistent, ...)
29950 \begin_layout Itemize
29951 run a syntax-checking tool like splint
29952 \begin_inset LatexCommand index
29953 name "splint (syntax checking tool)"
29958 \begin_inset LatexCommand index
29959 name "lint (syntax checking tool)"
29967 \begin_layout Standard
29977 \begin_inset LatexCommand ref
29978 reference "lyx:more-pedantic-SPLINT"
29985 \begin_layout Itemize
29986 for the high level code use a C-compiler (like f.e.
29987 GCC) to compile run and debug the code on your host.
29992 \begin_layout Standard
30002 \begin_inset LatexCommand ref
30003 reference "lyx:more-pedantic-SPLINT"
30007 ) on how to handle syntax extensions like __xdata, __at(), ...
30011 \begin_layout Itemize
30012 use another C-compiler to compile code for your target.
30013 Always an option but not recommended:) And not very likely to help you.
30014 If you seriously consider walking this path you should at least occasionally
30015 check portability of your code.
30016 Most commercial compiler vendors will offer an evaluation version so you
30017 can test compile your code or snippets of your code.
30020 \begin_layout Standard
30021 Debugging on a simulator:
30024 \begin_layout Itemize
30025 there is a separate section about SDCDB (section
30026 \begin_inset LatexCommand ref
30027 reference "cha:Debugging-with-SDCDB"
30034 \begin_layout Itemize
30035 or (8051 specific) use a freeware/commercial simulator which interfaces
30037 \begin_inset LatexCommand index
30038 name "AOMF, AOMF51"
30043 \begin_inset LatexCommand ref
30044 reference "OMF file"
30048 ) optionally generated by SDCC.
30051 \begin_layout Standard
30052 Debugging On-target:
30055 \begin_layout Itemize
30056 use a MCU port pin to serially output debug data to the RS232 port of your
30058 You'll probably want some level shifting device typically involving a MAX232
30060 If the hardware serial port of the MCU is not available search for 'Software
30061 UART' in your favourite search machine.
30064 \begin_layout Itemize
30065 use an on-target monitor.
30066 In this context a monitor is a small program which usually accepts commands
30067 via a serial line and allows to set program counter, to single step through
30068 a program and read/write memory locations.
30069 For the 8051 good examples of monitors are paulmon and cmon51 (see section
30071 \begin_inset LatexCommand ref
30072 reference "sec:Related-open-source-tools"
30079 \begin_layout Itemize
30080 toggle MCU port pins at strategic points within your code and use an oscilloscop
30084 digital oscilloscope
30087 \begin_inset LatexCommand index
30088 name "Oscilloscope"
30092 with deep trace memory is really helpful especially if you have to debug
30093 a realtime application.
30094 If you need to monitor more pins than your oscilloscope provides you can
30095 sometimes get away with a small R-2R network.
30096 On a single channel oscilloscope you could f.e.
30097 monitor 2 push-pull driven pins by connecting one via a 10\InsetSpace ~
30099 \begin_inset Formula $\Omega$
30102 resistor and the other one by a 5\InsetSpace ~
30104 \begin_inset Formula $\Omega$
30107 resistor to the oscilloscope probe (check output drive capability of the
30108 pins you want to monitor).
30109 If you need to monitor many more pins a
30116 \begin_layout Itemize
30130 \begin_inset LatexCommand index
30131 name "ICE (in circuit emulator)"
30136 Usually very expensive.
30137 And very nice to have too.
30138 And usually locks you (for years...) to the devices the ICE can emulate.
30142 \begin_layout Itemize
30143 use a remote debugger.
30144 In most 8-bit systems the symbol information is not available on the target,
30145 and a complete debugger is too bulky for the target system.
30146 Therefore usually a debugger on the host system connects to an on-target
30147 debugging stub which accepts only primitive commands.
30150 Terms to enter into your favourite search engine could be 'remote debugging',
30151 'gdb stub' or 'inferior debugger'.
30155 \begin_layout Itemize
30156 use an on target hardware debugger.
30157 Some of the more modern MCUs include hardware support for setting break
30158 points and monitoring/changing variables by using dedicated hardware pins.
30159 This facility doesn't require additional code to run on the target and
30164 doesn't affect runtime behaviour until a breakpoint is hit.
30165 For the mcs51 most hardware debuggers use the AOMF
30166 \begin_inset LatexCommand index
30167 name "AOMF, AOMF51"
30172 \begin_inset LatexCommand ref
30173 reference "OMF file"
30181 \begin_layout Standard
30185 \begin_layout Itemize
30186 if you are not familiar with any of the following terms you're likely to
30187 run into problems rather sooner than later:
30204 As an embedded programmer you
30208 to know them so why not look them up
30212 you have problems?)
30215 \begin_layout Itemize
30216 tell someone else about your problem (actually this is a surprisingly effective
30217 means to hunt down the bug even if the listener is not familiar with your
30219 As 'failure to communicate' is probably one of the job-induced deformations
30220 of an embedded programmer this is highly encouraged.
30223 \begin_layout Section
30224 Debugging with SDCDB
30225 \begin_inset LatexCommand label
30226 name "cha:Debugging-with-SDCDB"
30231 \begin_inset LatexCommand index
30232 name "SDCDB (debugger)"
30239 \begin_layout Standard
30240 SDCC is distributed with a source level debugger
30241 \begin_inset LatexCommand index
30247 The debugger uses a command line interface, the command repertoire of the
30248 debugger has been kept as close to gdb
30249 \begin_inset LatexCommand index
30254 (the GNU debugger) as possible.
30255 The configuration and build process is part of the standard compiler installati
30256 on, which also builds and installs the debugger in the target directory
30257 specified during configuration.
30258 The debugger allows you debug BOTH at the C source and at the ASM source
30262 \begin_layout Subsection
30263 Compiling for Debugging
30266 \begin_layout Standard
30271 \begin_layout Standard
30281 \begin_inset LatexCommand index
30286 option must be specified for all files for which debug information is to
30288 The compiler generates a .adb file for each of these files.
30289 The linker creates the .cdb
30290 \begin_inset LatexCommand index
30296 \begin_inset LatexCommand index
30301 files and the address information.
30302 This .cdb is used by the debugger.
30305 \begin_layout Subsection
30306 How the Debugger Works
30309 \begin_layout Standard
30314 \begin_layout Standard
30323 -debug option is specified the compiler generates extra symbol information
30324 some of which are put into the assembler source and some are put into the
30326 Then the linker creates the .cdb file from the individual .adb files with
30327 the address information for the symbols.
30328 The debugger reads the symbolic information generated by the compiler &
30329 the address information generated by the linker.
30330 It uses the SIMULATOR (Daniel's S51) to execute the program, the program
30331 execution is controlled by the debugger.
30332 When a command is issued for the debugger, it translates it into appropriate
30333 commands for the simulator.
30334 (Currently SDCDM only connects to the simulator but
30339 \begin_inset LatexCommand url
30340 target "http://ec2drv.sf.net/"
30344 is an effort to connect directly to the hardware.)
30347 \begin_layout Subsection
30348 Starting the Debugger SDCDB
30351 \begin_layout Standard
30352 The debugger can be started using the following command line.
30353 (Assume the file you are debugging has the file name foo).
30367 The debugger will look for the following files.
30370 \begin_layout Itemize
30371 foo.c - the source file.
30374 \begin_layout Itemize
30375 foo.cdb - the debugger symbol information file.
30378 \begin_layout Itemize
30379 foo.ihx - the Intel hex format
30380 \begin_inset LatexCommand index
30381 name "Intel hex format"
30388 \begin_layout Subsection
30389 SDCDB Command Line Options
30392 \begin_layout Itemize
30397 \begin_layout Standard
30406 -directory=<source file directory> this option can used to specify the directory
30408 The debugger will look into the directory list specified for source, cdb
30410 The items in the directory list must be separated by ':', e.g.
30411 if the source files can be in the directories /home/src1 and /home/src2,
30416 \begin_layout Standard
30425 -directory option should be -
30429 \begin_layout Standard
30438 -directory=/home/src1:/home/src2.
30439 Note there can be no spaces in the option.
30443 \begin_layout Itemize
30444 -cd <directory> - change to the <directory>.
30447 \begin_layout Itemize
30448 -fullname - used by GUI front ends.
30451 \begin_layout Itemize
30452 -cpu <cpu-type> - this argument is passed to the simulator please see the
30453 simulator docs for details.
30456 \begin_layout Itemize
30457 -X <Clock frequency > this options is passed to the simulator please see
30458 the simulator docs for details.
30461 \begin_layout Itemize
30462 -s <serial port file> passed to simulator see the simulator docs for details.
30465 \begin_layout Itemize
30466 -S <serial in,out> passed to simulator see the simulator docs for details.
30469 \begin_layout Itemize
30470 -k <port number> passed to simulator see the simulator docs for details.
30473 \begin_layout Subsection
30474 SDCDB Debugger Commands
30477 \begin_layout Standard
30478 As mentioned earlier the command interface for the debugger has been deliberatel
30479 y kept as close the GNU debugger gdb, as possible.
30480 This will help the integration with existing graphical user interfaces
30481 (like ddd, xxgdb or xemacs) existing for the GNU debugger.
30482 If you use a graphical user interface for the debugger you can skip this
30486 \begin_layout Subsubsection*
30487 break [line | file:line | function | file:function]
30490 \begin_layout Standard
30491 Set breakpoint at specified line or function:
30500 sdcdb>break foo.c:100
30502 sdcdb>break funcfoo
30504 sdcdb>break foo.c:funcfoo
30507 \begin_layout Subsubsection*
30508 clear [line | file:line | function | file:function ]
30511 \begin_layout Standard
30512 Clear breakpoint at specified line or function:
30521 sdcdb>clear foo.c:100
30523 sdcdb>clear funcfoo
30525 sdcdb>clear foo.c:funcfoo
30528 \begin_layout Subsubsection*
30532 \begin_layout Standard
30533 Continue program being debugged, after breakpoint.
30536 \begin_layout Subsubsection*
30540 \begin_layout Standard
30541 Execute till the end of the current function.
30544 \begin_layout Subsubsection*
30548 \begin_layout Standard
30549 Delete breakpoint number 'n'.
30550 If used without any option clear ALL user defined break points.
30553 \begin_layout Subsubsection*
30554 info [break | stack | frame | registers ]
30557 \begin_layout Itemize
30558 info break - list all breakpoints
30561 \begin_layout Itemize
30562 info stack - show the function call stack.
30565 \begin_layout Itemize
30566 info frame - show information about the current execution frame.
30569 \begin_layout Itemize
30570 info registers - show content of all registers.
30573 \begin_layout Subsubsection*
30577 \begin_layout Standard
30578 Step program until it reaches a different source line.
30579 Note: pressing <return> repeats the last command.
30582 \begin_layout Subsubsection*
30586 \begin_layout Standard
30587 Step program, proceeding through subroutine calls.
30590 \begin_layout Subsubsection*
30594 \begin_layout Standard
30595 Start debugged program.
30598 \begin_layout Subsubsection*
30602 \begin_layout Standard
30603 Print type information of the variable.
30606 \begin_layout Subsubsection*
30610 \begin_layout Standard
30611 print value of variable.
30614 \begin_layout Subsubsection*
30618 \begin_layout Standard
30619 load the given file name.
30620 Note this is an alternate method of loading file for debugging.
30623 \begin_layout Subsubsection*
30627 \begin_layout Standard
30628 print information about current frame.
30631 \begin_layout Subsubsection*
30635 \begin_layout Standard
30636 Toggle between C source & assembly source.
30639 \begin_layout Subsubsection*
30640 ! simulator command
30643 \begin_layout Standard
30644 Send the string following '!' to the simulator, the simulator response is
30646 Note the debugger does not interpret the command being sent to the simulator,
30647 so if a command like 'go' is sent the debugger can loose its execution
30648 context and may display incorrect values.
30651 \begin_layout Subsubsection*
30655 \begin_layout Standard
30658 My name is Bobby Brown"
30661 \begin_layout Subsection
30662 Interfacing SDCDB with DDD
30665 \begin_layout Standard
30666 \begin_inset Note Note
30669 \begin_layout Standard
30670 The screenshot was converted from png to eps with:
30671 \begin_inset Quotes sld
30674 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
30675 \begin_inset Quotes srd
30678 which produces a pretty compact eps file which is free from compression
30682 \begin_layout Standard
30683 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
30684 as this broke the build system on Sourceforge (pdf-file was broken.
30685 pdflatex does not accept eps files).
30693 \begin_layout Standard
30709 \begin_inset LatexCommand url
30710 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png"
30716 shows a screenshot of a debugging session with DDD
30717 \begin_inset LatexCommand index
30718 name "DDD (debugger)"
30722 (Unix only) on a simulated 8032.
30723 The debugging session might not run as smoothly as the screenshot suggests.
30724 The debugger allows setting of breakpoints, displaying and changing variables,
30725 single stepping through C and assembler code.
30728 The source was compiled with
30742 \begin_layout Standard
30754 -debug ddd_example.c
30767 and DDD was invoked with
30774 ddd -debugger "sdcdb -cpu 8032 ddd_example"
30777 \begin_layout Standard
30778 \begin_inset Note Note
30781 \begin_layout Standard
30782 Check that the double quotes or an apostrophe within the command line survive
30783 the LyX tool chain.
30784 Previously the apostrophes got slanted in the PDF output so a cut and paste
30793 \begin_layout Subsection
30794 Interfacing SDCDB with XEmacs
30795 \begin_inset LatexCommand index
30801 \begin_inset LatexCommand index
30809 \begin_layout Standard
30810 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
30811 sdcdb.el and sdcdbsrc.el.
30812 These two files can be found in the $(prefix)/bin directory after the installat
30814 These files need to be loaded into XEmacs for the interface to work.
30815 This can be done at XEmacs startup time by inserting the following into
30816 your '.xemacs' file (which can be found in your HOME directory):
30822 (load-file sdcdbsrc.el)
30828 .xemacs is a lisp file so the () around the command is REQUIRED.
30829 The files can also be loaded dynamically while XEmacs is running, set the
30830 environment variable 'EMACSLOADPATH' to the installation bin directory
30831 (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
30832 To start the interface enter the following command:
30846 You will prompted to enter the file name to be debugged.
30851 The command line options that are passed to the simulator directly are
30852 bound to default values in the file sdcdbsrc.el.
30853 The variables are listed below, these values maybe changed as required.
30856 \begin_layout Itemize
30857 sdcdbsrc-cpu-type '51
30860 \begin_layout Itemize
30861 sdcdbsrc-frequency '11059200
30864 \begin_layout Itemize
30865 sdcdbsrc-serial nil
30868 \begin_layout Standard
30869 The following is a list of key mapping for the debugger interface.
30872 \begin_layout Standard
30895 binding\InsetSpace ~
30933 -------\InsetSpace ~
31004 sdcdb-back-from-src\InsetSpace ~
31033 rom-src\InsetSpace ~
31043 SDCDB continue command
31061 sdcdb-step-from-src\InsetSpace ~
31090 hatis-c-sexp\InsetSpace ~
31100 SDCDB ptypecommand for data at
31167 sdcdbsrc-delete\InsetSpace ~
31182 B Delete all breakpoints if no arg
31231 given or delete arg (C-u arg x)
31250 -frame\InsetSpace ~
31265 SDCDB Display current frame if no arg,
31314 given or display frame arg
31382 sdcdbsrc-goto-sdcdb\InsetSpace ~
31392 Goto the SDCDB output buffer
31411 t-c-sexp\InsetSpace ~
31422 SDCDB print command for data at
31489 sdcdbsrc-goto-sdcdb\InsetSpace ~
31500 o the SDCDB output buffer
31518 sdcdbsrc-mode\InsetSpace ~
31534 Toggles Sdcdbsrc mode (turns it
31550 sdcdb-finish-from-src\InsetSpace ~
31558 SDCDB finish command
31592 Set break for line with point
31607 sdcdbsrc-mode\InsetSpace ~
31623 Toggle Sdcdbsrc mode
31639 dbsrc-srcmode\InsetSpace ~
31663 \begin_layout Chapter
31667 \begin_layout Standard
31668 Here are a few guidelines that will help the compiler generate more efficient
31669 code, some of the tips are specific to this compiler others are generally
31670 good programming practice.
31673 \begin_layout Itemize
31674 Use the smallest data type to represent your data-value.
31675 If it is known in advance that the value is going to be less than 256 then
31676 use an 'unsigned char' instead of a 'short' or 'int'.
31677 Please note, that ANSI C requires both signed and unsigned chars to be
31678 promoted to 'signed int'
31679 \begin_inset LatexCommand index
31680 name "promotion to signed int"
31685 \begin_inset Marginal
31688 \begin_layout Standard
31697 before doing any operation.
31699 \begin_inset LatexCommand index
31700 name "type promotion"
31705 \begin_inset LatexCommand label
31706 name "type promotion"
31710 can be omitted, if the result is the same.
31711 The effect of the promotion rules together with the sign-extension is often
31716 \begin_layout Verse
31719 unsigned char uc = 0xfe;
31721 if (uc * uc < 0) /* this is true! */
31734 \begin_layout Standard
31741 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
31749 \begin_layout Verse
31752 (unsigned char) -12 / (signed char) -3 = ...
31755 \begin_layout Standard
31756 No, the result is not 4:
31759 \begin_layout Verse
31762 (int) (unsigned char) -12 / (int) (signed char) -3 =
31764 (int) (unsigned char)
31765 0xf4 / (int) (signed char) 0xfd =
31767 (int) 0x00f4 / (int) 0xfffd =
31772 (int) 244 / (int) -3 =
31774 (int) -81 = (int) 0xffaf;
31777 \begin_layout Standard
31778 Don't complain, that gcc gives you a different result.
31779 gcc uses 32 bit ints, while SDCC uses 16 bit ints.
31780 Therefore the results are different.
31783 \begin_inset Quotes sld
31787 \begin_inset Quotes srd
31793 \begin_layout Quote
31796 If well-defined overflow characteristics are important and negative values
31797 are not, or if you want to steer clear of sign-extension problems when
31798 manipulating bits or bytes, use one of the corresponding unsigned types.
31799 (Beware when mixing signed and unsigned values in expressions, though.)
31802 character types (especially unsigned char) can be used as "tiny" integers,
31803 doing so is sometimes more trouble than it's worth, due to unpredictable
31804 sign extension and increased code size.
31808 \begin_layout Itemize
31809 Use unsigned when it is known in advance that the value is not going to
31811 This helps especially if you are doing division or multiplication, bit-shifting
31812 or are using an array index.
31815 \begin_layout Itemize
31816 NEVER jump into a LOOP.
31819 \begin_layout Itemize
31820 Declare the variables to be local
31821 \begin_inset LatexCommand index
31822 name "local variables"
31826 whenever possible, especially loop control variables (induction).
31829 \begin_layout Itemize
31830 Have a look at the assembly listing to get a
31831 \begin_inset Quotes sld
31835 \begin_inset Quotes srd
31838 for the code generation.
31841 \begin_layout Section
31842 Porting code from or to other compilers
31843 \begin_inset LatexCommand label
31844 name "sec:Porting-code-to-other-compilers"
31851 \begin_layout Itemize
31852 check whether endianness of the compilers differs and adapt where needed.
31855 \begin_layout Itemize
31856 check the device specific header files
31857 \begin_inset LatexCommand index
31858 name "Header files"
31863 \begin_inset LatexCommand index
31864 name "Include files"
31868 for compiler specific syntax.
31869 Eventually include the file <compiler.h
31870 \begin_inset LatexCommand index
31871 name "compiler.h (include file)"
31876 \begin_inset LatexCommand url
31877 target "http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/compiler.h?view=markup"
31881 to allow using common header files.
31884 \begin_inset LatexCommand url
31885 target "http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/cc2510fx.h?view=markup"
31892 \begin_layout Itemize
31893 check whether the startup code contains the correct initialization (watchdog,
31897 \begin_layout Itemize
31898 check whether the sizes of short, int, long match.
31901 \begin_layout Itemize
31902 check if some 16 or 32 bit hardware registers require a specific addressing
31903 order (least significant or most significant byte first) and adapt if needed
31912 relate to time and not to lower/upper memory location here, so this is
31917 the same as endianness).
31920 \begin_layout Itemize
31921 check whether the keyword
31925 is used where needed.
31926 The compilers might differ in their optimization characteristics (as different
31927 versions of the same compiler might also use more clever optimizations
31928 this is good idea anyway).
31930 \begin_inset LatexCommand ref
31931 reference "sub:Common-interrupt-pitfall-volatile"
31938 \begin_layout Itemize
31939 check that the compilers are not told to suppress warnings.
31942 \begin_layout Itemize
31943 check and convert compiler specific extensions (interrupts, memory areas,
31947 \begin_layout Itemize
31948 check for differences in type promotion.
31949 Especially check for math operations on
31958 For the sake of C99 compatibility SDCC will probably promote these to
31962 more often than other compilers.
31963 Eventually insert explicit casts to
31972 Also check that the ~\InsetSpace ~
31974 \begin_inset LatexCommand index
31975 name "\\~\\/ Operator"
31982 \begin_inset LatexCommand index
31989 variables, use the !\InsetSpace ~
31992 \begin_inset LatexCommand ref
31993 reference "type promotion"
31998 \begin_inset LatexCommand ref
31999 reference "sec:Compatibility-with-previous"
32006 \begin_layout Itemize
32007 check the assembly code generated for interrupt routines (f.e.
32008 for calls to possibly non-reentrant library functions).
32011 \begin_layout Itemize
32012 check whether timing loops result in proper timing (or preferably consider
32013 a rewrite of the code with timer based delays instead).
32016 \begin_layout Itemize
32017 check for differences in printf parameters (some compilers push (va_arg
32018 \begin_inset LatexCommand index
32019 name "vararg, va\\_arg"
32023 ) char variables as
32027 others push them as
32033 \begin_inset LatexCommand ref
32034 reference "sec:Compatibility-with-previous"
32041 \begin_layout Itemize
32042 check the resulting memory map
32043 \begin_inset LatexCommand index
32049 Usage of different memory spaces: code, stack, data (for mcs51/ds390 additional
32050 ly idata, pdata, xdata).
32051 Eventually check if unexpected library functions are included.
32054 \begin_layout Section
32056 \begin_inset LatexCommand index
32061 included in the distribution
32064 \begin_layout Standard
32066 \begin_inset Tabular
32067 <lyxtabular version="3" rows="12" columns="3">
32069 <column alignment="left" valignment="top" leftline="true" width="0pt">
32070 <column alignment="left" valignment="top" leftline="true" width="0pt">
32071 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
32072 <row topline="true" bottomline="true">
32073 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32076 \begin_layout Standard
32084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32087 \begin_layout Standard
32095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32098 \begin_layout Standard
32107 <row topline="true">
32108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32111 \begin_layout Standard
32113 \begin_inset LatexCommand index
32123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32126 \begin_layout Standard
32127 Simulator for various architectures
32132 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32135 \begin_layout Standard
32142 <row topline="true">
32143 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32146 \begin_layout Standard
32152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32155 \begin_layout Standard
32157 \begin_inset LatexCommand index
32158 name "Header files"
32163 \begin_inset LatexCommand index
32164 name "Include files"
32173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32176 \begin_layout Standard
32177 sdcc/support/scripts
32183 <row topline="true">
32184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32187 \begin_layout Standard
32193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32196 \begin_layout Standard
32197 header file conversion
32202 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32205 \begin_layout Standard
32206 sdcc/support/scripts
32212 <row topline="true">
32213 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32216 \begin_layout Standard
32222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32225 \begin_layout Standard
32231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32234 \begin_layout Standard
32250 <row topline="true">
32251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32254 \begin_layout Standard
32260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32263 \begin_layout Standard
32269 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32272 \begin_layout Standard
32288 <row topline="true">
32289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32292 \begin_layout Standard
32298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32301 \begin_layout Standard
32307 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32310 \begin_layout Standard
32326 <row topline="true">
32327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32330 \begin_layout Standard
32336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32339 \begin_layout Standard
32345 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32348 \begin_layout Standard
32364 <row topline="true">
32365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32368 \begin_layout Standard
32374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32377 \begin_layout Standard
32383 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32386 \begin_layout Standard
32402 <row topline="true">
32403 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32406 \begin_layout Standard
32412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32415 \begin_layout Standard
32421 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32424 \begin_layout Standard
32440 <row topline="true">
32441 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32444 \begin_layout Standard
32450 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32453 \begin_layout Standard
32459 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32462 \begin_layout Standard
32478 <row topline="true" bottomline="true">
32479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32482 \begin_layout Standard
32488 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32491 \begin_layout Standard
32493 \begin_inset LatexCommand index
32494 name "packihx (tool)"
32503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32506 \begin_layout Standard
32531 \begin_layout Section
32533 \begin_inset LatexCommand index
32534 name "Documentation"
32538 included in the distribution
32541 \begin_layout Standard
32543 \begin_inset Tabular
32544 <lyxtabular version="3" rows="10" columns="2">
32546 <column alignment="block" valignment="top" leftline="true" width="40col%">
32547 <column alignment="block" valignment="top" leftline="true" rightline="true" width="60col%">
32548 <row topline="true" bottomline="true" endhead="true">
32549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32552 \begin_layout Standard
32560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32563 \begin_layout Standard
32566 Filename / Where to get
32572 <row topline="true">
32573 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32576 \begin_layout Standard
32577 SDCC Compiler User Guide
32582 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32585 \begin_layout Standard
32586 You're reading it right now
32598 \begin_inset LatexCommand url
32599 target "http://sdcc.sourceforge.net/doc/sdccman.pdf"
32609 <row topline="true">
32610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32613 \begin_layout Standard
32619 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32622 \begin_layout Standard
32635 \begin_inset LatexCommand url
32636 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/ChangeLog"
32646 <row topline="true">
32647 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32650 \begin_layout Standard
32652 \begin_inset LatexCommand index
32653 name "asXXXX (as-gbz80, as-hc08, asx8051, as-z80)"
32658 \begin_inset LatexCommand index
32659 name "Assembler documentation"
32666 \begin_inset LatexCommand index
32672 \begin_inset LatexCommand index
32673 name "Linker documentation"
32682 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32685 \begin_layout Standard
32686 sdcc/as/doc/asxhtm.html
32698 \begin_inset LatexCommand url
32699 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html"
32709 <row topline="true">
32710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32713 \begin_layout Standard
32714 SDCC regression test
32715 \begin_inset LatexCommand index
32716 name "Regression test"
32725 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32728 \begin_layout Standard
32729 sdcc/doc/test_suite_spec.pdf
32741 \begin_inset LatexCommand url
32742 target "http://sdcc.sourceforge.net/doc/test_suite_spec.pdf"
32752 <row topline="true">
32753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32756 \begin_layout Standard
32762 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32765 \begin_layout Standard
32778 \begin_inset LatexCommand url
32779 target "http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/doc/"
32789 <row topline="true">
32790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32793 \begin_layout Standard
32794 Notes on debugging with SDCDB
32795 \begin_inset LatexCommand index
32796 name "SDCDB (debugger)"
32805 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32808 \begin_layout Standard
32809 sdcc/debugger/README
32821 \begin_inset LatexCommand url
32822 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/debugger/README"
32832 <row topline="true">
32833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32836 \begin_layout Standard
32838 \begin_inset LatexCommand index
32843 Software simulator for microcontrollers
32848 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32851 \begin_layout Standard
32881 \begin_inset LatexCommand url
32882 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/sim/ucsim/doc/index.html"
32892 <row topline="true">
32893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32896 \begin_layout Standard
32897 Temporary notes on the pic16
32898 \begin_inset LatexCommand index
32908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32911 \begin_layout Standard
32912 sdcc/src/pic16/NOTES
32924 \begin_inset LatexCommand url
32925 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/src/pic16/NOTES"
32935 <row topline="true" bottomline="true">
32936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32939 \begin_layout Standard
32940 SDCC internal documentation (debugging file format)
32945 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32948 \begin_layout Standard
32978 \begin_inset LatexCommand url
32979 target "http://sdcc.sourceforge.net/doc/cdbfileformat.pdf"
32998 \begin_layout Section
32999 Related open source tools
33000 \begin_inset LatexCommand label
33001 name "sec:Related-open-source-tools"
33006 \begin_inset LatexCommand index
33007 name "Related tools"
33014 \begin_layout Standard
33016 \begin_inset Tabular
33017 <lyxtabular version="3" rows="16" columns="3">
33019 <column alignment="left" valignment="top" leftline="true" width="0pt">
33020 <column alignment="block" valignment="top" leftline="true" width="30line%">
33021 <column alignment="left" valignment="top" leftline="true" rightline="true" width="40col%">
33022 <row topline="true" bottomline="true">
33023 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33026 \begin_layout Standard
33034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33037 \begin_layout Standard
33045 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33048 \begin_layout Standard
33057 <row topline="true">
33058 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33061 \begin_layout Standard
33063 \begin_inset LatexCommand index
33064 name "gpsim (pic simulator)"
33073 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33076 \begin_layout Standard
33082 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33085 \begin_layout Standard
33086 \begin_inset LatexCommand url
33087 target "http://www.dattalo.com/gnupic/gpsim.html"
33097 <row topline="true">
33098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33101 \begin_layout Standard
33103 \begin_inset LatexCommand index
33104 name "gputils (pic tools)"
33113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33116 \begin_layout Standard
33122 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33125 \begin_layout Standard
33126 \begin_inset LatexCommand url
33127 target "http://sourceforge.net/projects/gputils"
33137 <row topline="true">
33138 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33141 \begin_layout Standard
33147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33150 \begin_layout Standard
33156 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33159 \begin_layout Standard
33160 \begin_inset LatexCommand url
33161 target "http://freshmeat.net/projects/flp5/"
33171 <row topline="true">
33172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33175 \begin_layout Standard
33181 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33184 \begin_layout Standard
33185 Tools for Silicon Laboratories JTAG debug adapter, partly based on SDCDB
33191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33194 \begin_layout Standard
33195 \begin_inset LatexCommand url
33196 target "http://sourceforge.net/projects/ec2drv"
33206 <row topline="true">
33207 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33210 \begin_layout Standard
33212 \begin_inset LatexCommand index
33213 name "indent (source formatting tool)"
33222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33225 \begin_layout Standard
33226 Formats C source - Master of the white spaces
33231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33234 \begin_layout Standard
33235 \begin_inset LatexCommand url
33236 target "http://directory.fsf.org/GNU/indent.html"
33246 <row topline="true">
33247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33250 \begin_layout Standard
33252 \begin_inset LatexCommand index
33253 name "srecord (bin, hex, ... tool)"
33262 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33265 \begin_layout Standard
33266 Object file conversion, checksumming, ...
33271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33274 \begin_layout Standard
33275 \begin_inset LatexCommand url
33276 target "http://sourceforge.net/projects/srecord"
33286 <row topline="true">
33287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33290 \begin_layout Standard
33292 \begin_inset LatexCommand index
33293 name "objdump (tool)"
33302 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33305 \begin_layout Standard
33306 Object file conversion, ...
33311 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33314 \begin_layout Standard
33315 Part of binutils (should be there anyway)
33321 <row topline="true">
33322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33325 \begin_layout Standard
33331 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33334 \begin_layout Standard
33335 8051 monitor (hex up-/download, single step, disassemble)
33340 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33343 \begin_layout Standard
33344 \begin_inset LatexCommand url
33345 target "http://sourceforge.net/projects/cmon51"
33355 <row topline="true">
33356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33359 \begin_layout Standard
33361 \begin_inset LatexCommand index
33362 name "doxygen (source documentation tool)"
33371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33374 \begin_layout Standard
33375 Source code documentation system
33380 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33383 \begin_layout Standard
33384 \begin_inset LatexCommand url
33385 target "http://www.doxygen.org"
33395 <row topline="true">
33396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33399 \begin_layout Standard
33405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33408 \begin_layout Standard
33409 IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
33414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33417 \begin_layout Standard
33418 \begin_inset LatexCommand url
33419 target "http://www.kdevelop.org"
33429 <row topline="true">
33430 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33433 \begin_layout Standard
33439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33442 \begin_layout Standard
33443 8051 monitor (hex up-/download, single step, disassemble)
33448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33451 \begin_layout Standard
33452 \begin_inset LatexCommand url
33453 target "http://www.pjrc.com/tech/8051/paulmon2.html"
33463 <row topline="true">
33464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33467 \begin_layout Standard
33469 \begin_inset LatexCommand index
33470 name "splint (syntax checking tool)"
33479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33482 \begin_layout Standard
33483 Statically checks c sources (see
33484 \begin_inset LatexCommand ref
33485 reference "lyx:more-pedantic-SPLINT"
33494 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33497 \begin_layout Standard
33498 \begin_inset LatexCommand url
33499 target "http://www.splint.org"
33509 <row topline="true" bottomline="true">
33510 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33513 \begin_layout Standard
33515 \begin_inset LatexCommand index
33516 name "DDD (debugger)"
33525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33528 \begin_layout Standard
33529 Debugger, serves nicely as GUI to SDCDB
33530 \begin_inset LatexCommand index
33531 name "SDCDB (debugger)"
33540 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33543 \begin_layout Standard
33544 \begin_inset LatexCommand url
33545 target "http://www.gnu.org/software/ddd/"
33555 <row bottomline="true">
33556 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33559 \begin_layout Standard
33561 \begin_inset LatexCommand index
33567 \begin_inset LatexCommand index
33568 name "d52 (disassembler)"
33577 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33580 \begin_layout Standard
33581 Disassembler, can count instruction cycles
33582 \begin_inset LatexCommand index
33583 name "instruction cycles (count)"
33587 , use with options -pnd
33592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33595 \begin_layout Standard
33596 \begin_inset LatexCommand url
33597 target "http://www.8052.com/users/disasm/"
33607 <row bottomline="true">
33608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33611 \begin_layout Standard
33613 \begin_inset LatexCommand index
33623 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33626 \begin_layout Standard
33627 Cross platform build system, generates Makefiles
33628 \begin_inset LatexCommand index
33633 and project workspaces
33634 \begin_inset LatexCommand index
33635 name "project workspace"
33644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33647 \begin_layout Standard
33648 \begin_inset LatexCommand url
33649 target "http://www.cmake.org"
33657 and a dedicated wiki entry:
33658 \begin_inset LatexCommand url
33659 target "http://www.cmake.org/Wiki/CmakeSdcc"
33678 \begin_layout Section
33679 Related documentation / recommended reading
33682 \begin_layout Standard
33684 \begin_inset Tabular
33685 <lyxtabular version="3" rows="7" columns="3">
33687 <column alignment="left" valignment="top" leftline="true" width="0pt">
33688 <column alignment="left" valignment="top" leftline="true" width="0">
33689 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
33690 <row topline="true" bottomline="true">
33691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33694 \begin_layout Standard
33702 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33705 \begin_layout Standard
33713 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33716 \begin_layout Standard
33725 <row topline="true">
33726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33729 \begin_layout Standard
33744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33747 \begin_layout Standard
33749 \begin_inset LatexCommand index
33750 name "C Reference card"
33759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33762 \begin_layout Standard
33763 \begin_inset LatexCommand url
33764 target "http://refcards.com/refcards/c/index.html"
33774 <row topline="true">
33775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33778 \begin_layout Standard
33784 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33787 \begin_layout Standard
33789 \begin_inset LatexCommand index
33799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33802 \begin_layout Standard
33803 \begin_inset LatexCommand url
33804 target "http://www.c-faq.com"
33814 <row topline="true">
33815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33818 \begin_layout Standard
33824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33827 \begin_layout Standard
33828 \begin_inset Quotes sld
33832 \begin_inset Quotes srd
33840 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33843 \begin_layout Standard
33846 \begin_inset LatexCommand url
33847 target "http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899"
33857 <row topline="true">
33858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33861 \begin_layout Standard
33867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33870 \begin_layout Standard
33871 \begin_inset Quotes sld
33874 Extensions for Embedded C
33875 \begin_inset Quotes srd
33883 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33886 \begin_layout Standard
33889 \begin_inset LatexCommand url
33890 target "http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf"
33900 <row topline="true">
33901 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33904 \begin_layout Standard
33910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33913 \begin_layout Standard
33914 Latest datasheet of target CPU
33919 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33922 \begin_layout Standard
33929 <row topline="true" bottomline="true">
33930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33933 \begin_layout Standard
33939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33942 \begin_layout Standard
33943 Revision history of datasheet
33948 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33951 \begin_layout Standard
33967 \begin_layout Section
33968 Application notes specifically for SDCC
33971 \begin_layout Standard
33972 SDCC makes no claims about the completeness of this list and about up-to-datenes
33973 s or correctness of the application notes
33974 \begin_inset LatexCommand index
33975 name "Application notes"
33982 \begin_layout Standard
33986 \begin_inset Tabular
33987 <lyxtabular version="3" rows="7" columns="3">
33989 <column alignment="block" valignment="top" leftline="true" width="17col%">
33990 <column alignment="block" valignment="top" leftline="true" width="27col%">
33991 <column alignment="block" valignment="top" leftline="true" rightline="true" width="57col%">
33992 <row topline="true" bottomline="true">
33993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33996 \begin_layout Standard
34005 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
34008 \begin_layout Standard
34017 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34020 \begin_layout Standard
34030 <row topline="true">
34031 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34034 \begin_layout Standard
34042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34045 \begin_layout Standard
34048 Using the SDCC Compiler for the DS80C400
34049 \begin_inset LatexCommand index
34059 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34062 \begin_layout Standard
34065 \begin_inset LatexCommand url
34066 target "http://pdfserv.maxim-ic.com/en/an/AN3346.pdf"
34076 <row topline="true">
34077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34080 \begin_layout Standard
34088 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none" width="30line%">
34091 \begin_layout Standard
34094 Using the Free SDCC C Compiler to Develop Firmware for the DS89C420/430/440/450
34095 \begin_inset LatexCommand index
34100 Family of Microcontrollers
34105 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34108 \begin_layout Standard
34111 \begin_inset LatexCommand url
34112 target "http://pdfserv.maxim-ic.com/en/an/AN3477.pdf"
34122 <row topline="true">
34123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34126 \begin_layout Standard
34129 Silicon Laboratories / Cygnal
34134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34137 \begin_layout Standard
34140 Integrating SDCC 8051 Tools Into The Silicon Labs IDE
34141 \begin_inset LatexCommand index
34151 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34154 \begin_layout Standard
34157 \begin_inset LatexCommand url
34158 target "http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/en/an198.pdf"
34168 <row topline="true">
34169 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34172 \begin_layout Standard
34175 Ramtron / Goal Semiconductor
34180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34183 \begin_layout Standard
34186 Interfacing SDCC to Syn and Textpad
34191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34194 \begin_layout Standard
34197 \begin_inset LatexCommand url
34198 target "http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp"
34208 <row topline="true">
34209 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34212 \begin_layout Standard
34215 Ramtron / Goal Semiconductor
34220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34223 \begin_layout Standard
34226 Installing and Configuring SDCC and Crimson Editor
34231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34234 \begin_layout Standard
34237 \begin_inset LatexCommand url
34238 target "http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp"
34248 <row topline="true" bottomline="true">
34249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34252 \begin_layout Standard
34260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34263 \begin_layout Standard
34266 MSC12xx Programming with SDCC
34271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34274 \begin_layout Standard
34277 \begin_inset LatexCommand url
34278 target "http://focus.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=sbaa109&fileType=pdf"
34295 \begin_layout Section
34299 \begin_layout Standard
34300 Some questions answered, some pointers given - it might be time to in turn
34308 \begin_layout Itemize
34309 can you solve your project with the selected microcontroller? Would you
34310 find out early or rather late that your target is too small/slow/whatever?
34311 Can you switch to a slightly better device if it doesn't fit?
34314 \begin_layout Itemize
34315 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
34316 and/or another programming language be more adequate? Would an operating
34317 system on the target device help?
34320 \begin_layout Itemize
34321 if you solved the problem, will the marketing department be happy?
34324 \begin_layout Itemize
34325 if the marketing department is happy, will customers be happy?
34328 \begin_layout Itemize
34329 if you're the project manager, marketing department and maybe even the customer
34330 in one person, have you tried to see the project from the outside?
34333 \begin_layout Itemize
34334 is the project done if you think it is done? Or is just that other interface/pro
34335 tocol/feature/configuration/option missing? How about website, manual(s),
34336 internationali(z|s)ation, packaging, labels, 2nd source for components,
34337 electromagnetic compatability/interference, documentation for production,
34338 production test software, update mechanism, patent issues?
34341 \begin_layout Itemize
34342 is your project adequately positioned in that magic triangle: fame, fortune,
34346 \begin_layout Standard
34347 Maybe not all answers to these questions are known and some answers may
34352 , nevertheless knowing these questions may help you to avoid burnout
34356 \begin_layout Standard
34357 burnout is bad for electronic devices, programmers and motorcycle tyres
34363 Chances are you didn't want to hear some of them...
34366 \begin_layout Chapter
34368 \begin_inset LatexCommand index
34376 \begin_layout Standard
34377 SDCC has grown to be a large project.
34378 The compiler alone (without the preprocessor, assembler and linker) is
34379 well over 150,000 lines of code (blank stripped).
34380 The open source nature of this project is a key to its continued growth
34382 You gain the benefit and support of many active software developers and
34384 Is SDCC perfect? No, that's why we need your help.
34385 The developers take pride in fixing reported bugs.
34386 You can help by reporting the bugs and helping other SDCC users.
34387 There are lots of ways to contribute, and we encourage you to take part
34388 in making SDCC a great software package.
34392 \begin_layout Standard
34393 The SDCC project is hosted on the SDCC sourceforge site at
34394 \begin_inset LatexCommand htmlurl
34395 target "http://sourceforge.net/projects/sdcc"
34400 You'll find the complete set of mailing lists
34401 \begin_inset LatexCommand index
34402 name "Mailing list(s)"
34406 , forums, bug reporting system, patch submission
34407 \begin_inset LatexCommand index
34408 name "Patch submission"
34413 \begin_inset LatexCommand index
34418 area and Subversion code repository
34419 \begin_inset LatexCommand index
34420 name "Subversion code repository"
34427 \begin_layout Section
34429 \begin_inset LatexCommand index
34430 name "Bug reporting"
34435 \begin_inset LatexCommand index
34436 name "Reporting bugs"
34443 \begin_layout Standard
34444 The recommended way of reporting bugs is using the infrastructure of the
34446 You can follow the status of bug reports there and have an overview about
34450 \begin_layout Standard
34451 Bug reports are automatically forwarded to the developer mailing list and
34452 will be fixed ASAP.
34453 When reporting a bug, it is very useful to include a small test program
34454 (the smaller the better) which reproduces the problem.
34455 If you can isolate the problem by looking at the generated assembly code,
34456 this can be very helpful.
34457 Compiling your program with the -
34461 \begin_layout Standard
34471 \begin_inset LatexCommand index
34472 name "-\\/-dumpall"
34476 option can sometimes be useful in locating optimization problems.
34477 When reporting a bug please make sure you:
34480 \begin_layout Enumerate
34481 Attach the code you are compiling with SDCC.
34485 \begin_layout Enumerate
34486 Specify the exact command you use to run SDCC, or attach your Makefile.
34490 \begin_layout Enumerate
34491 Specify the SDCC version (type "
34497 "), your platform, and operating system.
34501 \begin_layout Enumerate
34502 Provide an exact copy of any error message or incorrect output.
34506 \begin_layout Enumerate
34507 Put something meaningful in the subject of your message.
34510 \begin_layout Standard
34511 Please attempt to include these 5 important parts, as applicable, in all
34512 requests for support or when reporting any problems or bugs with SDCC.
34513 Though this will make your message lengthy, it will greatly improve your
34514 chance that SDCC users and developers will be able to help you.
34515 Some SDCC developers are frustrated by bug reports without code provided
34516 that they can use to reproduce and ultimately fix the problem, so please
34517 be sure to provide sample code if you are reporting a bug!
34520 \begin_layout Standard
34521 Please have a short check that you are using a recent version of SDCC and
34522 the bug is not yet known.
34523 This is the link for reporting bugs:
34524 \begin_inset LatexCommand htmlurl
34525 target "http://sourceforge.net/tracker/?group_id=599&atid=100599"
34530 With SDCC on average having more than 200 downloads
34531 \begin_inset LatexCommand index
34536 on sourceforge per day
34540 \begin_layout Standard
34541 220 daily downloads on average Jan-Sept 2006 and about 150 daily downloads
34542 between 2002 and 2005.
34543 This does not include other methods of distribution.
34548 there must be some users.
34549 So it's not exactly easy to find a new bug.
34550 If you find one we need it:
34552 reporting bugs is good
34557 \begin_layout Section
34558 Requesting Features
34559 \begin_inset LatexCommand label
34560 name "sub:Requesting-Features"
34565 \begin_inset LatexCommand index
34566 name "Feature request"
34571 \begin_inset LatexCommand index
34572 name "Requesting features"
34579 \begin_layout Standard
34580 Like bug reports feature requests are forwarded to the developer mailing
34582 This is the link for requesting features:
34583 \begin_inset LatexCommand htmlurl
34584 target "http://sourceforge.net/tracker/?group_id=599&atid=350599"
34591 \begin_layout Section
34595 \begin_layout Standard
34596 Like bug reports contributed patches are forwarded to the developer mailing
34598 This is the link for submitting patches
34599 \begin_inset LatexCommand index
34600 name "Patch submission"
34605 \begin_inset LatexCommand url
34606 target "http://sourceforge.net/tracker/?group_id=599&atid=300599"
34613 \begin_layout Standard
34614 You need to specify some parameters to the
34618 command for the patches to be useful.
34619 If you modified more than one file a patch created f.e.
34624 \begin_inset Quotes sld
34627 diff -Naur unmodified_directory modified_directory >my_changes.patch
34628 \begin_inset Quotes srd
34634 will be fine, otherwise
34638 \begin_inset Quotes sld
34641 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
34642 \begin_inset Quotes srd
34651 \begin_layout Section
34655 \begin_layout Standard
34656 These links should take you directly to the
34657 \begin_inset LatexCommand url
34658 name "Mailing lists"
34659 target "http://sourceforge.net/mail/?group_id=599"
34667 \begin_layout Standard
34668 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
34669 automated messages (mid 2003)
34675 \begin_inset LatexCommand url
34677 target "http://sourceforge.net/forum/?group_id=599"
34682 \begin_inset LatexCommand index
34683 name "Mailing list(s)"
34687 and forums are archived and searchable so if you are lucky someone already
34688 had a similar problem.
34689 While mails to the lists themselves are delivered promptly their web front
34690 end on sourceforge sometimes shows a severe time lag (up to several weeks),
34691 if you're seriously using SDCC please consider subscribing to the lists.
34694 \begin_layout Section
34698 \begin_layout Standard
34699 You can follow the status of the Subversion version
34700 \begin_inset LatexCommand index
34705 of SDCC by watching the Changelog
34706 \begin_inset LatexCommand index
34711 in the Subversion repository
34714 \begin_inset LatexCommand htmlurl
34715 target "http://sdcc.svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog"
34722 \begin_layout Section
34723 Subversion Source Code Repository
34726 \begin_layout Standard
34736 \begin_layout Standard
34750 or the filenames of the snapshot versions of SDCC include date and its
34752 \begin_inset LatexCommand index
34753 name "Subversion code repository"
34758 Subversion allows to download the source of recent or previous versions
34760 \begin_inset LatexCommand url
34761 target "http://sourceforge.net/svn/?group_id=599"
34765 (by number or by date).
34766 An on-line source code browser and detailled instructions are also available
34768 SDCC versions starting from 1999 up to now are available (currently the
34769 versions prior to the conversion from cvs
34770 \begin_inset LatexCommand index
34771 name "cvs|see{Subversion}"
34775 to Subversion (April 2006) are either by accessible by Subversion or by
34779 \begin_layout Section
34781 \begin_inset LatexCommand index
34782 name "Release policy"
34789 \begin_layout Standard
34790 Historically there often were long delays between official releases and
34791 the sourceforge download area tends to get not updated at all.
34792 Excuses in the past might have referred to problems with live range analysis,
34793 but as this was fixed a while ago, the current problem is that another
34794 excuse has to be found.
34795 Kidding aside, we have to get better there! On the other hand there are
34796 daily snapshots available at
34797 \begin_inset LatexCommand htmlurl
34799 target "http://sdcc.sourceforge.net/snap.php"
34803 , and you can always build the very last version (hopefully with many bugs
34804 fixed, and features added) from the source code available at
34805 \begin_inset LatexCommand htmlurl
34807 target "http://sdcc.sourceforge.net/snap.php#Source"
34813 \begin_inset LatexCommand index
34819 \begin_inset LatexCommand index
34825 \begin_inset LatexCommand url
34826 target "http://sdcc.wiki.sourceforge.net/"
34830 also holds some information about past and future releases.
34833 \begin_layout Section
34835 \begin_inset LatexCommand index
34843 \begin_layout Standard
34844 You'll find some small examples in the directory
34846 sdcc/device/examples/.
34849 More examples and libraries are available at
34851 The SDCC Open Knowledge Resource
34852 \begin_inset LatexCommand url
34853 target "http://sdccokr.dl9sec.de/"
34860 \begin_inset LatexCommand url
34861 target "http://www.pjrc.com/tech/8051/"
34868 \begin_layout Standard
34869 \begin_inset Note Note
34872 \begin_layout Standard
34873 I did insert a reference to Paul's web site here although it seems rather
34874 dedicated to a specific 8032 board (I think it's okay because it f.e.
34875 shows LCD/Harddisc interface and has a free 8051 monitor.
34876 Independent 8032 board vendors face hard competition of heavily subsidized
34877 development boards anyway).
34880 \begin_layout Standard
34881 Maybe we should include some links to real world applications.
34882 Preferably pointer to pointers (one for each architecture) so this stays
34891 \begin_layout Section
34893 \begin_inset LatexCommand label
34894 name "sec:Quality-control"
34899 \begin_inset LatexCommand index
34900 name "Quality control"
34907 \begin_layout Standard
34908 The compiler is passed through snaphot build compile and build checks.
34914 \begin_inset LatexCommand index
34915 name "Regression test"
34919 check that SDCC itself compiles flawlessly on several host platforms (i386,
34920 Opteron, 64 bit Alpha, ppc64, Mac OS X on ppc and i386, Solaris on Sparc)
34921 and checks the quality of the code generated by SDCC by running the code
34922 for several target platforms through simulators.
34923 The regression test suite comprises more than 100 files which expand to
34924 more than 500 test cases which include more than 4500 tests.
34925 The results of these tests are published daily on SDCC's snapshot page
34926 (click on the red or green symbols on the right side of
34927 \begin_inset LatexCommand url
34928 target "http://sdcc.sourceforge.net/snap.php"
34935 \begin_layout Standard
34936 There is a separate document
34939 \begin_inset LatexCommand index
34947 \begin_inset LatexCommand url
34948 target "http://sdcc.sourceforge.net/doc/test_suite_spec.pdf"
34952 about the regression test suite.
34955 \begin_layout Standard
34956 You'll find the test code in the directory
34958 sdcc/support/regression
34961 You can run these tests manually by running
34965 in this directory (or f.e.
34970 \begin_inset Quotes sld
34974 \begin_inset Quotes srd
34980 if you don't want to run the complete tests).
34981 The test code might also be interesting if you want to look for examples
34982 \begin_inset LatexCommand index
34987 checking corner cases of SDCC or if you plan to submit patches
34988 \begin_inset LatexCommand index
34989 name "Patch submission"
34996 \begin_layout Standard
34997 The PIC14 port uses a different set of regression tests
34998 \begin_inset LatexCommand index
34999 name "Regression test (PIC14)"
35003 , you'll find them in the directory
35005 sdcc/src/regression
35010 \begin_layout Section
35011 Use of SDCC in Education
35014 \begin_layout Standard
35023 \begin_layout Standard
35024 the phrase "use in education" might evoke the association "
35028 fit for use in education".
35029 This connotation is not intended but nevertheless risked as the licensing
35030 of SDCC makes it difficult to offer educational discounts
35036 If your rationales are to:
35039 \begin_layout Enumerate
35040 give students a chance to understand the
35044 steps of code generation
35047 \begin_layout Enumerate
35048 have a curriculum that can be extended for years.
35049 Then you could use an fpga board as target and your curriculum will seamlessly
35050 extend from logic synthesis (
35051 \begin_inset LatexCommand url
35052 name "http://www.opencores.org"
35053 target "opencores.org"
35058 \begin_inset LatexCommand url
35060 target "http://www.oregano.at/ip/ip01.htm"
35064 ), over assembly programming, to C to FPGA compilers (
35065 \begin_inset LatexCommand url
35067 target "http://sf.net/projects/fpgac"
35074 \begin_layout Enumerate
35075 be able to insert excursions about skills like using a revision control
35076 system, submitting/applying patches, using a type-setting (as opposed to
35077 word-processing) engine LyX/LaTeX, using
35078 \begin_inset LatexCommand url
35080 target "http://www.sf.net"
35085 \begin_inset LatexCommand url
35087 target "http://en.wikipedia.org/wiki/Netiquette"
35091 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
35092 Source Software, CPU simulation, compiler regression tests
35093 \begin_inset LatexCommand index
35094 name "Regression test"
35101 And if there should be a shortage of ideas then you can always point students
35102 to the ever-growing feature request list
35103 \begin_inset LatexCommand htmlurl
35104 target "http://sourceforge.net/tracker/?group_id=599&atid=350599"
35111 \begin_layout Enumerate
35112 not tie students to a specific host platform and instead allow them to use
35117 choice (among them Alpha, i386, i386_64, Mac OS X, Mips, Sparc, Windows
35119 \begin_inset LatexCommand url
35121 target "http://www.laptop.org"
35128 \begin_layout Enumerate
35129 not encourage students to use illegal copies of educational software
35132 \begin_layout Enumerate
35133 be immune to licensing/availability/price changes of the chosen tool chain
35136 \begin_layout Enumerate
35137 be able to change to a new target platform without having to adopt a new
35141 \begin_layout Enumerate
35142 have complete control over and insight into the tool chain
35145 \begin_layout Enumerate
35146 make your students aware about the pros and cons of open source software
35150 \begin_layout Enumerate
35151 give back to the public as you are probably at least partially publicly
35155 \begin_layout Enumerate
35156 give students a chance to publicly prove their skills and to possibly see
35157 a world wide impact
35160 \begin_layout Standard
35161 then SDCC is probably among the first choices.
35162 Well, probably SDCC might be the only choice.
35167 \begin_layout Chapter
35168 SDCC Technical Data
35171 \begin_layout Section
35173 \begin_inset LatexCommand index
35174 name "Optimizations"
35181 \begin_layout Standard
35182 SDCC performs a host of standard optimizations in addition to some MCU specific
35187 \begin_layout Subsection
35188 Sub-expression Elimination
35189 \begin_inset LatexCommand index
35190 name "Subexpression elimination"
35197 \begin_layout Standard
35198 The compiler does local and
35217 \begin_layout Verse
35225 \begin_layout Standard
35226 will be translated to
35229 \begin_layout Verse
35239 \begin_layout Standard
35240 Some subexpressions are not as obvious as the above example, e.g.:
35243 \begin_layout Verse
35251 \begin_layout Standard
35252 In this case the address arithmetic a->b[i] will be computed only once;
35253 the equivalent code in C would be.
35256 \begin_layout Verse
35266 \begin_layout Standard
35267 The compiler will try to keep these temporary variables in registers.
35270 \begin_layout Subsection
35271 Dead-Code Elimination
35272 \begin_inset LatexCommand index
35273 name "Dead-code elimination"
35280 \begin_layout Verse
35295 i = 1; \InsetSpace ~
35304 global = 1;\InsetSpace ~
35318 global = 3;\InsetSpace ~
35324 \begin_layout Standard
35328 \begin_layout Verse
35344 \begin_layout Subsection
35346 \begin_inset LatexCommand index
35347 name "Copy propagation"
35354 \begin_layout Verse
35378 \begin_layout Standard
35382 \begin_layout Verse
35406 \begin_layout Standard
35407 Note: the dead stores created by this copy propagation will be eliminated
35408 by dead-code elimination.
35411 \begin_layout Subsection
35413 \begin_inset LatexCommand index
35414 name "Loop optimization"
35419 \begin_inset LatexCommand label
35420 name "sub:Loop-Optimizations"
35427 \begin_layout Standard
35428 Two types of loop optimizations are done by SDCC
35436 of loop induction variables.
35437 In addition to the strength reduction the optimizer marks the induction
35438 variables and the register allocator tries to keep the induction variables
35439 in registers for the duration of the loop.
35440 Because of this preference of the register allocator
35441 \begin_inset LatexCommand index
35442 name "Register allocation"
35446 , loop induction optimization causes an increase in register pressure, which
35447 may cause unwanted spilling of other temporary variables into the stack
35448 \begin_inset LatexCommand index
35454 The compiler will generate a warning message when it is forced to allocate
35455 extra space either on the stack or data space.
35456 If this extra space allocation is undesirable then induction optimization
35457 can be eliminated either for the entire source file (with -
35461 \begin_layout Standard
35470 -noinduction option) or for a given function only using #pragma\InsetSpace ~
35472 \begin_inset LatexCommand index
35473 name "\\#pragma noinduction"
35484 \begin_layout Verse
35487 for (i = 0 ; i < 100 ; i ++)
35496 \begin_layout Standard
35500 \begin_layout Verse
35505 for (i = 0; i < 100; i++)
35514 \begin_layout Standard
35515 As mentioned previously some loop invariants are not as apparent, all static
35516 address computations are also moved out of the loop.
35521 \begin_inset LatexCommand index
35522 name "Strength reduction"
35526 , this optimization substitutes an expression by a cheaper expression:
35529 \begin_layout Verse
35532 for (i=0;i < 100; i++)
35541 \begin_layout Standard
35545 \begin_layout Verse
35552 for (i=0;i< 100;i++) {
35558 ar[itemp1] = itemp2;
35576 \begin_layout Standard
35577 The more expensive multiplication
35578 \begin_inset LatexCommand index
35579 name "Multiplication"
35583 is changed to a less expensive addition.
35586 \begin_layout Subsection
35588 \begin_inset LatexCommand index
35589 name "Loop reversing"
35596 \begin_layout Standard
35597 This optimization is done to reduce the overhead of checking loop boundaries
35598 for every iteration.
35599 Some simple loops can be reversed and implemented using a
35600 \begin_inset Quotes eld
35603 decrement and jump if not zero
35604 \begin_inset Quotes erd
35608 SDCC checks for the following criterion to determine if a loop is reversible
35609 (note: more sophisticated compilers use data-dependency analysis to make
35610 this determination, SDCC uses a more simple minded analysis).
35613 \begin_layout Itemize
35614 The 'for' loop is of the form
35620 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
35630 \begin_layout Itemize
35631 The <for body> does not contain
35632 \begin_inset Quotes eld
35636 \begin_inset Quotes erd
35640 \begin_inset Quotes erd
35646 \begin_layout Itemize
35647 All goto's are contained within the loop.
35650 \begin_layout Itemize
35651 No function calls within the loop.
35654 \begin_layout Itemize
35655 The loop control variable <sym> is not assigned any value within the loop
35658 \begin_layout Itemize
35659 The loop control variable does NOT participate in any arithmetic operation
35663 \begin_layout Itemize
35664 There are NO switch statements in the loop.
35667 \begin_layout Subsection
35668 Algebraic Simplifications
35671 \begin_layout Standard
35672 SDCC does numerous algebraic simplifications, the following is a small sub-set
35673 of these optimizations.
35676 \begin_layout Verse
35679 i = j + 0;\InsetSpace ~
35683 /* changed to: */\InsetSpace ~
35689 i /= 2;\InsetSpace ~
35696 /* changed to: */\InsetSpace ~
35703 = j - j;\InsetSpace ~
35707 /* changed to: */\InsetSpace ~
35713 i = j / 1;\InsetSpace ~
35717 /* changed to: */\InsetSpace ~
35724 \begin_layout Standard
35725 Note the subexpressions
35726 \begin_inset LatexCommand index
35727 name "Subexpression"
35731 given above are generally introduced by macro expansions or as a result
35732 of copy/constant propagation.
35735 \begin_layout Subsection
35736 'switch' Statements
35737 \begin_inset LatexCommand label
35738 name "sub:'switch'-Statements"
35743 \begin_inset LatexCommand index
35744 name "switch statement"
35751 \begin_layout Standard
35752 SDCC can optimize switch statements to jump tables
35753 \begin_inset LatexCommand index
35759 It makes the decision based on an estimate of the generated code size.
35760 SDCC is quite liberal in the requirements for jump table generation:
35763 \begin_layout Itemize
35764 The labels need not be in order, and the starting number need not be one
35765 or zero, the case labels are in numerical sequence or not too many case
35766 labels are missing.
35770 \begin_layout Verse
35773 switch(i) {\InsetSpace ~
35804 case 4: ...\InsetSpace ~
35836 case 5: ...\InsetSpace ~
35868 case 3: ...\InsetSpace ~
35899 case 6: ...\InsetSpace ~
35931 case 7: ...\InsetSpace ~
35963 case 8: ...\InsetSpace ~
35995 case 9: ...\InsetSpace ~
36027 case 10: ...\InsetSpace ~
36058 case 11: ...\InsetSpace ~
36125 \begin_layout Standard
36126 Both the above switch statements will be implemented using a jump-table.
36127 The example to the right side is slightly more efficient as the check for
36128 the lower boundary of the jump-table is not needed.
36132 \begin_layout Itemize
36133 The number of case labels is not larger than supported by the target architectur
36137 \begin_layout Itemize
36138 If the case labels are not in numerical sequence ('gaps' between cases)
36139 SDCC checks whether a jump table with additionally inserted dummy cases
36140 is still attractive.
36144 \begin_layout Itemize
36145 If the starting number is not zero and a check for the lower boundary of
36146 the jump-table can thus be eliminated SDCC might insert dummy cases 0,
36151 \begin_layout Standard
36152 Switch statements which have large gaps in the numeric sequence or those
36153 that have too many case labels can be split into more than one switch statement
36154 for efficient code generation, e.g.:
36157 \begin_layout Verse
36235 \begin_layout Standard
36236 If the above switch statement is broken down into two switch statements
36239 \begin_layout Verse
36282 \begin_layout Standard
36286 \begin_layout Verse
36329 \begin_layout Standard
36330 then both the switch statements will be implemented using jump-tables whereas
36331 the unmodified switch statement will not be.
36334 \begin_layout Standard
36335 \begin_inset Note Note
36338 \begin_layout Standard
36339 There might be reasons which SDCC cannot know about to either favour or
36340 not favour jump tables.
36341 If the target system has to be as quick for the last switch case as for
36342 the first (pro jump table), or if the switch argument is known to be zero
36343 in the majority of the cases (contra jump table).
36351 \begin_layout Standard
36352 The pragma nojtbound
36353 \begin_inset LatexCommand index
36354 name "\\#pragma nojtbound"
36358 can be used to turn off checking the
36371 It has no effect if a default label is supplied.
36372 Use of this pragma is dangerous: if the switch
36373 \begin_inset LatexCommand index
36374 name "switch statement"
36378 argument is not matched by a case statement the processor will happily
36382 \begin_layout Subsection
36383 Bit-shifting Operations
36384 \begin_inset LatexCommand index
36385 name "Bit shifting"
36392 \begin_layout Standard
36393 Bit shifting is one of the most frequently used operation in embedded programmin
36395 SDCC tries to implement bit-shift operations in the most efficient way
36399 \begin_layout Verse
36412 \begin_layout Standard
36413 generates the following code:
36416 \begin_layout Verse
36431 \begin_layout Standard
36432 In general SDCC will never setup a loop if the shift count is known.
36436 \begin_layout Verse
36449 \begin_layout Standard
36453 \begin_layout Verse
36477 \begin_layout Subsection
36479 \begin_inset LatexCommand index
36480 name "Bit rotation"
36487 \begin_layout Standard
36488 A special case of the bit-shift operation is bit rotation
36489 \begin_inset LatexCommand index
36490 name "rotating bits"
36494 , SDCC recognizes the following expression to be a left bit-rotation:
36497 \begin_layout Verse
36505 char i;\InsetSpace ~
36516 /* unsigned is needed for rotation */
36521 i = ((i << 1) | (i >> 7));
36530 \begin_layout Standard
36531 will generate the following code:
36534 \begin_layout Verse
36551 \begin_layout Standard
36552 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
36553 ns of this case will also be recognized as bit-rotation, i.e.:
36556 \begin_layout Verse
36559 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
36562 \begin_layout Subsection
36563 Nibble and Byte Swapping
36566 \begin_layout Standard
36567 Other special cases of the bit-shift operations are nibble or byte swapping
36568 \begin_inset LatexCommand index
36569 name "swapping nibbles/bytes"
36573 , SDCC recognizes the following expressions:
36576 \begin_layout Verse
36597 i = ((i << 4) | (i >> 4));
36603 j = ((j << 8) | (j >> 8));
36606 \begin_layout Standard
36607 and generates a swap instruction for the nibble swapping
36608 \begin_inset LatexCommand index
36609 name "Nibble swapping"
36613 or move instructions for the byte swapping
36614 \begin_inset LatexCommand index
36615 name "Byte swapping"
36621 \begin_inset Quotes sld
36625 \begin_inset Quotes srd
36628 example can be used to convert from little to big-endian or vice versa.
36629 If you want to change the endianness of a
36633 integer you have to cast to
36640 \begin_layout Standard
36641 Note that SDCC stores numbers in little-endian
36645 \begin_layout Standard
36646 Usually 8-bit processors don't care much about endianness.
36647 This is not the case for the standard 8051 which only has an instruction
36653 \begin_inset LatexCommand index
36658 -datapointer so little-endian is the more efficient byte order.
36664 \begin_inset LatexCommand index
36665 name "little-endian"
36670 \begin_inset LatexCommand index
36676 lowest order first).
36679 \begin_layout Subsection
36681 \begin_inset LatexCommand index
36682 name "Highest Order Bit"
36687 \begin_inset LatexCommand index
36688 name "Any Order Bit"
36695 \begin_layout Standard
36696 It is frequently required to obtain the highest order bit of an integral
36697 type (long, int, short or char types).
36698 Also obtaining any other order bit is not uncommon.
36699 SDCC recognizes the following expressions to yield the highest order bit
36700 and generates optimized code for it, e.g.:
36703 \begin_layout Verse
36714 unsigned char hob1, aob1;
36718 bit hob2, hob3, aob2,
36728 hob1 = (gint >> 15) & 1;
36732 hob2 = (gint >> 15) & 1;
36736 hob3 = gint & 0x8000;
36741 aob1 = (gint >> 9) & 1;
36745 aob2 = (gint >> 8) & 1;
36749 aob3 = gint & 0x0800;
36759 \begin_layout Standard
36760 will generate the following code:
36763 \begin_layout Verse
36794 000A E5*01\InsetSpace ~
36821 000C 23\InsetSpace ~
36852 000D 54 01\InsetSpace ~
36880 000F F5*02\InsetSpace ~
36935 0011 E5*01\InsetSpace ~
36963 0013 33\InsetSpace ~
36993 0014 92*00\InsetSpace ~
37049 0016 E5*01\InsetSpace ~
37076 0018 33\InsetSpace ~
37106 0019 92*01\InsetSpace ~
37162 001B E5*01\InsetSpace ~
37221 001E 54 01\InsetSpace ~
37248 0020 F5*03\InsetSpace ~
37304 0022 E5*01\InsetSpace ~
37331 0024 13\InsetSpace ~
37361 0025 92*02\InsetSpace ~
37417 0027 E5*01\InsetSpace ~
37472 002B 92*03\InsetSpace ~
37500 \begin_layout Standard
37501 Other variations of these cases however will
37506 They are standard C expressions, so I heartily recommend these be the only
37507 way to get the highest order bit, (it is portable).
37508 Of course it will be recognized even if it is embedded in other expressions,
37512 \begin_layout Verse
37515 xyz = gint + ((gint >> 15) & 1);
37518 \begin_layout Standard
37519 will still be recognized.
37522 \begin_layout Subsection
37524 \begin_inset LatexCommand index
37525 name "Higher Order Byte"
37529 / Higher Order Word
37530 \begin_inset LatexCommand index
37531 name "Higher Order Word"
37538 \begin_layout Standard
37539 It is also frequently required to obtain a higher order byte or word of
37540 a larger integral type (long, int or short types).
37541 SDCC recognizes the following expressions to yield the higher order byte
37542 or word and generates optimized code for it, e.g.:
37545 \begin_layout Verse
37550 unsigned long int glong;
37558 unsigned char hob1,
37563 unsigned int how1, how2;
37572 hob1 = (gint >> 8) & 0xFF;
37576 hob2 = glong >> 24;
37580 how1 = (glong >> 16) & 0xFFFF;
37595 \begin_layout Standard
37596 will generate the following code:
37599 \begin_layout Verse
37630 0037 85*01*06\InsetSpace ~
37652 _foo_hob1_1_1,(_gint + 1)
37683 003A 85*05*07\InsetSpace ~
37705 _foo_hob2_1_1,(_glong + 3)
37735 003D 85*04*08\InsetSpace ~
37758 _foo_how1_1_1,(_glong + 2)
37760 0040 85*05*09\InsetSpace ~
37785 0043 85*03*0A\InsetSpace ~
37807 _foo_how2_1_1,(_glong + 1)
37809 0046 85*04*0B\InsetSpace ~
37832 (_foo_how2_1_1 + 1),(_glong + 2)
37835 \begin_layout Standard
37836 Again, variations of these cases may
37841 They are standard C expressions, so I heartily recommend these be the only
37842 way to get the higher order byte/word, (it is portable).
37843 Of course it will be recognized even if it is embedded in other expressions,
37847 \begin_layout Verse
37850 xyz = gint + ((gint >> 8) & 0xFF);
37853 \begin_layout Standard
37854 will still be recognized.
37857 \begin_layout Subsection
37859 \begin_inset LatexCommand label
37860 name "sub:Peephole-Optimizer"
37865 \begin_inset LatexCommand index
37866 name "Peephole optimizer"
37873 \begin_layout Standard
37874 The compiler uses a rule based, pattern matching and re-writing mechanism
37875 for peep-hole optimization.
37880 a peep-hole optimizer by Christopher W.
37881 Fraser (cwfraser\InsetSpace ~
37884 A default set of rules are compiled into the compiler, additional rules
37885 may be added with the
37891 \begin_layout Standard
37901 \begin_inset LatexCommand index
37902 name "-\\/-peep-file"
37909 The rule language is best illustrated with examples.
37912 \begin_layout Verse
37934 \begin_layout Standard
37935 The above rule will change the following assembly
37936 \begin_inset LatexCommand index
37937 name "Assembler routines"
37944 \begin_layout Verse
37952 \begin_layout Standard
37956 \begin_layout Verse
37962 \begin_layout Standard
37963 Note: All occurrences of a
37967 (pattern variable) must denote the same string.
37968 With the above rule, the assembly sequence:
37971 \begin_layout Verse
37979 \begin_layout Standard
37980 will remain unmodified.
37984 Other special case optimizations may be added by the
37991 \begin_layout Standard
38004 some variants of the 8051 MCU
38005 \begin_inset LatexCommand index
38006 name "MCS51 variants"
38019 The following two rules will change all
38036 \begin_layout Verse
38039 replace { lcall %1 } by { acall %1 }
38041 replace { ljmp %1 } by { ajmp %1 }
38044 \begin_layout Standard
38045 (NOTE: from version 2.7.3 on, you can use option -
38051 \begin_layout Standard
38063 \begin_inset LatexCommand index
38064 name "-\\/-acall-ajmp"
38068 , which also takes care of aligning the interrupt vectors properly.)
38073 \begin_layout Standard
38076 inline-assembler code
38078 is also passed through the peep hole optimizer, thus the peephole optimizer
38079 can also be used as an assembly level macro expander.
38080 The rules themselves are MCU dependent whereas the rule language infra-structur
38081 e is MCU independent.
38082 Peephole optimization rules for other MCU can be easily programmed using
38087 The syntax for a rule is as follows:
38090 \begin_layout Verse
38093 rule := replace [ restart ] '{' <assembly sequence> '
38131 <assembly sequence> '
38149 '}' [if <functionName> ] '
38154 \begin_layout Standard
38155 <assembly sequence> := assembly instruction (each instruction including
38156 labels must be on a separate line).
38160 The optimizer will apply to the rules
38161 one by one from the top in the sequence of their appearance, it will terminate
38162 when all rules are exhausted.
38163 If the 'restart' option is specified, then the optimizer will start matching
38164 the rules again from the top, this option for a rule is expensive (performance)
38165 , it is intended to be used in situations where a transformation will trigger
38166 the same rule again.
38167 An example of this (not a good one, it has side effects) is the following
38171 \begin_layout Verse
38191 \begin_layout Standard
38192 Note that the replace pattern cannot be a blank, but can be a comment line.
38193 Without the 'restart' option only the innermost 'pop' 'push' pair would
38194 be eliminated, i.e.:
38197 \begin_layout Verse
38209 \begin_layout Standard
38213 \begin_layout Verse
38223 \begin_layout Standard
38228 the restart option the rule will be applied again to the resulting code
38229 and then all the pop-push pairs will be eliminated to yield:
38232 \begin_layout Verse
38240 \begin_layout Standard
38241 A conditional function can be attached to a rule.
38242 Attaching rules are somewhat more involved, let me illustrate this with
38246 \begin_layout Verse
38270 \begin_layout Standard
38271 The optimizer does a look-up of a function name table defined in function
38276 in the source file SDCCpeeph.c, with the name
38281 If it finds a corresponding entry the function is called.
38282 Note there can be no parameters specified for these functions, in this
38287 is crucial, since the function
38291 expects to find the label in that particular variable (the hash table containin
38292 g the variable bindings is passed as a parameter).
38293 If you want to code more such functions, take a close look at the function
38294 labelInRange and the calling mechanism in source file SDCCpeeph.c.
38295 Currently implemented are
38297 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
38298 24bitMode, portIsDS390, 24bitModeAndPortDS390
38307 \begin_layout Standard
38308 I know this whole thing is a little kludgey, but maybe some day we will
38309 have some better means.
38310 If you are looking at this file, you will see the default rules that are
38311 compiled into the compiler, you can add your own rules in the default set
38312 there if you get tired of specifying the -
38316 \begin_layout Standard
38328 \begin_layout Section
38330 \begin_inset LatexCommand index
38331 name "ANSI-compliance"
38336 \begin_inset LatexCommand label
38337 name "sub:ANSI-Compliance"
38344 \begin_layout Standard
38345 The latest publicly available version of the standard
38347 ISO/IEC 9899 - Programming languages - C
38349 should be available at:
38350 \begin_inset LatexCommand url
38351 target "http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899"
38360 \begin_layout Standard
38361 Deviations from the compliance:
38364 \begin_layout Itemize
38365 functions are not reentrant
38366 \begin_inset LatexCommand index
38371 unless explicitly declared as such or the
38377 \begin_layout Standard
38387 \begin_inset LatexCommand index
38388 name "-\\/-stack-auto"
38394 command line option is specified.
38397 \begin_layout Itemize
38399 \begin_inset LatexCommand index
38405 \begin_inset LatexCommand index
38410 cannot be assigned values directly, cannot be passed as function parameters
38411 or assigned to each other and cannot be a return value
38412 \begin_inset LatexCommand index
38413 name "return value"
38417 from a function, e.g.:
38421 \begin_layout Verse
38444 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
38469 s parms) /* invalid in SDCC although allowed in ANSI */
38491 return rets; /* is invalid in SDCC although allowed in ANSI */
38497 \begin_layout Itemize
38498 initialization of structure arrays must be fully braced.
38502 \begin_layout Verse
38505 struct s { char x } a[] = {1, 2};\InsetSpace ~
38510 /* invalid in SDCC */
38513 } a[] = {{1}, {2}}; /* OK */
38517 \begin_layout Itemize
38519 \begin_inset LatexCommand index
38520 name "long long (not supported)"
38525 \begin_inset LatexCommand index
38526 name "int (64 bit) (not supported)"
38533 \begin_layout Itemize
38535 \begin_inset LatexCommand index
38536 name "double (not supported)"
38540 ' precision floating point
38541 \begin_inset LatexCommand index
38542 name "Floating point support"
38549 \begin_layout Itemize
38551 \begin_inset LatexCommand index
38556 function declarations are NOT allowed.
38560 \begin_layout Verse
38563 foo(i,j) /* this old style of function declarations */
38565 int i,j; /* is valid
38566 in ANSI but not valid in SDCC */
38581 \begin_layout Itemize
38582 Most enhancements in C99 are not supported, e.g.:
38586 \begin_layout Verse
38596 i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
38600 \begin_layout Itemize
38601 But some have been added recently in SDCC 2.7.0.
38602 They must be considered alpha quality however.
38606 \begin_layout Verse
38611 \begin_inset LatexCommand index
38612 name "inline (not supported)"
38621 int increment (int a) { return a+1; } /* inlines the increment without function
38630 \begin_inset LatexCommand index
38631 name "inline (not supported)"
38640 p; /* accepted but ignored */
38644 \begin_layout Itemize
38645 Certain words that are valid identifiers in the standard may be reserved
38646 words in SDCC unless the
38652 \begin_layout Standard
38662 \begin_inset LatexCommand index
38663 name "-\\/-std-c89"
38675 \begin_layout Standard
38685 \begin_inset LatexCommand index
38686 name "-\\/-std-c99"
38692 command line options are used.
38693 These may include (depending on the selected processor): 'at', 'banked',
38694 'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
38695 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
38696 'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
38698 Compliant equivalents of these keywords are always available in a form
38699 that begin with two underscores
38700 \begin_inset LatexCommand index
38701 name "\\_\\_ (prefix for extended keywords)"
38706 '__data' instead of 'data'.
38709 \begin_layout Itemize
38710 Integer promotion of variable arguments is not performed if the argument
38711 is explicitly taypecasted unless the
38717 \begin_layout Standard
38727 \begin_inset LatexCommand index
38728 name "-\\/-std-c89"
38740 \begin_layout Standard
38750 \begin_inset LatexCommand index
38751 name "-\\/-std-c99"
38757 command line options are used.
38761 \begin_layout Verse
38764 void vararg_func (char *str, ...) { str; }
38781 u is promoted to int before
38786 * passing to function */
38790 vararg_func ("%c", c);
38797 argument u is not promoted to int,
38802 * it is passed as char to function
38808 --std-cXX is not defined;
38813 * is promoted to int before passing
38819 if --std-cXX is defined */
38823 vararg_func ("%bc", (char)u);
38829 \begin_layout Section
38830 Cyclomatic Complexity
38831 \begin_inset LatexCommand index
38832 name "Cyclomatic complexity"
38839 \begin_layout Standard
38840 Cyclomatic complexity of a function is defined as the number of independent
38841 paths the program can take during execution of the function.
38842 This is an important number since it defines the number test cases you
38843 have to generate to validate the function.
38844 The accepted industry standard for complexity number is 10, if the cyclomatic
38845 complexity reported by SDCC exceeds 10 you should think about simplification
38846 of the function logic.
38847 Note that the complexity level is not related to the number of lines of
38848 code in a function.
38849 Large functions can have low complexity, and small functions can have large
38855 SDCC uses the following formula to compute the complexity:
38860 \begin_layout Standard
38861 complexity = (number of edges in control flow graph) - (number of nodes
38862 in control flow graph) + 2;
38866 Having said that the industry standard is 10,
38867 you should be aware that in some cases it be may unavoidable to have a
38868 complexity level of less than 10.
38869 For example if you have switch statement with more than 10 case labels,
38870 each case label adds one to the complexity level.
38871 The complexity level is by no means an absolute measure of the algorithmic
38872 complexity of the function, it does however provide a good starting point
38873 for which functions you might look at for further optimization.
38876 \begin_layout Section
38877 Retargetting for other Processors
38880 \begin_layout Standard
38881 The issues for retargetting the compiler are far too numerous to be covered
38883 What follows is a brief description of each of the seven phases of the
38884 compiler and its MCU dependency.
38887 \begin_layout Itemize
38888 Parsing the source and building the annotated parse tree.
38889 This phase is largely MCU independent (except for the language extensions).
38890 Syntax & semantic checks are also done in this phase, along with some initial
38891 optimizations like back patching labels and the pattern matching optimizations
38892 like bit-rotation etc.
38895 \begin_layout Itemize
38896 The second phase involves generating an intermediate code which can be easy
38897 manipulated during the later phases.
38898 This phase is entirely MCU independent.
38899 The intermediate code generation assumes the target machine has unlimited
38900 number of registers, and designates them with the name iTemp.
38901 The compiler can be made to dump a human readable form of the code generated
38906 \begin_layout Standard
38918 \begin_layout Itemize
38919 This phase does the bulk of the standard optimizations and is also MCU independe
38921 This phase can be broken down into several sub-phases:
38925 Break down intermediate
38926 code (iCode) into basic blocks.
38928 Do control flow & data flow analysis on the
38931 Do local common subexpression elimination, then global subexpressio
38934 Dead code elimination
38938 If loop optimizations
38939 caused any changes then do 'global subexpression elimination' and 'dead
38940 code elimination' again.
38943 \begin_layout Itemize
38944 This phase determines the live-ranges; by live range I mean those iTemp
38945 variables defined by the compiler that still survive after all the optimization
38947 Live range analysis
38948 \begin_inset LatexCommand index
38949 name "Live range analysis"
38953 is essential for register allocation, since these computation determines
38954 which of these iTemps will be assigned to registers, and for how long.
38957 \begin_layout Itemize
38958 Phase five is register allocation.
38959 There are two parts to this process.
38963 The first part I call 'register packing'
38964 (for lack of a better term).
38965 In this case several MCU specific expression folding is done to reduce
38970 The second part is more MCU independent and deals with
38971 allocating registers to the remaining live ranges.
38972 A lot of MCU specific code does creep into this phase because of the limited
38973 number of index registers available in the 8051.
38976 \begin_layout Itemize
38977 The Code generation phase is (unhappily), entirely MCU dependent and very
38978 little (if any at all) of this code can be reused for other MCU.
38979 However the scheme for allocating a homogenized assembler operand for each
38980 iCode operand may be reused.
38983 \begin_layout Itemize
38984 As mentioned in the optimization section the peep-hole optimizer is rule
38985 based system, which can reprogrammed for other MCUs.
38988 \begin_layout Standard
38989 More information is available on SDCC Wiki
38990 \begin_inset LatexCommand index
38996 \begin_inset LatexCommand url
38997 target "http://sdcc.wiki.sourceforge.net/SDCC+internals+and+porting"
39001 ) and in the thread
39002 \begin_inset LatexCommand url
39003 target "http://sf.net/mailarchive/message.php?msg_id=13954144"
39010 \begin_layout Chapter
39012 \begin_inset LatexCommand index
39013 name "Compiler internals"
39020 \begin_layout Section
39021 The anatomy of the compiler
39022 \begin_inset LatexCommand label
39023 name "sub:The-anatomy-of"
39030 \begin_layout Standard
39033 This is an excerpt from an article published in Circuit Cellar Magazine
39042 It's a little outdated (the compiler is much more efficient now and user/develo
39043 per friendly), but pretty well exposes the guts of it all.
39049 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
39050 It is fairly easy to retarget for other 8-bit MCU.
39051 Here we take a look at some of the internals of the compiler.
39055 \begin_layout Paragraph*
39057 \begin_inset LatexCommand index
39065 \begin_layout Standard
39066 Parsing the input source file and creating an AST (Annotated Syntax Tree
39067 \begin_inset LatexCommand index
39068 name "Annotated syntax tree"
39073 This phase also involves propagating types (annotating each node of the
39074 parse tree with type information) and semantic analysis.
39075 There are some MCU specific parsing rules.
39076 For example the storage classes, the extended storage classes are MCU specific
39077 while there may be a xdata storage class for 8051 there is no such storage
39078 class for z80 or Atmel AVR.
39079 SDCC allows MCU specific storage class extensions, i.e.
39080 xdata will be treated as a storage class specifier when parsing 8051 C
39081 code but will be treated as a C identifier when parsing z80 or ATMEL AVR
39085 \begin_layout Paragraph*
39087 \begin_inset LatexCommand index
39095 \begin_layout Standard
39096 Intermediate code generation.
39097 In this phase the AST is broken down into three-operand form (iCode).
39098 These three operand forms are represented as doubly linked lists.
39099 ICode is the term given to the intermediate form generated by the compiler.
39100 ICode example section shows some examples of iCode generated for some simple
39101 C source functions.
39104 \begin_layout Paragraph*
39106 \begin_inset LatexCommand index
39107 name "Optimizations"
39114 \begin_layout Standard
39115 Bulk of the target independent optimizations is performed in this phase.
39116 The optimizations include constant propagation, common sub-expression eliminati
39117 on, loop invariant code movement, strength reduction of loop induction variables
39118 and dead-code elimination.
39121 \begin_layout Paragraph*
39122 Live range analysis
39123 \begin_inset LatexCommand index
39124 name "Live range analysis"
39131 \begin_layout Standard
39132 During intermediate code generation phase, the compiler assumes the target
39133 machine has infinite number of registers and generates a lot of temporary
39135 The live range computation determines the lifetime of each of these compiler-ge
39136 nerated temporaries.
39137 A picture speaks a thousand words.
39138 ICode example sections show the live range annotations for each of the
39140 It is important to note here, each iCode is assigned a number in the order
39141 of its execution in the function.
39142 The live ranges are computed in terms of these numbers.
39143 The from number is the number of the iCode which first defines the operand
39144 and the to number signifies the iCode which uses this operand last.
39147 \begin_layout Paragraph*
39148 Register Allocation
39149 \begin_inset LatexCommand index
39150 name "Register allocation"
39157 \begin_layout Standard
39158 The register allocation determines the type and number of registers needed
39160 In most MCUs only a few registers can be used for indirect addressing.
39161 In case of 8051 for example the registers R0 & R1 can be used to indirectly
39162 address the internal ram and DPTR to indirectly address the external ram.
39163 The compiler will try to allocate the appropriate register to pointer variables
39165 ICode example section shows the operands annotated with the registers assigned
39167 The compiler will try to keep operands in registers as much as possible;
39168 there are several schemes the compiler uses to do achieve this.
39169 When the compiler runs out of registers the compiler will check to see
39170 if there are any live operands which is not used or defined in the current
39171 basic block being processed, if there are any found then it will push that
39172 operand and use the registers in this block, the operand will then be popped
39173 at the end of the basic block.
39177 \begin_layout Standard
39178 There are other MCU specific considerations in this phase.
39179 Some MCUs have an accumulator; very short-lived operands could be assigned
39180 to the accumulator instead of a general-purpose register.
39183 \begin_layout Paragraph*
39187 \begin_layout Standard
39188 Figure II gives a table of iCode
39189 \begin_inset LatexCommand index
39194 operations supported by the compiler.
39195 The code generation involves translating these operations into corresponding
39196 assembly code for the processor.
39197 This sounds overly simple but that is the essence of code generation.
39198 Some of the iCode operations are generated on a MCU specific manner for
39199 example, the z80 port does not use registers to pass parameters so the
39200 SEND and RECV iCode operations will not be generated, and it also does
39201 not support JUMPTABLES.
39207 \begin_layout Standard
39211 \begin_inset Tabular
39212 <lyxtabular version="3" rows="39" columns="4">
39213 <features islongtable="true" headBottomDL="true">
39214 <column alignment="block" valignment="top" leftline="true" width="13col%">
39215 <column alignment="left" valignment="top" leftline="true" width="13col%">
39216 <column alignment="block" valignment="top" leftline="true" width="22col%">
39217 <column alignment="block" valignment="top" leftline="true" rightline="true" width="40col%">
39218 <row topline="true" bottomline="true" endhead="true">
39219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39222 \begin_layout Standard
39228 \begin_inset LatexCommand index
39238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39241 \begin_layout Standard
39249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39252 \begin_layout Standard
39260 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39263 \begin_layout Standard
39272 <row topline="true">
39273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39276 \begin_layout Standard
39284 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39287 \begin_layout Standard
39290 IC_LEFT() IC_RESULT()
39295 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39298 \begin_layout Standard
39306 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39309 \begin_layout Standard
39312 IC_RESULT = ! IC_LEFT;
39318 <row topline="true">
39319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39322 \begin_layout Standard
39330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39333 \begin_layout Standard
39336 IC_LEFT() IC_RESULT()
39341 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39344 \begin_layout Standard
39347 Bitwise complement of
39352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39355 \begin_layout Standard
39358 IC_RESULT = ~IC_LEFT;
39364 <row topline="true">
39365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39368 \begin_layout Standard
39376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39379 \begin_layout Standard
39382 IC_LEFT() IC_RESULT()
39387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39390 \begin_layout Standard
39393 Rotate right with carry
39398 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39401 \begin_layout Standard
39404 IC_RESULT = (IC_LEFT << 1) | (IC_LEFT >> (sizeof(IC_LEFT)*8-1));
39410 <row topline="true">
39411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39414 \begin_layout Standard
39422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39425 \begin_layout Standard
39428 IC_LEFT() IC_RESULT()
39433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39436 \begin_layout Standard
39439 Rotate left with carry
39444 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39447 \begin_layout Standard
39450 IC_RESULT = (IC_LEFT << (sizeof(LC_LEFT)*8-1) ) | (IC_LEFT >> 1);
39456 <row topline="true">
39457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39460 \begin_layout Standard
39468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39471 \begin_layout Standard
39474 IC_LEFT() IC_RESULT()
39479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39482 \begin_layout Standard
39485 Get the highest order bit of IC_LEFT
39490 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39493 \begin_layout Standard
39496 IC_RESULT = (IC_LEFT >> (sizeof(IC_LEFT)*8 -1));
39502 <row topline="true">
39503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39506 \begin_layout Standard
39514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39517 \begin_layout Standard
39520 IC_LEFT() IC_RESULT()
39525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39528 \begin_layout Standard
39536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39539 \begin_layout Standard
39542 IC_RESULT = - IC_LEFT;
39548 <row topline="true">
39549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39552 \begin_layout Standard
39560 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39563 \begin_layout Standard
39571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39574 \begin_layout Standard
39577 Push the operand into stack
39582 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39585 \begin_layout Standard
39594 <row topline="true">
39595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39598 \begin_layout Standard
39606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39609 \begin_layout Standard
39617 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39620 \begin_layout Standard
39623 Pop the operand from the stack
39628 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39631 \begin_layout Standard
39640 <row topline="true">
39641 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39644 \begin_layout Standard
39652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39655 \begin_layout Standard
39658 IC_LEFT() IC_RESULT()
39663 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39666 \begin_layout Standard
39669 Call the function represented by IC_LEFT
39674 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39677 \begin_layout Standard
39680 IC_RESULT = IC_LEFT();
39686 <row topline="true">
39687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39690 \begin_layout Standard
39698 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39701 \begin_layout Standard
39704 IC_LEFT() IC_RESULT()
39709 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39712 \begin_layout Standard
39715 Call via function pointer
39720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39723 \begin_layout Standard
39726 IC_RESULT = (*IC_LEFT)();
39732 <row topline="true">
39733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39736 \begin_layout Standard
39744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39747 \begin_layout Standard
39755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39758 \begin_layout Standard
39761 Return the value in operand IC_LEFT
39766 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39769 \begin_layout Standard
39778 <row topline="true">
39779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39782 \begin_layout Standard
39790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39793 \begin_layout Standard
39801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39804 \begin_layout Standard
39812 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39815 \begin_layout Standard
39824 <row topline="true">
39825 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39828 \begin_layout Standard
39836 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39839 \begin_layout Standard
39847 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39850 \begin_layout Standard
39858 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39861 \begin_layout Standard
39870 <row topline="true">
39871 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39874 \begin_layout Standard
39882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39885 \begin_layout Standard
39888 IC_LEFT() IC_RIGHT() IC_RESULT()
39893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39896 \begin_layout Standard
39904 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39907 \begin_layout Standard
39910 IC_RESULT = IC_LEFT + IC_RIGHT
39916 <row topline="true">
39917 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39920 \begin_layout Standard
39928 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39931 \begin_layout Standard
39934 IC_LEFT() IC_RIGHT() IC_RESULT()
39939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39942 \begin_layout Standard
39950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39953 \begin_layout Standard
39956 IC_RESULT = IC_LEFT - IC_RIGHT
39962 <row topline="true">
39963 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39966 \begin_layout Standard
39974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39977 \begin_layout Standard
39980 IC_LEFT() IC_RIGHT() IC_RESULT()
39985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39988 \begin_layout Standard
39996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39999 \begin_layout Standard
40002 IC_RESULT = IC_LEFT * IC_RIGHT;
40008 <row topline="true">
40009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40012 \begin_layout Standard
40020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40023 \begin_layout Standard
40026 IC_LEFT() IC_RIGHT() IC_RESULT()
40031 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40034 \begin_layout Standard
40042 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40045 \begin_layout Standard
40048 IC_RESULT = IC_LEFT / IC_RIGHT;
40054 <row topline="true">
40055 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40058 \begin_layout Standard
40066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40069 \begin_layout Standard
40072 IC_LEFT() IC_RIGHT() IC_RESULT()
40077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40080 \begin_layout Standard
40088 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40091 \begin_layout Standard
40094 IC_RESULT = IC_LEFT % IC_RIGHT;
40100 <row topline="true">
40101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40104 \begin_layout Standard
40112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40115 \begin_layout Standard
40118 IC_LEFT() IC_RIGHT() IC_RESULT()
40123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40126 \begin_layout Standard
40134 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40137 \begin_layout Standard
40140 IC_RESULT = IC_LEFT < IC_RIGHT;
40146 <row topline="true">
40147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40150 \begin_layout Standard
40158 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40161 \begin_layout Standard
40164 IC_LEFT() IC_RIGHT() IC_RESULT()
40169 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40172 \begin_layout Standard
40180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40183 \begin_layout Standard
40186 IC_RESULT = IC_LEFT > IC_RIGHT;
40192 <row topline="true">
40193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40196 \begin_layout Standard
40204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40207 \begin_layout Standard
40210 IC_LEFT() IC_RIGHT() IC_RESULT()
40215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40218 \begin_layout Standard
40226 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40229 \begin_layout Standard
40232 IC_RESULT = IC_LEFT == IC_RIGHT;
40238 <row topline="true">
40239 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40242 \begin_layout Standard
40250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40253 \begin_layout Standard
40256 IC_LEFT() IC_RIGHT() IC_RESULT()
40261 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40264 \begin_layout Standard
40267 Logical and operation
40272 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40275 \begin_layout Standard
40278 IC_RESULT = IC_LEFT && IC_RIGHT;
40284 <row topline="true">
40285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40288 \begin_layout Standard
40296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40299 \begin_layout Standard
40302 IC_LEFT() IC_RIGHT() IC_RESULT()
40307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40310 \begin_layout Standard
40313 Logical or operation
40318 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40321 \begin_layout Standard
40324 IC_RESULT = IC_LEFT || IC_RIGHT;
40330 <row topline="true">
40331 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40334 \begin_layout Standard
40342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40345 \begin_layout Standard
40348 IC_LEFT() IC_RIGHT() IC_RESULT()
40353 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40356 \begin_layout Standard
40364 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40367 \begin_layout Standard
40370 IC_RESULT = IC_LEFT ^ IC_RIGHT;
40376 <row topline="true">
40377 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40380 \begin_layout Standard
40388 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40391 \begin_layout Standard
40394 IC_LEFT() IC_RIGHT() IC_RESULT()
40399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40402 \begin_layout Standard
40410 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40413 \begin_layout Standard
40416 IC_RESULT = IC_LEFT | IC_RIGHT;
40422 <row topline="true">
40423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40426 \begin_layout Standard
40434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40437 \begin_layout Standard
40440 IC_LEFT() IC_RIGHT() IC_RESULT()
40445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40448 \begin_layout Standard
40456 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40459 \begin_layout Standard
40462 IC_RESULT = IC_LEFT & IC_RIGHT;
40468 <row topline="true">
40469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40472 \begin_layout Standard
40480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40483 \begin_layout Standard
40486 IC_LEFT() IC_RIGHT() IC_RESULT()
40491 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40494 \begin_layout Standard
40502 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40505 \begin_layout Standard
40508 IC_RESULT = IC_LEFT << IC_RIGHT
40514 <row topline="true">
40515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40518 \begin_layout Standard
40526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40529 \begin_layout Standard
40532 IC_LEFT() IC_RIGHT() IC_RESULT()
40537 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40540 \begin_layout Standard
40548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40551 \begin_layout Standard
40554 IC_RESULT = IC_LEFT >> IC_RIGHT
40560 <row topline="true">
40561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40564 \begin_layout Standard
40574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40577 \begin_layout Standard
40580 IC_LEFT() IC_RESULT()
40585 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40588 \begin_layout Standard
40596 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40599 \begin_layout Standard
40602 IC_RESULT = (*IC_LEFT);
40608 <row topline="true">
40609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40612 \begin_layout Standard
40620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40623 \begin_layout Standard
40626 IC_RIGHT() IC_RESULT()
40631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40634 \begin_layout Standard
40642 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40645 \begin_layout Standard
40648 (*IC_RESULT) = IC_RIGHT;
40654 <row topline="true">
40655 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40658 \begin_layout Standard
40666 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40669 \begin_layout Standard
40672 IC_RIGHT() IC_RESULT()
40677 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40680 \begin_layout Standard
40688 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40691 \begin_layout Standard
40694 IC_RESULT = IC_RIGHT;
40700 <row topline="true">
40701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40704 \begin_layout Standard
40712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40715 \begin_layout Standard
40718 IC_COND IC_TRUE IC_LABEL
40723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40726 \begin_layout Standard
40730 If true label is present then jump to true label if condition is true else
40731 jump to false label if condition is false
40736 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40739 \begin_layout Standard
40742 if (IC_COND) goto IC_TRUE;
40748 If (!IC_COND) goto IC_FALSE;
40754 <row topline="true">
40755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40758 \begin_layout Standard
40766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40769 \begin_layout Standard
40772 IC_LEFT() IC_RESULT()
40777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40780 \begin_layout Standard
40788 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40791 \begin_layout Standard
40794 IC_RESULT = &IC_LEFT();
40800 <row topline="true">
40801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40804 \begin_layout Standard
40812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40815 \begin_layout Standard
40818 IC_JTCOND IC_JTLABELS
40823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40826 \begin_layout Standard
40829 Jump to list of labels depending on the value of JTCOND
40834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40837 \begin_layout Standard
40846 <row topline="true">
40847 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40850 \begin_layout Standard
40858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40861 \begin_layout Standard
40864 IC_RIGHT() IC_LEFT() IC_RESULT()
40869 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40872 \begin_layout Standard
40880 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40883 \begin_layout Standard
40886 IC_RESULT = (typeof IC_LEFT) IC_RIGHT;
40892 <row topline="true">
40893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40896 \begin_layout Standard
40904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40907 \begin_layout Standard
40915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40918 \begin_layout Standard
40921 This is used for passing parameters in registers;
40923 move IC_LEFT to the next
40924 available parameter register.
40929 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40932 \begin_layout Standard
40941 <row topline="true">
40942 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40945 \begin_layout Standard
40953 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40956 \begin_layout Standard
40964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40967 \begin_layout Standard
40970 This is used for receiving parameters passed in registers;
40973 in the next parameter register to IC_RESULT
40978 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40981 \begin_layout Standard
40990 <row topline="true" bottomline="true">
40991 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40994 \begin_layout Standard
40998 (some more have been added)
41003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
41006 \begin_layout Standard
41012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
41015 \begin_layout Standard
41021 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
41024 \begin_layout Standard
41057 \begin_layout Standard
41058 \begin_inset Note Note
41061 \begin_layout Standard
41062 In the original article Figure II was announced to be downloadable on
41067 ftp://ftp.circuitcellar.com/pub/Circuit_Cellar/2000/121/dutta.ZIP
41075 \begin_layout Paragraph*
41077 \begin_inset LatexCommand index
41085 \begin_layout Standard
41086 This section shows some details of iCode.
41087 The example C code does not do anything useful; it is used as an example
41088 to illustrate the intermediate code generated by the compiler.
41091 \begin_layout Verse
41101 /* This function does nothing useful.
41108 for the purpose of explaining iCode */
41111 short function (data
41120 short i=10; \InsetSpace ~
41122 /* dead initialization eliminated */
41128 /* dead initialization eliminated */
41156 /* compiler detects i,j to be induction
41161 for (i = 0, j = 10 ; i < 10 ; i++, j
41167 \begin_layout Standard
41190 mul += i * 3; \InsetSpace ~
41192 /* this multiplication remains */
41199 j * 3;\InsetSpace ~
41201 /* this multiplication changed to addition */
41215 \begin_layout Standard
41216 In addition to the operands each iCode contains information about the filename
41217 and line it corresponds to in the source file.
41218 The first field in the listing should be interpreted as follows:
41223 Filename(linenumber: iCode Execution sequence number : ICode hash table
41224 key : loop depth of the iCode).
41229 Then follows the human readable form of the ICode operation.
41230 Each operand of this triplet form can be of three basic types a) compiler
41231 generated temporary b) user defined variable c) a constant value.
41232 Note that local variables and parameters are replaced by compiler generated
41235 \begin_inset LatexCommand index
41236 name "Live range analysis"
41240 are computed only for temporaries (i.e.
41241 live ranges are not computed for global variables).
41243 \begin_inset LatexCommand index
41244 name "Register allocation"
41248 are allocated for temporaries only.
41249 Operands are formatted in the following manner:
41254 Operand Name [lr live-from : live-to ] { type information } [ registers
41260 As mentioned earlier the live ranges are computed in terms of the execution
41261 sequence number of the iCodes, for example
41263 the iTemp0 is live from (i.e.
41264 first defined in iCode with execution sequence number 3, and is last used
41265 in the iCode with sequence number 5).
41266 For induction variables such as iTemp21 the live range computation extends
41267 the lifetime from the start to the end of the loop.
41269 The register allocator
41270 used the live range information to allocate registers, the same registers
41271 may be used for different temporaries if their live ranges do not overlap,
41272 for example r0 is allocated to both iTemp6 and to iTemp17 since their live
41273 ranges do not overlap.
41274 In addition the allocator also takes into consideration the type and usage
41275 of a temporary, for example itemp6 is a pointer to near space and is used
41276 as to fetch data from (i.e.
41277 used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
41278 Some short lived temporaries are allocated to special registers which have
41279 meaning to the code generator e.g.
41280 iTemp13 is allocated to a pseudo register CC which tells the back end that
41281 the temporary is used only for a conditional jump the code generation makes
41282 use of this information to optimize a compare and jump ICode.
41286 \begin_inset LatexCommand index
41287 name "Loop optimization"
41291 performed by the compiler.
41292 It can detect induction variables iTemp21(i) and iTemp23(j).
41293 Also note the compiler does selective strength reduction
41294 \begin_inset LatexCommand index
41295 name "Strength reduction"
41300 the multiplication of an induction variable in line 18 (gint = j * 3) is
41301 changed to addition, a new temporary iTemp17 is allocated and assigned
41302 a initial value, a constant 3 is then added for each iteration of the loop.
41303 The compiler does not change the multiplication
41304 \begin_inset LatexCommand index
41305 name "Multiplication"
41309 in line 17 however since the processor does support an 8 * 8 bit multiplication.
41312 Note the dead code elimination
41313 \begin_inset LatexCommand index
41314 name "Dead-code elimination"
41318 optimization eliminated the dead assignments in line 7 & 8 to I and sum
41324 \begin_layout Standard
41327 Sample.c (5:1:0:0) _entry($9) :
41330 \begin_layout Standard
41333 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
41336 \begin_layout Standard
41339 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
41342 \begin_layout Standard
41345 Sample.c(11:4:53:0) preHeaderLbl0($11) :
41348 \begin_layout Standard
41351 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
41355 \begin_layout Standard
41358 Sample.c(11:6:5:1) _whilecontinue_0($1) :
41361 \begin_layout Standard
41364 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
41368 \begin_layout Standard
41371 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
41374 \begin_layout Standard
41377 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
41381 \begin_layout Standard
41384 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
41388 \begin_layout Standard
41391 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
41395 \begin_layout Standard
41398 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
41402 \begin_layout Standard
41405 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
41406 * int}[r0] + 0x2 {short}
41409 \begin_layout Standard
41412 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
41415 \begin_layout Standard
41418 Sample.c(11:17:21:0)_whilebreak_0($3) :
41421 \begin_layout Standard
41424 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
41427 \begin_layout Standard
41430 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
41433 \begin_layout Standard
41436 Sample.c(15:20:54:0)preHeaderLbl1($13) :
41439 \begin_layout Standard
41442 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
41445 \begin_layout Standard
41448 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
41451 \begin_layout Standard
41454 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
41457 \begin_layout Standard
41460 Sample.c(15:24:26:1)_forcond_0($4) :
41463 \begin_layout Standard
41466 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
41470 \begin_layout Standard
41473 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
41476 \begin_layout Standard
41479 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
41480 + ITemp21 [lr21:38]{short}[r4]
41483 \begin_layout Standard
41486 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
41490 \begin_layout Standard
41493 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
41494 + iTemp15 [lr29:30]{short}[r1]
41497 \begin_layout Standard
41500 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
41504 \begin_layout Standard
41507 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
41511 \begin_layout Standard
41514 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
41518 \begin_layout Standard
41521 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
41525 \begin_layout Standard
41528 Sample.c(19:38:47:1) goto _forcond_0($4)
41531 \begin_layout Standard
41534 Sample.c(19:39:48:0)_forbreak_0($7) :
41537 \begin_layout Standard
41540 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
41541 + ITemp11 [lr19:40]{short}[r3]
41544 \begin_layout Standard
41547 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
41550 \begin_layout Standard
41553 Sample.c(20:42:51:0)_return($8) :
41556 \begin_layout Standard
41559 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
41565 Finally the code generated for this function:
41570 \begin_layout Standard
41576 \begin_layout Standard
41582 \begin_layout Standard
41590 \begin_layout Standard
41596 \begin_layout Standard
41604 \begin_layout Standard
41610 \begin_layout Standard
41613 ; ----------------------------------------------
41616 \begin_layout Standard
41619 ; function function
41622 \begin_layout Standard
41625 ; ----------------------------------------------
41628 \begin_layout Standard
41634 \begin_layout Standard
41637 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
41640 \begin_layout Standard
41648 \begin_layout Standard
41651 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
41654 \begin_layout Standard
41662 \begin_layout Standard
41665 ;_whilecontinue_0($1) :
41668 \begin_layout Standard
41674 \begin_layout Standard
41677 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
41680 \begin_layout Standard
41683 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
41686 \begin_layout Standard
41694 \begin_layout Standard
41702 \begin_layout Standard
41710 \begin_layout Standard
41718 \begin_layout Standard
41726 \begin_layout Standard
41734 \begin_layout Standard
41742 \begin_layout Standard
41748 \begin_layout Standard
41751 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
41754 \begin_layout Standard
41762 \begin_layout Standard
41770 \begin_layout Standard
41773 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
41776 \begin_layout Standard
41784 \begin_layout Standard
41792 \begin_layout Standard
41800 \begin_layout Standard
41808 \begin_layout Standard
41816 \begin_layout Standard
41824 \begin_layout Standard
41827 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
41830 \begin_layout Standard
41838 \begin_layout Standard
41846 \begin_layout Standard
41854 \begin_layout Standard
41862 \begin_layout Standard
41870 \begin_layout Standard
41873 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
41876 \begin_layout Standard
41884 \begin_layout Standard
41892 \begin_layout Standard
41900 \begin_layout Standard
41903 ; iTemp6 [lr5:16]{_near * int}[r0] =
41906 \begin_layout Standard
41909 ; iTemp6 [lr5:16]{_near * int}[r0] +
41912 \begin_layout Standard
41918 \begin_layout Standard
41926 \begin_layout Standard
41929 ; goto _whilecontinue_0($1)
41932 \begin_layout Standard
41940 \begin_layout Standard
41943 ; _whilebreak_0($3) :
41946 \begin_layout Standard
41952 \begin_layout Standard
41955 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
41958 \begin_layout Standard
41966 \begin_layout Standard
41969 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
41972 \begin_layout Standard
41980 \begin_layout Standard
41983 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
41986 \begin_layout Standard
41994 \begin_layout Standard
41997 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
42000 \begin_layout Standard
42008 \begin_layout Standard
42016 \begin_layout Standard
42019 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
42022 \begin_layout Standard
42030 \begin_layout Standard
42038 \begin_layout Standard
42044 \begin_layout Standard
42050 \begin_layout Standard
42053 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
42056 \begin_layout Standard
42059 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
42062 \begin_layout Standard
42070 \begin_layout Standard
42078 \begin_layout Standard
42086 \begin_layout Standard
42094 \begin_layout Standard
42102 \begin_layout Standard
42108 \begin_layout Standard
42111 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
42114 \begin_layout Standard
42117 ; iTemp21 [lr21:38]{short}[r4]
42120 \begin_layout Standard
42128 \begin_layout Standard
42136 \begin_layout Standard
42144 \begin_layout Standard
42147 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
42150 \begin_layout Standard
42158 \begin_layout Standard
42166 \begin_layout Standard
42174 \begin_layout Standard
42182 \begin_layout Standard
42185 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
42188 \begin_layout Standard
42191 ; iTemp15 [lr29:30]{short}[r1]
42194 \begin_layout Standard
42202 \begin_layout Standard
42210 \begin_layout Standard
42213 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
42216 \begin_layout Standard
42224 \begin_layout Standard
42232 \begin_layout Standard
42240 \begin_layout Standard
42248 \begin_layout Standard
42256 \begin_layout Standard
42264 \begin_layout Standard
42267 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
42270 \begin_layout Standard
42278 \begin_layout Standard
42286 \begin_layout Standard
42294 \begin_layout Standard
42302 \begin_layout Standard
42310 \begin_layout Standard
42318 \begin_layout Standard
42321 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
42324 \begin_layout Standard
42332 \begin_layout Standard
42335 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
42338 \begin_layout Standard
42346 \begin_layout Standard
42351 cjne r5,#0xff,00104$
42354 \begin_layout Standard
42362 \begin_layout Standard
42365 ; goto _forcond_0($4)
42368 \begin_layout Standard
42376 \begin_layout Standard
42379 ; _forbreak_0($7) :
42382 \begin_layout Standard
42388 \begin_layout Standard
42391 ; ret iTemp24 [lr40:41]{short}
42394 \begin_layout Standard
42402 \begin_layout Standard
42410 \begin_layout Standard
42418 \begin_layout Standard
42424 \begin_layout Standard
42430 \begin_layout Standard
42440 \begin_layout Section
42441 A few words about basic block successors, predecessors and dominators
42444 \begin_layout Standard
42445 Successors are basic blocks
42446 \begin_inset LatexCommand index
42447 name "Basic blocks"
42451 that might execute after this basic block.
42453 Predecessors are basic blocks
42454 that might execute before reaching this basic block.
42456 Dominators are basic
42457 blocks that WILL execute before reaching this basic block.
42462 \begin_layout Standard
42466 \begin_layout Standard
42470 \begin_layout Standard
42478 \begin_layout Standard
42482 \begin_layout Standard
42490 \begin_layout Standard
42496 \begin_layout Standard
42497 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
42500 \begin_layout Standard
42501 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
42504 \begin_layout Standard
42505 c) domVect of [BB4] = BB1 ...
42506 here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
42510 \begin_layout Chapter
42514 \begin_layout Standard
42515 \begin_inset LatexCommand url
42516 target "http://sdcc.sourceforge.net/#Who"
42526 Thanks to all the other volunteer developers who have helped with coding,
42527 testing, web-page creation, distribution sets, etc.
42528 You know who you are :-)
42536 Thanks to Sourceforge
42537 \begin_inset LatexCommand url
42538 target "http://www.sf.net"
42542 which has hosted the project since 1999 and donates significant download
42551 Also thanks to all SDCC Distributed Compile Farm members for donating CPU
42552 cycles and bandwidth for snapshot builds.
42557 \begin_layout Standard
42558 This document was initially written by Sandeep Dutta
42561 \begin_layout Standard
42562 All product names mentioned herein may be trademarks
42563 \begin_inset LatexCommand index
42568 of their respective companies.
42572 \begin_layout Section*
42576 \begin_layout Standard
42577 To avoid confusion, the installation and building options for SDCC itself
42578 (chapter 2) are not part of the index.
42581 \begin_layout Standard
42582 \begin_inset LatexCommand printindex