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
62 \begin_layout Standard
63 \begin_inset Note Note
66 \begin_layout Standard
67 Please note: double dashed longoptions (e.g.
68 --version) are written this way: -
72 \begin_layout Standard
84 \begin_layout Standard
86 three consecutive dashes would otherwise result in a long resp.
90 \begin_layout Standard
91 Architecture specific stuff (like memory models, code examples) should maybe
95 \begin_layout Standard
96 into separate sections/chapters/appendices (it is hard to document PIC or
100 \begin_layout Standard
101 a 8051 centered document) - for now simply add.
110 SDCC Compiler User Guide
125 \begin_layout Standard
126 \begin_inset Note Note
129 \begin_layout Standard
130 The above strings enclosed in $ are automatically updated by Subversion
138 \begin_layout Standard
139 \begin_inset LatexCommand tableofcontents
146 \begin_layout Chapter
150 \begin_layout Section
154 \begin_layout Standard
175 ompiler) is free open source, retargettable, optimizing ANSI-C compiler
180 designed for 8 bit Microprocessors.
181 The current version targets Intel MCS51 based Microprocessors (8031, 8032,
183 \begin_inset LatexCommand index
184 name "8031, 8032, 8051, 8052, mcs51 CPU"
188 , etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
189 Zilog Z80 based MCUs.
190 It can be retargeted for other microprocessors, support for Microchip PIC,
191 Atmel AVR is under development.
192 The entire source code for the compiler is distributed under GPL.
194 \begin_inset LatexCommand index
195 name "asXXXX (as-gbz80, as-hc08, asx8051, as-z80)"
200 \begin_inset LatexCommand index
205 , an open source retargetable assembler & linker.
206 SDCC has extensive language extensions suitable for utilizing various microcont
207 rollers and underlying hardware effectively.
212 In addition to the MCU specific optimizations SDCC also does a host of
213 standard optimizations like:
216 \begin_layout Itemize
217 global sub expression elimination,
220 \begin_layout Itemize
221 loop optimizations (loop invariant, strength reduction of induction variables
225 \begin_layout Itemize
226 constant folding & propagation,
229 \begin_layout Itemize
233 \begin_layout Itemize
234 dead code elimination
237 \begin_layout Itemize
245 \begin_layout Standard
246 For the back-end SDCC uses a global register allocation scheme which should
247 be well suited for other 8 bit MCUs.
252 The peep hole optimizer uses a rule based substitution mechanism which
258 Supported data-types are:
261 \begin_layout Standard
263 <lyxtabular version="3" rows="8" columns="5">
265 <column alignment="center" valignment="top" leftline="true" width="0">
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="block" valignment="top" leftline="true" rightline="true" width="20text%">
270 <row topline="true" bottomline="true">
271 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
274 \begin_layout Standard
280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
283 \begin_layout Standard
289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
292 \begin_layout Standard
298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
301 \begin_layout Standard
307 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
310 \begin_layout Standard
318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
321 \begin_layout Standard
327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
330 \begin_layout Standard
336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
339 \begin_layout Standard
345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
348 \begin_layout Standard
354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
357 \begin_layout Standard
365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
368 \begin_layout Standard
374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
377 \begin_layout Standard
383 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
386 \begin_layout Standard
392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
395 \begin_layout Standard
401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
404 \begin_layout Standard
412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
415 \begin_layout Standard
421 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
424 \begin_layout Standard
430 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
433 \begin_layout Standard
439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
442 \begin_layout Standard
448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
451 \begin_layout Standard
459 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
462 \begin_layout Standard
468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
471 \begin_layout Standard
477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
480 \begin_layout Standard
486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
489 \begin_layout Standard
495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
498 \begin_layout Standard
505 <row topline="true" bottomline="true">
506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
509 \begin_layout Standard
515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
518 \begin_layout Standard
524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
527 \begin_layout Standard
533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
536 \begin_layout Standard
537 -2.147.483.648, +2.147.483.647
542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
545 \begin_layout Standard
552 <row topline="true" bottomline="true">
553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
556 \begin_layout Standard
562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
565 \begin_layout Standard
571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
574 \begin_layout Standard
580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
583 \begin_layout Standard
589 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
592 \begin_layout Standard
608 <row topline="true" bottomline="true">
609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
612 \begin_layout Standard
618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
621 \begin_layout Standard
627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
630 \begin_layout Standard
636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
639 \begin_layout Standard
645 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
648 \begin_layout Standard
661 The compiler also allows
663 inline assembler code
665 to be embedded anywhere in a function.
666 In addition, routines developed in assembly can also be called.
671 provides an option (-
675 \begin_layout Standard
684 -cyclomatic) to report the relative complexity of a function.
685 These functions can then be further optimized, or hand coded in assembly
691 SDCC also comes with a companion source level debugger SDCDB.
692 The debugger currently uses ucSim, a free open source simulator for 8051
693 and other micro-controllers.
697 The latest SDCC version can be downloaded from
699 \begin_inset LatexCommand url
700 target "http://sdcc.sourceforge.net/snap.php"
707 Please note: the compiler will probably always be some steps ahead of this
712 \begin_inset LatexCommand index
713 name "Status of documentation"
721 \begin_layout Standard
722 Obviously this has pros and cons
730 \begin_layout Section
734 \begin_layout Standard
735 All packages used in this compiler system are
743 ; source code for all the sub-packages (pre-processor, assemblers, linkers
744 etc.) is distributed with the package.
745 This documentation is maintained using a free open source word processor
748 This program is free software; you can redistribute it and/or modify
749 it under the terms of the GNU General Public License
750 \begin_inset LatexCommand index
751 name "GNU General Public License, GPL"
755 as published by the Free Software Foundation; either version 2, or (at
756 your option) any later version.
757 This program is distributed in the hope that it will be useful, but WITHOUT
758 ANY WARRANTY; without even the implied warranty
759 \begin_inset LatexCommand index
764 of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
765 See the GNU General Public License for more details.
766 You should have received a copy of the GNU General Public License along
767 with this program; if not, write to the Free Software Foundation, 59 Temple
768 Place - Suite 330, Boston, MA 02111-1307, USA.
769 In other words, you are welcome to use, share and improve this program.
770 You are forbidden to forbid anyone else to use, share and improve what
772 Help stamp out software-hoarding!
775 \begin_layout Section
776 Typographic conventions
777 \begin_inset LatexCommand index
778 name "Typographic conventions"
785 \begin_layout Standard
786 Throughout this manual, we will use the following convention.
787 Commands you have to type in are printed in
795 Code samples are printed in
800 Interesting items and new terms are printed in
805 \begin_layout Section
807 \begin_inset LatexCommand label
808 name "sec:Compatibility-with-previous"
812 with previous versions
813 \begin_inset LatexCommand index
814 name "Compatibility with previous versions"
821 \begin_layout Standard
822 Newer versions have usually numerous bug fixes compared with the previous
824 But we also sometimes introduce some incompatibilities with older versions.
825 Not just for the fun of it, but to make the compiler more stable, efficient
827 \begin_inset LatexCommand index
828 name "ANSI-compliance"
833 \begin_inset LatexCommand ref
834 reference "sub:ANSI-Compliance"
838 for ANSI-Compliance).
840 \begin_inset Note Note
843 \begin_layout Standard
844 It would be fine to add to each item, in which version was it changed.
854 \begin_layout Itemize
855 short is now equivalent to int (16 bits), it used to be equivalent to char
856 (8 bits) which is not ANSI compliant.
857 To maintain compatibility, old programs may be compiled using the -
861 \begin_layout Standard
870 -short-is-8bits commandline option (see
871 \begin_inset LatexCommand vref
872 reference "lyx:--short-is-8bits"
879 \begin_layout Itemize
880 the default directory for gcc-builds where include, library and documentation
881 files are stored is now in /usr/local/share.
884 \begin_layout Itemize
885 char type parameters to vararg
886 \begin_inset LatexCommand index
887 name "vararg, va\\_arg"
891 functions are casted to int unless explicitly casted and
897 \begin_layout Standard
907 \begin_inset LatexCommand index
920 \begin_layout Standard
930 \begin_inset LatexCommand index
937 command line option are not defined
938 \begin_inset Marginal
941 \begin_layout Standard
966 will push a as an int and as a char resp if
972 \begin_layout Standard
982 \begin_inset LatexCommand index
995 \begin_layout Standard
1005 \begin_inset LatexCommand index
1012 command line options are not defined,
1014 will push a as two ints if
1020 \begin_layout Standard
1030 \begin_inset LatexCommand index
1043 \begin_layout Standard
1053 \begin_inset LatexCommand index
1060 command line option is defined.
1063 \begin_layout Itemize
1068 \begin_layout Standard
1077 -regextend has been removed.
1080 \begin_layout Itemize
1085 \begin_layout Standard
1094 -noregparms has been removed.
1097 \begin_layout Itemize
1102 \begin_layout Standard
1111 -stack-after-data has been removed.
1114 \begin_layout Itemize
1116 \begin_inset LatexCommand index
1122 \begin_inset LatexCommand index
1128 \begin_inset LatexCommand index
1133 types now consistently behave like the C99 _Bool type with respect to type
1135 \begin_inset LatexCommand index
1136 name "type conversion"
1141 \begin_inset LatexCommand index
1142 name "type promotion"
1147 The most common incompatibility resulting from this change is related to
1149 \begin_inset LatexCommand index
1165 \begin_inset LatexCommand index
1166 name "\\~\\/ Operator"
1170 b; /* equivalent to b=1 instead of toggling b */
1171 \begin_inset Marginal
1174 \begin_layout Standard
1187 b = !b; /* toggles b */
1191 In previous versions, both forms would have toggled the bit.
1194 \begin_layout Itemize
1195 in older versions, the preprocessor was always called with
1201 \begin_layout Standard
1211 \begin_inset LatexCommand index
1224 \begin_layout Standard
1236 This is no longer true, and can cause compilation failures on code built
1243 \begin_layout Standard
1253 \begin_inset LatexCommand index
1260 but using c99 preprocessor features, such as one-line (//) comments
1263 \begin_layout Itemize
1264 in versions older then 2.8.4 the pic16 *printf() and printf_tiny() library
1265 functions supported undocumented and not standard compliant 'b' binary
1266 format specifier ("%b", "%hb" and "%lb").
1267 The 'b' specifier is now disabled by default.
1268 It can be enabled by defining BINARY_SPECIFIER macro in files device/lib/pic16/
1269 libc/stdio/vfprintf.c and device/lib/pic16/libc/stdio/printf_tiny.c and recompilin
1273 \begin_layout Itemize
1274 in versions older then 2.8.5 the unnamed bitfield structure members participated
1275 in initialization, which is not conforming with ISO/IEC 9899:1999 standard
1276 (see section Section 6.7.8 Initialization, clause 9)
1280 Old behavior, before
1316 /* s.a = 1, s.b = 3 */
1357 /* s.a = 1, s.b = 2 */
1360 \begin_layout Section
1364 \begin_layout Standard
1365 What do you need before you start installation of SDCC? A computer, and
1366 a desire to compute.
1367 The preferred method of installation is to compile SDCC from source using
1369 For Windows some pre-compiled binary distributions are available for your
1371 You should have some experience with command line tools and compiler use.
1374 \begin_layout Section
1378 \begin_layout Standard
1379 The SDCC home page at
1380 \begin_inset LatexCommand url
1381 target "http://sdcc.sourceforge.net/"
1385 is a great place to find distribution sets.
1386 You can also find links to the user mailing lists that offer help or discuss
1387 SDCC with other SDCC users.
1388 Web links to other SDCC related sites can also be found here.
1389 This document can be found in the DOC directory of the source package as
1390 a text or HTML file.
1391 A pdf version of this document is available at
1392 \begin_inset LatexCommand url
1393 target "http://sdcc.sourceforge.net/doc/sdccman.pdf"
1398 Some of the other tools (simulator and assembler) included with SDCC contain
1399 their own documentation and can be found in the source distribution.
1400 If you want the latest unreleased software, the complete source package
1401 is available directly from Subversion on https://sdcc.svn.sourceforge.net/svnroot/
1405 \begin_layout Section
1406 Wishes for the future
1409 \begin_layout Standard
1410 There are (and always will be) some things that could be done.
1411 Here are some I can think of:
1416 \begin_layout Standard
1419 char KernelFunction3(char p) at 0x340;
1424 \begin_layout Standard
1428 \begin_inset LatexCommand index
1429 name "code banking (limited support)"
1439 If you can think of some more, please see the section
1440 \begin_inset LatexCommand ref
1441 reference "sub:Requesting-Features"
1445 about filing feature requests
1446 \begin_inset LatexCommand index
1447 name "Requesting features"
1452 \begin_inset LatexCommand index
1453 name "Feature request"
1462 \begin_layout Chapter
1464 \begin_inset LatexCommand index
1472 \begin_layout Standard
1473 For most users it is sufficient to skip to either section
1474 \begin_inset LatexCommand ref
1475 reference "sub:Building-SDCC-on-Linux"
1480 \begin_inset LatexCommand ref
1481 reference "sub:Windows-Install"
1486 More detailed instructions follow below.
1489 \begin_layout Section
1491 \begin_inset LatexCommand index
1492 name "Options SDCC configuration"
1499 \begin_layout Standard
1500 The install paths, search paths and other options are defined when running
1502 The defaults can be overridden by:
1506 \labelwidthstring 00.00.0000
1511 \begin_layout Standard
1520 -prefix see table below
1524 \labelwidthstring 00.00.0000
1529 \begin_layout Standard
1538 -exec_prefix see table below
1542 \labelwidthstring 00.00.0000
1547 \begin_layout Standard
1556 -bindir see table below
1560 \labelwidthstring 00.00.0000
1565 \begin_layout Standard
1574 -datadir see table below
1578 \labelwidthstring 00.00.0000
1583 \begin_layout Standard
1592 -datarootdir see table below
1598 \labelwidthstring 00.00.0000
1601 docdir environment variable, see table below
1605 \labelwidthstring 00.00.0000
1608 include_dir_suffix environment variable, see table below
1612 \labelwidthstring 00.00.0000
1615 lib_dir_suffix environment variable, see table below
1619 \labelwidthstring 00.00.0000
1622 sdccconf_h_dir_separator environment variable, either / or
1627 This character will only be used in sdccconf.h; don't forget it's a C-header,
1628 therefore a double-backslash is needed there.
1634 \labelwidthstring 00.00.0000
1639 \begin_layout Standard
1648 -disable-mcs51-port Excludes the Intel mcs51 port
1652 \labelwidthstring 00.00.0000
1657 \begin_layout Standard
1666 -disable-gbz80-port Excludes the Gameboy gbz80 port
1670 \labelwidthstring 00.00.0000
1675 \begin_layout Standard
1684 -disable-z80-port Excludes the z80 port
1688 \labelwidthstring 00.00.0000
1693 \begin_layout Standard
1702 -disable-avr-port Excludes the AVR port
1706 \labelwidthstring 00.00.0000
1711 \begin_layout Standard
1720 -disable-ds390-port Excludes the DS390 port
1724 \labelwidthstring 00.00.0000
1729 \begin_layout Standard
1738 -disable-hc08-port Excludes the HC08 port
1742 \labelwidthstring 00.00.0000
1747 \begin_layout Standard
1756 -disable-pic-port Excludes the PIC14 port
1760 \labelwidthstring 00.00.0000
1765 \begin_layout Standard
1774 -disable-pic16-port Excludes the PIC16 port
1778 \labelwidthstring 00.00.0000
1783 \begin_layout Standard
1792 -disable-xa51-port Excludes the XA51 port
1796 \labelwidthstring 00.00.0000
1801 \begin_layout Standard
1810 -disable-ucsim Disables configuring and building of ucsim
1814 \labelwidthstring 00.00.0000
1819 \begin_layout Standard
1828 -disable-device-lib Disables automatically building device libraries
1832 \labelwidthstring 00.00.0000
1837 \begin_layout Standard
1846 -disable-packihx Disables building packihx
1852 \labelwidthstring 00.00.0000
1857 \begin_layout Standard
1866 -enable-doc Build pdf, html and txt files from the lyx sources
1870 \labelwidthstring 00.00.0000
1875 \begin_layout Standard
1884 -enable-libgc Use the Bohem memory allocator.
1885 Lower runtime footprint.
1889 \labelwidthstring 00.00.0000
1894 \begin_layout Standard
1903 -without-ccache Do not use ccache even if available
1906 \begin_layout Standard
1907 Furthermore the environment variables CC, CFLAGS, ...
1908 the tools and their arguments can be influenced.
1909 Please see `configure -
1913 \begin_layout Standard
1922 -help' and the man/info pages of `configure' for details.
1927 standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB, STD_FP_LIB, STD_DS390_LI
1928 B, STD_XA51_LIB and the environment variables SDCC_DIR_NAME, SDCC_INCLUDE_NAME,
1929 SDCC_LIB_NAME are defined by `configure' too.
1930 At the moment it's not possible to change the default settings (it was
1931 simply never required).
1935 These configure options are compiled into the binaries,
1936 and can only be changed by rerunning 'configure' and recompiling SDCC.
1937 The configure options are written in
1941 to distinguish them from run time environment variables (see section search
1947 \begin_inset Quotes sld
1951 \begin_inset Quotes srd
1954 are used by the SDCC team to build the official Win32 binaries.
1955 The SDCC team uses Mingw32 to build the official Windows binaries, because
1959 \begin_layout Enumerate
1963 \begin_layout Enumerate
1964 a gcc compiler and last but not least
1967 \begin_layout Enumerate
1968 the binaries can be built by cross compiling on SDCC Distributed Compile
1972 \begin_layout Standard
1973 See the examples, how to pass the Win32 settings to 'configure'.
1974 The other Win32 builds using Borland, VC or whatever don't use 'configure',
1975 but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
1985 \begin_layout Standard
1987 \begin_inset Tabular
1988 <lyxtabular version="3" rows="9" columns="3">
1990 <column alignment="block" valignment="top" leftline="true" width="0in">
1991 <column alignment="block" valignment="top" leftline="true" width="0in">
1992 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1993 <row topline="true" bottomline="true">
1994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1997 \begin_layout Standard
2003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2006 \begin_layout Standard
2012 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2015 \begin_layout Standard
2022 <row topline="true">
2023 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2026 \begin_layout Standard
2034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2037 \begin_layout Standard
2043 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2046 \begin_layout Standard
2055 <row topline="true">
2056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2059 \begin_layout Standard
2067 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2070 \begin_layout Standard
2078 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2081 \begin_layout Standard
2090 <row topline="true">
2091 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2094 \begin_layout Standard
2102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2105 \begin_layout Standard
2115 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2118 \begin_layout Standard
2131 <row topline="true">
2132 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2135 \begin_layout Standard
2143 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2146 \begin_layout Standard
2154 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2157 \begin_layout Standard
2166 <row topline="true">
2167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2170 \begin_layout Standard
2178 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2181 \begin_layout Standard
2191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2194 \begin_layout Standard
2203 <row topline="true">
2204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2207 \begin_layout Standard
2215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2218 \begin_layout Standard
2228 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2231 \begin_layout Standard
2244 <row topline="true">
2245 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2248 \begin_layout Standard
2256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2259 \begin_layout Standard
2265 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2268 \begin_layout Standard
2275 <row topline="true" bottomline="true">
2276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2279 \begin_layout Standard
2287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2290 \begin_layout Standard
2296 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2299 \begin_layout Standard
2315 \begin_layout Standard
2317 'configure' also computes relative paths.
2318 This is needed for full relocatability of a binary package and to complete
2319 search paths (see section search paths below):
2324 \begin_layout Standard
2326 \begin_inset Tabular
2327 <lyxtabular version="3" rows="4" columns="3">
2329 <column alignment="block" valignment="top" leftline="true" width="0in">
2330 <column alignment="block" valignment="top" leftline="true" width="0in">
2331 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2332 <row topline="true" bottomline="true">
2333 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2336 \begin_layout Standard
2342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2345 \begin_layout Standard
2351 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2354 \begin_layout Standard
2361 <row topline="true" bottomline="true">
2362 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2365 \begin_layout Standard
2373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2376 \begin_layout Standard
2382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2385 \begin_layout Standard
2392 <row bottomline="true">
2393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2396 \begin_layout Standard
2404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2407 \begin_layout Standard
2413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2416 \begin_layout Standard
2423 <row bottomline="true">
2424 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2427 \begin_layout Standard
2435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2438 \begin_layout Standard
2444 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2447 \begin_layout Standard
2463 \begin_layout Standard
2468 \begin_layout LyX-Code
2475 \begin_layout Standard
2485 \begin_inset Quotes srd
2489 \begin_inset Quotes srd
2496 \begin_layout Standard
2506 \begin_inset Quotes srd
2510 \begin_inset Quotes srd
2519 \begin_layout Standard
2532 \begin_layout Standard
2544 \begin_layout Standard
2545 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
2549 \begin_layout LyX-Code
2555 \begin_inset Quotes srd
2558 i586-mingw32msvc-gcc
2559 \begin_inset Quotes srd
2563 \begin_inset Quotes srd
2566 i586-mingw32msvc-g++
2567 \begin_inset Quotes srd
2575 \begin_inset Quotes srd
2578 i586-mingw32msvc-ranlib
2579 \begin_inset Quotes srd
2587 \begin_inset Quotes srd
2590 i586-mingw32msvc-strip
2591 \begin_inset Quotes srd
2602 \begin_layout Standard
2612 \begin_inset Quotes srd
2616 \begin_inset Quotes srd
2627 \begin_layout Standard
2637 \begin_inset Quotes srd
2641 \begin_inset Quotes srd
2649 \begin_inset Quotes srd
2655 \begin_inset Quotes srd
2663 \begin_inset Quotes srd
2667 \begin_inset Quotes srd
2675 \begin_inset Quotes srd
2679 \begin_inset Quotes srd
2686 sdccconf_h_dir_separator=
2687 \begin_inset Quotes srd
2699 \begin_inset Quotes srd
2710 \begin_layout Standard
2727 \begin_layout Standard
2736 -host=i586-mingw32msvc
2744 \begin_layout Standard
2753 -build=unknown-unknown-linux-gnu
2756 \begin_layout Standard
2758 \begin_inset Quotes sld
2762 \begin_inset Quotes srd
2765 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
2769 \begin_layout LyX-Code
2778 \begin_layout Standard
2788 \begin_inset Quotes srd
2792 \begin_inset Quotes srd
2803 \begin_layout Standard
2813 \begin_inset Quotes srd
2817 \begin_inset Quotes srd
2825 \begin_inset Quotes srd
2831 \begin_inset Quotes srd
2839 \begin_inset Quotes srd
2843 \begin_inset Quotes srd
2851 \begin_inset Quotes srd
2855 \begin_inset Quotes srd
2862 sdccconf_h_dir_separator=
2863 \begin_inset Quotes srd
2875 \begin_inset Quotes srd
2883 \begin_inset Quotes srd
2887 \begin_inset Quotes srd
2895 \begin_inset Quotes srd
2899 \begin_inset Quotes srd
2905 \begin_layout Standard
2906 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
2911 \begin_layout Standard
2920 -C' turns on caching, which gives a little bit extra speed.
2921 However if options are changed, it can be necessary to delete the config.cache
2925 \begin_layout Section
2927 \begin_inset LatexCommand label
2928 name "sub:Install-paths"
2933 \begin_inset LatexCommand index
2934 name "Install paths"
2941 \begin_layout Standard
2942 \begin_inset VSpace medskip
2948 \begin_layout Standard
2950 \begin_inset Tabular
2951 <lyxtabular version="3" rows="5" columns="4">
2953 <column alignment="left" valignment="top" leftline="true" width="0">
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" rightline="true" width="0">
2957 <row topline="true" bottomline="true">
2958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2961 \begin_layout Standard
2969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2972 \begin_layout Standard
2980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2983 \begin_layout Standard
2991 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2994 \begin_layout Standard
3003 <row topline="true">
3004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3007 \begin_layout Standard
3013 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3016 \begin_layout Standard
3024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3027 \begin_layout Standard
3033 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3036 \begin_layout Standard
3047 <row topline="true">
3048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3051 \begin_layout Standard
3057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3060 \begin_layout Standard
3063 $DATADIR/ $INCLUDE_DIR_SUFFIX
3068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3071 \begin_layout Standard
3072 /usr/local/share/sdcc/include
3077 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3080 \begin_layout Standard
3091 <row topline="true">
3092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3095 \begin_layout Standard
3101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3104 \begin_layout Standard
3107 $DATADIR/$LIB_DIR_SUFFIX
3112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3115 \begin_layout Standard
3116 /usr/local/share/sdcc/lib
3121 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3124 \begin_layout Standard
3135 <row topline="true" bottomline="true">
3136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3139 \begin_layout Standard
3145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3148 \begin_layout Standard
3156 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3159 \begin_layout Standard
3160 /usr/local/share/sdcc/doc
3165 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3168 \begin_layout Standard
3189 *compiler, preprocessor, assembler, and linker
3195 is auto-appended by the compiler, e.g.
3196 small, large, z80, ds390 etc
3199 \begin_layout Standard
3201 The install paths can still be changed during `make install' with e.g.:
3204 \begin_layout LyX-Code
3205 make install prefix=$(HOME)/local/sdcc
3208 \begin_layout Standard
3209 Of course this doesn't change the search paths compiled into the binaries.
3214 r the install path can be changed by defining DESTDIR
3215 \begin_inset LatexCommand index
3223 \begin_layout LyX-Code
3224 make install DESTDIR=$(HOME)/sdcc.rpm/
3227 \begin_layout Standard
3228 Please note that DESTDIR must have a trailing slash!
3231 \begin_layout Section
3233 \begin_inset LatexCommand label
3234 name "sub:Search-Paths"
3239 \begin_inset LatexCommand index
3247 \begin_layout Standard
3248 Some search paths or parts of them are determined by configure variables
3253 , see section above).
3254 Further search paths are determined by environment variables during runtime.
3257 The paths searched when running the compiler are as follows (the first
3263 Binary files (preprocessor, assembler and linker)
3268 \begin_layout Standard
3270 \begin_inset Tabular
3271 <lyxtabular version="3" rows="4" columns="3">
3273 <column alignment="block" valignment="top" leftline="true" width="0in">
3274 <column alignment="block" valignment="top" leftline="true" width="0in">
3275 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
3276 <row topline="true" bottomline="true">
3277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3280 \begin_layout Standard
3286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3289 \begin_layout Standard
3295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3298 \begin_layout Standard
3305 <row topline="true">
3306 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3309 \begin_layout Standard
3317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3320 \begin_layout Standard
3326 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3329 \begin_layout Standard
3338 <row topline="true">
3339 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3342 \begin_layout Standard
3343 Path of argv[0] (if available)
3348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3351 \begin_layout Standard
3357 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3360 \begin_layout Standard
3367 <row topline="true" bottomline="true">
3368 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3371 \begin_layout Standard
3377 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3380 \begin_layout Standard
3386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3389 \begin_layout Standard
3405 \begin_layout Standard
3413 \begin_layout Standard
3415 \begin_inset Tabular
3416 <lyxtabular version="3" rows="6" columns="3">
3418 <column alignment="block" valignment="top" leftline="true" width="1.5in">
3419 <column alignment="block" valignment="top" leftline="true" width="1.5in">
3420 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
3421 <row topline="true" bottomline="true">
3422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3425 \begin_layout Standard
3431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3434 \begin_layout Standard
3440 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3443 \begin_layout Standard
3450 <row topline="true">
3451 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3454 \begin_layout Standard
3459 \begin_layout Standard
3473 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3476 \begin_layout Standard
3481 \begin_layout Standard
3495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3498 \begin_layout Standard
3503 \begin_layout Standard
3518 <row topline="true">
3519 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3522 \begin_layout Standard
3528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3531 \begin_layout Standard
3537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3540 \begin_layout Standard
3547 <row topline="true">
3548 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3551 \begin_layout Standard
3563 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3566 \begin_layout Standard
3576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3579 \begin_layout Standard
3588 <row topline="true">
3589 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3592 \begin_layout Standard
3608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3611 \begin_layout Standard
3659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3662 \begin_layout Standard
3673 <row topline="true" bottomline="true">
3674 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3677 \begin_layout Standard
3691 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3694 \begin_layout Standard
3695 /usr/local/share/sdcc/
3702 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3705 \begin_layout Standard
3721 \begin_layout Standard
3727 \begin_layout Standard
3736 -nostdinc disables the last two search paths.
3746 \begin_layout Standard
3747 With the exception of
3748 \begin_inset Quotes sld
3755 \begin_layout Standard
3765 \begin_inset Quotes srd
3772 is auto-appended by the compiler (e.g.
3773 small, large, z80, ds390 etc.).
3779 \begin_layout Standard
3781 \begin_inset Tabular
3782 <lyxtabular version="3" rows="6" columns="3">
3784 <column alignment="block" valignment="top" leftline="true" width="1.7in">
3785 <column alignment="block" valignment="top" leftline="true" width="1.2in">
3786 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
3787 <row topline="true" bottomline="true">
3788 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3791 \begin_layout Standard
3797 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3800 \begin_layout Standard
3806 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3809 \begin_layout Standard
3816 <row topline="true">
3817 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3820 \begin_layout Standard
3825 \begin_layout Standard
3839 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3842 \begin_layout Standard
3847 \begin_layout Standard
3861 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3864 \begin_layout Standard
3869 \begin_layout Standard
3884 <row topline="true">
3885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3888 \begin_layout Standard
3898 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3901 \begin_layout Standard
3911 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3914 \begin_layout Standard
3927 <row topline="true">
3928 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3931 \begin_layout Standard
3938 $LIB_DIR_SUFFIX/<model>
3943 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3946 \begin_layout Standard
3958 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3961 \begin_layout Standard
3976 <row topline="true">
3977 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3980 \begin_layout Standard
3991 $LIB_DIR_SUFFIX/<model>
3996 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3999 \begin_layout Standard
4050 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4053 \begin_layout Standard
4107 <row topline="true" bottomline="true">
4108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4111 \begin_layout Standard
4116 $LIB_DIR_SUFFIX/<model>
4121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4124 \begin_layout Standard
4125 /usr/local/share/sdcc/
4134 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4137 \begin_layout Standard
4153 \begin_layout Standard
4154 \begin_inset Note Note
4157 \begin_layout Standard
4158 Don't delete any of the stray spaces in the table above without checking
4159 the HTML output (last line)!
4167 \begin_layout Standard
4175 \begin_layout Standard
4184 -nostdlib disables the last two search paths.
4187 \begin_layout Section
4189 \begin_inset LatexCommand index
4190 name "Building SDCC"
4197 \begin_layout Subsection
4198 Building SDCC on Linux
4199 \begin_inset LatexCommand label
4200 name "sub:Building-SDCC-on-Linux"
4207 \begin_layout Enumerate
4210 Download the source package
4212 either from the SDCC Subversion repository or from snapshot builds
4214 , it will be named something like sdcc
4225 \begin_inset LatexCommand url
4226 target "http://sdcc.sourceforge.net/snap.php"
4233 \begin_layout Enumerate
4236 Bring up a command line terminal, such as xterm.
4239 \begin_layout Enumerate
4242 Unpack the file using a command like:
4247 "tar -xvzf sdcc-src-yyyymmdd-rrrr.tar.bz2
4248 \begin_inset Quotes srd
4254 , this will create a sub-directory called sdcc with all of the sources.
4257 \begin_layout Enumerate
4258 Change directory into the main SDCC directory, for example type:
4266 \begin_layout Enumerate
4278 This configures the package for compilation on your system.
4281 \begin_layout Enumerate
4297 All of the source packages will compile, this can take a while.
4300 \begin_layout Enumerate
4316 This copies the binary executables, the include files, the libraries and
4317 the documentation to the install directories.
4318 Proceed with section
4319 \begin_inset LatexCommand ref
4320 reference "sec:Testing-the-SDCC"
4327 \begin_layout Subsection
4328 Building SDCC on Mac OS X
4331 \begin_layout Standard
4332 Follow the instruction for Linux.
4336 On Mac OS X 10.2.x it was reported, that the
4337 default gcc (version 3.1 20020420 (prerelease)) fails to compile SDCC.
4338 Fortunately there's also gcc 2.9.x installed, which works fine.
4339 This compiler can be selected by running 'configure' with:
4342 \begin_layout LyX-Code
4343 ./configure CC=gcc2 CXX=g++2
4346 \begin_layout Standard
4347 Universal (ppc and i386) binaries can be produced on Mac OS X 10.4.x with
4349 Run 'configure' with:
4352 \begin_layout LyX-Code
4358 \begin_layout LyX-Code
4359 LDFLAGS="-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch
4365 \begin_layout LyX-Code
4366 CXXFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch
4372 \begin_layout LyX-Code
4373 CFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc"
4376 \begin_layout Subsection
4377 Cross compiling SDCC on Linux for Windows
4380 \begin_layout Standard
4381 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
4382 See section 'Configure Options'.
4385 \begin_layout Subsection
4386 Building SDCC using Cygwin and Mingw32
4389 \begin_layout Standard
4390 For building and installing a Cygwin executable follow the instructions
4396 \begin_inset Quotes sld
4400 \begin_inset Quotes srd
4403 Win32-binary can be built, which will not need the Cygwin-DLL.
4404 For the necessary 'configure' options see section 'configure options' or
4405 the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
4410 Cygwin on Windows download setup.exe from
4411 \begin_inset LatexCommand url
4412 name "www.cygwin.com"
4413 target "http://www.cygwin.com/"
4419 \begin_inset Quotes sld
4422 default text file type
4423 \begin_inset Quotes srd
4427 \begin_inset Quotes sld
4431 \begin_inset Quotes srd
4434 and download/install at least the following packages.
4435 Some packages are selected by default, others will be automatically selected
4436 because of dependencies with the manually selected packages.
4437 Never deselect these packages!
4440 \begin_layout Itemize
4444 \begin_layout Itemize
4448 \begin_layout Itemize
4449 gcc ; version 3.x is fine, no need to use the old 2.9x
4452 \begin_layout Itemize
4453 binutils ; selected with gcc
4456 \begin_layout Itemize
4460 \begin_layout Itemize
4461 rxvt ; a nice console, which makes life much easier under windoze (see below)
4464 \begin_layout Itemize
4465 man ; not really needed for building SDCC, but you'll miss it sooner or
4469 \begin_layout Itemize
4470 less ; not really needed for building SDCC, but you'll miss it sooner or
4474 \begin_layout Itemize
4475 svn ; only if you use Subversion access
4478 \begin_layout Standard
4479 If you want to develop something you'll need:
4482 \begin_layout Itemize
4483 python ; for the regression tests
4486 \begin_layout Itemize
4487 gdb ; the gnu debugger, together with the nice GUI
4488 \begin_inset Quotes sld
4492 \begin_inset Quotes srd
4498 \begin_layout Itemize
4499 openssh ; to access the CF or commit changes
4502 \begin_layout Itemize
4503 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
4504 use autoconf-stable!
4507 \begin_layout Standard
4508 rxvt is a nice console with history.
4509 Replace in your cygwin.bat the line
4512 \begin_layout LyX-Code
4517 \begin_layout Standard
4529 \begin_layout Standard
4533 \begin_layout LyX-Code
4534 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
4537 \begin_layout LyX-Code
4538 -bg black -fg white -geometry 100x65 -e bash -
4542 \begin_layout Standard
4554 \begin_layout Standard
4555 Text selected with the mouse is automatically copied to the clipboard, pasting
4556 works with shift-insert.
4560 The other good tip is to make sure you have no //c/-styl
4561 e paths anywhere, use /cygdrive/c/ instead.
4562 Using // invokes a network lookup which is very slow.
4564 \begin_inset Quotes sld
4568 \begin_inset Quotes srd
4571 is too long, you can change it with e.g.
4574 \begin_layout LyX-Code
4578 \begin_layout Standard
4579 SDCC sources use the unix line ending LF.
4580 Life is much easier, if you store the source tree on a drive which is mounted
4582 And use an editor which can handle LF-only line endings.
4583 Make sure not to commit files with windows line endings.
4584 The tabulator spacing
4585 \begin_inset LatexCommand index
4586 name "tabulator spacing (8 columns)"
4590 used in the project is 8.
4591 Although a tabulator spacing of 8 is a sensible choice for programmers
4592 (it's a power of 2 and allows to display 8/16 bit signed variables without
4593 loosing columns) the plan is to move towards using only spaces in the source.
4596 \begin_layout Subsection
4597 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
4600 \begin_layout Standard
4603 Download the source package
4605 either from the SDCC Subversion repository or from the
4606 \begin_inset LatexCommand url
4607 name "snapshot builds"
4608 target "http://sdcc.sourceforge.net/snap.php"
4614 , it will be named something like sdcc
4618 -yyyymmdd-rrrr.tar.bz2.
4621 SDCC is distributed with all the projects, workspaces, and files you need
4622 to build it using Visual C++ 6.0/NET (except for SDCDB and ucSim).
4623 The workspace name is 'sdcc.dsw'.
4624 Please note that as it is now, all the executables are created in a folder
4628 Once built you need to copy the executables from sdcc
4632 bin before running SDCC.
4637 WARNING: Visual studio is very picky with line terminations; it expects
4638 the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
4639 When using the Subversion repository it's easiest to configure the svn
4640 client to convert automatically for you.
4641 If however you are getting a message such as "This makefile was not generated
4642 by Developer Studio etc.
4644 \begin_inset Quotes srd
4647 when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
4648 need to convert the Unix style line endings to DOS style line endings.
4649 To do so you can use the
4650 \begin_inset Quotes sld
4654 \begin_inset Quotes srd
4657 utility freely available on the internet.
4658 Doug Hawkins reported in the sdcc-user list that this works:
4666 SDCC> unix2dos sdcc.dsw
4672 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
4676 In order to build SDCC with MSVC
4677 you need win32 executables of bison.exe, flex.exe, and gawk.exe.
4678 One good place to get them is
4679 \begin_inset LatexCommand url
4681 target "http://unxutils.sourceforge.net"
4689 Download the file UnxUtils
4690 \begin_inset LatexCommand index
4696 Now you have to install the utilities and setup MSVC so it can locate the
4698 Here there are two alternatives (choose one!):
4701 \begin_layout Enumerate
4706 a) Extract UnxUtils.zip to your C:
4708 hard disk PRESERVING the original paths, otherwise bison won't work.
4709 (If you are using WinZip make certain that 'Use folder names' is selected)
4714 In the Visual C++ IDE click Tools, Options, select the Directory tab, in
4715 'Show directories for:' select 'Executable files', and in the directories
4716 window add a new path: 'C:
4726 (As a side effect, you get a bunch of Unix utilities that
4727 could be useful, such as diff and patch.)
4730 \begin_layout Enumerate
4735 This one avoids extracting a bunch of files you may not
4736 use, but requires some extra work:
4740 a) Create a directory were to put the
4741 tools needed, or use a directory already present.
4748 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and
4749 gawk.exe to such directory WITHOUT preserving the original paths.
4750 (If you are using WinZip make certain that 'Use folder names' is not selected)
4755 ) Rename bison.exe to '_bison.exe'.
4759 d) Create a batch file 'bison.bat' in 'C:
4763 ' and add these lines:
4783 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
4787 Steps 'c' and 'd' are needed
4788 because bison requires by default that the files 'bison.simple' and 'bison.hairy'
4789 reside in some weird Unix directory, '/usr/local/share/' I think.
4790 So it is necessary to tell bison where those files are located if they
4791 are not in such directory.
4792 That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
4797 ) In the Visual C++ IDE click Tools, Options, select the Directory tab,
4798 in 'Show directories for:' select 'Executable files', and in the directories
4799 window add a new path: 'c:
4802 Note that you can use any other path instead of 'c:
4804 util', even the path where the Visual C++ tools are, probably: 'C:
4808 Microsoft Visual Studio
4813 So you don't have to execute step 'e' :)
4816 \begin_layout Standard
4818 Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
4819 the executables from sdcc
4823 bin, and you can compile using SDCC.
4826 \begin_layout Subsection
4827 Building SDCC Using Borland
4830 \begin_layout Enumerate
4831 From the sdcc directory, run the command "make -f Makefile.bcc".
4832 This should regenerate all the .exe files in the bin directory except for
4836 \begin_layout Enumerate
4837 If you modify any source files and need to rebuild, be aware that the dependenci
4838 es may not be correctly calculated.
4839 The safest option is to delete all .obj files and run the build again.
4840 From a Cygwin BASH prompt, this can easily be done with the command (be
4841 sure you are in the sdcc directory):
4851 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
4853 ) -print -exec rm {}
4862 or on Windows NT/2000/XP from the command prompt with the command:
4869 del /s *.obj *.lib *.rul
4872 from the sdcc directory.
4875 \begin_layout Subsection
4876 Windows Install Using a ZIP Package
4879 \begin_layout Enumerate
4880 Download the binary zip package from
4881 \begin_inset LatexCommand url
4882 target "http://sdcc.sf.net/snap.php"
4886 and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
4887 This should unpack to a group of sub-directories.
4888 An example directory structure after unpacking the mingw32 package is:
4893 bin for the executables, c:
4901 lib for the include and libraries.
4904 \begin_layout Enumerate
4905 Adjust your environment variable PATH to include the location of the bin
4906 directory or start sdcc using the full path.
4909 \begin_layout Subsection
4910 Windows Install Using the Setup Program
4911 \begin_inset LatexCommand label
4912 name "sub:Windows-Install"
4919 \begin_layout Standard
4920 Download the setup program
4922 sdcc-x.y.z-setup.exe
4924 for an official release from
4927 \begin_inset LatexCommand url
4928 target "http://sf.net/project/showfiles.php?group_id=599"
4932 or a setup program for one of the snapshots
4934 sdcc-yyyymmdd-xxxx-setup.exe
4937 \begin_inset LatexCommand url
4938 target "http://sdcc.sf.net/snap.php"
4943 A windows typical installer will guide you through the installation process.
4946 \begin_layout Subsection
4948 \begin_inset LatexCommand index
4956 \begin_layout Standard
4957 SDCC supports the VPATH feature provided by configure and make.
4958 It allows to separate the source and build trees.
4962 \begin_layout Standard
4989 \begin_layout Standard
4992 tar -xzf sdcc.src.tar.gz\InsetSpace ~
4993 # extract source to directory sdcc
4996 \begin_layout Standard
4999 mkdir sdcc.build\InsetSpace ~
5008 # put output in sdcc.build
5011 \begin_layout Standard
5017 \begin_layout Standard
5020 ../sdcc/configure\InsetSpace ~
5028 # configure is doing all the magic!
5031 \begin_layout Standard
5037 \begin_layout Standard
5043 will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
5044 It automagically computes the variables srcdir, top_srcdir and top_buildir
5050 the generated files will be in ~/sdcc.build, while the source files stay
5053 This is not only usefull for building different binaries, e.g.
5054 when cross compiling.
5055 It also gives you a much better overview in the source tree when all the
5056 generated files are not scattered between the source files.
5057 And the best thing is: if you want to change a file you can leave the original
5058 file untouched in the source directory.
5059 Simply copy it to the build directory, edit it, enter `make clean', `rm
5060 Makefile.dep' and `make'.
5065 will do the rest for you!
5068 \begin_layout Section
5069 Building the Documentation
5072 \begin_layout Standard
5077 \begin_layout Standard
5086 -enable-doc to the configure arguments to build the documentation together
5087 with all the other stuff.
5088 You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
5089 dvips and makeindex) to get the job done.
5090 Another possibility is to change to the doc directory and to type
5094 \begin_inset Quotes srd
5098 \begin_inset Quotes srd
5105 You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
5108 \begin_inset LatexCommand url
5109 target "http://www.lyx.org"
5113 as editor is straightforward.
5114 Prebuilt documentation in html and pdf format is available from
5115 \begin_inset LatexCommand url
5116 target "http://sdcc.sf.net/snap.php"
5123 \begin_layout Section
5124 Reading the Documentation
5125 \begin_inset LatexCommand index
5126 name "Documentation"
5133 \begin_layout Standard
5134 Currently reading the document in pdf format is recommended, as for unknown
5135 reason the hyperlinks are working there whereas in the html version they
5140 \begin_layout Standard
5141 If you should know why please drop us a note
5149 You'll find the pdf version
5150 \begin_inset LatexCommand index
5151 name "PDF version of this document"
5156 \begin_inset LatexCommand url
5157 target "http://sdcc.sf.net/doc/sdccman.pdf"
5165 \begin_inset LatexCommand index
5166 name "HTML version of this document"
5171 \begin_inset LatexCommand url
5172 target "http://sdcc.sf.net/doc/sdccman.html/index.html"
5178 This documentation is in some aspects different from a commercial documentation:
5182 \begin_layout Itemize
5183 It tries to document SDCC for several processor architectures in one document
5184 (commercially these probably would be separate documents/products).
5186 \begin_inset LatexCommand index
5187 name "Status of documentation"
5191 currently matches SDCC for mcs51 and DS390 best and does give too few informati
5193 Z80, PIC14, PIC16 and HC08.
5196 \begin_layout Itemize
5197 There are many references pointing away from this documentation.
5198 Don't let this distract you.
5200 was a reference like
5201 \begin_inset LatexCommand url
5202 target "http://www.opencores.org"
5206 together with a statement
5207 \begin_inset Quotes sld
5210 some processors which are targetted by SDCC can be implemented in a
5227 \begin_inset LatexCommand index
5228 name "FPGA (field programmable gate array)"
5233 \begin_inset Quotes srd
5237 \begin_inset LatexCommand url
5238 target "http://sf.net/projects/fpgac"
5243 \begin_inset LatexCommand index
5244 name "FpgaC ((subset of) C to FPGA compiler)"
5249 \begin_inset Quotes sld
5252 have you ever heard of an open source compiler that compiles a subset of
5254 \begin_inset Quotes srd
5257 we expect you to have a quick look there and come back.
5258 If you read this you are on the right track.
5261 \begin_layout Itemize
5262 Some sections attribute more space to problems, restrictions and warnings
5263 than to the solution.
5266 \begin_layout Itemize
5267 The installation section and the section about the debugger is intimidating.
5270 \begin_layout Itemize
5271 There are still lots of typos and there are more different writing styles
5275 \begin_layout Section
5276 Testing the SDCC Compiler
5277 \begin_inset LatexCommand label
5278 name "sec:Testing-the-SDCC"
5285 \begin_layout Standard
5286 The first thing you should do after installing your SDCC compiler is to
5295 \begin_layout Standard
5305 \begin_inset LatexCommand index
5313 at the prompt, and the program should run and output its version like:
5318 SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
5322 \begin_layout Standard
5323 If it doesn't run, or gives a message about not finding sdcc program, then
5324 you need to check over your installation.
5325 Make sure that the sdcc bin directory is in your executable search path
5326 defined by the PATH environment setting (
5331 \begin_inset LatexCommand ref
5332 reference "sub:Install-Trouble-shooting"
5339 Install trouble-shooting for suggestions
5342 Make sure that the sdcc program is in the bin folder, if not perhaps something
5343 did not install correctly.
5351 is commonly installed as described in section
5352 \begin_inset Quotes sld
5355 Install and search paths
5356 \begin_inset Quotes srd
5365 Make sure the compiler works on a very simple example.
5366 Type in the following test.c program using your favorite
5391 \begin_layout Standard
5394 Compile this using the following command:
5405 If all goes well, the compiler will generate a test.asm and test.rel file.
5406 Congratulations, you've just compiled your first program with SDCC.
5407 We used the -c option to tell SDCC not to link the generated code, just
5408 to keep things simple for this step.
5416 The next step is to try it with the linker.
5428 If all goes well the compiler will link with the libraries and produce
5429 a test.ihx output file.
5434 (no test.ihx, and the linker generates warnings), then the problem is most
5443 usr/local/share/sdcc/lib directory
5450 \begin_inset LatexCommand ref
5451 reference "sub:Install-Trouble-shooting"
5458 Install trouble-shooting for suggestions).
5466 The final test is to ensure
5474 header files and libraries.
5475 Edit test.c and change it to the following:
5493 strcpy(str1, "testing");
5498 \begin_layout Standard
5501 Compile this by typing
5510 This should generate a test.ihx output file, and it should give no warnings
5511 such as not finding the string.h file.
5512 If it cannot find the string.h file, then the problem is that
5516 cannot find the /usr/local/share/sdcc/include directory
5523 \begin_inset LatexCommand ref
5524 reference "sub:Install-Trouble-shooting"
5531 Install trouble-shooting section for suggestions).
5540 \begin_layout Standard
5552 \begin_inset LatexCommand index
5553 name "-\\/-print-search-dirs"
5557 to find exactly where SDCC is looking for the include and lib files.
5560 \begin_layout Section
5561 Install Trouble-shooting
5562 \begin_inset LatexCommand label
5563 name "sub:Install-Trouble-shooting"
5568 \begin_inset LatexCommand index
5569 name "Install trouble-shooting"
5576 \begin_layout Subsection
5577 If SDCC does not build correctly
5580 \begin_layout Standard
5581 A thing to try is starting from scratch by unpacking the .tgz source package
5582 again in an empty directory.
5590 ./configure 2>&1 | tee configure.log
5604 make 2>&1 | tee make.log
5611 If anything goes wrong, you can review the log files to locate the problem.
5612 Or a relevant part of this can be attached to an email that could be helpful
5613 when requesting help from the mailing list.
5616 \begin_layout Subsection
5618 \begin_inset Quotes sld
5622 \begin_inset Quotes srd
5628 \begin_layout Standard
5630 \begin_inset Quotes sld
5634 \begin_inset Quotes srd
5637 command is a script that analyzes your system and performs some configuration
5638 to ensure the source package compiles on your system.
5639 It will take a few minutes to run, and will compile a few tests to determine
5640 what compiler features are installed.
5643 \begin_layout Subsection
5645 \begin_inset Quotes sld
5649 \begin_inset Quotes srd
5655 \begin_layout Standard
5656 This runs the GNU make tool, which automatically compiles all the source
5657 packages into the final installed binary executables.
5660 \begin_layout Subsection
5662 \begin_inset Quotes sld
5666 \begin_inset Quotes erd
5672 \begin_layout Standard
5673 This will install the compiler, other executables libraries and include
5674 files into the appropriate directories.
5676 \begin_inset LatexCommand ref
5677 reference "sub:Install-paths"
5683 \begin_inset LatexCommand ref
5684 reference "sub:Search-Paths"
5689 about install and search paths.
5691 On most systems you will need super-user privilege
5695 \begin_layout Section
5699 \begin_layout Standard
5700 SDCC is not just a compiler, but a collection of tools by various developers.
5701 These include linkers, assemblers, simulators and other components.
5702 Here is a summary of some of the components.
5703 Note that the included simulator and assembler have separate documentation
5704 which you can find in the source package in their respective directories.
5705 As SDCC grows to include support for other processors, other packages from
5706 various developers are included and may have their own sets of documentation.
5711 might want to look at the files which are installed in <installdir>.
5712 At the time of this writing, we find the following programs for gcc-builds:
5717 In <installdir>/bin:
5720 \begin_layout Itemize
5721 sdcc - The compiler.
5724 \begin_layout Itemize
5725 sdcpp - The C preprocessor.
5728 \begin_layout Itemize
5729 asx8051 - The assembler for 8051 type processors.
5732 \begin_layout Itemize
5737 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
5740 \begin_layout Itemize
5741 aslink -The linker for 8051 type processors.
5744 \begin_layout Itemize
5749 link-gbz80 - The Z80 and GameBoy Z80 linkers.
5752 \begin_layout Itemize
5753 s51 - The ucSim 8051 simulator.
5756 \begin_layout Itemize
5757 sdcdb - The source debugger.
5760 \begin_layout Itemize
5761 packihx - A tool to pack (compress) Intel hex files.
5764 \begin_layout Standard
5765 In <installdir>/share/sdcc/include
5768 \begin_layout Itemize
5772 \begin_layout Standard
5773 In <installdir>/share/sdcc/lib
5776 \begin_layout Itemize
5777 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
5781 \begin_layout Standard
5782 In <installdir>/share/sdcc/doc
5785 \begin_layout Itemize
5789 \begin_layout Standard
5790 As development for other processors proceeds, this list will expand to include
5791 executables to support processors like AVR, PIC, etc.
5794 \begin_layout Subsection
5798 \begin_layout Standard
5799 This is the actual compiler, it in turn uses the c-preprocessor and invokes
5800 the assembler and linkage editor.
5803 \begin_layout Subsection
5804 sdcpp - The C-Preprocessor
5807 \begin_layout Standard
5809 \begin_inset LatexCommand index
5810 name "sdcpp (preprocessor)"
5814 is a modified version of the GNU cpp
5815 \begin_inset LatexCommand index
5816 name "cpp|see{sdcpp}"
5821 \begin_inset LatexCommand url
5822 target "http://gcc.gnu.org/"
5827 The C preprocessor is used to pull in #include sources, process #ifdef
5828 statements, #defines and so on.
5831 \begin_layout Subsection
5840 - The Assemblers and Linkage Editors
5843 \begin_layout Standard
5844 This is retargettable assembler & linkage editor, it was developed by Alan
5846 John Hartman created the version for 8051, and I (Sandeep) have made some
5847 enhancements and bug fixes for it to work properly with SDCC.
5850 \begin_layout Subsection
5854 \begin_layout Standard
5856 \begin_inset LatexCommand index
5861 is a free open source simulator developed by Daniel Drotos.
5862 The simulator is built as part of the build process.
5863 For more information visit Daniel's web site at:
5864 \begin_inset LatexCommand url
5865 target "http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51"
5870 It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
5874 \begin_layout Subsection
5875 sdcdb - Source Level Debugger
5878 \begin_layout Standard
5880 \begin_inset LatexCommand index
5881 name "SDCDB (debugger)"
5885 is the companion source level debugger.
5886 More about SDCDB in section
5887 \begin_inset LatexCommand ref
5888 reference "cha:Debugging-with-SDCDB"
5893 The current version of the debugger uses Daniel's Simulator S51
5894 \begin_inset LatexCommand index
5899 , but can be easily changed to use other simulators.
5902 \begin_layout Chapter
5906 \begin_layout Section
5910 \begin_layout Subsection
5911 Single Source File Projects
5914 \begin_layout Standard
5915 For single source file 8051 projects the process is very simple.
5916 Compile your programs with the following command
5919 "sdcc sourcefile.c".
5923 This will compile, assemble and link your source file.
5924 Output files are as follows:
5927 \begin_layout Itemize
5929 \begin_inset LatexCommand index
5935 \begin_inset LatexCommand index
5936 name "Assembler source"
5940 file created by the compiler
5943 \begin_layout Itemize
5945 \begin_inset LatexCommand index
5951 \begin_inset LatexCommand index
5952 name "Assembler listing"
5956 file created by the Assembler
5959 \begin_layout Itemize
5961 \begin_inset LatexCommand index
5967 \begin_inset LatexCommand index
5968 name "Assembler listing"
5972 file updated with linkedit information, created by linkage editor
5975 \begin_layout Itemize
5977 \begin_inset LatexCommand index
5983 \begin_inset LatexCommand index
5984 name "Symbol listing"
5988 for the sourcefile, created by the assembler
5991 \begin_layout Itemize
5993 \begin_inset LatexCommand index
5999 \begin_inset LatexCommand index
6005 \begin_inset LatexCommand index
6010 created by the assembler, input to Linkage editor
6013 \begin_layout Itemize
6015 \begin_inset LatexCommand index
6021 \begin_inset LatexCommand index
6026 for the load module, created by the Linker
6029 \begin_layout Itemize
6031 \begin_inset LatexCommand index
6036 - A file with a summary of the memory usage
6039 \begin_layout Itemize
6041 \begin_inset LatexCommand index
6046 - The load module in Intel hex format
6047 \begin_inset LatexCommand index
6048 name "Intel hex format"
6052 (you can select the Motorola S19 format
6053 \begin_inset LatexCommand index
6054 name "Motorola S19 format"
6062 \begin_layout Standard
6072 \begin_inset LatexCommand index
6073 name "-\\/-out-fmt-s19"
6078 If you need another format you might want to use
6085 \begin_inset LatexCommand index
6086 name "objdump (tool)"
6097 \begin_inset LatexCommand index
6098 name "srecord (bin, hex, ... tool)"
6103 \begin_inset Note Note
6106 \begin_layout Standard
6113 \begin_inset LatexCommand vref
6114 reference "sub:Postprocessing-the-Intel"
6119 Both formats are documented in the documentation of srecord
6120 \begin_inset LatexCommand index
6121 name "srecord (bin, hex, ... tool)"
6128 \begin_layout Itemize
6130 \begin_inset LatexCommand index
6135 - An intermediate file containing debug information needed to create the
6140 \begin_layout Standard
6150 \begin_inset LatexCommand index
6158 \begin_layout Itemize
6160 \begin_inset LatexCommand index
6165 - An optional file (with -
6169 \begin_layout Standard
6178 -debug) containing debug information.
6179 The format is documented in cdbfileformat.pdf
6182 \begin_layout Itemize
6185 \begin_inset LatexCommand index
6186 name "<file> (no extension)"
6190 An optional AOMF or AOMF51
6191 \begin_inset LatexCommand index
6197 \begin_inset LatexCommand label
6202 file containing debug information (generated with option -
6206 \begin_layout Standard
6232 ormat is a subformat of the OMF51 format and is commonly used by third party
6234 \begin_inset LatexCommand index
6239 , simulators, emulators).
6242 \begin_layout Itemize
6244 \begin_inset LatexCommand index
6249 - Dump file to debug the compiler it self (generated with option -
6253 \begin_layout Standard
6262 -dumpall) (see section
6263 \begin_inset LatexCommand ref
6264 reference "sub:Intermediate-Dump-Options"
6270 \begin_inset LatexCommand ref
6271 reference "sub:The-anatomy-of"
6277 \begin_inset Quotes sld
6280 Anatomy of the compiler
6281 \begin_inset Quotes srd
6287 \begin_layout Subsection
6288 Postprocessing the Intel Hex
6289 \begin_inset LatexCommand index
6290 name "Intel hex format"
6295 \begin_inset LatexCommand label
6296 name "sub:Postprocessing-the-Intel"
6303 \begin_layout Standard
6304 In most cases this won't be needed but the Intel Hex file
6305 \begin_inset LatexCommand index
6310 which is generated by SDCC might include lines of varying length and the
6311 addresses within the file are not guaranteed to be strictly ascending.
6312 If your toolchain or a bootloader does not like this you can use the tool
6318 \begin_inset LatexCommand index
6319 name "packihx (tool)"
6323 which is part of the SDCC distribution:
6330 packihx sourcefile.ihx >sourcefile.hex
6337 The separately available
6342 \begin_inset LatexCommand index
6343 name "srecord (bin, hex, ... tool)"
6347 package additionally allows to set undefined locations to a predefined
6348 value, to insert checksums
6349 \begin_inset LatexCommand index
6354 of various flavours (crc, add, xor) and to perform other manipulations
6355 (convert, split, crop, offset, ...).
6363 srec_cat\InsetSpace ~
6365 sourcefile.ihx -intel\InsetSpace ~
6367 -o sourcefile.hex -intel
6374 An example for a more complex command line
6378 \begin_layout Standard
6379 the command backfills
6380 \begin_inset LatexCommand index
6381 name "backfill unused memory"
6385 unused memory with 0x12 and the overall 16 bit sum of the complete 64 kByte
6387 If the program counter on an mcs51 runs wild the backfill pattern 0x12
6388 will be interpreted as an
6396 (where an emergency routine could sit).
6409 srec_cat\InsetSpace ~
6410 sourcefile.ihx -intel\InsetSpace ~
6412 -fill 0x12 0x0000 0xfffe\InsetSpace ~
6413 -little-endian-checksum-nega
6414 tive 0xfffe 0x02 0x02\InsetSpace ~
6416 -o sourcefile.hex -intel
6425 The srecord package is available at
6426 \begin_inset LatexCommand url
6427 target "http://sf.net/projects/srecord"
6434 \begin_layout Subsection
6435 Projects with Multiple Source Files
6438 \begin_layout Standard
6439 SDCC can compile only ONE file at a time.
6440 Let us for example assume that you have a project containing the following
6445 foo1.c (contains some functions)
6447 foo2.c (contains some more functions)
6450 n.c (contains more functions and the function main)
6458 The first two files will need to be compiled separately with the commands:
6490 Then compile the source file containing the
6495 \begin_inset LatexCommand index
6500 the files together with the following command:
6508 foomain.c\InsetSpace ~
6509 foo1.rel\InsetSpace ~
6514 \begin_inset LatexCommand index
6527 can be separately compiled as well:
6538 sdcc foomain.rel foo1.rel foo2.rel
6545 The file containing the
6557 file specified in the command line, since the linkage editor processes
6558 file in the order they are presented to it.
6559 The linker is invoked from SDCC using a script file with extension .lnk
6560 \begin_inset LatexCommand index
6566 You can view this file to troubleshoot linking problems such as those arising
6567 from missing libraries.
6570 \begin_layout Subsection
6571 Projects with Additional Libraries
6572 \begin_inset LatexCommand index
6580 \begin_layout Standard
6581 Some reusable routines may be compiled into a library, see the documentation
6582 for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
6586 \begin_inset LatexCommand index
6594 Libraries created in this manner can be included in the command line.
6595 Make sure you include the -L <library-path> option to tell the linker where
6596 to look for these files if they are not in the current directory.
6597 Here is an example, assuming you have the source file
6609 (if that is not the same as your current project):
6616 sdcc foomain.c foolib.lib -L mylib
6627 must be an absolute path name.
6631 The most efficient way to use libraries is
6632 to keep separate modules in separate source files.
6633 The lib file now should name all the modules.rel
6634 \begin_inset LatexCommand index
6640 For an example see the standard library file
6644 in the directory <installdir>/share/lib/small.
6647 \begin_layout Subsection
6648 Using sdcclib to Create and Manage Libraries
6649 \begin_inset LatexCommand index
6657 \begin_layout Standard
6658 Alternatively, instead of having a .rel file for each entry on the library
6659 file as described in the preceding section, sdcclib can be used to embed
6660 all the modules belonging to such library in the library file itself.
6661 This results in a larger library file, but it greatly reduces the number
6662 of disk files accessed by the linker.
6663 Additionally, the packed library file contains an index of all include
6664 modules and symbols that significantly speeds up the linking process.
6665 To display a list of options supported by sdcclib type:
6670 \begin_layout Standard
6675 \begin_inset LatexCommand index
6687 To create a new library file, start by compiling all the required modules.
6693 \begin_layout Standard
6700 \begin_layout Standard
6707 \begin_layout Standard
6714 \begin_layout Standard
6721 \begin_layout Standard
6730 \begin_layout Standard
6731 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
6733 The next step is to add the .rel files to the library file:
6738 \begin_layout Standard
6742 sdcclib libint.lib _divsint.rel
6745 \begin_inset LatexCommand index
6753 \begin_layout Standard
6757 sdcclib libint.lib _divuint.rel
6760 \begin_layout Standard
6764 sdcclib libint.lib _modsint.rel
6767 \begin_layout Standard
6771 sdcclib libint.lib _moduint.rel
6774 \begin_layout Standard
6778 sdcclib libint.lib _mulint.rel
6786 \begin_layout Standard
6795 \begin_layout Standard
6799 sdcclib libint.lib _divsint.rel _divuint.rel _modsint.rel _moduint.rel _mulint.rel
6807 \begin_layout Standard
6808 If the file already exists in the library, it will be replaced.
6809 If a list of .rel files is available, you can tell sdcclib to add those
6811 For example, if the file 'myliblist.txt' contains
6819 \begin_layout Standard
6826 \begin_layout Standard
6833 \begin_layout Standard
6840 \begin_layout Standard
6847 \begin_layout Standard
6859 \begin_layout Standard
6868 \begin_layout Standard
6872 sdcclib -l libint.lib myliblist.txt
6880 \begin_layout Standard
6881 Additionally, you can instruct sdcclib to compiles the files before adding
6882 them to the library.
6883 This is achieved using the environment variables SDCCLIB_CC and/or SDCCLIB_AS.
6892 \begin_layout Standard
6896 set SDCCLIB_CC=sdcc -c
6899 \begin_layout Standard
6903 sdcclib -l libint.lib myliblist.txt
6911 \begin_layout Standard
6912 To see what modules and symbols are included in the library, options -s
6913 and -m are available.
6921 sdcclib -s libint.lib
6924 \begin_inset LatexCommand index
6937 \begin_layout Standard
6943 \begin_layout Standard
6949 \begin_layout Standard
6957 \begin_layout Standard
6963 \begin_layout Standard
6969 \begin_layout Standard
6975 \begin_layout Standard
6981 \begin_layout Standard
6989 \begin_layout Standard
6995 \begin_layout Standard
7001 \begin_layout Standard
7009 \begin_layout Standard
7015 \begin_layout Standard
7021 \begin_layout Standard
7027 \begin_layout Standard
7035 \begin_layout Standard
7041 \begin_layout Standard
7052 \begin_layout Standard
7053 If the source files are compiled using -
7057 \begin_layout Standard
7067 \begin_inset LatexCommand index
7072 , the corresponding debug information file .adb will be include in the library
7074 The library files created with sdcclib are plain text files, so they can
7075 be viewed with a text editor.
7076 It is not recommended to modify a library file created with sdcclib using
7077 a text editor, as there are file indexes numbers located across the file
7078 used by the linker to quickly locate the required module to link.
7079 Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
7080 it can be safely deleted, since all the information required for linking
7081 is embedded in the library file itself.
7082 Library files created using sdcclib are used as described in the preceding
7084 \begin_inset VSpace bigskip
7090 \begin_layout Section
7091 Command Line Options
7092 \begin_inset LatexCommand index
7093 name "Command Line Options"
7098 \begin_inset LatexCommand label
7099 name "sec:Command-Line-Options"
7106 \begin_layout Subsection
7107 Processor Selection Options
7108 \begin_inset LatexCommand index
7109 name "Options processor selection"
7114 \begin_inset LatexCommand index
7115 name "Processor selection options"
7123 \labelwidthstring 00.00.0000
7127 \begin_inset LatexCommand index
7134 Generate code for the Intel MCS51
7135 \begin_inset LatexCommand index
7140 family of processors.
7141 This is the default processor target.
7145 \labelwidthstring 00.00.0000
7149 \begin_inset LatexCommand index
7156 Generate code for the Dallas DS80C390
7157 \begin_inset LatexCommand index
7166 \labelwidthstring 00.00.0000
7170 \begin_inset LatexCommand index
7177 Generate code for the Dallas DS80C400
7178 \begin_inset LatexCommand index
7187 \labelwidthstring 00.00.0000
7191 \begin_inset LatexCommand index
7198 Generate code for the Freescale/Motorola HC08
7199 \begin_inset LatexCommand index
7204 family of processors.
7208 \labelwidthstring 00.00.0000
7212 \begin_inset LatexCommand index
7219 Generate code for the Zilog Z80
7220 \begin_inset LatexCommand index
7225 family of processors.
7229 \labelwidthstring 00.00.0000
7233 \begin_inset LatexCommand index
7240 Generate code for the GameBoy Z80
7241 \begin_inset LatexCommand index
7242 name "gbz80 (GameBoy Z80)"
7246 processor (Not actively maintained).
7250 \labelwidthstring 00.00.0000
7254 \begin_inset LatexCommand index
7261 Generate code for the Atmel AVR
7262 \begin_inset LatexCommand index
7267 processor (Not maintained, not complete).
7268 AVR users should probably have a look at winavr
7269 \begin_inset LatexCommand url
7270 target "http://sourceforge.net/projects/winavr"
7275 \begin_inset LatexCommand url
7276 target "http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index"
7280 , which is based on AVR-port of the gcc compiler.
7283 \begin_layout Standard
7284 \begin_inset Note Note
7287 \begin_layout Standard
7288 I think it is fair to direct users there for now.
7289 Open source is also about avoiding unnecessary work .
7290 But I didn't find the 'official' link.
7299 \labelwidthstring 00.00.0000
7303 \begin_inset LatexCommand index
7310 Generate code for the Microchip PIC 14
7311 \begin_inset LatexCommand index
7316 -bit processors (p16f84 and variants.
7317 In development, not complete).
7320 \begin_layout Standard
7321 \begin_inset Note Note
7324 \begin_layout Standard
7325 p16f627 p16f628 p16f84 p16f873 p16f877?
7334 \labelwidthstring 00.00.0000
7338 \begin_inset LatexCommand index
7345 Generate code for the Microchip PIC 16
7346 \begin_inset LatexCommand index
7351 -bit processors (p18f452 and variants.
7352 In development, not complete).
7356 \labelwidthstring 00.00.0000
7361 Generate code for the Toshiba TLCS-900H
7362 \begin_inset LatexCommand index
7367 processor (Not maintained, not complete).
7371 \labelwidthstring 00.00.0000
7375 \begin_inset LatexCommand index
7382 Generate code for the Phillips XA51
7383 \begin_inset LatexCommand index
7388 processor (Not maintained, not complete).
7391 \begin_layout Standard
7392 \begin_inset VSpace bigskip
7398 \begin_layout Subsection
7399 Preprocessor Options
7400 \begin_inset LatexCommand index
7401 name "Options preprocessor"
7406 \begin_inset LatexCommand index
7407 name "Preprocessor options"
7412 \begin_inset LatexCommand index
7413 name "sdcpp (preprocessor)"
7421 \labelwidthstring 00.00.0000
7425 \begin_inset LatexCommand index
7432 The additional location where the preprocessor will look for <..h> or
7433 \begin_inset Quotes eld
7437 \begin_inset Quotes erd
7444 \labelwidthstring 00.00.0000
7448 \begin_inset LatexCommand index
7449 name "-D<macro[=value]>"
7455 Command line definition of macros.
7456 Passed to the preprocessor.
7460 \labelwidthstring 00.00.0000
7464 \begin_inset LatexCommand index
7471 Tell the preprocessor to output a rule suitable for make describing the
7472 dependencies of each object file.
7473 For each source file, the preprocessor outputs one make-rule whose target
7474 is the object file name for that source file and whose dependencies are
7475 all the files `#include'd in it.
7476 This rule may be a single line or may be continued with `
7478 '-newline if it is long.
7479 The list of rules is printed on standard output instead of the preprocessed
7482 \begin_inset LatexCommand index
7491 \labelwidthstring 00.00.0000
7495 \begin_inset LatexCommand index
7502 Tell the preprocessor not to discard comments.
7503 Used with the `-E' option.
7507 \labelwidthstring 00.00.0000
7511 \begin_inset LatexCommand index
7521 Like `-M' but the output mentions only the user header files included with
7523 \begin_inset Quotes eld
7527 System header files included with `#include <file>' are omitted.
7531 \labelwidthstring 00.00.0000
7535 \begin_inset LatexCommand index
7536 name "-Aquestion(answer)"
7542 Assert the answer answer for question, in case it is tested with a preprocessor
7543 conditional such as `#if #question(answer)'.
7544 `-A-' disables the standard assertions that normally describe the target
7549 \labelwidthstring 00.00.0000
7553 \begin_inset LatexCommand index
7560 Undefine macro macro.
7561 `-U' options are evaluated after all `-D' options, but before any `-include'
7562 and `-imacros' options.
7566 \labelwidthstring 00.00.0000
7570 \begin_inset LatexCommand index
7577 Tell the preprocessor to output only a list of the macro definitions that
7578 are in effect at the end of preprocessing.
7579 Used with the `-E' option.
7583 \labelwidthstring 00.00.0000
7587 \begin_inset LatexCommand index
7594 Tell the preprocessor to pass all macro definitions into the output, in
7595 their proper sequence in the rest of the output.
7599 \labelwidthstring 00.00.0000
7603 \begin_inset LatexCommand index
7613 Like `-dD' except that the macro arguments and contents are omitted.
7614 Only `#define name' is included in the output.
7618 \labelwidthstring 00.00.0000
7621 -pedantic-parse-number
7622 \begin_inset LatexCommand index
7628 \begin_inset LatexCommand index
7629 name "-pedantic-parse-number"
7637 \begin_inset LatexCommand label
7638 name "lyx:-pedantic-parse-number"
7647 Pedantic parse numbers so that situations like 0xfe-LO_B(3) are parsed properly
7648 and the macro LO_B(3) gets expanded.
7649 See also #pragma pedantic_parse_number
7650 \begin_inset LatexCommand vpageref
7651 reference "ite:pedantic_parse_number"
7656 \begin_inset LatexCommand ref
7657 reference "sec:Pragmas"
7663 Note: this functionality is not in conformance with C99 standard!
7667 \labelwidthstring 00.00.0000
7671 preprocessorOption[,preprocessorOption]
7674 \begin_inset LatexCommand index
7675 name "-Wp preprocessorOption[,preprocessorOption]"
7680 Pass the preprocessorOption to the preprocessor
7685 \begin_inset LatexCommand index
7686 name "sdcpp (preprocessor)"
7691 SDCC uses an adapted version of the preprocessor
7695 of the GNU Compiler Collection
7696 \begin_inset LatexCommand index
7697 name "gcc (GNU Compiler Collection)"
7706 \begin_inset LatexCommand url
7707 target "http://gcc.gnu.org/"
7711 ), if you need more dedicated options please refer to the GCC\InsetSpace ~
7716 \begin_inset LatexCommand htmlurl
7717 target "http://www.gnu.org/software/gcc/onlinedocs/"
7724 \begin_layout Standard
7725 \begin_inset VSpace bigskip
7731 \begin_layout Subsection
7733 \begin_inset LatexCommand index
7734 name "Options linker"
7739 \begin_inset LatexCommand index
7740 name "Linker options"
7748 \labelwidthstring 00.00.0000
7758 \begin_layout Standard
7770 \begin_inset LatexCommand index
7771 name "-\\/-lib-path <path>"
7776 \begin_inset LatexCommand index
7777 name "-L -\\/-lib-path"
7784 <absolute path to additional libraries> This option is passed to the linkage
7785 editor's additional libraries
7786 \begin_inset LatexCommand index
7792 The path name must be absolute.
7793 Additional library files may be specified in the command line.
7794 See section Compiling programs for more details.
7798 \labelwidthstring 00.00.0000
7805 \begin_layout Standard
7817 \begin_inset LatexCommand index
7818 name "-\\/-xram-loc <Value>"
7823 <Value> The start location of the external ram
7824 \begin_inset LatexCommand index
7825 name "xdata (mcs51, ds390 storage class)"
7829 , default value is 0.
7830 The value entered can be in Hexadecimal or Decimal format, e.g.: -
7834 \begin_layout Standard
7843 -xram-loc 0x8000 or -
7847 \begin_layout Standard
7860 \labelwidthstring 00.00.0000
7867 \begin_layout Standard
7879 \begin_inset LatexCommand index
7880 name "-\\/-code-loc <Value>"
7885 <Value> The start location of the code
7886 \begin_inset LatexCommand index
7891 segment, default value 0.
7892 Note when this option is used the interrupt vector table
7893 \begin_inset LatexCommand index
7894 name "interrupt vector table"
7898 is also relocated to the given address.
7899 The value entered can be in Hexadecimal or Decimal format, e.g.: -
7903 \begin_layout Standard
7912 -code-loc 0x8000 or -
7916 \begin_layout Standard
7929 \labelwidthstring 00.00.0000
7936 \begin_layout Standard
7948 \begin_inset LatexCommand index
7949 name "-\\/-stack-loc <Value>"
7954 <Value> By default the stack
7955 \begin_inset LatexCommand index
7960 is placed after the data segment.
7961 Using this option the stack can be placed anywhere in the internal memory
7963 The value entered can be in Hexadecimal or Decimal format, e.g.
7968 \begin_layout Standard
7977 -stack-loc 0x20 or -
7981 \begin_layout Standard
7991 Since the sp register is incremented before a push or call, the initial
7992 sp will be set to one byte prior the provided value.
7993 The provided value should not overlap any other memory areas such as used
7994 register banks or the data segment and with enough space for the current
8002 \begin_layout Standard
8015 \begin_inset LatexCommand index
8016 name "-\\/-pack-iram"
8020 option (which is now a default setting) will override this setting, so
8021 you should also specify the
8027 \begin_layout Standard
8040 \begin_inset LatexCommand index
8041 name "-\\/-no-pack-iram"
8045 option if you need to manually place the stack.
8049 \labelwidthstring 00.00.0000
8056 \begin_layout Standard
8068 \begin_inset LatexCommand index
8069 name "-\\/-xstack-loc <Value>"
8074 <Value> By default the external stack
8075 \begin_inset LatexCommand index
8080 is placed after the pdata
8081 \begin_inset LatexCommand index
8082 name "pdata (mcs51, ds390 storage class)"
8087 Using this option the xstack can be placed anywhere in the external memory
8089 The value entered can be in Hexadecimal or Decimal format, e.g.
8094 \begin_layout Standard
8103 -xstack-loc 0x8000 or -
8107 \begin_layout Standard
8117 The provided value should not overlap any other memory areas such as the
8118 pdata or xdata segment and with enough space for the current application.
8122 \labelwidthstring 00.00.0000
8129 \begin_layout Standard
8141 \begin_inset LatexCommand index
8142 name "-\\/-data-loc <Value>"
8147 <Value> The start location of the internal ram data
8148 \begin_inset LatexCommand index
8149 name "data (mcs51, ds390 storage class)"
8154 The value entered can be in Hexadecimal or Decimal format, eg.
8159 \begin_layout Standard
8172 \begin_layout Standard
8182 (By default, the start location of the internal ram data segment is set
8183 as low as possible in memory, taking into account the used register banks
8184 and the bit segment at address 0x20.
8185 For example if register banks 0 and 1 are used without bit variables, the
8186 data segment will be set, if -
8190 \begin_layout Standard
8199 -data-loc is not used, to location 0x10.)
8203 \labelwidthstring 00.00.0000
8210 \begin_layout Standard
8222 \begin_inset LatexCommand index
8223 name "-\\/-idata-loc <Value>"
8228 <Value> The start location of the indirectly addressable internal ram
8229 \begin_inset LatexCommand index
8230 name "idata (mcs51, ds390 storage class)"
8234 of the 8051, default value is 0x80.
8235 The value entered can be in Hexadecimal or Decimal format, eg.
8240 \begin_layout Standard
8249 -idata-loc 0x88 or -
8253 \begin_layout Standard
8266 \labelwidthstring 00.00.0000
8273 \begin_layout Standard
8285 <Value> The start location of the bit
8286 \begin_inset LatexCommand index
8291 addressable internal ram of the 8051.
8297 Instead an option can be passed directly to the linker: -Wl\InsetSpace ~
8302 \labelwidthstring 00.00.0000
8309 \begin_layout Standard
8319 \begin_inset LatexCommand index
8320 name "-\\/-out-fmt-ihx"
8326 The linker output (final object code) is in Intel Hex format.
8327 \begin_inset LatexCommand index
8328 name "Intel hex format"
8332 This is the default option.
8333 The format itself is documented in the documentation of srecord
8334 \begin_inset LatexCommand index
8335 name "srecord (bin, hex, ... tool)"
8343 \labelwidthstring 00.00.0000
8350 \begin_layout Standard
8360 \begin_inset LatexCommand index
8361 name "-\\/-out-fmt-s19"
8367 The linker output (final object code) is in Motorola S19 format
8368 \begin_inset LatexCommand index
8369 name "Motorola S19 format"
8374 The format itself is documented in the documentation of srecord.
8378 \labelwidthstring 00.00.0000
8385 \begin_layout Standard
8395 \begin_inset LatexCommand index
8396 name "-\\/-out-fmt-s19"
8401 \begin_inset LatexCommand index
8402 name "HC08!Options!-\\/-out-fmt-elf"
8408 The linker output (final object code) is in ELF format
8409 \begin_inset LatexCommand index
8415 (Currently only supported for the HC08
8416 \begin_inset LatexCommand index
8425 \labelwidthstring 00.00.0000
8429 linkOption[,linkOption]
8432 \begin_inset LatexCommand index
8433 name "-Wl linkOption[,linkOption]"
8438 \begin_inset LatexCommand label
8439 name "lyx:-Wl option"
8444 Pass the linkOption to the linker.
8445 If a bootloader is used an option like
8446 \begin_inset Quotes sld
8451 \begin_inset Quotes srd
8454 would be typical to set the start of the code segment.
8455 Either use the double quotes around this option or use no space (e.g.
8457 See also #pragma constseg and #pragma codeseg in section
8458 \begin_inset LatexCommand ref
8459 reference "sec:Pragmas"
8464 File sdcc/as/doc/asxhtm.html has more on linker options.
8467 \begin_layout Standard
8468 \begin_inset VSpace bigskip
8474 \begin_layout Subsection
8476 \begin_inset LatexCommand index
8477 name "Options MCS51"
8482 \begin_inset LatexCommand index
8483 name "MCS51 options"
8491 \labelwidthstring 00.00.0000
8498 \begin_layout Standard
8508 \begin_inset LatexCommand index
8509 name "-\\/-model-small"
8518 Generate code for Small Model programs, see section Memory Models for more
8520 This is the default model.
8524 \labelwidthstring 00.00.0000
8531 \begin_layout Standard
8541 \begin_inset LatexCommand index
8542 name "-\\/-model-medium"
8548 Generate code for Medium model programs, see section Memory Models for
8550 If this option is used all source files in the project have to be compiled
8552 It must also be used when invoking the linker.
8556 \labelwidthstring 00.00.0000
8563 \begin_layout Standard
8573 \begin_inset LatexCommand index
8574 name "-\\/-model-large"
8580 Generate code for Large model programs, see section Memory Models for more
8582 If this option is used all source files in the project have to be compiled
8584 It must also be used when invoking the linker.
8588 \labelwidthstring 00.00.0000
8595 \begin_layout Standard
8605 \begin_inset LatexCommand index
8612 Uses a pseudo stack in the pdata
8613 \begin_inset LatexCommand index
8614 name "pdata (mcs51, ds390 storage class)"
8618 area (usually the first 256 bytes in the external ram) for allocating variables
8619 and passing parameters.
8621 \begin_inset LatexCommand ref
8622 reference "sub:External-Stack"
8627 External Stack for more details.
8631 \labelwidthstring 00.00.0000
8638 \begin_layout Standard
8651 \begin_inset LatexCommand index
8652 name "-\\/-iram-size <Value>"
8656 Causes the linker to check if the internal ram usage is within limits of
8661 \labelwidthstring 00.00.0000
8668 \begin_layout Standard
8681 \begin_inset LatexCommand index
8682 name "-\\/-xram-size <Value>"
8686 Causes the linker to check if the external ram usage is within limits of
8691 \labelwidthstring 00.00.0000
8698 \begin_layout Standard
8711 \begin_inset LatexCommand index
8712 name "-\\/-code-size <Value>"
8716 Causes the linker to check if the code memory usage is within limits of
8721 \labelwidthstring 00.00.0000
8728 \begin_layout Standard
8741 \begin_inset LatexCommand index
8742 name "-\\/-stack-size <Value>"
8746 Causes the linker to check if there is at minimum <Value> bytes for stack.
8750 \labelwidthstring 00.00.0000
8757 \begin_layout Standard
8770 \begin_inset LatexCommand index
8771 name "-\\/-pack-iram"
8775 Causes the linker to use unused register banks for data variables and pack
8776 data, idata and stack together.
8777 This is the default now.
8781 \labelwidthstring 00.00.0000
8788 \begin_layout Standard
8801 \begin_inset LatexCommand index
8802 name "-\\/-no-pack-iram"
8806 Causes the linker to use old style for allocating memory areas.
8810 \labelwidthstring 00.00.0000
8817 \begin_layout Standard
8830 \begin_inset LatexCommand index
8831 name "-\\/-acall-ajmp"
8835 Replaces the three byte instructions lcall/ljmp with the two byte instructions
8837 Only use this option if your code is in the same 2k block of memory.
8838 You may need to use this option for some 8051 derivatives which lack the
8839 lcall/ljmp instructions..
8842 \begin_layout Standard
8843 \begin_inset VSpace bigskip
8849 \begin_layout Subsection
8850 DS390 / DS400 Options
8851 \begin_inset LatexCommand index
8852 name "Options DS390"
8857 \begin_inset LatexCommand index
8866 \labelwidthstring 00.00.0000
8873 \begin_layout Standard
8885 \begin_inset LatexCommand index
8886 name "DS390!Options!-\\/-model-flat24"
8894 Generate 24-bit flat mode code.
8895 This is the one and only that the ds390 code generator supports right now
8896 and is default when using
8901 See section Memory Models for more details.
8905 \labelwidthstring 00.00.0000
8912 \begin_layout Standard
8922 \begin_inset LatexCommand index
8923 name "DS390!Options!-\\/-protect-sp-update"
8929 disable interrupts during ESP:SP updates.
8933 \labelwidthstring 00.00.0000
8940 \begin_layout Standard
8952 \begin_inset LatexCommand index
8953 name "DS390!Options!-\\/-stack-10bit"
8957 Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
8958 This is the one and only that the ds390 code generator supports right now
8959 and is default when using
8964 In this mode, the stack is located in the lower 1K of the internal RAM,
8965 which is mapped to 0x400000.
8966 Note that the support is incomplete, since it still uses a single byte
8967 as the stack pointer.
8968 This means that only the lower 256 bytes of the potential 1K stack space
8969 will actually be used.
8970 However, this does allow you to reclaim the precious 256 bytes of low RAM
8971 for use for the DATA and IDATA segments.
8972 The compiler will not generate any code to put the processor into 10 bit
8974 It is important to ensure that the processor is in this mode before calling
8975 any re-entrant functions compiled with this option.
8976 In principle, this should work with the
8982 \begin_layout Standard
8992 \begin_inset LatexCommand index
8993 name "-\\/-stack-auto"
8999 option, but that has not been tested.
9000 It is incompatible with the
9006 \begin_layout Standard
9016 \begin_inset LatexCommand index
9024 It also only makes sense if the processor is in 24 bit contiguous addressing
9031 \begin_layout Standard
9040 -model-flat24 option
9045 \begin_inset Note Note
9049 \labelwidthstring 00.00.0000
9056 \begin_layout Standard
9065 -stack-8-bit - switches off the 10-bit mode
9074 \labelwidthstring 00.00.0000
9081 \begin_layout Standard
9091 \begin_inset LatexCommand index
9092 name "DS390!Options!-\\/-stack-probe"
9098 insert call to function __stack_probe at each function prologue.
9102 \labelwidthstring 00.00.0000
9109 \begin_layout Standard
9119 \begin_inset LatexCommand index
9120 name "DS390!Options!-\\/-tini-libid"
9126 <nnnn> LibraryID used in -mTININative.
9131 \labelwidthstring 00.00.0000
9138 \begin_layout Standard
9148 \begin_inset LatexCommand index
9149 name "DS390!Options!-\\/-use-accelerator"
9155 generate code for DS390 Arithmetic Accelerator.
9159 \begin_layout Standard
9160 \begin_inset VSpace bigskip
9166 \begin_layout Subsection
9168 \begin_inset LatexCommand index
9174 \begin_inset LatexCommand index
9183 \labelwidthstring 00.00.0000
9190 \begin_layout Standard
9202 \begin_inset LatexCommand index
9203 name "Z80!Options!-\\/-callee-saves-bc"
9211 Force a called function to always save BC.
9215 \labelwidthstring 00.00.0000
9222 \begin_layout Standard
9234 \begin_inset LatexCommand index
9235 name "Z80!Options!-\\/-no-std-crt0"
9239 When linking, skip the standard crt0.o object file.
9240 You must provide your own crt0.o for your system when linking.
9244 \labelwidthstring 00.00.0000
9251 \begin_layout Standard
9263 \begin_inset LatexCommand index
9264 name "Z80!Options!-\\/-portmode=<Value>"
9268 Determinate PORT I/O mode (<Value> is z80 or z180).
9272 \labelwidthstring 00.00.0000
9279 \begin_layout Standard
9291 \begin_inset LatexCommand index
9292 name "Z80!Options!-\\/-asm=<Value>"
9296 Define assembler name (<Value> is rgbds, asxxxx, isas or z80asm).
9300 \labelwidthstring 00.00.0000
9307 \begin_layout Standard
9320 \begin_inset LatexCommand index
9321 name "Z80!Options!-\\/-codeseg <Value>"
9325 Use <Value> for the code segment name.
9329 \labelwidthstring 00.00.0000
9336 \begin_layout Standard
9349 \begin_inset LatexCommand index
9350 name "Z80!Options!-\\/-constseg <Value>"
9354 Use <Value> for the const segment name.
9358 \labelwidthstring 00.00.0000
9359 \begin_inset VSpace bigskip
9365 \begin_layout Subsection
9367 \begin_inset LatexCommand index
9368 name "Options GBZ80"
9373 \begin_inset LatexCommand index
9382 \labelwidthstring 00.00.0000
9389 \begin_layout Standard
9401 \begin_inset LatexCommand index
9402 name "GBZ80!Options!-\\/-callee-saves-bc"
9410 Force a called function to always save BC.
9414 \labelwidthstring 00.00.0000
9421 \begin_layout Standard
9433 \begin_inset LatexCommand index
9434 name "Z80!Options!-\\/-no-std-crt0"
9438 When linking, skip the standard crt0.o object file.
9439 You must provide your own crt0.o for your system when linking.
9443 \labelwidthstring 00.00.0000
9450 \begin_inset LatexCommand index
9451 name "GBZ80!Options!-bo <Num>"
9455 Use code bank <Num>.
9459 \labelwidthstring 00.00.0000
9466 \begin_inset LatexCommand index
9467 name "GBZ80!Options!-ba <Num>"
9471 Use data bank <Num>.
9475 \labelwidthstring 00.00.0000
9482 \begin_layout Standard
9495 \begin_inset LatexCommand index
9496 name "GBZ80!Options!-\\/-codeseg <Value>"
9500 Use <Value> for the code segment name.
9504 \labelwidthstring 00.00.0000
9511 \begin_layout Standard
9524 \begin_inset LatexCommand index
9525 name "GBZ80!Options!-\\/-constseg <Value>"
9529 Use <Value> for the const segment name.
9532 \begin_layout Standard
9533 \begin_inset VSpace bigskip
9539 \begin_layout Subsection
9540 Optimization Options
9541 \begin_inset LatexCommand index
9542 name "Options optimization"
9547 \begin_inset LatexCommand index
9548 name "Optimization options"
9556 \labelwidthstring 00.00.0000
9563 \begin_layout Standard
9573 \begin_inset LatexCommand index
9580 Will not do global subexpression elimination, this option may be used when
9581 the compiler creates undesirably large stack/data spaces to store compiler
9591 \begin_inset LatexCommand index
9592 name "sloc (spill location)"
9597 A warning message will be generated when this happens and the compiler
9598 will indicate the number of extra bytes it allocated.
9599 It is recommended that this option NOT be used, #pragma\InsetSpace ~
9601 \begin_inset LatexCommand index
9602 name "\\#pragma nogcse"
9606 can be used to turn off global subexpression elimination
9607 \begin_inset LatexCommand index
9608 name "Subexpression elimination"
9612 for a given function only.
9616 \labelwidthstring 00.00.0000
9623 \begin_layout Standard
9633 \begin_inset LatexCommand index
9634 name "-\\/-noinvariant"
9640 Will not do loop invariant optimizations, this may be turned off for reasons
9641 explained for the previous option.
9642 For more details of loop optimizations performed see Loop Invariants in
9644 \begin_inset LatexCommand ref
9645 reference "sub:Loop-Optimizations"
9650 It is recommended that this option NOT be used, #pragma\InsetSpace ~
9652 \begin_inset LatexCommand index
9653 name "\\#pragma noinvariant"
9657 can be used to turn off invariant optimizations for a given function only.
9661 \labelwidthstring 00.00.0000
9668 \begin_layout Standard
9678 \begin_inset LatexCommand index
9679 name "-\\/-noinduction"
9685 Will not do loop induction optimizations, see section strength reduction
9687 It is recommended that this option is NOT used, #pragma\InsetSpace ~
9689 \begin_inset LatexCommand index
9690 name "\\#pragma noinduction"
9694 can be used to turn off induction optimizations for a given function only.
9698 \labelwidthstring 00.00.0000
9705 \begin_layout Standard
9715 \begin_inset LatexCommand index
9716 name "-\\/-nojtbound"
9725 Will not generate boundary condition check when switch statements
9726 \begin_inset LatexCommand index
9727 name "switch statement"
9731 are implemented using jump-tables.
9733 \begin_inset LatexCommand ref
9734 reference "sub:'switch'-Statements"
9739 Switch Statements for more details.
9740 It is recommended that this option is NOT used, #pragma\InsetSpace ~
9742 \begin_inset LatexCommand index
9743 name "\\#pragma nojtbound"
9747 can be used to turn off boundary checking for jump tables for a given function
9752 \labelwidthstring 00.00.0000
9759 \begin_layout Standard
9769 \begin_inset LatexCommand index
9770 name "-\\/-noloopreverse"
9779 Will not do loop reversal
9780 \begin_inset LatexCommand index
9781 name "Loop reversing"
9789 \labelwidthstring 00.00.0000
9794 \begin_layout Standard
9808 \begin_inset LatexCommand index
9809 name "-\\/-nolabelopt "
9813 Will not optimize labels (makes the dumpfiles more readable).
9817 \labelwidthstring 00.00.0000
9824 \begin_layout Standard
9834 \begin_inset LatexCommand index
9835 name "-\\/-no-xinit-opt"
9841 Will not memcpy initialized data from code space into xdata space.
9842 This saves a few bytes in code space if you don't have initialized data
9843 \begin_inset LatexCommand index
9844 name "Variable initialization"
9852 \labelwidthstring 00.00.0000
9859 \begin_layout Standard
9869 \begin_inset LatexCommand index
9870 name "-\\/-nooverlay"
9876 The compiler will not overlay parameters and local variables of any function,
9877 see section Parameters and local variables for more details.
9881 \labelwidthstring 00.00.0000
9888 \begin_layout Standard
9898 \begin_inset LatexCommand index
9905 Disable peep-hole optimization with built-in rules.
9909 \labelwidthstring 00.00.0000
9916 \begin_layout Standard
9928 \begin_inset LatexCommand index
9929 name "-\\/-peep-file"
9934 <filename> This option can be used to use additional rules to be used by
9935 the peep hole optimizer.
9937 \begin_inset LatexCommand ref
9938 reference "sub:Peephole-Optimizer"
9943 Peep Hole optimizations for details on how to write these rules.
9947 \labelwidthstring 00.00.0000
9954 \begin_layout Standard
9964 \begin_inset LatexCommand index
9965 name "-\\/-peep-asm"
9971 Pass the inline assembler code through the peep hole optimizer.
9972 This can cause unexpected changes to inline assembler code, please go through
9973 the peephole optimizer
9974 \begin_inset LatexCommand index
9975 name "Peephole optimizer"
9979 rules defined in the source file tree '<target>/peeph.def' before using
9984 \labelwidthstring 00.00.0000
9991 \begin_layout Standard
10001 \begin_inset LatexCommand index
10002 name "-\\/-opt-code-speed"
10008 The compiler will optimize code generation towards fast code, possibly
10009 at the expense of code size.
10013 \labelwidthstring 00.00.0000
10020 \begin_layout Standard
10030 \begin_inset LatexCommand index
10031 name "-\\/-opt-code-size"
10037 The compiler will optimize code generation towards compact code, possibly
10038 at the expense of code speed.
10041 \begin_layout Standard
10042 \begin_inset VSpace bigskip
10048 \begin_layout Subsection
10050 \begin_inset LatexCommand index
10051 name "Options other"
10059 \labelwidthstring 00.00.0000
10067 \begin_layout Standard
10077 \begin_inset LatexCommand index
10078 name "-\\/-compile-only"
10083 \begin_inset LatexCommand index
10084 name "-c -\\/-compile-only"
10090 will compile and assemble the source, but will not call the linkage editor.
10094 \labelwidthstring 00.00.0000
10103 \begin_layout Standard
10115 \begin_inset LatexCommand index
10122 reads the preprocessed source from standard input and compiles it.
10123 The file name for the assembler output must be specified using the -o option.
10127 \labelwidthstring 00.00.0000
10131 \begin_inset LatexCommand index
10138 Run only the C preprocessor.
10139 Preprocess all the C source files specified and output the results to standard
10144 \labelwidthstring 00.00.0000
10149 \begin_inset LatexCommand index
10150 name "-o <path/file>"
10156 The output path where everything will be placed or the file name used for
10157 all generated output files.
10158 If the parameter is a path, it must have a trailing slash (or backslash
10159 for the Windows binaries) to be recognized as a path.
10160 Note for Windows users: if the path contains spaces, it should be surrounded
10162 The trailing backslash should be doubled in order to prevent escaping the
10163 final quote, for example:
10166 \begin_inset Quotes sld
10180 \begin_inset Quotes srd
10185 or put after the final quote, for example:
10188 \begin_inset Quotes sld
10198 \begin_inset Quotes srd
10206 The path using slashes for directory delimiters can be used too, for example:
10210 \begin_inset Quotes sld
10213 F:/Projects/test3/output 1/
10214 \begin_inset Quotes srd
10223 \labelwidthstring 00.00.0000
10230 \begin_layout Standard
10240 \begin_inset LatexCommand index
10241 name "-\\/-stack-auto"
10250 All functions in the source file will be compiled as
10255 \begin_inset LatexCommand index
10261 the parameters and local variables will be allocated on the stack
10262 \begin_inset LatexCommand index
10269 \begin_inset LatexCommand ref
10270 reference "sec:Parameters-and-Local-Variables"
10274 Parameters and Local Variables for more details.
10275 If this option is used all source files in the project should be compiled
10277 It automatically implies -
10283 \begin_layout Standard
10294 -int-long-reent and -
10300 \begin_layout Standard
10316 \labelwidthstring 00.00.0000
10323 \begin_layout Standard
10333 \begin_inset LatexCommand index
10334 name "-\\/-callee-saves"
10339 \begin_inset LatexCommand label
10340 name "lyx:--callee-saves-function1[,function2][,function3]..."
10344 function1[,function2][,function3]....
10347 The compiler by default uses a caller saves convention for register saving
10348 across function calls, however this can cause unnecessary register pushing
10349 and popping when calling small functions from larger functions.
10350 This option can be used to switch the register saving convention for the
10351 function names specified.
10352 The compiler will not save registers when calling these functions, no extra
10353 code will be generated at the entry and exit (function prologue
10356 \begin_inset LatexCommand index
10357 name "function prologue"
10366 \begin_inset LatexCommand index
10367 name "function epilogue"
10373 ) for these functions to save and restore the registers used by these functions,
10374 this can SUBSTANTIALLY reduce code and improve run time performance of
10375 the generated code.
10376 In the future the compiler (with inter procedural analysis) will be able
10377 to determine the appropriate scheme to use for each function call.
10378 DO NOT use this option for built-in functions such as _mulint..., if this
10379 option is used for a library function the appropriate library function
10380 needs to be recompiled with the same option.
10381 If the project consists of multiple source files then all the source file
10382 should be compiled with the same -
10386 \begin_layout Standard
10395 -callee-saves option string.
10396 Also see #pragma\InsetSpace ~
10398 \begin_inset LatexCommand index
10399 name "\\#pragma callee\\_saves"
10404 \begin_inset LatexCommand vpageref
10405 reference "ite:callee_saves-function1[,function2[,function3...]]--"
10413 \labelwidthstring 00.00.0000
10420 \begin_layout Standard
10430 \begin_inset LatexCommand index
10431 name "-\\/-all-callee-saves"
10441 \begin_layout Standard
10450 -callee-saves will be applied to all functions by default.
10454 \labelwidthstring 00.00.0000
10461 \begin_layout Standard
10471 \begin_inset LatexCommand index
10478 When this option is used the compiler will generate debug information.
10479 The debug information collected in a file with .cdb extension can be used
10481 For more information see documentation for SDCDB.
10482 Another file with no extension contains debug information in AOMF or AOMF51
10483 \begin_inset LatexCommand index
10484 name "AOMF, AOMF51"
10488 format which is commonly used by third party tools.
10492 \labelwidthstring 00.00.0000
10496 \begin_inset LatexCommand index
10506 Stop after the stage of compilation proper; do not assemble.
10507 The output is an assembler code file for the input file specified.
10511 \labelwidthstring 00.00.0000
10518 \begin_layout Standard
10528 \begin_inset LatexCommand index
10529 name "-\\/-int-long-reent"
10535 Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
10536 Note by default these libraries are compiled as non-reentrant.
10537 See section Installation for more details.
10541 \labelwidthstring 00.00.0000
10548 \begin_layout Standard
10558 \begin_inset LatexCommand index
10559 name "-\\/-cyclomatic"
10565 This option will cause the compiler to generate an information message for
10566 each function in the source file.
10567 The message contains some
10571 information about the function.
10572 The number of edges and nodes the compiler detected in the control flow
10573 graph of the function, and most importantly the
10575 cyclomatic complexity
10576 \begin_inset LatexCommand index
10577 name "Cyclomatic complexity"
10583 see section on Cyclomatic Complexity for more details.
10587 \labelwidthstring 00.00.0000
10594 \begin_layout Standard
10604 \begin_inset LatexCommand index
10605 name "-\\/-float-reent"
10611 Floating point library is compiled as reentrant
10612 \begin_inset LatexCommand index
10618 See section Installation for more details.
10622 \labelwidthstring 00.00.0000
10629 \begin_layout Standard
10639 \begin_inset LatexCommand index
10640 name "-\\/-funsigned-char"
10646 The default signedness for every type is
10651 In some embedded environments the default signedness of
10660 To set the signess for characters to unsigned, use the option -
10666 \begin_layout Standard
10678 If this option is set and no signedness keyword (unsigned/signed) is given,
10679 a char will be signed.
10680 All other types are unaffected.
10684 \labelwidthstring 00.00.0000
10691 \begin_layout Standard
10701 \begin_inset LatexCommand index
10702 name "-\\/-main-return"
10708 This option can be used if the code generated is called by a monitor program
10709 or if the main routine includes an endless loop.
10710 This option results in slightly smaller code and saves two bytes of stack
10712 The return from the 'main'
10713 \begin_inset LatexCommand index
10718 function will return to the function calling main.
10719 The default setting is to lock up i.e.
10728 \labelwidthstring 00.00.0000
10735 \begin_layout Standard
10745 \begin_inset LatexCommand index
10746 name "-\\/-nostdinc"
10752 This will prevent the compiler from passing on the default include path
10753 to the preprocessor.
10757 \labelwidthstring 00.00.0000
10764 \begin_layout Standard
10774 \begin_inset LatexCommand index
10775 name "-\\/-nostdlib"
10781 This will prevent the compiler from passing on the default library
10782 \begin_inset LatexCommand index
10787 path to the linker.
10791 \labelwidthstring 00.00.0000
10798 \begin_layout Standard
10808 \begin_inset LatexCommand index
10809 name "-\\/-verbose"
10815 Shows the various actions the compiler is performing.
10819 \labelwidthstring 00.00.0000
10823 \begin_inset LatexCommand index
10830 Shows the actual commands the compiler is executing.
10834 \labelwidthstring 00.00.0000
10841 \begin_layout Standard
10851 \begin_inset LatexCommand index
10852 name "-\\/-no-c-code-in-asm"
10858 Hides your ugly and inefficient c-code from the asm file, so you can always
10859 blame the compiler :)
10863 \labelwidthstring 00.00.0000
10870 \begin_layout Standard
10880 \begin_inset LatexCommand index
10881 name "-\\/-no-gen-comments"
10887 Include code generator and peep-hole comments in the generated asm files.
10891 \labelwidthstring 00.00.0000
10898 \begin_layout Standard
10908 \begin_inset LatexCommand index
10909 name "-\\/-no-peep-comments"
10915 Don't include peep-hole comments in the generated asm files even if -
10921 \begin_layout Standard
10932 -fverbose-asm option is specified.
10936 \labelwidthstring 00.00.0000
10943 \begin_layout Standard
10953 \begin_inset LatexCommand index
10954 name "-\\/-i-code-in-asm"
10960 Include i-codes in the asm file.
10961 Sounds like noise but is most helpful for debugging the compiler itself.
10965 \labelwidthstring 00.00.0000
10972 \begin_layout Standard
10982 \begin_inset LatexCommand index
10988 \begin_inset LatexCommand index
10989 name "-\\/-less-pedantic"
10996 \begin_inset LatexCommand label
10997 name "lyx:--less-pedantic"
11001 Disable some of the more pedantic warnings
11002 \begin_inset LatexCommand index
11008 For more details, see the less_pedantic pragma
11009 \begin_inset LatexCommand vpageref
11010 reference "ite:less_pedantic"
11018 \labelwidthstring 00.00.0000
11025 \begin_layout Standard
11034 -disable-warning\InsetSpace ~
11036 \begin_inset LatexCommand index
11037 name "-\\/-disable-warning"
11043 Disable specific warning with number <nnnn>.
11047 \labelwidthstring 00.00.0000
11054 \begin_layout Standard
11064 \begin_inset LatexCommand index
11071 Treat all warnings as errors.
11075 \labelwidthstring 00.00.0000
11082 \begin_layout Standard
11092 \begin_inset LatexCommand index
11093 name "-\\/-print-search-dirs"
11099 Display the directories in the compiler's search path
11103 \labelwidthstring 00.00.0000
11110 \begin_layout Standard
11120 \begin_inset LatexCommand index
11127 Display errors and warnings using MSVC style, so you can use SDCC with
11128 the visual studio IDE
11129 \begin_inset LatexCommand index
11135 With SDCC both offering a GCC-like (the default) and a MSVC-like
11136 \begin_inset LatexCommand index
11137 name "MSVC output style"
11141 output style, integration into most programming editors should be straightforwa
11146 \labelwidthstring 00.00.0000
11153 \begin_layout Standard
11163 \begin_inset LatexCommand index
11164 name "-\\/-use-stdout"
11170 Send errors and warnings to stdout instead of stderr.
11174 \labelwidthstring 00.00.0000
11178 asmOption[,asmOption]
11181 \begin_inset LatexCommand index
11182 name "-Wa asmOption[,asmOption]"
11187 Pass the asmOption to the assembler
11188 \begin_inset LatexCommand index
11189 name "Options assembler"
11194 \begin_inset LatexCommand index
11195 name "Assembler options"
11200 See file sdcc/as/doc/asxhtm.html for assembler options.cd
11204 \labelwidthstring 00.00.0000
11211 \begin_layout Standard
11221 \begin_inset LatexCommand index
11222 name "-\\/-std-sdcc89"
11228 Generally follow the C89 standard, but allow SDCC features that conflict
11229 with the standard (default).
11233 \labelwidthstring 00.00.0000
11240 \begin_layout Standard
11250 \begin_inset LatexCommand index
11251 name "-\\/-std-c89"
11257 Follow the C89 standard and disable SDCC features that conflict with the
11262 \labelwidthstring 00.00.0000
11269 \begin_layout Standard
11279 \begin_inset LatexCommand index
11280 name "-\\/-std-sdcc99"
11286 Generally follow the C99 standard, but allow SDCC features that conflict
11287 with the standard (incomplete support).
11291 \labelwidthstring 00.00.0000
11298 \begin_layout Standard
11308 \begin_inset LatexCommand index
11309 name "-\\/-std-sdcc99"
11315 Follow the C99 standard and disable SDCC features that conflict with the
11316 standard (incomplete support).
11320 \labelwidthstring 00.00.0000
11327 \begin_layout Standard
11339 \begin_inset LatexCommand index
11340 name "-\\/-codeseg <Value>"
11345 \begin_inset LatexCommand label
11346 name "lyx:-codeseg"
11351 <Name> The name to be used for the code
11352 \begin_inset LatexCommand index
11357 segment, default CSEG.
11358 This is useful if you need to tell the compiler to put the code in a special
11359 segment so you can later on tell the linker to put this segment in a special
11361 Can be used for instance when using bank switching to put the code in a
11366 \labelwidthstring 00.00.0000
11373 \begin_layout Standard
11385 \begin_inset LatexCommand index
11386 name "-\\/-constseg <Value>"
11391 <Name> The name to be used for the const
11392 \begin_inset LatexCommand index
11397 segment, default CONST.
11398 This is useful if you need to tell the compiler to put the const data in
11399 a special segment so you can later on tell the linker to put this segment
11400 in a special place in memory.
11401 Can be used for instance when using bank switching to put the const data
11406 \labelwidthstring 00.00.0000
11413 \begin_layout Standard
11422 -fdollars-in-identifiers
11423 \begin_inset LatexCommand index
11424 name "-\\/-fdollars-in-identifiers"
11430 Permit '$' as an identifier character.
11434 \labelwidthstring 00.00.0000
11441 \begin_layout Standard
11453 \begin_inset LatexCommand index
11454 name "-\\/-more-pedantic"
11459 \begin_inset LatexCommand index
11470 a SDCC compiler option but if you want
11474 warnings you can use a separate tool dedicated to syntax checking like
11476 \begin_inset LatexCommand label
11477 name "lyx:more-pedantic-SPLINT"
11482 \begin_inset LatexCommand index
11483 name "lint (syntax checking tool)"
11488 \begin_inset LatexCommand url
11489 target "http://www.splint.org"
11494 To make your source files parseable by splint you will have to include
11500 \begin_inset LatexCommand index
11501 name "splint (syntax checking tool)"
11505 in your source file and add brackets around extended keywords (like
11508 \begin_inset Quotes sld
11521 \begin_inset Quotes srd
11529 \begin_inset Quotes sld
11532 __interrupt\InsetSpace ~
11534 \begin_inset Quotes srd
11542 Splint has an excellent on line manual at
11543 \begin_inset LatexCommand url
11544 target "http://www.splint.org/manual/"
11548 and it's capabilities go beyond pure syntax checking.
11549 You'll need to tell splint the location of SDCC's include files so a typical
11550 command line could look like this:
11554 splint\InsetSpace ~
11556 /usr/local/share/sdcc/include/mcs51/\InsetSpace ~
11562 \labelwidthstring 00.00.0000
11569 \begin_layout Standard
11581 \begin_inset LatexCommand index
11582 name "-\\/-short-is-8bits"
11587 \begin_inset LatexCommand label
11588 name "lyx:--short-is-8bits"
11592 Treat short as 8-bit (for backward compatibility with older versions of
11593 compiler - see section
11594 \begin_inset LatexCommand ref
11595 reference "sec:Compatibility-with-previous"
11602 \begin_layout Standard
11603 \begin_inset VSpace bigskip
11609 \begin_layout Subsection
11610 Intermediate Dump Options
11611 \begin_inset LatexCommand label
11612 name "sub:Intermediate-Dump-Options"
11617 \begin_inset LatexCommand index
11618 name "Options intermediate dump"
11623 \begin_inset LatexCommand index
11624 name "Intermediate dump options"
11631 \begin_layout Standard
11632 The following options are provided for the purpose of retargetting and debugging
11634 They provide a means to dump the intermediate code (iCode
11635 \begin_inset LatexCommand index
11640 ) generated by the compiler in human readable form at various stages of
11641 the compilation process.
11642 More on iCodes see chapter
11643 \begin_inset LatexCommand ref
11644 reference "sub:The-anatomy-of"
11649 \begin_inset Quotes srd
11652 The anatomy of the compiler
11653 \begin_inset Quotes srd
11660 \labelwidthstring 00.00.0000
11667 \begin_layout Standard
11677 \begin_inset LatexCommand index
11678 name "-\\/-dumpraw"
11684 This option will cause the compiler to dump the intermediate code into
11687 <source filename>.dumpraw
11689 just after the intermediate code has been generated for a function, i.e.
11690 before any optimizations are done.
11692 \begin_inset LatexCommand index
11693 name "Basic blocks"
11697 at this stage ordered in the depth first number, so they may not be in
11698 sequence of execution.
11702 \labelwidthstring 00.00.0000
11709 \begin_layout Standard
11719 \begin_inset LatexCommand index
11720 name "-\\/-dumpgcse"
11726 Will create a dump of iCodes, after global subexpression elimination
11727 \begin_inset LatexCommand index
11728 name "Global subexpression elimination"
11732 , into a file named
11734 <source filename>.dumpgcse.
11738 \labelwidthstring 00.00.0000
11745 \begin_layout Standard
11755 \begin_inset LatexCommand index
11756 name "-\\/-dumpdeadcode"
11762 Will create a dump of iCodes, after deadcode elimination
11763 \begin_inset LatexCommand index
11764 name "Dead-code elimination"
11768 , into a file named
11770 <source filename>.dumpdeadcode.
11774 \labelwidthstring 00.00.0000
11781 \begin_layout Standard
11791 \begin_inset LatexCommand index
11792 name "-\\/-dumploop"
11801 Will create a dump of iCodes, after loop optimizations
11802 \begin_inset LatexCommand index
11803 name "Loop optimization"
11807 , into a file named
11809 <source filename>.dumploop.
11813 \labelwidthstring 00.00.0000
11820 \begin_layout Standard
11830 \begin_inset LatexCommand index
11831 name "-\\/-dumprange"
11840 Will create a dump of iCodes, after live range analysis
11841 \begin_inset LatexCommand index
11842 name "Live range analysis"
11846 , into a file named
11848 <source filename>.dumprange.
11852 \labelwidthstring 00.00.0000
11859 \begin_layout Standard
11869 \begin_inset LatexCommand index
11870 name "-\\/-dumlrange"
11876 Will dump the life ranges
11877 \begin_inset LatexCommand index
11878 name "Live range analysis"
11886 \labelwidthstring 00.00.0000
11893 \begin_layout Standard
11903 \begin_inset LatexCommand index
11904 name "-\\/-dumpregassign"
11910 Will create a dump of iCodes, after register assignment
11911 \begin_inset LatexCommand index
11912 name "Register assignment"
11916 , into a file named
11918 <source filename>.dumprassgn.
11922 \labelwidthstring 00.00.0000
11929 \begin_layout Standard
11939 \begin_inset LatexCommand index
11940 name "-\\/-dumplrange"
11946 Will create a dump of the live ranges of iTemp's
11950 \labelwidthstring 00.00.0000
11957 \begin_layout Standard
11967 \begin_inset LatexCommand index
11968 name "-\\/-dumpall"
11977 Will cause all the above mentioned dumps to be created.
11980 \begin_layout Standard
11981 \begin_inset VSpace bigskip
11987 \begin_layout Subsection
11988 Redirecting output on Windows Shells
11991 \begin_layout Standard
11992 By default SDCC writes its error messages to
11993 \begin_inset Quotes sld
11997 \begin_inset Quotes srd
12001 To force all messages to
12002 \begin_inset Quotes sld
12006 \begin_inset Quotes srd
12018 \begin_layout Standard
12033 \begin_inset LatexCommand index
12034 name "-\\/-use-stdout"
12039 Additionally, if you happen to have visual studio installed in your windows
12040 machine, you can use it to compile your sources using a custom build and
12047 \begin_layout Standard
12059 \begin_inset LatexCommand index
12065 Something like this should work:
12084 \begin_layout Standard
12103 \begin_layout Standard
12115 -model-large -c $(InputPath)
12118 \begin_inset VSpace bigskip
12124 \begin_layout Section
12125 Environment variables
12126 \begin_inset LatexCommand index
12127 name "Environment variables"
12134 \begin_layout Standard
12135 SDCC recognizes the following environment variables:
12139 \labelwidthstring 00.00.0000
12143 \begin_inset LatexCommand index
12144 name "SDCC\\_LEAVE\\_SIGNALS"
12150 SDCC installs a signal handler
12151 \begin_inset LatexCommand index
12152 name "signal handler"
12156 to be able to delete temporary files after an user break (^C) or an exception.
12157 If this environment variable is set, SDCC won't install the signal handler
12158 in order to be able to debug SDCC.
12162 \labelwidthstring 00.00.0000
12168 \begin_inset LatexCommand index
12169 name "TMP, TEMP, TMPDIR"
12175 Path, where temporary files will be created.
12176 The order of the variables is the search order.
12177 In a standard *nix environment these variables are not set, and there's
12178 no need to set them.
12179 On Windows it's recommended to set one of them.
12183 \labelwidthstring 00.00.0000
12187 \begin_inset LatexCommand index
12195 \begin_inset LatexCommand ref
12196 reference "sub:Install-paths"
12202 \begin_inset Quotes sld
12206 \begin_inset Quotes srd
12213 \labelwidthstring 00.00.0000
12217 \begin_inset LatexCommand index
12218 name "SDCC\\_INCLUDE"
12225 \begin_inset LatexCommand ref
12226 reference "sub:Search-Paths"
12232 \begin_inset Quotes sld
12236 \begin_inset Quotes srd
12243 \labelwidthstring 00.00.0000
12247 \begin_inset LatexCommand index
12255 \begin_inset LatexCommand ref
12256 reference "sub:Search-Paths"
12262 \begin_inset Quotes sld
12266 \begin_inset Quotes srd
12272 \begin_layout Standard
12273 There are some more environment variables recognized by SDCC, but these
12274 are solely used for debugging purposes.
12275 They can change or disappear very quickly, and will never be documented.
12276 \begin_inset VSpace bigskip
12282 \begin_layout Section
12283 Storage Class Language Extensions
12286 \begin_layout Subsection
12287 MCS51/DS390 Storage Class
12288 \begin_inset LatexCommand index
12289 name "Storage class"
12293 Language Extensions
12296 \begin_layout Standard
12297 In addition to the ANSI storage classes SDCC allows the following MCS51
12298 specific storage classes:
12301 \begin_layout Subsubsection
12303 \begin_inset LatexCommand index
12304 name "data (mcs51, ds390 storage class)"
12309 \begin_inset LatexCommand index
12310 name "\\_\\_data (mcs51, ds390 storage class)"
12315 \begin_inset LatexCommand index
12316 name "near (storage class)"
12321 \begin_inset LatexCommand index
12322 name "\\_\\_near (storage class)"
12329 \begin_layout Standard
12334 storage class for the Small Memory model (
12342 or the more ANSI-C compliant forms
12350 can be used synonymously).
12351 Variables declared with this storage class will be allocated in the directly
12352 addressable portion of the internal RAM of a 8051, e.g.:
12355 \begin_layout Verse
12358 __data unsigned char test_data;
12361 \begin_layout Standard
12362 Writing 0x01 to this variable generates the assembly code:
12365 \begin_layout Verse
12368 75*00 01\InsetSpace ~
12376 \begin_layout Subsubsection
12378 \begin_inset LatexCommand index
12379 name "xdata (mcs51, ds390 storage class)"
12384 \begin_inset LatexCommand index
12385 name "\\_\\_xdata (mcs51, ds390 storage class)"
12390 \begin_inset LatexCommand index
12391 name "far (storage class)"
12396 \begin_inset LatexCommand index
12397 name "\\_\\_far (storage class)"
12404 \begin_layout Standard
12405 Variables declared with this storage class will be placed in the external
12411 storage class for the Large Memory model, e.g.:
12414 \begin_layout Verse
12417 __xdata unsigned char test_xdata;
12420 \begin_layout Standard
12421 Writing 0x01 to this variable generates the assembly code:
12424 \begin_layout Verse
12427 90s00r00\InsetSpace ~
12458 \begin_layout Subsubsection
12460 \begin_inset LatexCommand index
12461 name "idata (mcs51, ds390 storage class)"
12466 \begin_inset LatexCommand index
12467 name "\\_\\_idata (mcs51, ds390 storage class)"
12474 \begin_layout Standard
12475 Variables declared with this storage class will be allocated into the indirectly
12476 addressable portion of the internal ram of a 8051, e.g.:
12479 \begin_layout Verse
12482 __idata unsigned char test_idata;
12485 \begin_layout Standard
12486 Writing 0x01 to this variable generates the assembly code:
12489 \begin_layout Verse
12516 \begin_layout Standard
12517 Please note, the first 128 byte of idata physically access the same RAM
12518 as the data memory.
12519 The original 8051 had 128 byte idata memory, nowadays most devices have
12520 256 byte idata memory.
12522 \begin_inset LatexCommand index
12527 is located in idata memory.
12530 \begin_layout Subsubsection
12532 \begin_inset LatexCommand index
12533 name "pdata (mcs51, ds390 storage class)"
12538 \begin_inset LatexCommand index
12539 name "\\_\\_pdata (mcs51, ds390 storage class)"
12546 \begin_layout Standard
12547 Paged xdata access is just as straightforward as using the other addressing
12549 It is typically located at the start of xdata and has a maximum size of
12551 The following example writes 0x01 to the pdata variable.
12552 Please note, pdata access physically accesses xdata memory.
12553 The high byte of the address is determined by port P2
12554 \begin_inset LatexCommand index
12555 name "P2 (mcs51 sfr)"
12559 (or in case of some 8051 variants by a separate Special Function Register,
12561 \begin_inset LatexCommand ref
12562 reference "sub:MCS51-variants"
12571 storage class for the Medium Memory model, e.g.:
12574 \begin_layout Verse
12577 __pdata unsigned char test_pdata;
12580 \begin_layout Standard
12581 Writing 0x01 to this variable generates the assembly code:
12584 \begin_layout Verse
12593 mov r0,#_test_pdata
12615 \begin_layout Standard
12620 \begin_layout Standard
12630 \begin_inset LatexCommand index
12635 option is used the pdata memory area is followed by the xstack memory area
12636 and the sum of their sizes is limited to 256 bytes.
12639 \begin_layout Subsubsection
12641 \begin_inset LatexCommand index
12647 \begin_inset LatexCommand index
12655 \begin_layout Standard
12656 'Variables' declared with this storage class will be placed in the code
12660 \begin_layout Verse
12663 __code unsigned char test_code;
12666 \begin_layout Standard
12667 Read access to this variable generates the assembly code:
12670 \begin_layout Verse
12673 90s00r6F\InsetSpace ~
12676 mov dptr,#_test_code
12701 \begin_layout Standard
12706 indexed arrays of characters in code memory can be accessed efficiently:
12709 \begin_layout Verse
12712 __code char test_array[] = {'c','h','e','a','p'};
12715 \begin_layout Standard
12716 Read access to this array using an 8-bit unsigned index generates the assembly
12720 \begin_layout Verse
12732 \begin_layout Verse
12735 90s00r41\InsetSpace ~
12738 mov dptr,#_test_array
12741 \begin_layout Verse
12756 \begin_layout Subsubsection
12758 \begin_inset LatexCommand index
12764 \begin_inset LatexCommand index
12772 \begin_layout Standard
12773 This is a data-type and a storage class specifier.
12774 When a variable is declared as a bit, it is allocated into the bit addressable
12775 memory of 8051, e.g.:
12778 \begin_layout Verse
12784 \begin_layout Standard
12785 Writing 1 to this variable generates the assembly code:
12788 \begin_layout Verse
12802 \begin_layout Standard
12803 The bit addressable memory consists of 128 bits which are located from 0x20
12804 to 0x2f in data memory.
12807 Apart from this 8051 specific storage class most architectures support
12809 \begin_inset LatexCommand index
12818 \begin_layout Standard
12819 Not really meant as examples, but nevertheless showing what bitfields are
12820 about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
12826 In accordance with ISO/IEC 9899 bits and bitfields without an explicit
12827 signed modifier are implemented as unsigned.
12830 \begin_layout Subsubsection
12832 \begin_inset LatexCommand index
12838 \begin_inset LatexCommand index
12844 \begin_inset LatexCommand index
12850 \begin_inset LatexCommand index
12856 \begin_inset LatexCommand index
12862 \begin_inset LatexCommand index
12868 \begin_inset LatexCommand index
12874 \begin_inset LatexCommand index
12882 \begin_layout Standard
12883 Like the bit keyword,
12885 sfr / sfr16 / sfr32 / sbit
12887 signify both a data-type and storage class, they are used to describe the
12908 variables of a 8051, eg:
12911 \begin_layout Verse
12915 \begin_inset LatexCommand index
12921 \begin_inset LatexCommand index
12926 (0x80) P0;\InsetSpace ~
12927 /* special function register P0 at location 0x80 */
12932 special function register combination for timer 0
12936 with the high byte at
12937 location 0x8C and the low byte at location 0x8A */
12939 __sfr16 __at (0x8C8A)
12945 \begin_inset LatexCommand index
12951 \begin_inset LatexCommand index
12956 (0xd7) CY;\InsetSpace ~
12958 \begin_inset LatexCommand index
12964 \begin_inset LatexCommand index
12972 \begin_layout Standard
12973 Special function registers which are located on an address dividable by
12974 8 are bit-addressable, an
12978 addresses a specific bit within these sfr.
12980 16 Bit and 32 bit special function
12981 register combinations which require a certain access order are better not
12991 Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
12992 this is not guaranteed.
12997 \begin_layout Standard
12998 Please note, if you use a header file which was written for another compiler
12999 then the sfr / sfr16 / sfr32 / sbit Storage Class extensions will most
13005 Specifically the syntax
13008 sfr P0 = 0x80;\InsetSpace ~
13015 by SDCC to an assignment of 0x80 to a variable called P0
13018 \begin_inset Marginal
13021 \begin_layout Standard
13035 Nevertheless it is possible to write header files
13036 \begin_inset LatexCommand index
13037 name "Header files"
13042 \begin_inset LatexCommand index
13043 name "Include files"
13047 which can be shared among different compilers (see section
13048 \begin_inset LatexCommand ref
13049 reference "sec:Porting-code-to-other-compilers"
13057 \begin_layout Subsubsection
13059 \begin_inset LatexCommand index
13064 to MCS51/DS390 specific memory spaces
13067 \begin_layout Standard
13068 SDCC allows (via language extensions) pointers to explicitly point to any
13069 of the memory spaces
13070 \begin_inset LatexCommand index
13071 name "Memory model"
13076 In addition to the explicit pointers, the compiler uses (by default) generic
13077 pointers which can be used to point to any of the memory spaces.
13082 declaration examples:
13085 \begin_layout Verse
13088 /* pointer physically in internal ram pointing to object in external ram
13091 __xdata unsigned char * __data p;
13095 /* pointer physically in external ram
13096 pointing to object in internal ram */
13098 __data unsigned char * __xdata p;
13103 pointer physically in code rom pointing to data in xdata space */
13106 unsigned char * __code p;
13110 /* pointer physically in code space pointing to
13111 data in code space */
13113 __code unsigned char * __code p;
13118 physically located in xdata space */
13120 unsigned char * __xdata p;
13125 pointer physically located in default memory space */
13132 the following is a function pointer
13133 \begin_inset LatexCommand index
13134 name "function pointer"
13138 physically located in data space */
13140 char (* __data fp)(void);
13143 \begin_layout Standard
13144 Well you get the idea.
13149 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
13162 The highest order byte of the
13166 pointers contains the data space information.
13167 Assembler support routines are called whenever data is stored or retrieved
13173 These are useful for developing reusable library
13174 \begin_inset LatexCommand index
13180 Explicitly specifying the pointer
13181 \begin_inset LatexCommand index
13186 type will generate the most efficient code.
13189 \begin_layout Subsubsection
13190 Notes on MCS51 memory
13191 \begin_inset LatexCommand index
13192 name "MCS51 memory"
13199 \begin_layout Standard
13200 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
13201 RAM memory which is structured as follows:
13205 - Bytes 00-1F - 32 bytes to hold
13206 up to 4 banks of the registers R0 to R7,
13208 - Bytes 20-2F - 16 bytes to hold
13210 \begin_inset LatexCommand index
13217 - Bytes 30-7F - 80 bytes for general purpose use.
13222 \begin_layout Standard
13223 Additionally some members of the MCS51 family may have up to 128 bytes of
13224 additional, indirectly addressable, internal RAM memory (
13229 \begin_inset LatexCommand index
13230 name "idata (mcs51, ds390 storage class)"
13235 \begin_inset LatexCommand index
13236 name "\\_\\_idata (mcs51, ds390 storage class)"
13241 Furthermore, some chips may have some built in external memory (
13246 \begin_inset LatexCommand index
13247 name "xdata (mcs51, ds390 storage class)"
13252 \begin_inset LatexCommand index
13253 name "\\_\\_xdata (mcs51, ds390 storage class)"
13257 ) which should not be confused with the internal, directly addressable RAM
13263 \begin_inset LatexCommand index
13264 name "data (mcs51, ds390 storage class)"
13269 \begin_inset LatexCommand index
13270 name "\\_\\_data (mcs51, ds390 storage class)"
13275 Sometimes this built in
13279 memory has to be activated before using it (you can probably find this
13280 information on the datasheet of the microcontroller your are using, see
13282 \begin_inset LatexCommand ref
13283 reference "sub:Startup-Code"
13291 \begin_layout Standard
13292 Normally SDCC will only use the first bank
13293 \begin_inset LatexCommand index
13294 name "register bank (mcs51, ds390)"
13298 of registers (register bank 0), but it is possible to specify that other
13299 banks of registers (keyword
13306 \begin_inset LatexCommand index
13307 name "using (mcs51, ds390 register bank)"
13312 \begin_inset LatexCommand index
13313 name "\\_\\_using (mcs51, ds390 register bank)"
13319 ) should be used for example in interrupt
13320 \begin_inset LatexCommand index
13326 \begin_inset LatexCommand index
13327 name "\\_\\_interrupt"
13332 By default, the compiler will place the stack after the last byte of allocated
13333 memory for variables.
13334 For example, if the first 2 banks of registers are used, and only four
13339 variables, it will position the base of the internal stack at address 20
13341 This implies that as the stack
13342 \begin_inset LatexCommand index
13347 grows, it will use up the remaining register banks, and the 16 bytes used
13348 by the 128 bit variables, and 80 bytes for general purpose use.
13349 If any bit variables are used, the data variables will be placed in unused
13350 register banks and after the byte holding the last bit variable.
13351 For example, if register banks 0 and 1 are used, and there are 9 bit variables
13356 variables will be placed starting from address 0x10 to 0x20 and continue
13362 \begin_layout Standard
13372 \begin_inset LatexCommand index
13373 name "-\\/-data-loc <Value>"
13377 to specify the start address of the
13385 \begin_layout Standard
13395 \begin_inset LatexCommand index
13396 name "-\\/-iram-size <Value>"
13400 to specify the size of the total internal RAM (
13414 \begin_layout Standard
13415 By default the 8051 linker will place the stack after the last byte of (i)data
13421 \begin_layout Standard
13431 \begin_inset LatexCommand index
13432 name "-\\/-stack-loc <Value>"
13436 allows you to specify the start of the stack, i.e.
13437 you could start it after any data in the general purpose area.
13438 If your microcontroller has additional indirectly addressable internal
13443 ) you can place the stack on it.
13444 You may also need to use -
13448 \begin_layout Standard
13458 \begin_inset LatexCommand index
13459 name "-\\/-xdata-loc<Value>"
13463 to set the start address of the external RAM (
13471 \begin_layout Standard
13481 \begin_inset LatexCommand index
13482 name "-\\/-xram-size <Value>"
13486 to specify its size.
13487 Same goes for the code memory, using -
13491 \begin_layout Standard
13501 \begin_inset LatexCommand index
13502 name "-\\/-code-loc <Value>"
13510 \begin_layout Standard
13520 \begin_inset LatexCommand index
13521 name "-\\/-code-size <Value>"
13526 If in doubt, don't specify any options and see if the resulting memory
13527 layout is appropriate, then you can adjust it.
13530 \begin_layout Standard
13531 The linker generates two files with memory allocation information.
13532 The first, with extension .map
13533 \begin_inset LatexCommand index
13538 shows all the variables and segments.
13539 The second with extension .mem
13540 \begin_inset LatexCommand index
13545 shows the final memory layout.
13546 The linker will complain either if memory segments overlap, there is not
13547 enough memory, or there is not enough space for stack.
13548 If you get any linking warnings and/or errors related to stack or segments
13549 allocation, take a look at either the .map or .mem files to find out what
13551 The .mem file may even suggest a solution to the problem.
13552 \begin_inset VSpace bigskip
13558 \begin_layout Subsection
13559 Z80/Z180 Storage Class
13560 \begin_inset LatexCommand index
13561 name "Z80!Storage class"
13565 Language Extensions
13568 \begin_layout Subsubsection
13570 \begin_inset LatexCommand index
13576 \begin_inset LatexCommand index
13581 (in/out to 8-bit addresses)
13584 \begin_layout Standard
13586 \begin_inset LatexCommand index
13591 family has separate address spaces for memory and
13601 \begin_inset LatexCommand index
13602 name "I/O memory (Z80, Z180)"
13607 \begin_inset LatexCommand index
13608 name "Z80!I/O memory"
13613 \begin_inset LatexCommand index
13614 name "Z180!I/O memory"
13618 is accessed with special instructions, e.g.:
13621 \begin_layout Verse
13624 sfr at 0x78 IoPort;\InsetSpace ~
13626 /* define a var in I/O space at 78h called IoPort */
13630 \begin_layout Standard
13631 Writing 0x01 to this variable generates the assembly code:
13634 \begin_layout Verse
13654 \begin_layout Subsubsection
13656 \begin_inset LatexCommand index
13662 \begin_inset LatexCommand index
13667 (in/out to 16-bit addresses)
13670 \begin_layout Standard
13675 is used to support 16 bit addresses in I/O memory e.g.:
13678 \begin_layout Verse
13682 \begin_inset LatexCommand index
13688 \begin_inset LatexCommand index
13696 \begin_layout Standard
13697 Writing 0x01 to this variable generates the assembly code:
13700 \begin_layout Verse
13703 01 23 01\InsetSpace ~
13725 \begin_layout Subsubsection
13727 \begin_inset LatexCommand index
13733 \begin_inset LatexCommand index
13738 (in0/out0 to 8 bit addresses on Z180
13739 \begin_inset LatexCommand index
13745 \begin_inset LatexCommand index
13746 name "HD64180 (see Z180)"
13753 \begin_layout Standard
13754 The compiler option -
13758 \begin_layout Standard
13768 \begin_inset LatexCommand index
13769 name "Z180!Options!-\\/-portmode"
13773 =180 (80) and a compiler #pragma\InsetSpace ~
13775 \begin_inset LatexCommand index
13776 name "Z180!Pragmas!\\#pragma portmode"
13780 z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
13790 If you include the file z180.h this will be set automatically.
13791 \begin_inset VSpace bigskip
13797 \begin_layout Subsection
13799 \begin_inset LatexCommand index
13800 name "HC08!Storage class"
13804 Language Extensions
13807 \begin_layout Subsubsection
13809 \begin_inset LatexCommand index
13810 name "data (hc08 storage class)"
13815 \begin_inset LatexCommand index
13816 name "\\_\\_data (hc08 storage class)"
13823 \begin_layout Standard
13824 The data storage class declares a variable that resides in the first 256
13825 bytes of memory (the direct page).
13827 \begin_inset LatexCommand index
13832 is most efficient at accessing variables (especially pointers) stored here.
13835 \begin_layout Subsubsection
13837 \begin_inset LatexCommand index
13838 name "xdata (hc08 storage class)"
13843 \begin_inset LatexCommand index
13844 name "\\_\\_xdata (hc08 storage class)"
13851 \begin_layout Standard
13852 The xdata storage class declares a variable that can reside anywhere in
13854 This is the default if no storage class is specified.
13856 \begin_inset VSpace bigskip
13862 \begin_layout Section
13863 Other SDCC language extensions
13864 \begin_inset LatexCommand index
13865 name "Other SDCC language extensions"
13872 \begin_layout Subsection
13876 \begin_layout Standard
13877 SDCC supports the use of binary constants, such as 0b01100010.
13878 This feature is only enabled when the compiler is invoked using --std-sdccxx.
13881 \begin_layout Standard
13882 \begin_inset VSpace bigskip
13888 \begin_layout Section
13889 Absolute Addressing
13890 \begin_inset LatexCommand index
13891 name "Absolute addressing"
13898 \begin_layout Standard
13899 Data items can be assigned an absolute address with the
13902 \begin_inset LatexCommand index
13908 \begin_inset LatexCommand index
13915 keyword, in addition to a storage class, e.g.:
13918 \begin_layout Verse
13922 \begin_inset LatexCommand index
13923 name "xdata (mcs51, ds390 storage class)"
13928 \begin_inset LatexCommand index
13929 name "\\_\\_xdata (mcs51, ds390 storage class)"
13934 \begin_inset LatexCommand index
13940 \begin_inset LatexCommand index
13945 0x7ffe unsigned int chksum;
13948 \begin_layout Standard
13949 or, better conforming to ISO/IEC 9899 C:
13952 \begin_layout Verse
13955 __xdata __at (0x7ffe) unsigned int chksum;
13958 \begin_layout Standard
13959 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
13960 of the external ram.
13965 reserve any space for variables declared in this way
13966 \begin_inset Marginal
13969 \begin_layout Standard
13978 (they are implemented with an equate in the assembler).
13979 Thus it is left to the programmer to make sure there are no overlaps with
13980 other variables that are declared without the absolute address.
13981 The assembler listing file (.lst
13982 \begin_inset LatexCommand index
13987 ) and the linker output files (.rst
13988 \begin_inset LatexCommand index
13994 \begin_inset LatexCommand index
13999 ) are good places to look for such overlaps.
14002 \begin_layout Standard
14003 If however you provide an initializer
14004 \begin_inset LatexCommand index
14005 name "Variable initialization"
14009 actual memory allocation will take place and overlaps will be detected
14014 \begin_layout Verse
14017 __code __at (0x7ff0) char Id[5] =
14018 \begin_inset Quotes sld
14022 \begin_inset Quotes srd
14028 \begin_layout Standard
14029 In the above example the variable Id will be located from 0x7ff0 to 0x7ff4
14033 \begin_layout Standard
14034 In case of memory mapped I/O devices the keyword
14038 has to be used to tell the compiler that accesses might not be removed:
14041 \begin_layout Verse
14045 \begin_inset LatexCommand index
14051 \begin_inset LatexCommand index
14052 name "xdata (mcs51, ds390 storage class)"
14057 \begin_inset LatexCommand index
14062 (0x8000) unsigned char PORTA_8255;
14065 \begin_layout Standard
14066 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
14071 \begin_inset LatexCommand index
14072 name "Aligned array"
14079 starts at a block (256 byte) boundary
14080 \begin_inset LatexCommand index
14081 name "block boundary"
14086 \begin_inset LatexCommand ref
14087 reference "sub:A-Step-by Assembler Introduction"
14093 Absolute addresses can be specified for variables in all
14094 storage classes, e.g.:
14097 \begin_layout Verse
14101 \begin_inset LatexCommand index
14107 \begin_inset LatexCommand index
14115 \begin_layout Standard
14116 The above example will allocate the variable at offset 0x02 in the bit-addressab
14118 There is no real advantage to assigning absolute addresses to variables
14119 in this manner, unless you want strict control over all the variables allocated.
14120 One possible use would be to write hardware portable code.
14121 For example, if you have a routine that uses one or more of the microcontroller
14122 I/O pins, and such pins are different for two different hardwares, you
14123 can declare the I/O pins in your routine using:
14126 \begin_layout Verse
14130 \begin_inset LatexCommand index
14135 __bit MOSI;\InsetSpace ~
14139 /* master out, slave in */
14141 extern volatile __bit MISO;\InsetSpace ~
14148 extern volatile __bit MCLK;\InsetSpace ~
14157 Output of a byte on a 3-wire serial bus.
14162 If needed adapt polarity of clock,
14163 polarity of data and bit order
14168 unsigned char spi_io(unsigned char out_byte)
14193 MOSI = out_byte & 0x80;
14224 /* _asm nop _endasm; */\InsetSpace ~
14232 /* for slow peripherals */
14284 \begin_layout Standard
14285 Then, someplace in the code for the first hardware you would use
14288 \begin_layout Verse
14292 \begin_inset LatexCommand index
14298 \begin_inset LatexCommand index
14303 (0x80) MOSI;\InsetSpace ~
14307 /* I/O port 0, bit 0 */
14309 __bit __at (0x81) MISO;\InsetSpace ~
14316 __bit __at (0x82) MCLK;\InsetSpace ~
14320 /* I/O port 0, bit 2 */
14323 \begin_layout Standard
14324 Similarly, for the second hardware you would use
14327 \begin_layout Verse
14330 __bit __at (0x83) MOSI;\InsetSpace ~
14334 /* I/O port 0, bit 3 */
14336 __bit __at (0x91) MISO;\InsetSpace ~
14341 I/O port 1, bit 1 */
14344 \begin_inset LatexCommand index
14349 __at (0x92) MCLK;\InsetSpace ~
14353 /* I/O port 1, bit 2 */
14356 \begin_layout Standard
14357 and you can use the same hardware dependent routine without changes, as
14358 for example in a library.
14359 This is somehow similar to sbit, but only one absolute address has to be
14360 specified in the whole project.
14361 \begin_inset VSpace bigskip
14367 \begin_layout Section
14369 \begin_inset LatexCommand index
14375 \begin_inset LatexCommand index
14376 name "function parameter"
14381 \begin_inset LatexCommand index
14382 name "local variables"
14387 \begin_inset LatexCommand label
14388 name "sec:Parameters-and-Local-Variables"
14395 \begin_layout Standard
14396 Automatic (local) variables and parameters to functions can either be placed
14397 on the stack or in data-space.
14398 The default action of the compiler is to place these variables in the internal
14399 RAM (for small model) or external RAM (for medium or large model).
14400 This in fact makes them similar to
14403 \begin_inset LatexCommand index
14410 so by default functions are non-reentrant
14411 \begin_inset LatexCommand index
14421 They can be placed on the stack
14422 \begin_inset LatexCommand index
14433 \begin_layout Standard
14443 \begin_inset LatexCommand index
14444 name "-\\/-stack-auto"
14452 #pragma\InsetSpace ~
14456 \begin_inset LatexCommand index
14457 name "\\#pragma stackauto"
14464 \begin_inset LatexCommand index
14471 keyword in the function declaration, e.g.:
14474 \begin_layout Verse
14477 unsigned char foo(char i) __reentrant
14491 \begin_layout Standard
14492 Since stack space on 8051 is limited, the
14502 \begin_layout Standard
14513 option should be used sparingly.
14514 Note that the reentrant keyword just means that the parameters & local
14515 variables will be allocated to the stack, it
14519 mean that the function is register bank
14520 \begin_inset LatexCommand index
14521 name "register bank (mcs51, ds390)"
14530 \begin_inset LatexCommand index
14531 name "local variables"
14535 can be assigned storage classes and absolute
14536 \begin_inset LatexCommand index
14537 name "Absolute addressing"
14544 \begin_layout Verse
14547 unsigned char foo()
14555 __xdata unsigned char i;
14568 \begin_inset LatexCommand index
14573 (0x31) unsigned char j;
14585 \begin_layout Standard
14586 In the above example the variable
14590 will be allocated in the external ram,
14594 in bit addressable space and
14605 \begin_layout Standard
14616 or when a function is declared as
14620 this should only be done for static variables.
14623 \begin_layout Standard
14625 \begin_inset LatexCommand index
14626 name "function parameter"
14630 however are not allowed any storage class
14631 \begin_inset LatexCommand index
14632 name "Storage class"
14636 , (storage classes for parameters will be ignored), their allocation is
14637 governed by the memory model in use, and the reentrancy options.
14640 \begin_layout Standard
14641 It is however allowed to use bit parameters in reentrant functions and also
14642 non-static local bit variables are supported.
14643 Efficient use is limited to 8 semi-bitregisters in bit space.
14644 They are pushed and popped to stack
14645 \begin_inset LatexCommand index
14650 as a single byte just like the normal registers.
14653 \begin_layout Section
14655 \begin_inset LatexCommand label
14656 name "sub:Overlaying"
14661 \begin_inset LatexCommand index
14669 \begin_layout Standard
14671 \begin_inset LatexCommand index
14676 functions SDCC will try to reduce internal ram space usage by overlaying
14677 parameters and local variables of a function (if possible).
14678 Parameters and local variables
14679 \begin_inset LatexCommand index
14680 name "local variables"
14684 of a function will be allocated to an overlayable segment if the function
14687 no other function calls and the function is non-reentrant and the memory
14689 \begin_inset LatexCommand index
14690 name "Memory model"
14697 If an explicit storage class
14698 \begin_inset LatexCommand index
14699 name "Storage class"
14703 is specified for a local variable, it will NOT be overlaid.
14706 \begin_layout Standard
14707 Note that the compiler (not the linkage editor) makes the decision for overlayin
14709 Functions that are called from an interrupt service routine
14710 \begin_inset Marginal
14713 \begin_layout Standard
14721 should be preceded by a #pragma\InsetSpace ~
14723 \begin_inset LatexCommand index
14724 name "\\#pragma nooverlay"
14728 if they are not reentrant.
14731 \begin_layout Standard
14732 Also note that the compiler does not do any processing of inline assembler
14733 code, so the compiler might incorrectly assign local variables and parameters
14734 of a function into the overlay segment if the inline assembler code calls
14735 other c-functions that might use the overlay.
14736 In that case the #pragma\InsetSpace ~
14737 nooverlay should be used.
14740 \begin_layout Standard
14741 Parameters and local variables of functions that contain 16 or 32 bit multiplica
14743 \begin_inset LatexCommand index
14744 name "Multiplication"
14749 \begin_inset LatexCommand index
14754 will NOT be overlaid since these are implemented using external functions,
14758 \begin_layout Verse
14764 \begin_inset LatexCommand index
14765 name "\\#pragma nooverlay"
14771 void set_error(unsigned char errcd)
14788 some_isr () __interrupt
14789 \begin_inset LatexCommand index
14820 \begin_layout Standard
14821 In the above example the parameter
14829 would be assigned to the overlayable segment if the #pragma\InsetSpace ~
14831 not present, this could cause unpredictable runtime behavior when called
14832 from an interrupt service routine.
14833 The #pragma\InsetSpace ~
14834 nooverlay ensures that the parameters and local variables for
14835 the function are NOT overlaid.
14836 \begin_inset VSpace bigskip
14842 \begin_layout Section
14843 Interrupt Service Routines
14844 \begin_inset LatexCommand label
14845 name "sub:Interrupt-Service-Routines"
14852 \begin_layout Subsection
14853 General Information
14856 \begin_layout Standard
14869 outines to be coded in C, with some extended keywords.
14872 \begin_layout Verse
14875 void timer_isr (void) __interrupt (1) __using (1)
14889 \begin_layout Standard
14890 The optional number following the
14893 \begin_inset LatexCommand index
14899 \begin_inset LatexCommand index
14900 name "\\_\\_interrupt"
14906 keyword is the interrupt number this routine will service.
14907 When present, the compiler will insert a call to this routine in the interrupt
14909 \begin_inset LatexCommand index
14910 name "interrupt vector table"
14914 for the interrupt number specified.
14915 If you have multiple source files in your project, interrupt service routines
14916 can be present in any of them, but a prototype of the isr MUST be present
14917 or included in the file that contains the function
14922 The optional (8051 specific) keyword
14925 \begin_inset LatexCommand index
14926 name "using (mcs51, ds390 register bank)"
14931 \begin_inset LatexCommand index
14932 name "\\_\\_using (mcs51, ds390 register bank)"
14938 can be used to tell the compiler to use the specified register bank when
14939 generating code for this function.
14942 Interrupt service routines open the door for some very interesting bugs:
14945 \begin_layout Subsubsection
14946 \begin_inset LatexCommand label
14947 name "sub:Common-interrupt-pitfall-volatile"
14951 Common interrupt pitfall: variable not declared
14956 \begin_layout Standard
14957 If an interrupt service routine changes variables which are accessed by
14958 other functions these variables have to be declared
14963 \begin_inset LatexCommand index
14970 \begin_inset LatexCommand url
14971 target "http://en.wikipedia.org/wiki/Volatile_variable"
14978 \begin_layout Subsubsection
14979 \begin_inset LatexCommand label
14980 name "sub:Common-interrupt-pitfall-non-atomic"
14984 Common interrupt pitfall:
14989 \begin_layout Standard
14990 If the access to these variables is not
14993 \begin_inset LatexCommand index
15001 the processor needs more than one instruction for the access and could
15002 be interrupted while accessing the variable) the interrupt must be disabled
15003 during the access to avoid inconsistent data.
15006 Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
15007 and should be protected by disabling interrupts.
15008 You're not automatically on the safe side if you use 8 bit variables though.
15009 We need an example here: f.e.
15010 on the 8051 the harmless looking
15011 \begin_inset Quotes srd
15021 \begin_inset Quotes sld
15030 \begin_inset Quotes srd
15040 \begin_inset Quotes sld
15043 from within an interrupt routine might get lost if the interrupt occurs
15046 \begin_inset Quotes sld
15051 counter\InsetSpace ~
15056 \begin_inset Quotes srd
15059 is not atomic on the 8051 even if
15063 is located in data memory.
15065 Bugs like these are hard to reproduce and can
15066 cause a lot of trouble.
15070 \begin_layout Subsubsection
15071 \begin_inset LatexCommand label
15072 name "sub:Common-interrupt-pitfall-stack-overflow"
15076 Common interrupt pitfall:
15081 \begin_layout Standard
15082 The return address and the registers used in the interrupt service routine
15083 are saved on the stack
15084 \begin_inset LatexCommand index
15089 so there must be sufficient stack space.
15090 If there isn't variables or registers (or even the return address itself)
15097 \begin_inset LatexCommand index
15098 name "stack overflow"
15102 is most likely to happen if the interrupt occurs during the
15103 \begin_inset Quotes sld
15107 \begin_inset Quotes srd
15110 subroutine when the stack is already in use for f.e.
15111 many return addresses.
15114 \begin_layout Subsubsection
15115 \begin_inset LatexCommand label
15116 name "sub:Common-interrupt-pitfall-non-reentrant"
15120 Common interrupt pitfall:
15122 use of non-reentrant functions
15125 \begin_layout Standard
15126 A special note here, int (16 bit) and long (32 bit) integer division
15127 \begin_inset LatexCommand index
15133 \begin_inset LatexCommand index
15134 name "Multiplication"
15139 \begin_inset LatexCommand index
15145 \begin_inset LatexCommand index
15146 name "Floating point support"
15150 operations are implemented using external support routines.
15151 If an interrupt service routine needs to do any of these operations then
15152 the support routines (as mentioned in a following section) will have to
15153 be recompiled using the
15159 \begin_layout Standard
15169 \begin_inset LatexCommand index
15170 name "-\\/-stack-auto"
15176 option and the source file will need to be compiled using the
15182 \begin_layout Standard
15194 \begin_inset LatexCommand index
15195 name "-\\/-int-long-reent"
15202 Note, the type promotion
15203 \begin_inset LatexCommand index
15204 name "type promotion"
15208 required by ANSI C can cause 16 bit routines to be used
15209 \begin_inset Marginal
15212 \begin_layout Standard
15221 without the programmer being aware of it.
15226 (unsigned char)(tail-1)
15231 within the if clause in section
15232 \begin_inset LatexCommand ref
15233 reference "sub:A-Step-by Assembler Introduction"
15240 \begin_layout Standard
15241 Calling other functions from an interrupt service routine is not recommended,
15242 avoid it if possible.
15243 Note that when some function is called from an interrupt service routine
15244 it should be preceded by a #pragma\InsetSpace ~
15246 \begin_inset LatexCommand index
15247 name "\\#pragma nooverlay"
15251 if it is not reentrant.
15252 Furthermore nonreentrant functions should not be called from the main program
15253 while the interrupt service routine might be active.
15254 They also must not be called from low priority interrupt service routines
15255 while a high priority interrupt service routine might be active.
15256 You could use semaphores or make the function
15260 if all parameters are passed in registers.
15263 \begin_inset LatexCommand ref
15264 reference "sub:Overlaying"
15269 about Overlaying and section
15270 \begin_inset LatexCommand ref
15271 reference "sub:Functions-using-private-banks"
15276 about Functions using private register banks.
15277 \begin_inset VSpace bigskip
15283 \begin_layout Subsection
15284 MCS51/DS390 Interrupt Service Routines
15287 \begin_layout Standard
15289 \begin_inset LatexCommand index
15294 numbers and the corresponding address & descriptions for the Standard 8051/8052
15296 SDCC will automatically adjust the
15297 \begin_inset LatexCommand index
15298 name "interrupt vector table"
15302 to the maximum interrupt number specified.
15307 \begin_layout Standard
15309 \begin_inset Tabular
15310 <lyxtabular version="3" rows="9" columns="3">
15312 <column alignment="center" valignment="top" leftline="true" width="0in">
15313 <column alignment="left" valignment="top" leftline="true" width="0in">
15314 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
15315 <row topline="true" bottomline="true">
15316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15319 \begin_layout Standard
15325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15328 \begin_layout Standard
15334 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15337 \begin_layout Standard
15344 <row topline="true">
15345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15348 \begin_layout Standard
15354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15357 \begin_layout Standard
15363 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15366 \begin_layout Standard
15373 <row topline="true">
15374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15377 \begin_layout Standard
15383 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15386 \begin_layout Standard
15392 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15395 \begin_layout Standard
15402 <row topline="true">
15403 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15406 \begin_layout Standard
15412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15415 \begin_layout Standard
15421 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15424 \begin_layout Standard
15431 <row topline="true">
15432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15435 \begin_layout Standard
15441 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15444 \begin_layout Standard
15450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15453 \begin_layout Standard
15460 <row topline="true">
15461 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15464 \begin_layout Standard
15470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15473 \begin_layout Standard
15479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15482 \begin_layout Standard
15489 <row topline="true">
15490 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15493 \begin_layout Standard
15499 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15502 \begin_layout Standard
15508 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15511 \begin_layout Standard
15518 <row topline="true">
15519 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15522 \begin_layout Standard
15528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15531 \begin_layout Standard
15537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15540 \begin_layout Standard
15547 <row topline="true" bottomline="true">
15548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15551 \begin_layout Standard
15557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15560 \begin_layout Standard
15566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15569 \begin_layout Standard
15585 \begin_layout Standard
15586 If the interrupt service routine is defined without
15589 \begin_inset LatexCommand index
15590 name "using (mcs51, ds390 register bank)"
15595 \begin_inset LatexCommand index
15596 name "\\_\\_using (mcs51, ds390 register bank)"
15602 a register bank or with register bank 0 (
15606 0), the compiler will save the registers used by itself on the stack upon
15607 entry and restore them at exit, however if such an interrupt service routine
15608 calls another function then the entire register bank will be saved on the
15610 This scheme may be advantageous for small interrupt service routines which
15611 have low register usage.
15614 \begin_layout Standard
15615 If the interrupt service routine is defined to be using a specific register
15620 & psw are saved and restored, if such an interrupt service routine calls
15621 another function (using another register bank) then the entire register
15622 bank of the called function will be saved on the stack
15623 \begin_inset LatexCommand index
15629 This scheme is recommended for larger interrupt service routines.
15630 \begin_inset VSpace bigskip
15636 \begin_layout Subsection
15638 \begin_inset LatexCommand index
15643 Interrupt Service Routines
15646 \begin_layout Standard
15647 Since the number of interrupts
15648 \begin_inset LatexCommand index
15649 name "HC08!interrupt"
15653 available is chip specific and the interrupt vector table always ends at
15654 the last byte of memory, the interrupt numbers corresponds to the interrupt
15655 vectors in reverse order of address.
15656 For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
15657 2 will use the interrupt vector at 0xfffa, and so on.
15658 However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
15659 this way; instead see section
15660 \begin_inset LatexCommand ref
15661 reference "sub:Startup-Code"
15665 for details on customizing startup.
15666 \begin_inset VSpace bigskip
15672 \begin_layout Subsection
15673 Z80 Interrupt Service Routines
15676 \begin_layout Standard
15678 \begin_inset LatexCommand index
15683 uses several different methods for determining the correct interrupt
15684 \begin_inset LatexCommand index
15685 name "Z80!interrupt"
15689 vector depending on the hardware implementation.
15690 Therefore, SDCC ignores the optional interrupt number and does not attempt
15691 to generate an interrupt vector table.
15694 \begin_layout Standard
15695 By default, SDCC generates code for a maskable interrupt, which uses a RETI
15696 instruction to return from the interrupt.
15697 To write an interrupt handler for the non-maskable interrupt, which needs
15698 a RETN instruction instead, add the
15705 \begin_layout Verse
15708 void nmi_isr (void) critical interrupt
15722 \begin_layout Standard
15723 However if you need to create a non-interruptable interrupt service routine
15724 you would also require the
15729 To distinguish between this and an nmi_isr you must provide an interrupt
15731 \begin_inset VSpace bigskip
15737 \begin_layout Section
15738 Enabling and Disabling Interrupts
15741 \begin_layout Subsection
15742 Critical Functions and Critical Statements
15745 \begin_layout Standard
15746 A special keyword may be associated with a block or a function declaring
15752 SDCC will generate code to disable all interrupts
15753 \begin_inset LatexCommand index
15758 upon entry to a critical function and restore the interrupt enable to the
15759 previous state before returning.
15760 Nesting critical functions will need one additional byte on the stack
15761 \begin_inset LatexCommand index
15769 \begin_layout Verse
15772 int foo () __critical
15773 \begin_inset LatexCommand index
15779 \begin_inset LatexCommand index
15780 name "\\_\\_critical"
15805 \begin_layout Standard
15806 The critical attribute maybe used with other attributes like
15816 may also be used to disable interrupts more locally:
15819 \begin_layout Verse
15825 \begin_layout Standard
15826 More than one statement could have been included in the block.
15829 \begin_layout Subsection
15830 Enabling and Disabling Interrupts directly
15833 \begin_layout Standard
15835 \begin_inset LatexCommand index
15840 can also be disabled and enabled directly (8051):
15843 \begin_layout Verse
15846 EA = 0;\InsetSpace ~
15872 \begin_layout Verse
15908 \begin_layout Verse
15911 EA = 1;\InsetSpace ~
15940 \begin_layout Verse
15979 \begin_layout Standard
15980 On other architectures which have separate opcodes for enabling and disabling
15981 interrupts you might want to make use of defines with inline assembly
15982 \begin_inset LatexCommand index
15983 name "Assembler routines"
15988 \begin_inset LatexCommand index
15989 name "HC08!interrupt"
15996 \begin_layout Verse
16000 \begin_inset LatexCommand index
16010 \begin_inset LatexCommand index
16018 \begin_layout Verse
16021 #define SEI _asm\InsetSpace ~
16028 \begin_layout Verse
16034 \begin_layout Standard
16035 Note: it is sometimes sufficient to disable only a specific interrupt source
16037 a timer or serial interrupt by manipulating an
16040 \begin_inset LatexCommand index
16041 name "interrupt mask"
16051 \begin_layout Standard
16052 Usually the time during which interrupts are disabled should be kept as
16054 This minimizes both
16059 \begin_inset LatexCommand index
16060 name "interrupt latency"
16064 (the time between the occurrence of the interrupt and the execution of
16065 the first code in the interrupt routine) and
16070 \begin_inset LatexCommand index
16071 name "interrupt jitter"
16075 (the difference between the shortest and the longest interrupt latency).
16076 These really are something different, f.e.
16077 a serial interrupt has to be served before its buffer overruns so it cares
16078 for the maximum interrupt latency, whereas it does not care about jitter.
16079 On a loudspeaker driven via a digital to analog converter which is fed
16080 by an interrupt a latency of a few milliseconds might be tolerable, whereas
16081 a much smaller jitter will be very audible.
16084 \begin_layout Standard
16085 You can reenable interrupts within an interrupt routine and on some architecture
16086 s you can make use of two (or more) levels of
16088 interrupt priorities
16091 \begin_inset LatexCommand index
16092 name "interrupt priority"
16097 On some architectures which don't support interrupt priorities these can
16098 be implemented by manipulating the interrupt mask and reenabling interrupts
16099 within the interrupt routine.
16100 Check there is sufficient space on the stack
16101 \begin_inset LatexCommand index
16106 and don't add complexity unless you have to.
16110 \begin_layout Subsection
16112 \begin_inset LatexCommand index
16117 locking (mcs51/ds390)
16120 \begin_layout Standard
16121 Some architectures (mcs51/ds390) have an atomic
16122 \begin_inset LatexCommand index
16127 bit test and clear instruction.
16128 These type of instructions are typically used in preemptive multitasking
16129 systems, where a routine f.e.
16130 claims the use of a data structure ('acquires a lock
16131 \begin_inset LatexCommand index
16136 on it'), makes some modifications and then releases the lock when the data
16137 structure is consistent again.
16138 The instruction may also be used if interrupt and non-interrupt code have
16139 to compete for a resource.
16140 With the atomic bit test and clear instruction interrupts
16141 \begin_inset LatexCommand index
16146 don't have to be disabled for the locking operation.
16150 \begin_layout Standard
16151 SDCC generates this instruction if the source follows this pattern:
16154 \begin_layout Verse
16158 \begin_inset LatexCommand index
16163 bit resource_is_free;
16167 if (resource_is_free)
16177 resource_is_free=0;
16190 resource_is_free=1;
16197 \begin_layout Standard
16198 Note, mcs51 and ds390 support only an atomic
16199 \begin_inset LatexCommand index
16208 instruction (as opposed to atomic bit test and
16213 \begin_layout Section
16214 Functions using private register banks
16215 \begin_inset LatexCommand label
16216 name "sub:Functions-using-private-banks"
16223 \begin_layout Standard
16224 Some architectures have support for quickly changing register sets.
16225 SDCC supports this feature with the
16228 \begin_inset LatexCommand index
16229 name "using (mcs51, ds390 register bank)"
16234 \begin_inset LatexCommand index
16235 name "\\_\\_using (mcs51, ds390 register bank)"
16241 attribute (which tells the compiler to use a register bank
16242 \begin_inset LatexCommand index
16243 name "register bank (mcs51, ds390)"
16247 other than the default bank zero).
16248 It should only be applied to
16251 \begin_inset LatexCommand index
16258 functions (see footnote below).
16259 This will in most circumstances make the generated ISR code more efficient
16260 since it will not have to save registers on the stack.
16263 \begin_layout Standard
16268 attribute will have no effect on the generated code for a
16272 function (but may occasionally be useful anyway
16276 \begin_layout Standard
16277 possible exception: if a function is called ONLY from 'interrupt' functions
16278 using a particular bank, it can be declared with the same 'using' attribute
16279 as the calling 'interrupt' functions.
16280 For instance, if you have several ISRs using bank one, and all of them
16281 call memcpy(), it might make sense to create a specialized version of memcpy()
16282 'using 1', since this would prevent the ISR from having to save bank zero
16283 to the stack on entry and switch to bank zero before calling the function
16292 (pending: Note, nowadays the
16296 attribute has an effect on
16300 the generated code for a
16311 \begin_layout Standard
16316 function using a non-zero bank will assume that it can trash that register
16317 bank, and will not save it.
16318 Since high-priority interrupts
16319 \begin_inset LatexCommand index
16325 \begin_inset LatexCommand index
16326 name "interrupt priority"
16330 can interrupt low-priority ones on the 8051 and friends, this means that
16331 if a high-priority ISR
16335 a particular bank occurs while processing a low-priority ISR
16339 the same bank, terrible and bad things can happen.
16340 To prevent this, no single register bank should be
16344 by both a high priority and a low priority ISR.
16345 This is probably most easily done by having all high priority ISRs use
16346 one bank and all low priority ISRs use another.
16347 If you have an ISR which can change priority at runtime, you're on your
16348 own: I suggest using the default bank zero and taking the small performance
16352 \begin_layout Standard
16353 It is most efficient if your ISR calls no other functions.
16354 If your ISR must call other functions, it is most efficient if those functions
16355 use the same bank as the ISR (see note 1 below); the next best is if the
16356 called functions use bank zero.
16357 It is very inefficient to call a function using a different, non-zero bank
16360 \begin_inset VSpace bigskip
16366 \begin_layout Section
16368 \begin_inset LatexCommand label
16369 name "sub:Startup-Code"
16374 \begin_inset LatexCommand index
16375 name "Startup code"
16382 \begin_layout Subsection
16383 MCS51/DS390 Startup Code
16386 \begin_layout Standard
16387 The compiler triggers the linker to link certain initialization modules
16388 from the runtime library
16389 \begin_inset LatexCommand index
16390 name "Runtime library"
16394 called crt<something>.
16395 Only the necessary ones are linked, for instance crtxstack.asm (GSINIT1,
16396 GSINIT5) is not linked unless the -
16402 \begin_layout Standard
16413 -xstack option is used.
16414 These modules are highly entangled by the use of special segments/areas,
16415 but a common layout is shown below:
16418 \begin_layout Verse
16426 \begin_layout Verse
16450 ljmp __sdcc_gsinit_startup
16453 \begin_layout Verse
16461 \begin_layout Verse
16473 .area GSINIT0 (CODE)
16475 __sdcc_gsinit_startup::
16485 mov sp,#__start__stack - 1
16488 \begin_layout Verse
16496 \begin_layout Verse
16508 .area GSINIT1 (CODE)
16510 __sdcc_init_xstack::
16512 ; Need to initialize in GSINIT1 in
16513 case the user's __sdcc_external_startup uses the xstack.
16523 mov __XPAGE,#(__start__x
16534 mov _spx,#__start__xstack
16537 \begin_layout Verse
16545 \begin_layout Verse
16557 .area GSINIT2 (CODE)
16567 lcall __sdcc_external_startup
16587 jz __sdcc_init_data
16598 __sdcc_program_startup
16603 \begin_layout Verse
16611 \begin_layout Verse
16623 .area GSINIT3 (CODE)
16676 mov r2,#((l_XINIT+255) >> 8)
16707 __XPAGE,#(s_XISEG >> 8)
16709 00001$:\InsetSpace ~
16773 00002$:\InsetSpace ~
16800 \begin_layout Verse
16808 \begin_layout Verse
16820 .area GSINIT4 (CODE)
16822 __mcs51_genRAMCLEAR::
16844 00004$:\InsetSpace ~
16858 ; _mcs51_genRAMCLEAR() end
16861 \begin_layout Verse
16869 \begin_layout Verse
16881 .area GSINIT4 (CODE)
16883 __mcs51_genXRAMCLEAR::
16944 mov __XPAGE,#(s_PSEG >> 8)
16956 00005$:\InsetSpace ~
17031 mov r1,#((l_XSEG + 255) >> 8)
17053 00007$:\InsetSpace ~
17090 \begin_layout Verse
17098 \begin_layout Verse
17110 .area GSINIT5 (CODE)
17112 ; Need to initialize in GSINIT5 because __mcs51_genXINIT
17115 ; and __mcs51_genRAMCLEAR modifies _spx.
17125 mov __XPAGE,#(__start__x
17136 mov _spx,#__start__xstack
17139 \begin_layout Verse
17144 (application modules)
17147 \begin_layout Verse
17159 .area GSINIT (CODE)
17162 \begin_layout Verse
17170 \begin_layout Verse
17182 .area GSFINAL (CODE)
17192 ljmp __sdcc_program_startup
17194 ;---------------------------------
17195 -----------------------
17199 ;--------------------------------------------------
17222 __sdcc_program_startup:
17235 return from main will lock up
17248 \begin_layout Standard
17249 One of these modules (crtstart.asm) contains a call to the C routine
17251 _sdcc_external_startup()
17252 \begin_inset LatexCommand index
17253 name "\\_sdcc\\_external\\_startup()"
17259 at the start of the CODE area.
17260 This routine is also in the runtime library
17261 \begin_inset LatexCommand index
17262 name "Runtime library"
17266 and returns 0 by default.
17267 If this routine returns a non-zero value, the static & global variable
17268 initialization will be skipped and the function main will be invoked.
17269 Otherwise static & global variables will be initialized before the function
17273 _sdcc_external_startup()
17275 routine to your program to override the default if you need to setup hardware
17276 or perform some other critical operation prior to static & global variable
17278 \begin_inset LatexCommand index
17279 name "Variable initialization"
17284 On some mcs51 variants xdata
17285 \begin_inset LatexCommand index
17286 name "xdata (mcs51, ds390 storage class)"
17290 memory has to be explicitly enabled before it can be accessed or if the
17292 \begin_inset LatexCommand index
17297 needs to be disabled, this is the place to do it.
17298 The startup code clears all internal data memory, 256 bytes by default,
17299 but from 0 to n-1 if
17305 \begin_layout Standard
17315 \begin_inset LatexCommand index
17316 name "-\\/-iram-size <Value>"
17323 (recommended for Chipcon CC1010).
17326 \begin_layout Standard
17327 See also the compiler options
17333 \begin_layout Standard
17349 \begin_inset LatexCommand index
17350 name "-\\/-no-xinit-opt"
17360 \begin_layout Standard
17372 \begin_inset LatexCommand index
17373 name "-\\/-main-return"
17378 \begin_inset LatexCommand ref
17379 reference "sub:MCS51-variants"
17383 about MCS51-variants.
17388 \begin_layout Standard
17389 While these initialization modules are meant as generic startup code there
17390 might be the need for customization.
17391 Let's assume the return value of
17393 _sdcc_external_startup()
17399 should not be checked (or
17401 _sdcc_external_startup()
17403 should not be called at all).
17404 The recommended way would be to copy
17410 \begin_inset LatexCommand url
17411 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/device/lib/mcs51/crtstart.asm"
17415 ) into the source directory, adapt it there, then assemble it with
17421 \begin_layout Standard
17422 \begin_inset Quotes sld
17426 \begin_inset Quotes srd
17429 are the assembler options used in
17430 \begin_inset LatexCommand url
17431 target "http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/lib/mcs51/Makefile.in?view=markup "
17442 and when linking your project explicitly specify
17447 As a bonus a listing of the relocated object file
17454 \begin_layout Standard
17455 \begin_inset VSpace bigskip
17461 \begin_layout Subsection
17465 \begin_layout Standard
17467 \begin_inset LatexCommand index
17472 startup code follows the same scheme as the MCS51 startup code.
17473 \begin_inset VSpace bigskip
17479 \begin_layout Subsection
17483 \begin_layout Standard
17485 \begin_inset LatexCommand index
17490 the startup code is inserted by linking with crt0.o which is generated from
17491 sdcc/device/lib/z80/crt0.s.
17492 If you need a different startup code you can use the compiler option
17501 \begin_layout Standard
17516 \begin_inset LatexCommand index
17517 name "-\\/-no-std-crt0"
17521 and provide your own crt0.o.
17523 \begin_inset VSpace bigskip
17529 \begin_layout Section
17530 Inline Assembler Code
17531 \begin_inset LatexCommand index
17532 name "Assembler routines"
17539 \begin_layout Subsection
17540 A Step by Step Introduction
17541 \begin_inset LatexCommand label
17542 name "sub:A-Step-by Assembler Introduction"
17549 \begin_layout Standard
17550 Starting from a small snippet of c-code this example shows for the MCS51
17551 how to use inline assembly, access variables, a function parameter and
17552 an array in xdata memory.
17553 The example uses an MCS51 here but is easily adapted for other architectures.
17554 This is a buffer routine which should be optimized:
17557 \begin_layout Verse
17561 unsigned char __far
17562 \begin_inset LatexCommand index
17563 name "far (storage class)"
17568 \begin_inset LatexCommand index
17569 name "\\_\\_far (storage class)"
17574 \begin_inset LatexCommand index
17580 \begin_inset LatexCommand index
17585 (0x7f00) buf[0x100];
17586 \begin_inset LatexCommand index
17587 name "Aligned array"
17593 unsigned char head, tail;\InsetSpace ~
17611 \begin_inset LatexCommand index
17664 \begin_inset LatexCommand ref
17665 reference "sub:Common-interrupt-pitfall-volatile"
17683 void to_buffer( unsigned char c )
17691 if( head != (unsigned char)(tail-1)
17704 \begin_inset LatexCommand index
17705 name "promotion to signed int"
17710 \begin_inset LatexCommand index
17711 name "type promotion"
17716 \begin_inset Marginal
17719 \begin_layout Standard
17738 buf[ head++ ] = c;\InsetSpace ~
17754 /* access to a 256 byte aligned array */
17759 \begin_layout Standard
17760 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
17761 then a corresponding buffer.asm file is generated.
17762 We define a new function
17766 in file buffer.c in which we cut and paste the generated code, removing
17767 unwanted comments and some ':'.
17769 \begin_inset Quotes sld
17777 \begin_inset Quotes srd
17781 \begin_inset Quotes sld
17789 \begin_inset Quotes srd
17796 \begin_layout Standard
17797 Note, that the single underscore form (_asm and _endasm) are not C99-compatible,
17798 and for C-99 compatibility, the double-underscore form (__asm and __endasm)
17800 The latter is also used in the library functions.
17805 to the beginning and the end of the function body:
17808 \begin_layout Verse
17812 /* With a cut and paste from the .asm file, we have something to start with.
17818 function is not yet OK! (registers aren't saved) */
17820 void to_buffer_asm(
17830 \begin_inset LatexCommand index
17836 \begin_inset LatexCommand index
17851 ;buffer.c if( head != (unsigned char)(tail-1) ) \InsetSpace ~
17863 \begin_inset LatexCommand index
17864 name "promotion to signed int"
17869 \begin_inset LatexCommand index
17870 name "type promotion"
17923 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
17924 \begin_inset LatexCommand index
17925 name "Aligned array"
17991 \begin_inset LatexCommand index
17997 \begin_inset LatexCommand index
17998 name "\\_\\_endasm"
18007 \begin_layout Standard
18008 The new file buffer.c should compile with only one warning about the unreferenced
18009 function argument 'c'.
18010 Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
18011 (1) and finally have:
18014 \begin_layout Verse
18018 unsigned char __far __at(0x7f00) buf[0x100];
18020 unsigned char head, tail;
18031 void to_buffer( unsigned char c )
18040 head != (unsigned char)(tail-1) )
18069 c; // to avoid warning: unreferenced function argument
18076 \begin_inset LatexCommand index
18082 \begin_inset LatexCommand index
18097 ; save used registers here.
18108 ; If we were still using r2,r3 we would have to push them here.
18111 ; if( head != (unsigned char)(tail-1) )
18155 could do an ANL a,#0x0f here to use a smaller buffer (see below)
18191 a,dpl \InsetSpace ~
18198 ; dpl holds lower byte of function argument
18210 dpl,_head \InsetSpace ~
18213 ; buf is 0x100 byte aligned so head can be used directly
18256 ; we could do an ANL _head,#0x0f here to use a
18257 smaller buffer (see above)
18269 ; restore used registers here
18276 \begin_inset LatexCommand index
18282 \begin_inset LatexCommand index
18283 name "\\_\\_endasm"
18294 \begin_layout Standard
18295 The inline assembler code can contain any valid code understood by the assembler
18296 , this includes any assembler directives and comment lines.
18297 The assembler does not like some characters like ':' or ''' in comments.
18298 You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
18299 \begin_inset LatexCommand index
18300 name "asXXXX (as-gbz80, as-hc08, asx8051, as-z80)"
18305 \begin_inset LatexCommand index
18306 name "Assembler documentation"
18311 \begin_inset LatexCommand url
18312 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html"
18320 \begin_layout Standard
18321 The compiler does not do any validation of the code within the
18324 \begin_inset LatexCommand index
18330 \begin_inset LatexCommand index
18339 \begin_inset LatexCommand index
18345 \begin_inset LatexCommand index
18346 name "\\_\\_endasm"
18355 Specifically it will not know which registers are used and thus register
18357 \begin_inset LatexCommand index
18362 has to be done manually.
18366 \begin_layout Standard
18367 It is recommended that each assembly instruction (including labels) be placed
18368 in a separate line (as the example shows).
18373 \begin_layout Standard
18385 \begin_inset LatexCommand index
18386 name "-\\/-peep-asm"
18392 command line option is used, the inline assembler code will be passed through
18393 the peephole optimizer
18394 \begin_inset LatexCommand index
18395 name "Peephole optimizer"
18400 There are only a few (if any) cases where this option makes sense, it might
18401 cause some unexpected changes in the inline assembler code.
18402 Please go through the peephole optimizer rules defined in file
18406 before using this option.
18409 \begin_layout Subsection
18411 \begin_inset LatexCommand label
18412 name "sub:Naked-Functions"
18417 \begin_inset LatexCommand index
18418 name "Naked functions"
18425 \begin_layout Standard
18426 A special keyword may be associated with a function declaring it as
18429 \begin_inset LatexCommand index
18435 \begin_inset LatexCommand index
18447 function modifier attribute prevents the compiler from generating prologue
18448 \begin_inset LatexCommand index
18449 name "function prologue"
18454 \begin_inset LatexCommand index
18455 name "function epilogue"
18459 code for that function.
18460 This means that the user is entirely responsible for such things as saving
18461 any registers that may need to be preserved, selecting the proper register
18462 bank, generating the
18466 instruction at the end, etc.
18467 Practically, this means that the contents of the function must be written
18468 in inline assembler.
18469 This is particularly useful for interrupt functions, which can have a large
18470 (and often unnecessary) prologue/epilogue.
18471 For example, compare the code generated by these two functions:
18474 \begin_layout Verse
18478 \begin_inset LatexCommand index
18483 data unsigned char counter;
18487 void simpleInterrupt(void) __interrupt
18488 \begin_inset LatexCommand index
18494 \begin_inset LatexCommand index
18495 name "\\_\\_interrupt"
18513 void nakedInterrupt(void) __interrupt (2) __naked
18522 \begin_inset LatexCommand index
18528 \begin_inset LatexCommand index
18546 _counter ; does not change flags, no need to save psw
18559 include ret or reti in _naked function.
18566 \begin_inset LatexCommand index
18572 \begin_inset LatexCommand index
18573 name "\\_\\_endasm"
18582 \begin_layout Standard
18583 For an 8051 target, the generated simpleInterrupt looks like:
18586 \begin_layout Verse
18599 example, recent versions of SDCC generate
18611 code for simpleInterrupt() and nakedInterrupt()!
18752 \begin_layout Standard
18753 whereas nakedInterrupt looks like:
18756 \begin_layout Verse
18769 _counter ; does not change flags, no need to save psw
18788 MUST explicitly include ret or reti in _naked function
18791 \begin_layout Standard
18792 The related directive #pragma exclude
18793 \begin_inset LatexCommand index
18794 name "\\#pragma exclude"
18798 allows a more fine grained control over pushing & popping
18799 \begin_inset LatexCommand index
18807 \begin_layout Standard
18808 While there is nothing preventing you from writing C code inside a
18812 function, there are many ways to shoot yourself in the foot doing this,
18813 and it is recommended that you stick to inline assembler.
18816 \begin_layout Subsection
18817 Use of Labels within Inline Assembler
18820 \begin_layout Standard
18821 SDCC allows the use of in-line assembler with a few restrictions regarding
18823 All labels defined within inline assembler code have to be of the form
18828 where nnnnn is a number less than 100 (which implies a limit of utmost
18829 100 inline assembler labels
18840 \begin_layout Standard
18841 This is a slightly more stringent rule than absolutely necessary, but stays
18842 always on the safe side.
18843 Labels in the form of nnnnn$ are local labels in the assembler, locality
18844 of which is confined within two labels of the standard form.
18845 The compiler uses the same form for labels within a function (but starting
18846 from nnnnn=00100); and places always a standard label at the beginning
18847 of a function, thus limiting the locality of labels within the scope of
18849 So, if the inline assembler part would be embedded into C-code, an improperly
18850 placed non-local label in the assembler would break up the reference space
18851 for labels created by the compiler for the C-code, leading to an assembling
18855 \begin_layout Standard
18856 The numeric part of local labels does not need to have 5 digits (although
18857 this is the form of labels output by the compiler), any valid integer will
18859 Please refer to the assemblers documentation for further details.
18867 \begin_layout Verse
18871 \begin_inset LatexCommand index
18877 \begin_inset LatexCommand index
18908 \begin_inset LatexCommand index
18914 \begin_inset LatexCommand index
18915 name "\\_\\_endasm"
18922 \begin_layout Standard
18923 Inline assembler code cannot reference any C-labels, however it can reference
18925 \begin_inset LatexCommand index
18930 defined by the inline assembler, e.g.:
18933 \begin_layout Verse
18956 ; some assembler code
18977 /* some more c code */
18979 clabel:\InsetSpace ~
18981 /* inline assembler cannot reference this
18986 \begin_layout Standard
18991 is translated by the compiler into a local label, so the locality of labels
18992 within the function is not broken.
19009 0003$: ;label (can be referenced by inline assembler only)
19016 \begin_inset LatexCommand index
19022 \begin_inset LatexCommand index
19023 name "\\_\\_endasm"
19033 /* some more c code */
19038 \begin_layout Standard
19039 In other words inline assembly code can access labels defined in inline
19040 assembly within the scope of the function.
19041 The same goes the other way, i.e.
19042 labels defines in inline assembly can not be accessed by C statements.
19045 \begin_layout Section
19046 Interfacing with Assembler Code
19047 \begin_inset LatexCommand index
19048 name "Assembler routines"
19055 \begin_layout Subsection
19056 Global Registers used for Parameter Passing
19057 \begin_inset LatexCommand index
19058 name "Parameter passing"
19065 \begin_layout Standard
19066 The compiler always uses the global registers
19069 \begin_inset LatexCommand index
19070 name "DPTR, DPH, DPL"
19075 \begin_inset LatexCommand index
19081 \begin_inset LatexCommand index
19082 name "B (mcs51, ds390 register)"
19091 \begin_inset LatexCommand index
19092 name "ACC (mcs51, ds390 register)"
19098 to pass the first (non-bit) parameter to a function, and also to pass the
19100 \begin_inset LatexCommand index
19101 name "return value"
19105 of function; according to the following scheme: one byte return value in
19110 , two byte value in
19119 three byte values (generic pointers) in
19131 , and four byte values in
19149 \begin_inset LatexCommand index
19150 name "generic pointer"
19154 contain type of accessed memory in
19175 \begin_inset Note Note
19178 \begin_layout Standard
19179 This might not be the case of certain memory models (medium???)
19187 \begin_layout Standard
19188 The second parameter onwards is either allocated on the stack (for reentrant
19193 \begin_layout Standard
19202 -stack-auto is used) or in data/xdata memory (depending on the memory model).
19205 \begin_layout Standard
19206 Bit parameters are passed in a virtual register called 'bits' in bit-addressable
19207 space for reentrant functions or allocated directly in bit memory otherwise.
19210 \begin_layout Standard
19211 Functions (with two or more parameters or bit parameters) that are called
19212 through function pointers
19213 \begin_inset LatexCommand index
19214 name "function pointers"
19218 must therefor be reentrant so the compiler knows how to pass the parameters.
19221 \begin_layout Subsection
19225 \begin_layout Standard
19226 Unless the called function is declared as
19231 \begin_inset LatexCommand index
19240 \begin_layout Standard
19250 \begin_inset LatexCommand index
19251 name "-\\/-callee-saves"
19259 \begin_layout Standard
19268 -all-callee-saves command line option or the corresponding callee_saves
19269 pragma are used, the caller will save the registers (
19273 ) around the call, so the called function can destroy they content freely.
19276 \begin_layout Standard
19277 If the called function is not declared as
19281 , the caller will swap register banks around the call, if caller and callee
19282 use different register banks (having them defined by the
19290 \begin_layout Standard
19291 The called function can also use
19307 observing that they are used for parameter/return value passing.
19310 \begin_layout Subsection
19311 Assembler Routine (non-reentrant)
19314 \begin_layout Standard
19315 In the following example
19316 \begin_inset LatexCommand index
19322 \begin_inset LatexCommand index
19323 name "Assembler routines (non-reentrant)"
19327 the function c_func calls an assembler routine asm_func, which takes two
19329 \begin_inset LatexCommand index
19330 name "function parameter"
19337 \begin_layout Verse
19340 extern int asm_func(unsigned char, unsigned char);
19344 int c_func (unsigned char
19345 i, unsigned char j)
19353 return asm_func(i,j);
19367 return c_func(10,9);
19372 \begin_layout Standard
19373 The corresponding assembler function is:
19376 \begin_layout Verse
19379 .globl _asm_func_PARM_2
19481 \begin_inset LatexCommand index
19482 name "DPTR, DPH, DPL"
19499 \begin_layout Standard
19500 The parameter naming convention is _<function_name>_PARM_<n>, where n is
19501 the parameter number starting from 1, and counting from the left.
19502 The first parameter is passed in
19518 according to the description above.
19519 The variable name for the second parameter will be _<function_name>_PARM_2.
19524 ble the assembler routine with the following command:
19531 asx8051 -losg asmfunc.asm
19538 Then compile and link the assembler routine to the C source file with the
19546 sdcc cfunc.c asmfunc.rel
19549 \begin_layout Subsection
19550 Assembler Routine (reentrant)
19553 \begin_layout Standard
19555 \begin_inset LatexCommand index
19561 \begin_inset LatexCommand index
19562 name "Assembler routines (reentrant)"
19566 the second parameter
19567 \begin_inset LatexCommand index
19568 name "function parameter"
19572 onwards will be passed on the stack, the parameters are pushed from right
19574 before the call the second leftmost parameter will be on the top of the
19575 stack (the leftmost parameter is passed in registers).
19576 Here is an example:
19579 \begin_layout Verse
19582 extern int asm_func(unsigned char, unsigned char, unsigned char) reentrant;
19587 c_func (unsigned char i, unsigned char j, unsigned char k) reentrant
19596 return asm_func(i,j,k);
19610 return c_func(10,9,8);
19615 \begin_layout Standard
19616 The corresponding (unoptimized) assembler routine is:
19619 \begin_layout Verse
19639 _bp,sp\InsetSpace ~
19645 ;stack contains: _bp, return
19646 address, second parameter, third parameter
19670 a,#0xfd\InsetSpace ~
19676 pointer to the second parameter
19700 a,#0xfc\InsetSpace ~
19706 to the rightmost parameter
19747 result (= sum of all three parameters)
19762 ;return value goes into dptr
19796 \begin_layout Standard
19797 The compiling and linking procedure remains the same, however note the extra
19798 entry & exit linkage required for the assembler code, _bp is the stack
19799 frame pointer and is used to compute the offset into the stack for parameters
19800 and local variables.
19801 \begin_inset VSpace bigskip
19807 \begin_layout Section
19809 \begin_inset LatexCommand index
19810 name "int (16 bit)"
19815 \begin_inset LatexCommand index
19816 name "long (32 bit)"
19823 \begin_layout Standard
19824 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
19825 multiplication and modulus operations are implemented by support routines.
19826 These support routines are all developed in ANSI-C to facilitate porting
19827 to other MCUs, although some model specific assembler optimizations are
19829 The following files contain the described routines, all of them can be
19830 found in <installdir>/share/sdcc/lib.
19835 \begin_layout Standard
19837 \begin_inset Tabular
19838 <lyxtabular version="3" rows="11" columns="2">
19840 <column alignment="left" valignment="top" leftline="true" width="0">
19841 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
19842 <row topline="true" bottomline="true">
19843 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19846 \begin_layout Standard
19854 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19857 \begin_layout Standard
19866 <row topline="true">
19867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19870 \begin_layout Standard
19876 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19879 \begin_layout Standard
19880 16 bit multiplication
19886 <row topline="true">
19887 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19890 \begin_layout Standard
19896 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19899 \begin_layout Standard
19900 signed 16 bit division (calls _divuint)
19906 <row topline="true">
19907 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19910 \begin_layout Standard
19916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19919 \begin_layout Standard
19920 unsigned 16 bit division
19926 <row topline="true">
19927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19930 \begin_layout Standard
19936 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19939 \begin_layout Standard
19940 signed 16 bit modulus (calls _moduint)
19946 <row topline="true">
19947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19950 \begin_layout Standard
19956 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19959 \begin_layout Standard
19960 unsigned 16 bit modulus
19966 <row topline="true">
19967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19970 \begin_layout Standard
19976 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19979 \begin_layout Standard
19980 32 bit multiplication
19986 <row topline="true">
19987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19990 \begin_layout Standard
19996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19999 \begin_layout Standard
20000 signed 32 division (calls _divulong)
20006 <row topline="true">
20007 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20010 \begin_layout Standard
20016 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20019 \begin_layout Standard
20020 unsigned 32 division
20026 <row topline="true">
20027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20030 \begin_layout Standard
20036 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20039 \begin_layout Standard
20040 signed 32 bit modulus (calls _modulong)
20046 <row topline="true" bottomline="true">
20047 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20050 \begin_layout Standard
20056 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20059 \begin_layout Standard
20060 unsigned 32 bit modulus
20075 \begin_layout Standard
20076 Since they are compiled as
20081 \begin_inset LatexCommand index
20087 \begin_inset LatexCommand index
20092 service routines should not do any of the above operations.
20093 If this is unavoidable then the above routines will need to be compiled
20100 \begin_layout Standard
20110 \begin_inset LatexCommand index
20111 name "-\\/-stack-auto"
20117 option, after which the source program will have to be compiled with
20123 \begin_layout Standard
20133 \begin_inset LatexCommand index
20134 name "-\\/-int-long-reent"
20141 Notice that you don't have to call these routines directly.
20142 The compiler will use them automatically every time an integer operation
20146 \begin_layout Section
20147 Floating Point Support
20148 \begin_inset LatexCommand index
20149 name "Floating point support"
20156 \begin_layout Standard
20157 SDCC supports IEEE (single precision 4 bytes) floating point numbers.
20158 The floating point support routines are derived from gcc's floatlib.c and
20159 consist of the following routines:
20164 \begin_layout Standard
20168 \begin_inset Tabular
20169 <lyxtabular version="3" rows="17" columns="2">
20171 <column alignment="left" valignment="top" leftline="true" width="0">
20172 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
20173 <row topline="true" bottomline="true">
20174 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20177 \begin_layout Standard
20192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20195 \begin_layout Standard
20202 <row topline="true">
20203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20206 \begin_layout Standard
20221 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20224 \begin_layout Standard
20234 add floating point numbers
20240 <row topline="true">
20241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20244 \begin_layout Standard
20259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20262 \begin_layout Standard
20272 subtract floating point numbers
20278 <row topline="true">
20279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20282 \begin_layout Standard
20297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20300 \begin_layout Standard
20310 divide floating point numbers
20316 <row topline="true">
20317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20320 \begin_layout Standard
20335 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20338 \begin_layout Standard
20348 multiply floating point numbers
20354 <row topline="true">
20355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20358 \begin_layout Standard
20373 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20376 \begin_layout Standard
20386 convert floating point to unsigned char
20392 <row topline="true">
20393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20396 \begin_layout Standard
20411 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20414 \begin_layout Standard
20424 convert floating point to signed char
20430 <row topline="true">
20431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20434 \begin_layout Standard
20449 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20452 \begin_layout Standard
20462 convert floating point to unsigned int
20468 <row topline="true">
20469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20472 \begin_layout Standard
20487 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20490 \begin_layout Standard
20500 convert floating point to signed int
20506 <row topline="true">
20507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20510 \begin_layout Standard
20533 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20536 \begin_layout Standard
20546 convert floating point to unsigned long
20552 <row topline="true">
20553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20556 \begin_layout Standard
20571 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20574 \begin_layout Standard
20584 convert floating point to signed long
20590 <row topline="true">
20591 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20594 \begin_layout Standard
20609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20612 \begin_layout Standard
20622 convert unsigned char to floating point
20628 <row topline="true">
20629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20632 \begin_layout Standard
20647 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20650 \begin_layout Standard
20660 convert char to floating point number
20666 <row topline="true">
20667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20670 \begin_layout Standard
20685 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20688 \begin_layout Standard
20698 convert unsigned int to floating point
20704 <row topline="true">
20705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20708 \begin_layout Standard
20723 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20726 \begin_layout Standard
20736 convert int to floating point numbers
20742 <row topline="true">
20743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20746 \begin_layout Standard
20761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20764 \begin_layout Standard
20774 convert unsigned long to floating point number
20780 <row topline="true" bottomline="true">
20781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20784 \begin_layout Standard
20799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20802 \begin_layout Standard
20812 convert long to floating point number
20827 \begin_layout Standard
20828 These support routines are developed in ANSI-C so there is room for space
20829 and speed improvement
20833 \begin_layout Standard
20834 These floating point routines (
20838 sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
20845 Note if all these routines are used simultaneously the data space might
20847 For serious floating point usage the large model might be needed.
20848 Also notice that you don't have to call this routines directly.
20849 The compiler will use them automatically every time a floating point operation
20851 \begin_inset VSpace bigskip
20857 \begin_layout Section
20859 \begin_inset LatexCommand index
20867 \begin_layout Standard
20870 <pending: this is messy and incomplete - a little more information is in
20871 sdcc/doc/libdoc.txt
20876 \begin_layout Subsection
20877 Compiler support routines (_gptrget, _mulint etc.)
20880 \begin_layout Subsection
20881 Stdclib functions (puts, printf, strcat etc.)
20884 \begin_layout Subsubsection
20888 \begin_layout Paragraph
20889 getchar(), putchar()
20892 \begin_layout Standard
20893 \begin_inset LatexCommand index
20898 As usual on embedded systems you have to provide your own
20901 \begin_inset LatexCommand index
20911 \begin_inset LatexCommand index
20919 SDCC does not know whether the system connects to a serial line with or
20920 without handshake, LCD, keyboard or other device.
20934 You'll find examples for serial routines f.e.
20935 in sdcc/device/lib.
20936 For the mcs51 this minimalistic polling
20940 routine might be a start:
20943 \begin_layout Verse
20946 void putchar (char c) {
20952 while (!TI)\InsetSpace ~
20955 /* assumes UART is initialized */
20983 \begin_layout Paragraph
20987 \begin_layout Standard
20991 \begin_inset LatexCommand index
21002 does not support float (except on ds390).
21003 To enable this recompile it with the option
21009 \begin_layout Standard
21019 \begin_inset LatexCommand index
21020 name "USE\\_FLOATS"
21026 on the command line.
21033 \begin_layout Standard
21043 \begin_inset LatexCommand index
21044 name "-\\/-model-large"
21050 for the mcs51 port, since this uses a lot of memory.
21053 \begin_layout Standard
21054 If you're short on code memory you might want to use
21057 \begin_inset LatexCommand index
21058 name "printf\\_small()"
21073 For the mcs51 there additionally are assembly versions
21076 \begin_inset LatexCommand index
21077 name "printf\\_tiny() (mcs51)"
21083 (subset of printf using less than 270 bytes) and
21086 \begin_inset LatexCommand index
21087 name "printf\\_fast() (mcs51)"
21096 \begin_inset LatexCommand index
21097 name "printf\\_fast\\_f() (mcs51)"
21103 (floating-point aware version of printf_fast) which should fit the requirements
21104 of many embedded systems (printf_fast() can be customized by unsetting
21109 support long variables and field widths).
21110 Be sure to use only one of these printf options within a project.
21115 \begin_layout Standard
21116 Feature matrix of different
21123 \begin_layout Standard
21124 \begin_inset Tabular
21125 <lyxtabular version="3" rows="14" columns="7">
21126 <features islongtable="true">
21127 <column alignment="left" valignment="middle" leftline="true" width="14col%">
21128 <column alignment="center" valignment="top" leftline="true" width="0">
21129 <column alignment="center" valignment="top" leftline="true" width="12col%">
21130 <column alignment="center" valignment="top" leftline="true" width="10col%">
21131 <column alignment="center" valignment="top" leftline="true" width="0">
21132 <column alignment="center" valignment="top" leftline="true" rightline="true" width="12col%">
21133 <column alignment="center" valignment="top" rightline="true" width="0">
21134 <row topline="true" bottomline="true" endhead="true">
21135 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21138 \begin_layout Standard
21147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21150 \begin_layout Standard
21152 \begin_inset LatexCommand index
21162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21165 \begin_layout Standard
21173 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21176 \begin_layout Standard
21182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21185 \begin_layout Standard
21191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21194 \begin_layout Standard
21200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21203 \begin_layout Standard
21210 <row topline="true" endhead="true">
21211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21214 \begin_layout Standard
21220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21223 \begin_layout Standard
21231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21234 \begin_layout Standard
21242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21245 \begin_layout Standard
21253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21256 \begin_layout Standard
21264 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21267 \begin_layout Standard
21275 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21278 \begin_layout Standard
21287 <row topline="true" endhead="true">
21288 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21291 \begin_layout Standard
21292 \begin_inset Quotes sld
21296 \begin_inset Quotes srd
21302 \begin_layout Standard
21308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21311 \begin_layout Standard
21317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21320 \begin_layout Standard
21326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21329 \begin_layout Standard
21335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21338 \begin_layout Standard
21344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21347 \begin_layout Standard
21353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21356 \begin_layout Standard
21363 <row topline="true" endhead="true">
21364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21367 \begin_layout Standard
21371 \begin_layout Standard
21377 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21380 \begin_layout Standard
21386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21389 \begin_layout Standard
21395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21398 \begin_layout Standard
21399 0.45k / 0.47k (+ _ltoa)
21404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21407 \begin_layout Standard
21413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21416 \begin_layout Standard
21422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21425 \begin_layout Standard
21432 <row topline="true">
21433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21436 \begin_layout Standard
21442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21445 \begin_layout Standard
21455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21458 \begin_layout Standard
21505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21508 \begin_layout Standard
21547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21550 \begin_layout Standard
21556 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21559 \begin_layout Standard
21565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21568 \begin_layout Standard
21575 <row topline="true">
21576 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21579 \begin_layout Standard
21580 long (32 bit) support
21585 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21588 \begin_layout Standard
21594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21597 \begin_layout Standard
21603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21606 \begin_layout Standard
21612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21615 \begin_layout Standard
21621 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21624 \begin_layout Standard
21639 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21642 \begin_layout Standard
21649 <row topline="true">
21650 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21653 \begin_layout Standard
21654 byte arguments on stack
21659 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21662 \begin_layout Standard
21668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21671 \begin_layout Standard
21677 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21680 \begin_layout Standard
21686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21689 \begin_layout Standard
21695 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21698 \begin_layout Standard
21704 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21707 \begin_layout Standard
21714 <row topline="true">
21715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21718 \begin_layout Standard
21720 \begin_inset LatexCommand index
21721 name "Floating point support"
21730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21733 \begin_layout Standard
21739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21742 \begin_layout Standard
21748 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21751 \begin_layout Standard
21757 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21760 \begin_layout Standard
21766 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21769 \begin_layout Standard
21774 \begin_layout Standard
21775 Range limited to +/- 4294967040, precision limited to 8 digits past decimal
21785 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21788 \begin_layout Standard
21795 <row topline="true">
21796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21799 \begin_layout Standard
21800 float formats %e %g
21805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21808 \begin_layout Standard
21814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21817 \begin_layout Standard
21823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21826 \begin_layout Standard
21832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21835 \begin_layout Standard
21841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21844 \begin_layout Standard
21850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21853 \begin_layout Standard
21860 <row topline="true" bottomline="true">
21861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21864 \begin_layout Standard
21870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21873 \begin_layout Standard
21879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21882 \begin_layout Standard
21888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21891 \begin_layout Standard
21897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21900 \begin_layout Standard
21906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21909 \begin_layout Standard
21915 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21918 \begin_layout Standard
21925 <row bottomline="true">
21926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21929 \begin_layout Standard
21934 \begin_layout Standard
21935 Execution time of printf("%s%c%s%c%c%c", "Hello", ' ', "World", '!', '
21939 n'); standard 8051 @ 22.1184 MHz, empty putchar()
21947 \begin_layout Standard
21953 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21956 \begin_layout Standard
21962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21965 \begin_layout Standard
21971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21974 \begin_layout Standard
21980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21983 \begin_layout Standard
21989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21992 \begin_layout Standard
21998 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22001 \begin_layout Standard
22008 <row bottomline="true">
22009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22012 \begin_layout Standard
22017 \begin_layout Standard
22018 Execution time of printf("%d", -12345); standard 8051 @ 22.1184 MHz, empty
22027 \begin_layout Standard
22033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22036 \begin_layout Standard
22042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22045 \begin_layout Standard
22051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22054 \begin_layout Standard
22060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22063 \begin_layout Standard
22069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22072 \begin_layout Standard
22078 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22081 \begin_layout Standard
22086 \begin_layout Standard
22087 printf_tiny integer speed is data dependent, worst case is 0.33 ms
22098 <row bottomline="true">
22099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22102 \begin_layout Standard
22107 \begin_layout Standard
22108 Execution time of printf("%ld", -123456789); standard 8051 @ 22.1184 MHz,
22117 \begin_layout Standard
22123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22126 \begin_layout Standard
22132 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22135 \begin_layout Standard
22141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22144 \begin_layout Standard
22150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22153 \begin_layout Standard
22159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22162 \begin_layout Standard
22168 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22171 \begin_layout Standard
22178 <row bottomline="true">
22179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22182 \begin_layout Standard
22187 \begin_layout Standard
22188 Execution time of printf("%.3f", -12345.678); standard 8051 @ 22.1184 MHz,
22197 \begin_layout Standard
22203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22206 \begin_layout Standard
22212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22215 \begin_layout Standard
22221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22224 \begin_layout Standard
22230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22233 \begin_layout Standard
22239 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22242 \begin_layout Standard
22248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22251 \begin_layout Standard
22265 \begin_layout Subsubsection
22267 \begin_inset LatexCommand index
22275 \begin_layout Standard
22276 As of SDCC 2.6.2 you no longer need to call an initialization routine before
22277 using dynamic memory allocation
22278 \begin_inset LatexCommand index
22279 name "dynamic memory allocation (malloc)"
22284 \begin_inset LatexCommand index
22285 name "heap (malloc)"
22289 space of 1024 bytes is provided for malloc to allocate memory from.
22290 If you need a different heap size you need to recompile _heap.c with the
22291 required size defined in HEAP_SIZE.
22292 It is recommended to make a copy of this file into your project directory
22293 and compile it there with:
22296 \begin_layout Verse
22299 sdcc -c _heap.c -D HEAD_SIZE=2048
22302 \begin_layout Standard
22303 And then link it with:
22306 \begin_layout Verse
22309 sdcc main.rel _heap.rel
22312 \begin_layout Subsection
22313 Math functions (sinf, powf, sqrtf etc.)
22316 \begin_layout Subsubsection
22320 \begin_layout Standard
22321 See definitions in file <math.h>.
22324 \begin_layout Subsection
22328 \begin_layout Standard
22330 \begin_inset LatexCommand index
22335 included in SDCC should have a license at least as liberal as the GNU Lesser
22336 General Public License
22337 \begin_inset LatexCommand index
22338 name "GNU Lesser General Public License, LGPL"
22349 \begin_layout Standard
22350 \begin_inset Note Note
22353 \begin_layout Standard
22354 license statements for the libraries are missing.
22355 sdcc/device/lib/ser_ir.c
22358 \begin_layout Standard
22360 come with a GPL (as opposed to LGPL) License - this will not be liberal
22361 enough for many embedded programmers.
22369 \begin_layout Standard
22370 If you have ported some library or want to share experience about some code
22372 falls into any of these categories Busses (I
22373 \begin_inset Formula $^{\textrm{2}}$
22376 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
22377 cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
22378 Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
22379 \begin_inset LatexCommand url
22380 target "http://sourceforge.net/mail/?group_id=599"
22385 would certainly like to hear about it.
22388 \begin_layout Standard
22389 Programmers coding for embedded systems are not especially famous for being
22390 enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
22391 e these references are very valuable.
22392 Let's help to create a climate where information is shared.
22393 \begin_inset VSpace bigskip
22399 \begin_layout Section
22403 \begin_layout Subsection
22404 MCS51 Memory Models
22405 \begin_inset LatexCommand index
22406 name "Memory model"
22411 \begin_inset LatexCommand index
22412 name "MCS51 memory model"
22419 \begin_layout Subsubsection
22420 Small, Medium and Large
22423 \begin_layout Standard
22424 SDCC allows three memory models for MCS51 code,
22433 Modules compiled with different memory models should
22437 be combined together or the results would be unpredictable.
22438 The library routines supplied with the compiler are compiled as small,
22440 The compiled library modules are contained in separate directories as small,
22441 medium and large so that you can link to the appropriate set.
22444 \begin_layout Standard
22445 When the medium or large model is used all variables declared without a
22446 storage class will be allocated into the external ram, this includes all
22447 parameters and local variables (for non-reentrant
22448 \begin_inset LatexCommand index
22454 When the small model is used variables without storage class are allocated
22455 in the internal ram.
22458 \begin_layout Standard
22459 Judicious usage of the processor specific storage classes
22460 \begin_inset LatexCommand index
22461 name "Storage class"
22465 and the 'reentrant' function type will yield much more efficient code,
22466 than using the large model.
22467 Several optimizations are disabled when the program is compiled using the
22468 large model, it is therefore recommended that the small model be used unless
22469 absolutely required.
22472 \begin_layout Subsubsection
22474 \begin_inset LatexCommand label
22475 name "sub:External-Stack"
22480 \begin_inset LatexCommand index
22486 \begin_inset LatexCommand index
22487 name "External stack (mcs51)"
22494 \begin_layout Standard
22495 The external stack (-
22499 \begin_layout Standard
22509 \begin_inset LatexCommand index
22514 ) is located in pdata
22515 \begin_inset LatexCommand index
22516 name "pdata (mcs51, ds390 storage class)"
22520 memory (usually at the start of the external ram segment) and uses all
22521 unused space in pdata (max.
22527 \begin_layout Standard
22536 -xstack option is used to compile the program, the parameters and local
22538 \begin_inset LatexCommand index
22539 name "local variables"
22543 of all reentrant functions are allocated in this area.
22544 This option is provided for programs with large stack space requirements.
22545 When used with the -
22549 \begin_layout Standard
22559 \begin_inset LatexCommand index
22560 name "-\\/-stack-auto"
22564 option, all parameters and local variables are allocated on the external
22565 stack (note: support libraries will need to be recompiled with the same
22567 There is a predefined target in the library makefile).
22570 \begin_layout Standard
22571 The compiler outputs the higher order address byte of the external ram segment
22573 \begin_inset LatexCommand index
22574 name "P2 (mcs51 sfr)"
22579 \begin_inset LatexCommand ref
22580 reference "sub:MCS51-variants"
22584 ), therefore when using the External Stack option, this port
22588 be used by the application program.
22591 \begin_layout Subsection
22593 \begin_inset LatexCommand index
22594 name "Memory model"
22599 \begin_inset LatexCommand index
22600 name "DS390 memory model"
22607 \begin_layout Standard
22608 The only model supported is Flat 24
22609 \begin_inset LatexCommand index
22610 name "Flat 24 (DS390 memory model)"
22615 This generates code for the 24 bit contiguous addressing mode of the Dallas
22617 In this mode, up to four meg of external RAM or code space can be directly
22619 See the data sheets at www.dalsemi.com for further information on this part.
22624 that the compiler does not generate any code to place the processor into
22625 24 bitmode (although
22629 in the ds390 libraries will do that for you).
22635 \begin_inset LatexCommand index
22636 name "Tinibios (DS390)"
22640 , the boot loader or similar code must ensure that the processor is in 24
22641 bit contiguous addressing mode before calling the SDCC startup code.
22652 \begin_layout Standard
22663 option, variables will by default be placed into the XDATA segment.
22668 Segments may be placed anywhere in the 4 meg address space using the usual
22673 \begin_layout Standard
22683 Note that if any segments are located above 64K, the -r flag must be passed
22684 to the linker to generate the proper segment relocations, and the Intel
22685 HEX output format must be used.
22686 The -r flag can be passed to the linker by using the option
22690 on the SDCC command line.
22691 However, currently the linker can not handle code segments > 64k.
22694 \begin_layout Section
22696 \begin_inset LatexCommand label
22702 \begin_inset LatexCommand index
22710 \begin_layout Standard
22711 Pragmas are used to turn on and/or off certain compiler options.
22712 Some of them are closely related to corresponding command-line options
22714 \begin_inset LatexCommand vref
22715 reference "sec:Command-Line-Options"
22721 Pragmas should be placed before and/or after a function, placing pragmas
22722 inside a function body could have unpredictable results.
22727 following #pragma directives:
22730 \begin_layout Itemize
22736 \begin_inset LatexCommand index
22737 name "\\#pragma save"
22741 - this will save most current options to the save/restore stack.
22742 See #pragma\InsetSpace ~
22746 \begin_layout Itemize
22752 \begin_inset LatexCommand index
22753 name "\\#pragma restore"
22757 - will restore saved options from the last save.
22758 saves & restores can be nested.
22759 SDCC uses a save/restore stack: save pushes current options to the stack,
22760 restore pulls current options from the stack.
22761 See #pragma\InsetSpace ~
22767 \begin_layout Itemize
22773 \begin_inset LatexCommand index
22774 name "\\#pragma callee\\_saves"
22779 \begin_inset LatexCommand index
22780 name "function prologue"
22784 function1[,function2[,function3...]]
22785 \begin_inset LatexCommand label
22786 name "ite:callee_saves-function1[,function2[,function3...]]--"
22790 - The compiler by default uses a caller saves convention for register saving
22791 across function calls, however this can cause unnecessary register pushing
22793 \begin_inset LatexCommand index
22798 when calling small functions from larger functions.
22799 This option can be used to switch off the register saving convention for
22800 the function names specified.
22801 The compiler will not save registers when calling these functions, extra
22802 code need to be manually inserted at the entry and exit for these functions
22803 to save and restore the registers used by these functions, this can SUBSTANTIAL
22804 LY reduce code and improve run time performance of the generated code.
22805 In the future the compiler (with inter procedural analysis) may be able
22806 to determine the appropriate scheme to use for each function call.
22811 \begin_layout Standard
22820 -callee-saves command line option is used (see page
22821 \begin_inset LatexCommand vpageref
22822 reference "lyx:--callee-saves-function1[,function2][,function3]..."
22826 ), the function names specified in #pragma\InsetSpace ~
22828 \begin_inset LatexCommand index
22829 name "\\#pragma callee\\_saves"
22833 is appended to the list of functions specified in the command line.
22836 \begin_layout Itemize
22842 \begin_inset LatexCommand index
22843 name "\\#pragma exclude"
22847 none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
22848 of pairs of push/pop
22849 \begin_inset LatexCommand index
22859 \begin_inset LatexCommand index
22873 The directive should be placed immediately before the ISR function definition
22874 and it affects ALL ISR functions following it.
22875 To enable the normal register saving for ISR functions use #pragma\InsetSpace ~
22876 exclude\InsetSpace ~
22878 \begin_inset LatexCommand index
22879 name "\\#pragma exclude"
22884 See also the related keyword _naked
22885 \begin_inset LatexCommand index
22891 \begin_inset LatexCommand index
22899 \begin_layout Itemize
22905 \begin_inset LatexCommand index
22911 \begin_inset LatexCommand index
22912 name "\\#pragma less\\_pedantic"
22917 \begin_inset LatexCommand label
22918 name "ite:less_pedantic"
22922 - the compiler will not warn you anymore for obvious mistakes, you're on
22924 See also the command line option -
22928 \begin_layout Standard
22938 \begin_inset LatexCommand vpageref
22939 reference "lyx:--less-pedantic"
22946 More specifically, the following warnings will be disabled:
22948 comparison is always [true/false] due to limited range of data type
22952 overflow in implicit constant conversion
22954 (158); [the (in)famous]
22956 conditional flow changed by optimizer: so said EVELYN the modified DOG
22960 function '[function name]' must return value
22965 Furthermore, warnings of less importance (of PEDANTIC and INFO warning
22966 level) are disabled, too, namely:
22969 \begin_inset Note Note
22972 \begin_layout Standard
22973 dunno what comes here - this warning appears to be unused altogether
22982 [left/right] shifting more than size of object changed to zero
22990 integer overflow in expression
22994 unmatched #pragma save and #pragma restore
22998 comparison of 'signed char' with 'unsigned char' requires promotion to int
23002 ISO C90 does not support flexible array members
23006 extended stack by [number] bytes for compiler temp(s) :in function '[function\InsetSpace ~
23010 \begin_inset Note Note
23013 \begin_layout Standard
23014 appears to be always blank - what was supposed to be here?
23023 function '[function name]', # edges [number] , # nodes [number] , cyclomatic
23024 complexity [number]
23029 \begin_layout Itemize
23035 \begin_inset LatexCommand index
23036 name "\\#pragma disable\\_warning"
23040 - the compiler will not warn you anymore about warning number <nnnn>.
23043 \begin_layout Itemize
23049 \begin_inset LatexCommand index
23050 name "\\#pragma nogcse"
23054 - will stop global common subexpression elimination.
23057 \begin_layout Itemize
23063 \begin_inset LatexCommand index
23064 name "\\#pragma noinduction"
23068 - will stop loop induction optimizations.
23071 \begin_layout Itemize
23077 \begin_inset LatexCommand index
23078 name "\\#pragma noinvariant"
23082 - will not do loop invariant optimizations.
23083 For more details see Loop Invariants in section
23084 \begin_inset LatexCommand ref
23085 reference "sub:Loop-Optimizations"
23092 \begin_layout Itemize
23098 \begin_inset LatexCommand index
23099 name "\\#pragma noiv"
23103 - Do not generate interrupt
23104 \begin_inset LatexCommand index
23110 \begin_inset LatexCommand index
23111 name "interrupt vector table"
23115 entries for all ISR functions defined after the pragma.
23116 This is useful in cases where the interrupt vector table must be defined
23117 manually, or when there is a secondary, manually defined interrupt vector
23119 for the autovector feature of the Cypress EZ-USB FX2).
23120 More elegantly this can be achieved by omitting the optional interrupt
23121 number after the interrupt keyword, see section
23122 \begin_inset LatexCommand ref
23123 reference "sub:Interrupt-Service-Routines"
23131 \begin_layout Itemize
23137 \begin_inset LatexCommand index
23138 name "\\#pragma nojtbound"
23142 - will not generate code for boundary value checking, when switch statements
23143 are turned into jump-tables (dangerous).
23144 For more details see section
23145 \begin_inset LatexCommand ref
23146 reference "sub:'switch'-Statements"
23153 \begin_layout Itemize
23159 \begin_inset LatexCommand index
23160 name "\\#pragma noloopreverse"
23164 - Will not do loop reversal optimization
23167 \begin_layout Itemize
23173 \begin_inset LatexCommand index
23174 name "\\#pragma nooverlay"
23178 - the compiler will not overlay the parameters and local variables of a
23182 \begin_layout Itemize
23188 \begin_inset LatexCommand index
23189 name "\\#pragma stackauto"
23197 \begin_layout Standard
23207 \begin_inset LatexCommand index
23208 name "-\\/-stack-auto"
23213 \begin_inset LatexCommand ref
23214 reference "sec:Parameters-and-Local-Variables"
23218 Parameters and Local Variables.
23221 \begin_layout Itemize
23227 \begin_inset LatexCommand index
23228 name "\\#pragma opt\\_code\\_speed"
23232 - The compiler will optimize code generation towards fast code, possibly
23233 at the expense of code size.
23234 Currently this has little effect.
23237 \begin_layout Itemize
23243 \begin_inset LatexCommand index
23244 name "\\#pragma opt\\_code\\_size"
23248 - The compiler will optimize code generation towards compact code, possibly
23249 at the expense of code speed.
23250 Currently this has little effect.
23253 \begin_layout Itemize
23259 \begin_inset LatexCommand index
23260 name "\\#pragma opt\\_code\\_balanced"
23264 - The compiler will attempt to generate code that is both compact and fast,
23265 as long as meeting one goal is not a detriment to the other (this is the
23270 \begin_layout Itemize
23276 \begin_inset LatexCommand index
23277 name "\\#pragma std\\_sdcc89"
23281 - Generally follow the C89 standard, but allow SDCC features that conflict
23282 with the standard (default).
23285 \begin_layout Itemize
23291 \begin_inset LatexCommand index
23292 name "\\#pragma std\\_c89"
23296 - Follow the C89 standard and disable SDCC features that conflict with the
23300 \begin_layout Itemize
23306 \begin_inset LatexCommand index
23307 name "\\#pragma std\\_sdcc99"
23311 - Generally follow the C99 standard, but allow SDCC features that conflict
23312 with the standard (incomplete support).
23315 \begin_layout Itemize
23321 \begin_inset LatexCommand index
23322 name "\\#pragma std\\_c99"
23326 - Follow the C99 standard and disable SDCC features that conflict with the
23327 standard (incomplete support).
23330 \begin_layout Itemize
23336 \begin_inset LatexCommand index
23337 name "\\#pragma codeseg"
23341 - Use this name (max.
23342 8 characters) for the code segment.
23347 \begin_layout Standard
23359 \begin_layout Itemize
23365 \begin_inset LatexCommand index
23366 name "\\#pragma constseg"
23370 - Use this name (max.
23371 8 characters) for the const segment.
23376 \begin_layout Standard
23388 \begin_layout Standard
23389 The preprocessor SDCPP
23390 \begin_inset LatexCommand index
23391 name "sdcpp (preprocessor)"
23395 supports the following #pragma directives:
23398 \begin_layout Itemize
23401 pedantic_parse_number
23404 \begin_inset LatexCommand index
23410 \begin_inset LatexCommand index
23411 name "\\#pragma pedantic\\_parse\\_number"
23416 \begin_inset LatexCommand label
23417 name "ite:pedantic_parse_number"
23421 - Pedantic parse numbers so that situations like 0xfe-LO_B(3) are parsed
23422 properly and the macro LO_B(3) gets expanded.
23428 \begin_layout Standard
23437 -pedantic-parse-number command line option
23438 \begin_inset LatexCommand vpageref
23439 reference "lyx:-pedantic-parse-number"
23446 Below is an example on how to use this pragma.
23449 Note: this functionality is not in conformance with standard!
23452 \begin_layout Verse
23455 #pragma pedantic_parse_number +
23456 \begin_inset LatexCommand index
23457 name "\\#pragma pedantic\\_parse\\_number"
23465 #define LO_B(x) ((x) & 0xff)
23469 unsigned char foo(void)
23476 unsigned char c=0xfe-LO_B(3)
23491 \begin_layout Itemize
23497 \begin_inset LatexCommand index
23498 name "\\#pragma preproc\\_asm"
23502 (+ | -) - switch _asm _endasm block preprocessing on / off.
23504 You use this pragma to define multilines of assembly code.
23505 This will prevent the preprocessor from changing the formatting required
23507 Below is an example on how to use this pragma.
23510 \begin_layout Verse
23513 #pragma preproc_asm -
23514 \begin_inset LatexCommand index
23515 name "\\#pragma preproc\\_asm"
23521 #define MYDELAY _asm
23526 nop ;my assembly comment...
23540 #pragma preproc_asm
23571 \begin_layout Itemize
23577 \begin_inset LatexCommand index
23578 name "\\#pragma sdcc\\_hash"
23582 (+ | -) - Allow "naked" hash in macro definition, for example:
23586 #define DIR_LO(x) #(x & 0xff)
23591 Below is an example on how to use this pragma.
23594 \begin_layout Verse
23597 #pragma preproc_asm +
23599 #pragma sdcc_hash +
23600 \begin_inset LatexCommand index
23601 name "\\#pragma sdcc\\_hash"
23616 mov R6_B3, #(x & 0xff)
23623 mov R7_B3, #((x >> 8) & 0xff)
23647 \begin_layout Standard
23648 Some of the pragmas are intended to be used to turn-on or off certain optimizati
23649 ons which might cause the compiler to generate extra stack and/or data space
23650 to store compiler generated temporary variables.
23651 This usually happens in large functions.
23652 Pragma directives should be used as shown in the following example, they
23653 are used to control options and optimizations for a given function.
23657 \begin_layout Verse
23661 \begin_inset LatexCommand index
23662 name "\\#pragma save"
23673 /* save the current settings */
23676 \begin_inset LatexCommand index
23677 name "\\#pragma nogcse"
23686 /* turnoff global subexpression elimination */
23688 #pragma noinduction
23689 \begin_inset LatexCommand index
23690 name "\\#pragma noinduction"
23694 /* turn off induction optimizations */
23717 \begin_inset LatexCommand index
23718 name "\\#pragma restore"
23722 /* turn the optimizations back on */
23725 \begin_layout Standard
23726 The compiler will generate a warning message when extra space is allocated.
23727 It is strongly recommended that the save and restore pragmas be used when
23728 changing options for a function.
23737 \begin_layout Section
23738 Defines Created by the Compiler
23741 \begin_layout Standard
23742 The compiler creates the following #defines
23743 \begin_inset LatexCommand index
23749 \begin_inset LatexCommand index
23750 name "Defines created by the compiler"
23759 \begin_layout Standard
23760 \begin_inset Tabular
23761 <lyxtabular version="3" rows="15" columns="2">
23763 <column alignment="left" valignment="top" leftline="true" width="3in">
23764 <column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
23765 <row topline="true" bottomline="true">
23766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23769 \begin_layout Standard
23777 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23780 \begin_layout Standard
23789 <row topline="true">
23790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23793 \begin_layout Standard
23795 \begin_inset LatexCommand index
23805 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23808 \begin_layout Standard
23810 Since version 2.5.6 the version number as an int (ex.
23817 <row topline="true">
23818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23821 \begin_layout Standard
23823 \begin_inset LatexCommand index
23824 name "SDCC\\_mcs51"
23829 \begin_inset LatexCommand index
23830 name "SDCC\\_ds390"
23835 \begin_inset LatexCommand index
23845 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23848 \begin_layout Standard
23849 depending on the model used (e.g.: -mds390)
23855 <row topline="true">
23856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23859 \begin_layout Standard
23861 \begin_inset LatexCommand index
23867 \begin_inset LatexCommand index
23873 \begin_inset LatexCommand index
23879 \begin_inset LatexCommand index
23889 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23892 \begin_layout Standard
23893 depending on the model used (e.g.
23900 <row topline="true">
23901 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23904 \begin_layout Standard
23906 \begin_inset LatexCommand index
23907 name "SDCC\\_STACK\\_AUTO"
23916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23919 \begin_layout Standard
23926 \begin_layout Standard
23943 <row topline="true">
23944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23947 \begin_layout Standard
23949 \begin_inset LatexCommand index
23950 name "SDCC\\_MODEL\\_SMALL"
23959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23962 \begin_layout Standard
23969 \begin_layout Standard
23986 <row topline="true">
23987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23990 \begin_layout Standard
23992 \begin_inset LatexCommand index
23993 name "SDCC\\_MODEL\\_MEDIUM"
24002 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24005 \begin_layout Standard
24012 \begin_layout Standard
24029 <row topline="true">
24030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24033 \begin_layout Standard
24035 \begin_inset LatexCommand index
24036 name "SDCC\\_MODEL\\_LARGE"
24045 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24048 \begin_layout Standard
24055 \begin_layout Standard
24072 <row topline="true">
24073 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24076 \begin_layout Standard
24078 \begin_inset LatexCommand index
24079 name "SDCC\\_USE\\_XSTACK"
24088 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24091 \begin_layout Standard
24098 \begin_layout Standard
24115 <row topline="true">
24116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24119 \begin_layout Standard
24121 \begin_inset LatexCommand index
24122 name "SDCC\\_STACK\\_TENBIT"
24131 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24134 \begin_layout Standard
24145 <row topline="true">
24146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24149 \begin_layout Standard
24151 \begin_inset LatexCommand index
24152 name "SDCC\\_MODEL\\_FLAT24"
24161 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24164 \begin_layout Standard
24175 <row topline="true">
24176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24179 \begin_layout Standard
24181 \begin_inset LatexCommand index
24182 name "SDCC\\_REVISION"
24191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24194 \begin_layout Standard
24196 SDCC svn revision number
24202 <row topline="true">
24203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24206 \begin_layout Standard
24207 SDCC_PARMS_IN_BANK1
24208 \begin_inset LatexCommand index
24209 name "SDCC\\_PARMS\\_IN\\_BANK1"
24218 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24221 \begin_layout Standard
24228 \begin_layout Standard
24245 <row topline="true">
24246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24249 \begin_layout Standard
24251 \begin_inset LatexCommand index
24252 name "SDCC\\_MODEL\\_FLAT24"
24261 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24264 \begin_layout Standard
24271 \begin_layout Standard
24288 <row topline="true" bottomline="true">
24289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24292 \begin_layout Standard
24293 SDCC_INT_LONG_REENT
24294 \begin_inset LatexCommand index
24295 name "SDCC\\_INT\\_LONG\\_REENT"
24304 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24307 \begin_layout Standard
24314 \begin_layout Standard
24338 \begin_layout Chapter
24339 Notes on supported Processors
24342 \begin_layout Section
24344 \begin_inset LatexCommand label
24345 name "sub:MCS51-variants"
24350 \begin_inset LatexCommand index
24351 name "MCS51 variants"
24358 \begin_layout Standard
24359 MCS51 processors are available from many vendors and come in many different
24361 While they might differ considerably in respect to Special Function Registers
24362 the core MCS51 is usually not modified or is kept compatible.
24366 \begin_layout Subsection
24367 pdata access by SFR
24370 \begin_layout Standard
24371 With the upcome of devices with internal xdata and flash memory devices
24373 \begin_inset LatexCommand index
24374 name "P2 (mcs51 sfr)"
24378 as dedicated I/O port is becoming more popular.
24379 Switching the high byte for pdata
24380 \begin_inset LatexCommand index
24381 name "pdata (mcs51, ds390 storage class)"
24385 access which was formerly done by port P2 is then achieved by a Special
24387 \begin_inset LatexCommand index
24393 In well-established MCS51 tradition the address of this
24397 is where the chip designers decided to put it.
24398 Needless to say that they didn't agree on a common name either.
24399 So that the startup code can correctly initialize xdata variables, you
24400 should define an sfr with the name _XPAGE
24403 \begin_inset LatexCommand index
24404 name "\\_XPAGE (mcs51)"
24410 at the appropriate location if the default, port P2, is not used for this.
24414 \begin_layout Verse
24417 __sfr __at (0x85) _XPAGE; /* Ramtron VRS51 family a.k.a.
24421 \begin_layout Verse
24424 __sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family, Texas Instruments (Chipcon)
24429 \begin_layout Verse
24432 __sfr __at (0x91) _XPAGE; /* Infineon (Siemens) C500 family a.k.a.
24436 \begin_layout Verse
24439 __sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
24443 \begin_layout Verse
24446 __sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
24450 \begin_layout Standard
24451 For more exotic implementations further customizations may be needed.
24453 \begin_inset LatexCommand ref
24454 reference "sub:Startup-Code"
24458 for other possibilities.
24461 \begin_layout Subsection
24462 Other Features available by SFR
24465 \begin_layout Standard
24466 Some MCS51 variants offer features like Double DPTR
24467 \begin_inset LatexCommand index
24472 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
24473 These are currently not used for the MCS51 port.
24474 If you absolutely need them you can fall back to inline assembly or submit
24478 \begin_layout Subsection
24482 \begin_layout Standard
24484 \begin_inset LatexCommand index
24485 name "Bankswitching"
24491 \begin_inset LatexCommand index
24492 name "code banking"
24496 ) is a technique to increase the code space above the 64k limit of the 8051.
24499 \begin_layout Subsubsection
24503 \begin_layout Standard
24504 \begin_inset Tabular
24505 <lyxtabular version="3" rows="3" columns="4">
24507 <column alignment="center" valignment="top" width="0">
24508 <column alignment="center" valignment="top" leftline="true" width="0">
24509 <column alignment="center" valignment="top" leftline="true" width="0">
24510 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
24511 <row topline="true" bottomline="true">
24512 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
24515 \begin_layout Standard
24521 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24524 \begin_layout Standard
24530 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24533 \begin_layout Standard
24539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24542 \begin_layout Standard
24549 <row topline="true" bottomline="true">
24550 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
24553 \begin_layout Standard
24559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24562 \begin_layout Standard
24568 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
24571 \begin_layout Standard
24577 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24580 \begin_layout Standard
24588 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
24591 \begin_layout Standard
24592 SiLabs C8051F120 example
24597 <cell multicolumn="2" alignment="center" valignment="top" usebox="none">
24600 \begin_layout Standard
24606 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24609 \begin_layout Standard
24615 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24618 \begin_layout Standard
24633 Usually the hardware uses some sfr (an output port or an internal sfr) to
24634 select a bank and put it in the banked area of the memory map.
24635 The selected bank usually becomes active immediately upon assignment to
24636 this sfr and when running inside a bank it will switch out this code it
24637 is currently running.
24638 Therefor you cannot jump or call directly from one bank to another and
24639 need to use a so-called trampoline in the common area.
24640 For SDCC an example trampoline is in crtbank.asm and you may need to change
24641 it to your 8051 derivative or schematic.
24642 The presented code is written for the C8051F120.
24646 When calling a banked function
24647 SDCC will put the LSB of the functions address in register R0, the MSB
24648 in R1 and the bank in R2 and then call this trampoline
24653 The current selected bank is saved on the stack, the new bank is selected
24654 and an indirect jump is made.
24655 When the banked function returns it jumps to
24659 which restores the previous bank and returns to the caller.
24662 \begin_layout Subsubsection
24666 \begin_layout Standard
24667 When writing banked software using SDCC you need to use some special keywords
24669 You also need to take over a bit of work from the linker.
24673 To create a function
24674 that can be called from another bank it requires the keyword
24679 \begin_inset LatexCommand index
24685 The caller must see this in the prototype of the callee and the callee
24686 needs it for a proper return.
24687 Called functions within the same bank as the caller do not need the
24691 keyword nor do functions in the common area.
24692 Beware: SDCC does not know or check if functions are in the same bank.
24693 This is your responsibility!
24697 Normally all functions you write end up in
24699 If you want a function explicitly to reside in the common area put it in
24701 This applies for instance to interrupt service routines as they should
24705 \begin_layout Standard
24706 Functions that need to be in a switched bank must be put in a named segment.
24707 The name can be mostly anything up to eight characters (e.g.
24709 To do this you either use -
24713 \begin_layout Standard
24722 -codeseg BANK1 (See
24723 \begin_inset LatexCommand ref
24724 reference "lyx:-codeseg"
24728 ) on the command line when compiling or #pragma codeseg BANK1 (See
24729 \begin_inset LatexCommand ref
24730 reference "sec:Pragmas"
24734 ) at the top of the C source file.
24735 The segment name always applies to the whole source file and generated
24736 object so functions for different banks need to be defined in different
24741 When linking your objects you need to tell the linker where
24742 to put your segments.
24743 To do this you use the following command line option to SDCC: -Wl-b BANK1=0x180
24745 \begin_inset LatexCommand ref
24746 reference "lyx:-Wl option"
24751 This sets the virtual start address of this segment.
24752 It sets the banknumber to 0x01 and maps the bank to 0x8000 and up.
24753 The linker will not check for overflows, again this is your responsibility.
24756 \begin_layout Standard
24757 \begin_inset VSpace bigskip
24763 \begin_layout Section
24767 \begin_layout Standard
24769 \begin_inset LatexCommand index
24775 \begin_inset LatexCommand index
24780 microcontroller has a rich set of peripherals.
24781 In its built-in ROM library it includes functions to access some of the
24782 features, among them is a TCP stack with IP4 and IP6 support.
24783 Library headers (currently in beta status) and other files are provided
24787 \begin_inset LatexCommand url
24788 target "ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html"
24794 \begin_inset VSpace bigskip
24800 \begin_layout Section
24801 The Z80 and gbz80 port
24804 \begin_layout Standard
24805 SDCC can target both the Zilog Z80
24806 \begin_inset LatexCommand index
24811 and the Nintendo Gameboy's Z80-like gbz80
24812 \begin_inset LatexCommand index
24813 name "gbz80 (GameBoy Z80)"
24818 The Z80 port is passed through the same
24821 \begin_inset LatexCommand index
24822 name "Regression test"
24829 \begin_inset LatexCommand ref
24830 reference "sec:Quality-control"
24834 ) as the MCS51 and DS390 ports, so floating point support, support for long
24835 variables and bitfield support is fine.
24836 See mailing lists and forums about interrupt routines.
24839 \begin_layout Standard
24840 As always, the code is the authoritative reference - see z80/ralloc.c and
24843 \begin_inset LatexCommand index
24848 frame is similar to that generated by the IAR Z80 compiler.
24849 IX is used as the base pointer, HL and IY are used as a temporary registers,
24850 and BC and DE are available for holding variables.
24852 \begin_inset LatexCommand index
24853 name "Z80!return value"
24857 for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
24859 The gbz80 port use the same set of registers for the return values, but
24860 in a different order of significance: E (one byte), DE (two bytes), or
24862 \begin_inset VSpace bigskip
24868 \begin_layout Section
24872 \begin_layout Standard
24873 The port to the Freescale/Motorola HC08
24874 \begin_inset LatexCommand index
24879 family has been added in October 2003, and is still undergoing some basic
24881 The code generator is complete, but the register allocation is still quite
24883 Some of the SDCC's standard C library functions have embedded non-HC08
24884 inline assembly and so are not yet usable.
24887 \begin_layout Standard
24888 The HC08 port passes the regression test suite (see section
24889 \begin_inset LatexCommand ref
24890 reference "sec:Quality-control"
24895 \begin_inset VSpace bigskip
24901 \begin_layout Section
24903 \begin_inset LatexCommand index
24911 \begin_layout Standard
24912 The PIC14 port adds support for Microchip
24913 \begin_inset LatexCommand index
24919 \begin_inset Formula $^{\text{TM}}$
24923 \begin_inset LatexCommand index
24929 \begin_inset Formula $^{\text{TM}}$
24932 MCUs with 14 bit wide instructions.
24933 This port is not yet mature and still lacks many features.
24934 However, it can work for simple code.
24937 \begin_layout Standard
24939 Currently supported devices include:
24942 \begin_layout Standard
24943 12F: 629, 635, 675, 683
24946 \begin_layout Standard
24950 \begin_layout Standard
24954 \begin_layout Standard
24955 16C: 62, 620, 620a, 621, 621a, 622, 622a, 63a, 65b
24958 \begin_layout Standard
24959 16C: 71, 710, 711, 715, 717, 72, 73b, 745, 74b, 765, 770, 771, 773, 774,
24963 \begin_layout Standard
24967 \begin_layout Standard
24968 16CR: 620a, 73, 74, 76, 77
24971 \begin_layout Standard
24972 16F: 616, 627, 627a, 628, 628a, 630, 636, 639, 648, 648a, 676, 684, 685,
24976 \begin_layout Standard
24977 16F: 716, 72, 73, 737, 74, 747, 76, 767, 77, 777, 785
24980 \begin_layout Standard
24981 16F: 818, 819, 84, 84a, 87, 870, 871, 872, 873, 873a, 874, 874a, 876, 876a,
24982 877, 877a, 88, 886, 887
24985 \begin_layout Standard
24986 16F: 913, 914, 916, 917, 946
24989 \begin_layout Standard
24993 \begin_layout Standard
24995 An up-to-date list of currently supported devices can be obtained via
24997 sdcc -mpic14 -phelp foo.c
24999 (foo.c must exist...).
25002 \begin_layout Subsection
25004 \begin_inset LatexCommand index
25005 name "code page (pic14)"
25010 \begin_inset LatexCommand index
25011 name "Memory bank (pic14)"
25018 \begin_layout Standard
25019 The linker organizes allocation for the code page and RAM banks.
25020 It does not have intimate knowledge of the code flow.
25021 It will put all the code section of a single .asm file into a single code
25023 In order to make use of multiple code pages, separate asm files must be
25025 The compiler assigns all
25029 functions of a single .c file into the same code page.
25033 To get the best results,
25034 follow these guidelines:
25037 \begin_layout Enumerate
25038 Make local functions static, as non static functions require code page selection
25041 Due to the way sdcc handles functions, place called functions prior
25042 to calling functions in the file wherever possible: Otherwise sdcc will
25043 insert unnecessary pagesel directives around the call, believing that
25044 the called function is externally defined.
25047 \begin_layout Enumerate
25048 For devices that have multiple code pages it is more efficient to use the
25049 same number of files as pages: Use up to 4 separate .c files for the 16F877,
25050 but only 2 files for the 16F874.
25051 This way the linker can put the code for each file into different code
25052 pages and there will be less page selection overhead.
25055 \begin_layout Enumerate
25056 And as for any 8 bit micro (especially for PIC14 as they have a very simple
25057 instruction set), use `unsigned char' wherever possible instead of `int'.
25060 \begin_layout Subsection
25061 Adding New Devices to the Port
25064 \begin_layout Standard
25065 Adding support for a new 14
25069 \begin_layout Standard
25078 bit PIC MCU requires the following steps:
25081 \begin_layout Enumerate
25082 Create a new device description.
25084 Each device is described in two files: pic16f*.h
25086 These files primarily define SFRs, structs to access their bits, and symbolic
25087 configuration options.
25088 Both files can be generated from gputils' .inc files using the perl script
25091 support/scripts/inc2h.pl
25094 This file also contains further instructions on how to proceed.
25097 \begin_layout Enumerate
25098 Copy the .h file into SDCC's include path and either add the .c file to your
25099 project or copy it to
25101 device/lib/pic/libdev
25104 Afterwards, rebuild and install the libraries.
25107 \begin_layout Enumerate
25108 Edit pic14devices.txt in SDCC's include path (
25110 device/include/pic/
25112 in the source tree or
25114 /usr/local/share/sdcc/include/pic
25116 after installation).
25118 You need to add a device specification here to make
25119 the memory layout (code banks, RAM, aliased memory regions, ...) known to
25121 Probably you can copy and modify an existing entry.
25122 The file format is documented at the top of the file.
25125 \begin_layout Subsection
25129 \begin_layout Standard
25130 For the interrupt function, use the keyword `__interrupt'
25131 \begin_inset LatexCommand index
25132 name "PIC14!interrupt"
25136 with level number of 0 (PIC14 only has 1 interrupt so this number is only
25137 there to avoid a syntax error - it ought to be fixed).
25141 \begin_layout Verse
25144 void Intr(void) __interrupt 0
25150 T0IF = 0; /* Clear timer interrupt */
25155 \begin_layout Subsection
25156 Linking and Assembling
25159 \begin_layout Standard
25160 For assembling you can use either GPUTILS'
25161 \begin_inset LatexCommand index
25162 name "gputils (pic tools)"
25166 gpasm.exe or MPLAB's mpasmwin.exe.
25167 GPUTILS are available from
25168 \begin_inset LatexCommand url
25169 target "http://sourceforge.net/projects/gputils"
25174 For linking you can use either GPUTILS' gplink or MPLAB's mplink.exe.
25175 If you use MPLAB and an interrupt function then the linker script file
25176 vectors section will need to be enlarged to link with mplink.
25187 \begin_layout Verse
25200 sdcc -V -mpic14 -p16f877 -c $<
25204 $(PRJ).hex: $(OBJS)
25214 gplink -m -s $(PRJ).lkr
25215 -o $(PRJ).hex $(OBJS) libsdcc.lib
25218 \begin_layout Standard
25226 \begin_layout Verse
25239 sdcc -S -V -mpic14 -p16f877 $<
25249 mpasmwin /q /o $*.asm
25253 $(PRJ).hex: $(OBJS)
25264 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
25267 \begin_layout Standard
25268 Please note that indentations within a
25272 have to be done with a tabulator character.
25275 \begin_layout Subsection
25276 Command-Line Options
25279 \begin_layout Standard
25280 Besides the switches common to all SDCC backends, the PIC14 port accepts
25281 the following options (for an updated list see sdcc -
25285 \begin_layout Standard
25297 \begin_layout Description
25302 \begin_layout Standard
25312 \begin_inset LatexCommand index
25313 name "PIC14!Options!-\\/-debug-extra"
25317 emit debug info in assembly output
25320 \begin_layout Description
25325 \begin_layout Standard
25335 \begin_inset LatexCommand index
25336 name "PIC14!Options!-\\/-no-pcode-opt"
25340 disable (slightly faulty) optimization on pCode
25343 \begin_layout Description
25348 \begin_layout Standard
25358 \begin_inset LatexCommand index
25359 name "PIC14!Options!-\\/-stack-loc"
25363 sets the lowest address of the argument passing stack (defaults to a suitably
25364 large shared databank to reduce BANKSEL overhead)
25367 \begin_layout Description
25372 \begin_layout Standard
25382 \begin_inset LatexCommand index
25383 name "PIC14!Options!-\\/-stack-size"
25387 sets the size if the argument passing stack (default: 16, minimum: 4)
25390 \begin_layout Subsection
25391 Environment Variables
25394 \begin_layout Standard
25395 The PIC14 port recognizes the following environment variables:
25398 \begin_layout Description
25399 SDCC_PIC14_SPLIT_LOCALS If set and not empty, sdcc will allocate each temporary
25400 register (the ones called r0xNNNN) in a section of its own.
25401 By default (if this variable is unset), sdcc tries to cluster registers
25402 in sections in order to reduce the BANKSEL overhead when accessing them.
25405 \begin_layout Subsection
25409 \begin_layout Standard
25410 The PIC14 library currently only contains support routines required by the
25411 compiler to implement multiplication, division, and floating point support.
25412 No libc-like replacement is available at the moment, though many of the
25413 common sdcc library sources (in
25417 ) should also compile with the PIC14 port.
25420 \begin_layout Subsubsection
25421 error: missing definition for symbol ``__gptrget1''
25424 \begin_layout Standard
25425 The PIC14 port uses library routines to provide more complex operations
25426 like multiplication, division/modulus and (generic) pointer dereferencing.
25427 In order to add these routines to your project, you must link with PIC14's
25433 For single source file projects this is done automatically, more complex
25438 to the linker's arguments.
25439 Make sure you also add an include path for the library (using the -I switch
25443 \begin_layout Subsubsection
25444 Processor mismatch in file ``XXX''.
25447 \begin_layout Standard
25448 This warning can usually be ignored due to the very good compatibility amongst
25453 \begin_layout Standard
25463 \begin_inset LatexCommand index
25471 \begin_layout Standard
25472 You might also consider recompiling the library for your specific device
25473 by changing the ARCH=p16f877 (default target) entry in
25475 device/lib/pic/Makefile.in
25479 device/lib/pic/Makefile
25481 to reflect your device.
25482 This might even improve performance for smaller devices as unnecessary
25483 BANKSELs might be removed.
25486 \begin_layout Subsection
25490 \begin_layout Subsubsection
25494 \begin_layout Standard
25495 Functions with variable argument lists (like printf) are not yet supported.
25496 Similarly, taking the address of the first argument passed into a function
25497 does not work: It is currently passed in WREG and has no address...
25500 \begin_layout Subsubsection
25501 Regression tests fail
25504 \begin_layout Standard
25505 Though the small subset of regression tests in src/regression passes, SDCC
25506 regression test suite does not, indicating that there are still major bugs
25508 However, many smaller projects have successfully used SDCC in the past...
25511 \begin_layout Standard
25519 \begin_layout Section
25521 \begin_inset LatexCommand index
25529 \begin_layout Standard
25530 The PIC16 port adds support for Microchip
25531 \begin_inset LatexCommand index
25537 \begin_inset Formula $^{\text{TM}}$
25541 \begin_inset LatexCommand index
25547 \begin_inset Formula $^{\text{TM}}$
25550 MCUs with 16 bit wide instructions.
25551 Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx
25552 ; devices supported by the port include:
25555 \begin_layout Standard
25556 18F: 242, 248, 252, 258, 442, 448, 452, 458
25559 \begin_layout Standard
25563 \begin_layout Standard
25564 18F: 2220, 2221, 2320, 2321, 2331, 2410, 2420, 2423, 2431, 2450, 2455, 2480,
25568 \begin_layout Standard
25569 18F: (2510,) 2515, 2520, 2523, 2525, 2550, 2580, 2585, 25j10, 2610, 2620,
25573 \begin_layout Standard
25574 18F: 4220, 4221, 4320, 4321, 4331, 4410, 4420, 4423, 4431, 4450, 4455, 4480,
25578 \begin_layout Standard
25579 18F: 4510, 4515, 4520, 4523, 4525, 4550, 4580, 4585, 45j10, 4610, 4620,
25583 \begin_layout Standard
25584 18F: 6520, 6585, 6620, 6680, 66j60, 66j65, 6720, 67j60
25587 \begin_layout Standard
25588 18F: 8520, 8585, 8620, 8680, 86j60, 86j65, 8720, 87j60
25591 \begin_layout Standard
25592 18F: 96j60, 96j65, 97j60
25595 \begin_layout Standard
25597 An up-to-date list of supported devices is also available via '
25599 sdcc -mpic16 -plist
25604 \begin_layout Subsection
25608 \begin_layout Standard
25609 PIC16 port supports the standard command line arguments as supposed, with
25610 the exception of certain cases that will be mentioned in the following
25614 \begin_layout Description
25619 \begin_layout Standard
25629 \begin_inset LatexCommand index
25630 name "PIC16!Options!-\\/-callee-saves"
25638 \begin_layout Standard
25650 \begin_layout Description
25655 \begin_layout Standard
25664 -fommit-frame-pointer
25665 \begin_inset LatexCommand index
25666 name "PIC16!Options!-\\/-fommit-frame-pointer"
25670 Frame pointer will be omitted when the function uses no local variables.
25673 \begin_layout Subsection
25674 Port Specific Options
25675 \begin_inset LatexCommand index
25676 name "Options PIC16"
25683 \begin_layout Standard
25684 The port specific options appear after the global options in the sdcc -
25688 \begin_layout Standard
25700 \begin_layout Subsubsection
25701 Code Generation Options
25704 \begin_layout Standard
25705 These options influence the generated assembler code.
25708 \begin_layout Description
25713 \begin_layout Standard
25722 -pstack-model=[model] Used in conjunction with the command above.
25723 Defines the stack model to be used, valid stack models are:
25728 \labelwidthstring 00.00.0000
25733 Selects small stack model.
25734 8 bit stack and frame pointers.
25735 Supports 256 bytes stack size.
25739 \labelwidthstring 00.00.0000
25744 Selects large stack model.
25745 16 bit stack and frame pointers.
25746 Supports 65536 bytes stack size.
25750 \begin_layout Description
25755 \begin_layout Standard
25764 -pno-banksel Do not generate BANKSEL assembler directives.
25767 \begin_layout Description
25772 \begin_layout Standard
25781 -extended Enable extended instruction set/literal offset addressing mode.
25785 \begin_layout Subsubsection
25786 Optimization Options
25789 \begin_layout Description
25794 \begin_layout Standard
25803 -obanksel=n Set optimization level for inserting BANKSELs.
25810 \labelwidthstring 00.00.0000
25815 \labelwidthstring 00.00.0000
25816 1 checks previous used register and if it is the same then does not emit
25817 BANKSEL, accounts only for labels.
25821 \labelwidthstring 00.00.0000
25822 2 tries to check the location of (even different) symbols and removes BANKSELs
25823 if they are in the same bank.
25828 Important: There might be problems if the linker script has data sections
25829 across bank borders!
25833 \begin_layout Description
25838 \begin_layout Standard
25847 -denable-peeps Force the usage of peepholes.
25851 \begin_layout Description
25856 \begin_layout Standard
25865 -no-optimize-goto Do not use (conditional) BRA instead of GOTO.
25868 \begin_layout Description
25873 \begin_layout Standard
25882 -optimize-cmp Try to optimize some compares.
25885 \begin_layout Description
25890 \begin_layout Standard
25899 -optimize-df Analyze the dataflow of the generated code and improve it.
25902 \begin_layout Subsubsection
25906 \begin_layout Description
25911 \begin_layout Standard
25920 -asm= Sets the full path and name of an external assembler to call.
25923 \begin_layout Description
25928 \begin_layout Standard
25938 \begin_inset LatexCommand index
25943 compatibility option.
25944 Currently only suppresses special gpasm directives.
25947 \begin_layout Subsubsection
25951 \begin_layout Description
25956 \begin_layout Standard
25965 -link= Sets the full path and name of an external linker to call.
25968 \begin_layout Description
25973 \begin_layout Standard
25982 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
25983 unitialized data variables with [kword].
25984 Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
25987 \begin_layout Description
25992 \begin_layout Standard
26001 -ivt-loc=n Place the interrupt vector table at address
26006 Useful for bootloaders.
26009 \begin_layout Description
26014 \begin_layout Standard
26023 -nodefaultlibs Do not link default libraries when linking.
26026 \begin_layout Description
26031 \begin_layout Standard
26040 -use-crt= Use a custom run-time module instead of the defaults.
26043 \begin_layout Description
26048 \begin_layout Standard
26057 -no-crt Don't link the default run-time modules
26060 \begin_layout Subsubsection
26064 \begin_layout Standard
26065 Debugging options enable extra debugging information in the output files.
26068 \begin_layout Description
26073 \begin_layout Standard
26082 -debug-xtra Similar to -
26086 \begin_layout Standard
26096 \begin_inset LatexCommand index
26101 , but dumps more information.
26104 \begin_layout Description
26109 \begin_layout Standard
26118 -debug-ralloc Force register allocator to dump <source>.d file with debugging
26120 <source> is the name of the file being compiled.
26123 \begin_layout Description
26128 \begin_layout Standard
26137 -pcode-verbose Enable pcode debugging information in translation.
26140 \begin_layout Description
26145 \begin_layout Standard
26154 -calltree Dump call tree in .calltree file.
26157 \begin_layout Description
26162 \begin_layout Standard
26171 -gstack Trace push/pops for stack pointer overflow.
26174 \begin_layout Subsection
26175 Environment Variables
26178 \begin_layout Standard
26179 There is a number of environmental variables that can be used when running
26180 SDCC to enable certain optimizations or force a specific program behaviour.
26181 these variables are primarily for debugging purposes so they can be enabled/dis
26185 \begin_layout Standard
26186 Currently there is only two such variables available:
26189 \begin_layout Description
26190 OPTIMIZE_BITFIELD_POINTER_GET When this variable exists, reading of structure
26191 bitfields is optimized by directly loading FSR0 with the address of the
26192 bitfield structure.
26193 Normally SDCC will cast the bitfield structure to a bitfield pointer and
26195 This step saves data ram and code space for functions that make heavy use
26197 (i.e., 80 bytes of code space are saved when compiling malloc.c with this
26202 \begin_layout Description
26203 NO_REG_OPT Do not perform pCode registers optimization.
26204 This should be used for debugging purposes.
26205 If bugs in the pcode optimizer are found, users can benefit from temporarily
26206 disabling the optimizer until the bug is fixed.
26209 \begin_layout Subsection
26210 Preprocessor Macros
26213 \begin_layout Standard
26215 \begin_inset LatexCommand index
26220 port defines the following preprocessor macros while translating a source.
26223 \begin_layout Standard
26225 \begin_inset Tabular
26226 <lyxtabular version="3" rows="6" columns="2">
26228 <column alignment="center" valignment="top" leftline="true" width="0">
26229 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26230 <row topline="true" bottomline="true">
26231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26234 \begin_layout Standard
26240 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26243 \begin_layout Standard
26250 <row topline="true">
26251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26254 \begin_layout Standard
26260 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26263 \begin_layout Standard
26264 Port identification
26270 <row topline="true">
26271 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26274 \begin_layout Standard
26279 \begin_layout Standard
26293 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26296 \begin_layout Standard
26297 Port identification (same as above)
26303 <row topline="true">
26304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26307 \begin_layout Standard
26313 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26316 \begin_layout Standard
26317 MCU Identification.
26322 is the microcontrol identification number, i.e.
26329 <row topline="true">
26330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26333 \begin_layout Standard
26338 \begin_layout Standard
26352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26355 \begin_layout Standard
26356 MCU Identification (same as above)
26362 <row topline="true" bottomline="true">
26363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26366 \begin_layout Standard
26372 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26375 \begin_layout Standard
26376 nnn = SMALL or LARGE respectively according to the stack model used
26389 \begin_layout Standard
26391 In addition the following macros are defined when calling assembler:
26394 \begin_layout Standard
26396 \begin_inset Tabular
26397 <lyxtabular version="3" rows="4" columns="2">
26399 <column alignment="center" valignment="top" leftline="true" width="0">
26400 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26401 <row topline="true" bottomline="true">
26402 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26405 \begin_layout Standard
26411 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26414 \begin_layout Standard
26421 <row topline="true">
26422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26425 \begin_layout Standard
26431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26434 \begin_layout Standard
26435 MCU Identification.
26440 is the microcontrol identification number, i.e.
26447 <row topline="true">
26448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26451 \begin_layout Standard
26457 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26460 \begin_layout Standard
26461 nnn = SMALL or LARGE respectively according to the memory model used for
26468 <row topline="true" bottomline="true">
26469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26472 \begin_layout Standard
26478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26481 \begin_layout Standard
26482 nnn = SMALL or LARGE respectively according to the stack model used
26495 \begin_layout Subsection
26499 \begin_layout Standard
26501 \begin_inset LatexCommand index
26506 port uses the following directories for searching header files and libraries.
26509 \begin_layout Standard
26511 \begin_inset Tabular
26512 <lyxtabular version="3" rows="3" columns="4">
26514 <column alignment="center" valignment="top" leftline="true" width="0">
26515 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26516 <column alignment="center" valignment="top" width="0">
26517 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26518 <row topline="true" bottomline="true">
26519 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26522 \begin_layout Standard
26528 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26531 \begin_layout Standard
26537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26540 \begin_layout Standard
26546 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26549 \begin_layout Standard
26556 <row topline="true">
26557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26560 \begin_layout Standard
26561 PREFIX/sdcc/include/pic16
26566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26569 \begin_layout Standard
26570 PIC16 specific headers
26575 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26578 \begin_layout Standard
26584 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26587 \begin_layout Standard
26594 <row topline="true" bottomline="true">
26595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26598 \begin_layout Standard
26599 PREFIX/sdcc/lib/pic16
26604 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26607 \begin_layout Standard
26608 PIC16 specific libraries
26613 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26616 \begin_layout Standard
26622 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26625 \begin_layout Standard
26639 \begin_layout Subsection
26641 \begin_inset LatexCommand label
26642 name "sub:PIC16_Pragmas"
26649 \begin_layout Standard
26651 \begin_inset LatexCommand index
26656 port currently supports the following pragmas:
26659 \begin_layout Description
26661 \begin_inset LatexCommand index
26662 name "PIC16!Pragmas!\\#pragma stack"
26666 This forces the code generator to initialize the stack & frame pointers
26667 at a specific address.
26668 This is an ad hoc solution for cases where no STACK directive is available
26669 in the linker script or gplink is not instructed to create a stack section.
26672 stack pragma should be used only once in a project.
26673 Multiple pragmas may result in indeterminate behaviour of the program.
26677 \begin_layout Standard
26678 The old format (ie.
26679 #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
26680 cross page boundaries (or even exceed the available data RAM) and crash
26682 Make sure that stack does not cross page boundaries when using the SMALL
26690 The format is as follows:
26695 \begin_layout LyX-Code
26696 #pragma stack bottom_address [stack_size]
26701 \begin_layout Standard
26706 is the lower bound of the stack section.
26707 The stack pointer initially will point at address (bottom_address+stack_size-1).
26710 \begin_layout LyX-Code
26714 \begin_layout LyX-Code
26718 \begin_layout LyX-Code
26719 /* initializes stack of 100 bytes at RAM address 0x200 */
26722 \begin_layout LyX-Code
26723 #pragma stack 0x200 100
26726 \begin_layout Standard
26727 If the stack_size field is omitted then a stack is created with the default
26729 This size might be enough for most programs, but its not enough for operations
26730 with deep function nesting or excessive stack usage.
26733 \begin_layout Description
26735 \begin_inset LatexCommand index
26736 name "PIC16!Pragmas!\\#pragma code"
26740 Force a function to a static FLASH address.
26743 \begin_layout LyX-Code
26747 \begin_layout LyX-Code
26751 \begin_layout LyX-Code
26752 /* place function test_func at 0x4000 */
26755 \begin_layout LyX-Code
26756 #pragma code test_func 0x4000
26759 \begin_layout LyX-Code
26763 \begin_layout Description
26764 library instructs the linker to use a library module.
26769 \begin_layout LyX-Code
26770 #pragma library module_name
26773 \begin_layout Standard
26778 can be any library or object file (including its path).
26779 Note that there are four reserved keywords which have special meaning.
26783 \begin_layout Standard
26785 \begin_inset Tabular
26786 <lyxtabular version="3" rows="6" columns="3">
26788 <column alignment="center" valignment="top" leftline="true" width="0">
26789 <column alignment="block" valignment="top" leftline="true" width="20page%">
26790 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
26791 <row topline="true" bottomline="true">
26792 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26795 \begin_layout Standard
26801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26804 \begin_layout Standard
26810 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26813 \begin_layout Standard
26820 <row topline="true">
26821 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26824 \begin_layout Standard
26832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26835 \begin_layout Standard
26836 ignore all library pragmas
26841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26844 \begin_layout Standard
26853 <row topline="true">
26854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26857 \begin_layout Standard
26865 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26868 \begin_layout Standard
26874 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26877 \begin_layout Standard
26888 <row topline="true">
26889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26892 \begin_layout Standard
26900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26903 \begin_layout Standard
26904 link the Math libarary
26909 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26912 \begin_layout Standard
26923 <row topline="true">
26924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26927 \begin_layout Standard
26935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26938 \begin_layout Standard
26939 link the I/O library
26944 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26947 \begin_layout Standard
26958 <row topline="true" bottomline="true">
26959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26962 \begin_layout Standard
26970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26973 \begin_layout Standard
26974 link the debug library
26979 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26982 \begin_layout Standard
26999 * is the device number, i.e.
27000 452 for PIC18F452 MCU.
27003 \begin_layout Standard
27005 This feature allows for linking with specific libraries without having to
27006 explicit name them in the command line.
27011 keyword will reject all modules specified by the library pragma.
27014 \begin_layout Description
27015 udata The pragma udata instructs the compiler to emit code so that linker
27016 will place a variable at a specific memory bank.
27019 \begin_layout LyX-Code
27023 \begin_layout LyX-Code
27027 \begin_layout LyX-Code
27028 /* places variable foo at bank2 */
27031 \begin_layout LyX-Code
27032 #pragma udata bank2 foo
27035 \begin_layout LyX-Code
27039 \begin_layout Standard
27040 In order for this pragma to work extra SECTION directives should be added
27041 in the .lkr script.
27042 In the following example a sample .lkr file is shown:
27045 \begin_layout LyX-Code
27049 \begin_layout LyX-Code
27050 // Sample linker script for the PIC18F452 processor
27053 \begin_layout LyX-Code
27057 \begin_layout LyX-Code
27058 CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED
27061 \begin_layout LyX-Code
27062 CODEPAGE NAME=page START=0x2A END=0x7FFF
27065 \begin_layout LyX-Code
27066 CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED
27069 \begin_layout LyX-Code
27070 CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED
27073 \begin_layout LyX-Code
27074 CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED
27077 \begin_layout LyX-Code
27078 CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED
27081 \begin_layout LyX-Code
27082 ACCESSBANK NAME=accessram START=0x0 END=0x7F
27085 \begin_layout LyX-Code
27089 \begin_layout LyX-Code
27090 DATABANK NAME=gpr0 START=0x80 END=0xFF
27093 \begin_layout LyX-Code
27094 DATABANK NAME=gpr1 START=0x100 END=0x1FF
27097 \begin_layout LyX-Code
27098 DATABANK NAME=gpr2 START=0x200 END=0x2FF
27101 \begin_layout LyX-Code
27102 DATABANK NAME=gpr3 START=0x300 END=0x3FF
27105 \begin_layout LyX-Code
27106 DATABANK NAME=gpr4 START=0x400 END=0x4FF
27109 \begin_layout LyX-Code
27110 DATABANK NAME=gpr5 START=0x500 END=0x5FF
27113 \begin_layout LyX-Code
27114 ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED
27117 \begin_layout LyX-Code
27121 \begin_layout LyX-Code
27122 SECTION NAME=CONFIG ROM=config
27125 \begin_layout LyX-Code
27129 \begin_layout LyX-Code
27130 SECTION NAME=bank0 RAM=gpr0 # these SECTION directives
27133 \begin_layout LyX-Code
27134 SECTION NAME=bank1 RAM=gpr1 # should be added to link
27137 \begin_layout LyX-Code
27138 SECTION NAME=bank2 RAM=gpr2 # section name 'bank?' with
27141 \begin_layout LyX-Code
27142 SECTION NAME=bank3 RAM=gpr3 # a specific DATABANK name
27145 \begin_layout LyX-Code
27146 SECTION NAME=bank4 RAM=gpr4
27149 \begin_layout LyX-Code
27150 SECTION NAME=bank5 RAM=gpr5
27153 \begin_layout Standard
27154 The linker will recognise the section name set in the pragma statement and
27155 will position the variable at the memory bank set with the RAM field at
27156 the SECTION line in the linker script file.
27159 \begin_layout Subsection
27161 \begin_inset LatexCommand label
27162 name "sub:PIC16_Header-Files"
27169 \begin_layout Standard
27170 There is one main header file
27171 \begin_inset LatexCommand index
27172 name "PIC16!Header files"
27176 that can be included to the source files using the pic16
27177 \begin_inset LatexCommand index
27188 This header file contains the definitions for the processor special registers,
27189 so it is necessary if the source accesses them.
27190 It can be included by adding the following line in the beginning of the
27194 \begin_layout LyX-Code
27195 #include <pic18fregs.h>
27198 \begin_layout Standard
27199 The specific microcontroller is selected within the pic18fregs.h automatically,
27200 so the same source can be used with a variety of devices.
27203 \begin_layout Subsection
27205 \begin_inset LatexCommand label
27206 name "sub:pic16Libraries"
27213 \begin_layout Standard
27215 \begin_inset LatexCommand index
27216 name "PIC16!Libraries"
27221 \begin_inset LatexCommand index
27226 port depends on are the microcontroller device libraries which contain
27227 the symbol definitions for the microcontroller special function registers.
27228 These libraries have the format pic18fxxxx.lib, where
27232 is the microcontroller identification number.
27233 The specific library is selected automatically by the compiler at link
27234 stage according to the selected device.
27237 \begin_layout Standard
27239 Libraries are created with gplib which is part of the gputils package
27240 \begin_inset LatexCommand url
27241 target "http://sourceforge.net/projects/gputils"
27248 \begin_layout Subsubsection*
27249 Building the libraries
27252 \begin_layout Standard
27253 Before using SDCC/pic16 there are some libraries that need to be compiled.
27254 This process is done automatically if gputils are found at SDCC's compile
27256 Should you require to rebuild the pic16 libraries manually, these are the
27257 steps required to do so under Linux or Mac OS X (cygwin might work as well,
27261 \begin_layout LyX-Code
27262 cd device/lib/pic16
27265 \begin_layout LyX-Code
27269 \begin_layout LyX-Code
27273 \begin_layout LyX-Code
27277 \begin_layout LyX-Code
27278 su -c 'make install' # install the libraries, you need the root password
27281 \begin_layout LyX-Code
27285 \begin_layout Standard
27286 If you need to install the headers too, do:
27289 \begin_layout LyX-Code
27293 \begin_layout LyX-Code
27294 su -c 'make install' # install the headers, you need the root password
27297 \begin_layout Subsection
27298 Adding New Devices to the Port
27301 \begin_layout Standard
27302 Adding support for a new 16
27306 \begin_layout Standard
27315 bit PIC MCU requires the following steps:
27318 \begin_layout Enumerate
27319 Create picDEVICE.c and picDEVICE.h from pDEVICE.inc using
27323 perl /path/to/sdcc/support/scripts/inc2h-pic16.pl /path/to/gputils/header/pDEVICE.
27327 \begin_layout Enumerate
27330 mv picDEVICE.h /path/to/sdcc/device/include/pic16
27333 \begin_layout Enumerate
27336 mv picDEVICE.c /path/to/sdcc/device/lib/pic16/libdev
27339 \begin_layout Enumerate
27342 /path/to/sdcc/device/lib/pic16/pics.all
27346 Note: No 18f prefix here!
27349 \begin_layout Enumerate
27352 /path/to/sdcc/device/include/pic16/adc.h
27356 Add the new devices to the correct ADC style class (depending on the number
27363 if the device does not offer any ADC at all.
27366 \begin_layout Enumerate
27369 /path/to/sdcc/device/include/pic16/pic18fregs.h
27373 The file format is self-explanatory, just add
27377 #elif defined(picDEVICE)
27383 \begin_layout Standard
27394 include <picDEVICE.h>
27398 at the right place (keep the file sorted, please).
27401 \begin_layout Enumerate
27404 /path/to/sdcc/device/include/pic16devices.txt
27408 Copy and modify an existing entry or create a new one and insert it at the
27409 correct place (keep the file sorted, please).
27412 \begin_layout Enumerate
27415 /path/to/sdcc/device/lib/pic16/libdev/Makefile.am
27419 Copy an existing entry and adjust the device name.
27422 \begin_layout Enumerate
27425 /path/to/sdcc/device/lib/pic16/libio/Makefile.am
27429 Copy the record from the 18f2220 and adjust the device name.
27432 does not offer ADC, I
27433 \begin_inset Formula $^{\text{2}}$
27436 C, and/or (E)USART functionality as assumed by the library, remove the lines
27452 \begin_layout Enumerate
27471 /path/to/sdcc/device/lib/pic16
27476 \begin_layout Enumerate
27477 Recompile the pic16 libraries as described in
27478 \begin_inset LatexCommand ref
27479 reference "sub:pic16Libraries"
27486 \begin_layout Subsection
27490 \begin_layout Standard
27491 The following memory models are supported by the PIC16 port:
27494 \begin_layout Itemize
27498 \begin_layout Itemize
27502 \begin_layout Standard
27503 Memory model affects the default size of pointers within the source.
27504 The sizes are shown in the next table:
27507 \begin_layout Standard
27509 \begin_inset Tabular
27510 <lyxtabular version="3" rows="3" columns="3">
27512 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27513 <column alignment="center" valignment="top" leftline="true" width="0">
27514 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27515 <row topline="true" bottomline="true">
27516 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27519 \begin_layout Standard
27520 Pointer sizes according to memory model
27525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27528 \begin_layout Standard
27534 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27537 \begin_layout Standard
27544 <row topline="true" bottomline="true">
27545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27548 \begin_layout Standard
27554 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27557 \begin_layout Standard
27563 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27566 \begin_layout Standard
27573 <row topline="true" bottomline="true">
27574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27577 \begin_layout Standard
27583 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
27586 \begin_layout Standard
27592 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27595 \begin_layout Standard
27609 \begin_layout Standard
27610 It is advisable that all sources within a project are compiled with the
27612 If one wants to override the default memory model, this can be done by
27613 declaring a pointer as
27622 Far selects large memory model's pointers, while near selects small memory
27626 \begin_layout Standard
27627 The standard device libraries (see
27628 \begin_inset LatexCommand ref
27629 reference "sub:PIC16_Header-Files"
27633 ) contain no reference to pointers, so they can be used with both memory
27637 \begin_layout Subsection
27641 \begin_layout Standard
27643 \begin_inset LatexCommand index
27648 implementation for the PIC16 port uses two indirect registers, FSR1 and
27652 \begin_layout Description
27653 FSR1 is assigned as stack pointer
27656 \begin_layout Description
27657 FSR2 is assigned as frame pointer
27660 \begin_layout Standard
27661 The following stack models are supported by the PIC16 port
27664 \begin_layout Itemize
27672 \begin_layout Itemize
27680 \begin_layout Standard
27685 model means that only the FSRxL byte is used to access stack and frame,
27692 uses both FSRxL and FSRxH registers.
27693 The following table shows the stack/frame pointers sizes according to stack
27694 model and the maximum space they can address:
27697 \begin_layout Standard
27699 \begin_inset Tabular
27700 <lyxtabular version="3" rows="3" columns="3">
27702 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27703 <column alignment="center" valignment="top" leftline="true" width="0">
27704 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27705 <row topline="true" bottomline="true">
27706 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27709 \begin_layout Standard
27710 Stack & Frame pointer sizes according to stack model
27715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27718 \begin_layout Standard
27724 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27727 \begin_layout Standard
27734 <row topline="true">
27735 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27738 \begin_layout Standard
27744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27747 \begin_layout Standard
27753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27756 \begin_layout Standard
27763 <row topline="true" bottomline="true">
27764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27767 \begin_layout Standard
27773 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27776 \begin_layout Standard
27782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27785 \begin_layout Standard
27799 \begin_layout Standard
27805 stack model is currently not working properly throughout the code generator.
27806 So its use is not advised.
27807 Also there are some other points that need special care:
27812 \begin_layout Enumerate
27813 Do not create stack sections with size more than one physical bank (that
27817 \begin_layout Enumerate
27818 Stack sections should no cross physical bank limits (i.e.
27819 #pragma stack 0x50 0x100)
27822 \begin_layout Standard
27823 These limitations are caused by the fact that only FSRxL is modified when
27824 using SMALL stack model, so no more than 256 bytes of stack can be used.
27825 This problem will disappear after LARGE model is fully implemented.
27828 \begin_layout Subsection
27832 \begin_layout Standard
27833 In addition to the standard SDCC function keywords, PIC16
27834 \begin_inset LatexCommand index
27839 port makes available two more:
27842 \begin_layout Description
27844 \begin_inset LatexCommand index
27845 name "PIC16!wparam"
27849 Use the WREG to pass one byte of the first function argument.
27850 This improves speed but you may not use this for functions with arguments
27851 that are called via function pointers, otherwise the first byte of the
27852 first parameter will get lost.
27856 \begin_layout LyX-Code
27857 void func_wparam(int a) wparam
27860 \begin_layout LyX-Code
27864 \begin_layout LyX-Code
27865 /* WREG hold the lower part of a */
27868 \begin_layout LyX-Code
27869 /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
27873 \begin_layout LyX-Code
27877 \begin_layout LyX-Code
27881 \begin_layout Description
27883 \begin_inset LatexCommand index
27884 name "PIC16!shadowregs"
27888 When entering/exiting an ISR, it is possible to take advantage of the PIC18F
27889 hardware shadow registers which hold the values of WREG, STATUS and BSR
27891 This can be done by adding the keyword
27899 keyword in the function's header.
27902 \begin_layout LyX-Code
27903 void isr_shadow(void) shadowregs interrupt 1
27906 \begin_layout LyX-Code
27910 \begin_layout LyX-Code
27914 \begin_layout LyX-Code
27918 \begin_layout Standard
27923 instructs the code generator not to store/restore WREG, STATUS, BSR when
27924 entering/exiting the ISR.
27927 \begin_layout Subsection
27928 Function return values
27931 \begin_layout Standard
27932 Return values from functions are placed to the appropriate registers following
27933 a modified Microchip policy optimized for SDCC.
27934 The following table shows these registers:
27937 \begin_layout Standard
27939 \begin_inset Tabular
27940 <lyxtabular version="3" rows="6" columns="2">
27942 <column alignment="center" valignment="top" leftline="true" width="0">
27943 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27944 <row topline="true" bottomline="true">
27945 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27948 \begin_layout Standard
27954 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27957 \begin_layout Standard
27958 destination register
27964 <row topline="true">
27965 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27968 \begin_layout Standard
27974 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27977 \begin_layout Standard
27984 <row topline="true">
27985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27988 \begin_layout Standard
27994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27997 \begin_layout Standard
28004 <row topline="true">
28005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28008 \begin_layout Standard
28014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28017 \begin_layout Standard
28024 <row topline="true">
28025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28028 \begin_layout Standard
28034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28037 \begin_layout Standard
28038 FSR0L:PRODH:PRODL:WREG
28044 <row topline="true" bottomline="true">
28045 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28048 \begin_layout Standard
28054 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28057 \begin_layout Standard
28058 on stack, FSR0 points to the beginning
28071 \begin_layout Subsection
28075 \begin_layout Standard
28077 \begin_inset LatexCommand index
28078 name "PIC16!interrupt"
28082 service routine (ISR) is declared using the
28089 \begin_layout LyX-Code
28090 void isr(void) interrupt
28095 \begin_layout LyX-Code
28099 \begin_layout LyX-Code
28103 \begin_layout LyX-Code
28107 \begin_layout Standard
28112 is the interrupt number, which for PIC18F devices can be:
28115 \begin_layout Standard
28117 \begin_inset Tabular
28118 <lyxtabular version="3" rows="4" columns="3">
28120 <column alignment="center" valignment="top" leftline="true" width="0">
28121 <column alignment="center" valignment="top" leftline="true" width="0">
28122 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28123 <row topline="true" bottomline="true">
28124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28127 \begin_layout Standard
28135 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28138 \begin_layout Standard
28144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28147 \begin_layout Standard
28148 Interrupt Vector Address
28154 <row topline="true">
28155 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28158 \begin_layout Standard
28164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28167 \begin_layout Standard
28173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28176 \begin_layout Standard
28183 <row topline="true">
28184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28187 \begin_layout Standard
28202 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28205 \begin_layout Standard
28215 HIGH priority interrupts
28220 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28223 \begin_layout Standard
28230 <row topline="true" bottomline="true">
28231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28234 \begin_layout Standard
28240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28243 \begin_layout Standard
28244 LOW priority interrupts
28249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28252 \begin_layout Standard
28266 \begin_layout Standard
28267 When generating assembly code for ISR the code generator places a
28273 Interrupt Vector Address
28275 which points at the generated ISR.
28276 This single GOTO instruction is part of an automatically generated
28278 interrupt entry point
28281 The actuall ISR code is placed as normally would in the code space.
28282 Upon interrupt request, the GOTO instruction is executed which jumps to
28284 When declaring interrupt functions as _naked this GOTO instruction is
28289 The whole interrupt functions is therefore placed at the Interrupt Vector
28290 Address of the specific interrupt.
28291 This is not a problem for the LOW priority interrupts, but it is a problem
28292 for the RESET and the HIGH priority interrupts because code may be written
28293 at the next interrupt's vector address and cause indeterminate program
28294 behaviour if that interrupt is raised.
28298 \begin_layout Standard
28299 This is not a problem when
28302 \begin_layout Enumerate
28303 this is a HIGH interrupt ISR and LOW interrupts are
28310 \begin_layout Enumerate
28311 when the ISR is small enough not to reach the next interrupt's vector address.
28319 \begin_layout Standard
28325 This way a function is generated similar to an ISR, but it is not assigned
28329 \begin_layout Standard
28330 When entering an interrupt, currently the PIC16
28331 \begin_inset LatexCommand index
28336 port automatically saves the following registers:
28339 \begin_layout Itemize
28343 \begin_layout Itemize
28347 \begin_layout Itemize
28351 \begin_layout Itemize
28352 PROD (PRODL and PRODH)
28355 \begin_layout Itemize
28356 FSR0 (FSR0L and FSR0H)
28359 \begin_layout Standard
28360 These registers are restored upon return from the interrupt routine.
28364 \begin_layout Standard
28365 NOTE that when the _naked attribute is specified for an interrupt routine,
28366 then NO registers are stored or restored.
28374 \begin_layout Subsection
28378 \begin_layout Standard
28379 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
28380 There are 3 types of generic pointers currently implemented data, code
28381 and eeprom pointers.
28382 They are differentiated by the value of the 7th and 6th bits of the upper
28386 \begin_layout Standard
28388 \begin_inset Tabular
28389 <lyxtabular version="3" rows="5" columns="5">
28391 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28392 <column alignment="center" valignment="top" width="0">
28393 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28394 <column alignment="center" valignment="top" width="0">
28395 <column alignment="left" valignment="top" rightline="true" width="0">
28396 <row topline="true" bottomline="true">
28397 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28400 \begin_layout Standard
28406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28409 \begin_layout Standard
28415 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28418 \begin_layout Standard
28424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28427 \begin_layout Standard
28428 rest of the pointer
28433 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28436 \begin_layout Standard
28443 <row topline="true" bottomline="true">
28444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28447 \begin_layout Standard
28453 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28456 \begin_layout Standard
28462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28465 \begin_layout Standard
28471 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28474 \begin_layout Standard
28479 uuuuuu uuuuxxxx xxxxxxxx
28484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28487 \begin_layout Standard
28488 a 12-bit data pointer in data RAM memory
28494 <row bottomline="true">
28495 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28498 \begin_layout Standard
28504 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28507 \begin_layout Standard
28513 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28516 \begin_layout Standard
28522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28525 \begin_layout Standard
28530 uxxxxx xxxxxxxx xxxxxxxx
28535 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28538 \begin_layout Standard
28539 a 21-bit code pointer in FLASH memory
28545 <row bottomline="true">
28546 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28549 \begin_layout Standard
28555 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28558 \begin_layout Standard
28564 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28567 \begin_layout Standard
28573 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28576 \begin_layout Standard
28581 uuuuuu uuuuuuxx xxxxxxxx
28586 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28589 \begin_layout Standard
28590 a 10-bit eeprom pointer in EEPROM memory
28596 <row bottomline="true">
28597 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28600 \begin_layout Standard
28606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28609 \begin_layout Standard
28615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28618 \begin_layout Standard
28624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28627 \begin_layout Standard
28632 xxxxxx xxxxxxxx xxxxxxxx
28637 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28640 \begin_layout Standard
28641 unimplemented pointer type
28654 \begin_layout Standard
28656 Generic pointer are read and written with a set of library functions which
28657 read/write 1, 2, 3, 4 bytes.
28660 \begin_layout Subsection
28664 \begin_layout Subsubsection
28665 Standard I/O Streams
28668 \begin_layout Standard
28673 the type FILE is defined as:
28676 \begin_layout LyX-Code
28677 typedef char * FILE;
28680 \begin_layout Standard
28681 This type is the stream type implemented I/O in the PIC18F devices.
28682 Also the standard input and output streams are declared in stdio.h:
28685 \begin_layout LyX-Code
28686 extern FILE * stdin;
28689 \begin_layout LyX-Code
28690 extern FILE * stdout;
28693 \begin_layout Standard
28694 The FILE type is actually a generic pointer which defines one more type
28695 of generic pointers, the
28700 This new type has the format:
28703 \begin_layout Standard
28706 \begin_inset Tabular
28707 <lyxtabular version="3" rows="2" columns="7">
28709 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28710 <column alignment="center" valignment="top" width="0">
28711 <column alignment="center" valignment="top" leftline="true" width="0">
28712 <column alignment="center" valignment="top" leftline="true" width="0">
28713 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28714 <column alignment="center" valignment="top" width="0">
28715 <column alignment="left" valignment="top" rightline="true" width="0">
28716 <row topline="true" bottomline="true">
28717 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28720 \begin_layout Standard
28726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28729 \begin_layout Standard
28735 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28738 \begin_layout Standard
28744 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28747 \begin_layout Standard
28753 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28756 \begin_layout Standard
28762 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28765 \begin_layout Standard
28766 rest of the pointer
28771 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28774 \begin_layout Standard
28781 <row topline="true" bottomline="true">
28782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28785 \begin_layout Standard
28791 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28794 \begin_layout Standard
28800 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28803 \begin_layout Standard
28809 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28812 \begin_layout Standard
28818 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28821 \begin_layout Standard
28827 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28830 \begin_layout Standard
28840 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28843 \begin_layout Standard
28844 upper byte high nubble is 0x2n, the rest are zeroes
28857 \begin_layout Standard
28859 Currently implemented there are 3 types of streams defined:
28862 \begin_layout Standard
28865 \begin_inset Tabular
28866 <lyxtabular version="3" rows="4" columns="4">
28868 <column alignment="center" valignment="top" leftline="true" width="0">
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" rightline="true" width="0">
28872 <row topline="true" bottomline="true">
28873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28876 \begin_layout Standard
28882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28885 \begin_layout Standard
28891 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28894 \begin_layout Standard
28900 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28903 \begin_layout Standard
28910 <row topline="true">
28911 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28914 \begin_layout Standard
28920 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28923 \begin_layout Standard
28931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28934 \begin_layout Standard
28940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28943 \begin_layout Standard
28944 Writes/Reads characters via the USART peripheral
28950 <row topline="true">
28951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28954 \begin_layout Standard
28960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28963 \begin_layout Standard
28971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28974 \begin_layout Standard
28980 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28983 \begin_layout Standard
28984 Writes/Reads characters via the MSSP peripheral
28990 <row topline="true" bottomline="true">
28991 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28994 \begin_layout Standard
29000 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29003 \begin_layout Standard
29011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29014 \begin_layout Standard
29020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29023 \begin_layout Standard
29024 Writes/Reads characters via used defined functions
29037 \begin_layout Standard
29039 The stream identifiers are declared as macros in the stdio.h header.
29042 \begin_layout Standard
29044 In the libc library there exist the functions that are used to write to
29045 each of the above streams.
29049 \begin_layout Description
29054 \begin_layout Standard
29063 _stream_usart_putchar writes a character at the USART stream
29066 \begin_layout Description
29071 \begin_layout Standard
29080 _stream_mssp_putchar writes a character at the MSSP stream
29083 \begin_layout Description
29084 putchar dummy function.
29085 This writes a character to a user specified manner.
29088 \begin_layout Standard
29089 In order to increase performance
29093 is declared in stdio.h as having its parameter in WREG (it has the wparam
29095 In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
29096 in a user-friendly way.
29101 is the name of the variable that holds the character to print.
29102 An example follows:
29105 \begin_layout LyX-Code
29106 #include <pic18fregs.h>
29115 \begin_layout LyX-Code
29119 \begin_layout LyX-Code
29120 PORTA = c; /* dump character c to PORTA */
29123 \begin_layout LyX-Code
29131 \begin_layout LyX-Code
29135 \begin_layout LyX-Code
29136 stdout = STREAM_USER; /* this is not necessary, since stdout points
29139 \begin_layout LyX-Code
29140 * by default to STREAM_USER */
29143 \begin_layout LyX-Code
29145 \begin_inset Quotes sld
29148 This is a printf test
29151 \begin_inset Quotes srd
29157 \begin_layout LyX-Code
29161 \begin_layout LyX-Code
29165 \begin_layout Subsubsection
29169 \begin_layout Standard
29170 PIC16 contains an implementation of the printf-family of functions.
29171 There exist the following functions:
29174 \begin_layout LyX-Code
29175 extern unsigned int sprintf(char *buf, char *fmt, ...);
29178 \begin_layout LyX-Code
29179 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
29182 \begin_layout LyX-Code
29186 \begin_layout LyX-Code
29187 extern unsigned int printf(char *fmt, ...);
29190 \begin_layout LyX-Code
29191 extern unsigned int vprintf(char *fmt, va_lista ap);
29194 \begin_layout LyX-Code
29198 \begin_layout LyX-Code
29199 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
29202 \begin_layout LyX-Code
29203 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
29206 \begin_layout Standard
29207 For sprintf and vsprintf
29211 should normally be a data pointer where the resulting string will be placed.
29212 No range checking is done so the user should allocate the necessary buffer.
29213 For fprintf and vfprintf
29217 should be a stream pointer (i.e.
29218 stdout, STREAM_MSSP, etc...).
29221 \begin_layout Subsubsection
29225 \begin_layout Standard
29226 The PIC18F family of microcontrollers supports a number of interrupt sources.
29227 A list of these interrupts is shown in the following table:
29230 \begin_layout Standard
29232 \begin_inset Tabular
29233 <lyxtabular version="3" rows="11" columns="4">
29235 <column alignment="left" valignment="top" leftline="true" width="0">
29236 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
29237 <column alignment="left" valignment="top" leftline="true" width="0">
29238 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
29239 <row topline="true" bottomline="true">
29240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29243 \begin_layout Standard
29249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29252 \begin_layout Standard
29258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29261 \begin_layout Standard
29267 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29270 \begin_layout Standard
29277 <row topline="true">
29278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29281 \begin_layout Standard
29287 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29290 \begin_layout Standard
29291 PORTB change interrupt
29296 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29299 \begin_layout Standard
29305 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29308 \begin_layout Standard
29309 EEPROM/FLASH write complete interrupt
29315 <row topline="true">
29316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29319 \begin_layout Standard
29325 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29328 \begin_layout Standard
29329 INT0 external interrupt
29334 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29337 \begin_layout Standard
29343 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29346 \begin_layout Standard
29347 Bus collision interrupt
29353 <row topline="true">
29354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29357 \begin_layout Standard
29363 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29366 \begin_layout Standard
29367 INT1 external interrupt
29372 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29375 \begin_layout Standard
29381 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29384 \begin_layout Standard
29385 Low voltage detect interrupt
29391 <row topline="true">
29392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29395 \begin_layout Standard
29401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29404 \begin_layout Standard
29405 INT2 external interrupt
29410 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29413 \begin_layout Standard
29419 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29422 \begin_layout Standard
29423 Parallel slave port interrupt
29429 <row topline="true">
29430 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29433 \begin_layout Standard
29439 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29442 \begin_layout Standard
29443 CCP1 module interrupt
29448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29451 \begin_layout Standard
29457 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29460 \begin_layout Standard
29461 AD convertion complete interrupt
29467 <row topline="true">
29468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29471 \begin_layout Standard
29477 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29480 \begin_layout Standard
29481 CCP2 module interrupt
29486 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29489 \begin_layout Standard
29495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29498 \begin_layout Standard
29499 USART receive interrupt
29505 <row topline="true">
29506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29509 \begin_layout Standard
29515 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29518 \begin_layout Standard
29519 TMR0 overflow interrupt
29524 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29527 \begin_layout Standard
29533 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29536 \begin_layout Standard
29537 USART transmit interrupt
29543 <row topline="true">
29544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29547 \begin_layout Standard
29553 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29556 \begin_layout Standard
29557 TMR1 overflow interrupt
29562 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29565 \begin_layout Standard
29571 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29574 \begin_layout Standard
29575 SSP receive/transmit interrupt
29581 <row topline="true">
29582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29585 \begin_layout Standard
29591 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29594 \begin_layout Standard
29595 TMR2 matches PR2 interrupt
29600 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29603 \begin_layout Standard
29609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29612 \begin_layout Standard
29619 <row topline="true" bottomline="true">
29620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29623 \begin_layout Standard
29629 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29632 \begin_layout Standard
29633 TMR3 overflow interrupt
29638 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29641 \begin_layout Standard
29647 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29650 \begin_layout Standard
29664 \begin_layout Standard
29666 The prototypes for these names are defined in the header file
29673 \begin_layout Standard
29675 In order to simplify signal handling, a number of macros is provided:
29679 \labelwidthstring 00.00.0000
29680 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
29681 high priority interrupts.
29686 is the function name to use.
29690 \labelwidthstring 00.00.0000
29691 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
29692 low priority interrupt.
29697 is the function name to use.
29701 \labelwidthstring 00.00.0000
29702 DEF_HANDLER(sig,handler) define a handler for signal
29708 \labelwidthstring 00.00.0000
29709 END_DEF end the declaration of the dispatch table.
29712 \begin_layout Standard
29713 Additionally there are two more macros to simplify the declaration of the
29718 \labelwidthstring 00.00.0000
29721 SIGHANDLER(handler)
29723 this declares the function prototype for the
29731 \labelwidthstring 00.00.0000
29732 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
29735 \begin_layout Standard
29736 An example of using the macros above is shown below:
29739 \begin_layout LyX-Code
29740 #include <pic18fregs.h>
29743 \begin_layout LyX-Code
29744 #include <signal.h>
29748 DEF_INTHIGH(high_int)
29751 \begin_layout LyX-Code
29752 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
29755 \begin_layout LyX-Code
29756 DEF_HANDLER(SIG_BCOL, _bcol_handler)
29759 \begin_layout LyX-Code
29764 SIGHANDLER(_tmr0_handler)
29767 \begin_layout LyX-Code
29771 \begin_layout LyX-Code
29772 /* action to be taken when timer 0 overflows */
29775 \begin_layout LyX-Code
29780 SIGHANDLERNAKED(_bcol_handler)
29783 \begin_layout LyX-Code
29787 \begin_layout LyX-Code
29791 \begin_layout LyX-Code
29792 /* action to be taken when bus collision occurs */
29795 \begin_layout LyX-Code
29799 \begin_layout LyX-Code
29803 \begin_layout LyX-Code
29807 \begin_layout Standard
29812 Special care should be taken when using the above scheme:
29815 \begin_layout Itemize
29816 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
29819 \begin_layout Itemize
29820 when declaring SIGHANDLERNAKED handler never forget to use
29824 for proper returning.
29827 \begin_layout Subsection
29831 \begin_layout Standard
29832 Here you can find some general tips for compiling programs with SDCC/pic16.
29835 \begin_layout Subsubsection
29839 \begin_layout Standard
29841 \begin_inset LatexCommand index
29846 size (that is 64 bytes) probably is enough for many programs.
29847 One must take care that when there are many levels of function nesting,
29848 or there is excessive usage of stack, its size should be extended.
29849 An example of such a case is the printf/sprintf family of functions.
29850 If you encounter problems like not being able to print integers, then you
29851 need to set the stack size around the maximum (256 for small stack model).
29852 The following diagram shows what happens when calling printf to print an
29856 \begin_layout LyX-Code
29857 printf () --> ltoa () --> ultoa () --> divschar ()
29860 \begin_layout Standard
29861 It is should be understood that stack is easily consumed when calling complicate
29863 Using command line arguments like -
29867 \begin_layout Standard
29876 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
29878 Other ways to reduce stack usage may exist.
29881 \begin_layout Subsection
29885 \begin_layout Subsubsection
29886 Extended Instruction Set
29889 \begin_layout Standard
29890 The PIC16 port emits code which is incompatible with the extended instruction
29891 set available with many newer devices.
29892 Make sure to always explicitly disable it, usually using
29895 \begin_layout Standard
29898 static __code char __at(__CONFIG4L) conf4l = /* more flags & */ _XINST_OFF_4L;
29901 \begin_layout Standard
29903 Some devices (namely 18f2455, 18f2550, 18f4455, and 18f4550) use _ENHCPU_OFF_4L
29904 instead of _XINST_OFF_4L.
29907 \begin_layout Subsubsection
29911 \begin_layout Standard
29912 The PIC16 port currently passes most but not all of the tests in SDCC's
29914 \begin_inset LatexCommand index
29915 name "Regression test (PIC16)"
29920 \begin_inset LatexCommand ref
29921 reference "sec:Quality-control"
29925 ), thus no automatic regression tests are currently performed for the PIC16
29929 \begin_layout Chapter
29933 \begin_layout Standard
29934 There are several approaches to debugging your code.
29935 This chapter is meant to show your options and to give detail on some of
29940 When writing your code:
29943 \begin_layout Itemize
29944 write your code with debugging in mind (avoid duplicating code, put conceptually
29945 similar variables into structs, use structured code, have strategic points
29946 within your code where all variables are consistent, ...)
29949 \begin_layout Itemize
29950 run a syntax-checking tool like splint
29951 \begin_inset LatexCommand index
29952 name "splint (syntax checking tool)"
29957 \begin_inset LatexCommand index
29958 name "lint (syntax checking tool)"
29966 \begin_layout Standard
29976 \begin_inset LatexCommand ref
29977 reference "lyx:more-pedantic-SPLINT"
29984 \begin_layout Itemize
29985 for the high level code use a C-compiler (like f.e.
29986 GCC) to compile run and debug the code on your host.
29991 \begin_layout Standard
30001 \begin_inset LatexCommand ref
30002 reference "lyx:more-pedantic-SPLINT"
30006 ) on how to handle syntax extensions like __xdata, __at(), ...
30010 \begin_layout Itemize
30011 use another C-compiler to compile code for your target.
30012 Always an option but not recommended:) And not very likely to help you.
30013 If you seriously consider walking this path you should at least occasionally
30014 check portability of your code.
30015 Most commercial compiler vendors will offer an evaluation version so you
30016 can test compile your code or snippets of your code.
30019 \begin_layout Standard
30020 Debugging on a simulator:
30023 \begin_layout Itemize
30024 there is a separate section about SDCDB (section
30025 \begin_inset LatexCommand ref
30026 reference "cha:Debugging-with-SDCDB"
30033 \begin_layout Itemize
30034 or (8051 specific) use a freeware/commercial simulator which interfaces
30036 \begin_inset LatexCommand index
30037 name "AOMF, AOMF51"
30042 \begin_inset LatexCommand ref
30043 reference "OMF file"
30047 ) optionally generated by SDCC.
30050 \begin_layout Standard
30051 Debugging On-target:
30054 \begin_layout Itemize
30055 use a MCU port pin to serially output debug data to the RS232 port of your
30057 You'll probably want some level shifting device typically involving a MAX232
30059 If the hardware serial port of the MCU is not available search for 'Software
30060 UART' in your favourite search machine.
30063 \begin_layout Itemize
30064 use an on-target monitor.
30065 In this context a monitor is a small program which usually accepts commands
30066 via a serial line and allows to set program counter, to single step through
30067 a program and read/write memory locations.
30068 For the 8051 good examples of monitors are paulmon and cmon51 (see section
30070 \begin_inset LatexCommand ref
30071 reference "sec:Related-open-source-tools"
30078 \begin_layout Itemize
30079 toggle MCU port pins at strategic points within your code and use an oscilloscop
30083 digital oscilloscope
30086 \begin_inset LatexCommand index
30087 name "Oscilloscope"
30091 with deep trace memory is really helpful especially if you have to debug
30092 a realtime application.
30093 If you need to monitor more pins than your oscilloscope provides you can
30094 sometimes get away with a small R-2R network.
30095 On a single channel oscilloscope you could f.e.
30096 monitor 2 push-pull driven pins by connecting one via a 10\InsetSpace ~
30098 \begin_inset Formula $\Omega$
30101 resistor and the other one by a 5\InsetSpace ~
30103 \begin_inset Formula $\Omega$
30106 resistor to the oscilloscope probe (check output drive capability of the
30107 pins you want to monitor).
30108 If you need to monitor many more pins a
30115 \begin_layout Itemize
30129 \begin_inset LatexCommand index
30130 name "ICE (in circuit emulator)"
30135 Usually very expensive.
30136 And very nice to have too.
30137 And usually locks you (for years...) to the devices the ICE can emulate.
30141 \begin_layout Itemize
30142 use a remote debugger.
30143 In most 8-bit systems the symbol information is not available on the target,
30144 and a complete debugger is too bulky for the target system.
30145 Therefore usually a debugger on the host system connects to an on-target
30146 debugging stub which accepts only primitive commands.
30149 Terms to enter into your favourite search engine could be 'remote debugging',
30150 'gdb stub' or 'inferior debugger'.
30154 \begin_layout Itemize
30155 use an on target hardware debugger.
30156 Some of the more modern MCUs include hardware support for setting break
30157 points and monitoring/changing variables by using dedicated hardware pins.
30158 This facility doesn't require additional code to run on the target and
30163 doesn't affect runtime behaviour until a breakpoint is hit.
30164 For the mcs51 most hardware debuggers use the AOMF
30165 \begin_inset LatexCommand index
30166 name "AOMF, AOMF51"
30171 \begin_inset LatexCommand ref
30172 reference "OMF file"
30180 \begin_layout Standard
30184 \begin_layout Itemize
30185 if you are not familiar with any of the following terms you're likely to
30186 run into problems rather sooner than later:
30203 As an embedded programmer you
30207 to know them so why not look them up
30211 you have problems?)
30214 \begin_layout Itemize
30215 tell someone else about your problem (actually this is a surprisingly effective
30216 means to hunt down the bug even if the listener is not familiar with your
30218 As 'failure to communicate' is probably one of the job-induced deformations
30219 of an embedded programmer this is highly encouraged.
30222 \begin_layout Section
30223 Debugging with SDCDB
30224 \begin_inset LatexCommand label
30225 name "cha:Debugging-with-SDCDB"
30230 \begin_inset LatexCommand index
30231 name "SDCDB (debugger)"
30238 \begin_layout Standard
30239 SDCC is distributed with a source level debugger
30240 \begin_inset LatexCommand index
30246 The debugger uses a command line interface, the command repertoire of the
30247 debugger has been kept as close to gdb
30248 \begin_inset LatexCommand index
30253 (the GNU debugger) as possible.
30254 The configuration and build process is part of the standard compiler installati
30255 on, which also builds and installs the debugger in the target directory
30256 specified during configuration.
30257 The debugger allows you debug BOTH at the C source and at the ASM source
30261 \begin_layout Subsection
30262 Compiling for Debugging
30265 \begin_layout Standard
30270 \begin_layout Standard
30280 \begin_inset LatexCommand index
30285 option must be specified for all files for which debug information is to
30287 The compiler generates a .adb file for each of these files.
30288 The linker creates the .cdb
30289 \begin_inset LatexCommand index
30295 \begin_inset LatexCommand index
30300 files and the address information.
30301 This .cdb is used by the debugger.
30304 \begin_layout Subsection
30305 How the Debugger Works
30308 \begin_layout Standard
30313 \begin_layout Standard
30322 -debug option is specified the compiler generates extra symbol information
30323 some of which are put into the assembler source and some are put into the
30325 Then the linker creates the .cdb file from the individual .adb files with
30326 the address information for the symbols.
30327 The debugger reads the symbolic information generated by the compiler &
30328 the address information generated by the linker.
30329 It uses the SIMULATOR (Daniel's S51) to execute the program, the program
30330 execution is controlled by the debugger.
30331 When a command is issued for the debugger, it translates it into appropriate
30332 commands for the simulator.
30333 (Currently SDCDM only connects to the simulator but
30338 \begin_inset LatexCommand url
30339 target "http://ec2drv.sf.net/"
30343 is an effort to connect directly to the hardware.)
30346 \begin_layout Subsection
30347 Starting the Debugger SDCDB
30350 \begin_layout Standard
30351 The debugger can be started using the following command line.
30352 (Assume the file you are debugging has the file name foo).
30366 The debugger will look for the following files.
30369 \begin_layout Itemize
30370 foo.c - the source file.
30373 \begin_layout Itemize
30374 foo.cdb - the debugger symbol information file.
30377 \begin_layout Itemize
30378 foo.ihx - the Intel hex format
30379 \begin_inset LatexCommand index
30380 name "Intel hex format"
30387 \begin_layout Subsection
30388 SDCDB Command Line Options
30391 \begin_layout Itemize
30396 \begin_layout Standard
30405 -directory=<source file directory> this option can used to specify the directory
30407 The debugger will look into the directory list specified for source, cdb
30409 The items in the directory list must be separated by ':', e.g.
30410 if the source files can be in the directories /home/src1 and /home/src2,
30415 \begin_layout Standard
30424 -directory option should be -
30428 \begin_layout Standard
30437 -directory=/home/src1:/home/src2.
30438 Note there can be no spaces in the option.
30442 \begin_layout Itemize
30443 -cd <directory> - change to the <directory>.
30446 \begin_layout Itemize
30447 -fullname - used by GUI front ends.
30450 \begin_layout Itemize
30451 -cpu <cpu-type> - this argument is passed to the simulator please see the
30452 simulator docs for details.
30455 \begin_layout Itemize
30456 -X <Clock frequency > this options is passed to the simulator please see
30457 the simulator docs for details.
30460 \begin_layout Itemize
30461 -s <serial port file> passed to simulator see the simulator docs for details.
30464 \begin_layout Itemize
30465 -S <serial in,out> passed to simulator see the simulator docs for details.
30468 \begin_layout Itemize
30469 -k <port number> passed to simulator see the simulator docs for details.
30472 \begin_layout Subsection
30473 SDCDB Debugger Commands
30476 \begin_layout Standard
30477 As mentioned earlier the command interface for the debugger has been deliberatel
30478 y kept as close the GNU debugger gdb, as possible.
30479 This will help the integration with existing graphical user interfaces
30480 (like ddd, xxgdb or xemacs) existing for the GNU debugger.
30481 If you use a graphical user interface for the debugger you can skip this
30485 \begin_layout Subsubsection*
30486 break [line | file:line | function | file:function]
30489 \begin_layout Standard
30490 Set breakpoint at specified line or function:
30499 sdcdb>break foo.c:100
30501 sdcdb>break funcfoo
30503 sdcdb>break foo.c:funcfoo
30506 \begin_layout Subsubsection*
30507 clear [line | file:line | function | file:function ]
30510 \begin_layout Standard
30511 Clear breakpoint at specified line or function:
30520 sdcdb>clear foo.c:100
30522 sdcdb>clear funcfoo
30524 sdcdb>clear foo.c:funcfoo
30527 \begin_layout Subsubsection*
30531 \begin_layout Standard
30532 Continue program being debugged, after breakpoint.
30535 \begin_layout Subsubsection*
30539 \begin_layout Standard
30540 Execute till the end of the current function.
30543 \begin_layout Subsubsection*
30547 \begin_layout Standard
30548 Delete breakpoint number 'n'.
30549 If used without any option clear ALL user defined break points.
30552 \begin_layout Subsubsection*
30553 info [break | stack | frame | registers ]
30556 \begin_layout Itemize
30557 info break - list all breakpoints
30560 \begin_layout Itemize
30561 info stack - show the function call stack.
30564 \begin_layout Itemize
30565 info frame - show information about the current execution frame.
30568 \begin_layout Itemize
30569 info registers - show content of all registers.
30572 \begin_layout Subsubsection*
30576 \begin_layout Standard
30577 Step program until it reaches a different source line.
30578 Note: pressing <return> repeats the last command.
30581 \begin_layout Subsubsection*
30585 \begin_layout Standard
30586 Step program, proceeding through subroutine calls.
30589 \begin_layout Subsubsection*
30593 \begin_layout Standard
30594 Start debugged program.
30597 \begin_layout Subsubsection*
30601 \begin_layout Standard
30602 Print type information of the variable.
30605 \begin_layout Subsubsection*
30609 \begin_layout Standard
30610 print value of variable.
30613 \begin_layout Subsubsection*
30617 \begin_layout Standard
30618 load the given file name.
30619 Note this is an alternate method of loading file for debugging.
30622 \begin_layout Subsubsection*
30626 \begin_layout Standard
30627 print information about current frame.
30630 \begin_layout Subsubsection*
30634 \begin_layout Standard
30635 Toggle between C source & assembly source.
30638 \begin_layout Subsubsection*
30639 ! simulator command
30642 \begin_layout Standard
30643 Send the string following '!' to the simulator, the simulator response is
30645 Note the debugger does not interpret the command being sent to the simulator,
30646 so if a command like 'go' is sent the debugger can loose its execution
30647 context and may display incorrect values.
30650 \begin_layout Subsubsection*
30654 \begin_layout Standard
30657 My name is Bobby Brown"
30660 \begin_layout Subsection
30661 Interfacing SDCDB with DDD
30664 \begin_layout Standard
30665 \begin_inset Note Note
30668 \begin_layout Standard
30669 The screenshot was converted from png to eps with:
30670 \begin_inset Quotes sld
30673 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
30674 \begin_inset Quotes srd
30677 which produces a pretty compact eps file which is free from compression
30681 \begin_layout Standard
30682 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
30683 as this broke the build system on Sourceforge (pdf-file was broken.
30684 pdflatex does not accept eps files).
30692 \begin_layout Standard
30708 \begin_inset LatexCommand url
30709 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png"
30715 shows a screenshot of a debugging session with DDD
30716 \begin_inset LatexCommand index
30717 name "DDD (debugger)"
30721 (Unix only) on a simulated 8032.
30722 The debugging session might not run as smoothly as the screenshot suggests.
30723 The debugger allows setting of breakpoints, displaying and changing variables,
30724 single stepping through C and assembler code.
30727 The source was compiled with
30741 \begin_layout Standard
30753 -debug ddd_example.c
30766 and DDD was invoked with
30773 ddd -debugger "sdcdb -cpu 8032 ddd_example"
30776 \begin_layout Standard
30777 \begin_inset Note Note
30780 \begin_layout Standard
30781 Check that the double quotes or an apostrophe within the command line survive
30782 the LyX tool chain.
30783 Previously the apostrophes got slanted in the PDF output so a cut and paste
30792 \begin_layout Subsection
30793 Interfacing SDCDB with XEmacs
30794 \begin_inset LatexCommand index
30800 \begin_inset LatexCommand index
30808 \begin_layout Standard
30809 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
30810 sdcdb.el and sdcdbsrc.el.
30811 These two files can be found in the $(prefix)/bin directory after the installat
30813 These files need to be loaded into XEmacs for the interface to work.
30814 This can be done at XEmacs startup time by inserting the following into
30815 your '.xemacs' file (which can be found in your HOME directory):
30821 (load-file sdcdbsrc.el)
30827 .xemacs is a lisp file so the () around the command is REQUIRED.
30828 The files can also be loaded dynamically while XEmacs is running, set the
30829 environment variable 'EMACSLOADPATH' to the installation bin directory
30830 (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
30831 To start the interface enter the following command:
30845 You will prompted to enter the file name to be debugged.
30850 The command line options that are passed to the simulator directly are
30851 bound to default values in the file sdcdbsrc.el.
30852 The variables are listed below, these values maybe changed as required.
30855 \begin_layout Itemize
30856 sdcdbsrc-cpu-type '51
30859 \begin_layout Itemize
30860 sdcdbsrc-frequency '11059200
30863 \begin_layout Itemize
30864 sdcdbsrc-serial nil
30867 \begin_layout Standard
30868 The following is a list of key mapping for the debugger interface.
30871 \begin_layout Standard
30894 binding\InsetSpace ~
30932 -------\InsetSpace ~
31003 sdcdb-back-from-src\InsetSpace ~
31032 rom-src\InsetSpace ~
31042 SDCDB continue command
31060 sdcdb-step-from-src\InsetSpace ~
31089 hatis-c-sexp\InsetSpace ~
31099 SDCDB ptypecommand for data at
31166 sdcdbsrc-delete\InsetSpace ~
31181 B Delete all breakpoints if no arg
31230 given or delete arg (C-u arg x)
31249 -frame\InsetSpace ~
31264 SDCDB Display current frame if no arg,
31313 given or display frame arg
31381 sdcdbsrc-goto-sdcdb\InsetSpace ~
31391 Goto the SDCDB output buffer
31410 t-c-sexp\InsetSpace ~
31421 SDCDB print command for data at
31488 sdcdbsrc-goto-sdcdb\InsetSpace ~
31499 o the SDCDB output buffer
31517 sdcdbsrc-mode\InsetSpace ~
31533 Toggles Sdcdbsrc mode (turns it
31549 sdcdb-finish-from-src\InsetSpace ~
31557 SDCDB finish command
31591 Set break for line with point
31606 sdcdbsrc-mode\InsetSpace ~
31622 Toggle Sdcdbsrc mode
31638 dbsrc-srcmode\InsetSpace ~
31662 \begin_layout Chapter
31666 \begin_layout Standard
31667 Here are a few guidelines that will help the compiler generate more efficient
31668 code, some of the tips are specific to this compiler others are generally
31669 good programming practice.
31672 \begin_layout Itemize
31673 Use the smallest data type to represent your data-value.
31674 If it is known in advance that the value is going to be less than 256 then
31675 use an 'unsigned char' instead of a 'short' or 'int'.
31676 Please note, that ANSI C requires both signed and unsigned chars to be
31677 promoted to 'signed int'
31678 \begin_inset LatexCommand index
31679 name "promotion to signed int"
31684 \begin_inset Marginal
31687 \begin_layout Standard
31696 before doing any operation.
31698 \begin_inset LatexCommand index
31699 name "type promotion"
31704 \begin_inset LatexCommand label
31705 name "type promotion"
31709 can be omitted, if the result is the same.
31710 The effect of the promotion rules together with the sign-extension is often
31715 \begin_layout Verse
31718 unsigned char uc = 0xfe;
31720 if (uc * uc < 0) /* this is true! */
31733 \begin_layout Standard
31740 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
31748 \begin_layout Verse
31751 (unsigned char) -12 / (signed char) -3 = ...
31754 \begin_layout Standard
31755 No, the result is not 4:
31758 \begin_layout Verse
31761 (int) (unsigned char) -12 / (int) (signed char) -3 =
31763 (int) (unsigned char)
31764 0xf4 / (int) (signed char) 0xfd =
31766 (int) 0x00f4 / (int) 0xfffd =
31771 (int) 244 / (int) -3 =
31773 (int) -81 = (int) 0xffaf;
31776 \begin_layout Standard
31777 Don't complain, that gcc gives you a different result.
31778 gcc uses 32 bit ints, while SDCC uses 16 bit ints.
31779 Therefore the results are different.
31782 \begin_inset Quotes sld
31786 \begin_inset Quotes srd
31792 \begin_layout Quote
31795 If well-defined overflow characteristics are important and negative values
31796 are not, or if you want to steer clear of sign-extension problems when
31797 manipulating bits or bytes, use one of the corresponding unsigned types.
31798 (Beware when mixing signed and unsigned values in expressions, though.)
31801 character types (especially unsigned char) can be used as "tiny" integers,
31802 doing so is sometimes more trouble than it's worth, due to unpredictable
31803 sign extension and increased code size.
31807 \begin_layout Itemize
31808 Use unsigned when it is known in advance that the value is not going to
31810 This helps especially if you are doing division or multiplication, bit-shifting
31811 or are using an array index.
31814 \begin_layout Itemize
31815 NEVER jump into a LOOP.
31818 \begin_layout Itemize
31819 Declare the variables to be local
31820 \begin_inset LatexCommand index
31821 name "local variables"
31825 whenever possible, especially loop control variables (induction).
31828 \begin_layout Itemize
31829 Have a look at the assembly listing to get a
31830 \begin_inset Quotes sld
31834 \begin_inset Quotes srd
31837 for the code generation.
31840 \begin_layout Section
31841 Porting code from or to other compilers
31842 \begin_inset LatexCommand label
31843 name "sec:Porting-code-to-other-compilers"
31850 \begin_layout Itemize
31851 check whether endianness of the compilers differs and adapt where needed.
31854 \begin_layout Itemize
31855 check the device specific header files
31856 \begin_inset LatexCommand index
31857 name "Header files"
31862 \begin_inset LatexCommand index
31863 name "Include files"
31867 for compiler specific syntax.
31868 Eventually include the file <compiler.h
31869 \begin_inset LatexCommand index
31870 name "compiler.h (include file)"
31875 \begin_inset LatexCommand url
31876 target "http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/compiler.h?view=markup"
31880 to allow using common header files.
31883 \begin_inset LatexCommand url
31884 target "http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/cc2510fx.h?view=markup"
31891 \begin_layout Itemize
31892 check whether the startup code contains the correct initialization (watchdog,
31896 \begin_layout Itemize
31897 check whether the sizes of short, int, long match.
31900 \begin_layout Itemize
31901 check if some 16 or 32 bit hardware registers require a specific addressing
31902 order (least significant or most significant byte first) and adapt if needed
31911 relate to time and not to lower/upper memory location here, so this is
31916 the same as endianness).
31919 \begin_layout Itemize
31920 check whether the keyword
31924 is used where needed.
31925 The compilers might differ in their optimization characteristics (as different
31926 versions of the same compiler might also use more clever optimizations
31927 this is good idea anyway).
31929 \begin_inset LatexCommand ref
31930 reference "sub:Common-interrupt-pitfall-volatile"
31937 \begin_layout Itemize
31938 check that the compilers are not told to suppress warnings.
31941 \begin_layout Itemize
31942 check and convert compiler specific extensions (interrupts, memory areas,
31946 \begin_layout Itemize
31947 check for differences in type promotion.
31948 Especially check for math operations on
31957 For the sake of C99 compatibility SDCC will probably promote these to
31961 more often than other compilers.
31962 Eventually insert explicit casts to
31971 Also check that the ~\InsetSpace ~
31973 \begin_inset LatexCommand index
31974 name "\\~\\/ Operator"
31981 \begin_inset LatexCommand index
31988 variables, use the !\InsetSpace ~
31991 \begin_inset LatexCommand ref
31992 reference "type promotion"
31997 \begin_inset LatexCommand ref
31998 reference "sec:Compatibility-with-previous"
32005 \begin_layout Itemize
32006 check the assembly code generated for interrupt routines (f.e.
32007 for calls to possibly non-reentrant library functions).
32010 \begin_layout Itemize
32011 check whether timing loops result in proper timing (or preferably consider
32012 a rewrite of the code with timer based delays instead).
32015 \begin_layout Itemize
32016 check for differences in printf parameters (some compilers push (va_arg
32017 \begin_inset LatexCommand index
32018 name "vararg, va\\_arg"
32022 ) char variables as
32026 others push them as
32032 \begin_inset LatexCommand ref
32033 reference "sec:Compatibility-with-previous"
32040 \begin_layout Itemize
32041 check the resulting memory map
32042 \begin_inset LatexCommand index
32048 Usage of different memory spaces: code, stack, data (for mcs51/ds390 additional
32049 ly idata, pdata, xdata).
32050 Eventually check if unexpected library functions are included.
32053 \begin_layout Section
32055 \begin_inset LatexCommand index
32060 included in the distribution
32063 \begin_layout Standard
32065 \begin_inset Tabular
32066 <lyxtabular version="3" rows="12" columns="3">
32068 <column alignment="left" valignment="top" leftline="true" width="0pt">
32069 <column alignment="left" valignment="top" leftline="true" width="0pt">
32070 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
32071 <row topline="true" bottomline="true">
32072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32075 \begin_layout Standard
32083 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32086 \begin_layout Standard
32094 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32097 \begin_layout Standard
32106 <row topline="true">
32107 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32110 \begin_layout Standard
32112 \begin_inset LatexCommand index
32122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32125 \begin_layout Standard
32126 Simulator for various architectures
32131 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32134 \begin_layout Standard
32141 <row topline="true">
32142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32145 \begin_layout Standard
32151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32154 \begin_layout Standard
32156 \begin_inset LatexCommand index
32157 name "Header files"
32162 \begin_inset LatexCommand index
32163 name "Include files"
32172 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32175 \begin_layout Standard
32176 sdcc/support/scripts
32182 <row topline="true">
32183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32186 \begin_layout Standard
32192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32195 \begin_layout Standard
32196 header file conversion
32201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32204 \begin_layout Standard
32205 sdcc/support/scripts
32211 <row topline="true">
32212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32215 \begin_layout Standard
32221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32224 \begin_layout Standard
32230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32233 \begin_layout Standard
32249 <row topline="true">
32250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32253 \begin_layout Standard
32259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32262 \begin_layout Standard
32268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32271 \begin_layout Standard
32287 <row topline="true">
32288 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32291 \begin_layout Standard
32297 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32300 \begin_layout Standard
32306 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32309 \begin_layout Standard
32325 <row topline="true">
32326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32329 \begin_layout Standard
32335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32338 \begin_layout Standard
32344 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32347 \begin_layout Standard
32363 <row topline="true">
32364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32367 \begin_layout Standard
32373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32376 \begin_layout Standard
32382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32385 \begin_layout Standard
32401 <row topline="true">
32402 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32405 \begin_layout Standard
32411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32414 \begin_layout Standard
32420 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32423 \begin_layout Standard
32439 <row topline="true">
32440 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32443 \begin_layout Standard
32449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32452 \begin_layout Standard
32458 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32461 \begin_layout Standard
32477 <row topline="true" bottomline="true">
32478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32481 \begin_layout Standard
32487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32490 \begin_layout Standard
32492 \begin_inset LatexCommand index
32493 name "packihx (tool)"
32502 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32505 \begin_layout Standard
32530 \begin_layout Section
32532 \begin_inset LatexCommand index
32533 name "Documentation"
32537 included in the distribution
32540 \begin_layout Standard
32542 \begin_inset Tabular
32543 <lyxtabular version="3" rows="10" columns="2">
32545 <column alignment="block" valignment="top" leftline="true" width="40col%">
32546 <column alignment="block" valignment="top" leftline="true" rightline="true" width="60col%">
32547 <row topline="true" bottomline="true" endhead="true">
32548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32551 \begin_layout Standard
32559 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32562 \begin_layout Standard
32565 Filename / Where to get
32571 <row topline="true">
32572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32575 \begin_layout Standard
32576 SDCC Compiler User Guide
32581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32584 \begin_layout Standard
32585 You're reading it right now
32597 \begin_inset LatexCommand url
32598 target "http://sdcc.sourceforge.net/doc/sdccman.pdf"
32608 <row topline="true">
32609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32612 \begin_layout Standard
32618 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32621 \begin_layout Standard
32634 \begin_inset LatexCommand url
32635 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/ChangeLog"
32645 <row topline="true">
32646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32649 \begin_layout Standard
32651 \begin_inset LatexCommand index
32652 name "asXXXX (as-gbz80, as-hc08, asx8051, as-z80)"
32657 \begin_inset LatexCommand index
32658 name "Assembler documentation"
32665 \begin_inset LatexCommand index
32671 \begin_inset LatexCommand index
32672 name "Linker documentation"
32681 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32684 \begin_layout Standard
32685 sdcc/as/doc/asxhtm.html
32697 \begin_inset LatexCommand url
32698 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html"
32708 <row topline="true">
32709 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32712 \begin_layout Standard
32713 SDCC regression test
32714 \begin_inset LatexCommand index
32715 name "Regression test"
32724 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32727 \begin_layout Standard
32728 sdcc/doc/test_suite_spec.pdf
32740 \begin_inset LatexCommand url
32741 target "http://sdcc.sourceforge.net/doc/test_suite_spec.pdf"
32751 <row topline="true">
32752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32755 \begin_layout Standard
32761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32764 \begin_layout Standard
32777 \begin_inset LatexCommand url
32778 target "http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/doc/"
32788 <row topline="true">
32789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32792 \begin_layout Standard
32793 Notes on debugging with SDCDB
32794 \begin_inset LatexCommand index
32795 name "SDCDB (debugger)"
32804 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32807 \begin_layout Standard
32808 sdcc/debugger/README
32820 \begin_inset LatexCommand url
32821 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/debugger/README"
32831 <row topline="true">
32832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32835 \begin_layout Standard
32837 \begin_inset LatexCommand index
32842 Software simulator for microcontrollers
32847 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32850 \begin_layout Standard
32880 \begin_inset LatexCommand url
32881 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/sim/ucsim/doc/index.html"
32891 <row topline="true">
32892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32895 \begin_layout Standard
32896 Temporary notes on the pic16
32897 \begin_inset LatexCommand index
32907 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32910 \begin_layout Standard
32911 sdcc/src/pic16/NOTES
32923 \begin_inset LatexCommand url
32924 target "http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/src/pic16/NOTES"
32934 <row topline="true" bottomline="true">
32935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32938 \begin_layout Standard
32939 SDCC internal documentation (debugging file format)
32944 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32947 \begin_layout Standard
32977 \begin_inset LatexCommand url
32978 target "http://sdcc.sourceforge.net/doc/cdbfileformat.pdf"
32997 \begin_layout Section
32998 Related open source tools
32999 \begin_inset LatexCommand label
33000 name "sec:Related-open-source-tools"
33005 \begin_inset LatexCommand index
33006 name "Related tools"
33013 \begin_layout Standard
33015 \begin_inset Tabular
33016 <lyxtabular version="3" rows="16" columns="3">
33018 <column alignment="left" valignment="top" leftline="true" width="0pt">
33019 <column alignment="block" valignment="top" leftline="true" width="30line%">
33020 <column alignment="left" valignment="top" leftline="true" rightline="true" width="40col%">
33021 <row topline="true" bottomline="true">
33022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33025 \begin_layout Standard
33033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33036 \begin_layout Standard
33044 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33047 \begin_layout Standard
33056 <row topline="true">
33057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33060 \begin_layout Standard
33062 \begin_inset LatexCommand index
33063 name "gpsim (pic simulator)"
33072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33075 \begin_layout Standard
33081 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33084 \begin_layout Standard
33085 \begin_inset LatexCommand url
33086 target "http://www.dattalo.com/gnupic/gpsim.html"
33096 <row topline="true">
33097 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33100 \begin_layout Standard
33102 \begin_inset LatexCommand index
33103 name "gputils (pic tools)"
33112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33115 \begin_layout Standard
33121 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33124 \begin_layout Standard
33125 \begin_inset LatexCommand url
33126 target "http://sourceforge.net/projects/gputils"
33136 <row topline="true">
33137 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33140 \begin_layout Standard
33146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33149 \begin_layout Standard
33155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33158 \begin_layout Standard
33159 \begin_inset LatexCommand url
33160 target "http://freshmeat.net/projects/flp5/"
33170 <row topline="true">
33171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33174 \begin_layout Standard
33180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33183 \begin_layout Standard
33184 Tools for Silicon Laboratories JTAG debug adapter, partly based on SDCDB
33190 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33193 \begin_layout Standard
33194 \begin_inset LatexCommand url
33195 target "http://sourceforge.net/projects/ec2drv"
33205 <row topline="true">
33206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33209 \begin_layout Standard
33211 \begin_inset LatexCommand index
33212 name "indent (source formatting tool)"
33221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33224 \begin_layout Standard
33225 Formats C source - Master of the white spaces
33230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33233 \begin_layout Standard
33234 \begin_inset LatexCommand url
33235 target "http://directory.fsf.org/GNU/indent.html"
33245 <row topline="true">
33246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33249 \begin_layout Standard
33251 \begin_inset LatexCommand index
33252 name "srecord (bin, hex, ... tool)"
33261 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33264 \begin_layout Standard
33265 Object file conversion, checksumming, ...
33270 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33273 \begin_layout Standard
33274 \begin_inset LatexCommand url
33275 target "http://sourceforge.net/projects/srecord"
33285 <row topline="true">
33286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33289 \begin_layout Standard
33291 \begin_inset LatexCommand index
33292 name "objdump (tool)"
33301 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33304 \begin_layout Standard
33305 Object file conversion, ...
33310 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33313 \begin_layout Standard
33314 Part of binutils (should be there anyway)
33320 <row topline="true">
33321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33324 \begin_layout Standard
33330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33333 \begin_layout Standard
33334 8051 monitor (hex up-/download, single step, disassemble)
33339 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33342 \begin_layout Standard
33343 \begin_inset LatexCommand url
33344 target "http://sourceforge.net/projects/cmon51"
33354 <row topline="true">
33355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33358 \begin_layout Standard
33360 \begin_inset LatexCommand index
33361 name "doxygen (source documentation tool)"
33370 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33373 \begin_layout Standard
33374 Source code documentation system
33379 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33382 \begin_layout Standard
33383 \begin_inset LatexCommand url
33384 target "http://www.doxygen.org"
33394 <row topline="true">
33395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33398 \begin_layout Standard
33404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33407 \begin_layout Standard
33408 IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
33413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33416 \begin_layout Standard
33417 \begin_inset LatexCommand url
33418 target "http://www.kdevelop.org"
33428 <row topline="true">
33429 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33432 \begin_layout Standard
33438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33441 \begin_layout Standard
33442 8051 monitor (hex up-/download, single step, disassemble)
33447 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33450 \begin_layout Standard
33451 \begin_inset LatexCommand url
33452 target "http://www.pjrc.com/tech/8051/paulmon2.html"
33462 <row topline="true">
33463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33466 \begin_layout Standard
33468 \begin_inset LatexCommand index
33469 name "splint (syntax checking tool)"
33478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33481 \begin_layout Standard
33482 Statically checks c sources (see
33483 \begin_inset LatexCommand ref
33484 reference "lyx:more-pedantic-SPLINT"
33493 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33496 \begin_layout Standard
33497 \begin_inset LatexCommand url
33498 target "http://www.splint.org"
33508 <row topline="true" bottomline="true">
33509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33512 \begin_layout Standard
33514 \begin_inset LatexCommand index
33515 name "DDD (debugger)"
33524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33527 \begin_layout Standard
33528 Debugger, serves nicely as GUI to SDCDB
33529 \begin_inset LatexCommand index
33530 name "SDCDB (debugger)"
33539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33542 \begin_layout Standard
33543 \begin_inset LatexCommand url
33544 target "http://www.gnu.org/software/ddd/"
33554 <row bottomline="true">
33555 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33558 \begin_layout Standard
33560 \begin_inset LatexCommand index
33566 \begin_inset LatexCommand index
33567 name "d52 (disassembler)"
33576 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33579 \begin_layout Standard
33580 Disassembler, can count instruction cycles
33581 \begin_inset LatexCommand index
33582 name "instruction cycles (count)"
33586 , use with options -pnd
33591 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33594 \begin_layout Standard
33595 \begin_inset LatexCommand url
33596 target "http://www.8052.com/users/disasm/"
33606 <row bottomline="true">
33607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33610 \begin_layout Standard
33612 \begin_inset LatexCommand index
33622 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33625 \begin_layout Standard
33626 Cross platform build system, generates Makefiles
33627 \begin_inset LatexCommand index
33632 and project workspaces
33633 \begin_inset LatexCommand index
33634 name "project workspace"
33643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33646 \begin_layout Standard
33647 \begin_inset LatexCommand url
33648 target "http://www.cmake.org"
33656 and a dedicated wiki entry:
33657 \begin_inset LatexCommand url
33658 target "http://www.cmake.org/Wiki/CmakeSdcc"
33677 \begin_layout Section
33678 Related documentation / recommended reading
33681 \begin_layout Standard
33683 \begin_inset Tabular
33684 <lyxtabular version="3" rows="7" columns="3">
33686 <column alignment="left" valignment="top" leftline="true" width="0pt">
33687 <column alignment="left" valignment="top" leftline="true" width="0">
33688 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
33689 <row topline="true" bottomline="true">
33690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33693 \begin_layout Standard
33701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33704 \begin_layout Standard
33712 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33715 \begin_layout Standard
33724 <row topline="true">
33725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33728 \begin_layout Standard
33743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33746 \begin_layout Standard
33748 \begin_inset LatexCommand index
33749 name "C Reference card"
33758 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33761 \begin_layout Standard
33762 \begin_inset LatexCommand url
33763 target "http://refcards.com/refcards/c/index.html"
33773 <row topline="true">
33774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33777 \begin_layout Standard
33783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33786 \begin_layout Standard
33788 \begin_inset LatexCommand index
33798 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33801 \begin_layout Standard
33802 \begin_inset LatexCommand url
33803 target "http://www.c-faq.com"
33813 <row topline="true">
33814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33817 \begin_layout Standard
33823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33826 \begin_layout Standard
33827 \begin_inset Quotes sld
33831 \begin_inset Quotes srd
33839 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33842 \begin_layout Standard
33845 \begin_inset LatexCommand url
33846 target "http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899"
33856 <row topline="true">
33857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33860 \begin_layout Standard
33866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33869 \begin_layout Standard
33870 \begin_inset Quotes sld
33873 Extensions for Embedded C
33874 \begin_inset Quotes srd
33882 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33885 \begin_layout Standard
33888 \begin_inset LatexCommand url
33889 target "http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf"
33899 <row topline="true">
33900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33903 \begin_layout Standard
33909 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33912 \begin_layout Standard
33913 Latest datasheet of target CPU
33918 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33921 \begin_layout Standard
33928 <row topline="true" bottomline="true">
33929 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33932 \begin_layout Standard
33938 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33941 \begin_layout Standard
33942 Revision history of datasheet
33947 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33950 \begin_layout Standard
33966 \begin_layout Section
33967 Application notes specifically for SDCC
33970 \begin_layout Standard
33971 SDCC makes no claims about the completeness of this list and about up-to-datenes
33972 s or correctness of the application notes
33973 \begin_inset LatexCommand index
33974 name "Application notes"
33981 \begin_layout Standard
33985 \begin_inset Tabular
33986 <lyxtabular version="3" rows="7" columns="3">
33988 <column alignment="block" valignment="top" leftline="true" width="17col%">
33989 <column alignment="block" valignment="top" leftline="true" width="27col%">
33990 <column alignment="block" valignment="top" leftline="true" rightline="true" width="57col%">
33991 <row topline="true" bottomline="true">
33992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33995 \begin_layout Standard
34004 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
34007 \begin_layout Standard
34016 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34019 \begin_layout Standard
34029 <row topline="true">
34030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34033 \begin_layout Standard
34041 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34044 \begin_layout Standard
34047 Using the SDCC Compiler for the DS80C400
34048 \begin_inset LatexCommand index
34058 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34061 \begin_layout Standard
34064 \begin_inset LatexCommand url
34065 target "http://pdfserv.maxim-ic.com/en/an/AN3346.pdf"
34075 <row topline="true">
34076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34079 \begin_layout Standard
34087 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none" width="30line%">
34090 \begin_layout Standard
34093 Using the Free SDCC C Compiler to Develop Firmware for the DS89C420/430/440/450
34094 \begin_inset LatexCommand index
34099 Family of Microcontrollers
34104 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34107 \begin_layout Standard
34110 \begin_inset LatexCommand url
34111 target "http://pdfserv.maxim-ic.com/en/an/AN3477.pdf"
34121 <row topline="true">
34122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34125 \begin_layout Standard
34128 Silicon Laboratories / Cygnal
34133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34136 \begin_layout Standard
34139 Integrating SDCC 8051 Tools Into The Silicon Labs IDE
34140 \begin_inset LatexCommand index
34150 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34153 \begin_layout Standard
34156 \begin_inset LatexCommand url
34157 target "http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/en/an198.pdf"
34167 <row topline="true">
34168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34171 \begin_layout Standard
34174 Ramtron / Goal Semiconductor
34179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34182 \begin_layout Standard
34185 Interfacing SDCC to Syn and Textpad
34190 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34193 \begin_layout Standard
34196 \begin_inset LatexCommand url
34197 target "http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp"
34207 <row topline="true">
34208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34211 \begin_layout Standard
34214 Ramtron / Goal Semiconductor
34219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34222 \begin_layout Standard
34225 Installing and Configuring SDCC and Crimson Editor
34230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34233 \begin_layout Standard
34236 \begin_inset LatexCommand url
34237 target "http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp"
34247 <row topline="true" bottomline="true">
34248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34251 \begin_layout Standard
34259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
34262 \begin_layout Standard
34265 MSC12xx Programming with SDCC
34270 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
34273 \begin_layout Standard
34276 \begin_inset LatexCommand url
34277 target "http://focus.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=sbaa109&fileType=pdf"
34294 \begin_layout Section
34298 \begin_layout Standard
34299 Some questions answered, some pointers given - it might be time to in turn
34307 \begin_layout Itemize
34308 can you solve your project with the selected microcontroller? Would you
34309 find out early or rather late that your target is too small/slow/whatever?
34310 Can you switch to a slightly better device if it doesn't fit?
34313 \begin_layout Itemize
34314 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
34315 and/or another programming language be more adequate? Would an operating
34316 system on the target device help?
34319 \begin_layout Itemize
34320 if you solved the problem, will the marketing department be happy?
34323 \begin_layout Itemize
34324 if the marketing department is happy, will customers be happy?
34327 \begin_layout Itemize
34328 if you're the project manager, marketing department and maybe even the customer
34329 in one person, have you tried to see the project from the outside?
34332 \begin_layout Itemize
34333 is the project done if you think it is done? Or is just that other interface/pro
34334 tocol/feature/configuration/option missing? How about website, manual(s),
34335 internationali(z|s)ation, packaging, labels, 2nd source for components,
34336 electromagnetic compatability/interference, documentation for production,
34337 production test software, update mechanism, patent issues?
34340 \begin_layout Itemize
34341 is your project adequately positioned in that magic triangle: fame, fortune,
34345 \begin_layout Standard
34346 Maybe not all answers to these questions are known and some answers may
34351 , nevertheless knowing these questions may help you to avoid burnout
34355 \begin_layout Standard
34356 burnout is bad for electronic devices, programmers and motorcycle tyres
34362 Chances are you didn't want to hear some of them...
34365 \begin_layout Chapter
34367 \begin_inset LatexCommand index
34375 \begin_layout Standard
34376 SDCC has grown to be a large project.
34377 The compiler alone (without the preprocessor, assembler and linker) is
34378 well over 150,000 lines of code (blank stripped).
34379 The open source nature of this project is a key to its continued growth
34381 You gain the benefit and support of many active software developers and
34383 Is SDCC perfect? No, that's why we need your help.
34384 The developers take pride in fixing reported bugs.
34385 You can help by reporting the bugs and helping other SDCC users.
34386 There are lots of ways to contribute, and we encourage you to take part
34387 in making SDCC a great software package.
34391 \begin_layout Standard
34392 The SDCC project is hosted on the SDCC sourceforge site at
34393 \begin_inset LatexCommand htmlurl
34394 target "http://sourceforge.net/projects/sdcc"
34399 You'll find the complete set of mailing lists
34400 \begin_inset LatexCommand index
34401 name "Mailing list(s)"
34405 , forums, bug reporting system, patch submission
34406 \begin_inset LatexCommand index
34407 name "Patch submission"
34412 \begin_inset LatexCommand index
34417 area and Subversion code repository
34418 \begin_inset LatexCommand index
34419 name "Subversion code repository"
34426 \begin_layout Section
34428 \begin_inset LatexCommand index
34429 name "Bug reporting"
34434 \begin_inset LatexCommand index
34435 name "Reporting bugs"
34442 \begin_layout Standard
34443 The recommended way of reporting bugs is using the infrastructure of the
34445 You can follow the status of bug reports there and have an overview about
34449 \begin_layout Standard
34450 Bug reports are automatically forwarded to the developer mailing list and
34451 will be fixed ASAP.
34452 When reporting a bug, it is very useful to include a small test program
34453 (the smaller the better) which reproduces the problem.
34454 If you can isolate the problem by looking at the generated assembly code,
34455 this can be very helpful.
34456 Compiling your program with the -
34460 \begin_layout Standard
34470 \begin_inset LatexCommand index
34471 name "-\\/-dumpall"
34475 option can sometimes be useful in locating optimization problems.
34476 When reporting a bug please make sure you:
34479 \begin_layout Enumerate
34480 Attach the code you are compiling with SDCC.
34484 \begin_layout Enumerate
34485 Specify the exact command you use to run SDCC, or attach your Makefile.
34489 \begin_layout Enumerate
34490 Specify the SDCC version (type "
34496 "), your platform, and operating system.
34500 \begin_layout Enumerate
34501 Provide an exact copy of any error message or incorrect output.
34505 \begin_layout Enumerate
34506 Put something meaningful in the subject of your message.
34509 \begin_layout Standard
34510 Please attempt to include these 5 important parts, as applicable, in all
34511 requests for support or when reporting any problems or bugs with SDCC.
34512 Though this will make your message lengthy, it will greatly improve your
34513 chance that SDCC users and developers will be able to help you.
34514 Some SDCC developers are frustrated by bug reports without code provided
34515 that they can use to reproduce and ultimately fix the problem, so please
34516 be sure to provide sample code if you are reporting a bug!
34519 \begin_layout Standard
34520 Please have a short check that you are using a recent version of SDCC and
34521 the bug is not yet known.
34522 This is the link for reporting bugs:
34523 \begin_inset LatexCommand htmlurl
34524 target "http://sourceforge.net/tracker/?group_id=599&atid=100599"
34529 With SDCC on average having more than 200 downloads
34530 \begin_inset LatexCommand index
34535 on sourceforge per day
34539 \begin_layout Standard
34540 220 daily downloads on average Jan-Sept 2006 and about 150 daily downloads
34541 between 2002 and 2005.
34542 This does not include other methods of distribution.
34547 there must be some users.
34548 So it's not exactly easy to find a new bug.
34549 If you find one we need it:
34551 reporting bugs is good
34556 \begin_layout Section
34557 Requesting Features
34558 \begin_inset LatexCommand label
34559 name "sub:Requesting-Features"
34564 \begin_inset LatexCommand index
34565 name "Feature request"
34570 \begin_inset LatexCommand index
34571 name "Requesting features"
34578 \begin_layout Standard
34579 Like bug reports feature requests are forwarded to the developer mailing
34581 This is the link for requesting features:
34582 \begin_inset LatexCommand htmlurl
34583 target "http://sourceforge.net/tracker/?group_id=599&atid=350599"
34590 \begin_layout Section
34594 \begin_layout Standard
34595 Like bug reports contributed patches are forwarded to the developer mailing
34597 This is the link for submitting patches
34598 \begin_inset LatexCommand index
34599 name "Patch submission"
34604 \begin_inset LatexCommand url
34605 target "http://sourceforge.net/tracker/?group_id=599&atid=300599"
34612 \begin_layout Standard
34613 You need to specify some parameters to the
34617 command for the patches to be useful.
34618 If you modified more than one file a patch created f.e.
34623 \begin_inset Quotes sld
34626 diff -Naur unmodified_directory modified_directory >my_changes.patch
34627 \begin_inset Quotes srd
34633 will be fine, otherwise
34637 \begin_inset Quotes sld
34640 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
34641 \begin_inset Quotes srd
34650 \begin_layout Section
34654 \begin_layout Standard
34655 These links should take you directly to the
34656 \begin_inset LatexCommand url
34657 name "Mailing lists"
34658 target "http://sourceforge.net/mail/?group_id=599"
34666 \begin_layout Standard
34667 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
34668 automated messages (mid 2003)
34674 \begin_inset LatexCommand url
34676 target "http://sourceforge.net/forum/?group_id=599"
34681 \begin_inset LatexCommand index
34682 name "Mailing list(s)"
34686 and forums are archived and searchable so if you are lucky someone already
34687 had a similar problem.
34688 While mails to the lists themselves are delivered promptly their web front
34689 end on sourceforge sometimes shows a severe time lag (up to several weeks),
34690 if you're seriously using SDCC please consider subscribing to the lists.
34693 \begin_layout Section
34697 \begin_layout Standard
34698 You can follow the status of the Subversion version
34699 \begin_inset LatexCommand index
34704 of SDCC by watching the Changelog
34705 \begin_inset LatexCommand index
34710 in the Subversion repository
34713 \begin_inset LatexCommand htmlurl
34714 target "http://sdcc.svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog"
34721 \begin_layout Section
34722 Subversion Source Code Repository
34725 \begin_layout Standard
34735 \begin_layout Standard
34749 or the filenames of the snapshot versions of SDCC include date and its
34751 \begin_inset LatexCommand index
34752 name "Subversion code repository"
34757 Subversion allows to download the source of recent or previous versions
34759 \begin_inset LatexCommand url
34760 target "http://sourceforge.net/svn/?group_id=599"
34764 (by number or by date).
34765 An on-line source code browser and detailled instructions are also available
34767 SDCC versions starting from 1999 up to now are available (currently the
34768 versions prior to the conversion from cvs
34769 \begin_inset LatexCommand index
34770 name "cvs|see{Subversion}"
34774 to Subversion (April 2006) are either by accessible by Subversion or by
34778 \begin_layout Section
34780 \begin_inset LatexCommand index
34781 name "Release policy"
34788 \begin_layout Standard
34789 Historically there often were long delays between official releases and
34790 the sourceforge download area tends to get not updated at all.
34791 Excuses in the past might have referred to problems with live range analysis,
34792 but as this was fixed a while ago, the current problem is that another
34793 excuse has to be found.
34794 Kidding aside, we have to get better there! On the other hand there are
34795 daily snapshots available at
34796 \begin_inset LatexCommand htmlurl
34798 target "http://sdcc.sourceforge.net/snap.php"
34802 , and you can always build the very last version (hopefully with many bugs
34803 fixed, and features added) from the source code available at
34804 \begin_inset LatexCommand htmlurl
34806 target "http://sdcc.sourceforge.net/snap.php#Source"
34812 \begin_inset LatexCommand index
34818 \begin_inset LatexCommand index
34824 \begin_inset LatexCommand url
34825 target "http://sdcc.wiki.sourceforge.net/"
34829 also holds some information about past and future releases.
34832 \begin_layout Section
34834 \begin_inset LatexCommand index
34842 \begin_layout Standard
34843 You'll find some small examples in the directory
34845 sdcc/device/examples/.
34848 More examples and libraries are available at
34850 The SDCC Open Knowledge Resource
34851 \begin_inset LatexCommand url
34852 target "http://sdccokr.dl9sec.de/"
34859 \begin_inset LatexCommand url
34860 target "http://www.pjrc.com/tech/8051/"
34867 \begin_layout Standard
34868 \begin_inset Note Note
34871 \begin_layout Standard
34872 I did insert a reference to Paul's web site here although it seems rather
34873 dedicated to a specific 8032 board (I think it's okay because it f.e.
34874 shows LCD/Harddisc interface and has a free 8051 monitor.
34875 Independent 8032 board vendors face hard competition of heavily subsidized
34876 development boards anyway).
34879 \begin_layout Standard
34880 Maybe we should include some links to real world applications.
34881 Preferably pointer to pointers (one for each architecture) so this stays
34890 \begin_layout Section
34892 \begin_inset LatexCommand label
34893 name "sec:Quality-control"
34898 \begin_inset LatexCommand index
34899 name "Quality control"
34906 \begin_layout Standard
34907 The compiler is passed through snaphot build compile and build checks.
34913 \begin_inset LatexCommand index
34914 name "Regression test"
34918 check that SDCC itself compiles flawlessly on several host platforms (i386,
34919 Opteron, 64 bit Alpha, ppc64, Mac OS X on ppc and i386, Solaris on Sparc)
34920 and checks the quality of the code generated by SDCC by running the code
34921 for several target platforms through simulators.
34922 The regression test suite comprises more than 100 files which expand to
34923 more than 500 test cases which include more than 4500 tests.
34924 The results of these tests are published daily on SDCC's snapshot page
34925 (click on the red or green symbols on the right side of
34926 \begin_inset LatexCommand url
34927 target "http://sdcc.sourceforge.net/snap.php"
34934 \begin_layout Standard
34935 There is a separate document
34938 \begin_inset LatexCommand index
34946 \begin_inset LatexCommand url
34947 target "http://sdcc.sourceforge.net/doc/test_suite_spec.pdf"
34951 about the regression test suite.
34954 \begin_layout Standard
34955 You'll find the test code in the directory
34957 sdcc/support/regression
34960 You can run these tests manually by running
34964 in this directory (or f.e.
34969 \begin_inset Quotes sld
34973 \begin_inset Quotes srd
34979 if you don't want to run the complete tests).
34980 The test code might also be interesting if you want to look for examples
34981 \begin_inset LatexCommand index
34986 checking corner cases of SDCC or if you plan to submit patches
34987 \begin_inset LatexCommand index
34988 name "Patch submission"
34995 \begin_layout Standard
34996 The PIC14 port uses a different set of regression tests
34997 \begin_inset LatexCommand index
34998 name "Regression test (PIC14)"
35002 , you'll find them in the directory
35004 sdcc/src/regression
35009 \begin_layout Section
35010 Use of SDCC in Education
35013 \begin_layout Standard
35022 \begin_layout Standard
35023 the phrase "use in education" might evoke the association "
35027 fit for use in education".
35028 This connotation is not intended but nevertheless risked as the licensing
35029 of SDCC makes it difficult to offer educational discounts
35035 If your rationales are to:
35038 \begin_layout Enumerate
35039 give students a chance to understand the
35043 steps of code generation
35046 \begin_layout Enumerate
35047 have a curriculum that can be extended for years.
35048 Then you could use an fpga board as target and your curriculum will seamlessly
35049 extend from logic synthesis (
35050 \begin_inset LatexCommand url
35051 name "http://www.opencores.org"
35052 target "opencores.org"
35057 \begin_inset LatexCommand url
35059 target "http://www.oregano.at/ip/ip01.htm"
35063 ), over assembly programming, to C to FPGA compilers (
35064 \begin_inset LatexCommand url
35066 target "http://sf.net/projects/fpgac"
35073 \begin_layout Enumerate
35074 be able to insert excursions about skills like using a revision control
35075 system, submitting/applying patches, using a type-setting (as opposed to
35076 word-processing) engine LyX/LaTeX, using
35077 \begin_inset LatexCommand url
35079 target "http://www.sf.net"
35084 \begin_inset LatexCommand url
35086 target "http://en.wikipedia.org/wiki/Netiquette"
35090 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
35091 Source Software, CPU simulation, compiler regression tests
35092 \begin_inset LatexCommand index
35093 name "Regression test"
35100 And if there should be a shortage of ideas then you can always point students
35101 to the ever-growing feature request list
35102 \begin_inset LatexCommand htmlurl
35103 target "http://sourceforge.net/tracker/?group_id=599&atid=350599"
35110 \begin_layout Enumerate
35111 not tie students to a specific host platform and instead allow them to use
35116 choice (among them Alpha, i386, i386_64, Mac OS X, Mips, Sparc, Windows
35118 \begin_inset LatexCommand url
35120 target "http://www.laptop.org"
35127 \begin_layout Enumerate
35128 not encourage students to use illegal copies of educational software
35131 \begin_layout Enumerate
35132 be immune to licensing/availability/price changes of the chosen tool chain
35135 \begin_layout Enumerate
35136 be able to change to a new target platform without having to adopt a new
35140 \begin_layout Enumerate
35141 have complete control over and insight into the tool chain
35144 \begin_layout Enumerate
35145 make your students aware about the pros and cons of open source software
35149 \begin_layout Enumerate
35150 give back to the public as you are probably at least partially publicly
35154 \begin_layout Enumerate
35155 give students a chance to publicly prove their skills and to possibly
35156 see a world wide impact
35159 \begin_layout Standard
35160 then SDCC is probably among the first choices.
35161 Well, probably SDCC might be the only choice.
35166 \begin_layout Chapter
35167 SDCC Technical Data
35170 \begin_layout Section
35172 \begin_inset LatexCommand index
35173 name "Optimizations"
35180 \begin_layout Standard
35181 SDCC performs a host of standard optimizations in addition to some MCU specific
35186 \begin_layout Subsection
35187 Sub-expression Elimination
35188 \begin_inset LatexCommand index
35189 name "Subexpression elimination"
35196 \begin_layout Standard
35197 The compiler does local and
35216 \begin_layout Verse
35224 \begin_layout Standard
35225 will be translated to
35228 \begin_layout Verse
35238 \begin_layout Standard
35239 Some subexpressions are not as obvious as the above example, e.g.:
35242 \begin_layout Verse
35250 \begin_layout Standard
35251 In this case the address arithmetic a->b[i] will be computed only once;
35252 the equivalent code in C would be.
35255 \begin_layout Verse
35265 \begin_layout Standard
35266 The compiler will try to keep these temporary variables in registers.
35269 \begin_layout Subsection
35270 Dead-Code Elimination
35271 \begin_inset LatexCommand index
35272 name "Dead-code elimination"
35279 \begin_layout Verse
35294 i = 1; \InsetSpace ~
35303 global = 1;\InsetSpace ~
35317 global = 3;\InsetSpace ~
35323 \begin_layout Standard
35327 \begin_layout Verse
35343 \begin_layout Subsection
35345 \begin_inset LatexCommand index
35346 name "Copy propagation"
35353 \begin_layout Verse
35377 \begin_layout Standard
35381 \begin_layout Verse
35405 \begin_layout Standard
35406 Note: the dead stores created by this copy propagation will be eliminated
35407 by dead-code elimination.
35410 \begin_layout Subsection
35412 \begin_inset LatexCommand index
35413 name "Loop optimization"
35418 \begin_inset LatexCommand label
35419 name "sub:Loop-Optimizations"
35426 \begin_layout Standard
35427 Two types of loop optimizations are done by SDCC
35435 of loop induction variables.
35436 In addition to the strength reduction the optimizer marks the induction
35437 variables and the register allocator tries to keep the induction variables
35438 in registers for the duration of the loop.
35439 Because of this preference of the register allocator
35440 \begin_inset LatexCommand index
35441 name "Register allocation"
35445 , loop induction optimization causes an increase in register pressure, which
35446 may cause unwanted spilling of other temporary variables into the stack
35447 \begin_inset LatexCommand index
35453 The compiler will generate a warning message when it is forced to allocate
35454 extra space either on the stack or data space.
35455 If this extra space allocation is undesirable then induction optimization
35456 can be eliminated either for the entire source file (with -
35460 \begin_layout Standard
35469 -noinduction option) or for a given function only using #pragma\InsetSpace ~
35471 \begin_inset LatexCommand index
35472 name "\\#pragma noinduction"
35483 \begin_layout Verse
35486 for (i = 0 ; i < 100 ; i ++)
35495 \begin_layout Standard
35499 \begin_layout Verse
35504 for (i = 0; i < 100; i++)
35513 \begin_layout Standard
35514 As mentioned previously some loop invariants are not as apparent, all static
35515 address computations are also moved out of the loop.
35520 \begin_inset LatexCommand index
35521 name "Strength reduction"
35525 , this optimization substitutes an expression by a cheaper expression:
35528 \begin_layout Verse
35531 for (i=0;i < 100; i++)
35540 \begin_layout Standard
35544 \begin_layout Verse
35551 for (i=0;i< 100;i++) {
35557 ar[itemp1] = itemp2;
35575 \begin_layout Standard
35576 The more expensive multiplication
35577 \begin_inset LatexCommand index
35578 name "Multiplication"
35582 is changed to a less expensive addition.
35585 \begin_layout Subsection
35587 \begin_inset LatexCommand index
35588 name "Loop reversing"
35595 \begin_layout Standard
35596 This optimization is done to reduce the overhead of checking loop boundaries
35597 for every iteration.
35598 Some simple loops can be reversed and implemented using a
35599 \begin_inset Quotes eld
35602 decrement and jump if not zero
35603 \begin_inset Quotes erd
35607 SDCC checks for the following criterion to determine if a loop is reversible
35608 (note: more sophisticated compilers use data-dependency analysis to make
35609 this determination, SDCC uses a more simple minded analysis).
35612 \begin_layout Itemize
35613 The 'for' loop is of the form
35619 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
35629 \begin_layout Itemize
35630 The <for body> does not contain
35631 \begin_inset Quotes eld
35635 \begin_inset Quotes erd
35639 \begin_inset Quotes erd
35645 \begin_layout Itemize
35646 All goto's are contained within the loop.
35649 \begin_layout Itemize
35650 No function calls within the loop.
35653 \begin_layout Itemize
35654 The loop control variable <sym> is not assigned any value within the loop
35657 \begin_layout Itemize
35658 The loop control variable does NOT participate in any arithmetic operation
35662 \begin_layout Itemize
35663 There are NO switch statements in the loop.
35666 \begin_layout Subsection
35667 Algebraic Simplifications
35670 \begin_layout Standard
35671 SDCC does numerous algebraic simplifications, the following is a small sub-set
35672 of these optimizations.
35675 \begin_layout Verse
35678 i = j + 0;\InsetSpace ~
35682 /* changed to: */\InsetSpace ~
35688 i /= 2;\InsetSpace ~
35695 /* changed to: */\InsetSpace ~
35702 = j - j;\InsetSpace ~
35706 /* changed to: */\InsetSpace ~
35712 i = j / 1;\InsetSpace ~
35716 /* changed to: */\InsetSpace ~
35723 \begin_layout Standard
35724 Note the subexpressions
35725 \begin_inset LatexCommand index
35726 name "Subexpression"
35730 given above are generally introduced by macro expansions or as a result
35731 of copy/constant propagation.
35734 \begin_layout Subsection
35735 'switch' Statements
35736 \begin_inset LatexCommand label
35737 name "sub:'switch'-Statements"
35742 \begin_inset LatexCommand index
35743 name "switch statement"
35750 \begin_layout Standard
35751 SDCC can optimize switch statements to jump tables
35752 \begin_inset LatexCommand index
35758 It makes the decision based on an estimate of the generated code size.
35759 SDCC is quite liberal in the requirements for jump table generation:
35762 \begin_layout Itemize
35763 The labels need not be in order, and the starting number need not be one
35764 or zero, the case labels are in numerical sequence or not too many case
35765 labels are missing.
35769 \begin_layout Verse
35772 switch(i) {\InsetSpace ~
35803 case 4: ...\InsetSpace ~
35835 case 5: ...\InsetSpace ~
35867 case 3: ...\InsetSpace ~
35898 case 6: ...\InsetSpace ~
35930 case 7: ...\InsetSpace ~
35962 case 8: ...\InsetSpace ~
35994 case 9: ...\InsetSpace ~
36026 case 10: ...\InsetSpace ~
36057 case 11: ...\InsetSpace ~
36124 \begin_layout Standard
36125 Both the above switch statements will be implemented using a jump-table.
36126 The example to the right side is slightly more efficient as the check for
36127 the lower boundary of the jump-table is not needed.
36131 \begin_layout Itemize
36132 The number of case labels is not larger than supported by the target architectur
36136 \begin_layout Itemize
36137 If the case labels are not in numerical sequence ('gaps' between cases)
36138 SDCC checks whether a jump table with additionally inserted dummy cases
36139 is still attractive.
36143 \begin_layout Itemize
36144 If the starting number is not zero and a check for the lower boundary of
36145 the jump-table can thus be eliminated SDCC might insert dummy cases 0,
36150 \begin_layout Standard
36151 Switch statements which have large gaps in the numeric sequence or those
36152 that have too many case labels can be split into more than one switch statement
36153 for efficient code generation, e.g.:
36156 \begin_layout Verse
36234 \begin_layout Standard
36235 If the above switch statement is broken down into two switch statements
36238 \begin_layout Verse
36281 \begin_layout Standard
36285 \begin_layout Verse
36328 \begin_layout Standard
36329 then both the switch statements will be implemented using jump-tables whereas
36330 the unmodified switch statement will not be.
36333 \begin_layout Standard
36334 \begin_inset Note Note
36337 \begin_layout Standard
36338 There might be reasons which SDCC cannot know about to either favour or
36339 not favour jump tables.
36340 If the target system has to be as quick for the last switch case as for
36341 the first (pro jump table), or if the switch argument is known to be zero
36342 in the majority of the cases (contra jump table).
36350 \begin_layout Standard
36351 The pragma nojtbound
36352 \begin_inset LatexCommand index
36353 name "\\#pragma nojtbound"
36357 can be used to turn off checking the
36370 It has no effect if a default label is supplied.
36371 Use of this pragma is dangerous: if the switch
36372 \begin_inset LatexCommand index
36373 name "switch statement"
36377 argument is not matched by a case statement the processor will happily
36381 \begin_layout Subsection
36382 Bit-shifting Operations
36383 \begin_inset LatexCommand index
36384 name "Bit shifting"
36391 \begin_layout Standard
36392 Bit shifting is one of the most frequently used operation in embedded programmin
36394 SDCC tries to implement bit-shift operations in the most efficient way
36398 \begin_layout Verse
36411 \begin_layout Standard
36412 generates the following code:
36415 \begin_layout Verse
36430 \begin_layout Standard
36431 In general SDCC will never setup a loop if the shift count is known.
36435 \begin_layout Verse
36448 \begin_layout Standard
36452 \begin_layout Verse
36476 \begin_layout Subsection
36478 \begin_inset LatexCommand index
36479 name "Bit rotation"
36486 \begin_layout Standard
36487 A special case of the bit-shift operation is bit rotation
36488 \begin_inset LatexCommand index
36489 name "rotating bits"
36493 , SDCC recognizes the following expression to be a left bit-rotation:
36496 \begin_layout Verse
36504 char i;\InsetSpace ~
36515 /* unsigned is needed for rotation */
36520 i = ((i << 1) | (i >> 7));
36529 \begin_layout Standard
36530 will generate the following code:
36533 \begin_layout Verse
36550 \begin_layout Standard
36551 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
36552 ns of this case will also be recognized as bit-rotation, i.e.:
36555 \begin_layout Verse
36558 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
36561 \begin_layout Subsection
36562 Nibble and Byte Swapping
36565 \begin_layout Standard
36566 Other special cases of the bit-shift operations are nibble or byte swapping
36567 \begin_inset LatexCommand index
36568 name "swapping nibbles/bytes"
36572 , SDCC recognizes the following expressions:
36575 \begin_layout Verse
36596 i = ((i << 4) | (i >> 4));
36602 j = ((j << 8) | (j >> 8));
36605 \begin_layout Standard
36606 and generates a swap instruction for the nibble swapping
36607 \begin_inset LatexCommand index
36608 name "Nibble swapping"
36612 or move instructions for the byte swapping
36613 \begin_inset LatexCommand index
36614 name "Byte swapping"
36620 \begin_inset Quotes sld
36624 \begin_inset Quotes srd
36627 example can be used to convert from little to big-endian or vice versa.
36628 If you want to change the endianness of a
36632 integer you have to cast to
36639 \begin_layout Standard
36640 Note that SDCC stores numbers in little-endian
36644 \begin_layout Standard
36645 Usually 8-bit processors don't care much about endianness.
36646 This is not the case for the standard 8051 which only has an instruction
36652 \begin_inset LatexCommand index
36657 -datapointer so little-endian is the more efficient byte order.
36663 \begin_inset LatexCommand index
36664 name "little-endian"
36669 \begin_inset LatexCommand index
36675 lowest order first).
36678 \begin_layout Subsection
36680 \begin_inset LatexCommand index
36681 name "Highest Order Bit"
36686 \begin_inset LatexCommand index
36687 name "Any Order Bit"
36694 \begin_layout Standard
36695 It is frequently required to obtain the highest order bit of an integral
36696 type (long, int, short or char types).
36697 Also obtaining any other order bit is not uncommon.
36698 SDCC recognizes the following expressions to yield the highest order bit
36699 and generates optimized code for it, e.g.:
36702 \begin_layout Verse
36713 unsigned char hob1, aob1;
36717 bit hob2, hob3, aob2,
36727 hob1 = (gint >> 15) & 1;
36731 hob2 = (gint >> 15) & 1;
36735 hob3 = gint & 0x8000;
36740 aob1 = (gint >> 9) & 1;
36744 aob2 = (gint >> 8) & 1;
36748 aob3 = gint & 0x0800;
36758 \begin_layout Standard
36759 will generate the following code:
36762 \begin_layout Verse
36793 000A E5*01\InsetSpace ~
36820 000C 23\InsetSpace ~
36851 000D 54 01\InsetSpace ~
36879 000F F5*02\InsetSpace ~
36934 0011 E5*01\InsetSpace ~
36962 0013 33\InsetSpace ~
36992 0014 92*00\InsetSpace ~
37048 0016 E5*01\InsetSpace ~
37075 0018 33\InsetSpace ~
37105 0019 92*01\InsetSpace ~
37161 001B E5*01\InsetSpace ~
37220 001E 54 01\InsetSpace ~
37247 0020 F5*03\InsetSpace ~
37303 0022 E5*01\InsetSpace ~
37330 0024 13\InsetSpace ~
37360 0025 92*02\InsetSpace ~
37416 0027 E5*01\InsetSpace ~
37471 002B 92*03\InsetSpace ~
37499 \begin_layout Standard
37500 Other variations of these cases however will
37505 They are standard C expressions, so I heartily recommend these be the only
37506 way to get the highest order bit, (it is portable).
37507 Of course it will be recognized even if it is embedded in other expressions,
37511 \begin_layout Verse
37514 xyz = gint + ((gint >> 15) & 1);
37517 \begin_layout Standard
37518 will still be recognized.
37521 \begin_layout Subsection
37523 \begin_inset LatexCommand index
37524 name "Higher Order Byte"
37528 / Higher Order Word
37529 \begin_inset LatexCommand index
37530 name "Higher Order Word"
37537 \begin_layout Standard
37538 It is also frequently required to obtain a higher order byte or word of
37539 a larger integral type (long, int or short types).
37540 SDCC recognizes the following expressions to yield the higher order byte
37541 or word and generates optimized code for it, e.g.:
37544 \begin_layout Verse
37549 unsigned long int glong;
37557 unsigned char hob1,
37562 unsigned int how1, how2;
37571 hob1 = (gint >> 8) & 0xFF;
37575 hob2 = glong >> 24;
37579 how1 = (glong >> 16) & 0xFFFF;
37594 \begin_layout Standard
37595 will generate the following code:
37598 \begin_layout Verse
37629 0037 85*01*06\InsetSpace ~
37651 _foo_hob1_1_1,(_gint + 1)
37682 003A 85*05*07\InsetSpace ~
37704 _foo_hob2_1_1,(_glong + 3)
37734 003D 85*04*08\InsetSpace ~
37757 _foo_how1_1_1,(_glong + 2)
37759 0040 85*05*09\InsetSpace ~
37784 0043 85*03*0A\InsetSpace ~
37806 _foo_how2_1_1,(_glong + 1)
37808 0046 85*04*0B\InsetSpace ~
37831 (_foo_how2_1_1 + 1),(_glong + 2)
37834 \begin_layout Standard
37835 Again, variations of these cases may
37840 They are standard C expressions, so I heartily recommend these be the only
37841 way to get the higher order byte/word, (it is portable).
37842 Of course it will be recognized even if it is embedded in other expressions,
37846 \begin_layout Verse
37849 xyz = gint + ((gint >> 8) & 0xFF);
37852 \begin_layout Standard
37853 will still be recognized.
37856 \begin_layout Subsection
37858 \begin_inset LatexCommand label
37859 name "sub:Peephole-Optimizer"
37864 \begin_inset LatexCommand index
37865 name "Peephole optimizer"
37872 \begin_layout Standard
37873 The compiler uses a rule based, pattern matching and re-writing mechanism
37874 for peep-hole optimization.
37879 a peep-hole optimizer by Christopher W.
37880 Fraser (cwfraser\InsetSpace ~
37883 A default set of rules are compiled into the compiler, additional rules
37884 may be added with the
37890 \begin_layout Standard
37900 \begin_inset LatexCommand index
37901 name "-\\/-peep-file"
37908 The rule language is best illustrated with examples.
37911 \begin_layout Verse
37933 \begin_layout Standard
37934 The above rule will change the following assembly
37935 \begin_inset LatexCommand index
37936 name "Assembler routines"
37943 \begin_layout Verse
37951 \begin_layout Standard
37955 \begin_layout Verse
37961 \begin_layout Standard
37962 Note: All occurrences of a
37966 (pattern variable) must denote the same string.
37967 With the above rule, the assembly sequence:
37970 \begin_layout Verse
37978 \begin_layout Standard
37979 will remain unmodified.
37983 Other special case optimizations may be added by the
37990 \begin_layout Standard
38003 some variants of the 8051 MCU
38004 \begin_inset LatexCommand index
38005 name "MCS51 variants"
38018 The following two rules will change all
38035 \begin_layout Verse
38038 replace { lcall %1 } by { acall %1 }
38040 replace { ljmp %1 } by { ajmp %1 }
38043 \begin_layout Standard
38044 (NOTE: from version 2.7.3 on, you can use option -
38050 \begin_layout Standard
38062 \begin_inset LatexCommand index
38063 name "-\\/-acall-ajmp"
38067 , which also takes care of aligning the interrupt vectors properly.)
38072 \begin_layout Standard
38075 inline-assembler code
38077 is also passed through the peep hole optimizer, thus the peephole optimizer
38078 can also be used as an assembly level macro expander.
38079 The rules themselves are MCU dependent whereas the rule language infra-structur
38080 e is MCU independent.
38081 Peephole optimization rules for other MCU can be easily programmed using
38086 The syntax for a rule is as follows:
38089 \begin_layout Verse
38092 rule := replace [ restart ] '{' <assembly sequence> '
38130 <assembly sequence> '
38148 '}' [if <functionName> ] '
38153 \begin_layout Standard
38154 <assembly sequence> := assembly instruction (each instruction including
38155 labels must be on a separate line).
38159 The optimizer will apply to the rules
38160 one by one from the top in the sequence of their appearance, it will terminate
38161 when all rules are exhausted.
38162 If the 'restart' option is specified, then the optimizer will start matching
38163 the rules again from the top, this option for a rule is expensive (performance)
38164 , it is intended to be used in situations where a transformation will trigger
38165 the same rule again.
38166 An example of this (not a good one, it has side effects) is the following
38170 \begin_layout Verse
38190 \begin_layout Standard
38191 Note that the replace pattern cannot be a blank, but can be a comment line.
38192 Without the 'restart' option only the innermost 'pop' 'push' pair would
38193 be eliminated, i.e.:
38196 \begin_layout Verse
38208 \begin_layout Standard
38212 \begin_layout Verse
38222 \begin_layout Standard
38227 the restart option the rule will be applied again to the resulting code
38228 and then all the pop-push pairs will be eliminated to yield:
38231 \begin_layout Verse
38239 \begin_layout Standard
38240 A conditional function can be attached to a rule.
38241 Attaching rules are somewhat more involved, let me illustrate this with
38245 \begin_layout Verse
38269 \begin_layout Standard
38270 The optimizer does a look-up of a function name table defined in function
38275 in the source file SDCCpeeph.c, with the name
38280 If it finds a corresponding entry the function is called.
38281 Note there can be no parameters specified for these functions, in this
38286 is crucial, since the function
38290 expects to find the label in that particular variable (the hash table containin
38291 g the variable bindings is passed as a parameter).
38292 If you want to code more such functions, take a close look at the function
38293 labelInRange and the calling mechanism in source file SDCCpeeph.c.
38294 Currently implemented are
38296 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
38297 24bitMode, portIsDS390, 24bitModeAndPortDS390
38306 \begin_layout Standard
38307 I know this whole thing is a little kludgey, but maybe some day we will
38308 have some better means.
38309 If you are looking at this file, you will see the default rules that are
38310 compiled into the compiler, you can add your own rules in the default set
38311 there if you get tired of specifying the -
38315 \begin_layout Standard
38327 \begin_layout Section
38329 \begin_inset LatexCommand index
38330 name "ANSI-compliance"
38335 \begin_inset LatexCommand label
38336 name "sub:ANSI-Compliance"
38343 \begin_layout Standard
38344 The latest publicly available version of the standard
38346 ISO/IEC 9899 - Programming languages - C
38348 should be available at:
38349 \begin_inset LatexCommand url
38350 target "http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899"
38359 \begin_layout Standard
38360 Deviations from the compliance:
38363 \begin_layout Itemize
38364 functions are not reentrant
38365 \begin_inset LatexCommand index
38370 unless explicitly declared as such or the
38376 \begin_layout Standard
38386 \begin_inset LatexCommand index
38387 name "-\\/-stack-auto"
38393 command line option is specified.
38396 \begin_layout Itemize
38398 \begin_inset LatexCommand index
38404 \begin_inset LatexCommand index
38409 cannot be assigned values directly, cannot be passed as function parameters
38410 or assigned to each other and cannot be a return value
38411 \begin_inset LatexCommand index
38412 name "return value"
38416 from a function, e.g.:
38420 \begin_layout Verse
38443 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
38468 s parms) /* invalid in SDCC although allowed in ANSI */
38490 return rets; /* is invalid in SDCC although allowed in ANSI */
38496 \begin_layout Itemize
38497 initialization of structure arrays must be fully braced.
38501 \begin_layout Verse
38504 struct s { char x } a[] = {1, 2};\InsetSpace ~
38509 /* invalid in SDCC */
38512 } a[] = {{1}, {2}}; /* OK */
38516 \begin_layout Itemize
38518 \begin_inset LatexCommand index
38519 name "long long (not supported)"
38524 \begin_inset LatexCommand index
38525 name "int (64 bit) (not supported)"
38532 \begin_layout Itemize
38534 \begin_inset LatexCommand index
38535 name "double (not supported)"
38539 ' precision floating point
38540 \begin_inset LatexCommand index
38541 name "Floating point support"
38548 \begin_layout Itemize
38550 \begin_inset LatexCommand index
38555 function declarations are NOT allowed.
38559 \begin_layout Verse
38562 foo(i,j) /* this old style of function declarations */
38564 int i,j; /* is valid
38565 in ANSI but not valid in SDCC */
38580 \begin_layout Itemize
38581 Most enhancements in C99 are not supported, e.g.:
38585 \begin_layout Verse
38595 i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
38599 \begin_layout Itemize
38600 But some have been added recently in SDCC 2.7.0.
38601 They must be considered alpha quality however.
38605 \begin_layout Verse
38610 \begin_inset LatexCommand index
38611 name "inline (not supported)"
38620 int increment (int a) { return a+1; } /* inlines the increment without function
38629 \begin_inset LatexCommand index
38630 name "inline (not supported)"
38639 p; /* accepted but ignored */
38643 \begin_layout Itemize
38644 Certain words that are valid identifiers in the standard may be reserved
38645 words in SDCC unless the
38651 \begin_layout Standard
38661 \begin_inset LatexCommand index
38662 name "-\\/-std-c89"
38674 \begin_layout Standard
38684 \begin_inset LatexCommand index
38685 name "-\\/-std-c99"
38691 command line options are used.
38692 These may include (depending on the selected processor): 'at', 'banked',
38693 'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
38694 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
38695 'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
38697 Compliant equivalents of these keywords are always available in a form
38698 that begin with two underscores
38699 \begin_inset LatexCommand index
38700 name "\\_\\_ (prefix for extended keywords)"
38705 '__data' instead of 'data'.
38708 \begin_layout Itemize
38709 Integer promotion of variable arguments is not performed if the argument
38710 is explicitly taypecasted unless the
38716 \begin_layout Standard
38726 \begin_inset LatexCommand index
38727 name "-\\/-std-c89"
38739 \begin_layout Standard
38749 \begin_inset LatexCommand index
38750 name "-\\/-std-c99"
38756 command line options are used.
38760 \begin_layout Verse
38763 void vararg_func (char *str, ...) { str; }
38780 u is promoted to int before
38785 * passing to function */
38789 vararg_func ("%c", c);
38796 argument u is not promoted to int,
38801 * it is passed as char to function
38807 --std-cXX is not defined;
38812 * is promoted to int before passing
38818 if --std-cXX is defined */
38822 vararg_func ("%bc", (char)u);
38828 \begin_layout Section
38829 Cyclomatic Complexity
38830 \begin_inset LatexCommand index
38831 name "Cyclomatic complexity"
38838 \begin_layout Standard
38839 Cyclomatic complexity of a function is defined as the number of independent
38840 paths the program can take during execution of the function.
38841 This is an important number since it defines the number test cases you
38842 have to generate to validate the function.
38843 The accepted industry standard for complexity number is 10, if the cyclomatic
38844 complexity reported by SDCC exceeds 10 you should think about simplification
38845 of the function logic.
38846 Note that the complexity level is not related to the number of lines of
38847 code in a function.
38848 Large functions can have low complexity, and small functions can have large
38854 SDCC uses the following formula to compute the complexity:
38859 \begin_layout Standard
38860 complexity = (number of edges in control flow graph) - (number of nodes
38861 in control flow graph) + 2;
38865 Having said that the industry standard is 10,
38866 you should be aware that in some cases it be may unavoidable to have a
38867 complexity level of less than 10.
38868 For example if you have switch statement with more than 10 case labels,
38869 each case label adds one to the complexity level.
38870 The complexity level is by no means an absolute measure of the algorithmic
38871 complexity of the function, it does however provide a good starting point
38872 for which functions you might look at for further optimization.
38875 \begin_layout Section
38876 Retargetting for other Processors
38879 \begin_layout Standard
38880 The issues for retargetting the compiler are far too numerous to be covered
38882 What follows is a brief description of each of the seven phases of the
38883 compiler and its MCU dependency.
38886 \begin_layout Itemize
38887 Parsing the source and building the annotated parse tree.
38888 This phase is largely MCU independent (except for the language extensions).
38889 Syntax & semantic checks are also done in this phase, along with some initial
38890 optimizations like back patching labels and the pattern matching optimizations
38891 like bit-rotation etc.
38894 \begin_layout Itemize
38895 The second phase involves generating an intermediate code which can be easy
38896 manipulated during the later phases.
38897 This phase is entirely MCU independent.
38898 The intermediate code generation assumes the target machine has unlimited
38899 number of registers, and designates them with the name iTemp.
38900 The compiler can be made to dump a human readable form of the code generated
38905 \begin_layout Standard
38917 \begin_layout Itemize
38918 This phase does the bulk of the standard optimizations and is also MCU independe
38920 This phase can be broken down into several sub-phases:
38924 Break down intermediate
38925 code (iCode) into basic blocks.
38927 Do control flow & data flow analysis on the
38930 Do local common subexpression elimination, then global subexpressio
38933 Dead code elimination
38937 If loop optimizations
38938 caused any changes then do 'global subexpression elimination' and 'dead
38939 code elimination' again.
38942 \begin_layout Itemize
38943 This phase determines the live-ranges; by live range I mean those iTemp
38944 variables defined by the compiler that still survive after all the optimization
38946 Live range analysis
38947 \begin_inset LatexCommand index
38948 name "Live range analysis"
38952 is essential for register allocation, since these computation determines
38953 which of these iTemps will be assigned to registers, and for how long.
38956 \begin_layout Itemize
38957 Phase five is register allocation.
38958 There are two parts to this process.
38962 The first part I call 'register packing'
38963 (for lack of a better term).
38964 In this case several MCU specific expression folding is done to reduce
38969 The second part is more MCU independent and deals with
38970 allocating registers to the remaining live ranges.
38971 A lot of MCU specific code does creep into this phase because of the limited
38972 number of index registers available in the 8051.
38975 \begin_layout Itemize
38976 The Code generation phase is (unhappily), entirely MCU dependent and very
38977 little (if any at all) of this code can be reused for other MCU.
38978 However the scheme for allocating a homogenized assembler operand for each
38979 iCode operand may be reused.
38982 \begin_layout Itemize
38983 As mentioned in the optimization section the peep-hole optimizer is rule
38984 based system, which can reprogrammed for other MCUs.
38987 \begin_layout Standard
38988 More information is available on SDCC Wiki
38989 \begin_inset LatexCommand index
38995 \begin_inset LatexCommand url
38996 target "http://sdcc.wiki.sourceforge.net/SDCC+internals+and+porting"
39000 ) and in the thread
39001 \begin_inset LatexCommand url
39002 target "http://sf.net/mailarchive/message.php?msg_id=13954144"
39009 \begin_layout Chapter
39011 \begin_inset LatexCommand index
39012 name "Compiler internals"
39019 \begin_layout Section
39020 The anatomy of the compiler
39021 \begin_inset LatexCommand label
39022 name "sub:The-anatomy-of"
39029 \begin_layout Standard
39032 This is an excerpt from an article published in Circuit Cellar Magazine
39041 It's a little outdated (the compiler is much more efficient now and user/develo
39042 per friendly), but pretty well exposes the guts of it all.
39048 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
39049 It is fairly easy to retarget for other 8-bit MCU.
39050 Here we take a look at some of the internals of the compiler.
39054 \begin_layout Paragraph*
39056 \begin_inset LatexCommand index
39064 \begin_layout Standard
39065 Parsing the input source file and creating an AST (Annotated Syntax Tree
39066 \begin_inset LatexCommand index
39067 name "Annotated syntax tree"
39072 This phase also involves propagating types (annotating each node of the
39073 parse tree with type information) and semantic analysis.
39074 There are some MCU specific parsing rules.
39075 For example the storage classes, the extended storage classes are MCU specific
39076 while there may be a xdata storage class for 8051 there is no such storage
39077 class for z80 or Atmel AVR.
39078 SDCC allows MCU specific storage class extensions, i.e.
39079 xdata will be treated as a storage class specifier when parsing 8051 C
39080 code but will be treated as a C identifier when parsing z80 or ATMEL AVR
39084 \begin_layout Paragraph*
39086 \begin_inset LatexCommand index
39094 \begin_layout Standard
39095 Intermediate code generation.
39096 In this phase the AST is broken down into three-operand form (iCode).
39097 These three operand forms are represented as doubly linked lists.
39098 ICode is the term given to the intermediate form generated by the compiler.
39099 ICode example section shows some examples of iCode generated for some simple
39100 C source functions.
39103 \begin_layout Paragraph*
39105 \begin_inset LatexCommand index
39106 name "Optimizations"
39113 \begin_layout Standard
39114 Bulk of the target independent optimizations is performed in this phase.
39115 The optimizations include constant propagation, common sub-expression eliminati
39116 on, loop invariant code movement, strength reduction of loop induction variables
39117 and dead-code elimination.
39120 \begin_layout Paragraph*
39121 Live range analysis
39122 \begin_inset LatexCommand index
39123 name "Live range analysis"
39130 \begin_layout Standard
39131 During intermediate code generation phase, the compiler assumes the target
39132 machine has infinite number of registers and generates a lot of temporary
39134 The live range computation determines the lifetime of each of these compiler-ge
39135 nerated temporaries.
39136 A picture speaks a thousand words.
39137 ICode example sections show the live range annotations for each of the
39139 It is important to note here, each iCode is assigned a number in the order
39140 of its execution in the function.
39141 The live ranges are computed in terms of these numbers.
39142 The from number is the number of the iCode which first defines the operand
39143 and the to number signifies the iCode which uses this operand last.
39146 \begin_layout Paragraph*
39147 Register Allocation
39148 \begin_inset LatexCommand index
39149 name "Register allocation"
39156 \begin_layout Standard
39157 The register allocation determines the type and number of registers needed
39159 In most MCUs only a few registers can be used for indirect addressing.
39160 In case of 8051 for example the registers R0 & R1 can be used to indirectly
39161 address the internal ram and DPTR to indirectly address the external ram.
39162 The compiler will try to allocate the appropriate register to pointer variables
39164 ICode example section shows the operands annotated with the registers assigned
39166 The compiler will try to keep operands in registers as much as possible;
39167 there are several schemes the compiler uses to do achieve this.
39168 When the compiler runs out of registers the compiler will check to see
39169 if there are any live operands which is not used or defined in the current
39170 basic block being processed, if there are any found then it will push that
39171 operand and use the registers in this block, the operand will then be popped
39172 at the end of the basic block.
39176 \begin_layout Standard
39177 There are other MCU specific considerations in this phase.
39178 Some MCUs have an accumulator; very short-lived operands could be assigned
39179 to the accumulator instead of a general-purpose register.
39182 \begin_layout Paragraph*
39186 \begin_layout Standard
39187 Figure II gives a table of iCode
39188 \begin_inset LatexCommand index
39193 operations supported by the compiler.
39194 The code generation involves translating these operations into corresponding
39195 assembly code for the processor.
39196 This sounds overly simple but that is the essence of code generation.
39197 Some of the iCode operations are generated on a MCU specific manner for
39198 example, the z80 port does not use registers to pass parameters so the
39199 SEND and RECV iCode operations will not be generated, and it also does
39200 not support JUMPTABLES.
39206 \begin_layout Standard
39210 \begin_inset Tabular
39211 <lyxtabular version="3" rows="39" columns="4">
39212 <features islongtable="true" headBottomDL="true">
39213 <column alignment="block" valignment="top" leftline="true" width="13col%">
39214 <column alignment="left" valignment="top" leftline="true" width="13col%">
39215 <column alignment="block" valignment="top" leftline="true" width="22col%">
39216 <column alignment="block" valignment="top" leftline="true" rightline="true" width="40col%">
39217 <row topline="true" bottomline="true" endhead="true">
39218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39221 \begin_layout Standard
39227 \begin_inset LatexCommand index
39237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39240 \begin_layout Standard
39248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39251 \begin_layout Standard
39259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39262 \begin_layout Standard
39271 <row topline="true">
39272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39275 \begin_layout Standard
39283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39286 \begin_layout Standard
39289 IC_LEFT() IC_RESULT()
39294 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39297 \begin_layout Standard
39305 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39308 \begin_layout Standard
39311 IC_RESULT = ! IC_LEFT;
39317 <row topline="true">
39318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39321 \begin_layout Standard
39329 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39332 \begin_layout Standard
39335 IC_LEFT() IC_RESULT()
39340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39343 \begin_layout Standard
39346 Bitwise complement of
39351 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39354 \begin_layout Standard
39357 IC_RESULT = ~IC_LEFT;
39363 <row topline="true">
39364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39367 \begin_layout Standard
39375 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39378 \begin_layout Standard
39381 IC_LEFT() IC_RESULT()
39386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39389 \begin_layout Standard
39392 Rotate right with carry
39397 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39400 \begin_layout Standard
39403 IC_RESULT = (IC_LEFT << 1) | (IC_LEFT >> (sizeof(IC_LEFT)*8-1));
39409 <row topline="true">
39410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39413 \begin_layout Standard
39421 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39424 \begin_layout Standard
39427 IC_LEFT() IC_RESULT()
39432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39435 \begin_layout Standard
39438 Rotate left with carry
39443 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39446 \begin_layout Standard
39449 IC_RESULT = (IC_LEFT << (sizeof(LC_LEFT)*8-1) ) | (IC_LEFT >> 1);
39455 <row topline="true">
39456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39459 \begin_layout Standard
39467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39470 \begin_layout Standard
39473 IC_LEFT() IC_RESULT()
39478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39481 \begin_layout Standard
39484 Get the highest order bit of IC_LEFT
39489 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39492 \begin_layout Standard
39495 IC_RESULT = (IC_LEFT >> (sizeof(IC_LEFT)*8 -1));
39501 <row topline="true">
39502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39505 \begin_layout Standard
39513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39516 \begin_layout Standard
39519 IC_LEFT() IC_RESULT()
39524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39527 \begin_layout Standard
39535 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39538 \begin_layout Standard
39541 IC_RESULT = - IC_LEFT;
39547 <row topline="true">
39548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39551 \begin_layout Standard
39559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39562 \begin_layout Standard
39570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39573 \begin_layout Standard
39576 Push the operand into stack
39581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39584 \begin_layout Standard
39593 <row topline="true">
39594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39597 \begin_layout Standard
39605 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39608 \begin_layout Standard
39616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39619 \begin_layout Standard
39622 Pop the operand from the stack
39627 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39630 \begin_layout Standard
39639 <row topline="true">
39640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39643 \begin_layout Standard
39651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39654 \begin_layout Standard
39657 IC_LEFT() IC_RESULT()
39662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39665 \begin_layout Standard
39668 Call the function represented by IC_LEFT
39673 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39676 \begin_layout Standard
39679 IC_RESULT = IC_LEFT();
39685 <row topline="true">
39686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39689 \begin_layout Standard
39697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39700 \begin_layout Standard
39703 IC_LEFT() IC_RESULT()
39708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39711 \begin_layout Standard
39714 Call via function pointer
39719 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39722 \begin_layout Standard
39725 IC_RESULT = (*IC_LEFT)();
39731 <row topline="true">
39732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39735 \begin_layout Standard
39743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39746 \begin_layout Standard
39754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39757 \begin_layout Standard
39760 Return the value in operand IC_LEFT
39765 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39768 \begin_layout Standard
39777 <row topline="true">
39778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39781 \begin_layout Standard
39789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39792 \begin_layout Standard
39800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39803 \begin_layout Standard
39811 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39814 \begin_layout Standard
39823 <row topline="true">
39824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39827 \begin_layout Standard
39835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39838 \begin_layout Standard
39846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39849 \begin_layout Standard
39857 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39860 \begin_layout Standard
39869 <row topline="true">
39870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39873 \begin_layout Standard
39881 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39884 \begin_layout Standard
39887 IC_LEFT() IC_RIGHT() IC_RESULT()
39892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39895 \begin_layout Standard
39903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39906 \begin_layout Standard
39909 IC_RESULT = IC_LEFT + IC_RIGHT
39915 <row topline="true">
39916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39919 \begin_layout Standard
39927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39930 \begin_layout Standard
39933 IC_LEFT() IC_RIGHT() IC_RESULT()
39938 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39941 \begin_layout Standard
39949 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39952 \begin_layout Standard
39955 IC_RESULT = IC_LEFT - IC_RIGHT
39961 <row topline="true">
39962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39965 \begin_layout Standard
39973 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39976 \begin_layout Standard
39979 IC_LEFT() IC_RIGHT() IC_RESULT()
39984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39987 \begin_layout Standard
39995 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39998 \begin_layout Standard
40001 IC_RESULT = IC_LEFT * IC_RIGHT;
40007 <row topline="true">
40008 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40011 \begin_layout Standard
40019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40022 \begin_layout Standard
40025 IC_LEFT() IC_RIGHT() IC_RESULT()
40030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40033 \begin_layout Standard
40041 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40044 \begin_layout Standard
40047 IC_RESULT = IC_LEFT / IC_RIGHT;
40053 <row topline="true">
40054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40057 \begin_layout Standard
40065 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40068 \begin_layout Standard
40071 IC_LEFT() IC_RIGHT() IC_RESULT()
40076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40079 \begin_layout Standard
40087 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40090 \begin_layout Standard
40093 IC_RESULT = IC_LEFT % IC_RIGHT;
40099 <row topline="true">
40100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40103 \begin_layout Standard
40111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40114 \begin_layout Standard
40117 IC_LEFT() IC_RIGHT() IC_RESULT()
40122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40125 \begin_layout Standard
40133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40136 \begin_layout Standard
40139 IC_RESULT = IC_LEFT < IC_RIGHT;
40145 <row topline="true">
40146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40149 \begin_layout Standard
40157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40160 \begin_layout Standard
40163 IC_LEFT() IC_RIGHT() IC_RESULT()
40168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40171 \begin_layout Standard
40179 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40182 \begin_layout Standard
40185 IC_RESULT = IC_LEFT > IC_RIGHT;
40191 <row topline="true">
40192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40195 \begin_layout Standard
40203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40206 \begin_layout Standard
40209 IC_LEFT() IC_RIGHT() IC_RESULT()
40214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40217 \begin_layout Standard
40225 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40228 \begin_layout Standard
40231 IC_RESULT = IC_LEFT == IC_RIGHT;
40237 <row topline="true">
40238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40241 \begin_layout Standard
40249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40252 \begin_layout Standard
40255 IC_LEFT() IC_RIGHT() IC_RESULT()
40260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40263 \begin_layout Standard
40266 Logical and operation
40271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40274 \begin_layout Standard
40277 IC_RESULT = IC_LEFT && IC_RIGHT;
40283 <row topline="true">
40284 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40287 \begin_layout Standard
40295 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40298 \begin_layout Standard
40301 IC_LEFT() IC_RIGHT() IC_RESULT()
40306 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40309 \begin_layout Standard
40312 Logical or operation
40317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40320 \begin_layout Standard
40323 IC_RESULT = IC_LEFT || IC_RIGHT;
40329 <row topline="true">
40330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40333 \begin_layout Standard
40341 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40344 \begin_layout Standard
40347 IC_LEFT() IC_RIGHT() IC_RESULT()
40352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40355 \begin_layout Standard
40363 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40366 \begin_layout Standard
40369 IC_RESULT = IC_LEFT ^ IC_RIGHT;
40375 <row topline="true">
40376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40379 \begin_layout Standard
40387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40390 \begin_layout Standard
40393 IC_LEFT() IC_RIGHT() IC_RESULT()
40398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40401 \begin_layout Standard
40409 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40412 \begin_layout Standard
40415 IC_RESULT = IC_LEFT | IC_RIGHT;
40421 <row topline="true">
40422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40425 \begin_layout Standard
40433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40436 \begin_layout Standard
40439 IC_LEFT() IC_RIGHT() IC_RESULT()
40444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40447 \begin_layout Standard
40455 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40458 \begin_layout Standard
40461 IC_RESULT = IC_LEFT & IC_RIGHT;
40467 <row topline="true">
40468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40471 \begin_layout Standard
40479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40482 \begin_layout Standard
40485 IC_LEFT() IC_RIGHT() IC_RESULT()
40490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40493 \begin_layout Standard
40501 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40504 \begin_layout Standard
40507 IC_RESULT = IC_LEFT << IC_RIGHT
40513 <row topline="true">
40514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40517 \begin_layout Standard
40525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40528 \begin_layout Standard
40531 IC_LEFT() IC_RIGHT() IC_RESULT()
40536 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40539 \begin_layout Standard
40547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40550 \begin_layout Standard
40553 IC_RESULT = IC_LEFT >> IC_RIGHT
40559 <row topline="true">
40560 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40563 \begin_layout Standard
40573 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40576 \begin_layout Standard
40579 IC_LEFT() IC_RESULT()
40584 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40587 \begin_layout Standard
40595 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40598 \begin_layout Standard
40601 IC_RESULT = (*IC_LEFT);
40607 <row topline="true">
40608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40611 \begin_layout Standard
40619 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40622 \begin_layout Standard
40625 IC_RIGHT() IC_RESULT()
40630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40633 \begin_layout Standard
40641 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40644 \begin_layout Standard
40647 (*IC_RESULT) = IC_RIGHT;
40653 <row topline="true">
40654 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40657 \begin_layout Standard
40665 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40668 \begin_layout Standard
40671 IC_RIGHT() IC_RESULT()
40676 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40679 \begin_layout Standard
40687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40690 \begin_layout Standard
40693 IC_RESULT = IC_RIGHT;
40699 <row topline="true">
40700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40703 \begin_layout Standard
40711 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40714 \begin_layout Standard
40717 IC_COND IC_TRUE IC_LABEL
40722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40725 \begin_layout Standard
40729 If true label is present then jump to true label if condition is true else
40730 jump to false label if condition is false
40735 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40738 \begin_layout Standard
40741 if (IC_COND) goto IC_TRUE;
40747 If (!IC_COND) goto IC_FALSE;
40753 <row topline="true">
40754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40757 \begin_layout Standard
40765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40768 \begin_layout Standard
40771 IC_LEFT() IC_RESULT()
40776 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40779 \begin_layout Standard
40787 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40790 \begin_layout Standard
40793 IC_RESULT = &IC_LEFT();
40799 <row topline="true">
40800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40803 \begin_layout Standard
40811 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40814 \begin_layout Standard
40817 IC_JTCOND IC_JTLABELS
40822 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40825 \begin_layout Standard
40828 Jump to list of labels depending on the value of JTCOND
40833 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40836 \begin_layout Standard
40845 <row topline="true">
40846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40849 \begin_layout Standard
40857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40860 \begin_layout Standard
40863 IC_RIGHT() IC_LEFT() IC_RESULT()
40868 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40871 \begin_layout Standard
40879 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40882 \begin_layout Standard
40885 IC_RESULT = (typeof IC_LEFT) IC_RIGHT;
40891 <row topline="true">
40892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40895 \begin_layout Standard
40903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40906 \begin_layout Standard
40914 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40917 \begin_layout Standard
40920 This is used for passing parameters in registers;
40922 move IC_LEFT to the next
40923 available parameter register.
40928 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40931 \begin_layout Standard
40940 <row topline="true">
40941 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40944 \begin_layout Standard
40952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40955 \begin_layout Standard
40963 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40966 \begin_layout Standard
40969 This is used for receiving parameters passed in registers;
40972 in the next parameter register to IC_RESULT
40977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
40980 \begin_layout Standard
40989 <row topline="true" bottomline="true">
40990 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
40993 \begin_layout Standard
40997 (some more have been added)
41002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
41005 \begin_layout Standard
41011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
41014 \begin_layout Standard
41020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
41023 \begin_layout Standard
41056 \begin_layout Standard
41057 \begin_inset Note Note
41060 \begin_layout Standard
41061 In the original article Figure II was announced to be downloadable on
41066 ftp://ftp.circuitcellar.com/pub/Circuit_Cellar/2000/121/dutta.ZIP
41074 \begin_layout Paragraph*
41076 \begin_inset LatexCommand index
41084 \begin_layout Standard
41085 This section shows some details of iCode.
41086 The example C code does not do anything useful; it is used as an example
41087 to illustrate the intermediate code generated by the compiler.
41090 \begin_layout Verse
41100 /* This function does nothing useful.
41107 for the purpose of explaining iCode */
41110 short function (data
41119 short i=10; \InsetSpace ~
41121 /* dead initialization eliminated */
41127 /* dead initialization eliminated */
41155 /* compiler detects i,j to be induction
41160 for (i = 0, j = 10 ; i < 10 ; i++, j
41166 \begin_layout Standard
41189 mul += i * 3; \InsetSpace ~
41191 /* this multiplication remains */
41198 j * 3;\InsetSpace ~
41200 /* this multiplication changed to addition */
41214 \begin_layout Standard
41215 In addition to the operands each iCode contains information about the filename
41216 and line it corresponds to in the source file.
41217 The first field in the listing should be interpreted as follows:
41222 Filename(linenumber: iCode Execution sequence number : ICode hash table
41223 key : loop depth of the iCode).
41228 Then follows the human readable form of the ICode operation.
41229 Each operand of this triplet form can be of three basic types a) compiler
41230 generated temporary b) user defined variable c) a constant value.
41231 Note that local variables and parameters are replaced by compiler generated
41234 \begin_inset LatexCommand index
41235 name "Live range analysis"
41239 are computed only for temporaries (i.e.
41240 live ranges are not computed for global variables).
41242 \begin_inset LatexCommand index
41243 name "Register allocation"
41247 are allocated for temporaries only.
41248 Operands are formatted in the following manner:
41253 Operand Name [lr live-from : live-to ] { type information } [ registers
41259 As mentioned earlier the live ranges are computed in terms of the execution
41260 sequence number of the iCodes, for example
41262 the iTemp0 is live from (i.e.
41263 first defined in iCode with execution sequence number 3, and is last used
41264 in the iCode with sequence number 5).
41265 For induction variables such as iTemp21 the live range computation extends
41266 the lifetime from the start to the end of the loop.
41268 The register allocator
41269 used the live range information to allocate registers, the same registers
41270 may be used for different temporaries if their live ranges do not overlap,
41271 for example r0 is allocated to both iTemp6 and to iTemp17 since their live
41272 ranges do not overlap.
41273 In addition the allocator also takes into consideration the type and usage
41274 of a temporary, for example itemp6 is a pointer to near space and is used
41275 as to fetch data from (i.e.
41276 used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
41277 Some short lived temporaries are allocated to special registers which have
41278 meaning to the code generator e.g.
41279 iTemp13 is allocated to a pseudo register CC which tells the back end that
41280 the temporary is used only for a conditional jump the code generation makes
41281 use of this information to optimize a compare and jump ICode.
41285 \begin_inset LatexCommand index
41286 name "Loop optimization"
41290 performed by the compiler.
41291 It can detect induction variables iTemp21(i) and iTemp23(j).
41292 Also note the compiler does selective strength reduction
41293 \begin_inset LatexCommand index
41294 name "Strength reduction"
41299 the multiplication of an induction variable in line 18 (gint = j * 3) is
41300 changed to addition, a new temporary iTemp17 is allocated and assigned
41301 a initial value, a constant 3 is then added for each iteration of the loop.
41302 The compiler does not change the multiplication
41303 \begin_inset LatexCommand index
41304 name "Multiplication"
41308 in line 17 however since the processor does support an 8 * 8 bit multiplication.
41311 Note the dead code elimination
41312 \begin_inset LatexCommand index
41313 name "Dead-code elimination"
41317 optimization eliminated the dead assignments in line 7 & 8 to I and sum
41323 \begin_layout Standard
41326 Sample.c (5:1:0:0) _entry($9) :
41329 \begin_layout Standard
41332 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
41335 \begin_layout Standard
41338 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
41341 \begin_layout Standard
41344 Sample.c(11:4:53:0) preHeaderLbl0($11) :
41347 \begin_layout Standard
41350 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
41354 \begin_layout Standard
41357 Sample.c(11:6:5:1) _whilecontinue_0($1) :
41360 \begin_layout Standard
41363 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
41367 \begin_layout Standard
41370 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
41373 \begin_layout Standard
41376 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
41380 \begin_layout Standard
41383 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
41387 \begin_layout Standard
41390 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
41394 \begin_layout Standard
41397 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
41401 \begin_layout Standard
41404 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
41405 * int}[r0] + 0x2 {short}
41408 \begin_layout Standard
41411 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
41414 \begin_layout Standard
41417 Sample.c(11:17:21:0)_whilebreak_0($3) :
41420 \begin_layout Standard
41423 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
41426 \begin_layout Standard
41429 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
41432 \begin_layout Standard
41435 Sample.c(15:20:54:0)preHeaderLbl1($13) :
41438 \begin_layout Standard
41441 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
41444 \begin_layout Standard
41447 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
41450 \begin_layout Standard
41453 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
41456 \begin_layout Standard
41459 Sample.c(15:24:26:1)_forcond_0($4) :
41462 \begin_layout Standard
41465 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
41469 \begin_layout Standard
41472 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
41475 \begin_layout Standard
41478 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
41479 + ITemp21 [lr21:38]{short}[r4]
41482 \begin_layout Standard
41485 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
41489 \begin_layout Standard
41492 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
41493 + iTemp15 [lr29:30]{short}[r1]
41496 \begin_layout Standard
41499 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
41503 \begin_layout Standard
41506 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
41510 \begin_layout Standard
41513 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
41517 \begin_layout Standard
41520 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
41524 \begin_layout Standard
41527 Sample.c(19:38:47:1) goto _forcond_0($4)
41530 \begin_layout Standard
41533 Sample.c(19:39:48:0)_forbreak_0($7) :
41536 \begin_layout Standard
41539 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
41540 + ITemp11 [lr19:40]{short}[r3]
41543 \begin_layout Standard
41546 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
41549 \begin_layout Standard
41552 Sample.c(20:42:51:0)_return($8) :
41555 \begin_layout Standard
41558 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
41564 Finally the code generated for this function:
41569 \begin_layout Standard
41575 \begin_layout Standard
41581 \begin_layout Standard
41589 \begin_layout Standard
41595 \begin_layout Standard
41603 \begin_layout Standard
41609 \begin_layout Standard
41612 ; ----------------------------------------------
41615 \begin_layout Standard
41618 ; function function
41621 \begin_layout Standard
41624 ; ----------------------------------------------
41627 \begin_layout Standard
41633 \begin_layout Standard
41636 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
41639 \begin_layout Standard
41647 \begin_layout Standard
41650 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
41653 \begin_layout Standard
41661 \begin_layout Standard
41664 ;_whilecontinue_0($1) :
41667 \begin_layout Standard
41673 \begin_layout Standard
41676 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
41679 \begin_layout Standard
41682 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
41685 \begin_layout Standard
41693 \begin_layout Standard
41701 \begin_layout Standard
41709 \begin_layout Standard
41717 \begin_layout Standard
41725 \begin_layout Standard
41733 \begin_layout Standard
41741 \begin_layout Standard
41747 \begin_layout Standard
41750 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
41753 \begin_layout Standard
41761 \begin_layout Standard
41769 \begin_layout Standard
41772 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
41775 \begin_layout Standard
41783 \begin_layout Standard
41791 \begin_layout Standard
41799 \begin_layout Standard
41807 \begin_layout Standard
41815 \begin_layout Standard
41823 \begin_layout Standard
41826 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
41829 \begin_layout Standard
41837 \begin_layout Standard
41845 \begin_layout Standard
41853 \begin_layout Standard
41861 \begin_layout Standard
41869 \begin_layout Standard
41872 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
41875 \begin_layout Standard
41883 \begin_layout Standard
41891 \begin_layout Standard
41899 \begin_layout Standard
41902 ; iTemp6 [lr5:16]{_near * int}[r0] =
41905 \begin_layout Standard
41908 ; iTemp6 [lr5:16]{_near * int}[r0] +
41911 \begin_layout Standard
41917 \begin_layout Standard
41925 \begin_layout Standard
41928 ; goto _whilecontinue_0($1)
41931 \begin_layout Standard
41939 \begin_layout Standard
41942 ; _whilebreak_0($3) :
41945 \begin_layout Standard
41951 \begin_layout Standard
41954 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
41957 \begin_layout Standard
41965 \begin_layout Standard
41968 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
41971 \begin_layout Standard
41979 \begin_layout Standard
41982 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
41985 \begin_layout Standard
41993 \begin_layout Standard
41996 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
41999 \begin_layout Standard
42007 \begin_layout Standard
42015 \begin_layout Standard
42018 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
42021 \begin_layout Standard
42029 \begin_layout Standard
42037 \begin_layout Standard
42043 \begin_layout Standard
42049 \begin_layout Standard
42052 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
42055 \begin_layout Standard
42058 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
42061 \begin_layout Standard
42069 \begin_layout Standard
42077 \begin_layout Standard
42085 \begin_layout Standard
42093 \begin_layout Standard
42101 \begin_layout Standard
42107 \begin_layout Standard
42110 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
42113 \begin_layout Standard
42116 ; iTemp21 [lr21:38]{short}[r4]
42119 \begin_layout Standard
42127 \begin_layout Standard
42135 \begin_layout Standard
42143 \begin_layout Standard
42146 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
42149 \begin_layout Standard
42157 \begin_layout Standard
42165 \begin_layout Standard
42173 \begin_layout Standard
42181 \begin_layout Standard
42184 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
42187 \begin_layout Standard
42190 ; iTemp15 [lr29:30]{short}[r1]
42193 \begin_layout Standard
42201 \begin_layout Standard
42209 \begin_layout Standard
42212 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
42215 \begin_layout Standard
42223 \begin_layout Standard
42231 \begin_layout Standard
42239 \begin_layout Standard
42247 \begin_layout Standard
42255 \begin_layout Standard
42263 \begin_layout Standard
42266 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
42269 \begin_layout Standard
42277 \begin_layout Standard
42285 \begin_layout Standard
42293 \begin_layout Standard
42301 \begin_layout Standard
42309 \begin_layout Standard
42317 \begin_layout Standard
42320 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
42323 \begin_layout Standard
42331 \begin_layout Standard
42334 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
42337 \begin_layout Standard
42345 \begin_layout Standard
42350 cjne r5,#0xff,00104$
42353 \begin_layout Standard
42361 \begin_layout Standard
42364 ; goto _forcond_0($4)
42367 \begin_layout Standard
42375 \begin_layout Standard
42378 ; _forbreak_0($7) :
42381 \begin_layout Standard
42387 \begin_layout Standard
42390 ; ret iTemp24 [lr40:41]{short}
42393 \begin_layout Standard
42401 \begin_layout Standard
42409 \begin_layout Standard
42417 \begin_layout Standard
42423 \begin_layout Standard
42429 \begin_layout Standard
42439 \begin_layout Section
42440 A few words about basic block successors, predecessors and dominators
42443 \begin_layout Standard
42444 Successors are basic blocks
42445 \begin_inset LatexCommand index
42446 name "Basic blocks"
42450 that might execute after this basic block.
42452 Predecessors are basic blocks
42453 that might execute before reaching this basic block.
42455 Dominators are basic
42456 blocks that WILL execute before reaching this basic block.
42461 \begin_layout Standard
42465 \begin_layout Standard
42469 \begin_layout Standard
42477 \begin_layout Standard
42481 \begin_layout Standard
42489 \begin_layout Standard
42495 \begin_layout Standard
42496 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
42499 \begin_layout Standard
42500 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
42503 \begin_layout Standard
42504 c) domVect of [BB4] = BB1 ...
42505 here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
42509 \begin_layout Chapter
42513 \begin_layout Standard
42514 \begin_inset LatexCommand url
42515 target "http://sdcc.sourceforge.net/#Who"
42525 Thanks to all the other volunteer developers who have helped with coding,
42526 testing, web-page creation, distribution sets, etc.
42527 You know who you are :-)
42535 Thanks to Sourceforge
42536 \begin_inset LatexCommand url
42537 target "http://www.sf.net"
42541 which has hosted the project since 1999 and donates significant download
42550 Also thanks to all SDCC Distributed Compile Farm members for donating CPU
42551 cycles and bandwidth for snapshot builds.
42556 \begin_layout Standard
42557 This document was initially written by Sandeep Dutta
42560 \begin_layout Standard
42561 All product names mentioned herein may be trademarks
42562 \begin_inset LatexCommand index
42567 of their respective companies.
42571 \begin_layout Section*
42575 \begin_layout Standard
42576 To avoid confusion, the installation and building options for SDCC itself
42577 (chapter 2) are not part of the index.
42580 \begin_layout Standard
42581 \begin_inset LatexCommand printindex