1 #LyX 1.4.5 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 \paperfontsize default
29 \papersize letterpaper
34 \paperorientation portrait
41 \paragraph_separation indent
43 \quotes_language swedish
47 \tracking_changes false
53 \begin_layout Standard
54 \begin_inset Note Note
57 \begin_layout Standard
58 Please note: double dashed longoptions (e.g.
59 --version) are written this way: -
63 \begin_layout Standard
75 \begin_layout Standard
77 three consecutive dashes would otherwise result in a long resp.
81 \begin_layout Standard
82 Architecture specific stuff (like memory models, code examples) should maybe
86 \begin_layout Standard
87 into seperate sections/chapters/appendices (it is hard to document PIC or
91 \begin_layout Standard
92 a 8051 centered document) - for now simply add.
101 SDCC Compiler User Guide
116 \begin_layout Standard
117 \begin_inset Note Note
120 \begin_layout Standard
121 The above strings enclosed in $ are automatically updated by Subversion
129 \begin_layout Standard
130 \begin_inset LatexCommand \tableofcontents{}
137 \begin_layout Chapter
141 \begin_layout Section
145 \begin_layout Standard
166 ompiler) is free open source, retargettable, optimizing ANSI-C compiler
171 designed for 8 bit Microprocessors.
172 The current version targets Intel MCS51 based Microprocessors (8031, 8032,
174 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
178 , etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
179 Zilog Z80 based MCUs.
180 It can be retargeted for other microprocessors, support for Microchip PIC,
181 Atmel AVR is under development.
182 The entire source code for the compiler is distributed under GPL.
184 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
189 \begin_inset LatexCommand \index{aslink}
193 , an open source retargetable assembler & linker.
194 SDCC has extensive language extensions suitable for utilizing various microcont
195 rollers and underlying hardware effectively.
200 In addition to the MCU specific optimizations SDCC also does a host of
201 standard optimizations like:
204 \begin_layout Itemize
205 global sub expression elimination,
208 \begin_layout Itemize
209 loop optimizations (loop invariant, strength reduction of induction variables
213 \begin_layout Itemize
214 constant folding & propagation,
217 \begin_layout Itemize
221 \begin_layout Itemize
222 dead code elimination
225 \begin_layout Itemize
233 \begin_layout Standard
234 For the back-end SDCC uses a global register allocation scheme which should
235 be well suited for other 8 bit MCUs.
240 The peep hole optimizer uses a rule based substitution mechanism which
246 Supported data-types are:
249 \begin_layout Standard
251 <lyxtabular version="3" rows="8" columns="5">
253 <column alignment="center" valignment="top" leftline="true" width="0">
254 <column alignment="center" valignment="top" leftline="true" width="0">
255 <column alignment="center" valignment="top" leftline="true" width="0">
256 <column alignment="center" valignment="top" leftline="true" width="0">
257 <column alignment="block" valignment="top" leftline="true" rightline="true" width="20text%">
258 <row topline="true" bottomline="true">
259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
262 \begin_layout Standard
268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
271 \begin_layout Standard
277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
280 \begin_layout Standard
286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
289 \begin_layout Standard
295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
298 \begin_layout Standard
306 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
309 \begin_layout Standard
315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
318 \begin_layout Standard
324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
327 \begin_layout Standard
333 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
336 \begin_layout Standard
342 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
345 \begin_layout Standard
353 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
356 \begin_layout Standard
362 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
365 \begin_layout Standard
371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
374 \begin_layout Standard
380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
383 \begin_layout Standard
389 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
392 \begin_layout Standard
400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
403 \begin_layout Standard
409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
412 \begin_layout Standard
418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
421 \begin_layout Standard
427 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
430 \begin_layout Standard
436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
439 \begin_layout Standard
447 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
450 \begin_layout Standard
456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
459 \begin_layout Standard
465 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
468 \begin_layout Standard
474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
477 \begin_layout Standard
483 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
486 \begin_layout Standard
493 <row topline="true" bottomline="true">
494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
497 \begin_layout Standard
503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
506 \begin_layout Standard
512 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
515 \begin_layout Standard
521 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
524 \begin_layout Standard
525 -2.147.483.648, +2.147.483.647
530 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
533 \begin_layout Standard
540 <row topline="true" bottomline="true">
541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
544 \begin_layout Standard
550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
553 \begin_layout Standard
559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
562 \begin_layout Standard
568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
571 \begin_layout Standard
577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
580 \begin_layout Standard
596 <row topline="true" bottomline="true">
597 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
600 \begin_layout Standard
606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
609 \begin_layout Standard
615 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
618 \begin_layout Standard
624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
627 \begin_layout Standard
633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
636 \begin_layout Standard
649 The compiler also allows
651 inline assembler code
653 to be embedded anywhere in a function.
654 In addition, routines developed in assembly can also be called.
659 provides an option (-
663 \begin_layout Standard
672 -cyclomatic) to report the relative complexity of a function.
673 These functions can then be further optimized, or hand coded in assembly
679 SDCC also comes with a companion source level debugger SDCDB.
680 The debugger currently uses ucSim, a free open source simulator for 8051
681 and other micro-controllers.
685 The latest SDCC version can be downloaded from
687 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
697 Please note: the compiler will probably always be some steps ahead of this
702 \begin_inset LatexCommand \index{Status of documentation}
710 \begin_layout Standard
711 Obviously this has pros and cons
719 \begin_layout Section
723 \begin_layout Standard
724 All packages used in this compiler system are
732 ; source code for all the sub-packages (pre-processor, assemblers, linkers
733 etc.) is distributed with the package.
734 This documentation is maintained using a free open source word processor
737 This program is free software; you can redistribute it and/or modify
738 it under the terms of the GNU General Public License
739 \begin_inset LatexCommand \index{GNU General Public License, GPL}
743 as published by the Free Software Foundation; either version 2, or (at
744 your option) any later version.
745 This program is distributed in the hope that it will be useful, but WITHOUT
746 ANY WARRANTY; without even the implied warranty
747 \begin_inset LatexCommand \index{warranty}
751 of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
752 See the GNU General Public License for more details.
753 You should have received a copy of the GNU General Public License along
754 with this program; if not, write to the Free Software Foundation, 59 Temple
755 Place - Suite 330, Boston, MA 02111-1307, USA.
756 In other words, you are welcome to use, share and improve this program.
757 You are forbidden to forbid anyone else to use, share and improve what
759 Help stamp out software-hoarding!
762 \begin_layout Section
763 Typographic conventions
764 \begin_inset LatexCommand \index{Typographic conventions}
771 \begin_layout Standard
772 Throughout this manual, we will use the following convention.
773 Commands you have to type in are printed in
781 Code samples are printed in
786 Interesting items and new terms are printed in
791 \begin_layout Section
793 \begin_inset LatexCommand \label{sec:Compatibility-with-previous}
797 with previous versions
798 \begin_inset LatexCommand \index{Compatibility with previous versions}
805 \begin_layout Standard
806 Newer versions have usually numerous bug fixes compared with the previous
808 But we also sometimes introduce some incompatibilities with older versions.
809 Not just for the fun of it, but to make the compiler more stable, efficient
811 \begin_inset LatexCommand \index{ANSI-compliance}
816 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
820 for ANSI-Compliance).
822 \begin_inset Note Note
825 \begin_layout Standard
826 It would be fine to add to each item, in which version was it changed.
836 \begin_layout Itemize
837 short is now equivalent to int (16 bits), it used to be equivalent to char
838 (8 bits) which is not ANSI compliant.
839 To maintain compatibility, old programs may be compiled using the -
843 \begin_layout Standard
852 -short-is-8bits commandline option (see
853 \begin_inset LatexCommand \vref{lyx:--short-is-8bits}
860 \begin_layout Itemize
861 the default directory for gcc-builds where include, library and documentation
862 files are stored is now in /usr/local/share.
865 \begin_layout Itemize
866 char type parameters to vararg
867 \begin_inset LatexCommand \index{vararg, va\_arg}
871 functions are casted to int unless explicitly casted and
877 \begin_layout Standard
887 \begin_inset LatexCommand \index{-\/-std-c89}
899 \begin_layout Standard
909 \begin_inset LatexCommand \index{-\/-std-c99}
915 command line option are not defined
916 \begin_inset Marginal
919 \begin_layout Standard
944 will push a as an int and as a char resp if
950 \begin_layout Standard
960 \begin_inset LatexCommand \index{-\/-std-c89}
972 \begin_layout Standard
982 \begin_inset LatexCommand \index{-\/-std-c99}
988 command line options are not defined,
990 will push a as two ints if
996 \begin_layout Standard
1006 \begin_inset LatexCommand \index{-\/-std-c89}
1018 \begin_layout Standard
1028 \begin_inset LatexCommand \index{-\/-std-c99}
1034 command line option is defined.
1037 \begin_layout Itemize
1042 \begin_layout Standard
1051 -regextend has been removed.
1054 \begin_layout Itemize
1059 \begin_layout Standard
1068 -noregparms has been removed.
1071 \begin_layout Itemize
1076 \begin_layout Standard
1085 -stack-after-data has been removed.
1088 \begin_layout Itemize
1090 \begin_inset LatexCommand \index{bit}
1095 \begin_inset LatexCommand \index{sbit}
1100 \begin_inset LatexCommand \index{\_\_sbit}
1104 types now consistently behave like the C99 _Bool type with respect to type
1106 \begin_inset LatexCommand \index{type conversion}
1111 \begin_inset LatexCommand \index{type promotion}
1116 The most common incompatibility resulting from this change is related to
1118 \begin_inset LatexCommand \index{Bit toggling}
1133 \begin_inset LatexCommand \index{\~\/ Operator}
1137 b; /* equivalent to b=1 instead of toggling b */
1138 \begin_inset Marginal
1141 \begin_layout Standard
1154 b = !b; /* toggles b */
1158 In previous versions, both forms would have toggled the bit.
1161 \begin_layout Itemize
1162 in older versions, the preprocessor was always called with -std=c99 regardless
1163 of the --std-xxx setting.
1164 This is no longer true, and can cause compilation failures on code built
1165 with --std-c89 but using c99 preprocessor features, such as one-line (//)
1169 \begin_layout Standard
1172 <pending: more incompatibilities?>
1175 \begin_layout Section
1179 \begin_layout Standard
1180 What do you need before you start installation of SDCC? A computer, and
1181 a desire to compute.
1182 The preferred method of installation is to compile SDCC from source using
1184 For Windows some pre-compiled binary distributions are available for your
1186 You should have some experience with command line tools and compiler use.
1189 \begin_layout Section
1193 \begin_layout Standard
1194 The SDCC home page at
1195 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
1199 is a great place to find distribution sets.
1200 You can also find links to the user mailing lists that offer help or discuss
1201 SDCC with other SDCC users.
1202 Web links to other SDCC related sites can also be found here.
1203 This document can be found in the DOC directory of the source package as
1204 a text or HTML file.
1205 A pdf version of this document is available at
1206 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
1211 Some of the other tools (simulator and assembler) included with SDCC contain
1212 their own documentation and can be found in the source distribution.
1213 If you want the latest unreleased software, the complete source package
1214 is available directly from Subversion on https://sdcc.svn.sourceforge.net/svnroot/
1218 \begin_layout Section
1219 Wishes for the future
1222 \begin_layout Standard
1223 There are (and always will be) some things that could be done.
1224 Here are some I can think of:
1229 \begin_layout Standard
1232 char KernelFunction3(char p) at 0x340;
1237 \begin_layout Standard
1241 \begin_inset LatexCommand \index{code banking (limited support)}
1251 If you can think of some more, please see the section
1252 \begin_inset LatexCommand \ref{sub:Requesting-Features}
1256 about filing feature requests
1257 \begin_inset LatexCommand \index{Requesting features}
1262 \begin_inset LatexCommand \index{Feature request}
1271 \begin_layout Chapter
1273 \begin_inset LatexCommand \index{Installation}
1280 \begin_layout Standard
1281 For most users it is sufficient to skip to either section
1282 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
1287 \begin_inset LatexCommand \ref{sub:Windows-Install}
1292 More detailed instructions follow below.
1295 \begin_layout Section
1297 \begin_inset LatexCommand \index{Options SDCC configuration}
1304 \begin_layout Standard
1305 The install paths, search paths and other options are defined when running
1307 The defaults can be overridden by:
1311 \labelwidthstring 00.00.0000
1316 \begin_layout Standard
1325 -prefix see table below
1329 \labelwidthstring 00.00.0000
1334 \begin_layout Standard
1343 -exec_prefix see table below
1347 \labelwidthstring 00.00.0000
1352 \begin_layout Standard
1361 -bindir see table below
1365 \labelwidthstring 00.00.0000
1370 \begin_layout Standard
1379 -datadir see table below
1383 \labelwidthstring 00.00.0000
1388 \begin_layout Standard
1397 -datarootdir see table below
1403 \labelwidthstring 00.00.0000
1406 docdir environment variable, see table below
1410 \labelwidthstring 00.00.0000
1413 include_dir_suffix environment variable, see table below
1417 \labelwidthstring 00.00.0000
1420 lib_dir_suffix environment variable, see table below
1424 \labelwidthstring 00.00.0000
1427 sdccconf_h_dir_separator environment variable, either / or
1432 This character will only be used in sdccconf.h; don't forget it's a C-header,
1433 therefore a double-backslash is needed there.
1439 \labelwidthstring 00.00.0000
1444 \begin_layout Standard
1453 -disable-mcs51-port Excludes the Intel mcs51 port
1457 \labelwidthstring 00.00.0000
1462 \begin_layout Standard
1471 -disable-gbz80-port Excludes the Gameboy gbz80 port
1475 \labelwidthstring 00.00.0000
1480 \begin_layout Standard
1489 -disable-z80-port Excludes the z80 port
1493 \labelwidthstring 00.00.0000
1498 \begin_layout Standard
1507 -disable-avr-port Excludes the AVR port
1511 \labelwidthstring 00.00.0000
1516 \begin_layout Standard
1525 -disable-ds390-port Excludes the DS390 port
1529 \labelwidthstring 00.00.0000
1534 \begin_layout Standard
1543 -disable-hc08-port Excludes the HC08 port
1547 \labelwidthstring 00.00.0000
1552 \begin_layout Standard
1561 -disable-pic-port Excludes the PIC14 port
1565 \labelwidthstring 00.00.0000
1570 \begin_layout Standard
1579 -disable-pic16-port Excludes the PIC16 port
1583 \labelwidthstring 00.00.0000
1588 \begin_layout Standard
1597 -disable-xa51-port Excludes the XA51 port
1601 \labelwidthstring 00.00.0000
1606 \begin_layout Standard
1615 -disable-ucsim Disables configuring and building of ucsim
1619 \labelwidthstring 00.00.0000
1624 \begin_layout Standard
1633 -disable-device-lib Disables automatically building device libraries
1637 \labelwidthstring 00.00.0000
1642 \begin_layout Standard
1651 -disable-packihx Disables building packihx
1657 \labelwidthstring 00.00.0000
1662 \begin_layout Standard
1671 -enable-doc Build pdf, html and txt files from the lyx sources
1675 \labelwidthstring 00.00.0000
1680 \begin_layout Standard
1689 -enable-libgc Use the Bohem memory allocator.
1690 Lower runtime footprint.
1694 \labelwidthstring 00.00.0000
1699 \begin_layout Standard
1708 -without-ccache Do not use ccache even if available
1711 \begin_layout Standard
1712 Furthermore the environment variables CC, CFLAGS, ...
1713 the tools and their arguments can be influenced.
1714 Please see `configure -
1718 \begin_layout Standard
1727 -help' and the man/info pages of `configure' for details.
1732 standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB, STD_FP_LIB, STD_DS390_LI
1733 B, STD_XA51_LIB and the environment variables SDCC_DIR_NAME, SDCC_INCLUDE_NAME,
1734 SDCC_LIB_NAME are defined by `configure' too.
1735 At the moment it's not possible to change the default settings (it was
1736 simply never required).
1740 These configure options are compiled into the binaries,
1741 and can only be changed by rerunning 'configure' and recompiling SDCC.
1742 The configure options are written in
1746 to distinguish them from run time environment variables (see section search
1752 \begin_inset Quotes sld
1756 \begin_inset Quotes srd
1759 are used by the SDCC team to build the official Win32 binaries.
1760 The SDCC team uses Mingw32 to build the official Windows binaries, because
1764 \begin_layout Enumerate
1768 \begin_layout Enumerate
1769 a gcc compiler and last but not least
1772 \begin_layout Enumerate
1773 the binaries can be built by cross compiling on SDCC Distributed Compile
1777 \begin_layout Standard
1778 See the examples, how to pass the Win32 settings to 'configure'.
1779 The other Win32 builds using Borland, VC or whatever don't use 'configure',
1780 but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
1790 \begin_layout Standard
1792 \begin_inset Tabular
1793 <lyxtabular version="3" rows="9" columns="3">
1795 <column alignment="block" valignment="top" leftline="true" width="0in">
1796 <column alignment="block" valignment="top" leftline="true" width="0in">
1797 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1798 <row topline="true" bottomline="true">
1799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1802 \begin_layout Standard
1808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1811 \begin_layout Standard
1817 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1820 \begin_layout Standard
1827 <row topline="true">
1828 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1831 \begin_layout Standard
1839 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1842 \begin_layout Standard
1848 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1851 \begin_layout Standard
1860 <row topline="true">
1861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1864 \begin_layout Standard
1872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1875 \begin_layout Standard
1883 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1886 \begin_layout Standard
1895 <row topline="true">
1896 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1899 \begin_layout Standard
1907 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1910 \begin_layout Standard
1920 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1923 \begin_layout Standard
1936 <row topline="true">
1937 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1940 \begin_layout Standard
1948 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1951 \begin_layout Standard
1959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1962 \begin_layout Standard
1971 <row topline="true">
1972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1975 \begin_layout Standard
1983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1986 \begin_layout Standard
1996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1999 \begin_layout Standard
2008 <row topline="true">
2009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2012 \begin_layout Standard
2020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2023 \begin_layout Standard
2033 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2036 \begin_layout Standard
2049 <row topline="true">
2050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2053 \begin_layout Standard
2061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2064 \begin_layout Standard
2070 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2073 \begin_layout Standard
2080 <row topline="true" bottomline="true">
2081 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2084 \begin_layout Standard
2092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2095 \begin_layout Standard
2101 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2104 \begin_layout Standard
2120 \begin_layout Standard
2122 'configure' also computes relative paths.
2123 This is needed for full relocatability of a binary package and to complete
2124 search paths (see section search paths below):
2129 \begin_layout Standard
2131 \begin_inset Tabular
2132 <lyxtabular version="3" rows="4" columns="3">
2134 <column alignment="block" valignment="top" leftline="true" width="0in">
2135 <column alignment="block" valignment="top" leftline="true" width="0in">
2136 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2137 <row topline="true" bottomline="true">
2138 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2141 \begin_layout Standard
2147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2150 \begin_layout Standard
2156 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2159 \begin_layout Standard
2166 <row topline="true" bottomline="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
2187 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2190 \begin_layout Standard
2197 <row bottomline="true">
2198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2201 \begin_layout Standard
2209 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2212 \begin_layout Standard
2218 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2221 \begin_layout Standard
2228 <row bottomline="true">
2229 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2232 \begin_layout Standard
2240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2243 \begin_layout Standard
2249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2252 \begin_layout Standard
2268 \begin_layout Standard
2273 \begin_layout LyX-Code
2280 \begin_layout Standard
2290 \begin_inset Quotes srd
2294 \begin_inset Quotes srd
2301 \begin_layout Standard
2311 \begin_inset Quotes srd
2315 \begin_inset Quotes srd
2324 \begin_layout Standard
2337 \begin_layout Standard
2349 \begin_layout Standard
2350 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
2354 \begin_layout LyX-Code
2360 \begin_inset Quotes srd
2363 i586-mingw32msvc-gcc
2364 \begin_inset Quotes srd
2368 \begin_inset Quotes srd
2371 i586-mingw32msvc-g++
2372 \begin_inset Quotes srd
2380 \begin_inset Quotes srd
2383 i586-mingw32msvc-ranlib
2384 \begin_inset Quotes srd
2392 \begin_inset Quotes srd
2395 i586-mingw32msvc-strip
2396 \begin_inset Quotes srd
2407 \begin_layout Standard
2417 \begin_inset Quotes srd
2421 \begin_inset Quotes srd
2432 \begin_layout Standard
2442 \begin_inset Quotes srd
2446 \begin_inset Quotes srd
2454 \begin_inset Quotes srd
2460 \begin_inset Quotes srd
2468 \begin_inset Quotes srd
2472 \begin_inset Quotes srd
2480 \begin_inset Quotes srd
2484 \begin_inset Quotes srd
2491 sdccconf_h_dir_separator=
2492 \begin_inset Quotes srd
2504 \begin_inset Quotes srd
2515 \begin_layout Standard
2532 \begin_layout Standard
2541 -host=i586-mingw32msvc
2549 \begin_layout Standard
2558 -build=unknown-unknown-linux-gnu
2561 \begin_layout Standard
2563 \begin_inset Quotes sld
2567 \begin_inset Quotes srd
2570 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
2574 \begin_layout LyX-Code
2583 \begin_layout Standard
2593 \begin_inset Quotes srd
2597 \begin_inset Quotes srd
2608 \begin_layout Standard
2618 \begin_inset Quotes srd
2622 \begin_inset Quotes srd
2630 \begin_inset Quotes srd
2636 \begin_inset Quotes srd
2644 \begin_inset Quotes srd
2648 \begin_inset Quotes srd
2656 \begin_inset Quotes srd
2660 \begin_inset Quotes srd
2667 sdccconf_h_dir_separator=
2668 \begin_inset Quotes srd
2680 \begin_inset Quotes srd
2688 \begin_inset Quotes srd
2692 \begin_inset Quotes srd
2700 \begin_inset Quotes srd
2704 \begin_inset Quotes srd
2710 \begin_layout Standard
2711 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
2716 \begin_layout Standard
2725 -C' turns on caching, which gives a little bit extra speed.
2726 However if options are changed, it can be necessary to delete the config.cache
2730 \begin_layout Section
2732 \begin_inset LatexCommand \label{sub:Install-paths}
2737 \begin_inset LatexCommand \index{Install paths}
2744 \begin_layout Standard
2745 \begin_inset VSpace medskip
2751 \begin_layout Standard
2753 \begin_inset Tabular
2754 <lyxtabular version="3" rows="5" columns="4">
2756 <column alignment="left" valignment="top" leftline="true" width="0">
2757 <column alignment="left" valignment="top" leftline="true" width="0">
2758 <column alignment="left" valignment="top" leftline="true" width="0">
2759 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
2760 <row topline="true" bottomline="true">
2761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2764 \begin_layout Standard
2772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2775 \begin_layout Standard
2783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2786 \begin_layout Standard
2794 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2797 \begin_layout Standard
2806 <row topline="true">
2807 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2810 \begin_layout Standard
2816 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2819 \begin_layout Standard
2827 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2830 \begin_layout Standard
2836 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2839 \begin_layout Standard
2850 <row topline="true">
2851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2854 \begin_layout Standard
2860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2863 \begin_layout Standard
2866 $DATADIR/ $INCLUDE_DIR_SUFFIX
2871 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2874 \begin_layout Standard
2875 /usr/local/share/sdcc/include
2880 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2883 \begin_layout Standard
2894 <row topline="true">
2895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2898 \begin_layout Standard
2904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2907 \begin_layout Standard
2910 $DATADIR/$LIB_DIR_SUFFIX
2915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2918 \begin_layout Standard
2919 /usr/local/share/sdcc/lib
2924 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2927 \begin_layout Standard
2938 <row topline="true" bottomline="true">
2939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2942 \begin_layout Standard
2948 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2951 \begin_layout Standard
2959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2962 \begin_layout Standard
2963 /usr/local/share/sdcc/doc
2968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2971 \begin_layout Standard
2992 *compiler, preprocessor, assembler, and linker
2998 is auto-appended by the compiler, e.g.
2999 small, large, z80, ds390 etc
3002 \begin_layout Standard
3004 The install paths can still be changed during `make install' with e.g.:
3007 \begin_layout LyX-Code
3008 make install prefix=$(HOME)/local/sdcc
3011 \begin_layout Standard
3012 Of course this doesn't change the search paths compiled into the binaries.
3017 r the install path can be changed by defining DESTDIR
3018 \begin_inset LatexCommand \index{DESTDIR}
3025 \begin_layout LyX-Code
3026 make install DESTDIR=$(HOME)/sdcc.rpm/
3029 \begin_layout Standard
3030 Please note that DESTDIR must have a trailing slash!
3033 \begin_layout Section
3035 \begin_inset LatexCommand \label{sub:Search-Paths}
3040 \begin_inset LatexCommand \index{Search path}
3047 \begin_layout Standard
3048 Some search paths or parts of them are determined by configure variables
3053 , see section above).
3054 Further search paths are determined by environment variables during runtime.
3057 The paths searched when running the compiler are as follows (the first
3063 Binary files (preprocessor, assembler and linker)
3068 \begin_layout Standard
3070 \begin_inset Tabular
3071 <lyxtabular version="3" rows="4" columns="3">
3073 <column alignment="block" valignment="top" leftline="true" width="0in">
3074 <column alignment="block" valignment="top" leftline="true" width="0in">
3075 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
3076 <row topline="true" bottomline="true">
3077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3080 \begin_layout Standard
3086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3089 \begin_layout Standard
3095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3098 \begin_layout Standard
3105 <row topline="true">
3106 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3109 \begin_layout Standard
3117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3120 \begin_layout Standard
3126 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3129 \begin_layout Standard
3138 <row topline="true">
3139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3142 \begin_layout Standard
3143 Path of argv[0] (if available)
3148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3151 \begin_layout Standard
3157 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3160 \begin_layout Standard
3167 <row topline="true" bottomline="true">
3168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3171 \begin_layout Standard
3177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3180 \begin_layout Standard
3186 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3189 \begin_layout Standard
3205 \begin_layout Standard
3213 \begin_layout Standard
3215 \begin_inset Tabular
3216 <lyxtabular version="3" rows="6" columns="3">
3218 <column alignment="block" valignment="top" leftline="true" width="1.5in">
3219 <column alignment="block" valignment="top" leftline="true" width="1.5in">
3220 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
3221 <row topline="true" bottomline="true">
3222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3225 \begin_layout Standard
3231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3234 \begin_layout Standard
3240 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3243 \begin_layout Standard
3250 <row topline="true">
3251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3254 \begin_layout Standard
3259 \begin_layout Standard
3273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3276 \begin_layout Standard
3281 \begin_layout Standard
3295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3298 \begin_layout Standard
3303 \begin_layout Standard
3318 <row topline="true">
3319 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3322 \begin_layout Standard
3328 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3331 \begin_layout Standard
3337 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3340 \begin_layout Standard
3347 <row topline="true">
3348 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3351 \begin_layout Standard
3363 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3366 \begin_layout Standard
3376 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3379 \begin_layout Standard
3388 <row topline="true">
3389 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3392 \begin_layout Standard
3408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3411 \begin_layout Standard
3459 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3462 \begin_layout Standard
3473 <row topline="true" bottomline="true">
3474 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3477 \begin_layout Standard
3491 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3494 \begin_layout Standard
3495 /usr/local/share/sdcc/
3502 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3505 \begin_layout Standard
3521 \begin_layout Standard
3527 \begin_layout Standard
3536 -nostdinc disables the last two search paths.
3546 \begin_layout Standard
3547 With the exception of
3548 \begin_inset Quotes sld
3555 \begin_layout Standard
3565 \begin_inset Quotes srd
3572 is auto-appended by the compiler (e.g.
3573 small, large, z80, ds390 etc.).
3579 \begin_layout Standard
3581 \begin_inset Tabular
3582 <lyxtabular version="3" rows="6" columns="3">
3584 <column alignment="block" valignment="top" leftline="true" width="1.7in">
3585 <column alignment="block" valignment="top" leftline="true" width="1.2in">
3586 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
3587 <row topline="true" bottomline="true">
3588 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3591 \begin_layout Standard
3597 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3600 \begin_layout Standard
3606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3609 \begin_layout Standard
3616 <row topline="true">
3617 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3620 \begin_layout Standard
3625 \begin_layout Standard
3639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3642 \begin_layout Standard
3647 \begin_layout Standard
3661 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3664 \begin_layout Standard
3669 \begin_layout Standard
3684 <row topline="true">
3685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3688 \begin_layout Standard
3698 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3701 \begin_layout Standard
3711 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3714 \begin_layout Standard
3727 <row topline="true">
3728 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3731 \begin_layout Standard
3738 $LIB_DIR_SUFFIX/<model>
3743 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3746 \begin_layout Standard
3758 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3761 \begin_layout Standard
3776 <row topline="true">
3777 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3780 \begin_layout Standard
3791 $LIB_DIR_SUFFIX/<model>
3796 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3799 \begin_layout Standard
3850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3853 \begin_layout Standard
3907 <row topline="true" bottomline="true">
3908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3911 \begin_layout Standard
3916 $LIB_DIR_SUFFIX/<model>
3921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3924 \begin_layout Standard
3925 /usr/local/share/sdcc/
3934 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3937 \begin_layout Standard
3953 \begin_layout Standard
3954 \begin_inset Note Note
3957 \begin_layout Standard
3958 Don't delete any of the stray spaces in the table above without checking
3959 the HTML output (last line)!
3967 \begin_layout Standard
3975 \begin_layout Standard
3984 -nostdlib disables the last two search paths.
3987 \begin_layout Section
3989 \begin_inset LatexCommand \index{Building SDCC}
3996 \begin_layout Subsection
3997 Building SDCC on Linux
3998 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
4005 \begin_layout Enumerate
4008 Download the source package
4010 either from the SDCC Subversion repository or from snapshot builds
4012 , it will be named something like sdcc
4023 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
4030 \begin_layout Enumerate
4033 Bring up a command line terminal, such as xterm.
4036 \begin_layout Enumerate
4039 Unpack the file using a command like:
4042 "tar -xvzf sdcc-src-yyyymmdd-rrrr.tar.bz2
4043 \begin_inset Quotes srd
4049 , this will create a sub-directory called sdcc with all of the sources.
4052 \begin_layout Enumerate
4053 Change directory into the main SDCC directory, for example type:
4061 \begin_layout Enumerate
4071 This configures the package for compilation on your system.
4074 \begin_layout Enumerate
4088 All of the source packages will compile, this can take a while.
4091 \begin_layout Enumerate
4105 This copies the binary executables, the include files, the libraries and
4106 the documentation to the install directories.
4107 Proceed with section
4108 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
4115 \begin_layout Subsection
4116 Building SDCC on Mac OS X
4119 \begin_layout Standard
4120 Follow the instruction for Linux.
4124 On Mac OS X 10.2.x it was reported, that the
4125 default gcc (version 3.1 20020420 (prerelease)) fails to compile SDCC.
4126 Fortunately there's also gcc 2.9.x installed, which works fine.
4127 This compiler can be selected by running 'configure' with:
4130 \begin_layout LyX-Code
4131 ./configure CC=gcc2 CXX=g++2
4134 \begin_layout Standard
4135 Universal (ppc and i386) binaries can be produced on Mac OS X 10.4.x with
4137 Run 'configure' with:
4140 \begin_layout LyX-Code
4146 \begin_layout LyX-Code
4147 LDFLAGS="-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch
4153 \begin_layout LyX-Code
4154 CXXFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch
4160 \begin_layout LyX-Code
4161 CFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc"
4164 \begin_layout Subsection
4165 Cross compiling SDCC on Linux for Windows
4168 \begin_layout Standard
4169 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
4170 See section 'Configure Options'.
4173 \begin_layout Subsection
4174 Building SDCC using Cygwin and Mingw32
4177 \begin_layout Standard
4178 For building and installing a Cygwin executable follow the instructions
4184 \begin_inset Quotes sld
4188 \begin_inset Quotes srd
4191 Win32-binary can be built, which will not need the Cygwin-DLL.
4192 For the necessary 'configure' options see section 'configure options' or
4193 the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
4198 Cygwin on Windows download setup.exe from
4199 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
4205 \begin_inset Quotes sld
4208 default text file type
4209 \begin_inset Quotes srd
4213 \begin_inset Quotes sld
4217 \begin_inset Quotes srd
4220 and download/install at least the following packages.
4221 Some packages are selected by default, others will be automatically selected
4222 because of dependencies with the manually selected packages.
4223 Never deselect these packages!
4226 \begin_layout Itemize
4230 \begin_layout Itemize
4234 \begin_layout Itemize
4235 gcc ; version 3.x is fine, no need to use the old 2.9x
4238 \begin_layout Itemize
4239 binutils ; selected with gcc
4242 \begin_layout Itemize
4246 \begin_layout Itemize
4247 rxvt ; a nice console, which makes life much easier under windoze (see below)
4250 \begin_layout Itemize
4251 man ; not really needed for building SDCC, but you'll miss it sooner or
4255 \begin_layout Itemize
4256 less ; not really needed for building SDCC, but you'll miss it sooner or
4260 \begin_layout Itemize
4261 svn ; only if you use Subversion access
4264 \begin_layout Standard
4265 If you want to develop something you'll need:
4268 \begin_layout Itemize
4269 python ; for the regression tests
4272 \begin_layout Itemize
4273 gdb ; the gnu debugger, together with the nice GUI
4274 \begin_inset Quotes sld
4278 \begin_inset Quotes srd
4284 \begin_layout Itemize
4285 openssh ; to access the CF or commit changes
4288 \begin_layout Itemize
4289 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
4290 use autoconf-stable!
4293 \begin_layout Standard
4294 rxvt is a nice console with history.
4295 Replace in your cygwin.bat the line
4298 \begin_layout LyX-Code
4303 \begin_layout Standard
4315 \begin_layout Standard
4319 \begin_layout LyX-Code
4320 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
4323 \begin_layout LyX-Code
4324 -bg black -fg white -geometry 100x65 -e bash -
4328 \begin_layout Standard
4340 \begin_layout Standard
4341 Text selected with the mouse is automatically copied to the clipboard, pasting
4342 works with shift-insert.
4346 The other good tip is to make sure you have no //c/-styl
4347 e paths anywhere, use /cygdrive/c/ instead.
4348 Using // invokes a network lookup which is very slow.
4350 \begin_inset Quotes sld
4354 \begin_inset Quotes srd
4357 is too long, you can change it with e.g.
4360 \begin_layout LyX-Code
4364 \begin_layout Standard
4365 SDCC sources use the unix line ending LF.
4366 Life is much easier, if you store the source tree on a drive which is mounted
4368 And use an editor which can handle LF-only line endings.
4369 Make sure not to commit files with windows line endings.
4370 The tabulator spacing
4371 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
4375 used in the project is 8.
4376 Although a tabulator spacing of 8 is a sensible choice for programmers
4377 (it's a power of 2 and allows to display 8/16 bit signed variables without
4378 loosing columns) the plan is to move towards using only spaces in the source.
4381 \begin_layout Subsection
4382 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
4385 \begin_layout Standard
4388 Download the source package
4390 either from the SDCC Subversion repository or from the
4391 \begin_inset LatexCommand \url[snapshot builds]{http://sdcc.sourceforge.net/snap.php}
4397 , it will be named something like sdcc
4401 -yyyymmdd-rrrr.tar.bz2.
4404 SDCC is distributed with all the projects, workspaces, and files you need
4405 to build it using Visual C++ 6.0/NET (except for SDCDB and ucSim).
4406 The workspace name is 'sdcc.dsw'.
4407 Please note that as it is now, all the executables are created in a folder
4411 Once built you need to copy the executables from sdcc
4415 bin before running SDCC.
4420 WARNING: Visual studio is very picky with line terminations; it expects
4421 the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
4422 When using the Subversion repository it's easiest to configure the svn
4423 client to convert automatically for you.
4424 If however you are getting a message such as "This makefile was not generated
4425 by Developer Studio etc.
4427 \begin_inset Quotes srd
4430 when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
4431 need to convert the Unix style line endings to DOS style line endings.
4432 To do so you can use the
4433 \begin_inset Quotes sld
4437 \begin_inset Quotes srd
4440 utility freely available on the internet.
4441 Doug Hawkins reported in the sdcc-user list that this works:
4449 SDCC> unix2dos sdcc.dsw
4455 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
4459 In order to build SDCC with MSVC
4460 you need win32 executables of bison.exe, flex.exe, and gawk.exe.
4461 One good place to get them is
4462 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
4470 Download the file UnxUtils
4471 \begin_inset LatexCommand \index{UnxUtils}
4476 Now you have to install the utilities and setup MSVC so it can locate the
4478 Here there are two alternatives (choose one!):
4481 \begin_layout Enumerate
4486 a) Extract UnxUtils.zip to your C:
4488 hard disk PRESERVING the original paths, otherwise bison won't work.
4489 (If you are using WinZip make certain that 'Use folder names' is selected)
4494 In the Visual C++ IDE click Tools, Options, select the Directory tab, in
4495 'Show directories for:' select 'Executable files', and in the directories
4496 window add a new path: 'C:
4506 (As a side effect, you get a bunch of Unix utilities that
4507 could be useful, such as diff and patch.)
4510 \begin_layout Enumerate
4515 This one avoids extracting a bunch of files you may not
4516 use, but requires some extra work:
4520 a) Create a directory were to put the
4521 tools needed, or use a directory already present.
4528 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and
4529 gawk.exe to such directory WITHOUT preserving the original paths.
4530 (If you are using WinZip make certain that 'Use folder names' is not selected)
4535 ) Rename bison.exe to '_bison.exe'.
4539 d) Create a batch file 'bison.bat' in 'C:
4543 ' and add these lines:
4563 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
4567 Steps 'c' and 'd' are needed
4568 because bison requires by default that the files 'bison.simple' and 'bison.hairy'
4569 reside in some weird Unix directory, '/usr/local/share/' I think.
4570 So it is necessary to tell bison where those files are located if they
4571 are not in such directory.
4572 That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
4577 ) In the Visual C++ IDE click Tools, Options, select the Directory tab,
4578 in 'Show directories for:' select 'Executable files', and in the directories
4579 window add a new path: 'c:
4582 Note that you can use any other path instead of 'c:
4584 util', even the path where the Visual C++ tools are, probably: 'C:
4588 Microsoft Visual Studio
4593 So you don't have to execute step 'e' :)
4596 \begin_layout Standard
4598 Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
4599 the executables from sdcc
4603 bin, and you can compile using SDCC.
4606 \begin_layout Subsection
4607 Building SDCC Using Borland
4610 \begin_layout Enumerate
4611 From the sdcc directory, run the command "make -f Makefile.bcc".
4612 This should regenerate all the .exe files in the bin directory except for
4616 \begin_layout Enumerate
4617 If you modify any source files and need to rebuild, be aware that the dependenci
4618 es may not be correctly calculated.
4619 The safest option is to delete all .obj files and run the build again.
4620 From a Cygwin BASH prompt, this can easily be done with the command (be
4621 sure you are in the sdcc directory):
4631 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
4633 ) -print -exec rm {}
4642 or on Windows NT/2000/XP from the command prompt with the command:
4649 del /s *.obj *.lib *.rul
4652 from the sdcc directory.
4655 \begin_layout Subsection
4656 Windows Install Using a ZIP Package
4659 \begin_layout Enumerate
4660 Download the binary zip package from
4661 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4665 and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
4666 This should unpack to a group of sub-directories.
4667 An example directory structure after unpacking the mingw32 package is:
4672 bin for the executables, c:
4680 lib for the include and libraries.
4683 \begin_layout Enumerate
4684 Adjust your environment variable PATH to include the location of the bin
4685 directory or start sdcc using the full path.
4688 \begin_layout Subsection
4689 Windows Install Using the Setup Program
4690 \begin_inset LatexCommand \label{sub:Windows-Install}
4697 \begin_layout Standard
4698 Download the setup program
4700 sdcc-x.y.z-setup.exe
4702 for an official release from
4705 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
4709 or a setup program for one of the snapshots
4711 sdcc-yyyymmdd-xxxx-setup.exe
4714 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4719 A windows typical installer will guide you through the installation process.
4722 \begin_layout Subsection
4724 \begin_inset LatexCommand \index{VPATH}
4731 \begin_layout Standard
4732 SDCC supports the VPATH feature provided by configure and make.
4733 It allows to separate the source and build trees.
4737 \begin_layout Standard
4764 \begin_layout Standard
4767 tar -xzf sdcc.src.tar.gz\InsetSpace ~
4768 # extract source to directory sdcc
4771 \begin_layout Standard
4774 mkdir sdcc.build\InsetSpace ~
4783 # put output in sdcc.build
4786 \begin_layout Standard
4792 \begin_layout Standard
4795 ../sdcc/configure\InsetSpace ~
4803 # configure is doing all the magic!
4806 \begin_layout Standard
4812 \begin_layout Standard
4818 will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
4819 It automagically computes the variables srcdir, top_srcdir and top_buildir
4825 the generated files will be in ~/sdcc.build, while the source files stay
4828 This is not only usefull for building different binaries, e.g.
4829 when cross compiling.
4830 It also gives you a much better overview in the source tree when all the
4831 generated files are not scattered between the source files.
4832 And the best thing is: if you want to change a file you can leave the original
4833 file untouched in the source directory.
4834 Simply copy it to the build directory, edit it, enter `make clean', `rm
4835 Makefile.dep' and `make'.
4840 will do the rest for you!
4843 \begin_layout Section
4844 Building the Documentation
4847 \begin_layout Standard
4852 \begin_layout Standard
4861 -enable-doc to the configure arguments to build the documentation together
4862 with all the other stuff.
4863 You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
4864 dvips and makeindex) to get the job done.
4865 Another possibility is to change to the doc directory and to type
4869 \begin_inset Quotes srd
4873 \begin_inset Quotes srd
4880 You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
4883 \begin_inset LatexCommand \url{http://www.lyx.org}
4887 as editor is straightforward.
4888 Prebuilt documentation in html and pdf format is available from
4889 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4896 \begin_layout Section
4897 Reading the Documentation
4898 \begin_inset LatexCommand \index{Documentation}
4905 \begin_layout Standard
4906 Currently reading the document in pdf format is recommended, as for unknown
4907 reason the hyperlinks are working there whereas in the html version they
4912 \begin_layout Standard
4913 If you should know why please drop us a note
4921 You'll find the pdf version
4922 \begin_inset LatexCommand \index{PDF version of this document}
4927 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
4935 \begin_inset LatexCommand \index{HTML version of this document}
4940 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
4946 This documentation is in some aspects different from a commercial documentation:
4950 \begin_layout Itemize
4951 It tries to document SDCC for several processor architectures in one document
4952 (commercially these probably would be separate documents/products).
4954 \begin_inset LatexCommand \index{Status of documentation}
4958 currently matches SDCC for mcs51 and DS390 best and does give too few informati
4960 Z80, PIC14, PIC16 and HC08.
4963 \begin_layout Itemize
4964 There are many references pointing away from this documentation.
4965 Don't let this distract you.
4967 was a reference like
4968 \begin_inset LatexCommand \url{http://www.opencores.org}
4972 together with a statement
4973 \begin_inset Quotes sld
4976 some processors which are targetted by SDCC can be implemented in a
4993 \begin_inset LatexCommand \index{FPGA (field programmable gate array)}
4998 \begin_inset Quotes srd
5002 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
5007 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
5012 \begin_inset Quotes sld
5015 have you ever heard of an open source compiler that compiles a subset of
5017 \begin_inset Quotes srd
5020 we expect you to have a quick look there and come back.
5021 If you read this you are on the right track.
5024 \begin_layout Itemize
5025 Some sections attribute more space to problems, restrictions and warnings
5026 than to the solution.
5029 \begin_layout Itemize
5030 The installation section and the section about the debugger is intimidating.
5033 \begin_layout Itemize
5034 There are still lots of typos and there are more different writing styles
5038 \begin_layout Section
5039 Testing the SDCC Compiler
5040 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
5047 \begin_layout Standard
5048 The first thing you should do after installing your SDCC compiler is to
5057 \begin_layout Standard
5067 \begin_inset LatexCommand \index{version}
5074 at the prompt, and the program should run and output its version like:
5079 SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
5083 \begin_layout Standard
5084 If it doesn't run, or gives a message about not finding sdcc program, then
5085 you need to check over your installation.
5086 Make sure that the sdcc bin directory is in your executable search path
5087 defined by the PATH environment setting (
5092 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
5099 Install trouble-shooting for suggestions
5102 Make sure that the sdcc program is in the bin folder, if not perhaps something
5103 did not install correctly.
5111 is commonly installed as described in section
5112 \begin_inset Quotes sld
5115 Install and search paths
5116 \begin_inset Quotes srd
5125 Make sure the compiler works on a very simple example.
5126 Type in the following test.c program using your favorite
5151 \begin_layout Standard
5154 Compile this using the following command:
5163 If all goes well, the compiler will generate a test.asm and test.rel file.
5164 Congratulations, you've just compiled your first program with SDCC.
5165 We used the -c option to tell SDCC not to link the generated code, just
5166 to keep things simple for this step.
5174 The next step is to try it with the linker.
5184 If all goes well the compiler will link with the libraries and produce
5185 a test.ihx output file.
5190 (no test.ihx, and the linker generates warnings), then the problem is most
5199 usr/local/share/sdcc/lib directory
5206 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
5213 Install trouble-shooting for suggestions).
5221 The final test is to ensure
5229 header files and libraries.
5230 Edit test.c and change it to the following:
5248 strcpy(str1, "testing");
5253 \begin_layout Standard
5256 Compile this by typing
5263 This should generate a test.ihx output file, and it should give no warnings
5264 such as not finding the string.h file.
5265 If it cannot find the string.h file, then the problem is that
5269 cannot find the /usr/local/share/sdcc/include directory
5276 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
5283 Install trouble-shooting section for suggestions).
5292 \begin_layout Standard
5304 \begin_inset LatexCommand \index{-\/-print-search-dirs}
5308 to find exactly where SDCC is looking for the include and lib files.
5311 \begin_layout Section
5312 Install Trouble-shooting
5313 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
5318 \begin_inset LatexCommand \index{Install trouble-shooting}
5325 \begin_layout Subsection
5326 If SDCC does not build correctly
5329 \begin_layout Standard
5330 A thing to try is starting from scratch by unpacking the .tgz source package
5331 again in an empty directory.
5339 ./configure 2>&1 | tee configure.log
5353 make 2>&1 | tee make.log
5360 If anything goes wrong, you can review the log files to locate the problem.
5361 Or a relevant part of this can be attached to an email that could be helpful
5362 when requesting help from the mailing list.
5365 \begin_layout Subsection
5367 \begin_inset Quotes sld
5371 \begin_inset Quotes srd
5377 \begin_layout Standard
5379 \begin_inset Quotes sld
5383 \begin_inset Quotes srd
5386 command is a script that analyzes your system and performs some configuration
5387 to ensure the source package compiles on your system.
5388 It will take a few minutes to run, and will compile a few tests to determine
5389 what compiler features are installed.
5392 \begin_layout Subsection
5394 \begin_inset Quotes sld
5398 \begin_inset Quotes srd
5404 \begin_layout Standard
5405 This runs the GNU make tool, which automatically compiles all the source
5406 packages into the final installed binary executables.
5409 \begin_layout Subsection
5411 \begin_inset Quotes sld
5415 \begin_inset Quotes erd
5421 \begin_layout Standard
5422 This will install the compiler, other executables libraries and include
5423 files into the appropriate directories.
5425 \begin_inset LatexCommand \ref{sub:Install-paths}
5431 \begin_inset LatexCommand \ref{sub:Search-Paths}
5436 about install and search paths.
5438 On most systems you will need super-user privilege
5442 \begin_layout Section
5446 \begin_layout Standard
5447 SDCC is not just a compiler, but a collection of tools by various developers.
5448 These include linkers, assemblers, simulators and other components.
5449 Here is a summary of some of the components.
5450 Note that the included simulator and assembler have separate documentation
5451 which you can find in the source package in their respective directories.
5452 As SDCC grows to include support for other processors, other packages from
5453 various developers are included and may have their own sets of documentation.
5458 might want to look at the files which are installed in <installdir>.
5459 At the time of this writing, we find the following programs for gcc-builds:
5464 In <installdir>/bin:
5467 \begin_layout Itemize
5468 sdcc - The compiler.
5471 \begin_layout Itemize
5472 sdcpp - The C preprocessor.
5475 \begin_layout Itemize
5476 asx8051 - The assembler for 8051 type processors.
5479 \begin_layout Itemize
5484 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
5487 \begin_layout Itemize
5488 aslink -The linker for 8051 type processors.
5491 \begin_layout Itemize
5496 link-gbz80 - The Z80 and GameBoy Z80 linkers.
5499 \begin_layout Itemize
5500 s51 - The ucSim 8051 simulator.
5503 \begin_layout Itemize
5504 sdcdb - The source debugger.
5507 \begin_layout Itemize
5508 packihx - A tool to pack (compress) Intel hex files.
5511 \begin_layout Standard
5512 In <installdir>/share/sdcc/include
5515 \begin_layout Itemize
5519 \begin_layout Standard
5520 In <installdir>/share/sdcc/lib
5523 \begin_layout Itemize
5524 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
5528 \begin_layout Standard
5529 In <installdir>/share/sdcc/doc
5532 \begin_layout Itemize
5536 \begin_layout Standard
5537 As development for other processors proceeds, this list will expand to include
5538 executables to support processors like AVR, PIC, etc.
5541 \begin_layout Subsection
5545 \begin_layout Standard
5546 This is the actual compiler, it in turn uses the c-preprocessor and invokes
5547 the assembler and linkage editor.
5550 \begin_layout Subsection
5551 sdcpp - The C-Preprocessor
5554 \begin_layout Standard
5556 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5560 is a modified version of the GNU cpp
5561 \begin_inset LatexCommand \index{cpp|see{sdcpp}}
5566 \begin_inset LatexCommand \url{http://gcc.gnu.org/}
5571 The C preprocessor is used to pull in #include sources, process #ifdef
5572 statements, #defines and so on.
5575 \begin_layout Subsection
5584 - The Assemblers and Linkage Editors
5587 \begin_layout Standard
5588 This is retargettable assembler & linkage editor, it was developed by Alan
5590 John Hartman created the version for 8051, and I (Sandeep) have made some
5591 enhancements and bug fixes for it to work properly with SDCC.
5594 \begin_layout Subsection
5598 \begin_layout Standard
5600 \begin_inset LatexCommand \index{s51}
5604 is a free open source simulator developed by Daniel Drotos.
5605 The simulator is built as part of the build process.
5606 For more information visit Daniel's web site at:
5607 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
5612 It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
5616 \begin_layout Subsection
5617 sdcdb - Source Level Debugger
5620 \begin_layout Standard
5622 \begin_inset LatexCommand \index{SDCDB (debugger)}
5626 is the companion source level debugger.
5627 More about SDCDB in section
5628 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
5633 The current version of the debugger uses Daniel's Simulator S51
5634 \begin_inset LatexCommand \index{s51}
5638 , but can be easily changed to use other simulators.
5641 \begin_layout Chapter
5645 \begin_layout Section
5649 \begin_layout Subsection
5650 Single Source File Projects
5653 \begin_layout Standard
5654 For single source file 8051 projects the process is very simple.
5655 Compile your programs with the following command
5658 "sdcc sourcefile.c".
5662 This will compile, assemble and link your source file.
5663 Output files are as follows:
5666 \begin_layout Itemize
5668 \begin_inset LatexCommand \index{<file>.asm}
5673 \begin_inset LatexCommand \index{Assembler source}
5677 file created by the compiler
5680 \begin_layout Itemize
5682 \begin_inset LatexCommand \index{<file>.lst}
5687 \begin_inset LatexCommand \index{Assembler listing}
5691 file created by the Assembler
5694 \begin_layout Itemize
5696 \begin_inset LatexCommand \index{<file>.rst}
5701 \begin_inset LatexCommand \index{Assembler listing}
5705 file updated with linkedit information, created by linkage editor
5708 \begin_layout Itemize
5710 \begin_inset LatexCommand \index{<file>.sym}
5715 \begin_inset LatexCommand \index{Symbol listing}
5719 for the sourcefile, created by the assembler
5722 \begin_layout Itemize
5724 \begin_inset LatexCommand \index{<file>.rel}
5729 \begin_inset LatexCommand \index{<file>.o}
5734 \begin_inset LatexCommand \index{Object file}
5738 created by the assembler, input to Linkage editor
5741 \begin_layout Itemize
5743 \begin_inset LatexCommand \index{<file>.map}
5748 \begin_inset LatexCommand \index{Memory map}
5752 for the load module, created by the Linker
5755 \begin_layout Itemize
5757 \begin_inset LatexCommand \index{<file>.mem}
5761 - A file with a summary of the memory usage
5764 \begin_layout Itemize
5766 \begin_inset LatexCommand \index{<file>.ihx}
5770 - The load module in Intel hex format
5771 \begin_inset LatexCommand \index{Intel hex format}
5775 (you can select the Motorola S19 format
5776 \begin_inset LatexCommand \index{Motorola S19 format}
5784 \begin_layout Standard
5794 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5799 If you need another format you might want to use
5806 \begin_inset LatexCommand \index{objdump (tool)}
5817 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5822 \begin_inset Note Note
5825 \begin_layout Standard
5832 \begin_inset LatexCommand \vref{sub:Postprocessing-the-Intel}
5837 Both formats are documented in the documentation of srecord
5838 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5845 \begin_layout Itemize
5847 \begin_inset LatexCommand \index{<file>.adb}
5851 - An intermediate file containing debug information needed to create the
5856 \begin_layout Standard
5866 \begin_inset LatexCommand \index{-\/-debug}
5873 \begin_layout Itemize
5875 \begin_inset LatexCommand \index{<file>.cdb}
5879 - An optional file (with -
5883 \begin_layout Standard
5892 -debug) containing debug information.
5893 The format is documented in cdbfileformat.pdf
5896 \begin_layout Itemize
5899 \begin_inset LatexCommand \index{<file> (no extension)}
5903 An optional AOMF or AOMF51
5904 \begin_inset LatexCommand \index{AOMF, AOMF51}
5909 \begin_inset LatexCommand \label{OMF file}
5913 file containing debug information (generated with option -
5917 \begin_layout Standard
5943 ormat is a subformat of the OMF51 format and is commonly used by third party
5945 \begin_inset LatexCommand \index{Debugger}
5949 , simulators, emulators).
5952 \begin_layout Itemize
5954 \begin_inset LatexCommand \index{<file>.dump*}
5958 - Dump file to debug the compiler it self (generated with option -
5962 \begin_layout Standard
5971 -dumpall) (see section
5972 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
5978 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
5984 \begin_inset Quotes sld
5987 Anatomy of the compiler
5988 \begin_inset Quotes srd
5994 \begin_layout Subsection
5995 Postprocessing the Intel Hex
5996 \begin_inset LatexCommand \index{Intel hex format}
6001 \begin_inset LatexCommand \label{sub:Postprocessing-the-Intel}
6008 \begin_layout Standard
6009 In most cases this won't be needed but the Intel Hex file
6010 \begin_inset LatexCommand \index{<file>.ihx}
6014 which is generated by SDCC might include lines of varying length and the
6015 addresses within the file are not guaranteed to be strictly ascending.
6016 If your toolchain or a bootloader does not like this you can use the tool
6022 \begin_inset LatexCommand \index{packihx (tool)}
6026 which is part of the SDCC distribution:
6033 packihx sourcefile.ihx >sourcefile.hex
6040 The separately available
6045 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
6049 package additionally allows to set undefined locations to a predefined
6050 value, to insert checksums
6051 \begin_inset LatexCommand \index{checksum}
6055 of various flavours (crc, add, xor) and to perform other manipulations
6056 (convert, split, crop, offset, ...).
6064 srec_cat\InsetSpace ~
6066 sourcefile.ihx -intel\InsetSpace ~
6068 -o sourcefile.hex -intel
6075 An example for a more complex command line
6079 \begin_layout Standard
6080 the command backfills
6081 \begin_inset LatexCommand \index{backfill unused memory}
6085 unused memory with 0x12 and the overall 16 bit sum of the complete 64 kByte
6087 If the program counter on an mcs51 runs wild the backfill pattern 0x12
6088 will be interpreted as an
6096 (where an emergency routine could sit).
6109 srec_cat\InsetSpace ~
6110 sourcefile.ihx -intel\InsetSpace ~
6112 -fill 0x12 0x0000 0xfffe\InsetSpace ~
6113 -little-endian-checksum-nega
6114 tive 0xfffe 0x02 0x02\InsetSpace ~
6116 -o sourcefile.hex -intel
6125 The srecord package is available at
6126 \begin_inset LatexCommand \url{http://sf.net/projects/srecord}
6133 \begin_layout Subsection
6134 Projects with Multiple Source Files
6137 \begin_layout Standard
6138 SDCC can compile only ONE file at a time.
6139 Let us for example assume that you have a project containing the following
6144 foo1.c (contains some functions)
6146 foo2.c (contains some more functions)
6149 n.c (contains more functions and the function main)
6157 The first two files will need to be compiled separately with the commands:
6189 Then compile the source file containing the
6194 \begin_inset LatexCommand \index{Linker}
6198 the files together with the following command:
6206 foomain.c\InsetSpace ~
6207 foo1.rel\InsetSpace ~
6212 \begin_inset LatexCommand \index{<file>.rel}
6224 can be separately compiled as well:
6235 sdcc foomain.rel foo1.rel foo2.rel
6242 The file containing the
6257 file specified in the command line, since the linkage editor processes
6258 file in the order they are presented to it.
6259 The linker is invoked from SDCC using a script file with extension .lnk
6260 \begin_inset LatexCommand \index{<file>.lnk}
6265 You can view this file to troubleshoot linking problems such as those arising
6266 from missing libraries.
6269 \begin_layout Subsection
6270 Projects with Additional Libraries
6271 \begin_inset LatexCommand \index{Libraries}
6278 \begin_layout Standard
6279 Some reusable routines may be compiled into a library, see the documentation
6280 for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
6284 \begin_inset LatexCommand \index{<file>.lib}
6291 Libraries created in this manner can be included in the command line.
6292 Make sure you include the -L <library-path> option to tell the linker where
6293 to look for these files if they are not in the current directory.
6294 Here is an example, assuming you have the source file
6306 (if that is not the same as your current project):
6313 sdcc foomain.c foolib.lib -L mylib
6324 must be an absolute path name.
6328 The most efficient way to use libraries is
6329 to keep separate modules in separate source files.
6330 The lib file now should name all the modules.rel
6331 \begin_inset LatexCommand \index{<file>.rel}
6336 For an example see the standard library file
6340 in the directory <installdir>/share/lib/small.
6343 \begin_layout Subsection
6344 Using sdcclib to Create and Manage Libraries
6345 \begin_inset LatexCommand \index{sdcclib}
6352 \begin_layout Standard
6353 Alternatively, instead of having a .rel file for each entry on the library
6354 file as described in the preceding section, sdcclib can be used to embed
6355 all the modules belonging to such library in the library file itself.
6356 This results in a larger library file, but it greatly reduces the number
6357 of disk files accessed by the linker.
6358 Additionally, the packed library file contains an index of all include
6359 modules and symbols that significantly speeds up the linking process.
6360 To display a list of options supported by sdcclib type:
6365 \begin_layout Standard
6370 \begin_inset LatexCommand \index{sdcclib}
6381 To create a new library file, start by compiling all the required modules.
6387 \begin_layout Standard
6394 \begin_layout Standard
6401 \begin_layout Standard
6408 \begin_layout Standard
6415 \begin_layout Standard
6424 \begin_layout Standard
6425 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
6427 The next step is to add the .rel files to the library file:
6432 \begin_layout Standard
6436 sdcclib libint.lib _divsint.rel
6439 \begin_inset LatexCommand \index{sdcclib}
6446 \begin_layout Standard
6450 sdcclib libint.lib _divuint.rel
6453 \begin_layout Standard
6457 sdcclib libint.lib _modsint.rel
6460 \begin_layout Standard
6464 sdcclib libint.lib _moduint.rel
6467 \begin_layout Standard
6471 sdcclib libint.lib _mulint.rel
6479 \begin_layout Standard
6488 \begin_layout Standard
6492 sdcclib libint.lib _divsint.rel _divuint.rel _modsint.rel _moduint.rel _mulint.rel
6500 \begin_layout Standard
6501 If the file already exists in the library, it will be replaced.
6502 If a list of .rel files is available, you can tell sdcclib to add those
6504 For example, if the file 'myliblist.txt' contains
6512 \begin_layout Standard
6519 \begin_layout Standard
6526 \begin_layout Standard
6533 \begin_layout Standard
6540 \begin_layout Standard
6552 \begin_layout Standard
6561 \begin_layout Standard
6565 sdcclib -l libint.lib myliblist.txt
6573 \begin_layout Standard
6574 Additionally, you can instruct sdcclib to compiles the files before adding
6575 them to the library.
6576 This is achieved using the environment variables SDCCLIB_CC and/or SDCCLIB_AS.
6585 \begin_layout Standard
6589 set SDCCLIB_CC=sdcc -c
6592 \begin_layout Standard
6596 sdcclib -l libint.lib myliblist.txt
6604 \begin_layout Standard
6605 To see what modules and symbols are included in the library, options -s
6606 and -m are available.
6614 sdcclib -s libint.lib
6617 \begin_inset LatexCommand \index{sdcclib}
6629 \begin_layout Standard
6635 \begin_layout Standard
6641 \begin_layout Standard
6649 \begin_layout Standard
6655 \begin_layout Standard
6661 \begin_layout Standard
6667 \begin_layout Standard
6673 \begin_layout Standard
6681 \begin_layout Standard
6687 \begin_layout Standard
6693 \begin_layout Standard
6701 \begin_layout Standard
6707 \begin_layout Standard
6713 \begin_layout Standard
6719 \begin_layout Standard
6727 \begin_layout Standard
6733 \begin_layout Standard
6744 \begin_layout Standard
6745 If the source files are compiled using -
6749 \begin_layout Standard
6759 \begin_inset LatexCommand \index{-\/-debug}
6763 , the corresponding debug information file .adb will be include in the library
6765 The library files created with sdcclib are plain text files, so they can
6766 be viewed with a text editor.
6767 It is not recomended to modify a library file created with sdcclib using
6768 a text editor, as there are file indexes numbers located accross the file
6769 used by the linker to quickly locate the required module to link.
6770 Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
6771 it can be safely deleted, since all the information required for linking
6772 is embedded in the library file itself.
6773 Library files created using sdcclib are used as described in the preceding
6775 \begin_inset VSpace bigskip
6781 \begin_layout Section
6782 Command Line Options
6783 \begin_inset LatexCommand \index{Command Line Options}
6788 \begin_inset LatexCommand \label{sec:Command-Line-Options}
6795 \begin_layout Subsection
6796 Processor Selection Options
6797 \begin_inset LatexCommand \index{Options processor selection}
6802 \begin_inset LatexCommand \index{Processor selection options}
6810 \labelwidthstring 00.00.0000
6814 \begin_inset LatexCommand \index{-mmcs51}
6820 Generate code for the Intel MCS51
6821 \begin_inset LatexCommand \index{MCS51}
6825 family of processors.
6826 This is the default processor target.
6830 \labelwidthstring 00.00.0000
6834 \begin_inset LatexCommand \index{-mds390}
6840 Generate code for the Dallas DS80C390
6841 \begin_inset LatexCommand \index{DS80C390}
6849 \labelwidthstring 00.00.0000
6853 \begin_inset LatexCommand \index{-mds400}
6859 Generate code for the Dallas DS80C400
6860 \begin_inset LatexCommand \index{DS80C400}
6868 \labelwidthstring 00.00.0000
6872 \begin_inset LatexCommand \index{-mhc08}
6878 Generate code for the Freescale/Motorola HC08
6879 \begin_inset LatexCommand \index{HC08}
6883 family of processors.
6887 \labelwidthstring 00.00.0000
6891 \begin_inset LatexCommand \index{-mz80}
6897 Generate code for the Zilog Z80
6898 \begin_inset LatexCommand \index{Z80}
6902 family of processors.
6906 \labelwidthstring 00.00.0000
6910 \begin_inset LatexCommand \index{-mgbz80}
6916 Generate code for the GameBoy Z80
6917 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
6921 processor (Not actively maintained).
6925 \labelwidthstring 00.00.0000
6929 \begin_inset LatexCommand \index{-mavr}
6935 Generate code for the Atmel AVR
6936 \begin_inset LatexCommand \index{AVR}
6940 processor (Not maintained, not complete).
6941 AVR users should probably have a look at winavr
6942 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
6947 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
6951 , which is based on AVR-port of the gcc compiler.
6954 \begin_layout Standard
6955 \begin_inset Note Note
6958 \begin_layout Standard
6959 I think it is fair to direct users there for now.
6960 Open source is also about avoiding unnecessary work .
6961 But I didn't find the 'official' link.
6970 \labelwidthstring 00.00.0000
6974 \begin_inset LatexCommand \index{-mpic14}
6980 Generate code for the Microchip PIC 14
6981 \begin_inset LatexCommand \index{PIC14}
6985 -bit processors (p16f84 and variants.
6986 In development, not complete).
6989 \begin_layout Standard
6990 \begin_inset Note Note
6993 \begin_layout Standard
6994 p16f627 p16f628 p16f84 p16f873 p16f877?
7003 \labelwidthstring 00.00.0000
7007 \begin_inset LatexCommand \index{-mpic16}
7013 Generate code for the Microchip PIC 16
7014 \begin_inset LatexCommand \index{PIC16}
7018 -bit processors (p18f452 and variants.
7019 In development, not complete).
7023 \labelwidthstring 00.00.0000
7028 Generate code for the Toshiba TLCS-900H
7029 \begin_inset LatexCommand \index{TLCS-900H}
7033 processor (Not maintained, not complete).
7037 \labelwidthstring 00.00.0000
7041 \begin_inset LatexCommand \index{-mxa51}
7047 Generate code for the Phillips XA51
7048 \begin_inset LatexCommand \index{XA51}
7052 processor (Not maintained, not complete).
7055 \begin_layout Standard
7056 \begin_inset VSpace bigskip
7062 \begin_layout Subsection
7063 Preprocessor Options
7064 \begin_inset LatexCommand \index{Options preprocessor}
7069 \begin_inset LatexCommand \index{Preprocessor options}
7074 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
7082 \labelwidthstring 00.00.0000
7086 \begin_inset LatexCommand \index{-I<path>}
7092 The additional location where the preprocessor will look for <..h> or
7093 \begin_inset Quotes eld
7097 \begin_inset Quotes erd
7104 \labelwidthstring 00.00.0000
7108 \begin_inset LatexCommand \index{-D<macro[=value]>}
7114 Command line definition of macros.
7115 Passed to the preprocessor.
7119 \labelwidthstring 00.00.0000
7123 \begin_inset LatexCommand \index{-M}
7129 Tell the preprocessor to output a rule suitable for make describing the
7130 dependencies of each object file.
7131 For each source file, the preprocessor outputs one make-rule whose target
7132 is the object file name for that source file and whose dependencies are
7133 all the files `#include'd in it.
7134 This rule may be a single line or may be continued with `
7136 '-newline if it is long.
7137 The list of rules is printed on standard output instead of the preprocessed
7140 \begin_inset LatexCommand \index{-E}
7148 \labelwidthstring 00.00.0000
7152 \begin_inset LatexCommand \index{-C}
7158 Tell the preprocessor not to discard comments.
7159 Used with the `-E' option.
7163 \labelwidthstring 00.00.0000
7167 \begin_inset LatexCommand \index{-MM}
7178 Like `-M' but the output mentions only the user header files included with
7180 \begin_inset Quotes eld
7184 System header files included with `#include <file>' are omitted.
7188 \labelwidthstring 00.00.0000
7192 \begin_inset LatexCommand \index{-Aquestion(answer)}
7198 Assert the answer answer for question, in case it is tested with a preprocessor
7199 conditional such as `#if #question(answer)'.
7200 `-A-' disables the standard assertions that normally describe the target
7205 \labelwidthstring 00.00.0000
7209 \begin_inset LatexCommand \index{-Umacro}
7215 Undefine macro macro.
7216 `-U' options are evaluated after all `-D' options, but before any `-include'
7217 and `-imacros' options.
7221 \labelwidthstring 00.00.0000
7225 \begin_inset LatexCommand \index{-dM}
7231 Tell the preprocessor to output only a list of the macro definitions that
7232 are in effect at the end of preprocessing.
7233 Used with the `-E' option.
7237 \labelwidthstring 00.00.0000
7241 \begin_inset LatexCommand \index{-dD}
7247 Tell the preprocessor to pass all macro definitions into the output, in
7248 their proper sequence in the rest of the output.
7252 \labelwidthstring 00.00.0000
7256 \begin_inset LatexCommand \index{-dN}
7267 Like `-dD' except that the macro arguments and contents are omitted.
7268 Only `#define name' is included in the output.
7272 \labelwidthstring 00.00.0000
7275 -pedantic-parse-number
7276 \begin_inset LatexCommand \index{pedantic}
7281 \begin_inset LatexCommand \index{-pedantic-parse-number}
7289 \begin_inset LatexCommand \label{lyx:-pedantic-parse-number}
7297 Pedantic parse numbers so that situations like 0xfe-LO_B(3) are parsed properly
7298 and the macro LO_B(3) gets expanded.
7299 See also #pragma pedantic_parse_number
7300 \begin_inset LatexCommand \vpageref{ite:pedantic_parse_number}
7305 \begin_inset LatexCommand \ref{sec:Pragmas}
7311 Note: this functionality is not in conformance with C99 standard!
7315 \labelwidthstring 00.00.0000
7319 preprocessorOption[,preprocessorOption]
7322 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
7327 Pass the preprocessorOption to the preprocessor
7332 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
7337 SDCC uses an adapted version of the preprocessor
7341 of the GNU Compiler Collection
7342 \begin_inset LatexCommand \index{gcc (GNU Compiler Collection)}
7351 \begin_inset LatexCommand \url{http://gcc.gnu.org/}
7355 ), if you need more dedicated options please refer to the GCC\InsetSpace ~
7360 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
7367 \begin_layout Standard
7368 \begin_inset VSpace bigskip
7374 \begin_layout Subsection
7376 \begin_inset LatexCommand \index{Options linker}
7381 \begin_inset LatexCommand \index{Linker options}
7389 \labelwidthstring 00.00.0000
7399 \begin_layout Standard
7411 \begin_inset LatexCommand \index{-\/-lib-path <path>}
7416 \begin_inset LatexCommand \index{-L -\/-lib-path}
7423 <absolute path to additional libraries> This option is passed to the linkage
7424 editor's additional libraries
7425 \begin_inset LatexCommand \index{Libraries}
7430 The path name must be absolute.
7431 Additional library files may be specified in the command line.
7432 See section Compiling programs for more details.
7436 \labelwidthstring 00.00.0000
7443 \begin_layout Standard
7455 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
7460 <Value> The start location of the external ram
7461 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
7465 , default value is 0.
7466 The value entered can be in Hexadecimal or Decimal format, e.g.: -
7470 \begin_layout Standard
7479 -xram-loc 0x8000 or -
7483 \begin_layout Standard
7496 \labelwidthstring 00.00.0000
7503 \begin_layout Standard
7515 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
7520 <Value> The start location of the code
7521 \begin_inset LatexCommand \index{code}
7525 segment, default value 0.
7526 Note when this option is used the interrupt vector table
7527 \begin_inset LatexCommand \index{interrupt vector table}
7531 is also relocated to the given address.
7532 The value entered can be in Hexadecimal or Decimal format, e.g.: -
7536 \begin_layout Standard
7545 -code-loc 0x8000 or -
7549 \begin_layout Standard
7562 \labelwidthstring 00.00.0000
7569 \begin_layout Standard
7581 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
7586 <Value> By default the stack
7587 \begin_inset LatexCommand \index{stack}
7591 is placed after the data segment.
7592 Using this option the stack can be placed anywhere in the internal memory
7594 The value entered can be in Hexadecimal or Decimal format, e.g.
7599 \begin_layout Standard
7608 -stack-loc 0x20 or -
7612 \begin_layout Standard
7622 Since the sp register is incremented before a push or call, the initial
7623 sp will be set to one byte prior the provided value.
7624 The provided value should not overlap any other memory areas such as used
7625 register banks or the data segment and with enough space for the current
7633 \begin_layout Standard
7646 \begin_inset LatexCommand \index{-\/-pack-iram}
7650 option (which is now a default setting) will override this setting, so
7651 you should also specify the
7657 \begin_layout Standard
7670 \begin_inset LatexCommand \index{-\/-no-pack-iram}
7674 option if you need to manually place the stack.
7678 \labelwidthstring 00.00.0000
7685 \begin_layout Standard
7697 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
7702 <Value> By default the external stack
7703 \begin_inset LatexCommand \index{xstack}
7707 is placed after the pdata
7708 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
7713 Using this option the xstack can be placed anywhere in the external memory
7715 The value entered can be in Hexadecimal or Decimal format, e.g.
7720 \begin_layout Standard
7729 -xstack-loc 0x8000 or -
7733 \begin_layout Standard
7743 The provided value should not overlap any other memory areas such as the
7744 pdata or xdata segment and with enough space for the current application.
7748 \labelwidthstring 00.00.0000
7755 \begin_layout Standard
7767 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
7772 <Value> The start location of the internal ram data
7773 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
7778 The value entered can be in Hexadecimal or Decimal format, eg.
7783 \begin_layout Standard
7796 \begin_layout Standard
7806 (By default, the start location of the internal ram data segment is set
7807 as low as possible in memory, taking into account the used register banks
7808 and the bit segment at address 0x20.
7809 For example if register banks 0 and 1 are used without bit variables, the
7810 data segment will be set, if -
7814 \begin_layout Standard
7823 -data-loc is not used, to location 0x10.)
7827 \labelwidthstring 00.00.0000
7834 \begin_layout Standard
7846 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
7851 <Value> The start location of the indirectly addressable internal ram
7852 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
7856 of the 8051, default value is 0x80.
7857 The value entered can be in Hexadecimal or Decimal format, eg.
7862 \begin_layout Standard
7871 -idata-loc 0x88 or -
7875 \begin_layout Standard
7888 \labelwidthstring 00.00.0000
7895 \begin_layout Standard
7907 <Value> The start location of the bit
7908 \begin_inset LatexCommand \index{bit}
7912 addressable internal ram of the 8051.
7918 Instead an option can be passed directly to the linker: -Wl\InsetSpace ~
7923 \labelwidthstring 00.00.0000
7930 \begin_layout Standard
7940 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
7949 The linker output (final object code) is in Intel Hex format.
7950 \begin_inset LatexCommand \index{Intel hex format}
7954 This is the default option.
7955 The format itself is documented in the documentation of srecord
7956 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
7964 \labelwidthstring 00.00.0000
7971 \begin_layout Standard
7981 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
7990 The linker output (final object code) is in Motorola S19 format
7991 \begin_inset LatexCommand \index{Motorola S19 format}
7996 The format itself is documented in the documentation of srecord.
8000 \labelwidthstring 00.00.0000
8007 \begin_layout Standard
8017 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
8022 \begin_inset LatexCommand \index{HC08!Options!-\/-out-fmt-elf}
8031 The linker output (final object code) is in ELF format
8032 \begin_inset LatexCommand \index{ELF format}
8037 (Currently only supported for the HC08
8038 \begin_inset LatexCommand \index{HC08}
8046 \labelwidthstring 00.00.0000
8050 linkOption[,linkOption]
8053 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
8058 \begin_inset LatexCommand \label{lyx:-Wl option}
8063 Pass the linkOption to the linker.
8064 If a bootloader is used an option like
8065 \begin_inset Quotes sld
8070 \begin_inset Quotes srd
8073 would be typical to set the start of the code segment.
8074 Either use the double quotes around this option or use no space (e.g.
8076 See also #pragma constseg and #pragma codeseg in section
8077 \begin_inset LatexCommand \ref{sec:Pragmas}
8082 File sdcc/as/doc/asxhtm.html has more on linker options.
8085 \begin_layout Standard
8086 \begin_inset VSpace bigskip
8092 \begin_layout Subsection
8094 \begin_inset LatexCommand \index{Options MCS51}
8099 \begin_inset LatexCommand \index{MCS51 options}
8107 \labelwidthstring 00.00.0000
8114 \begin_layout Standard
8124 \begin_inset LatexCommand \index{-\/-model-small}
8135 Generate code for Small Model programs, see section Memory Models for more
8137 This is the default model.
8141 \labelwidthstring 00.00.0000
8148 \begin_layout Standard
8158 \begin_inset LatexCommand \index{-\/-model-medium}
8164 Generate code for Medium model programs, see section Memory Models for
8166 If this option is used all source files in the project have to be compiled
8168 It must also be used when invoking the linker.
8172 \labelwidthstring 00.00.0000
8179 \begin_layout Standard
8189 \begin_inset LatexCommand \index{-\/-model-large}
8195 Generate code for Large model programs, see section Memory Models for more
8197 If this option is used all source files in the project have to be compiled
8199 It must also be used when invoking the linker.
8203 \labelwidthstring 00.00.0000
8210 \begin_layout Standard
8220 \begin_inset LatexCommand \index{-\/-xstack}
8226 Uses a pseudo stack in the pdata
8227 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8231 area (usually the first 256 bytes in the external ram) for allocating variables
8232 and passing parameters.
8234 \begin_inset LatexCommand \ref{sub:External-Stack}
8239 External Stack for more details.
8243 \labelwidthstring 00.00.0000
8250 \begin_layout Standard
8263 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
8267 Causes the linker to check if the internal ram usage is within limits of
8272 \labelwidthstring 00.00.0000
8279 \begin_layout Standard
8292 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
8296 Causes the linker to check if the external ram usage is within limits of
8301 \labelwidthstring 00.00.0000
8308 \begin_layout Standard
8321 \begin_inset LatexCommand \index{-\/-code-size <Value>}
8325 Causes the linker to check if the code memory usage is within limits of
8330 \labelwidthstring 00.00.0000
8337 \begin_layout Standard
8350 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
8354 Causes the linker to check if there is at minimum <Value> bytes for stack.
8358 \labelwidthstring 00.00.0000
8365 \begin_layout Standard
8378 \begin_inset LatexCommand \index{-\/-pack-iram}
8382 Causes the linker to use unused register banks for data variables and pack
8383 data, idata and stack together.
8384 This is the default now.
8388 \labelwidthstring 00.00.0000
8395 \begin_layout Standard
8408 \begin_inset LatexCommand \index{-\/-no-pack-iram}
8412 Causes the linker to use old style for allocating memory areas.
8416 \labelwidthstring 00.00.0000
8423 \begin_layout Standard
8436 \begin_inset LatexCommand \index{-\/-acall-ajmp}
8440 Replaces the three byte instructions lcall/ljmp with the two byte instructions
8442 Only use this option if your code is in the same 2k block of memory.
8443 You may need to use this option for some 8051 derivatives which lack the
8444 lcall/ljmp instructions..
8447 \begin_layout Standard
8448 \begin_inset VSpace bigskip
8454 \begin_layout Subsection
8455 DS390 / DS400 Options
8456 \begin_inset LatexCommand \index{Options DS390}
8461 \begin_inset LatexCommand \index{DS390}
8469 \labelwidthstring 00.00.0000
8476 \begin_layout Standard
8488 \begin_inset LatexCommand \index{DS390!Options!-\/-model-flat24}
8498 Generate 24-bit flat mode code.
8499 This is the one and only that the ds390 code generator supports right now
8500 and is default when using
8505 See section Memory Models for more details.
8509 \labelwidthstring 00.00.0000
8516 \begin_layout Standard
8526 \begin_inset LatexCommand \index{DS390!Options!-\/-protect-sp-update}
8532 disable interrupts during ESP:SP updates.
8536 \labelwidthstring 00.00.0000
8543 \begin_layout Standard
8555 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-10bit}
8559 Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
8560 This is the one and only that the ds390 code generator supports right now
8561 and is default when using
8566 In this mode, the stack is located in the lower 1K of the internal RAM,
8567 which is mapped to 0x400000.
8568 Note that the support is incomplete, since it still uses a single byte
8569 as the stack pointer.
8570 This means that only the lower 256 bytes of the potential 1K stack space
8571 will actually be used.
8572 However, this does allow you to reclaim the precious 256 bytes of low RAM
8573 for use for the DATA and IDATA segments.
8574 The compiler will not generate any code to put the processor into 10 bit
8576 It is important to ensure that the processor is in this mode before calling
8577 any re-entrant functions compiled with this option.
8578 In principle, this should work with the
8584 \begin_layout Standard
8594 \begin_inset LatexCommand \index{-\/-stack-auto}
8600 option, but that has not been tested.
8601 It is incompatible with the
8607 \begin_layout Standard
8617 \begin_inset LatexCommand \index{-\/-xstack}
8624 It also only makes sense if the processor is in 24 bit contiguous addressing
8631 \begin_layout Standard
8640 -model-flat24 option
8645 \begin_inset Note Note
8649 \labelwidthstring 00.00.0000
8656 \begin_layout Standard
8665 -stack-8-bit - switches off the 10-bit mode
8674 \labelwidthstring 00.00.0000
8681 \begin_layout Standard
8691 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-probe}
8697 insert call to function __stack_probe at each function prologue.
8701 \labelwidthstring 00.00.0000
8708 \begin_layout Standard
8718 \begin_inset LatexCommand \index{DS390!Options!-\/-tini-libid}
8724 <nnnn> LibraryID used in -mTININative.
8729 \labelwidthstring 00.00.0000
8736 \begin_layout Standard
8746 \begin_inset LatexCommand \index{DS390!Options!-\/-use-accelerator}
8752 generate code for DS390 Arithmetic Accelerator.
8756 \begin_layout Standard
8757 \begin_inset VSpace bigskip
8763 \begin_layout Subsection
8765 \begin_inset LatexCommand \index{Options Z80}
8770 \begin_inset LatexCommand \index{Z80}
8778 \labelwidthstring 00.00.0000
8785 \begin_layout Standard
8797 \begin_inset LatexCommand \index{Z80!Options!-\/-callee-saves-bc}
8807 Force a called function to always save BC.
8811 \labelwidthstring 00.00.0000
8818 \begin_layout Standard
8830 \begin_inset LatexCommand \index{Z80!Options!-\/-no-std-crt0}
8834 When linking, skip the standard crt0.o object file.
8835 You must provide your own crt0.o for your system when linking.
8839 \labelwidthstring 00.00.0000
8846 \begin_layout Standard
8858 \begin_inset LatexCommand \index{Z80!Options!-\/-portmode=<Value>}
8862 Determinate PORT I/O mode (<Value> is z80 or z180).
8866 \labelwidthstring 00.00.0000
8873 \begin_layout Standard
8885 \begin_inset LatexCommand \index{Z80!Options!-\/-asm=<Value>}
8889 Define assembler name (<Value> is rgbds, asxxxx, isas or z80asm).
8893 \labelwidthstring 00.00.0000
8900 \begin_layout Standard
8913 \begin_inset LatexCommand \index{Z80!Options!-\/-codeseg <Value>}
8917 Use <Value> for the code segment name.
8921 \labelwidthstring 00.00.0000
8928 \begin_layout Standard
8941 \begin_inset LatexCommand \index{Z80!Options!-\/-constseg <Value>}
8945 Use <Value> for the const segment name.
8949 \labelwidthstring 00.00.0000
8950 \begin_inset VSpace bigskip
8956 \begin_layout Subsection
8958 \begin_inset LatexCommand \index{Options GBZ80}
8963 \begin_inset LatexCommand \index{GBZ80}
8971 \labelwidthstring 00.00.0000
8978 \begin_layout Standard
8990 \begin_inset LatexCommand \index{GBZ80!Options!-\/-callee-saves-bc}
9000 Force a called function to always save BC.
9004 \labelwidthstring 00.00.0000
9011 \begin_layout Standard
9023 \begin_inset LatexCommand \index{Z80!Options!-\/-no-std-crt0}
9027 When linking, skip the standard crt0.o object file.
9028 You must provide your own crt0.o for your system when linking.
9032 \labelwidthstring 00.00.0000
9039 \begin_inset LatexCommand \index{GBZ80!Options!-bo <Num>}
9043 Use code bank <Num>.
9047 \labelwidthstring 00.00.0000
9054 \begin_inset LatexCommand \index{GBZ80!Options!-ba <Num>}
9058 Use data bank <Num>.
9062 \labelwidthstring 00.00.0000
9069 \begin_layout Standard
9082 \begin_inset LatexCommand \index{GBZ80!Options!-\/-codeseg <Value>}
9086 Use <Value> for the code segment name.
9090 \labelwidthstring 00.00.0000
9097 \begin_layout Standard
9110 \begin_inset LatexCommand \index{GBZ80!Options!-\/-constseg <Value>}
9114 Use <Value> for the const segment name.
9117 \begin_layout Standard
9118 \begin_inset VSpace bigskip
9124 \begin_layout Subsection
9125 Optimization Options
9126 \begin_inset LatexCommand \index{Options optimization}
9131 \begin_inset LatexCommand \index{Optimization options}
9139 \labelwidthstring 00.00.0000
9146 \begin_layout Standard
9156 \begin_inset LatexCommand \index{-\/-nogcse}
9162 Will not do global subexpression elimination, this option may be used when
9163 the compiler creates undesirably large stack/data spaces to store compiler
9173 \begin_inset LatexCommand \index{sloc (spill location)}
9178 A warning message will be generated when this happens and the compiler
9179 will indicate the number of extra bytes it allocated.
9180 It is recommended that this option NOT be used, #pragma\InsetSpace ~
9182 \begin_inset LatexCommand \index{\#pragma nogcse}
9186 can be used to turn off global subexpression elimination
9187 \begin_inset LatexCommand \index{Subexpression elimination}
9191 for a given function only.
9195 \labelwidthstring 00.00.0000
9202 \begin_layout Standard
9212 \begin_inset LatexCommand \index{-\/-noinvariant}
9218 Will not do loop invariant optimizations, this may be turned off for reasons
9219 explained for the previous option.
9220 For more details of loop optimizations performed see Loop Invariants in
9222 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
9227 It is recommended that this option NOT be used, #pragma\InsetSpace ~
9229 \begin_inset LatexCommand \index{\#pragma noinvariant}
9233 can be used to turn off invariant optimizations for a given function only.
9237 \labelwidthstring 00.00.0000
9244 \begin_layout Standard
9254 \begin_inset LatexCommand \index{-\/-noinduction}
9260 Will not do loop induction optimizations, see section strength reduction
9262 It is recommended that this option is NOT used, #pragma\InsetSpace ~
9264 \begin_inset LatexCommand \index{\#pragma noinduction}
9268 can be used to turn off induction optimizations for a given function only.
9272 \labelwidthstring 00.00.0000
9279 \begin_layout Standard
9289 \begin_inset LatexCommand \index{-\/-nojtbound}
9300 Will not generate boundary condition check when switch statements
9301 \begin_inset LatexCommand \index{switch statement}
9305 are implemented using jump-tables.
9307 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
9312 Switch Statements for more details.
9313 It is recommended that this option is NOT used, #pragma\InsetSpace ~
9315 \begin_inset LatexCommand \index{\#pragma nojtbound}
9319 can be used to turn off boundary checking for jump tables for a given function
9324 \labelwidthstring 00.00.0000
9331 \begin_layout Standard
9341 \begin_inset LatexCommand \index{-\/-noloopreverse}
9350 Will not do loop reversal
9351 \begin_inset LatexCommand \index{Loop reversing}
9359 \labelwidthstring 00.00.0000
9364 \begin_layout Standard
9378 \begin_inset LatexCommand \index{-\/-nolabelopt }
9382 Will not optimize labels (makes the dumpfiles more readable).
9386 \labelwidthstring 00.00.0000
9393 \begin_layout Standard
9403 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
9409 Will not memcpy initialized data from code space into xdata space.
9410 This saves a few bytes in code space if you don't have initialized data
9411 \begin_inset LatexCommand \index{Variable initialization}
9419 \labelwidthstring 00.00.0000
9426 \begin_layout Standard
9436 \begin_inset LatexCommand \index{-\/-nooverlay}
9442 The compiler will not overlay parameters and local variables of any function,
9443 see section Parameters and local variables for more details.
9447 \labelwidthstring 00.00.0000
9454 \begin_layout Standard
9464 \begin_inset LatexCommand \index{-\/-no-peep}
9470 Disable peep-hole optimization with built-in rules.
9474 \labelwidthstring 00.00.0000
9481 \begin_layout Standard
9493 \begin_inset LatexCommand \index{-\/-peep-file}
9498 <filename> This option can be used to use additional rules to be used by
9499 the peep hole optimizer.
9501 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
9506 Peep Hole optimizations for details on how to write these rules.
9510 \labelwidthstring 00.00.0000
9517 \begin_layout Standard
9527 \begin_inset LatexCommand \index{-\/-peep-asm}
9533 Pass the inline assembler code through the peep hole optimizer.
9534 This can cause unexpected changes to inline assembler code, please go through
9535 the peephole optimizer
9536 \begin_inset LatexCommand \index{Peephole optimizer}
9540 rules defined in the source file tree '<target>/peeph.def' before using
9545 \labelwidthstring 00.00.0000
9552 \begin_layout Standard
9562 \begin_inset LatexCommand \index{-\/-opt-code-speed}
9568 The compiler will optimize code generation towards fast code, possibly
9569 at the expense of code size.
9573 \labelwidthstring 00.00.0000
9580 \begin_layout Standard
9590 \begin_inset LatexCommand \index{-\/-opt-code-size}
9596 The compiler will optimize code generation towards compact code, possibly
9597 at the expense of code speed.
9600 \begin_layout Standard
9601 \begin_inset VSpace bigskip
9607 \begin_layout Subsection
9609 \begin_inset LatexCommand \index{Options other}
9617 \labelwidthstring 00.00.0000
9625 \begin_layout Standard
9635 \begin_inset LatexCommand \index{-\/-compile-only}
9640 \begin_inset LatexCommand \index{-c -\/-compile-only}
9646 will compile and assemble the source, but will not call the linkage editor.
9650 \labelwidthstring 00.00.0000
9659 \begin_layout Standard
9671 \begin_inset LatexCommand \index{-\/-c1mode}
9677 reads the preprocessed source from standard input and compiles it.
9678 The file name for the assembler output must be specified using the -o option.
9682 \labelwidthstring 00.00.0000
9686 \begin_inset LatexCommand \index{-E}
9692 Run only the C preprocessor.
9693 Preprocess all the C source files specified and output the results to standard
9698 \labelwidthstring 00.00.0000
9703 \begin_inset LatexCommand \index{-o <path/file>}
9709 The output path where everything will be placed or the file name used for
9710 all generated output files.
9711 If the parameter is a path, it must have a trailing slash (or backslash
9712 for the Windows binaries) to be recognized as a path.
9717 Note for Windows users: if the path contains spaces, it should be surrounded
9719 The trailing backslash should be doubled in order to prevent escaping the
9720 final quote, for example:
9723 \begin_inset Quotes sld
9737 \begin_inset Quotes srd
9742 or put after the final quote, for example:
9745 \begin_inset Quotes sld
9755 \begin_inset Quotes srd
9763 The path using slashes for directory delimiters can be used too, for example:
9767 \begin_inset Quotes sld
9770 F:/Projects/test3/output 1/
9771 \begin_inset Quotes srd
9780 \labelwidthstring 00.00.0000
9787 \begin_layout Standard
9797 \begin_inset LatexCommand \index{-\/-stack-auto}
9808 All functions in the source file will be compiled as
9813 \begin_inset LatexCommand \index{reentrant}
9818 the parameters and local variables will be allocated on the stack
9819 \begin_inset LatexCommand \index{stack}
9825 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
9829 Parameters and Local Variables for more details.
9830 If this option is used all source files in the project should be compiled
9832 It automatically implies -
9838 \begin_layout Standard
9849 -int-long-reent and -
9855 \begin_layout Standard
9871 \labelwidthstring 00.00.0000
9878 \begin_layout Standard
9888 \begin_inset LatexCommand \index{-\/-callee-saves}
9893 \begin_inset LatexCommand \label{lyx:--callee-saves-function1[,function2][,function3]...}
9897 function1[,function2][,function3]....
9900 The compiler by default uses a caller saves convention for register saving
9901 across function calls, however this can cause unnecessary register pushing
9902 and popping when calling small functions from larger functions.
9903 This option can be used to switch the register saving convention for the
9904 function names specified.
9905 The compiler will not save registers when calling these functions, no extra
9906 code will be generated at the entry and exit (function prologue
9909 \begin_inset LatexCommand \index{function prologue}
9918 \begin_inset LatexCommand \index{function epilogue}
9924 ) for these functions to save and restore the registers used by these functions,
9925 this can SUBSTANTIALLY reduce code and improve run time performance of
9927 In the future the compiler (with inter procedural analysis) will be able
9928 to determine the appropriate scheme to use for each function call.
9929 DO NOT use this option for built-in functions such as _mulint..., if this
9930 option is used for a library function the appropriate library function
9931 needs to be recompiled with the same option.
9932 If the project consists of multiple source files then all the source file
9933 should be compiled with the same -
9937 \begin_layout Standard
9946 -callee-saves option string.
9947 Also see #pragma\InsetSpace ~
9949 \begin_inset LatexCommand \index{\#pragma callee\_saves}
9954 \begin_inset LatexCommand \vpageref{ite:callee_saves-function1[,function2[,function3...]]--}
9962 \labelwidthstring 00.00.0000
9969 \begin_layout Standard
9979 \begin_inset LatexCommand \index{-\/-all-callee-saves}
9993 \begin_layout Standard
10002 -callee-saves will be applied to all functions by default.
10006 \labelwidthstring 00.00.0000
10013 \begin_layout Standard
10023 \begin_inset LatexCommand \index{-\/-debug}
10032 When this option is used the compiler will generate debug information.
10033 The debug information collected in a file with .cdb extension can be used
10035 For more information see documentation for SDCDB.
10036 Another file with no extension contains debug information in AOMF or AOMF51
10037 \begin_inset LatexCommand \index{AOMF, AOMF51}
10041 format which is commonly used by third party tools.
10045 \labelwidthstring 00.00.0000
10049 \begin_inset LatexCommand \index{-S}
10060 Stop after the stage of compilation proper; do not assemble.
10061 The output is an assembler code file for the input file specified.
10065 \labelwidthstring 00.00.0000
10072 \begin_layout Standard
10082 \begin_inset LatexCommand \index{-\/-int-long-reent}
10088 Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
10089 Note by default these libraries are compiled as non-reentrant.
10090 See section Installation for more details.
10094 \labelwidthstring 00.00.0000
10101 \begin_layout Standard
10111 \begin_inset LatexCommand \index{-\/-cyclomatic}
10120 This option will cause the compiler to generate an information message for
10121 each function in the source file.
10122 The message contains some
10126 information about the function.
10127 The number of edges and nodes the compiler detected in the control flow
10128 graph of the function, and most importantly the
10130 cyclomatic complexity
10131 \begin_inset LatexCommand \index{Cyclomatic complexity}
10137 see section on Cyclomatic Complexity for more details.
10141 \labelwidthstring 00.00.0000
10148 \begin_layout Standard
10158 \begin_inset LatexCommand \index{-\/-float-reent}
10164 Floating point library is compiled as reentrant
10165 \begin_inset LatexCommand \index{reentrant}
10170 See section Installation for more details.
10174 \labelwidthstring 00.00.0000
10181 \begin_layout Standard
10191 \begin_inset LatexCommand \index{-\/-funsigned-char}
10197 The default signedness for every type is
10202 In some embedded environments the default signedness of
10211 To set the signess for characters to unsigned, use the option -
10217 \begin_layout Standard
10229 If this option is set and no signedness keyword (unsigned/signed) is given,
10230 a char will be signed.
10231 All other types are unaffected.
10235 \labelwidthstring 00.00.0000
10242 \begin_layout Standard
10252 \begin_inset LatexCommand \index{-\/-main-return}
10258 This option can be used if the code generated is called by a monitor program
10259 or if the main routine includes an endless loop.
10260 This option results in slightly smaller code and saves two bytes of stack
10262 The return from the 'main'
10263 \begin_inset LatexCommand \index{main return}
10267 function will return to the function calling main.
10268 The default setting is to lock up i.e.
10277 \labelwidthstring 00.00.0000
10284 \begin_layout Standard
10294 \begin_inset LatexCommand \index{-\/-nostdinc}
10300 This will prevent the compiler from passing on the default include path
10301 to the preprocessor.
10305 \labelwidthstring 00.00.0000
10312 \begin_layout Standard
10322 \begin_inset LatexCommand \index{-\/-nostdlib}
10328 This will prevent the compiler from passing on the default library
10329 \begin_inset LatexCommand \index{Libraries}
10333 path to the linker.
10337 \labelwidthstring 00.00.0000
10344 \begin_layout Standard
10354 \begin_inset LatexCommand \index{-\/-verbose}
10360 Shows the various actions the compiler is performing.
10364 \labelwidthstring 00.00.0000
10368 \begin_inset LatexCommand \index{-V}
10374 Shows the actual commands the compiler is executing.
10378 \labelwidthstring 00.00.0000
10385 \begin_layout Standard
10395 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
10401 Hides your ugly and inefficient c-code from the asm file, so you can always
10402 blame the compiler :)
10406 \labelwidthstring 00.00.0000
10413 \begin_layout Standard
10423 \begin_inset LatexCommand \index{-\/-no-gen-comments}
10429 Include code generator and peep-hole comments in the generated asm files.
10433 \labelwidthstring 00.00.0000
10440 \begin_layout Standard
10450 \begin_inset LatexCommand \index{-\/-no-peep-comments}
10456 Don't include peep-hole comments in the generated asm files even if -
10462 \begin_layout Standard
10473 -fverbose-asm option is specified.
10477 \labelwidthstring 00.00.0000
10484 \begin_layout Standard
10494 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
10500 Include i-codes in the asm file.
10501 Sounds like noise but is most helpful for debugging the compiler itself.
10505 \labelwidthstring 00.00.0000
10512 \begin_layout Standard
10522 \begin_inset LatexCommand \index{pedantic}
10527 \begin_inset LatexCommand \index{-\/-less-pedantic}
10534 \begin_inset LatexCommand \label{lyx:--less-pedantic}
10538 Disable some of the more pedantic warnings
10539 \begin_inset LatexCommand \index{Warnings}
10544 For more details, see the less_pedantic pragma
10545 \begin_inset LatexCommand \vpageref{ite:less_pedantic}
10553 \labelwidthstring 00.00.0000
10560 \begin_layout Standard
10569 -disable-warning\InsetSpace ~
10571 \begin_inset LatexCommand \index{-\/-disable-warning}
10577 Disable specific warning with number <nnnn>.
10581 \labelwidthstring 00.00.0000
10588 \begin_layout Standard
10598 \begin_inset LatexCommand \index{-\/-Werror}
10604 Treat all warnings as errors.
10608 \labelwidthstring 00.00.0000
10615 \begin_layout Standard
10625 \begin_inset LatexCommand \index{-\/-print-search-dirs}
10631 Display the directories in the compiler's search path
10635 \labelwidthstring 00.00.0000
10642 \begin_layout Standard
10652 \begin_inset LatexCommand \index{-\/-vc}
10658 Display errors and warnings using MSVC style, so you can use SDCC with
10659 the visual studio IDE
10660 \begin_inset LatexCommand \index{IDE}
10665 With SDCC both offering a GCC-like (the default) and a MSVC-like
10666 \begin_inset LatexCommand \index{MSVC output style}
10670 output style, integration into most programming editors should be straightforwa
10675 \labelwidthstring 00.00.0000
10682 \begin_layout Standard
10692 \begin_inset LatexCommand \index{-\/-use-stdout}
10698 Send errors and warnings to stdout instead of stderr.
10702 \labelwidthstring 00.00.0000
10706 asmOption[,asmOption]
10709 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
10714 Pass the asmOption to the assembler
10715 \begin_inset LatexCommand \index{Options assembler}
10720 \begin_inset LatexCommand \index{Assembler options}
10725 See file sdcc/as/doc/asxhtm.html for assembler options.cd
10729 \labelwidthstring 00.00.0000
10736 \begin_layout Standard
10746 \begin_inset LatexCommand \index{-\/-std-sdcc89}
10752 Generally follow the C89 standard, but allow SDCC features that conflict
10753 with the standard (default).
10757 \labelwidthstring 00.00.0000
10764 \begin_layout Standard
10774 \begin_inset LatexCommand \index{-\/-std-c89}
10780 Follow the C89 standard and disable SDCC features that conflict with the
10785 \labelwidthstring 00.00.0000
10792 \begin_layout Standard
10802 \begin_inset LatexCommand \index{-\/-std-sdcc99}
10808 Generally follow the C99 standard, but allow SDCC features that conflict
10809 with the standard (incomplete support).
10813 \labelwidthstring 00.00.0000
10820 \begin_layout Standard
10830 \begin_inset LatexCommand \index{-\/-std-sdcc99}
10836 Follow the C99 standard and disable SDCC features that conflict with the
10837 standard (incomplete support).
10841 \labelwidthstring 00.00.0000
10848 \begin_layout Standard
10860 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
10865 \begin_inset LatexCommand \label{lyx:-codeseg}
10870 <Name> The name to be used for the code
10871 \begin_inset LatexCommand \index{code}
10875 segment, default CSEG.
10876 This is useful if you need to tell the compiler to put the code in a special
10877 segment so you can later on tell the linker to put this segment in a special
10879 Can be used for instance when using bank switching to put the code in a
10884 \labelwidthstring 00.00.0000
10891 \begin_layout Standard
10903 \begin_inset LatexCommand \index{-\/-constseg <Value>}
10908 <Name> The name to be used for the const
10909 \begin_inset LatexCommand \index{const}
10913 segment, default CONST.
10914 This is useful if you need to tell the compiler to put the const data in
10915 a special segment so you can later on tell the linker to put this segment
10916 in a special place in memory.
10917 Can be used for instance when using bank switching to put the const data
10922 \labelwidthstring 00.00.0000
10929 \begin_layout Standard
10938 -fdollars-in-identifiers
10939 \begin_inset LatexCommand \index{-\/-fdollars-in-identifiers}
10945 Permit '$' as an identifier character.
10949 \labelwidthstring 00.00.0000
10956 \begin_layout Standard
10968 \begin_inset LatexCommand \index{-\/-more-pedantic}
10973 \begin_inset LatexCommand \index{pedantic}
10983 a SDCC compiler option but if you want
10987 warnings you can use a separate tool dedicated to syntax checking like
10989 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
10994 \begin_inset LatexCommand \index{lint (syntax checking tool)}
10999 \begin_inset LatexCommand \url{http://www.splint.org}
11004 To make your source files parseable by splint you will have to include
11010 \begin_inset LatexCommand \index{splint (syntax checking tool)}
11014 in your source file and add brackets around extended keywords (like
11017 \begin_inset Quotes sld
11030 \begin_inset Quotes srd
11038 \begin_inset Quotes sld
11041 __interrupt\InsetSpace ~
11043 \begin_inset Quotes srd
11051 Splint has an excellent on line manual at
11052 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
11056 and it's capabilities go beyond pure syntax checking.
11057 You'll need to tell splint the location of SDCC's include files so a typical
11058 command line could look like this:
11062 splint\InsetSpace ~
11064 /usr/local/share/sdcc/include/mcs51/\InsetSpace ~
11070 \labelwidthstring 00.00.0000
11077 \begin_layout Standard
11089 \begin_inset LatexCommand \index{-\/-short-is-8bits}
11094 \begin_inset LatexCommand \label{lyx:--short-is-8bits}
11098 Treat short as 8-bit (for backward compatibility with older versions of
11099 compiler - see section
11100 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
11107 \begin_layout Standard
11108 \begin_inset VSpace bigskip
11114 \begin_layout Subsection
11115 Intermediate Dump Options
11116 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
11121 \begin_inset LatexCommand \index{Options intermediate dump}
11126 \begin_inset LatexCommand \index{Intermediate dump options}
11133 \begin_layout Standard
11134 The following options are provided for the purpose of retargetting and debugging
11136 They provide a means to dump the intermediate code (iCode
11137 \begin_inset LatexCommand \index{iCode}
11141 ) generated by the compiler in human readable form at various stages of
11142 the compilation process.
11143 More on iCodes see chapter
11144 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
11149 \begin_inset Quotes srd
11152 The anatomy of the compiler
11153 \begin_inset Quotes srd
11160 \labelwidthstring 00.00.0000
11167 \begin_layout Standard
11177 \begin_inset LatexCommand \index{-\/-dumpraw}
11183 This option will cause the compiler to dump the intermediate code into
11186 <source filename>.dumpraw
11188 just after the intermediate code has been generated for a function, i.e.
11189 before any optimizations are done.
11191 \begin_inset LatexCommand \index{Basic blocks}
11195 at this stage ordered in the depth first number, so they may not be in
11196 sequence of execution.
11200 \labelwidthstring 00.00.0000
11207 \begin_layout Standard
11217 \begin_inset LatexCommand \index{-\/-dumpgcse}
11223 Will create a dump of iCodes, after global subexpression elimination
11224 \begin_inset LatexCommand \index{Global subexpression elimination}
11228 , into a file named
11230 <source filename>.dumpgcse.
11234 \labelwidthstring 00.00.0000
11241 \begin_layout Standard
11251 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
11257 Will create a dump of iCodes, after deadcode elimination
11258 \begin_inset LatexCommand \index{Dead-code elimination}
11262 , into a file named
11264 <source filename>.dumpdeadcode.
11268 \labelwidthstring 00.00.0000
11275 \begin_layout Standard
11285 \begin_inset LatexCommand \index{-\/-dumploop}
11294 Will create a dump of iCodes, after loop optimizations
11295 \begin_inset LatexCommand \index{Loop optimization}
11299 , into a file named
11301 <source filename>.dumploop.
11305 \labelwidthstring 00.00.0000
11312 \begin_layout Standard
11322 \begin_inset LatexCommand \index{-\/-dumprange}
11331 Will create a dump of iCodes, after live range analysis
11332 \begin_inset LatexCommand \index{Live range analysis}
11336 , into a file named
11338 <source filename>.dumprange.
11342 \labelwidthstring 00.00.0000
11349 \begin_layout Standard
11359 \begin_inset LatexCommand \index{-\/-dumlrange}
11365 Will dump the life ranges
11366 \begin_inset LatexCommand \index{Live range analysis}
11374 \labelwidthstring 00.00.0000
11381 \begin_layout Standard
11391 \begin_inset LatexCommand \index{-\/-dumpregassign}
11400 Will create a dump of iCodes, after register assignment
11401 \begin_inset LatexCommand \index{Register assignment}
11405 , into a file named
11407 <source filename>.dumprassgn.
11411 \labelwidthstring 00.00.0000
11418 \begin_layout Standard
11428 \begin_inset LatexCommand \index{-\/-dumplrange}
11434 Will create a dump of the live ranges of iTemp's
11438 \labelwidthstring 00.00.0000
11445 \begin_layout Standard
11455 \begin_inset LatexCommand \index{-\/-dumpall}
11466 Will cause all the above mentioned dumps to be created.
11469 \begin_layout Standard
11470 \begin_inset VSpace bigskip
11476 \begin_layout Subsection
11477 Redirecting output on Windows Shells
11480 \begin_layout Standard
11481 By default SDCC writes its error messages to
11482 \begin_inset Quotes sld
11486 \begin_inset Quotes srd
11490 To force all messages to
11491 \begin_inset Quotes sld
11495 \begin_inset Quotes srd
11507 \begin_layout Standard
11522 \begin_inset LatexCommand \index{-\/-use-stdout}
11527 Additionally, if you happen to have visual studio installed in your windows
11528 machine, you can use it to compile your sources using a custom build and
11535 \begin_layout Standard
11547 \begin_inset LatexCommand \index{-\/-vc}
11552 Something like this should work:
11571 \begin_layout Standard
11590 \begin_layout Standard
11602 -model-large -c $(InputPath)
11605 \begin_inset VSpace bigskip
11611 \begin_layout Section
11612 Environment variables
11613 \begin_inset LatexCommand \index{Environment variables}
11620 \begin_layout Standard
11621 SDCC recognizes the following environment variables:
11625 \labelwidthstring 00.00.0000
11629 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
11635 SDCC installs a signal handler
11636 \begin_inset LatexCommand \index{signal handler}
11640 to be able to delete temporary files after an user break (^C) or an exception.
11641 If this environment variable is set, SDCC won't install the signal handler
11642 in order to be able to debug SDCC.
11646 \labelwidthstring 00.00.0000
11652 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
11658 Path, where temporary files will be created.
11659 The order of the variables is the search order.
11660 In a standard *nix environment these variables are not set, and there's
11661 no need to set them.
11662 On Windows it's recommended to set one of them.
11666 \labelwidthstring 00.00.0000
11670 \begin_inset LatexCommand \index{SDCC\_HOME}
11677 \begin_inset LatexCommand \ref{sub:Install-paths}
11683 \begin_inset Quotes sld
11687 \begin_inset Quotes srd
11694 \labelwidthstring 00.00.0000
11698 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
11705 \begin_inset LatexCommand \ref{sub:Search-Paths}
11711 \begin_inset Quotes sld
11715 \begin_inset Quotes srd
11722 \labelwidthstring 00.00.0000
11726 \begin_inset LatexCommand \index{SDCC\_LIB}
11733 \begin_inset LatexCommand \ref{sub:Search-Paths}
11739 \begin_inset Quotes sld
11743 \begin_inset Quotes srd
11749 \begin_layout Standard
11750 There are some more environment variables recognized by SDCC, but these
11751 are solely used for debugging purposes.
11752 They can change or disappear very quickly, and will never be documented.
11753 \begin_inset VSpace bigskip
11759 \begin_layout Section
11760 Storage Class Language Extensions
11763 \begin_layout Subsection
11764 MCS51/DS390 Storage Class
11765 \begin_inset LatexCommand \index{Storage class}
11769 Language Extensions
11772 \begin_layout Standard
11773 In addition to the ANSI storage classes SDCC allows the following MCS51
11774 specific storage classes:
11777 \begin_layout Subsubsection
11779 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
11784 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
11789 \begin_inset LatexCommand \index{near (storage class)}
11794 \begin_inset LatexCommand \index{\_\_near (storage class)}
11801 \begin_layout Standard
11806 storage class for the Small Memory model (
11814 or the more ANSI-C compliant forms
11822 can be used synonymously).
11823 Variables declared with this storage class will be allocated in the directly
11824 addressable portion of the internal RAM of a 8051, e.g.:
11827 \begin_layout Verse
11830 __data unsigned char test_data;
11833 \begin_layout Standard
11834 Writing 0x01 to this variable generates the assembly code:
11837 \begin_layout Verse
11840 75*00 01\InsetSpace ~
11848 \begin_layout Subsubsection
11850 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11855 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
11860 \begin_inset LatexCommand \index{far (storage class)}
11865 \begin_inset LatexCommand \index{\_\_far (storage class)}
11872 \begin_layout Standard
11873 Variables declared with this storage class will be placed in the external
11879 storage class for the Large Memory model, e.g.:
11882 \begin_layout Verse
11885 __xdata unsigned char test_xdata;
11888 \begin_layout Standard
11889 Writing 0x01 to this variable generates the assembly code:
11892 \begin_layout Verse
11895 90s00r00\InsetSpace ~
11926 \begin_layout Subsubsection
11928 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
11933 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
11940 \begin_layout Standard
11941 Variables declared with this storage class will be allocated into the indirectly
11942 addressable portion of the internal ram of a 8051, e.g.:
11945 \begin_layout Verse
11948 __idata unsigned char test_idata;
11951 \begin_layout Standard
11952 Writing 0x01 to this variable generates the assembly code:
11955 \begin_layout Verse
11982 \begin_layout Standard
11983 Please note, the first 128 byte of idata physically access the same RAM
11984 as the data memory.
11985 The original 8051 had 128 byte idata memory, nowadays most devices have
11986 256 byte idata memory.
11988 \begin_inset LatexCommand \index{stack}
11992 is located in idata memory.
11995 \begin_layout Subsubsection
11997 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
12002 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
12009 \begin_layout Standard
12010 Paged xdata access is just as straightforward as using the other addressing
12012 It is typically located at the start of xdata and has a maximum size of
12014 The following example writes 0x01 to the pdata variable.
12015 Please note, pdata access physically accesses xdata memory.
12016 The high byte of the address is determined by port P2
12017 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
12021 (or in case of some 8051 variants by a separate Special Function Register,
12023 \begin_inset LatexCommand \ref{sub:MCS51-variants}
12032 storage class for the Medium Memory model, e.g.:
12035 \begin_layout Verse
12038 __pdata unsigned char test_pdata;
12041 \begin_layout Standard
12042 Writing 0x01 to this variable generates the assembly code:
12045 \begin_layout Verse
12054 mov r0,#_test_pdata
12076 \begin_layout Standard
12081 \begin_layout Standard
12091 \begin_inset LatexCommand \index{-\/-xstack}
12095 option is used the pdata memory area is followed by the xstack memory area
12096 and the sum of their sizes is limited to 256 bytes.
12099 \begin_layout Subsubsection
12101 \begin_inset LatexCommand \index{code}
12106 \begin_inset LatexCommand \index{\_\_code}
12113 \begin_layout Standard
12114 'Variables' declared with this storage class will be placed in the code
12118 \begin_layout Verse
12121 __code unsigned char test_code;
12124 \begin_layout Standard
12125 Read access to this variable generates the assembly code:
12128 \begin_layout Verse
12131 90s00r6F\InsetSpace ~
12134 mov dptr,#_test_code
12159 \begin_layout Standard
12164 indexed arrays of characters in code memory can be accessed efficiently:
12167 \begin_layout Verse
12170 __code char test_array[] = {'c','h','e','a','p'};
12173 \begin_layout Standard
12174 Read access to this array using an 8-bit unsigned index generates the assembly
12178 \begin_layout Verse
12190 \begin_layout Verse
12193 90s00r41\InsetSpace ~
12196 mov dptr,#_test_array
12199 \begin_layout Verse
12214 \begin_layout Subsubsection
12216 \begin_inset LatexCommand \index{bit}
12221 \begin_inset LatexCommand \index{\_\_bit}
12228 \begin_layout Standard
12229 This is a data-type and a storage class specifier.
12230 When a variable is declared as a bit, it is allocated into the bit addressable
12231 memory of 8051, e.g.:
12234 \begin_layout Verse
12240 \begin_layout Standard
12241 Writing 1 to this variable generates the assembly code:
12244 \begin_layout Verse
12258 \begin_layout Standard
12259 The bit addressable memory consists of 128 bits which are located from 0x20
12260 to 0x2f in data memory.
12263 Apart from this 8051 specific storage class most architectures support
12265 \begin_inset LatexCommand \index{bitfields}
12273 \begin_layout Standard
12274 Not really meant as examples, but nevertheless showing what bitfields are
12275 about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
12281 In accordance with ISO/IEC 9899 bits and bitfields without an explicit
12282 signed modifier are implemented as unsigned.
12285 \begin_layout Subsubsection
12287 \begin_inset LatexCommand \index{sfr}
12292 \begin_inset LatexCommand \index{\_\_sfr}
12297 \begin_inset LatexCommand \index{sfr16}
12302 \begin_inset LatexCommand \index{\_\_sfr16}
12307 \begin_inset LatexCommand \index{sfr32}
12312 \begin_inset LatexCommand \index{\_\_sfr32}
12317 \begin_inset LatexCommand \index{\_\_sbit}
12322 \begin_inset LatexCommand \index{sbit}
12329 \begin_layout Standard
12330 Like the bit keyword,
12332 sfr / sfr16 / sfr32 / sbit
12334 signify both a data-type and storage class, they are used to describe the
12355 variables of a 8051, eg:
12358 \begin_layout Verse
12362 \begin_inset LatexCommand \index{at}
12367 \begin_inset LatexCommand \index{\_\_at}
12371 (0x80) P0;\InsetSpace ~
12372 /* special function register P0 at location 0x80 */
12377 special function register combination for timer 0
12381 with the high byte at
12382 location 0x8C and the low byte at location 0x8A */
12384 __sfr16 __at (0x8C8A)
12390 \begin_inset LatexCommand \index{at}
12395 \begin_inset LatexCommand \index{\_\_at}
12399 (0xd7) CY;\InsetSpace ~
12401 \begin_inset LatexCommand \index{Flags}
12406 \begin_inset LatexCommand \index{Carry flag}
12413 \begin_layout Standard
12414 Special function registers which are located on an address dividable by
12415 8 are bit-addressable, an
12419 addresses a specific bit within these sfr.
12421 16 Bit and 32 bit special function
12422 register combinations which require a certain access order are better not
12432 Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
12433 this is not guaranteed.
12438 \begin_layout Standard
12439 Please note, if you use a header file which was written for another compiler
12440 then the sfr / sfr16 / sfr32 / sbit Storage Class extensions will most
12446 Specifically the syntax
12449 sfr P0 = 0x80;\InsetSpace ~
12456 by SDCC to an assignment of 0x80 to a variable called P0
12459 \begin_inset Marginal
12462 \begin_layout Standard
12474 Nevertheless it is possible to write header files
12475 \begin_inset LatexCommand \index{Header files}
12480 \begin_inset LatexCommand \index{Include files}
12484 which can be shared among different compilers (see section
12485 \begin_inset LatexCommand \ref{sec:Porting-code-to-other-compilers}
12493 \begin_layout Subsubsection
12495 \begin_inset LatexCommand \index{Pointer}
12499 to MCS51/DS390 specific memory spaces
12502 \begin_layout Standard
12503 SDCC allows (via language extensions) pointers to explicitly point to any
12504 of the memory spaces
12505 \begin_inset LatexCommand \index{Memory model}
12510 In addition to the explicit pointers, the compiler uses (by default) generic
12511 pointers which can be used to point to any of the memory spaces.
12516 declaration examples:
12519 \begin_layout Verse
12522 /* pointer physically in internal ram pointing to object in external ram
12525 __xdata unsigned char * __data p;
12529 /* pointer physically in external ram
12530 pointing to object in internal ram */
12532 __data unsigned char * __xdata p;
12537 pointer physically in code rom pointing to data in xdata space */
12540 unsigned char * __code p;
12544 /* pointer physically in code space pointing to
12545 data in code space */
12547 __code unsigned char * __code p;
12552 physically located in xdata space */
12554 unsigned char * __xdata p;
12559 pointer physically located in default memory space */
12566 the following is a function pointer
12567 \begin_inset LatexCommand \index{function pointer}
12571 physically located in data space */
12573 char (* __data fp)(void);
12576 \begin_layout Standard
12577 Well you get the idea.
12582 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
12595 The highest order byte of the
12599 pointers contains the data space information.
12600 Assembler support routines are called whenever data is stored or retrieved
12606 These are useful for developing reusable library
12607 \begin_inset LatexCommand \index{Libraries}
12612 Explicitly specifying the pointer
12613 \begin_inset LatexCommand \index{pointer}
12617 type will generate the most efficient code.
12620 \begin_layout Subsubsection
12621 Notes on MCS51 memory
12622 \begin_inset LatexCommand \index{MCS51 memory}
12629 \begin_layout Standard
12630 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
12631 RAM memory which is structured as follows:
12635 - Bytes 00-1F - 32 bytes to hold
12636 up to 4 banks of the registers R0 to R7,
12638 - Bytes 20-2F - 16 bytes to hold
12640 \begin_inset LatexCommand \index{bit}
12646 - Bytes 30-7F - 80 bytes for general purpose use.
12651 \begin_layout Standard
12652 Additionally some members of the MCS51 family may have up to 128 bytes of
12653 additional, indirectly addressable, internal RAM memory (
12658 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
12663 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
12668 Furthermore, some chips may have some built in external memory (
12673 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
12678 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
12682 ) which should not be confused with the internal, directly addressable RAM
12688 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
12693 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
12698 Sometimes this built in
12702 memory has to be activated before using it (you can probably find this
12703 information on the datasheet of the microcontroller your are using, see
12705 \begin_inset LatexCommand \ref{sub:Startup-Code}
12713 \begin_layout Standard
12714 Normally SDCC will only use the first bank
12715 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
12719 of registers (register bank 0), but it is possible to specify that other
12720 banks of registers (keyword
12727 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12732 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12738 ) should be used for example in interrupt
12739 \begin_inset LatexCommand \index{interrupt}
12744 \begin_inset LatexCommand \index{\_\_interrupt}
12749 By default, the compiler will place the stack after the last byte of allocated
12750 memory for variables.
12751 For example, if the first 2 banks of registers are used, and only four
12756 variables, it will position the base of the internal stack at address 20
12758 This implies that as the stack
12759 \begin_inset LatexCommand \index{stack}
12763 grows, it will use up the remaining register banks, and the 16 bytes used
12764 by the 128 bit variables, and 80 bytes for general purpose use.
12765 If any bit variables are used, the data variables will be placed in unused
12766 register banks and after the byte holding the last bit variable.
12767 For example, if register banks 0 and 1 are used, and there are 9 bit variables
12772 variables will be placed starting from address 0x10 to 0x20 and continue
12778 \begin_layout Standard
12788 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
12792 to specify the start address of the
12800 \begin_layout Standard
12810 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
12814 to specify the size of the total internal RAM (
12828 \begin_layout Standard
12829 By default the 8051 linker will place the stack after the last byte of (i)data
12835 \begin_layout Standard
12845 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
12849 allows you to specify the start of the stack, i.e.
12850 you could start it after any data in the general purpose area.
12851 If your microcontroller has additional indirectly addressable internal
12856 ) you can place the stack on it.
12857 You may also need to use -
12861 \begin_layout Standard
12871 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
12875 to set the start address of the external RAM (
12883 \begin_layout Standard
12893 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
12897 to specify its size.
12898 Same goes for the code memory, using -
12902 \begin_layout Standard
12912 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
12920 \begin_layout Standard
12930 \begin_inset LatexCommand \index{-\/-code-size <Value>}
12935 If in doubt, don't specify any options and see if the resulting memory
12936 layout is appropriate, then you can adjust it.
12939 \begin_layout Standard
12940 The linker generates two files with memory allocation information.
12941 The first, with extension .map
12942 \begin_inset LatexCommand \index{<file>.map}
12946 shows all the variables and segments.
12947 The second with extension .mem
12948 \begin_inset LatexCommand \index{<file>.mem}
12952 shows the final memory layout.
12953 The linker will complain either if memory segments overlap, there is not
12954 enough memory, or there is not enough space for stack.
12955 If you get any linking warnings and/or errors related to stack or segments
12956 allocation, take a look at either the .map or .mem files to find out what
12958 The .mem file may even suggest a solution to the problem.
12959 \begin_inset VSpace bigskip
12965 \begin_layout Subsection
12966 Z80/Z180 Storage Class
12967 \begin_inset LatexCommand \index{Z80!Storage class}
12971 Language Extensions
12974 \begin_layout Subsubsection
12976 \begin_inset LatexCommand \index{sfr}
12981 \begin_inset LatexCommand \index{\_\_sfr}
12985 (in/out to 8-bit addresses)
12988 \begin_layout Standard
12990 \begin_inset LatexCommand \index{Z80}
12994 family has separate address spaces for memory and
13004 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
13009 \begin_inset LatexCommand \index{Z80!I/O memory}
13014 \begin_inset LatexCommand \index{Z180!I/O memory}
13018 is accessed with special instructions, e.g.:
13021 \begin_layout Verse
13024 sfr at 0x78 IoPort;\InsetSpace ~
13026 /* define a var in I/O space at 78h called IoPort */
13030 \begin_layout Standard
13031 Writing 0x01 to this variable generates the assembly code:
13034 \begin_layout Verse
13054 \begin_layout Subsubsection
13056 \begin_inset LatexCommand \index{sfr}
13061 \begin_inset LatexCommand \index{\_\_sfr}
13065 (in/out to 16-bit addresses)
13068 \begin_layout Standard
13073 is used to support 16 bit addresses in I/O memory e.g.:
13076 \begin_layout Verse
13080 \begin_inset LatexCommand \index{at}
13085 \begin_inset LatexCommand \index{\_\_at}
13092 \begin_layout Standard
13093 Writing 0x01 to this variable generates the assembly code:
13096 \begin_layout Verse
13099 01 23 01\InsetSpace ~
13121 \begin_layout Subsubsection
13123 \begin_inset LatexCommand \index{sfr}
13128 \begin_inset LatexCommand \index{\_\_sfr}
13132 (in0/out0 to 8 bit addresses on Z180
13133 \begin_inset LatexCommand \index{Z180}
13138 \begin_inset LatexCommand \index{HD64180 (see Z180)}
13145 \begin_layout Standard
13146 The compiler option -
13150 \begin_layout Standard
13160 \begin_inset LatexCommand \index{Z180!Options!-\/-portmode}
13164 =180 (80) and a compiler #pragma\InsetSpace ~
13166 \begin_inset LatexCommand \index{Z180!Pragmas!\#pragma portmode}
13170 z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
13180 If you include the file z180.h this will be set automatically.
13181 \begin_inset VSpace bigskip
13187 \begin_layout Subsection
13189 \begin_inset LatexCommand \index{HC08!Storage class}
13193 Language Extensions
13196 \begin_layout Subsubsection
13198 \begin_inset LatexCommand \index{data (hc08 storage class)}
13203 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
13210 \begin_layout Standard
13211 The data storage class declares a variable that resides in the first 256
13212 bytes of memory (the direct page).
13214 \begin_inset LatexCommand \index{HC08}
13218 is most efficient at accessing variables (especially pointers) stored here.
13221 \begin_layout Subsubsection
13223 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
13228 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
13235 \begin_layout Standard
13236 The xdata storage class declares a variable that can reside anywhere in
13238 This is the default if no storage class is specified.
13240 \begin_inset VSpace bigskip
13246 \begin_layout Section
13247 Other SDCC language extensions
13248 \begin_inset LatexCommand \index{Other SDCC language extensions}
13255 \begin_layout Subsection
13259 \begin_layout Standard
13260 SDCC supports the use of binary constants, such as 0b01100010.
13261 This feature is only enabled when the compiler is invoked using --std-sdccxx.
13264 \begin_layout Standard
13265 \begin_inset VSpace bigskip
13271 \begin_layout Section
13272 Absolute Addressing
13273 \begin_inset LatexCommand \index{Absolute addressing}
13280 \begin_layout Standard
13281 Data items can be assigned an absolute address with the
13284 \begin_inset LatexCommand \index{at}
13289 \begin_inset LatexCommand \index{\_\_at}
13295 keyword, in addition to a storage class, e.g.:
13298 \begin_layout Verse
13302 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
13307 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
13312 \begin_inset LatexCommand \index{at}
13317 \begin_inset LatexCommand \index{\_\_at}
13321 0x7ffe unsigned int chksum;
13324 \begin_layout Standard
13325 or, better conforming to ISO/IEC 9899 C:
13328 \begin_layout Verse
13331 __xdata __at (0x7ffe) unsigned int chksum;
13334 \begin_layout Standard
13335 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
13336 of the external ram.
13341 reserve any space for variables declared in this way
13342 \begin_inset Marginal
13345 \begin_layout Standard
13354 (they are implemented with an equate in the assembler).
13355 Thus it is left to the programmer to make sure there are no overlaps with
13356 other variables that are declared without the absolute address.
13357 The assembler listing file (.lst
13358 \begin_inset LatexCommand \index{<file>.lst}
13362 ) and the linker output files (.rst
13363 \begin_inset LatexCommand \index{<file>.rst}
13368 \begin_inset LatexCommand \index{<file>.map}
13372 ) are good places to look for such overlaps.
13375 \begin_layout Standard
13376 If however you provide an initializer
13377 \begin_inset LatexCommand \index{Variable initialization}
13381 actual memory allocation will take place and overlaps will be detected
13386 \begin_layout Verse
13389 __code __at (0x7ff0) char Id[5] =
13390 \begin_inset Quotes sld
13394 \begin_inset Quotes srd
13400 \begin_layout Standard
13401 In the above example the variable Id will be located from 0x7ff0 to 0x7ff4
13405 \begin_layout Standard
13406 In case of memory mapped I/O devices the keyword
13410 has to be used to tell the compiler that accesses might not be removed:
13413 \begin_layout Verse
13417 \begin_inset LatexCommand \index{volatile}
13422 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
13427 \begin_inset LatexCommand \index{at}
13431 (0x8000) unsigned char PORTA_8255;
13434 \begin_layout Standard
13435 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
13440 \begin_inset LatexCommand \index{Aligned array}
13447 starts at a block (256 byte) boundary
13448 \begin_inset LatexCommand \index{block boundary}
13453 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
13459 Absolute addresses can be specified for variables in all
13460 storage classes, e.g.:
13463 \begin_layout Verse
13467 \begin_inset LatexCommand \index{bit}
13472 \begin_inset LatexCommand \index{at}
13479 \begin_layout Standard
13480 The above example will allocate the variable at offset 0x02 in the bit-addressab
13482 There is no real advantage to assigning absolute addresses to variables
13483 in this manner, unless you want strict control over all the variables allocated.
13484 One possible use would be to write hardware portable code.
13485 For example, if you have a routine that uses one or more of the microcontroller
13486 I/O pins, and such pins are different for two different hardwares, you
13487 can declare the I/O pins in your routine using:
13490 \begin_layout Verse
13494 \begin_inset LatexCommand \index{volatile}
13498 __bit MOSI;\InsetSpace ~
13502 /* master out, slave in */
13504 extern volatile __bit MISO;\InsetSpace ~
13511 extern volatile __bit MCLK;\InsetSpace ~
13520 Output of a byte on a 3-wire serial bus.
13525 If needed adapt polarity of clock,
13526 polarity of data and bit order
13531 unsigned char spi_io(unsigned char out_byte)
13556 MOSI = out_byte & 0x80;
13587 /* _asm nop _endasm; */\InsetSpace ~
13595 /* for slow peripherals */
13647 \begin_layout Standard
13648 Then, someplace in the code for the first hardware you would use
13651 \begin_layout Verse
13655 \begin_inset LatexCommand \index{at}
13660 \begin_inset LatexCommand \index{\_\_at}
13664 (0x80) MOSI;\InsetSpace ~
13668 /* I/O port 0, bit 0 */
13670 __bit __at (0x81) MISO;\InsetSpace ~
13677 __bit __at (0x82) MCLK;\InsetSpace ~
13681 /* I/O port 0, bit 2 */
13684 \begin_layout Standard
13685 Similarly, for the second hardware you would use
13688 \begin_layout Verse
13691 __bit __at (0x83) MOSI;\InsetSpace ~
13695 /* I/O port 0, bit 3 */
13697 __bit __at (0x91) MISO;\InsetSpace ~
13702 I/O port 1, bit 1 */
13705 \begin_inset LatexCommand \index{bit}
13709 __at (0x92) MCLK;\InsetSpace ~
13713 /* I/O port 1, bit 2 */
13716 \begin_layout Standard
13717 and you can use the same hardware dependent routine without changes, as
13718 for example in a library.
13719 This is somehow similar to sbit, but only one absolute address has to be
13720 specified in the whole project.
13721 \begin_inset VSpace bigskip
13727 \begin_layout Section
13729 \begin_inset LatexCommand \index{Parameters}
13734 \begin_inset LatexCommand \index{function parameter}
13739 \begin_inset LatexCommand \index{local variables}
13744 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
13751 \begin_layout Standard
13752 Automatic (local) variables and parameters to functions can either be placed
13753 on the stack or in data-space.
13754 The default action of the compiler is to place these variables in the internal
13755 RAM (for small model) or external RAM (for medium or large model).
13756 This in fact makes them similar to
13759 \begin_inset LatexCommand \index{static}
13765 so by default functions are non-reentrant
13766 \begin_inset LatexCommand \index{reentrant}
13775 They can be placed on the stack
13776 \begin_inset LatexCommand \index{stack}
13786 \begin_layout Standard
13796 \begin_inset LatexCommand \index{-\/-stack-auto}
13804 #pragma\InsetSpace ~
13808 \begin_inset LatexCommand \index{\#pragma stackauto}
13815 \begin_inset LatexCommand \index{reentrant}
13821 keyword in the function declaration, e.g.:
13824 \begin_layout Verse
13827 unsigned char foo(char i) __reentrant
13841 \begin_layout Standard
13842 Since stack space on 8051 is limited, the
13852 \begin_layout Standard
13863 option should be used sparingly.
13864 Note that the reentrant keyword just means that the parameters & local
13865 variables will be allocated to the stack, it
13869 mean that the function is register bank
13870 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
13879 \begin_inset LatexCommand \index{local variables}
13883 can be assigned storage classes and absolute
13884 \begin_inset LatexCommand \index{Absolute addressing}
13891 \begin_layout Verse
13894 unsigned char foo()
13902 __xdata unsigned char i;
13915 \begin_inset LatexCommand \index{at}
13919 (0x31) unsigned char j;
13931 \begin_layout Standard
13932 In the above example the variable
13936 will be allocated in the external ram,
13940 in bit addressable space and
13951 \begin_layout Standard
13962 or when a function is declared as
13966 this should only be done for static variables.
13969 \begin_layout Standard
13971 \begin_inset LatexCommand \index{function parameter}
13975 however are not allowed any storage class
13976 \begin_inset LatexCommand \index{Storage class}
13980 , (storage classes for parameters will be ignored), their allocation is
13981 governed by the memory model in use, and the reentrancy options.
13984 \begin_layout Standard
13985 It is however allowed to use bit parameters in reentrant functions and also
13986 non-static local bit variables are supported.
13987 Efficient use is limited to 8 semi-bitregisters in bit space.
13988 They are pushed and popped to stack
13989 \begin_inset LatexCommand \index{stack}
13993 as a single byte just like the normal registers.
13996 \begin_layout Section
13998 \begin_inset LatexCommand \label{sub:Overlaying}
14003 \begin_inset LatexCommand \index{Overlaying}
14010 \begin_layout Standard
14012 \begin_inset LatexCommand \index{reentrant}
14016 functions SDCC will try to reduce internal ram space usage by overlaying
14017 parameters and local variables of a function (if possible).
14018 Parameters and local variables
14019 \begin_inset LatexCommand \index{local variables}
14023 of a function will be allocated to an overlayable segment if the function
14026 no other function calls and the function is non-reentrant and the memory
14028 \begin_inset LatexCommand \index{Memory model}
14035 If an explicit storage class
14036 \begin_inset LatexCommand \index{Storage class}
14040 is specified for a local variable, it will NOT be overlayed.
14043 \begin_layout Standard
14044 Note that the compiler (not the linkage editor) makes the decision for overlayin
14046 Functions that are called from an interrupt service routine
14047 \begin_inset Marginal
14050 \begin_layout Standard
14058 should be preceded by a #pragma\InsetSpace ~
14060 \begin_inset LatexCommand \index{\#pragma nooverlay}
14064 if they are not reentrant.
14067 \begin_layout Standard
14068 Also note that the compiler does not do any processing of inline assembler
14069 code, so the compiler might incorrectly assign local variables and parameters
14070 of a function into the overlay segment if the inline assembler code calls
14071 other c-functions that might use the overlay.
14072 In that case the #pragma\InsetSpace ~
14073 nooverlay should be used.
14076 \begin_layout Standard
14077 Parameters and local variables of functions that contain 16 or 32 bit multiplica
14079 \begin_inset LatexCommand \index{Multiplication}
14084 \begin_inset LatexCommand \index{Division}
14088 will NOT be overlayed since these are implemented using external functions,
14092 \begin_layout Verse
14098 \begin_inset LatexCommand \index{\#pragma nooverlay}
14104 void set_error(unsigned char errcd)
14121 some_isr () __interrupt
14122 \begin_inset LatexCommand \index{interrupt}
14152 \begin_layout Standard
14153 In the above example the parameter
14161 would be assigned to the overlayable segment if the #pragma\InsetSpace ~
14163 not present, this could cause unpredictable runtime behavior when called
14164 from an interrupt service routine.
14165 The #pragma\InsetSpace ~
14166 nooverlay ensures that the parameters and local variables for
14167 the function are NOT overlayed.
14168 \begin_inset VSpace bigskip
14174 \begin_layout Section
14175 Interrupt Service Routines
14176 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
14183 \begin_layout Subsection
14184 General Information
14187 \begin_layout Standard
14200 outines to be coded in C, with some extended keywords.
14203 \begin_layout Verse
14206 void timer_isr (void) __interrupt (1) __using (1)
14220 \begin_layout Standard
14221 The optional number following the
14224 \begin_inset LatexCommand \index{interrupt}
14229 \begin_inset LatexCommand \index{\_\_interrupt}
14235 keyword is the interrupt number this routine will service.
14236 When present, the compiler will insert a call to this routine in the interrupt
14238 \begin_inset LatexCommand \index{interrupt vector table}
14242 for the interrupt number specified.
14243 If you have multiple source files in your project, interrupt service routines
14244 can be present in any of them, but a prototype of the isr MUST be present
14245 or included in the file that contains the function
14250 The optional (8051 specific) keyword
14253 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
14258 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
14264 can be used to tell the compiler to use the specified register bank when
14265 generating code for this function.
14268 Interrupt service routines open the door for some very interesting bugs:
14271 \begin_layout Subsubsection
14272 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-volatile}
14276 Common interrupt pitfall: variable not declared
14281 \begin_layout Standard
14282 If an interrupt service routine changes variables which are accessed by
14283 other functions these variables have to be declared
14288 \begin_inset LatexCommand \index{volatile}
14294 \begin_inset LatexCommand \url{http://en.wikipedia.org/wiki/Volatile_variable}
14301 \begin_layout Subsubsection
14302 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-atomic}
14306 Common interrupt pitfall:
14311 \begin_layout Standard
14312 If the access to these variables is not
14315 \begin_inset LatexCommand \index{atomic}
14322 the processor needs more than one instruction for the access and could
14323 be interrupted while accessing the variable) the interrupt must be disabled
14324 during the access to avoid inconsistent data.
14327 Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
14328 and should be protected by disabling interrupts.
14329 You're not automatically on the safe side if you use 8 bit variables though.
14330 We need an example here: f.e.
14331 on the 8051 the harmless looking
14332 \begin_inset Quotes srd
14342 \begin_inset Quotes sld
14351 \begin_inset Quotes srd
14361 \begin_inset Quotes sld
14364 from within an interrupt routine might get lost if the interrupt occurs
14367 \begin_inset Quotes sld
14372 counter\InsetSpace ~
14377 \begin_inset Quotes srd
14380 is not atomic on the 8051 even if
14384 is located in data memory.
14386 Bugs like these are hard to reproduce and can
14387 cause a lot of trouble.
14391 \begin_layout Subsubsection
14392 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-stack-overflow}
14396 Common interrupt pitfall:
14401 \begin_layout Standard
14402 The return address and the registers used in the interrupt service routine
14403 are saved on the stack
14404 \begin_inset LatexCommand \index{stack}
14408 so there must be sufficient stack space.
14409 If there isn't variables or registers (or even the return address itself)
14416 \begin_inset LatexCommand \index{stack overflow}
14420 is most likely to happen if the interrupt occurs during the
14421 \begin_inset Quotes sld
14425 \begin_inset Quotes srd
14428 subroutine when the stack is already in use for f.e.
14429 many return addresses.
14432 \begin_layout Subsubsection
14433 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-reentrant}
14437 Common interrupt pitfall:
14439 use of non-reentrant functions
14442 \begin_layout Standard
14443 A special note here, int (16 bit) and long (32 bit) integer division
14444 \begin_inset LatexCommand \index{Division}
14449 \begin_inset LatexCommand \index{Multiplication}
14454 \begin_inset LatexCommand \index{Modulus}
14459 \begin_inset LatexCommand \index{Floating point support}
14463 operations are implemented using external support routines.
14464 If an interrupt service routine needs to do any of these operations then
14465 the support routines (as mentioned in a following section) will have to
14466 be recompiled using the
14472 \begin_layout Standard
14482 \begin_inset LatexCommand \index{-\/-stack-auto}
14488 option and the source file will need to be compiled using the
14494 \begin_layout Standard
14506 \begin_inset LatexCommand \index{-\/-int-long-reent}
14513 Note, the type promotion
14514 \begin_inset LatexCommand \index{type promotion}
14518 required by ANSI C can cause 16 bit routines to be used
14519 \begin_inset Marginal
14522 \begin_layout Standard
14531 without the programmer being aware of it.
14535 (unsigned char)(tail-1)
14537 within the if clause in section
14538 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
14545 \begin_layout Standard
14546 Calling other functions from an interrupt service routine is not recommended,
14547 avoid it if possible.
14548 Note that when some function is called from an interrupt service routine
14549 it should be preceded by a #pragma\InsetSpace ~
14551 \begin_inset LatexCommand \index{\#pragma nooverlay}
14555 if it is not reentrant.
14556 Furthermore nonreentrant functions should not be called from the main program
14557 while the interrupt service routine might be active.
14558 They also must not be called from low priority interrupt service routines
14559 while a high priority interrupt service routine might be active.
14560 You could use semaphores or make the function
14564 if all parameters are passed in registers.
14567 \begin_inset LatexCommand \ref{sub:Overlaying}
14572 about Overlaying and section
14573 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
14578 about Functions using private register banks.
14579 \begin_inset VSpace bigskip
14585 \begin_layout Subsection
14586 MCS51/DS390 Interrupt Service Routines
14589 \begin_layout Standard
14591 \begin_inset LatexCommand \index{interrupt}
14595 numbers and the corresponding address & descriptions for the Standard 8051/8052
14597 SDCC will automatically adjust the
14598 \begin_inset LatexCommand \index{interrupt vector table}
14602 to the maximum interrupt number specified.
14607 \begin_layout Standard
14609 \begin_inset Tabular
14610 <lyxtabular version="3" rows="9" columns="3">
14612 <column alignment="center" valignment="top" leftline="true" width="0in">
14613 <column alignment="left" valignment="top" leftline="true" width="0in">
14614 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
14615 <row topline="true" bottomline="true">
14616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14619 \begin_layout Standard
14625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14628 \begin_layout Standard
14634 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14637 \begin_layout Standard
14644 <row topline="true">
14645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14648 \begin_layout Standard
14654 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14657 \begin_layout Standard
14663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14666 \begin_layout Standard
14673 <row topline="true">
14674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14677 \begin_layout Standard
14683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14686 \begin_layout Standard
14692 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14695 \begin_layout Standard
14702 <row topline="true">
14703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14706 \begin_layout Standard
14712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14715 \begin_layout Standard
14721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14724 \begin_layout Standard
14731 <row topline="true">
14732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14735 \begin_layout Standard
14741 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14744 \begin_layout Standard
14750 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14753 \begin_layout Standard
14760 <row topline="true">
14761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14764 \begin_layout Standard
14770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14773 \begin_layout Standard
14779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14782 \begin_layout Standard
14789 <row topline="true">
14790 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14793 \begin_layout Standard
14799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14802 \begin_layout Standard
14808 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14811 \begin_layout Standard
14818 <row topline="true">
14819 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14822 \begin_layout Standard
14828 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14831 \begin_layout Standard
14837 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14840 \begin_layout Standard
14847 <row topline="true" bottomline="true">
14848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14851 \begin_layout Standard
14857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14860 \begin_layout Standard
14866 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14869 \begin_layout Standard
14885 \begin_layout Standard
14886 If the interrupt service routine is defined without
14889 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
14894 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
14900 a register bank or with register bank 0 (
14904 0), the compiler will save the registers used by itself on the stack upon
14905 entry and restore them at exit, however if such an interrupt service routine
14906 calls another function then the entire register bank will be saved on the
14908 This scheme may be advantageous for small interrupt service routines which
14909 have low register usage.
14912 \begin_layout Standard
14913 If the interrupt service routine is defined to be using a specific register
14918 & psw are saved and restored, if such an interrupt service routine calls
14919 another function (using another register bank) then the entire register
14920 bank of the called function will be saved on the stack
14921 \begin_inset LatexCommand \index{stack}
14926 This scheme is recommended for larger interrupt service routines.
14927 \begin_inset VSpace bigskip
14933 \begin_layout Subsection
14935 \begin_inset LatexCommand \index{HC08}
14939 Interrupt Service Routines
14942 \begin_layout Standard
14943 Since the number of interrupts
14944 \begin_inset LatexCommand \index{HC08!interrupt}
14948 available is chip specific and the interrupt vector table always ends at
14949 the last byte of memory, the interrupt numbers corresponds to the interrupt
14950 vectors in reverse order of address.
14951 For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
14952 2 will use the interrupt vector at 0xfffa, and so on.
14953 However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
14954 this way; instead see section
14955 \begin_inset LatexCommand \ref{sub:Startup-Code}
14959 for details on customizing startup.
14960 \begin_inset VSpace bigskip
14966 \begin_layout Subsection
14967 Z80 Interrupt Service Routines
14970 \begin_layout Standard
14972 \begin_inset LatexCommand \index{Z80}
14976 uses several different methods for determining the correct interrupt
14977 \begin_inset LatexCommand \index{Z80!interrupt}
14981 vector depending on the hardware implementation.
14982 Therefore, SDCC ignores the optional interrupt number and does not attempt
14983 to generate an interrupt vector table.
14986 \begin_layout Standard
14987 By default, SDCC generates code for a maskable interrupt, which uses a RETI
14988 instruction to return from the interrupt.
14989 To write an interrupt handler for the non-maskable interrupt, which needs
14990 a RETN instruction instead, add the
14997 \begin_layout Verse
15000 void nmi_isr (void) critical interrupt
15014 \begin_layout Standard
15015 However if you need to create a non-interruptable interrupt service routine
15016 you would also require the
15021 To distinguish between this and an nmi_isr you must provide an interrupt
15023 \begin_inset VSpace bigskip
15029 \begin_layout Section
15030 Enabling and Disabling Interrupts
15033 \begin_layout Subsection
15034 Critical Functions and Critical Statements
15037 \begin_layout Standard
15038 A special keyword may be associated with a block or a function declaring
15044 SDCC will generate code to disable all interrupts
15045 \begin_inset LatexCommand \index{interrupt}
15049 upon entry to a critical function and restore the interrupt enable to the
15050 previous state before returning.
15051 Nesting critical functions will need one additional byte on the stack
15052 \begin_inset LatexCommand \index{stack}
15059 \begin_layout Verse
15062 int foo () __critical
15063 \begin_inset LatexCommand \index{critical}
15068 \begin_inset LatexCommand \index{\_\_critical}
15093 \begin_layout Standard
15094 The critical attribute maybe used with other attributes like
15104 may also be used to disable interrupts more locally:
15107 \begin_layout Verse
15113 \begin_layout Standard
15114 More than one statement could have been included in the block.
15117 \begin_layout Subsection
15118 Enabling and Disabling Interrupts directly
15121 \begin_layout Standard
15123 \begin_inset LatexCommand \index{interrupt}
15127 can also be disabled and enabled directly (8051):
15130 \begin_layout Verse
15133 EA = 0;\InsetSpace ~
15159 \begin_layout Verse
15195 \begin_layout Verse
15198 EA = 1;\InsetSpace ~
15227 \begin_layout Verse
15266 \begin_layout Standard
15267 On other architectures which have seperate opcodes for enabling and disabling
15268 interrupts you might want to make use of defines with inline assembly
15269 \begin_inset LatexCommand \index{Assembler routines}
15274 \begin_inset LatexCommand \index{HC08!interrupt}
15281 \begin_layout Verse
15285 \begin_inset LatexCommand \index{\_asm}
15294 \begin_inset LatexCommand \index{\_endasm}
15301 \begin_layout Verse
15304 #define SEI _asm\InsetSpace ~
15311 \begin_layout Verse
15317 \begin_layout Standard
15318 Note: it is sometimes sufficient to disable only a specific interrupt source
15320 a timer or serial interrupt by manipulating an
15323 \begin_inset LatexCommand \index{interrupt mask}
15333 \begin_layout Standard
15334 Usually the time during which interrupts are disabled should be kept as
15336 This minimizes both
15341 \begin_inset LatexCommand \index{interrupt latency}
15345 (the time between the occurrence of the interrupt and the execution of
15346 the first code in the interrupt routine) and
15351 \begin_inset LatexCommand \index{interrupt jitter}
15355 (the difference between the shortest and the longest interrupt latency).
15356 These really are something different, f.e.
15357 a serial interrupt has to be served before its buffer overruns so it cares
15358 for the maximum interrupt latency, whereas it does not care about jitter.
15359 On a loudspeaker driven via a digital to analog converter which is fed
15360 by an interrupt a latency of a few milliseconds might be tolerable, whereas
15361 a much smaller jitter will be very audible.
15364 \begin_layout Standard
15365 You can reenable interrupts within an interrupt routine and on some architecture
15366 s you can make use of two (or more) levels of
15368 interrupt priorities
15371 \begin_inset LatexCommand \index{interrupt priority}
15376 On some architectures which don't support interrupt priorities these can
15377 be implemented by manipulating the interrupt mask and reenabling interrupts
15378 within the interrupt routine.
15379 Check there is sufficient space on the stack
15380 \begin_inset LatexCommand \index{stack}
15384 and don't add complexity unless you have to.
15388 \begin_layout Subsection
15390 \begin_inset LatexCommand \index{semaphore}
15394 locking (mcs51/ds390)
15397 \begin_layout Standard
15398 Some architectures (mcs51/ds390) have an atomic
15399 \begin_inset LatexCommand \index{atomic}
15412 These type of instructions are typically used in preemptive multitasking
15413 systems, where a routine f.e.
15414 claims the use of a data structure ('acquires a lock
15415 \begin_inset LatexCommand \index{lock}
15419 on it'), makes some modifications and then releases the lock when the data
15420 structure is consistent again.
15421 The instruction may also be used if interrupt and non-interrupt code have
15422 to compete for a resource.
15423 With the atomic bit test and clear instruction interrupts
15424 \begin_inset LatexCommand \index{interrupt}
15428 don't have to be disabled for the locking operation.
15432 \begin_layout Standard
15433 SDCC generates this instruction if the source follows this pattern:
15436 \begin_layout Verse
15440 \begin_inset LatexCommand \index{volatile}
15444 bit resource_is_free;
15448 if (resource_is_free)
15458 resource_is_free=0;
15471 resource_is_free=1;
15478 \begin_layout Standard
15479 Note, mcs51 and ds390 support only an atomic
15480 \begin_inset LatexCommand \index{atomic}
15488 instruction (as opposed to atomic bit test and
15493 \begin_layout Section
15494 Functions using private register banks
15495 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
15502 \begin_layout Standard
15503 Some architectures have support for quickly changing register sets.
15504 SDCC supports this feature with the
15507 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
15512 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
15518 attribute (which tells the compiler to use a register bank
15519 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
15523 other than the default bank zero).
15524 It should only be applied to
15527 \begin_inset LatexCommand \index{interrupt}
15533 functions (see footnote below).
15534 This will in most circumstances make the generated ISR code more efficient
15535 since it will not have to save registers on the stack.
15538 \begin_layout Standard
15543 attribute will have no effect on the generated code for a
15547 function (but may occasionally be useful anyway
15551 \begin_layout Standard
15552 possible exception: if a function is called ONLY from 'interrupt' functions
15553 using a particular bank, it can be declared with the same 'using' attribute
15554 as the calling 'interrupt' functions.
15555 For instance, if you have several ISRs using bank one, and all of them
15556 call memcpy(), it might make sense to create a specialized version of memcpy()
15557 'using 1', since this would prevent the ISR from having to save bank zero
15558 to the stack on entry and switch to bank zero before calling the function
15567 (pending: Note, nowadays the
15571 attribute has an effect on
15575 the generated code for a
15586 \begin_layout Standard
15591 function using a non-zero bank will assume that it can trash that register
15592 bank, and will not save it.
15593 Since high-priority interrupts
15594 \begin_inset LatexCommand \index{interrupts}
15599 \begin_inset LatexCommand \index{interrupt priority}
15603 can interrupt low-priority ones on the 8051 and friends, this means that
15604 if a high-priority ISR
15608 a particular bank occurs while processing a low-priority ISR
15612 the same bank, terrible and bad things can happen.
15613 To prevent this, no single register bank should be
15617 by both a high priority and a low priority ISR.
15618 This is probably most easily done by having all high priority ISRs use
15619 one bank and all low priority ISRs use another.
15620 If you have an ISR which can change priority at runtime, you're on your
15621 own: I suggest using the default bank zero and taking the small performance
15625 \begin_layout Standard
15626 It is most efficient if your ISR calls no other functions.
15627 If your ISR must call other functions, it is most efficient if those functions
15628 use the same bank as the ISR (see note 1 below); the next best is if the
15629 called functions use bank zero.
15630 It is very inefficient to call a function using a different, non-zero bank
15633 \begin_inset VSpace bigskip
15639 \begin_layout Section
15641 \begin_inset LatexCommand \label{sub:Startup-Code}
15646 \begin_inset LatexCommand \index{Startup code}
15653 \begin_layout Subsection
15654 MCS51/DS390 Startup Code
15657 \begin_layout Standard
15658 The compiler triggers the linker to link certain initialization modules
15659 from the runtime library
15660 \begin_inset LatexCommand \index{Runtime library}
15664 called crt<something>.
15665 Only the necessary ones are linked, for instance crtxstack.asm (GSINIT1,
15666 GSINIT5) is not linked unless the -
15672 \begin_layout Standard
15683 -xstack option is used.
15684 These modules are highly entangled by the use of special segments/areas,
15685 but a common layout is shown below:
15688 \begin_layout Verse
15696 \begin_layout Verse
15720 ljmp __sdcc_gsinit_startup
15723 \begin_layout Verse
15731 \begin_layout Verse
15743 .area GSINIT0 (CODE)
15745 __sdcc_gsinit_startup::
15755 mov sp,#__start__stack - 1
15758 \begin_layout Verse
15766 \begin_layout Verse
15778 .area GSINIT1 (CODE)
15780 __sdcc_init_xstack::
15782 ; Need to initialize in GSINIT1 in
15783 case the user's __sdcc_external_startup uses the xstack.
15793 mov __XPAGE,#(__start__x
15804 mov _spx,#__start__xstack
15807 \begin_layout Verse
15815 \begin_layout Verse
15827 .area GSINIT2 (CODE)
15837 lcall __sdcc_external_startup
15857 jz __sdcc_init_data
15868 __sdcc_program_startup
15873 \begin_layout Verse
15881 \begin_layout Verse
15893 .area GSINIT3 (CODE)
15946 mov r2,#((l_XINIT+255) >> 8)
15977 __XPAGE,#(s_XISEG >> 8)
15979 00001$:\InsetSpace ~
16043 00002$:\InsetSpace ~
16070 \begin_layout Verse
16078 \begin_layout Verse
16090 .area GSINIT4 (CODE)
16092 __mcs51_genRAMCLEAR::
16114 00004$:\InsetSpace ~
16128 ; _mcs51_genRAMCLEAR() end
16131 \begin_layout Verse
16139 \begin_layout Verse
16151 .area GSINIT4 (CODE)
16153 __mcs51_genXRAMCLEAR::
16214 mov __XPAGE,#(s_PSEG >> 8)
16226 00005$:\InsetSpace ~
16301 mov r1,#((l_XSEG + 255) >> 8)
16323 00007$:\InsetSpace ~
16360 \begin_layout Verse
16368 \begin_layout Verse
16380 .area GSINIT5 (CODE)
16382 ; Need to initialize in GSINIT5 because __mcs51_genXINIT
16385 ; and __mcs51_genRAMCLEAR modifies _spx.
16395 mov __XPAGE,#(__start__x
16406 mov _spx,#__start__xstack
16409 \begin_layout Verse
16414 (application modules)
16417 \begin_layout Verse
16429 .area GSINIT (CODE)
16432 \begin_layout Verse
16440 \begin_layout Verse
16452 .area GSFINAL (CODE)
16462 ljmp __sdcc_program_startup
16464 ;---------------------------------
16465 -----------------------
16469 ;--------------------------------------------------
16492 __sdcc_program_startup:
16505 return from main will lock up
16518 \begin_layout Standard
16519 One of these modules (crtstart.asm) contains a call to the C routine
16521 _sdcc_external_startup()
16522 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
16531 at the start of the CODE area.
16532 This routine is also in the runtime library
16533 \begin_inset LatexCommand \index{Runtime library}
16537 and returns 0 by default.
16538 If this routine returns a non-zero value, the static & global variable
16539 initialization will be skipped and the function main will be invoked.
16540 Otherwise static & global variables will be initialized before the function
16544 _sdcc_external_startup()
16546 routine to your program to override the default if you need to setup hardware
16547 or perform some other critical operation prior to static & global variable
16549 \begin_inset LatexCommand \index{Variable initialization}
16554 On some mcs51 variants xdata
16555 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
16559 memory has to be explicitly enabled before it can be accessed or if the
16561 \begin_inset LatexCommand \index{watchdog}
16565 needs to be disabled, this is the place to do it.
16566 The startup code clears all internal data memory, 256 bytes by default,
16567 but from 0 to n-1 if
16573 \begin_layout Standard
16583 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
16590 (recommended for Chipcon CC1010).
16593 \begin_layout Standard
16594 See also the compiler options
16600 \begin_layout Standard
16616 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
16626 \begin_layout Standard
16638 \begin_inset LatexCommand \index{-\/-main-return}
16643 \begin_inset LatexCommand \ref{sub:MCS51-variants}
16647 about MCS51-variants.
16652 \begin_layout Standard
16653 While these initialization modules are meant as generic startup code there
16654 might be the need for customization.
16655 Let's assume the return value of
16657 _sdcc_external_startup()
16663 should not be checked (or
16665 _sdcc_external_startup()
16667 should not be called at all).
16668 The recommended way would be to copy
16674 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/device/lib/mcs51/crtstart.asm}
16678 ) into the source directory, adapt it there, then assemble it with
16684 \begin_layout Standard
16685 \begin_inset Quotes sld
16689 \begin_inset Quotes srd
16692 are the assembler options used in
16693 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/lib/mcs51/Makefile.in?view=markup }
16704 and when linking your project explicitely specify
16709 As a bonus a listing of the relocated object file
16716 \begin_layout Standard
16717 \begin_inset VSpace bigskip
16723 \begin_layout Subsection
16727 \begin_layout Standard
16729 \begin_inset LatexCommand \index{HC08}
16733 startup code follows the same scheme as the MCS51 startup code.
16734 \begin_inset VSpace bigskip
16740 \begin_layout Subsection
16744 \begin_layout Standard
16746 \begin_inset LatexCommand \index{Z80}
16750 the startup code is inserted by linking with crt0.o which is generated from
16751 sdcc/device/lib/z80/crt0.s.
16752 If you need a different startup code you can use the compiler option
16761 \begin_layout Standard
16776 \begin_inset LatexCommand \index{-\/-no-std-crt0}
16780 and provide your own crt0.o.
16782 \begin_inset VSpace bigskip
16788 \begin_layout Section
16789 Inline Assembler Code
16790 \begin_inset LatexCommand \index{Assembler routines}
16797 \begin_layout Subsection
16798 A Step by Step Introduction
16799 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
16806 \begin_layout Standard
16807 Starting from a small snippet of c-code this example shows for the MCS51
16808 how to use inline assembly, access variables, a function parameter and
16809 an array in xdata memory.
16810 The example uses an MCS51 here but is easily adapted for other architectures.
16811 This is a buffer routine which should be optimized:
16814 \begin_layout Verse
16818 unsigned char __far
16819 \begin_inset LatexCommand \index{far (storage class)}
16824 \begin_inset LatexCommand \index{\_\_far (storage class)}
16829 \begin_inset LatexCommand \index{at}
16834 \begin_inset LatexCommand \index{\_\_at}
16838 (0x7f00) buf[0x100];
16839 \begin_inset LatexCommand \index{Aligned array}
16845 unsigned char head, tail;\InsetSpace ~
16863 \begin_inset LatexCommand \index{interrupt}
16915 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
16927 void to_buffer( unsigned char c )
16935 if( head != (unsigned char)(tail-1)
16942 \begin_inset LatexCommand \index{promotion to signed int}
16947 \begin_inset LatexCommand \index{type promotion}
16952 \begin_inset Marginal
16955 \begin_layout Standard
16974 buf[ head++ ] = c;\InsetSpace ~
16990 /* access to a 256 byte aligned array */
16995 \begin_layout Standard
16996 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
16997 then a corresponding buffer.asm file is generated.
16998 We define a new function
17002 in file buffer.c in which we cut and paste the generated code, removing
17003 unwanted comments and some ':'.
17005 \begin_inset Quotes sld
17013 \begin_inset Quotes srd
17017 \begin_inset Quotes sld
17025 \begin_inset Quotes srd
17032 \begin_layout Standard
17033 Note, that the single underscore form (_asm and _endasm) are not C99-compatible,
17034 and for C-99 compatibility, the double-underscore form (__asm and __endasm)
17036 The latter is also used in the library functions.
17041 to the beginning and the end of the function body:
17044 \begin_layout Verse
17048 /* With a cut and paste from the .asm file, we have something to start with.
17054 function is not yet OK! (registers aren't saved) */
17056 void to_buffer_asm(
17066 \begin_inset LatexCommand \index{\_asm}
17071 \begin_inset LatexCommand \index{\_\_asm}
17085 ;buffer.c if( head != (unsigned char)(tail-1) ) \InsetSpace ~
17091 \begin_inset LatexCommand \index{promotion to signed int}
17096 \begin_inset LatexCommand \index{type promotion}
17149 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
17150 \begin_inset LatexCommand \index{Aligned array}
17216 \begin_inset LatexCommand \index{\_endasm}
17221 \begin_inset LatexCommand \index{\_\_endasm}
17230 \begin_layout Standard
17231 The new file buffer.c should compile with only one warning about the unreferenced
17232 function argument 'c'.
17233 Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
17234 (1) and finally have:
17237 \begin_layout Verse
17241 unsigned char __far __at(0x7f00) buf[0x100];
17243 unsigned char head, tail;
17254 void to_buffer( unsigned char c )
17263 head != (unsigned char)(tail-1) )
17292 c; // to avoid warning: unreferenced function argument
17299 \begin_inset LatexCommand \index{\_asm}
17304 \begin_inset LatexCommand \index{\_\_asm}
17318 ; save used registers here.
17329 ; If we were still using r2,r3 we would have to push them here.
17332 ; if( head != (unsigned char)(tail-1) )
17376 could do an ANL a,#0x0f here to use a smaller buffer (see below)
17412 a,dpl \InsetSpace ~
17419 ; dpl holds lower byte of function argument
17431 dpl,_head \InsetSpace ~
17434 ; buf is 0x100 byte aligned so head can be used directly
17477 ; we could do an ANL _head,#0x0f here to use a
17478 smaller buffer (see above)
17490 ; restore used registers here
17497 \begin_inset LatexCommand \index{\_endasm}
17502 \begin_inset LatexCommand \index{\_\_endasm}
17513 \begin_layout Standard
17514 The inline assembler code can contain any valid code understood by the assembler
17515 , this includes any assembler directives and comment lines.
17516 The assembler does not like some characters like ':' or ''' in comments.
17517 You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
17518 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
17523 \begin_inset LatexCommand \index{Assembler documentation}
17528 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html}
17536 \begin_layout Standard
17537 The compiler does not do any validation of the code within the
17540 \begin_inset LatexCommand \index{\_asm}
17545 \begin_inset LatexCommand \index{\_\_asm}
17553 \begin_inset LatexCommand \index{\_endasm}
17558 \begin_inset LatexCommand \index{\_\_endasm}
17567 Specifically it will not know which registers are used and thus register
17569 \begin_inset LatexCommand \index{push/pop}
17573 has to be done manually.
17577 \begin_layout Standard
17578 It is recommended that each assembly instruction (including labels) be placed
17579 in a separate line (as the example shows).
17584 \begin_layout Standard
17596 \begin_inset LatexCommand \index{-\/-peep-asm}
17602 command line option is used, the inline assembler code will be passed through
17603 the peephole optimizer
17604 \begin_inset LatexCommand \index{Peephole optimizer}
17609 There are only a few (if any) cases where this option makes sense, it might
17610 cause some unexpected changes in the inline assembler code.
17611 Please go through the peephole optimizer rules defined in file
17615 before using this option.
17618 \begin_layout Subsection
17620 \begin_inset LatexCommand \label{sub:Naked-Functions}
17625 \begin_inset LatexCommand \index{Naked functions}
17632 \begin_layout Standard
17633 A special keyword may be associated with a function declaring it as
17636 \begin_inset LatexCommand \index{\_naked}
17641 \begin_inset LatexCommand \index{\_\_naked}
17652 function modifier attribute prevents the compiler from generating prologue
17653 \begin_inset LatexCommand \index{function prologue}
17658 \begin_inset LatexCommand \index{function epilogue}
17662 code for that function.
17663 This means that the user is entirely responsible for such things as saving
17664 any registers that may need to be preserved, selecting the proper register
17665 bank, generating the
17669 instruction at the end, etc.
17670 Practically, this means that the contents of the function must be written
17671 in inline assembler.
17672 This is particularly useful for interrupt functions, which can have a large
17673 (and often unnecessary) prologue/epilogue.
17674 For example, compare the code generated by these two functions:
17677 \begin_layout Verse
17681 \begin_inset LatexCommand \index{volatile}
17685 data unsigned char counter;
17689 void simpleInterrupt(void) __interrupt
17690 \begin_inset LatexCommand \index{interrupt}
17695 \begin_inset LatexCommand \index{\_\_interrupt}
17713 void nakedInterrupt(void) __interrupt (2) __naked
17722 \begin_inset LatexCommand \index{\_asm}
17727 \begin_inset LatexCommand \index{\_\_asm}
17744 _counter ; does not change flags, no need to save psw
17757 include ret or reti in _naked function.
17764 \begin_inset LatexCommand \index{\_endasm}
17769 \begin_inset LatexCommand \index{\_\_endasm}
17778 \begin_layout Standard
17779 For an 8051 target, the generated simpleInterrupt looks like:
17782 \begin_layout Verse
17789 example, recent versions of SDCC generate
17795 code for simpleInterrupt() and nakedInterrupt()!
17936 \begin_layout Standard
17937 whereas nakedInterrupt looks like:
17940 \begin_layout Verse
17953 _counter ; does not change flags, no need to save psw
17972 MUST explicitly include ret or reti in _naked function
17975 \begin_layout Standard
17976 The related directive #pragma exclude
17977 \begin_inset LatexCommand \index{\#pragma exclude}
17981 allows a more fine grained control over pushing & popping
17982 \begin_inset LatexCommand \index{push/pop}
17989 \begin_layout Standard
17990 While there is nothing preventing you from writing C code inside a
17994 function, there are many ways to shoot yourself in the foot doing this,
17995 and it is recommended that you stick to inline assembler.
17998 \begin_layout Subsection
17999 Use of Labels within Inline Assembler
18002 \begin_layout Standard
18003 SDCC allows the use of in-line assembler with a few restrictions regarding
18005 All labels defined within inline assembler code have to be of the form
18010 where nnnnn is a number less than 100 (which implies a limit of utmost
18011 100 inline assembler labels
18022 \begin_layout Standard
18023 This is a slightly more stringent rule than absolutely necessary, but stays
18024 always on the safe side.
18025 Labels in the form of nnnnn$ are local labels in the assembler, locality
18026 of which is confined within two labels of the standard form.
18027 The compiler uses the same form for labels within a function (but starting
18028 from nnnnn=00100); and places always a standard label at the beginning
18029 of a function, thus limiting the locality of labels within the scope of
18031 So, if the inline assembler part would be embedded into C-code, an improperly
18032 placed non-local label in the assembler would break up the reference space
18033 for labels created by the compiler for the C-code, leading to an assembling
18037 \begin_layout Standard
18038 The numeric part of local labels does not need to have 5 digits (although
18039 this is the form of labels output by the compiler), any valid integer will
18041 Please refer to the assemblers documentation for further details.
18049 \begin_layout Verse
18053 \begin_inset LatexCommand \index{\_asm}
18058 \begin_inset LatexCommand \index{\_\_asm}
18088 \begin_inset LatexCommand \index{\_endasm}
18093 \begin_inset LatexCommand \index{\_\_endasm}
18100 \begin_layout Standard
18101 Inline assembler code cannot reference any C-labels, however it can reference
18103 \begin_inset LatexCommand \index{Labels}
18107 defined by the inline assembler, e.g.:
18110 \begin_layout Verse
18133 ; some assembler code
18154 /* some more c code */
18156 clabel:\InsetSpace ~
18158 /* inline assembler cannot reference this
18163 \begin_layout Standard
18168 is translated by the compiler into a local label, so the locality of labels
18169 within the function is not broken.
18186 0003$: ;label (can be referenced by inline assembler only)
18193 \begin_inset LatexCommand \index{\_endasm}
18198 \begin_inset LatexCommand \index{\_\_endasm}
18208 /* some more c code */
18213 \begin_layout Standard
18214 In other words inline assembly code can access labels defined in inline
18215 assembly within the scope of the function.
18216 The same goes the other way, i.e.
18217 labels defines in inline assembly can not be accessed by C statements.
18220 \begin_layout Section
18221 Interfacing with Assembler Code
18222 \begin_inset LatexCommand \index{Assembler routines}
18229 \begin_layout Subsection
18230 Global Registers used for Parameter Passing
18231 \begin_inset LatexCommand \index{Parameter passing}
18238 \begin_layout Standard
18239 The compiler always uses the global registers
18242 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
18247 \begin_inset LatexCommand \index{DPTR}
18252 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
18261 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
18267 to pass the first (non-bit) parameter to a function, and also to pass the
18269 \begin_inset LatexCommand \index{return value}
18273 of function; according to the following scheme: one byte return value in
18278 , two byte value in
18287 three byte values (generic pointers) in
18299 , and four byte values in
18317 \begin_inset LatexCommand \index{generic pointer}
18321 contain type of accessed memory in
18342 \begin_inset Note Note
18345 \begin_layout Standard
18346 This might not be the case of certain memory models (medium???)
18354 \begin_layout Standard
18355 The second parameter onwards is either allocated on the stack (for reentrant
18360 \begin_layout Standard
18369 -stack-auto is used) or in data/xdata memory (depending on the memory model).
18372 \begin_layout Standard
18373 Bit parameters are passed in a virtual register called 'bits' in bit-addressable
18374 space for reentrant functions or allocated directly in bit memory otherwise.
18377 \begin_layout Standard
18378 Functions (with two or more parameters or bit parameters) that are called
18379 through function pointers
18380 \begin_inset LatexCommand \index{function pointers}
18384 must therefor be reentrant so the compiler knows how to pass the parameters.
18387 \begin_layout Subsection
18391 \begin_layout Standard
18392 Unless the called function is declared as
18397 \begin_inset LatexCommand \index{naked}
18405 \begin_layout Standard
18415 \begin_inset LatexCommand \index{-\/-callee-saves}
18423 \begin_layout Standard
18432 -all-callee-saves command line option or the corresponding callee_saves
18433 pragma are used, the caller will save the registers (
18437 ) around the call, so the called function can destroy they content freely.
18440 \begin_layout Standard
18441 If the called function is not declared as
18445 , the caller will swap register banks around the call, if caller and callee
18446 use different register banks (having them defined by the
18454 \begin_layout Standard
18455 The called function can also use
18471 observing that they are used for parameter/return value passing.
18474 \begin_layout Subsection
18475 Assembler Routine (non-reentrant)
18478 \begin_layout Standard
18479 In the following example
18480 \begin_inset LatexCommand \index{reentrant}
18485 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
18489 the function c_func calls an assembler routine asm_func, which takes two
18491 \begin_inset LatexCommand \index{function parameter}
18498 \begin_layout Verse
18501 extern int asm_func(unsigned char, unsigned char);
18505 int c_func (unsigned char
18506 i, unsigned char j)
18514 return asm_func(i,j);
18528 return c_func(10,9);
18533 \begin_layout Standard
18534 The corresponding assembler function is:
18537 \begin_layout Verse
18540 .globl _asm_func_PARM_2
18642 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
18659 \begin_layout Standard
18660 The parameter naming convention is _<function_name>_PARM_<n>, where n is
18661 the parameter number starting from 1, and counting from the left.
18662 The first parameter is passed in
18678 according to the description above.
18679 The variable name for the second parameter will be _<function_name>_PARM_2.
18684 ble the assembler routine with the following command:
18691 asx8051 -losg asmfunc.asm
18698 Then compile and link the assembler routine to the C source file with the
18706 sdcc cfunc.c asmfunc.rel
18709 \begin_layout Subsection
18710 Assembler Routine (reentrant)
18713 \begin_layout Standard
18715 \begin_inset LatexCommand \index{reentrant}
18720 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
18724 the second parameter
18725 \begin_inset LatexCommand \index{function parameter}
18729 onwards will be passed on the stack, the parameters are pushed from right
18731 before the call the second leftmost parameter will be on the top of the
18732 stack (the leftmost parameter is passed in registers).
18733 Here is an example:
18736 \begin_layout Verse
18739 extern int asm_func(unsigned char, unsigned char, unsigned char) reentrant;
18744 c_func (unsigned char i, unsigned char j, unsigned char k) reentrant
18753 return asm_func(i,j,k);
18767 return c_func(10,9,8);
18772 \begin_layout Standard
18773 The corresponding (unoptimized) assembler routine is:
18776 \begin_layout Verse
18796 _bp,sp\InsetSpace ~
18802 ;stack contains: _bp, return
18803 address, second parameter, third parameter
18827 a,#0xfd\InsetSpace ~
18833 pointer to the second parameter
18857 a,#0xfc\InsetSpace ~
18863 to the rightmost parameter
18904 result (= sum of all three parameters)
18919 ;return value goes into dptr
18953 \begin_layout Standard
18954 The compiling and linking procedure remains the same, however note the extra
18955 entry & exit linkage required for the assembler code, _bp is the stack
18956 frame pointer and is used to compute the offset into the stack for parameters
18957 and local variables.
18958 \begin_inset VSpace bigskip
18964 \begin_layout Section
18966 \begin_inset LatexCommand \index{int (16 bit)}
18971 \begin_inset LatexCommand \index{long (32 bit)}
18978 \begin_layout Standard
18979 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
18980 multiplication and modulus operations are implemented by support routines.
18981 These support routines are all developed in ANSI-C to facilitate porting
18982 to other MCUs, although some model specific assembler optimizations are
18984 The following files contain the described routines, all of them can be
18985 found in <installdir>/share/sdcc/lib.
18990 \begin_layout Standard
18992 \begin_inset Tabular
18993 <lyxtabular version="3" rows="11" columns="2">
18995 <column alignment="left" valignment="top" leftline="true" width="0">
18996 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
18997 <row topline="true" bottomline="true">
18998 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19001 \begin_layout Standard
19009 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19012 \begin_layout Standard
19021 <row topline="true">
19022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19025 \begin_layout Standard
19031 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19034 \begin_layout Standard
19035 16 bit multiplication
19041 <row topline="true">
19042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19045 \begin_layout Standard
19051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19054 \begin_layout Standard
19055 signed 16 bit division (calls _divuint)
19061 <row topline="true">
19062 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19065 \begin_layout Standard
19071 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19074 \begin_layout Standard
19075 unsigned 16 bit division
19081 <row topline="true">
19082 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19085 \begin_layout Standard
19091 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19094 \begin_layout Standard
19095 signed 16 bit modulus (calls _moduint)
19101 <row topline="true">
19102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19105 \begin_layout Standard
19111 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19114 \begin_layout Standard
19115 unsigned 16 bit modulus
19121 <row topline="true">
19122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19125 \begin_layout Standard
19131 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19134 \begin_layout Standard
19135 32 bit multiplication
19141 <row topline="true">
19142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19145 \begin_layout Standard
19151 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19154 \begin_layout Standard
19155 signed 32 division (calls _divulong)
19161 <row topline="true">
19162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19165 \begin_layout Standard
19171 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19174 \begin_layout Standard
19175 unsigned 32 division
19181 <row topline="true">
19182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19185 \begin_layout Standard
19191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19194 \begin_layout Standard
19195 signed 32 bit modulus (calls _modulong)
19201 <row topline="true" bottomline="true">
19202 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19205 \begin_layout Standard
19211 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19214 \begin_layout Standard
19215 unsigned 32 bit modulus
19230 \begin_layout Standard
19231 Since they are compiled as
19236 \begin_inset LatexCommand \index{reentrant}
19241 \begin_inset LatexCommand \index{interrupt}
19245 service routines should not do any of the above operations.
19246 If this is unavoidable then the above routines will need to be compiled
19253 \begin_layout Standard
19263 \begin_inset LatexCommand \index{-\/-stack-auto}
19269 option, after which the source program will have to be compiled with
19275 \begin_layout Standard
19285 \begin_inset LatexCommand \index{-\/-int-long-reent}
19292 Notice that you don't have to call these routines directly.
19293 The compiler will use them automatically every time an integer operation
19297 \begin_layout Section
19298 Floating Point Support
19299 \begin_inset LatexCommand \index{Floating point support}
19306 \begin_layout Standard
19307 SDCC supports IEEE (single precision 4 bytes) floating point numbers.
19308 The floating point support routines are derived from gcc's floatlib.c and
19309 consist of the following routines:
19314 \begin_layout Standard
19318 \begin_inset Tabular
19319 <lyxtabular version="3" rows="17" columns="2">
19321 <column alignment="left" valignment="top" leftline="true" width="0">
19322 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
19323 <row topline="true" bottomline="true">
19324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19327 \begin_layout Standard
19342 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19345 \begin_layout Standard
19352 <row topline="true">
19353 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19356 \begin_layout Standard
19371 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19374 \begin_layout Standard
19384 add floating point numbers
19390 <row topline="true">
19391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19394 \begin_layout Standard
19409 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19412 \begin_layout Standard
19422 subtract floating point numbers
19428 <row topline="true">
19429 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19432 \begin_layout Standard
19447 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19450 \begin_layout Standard
19460 divide floating point numbers
19466 <row topline="true">
19467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19470 \begin_layout Standard
19485 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19488 \begin_layout Standard
19498 multiply floating point numbers
19504 <row topline="true">
19505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19508 \begin_layout Standard
19523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19526 \begin_layout Standard
19536 convert floating point to unsigned char
19542 <row topline="true">
19543 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19546 \begin_layout Standard
19561 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19564 \begin_layout Standard
19574 convert floating point to signed char
19580 <row topline="true">
19581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19584 \begin_layout Standard
19599 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19602 \begin_layout Standard
19612 convert floating point to unsigned int
19618 <row topline="true">
19619 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19622 \begin_layout Standard
19637 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19640 \begin_layout Standard
19650 convert floating point to signed int
19656 <row topline="true">
19657 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19660 \begin_layout Standard
19683 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19686 \begin_layout Standard
19696 convert floating point to unsigned long
19702 <row topline="true">
19703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19706 \begin_layout Standard
19721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19724 \begin_layout Standard
19734 convert floating point to signed long
19740 <row topline="true">
19741 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19744 \begin_layout Standard
19759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19762 \begin_layout Standard
19772 convert unsigned char to floating point
19778 <row topline="true">
19779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19782 \begin_layout Standard
19797 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19800 \begin_layout Standard
19810 convert char to floating point number
19816 <row topline="true">
19817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19820 \begin_layout Standard
19835 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19838 \begin_layout Standard
19848 convert unsigned int to floating point
19854 <row topline="true">
19855 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19858 \begin_layout Standard
19873 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19876 \begin_layout Standard
19886 convert int to floating point numbers
19892 <row topline="true">
19893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19896 \begin_layout Standard
19911 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19914 \begin_layout Standard
19924 convert unsigned long to floating point number
19930 <row topline="true" bottomline="true">
19931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19934 \begin_layout Standard
19949 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19952 \begin_layout Standard
19962 convert long to floating point number
19977 \begin_layout Standard
19978 These support routines are developed in ANSI-C so there is room for space
19979 and speed improvement
19983 \begin_layout Standard
19984 These floating point routines (
19988 sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
19995 Note if all these routines are used simultaneously the data space might
19997 For serious floating point usage the large model might be needed.
19998 Also notice that you don't have to call this routines directly.
19999 The compiler will use them automatically every time a floating point operation
20001 \begin_inset VSpace bigskip
20007 \begin_layout Section
20009 \begin_inset LatexCommand \index{Libraries}
20016 \begin_layout Standard
20019 <pending: this is messy and incomplete - a little more information is in
20020 sdcc/doc/libdoc.txt
20025 \begin_layout Subsection
20026 Compiler support routines (_gptrget, _mulint etc.)
20029 \begin_layout Subsection
20030 Stdclib functions (puts, printf, strcat etc.)
20033 \begin_layout Subsubsection
20037 \begin_layout Paragraph
20038 getchar(), putchar()
20041 \begin_layout Standard
20042 \begin_inset LatexCommand \index{<stdio.h>}
20046 As usual on embedded systems you have to provide your own
20049 \begin_inset LatexCommand \index{getchar()}
20058 \begin_inset LatexCommand \index{putchar()}
20065 SDCC does not know whether the system connects to a serial line with or
20066 without handshake, LCD, keyboard or other device.
20080 You'll find examples for serial routines f.e.
20081 in sdcc/device/lib.
20082 For the mcs51 this minimalistic polling
20086 routine might be a start:
20089 \begin_layout Verse
20092 void putchar (char c) {
20098 while (!TI)\InsetSpace ~
20101 /* assumes UART is initialized */
20129 \begin_layout Paragraph
20133 \begin_layout Standard
20137 \begin_inset LatexCommand \index{printf()}
20147 does not support float (except on ds390).
20148 To enable this recompile it with the option
20154 \begin_layout Standard
20164 \begin_inset LatexCommand \index{USE\_FLOATS}
20170 on the command line.
20177 \begin_layout Standard
20187 \begin_inset LatexCommand \index{-\/-model-large}
20193 for the mcs51 port, since this uses a lot of memory.
20196 \begin_layout Standard
20197 If you're short on code memory you might want to use
20200 \begin_inset LatexCommand \index{printf\_small()}
20215 For the mcs51 there additionally are assembly versions
20218 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
20224 (subset of printf using less than 270 bytes) and
20227 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
20236 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
20242 (floating-point aware version of printf_fast) which should fit the requirements
20243 of many embedded systems (printf_fast() can be customized by unsetting
20248 support long variables and field widths).
20249 Be sure to use only one of these printf options within a project.
20254 \begin_layout Standard
20255 Feature matrix of different
20262 \begin_layout Standard
20263 \begin_inset Tabular
20264 <lyxtabular version="3" rows="14" columns="7">
20265 <features islongtable="true">
20266 <column alignment="left" valignment="middle" leftline="true" width="14col%">
20267 <column alignment="center" valignment="top" leftline="true" width="0">
20268 <column alignment="center" valignment="top" leftline="true" width="12col%">
20269 <column alignment="center" valignment="top" leftline="true" width="10col%">
20270 <column alignment="center" valignment="top" leftline="true" width="0">
20271 <column alignment="center" valignment="top" leftline="true" rightline="true" width="12col%">
20272 <column alignment="center" valignment="top" rightline="true" width="0">
20273 <row topline="true" bottomline="true" endhead="true">
20274 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20277 \begin_layout Standard
20286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20289 \begin_layout Standard
20291 \begin_inset LatexCommand \index{printf}
20300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20303 \begin_layout Standard
20311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20314 \begin_layout Standard
20320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20323 \begin_layout Standard
20329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20332 \begin_layout Standard
20338 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20341 \begin_layout Standard
20348 <row topline="true" endhead="true">
20349 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20352 \begin_layout Standard
20358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20361 \begin_layout Standard
20369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20372 \begin_layout Standard
20380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20383 \begin_layout Standard
20391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20394 \begin_layout Standard
20402 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20405 \begin_layout Standard
20413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20416 \begin_layout Standard
20425 <row topline="true" endhead="true">
20426 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20429 \begin_layout Standard
20430 \begin_inset Quotes sld
20434 \begin_inset Quotes srd
20440 \begin_layout Standard
20446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20449 \begin_layout Standard
20455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20458 \begin_layout Standard
20464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20467 \begin_layout Standard
20473 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20476 \begin_layout Standard
20482 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20485 \begin_layout Standard
20491 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20494 \begin_layout Standard
20501 <row topline="true" endhead="true">
20502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20505 \begin_layout Standard
20509 \begin_layout Standard
20515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20518 \begin_layout Standard
20524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20527 \begin_layout Standard
20533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20536 \begin_layout Standard
20537 0.45k / 0.47k (+ _ltoa)
20542 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20545 \begin_layout Standard
20551 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20554 \begin_layout Standard
20560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20563 \begin_layout Standard
20570 <row topline="true">
20571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20574 \begin_layout Standard
20580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20583 \begin_layout Standard
20593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20596 \begin_layout Standard
20643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20646 \begin_layout Standard
20685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20688 \begin_layout Standard
20694 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20697 \begin_layout Standard
20703 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20706 \begin_layout Standard
20713 <row topline="true">
20714 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20717 \begin_layout Standard
20718 long (32 bit) support
20723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20726 \begin_layout Standard
20732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20735 \begin_layout Standard
20741 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20744 \begin_layout Standard
20750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20753 \begin_layout Standard
20759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20762 \begin_layout Standard
20777 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20780 \begin_layout Standard
20787 <row topline="true">
20788 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20791 \begin_layout Standard
20792 byte arguments on stack
20797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20800 \begin_layout Standard
20806 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20809 \begin_layout Standard
20815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20818 \begin_layout Standard
20824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20827 \begin_layout Standard
20833 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20836 \begin_layout Standard
20842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20845 \begin_layout Standard
20852 <row topline="true">
20853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20856 \begin_layout Standard
20858 \begin_inset LatexCommand \index{Floating point support}
20867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20870 \begin_layout Standard
20876 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20879 \begin_layout Standard
20885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20888 \begin_layout Standard
20894 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20897 \begin_layout Standard
20903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20906 \begin_layout Standard
20911 \begin_layout Standard
20912 Range limited to +/- 4294967040, precision limited to 8 digits past decimal
20922 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20925 \begin_layout Standard
20932 <row topline="true">
20933 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20936 \begin_layout Standard
20937 float formats %e %g
20942 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20945 \begin_layout Standard
20951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20954 \begin_layout Standard
20960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20963 \begin_layout Standard
20969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20972 \begin_layout Standard
20978 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20981 \begin_layout Standard
20987 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20990 \begin_layout Standard
20997 <row topline="true" bottomline="true">
20998 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21001 \begin_layout Standard
21007 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21010 \begin_layout Standard
21016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21019 \begin_layout Standard
21025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21028 \begin_layout Standard
21034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21037 \begin_layout Standard
21043 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21046 \begin_layout Standard
21052 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21055 \begin_layout Standard
21062 <row bottomline="true">
21063 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21066 \begin_layout Standard
21071 \begin_layout Standard
21072 Execution time of printf("%s%c%s%c%c%c", "Hello", ' ', "World", '!', '
21076 n'); standard 8051 @ 22.1184 MHz, empty putchar()
21084 \begin_layout Standard
21090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21093 \begin_layout Standard
21099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21102 \begin_layout Standard
21108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21111 \begin_layout Standard
21117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21120 \begin_layout Standard
21126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21129 \begin_layout Standard
21135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21138 \begin_layout Standard
21145 <row bottomline="true">
21146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21149 \begin_layout Standard
21154 \begin_layout Standard
21155 Execution time of printf("%d", -12345); standard 8051 @ 22.1184 MHz, empty
21164 \begin_layout Standard
21170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21173 \begin_layout Standard
21179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21182 \begin_layout Standard
21188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21191 \begin_layout Standard
21197 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21200 \begin_layout Standard
21206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21209 \begin_layout Standard
21215 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21218 \begin_layout Standard
21223 \begin_layout Standard
21224 printf_tiny integer speed is data dependent, worst case is 0.33 ms
21235 <row bottomline="true">
21236 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21239 \begin_layout Standard
21244 \begin_layout Standard
21245 Execution time of printf("%ld", -123456789); standard 8051 @ 22.1184 MHz,
21254 \begin_layout Standard
21260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21263 \begin_layout Standard
21269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21272 \begin_layout Standard
21278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21281 \begin_layout Standard
21287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21290 \begin_layout Standard
21296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21299 \begin_layout Standard
21305 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21308 \begin_layout Standard
21315 <row bottomline="true">
21316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21319 \begin_layout Standard
21324 \begin_layout Standard
21325 Execution time of printf("%.3f", -12345.678); standard 8051 @ 22.1184 MHz,
21334 \begin_layout Standard
21340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21343 \begin_layout Standard
21349 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21352 \begin_layout Standard
21358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21361 \begin_layout Standard
21367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21370 \begin_layout Standard
21376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21379 \begin_layout Standard
21385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21388 \begin_layout Standard
21402 \begin_layout Subsubsection
21404 \begin_inset LatexCommand \index{malloc.h}
21411 \begin_layout Standard
21412 As of SDCC 2.6.2 you no longer need to call an initialization routine before
21413 using dynamic memory allocation
21414 \begin_inset LatexCommand \index{dynamic memory allocation (malloc)}
21419 \begin_inset LatexCommand \index{heap (malloc)}
21423 space of 1024 bytes is provided for malloc to allocate memory from.
21424 If you need a different heap size you need to recompile _heap.c with the
21425 required size defined in HEAP_SIZE.
21426 It is recommended to make a copy of this file into your project directory
21427 and compile it there with:
21430 \begin_layout Verse
21433 sdcc -c _heap.c -D HEAD_SIZE=2048
21436 \begin_layout Standard
21437 And then link it with:
21440 \begin_layout Verse
21443 sdcc main.rel _heap.rel
21446 \begin_layout Subsection
21447 Math functions (sinf, powf, sqrtf etc.)
21450 \begin_layout Subsubsection
21454 \begin_layout Standard
21455 See definitions in file <math.h>.
21458 \begin_layout Subsection
21462 \begin_layout Standard
21464 \begin_inset LatexCommand \index{Libraries}
21468 included in SDCC should have a license at least as liberal as the GNU Lesser
21469 General Public License
21470 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
21481 \begin_layout Standard
21482 \begin_inset Note Note
21485 \begin_layout Standard
21486 license statements for the libraries are missing.
21487 sdcc/device/lib/ser_ir.c
21490 \begin_layout Standard
21492 come with a GPL (as opposed to LGPL) License - this will not be liberal
21493 enough for many embedded programmers.
21501 \begin_layout Standard
21502 If you have ported some library or want to share experience about some code
21504 falls into any of these categories Busses (I
21505 \begin_inset Formula $^{\textrm{2}}$
21508 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
21509 cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
21510 Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
21511 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
21516 would certainly like to hear about it.
21519 \begin_layout Standard
21520 Programmers coding for embedded systems are not especially famous for being
21521 enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
21522 e these references are very valuable.
21523 Let's help to create a climate where information is shared.
21524 \begin_inset VSpace bigskip
21530 \begin_layout Section
21534 \begin_layout Subsection
21535 MCS51 Memory Models
21536 \begin_inset LatexCommand \index{Memory model}
21541 \begin_inset LatexCommand \index{MCS51 memory model}
21548 \begin_layout Subsubsection
21549 Small, Medium and Large
21552 \begin_layout Standard
21553 SDCC allows three memory models for MCS51 code,
21562 Modules compiled with different memory models should
21566 be combined together or the results would be unpredictable.
21567 The library routines supplied with the compiler are compiled as small,
21569 The compiled library modules are contained in separate directories as small,
21570 medium and large so that you can link to the appropriate set.
21573 \begin_layout Standard
21574 When the medium or large model is used all variables declared without a
21575 storage class will be allocated into the external ram, this includes all
21576 parameters and local variables (for non-reentrant
21577 \begin_inset LatexCommand \index{reentrant}
21582 When the small model is used variables without storage class are allocated
21583 in the internal ram.
21586 \begin_layout Standard
21587 Judicious usage of the processor specific storage classes
21588 \begin_inset LatexCommand \index{Storage class}
21592 and the 'reentrant' function type will yield much more efficient code,
21593 than using the large model.
21594 Several optimizations are disabled when the program is compiled using the
21595 large model, it is therefore recommended that the small model be used unless
21596 absolutely required.
21599 \begin_layout Subsubsection
21601 \begin_inset LatexCommand \label{sub:External-Stack}
21606 \begin_inset LatexCommand \index{stack}
21611 \begin_inset LatexCommand \index{External stack (mcs51)}
21618 \begin_layout Standard
21619 The external stack (-
21623 \begin_layout Standard
21633 \begin_inset LatexCommand \index{-\/-xstack}
21637 ) is located in pdata
21638 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
21642 memory (usually at the start of the external ram segment) and uses all
21643 unused space in pdata (max.
21649 \begin_layout Standard
21658 -xstack option is used to compile the program, the parameters and local
21660 \begin_inset LatexCommand \index{local variables}
21664 of all reentrant functions are allocated in this area.
21665 This option is provided for programs with large stack space requirements.
21666 When used with the -
21670 \begin_layout Standard
21680 \begin_inset LatexCommand \index{-\/-stack-auto}
21684 option, all parameters and local variables are allocated on the external
21685 stack (note: support libraries will need to be recompiled with the same
21687 There is a predefined target in the library makefile).
21690 \begin_layout Standard
21691 The compiler outputs the higher order address byte of the external ram segment
21693 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
21698 \begin_inset LatexCommand \ref{sub:MCS51-variants}
21702 ), therefore when using the External Stack option, this port
21706 be used by the application program.
21709 \begin_layout Subsection
21711 \begin_inset LatexCommand \index{Memory model}
21716 \begin_inset LatexCommand \index{DS390 memory model}
21723 \begin_layout Standard
21724 The only model supported is Flat 24
21725 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
21730 This generates code for the 24 bit contiguous addressing mode of the Dallas
21732 In this mode, up to four meg of external RAM or code space can be directly
21734 See the data sheets at www.dalsemi.com for further information on this part.
21739 that the compiler does not generate any code to place the processor into
21740 24 bitmode (although
21744 in the ds390 libraries will do that for you).
21750 \begin_inset LatexCommand \index{Tinibios (DS390)}
21754 , the boot loader or similar code must ensure that the processor is in 24
21755 bit contiguous addressing mode before calling the SDCC startup code.
21766 \begin_layout Standard
21777 option, variables will by default be placed into the XDATA segment.
21782 Segments may be placed anywhere in the 4 meg address space using the usual
21787 \begin_layout Standard
21797 Note that if any segments are located above 64K, the -r flag must be passed
21798 to the linker to generate the proper segment relocations, and the Intel
21799 HEX output format must be used.
21800 The -r flag can be passed to the linker by using the option
21804 on the SDCC command line.
21805 However, currently the linker can not handle code segments > 64k.
21808 \begin_layout Section
21810 \begin_inset LatexCommand \label{sec:Pragmas}
21815 \begin_inset LatexCommand \index{Pragmas}
21822 \begin_layout Standard
21823 Pragmas are used to turn on and/or off certain compiler options.
21824 Some of them are closely related to corresponding command-line options
21826 \begin_inset LatexCommand \vref{sec:Command-Line-Options}
21832 Pragmas should be placed before and/or after a function, placing pragmas
21833 inside a function body could have unpredictable results.
21838 following #pragma directives:
21841 \begin_layout Itemize
21847 \begin_inset LatexCommand \index{\#pragma save}
21851 - this will save most current options to the save/restore stack.
21852 See #pragma\InsetSpace ~
21856 \begin_layout Itemize
21862 \begin_inset LatexCommand \index{\#pragma restore}
21866 - will restore saved options from the last save.
21867 saves & restores can be nested.
21868 SDCC uses a save/restore stack: save pushes current options to the stack,
21869 restore pulls current options from the stack.
21870 See #pragma\InsetSpace ~
21876 \begin_layout Itemize
21882 \begin_inset LatexCommand \index{\#pragma callee\_saves}
21887 \begin_inset LatexCommand \index{function prologue}
21891 function1[,function2[,function3...]]
21892 \begin_inset LatexCommand \label{ite:callee_saves-function1[,function2[,function3...]]--}
21896 - The compiler by default uses a caller saves convention for register saving
21897 across function calls, however this can cause unnecessary register pushing
21899 \begin_inset LatexCommand \index{push/pop}
21903 when calling small functions from larger functions.
21904 This option can be used to switch off the register saving convention for
21905 the function names specified.
21906 The compiler will not save registers when calling these functions, extra
21907 code need to be manually inserted at the entry and exit for these functions
21908 to save and restore the registers used by these functions, this can SUBSTANTIAL
21909 LY reduce code and improve run time performance of the generated code.
21910 In the future the compiler (with inter procedural analysis) may be able
21911 to determine the appropriate scheme to use for each function call.
21916 \begin_layout Standard
21925 -callee-saves command line option is used (see page
21926 \begin_inset LatexCommand \vpageref{lyx:--callee-saves-function1[,function2][,function3]...}
21930 ), the function names specified in #pragma\InsetSpace ~
21932 \begin_inset LatexCommand \index{\#pragma callee\_saves}
21936 is appended to the list of functions specified in the command line.
21939 \begin_layout Itemize
21945 \begin_inset LatexCommand \index{\#pragma exclude}
21949 none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
21950 of pairs of push/pop
21951 \begin_inset LatexCommand \index{push/pop}
21960 \begin_inset LatexCommand \index{interrupt}
21973 The directive should be placed immediately before the ISR function definition
21974 and it affects ALL ISR functions following it.
21975 To enable the normal register saving for ISR functions use #pragma\InsetSpace ~
21976 exclude\InsetSpace ~
21978 \begin_inset LatexCommand \index{\#pragma exclude}
21983 See also the related keyword _naked
21984 \begin_inset LatexCommand \index{\_naked}
21989 \begin_inset LatexCommand \index{\_\_naked}
21996 \begin_layout Itemize
22002 \begin_inset LatexCommand \index{pedantic}
22007 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
22012 \begin_inset LatexCommand \label{ite:less_pedantic}
22016 - the compiler will not warn you anymore for obvious mistakes, you're on
22018 See also the command line option -
22022 \begin_layout Standard
22032 \begin_inset LatexCommand \vpageref{lyx:--less-pedantic}
22039 More specifically, the following warnings will be disabled:
22041 comparison is always [true/false] due to limited range of data type
22045 overflow in implicit constant conversion
22047 (158); [the (in)famous]
22049 conditional flow changed by optimizer: so said EVELYN the modified DOG
22053 function '[function name]' must return value
22058 Furthermore, warnings of less importance (of PEDANTIC and INFO warning
22059 level) are disabled, too, namely:
22062 \begin_inset Note Note
22065 \begin_layout Standard
22066 dunno what comes here - this warning appears to be unused altogether
22075 [left/right] shifting more than size of object changed to zero
22083 integer overflow in expression
22087 unmatched #pragma save and #pragma restore
22091 comparison of 'signed char' with 'unsigned char' requires promotion to int
22095 ISO C90 does not support flexible array members
22099 extended stack by [number] bytes for compiler temp(s) :in function '[function\InsetSpace ~
22103 \begin_inset Note Note
22106 \begin_layout Standard
22107 appears to be always blank - what was supposed to be here?
22116 function '[function name]', # edges [number] , # nodes [number] , cyclomatic
22117 complexity [number]
22122 \begin_layout Itemize
22128 \begin_inset LatexCommand \index{\#pragma disable\_warning}
22132 - the compiler will not warn you anymore about warning number <nnnn>.
22135 \begin_layout Itemize
22141 \begin_inset LatexCommand \index{\#pragma nogcse}
22145 - will stop global common subexpression elimination.
22148 \begin_layout Itemize
22154 \begin_inset LatexCommand \index{\#pragma noinduction}
22158 - will stop loop induction optimizations.
22161 \begin_layout Itemize
22167 \begin_inset LatexCommand \index{\#pragma noinvariant}
22171 - will not do loop invariant optimizations.
22172 For more details see Loop Invariants in section
22173 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
22180 \begin_layout Itemize
22186 \begin_inset LatexCommand \index{\#pragma noiv}
22190 - Do not generate interrupt
22191 \begin_inset LatexCommand \index{interrupt}
22196 \begin_inset LatexCommand \index{interrupt vector table}
22200 entries for all ISR functions defined after the pragma.
22201 This is useful in cases where the interrupt vector table must be defined
22202 manually, or when there is a secondary, manually defined interrupt vector
22204 for the autovector feature of the Cypress EZ-USB FX2).
22205 More elegantly this can be achieved by obmitting the optional interrupt
22206 number after the interrupt keyword, see section
22207 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
22215 \begin_layout Itemize
22221 \begin_inset LatexCommand \index{\#pragma nojtbound}
22225 - will not generate code for boundary value checking, when switch statements
22226 are turned into jump-tables (dangerous).
22227 For more details see section
22228 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
22235 \begin_layout Itemize
22241 \begin_inset LatexCommand \index{\#pragma noloopreverse}
22245 - Will not do loop reversal optimization
22248 \begin_layout Itemize
22254 \begin_inset LatexCommand \index{\#pragma nooverlay}
22258 - the compiler will not overlay the parameters and local variables of a
22262 \begin_layout Itemize
22268 \begin_inset LatexCommand \index{\#pragma stackauto}
22276 \begin_layout Standard
22286 \begin_inset LatexCommand \index{-\/-stack-auto}
22291 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
22295 Parameters and Local Variables.
22298 \begin_layout Itemize
22304 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
22308 - The compiler will optimize code generation towards fast code, possibly
22309 at the expense of code size.
22310 Currently this has little effect.
22313 \begin_layout Itemize
22319 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
22323 - The compiler will optimize code generation towards compact code, possibly
22324 at the expense of code speed.
22325 Currently this has little effect.
22328 \begin_layout Itemize
22334 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
22338 - The compiler will attempt to generate code that is both compact and fast,
22339 as long as meeting one goal is not a detriment to the other (this is the
22344 \begin_layout Itemize
22350 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
22354 - Generally follow the C89 standard, but allow SDCC features that conflict
22355 with the standard (default).
22358 \begin_layout Itemize
22364 \begin_inset LatexCommand \index{\#pragma std\_c89}
22368 - Follow the C89 standard and disable SDCC features that conflict with the
22372 \begin_layout Itemize
22378 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
22382 - Generally follow the C99 standard, but allow SDCC features that conflict
22383 with the standard (incomplete support).
22386 \begin_layout Itemize
22392 \begin_inset LatexCommand \index{\#pragma std\_c99}
22396 - Follow the C99 standard and disable SDCC features that conflict with the
22397 standard (incomplete support).
22400 \begin_layout Itemize
22406 \begin_inset LatexCommand \index{\#pragma codeseg}
22410 - Use this name (max.
22411 8 characters) for the code segment.
22416 \begin_layout Standard
22428 \begin_layout Itemize
22434 \begin_inset LatexCommand \index{\#pragma constseg}
22438 - Use this name (max.
22439 8 characters) for the const segment.
22444 \begin_layout Standard
22456 \begin_layout Standard
22457 The preprocessor SDCPP
22458 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
22462 supports the following #pragma directives:
22465 \begin_layout Itemize
22468 pedantic_parse_number
22471 \begin_inset LatexCommand \index{pedantic}
22476 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
22481 \begin_inset LatexCommand \label{ite:pedantic_parse_number}
22485 - Pedantic parse numbers so that situations like 0xfe-LO_B(3) are parsed
22486 properly and the macro LO_B(3) gets expanded.
22492 \begin_layout Standard
22501 -pedantic-parse-number command line option
22502 \begin_inset LatexCommand \vpageref{lyx:-pedantic-parse-number}
22509 Below is an example on how to use this pragma.
22512 Note: this functionality is not in conformance with standard!
22515 \begin_layout Verse
22518 #pragma pedantic_parse_number +
22519 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
22527 #define LO_B(x) ((x) & 0xff)
22531 unsigned char foo(void)
22538 unsigned char c=0xfe-LO_B(3)
22553 \begin_layout Itemize
22559 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
22563 (+ | -) - switch _asm _endasm block preprocessing on / off.
22565 You use this prama to define multilines of assembly code.
22566 This will prevent the preprocessor from changing the formating required
22568 Below is an example on how to use this pragma.
22571 \begin_layout Verse
22574 #pragma preproc_asm -
22575 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
22581 #define MYDELAY _asm
22586 nop ;my assembly comment...
22600 #pragma preproc_asm
22631 \begin_layout Itemize
22637 \begin_inset LatexCommand \index{\#pragma sdcc\_hash}
22641 (+ | -) - Allow "naked" hash in macro definition, for example:
22645 #define DIR_LO(x) #(x & 0xff)
22650 Below is an example on how to use this pragma.
22653 \begin_layout Verse
22656 #pragma preproc_asm +
22658 #pragma sdcc_hash +
22659 \begin_inset LatexCommand \index{\#pragma sdcc\_hash}
22674 mov R6_B3, #(x & 0xff)
22681 mov R7_B3, #((x >> 8) & 0xff)
22705 \begin_layout Standard
22706 Some of the pragmas are intended to be used to turn-on or off certain optimizati
22707 ons which might cause the compiler to generate extra stack and/or data space
22708 to store compiler generated temporary variables.
22709 This usually happens in large functions.
22710 Pragma directives should be used as shown in the following example, they
22711 are used to control options and optimizations for a given function.
22715 \begin_layout Verse
22719 \begin_inset LatexCommand \index{\#pragma save}
22730 /* save the current settings */
22733 \begin_inset LatexCommand \index{\#pragma nogcse}
22742 /* turnoff global subexpression elimination */
22744 #pragma noinduction
22745 \begin_inset LatexCommand \index{\#pragma noinduction}
22749 /* turn off induction optimizations */
22772 \begin_inset LatexCommand \index{\#pragma restore}
22776 /* turn the optimizations back on */
22779 \begin_layout Standard
22780 The compiler will generate a warning message when extra space is allocated.
22781 It is strongly recommended that the save and restore pragmas be used when
22782 changing options for a function.
22791 \begin_layout Section
22792 Defines Created by the Compiler
22795 \begin_layout Standard
22796 The compiler creates the following #defines
22797 \begin_inset LatexCommand \index{\#defines}
22802 \begin_inset LatexCommand \index{Defines created by the compiler}
22811 \begin_layout Standard
22812 \begin_inset Tabular
22813 <lyxtabular version="3" rows="15" columns="2">
22815 <column alignment="left" valignment="top" leftline="true" width="3in">
22816 <column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
22817 <row topline="true" bottomline="true">
22818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22821 \begin_layout Standard
22829 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22832 \begin_layout Standard
22841 <row topline="true">
22842 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22845 \begin_layout Standard
22847 \begin_inset LatexCommand \index{SDCC}
22856 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22859 \begin_layout Standard
22861 Since version 2.5.6 the version number as an int (ex.
22868 <row topline="true">
22869 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22872 \begin_layout Standard
22874 \begin_inset LatexCommand \index{SDCC\_mcs51}
22879 \begin_inset LatexCommand \index{SDCC\_ds390}
22884 \begin_inset LatexCommand \index{SDCC\_z80}
22893 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22896 \begin_layout Standard
22897 depending on the model used (e.g.: -mds390)
22903 <row topline="true">
22904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22907 \begin_layout Standard
22909 \begin_inset LatexCommand \index{\_\_mcs51}
22914 \begin_inset LatexCommand \index{\_\_ds390}
22919 \begin_inset LatexCommand \index{\_\_hc08}
22924 \begin_inset LatexCommand \index{\_\_z80}
22933 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22936 \begin_layout Standard
22937 depending on the model used (e.g.
22944 <row topline="true">
22945 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22948 \begin_layout Standard
22950 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
22959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22962 \begin_layout Standard
22969 \begin_layout Standard
22986 <row topline="true">
22987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22990 \begin_layout Standard
22992 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
23001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23004 \begin_layout Standard
23011 \begin_layout Standard
23028 <row topline="true">
23029 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23032 \begin_layout Standard
23034 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
23043 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23046 \begin_layout Standard
23053 \begin_layout Standard
23070 <row topline="true">
23071 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23074 \begin_layout Standard
23076 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
23085 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23088 \begin_layout Standard
23095 \begin_layout Standard
23112 <row topline="true">
23113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23116 \begin_layout Standard
23118 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
23127 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23130 \begin_layout Standard
23137 \begin_layout Standard
23154 <row topline="true">
23155 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23158 \begin_layout Standard
23160 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
23169 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23172 \begin_layout Standard
23183 <row topline="true">
23184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23187 \begin_layout Standard
23189 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
23198 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23201 \begin_layout Standard
23212 <row topline="true">
23213 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23216 \begin_layout Standard
23218 \begin_inset LatexCommand \index{SDCC\_REVISION}
23227 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23230 \begin_layout Standard
23232 SDCC svn revision number
23238 <row topline="true">
23239 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23242 \begin_layout Standard
23243 SDCC_PARMS_IN_BANK1
23244 \begin_inset LatexCommand \index{SDCC\_PARMS\_IN\_BANK1}
23253 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23256 \begin_layout Standard
23263 \begin_layout Standard
23280 <row topline="true">
23281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23284 \begin_layout Standard
23286 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
23295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23298 \begin_layout Standard
23305 \begin_layout Standard
23322 <row topline="true" bottomline="true">
23323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23326 \begin_layout Standard
23327 SDCC_INT_LONG_REENT
23328 \begin_inset LatexCommand \index{SDCC\_INT\_LONG\_REENT}
23337 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23340 \begin_layout Standard
23347 \begin_layout Standard
23371 \begin_layout Chapter
23372 Notes on supported Processors
23375 \begin_layout Section
23377 \begin_inset LatexCommand \label{sub:MCS51-variants}
23382 \begin_inset LatexCommand \index{MCS51 variants}
23389 \begin_layout Standard
23390 MCS51 processors are available from many vendors and come in many different
23392 While they might differ considerably in respect to Special Function Registers
23393 the core MCS51 is usually not modified or is kept compatible.
23397 \begin_layout Subsection
23398 pdata access by SFR
23401 \begin_layout Standard
23402 With the upcome of devices with internal xdata and flash memory devices
23404 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
23408 as dedicated I/O port is becoming more popular.
23409 Switching the high byte for pdata
23410 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
23414 access which was formerly done by port P2 is then achieved by a Special
23416 \begin_inset LatexCommand \index{sfr}
23421 In well-established MCS51 tradition the address of this
23425 is where the chip designers decided to put it.
23426 Needless to say that they didn't agree on a common name either.
23427 So that the startup code can correctly initialize xdata variables, you
23428 should define an sfr with the name _XPAGE
23431 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
23437 at the appropriate location if the default, port P2, is not used for this.
23441 \begin_layout Verse
23444 __sfr __at (0x85) _XPAGE; /* Ramtron VRS51 family a.k.a.
23448 \begin_layout Verse
23451 __sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family, Texas Instruments (Chipcon)
23456 \begin_layout Verse
23459 __sfr __at (0x91) _XPAGE; /* Infineon (Siemens) C500 family a.k.a.
23463 \begin_layout Verse
23466 __sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
23470 \begin_layout Verse
23473 __sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
23477 \begin_layout Standard
23478 For more exotic implementations further customizations may be needed.
23480 \begin_inset LatexCommand \ref{sub:Startup-Code}
23484 for other possibilities.
23487 \begin_layout Subsection
23488 Other Features available by SFR
23491 \begin_layout Standard
23492 Some MCS51 variants offer features like Double DPTR
23493 \begin_inset LatexCommand \index{DPTR}
23497 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
23498 These are currently not used for the MCS51 port.
23499 If you absolutely need them you can fall back to inline assembly or submit
23503 \begin_layout Subsection
23507 \begin_layout Standard
23509 \begin_inset LatexCommand \index{Bankswitching}
23515 \begin_inset LatexCommand \index{code banking}
23519 ) is a technique to increase the code space above the 64k limit of the 8051.
23522 \begin_layout Subsubsection
23526 \begin_layout Standard
23527 \begin_inset Tabular
23528 <lyxtabular version="3" rows="3" columns="4">
23530 <column alignment="center" valignment="top" width="0">
23531 <column alignment="center" valignment="top" leftline="true" width="0">
23532 <column alignment="center" valignment="top" leftline="true" width="0">
23533 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
23534 <row topline="true" bottomline="true">
23535 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
23538 \begin_layout Standard
23544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23547 \begin_layout Standard
23553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23556 \begin_layout Standard
23562 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23565 \begin_layout Standard
23572 <row topline="true" bottomline="true">
23573 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
23576 \begin_layout Standard
23582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23585 \begin_layout Standard
23591 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
23594 \begin_layout Standard
23600 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23603 \begin_layout Standard
23611 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
23614 \begin_layout Standard
23615 SiLabs C8051F120 example
23620 <cell multicolumn="2" alignment="center" valignment="top" usebox="none">
23623 \begin_layout Standard
23629 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23632 \begin_layout Standard
23638 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23641 \begin_layout Standard
23656 Usually the hardware uses some sfr (an output port or an internal sfr) to
23657 select a bank and put it in the banked area of the memory map.
23658 The selected bank usually becomes active immediately upon assignment to
23659 this sfr and when running inside a bank it will switch out this code it
23660 is currently running.
23661 Therefor you cannot jump or call directly from one bank to another and
23662 need to use a so-called trampoline in the common area.
23663 For SDCC an example trampoline is in crtbank.asm and you may need to change
23664 it to your 8051 derivative or schematic.
23665 The presented code is written for the C8051F120.
23669 When calling a banked function
23670 SDCC will put the LSB of the functions address in register R0, the MSB
23671 in R1 and the bank in R2 and then call this trampoline
23676 The current selected bank is saved on the stack, the new bank is selected
23677 and an indirect jump is made.
23678 When the banked function returns it jumps to
23682 which restores the previous bank and returns to the caller.
23685 \begin_layout Subsubsection
23689 \begin_layout Standard
23690 When writing banked software using SDCC you need to use some special keywords
23692 You also need to take over a bit of work from the linker.
23696 To create a function
23697 that can be called from another bank it requires the keyword
23702 \begin_inset LatexCommand \index{banked}
23707 The caller must see this in the prototype of the callee and the callee
23708 needs it for a proper return.
23709 Called functions within the same bank as the caller do not need the
23713 keyword nor do functions in the common area.
23714 Beware: SDCC does not know or check if functions are in the same bank.
23715 This is your responsibility!
23719 Normally all functions you write end up in
23721 If you want a function explicitly to reside in the common area put it in
23723 This applies for instance to interrupt service routines as they should
23727 \begin_layout Standard
23728 Functions that need to be in a switched bank must be put in a named segment.
23729 The name can be mostly anything upto eight characters (e.g.
23731 To do this you either use -
23735 \begin_layout Standard
23744 -codeseg BANK1 (See
23745 \begin_inset LatexCommand \ref{lyx:-codeseg}
23749 ) on the command line when compiling or #pragma codeseg BANK1 (See
23750 \begin_inset LatexCommand \ref{sec:Pragmas}
23754 ) at the top of the C source file.
23755 The segment name always applies to the whole source file and generated
23756 object so functions for different banks need to be defined in different
23761 When linking your objects you need to tell the linker where
23762 to put your segments.
23763 To do this you use the following command line option to SDCC: -Wl-b BANK1=0x180
23765 \begin_inset LatexCommand \ref{lyx:-Wl option}
23770 This sets the virtual start address of this segment.
23771 It sets the banknumber to 0x01 and maps the bank to 0x8000 and up.
23772 The linker will not check for overflows, again this is your responsibility.
23775 \begin_layout Standard
23776 \begin_inset VSpace bigskip
23782 \begin_layout Section
23786 \begin_layout Standard
23788 \begin_inset LatexCommand \index{DS80C400}
23793 \begin_inset LatexCommand \index{DS400}
23797 microcontroller has a rich set of peripherals.
23798 In its built-in ROM library it includes functions to access some of the
23799 features, among them is a TCP stack with IP4 and IP6 support.
23800 Library headers (currently in beta status) and other files are provided
23804 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
23810 \begin_inset VSpace bigskip
23816 \begin_layout Section
23817 The Z80 and gbz80 port
23820 \begin_layout Standard
23821 SDCC can target both the Zilog Z80
23822 \begin_inset LatexCommand \index{Z80}
23826 and the Nintendo Gameboy's Z80-like gbz80
23827 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
23832 The Z80 port is passed through the same
23835 \begin_inset LatexCommand \index{Regression test}
23842 \begin_inset LatexCommand \ref{sec:Quality-control}
23846 ) as the MCS51 and DS390 ports, so floating point support, support for long
23847 variables and bitfield support is fine.
23848 See mailing lists and forums about interrupt routines.
23851 \begin_layout Standard
23852 As always, the code is the authoritative reference - see z80/ralloc.c and
23855 \begin_inset LatexCommand \index{Z80!stack}
23859 frame is similar to that generated by the IAR Z80 compiler.
23860 IX is used as the base pointer, HL and IY are used as a temporary registers,
23861 and BC and DE are available for holding variables.
23863 \begin_inset LatexCommand \index{Z80!return value}
23867 for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
23869 The gbz80 port use the same set of registers for the return values, but
23870 in a different order of significance: E (one byte), DE (two bytes), or
23872 \begin_inset VSpace bigskip
23878 \begin_layout Section
23882 \begin_layout Standard
23883 The port to the Freescale/Motorola HC08
23884 \begin_inset LatexCommand \index{HC08}
23888 family has been added in October 2003, and is still undergoing some basic
23890 The code generator is complete, but the register allocation is still quite
23892 Some of the SDCC's standard C library functions have embedded non-HC08
23893 inline assembly and so are not yet usable.
23896 \begin_layout Standard
23897 The HC08 port passes the regression test suite (see section
23898 \begin_inset LatexCommand \ref{sec:Quality-control}
23903 \begin_inset VSpace bigskip
23909 \begin_layout Section
23911 \begin_inset LatexCommand \index{PIC14}
23918 \begin_layout Standard
23919 The PIC14 port adds support for Microchip
23920 \begin_inset LatexCommand \index{Microchip}
23925 \begin_inset Formula $^{\text{TM}}$
23929 \begin_inset LatexCommand \index{PIC14}
23934 \begin_inset Formula $^{\text{TM}}$
23937 MCUs with 14 bit wide instructions.
23938 This port is not yet mature and still lacks many features.
23939 However, it can work for simple code.
23942 \begin_layout Standard
23943 Currently supported devices include:
23946 \begin_layout Standard
23947 12F: 629, 635, 675, 683
23950 \begin_layout Standard
23954 \begin_layout Standard
23958 \begin_layout Standard
23959 16C: 62, 620, 620a, 621, 621a, 622, 622a, 63a, 65b
23962 \begin_layout Standard
23963 16C: 71, 710, 711, 715, 717, 72, 73b, 745, 74b, 765, 770, 771, 773, 774,
23967 \begin_layout Standard
23971 \begin_layout Standard
23972 16CR: 620a, 73, 74, 76, 77
23975 \begin_layout Standard
23976 16F: 616, 627, 627a, 628, 628a, 630, 636, 639, 648, 648a, 676, 684, 685,
23980 \begin_layout Standard
23981 16F: 716, 72, 73, 737, 74, 747, 76, 767, 77, 777, 785
23984 \begin_layout Standard
23985 16F: 818, 819, 84, 84a, 87, 870, 871, 872, 873, 873a, 874, 874a, 876, 876a,
23986 877, 877a, 88, 886, 887
23989 \begin_layout Standard
23990 16F: 913, 914, 916, 917, 946
23993 \begin_layout Standard
23997 \begin_layout Standard
23998 An up-to-date list of currently supported devices can be obtained via
24000 sdcc -mpic14 -phelp foo.c
24002 (foo.c must exist...).
24005 \begin_layout Subsection
24007 \begin_inset LatexCommand \index{code page (pic14)}
24012 \begin_inset LatexCommand \index{Memory bank (pic14)}
24019 \begin_layout Standard
24020 The linker organizes allocation for the code page and RAM banks.
24021 It does not have intimate knowledge of the code flow.
24022 It will put all the code section of a single .asm file into a single code
24024 In order to make use of multiple code pages, separate asm files must be
24026 The compiler assigns all
24030 functions of a single .c file into the same code page.
24034 To get the best results,
24035 follow these guidelines:
24038 \begin_layout Enumerate
24039 Make local functions static, as non static functions require code page selection
24042 Due to the way sdcc handles functions, place called functions prior
24043 to calling functions in the file wherever possible: Otherwise sdcc will
24044 insert unneccessary pagesel directives around the call, believing that
24045 the called function is externally defined.
24048 \begin_layout Enumerate
24049 For devices that have multiple code pages it is more efficient to use the
24050 same number of files as pages: Use up to 4 separate .c files for the 16F877,
24051 but only 2 files for the 16F874.
24052 This way the linker can put the code for each file into different code
24053 pages and there will be less page selection overhead.
24056 \begin_layout Enumerate
24057 And as for any 8 bit micro (especially for PIC14 as they have a very simple
24058 instruction set), use `unsigned char' wherever possible instead of `int'.
24061 \begin_layout Subsection
24062 Adding New Devices to the Port
24065 \begin_layout Standard
24066 Adding support for a new 14
24070 \begin_layout Standard
24079 bit PIC MCU requires the following steps:
24082 \begin_layout Enumerate
24083 Create a new device description.
24085 Each device is described in two files: pic16f*.h
24087 These files primarily define SFRs, structs to access their bits, and symbolic
24088 configuration options.
24089 Both files can be generated from gputils' .inc files using the perl script
24092 support/scripts/inc2h.pl
24095 This file also contains further instructions on how to proceed.
24098 \begin_layout Enumerate
24099 Copy the .h file into SDCC's include path and either add the .c file to your
24100 project or copy it to
24102 device/lib/pic/libdev
24105 Afterwards, rebuild and install the libraries.
24108 \begin_layout Enumerate
24109 Edit pic14devices.txt in SDCC's include path (
24111 device/include/pic/
24113 in the source tree or
24115 /usr/local/share/sdcc/include/pic
24117 after installation).
24119 You need to add a device specification here to make
24120 the memory layout (code banks, RAM, aliased memory regions, ...) known to
24122 Probably you can copy and modify an existing entry.
24123 The file format is documented at the top of the file.
24126 \begin_layout Subsection
24130 \begin_layout Standard
24131 For the interrupt function, use the keyword `__interrupt'
24132 \begin_inset LatexCommand \index{PIC14!interrupt}
24136 with level number of 0 (PIC14 only has 1 interrupt so this number is only
24137 there to avoid a syntax error - it ought to be fixed).
24141 \begin_layout Verse
24144 void Intr(void) __interrupt 0
24150 T0IF = 0; /* Clear timer interrupt */
24155 \begin_layout Subsection
24156 Linking and Assembling
24159 \begin_layout Standard
24160 For assembling you can use either GPUTILS'
24161 \begin_inset LatexCommand \index{gputils (pic tools)}
24165 gpasm.exe or MPLAB's mpasmwin.exe.
24166 GPUTILS are available from
24167 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
24172 For linking you can use either GPUTILS' gplink or MPLAB's mplink.exe.
24173 If you use MPLAB and an interrupt function then the linker script file
24174 vectors section will need to be enlarged to link with mplink.
24185 \begin_layout Verse
24198 sdcc -V -mpic14 -p16f877 -c $<
24202 $(PRJ).hex: $(OBJS)
24212 gplink -m -s $(PRJ).lkr
24213 -o $(PRJ).hex $(OBJS) libsdcc.lib
24216 \begin_layout Standard
24224 \begin_layout Verse
24237 sdcc -S -V -mpic14 -p16f877 $<
24247 mpasmwin /q /o $*.asm
24251 $(PRJ).hex: $(OBJS)
24262 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
24265 \begin_layout Standard
24266 Please note that indentations within a
24270 have to be done with a tabulator character.
24273 \begin_layout Subsection
24274 Command-Line Options
24277 \begin_layout Standard
24278 Besides the switches common to all SDCC backends, the PIC14 port accepts
24279 the following options (for an updated list see sdcc -
24283 \begin_layout Standard
24295 \begin_layout Description
24300 \begin_layout Standard
24310 \begin_inset LatexCommand \index{PIC14!Options!-\/-debug-extra}
24314 emit debug info in assembly output
24317 \begin_layout Description
24322 \begin_layout Standard
24332 \begin_inset LatexCommand \index{PIC14!Options!-\/-no-pcode-opt}
24336 disable (slightly faulty) optimization on pCode
24339 \begin_layout Description
24344 \begin_layout Standard
24354 \begin_inset LatexCommand \index{PIC14!Options!-\/-stack-loc}
24358 sets the lowest address of the argument passing stack (defaults to a suitably
24359 large shared databank to reduce BANKSEL overhead)
24362 \begin_layout Description
24367 \begin_layout Standard
24377 \begin_inset LatexCommand \index{PIC14!Options!-\/-stack-size}
24381 sets the size if the argument passing stack (default: 16, minimum: 4)
24384 \begin_layout Subsection
24385 Environment Variables
24388 \begin_layout Standard
24389 The PIC14 port recognizes the following environment variables:
24392 \begin_layout Description
24393 SDCC_PIC14_SPLIT_LOCALS If set and not empty, sdcc will allocate each temporary
24394 register (the ones called r0xNNNN) in a section of its own.
24395 By default (if this variable is unset), sdcc tries to cluster registers
24396 in sections in order to reduce the BANKSEL overhead when accessing them.
24399 \begin_layout Subsection
24403 \begin_layout Standard
24404 The PIC14 library currently only contains support routines required by the
24405 compiler to implement multiplication, division, and floating point support.
24406 No libc-like replacement is available at the moment, though many of the
24407 common sdcc library sources (in
24411 ) should also compile with the PIC14 port.
24414 \begin_layout Subsubsection
24415 error: missing definition for symbol ``__gptrget1''
24418 \begin_layout Standard
24419 The PIC14 port uses library routines to provide more complex operations
24420 like multiplication, division/modulus and (generic) pointer dereferencing.
24421 In order to add these routines to your project, you must link with PIC14's
24427 For single source file projects this is done automatically, more complex
24432 to the linker's arguments.
24433 Make sure you also add an include path for the library (using the -I switch
24437 \begin_layout Subsubsection
24438 Processor mismatch in file ``XXX''.
24441 \begin_layout Standard
24442 This warning can usually be ignored due to the very good compatibility amongst
24447 \begin_layout Standard
24457 \begin_inset LatexCommand \index{PIC14}
24464 \begin_layout Standard
24465 You might also consider recompiling the library for your specific device
24466 by changing the ARCH=p16f877 (default target) entry in
24468 device/lib/pic/Makefile.in
24472 device/lib/pic/Makefile
24474 to reflect your device.
24475 This might even improve performance for smaller devices as unneccesary
24476 BANKSELs might be removed.
24479 \begin_layout Subsection
24483 \begin_layout Subsubsection
24487 \begin_layout Standard
24488 Functions with variable argument lists (like printf) are not yet supported.
24489 Similarly, taking the address of the first argument passed into a function
24490 does not work: It is currently passed in WREG and has no address...
24493 \begin_layout Subsubsection
24494 Regression tests fail
24497 \begin_layout Standard
24498 Though the small subset of regression tests in src/regression passes, SDCC
24499 regression test suite does not, indicating that there are still major bugs
24501 However, many smaller projects have successfully used SDCC in the past...
24504 \begin_layout Standard
24512 \begin_layout Section
24514 \begin_inset LatexCommand \index{PIC16}
24521 \begin_layout Standard
24522 The PIC16 port adds support for Microchip
24523 \begin_inset LatexCommand \index{Microchip}
24528 \begin_inset Formula $^{\text{TM}}$
24532 \begin_inset LatexCommand \index{PIC}
24537 \begin_inset Formula $^{\text{TM}}$
24540 MCUs with 16 bit wide instructions.
24541 Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx
24542 ; devices supported by the port include:
24545 \begin_layout Standard
24546 18F: 242, 248, 252, 258, 442, 448, 452, 458
24549 \begin_layout Standard
24553 \begin_layout Standard
24554 18F: 2220, 2221, 2320, 2321, 2331, 2420, 2423, 2431, 2455, 2480, 24j10
24557 \begin_layout Standard
24558 18F: 2520, 2523, 2525, 2550, 2580, 2585, 25j10, 2620, 2680, 2682, 2685
24561 \begin_layout Standard
24562 18F: 4220, 4221, 4320, 4321, 4331, 4420, 4423, 4431, 4455, 4480, 44j10
24565 \begin_layout Standard
24566 18F: 4520, 4523, 4525, 4550, 4580, 4585, 45j10, 4620, 4680, 4682, 4685
24569 \begin_layout Standard
24570 18F: 6520, 6585, 6620, 6680, 6720
24573 \begin_layout Standard
24574 18F: 8520, 8585, 8620, 8680, 8720
24577 \begin_layout Standard
24578 A list of supported devices is also available via '
24580 sdcc -mpic16 -plist
24585 \begin_layout Subsection
24589 \begin_layout Standard
24590 PIC16 port supports the standard command line arguments as supposed, with
24591 the exception of certain cases that will be mentioned in the following
24595 \begin_layout Description
24600 \begin_layout Standard
24610 \begin_inset LatexCommand \index{PIC16!Options!-\/-callee-saves}
24618 \begin_layout Standard
24630 \begin_layout Description
24635 \begin_layout Standard
24644 -fommit-frame-pointer
24645 \begin_inset LatexCommand \index{PIC16!Options!-\/-fommit-frame-pointer}
24649 Frame pointer will be omitted when the function uses no local variables.
24652 \begin_layout Subsection
24653 Port Specific Options
24654 \begin_inset LatexCommand \index{Options PIC16}
24661 \begin_layout Standard
24662 The port specific options appear after the global options in the sdcc -
24666 \begin_layout Standard
24678 \begin_layout Subsubsection
24679 Code Generation Options
24682 \begin_layout Standard
24683 These options influence the generated assembler code.
24686 \begin_layout Description
24691 \begin_layout Standard
24700 -pstack-model=[model] Used in conjuction with the command above.
24701 Defines the stack model to be used, valid stack models are:
24706 \labelwidthstring 00.00.0000
24711 Selects small stack model.
24712 8 bit stack and frame pointers.
24713 Supports 256 bytes stack size.
24717 \labelwidthstring 00.00.0000
24722 Selects large stack model.
24723 16 bit stack and frame pointers.
24724 Supports 65536 bytes stack size.
24728 \begin_layout Description
24733 \begin_layout Standard
24742 -pno-banksel Do not generate BANKSEL assembler directives.
24745 \begin_layout Description
24750 \begin_layout Standard
24759 -extended Enable extended instruction set/literal offset addressing mode.
24763 \begin_layout Subsubsection
24764 Optimization Options
24767 \begin_layout Description
24772 \begin_layout Standard
24781 -obanksel=n Set optimization level for inserting BANKSELs.
24788 \labelwidthstring 00.00.0000
24793 \labelwidthstring 00.00.0000
24794 1 checks previous used register and if it is the same then does not emit
24795 BANKSEL, accounts only for labels.
24799 \labelwidthstring 00.00.0000
24800 2 tries to check the location of (even different) symbols and removes BANKSELs
24801 if they are in the same bank.
24806 Important: There might be problems if the linker script has data sections
24807 across bank borders!
24811 \begin_layout Description
24816 \begin_layout Standard
24825 -denable-peeps Force the usage of peepholes.
24829 \begin_layout Description
24834 \begin_layout Standard
24843 -no-optimize-goto Do not use (conditional) BRA instead of GOTO.
24846 \begin_layout Description
24851 \begin_layout Standard
24860 -optimize-cmp Try to optimize some compares.
24863 \begin_layout Description
24868 \begin_layout Standard
24877 -optimize-df Analyze the dataflow of the generated code and improve it.
24880 \begin_layout Subsubsection
24884 \begin_layout Description
24889 \begin_layout Standard
24898 -asm= Sets the full path and name of an external assembler to call.
24901 \begin_layout Description
24906 \begin_layout Standard
24916 \begin_inset LatexCommand \index{PIC16!MPLAB}
24920 compatibility option.
24921 Currently only suppresses special gpasm directives.
24924 \begin_layout Subsubsection
24928 \begin_layout Description
24933 \begin_layout Standard
24942 -link= Sets the full path and name of an external linker to call.
24945 \begin_layout Description
24950 \begin_layout Standard
24959 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
24960 unitialized data variables with [kword].
24961 Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
24964 \begin_layout Description
24969 \begin_layout Standard
24978 -ivt-loc=n Place the interrupt vector table at address
24983 Useful for bootloaders.
24986 \begin_layout Description
24991 \begin_layout Standard
25000 -nodefaultlibs Do not link default libraries when linking.
25003 \begin_layout Description
25008 \begin_layout Standard
25017 -use-crt= Use a custom run-time module instead of the defaults.
25020 \begin_layout Description
25025 \begin_layout Standard
25034 -no-crt Don't link the default run-time modules
25037 \begin_layout Subsubsection
25041 \begin_layout Standard
25042 Debugging options enable extra debugging information in the output files.
25045 \begin_layout Description
25050 \begin_layout Standard
25059 -debug-xtra Similar to -
25063 \begin_layout Standard
25073 \begin_inset LatexCommand \index{-\/-debug}
25077 , but dumps more information.
25080 \begin_layout Description
25085 \begin_layout Standard
25094 -debug-ralloc Force register allocator to dump <source>.d file with debugging
25096 <source> is the name of the file being compiled.
25099 \begin_layout Description
25104 \begin_layout Standard
25113 -pcode-verbose Enable pcode debugging information in translation.
25116 \begin_layout Description
25121 \begin_layout Standard
25130 -calltree Dump call tree in .calltree file.
25133 \begin_layout Description
25138 \begin_layout Standard
25147 -gstack Trace push/pops for stack pointer overflow.
25150 \begin_layout Subsection
25151 Enviroment Variables
25154 \begin_layout Standard
25155 There is a number of enviromental variables that can be used when running
25156 SDCC to enable certain optimizations or force a specific program behaviour.
25157 these variables are primarily for debugging purposes so they can be enabled/dis
25161 \begin_layout Standard
25162 Currently there is only two such variables available:
25165 \begin_layout Description
25166 OPTIMIZE_BITFIELD_POINTER_GET When this variable exists, reading of structure
25167 bitfields is optimized by directly loading FSR0 with the address of the
25168 bitfield structure.
25169 Normally SDCC will cast the bitfield structure to a bitfield pointer and
25171 This step saves data ram and code space for functions that make heavy use
25173 (i.e., 80 bytes of code space are saved when compiling malloc.c with this
25178 \begin_layout Description
25179 NO_REG_OPT Do not perform pCode registers optimization.
25180 This should be used for debugging purposes.
25181 If bugs in the pcode optimizer are found, users can benefit from temporarily
25182 disabling the optimizer until the bug is fixed.
25185 \begin_layout Subsection
25186 Preprocessor Macros
25189 \begin_layout Standard
25191 \begin_inset LatexCommand \index{PIC16}
25195 port defines the following preprocessor macros while translating a source.
25198 \begin_layout Standard
25200 \begin_inset Tabular
25201 <lyxtabular version="3" rows="6" columns="2">
25203 <column alignment="center" valignment="top" leftline="true" width="0">
25204 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
25205 <row topline="true" bottomline="true">
25206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25209 \begin_layout Standard
25215 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25218 \begin_layout Standard
25225 <row topline="true">
25226 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25229 \begin_layout Standard
25235 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25238 \begin_layout Standard
25239 Port identification
25245 <row topline="true">
25246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25249 \begin_layout Standard
25254 \begin_layout Standard
25268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25271 \begin_layout Standard
25272 Port identification (same as above)
25278 <row topline="true">
25279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25282 \begin_layout Standard
25288 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25291 \begin_layout Standard
25292 MCU Identification.
25297 is the microcontrol identification number, i.e.
25304 <row topline="true">
25305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25308 \begin_layout Standard
25313 \begin_layout Standard
25327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25330 \begin_layout Standard
25331 MCU Identification (same as above)
25337 <row topline="true" bottomline="true">
25338 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25341 \begin_layout Standard
25347 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25350 \begin_layout Standard
25351 nnn = SMALL or LARGE respectively according to the stack model used
25364 \begin_layout Standard
25365 In addition the following macros are defined when calling assembler:
25368 \begin_layout Standard
25370 \begin_inset Tabular
25371 <lyxtabular version="3" rows="4" columns="2">
25373 <column alignment="center" valignment="top" leftline="true" width="0">
25374 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
25375 <row topline="true" bottomline="true">
25376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25379 \begin_layout Standard
25385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25388 \begin_layout Standard
25395 <row topline="true">
25396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25399 \begin_layout Standard
25405 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25408 \begin_layout Standard
25409 MCU Identification.
25414 is the microcontrol identification number, i.e.
25421 <row topline="true">
25422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25425 \begin_layout Standard
25431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25434 \begin_layout Standard
25435 nnn = SMALL or LARGE respectively according to the memory model used for
25442 <row topline="true" bottomline="true">
25443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25446 \begin_layout Standard
25452 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25455 \begin_layout Standard
25456 nnn = SMALL or LARGE respectively according to the stack model used
25469 \begin_layout Subsection
25473 \begin_layout Standard
25475 \begin_inset LatexCommand \index{PIC16}
25479 port uses the following directories for searching header files and libraries.
25482 \begin_layout Standard
25484 \begin_inset Tabular
25485 <lyxtabular version="3" rows="3" columns="4">
25487 <column alignment="center" valignment="top" leftline="true" width="0">
25488 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
25489 <column alignment="center" valignment="top" width="0">
25490 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
25491 <row topline="true" bottomline="true">
25492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25495 \begin_layout Standard
25501 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25504 \begin_layout Standard
25510 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25513 \begin_layout Standard
25519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25522 \begin_layout Standard
25529 <row topline="true">
25530 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25533 \begin_layout Standard
25534 PREFIX/sdcc/include/pic16
25539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25542 \begin_layout Standard
25543 PIC16 specific headers
25548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25551 \begin_layout Standard
25557 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25560 \begin_layout Standard
25567 <row topline="true" bottomline="true">
25568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25571 \begin_layout Standard
25572 PREFIX/sdcc/lib/pic16
25577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25580 \begin_layout Standard
25581 PIC16 specific libraries
25586 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25589 \begin_layout Standard
25595 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25598 \begin_layout Standard
25612 \begin_layout Subsection
25614 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
25621 \begin_layout Standard
25623 \begin_inset LatexCommand \index{PIC16}
25627 port currently supports the following pragmas:
25630 \begin_layout Description
25632 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma stack}
25636 This forces the code generator to initialize the stack & frame pointers
25637 at a specific address.
25638 This is an ad hoc solution for cases where no STACK directive is available
25639 in the linker script or gplink is not instructed to create a stack section.
25642 stack pragma should be used only once in a project.
25643 Multiple pragmas may result in indeterminate behaviour of the program.
25647 \begin_layout Standard
25648 The old format (ie.
25649 #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
25650 cross page boundaries (or even exceed the available data RAM) and crash
25652 Make sure that stack does not cross page boundaries when using the SMALL
25660 The format is as follows:
25665 \begin_layout LyX-Code
25666 #pragma stack bottom_address [stack_size]
25671 \begin_layout Standard
25676 is the lower bound of the stack section.
25677 The stack pointer initially will point at address (bottom_address+stack_size-1).
25680 \begin_layout LyX-Code
25684 \begin_layout LyX-Code
25688 \begin_layout LyX-Code
25689 /* initializes stack of 100 bytes at RAM address 0x200 */
25692 \begin_layout LyX-Code
25693 #pragma stack 0x200 100
25696 \begin_layout Standard
25697 If the stack_size field is omitted then a stack is created with the default
25699 This size might be enough for most programs, but its not enough for operations
25700 with deep function nesting or excessive stack usage.
25703 \begin_layout Description
25705 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma code}
25709 Force a function to a static FLASH address.
25712 \begin_layout LyX-Code
25716 \begin_layout LyX-Code
25720 \begin_layout LyX-Code
25721 /* place function test_func at 0x4000 */
25724 \begin_layout LyX-Code
25725 #pragma code test_func 0x4000
25728 \begin_layout LyX-Code
25732 \begin_layout Description
25733 library instructs the linker to use a library module.
25738 \begin_layout LyX-Code
25739 #pragma library module_name
25742 \begin_layout Standard
25747 can be any library or object file (including its path).
25748 Note that there are four reserved keywords which have special meaning.
25752 \begin_layout Standard
25754 \begin_inset Tabular
25755 <lyxtabular version="3" rows="6" columns="3">
25757 <column alignment="center" valignment="top" leftline="true" width="0">
25758 <column alignment="block" valignment="top" leftline="true" width="20page%">
25759 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
25760 <row topline="true" bottomline="true">
25761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25764 \begin_layout Standard
25770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25773 \begin_layout Standard
25779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25782 \begin_layout Standard
25789 <row topline="true">
25790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25793 \begin_layout Standard
25801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25804 \begin_layout Standard
25805 ignore all library pragmas
25810 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25813 \begin_layout Standard
25822 <row topline="true">
25823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25826 \begin_layout Standard
25834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25837 \begin_layout Standard
25843 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25846 \begin_layout Standard
25857 <row topline="true">
25858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25861 \begin_layout Standard
25869 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25872 \begin_layout Standard
25873 link the Math libarary
25878 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25881 \begin_layout Standard
25892 <row topline="true">
25893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25896 \begin_layout Standard
25904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25907 \begin_layout Standard
25908 link the I/O library
25913 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25916 \begin_layout Standard
25927 <row topline="true" bottomline="true">
25928 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25931 \begin_layout Standard
25939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25942 \begin_layout Standard
25943 link the debug library
25948 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25951 \begin_layout Standard
25968 * is the device number, i.e.
25969 452 for PIC18F452 MCU.
25972 \begin_layout Standard
25973 This feature allows for linking with specific libraries withoug having to
25974 explicit name them in the command line.
25979 keyword will reject all modules specified by the library pragma.
25982 \begin_layout Description
25983 udata The pragma udata instructs the compiler to emit code so that linker
25984 will place a variable at a specific memory bank.
25987 \begin_layout LyX-Code
25991 \begin_layout LyX-Code
25995 \begin_layout LyX-Code
25996 /* places variable foo at bank2 */
25999 \begin_layout LyX-Code
26000 #pragma udata bank2 foo
26003 \begin_layout LyX-Code
26007 \begin_layout Standard
26008 In order for this pragma to work extra SECTION directives should be added
26009 in the .lkr script.
26010 In the following example a sample .lkr file is shown:
26013 \begin_layout LyX-Code
26017 \begin_layout LyX-Code
26018 // Sample linker script for the PIC18F452 processor
26021 \begin_layout LyX-Code
26025 \begin_layout LyX-Code
26026 CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED
26029 \begin_layout LyX-Code
26030 CODEPAGE NAME=page START=0x2A END=0x7FFF
26033 \begin_layout LyX-Code
26034 CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED
26037 \begin_layout LyX-Code
26038 CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED
26041 \begin_layout LyX-Code
26042 CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED
26045 \begin_layout LyX-Code
26046 CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED
26049 \begin_layout LyX-Code
26050 ACCESSBANK NAME=accessram START=0x0 END=0x7F
26053 \begin_layout LyX-Code
26057 \begin_layout LyX-Code
26058 DATABANK NAME=gpr0 START=0x80 END=0xFF
26061 \begin_layout LyX-Code
26062 DATABANK NAME=gpr1 START=0x100 END=0x1FF
26065 \begin_layout LyX-Code
26066 DATABANK NAME=gpr2 START=0x200 END=0x2FF
26069 \begin_layout LyX-Code
26070 DATABANK NAME=gpr3 START=0x300 END=0x3FF
26073 \begin_layout LyX-Code
26074 DATABANK NAME=gpr4 START=0x400 END=0x4FF
26077 \begin_layout LyX-Code
26078 DATABANK NAME=gpr5 START=0x500 END=0x5FF
26081 \begin_layout LyX-Code
26082 ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED
26085 \begin_layout LyX-Code
26089 \begin_layout LyX-Code
26090 SECTION NAME=CONFIG ROM=config
26093 \begin_layout LyX-Code
26097 \begin_layout LyX-Code
26098 SECTION NAME=bank0 RAM=gpr0 # these SECTION directives
26101 \begin_layout LyX-Code
26102 SECTION NAME=bank1 RAM=gpr1 # should be added to link
26105 \begin_layout LyX-Code
26106 SECTION NAME=bank2 RAM=gpr2 # section name 'bank?' with
26109 \begin_layout LyX-Code
26110 SECTION NAME=bank3 RAM=gpr3 # a specific DATABANK name
26113 \begin_layout LyX-Code
26114 SECTION NAME=bank4 RAM=gpr4
26117 \begin_layout LyX-Code
26118 SECTION NAME=bank5 RAM=gpr5
26121 \begin_layout Standard
26122 The linker will recognise the section name set in the pragma statement and
26123 will position the variable at the memory bank set with the RAM field at
26124 the SECTION line in the linker script file.
26127 \begin_layout Subsection
26129 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
26136 \begin_layout Standard
26137 There is one main header file
26138 \begin_inset LatexCommand \index{PIC16!Header files}
26142 that can be included to the source files using the pic16
26143 \begin_inset LatexCommand \index{PIC16}
26153 This header file contains the definitions for the processor special registers,
26154 so it is necessary if the source accesses them.
26155 It can be included by adding the following line in the beginning of the
26159 \begin_layout LyX-Code
26160 #include <pic18fregs.h>
26163 \begin_layout Standard
26164 The specific microcontroller is selected within the pic18fregs.h automatically,
26165 so the same source can be used with a variety of devices.
26168 \begin_layout Subsection
26172 \begin_layout Standard
26174 \begin_inset LatexCommand \index{PIC16!Libraries}
26179 \begin_inset LatexCommand \index{PIC16}
26183 port depends on are the microcontroller device libraries which contain
26184 the symbol definitions for the microcontroller special function registers.
26185 These libraries have the format pic18fxxxx.lib, where
26189 is the microcontroller identification number.
26190 The specific library is selected automatically by the compiler at link
26191 stage according to the selected device.
26194 \begin_layout Standard
26195 Libraries are created with gplib which is part of the gputils package
26196 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
26203 \begin_layout Subsubsection*
26204 Building the libraries
26207 \begin_layout Standard
26208 Before using SDCC/pic16 there are some libraries that need to be compiled.
26209 This process is not done automatically by SDCC since not all users use
26210 SDCC for pic16 projects.
26211 So each user should compile the libraries separately.
26214 \begin_layout Standard
26215 The steps to compile the pic16 libraries under Linux and Mac OS X are:
26218 \begin_layout LyX-Code
26219 cd device/lib/pic16
26222 \begin_layout LyX-Code
26226 \begin_layout LyX-Code
26230 \begin_layout LyX-Code
26234 \begin_layout LyX-Code
26238 \begin_layout LyX-Code
26239 su -c 'make install' # install the libraries, you need the root password
26242 \begin_layout Standard
26243 If you need to install the headers too, do:
26246 \begin_layout LyX-Code
26250 \begin_layout LyX-Code
26251 su -c 'make install' # install the headers, you need the root password
26254 \begin_layout Standard
26255 There exist a special target to build the I/O libraries.
26256 This target is not automatically build because it will build the I/O library
26262 This way building will take quite a lot of time.
26263 Users are advised to edit the
26265 device/lib/pic16/pics.build
26267 file and then execute:
26270 \begin_layout LyX-Code
26274 \begin_layout Subsection
26275 Adding New Devices to the Port
26278 \begin_layout Standard
26279 Adding support for a new 16
26283 \begin_layout Standard
26292 bit PIC MCU requires the following steps:
26295 \begin_layout Enumerate
26296 Create picDEVICE.c and picDEVICE.h from pDEVICE.inc using
26300 perl /path/to/sdcc/support/scripts/inc2h-pic16.pl /path/to/gputils/header/pDEVICE.
26304 \begin_layout Enumerate
26307 mv picDEVICE.h /path/to/sdcc/device/include/pic16
26310 \begin_layout Enumerate
26313 mv picDEVICE.c /path/to/sdcc/device/lib/pic16/libdev
26316 \begin_layout Enumerate
26319 /path/to/sdcc/device/lib/pic16/pics.all
26327 Note: No 18f prefix here!
26330 \begin_layout Enumerate
26331 Set up the I/O library by doing
26339 \begin_layout Enumerate
26342 /path/to/sdcc/device/lib/pic16/libio/*.ignore
26346 Add your DEVICE if it does not compile in
26361 \begin_layout Enumerate
26364 /path/to/sdcc/device/include/pic16/adc.h
26368 Add the new devices to the correct ADC style class.
26372 \begin_layout Enumerate
26375 /path/to/sdcc/device/include/pic16/pic18fregs.h
26378 The file format is self-explanatory, just add
26382 #elif defined(picDEVICE)
26384 # include <picDEVICE.h>
26388 at the right place (keep it sorted).
26391 \begin_layout Enumerate
26394 /path/to/sdcc/device/include/pic16devices.txt
26398 Copy and modify an existing entry or create a new one and insert it at the
26399 correct place (keep the file sorted).
26402 \begin_layout Enumerate
26403 Recompile the pic16 libraries.
26406 \begin_layout Subsection
26410 \begin_layout Standard
26411 The following memory models are supported by the PIC16 port:
26414 \begin_layout Itemize
26418 \begin_layout Itemize
26422 \begin_layout Standard
26423 Memory model affects the default size of pointers within the source.
26424 The sizes are shown in the next table:
26427 \begin_layout Standard
26429 \begin_inset Tabular
26430 <lyxtabular version="3" rows="3" columns="3">
26432 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26433 <column alignment="center" valignment="top" leftline="true" width="0">
26434 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26435 <row topline="true" bottomline="true">
26436 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26439 \begin_layout Standard
26440 Pointer sizes according to memory model
26445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26448 \begin_layout Standard
26454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26457 \begin_layout Standard
26464 <row topline="true" bottomline="true">
26465 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26468 \begin_layout Standard
26474 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26477 \begin_layout Standard
26483 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26486 \begin_layout Standard
26493 <row topline="true" bottomline="true">
26494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26497 \begin_layout Standard
26503 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
26506 \begin_layout Standard
26512 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26515 \begin_layout Standard
26529 \begin_layout Standard
26530 It is advisable that all sources within a project are compiled with the
26532 If one wants to override the default memory model, this can be done by
26533 declaring a pointer as
26542 Far selects large memory model's pointers, while near selects small memory
26546 \begin_layout Standard
26547 The standard device libraries (see
26548 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
26552 ) contain no reference to pointers, so they can be used with both memory
26556 \begin_layout Subsection
26560 \begin_layout Standard
26562 \begin_inset LatexCommand \index{PIC16!stack}
26566 implementation for the PIC16 port uses two indirect registers, FSR1 and
26570 \begin_layout Description
26571 FSR1 is assigned as stack pointer
26574 \begin_layout Description
26575 FSR2 is assigned as frame pointer
26578 \begin_layout Standard
26579 The following stack models are supported by the PIC16 port
26582 \begin_layout Itemize
26590 \begin_layout Itemize
26598 \begin_layout Standard
26603 model means that only the FSRxL byte is used to access stack and frame,
26610 uses both FSRxL and FSRxH registers.
26611 The following table shows the stack/frame pointers sizes according to stack
26612 model and the maximum space they can address:
26615 \begin_layout Standard
26617 \begin_inset Tabular
26618 <lyxtabular version="3" rows="3" columns="3">
26620 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26621 <column alignment="center" valignment="top" leftline="true" width="0">
26622 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26623 <row topline="true" bottomline="true">
26624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26627 \begin_layout Standard
26628 Stack & Frame pointer sizes according to stack model
26633 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26636 \begin_layout Standard
26642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26645 \begin_layout Standard
26652 <row topline="true">
26653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26656 \begin_layout Standard
26662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26665 \begin_layout Standard
26671 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26674 \begin_layout Standard
26681 <row topline="true" bottomline="true">
26682 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26685 \begin_layout Standard
26691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26694 \begin_layout Standard
26700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26703 \begin_layout Standard
26717 \begin_layout Standard
26722 stack model is currently not working properly throughout the code generator.
26723 So its use is not advised.
26724 Also there are some other points that need special care:
26729 \begin_layout Enumerate
26730 Do not create stack sections with size more than one physical bank (that
26734 \begin_layout Enumerate
26735 Stack sections should no cross physical bank limits (i.e.
26736 #pragma stack 0x50 0x100)
26739 \begin_layout Standard
26740 These limitations are caused by the fact that only FSRxL is modified when
26741 using SMALL stack model, so no more than 256 bytes of stack can be used.
26742 This problem will disappear after LARGE model is fully implemented.
26745 \begin_layout Subsection
26749 \begin_layout Standard
26750 In addition to the standard SDCC function keywords, PIC16
26751 \begin_inset LatexCommand \index{PIC16}
26755 port makes available two more:
26758 \begin_layout Description
26760 \begin_inset LatexCommand \index{PIC16!wparam}
26764 Use the WREG to pass one byte of the first function argument.
26765 This improves speed but you may not use this for functions with arguments
26766 that are called via function pointers, otherwise the first byte of the
26767 first parameter will get lost.
26771 \begin_layout LyX-Code
26772 void func_wparam(int a) wparam
26775 \begin_layout LyX-Code
26779 \begin_layout LyX-Code
26780 /* WREG hold the lower part of a */
26783 \begin_layout LyX-Code
26784 /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
26788 \begin_layout LyX-Code
26792 \begin_layout LyX-Code
26796 \begin_layout Description
26798 \begin_inset LatexCommand \index{PIC16!shadowregs}
26802 When entering/exiting an ISR, it is possible to take advantage of the PIC18F
26803 hardware shadow registers which hold the values of WREG, STATUS and BSR
26805 This can be done by adding the keyword
26813 keyword in the function's header.
26816 \begin_layout LyX-Code
26817 void isr_shadow(void) shadowregs interrupt 1
26820 \begin_layout LyX-Code
26824 \begin_layout LyX-Code
26828 \begin_layout LyX-Code
26832 \begin_layout Standard
26837 instructs the code generator not to store/restore WREG, STATUS, BSR when
26838 entering/exiting the ISR.
26841 \begin_layout Subsection
26842 Function return values
26845 \begin_layout Standard
26846 Return values from functions are placed to the appropriate registers following
26847 a modified Microchip policy optimized for SDCC.
26848 The following table shows these registers:
26851 \begin_layout Standard
26853 \begin_inset Tabular
26854 <lyxtabular version="3" rows="6" columns="2">
26856 <column alignment="center" valignment="top" leftline="true" width="0">
26857 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26858 <row topline="true" bottomline="true">
26859 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26862 \begin_layout Standard
26868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26871 \begin_layout Standard
26872 destination register
26878 <row topline="true">
26879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26882 \begin_layout Standard
26888 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26891 \begin_layout Standard
26898 <row topline="true">
26899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26902 \begin_layout Standard
26908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26911 \begin_layout Standard
26918 <row topline="true">
26919 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26922 \begin_layout Standard
26928 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26931 \begin_layout Standard
26938 <row topline="true">
26939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26942 \begin_layout Standard
26948 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26951 \begin_layout Standard
26952 FSR0L:PRODH:PRODL:WREG
26958 <row topline="true" bottomline="true">
26959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26962 \begin_layout Standard
26968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26971 \begin_layout Standard
26972 on stack, FSR0 points to the beginning
26985 \begin_layout Subsection
26989 \begin_layout Standard
26991 \begin_inset LatexCommand \index{PIC16!interrupt}
26995 service routine (ISR) is declared using the
27002 \begin_layout LyX-Code
27003 void isr(void) interrupt
27008 \begin_layout LyX-Code
27012 \begin_layout LyX-Code
27016 \begin_layout LyX-Code
27020 \begin_layout Standard
27025 is the interrupt number, which for PIC18F devices can be:
27028 \begin_layout Standard
27030 \begin_inset Tabular
27031 <lyxtabular version="3" rows="4" columns="3">
27033 <column alignment="center" valignment="top" leftline="true" width="0">
27034 <column alignment="center" valignment="top" leftline="true" width="0">
27035 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27036 <row topline="true" bottomline="true">
27037 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27040 \begin_layout Standard
27048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27051 \begin_layout Standard
27057 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27060 \begin_layout Standard
27061 Interrupt Vector Address
27067 <row topline="true">
27068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27071 \begin_layout Standard
27077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27080 \begin_layout Standard
27086 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27089 \begin_layout Standard
27096 <row topline="true">
27097 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27100 \begin_layout Standard
27115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27118 \begin_layout Standard
27128 HIGH priority interrupts
27133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27136 \begin_layout Standard
27143 <row topline="true" bottomline="true">
27144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27147 \begin_layout Standard
27153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27156 \begin_layout Standard
27157 LOW priority interrupts
27162 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27165 \begin_layout Standard
27179 \begin_layout Standard
27180 When generating assembly code for ISR the code generator places a
27186 Interrupt Vector Address
27188 which points at the genetated ISR.
27189 This single GOTO instruction is part of an automatically generated
27191 interrupt entry point
27194 The actuall ISR code is placed as normally would in the code space.
27195 Upon interrupt request, the GOTO instruction is executed which jumps to
27197 When declaring interrupt functions as _naked this GOTO instruction is
27202 The whole interrupt functions is therefore placed at the Interrupt Vector
27203 Address of the specific interrupt.
27204 This is not a problem for the LOW priority interrupts, but it is a problem
27205 for the RESET and the HIGH priority interrupts because code may be written
27206 at the next interrupt's vector address and cause undeterminate program
27207 behaviour if that interrupt is raised.
27211 \begin_layout Standard
27212 This is not a problem when
27215 \begin_layout Enumerate
27216 this is a HIGH interrupt ISR and LOW interrupts are
27223 \begin_layout Enumerate
27224 when the ISR is small enough not to reach the next interrupt's vector address.
27232 \begin_layout Standard
27238 This way a function is generated similar to an ISR, but it is not assigned
27242 \begin_layout Standard
27243 When entering an interrupt, currently the PIC16
27244 \begin_inset LatexCommand \index{PIC16}
27248 port automatically saves the following registers:
27251 \begin_layout Itemize
27255 \begin_layout Itemize
27259 \begin_layout Itemize
27263 \begin_layout Itemize
27264 PROD (PRODL and PRODH)
27267 \begin_layout Itemize
27268 FSR0 (FSR0L and FSR0H)
27271 \begin_layout Standard
27272 These registers are restored upon return from the interrupt routine.
27276 \begin_layout Standard
27277 NOTE that when the _naked attribute is specified for an interrupt routine,
27278 then NO registers are stored or restored.
27286 \begin_layout Subsection
27290 \begin_layout Standard
27291 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
27292 There are 3 types of generic pointers currently implemented data, code
27293 and eeprom pointers.
27294 They are differentiated by the value of the 7th and 6th bits of the upper
27298 \begin_layout Standard
27300 \begin_inset Tabular
27301 <lyxtabular version="3" rows="5" columns="5">
27303 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27304 <column alignment="center" valignment="top" width="0">
27305 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27306 <column alignment="center" valignment="top" width="0">
27307 <column alignment="left" valignment="top" rightline="true" width="0">
27308 <row topline="true" bottomline="true">
27309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27312 \begin_layout Standard
27318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27321 \begin_layout Standard
27327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27330 \begin_layout Standard
27336 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27339 \begin_layout Standard
27340 rest of the pointer
27345 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27348 \begin_layout Standard
27355 <row topline="true" bottomline="true">
27356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27359 \begin_layout Standard
27365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27368 \begin_layout Standard
27374 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27377 \begin_layout Standard
27383 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27386 \begin_layout Standard
27391 uuuuuu uuuuxxxx xxxxxxxx
27396 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27399 \begin_layout Standard
27400 a 12-bit data pointer in data RAM memory
27406 <row bottomline="true">
27407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27410 \begin_layout Standard
27416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27419 \begin_layout Standard
27425 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27428 \begin_layout Standard
27434 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27437 \begin_layout Standard
27442 uxxxxx xxxxxxxx xxxxxxxx
27447 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27450 \begin_layout Standard
27451 a 21-bit code pointer in FLASH memory
27457 <row bottomline="true">
27458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27461 \begin_layout Standard
27467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27470 \begin_layout Standard
27476 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27479 \begin_layout Standard
27485 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27488 \begin_layout Standard
27493 uuuuuu uuuuuuxx xxxxxxxx
27498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27501 \begin_layout Standard
27502 a 10-bit eeprom pointer in EEPROM memory
27508 <row bottomline="true">
27509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27512 \begin_layout Standard
27518 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27521 \begin_layout Standard
27527 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27530 \begin_layout Standard
27536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27539 \begin_layout Standard
27544 xxxxxx xxxxxxxx xxxxxxxx
27549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27552 \begin_layout Standard
27553 unimplemented pointer type
27566 \begin_layout Standard
27567 Generic pointer are read and written with a set of library functions which
27568 read/write 1, 2, 3, 4 bytes.
27571 \begin_layout Subsection
27575 \begin_layout Subsubsection
27576 Standard I/O Streams
27579 \begin_layout Standard
27584 the type FILE is defined as:
27587 \begin_layout LyX-Code
27588 typedef char * FILE;
27591 \begin_layout Standard
27592 This type is the stream type implemented I/O in the PIC18F devices.
27593 Also the standard input and output streams are declared in stdio.h:
27596 \begin_layout LyX-Code
27597 extern FILE * stdin;
27600 \begin_layout LyX-Code
27601 extern FILE * stdout;
27604 \begin_layout Standard
27605 The FILE type is actually a generic pointer which defines one more type
27606 of generic pointers, the
27611 This new type has the format:
27614 \begin_layout Standard
27616 \begin_inset Tabular
27617 <lyxtabular version="3" rows="2" columns="7">
27619 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27620 <column alignment="center" valignment="top" width="0">
27621 <column alignment="center" valignment="top" leftline="true" width="0">
27622 <column alignment="center" valignment="top" leftline="true" width="0">
27623 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27624 <column alignment="center" valignment="top" width="0">
27625 <column alignment="left" valignment="top" rightline="true" width="0">
27626 <row topline="true" bottomline="true">
27627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27630 \begin_layout Standard
27636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27639 \begin_layout Standard
27645 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27648 \begin_layout Standard
27654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27657 \begin_layout Standard
27663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27666 \begin_layout Standard
27672 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27675 \begin_layout Standard
27676 rest of the pointer
27681 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27684 \begin_layout Standard
27691 <row topline="true" bottomline="true">
27692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27695 \begin_layout Standard
27701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27704 \begin_layout Standard
27710 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27713 \begin_layout Standard
27719 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27722 \begin_layout Standard
27728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27731 \begin_layout Standard
27737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27740 \begin_layout Standard
27750 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27753 \begin_layout Standard
27754 upper byte high nubble is 0x2n, the rest are zeroes
27767 \begin_layout Standard
27768 Currently implemented there are 3 types of streams defined:
27771 \begin_layout Standard
27773 \begin_inset Tabular
27774 <lyxtabular version="3" rows="4" columns="4">
27776 <column alignment="center" valignment="top" leftline="true" width="0">
27777 <column alignment="center" valignment="top" leftline="true" width="0">
27778 <column alignment="center" valignment="top" leftline="true" width="0">
27779 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27780 <row topline="true" bottomline="true">
27781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27784 \begin_layout Standard
27790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27793 \begin_layout Standard
27799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27802 \begin_layout Standard
27808 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27811 \begin_layout Standard
27818 <row topline="true">
27819 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27822 \begin_layout Standard
27828 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27831 \begin_layout Standard
27839 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27842 \begin_layout Standard
27848 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27851 \begin_layout Standard
27852 Writes/Reads characters via the USART peripheral
27858 <row topline="true">
27859 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27862 \begin_layout Standard
27868 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27871 \begin_layout Standard
27879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27882 \begin_layout Standard
27888 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27891 \begin_layout Standard
27892 Writes/Reads characters via the MSSP peripheral
27898 <row topline="true" bottomline="true">
27899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27902 \begin_layout Standard
27908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27911 \begin_layout Standard
27919 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27922 \begin_layout Standard
27928 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27931 \begin_layout Standard
27932 Writes/Reads characters via used defined functions
27945 \begin_layout Standard
27946 The stream identifiers are declared as macros in the stdio.h header.
27949 \begin_layout Standard
27950 In the libc library there exist the functions that are used to write to
27951 each of the above streams.
27955 \begin_layout Description
27960 \begin_layout Standard
27969 _stream_usart_putchar writes a character at the USART stream
27972 \begin_layout Description
27977 \begin_layout Standard
27986 _stream_mssp_putchar writes a character at the MSSP stream
27989 \begin_layout Description
27990 putchar dummy function.
27991 This writes a character to a user specified manner.
27994 \begin_layout Standard
27995 In order to increase performance
27999 is declared in stdio.h as having its parameter in WREG (it has the wparam
28001 In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
28002 in a user-friendly way.
28007 is the name of the variable that holds the character to print.
28008 An example follows:
28011 \begin_layout LyX-Code
28012 #include <pic18fregs.h>
28021 \begin_layout LyX-Code
28025 \begin_layout LyX-Code
28026 PORTA = c; /* dump character c to PORTA */
28029 \begin_layout LyX-Code
28037 \begin_layout LyX-Code
28041 \begin_layout LyX-Code
28042 stdout = STREAM_USER; /* this is not necessary, since stdout points
28045 \begin_layout LyX-Code
28046 * by default to STREAM_USER */
28049 \begin_layout LyX-Code
28051 \begin_inset Quotes sld
28054 This is a printf test
28057 \begin_inset Quotes srd
28063 \begin_layout LyX-Code
28067 \begin_layout LyX-Code
28071 \begin_layout Subsubsection
28075 \begin_layout Standard
28076 PIC16 contains an implementation of the printf-family of functions.
28077 There exist the following functions:
28080 \begin_layout LyX-Code
28081 extern unsigned int sprintf(char *buf, char *fmt, ...);
28084 \begin_layout LyX-Code
28085 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
28088 \begin_layout LyX-Code
28092 \begin_layout LyX-Code
28093 extern unsigned int printf(char *fmt, ...);
28096 \begin_layout LyX-Code
28097 extern unsigned int vprintf(char *fmt, va_lista ap);
28100 \begin_layout LyX-Code
28104 \begin_layout LyX-Code
28105 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
28108 \begin_layout LyX-Code
28109 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
28112 \begin_layout Standard
28113 For sprintf and vsprintf
28117 should normally be a data pointer where the resulting string will be placed.
28118 No range checking is done so the user should allocate the necessery buffer.
28119 For fprintf and vfprintf
28123 should be a stream pointer (i.e.
28124 stdout, STREAM_MSSP, etc...).
28127 \begin_layout Subsubsection
28131 \begin_layout Standard
28132 The PIC18F family of microcontrollers supports a number of interrupt sources.
28133 A list of these interrupts is shown in the following table:
28136 \begin_layout Standard
28138 \begin_inset Tabular
28139 <lyxtabular version="3" rows="11" columns="4">
28141 <column alignment="left" valignment="top" leftline="true" width="0">
28142 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28143 <column alignment="left" valignment="top" leftline="true" width="0">
28144 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28145 <row topline="true" bottomline="true">
28146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28149 \begin_layout Standard
28155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28158 \begin_layout Standard
28164 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
28193 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28196 \begin_layout Standard
28197 PORTB change interrupt
28202 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28205 \begin_layout Standard
28211 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28214 \begin_layout Standard
28215 EEPROM/FLASH write complete interrupt
28221 <row topline="true">
28222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28225 \begin_layout Standard
28231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28234 \begin_layout Standard
28235 INT0 external interrupt
28240 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28243 \begin_layout Standard
28249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28252 \begin_layout Standard
28253 Bus collision interrupt
28259 <row topline="true">
28260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28263 \begin_layout Standard
28269 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28272 \begin_layout Standard
28273 INT1 external interrupt
28278 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28281 \begin_layout Standard
28287 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28290 \begin_layout Standard
28291 Low voltage detect interrupt
28297 <row topline="true">
28298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28301 \begin_layout Standard
28307 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28310 \begin_layout Standard
28311 INT2 external interrupt
28316 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28319 \begin_layout Standard
28325 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28328 \begin_layout Standard
28329 Parallel slave port interrupt
28335 <row topline="true">
28336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28339 \begin_layout Standard
28345 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28348 \begin_layout Standard
28349 CCP1 module interrupt
28354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28357 \begin_layout Standard
28363 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28366 \begin_layout Standard
28367 AD convertion complete interrupt
28373 <row topline="true">
28374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28377 \begin_layout Standard
28383 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28386 \begin_layout Standard
28387 CCP2 module interrupt
28392 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28395 \begin_layout Standard
28401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28404 \begin_layout Standard
28405 USART receive interrupt
28411 <row topline="true">
28412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28415 \begin_layout Standard
28421 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28424 \begin_layout Standard
28425 TMR0 overflow interrupt
28430 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28433 \begin_layout Standard
28439 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28442 \begin_layout Standard
28443 USART transmit interrupt
28449 <row topline="true">
28450 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28453 \begin_layout Standard
28459 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28462 \begin_layout Standard
28463 TMR1 overflow interrupt
28468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28471 \begin_layout Standard
28477 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28480 \begin_layout Standard
28481 SSP receive/transmit interrupt
28487 <row topline="true">
28488 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28491 \begin_layout Standard
28497 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28500 \begin_layout Standard
28501 TMR2 matches PR2 interrupt
28506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28509 \begin_layout Standard
28515 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28518 \begin_layout Standard
28525 <row topline="true" bottomline="true">
28526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28529 \begin_layout Standard
28535 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28538 \begin_layout Standard
28539 TMR3 overflow interrupt
28544 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28547 \begin_layout Standard
28553 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28556 \begin_layout Standard
28570 \begin_layout Standard
28571 The prototypes for these names are defined in the header file
28578 \begin_layout Standard
28579 In order to simplify signal handling, a number of macros is provided:
28583 \labelwidthstring 00.00.0000
28584 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
28585 high priority interrupts.
28590 is the function name to use.
28594 \labelwidthstring 00.00.0000
28595 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
28596 low priority interrupt.
28601 is the function name to use.
28605 \labelwidthstring 00.00.0000
28606 DEF_HANDLER(sig,handler) define a handler for signal
28612 \labelwidthstring 00.00.0000
28613 END_DEF end the declaration of the dispatch table.
28616 \begin_layout Standard
28617 Additionally there are two more macros to simplify the declaration of the
28622 \labelwidthstring 00.00.0000
28625 SIGHANDLER(handler)
28627 this declares the function prototype for the
28635 \labelwidthstring 00.00.0000
28636 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
28639 \begin_layout Standard
28640 An example of using the macros above is shown below:
28643 \begin_layout LyX-Code
28644 #include <pic18fregs.h>
28647 \begin_layout LyX-Code
28648 #include <signal.h>
28652 DEF_INTHIGH(high_int)
28655 \begin_layout LyX-Code
28656 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
28659 \begin_layout LyX-Code
28660 DEF_HANDLER(SIG_BCOL, _bcol_handler)
28663 \begin_layout LyX-Code
28668 SIGHANDLER(_tmr0_handler)
28671 \begin_layout LyX-Code
28675 \begin_layout LyX-Code
28676 /* action to be taken when timer 0 overflows */
28679 \begin_layout LyX-Code
28684 SIGHANDLERNAKED(_bcol_handler)
28687 \begin_layout LyX-Code
28691 \begin_layout LyX-Code
28695 \begin_layout LyX-Code
28696 /* action to be taken when bus collision occurs */
28699 \begin_layout LyX-Code
28703 \begin_layout LyX-Code
28707 \begin_layout LyX-Code
28711 \begin_layout Standard
28716 Special care should be taken when using the above scheme:
28719 \begin_layout Itemize
28720 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
28723 \begin_layout Itemize
28724 when declaring SIGHANDLERNAKED handler never forget to use
28728 for proper returning.
28731 \begin_layout Subsection
28735 \begin_layout Standard
28736 Here you can find some general tips for compiling programs with SDCC/pic16.
28739 \begin_layout Subsubsection
28743 \begin_layout Standard
28745 \begin_inset LatexCommand \index{PIC16!stack}
28749 size (that is 64 bytes) probably is enough for many programs.
28750 One must take care that when there are many levels of function nesting,
28751 or there is excessive usage of stack, its size should be extended.
28752 An example of such a case is the printf/sprintf family of functions.
28753 If you encounter problems like not being able to print integers, then you
28754 need to set the stack size around the maximum (256 for small stack model).
28755 The following diagram shows what happens when calling printf to print an
28759 \begin_layout LyX-Code
28760 printf () --> ltoa () --> ultoa () --> divschar ()
28763 \begin_layout Standard
28764 It is should be understood that stack is easily consumed when calling complicate
28766 Using command line arguments like -
28770 \begin_layout Standard
28779 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
28781 Other ways to reduce stack usage may exist.
28784 \begin_layout Subsection
28788 \begin_layout Standard
28789 The PIC16 Port currently does not pass SDCC's regression test
28790 \begin_inset LatexCommand \index{Regression test (PIC16)}
28795 \begin_inset LatexCommand \ref{sec:Quality-control}
28799 ) and thus the snapshot build regression tests for the PIC16 target are
28800 currently disabled for all hosts
28805 \begin_layout Chapter
28809 \begin_layout Standard
28810 There are several approaches to debugging your code.
28811 This chapter is meant to show your options and to give detail on some of
28816 When writing your code:
28819 \begin_layout Itemize
28820 write your code with debugging in mind (avoid duplicating code, put conceptually
28821 similar variables into structs, use structured code, have strategic points
28822 within your code where all variables are consistent, ...)
28825 \begin_layout Itemize
28826 run a syntax-checking tool like splint
28827 \begin_inset LatexCommand \index{splint (syntax checking tool)}
28832 \begin_inset LatexCommand \index{lint (syntax checking tool)}
28840 \begin_layout Standard
28850 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
28857 \begin_layout Itemize
28858 for the high level code use a C-compiler (like f.e.
28859 GCC) to compile run and debug the code on your host.
28864 \begin_layout Standard
28874 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
28878 ) on how to handle syntax extensions like __xdata, __at(), ...
28882 \begin_layout Itemize
28883 use another C-compiler to compile code for your target.
28884 Always an option but not recommended:) And not very likely to help you.
28885 If you seriously consider walking this path you should at least occasionally
28886 check portability of your code.
28887 Most commercial compiler vendors will offer an evaluation version so you
28888 can test compile your code or snippets of your code.
28891 \begin_layout Standard
28892 Debugging on a simulator:
28895 \begin_layout Itemize
28896 there is a separate section about SDCDB (section
28897 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
28904 \begin_layout Itemize
28905 or (8051 specific) use a freeware/commercial simulator which interfaces
28907 \begin_inset LatexCommand \index{AOMF, AOMF51}
28912 \begin_inset LatexCommand \ref{OMF file}
28916 ) optionally generated by SDCC.
28919 \begin_layout Standard
28920 Debugging On-target:
28923 \begin_layout Itemize
28924 use a MCU port pin to serially output debug data to the RS232 port of your
28926 You'll probably want some level shifting device typically involving a MAX232
28928 If the hardware serial port of the MCU is not available search for 'Software
28929 UART' in your favourite search machine.
28932 \begin_layout Itemize
28933 use an on-target monitor.
28934 In this context a monitor is a small program which usually accepts commands
28935 via a serial line and allows to set program counter, to single step through
28936 a program and read/write memory locations.
28937 For the 8051 good examples of monitors are paulmon and cmon51 (see section
28939 \begin_inset LatexCommand \ref{sec:Related-open-source-tools}
28946 \begin_layout Itemize
28947 toggle MCU port pins at strategic points within your code and use an oscilloscop
28951 digital oscilloscope
28954 \begin_inset LatexCommand \index{Oscilloscope}
28958 with deep trace memory is really helpful especially if you have to debug
28959 a realtime application.
28960 If you need to monitor more pins than your oscilloscope provides you can
28961 sometimes get away with a small R-2R network.
28962 On a single channel oscilloscope you could f.e.
28963 monitor 2 push-pull driven pins by connecting one via a 10\InsetSpace ~
28965 \begin_inset Formula $\Omega$
28968 resistor and the other one by a 5\InsetSpace ~
28970 \begin_inset Formula $\Omega$
28973 resistor to the oscilloscope probe (check output drive capability of the
28974 pins you want to monitor).
28975 If you need to monitor many more pins a
28982 \begin_layout Itemize
28996 \begin_inset LatexCommand \index{ICE (in circuit emulator)}
29001 Usually very expensive.
29002 And very nice to have too.
29003 And usually locks you (for years...) to the devices the ICE can emulate.
29007 \begin_layout Itemize
29008 use a remote debugger.
29009 In most 8-bit systems the symbol information is not available on the target,
29010 and a complete debugger is too bulky for the target system.
29011 Therefore usually a debugger on the host system connects to an on-target
29012 debugging stub which accepts only primitive commands.
29015 Terms to enter into your favourite search engine could be 'remote debugging',
29016 'gdb stub' or 'inferior debugger'.
29020 \begin_layout Itemize
29021 use an on target hardware debugger.
29022 Some of the more modern MCUs include hardware support for setting break
29023 points and monitoring/changing variables by using dedicated hardware pins.
29024 This facility doesn't require additional code to run on the target and
29029 doesn't affect runtime behaviour until a breakpoint is hit.
29030 For the mcs51 most hardware debuggers use the AOMF
29031 \begin_inset LatexCommand \index{AOMF, AOMF51}
29036 \begin_inset LatexCommand \ref{OMF file}
29044 \begin_layout Standard
29048 \begin_layout Itemize
29049 if you are not familiar with any of the following terms you're likely to
29050 run into problems rather sooner than later:
29067 As an embedded programmer you
29071 to know them so why not look them up
29075 you have problems?)
29078 \begin_layout Itemize
29079 tell someone else about your problem (actually this is a surprisingly effective
29080 means to hunt down the bug even if the listener is not familiar with your
29082 As 'failure to communicate' is probably one of the job-induced deformations
29083 of an embedded programmer this is highly encouraged.
29086 \begin_layout Section
29087 Debugging with SDCDB
29088 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
29093 \begin_inset LatexCommand \index{SDCDB (debugger)}
29100 \begin_layout Standard
29101 SDCC is distributed with a source level debugger
29102 \begin_inset LatexCommand \index{Debugger}
29107 The debugger uses a command line interface, the command repertoire of the
29108 debugger has been kept as close to gdb
29109 \begin_inset LatexCommand \index{gdb}
29113 (the GNU debugger) as possible.
29114 The configuration and build process is part of the standard compiler installati
29115 on, which also builds and installs the debugger in the target directory
29116 specified during configuration.
29117 The debugger allows you debug BOTH at the C source and at the ASM source
29121 \begin_layout Subsection
29122 Compiling for Debugging
29125 \begin_layout Standard
29130 \begin_layout Standard
29140 \begin_inset LatexCommand \index{-\/-debug}
29144 option must be specified for all files for which debug information is to
29146 The compiler generates a .adb file for each of these files.
29147 The linker creates the .cdb
29148 \begin_inset LatexCommand \index{<file>.cdb}
29153 \begin_inset LatexCommand \index{<file>.adb}
29157 files and the address information.
29158 This .cdb is used by the debugger.
29161 \begin_layout Subsection
29162 How the Debugger Works
29165 \begin_layout Standard
29170 \begin_layout Standard
29179 -debug option is specified the compiler generates extra symbol information
29180 some of which are put into the assembler source and some are put into the
29182 Then the linker creates the .cdb file from the individual .adb files with
29183 the address information for the symbols.
29184 The debugger reads the symbolic information generated by the compiler &
29185 the address information generated by the linker.
29186 It uses the SIMULATOR (Daniel's S51) to execute the program, the program
29187 execution is controlled by the debugger.
29188 When a command is issued for the debugger, it translates it into appropriate
29189 commands for the simulator.
29190 (Currently SDCDM only connects to the simulator but
29195 \begin_inset LatexCommand \url{http://ec2drv.sf.net/}
29199 is an effort to connect directly to the hardware.)
29202 \begin_layout Subsection
29203 Starting the Debugger SDCDB
29206 \begin_layout Standard
29207 The debugger can be started using the following command line.
29208 (Assume the file you are debugging has the file name foo).
29222 The debugger will look for the following files.
29225 \begin_layout Itemize
29226 foo.c - the source file.
29229 \begin_layout Itemize
29230 foo.cdb - the debugger symbol information file.
29233 \begin_layout Itemize
29234 foo.ihx - the Intel hex format
29235 \begin_inset LatexCommand \index{Intel hex format}
29242 \begin_layout Subsection
29243 SDCDB Command Line Options
29246 \begin_layout Itemize
29251 \begin_layout Standard
29260 -directory=<source file directory> this option can used to specify the directory
29262 The debugger will look into the directory list specified for source, cdb
29264 The items in the directory list must be separated by ':', e.g.
29265 if the source files can be in the directories /home/src1 and /home/src2,
29270 \begin_layout Standard
29279 -directory option should be -
29283 \begin_layout Standard
29292 -directory=/home/src1:/home/src2.
29293 Note there can be no spaces in the option.
29297 \begin_layout Itemize
29298 -cd <directory> - change to the <directory>.
29301 \begin_layout Itemize
29302 -fullname - used by GUI front ends.
29305 \begin_layout Itemize
29306 -cpu <cpu-type> - this argument is passed to the simulator please see the
29307 simulator docs for details.
29310 \begin_layout Itemize
29311 -X <Clock frequency > this options is passed to the simulator please see
29312 the simulator docs for details.
29315 \begin_layout Itemize
29316 -s <serial port file> passed to simulator see the simulator docs for details.
29319 \begin_layout Itemize
29320 -S <serial in,out> passed to simulator see the simulator docs for details.
29323 \begin_layout Itemize
29324 -k <port number> passed to simulator see the simulator docs for details.
29327 \begin_layout Subsection
29328 SDCDB Debugger Commands
29331 \begin_layout Standard
29332 As mentioned earlier the command interface for the debugger has been deliberatel
29333 y kept as close the GNU debugger gdb, as possible.
29334 This will help the integration with existing graphical user interfaces
29335 (like ddd, xxgdb or xemacs) existing for the GNU debugger.
29336 If you use a graphical user interface for the debugger you can skip this
29340 \begin_layout Subsubsection*
29341 break [line | file:line | function | file:function]
29344 \begin_layout Standard
29345 Set breakpoint at specified line or function:
29354 sdcdb>break foo.c:100
29356 sdcdb>break funcfoo
29358 sdcdb>break foo.c:funcfoo
29361 \begin_layout Subsubsection*
29362 clear [line | file:line | function | file:function ]
29365 \begin_layout Standard
29366 Clear breakpoint at specified line or function:
29375 sdcdb>clear foo.c:100
29377 sdcdb>clear funcfoo
29379 sdcdb>clear foo.c:funcfoo
29382 \begin_layout Subsubsection*
29386 \begin_layout Standard
29387 Continue program being debugged, after breakpoint.
29390 \begin_layout Subsubsection*
29394 \begin_layout Standard
29395 Execute till the end of the current function.
29398 \begin_layout Subsubsection*
29402 \begin_layout Standard
29403 Delete breakpoint number 'n'.
29404 If used without any option clear ALL user defined break points.
29407 \begin_layout Subsubsection*
29408 info [break | stack | frame | registers ]
29411 \begin_layout Itemize
29412 info break - list all breakpoints
29415 \begin_layout Itemize
29416 info stack - show the function call stack.
29419 \begin_layout Itemize
29420 info frame - show information about the current execution frame.
29423 \begin_layout Itemize
29424 info registers - show content of all registers.
29427 \begin_layout Subsubsection*
29431 \begin_layout Standard
29432 Step program until it reaches a different source line.
29433 Note: pressing <return> repeats the last command.
29436 \begin_layout Subsubsection*
29440 \begin_layout Standard
29441 Step program, proceeding through subroutine calls.
29444 \begin_layout Subsubsection*
29448 \begin_layout Standard
29449 Start debugged program.
29452 \begin_layout Subsubsection*
29456 \begin_layout Standard
29457 Print type information of the variable.
29460 \begin_layout Subsubsection*
29464 \begin_layout Standard
29465 print value of variable.
29468 \begin_layout Subsubsection*
29472 \begin_layout Standard
29473 load the given file name.
29474 Note this is an alternate method of loading file for debugging.
29477 \begin_layout Subsubsection*
29481 \begin_layout Standard
29482 print information about current frame.
29485 \begin_layout Subsubsection*
29489 \begin_layout Standard
29490 Toggle between C source & assembly source.
29493 \begin_layout Subsubsection*
29494 ! simulator command
29497 \begin_layout Standard
29498 Send the string following '!' to the simulator, the simulator response is
29500 Note the debugger does not interpret the command being sent to the simulator,
29501 so if a command like 'go' is sent the debugger can loose its execution
29502 context and may display incorrect values.
29505 \begin_layout Subsubsection*
29509 \begin_layout Standard
29512 My name is Bobby Brown"
29515 \begin_layout Subsection
29516 Interfacing SDCDB with DDD
29519 \begin_layout Standard
29520 \begin_inset Note Note
29523 \begin_layout Standard
29524 The screenshot was converted from png to eps with:
29525 \begin_inset Quotes sld
29528 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
29529 \begin_inset Quotes srd
29532 which produces a pretty compact eps file which is free from compression
29536 \begin_layout Standard
29537 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
29538 as this broke the build system on Sourceforge (pdf-file was broken.
29539 pdflatex does not accept eps files).
29547 \begin_layout Standard
29563 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png}
29569 shows a screenshot of a debugging session with DDD
29570 \begin_inset LatexCommand \index{DDD (debugger)}
29574 (Unix only) on a simulated 8032.
29575 The debugging session might not run as smoothly as the screenshot suggests.
29576 The debugger allows setting of breakpoints, displaying and changing variables,
29577 single stepping through C and assembler code.
29580 The source was compiled with
29594 \begin_layout Standard
29606 -debug ddd_example.c
29619 and DDD was invoked with
29626 ddd -debugger "sdcdb -cpu 8032 ddd_example"
29629 \begin_layout Standard
29630 \begin_inset Note Note
29633 \begin_layout Standard
29634 Check that the double quotes or an apostroph within the command line survive
29635 the LyX tool chain.
29636 Previously the apostrophs got slanted in the PDF output so a cut and paste
29645 \begin_layout Subsection
29646 Interfacing SDCDB with XEmacs
29647 \begin_inset LatexCommand \index{XEmacs}
29652 \begin_inset LatexCommand \index{Emacs}
29659 \begin_layout Standard
29660 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
29661 sdcdb.el and sdcdbsrc.el.
29662 These two files can be found in the $(prefix)/bin directory after the installat
29664 These files need to be loaded into XEmacs for the interface to work.
29665 This can be done at XEmacs startup time by inserting the following into
29666 your '.xemacs' file (which can be found in your HOME directory):
29672 (load-file sdcdbsrc.el)
29678 .xemacs is a lisp file so the () around the command is REQUIRED.
29679 The files can also be loaded dynamically while XEmacs is running, set the
29680 environment variable 'EMACSLOADPATH' to the installation bin directory
29681 (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
29682 To start the interface enter the following command:
29696 You will prompted to enter the file name to be debugged.
29701 The command line options that are passed to the simulator directly are
29702 bound to default values in the file sdcdbsrc.el.
29703 The variables are listed below, these values maybe changed as required.
29706 \begin_layout Itemize
29707 sdcdbsrc-cpu-type '51
29710 \begin_layout Itemize
29711 sdcdbsrc-frequency '11059200
29714 \begin_layout Itemize
29715 sdcdbsrc-serial nil
29718 \begin_layout Standard
29719 The following is a list of key mapping for the debugger interface.
29722 \begin_layout Standard
29745 binding\InsetSpace ~
29783 -------\InsetSpace ~
29854 sdcdb-back-from-src\InsetSpace ~
29883 rom-src\InsetSpace ~
29893 SDCDB continue command
29911 sdcdb-step-from-src\InsetSpace ~
29940 hatis-c-sexp\InsetSpace ~
29950 SDCDB ptypecommand for data at
30017 sdcdbsrc-delete\InsetSpace ~
30032 B Delete all breakpoints if no arg
30081 given or delete arg (C-u arg x)
30100 -frame\InsetSpace ~
30115 SDCDB Display current frame if no arg,
30164 given or display frame arg
30232 sdcdbsrc-goto-sdcdb\InsetSpace ~
30242 Goto the SDCDB output buffer
30261 t-c-sexp\InsetSpace ~
30272 SDCDB print command for data at
30339 sdcdbsrc-goto-sdcdb\InsetSpace ~
30350 o the SDCDB output buffer
30368 sdcdbsrc-mode\InsetSpace ~
30384 Toggles Sdcdbsrc mode (turns it
30400 sdcdb-finish-from-src\InsetSpace ~
30408 SDCDB finish command
30442 Set break for line with point
30457 sdcdbsrc-mode\InsetSpace ~
30473 Toggle Sdcdbsrc mode
30489 dbsrc-srcmode\InsetSpace ~
30513 \begin_layout Chapter
30517 \begin_layout Standard
30518 Here are a few guidelines that will help the compiler generate more efficient
30519 code, some of the tips are specific to this compiler others are generally
30520 good programming practice.
30523 \begin_layout Itemize
30524 Use the smallest data type to represent your data-value.
30525 If it is known in advance that the value is going to be less than 256 then
30526 use an 'unsigned char' instead of a 'short' or 'int'.
30527 Please note, that ANSI C requires both signed and unsigned chars to be
30528 promoted to 'signed int'
30529 \begin_inset LatexCommand \index{promotion to signed int}
30534 \begin_inset Marginal
30537 \begin_layout Standard
30546 before doing any operation.
30548 \begin_inset LatexCommand \index{type promotion}
30553 \begin_inset LatexCommand \label{type promotion}
30557 can be omitted, if the result is the same.
30558 The effect of the promotion rules together with the sign-extension is often
30563 \begin_layout Verse
30566 unsigned char uc = 0xfe;
30568 if (uc * uc < 0) /* this is true! */
30581 \begin_layout Standard
30588 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
30596 \begin_layout Verse
30599 (unsigned char) -12 / (signed char) -3 = ...
30602 \begin_layout Standard
30603 No, the result is not 4:
30606 \begin_layout Verse
30609 (int) (unsigned char) -12 / (int) (signed char) -3 =
30611 (int) (unsigned char)
30612 0xf4 / (int) (signed char) 0xfd =
30614 (int) 0x00f4 / (int) 0xfffd =
30619 (int) 244 / (int) -3 =
30621 (int) -81 = (int) 0xffaf;
30624 \begin_layout Standard
30625 Don't complain, that gcc gives you a different result.
30626 gcc uses 32 bit ints, while SDCC uses 16 bit ints.
30627 Therefore the results are different.
30630 \begin_inset Quotes sld
30634 \begin_inset Quotes srd
30640 \begin_layout Quote
30643 If well-defined overflow characteristics are important and negative values
30644 are not, or if you want to steer clear of sign-extension problems when
30645 manipulating bits or bytes, use one of the corresponding unsigned types.
30646 (Beware when mixing signed and unsigned values in expressions, though.)
30649 character types (especially unsigned char) can be used as "tiny" integers,
30650 doing so is sometimes more trouble than it's worth, due to unpredictable
30651 sign extension and increased code size.
30655 \begin_layout Itemize
30656 Use unsigned when it is known in advance that the value is not going to
30658 This helps especially if you are doing division or multiplication, bit-shifting
30659 or are using an array index.
30662 \begin_layout Itemize
30663 NEVER jump into a LOOP.
30666 \begin_layout Itemize
30667 Declare the variables to be local
30668 \begin_inset LatexCommand \index{local variables}
30672 whenever possible, especially loop control variables (induction).
30675 \begin_layout Itemize
30676 Have a look at the assembly listing to get a
30677 \begin_inset Quotes sld
30681 \begin_inset Quotes srd
30684 for the code generation.
30687 \begin_layout Section
30688 Porting code from or to other compilers
30689 \begin_inset LatexCommand \label{sec:Porting-code-to-other-compilers}
30696 \begin_layout Itemize
30697 check whether endianness of the compilers differs and adapt where needed.
30700 \begin_layout Itemize
30701 check the device specific header files
30702 \begin_inset LatexCommand \index{Header files}
30707 \begin_inset LatexCommand \index{Include files}
30711 for compiler specific syntax.
30712 Eventually include the file <compiler.h
30713 \begin_inset LatexCommand \index{compiler.h (include file)}
30718 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/compiler.h?view=markup}
30722 to allow using common header files.
30725 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/cc2510fx.h?view=markup}
30732 \begin_layout Itemize
30733 check whether the startup code contains the correct initialization (watchdog,
30737 \begin_layout Itemize
30738 check whether the sizes of short, int, long match.
30741 \begin_layout Itemize
30742 check if some 16 or 32 bit hardware registers require a specific addressing
30743 order (least significant or most significant byte first) and adapt if needed
30752 relate to time and not to lower/upper memory location here, so this is
30757 the same as endianness).
30760 \begin_layout Itemize
30761 check whether the keyword
30765 is used where needed.
30766 The compilers might differ in their optimization characteristics (as different
30767 versions of the same compiler might also use more clever optimizations
30768 this is good idea anyway).
30770 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
30777 \begin_layout Itemize
30778 check that the compilers are not told to supress warnings.
30781 \begin_layout Itemize
30782 check and convert compiler specific extensions (interrupts, memory areas,
30786 \begin_layout Itemize
30787 check for differences in type promotion.
30788 Especially check for math operations on
30797 For the sake of C99 compatibility SDCC will probably promote these to
30801 more often than other compilers.
30802 Eventually insert explicit casts to
30811 Also check that the ~\InsetSpace ~
30813 \begin_inset LatexCommand \index{\~\/ Operator}
30820 \begin_inset LatexCommand \index{bit}
30826 variables, use the !\InsetSpace ~
30829 \begin_inset LatexCommand \ref{type promotion}
30834 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
30841 \begin_layout Itemize
30842 check the assembly code generated for interrupt routines (f.e.
30843 for calls to possibly non-reentrant library functions).
30846 \begin_layout Itemize
30847 check whether timing loops result in proper timing (or preferably consider
30848 a rewrite of the code with timer based delays instead).
30851 \begin_layout Itemize
30852 check for differences in printf parameters (some compilers push (va_arg
30853 \begin_inset LatexCommand \index{vararg, va\_arg}
30857 ) char variables as
30861 others push them as
30867 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
30874 \begin_layout Itemize
30875 check the resulting memory map
30876 \begin_inset LatexCommand \index{Memory map}
30881 Usage of different memory spaces: code, stack, data (for mcs51/ds390 additional
30882 ly idata, pdata, xdata).
30883 Eventually check if unexpected library functions are included.
30886 \begin_layout Section
30888 \begin_inset LatexCommand \index{Tools}
30892 included in the distribution
30895 \begin_layout Standard
30897 \begin_inset Tabular
30898 <lyxtabular version="3" rows="12" columns="3">
30900 <column alignment="left" valignment="top" leftline="true" width="0pt">
30901 <column alignment="left" valignment="top" leftline="true" width="0pt">
30902 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
30903 <row topline="true" bottomline="true">
30904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30907 \begin_layout Standard
30915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30918 \begin_layout Standard
30926 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30929 \begin_layout Standard
30938 <row topline="true">
30939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30942 \begin_layout Standard
30944 \begin_inset LatexCommand \index{uCsim}
30953 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30956 \begin_layout Standard
30957 Simulator for various architectures
30962 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30965 \begin_layout Standard
30972 <row topline="true">
30973 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30976 \begin_layout Standard
30982 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30985 \begin_layout Standard
30987 \begin_inset LatexCommand \index{Header files}
30992 \begin_inset LatexCommand \index{Include files}
31001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31004 \begin_layout Standard
31005 sdcc/support/scripts
31011 <row topline="true">
31012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31015 \begin_layout Standard
31021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31024 \begin_layout Standard
31025 header file conversion
31030 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31033 \begin_layout Standard
31034 sdcc/support/scripts
31040 <row topline="true">
31041 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31044 \begin_layout Standard
31050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31053 \begin_layout Standard
31059 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31062 \begin_layout Standard
31078 <row topline="true">
31079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31082 \begin_layout Standard
31088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31091 \begin_layout Standard
31097 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31100 \begin_layout Standard
31116 <row topline="true">
31117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31120 \begin_layout Standard
31126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31129 \begin_layout Standard
31135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31138 \begin_layout Standard
31154 <row topline="true">
31155 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31158 \begin_layout Standard
31164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31167 \begin_layout Standard
31173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31176 \begin_layout Standard
31192 <row topline="true">
31193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31196 \begin_layout Standard
31202 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31205 \begin_layout Standard
31211 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31214 \begin_layout Standard
31230 <row topline="true">
31231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31234 \begin_layout Standard
31240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31243 \begin_layout Standard
31249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31252 \begin_layout Standard
31268 <row topline="true">
31269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31272 \begin_layout Standard
31278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31281 \begin_layout Standard
31287 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31290 \begin_layout Standard
31306 <row topline="true" bottomline="true">
31307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31310 \begin_layout Standard
31316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31319 \begin_layout Standard
31321 \begin_inset LatexCommand \index{packihx (tool)}
31330 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31333 \begin_layout Standard
31358 \begin_layout Section
31360 \begin_inset LatexCommand \index{Documentation}
31364 included in the distribution
31367 \begin_layout Standard
31369 \begin_inset Tabular
31370 <lyxtabular version="3" rows="10" columns="2">
31372 <column alignment="block" valignment="top" leftline="true" width="40col%">
31373 <column alignment="block" valignment="top" leftline="true" rightline="true" width="60col%">
31374 <row topline="true" bottomline="true" endhead="true">
31375 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31378 \begin_layout Standard
31386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31389 \begin_layout Standard
31392 Filename / Where to get
31398 <row topline="true">
31399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31402 \begin_layout Standard
31403 SDCC Compiler User Guide
31408 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31411 \begin_layout Standard
31412 You're reading it right now
31424 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
31434 <row topline="true">
31435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31438 \begin_layout Standard
31444 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31447 \begin_layout Standard
31460 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/ChangeLog}
31470 <row topline="true">
31471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31474 \begin_layout Standard
31476 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
31481 \begin_inset LatexCommand \index{Assembler documentation}
31488 \begin_inset LatexCommand \index{aslink}
31493 \begin_inset LatexCommand \index{Linker documentation}
31502 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31505 \begin_layout Standard
31506 sdcc/as/doc/asxhtm.html
31518 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html}
31528 <row topline="true">
31529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31532 \begin_layout Standard
31533 SDCC regression test
31534 \begin_inset LatexCommand \index{Regression test}
31543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31546 \begin_layout Standard
31547 sdcc/doc/test_suite_spec.pdf
31559 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf}
31569 <row topline="true">
31570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31573 \begin_layout Standard
31579 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31582 \begin_layout Standard
31595 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/doc/}
31605 <row topline="true">
31606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31609 \begin_layout Standard
31610 Notes on debugging with SDCDB
31611 \begin_inset LatexCommand \index{SDCDB (debugger)}
31620 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31623 \begin_layout Standard
31624 sdcc/debugger/README
31636 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/debugger/README}
31646 <row topline="true">
31647 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31650 \begin_layout Standard
31652 \begin_inset LatexCommand \index{uCsim}
31656 Software simulator for microcontrollers
31661 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31664 \begin_layout Standard
31694 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/sim/ucsim/doc/index.html}
31704 <row topline="true">
31705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31708 \begin_layout Standard
31709 Temporary notes on the pic16
31710 \begin_inset LatexCommand \index{PIC16}
31719 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31722 \begin_layout Standard
31723 sdcc/src/pic16/NOTES
31735 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/src/pic16/NOTES}
31745 <row topline="true" bottomline="true">
31746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31749 \begin_layout Standard
31750 SDCC internal documentation (debugging file format)
31755 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31758 \begin_layout Standard
31788 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/cdbfileformat.pdf}
31807 \begin_layout Section
31808 Related open source tools
31809 \begin_inset LatexCommand \label{sec:Related-open-source-tools}
31814 \begin_inset LatexCommand \index{Related tools}
31821 \begin_layout Standard
31823 \begin_inset Tabular
31824 <lyxtabular version="3" rows="16" columns="3">
31826 <column alignment="left" valignment="top" leftline="true" width="0pt">
31827 <column alignment="block" valignment="top" leftline="true" width="30line%">
31828 <column alignment="left" valignment="top" leftline="true" rightline="true" width="40col%">
31829 <row topline="true" bottomline="true">
31830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31833 \begin_layout Standard
31841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31844 \begin_layout Standard
31852 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31855 \begin_layout Standard
31864 <row topline="true">
31865 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31868 \begin_layout Standard
31870 \begin_inset LatexCommand \index{gpsim (pic simulator)}
31879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31882 \begin_layout Standard
31888 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31891 \begin_layout Standard
31892 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
31902 <row topline="true">
31903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31906 \begin_layout Standard
31908 \begin_inset LatexCommand \index{gputils (pic tools)}
31917 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31920 \begin_layout Standard
31926 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31929 \begin_layout Standard
31930 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
31940 <row topline="true">
31941 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31944 \begin_layout Standard
31950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31953 \begin_layout Standard
31959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31962 \begin_layout Standard
31963 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
31973 <row topline="true">
31974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31977 \begin_layout Standard
31983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31986 \begin_layout Standard
31987 Tools for Silicon Laboratories JTAG debug adapter, partly based on SDCDB
31993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31996 \begin_layout Standard
31997 \begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
32007 <row topline="true">
32008 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32011 \begin_layout Standard
32013 \begin_inset LatexCommand \index{indent (source formatting tool)}
32022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32025 \begin_layout Standard
32026 Formats C source - Master of the white spaces
32031 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32034 \begin_layout Standard
32035 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
32045 <row topline="true">
32046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32049 \begin_layout Standard
32051 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
32060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32063 \begin_layout Standard
32064 Object file conversion, checksumming, ...
32069 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32072 \begin_layout Standard
32073 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
32083 <row topline="true">
32084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32087 \begin_layout Standard
32089 \begin_inset LatexCommand \index{objdump (tool)}
32098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32101 \begin_layout Standard
32102 Object file conversion, ...
32107 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32110 \begin_layout Standard
32111 Part of binutils (should be there anyway)
32117 <row topline="true">
32118 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32121 \begin_layout Standard
32127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32130 \begin_layout Standard
32131 8051 monitor (hex up-/download, single step, disassemble)
32136 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32139 \begin_layout Standard
32140 \begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51}
32150 <row topline="true">
32151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32154 \begin_layout Standard
32156 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
32165 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32168 \begin_layout Standard
32169 Source code documentation system
32174 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32177 \begin_layout Standard
32178 \begin_inset LatexCommand \url{http://www.doxygen.org}
32188 <row topline="true">
32189 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32192 \begin_layout Standard
32198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32201 \begin_layout Standard
32202 IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
32207 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32210 \begin_layout Standard
32211 \begin_inset LatexCommand \url{http://www.kdevelop.org}
32221 <row topline="true">
32222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32225 \begin_layout Standard
32231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32234 \begin_layout Standard
32235 8051 monitor (hex up-/download, single step, disassemble)
32240 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32243 \begin_layout Standard
32244 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
32254 <row topline="true">
32255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32258 \begin_layout Standard
32260 \begin_inset LatexCommand \index{splint (syntax checking tool)}
32269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32272 \begin_layout Standard
32273 Statically checks c sources (see
32274 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
32283 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32286 \begin_layout Standard
32287 \begin_inset LatexCommand \url{http://www.splint.org}
32297 <row topline="true" bottomline="true">
32298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32301 \begin_layout Standard
32303 \begin_inset LatexCommand \index{DDD (debugger)}
32312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32315 \begin_layout Standard
32316 Debugger, serves nicely as GUI to SDCDB
32317 \begin_inset LatexCommand \index{SDCDB (debugger)}
32326 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32329 \begin_layout Standard
32330 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
32340 <row bottomline="true">
32341 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32344 \begin_layout Standard
32346 \begin_inset LatexCommand \index{d52}
32351 \begin_inset LatexCommand \index{d52 (disassembler)}
32360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32363 \begin_layout Standard
32364 Disassembler, can count instruction cycles
32365 \begin_inset LatexCommand \index{instruction cycles (count)}
32369 , use with options -pnd
32374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32377 \begin_layout Standard
32378 \begin_inset LatexCommand \url{http://www.8052.com/users/disasm/}
32388 <row bottomline="true">
32389 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32392 \begin_layout Standard
32394 \begin_inset LatexCommand \index{cmake}
32403 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32406 \begin_layout Standard
32407 Cross platform build system, generates Makefiles
32408 \begin_inset LatexCommand \index{Makefile}
32412 and project workspaces
32413 \begin_inset LatexCommand \index{project workspace}
32422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32425 \begin_layout Standard
32426 \begin_inset LatexCommand \url{http://www.cmake.org}
32434 and a dedicated wiki entry:
32435 \begin_inset LatexCommand \url{http://www.cmake.org/Wiki/CmakeSdcc}
32454 \begin_layout Section
32455 Related documentation / recommended reading
32458 \begin_layout Standard
32460 \begin_inset Tabular
32461 <lyxtabular version="3" rows="7" columns="3">
32463 <column alignment="left" valignment="top" leftline="true" width="0pt">
32464 <column alignment="left" valignment="top" leftline="true" width="0">
32465 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
32466 <row topline="true" bottomline="true">
32467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32470 \begin_layout Standard
32478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32481 \begin_layout Standard
32489 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32492 \begin_layout Standard
32501 <row topline="true">
32502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32505 \begin_layout Standard
32520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32523 \begin_layout Standard
32525 \begin_inset LatexCommand \index{C Reference card}
32534 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32537 \begin_layout Standard
32538 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
32548 <row topline="true">
32549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32552 \begin_layout Standard
32558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32561 \begin_layout Standard
32563 \begin_inset LatexCommand \index{C FAQ}
32572 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32575 \begin_layout Standard
32576 \begin_inset LatexCommand \url{http://www.c-faq.com}
32586 <row topline="true">
32587 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32590 \begin_layout Standard
32596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32599 \begin_layout Standard
32600 \begin_inset Quotes sld
32604 \begin_inset Quotes srd
32612 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32615 \begin_layout Standard
32618 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
32628 <row topline="true">
32629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32632 \begin_layout Standard
32638 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32641 \begin_layout Standard
32642 \begin_inset Quotes sld
32645 Extensions for Embedded C
32646 \begin_inset Quotes srd
32654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32657 \begin_layout Standard
32660 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf}
32670 <row topline="true">
32671 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32674 \begin_layout Standard
32680 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32683 \begin_layout Standard
32684 Latest datasheet of target CPU
32689 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32692 \begin_layout Standard
32699 <row topline="true" bottomline="true">
32700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32703 \begin_layout Standard
32709 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32712 \begin_layout Standard
32713 Revision history of datasheet
32718 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32721 \begin_layout Standard
32737 \begin_layout Section
32738 Application notes specifically for SDCC
32741 \begin_layout Standard
32742 SDCC makes no claims about the completeness of this list and about up-to-datenes
32743 s or correctness of the application notes
32744 \begin_inset LatexCommand \index{Application notes}
32751 \begin_layout Standard
32755 \begin_inset Tabular
32756 <lyxtabular version="3" rows="7" columns="3">
32758 <column alignment="block" valignment="top" leftline="true" width="17col%">
32759 <column alignment="block" valignment="top" leftline="true" width="27col%">
32760 <column alignment="block" valignment="top" leftline="true" rightline="true" width="57col%">
32761 <row topline="true" bottomline="true">
32762 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32765 \begin_layout Standard
32774 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
32777 \begin_layout Standard
32786 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32789 \begin_layout Standard
32799 <row topline="true">
32800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32803 \begin_layout Standard
32811 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32814 \begin_layout Standard
32817 Using the SDCC Compiler for the DS80C400
32818 \begin_inset LatexCommand \index{DS80C400}
32827 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32830 \begin_layout Standard
32833 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3346.pdf}
32843 <row topline="true">
32844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32847 \begin_layout Standard
32855 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none" width="30line%">
32858 \begin_layout Standard
32861 Using the Free SDCC C Compiler to Develop Firmware for the DS89C420/430/440/450
32862 \begin_inset LatexCommand \index{DS89C4x0}
32866 Family of Microcontrollers
32871 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32874 \begin_layout Standard
32877 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3477.pdf}
32887 <row topline="true">
32888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32891 \begin_layout Standard
32894 Silicon Laboratories / Cygnal
32899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32902 \begin_layout Standard
32905 Integrating SDCC 8051 Tools Into The Silicon Labs IDE
32906 \begin_inset LatexCommand \index{IDE}
32915 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32918 \begin_layout Standard
32921 \begin_inset LatexCommand \url{http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/en/an198.pdf}
32931 <row topline="true">
32932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32935 \begin_layout Standard
32938 Ramtron / Goal Semiconductor
32943 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32946 \begin_layout Standard
32949 Interfacing SDCC to Syn and Textpad
32954 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32957 \begin_layout Standard
32960 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
32970 <row topline="true">
32971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32974 \begin_layout Standard
32977 Ramtron / Goal Semiconductor
32982 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32985 \begin_layout Standard
32988 Installing and Configuring SDCC and Crimson Editor
32993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32996 \begin_layout Standard
32999 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
33009 <row topline="true" bottomline="true">
33010 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33013 \begin_layout Standard
33021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33024 \begin_layout Standard
33027 MSC12xx Programming with SDCC
33032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33035 \begin_layout Standard
33038 \begin_inset LatexCommand \url{http://focus.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=sbaa109&fileType=pdf}
33055 \begin_layout Section
33059 \begin_layout Standard
33060 Some questions answered, some pointers given - it might be time to in turn
33068 \begin_layout Itemize
33069 can you solve your project with the selected microcontroller? Would you
33070 find out early or rather late that your target is too small/slow/whatever?
33071 Can you switch to a slightly better device if it doesn't fit?
33074 \begin_layout Itemize
33075 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
33076 and/or another programming language be more adequate? Would an operating
33077 system on the target device help?
33080 \begin_layout Itemize
33081 if you solved the problem, will the marketing department be happy?
33084 \begin_layout Itemize
33085 if the marketing department is happy, will customers be happy?
33088 \begin_layout Itemize
33089 if you're the project manager, marketing department and maybe even the customer
33090 in one person, have you tried to see the project from the outside?
33093 \begin_layout Itemize
33094 is the project done if you think it is done? Or is just that other interface/pro
33095 tocol/feature/configuration/option missing? How about website, manual(s),
33096 internationali(z|s)ation, packaging, labels, 2nd source for components,
33097 electromagnetic compatability/interference, documentation for production,
33098 production test software, update mechanism, patent issues?
33101 \begin_layout Itemize
33102 is your project adequately positioned in that magic triangle: fame, fortune,
33106 \begin_layout Standard
33107 Maybe not all answers to these questions are known and some answers may
33112 , nevertheless knowing these questions may help you to avoid burnout
33116 \begin_layout Standard
33117 burnout is bad for electronic devices, programmers and motorcycle tyres
33123 Chances are you didn't want to hear some of them...
33126 \begin_layout Chapter
33128 \begin_inset LatexCommand \index{Support}
33135 \begin_layout Standard
33136 SDCC has grown to be a large project.
33137 The compiler alone (without the preprocessor, assembler and linker) is
33138 well over 150,000 lines of code (blank stripped).
33139 The open source nature of this project is a key to its continued growth
33141 You gain the benefit and support of many active software developers and
33143 Is SDCC perfect? No, that's why we need your help.
33144 The developers take pride in fixing reported bugs.
33145 You can help by reporting the bugs and helping other SDCC users.
33146 There are lots of ways to contribute, and we encourage you to take part
33147 in making SDCC a great software package.
33151 \begin_layout Standard
33152 The SDCC project is hosted on the SDCC sourceforge site at
33153 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
33158 You'll find the complete set of mailing lists
33159 \begin_inset LatexCommand \index{Mailing list(s)}
33163 , forums, bug reporting system, patch submission
33164 \begin_inset LatexCommand \index{Patch submission}
33169 \begin_inset LatexCommand \index{download}
33173 area and Subversion code repository
33174 \begin_inset LatexCommand \index{Subversion code repository}
33181 \begin_layout Section
33183 \begin_inset LatexCommand \index{Bug reporting}
33188 \begin_inset LatexCommand \index{Reporting bugs}
33195 \begin_layout Standard
33196 The recommended way of reporting bugs is using the infrastructure of the
33198 You can follow the status of bug reports there and have an overview about
33202 \begin_layout Standard
33203 Bug reports are automatically forwarded to the developer mailing list and
33204 will be fixed ASAP.
33205 When reporting a bug, it is very useful to include a small test program
33206 (the smaller the better) which reproduces the problem.
33207 If you can isolate the problem by looking at the generated assembly code,
33208 this can be very helpful.
33209 Compiling your program with the -
33213 \begin_layout Standard
33223 \begin_inset LatexCommand \index{-\/-dumpall}
33227 option can sometimes be useful in locating optimization problems.
33228 When reporting a bug please make sure you:
33231 \begin_layout Enumerate
33232 Attach the code you are compiling with SDCC.
33236 \begin_layout Enumerate
33237 Specify the exact command you use to run SDCC, or attach your Makefile.
33241 \begin_layout Enumerate
33242 Specify the SDCC version (type "
33248 "), your platform, and operating system.
33252 \begin_layout Enumerate
33253 Provide an exact copy of any error message or incorrect output.
33257 \begin_layout Enumerate
33258 Put something meaningful in the subject of your message.
33261 \begin_layout Standard
33262 Please attempt to include these 5 important parts, as applicable, in all
33263 requests for support or when reporting any problems or bugs with SDCC.
33264 Though this will make your message lengthy, it will greatly improve your
33265 chance that SDCC users and developers will be able to help you.
33266 Some SDCC developers are frustrated by bug reports without code provided
33267 that they can use to reproduce and ultimately fix the problem, so please
33268 be sure to provide sample code if you are reporting a bug!
33271 \begin_layout Standard
33272 Please have a short check that you are using a recent version of SDCC and
33273 the bug is not yet known.
33274 This is the link for reporting bugs:
33275 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
33280 With SDCC on average having more than 200 downloads
33281 \begin_inset LatexCommand \index{download}
33285 on sourceforge per day
33289 \begin_layout Standard
33290 220 daily downloads on average Jan-Sept 2006 and about 150 daily downloads
33291 between 2002 and 2005.
33292 This does not include other methods of distribution.
33297 there must be some users.
33298 So it's not exactly easy to find a new bug.
33299 If you find one we need it:
33301 reporting bugs is good
33306 \begin_layout Section
33307 Requesting Features
33308 \begin_inset LatexCommand \label{sub:Requesting-Features}
33313 \begin_inset LatexCommand \index{Feature request}
33318 \begin_inset LatexCommand \index{Requesting features}
33325 \begin_layout Standard
33326 Like bug reports feature requests are forwarded to the developer mailing
33328 This is the link for requesting features:
33329 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
33336 \begin_layout Section
33340 \begin_layout Standard
33341 Like bug reports contributed patches are forwarded to the developer mailing
33343 This is the link for submitting patches
33344 \begin_inset LatexCommand \index{Patch submission}
33349 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
33356 \begin_layout Standard
33357 You need to specify some parameters to the
33361 command for the patches to be useful.
33362 If you modified more than one file a patch created f.e.
33367 \begin_inset Quotes sld
33370 diff -Naur unmodified_directory modified_directory >my_changes.patch
33371 \begin_inset Quotes srd
33377 will be fine, otherwise
33381 \begin_inset Quotes sld
33384 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
33385 \begin_inset Quotes srd
33395 \begin_layout Section
33399 \begin_layout Standard
33400 These links should take you directly to the
33401 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
33409 \begin_layout Standard
33410 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
33411 automated messages (mid 2003)
33417 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
33422 \begin_inset LatexCommand \index{Mailing list(s)}
33426 and forums are archived and searchable so if you are lucky someone already
33427 had a similar problem.
33428 While mails to the lists themselves are delivered promptly their web front
33429 end on sourceforge sometimes shows a severe time lag (up to several weeks),
33430 if you're seriously using SDCC please consider subscribing to the lists.
33433 \begin_layout Section
33437 \begin_layout Standard
33438 You can follow the status of the Subversion version
33439 \begin_inset LatexCommand \index{version}
33443 of SDCC by watching the Changelog
33444 \begin_inset LatexCommand \index{Changelog}
33448 in the Subversion repository
33451 \begin_inset LatexCommand \htmlurl{http://sdcc.svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
33458 \begin_layout Section
33459 Subversion Source Code Repository
33462 \begin_layout Standard
33472 \begin_layout Standard
33486 or the filenames of the snapshot versions of SDCC include date and its
33488 \begin_inset LatexCommand \index{Subversion code repository}
33493 Subversion allows to download the source of recent or previous versions
33495 \begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599}
33499 (by number or by date).
33500 An on-line source code browser and detailled instructions are also available
33502 SDCC versions starting from 1999 up to now are available (currently the
33503 versions prior to the conversion from cvs
33504 \begin_inset LatexCommand \index{cvs|see{Subversion}}
33508 to Subversion (April 2006) are either by accessible by Subversion or by
33512 \begin_layout Section
33514 \begin_inset LatexCommand \index{Release policy}
33521 \begin_layout Standard
33522 Historically there often were long delays between official releases and
33523 the sourceforge download area tends to get not updated at all.
33524 Excuses in the past might have referred to problems with live range analysis,
33525 but as this was fixed a while ago, the current problem is that another
33526 excuse has to be found.
33527 Kidding aside, we have to get better there! On the other hand there are
33528 daily snapshots available at
33529 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
33533 , and you can always build the very last version (hopefully with many bugs
33534 fixed, and features added) from the source code available at
33535 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
33541 \begin_inset LatexCommand \index{wiki}
33546 \begin_inset LatexCommand \index{SDCC Wiki}
33551 \begin_inset LatexCommand \url{http://sdcc.wiki.sourceforge.net/}
33555 also holds some information about past and future releases.
33558 \begin_layout Section
33560 \begin_inset LatexCommand \index{Examples}
33567 \begin_layout Standard
33568 You'll find some small examples in the directory
33570 sdcc/device/examples/.
33573 More examples and libraries are available at
33575 The SDCC Open Knowledge Resource
33576 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
33583 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
33590 \begin_layout Standard
33591 \begin_inset Note Note
33594 \begin_layout Standard
33595 I did insert a reference to Paul's web site here although it seems rather
33596 dedicated to a specific 8032 board (I think it's okay because it f.e.
33597 shows LCD/Harddisc interface and has a free 8051 monitor.
33598 Independent 8032 board vendors face hard competition of heavily subsidized
33599 development boards anyway).
33602 \begin_layout Standard
33603 Maybe we should include some links to real world applications.
33604 Preferably pointer to pointers (one for each architecture) so this stays
33613 \begin_layout Section
33615 \begin_inset LatexCommand \label{sec:Quality-control}
33620 \begin_inset LatexCommand \index{Quality control}
33627 \begin_layout Standard
33628 The compiler is passed through snaphot build compile and build checks.
33634 \begin_inset LatexCommand \index{Regression test}
33638 check that SDCC itself compiles flawlessly on several host platforms (i386,
33639 Opteron, 64 bit Alpha, ppc64, Mac OS X on ppc and i386, Solaris on Sparc)
33640 and checks the quality of the code generated by SDCC by running the code
33641 for several target platforms through simulators.
33642 The regression test suite comprises more than 100 files which expand to
33643 more than 500 test cases which include more than 4500 tests.
33644 The results of these tests are published daily on SDCC's snapshot page
33645 (click on the red or green symbols on the right side of
33646 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
33653 \begin_layout Standard
33654 There is a separate document
33657 \begin_inset LatexCommand \index{Test suite}
33664 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf}
33668 about the regression test suite.
33671 \begin_layout Standard
33672 You'll find the test code in the directory
33674 sdcc/support/regression
33677 You can run these tests manually by running
33681 in this directory (or f.e.
33686 \begin_inset Quotes sld
33690 \begin_inset Quotes srd
33696 if you don't want to run the complete tests).
33697 The test code might also be interesting if you want to look for examples
33698 \begin_inset LatexCommand \index{Examples}
33702 checking corner cases of SDCC or if you plan to submit patches
33703 \begin_inset LatexCommand \index{Patch submission}
33710 \begin_layout Standard
33711 The PIC14 port uses a different set of regression tests
33712 \begin_inset LatexCommand \index{Regression test (PIC14)}
33716 , you'll find them in the directory
33718 sdcc/src/regression
33723 \begin_layout Section
33724 Use of SDCC in Education
33727 \begin_layout Standard
33736 \begin_layout Standard
33737 the phrase "use in education" might evoke the association "
33741 fit for use in education".
33742 This connotation is not intended but nevertheless risked as the licensing
33743 of SDCC makes it difficult to offer educational discounts
33749 If your rationales are to:
33752 \begin_layout Enumerate
33753 give students a chance to understand the
33757 steps of code generation
33760 \begin_layout Enumerate
33761 have a curriculum that can be extended for years.
33762 Then you could use an fpga board as target and your curriculum will seamlessly
33763 extend from logic synthesis (
33764 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
33769 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
33773 ), over assembly programming, to C to FPGA compilers (
33774 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
33781 \begin_layout Enumerate
33782 be able to insert excursions about skills like using a revision control
33783 system, submitting/applying patches, using a type-setting (as opposed to
33784 word-processing) engine LyX/LaTeX, using
33785 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
33790 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
33794 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
33795 Source Software, CPU simulation, compiler regression tests
33796 \begin_inset LatexCommand \index{Regression test}
33803 And if there should be a shortage of ideas then you can always point students
33804 to the ever-growing feature request list
33805 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
33812 \begin_layout Enumerate
33813 not tie students to a specific host platform and instead allow them to use
33818 choice (among them Alpha, i386, i386_64, Mac OS X, Mips, Sparc, Windows
33820 \begin_inset LatexCommand \url[OLPC]{http://www.laptop.org}
33827 \begin_layout Enumerate
33828 not encourage students to use illegal copies of educational software
33831 \begin_layout Enumerate
33832 be immune to licensing/availability/price changes of the chosen tool chain
33835 \begin_layout Enumerate
33836 be able to change to a new target platform without having to adopt a new
33840 \begin_layout Enumerate
33841 have complete control over and insight into the tool chain
33844 \begin_layout Enumerate
33845 make your students aware about the pros and cons of open source software
33849 \begin_layout Enumerate
33850 give back to the public as you are probably at least partially publically
33854 \begin_layout Enumerate
33855 give students a chance to publically prove their skills and to possibly
33856 see a world wide impact
33859 \begin_layout Standard
33860 then SDCC is probably among the first choices.
33861 Well, probably SDCC might be the only choice.
33866 \begin_layout Chapter
33867 SDCC Technical Data
33870 \begin_layout Section
33872 \begin_inset LatexCommand \index{Optimizations}
33879 \begin_layout Standard
33880 SDCC performs a host of standard optimizations in addition to some MCU specific
33885 \begin_layout Subsection
33886 Sub-expression Elimination
33887 \begin_inset LatexCommand \index{Subexpression elimination}
33894 \begin_layout Standard
33895 The compiler does local and
33914 \begin_layout Verse
33922 \begin_layout Standard
33923 will be translated to
33926 \begin_layout Verse
33936 \begin_layout Standard
33937 Some subexpressions are not as obvious as the above example, e.g.:
33940 \begin_layout Verse
33948 \begin_layout Standard
33949 In this case the address arithmetic a->b[i] will be computed only once;
33950 the equivalent code in C would be.
33953 \begin_layout Verse
33963 \begin_layout Standard
33964 The compiler will try to keep these temporary variables in registers.
33967 \begin_layout Subsection
33968 Dead-Code Elimination
33969 \begin_inset LatexCommand \index{Dead-code elimination}
33976 \begin_layout Verse
33991 i = 1; \InsetSpace ~
34000 global = 1;\InsetSpace ~
34014 global = 3;\InsetSpace ~
34020 \begin_layout Standard
34024 \begin_layout Verse
34040 \begin_layout Subsection
34042 \begin_inset LatexCommand \index{Copy propagation}
34049 \begin_layout Verse
34073 \begin_layout Standard
34077 \begin_layout Verse
34101 \begin_layout Standard
34102 Note: the dead stores created by this copy propagation will be eliminated
34103 by dead-code elimination.
34106 \begin_layout Subsection
34108 \begin_inset LatexCommand \index{Loop optimization}
34113 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
34120 \begin_layout Standard
34121 Two types of loop optimizations are done by SDCC
34129 of loop induction variables.
34130 In addition to the strength reduction the optimizer marks the induction
34131 variables and the register allocator tries to keep the induction variables
34132 in registers for the duration of the loop.
34133 Because of this preference of the register allocator
34134 \begin_inset LatexCommand \index{Register allocation}
34138 , loop induction optimization causes an increase in register pressure, which
34139 may cause unwanted spilling of other temporary variables into the stack
34140 \begin_inset LatexCommand \index{stack}
34145 The compiler will generate a warning message when it is forced to allocate
34146 extra space either on the stack or data space.
34147 If this extra space allocation is undesirable then induction optimization
34148 can be eliminated either for the entire source file (with -
34152 \begin_layout Standard
34161 -noinduction option) or for a given function only using #pragma\InsetSpace ~
34163 \begin_inset LatexCommand \index{\#pragma noinduction}
34174 \begin_layout Verse
34177 for (i = 0 ; i < 100 ; i ++)
34186 \begin_layout Standard
34190 \begin_layout Verse
34195 for (i = 0; i < 100; i++)
34204 \begin_layout Standard
34205 As mentioned previously some loop invariants are not as apparent, all static
34206 address computations are also moved out of the loop.
34211 \begin_inset LatexCommand \index{Strength reduction}
34215 , this optimization substitutes an expression by a cheaper expression:
34218 \begin_layout Verse
34221 for (i=0;i < 100; i++)
34230 \begin_layout Standard
34234 \begin_layout Verse
34241 for (i=0;i< 100;i++) {
34247 ar[itemp1] = itemp2;
34265 \begin_layout Standard
34266 The more expensive multiplication
34267 \begin_inset LatexCommand \index{Multiplication}
34271 is changed to a less expensive addition.
34274 \begin_layout Subsection
34276 \begin_inset LatexCommand \index{Loop reversing}
34283 \begin_layout Standard
34284 This optimization is done to reduce the overhead of checking loop boundaries
34285 for every iteration.
34286 Some simple loops can be reversed and implemented using a
34287 \begin_inset Quotes eld
34290 decrement and jump if not zero
34291 \begin_inset Quotes erd
34295 SDCC checks for the following criterion to determine if a loop is reversible
34296 (note: more sophisticated compilers use data-dependency analysis to make
34297 this determination, SDCC uses a more simple minded analysis).
34300 \begin_layout Itemize
34301 The 'for' loop is of the form
34307 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
34317 \begin_layout Itemize
34318 The <for body> does not contain
34319 \begin_inset Quotes eld
34323 \begin_inset Quotes erd
34327 \begin_inset Quotes erd
34333 \begin_layout Itemize
34334 All goto's are contained within the loop.
34337 \begin_layout Itemize
34338 No function calls within the loop.
34341 \begin_layout Itemize
34342 The loop control variable <sym> is not assigned any value within the loop
34345 \begin_layout Itemize
34346 The loop control variable does NOT participate in any arithmetic operation
34350 \begin_layout Itemize
34351 There are NO switch statements in the loop.
34354 \begin_layout Subsection
34355 Algebraic Simplifications
34358 \begin_layout Standard
34359 SDCC does numerous algebraic simplifications, the following is a small sub-set
34360 of these optimizations.
34363 \begin_layout Verse
34366 i = j + 0;\InsetSpace ~
34370 /* changed to: */\InsetSpace ~
34376 i /= 2;\InsetSpace ~
34383 /* changed to: */\InsetSpace ~
34390 = j - j;\InsetSpace ~
34394 /* changed to: */\InsetSpace ~
34400 i = j / 1;\InsetSpace ~
34404 /* changed to: */\InsetSpace ~
34411 \begin_layout Standard
34412 Note the subexpressions
34413 \begin_inset LatexCommand \index{Subexpression}
34417 given above are generally introduced by macro expansions or as a result
34418 of copy/constant propagation.
34421 \begin_layout Subsection
34422 'switch' Statements
34423 \begin_inset LatexCommand \label{sub:'switch'-Statements}
34428 \begin_inset LatexCommand \index{switch statement}
34435 \begin_layout Standard
34436 SDCC can optimize switch statements to jump tables
34437 \begin_inset LatexCommand \index{jump tables}
34442 It makes the decision based on an estimate of the generated code size.
34443 SDCC is quite liberal in the requirements for jump table generation:
34446 \begin_layout Itemize
34447 The labels need not be in order, and the starting number need not be one
34448 or zero, the case labels are in numerical sequence or not too many case
34449 labels are missing.
34453 \begin_layout Verse
34456 switch(i) {\InsetSpace ~
34487 case 4: ...\InsetSpace ~
34519 case 5: ...\InsetSpace ~
34551 case 3: ...\InsetSpace ~
34582 case 6: ...\InsetSpace ~
34614 case 7: ...\InsetSpace ~
34646 case 8: ...\InsetSpace ~
34678 case 9: ...\InsetSpace ~
34710 case 10: ...\InsetSpace ~
34741 case 11: ...\InsetSpace ~
34808 \begin_layout Standard
34809 Both the above switch statements will be implemented using a jump-table.
34810 The example to the right side is slightly more efficient as the check for
34811 the lower boundary of the jump-table is not needed.
34815 \begin_layout Itemize
34816 The number of case labels is not larger than supported by the target architectur
34820 \begin_layout Itemize
34821 If the case labels are not in numerical sequence ('gaps' between cases)
34822 SDCC checks whether a jump table with additionally inserted dummy cases
34823 is still attractive.
34827 \begin_layout Itemize
34828 If the starting number is not zero and a check for the lower boundary of
34829 the jump-table can thus be eliminated SDCC might insert dummy cases 0,
34834 \begin_layout Standard
34835 Switch statements which have large gaps in the numeric sequence or those
34836 that have too many case labels can be split into more than one switch statement
34837 for efficient code generation, e.g.:
34840 \begin_layout Verse
34918 \begin_layout Standard
34919 If the above switch statement is broken down into two switch statements
34922 \begin_layout Verse
34965 \begin_layout Standard
34969 \begin_layout Verse
35012 \begin_layout Standard
35013 then both the switch statements will be implemented using jump-tables whereas
35014 the unmodified switch statement will not be.
35017 \begin_layout Standard
35018 \begin_inset Note Note
35021 \begin_layout Standard
35022 There might be reasons which SDCC cannot know about to either favour or
35023 not favour jump tables.
35024 If the target system has to be as quick for the last switch case as for
35025 the first (pro jump table), or if the switch argument is known to be zero
35026 in the majority of the cases (contra jump table).
35034 \begin_layout Standard
35035 The pragma nojtbound
35036 \begin_inset LatexCommand \index{\#pragma nojtbound}
35040 can be used to turn off checking the
35053 It has no effect if a default label is supplied.
35054 Use of this pragma is dangerous: if the switch
35055 \begin_inset LatexCommand \index{switch statement}
35059 argument is not matched by a case statement the processor will happily
35063 \begin_layout Subsection
35064 Bit-shifting Operations
35065 \begin_inset LatexCommand \index{Bit shifting}
35072 \begin_layout Standard
35073 Bit shifting is one of the most frequently used operation in embedded programmin
35075 SDCC tries to implement bit-shift operations in the most efficient way
35079 \begin_layout Verse
35092 \begin_layout Standard
35093 generates the following code:
35096 \begin_layout Verse
35111 \begin_layout Standard
35112 In general SDCC will never setup a loop if the shift count is known.
35116 \begin_layout Verse
35129 \begin_layout Standard
35133 \begin_layout Verse
35157 \begin_layout Subsection
35159 \begin_inset LatexCommand \index{Bit rotation}
35166 \begin_layout Standard
35167 A special case of the bit-shift operation is bit rotation
35168 \begin_inset LatexCommand \index{rotating bits}
35172 , SDCC recognizes the following expression to be a left bit-rotation:
35175 \begin_layout Verse
35183 char i;\InsetSpace ~
35194 /* unsigned is needed for rotation */
35199 i = ((i << 1) | (i >> 7));
35208 \begin_layout Standard
35209 will generate the following code:
35212 \begin_layout Verse
35229 \begin_layout Standard
35230 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
35231 ns of this case will also be recognized as bit-rotation, i.e.:
35234 \begin_layout Verse
35237 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
35240 \begin_layout Subsection
35241 Nibble and Byte Swapping
35244 \begin_layout Standard
35245 Other special cases of the bit-shift operations are nibble or byte swapping
35246 \begin_inset LatexCommand \index{swapping nibbles/bytes}
35250 , SDCC recognizes the following expressions:
35253 \begin_layout Verse
35274 i = ((i << 4) | (i >> 4));
35280 j = ((j << 8) | (j >> 8));
35283 \begin_layout Standard
35284 and generates a swap instruction for the nibble swapping
35285 \begin_inset LatexCommand \index{Nibble swapping}
35289 or move instructions for the byte swapping
35290 \begin_inset LatexCommand \index{Byte swapping}
35296 \begin_inset Quotes sld
35300 \begin_inset Quotes srd
35303 example can be used to convert from little to big-endian or vice versa.
35304 If you want to change the endianness of a
35308 integer you have to cast to
35315 \begin_layout Standard
35316 Note that SDCC stores numbers in little-endian
35320 \begin_layout Standard
35321 Usually 8-bit processors don't care much about endianness.
35322 This is not the case for the standard 8051 which only has an instruction
35328 \begin_inset LatexCommand \index{DPTR}
35336 so little-endian is the more efficient byte order.
35342 \begin_inset LatexCommand \index{little-endian}
35347 \begin_inset LatexCommand \index{Endianness}
35352 lowest order first).
35355 \begin_layout Subsection
35357 \begin_inset LatexCommand \index{Highest Order Bit}
35362 \begin_inset LatexCommand \index{Any Order Bit}
35369 \begin_layout Standard
35370 It is frequently required to obtain the highest order bit of an integral
35371 type (long, int, short or char types).
35372 Also obtaining any other order bit is not uncommon.
35373 SDCC recognizes the following expressions to yield the highest order bit
35374 and generates optimized code for it, e.g.:
35377 \begin_layout Verse
35388 unsigned char hob1, aob1;
35392 bit hob2, hob3, aob2,
35402 hob1 = (gint >> 15) & 1;
35406 hob2 = (gint >> 15) & 1;
35410 hob3 = gint & 0x8000;
35415 aob1 = (gint >> 9) & 1;
35419 aob2 = (gint >> 8) & 1;
35423 aob3 = gint & 0x0800;
35433 \begin_layout Standard
35434 will generate the following code:
35437 \begin_layout Verse
35468 000A E5*01\InsetSpace ~
35495 000C 23\InsetSpace ~
35526 000D 54 01\InsetSpace ~
35554 000F F5*02\InsetSpace ~
35609 0011 E5*01\InsetSpace ~
35637 0013 33\InsetSpace ~
35667 0014 92*00\InsetSpace ~
35723 0016 E5*01\InsetSpace ~
35750 0018 33\InsetSpace ~
35780 0019 92*01\InsetSpace ~
35836 001B E5*01\InsetSpace ~
35895 001E 54 01\InsetSpace ~
35922 0020 F5*03\InsetSpace ~
35978 0022 E5*01\InsetSpace ~
36005 0024 13\InsetSpace ~
36035 0025 92*02\InsetSpace ~
36091 0027 E5*01\InsetSpace ~
36146 002B 92*03\InsetSpace ~
36174 \begin_layout Standard
36175 Other variations of these cases however will
36180 They are standard C expressions, so I heartily recommend these be the only
36181 way to get the highest order bit, (it is portable).
36182 Of course it will be recognized even if it is embedded in other expressions,
36186 \begin_layout Verse
36189 xyz = gint + ((gint >> 15) & 1);
36192 \begin_layout Standard
36193 will still be recognized.
36196 \begin_layout Subsection
36198 \begin_inset LatexCommand \index{Higher Order Byte}
36202 / Higher Order Word
36203 \begin_inset LatexCommand \index{Higher Order Word}
36210 \begin_layout Standard
36211 It is also frequently required to obtain a higher order byte or word of
36212 a larger integral type (long, int or short types).
36213 SDCC recognizes the following expressions to yield the higher order byte
36214 or word and generates optimized code for it, e.g.:
36217 \begin_layout Verse
36222 unsigned long int glong;
36230 unsigned char hob1,
36235 unsigned int how1, how2;
36244 hob1 = (gint >> 8) & 0xFF;
36248 hob2 = glong >> 24;
36252 how1 = (glong >> 16) & 0xFFFF;
36267 \begin_layout Standard
36268 will generate the following code:
36271 \begin_layout Verse
36302 0037 85*01*06\InsetSpace ~
36324 _foo_hob1_1_1,(_gint + 1)
36355 003A 85*05*07\InsetSpace ~
36377 _foo_hob2_1_1,(_glong + 3)
36407 003D 85*04*08\InsetSpace ~
36430 _foo_how1_1_1,(_glong + 2)
36432 0040 85*05*09\InsetSpace ~
36457 0043 85*03*0A\InsetSpace ~
36479 _foo_how2_1_1,(_glong + 1)
36481 0046 85*04*0B\InsetSpace ~
36504 (_foo_how2_1_1 + 1),(_glong + 2)
36507 \begin_layout Standard
36508 Again, variations of these cases may
36513 They are standard C expressions, so I heartily recommend these be the only
36514 way to get the higher order byte/word, (it is portable).
36515 Of course it will be recognized even if it is embedded in other expressions,
36519 \begin_layout Verse
36522 xyz = gint + ((gint >> 8) & 0xFF);
36525 \begin_layout Standard
36526 will still be recognized.
36529 \begin_layout Subsection
36531 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
36536 \begin_inset LatexCommand \index{Peephole optimizer}
36543 \begin_layout Standard
36544 The compiler uses a rule based, pattern matching and re-writing mechanism
36545 for peep-hole optimization.
36550 a peep-hole optimizer by Christopher W.
36551 Fraser (cwfraser\InsetSpace ~
36554 A default set of rules are compiled into the compiler, additional rules
36555 may be added with the
36561 \begin_layout Standard
36571 \begin_inset LatexCommand \index{-\/-peep-file}
36578 The rule language is best illustrated with examples.
36581 \begin_layout Verse
36603 \begin_layout Standard
36604 The above rule will change the following assembly
36605 \begin_inset LatexCommand \index{Assembler routines}
36612 \begin_layout Verse
36620 \begin_layout Standard
36624 \begin_layout Verse
36630 \begin_layout Standard
36631 Note: All occurrences of a
36635 (pattern variable) must denote the same string.
36636 With the above rule, the assembly sequence:
36639 \begin_layout Verse
36647 \begin_layout Standard
36648 will remain unmodified.
36652 Other special case optimizations may be added by the
36659 \begin_layout Standard
36672 some variants of the 8051 MCU
36673 \begin_inset LatexCommand \index{MCS51 variants}
36686 The following two rules will change all
36703 \begin_layout Verse
36706 replace { lcall %1 } by { acall %1 }
36708 replace { ljmp %1 } by { ajmp %1 }
36711 \begin_layout Standard
36712 (NOTE: from version 2.7.3 on, you can use option -
36718 \begin_layout Standard
36730 \begin_inset LatexCommand \index{-\/-acall-ajmp}
36734 , which also takes care of aligning the interrupt vectors properly.)
36739 \begin_layout Standard
36742 inline-assembler code
36744 is also passed through the peep hole optimizer, thus the peephole optimizer
36745 can also be used as an assembly level macro expander.
36746 The rules themselves are MCU dependent whereas the rule language infra-structur
36747 e is MCU independent.
36748 Peephole optimization rules for other MCU can be easily programmed using
36753 The syntax for a rule is as follows:
36756 \begin_layout Verse
36759 rule := replace [ restart ] '{' <assembly sequence> '
36797 <assembly sequence> '
36815 '}' [if <functionName> ] '
36820 \begin_layout Standard
36821 <assembly sequence> := assembly instruction (each instruction including
36822 labels must be on a separate line).
36826 The optimizer will apply to the rules
36827 one by one from the top in the sequence of their appearance, it will terminate
36828 when all rules are exhausted.
36829 If the 'restart' option is specified, then the optimizer will start matching
36830 the rules again from the top, this option for a rule is expensive (performance)
36831 , it is intended to be used in situations where a transformation will trigger
36832 the same rule again.
36833 An example of this (not a good one, it has side effects) is the following
36837 \begin_layout Verse
36857 \begin_layout Standard
36858 Note that the replace pattern cannot be a blank, but can be a comment line.
36859 Without the 'restart' option only the innermost 'pop' 'push' pair would
36860 be eliminated, i.e.:
36863 \begin_layout Verse
36875 \begin_layout Standard
36879 \begin_layout Verse
36889 \begin_layout Standard
36894 the restart option the rule will be applied again to the resulting code
36895 and then all the pop-push pairs will be eliminated to yield:
36898 \begin_layout Verse
36906 \begin_layout Standard
36907 A conditional function can be attached to a rule.
36908 Attaching rules are somewhat more involved, let me illustrate this with
36912 \begin_layout Verse
36936 \begin_layout Standard
36937 The optimizer does a look-up of a function name table defined in function
36942 in the source file SDCCpeeph.c, with the name
36947 If it finds a corresponding entry the function is called.
36948 Note there can be no parameters specified for these functions, in this
36953 is crucial, since the function
36957 expects to find the label in that particular variable (the hash table containin
36958 g the variable bindings is passed as a parameter).
36959 If you want to code more such functions, take a close look at the function
36960 labelInRange and the calling mechanism in source file SDCCpeeph.c.
36961 Currently implemented are
36963 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
36964 24bitMode, portIsDS390, 24bitModeAndPortDS390
36973 \begin_layout Standard
36974 I know this whole thing is a little kludgey, but maybe some day we will
36975 have some better means.
36976 If you are looking at this file, you will see the default rules that are
36977 compiled into the compiler, you can add your own rules in the default set
36978 there if you get tired of specifying the -
36982 \begin_layout Standard
36994 \begin_layout Section
36996 \begin_inset LatexCommand \index{ANSI-compliance}
37001 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
37008 \begin_layout Standard
37009 The latest publically available version of the standard
37011 ISO/IEC 9899 - Programming languages - C
37013 should be available at:
37014 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
37023 \begin_layout Standard
37024 Deviations from the compliance:
37027 \begin_layout Itemize
37028 functions are not reentrant
37029 \begin_inset LatexCommand \index{reentrant}
37033 unless explicitly declared as such or the
37039 \begin_layout Standard
37049 \begin_inset LatexCommand \index{-\/-stack-auto}
37055 command line option is specified.
37058 \begin_layout Itemize
37060 \begin_inset LatexCommand \index{struct}
37065 \begin_inset LatexCommand \index{union}
37069 cannot be assigned values directly, cannot be passed as function parameters
37070 or assigned to each other and cannot be a return value
37071 \begin_inset LatexCommand \index{return value}
37075 from a function, e.g.:
37079 \begin_layout Verse
37102 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
37121 s parms) /* invalid in SDCC although allowed in ANSI */
37143 return rets; /* is invalid in SDCC although allowed in ANSI */
37149 \begin_layout Itemize
37150 initialization of structure arrays must be fully braced.
37154 \begin_layout Verse
37157 struct s { char x } a[] = {1, 2};\InsetSpace ~
37162 /* invalid in SDCC */
37165 } a[] = {{1}, {2}}; /* OK */
37169 \begin_layout Itemize
37171 \begin_inset LatexCommand \index{long long (not supported)}
37176 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
37183 \begin_layout Itemize
37185 \begin_inset LatexCommand \index{double (not supported)}
37189 ' precision floating point
37190 \begin_inset LatexCommand \index{Floating point support}
37197 \begin_layout Itemize
37199 \begin_inset LatexCommand \index{K\&R style}
37203 function declarations are NOT allowed.
37207 \begin_layout Verse
37210 foo(i,j) /* this old style of function declarations */
37212 int i,j; /* is valid
37213 in ANSI but not valid in SDCC */
37228 \begin_layout Itemize
37229 Most enhancements in C99 are not supported, e.g.:
37233 \begin_layout Verse
37240 i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
37244 \begin_layout Itemize
37245 But some have been added recently in SDCC 2.7.0.
37246 They must be considered alpha quality however.
37250 \begin_layout Verse
37255 \begin_inset LatexCommand \index{inline (not supported)}
37261 int increment (int a) { return a+1; } /* inlines the increment without
37262 function call overhead */
37267 \begin_inset LatexCommand \index{inline (not supported)}
37273 p; /* accepted but ignored */
37277 \begin_layout Itemize
37278 Certain words that are valid identifiers in the standard may be reserved
37279 words in SDCC unless the
37285 \begin_layout Standard
37295 \begin_inset LatexCommand \index{-\/-std-c89}
37307 \begin_layout Standard
37317 \begin_inset LatexCommand \index{-\/-std-c99}
37323 command line options are used.
37324 These may include (depending on the selected processor): 'at', 'banked',
37325 'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
37326 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
37327 'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
37329 Compliant equivalents of these keywords are always available in a form
37330 that begin with two underscores
37331 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
37336 '__data' instead of 'data'.
37339 \begin_layout Itemize
37340 Integer promotion of variable arguments is not performed if the argument
37341 is explicitly taypecasted unless the
37347 \begin_layout Standard
37357 \begin_inset LatexCommand \index{-\/-std-c89}
37369 \begin_layout Standard
37379 \begin_inset LatexCommand \index{-\/-std-c99}
37385 command line options are used.
37389 \begin_layout Verse
37392 void vararg_func (char *str, ...) { str; }
37409 u is promoted to int before
37414 * passing to function */
37418 vararg_func ("%c", c);
37425 argument u is not promoted to int,
37430 * it is passed as char to function
37436 --std-cXX is not defined;
37441 * is promoted to int before passing
37447 if --std-cXX is defined */
37451 vararg_func ("%bc", (char)u);
37457 \begin_layout Section
37458 Cyclomatic Complexity
37459 \begin_inset LatexCommand \index{Cyclomatic complexity}
37466 \begin_layout Standard
37467 Cyclomatic complexity of a function is defined as the number of independent
37468 paths the program can take during execution of the function.
37469 This is an important number since it defines the number test cases you
37470 have to generate to validate the function.
37471 The accepted industry standard for complexity number is 10, if the cyclomatic
37472 complexity reported by SDCC exceeds 10 you should think about simplification
37473 of the function logic.
37474 Note that the complexity level is not related to the number of lines of
37475 code in a function.
37476 Large functions can have low complexity, and small functions can have large
37482 SDCC uses the following formula to compute the complexity:
37487 \begin_layout Standard
37488 complexity = (number of edges in control flow graph) - (number of nodes
37489 in control flow graph) + 2;
37493 Having said that the industry standard is 10,
37494 you should be aware that in some cases it be may unavoidable to have a
37495 complexity level of less than 10.
37496 For example if you have switch statement with more than 10 case labels,
37497 each case label adds one to the complexity level.
37498 The complexity level is by no means an absolute measure of the algorithmic
37499 complexity of the function, it does however provide a good starting point
37500 for which functions you might look at for further optimization.
37503 \begin_layout Section
37504 Retargetting for other Processors
37507 \begin_layout Standard
37508 The issues for retargetting the compiler are far too numerous to be covered
37510 What follows is a brief description of each of the seven phases of the
37511 compiler and its MCU dependency.
37514 \begin_layout Itemize
37515 Parsing the source and building the annotated parse tree.
37516 This phase is largely MCU independent (except for the language extensions).
37517 Syntax & semantic checks are also done in this phase, along with some initial
37518 optimizations like back patching labels and the pattern matching optimizations
37519 like bit-rotation etc.
37522 \begin_layout Itemize
37523 The second phase involves generating an intermediate code which can be easy
37524 manipulated during the later phases.
37525 This phase is entirely MCU independent.
37526 The intermediate code generation assumes the target machine has unlimited
37527 number of registers, and designates them with the name iTemp.
37528 The compiler can be made to dump a human readable form of the code generated
37533 \begin_layout Standard
37545 \begin_layout Itemize
37546 This phase does the bulk of the standard optimizations and is also MCU independe
37548 This phase can be broken down into several sub-phases:
37552 Break down intermediate
37553 code (iCode) into basic blocks.
37555 Do control flow & data flow analysis on the
37558 Do local common subexpression elimination, then global subexpressio
37561 Dead code elimination
37565 If loop optimizations
37566 caused any changes then do 'global subexpression elimination' and 'dead
37567 code elimination' again.
37570 \begin_layout Itemize
37571 This phase determines the live-ranges; by live range I mean those iTemp
37572 variables defined by the compiler that still survive after all the optimization
37574 Live range analysis
37575 \begin_inset LatexCommand \index{Live range analysis}
37579 is essential for register allocation, since these computation determines
37580 which of these iTemps will be assigned to registers, and for how long.
37583 \begin_layout Itemize
37584 Phase five is register allocation.
37585 There are two parts to this process.
37589 The first part I call 'register packing'
37590 (for lack of a better term).
37591 In this case several MCU specific expression folding is done to reduce
37596 The second part is more MCU independent and deals with
37597 allocating registers to the remaining live ranges.
37598 A lot of MCU specific code does creep into this phase because of the limited
37599 number of index registers available in the 8051.
37602 \begin_layout Itemize
37603 The Code generation phase is (unhappily), entirely MCU dependent and very
37604 little (if any at all) of this code can be reused for other MCU.
37605 However the scheme for allocating a homogenized assembler operand for each
37606 iCode operand may be reused.
37609 \begin_layout Itemize
37610 As mentioned in the optimization section the peep-hole optimizer is rule
37611 based system, which can reprogrammed for other MCUs.
37614 \begin_layout Standard
37615 More information is available on SDCC Wiki
37616 \begin_inset LatexCommand \index{wiki}
37621 \begin_inset LatexCommand \url{http://sdcc.wiki.sourceforge.net/SDCC+internals+and+porting}
37625 ) and in the thread
37626 \begin_inset LatexCommand \url{http://sf.net/mailarchive/message.php?msg_id=13954144}
37633 \begin_layout Chapter
37635 \begin_inset LatexCommand \index{Compiler internals}
37642 \begin_layout Section
37643 The anatomy of the compiler
37644 \begin_inset LatexCommand \label{sub:The-anatomy-of}
37651 \begin_layout Standard
37654 This is an excerpt from an article published in Circuit Cellar Magazine
37660 It's a little outdated (the compiler is much more efficient now and user/develo
37661 per friendly), but pretty well exposes the guts of it all.
37667 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
37668 It is fairly easy to retarget for other 8-bit MCU.
37669 Here we take a look at some of the internals of the compiler.
37673 \begin_layout Paragraph*
37675 \begin_inset LatexCommand \index{Parsing}
37682 \begin_layout Standard
37683 Parsing the input source file and creating an AST (Annotated Syntax Tree
37684 \begin_inset LatexCommand \index{Annotated syntax tree}
37689 This phase also involves propagating types (annotating each node of the
37690 parse tree with type information) and semantic analysis.
37691 There are some MCU specific parsing rules.
37692 For example the storage classes, the extended storage classes are MCU specific
37693 while there may be a xdata storage class for 8051 there is no such storage
37694 class for z80 or Atmel AVR.
37695 SDCC allows MCU specific storage class extensions, i.e.
37696 xdata will be treated as a storage class specifier when parsing 8051 C
37697 code but will be treated as a C identifier when parsing z80 or ATMEL AVR
37701 \begin_layout Paragraph*
37703 \begin_inset LatexCommand \index{iCode}
37710 \begin_layout Standard
37711 Intermediate code generation.
37712 In this phase the AST is broken down into three-operand form (iCode).
37713 These three operand forms are represented as doubly linked lists.
37714 ICode is the term given to the intermediate form generated by the compiler.
37715 ICode example section shows some examples of iCode generated for some simple
37716 C source functions.
37719 \begin_layout Paragraph*
37721 \begin_inset LatexCommand \index{Optimizations}
37728 \begin_layout Standard
37729 Bulk of the target independent optimizations is performed in this phase.
37730 The optimizations include constant propagation, common sub-expression eliminati
37731 on, loop invariant code movement, strength reduction of loop induction variables
37732 and dead-code elimination.
37735 \begin_layout Paragraph*
37736 Live range analysis
37737 \begin_inset LatexCommand \index{Live range analysis}
37744 \begin_layout Standard
37745 During intermediate code generation phase, the compiler assumes the target
37746 machine has infinite number of registers and generates a lot of temporary
37748 The live range computation determines the lifetime of each of these compiler-ge
37749 nerated temporaries.
37750 A picture speaks a thousand words.
37751 ICode example sections show the live range annotations for each of the
37753 It is important to note here, each iCode is assigned a number in the order
37754 of its execution in the function.
37755 The live ranges are computed in terms of these numbers.
37756 The from number is the number of the iCode which first defines the operand
37757 and the to number signifies the iCode which uses this operand last.
37760 \begin_layout Paragraph*
37761 Register Allocation
37762 \begin_inset LatexCommand \index{Register allocation}
37769 \begin_layout Standard
37770 The register allocation determines the type and number of registers needed
37772 In most MCUs only a few registers can be used for indirect addressing.
37773 In case of 8051 for example the registers R0 & R1 can be used to indirectly
37774 address the internal ram and DPTR to indirectly address the external ram.
37775 The compiler will try to allocate the appropriate register to pointer variables
37777 ICode example section shows the operands annotated with the registers assigned
37779 The compiler will try to keep operands in registers as much as possible;
37780 there are several schemes the compiler uses to do achieve this.
37781 When the compiler runs out of registers the compiler will check to see
37782 if there are any live operands which is not used or defined in the current
37783 basic block being processed, if there are any found then it will push that
37784 operand and use the registers in this block, the operand will then be popped
37785 at the end of the basic block.
37789 \begin_layout Standard
37790 There are other MCU specific considerations in this phase.
37791 Some MCUs have an accumulator; very short-lived operands could be assigned
37792 to the accumulator instead of a general-purpose register.
37795 \begin_layout Paragraph*
37799 \begin_layout Standard
37800 Figure II gives a table of iCode
37801 \begin_inset LatexCommand \index{iCode}
37805 operations supported by the compiler.
37806 The code generation involves translating these operations into corresponding
37807 assembly code for the processor.
37808 This sounds overly simple but that is the essence of code generation.
37809 Some of the iCode operations are generated on a MCU specific manner for
37810 example, the z80 port does not use registers to pass parameters so the
37811 SEND and RECV iCode operations will not be generated, and it also does
37812 not support JUMPTABLES.
37818 \begin_layout Standard
37822 \begin_inset Tabular
37823 <lyxtabular version="3" rows="39" columns="4">
37824 <features islongtable="true" headBottomDL="true">
37825 <column alignment="block" valignment="top" leftline="true" width="13col%">
37826 <column alignment="left" valignment="top" leftline="true" width="13col%">
37827 <column alignment="block" valignment="top" leftline="true" width="22col%">
37828 <column alignment="block" valignment="top" leftline="true" rightline="true" width="40col%">
37829 <row topline="true" bottomline="true" endhead="true">
37830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37833 \begin_layout Standard
37839 \begin_inset LatexCommand \index{iCode}
37848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37851 \begin_layout Standard
37859 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37862 \begin_layout Standard
37870 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
37873 \begin_layout Standard
37882 <row topline="true">
37883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37886 \begin_layout Standard
37894 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37897 \begin_layout Standard
37900 IC_LEFT() IC_RESULT()
37905 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37908 \begin_layout Standard
37916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
37919 \begin_layout Standard
37922 IC_RESULT = ! IC_LEFT;
37928 <row topline="true">
37929 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37932 \begin_layout Standard
37940 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37943 \begin_layout Standard
37946 IC_LEFT() IC_RESULT()
37951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37954 \begin_layout Standard
37957 Bitwise complement of
37962 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
37965 \begin_layout Standard
37968 IC_RESULT = ~IC_LEFT;
37974 <row topline="true">
37975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37978 \begin_layout Standard
37986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37989 \begin_layout Standard
37992 IC_LEFT() IC_RESULT()
37997 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38000 \begin_layout Standard
38003 Rotate right with carry
38008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38011 \begin_layout Standard
38014 IC_RESULT = (IC_LEFT << 1) | (IC_LEFT >> (sizeof(IC_LEFT)*8-1));
38020 <row topline="true">
38021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38024 \begin_layout Standard
38032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38035 \begin_layout Standard
38038 IC_LEFT() IC_RESULT()
38043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38046 \begin_layout Standard
38049 Rotate left with carry
38054 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38057 \begin_layout Standard
38060 IC_RESULT = (IC_LEFT << (sizeof(LC_LEFT)*8-1) ) | (IC_LEFT >> 1);
38066 <row topline="true">
38067 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38070 \begin_layout Standard
38078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38081 \begin_layout Standard
38084 IC_LEFT() IC_RESULT()
38089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38092 \begin_layout Standard
38095 Get the highest order bit of IC_LEFT
38100 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38103 \begin_layout Standard
38106 IC_RESULT = (IC_LEFT >> (sizeof(IC_LEFT)*8 -1));
38112 <row topline="true">
38113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38116 \begin_layout Standard
38124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38127 \begin_layout Standard
38130 IC_LEFT() IC_RESULT()
38135 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38138 \begin_layout Standard
38146 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38149 \begin_layout Standard
38152 IC_RESULT = - IC_LEFT;
38158 <row topline="true">
38159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38162 \begin_layout Standard
38170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38173 \begin_layout Standard
38181 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38184 \begin_layout Standard
38187 Push the operand into stack
38192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38195 \begin_layout Standard
38204 <row topline="true">
38205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38208 \begin_layout Standard
38216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38219 \begin_layout Standard
38227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38230 \begin_layout Standard
38233 Pop the operand from the stack
38238 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38241 \begin_layout Standard
38250 <row topline="true">
38251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38254 \begin_layout Standard
38262 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38265 \begin_layout Standard
38268 IC_LEFT() IC_RESULT()
38273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38276 \begin_layout Standard
38279 Call the function represented by IC_LEFT
38284 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38287 \begin_layout Standard
38290 IC_RESULT = IC_LEFT();
38296 <row topline="true">
38297 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38300 \begin_layout Standard
38308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38311 \begin_layout Standard
38314 IC_LEFT() IC_RESULT()
38319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38322 \begin_layout Standard
38325 Call via function pointer
38330 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38333 \begin_layout Standard
38336 IC_RESULT = (*IC_LEFT)();
38342 <row topline="true">
38343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38346 \begin_layout Standard
38354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38357 \begin_layout Standard
38365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38368 \begin_layout Standard
38371 Return the value in operand IC_LEFT
38376 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38379 \begin_layout Standard
38388 <row topline="true">
38389 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38392 \begin_layout Standard
38400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38403 \begin_layout Standard
38411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38414 \begin_layout Standard
38422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38425 \begin_layout Standard
38434 <row topline="true">
38435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38438 \begin_layout Standard
38446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38449 \begin_layout Standard
38457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38460 \begin_layout Standard
38468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38471 \begin_layout Standard
38480 <row topline="true">
38481 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38484 \begin_layout Standard
38492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38495 \begin_layout Standard
38498 IC_LEFT() IC_RIGHT() IC_RESULT()
38503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38506 \begin_layout Standard
38514 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38517 \begin_layout Standard
38520 IC_RESULT = IC_LEFT + IC_RIGHT
38526 <row topline="true">
38527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38530 \begin_layout Standard
38538 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38541 \begin_layout Standard
38544 IC_LEFT() IC_RIGHT() IC_RESULT()
38549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38552 \begin_layout Standard
38560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38563 \begin_layout Standard
38566 IC_RESULT = IC_LEFT - IC_RIGHT
38572 <row topline="true">
38573 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38576 \begin_layout Standard
38584 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38587 \begin_layout Standard
38590 IC_LEFT() IC_RIGHT() IC_RESULT()
38595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38598 \begin_layout Standard
38606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38609 \begin_layout Standard
38612 IC_RESULT = IC_LEFT * IC_RIGHT;
38618 <row topline="true">
38619 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38622 \begin_layout Standard
38630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38633 \begin_layout Standard
38636 IC_LEFT() IC_RIGHT() IC_RESULT()
38641 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38644 \begin_layout Standard
38652 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38655 \begin_layout Standard
38658 IC_RESULT = IC_LEFT / IC_RIGHT;
38664 <row topline="true">
38665 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38668 \begin_layout Standard
38676 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38679 \begin_layout Standard
38682 IC_LEFT() IC_RIGHT() IC_RESULT()
38687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38690 \begin_layout Standard
38698 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38701 \begin_layout Standard
38704 IC_RESULT = IC_LEFT % IC_RIGHT;
38710 <row topline="true">
38711 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38714 \begin_layout Standard
38722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38725 \begin_layout Standard
38728 IC_LEFT() IC_RIGHT() IC_RESULT()
38733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38736 \begin_layout Standard
38744 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38747 \begin_layout Standard
38750 IC_RESULT = IC_LEFT < IC_RIGHT;
38756 <row topline="true">
38757 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38760 \begin_layout Standard
38768 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38771 \begin_layout Standard
38774 IC_LEFT() IC_RIGHT() IC_RESULT()
38779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38782 \begin_layout Standard
38790 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38793 \begin_layout Standard
38796 IC_RESULT = IC_LEFT > IC_RIGHT;
38802 <row topline="true">
38803 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38806 \begin_layout Standard
38814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38817 \begin_layout Standard
38820 IC_LEFT() IC_RIGHT() IC_RESULT()
38825 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38828 \begin_layout Standard
38836 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38839 \begin_layout Standard
38842 IC_RESULT = IC_LEFT == IC_RIGHT;
38848 <row topline="true">
38849 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38852 \begin_layout Standard
38860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38863 \begin_layout Standard
38866 IC_LEFT() IC_RIGHT() IC_RESULT()
38871 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38874 \begin_layout Standard
38877 Logical and operation
38882 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38885 \begin_layout Standard
38888 IC_RESULT = IC_LEFT && IC_RIGHT;
38894 <row topline="true">
38895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38898 \begin_layout Standard
38906 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38909 \begin_layout Standard
38912 IC_LEFT() IC_RIGHT() IC_RESULT()
38917 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38920 \begin_layout Standard
38923 Logical or operation
38928 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38931 \begin_layout Standard
38934 IC_RESULT = IC_LEFT || IC_RIGHT;
38940 <row topline="true">
38941 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38944 \begin_layout Standard
38952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38955 \begin_layout Standard
38958 IC_LEFT() IC_RIGHT() IC_RESULT()
38963 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38966 \begin_layout Standard
38974 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38977 \begin_layout Standard
38980 IC_RESULT = IC_LEFT ^ IC_RIGHT;
38986 <row topline="true">
38987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38990 \begin_layout Standard
38998 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39001 \begin_layout Standard
39004 IC_LEFT() IC_RIGHT() IC_RESULT()
39009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39012 \begin_layout Standard
39020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39023 \begin_layout Standard
39026 IC_RESULT = IC_LEFT | IC_RIGHT;
39032 <row topline="true">
39033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39036 \begin_layout Standard
39044 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39047 \begin_layout Standard
39050 IC_LEFT() IC_RIGHT() IC_RESULT()
39055 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39058 \begin_layout Standard
39066 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39069 \begin_layout Standard
39072 IC_RESULT = IC_LEFT & IC_RIGHT;
39078 <row topline="true">
39079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39082 \begin_layout Standard
39090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39093 \begin_layout Standard
39096 IC_LEFT() IC_RIGHT() IC_RESULT()
39101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39104 \begin_layout Standard
39112 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39115 \begin_layout Standard
39118 IC_RESULT = IC_LEFT << IC_RIGHT
39124 <row topline="true">
39125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39128 \begin_layout Standard
39136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39139 \begin_layout Standard
39142 IC_LEFT() IC_RIGHT() IC_RESULT()
39147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39150 \begin_layout Standard
39158 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39161 \begin_layout Standard
39164 IC_RESULT = IC_LEFT >> IC_RIGHT
39170 <row topline="true">
39171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39174 \begin_layout Standard
39184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39187 \begin_layout Standard
39190 IC_LEFT() IC_RESULT()
39195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39198 \begin_layout Standard
39206 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39209 \begin_layout Standard
39212 IC_RESULT = (*IC_LEFT);
39218 <row topline="true">
39219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39222 \begin_layout Standard
39230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39233 \begin_layout Standard
39236 IC_RIGHT() IC_RESULT()
39241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39244 \begin_layout Standard
39252 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39255 \begin_layout Standard
39258 (*IC_RESULT) = IC_RIGHT;
39264 <row topline="true">
39265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39268 \begin_layout Standard
39276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39279 \begin_layout Standard
39282 IC_RIGHT() IC_RESULT()
39287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39290 \begin_layout Standard
39298 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39301 \begin_layout Standard
39304 IC_RESULT = IC_RIGHT;
39310 <row topline="true">
39311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39314 \begin_layout Standard
39322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39325 \begin_layout Standard
39328 IC_COND IC_TRUE IC_LABEL
39333 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39336 \begin_layout Standard
39340 If true label is present then jump to true label if condition is true else
39341 jump to false label if condition is false
39346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39349 \begin_layout Standard
39352 if (IC_COND) goto IC_TRUE;
39358 If (!IC_COND) goto IC_FALSE;
39364 <row topline="true">
39365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39368 \begin_layout Standard
39376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39379 \begin_layout Standard
39382 IC_LEFT() IC_RESULT()
39387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39390 \begin_layout Standard
39398 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39401 \begin_layout Standard
39404 IC_RESULT = &IC_LEFT();
39410 <row topline="true">
39411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39414 \begin_layout Standard
39422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39425 \begin_layout Standard
39428 IC_JTCOND IC_JTLABELS
39433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39436 \begin_layout Standard
39439 Jump to list of labels depending on the value of JTCOND
39444 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39447 \begin_layout Standard
39456 <row topline="true">
39457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39460 \begin_layout Standard
39468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39471 \begin_layout Standard
39474 IC_RIGHT() IC_LEFT() IC_RESULT()
39479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39482 \begin_layout Standard
39490 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39493 \begin_layout Standard
39496 IC_RESULT = (typeof IC_LEFT) IC_RIGHT;
39502 <row topline="true">
39503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39506 \begin_layout Standard
39514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39517 \begin_layout Standard
39525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39528 \begin_layout Standard
39531 This is used for passing parameters in registers;
39533 move IC_LEFT to the next
39534 available parameter register.
39539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39542 \begin_layout Standard
39551 <row topline="true">
39552 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39555 \begin_layout Standard
39563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39566 \begin_layout Standard
39574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39577 \begin_layout Standard
39580 This is used for receiving parameters passed in registers;
39583 in the next parameter register to IC_RESULT
39588 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39591 \begin_layout Standard
39600 <row topline="true" bottomline="true">
39601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39604 \begin_layout Standard
39608 (some more have been added)
39613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39616 \begin_layout Standard
39622 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39625 \begin_layout Standard
39631 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39634 \begin_layout Standard
39658 \begin_layout Standard
39659 \begin_inset Note Note
39662 \begin_layout Standard
39663 In the original article Figure II was announced to be downloadable on
39668 ftp://ftp.circuitcellar.com/pub/Circuit_Cellar/2000/121/dutta.ZIP
39676 \begin_layout Paragraph*
39678 \begin_inset LatexCommand \index{iCode}
39685 \begin_layout Standard
39686 This section shows some details of iCode.
39687 The example C code does not do anything useful; it is used as an example
39688 to illustrate the intermediate code generated by the compiler.
39691 \begin_layout Verse
39701 /* This function does nothing useful.
39708 for the purpose of explaining iCode */
39711 short function (data
39720 short i=10; \InsetSpace ~
39722 /* dead initialization eliminated */
39728 /* dead initialization eliminated */
39756 /* compiler detects i,j to be induction
39761 for (i = 0, j = 10 ; i < 10 ; i++, j
39767 \begin_layout Standard
39790 mul += i * 3; \InsetSpace ~
39792 /* this multiplication remains */
39799 j * 3;\InsetSpace ~
39801 /* this multiplication changed to addition */
39815 \begin_layout Standard
39816 In addition to the operands each iCode contains information about the filename
39817 and line it corresponds to in the source file.
39818 The first field in the listing should be interpreted as follows:
39823 Filename(linenumber: iCode Execution sequence number : ICode hash table
39824 key : loop depth of the iCode).
39829 Then follows the human readable form of the ICode operation.
39830 Each operand of this triplet form can be of three basic types a) compiler
39831 generated temporary b) user defined variable c) a constant value.
39832 Note that local variables and parameters are replaced by compiler generated
39835 \begin_inset LatexCommand \index{Live range analysis}
39839 are computed only for temporaries (i.e.
39840 live ranges are not computed for global variables).
39842 \begin_inset LatexCommand \index{Register allocation}
39846 are allocated for temporaries only.
39847 Operands are formatted in the following manner:
39852 Operand Name [lr live-from : live-to ] { type information } [ registers
39858 As mentioned earlier the live ranges are computed in terms of the execution
39859 sequence number of the iCodes, for example
39861 the iTemp0 is live from (i.e.
39862 first defined in iCode with execution sequence number 3, and is last used
39863 in the iCode with sequence number 5).
39864 For induction variables such as iTemp21 the live range computation extends
39865 the lifetime from the start to the end of the loop.
39867 The register allocator
39868 used the live range information to allocate registers, the same registers
39869 may be used for different temporaries if their live ranges do not overlap,
39870 for example r0 is allocated to both iTemp6 and to iTemp17 since their live
39871 ranges do not overlap.
39872 In addition the allocator also takes into consideration the type and usage
39873 of a temporary, for example itemp6 is a pointer to near space and is used
39874 as to fetch data from (i.e.
39875 used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
39876 Some short lived temporaries are allocated to special registers which have
39877 meaning to the code generator e.g.
39878 iTemp13 is allocated to a pseudo register CC which tells the back end that
39879 the temporary is used only for a conditional jump the code generation makes
39880 use of this information to optimize a compare and jump ICode.
39884 \begin_inset LatexCommand \index{Loop optimization}
39888 performed by the compiler.
39889 It can detect induction variables iTemp21(i) and iTemp23(j).
39890 Also note the compiler does selective strength reduction
39891 \begin_inset LatexCommand \index{Strength reduction}
39896 the multiplication of an induction variable in line 18 (gint = j * 3) is
39897 changed to addition, a new temporary iTemp17 is allocated and assigned
39898 a initial value, a constant 3 is then added for each iteration of the loop.
39899 The compiler does not change the multiplication
39900 \begin_inset LatexCommand \index{Multiplication}
39904 in line 17 however since the processor does support an 8 * 8 bit multiplication.
39907 Note the dead code elimination
39908 \begin_inset LatexCommand \index{Dead-code elimination}
39912 optimization eliminated the dead assignments in line 7 & 8 to I and sum
39918 \begin_layout Standard
39921 Sample.c (5:1:0:0) _entry($9) :
39924 \begin_layout Standard
39927 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
39930 \begin_layout Standard
39933 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
39936 \begin_layout Standard
39939 Sample.c(11:4:53:0) preHeaderLbl0($11) :
39942 \begin_layout Standard
39945 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
39949 \begin_layout Standard
39952 Sample.c(11:6:5:1) _whilecontinue_0($1) :
39955 \begin_layout Standard
39958 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
39962 \begin_layout Standard
39965 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
39968 \begin_layout Standard
39971 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
39975 \begin_layout Standard
39978 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
39982 \begin_layout Standard
39985 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
39989 \begin_layout Standard
39992 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
39996 \begin_layout Standard
39999 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
40000 * int}[r0] + 0x2 {short}
40003 \begin_layout Standard
40006 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
40009 \begin_layout Standard
40012 Sample.c(11:17:21:0)_whilebreak_0($3) :
40015 \begin_layout Standard
40018 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
40021 \begin_layout Standard
40024 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
40027 \begin_layout Standard
40030 Sample.c(15:20:54:0)preHeaderLbl1($13) :
40033 \begin_layout Standard
40036 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
40039 \begin_layout Standard
40042 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
40045 \begin_layout Standard
40048 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
40051 \begin_layout Standard
40054 Sample.c(15:24:26:1)_forcond_0($4) :
40057 \begin_layout Standard
40060 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
40064 \begin_layout Standard
40067 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
40070 \begin_layout Standard
40073 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
40074 + ITemp21 [lr21:38]{short}[r4]
40077 \begin_layout Standard
40080 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
40084 \begin_layout Standard
40087 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
40088 + iTemp15 [lr29:30]{short}[r1]
40091 \begin_layout Standard
40094 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
40098 \begin_layout Standard
40101 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
40105 \begin_layout Standard
40108 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
40112 \begin_layout Standard
40115 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
40119 \begin_layout Standard
40122 Sample.c(19:38:47:1) goto _forcond_0($4)
40125 \begin_layout Standard
40128 Sample.c(19:39:48:0)_forbreak_0($7) :
40131 \begin_layout Standard
40134 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
40135 + ITemp11 [lr19:40]{short}[r3]
40138 \begin_layout Standard
40141 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
40144 \begin_layout Standard
40147 Sample.c(20:42:51:0)_return($8) :
40150 \begin_layout Standard
40153 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
40159 Finally the code generated for this function:
40164 \begin_layout Standard
40170 \begin_layout Standard
40176 \begin_layout Standard
40184 \begin_layout Standard
40190 \begin_layout Standard
40198 \begin_layout Standard
40204 \begin_layout Standard
40207 ; ----------------------------------------------
40210 \begin_layout Standard
40213 ; function function
40216 \begin_layout Standard
40219 ; ----------------------------------------------
40222 \begin_layout Standard
40228 \begin_layout Standard
40231 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
40234 \begin_layout Standard
40242 \begin_layout Standard
40245 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
40248 \begin_layout Standard
40256 \begin_layout Standard
40259 ;_whilecontinue_0($1) :
40262 \begin_layout Standard
40268 \begin_layout Standard
40271 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
40274 \begin_layout Standard
40277 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
40280 \begin_layout Standard
40288 \begin_layout Standard
40296 \begin_layout Standard
40304 \begin_layout Standard
40312 \begin_layout Standard
40320 \begin_layout Standard
40328 \begin_layout Standard
40336 \begin_layout Standard
40342 \begin_layout Standard
40345 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
40348 \begin_layout Standard
40356 \begin_layout Standard
40364 \begin_layout Standard
40367 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
40370 \begin_layout Standard
40378 \begin_layout Standard
40386 \begin_layout Standard
40394 \begin_layout Standard
40402 \begin_layout Standard
40410 \begin_layout Standard
40418 \begin_layout Standard
40421 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
40424 \begin_layout Standard
40432 \begin_layout Standard
40440 \begin_layout Standard
40448 \begin_layout Standard
40456 \begin_layout Standard
40464 \begin_layout Standard
40467 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
40470 \begin_layout Standard
40478 \begin_layout Standard
40486 \begin_layout Standard
40494 \begin_layout Standard
40497 ; iTemp6 [lr5:16]{_near * int}[r0] =
40500 \begin_layout Standard
40503 ; iTemp6 [lr5:16]{_near * int}[r0] +
40506 \begin_layout Standard
40512 \begin_layout Standard
40520 \begin_layout Standard
40523 ; goto _whilecontinue_0($1)
40526 \begin_layout Standard
40534 \begin_layout Standard
40537 ; _whilebreak_0($3) :
40540 \begin_layout Standard
40546 \begin_layout Standard
40549 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
40552 \begin_layout Standard
40560 \begin_layout Standard
40563 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
40566 \begin_layout Standard
40574 \begin_layout Standard
40577 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
40580 \begin_layout Standard
40588 \begin_layout Standard
40591 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
40594 \begin_layout Standard
40602 \begin_layout Standard
40610 \begin_layout Standard
40613 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
40616 \begin_layout Standard
40624 \begin_layout Standard
40632 \begin_layout Standard
40638 \begin_layout Standard
40644 \begin_layout Standard
40647 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
40650 \begin_layout Standard
40653 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
40656 \begin_layout Standard
40664 \begin_layout Standard
40672 \begin_layout Standard
40680 \begin_layout Standard
40688 \begin_layout Standard
40696 \begin_layout Standard
40702 \begin_layout Standard
40705 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
40708 \begin_layout Standard
40711 ; iTemp21 [lr21:38]{short}[r4]
40714 \begin_layout Standard
40722 \begin_layout Standard
40730 \begin_layout Standard
40738 \begin_layout Standard
40741 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
40744 \begin_layout Standard
40752 \begin_layout Standard
40760 \begin_layout Standard
40768 \begin_layout Standard
40776 \begin_layout Standard
40779 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
40782 \begin_layout Standard
40785 ; iTemp15 [lr29:30]{short}[r1]
40788 \begin_layout Standard
40796 \begin_layout Standard
40804 \begin_layout Standard
40807 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
40810 \begin_layout Standard
40818 \begin_layout Standard
40826 \begin_layout Standard
40834 \begin_layout Standard
40842 \begin_layout Standard
40850 \begin_layout Standard
40858 \begin_layout Standard
40861 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
40864 \begin_layout Standard
40872 \begin_layout Standard
40880 \begin_layout Standard
40888 \begin_layout Standard
40896 \begin_layout Standard
40904 \begin_layout Standard
40912 \begin_layout Standard
40915 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
40918 \begin_layout Standard
40926 \begin_layout Standard
40929 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
40932 \begin_layout Standard
40940 \begin_layout Standard
40945 cjne r5,#0xff,00104$
40948 \begin_layout Standard
40956 \begin_layout Standard
40959 ; goto _forcond_0($4)
40962 \begin_layout Standard
40970 \begin_layout Standard
40973 ; _forbreak_0($7) :
40976 \begin_layout Standard
40982 \begin_layout Standard
40985 ; ret iTemp24 [lr40:41]{short}
40988 \begin_layout Standard
40996 \begin_layout Standard
41004 \begin_layout Standard
41012 \begin_layout Standard
41018 \begin_layout Standard
41024 \begin_layout Standard
41034 \begin_layout Section
41035 A few words about basic block successors, predecessors and dominators
41038 \begin_layout Standard
41039 Successors are basic blocks
41040 \begin_inset LatexCommand \index{Basic blocks}
41044 that might execute after this basic block.
41046 Predecessors are basic blocks
41047 that might execute before reaching this basic block.
41049 Dominators are basic
41050 blocks that WILL execute before reaching this basic block.
41055 \begin_layout Standard
41059 \begin_layout Standard
41063 \begin_layout Standard
41071 \begin_layout Standard
41075 \begin_layout Standard
41083 \begin_layout Standard
41089 \begin_layout Standard
41090 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
41093 \begin_layout Standard
41094 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
41097 \begin_layout Standard
41098 c) domVect of [BB4] = BB1 ...
41099 here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
41103 \begin_layout Chapter
41107 \begin_layout Standard
41108 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/#Who}
41118 Thanks to all the other volunteer developers who have helped with coding,
41119 testing, web-page creation, distribution sets, etc.
41120 You know who you are :-)
41128 Thanks to Sourceforge
41129 \begin_inset LatexCommand \url{http://www.sf.net}
41133 which has hosted the project since 1999 and donates significant download
41142 Also thanks to all SDCC Distributed Compile Farm members for donating CPU
41143 cycles and bandwidth for snapshot builds.
41148 \begin_layout Standard
41149 This document was initially written by Sandeep Dutta
41152 \begin_layout Standard
41153 All product names mentioned herein may be trademarks
41154 \begin_inset LatexCommand \index{Trademarks}
41158 of their respective companies.
41162 \begin_layout Section*
41166 \begin_layout Standard
41167 To avoid confusion, the installation and building options for SDCC itself
41168 (chapter 2) are not part of the index.
41171 \begin_layout Standard
41172 \begin_inset LatexCommand \printindex{}