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.
1693 \begin_layout Standard
1694 Furthermore the environment variables CC, CFLAGS, ...
1695 the tools and their arguments can be influenced.
1696 Please see `configure -
1700 \begin_layout Standard
1709 -help' and the man/info pages of `configure' for details.
1714 standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB, STD_FP_LIB, STD_DS390_LI
1715 B, STD_XA51_LIB and the environment variables SDCC_DIR_NAME, SDCC_INCLUDE_NAME,
1716 SDCC_LIB_NAME are defined by `configure' too.
1717 At the moment it's not possible to change the default settings (it was
1718 simply never required).
1722 These configure options are compiled into the binaries,
1723 and can only be changed by rerunning 'configure' and recompiling SDCC.
1724 The configure options are written in
1728 to distinguish them from run time environment variables (see section search
1734 \begin_inset Quotes sld
1738 \begin_inset Quotes srd
1741 are used by the SDCC team to build the official Win32 binaries.
1742 The SDCC team uses Mingw32 to build the official Windows binaries, because
1746 \begin_layout Enumerate
1750 \begin_layout Enumerate
1751 a gcc compiler and last but not least
1754 \begin_layout Enumerate
1755 the binaries can be built by cross compiling on SDCC Distributed Compile
1759 \begin_layout Standard
1760 See the examples, how to pass the Win32 settings to 'configure'.
1761 The other Win32 builds using Borland, VC or whatever don't use 'configure',
1762 but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
1772 \begin_layout Standard
1774 \begin_inset Tabular
1775 <lyxtabular version="3" rows="9" columns="3">
1777 <column alignment="block" valignment="top" leftline="true" width="0in">
1778 <column alignment="block" valignment="top" leftline="true" width="0in">
1779 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1780 <row topline="true" bottomline="true">
1781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1784 \begin_layout Standard
1790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1793 \begin_layout Standard
1799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1802 \begin_layout Standard
1809 <row topline="true">
1810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1813 \begin_layout Standard
1821 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1824 \begin_layout Standard
1830 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1833 \begin_layout Standard
1842 <row topline="true">
1843 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1846 \begin_layout Standard
1854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1857 \begin_layout Standard
1865 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1868 \begin_layout Standard
1877 <row topline="true">
1878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1881 \begin_layout Standard
1889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1892 \begin_layout Standard
1902 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1905 \begin_layout Standard
1918 <row topline="true">
1919 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1922 \begin_layout Standard
1930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1933 \begin_layout Standard
1941 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1944 \begin_layout Standard
1953 <row topline="true">
1954 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1957 \begin_layout Standard
1965 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1968 \begin_layout Standard
1978 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1981 \begin_layout Standard
1990 <row topline="true">
1991 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1994 \begin_layout Standard
2002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2005 \begin_layout Standard
2015 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2018 \begin_layout Standard
2031 <row topline="true">
2032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2035 \begin_layout Standard
2043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2046 \begin_layout Standard
2052 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2055 \begin_layout Standard
2062 <row topline="true" bottomline="true">
2063 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2066 \begin_layout Standard
2074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2077 \begin_layout Standard
2083 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2086 \begin_layout Standard
2102 \begin_layout Standard
2104 'configure' also computes relative paths.
2105 This is needed for full relocatability of a binary package and to complete
2106 search paths (see section search paths below):
2111 \begin_layout Standard
2113 \begin_inset Tabular
2114 <lyxtabular version="3" rows="4" columns="3">
2116 <column alignment="block" valignment="top" leftline="true" width="0in">
2117 <column alignment="block" valignment="top" leftline="true" width="0in">
2118 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2119 <row topline="true" bottomline="true">
2120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2123 \begin_layout Standard
2129 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2132 \begin_layout Standard
2138 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2141 \begin_layout Standard
2148 <row topline="true" bottomline="true">
2149 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2152 \begin_layout Standard
2160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2163 \begin_layout Standard
2169 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2172 \begin_layout Standard
2179 <row bottomline="true">
2180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2183 \begin_layout Standard
2191 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2194 \begin_layout Standard
2200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2203 \begin_layout Standard
2210 <row bottomline="true">
2211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2214 \begin_layout Standard
2222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2225 \begin_layout Standard
2231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2234 \begin_layout Standard
2250 \begin_layout Standard
2255 \begin_layout LyX-Code
2262 \begin_layout Standard
2272 \begin_inset Quotes srd
2276 \begin_inset Quotes srd
2283 \begin_layout Standard
2293 \begin_inset Quotes srd
2297 \begin_inset Quotes srd
2306 \begin_layout Standard
2319 \begin_layout Standard
2331 \begin_layout Standard
2332 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
2336 \begin_layout LyX-Code
2342 \begin_inset Quotes srd
2345 i586-mingw32msvc-gcc
2346 \begin_inset Quotes srd
2350 \begin_inset Quotes srd
2353 i586-mingw32msvc-g++
2354 \begin_inset Quotes srd
2362 \begin_inset Quotes srd
2365 i586-mingw32msvc-ranlib
2366 \begin_inset Quotes srd
2374 \begin_inset Quotes srd
2377 i586-mingw32msvc-strip
2378 \begin_inset Quotes srd
2389 \begin_layout Standard
2399 \begin_inset Quotes srd
2403 \begin_inset Quotes srd
2414 \begin_layout Standard
2424 \begin_inset Quotes srd
2428 \begin_inset Quotes srd
2436 \begin_inset Quotes srd
2442 \begin_inset Quotes srd
2450 \begin_inset Quotes srd
2454 \begin_inset Quotes srd
2462 \begin_inset Quotes srd
2466 \begin_inset Quotes srd
2473 sdccconf_h_dir_separator=
2474 \begin_inset Quotes srd
2486 \begin_inset Quotes srd
2497 \begin_layout Standard
2514 \begin_layout Standard
2523 -host=i586-mingw32msvc
2531 \begin_layout Standard
2540 -build=unknown-unknown-linux-gnu
2543 \begin_layout Standard
2545 \begin_inset Quotes sld
2549 \begin_inset Quotes srd
2552 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
2556 \begin_layout LyX-Code
2565 \begin_layout Standard
2575 \begin_inset Quotes srd
2579 \begin_inset Quotes srd
2590 \begin_layout Standard
2600 \begin_inset Quotes srd
2604 \begin_inset Quotes srd
2612 \begin_inset Quotes srd
2618 \begin_inset Quotes srd
2626 \begin_inset Quotes srd
2630 \begin_inset Quotes srd
2638 \begin_inset Quotes srd
2642 \begin_inset Quotes srd
2649 sdccconf_h_dir_separator=
2650 \begin_inset Quotes srd
2662 \begin_inset Quotes srd
2670 \begin_inset Quotes srd
2674 \begin_inset Quotes srd
2682 \begin_inset Quotes srd
2686 \begin_inset Quotes srd
2692 \begin_layout Standard
2693 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
2698 \begin_layout Standard
2707 -C' turns on caching, which gives a little bit extra speed.
2708 However if options are changed, it can be necessary to delete the config.cache
2712 \begin_layout Section
2714 \begin_inset LatexCommand \label{sub:Install-paths}
2719 \begin_inset LatexCommand \index{Install paths}
2726 \begin_layout Standard
2727 \begin_inset VSpace medskip
2733 \begin_layout Standard
2735 \begin_inset Tabular
2736 <lyxtabular version="3" rows="5" columns="4">
2738 <column alignment="left" valignment="top" leftline="true" width="0">
2739 <column alignment="left" valignment="top" leftline="true" width="0">
2740 <column alignment="left" valignment="top" leftline="true" width="0">
2741 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
2742 <row topline="true" bottomline="true">
2743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2746 \begin_layout Standard
2754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2757 \begin_layout Standard
2765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2768 \begin_layout Standard
2776 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2779 \begin_layout Standard
2788 <row topline="true">
2789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2792 \begin_layout Standard
2798 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2801 \begin_layout Standard
2809 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2812 \begin_layout Standard
2818 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2821 \begin_layout Standard
2832 <row topline="true">
2833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2836 \begin_layout Standard
2842 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2845 \begin_layout Standard
2848 $DATADIR/ $INCLUDE_DIR_SUFFIX
2853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2856 \begin_layout Standard
2857 /usr/local/share/sdcc/include
2862 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2865 \begin_layout Standard
2876 <row topline="true">
2877 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2880 \begin_layout Standard
2886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2889 \begin_layout Standard
2892 $DATADIR/$LIB_DIR_SUFFIX
2897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2900 \begin_layout Standard
2901 /usr/local/share/sdcc/lib
2906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2909 \begin_layout Standard
2920 <row topline="true" bottomline="true">
2921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2924 \begin_layout Standard
2930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2933 \begin_layout Standard
2941 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2944 \begin_layout Standard
2945 /usr/local/share/sdcc/doc
2950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2953 \begin_layout Standard
2974 *compiler, preprocessor, assembler, and linker
2980 is auto-appended by the compiler, e.g.
2981 small, large, z80, ds390 etc
2984 \begin_layout Standard
2986 The install paths can still be changed during `make install' with e.g.:
2989 \begin_layout LyX-Code
2990 make install prefix=$(HOME)/local/sdcc
2993 \begin_layout Standard
2994 Of course this doesn't change the search paths compiled into the binaries.
2999 r the install path can be changed by defining DESTDIR
3000 \begin_inset LatexCommand \index{DESTDIR}
3007 \begin_layout LyX-Code
3008 make install DESTDIR=$(HOME)/sdcc.rpm/
3011 \begin_layout Standard
3012 Please note that DESTDIR must have a trailing slash!
3015 \begin_layout Section
3017 \begin_inset LatexCommand \label{sub:Search-Paths}
3022 \begin_inset LatexCommand \index{Search path}
3029 \begin_layout Standard
3030 Some search paths or parts of them are determined by configure variables
3035 , see section above).
3036 Further search paths are determined by environment variables during runtime.
3039 The paths searched when running the compiler are as follows (the first
3045 Binary files (preprocessor, assembler and linker)
3050 \begin_layout Standard
3052 \begin_inset Tabular
3053 <lyxtabular version="3" rows="4" columns="3">
3055 <column alignment="block" valignment="top" leftline="true" width="0in">
3056 <column alignment="block" valignment="top" leftline="true" width="0in">
3057 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
3058 <row topline="true" bottomline="true">
3059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3062 \begin_layout Standard
3068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3071 \begin_layout Standard
3077 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3080 \begin_layout Standard
3087 <row topline="true">
3088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3091 \begin_layout Standard
3099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3102 \begin_layout Standard
3108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3111 \begin_layout Standard
3120 <row topline="true">
3121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3124 \begin_layout Standard
3125 Path of argv[0] (if available)
3130 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3133 \begin_layout Standard
3139 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3142 \begin_layout Standard
3149 <row topline="true" bottomline="true">
3150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3153 \begin_layout Standard
3159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3162 \begin_layout Standard
3168 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3171 \begin_layout Standard
3187 \begin_layout Standard
3195 \begin_layout Standard
3197 \begin_inset Tabular
3198 <lyxtabular version="3" rows="6" columns="3">
3200 <column alignment="block" valignment="top" leftline="true" width="1.5in">
3201 <column alignment="block" valignment="top" leftline="true" width="1.5in">
3202 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
3203 <row topline="true" bottomline="true">
3204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3207 \begin_layout Standard
3213 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3216 \begin_layout Standard
3222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3225 \begin_layout Standard
3232 <row topline="true">
3233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3236 \begin_layout Standard
3241 \begin_layout Standard
3255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3258 \begin_layout Standard
3263 \begin_layout Standard
3277 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3280 \begin_layout Standard
3285 \begin_layout Standard
3300 <row topline="true">
3301 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3304 \begin_layout Standard
3310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3313 \begin_layout Standard
3319 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3322 \begin_layout Standard
3329 <row topline="true">
3330 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3333 \begin_layout Standard
3345 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3348 \begin_layout Standard
3358 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3361 \begin_layout Standard
3370 <row topline="true">
3371 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3374 \begin_layout Standard
3390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3393 \begin_layout Standard
3441 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3444 \begin_layout Standard
3455 <row topline="true" bottomline="true">
3456 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3459 \begin_layout Standard
3473 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3476 \begin_layout Standard
3477 /usr/local/share/sdcc/
3484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3487 \begin_layout Standard
3503 \begin_layout Standard
3509 \begin_layout Standard
3518 -nostdinc disables the last two search paths.
3528 \begin_layout Standard
3529 With the exception of
3530 \begin_inset Quotes sld
3537 \begin_layout Standard
3547 \begin_inset Quotes srd
3554 is auto-appended by the compiler (e.g.
3555 small, large, z80, ds390 etc.).
3561 \begin_layout Standard
3563 \begin_inset Tabular
3564 <lyxtabular version="3" rows="6" columns="3">
3566 <column alignment="block" valignment="top" leftline="true" width="1.7in">
3567 <column alignment="block" valignment="top" leftline="true" width="1.2in">
3568 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
3569 <row topline="true" bottomline="true">
3570 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3573 \begin_layout Standard
3579 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3582 \begin_layout Standard
3588 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3591 \begin_layout Standard
3598 <row topline="true">
3599 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3602 \begin_layout Standard
3607 \begin_layout Standard
3621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3624 \begin_layout Standard
3629 \begin_layout Standard
3643 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3646 \begin_layout Standard
3651 \begin_layout Standard
3666 <row topline="true">
3667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3670 \begin_layout Standard
3680 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3683 \begin_layout Standard
3693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3696 \begin_layout Standard
3709 <row topline="true">
3710 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3713 \begin_layout Standard
3720 $LIB_DIR_SUFFIX/<model>
3725 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3728 \begin_layout Standard
3740 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3743 \begin_layout Standard
3758 <row topline="true">
3759 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3762 \begin_layout Standard
3773 $LIB_DIR_SUFFIX/<model>
3778 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3781 \begin_layout Standard
3832 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3835 \begin_layout Standard
3889 <row topline="true" bottomline="true">
3890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3893 \begin_layout Standard
3898 $LIB_DIR_SUFFIX/<model>
3903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3906 \begin_layout Standard
3907 /usr/local/share/sdcc/
3916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3919 \begin_layout Standard
3935 \begin_layout Standard
3936 \begin_inset Note Note
3939 \begin_layout Standard
3940 Don't delete any of the stray spaces in the table above without checking
3941 the HTML output (last line)!
3949 \begin_layout Standard
3957 \begin_layout Standard
3966 -nostdlib disables the last two search paths.
3969 \begin_layout Section
3971 \begin_inset LatexCommand \index{Building SDCC}
3978 \begin_layout Subsection
3979 Building SDCC on Linux
3980 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
3987 \begin_layout Enumerate
3990 Download the source package
3992 either from the SDCC Subversion repository or from snapshot builds
3994 , it will be named something like sdcc
4005 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
4012 \begin_layout Enumerate
4015 Bring up a command line terminal, such as xterm.
4018 \begin_layout Enumerate
4021 Unpack the file using a command like:
4024 "tar -xvzf sdcc-src-yyyymmdd-rrrr.tar.bz2
4025 \begin_inset Quotes srd
4031 , this will create a sub-directory called sdcc with all of the sources.
4034 \begin_layout Enumerate
4035 Change directory into the main SDCC directory, for example type:
4043 \begin_layout Enumerate
4053 This configures the package for compilation on your system.
4056 \begin_layout Enumerate
4070 All of the source packages will compile, this can take a while.
4073 \begin_layout Enumerate
4087 This copies the binary executables, the include files, the libraries and
4088 the documentation to the install directories.
4089 Proceed with section
4090 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
4097 \begin_layout Subsection
4098 Building SDCC on Mac OS X
4101 \begin_layout Standard
4102 Follow the instruction for Linux.
4106 On Mac OS X 10.2.x it was reported, that the
4107 default gcc (version 3.1 20020420 (prerelease)) fails to compile SDCC.
4108 Fortunately there's also gcc 2.9.x installed, which works fine.
4109 This compiler can be selected by running 'configure' with:
4112 \begin_layout LyX-Code
4113 ./configure CC=gcc2 CXX=g++2
4116 \begin_layout Standard
4117 Universal (ppc and i386) binaries can be produced on Mac OS X 10.4.x with
4119 Run 'configure' with:
4122 \begin_layout LyX-Code
4128 \begin_layout LyX-Code
4129 LDFLAGS="-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch
4135 \begin_layout LyX-Code
4136 CXXFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch
4142 \begin_layout LyX-Code
4143 CFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc"
4146 \begin_layout Subsection
4147 Cross compiling SDCC on Linux for Windows
4150 \begin_layout Standard
4151 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
4152 See section 'Configure Options'.
4155 \begin_layout Subsection
4156 Building SDCC using Cygwin and Mingw32
4159 \begin_layout Standard
4160 For building and installing a Cygwin executable follow the instructions
4166 \begin_inset Quotes sld
4170 \begin_inset Quotes srd
4173 Win32-binary can be built, which will not need the Cygwin-DLL.
4174 For the necessary 'configure' options see section 'configure options' or
4175 the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
4180 Cygwin on Windows download setup.exe from
4181 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
4187 \begin_inset Quotes sld
4190 default text file type
4191 \begin_inset Quotes srd
4195 \begin_inset Quotes sld
4199 \begin_inset Quotes srd
4202 and download/install at least the following packages.
4203 Some packages are selected by default, others will be automatically selected
4204 because of dependencies with the manually selected packages.
4205 Never deselect these packages!
4208 \begin_layout Itemize
4212 \begin_layout Itemize
4216 \begin_layout Itemize
4217 gcc ; version 3.x is fine, no need to use the old 2.9x
4220 \begin_layout Itemize
4221 binutils ; selected with gcc
4224 \begin_layout Itemize
4228 \begin_layout Itemize
4229 rxvt ; a nice console, which makes life much easier under windoze (see below)
4232 \begin_layout Itemize
4233 man ; not really needed for building SDCC, but you'll miss it sooner or
4237 \begin_layout Itemize
4238 less ; not really needed for building SDCC, but you'll miss it sooner or
4242 \begin_layout Itemize
4243 svn ; only if you use Subversion access
4246 \begin_layout Standard
4247 If you want to develop something you'll need:
4250 \begin_layout Itemize
4251 python ; for the regression tests
4254 \begin_layout Itemize
4255 gdb ; the gnu debugger, together with the nice GUI
4256 \begin_inset Quotes sld
4260 \begin_inset Quotes srd
4266 \begin_layout Itemize
4267 openssh ; to access the CF or commit changes
4270 \begin_layout Itemize
4271 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
4272 use autoconf-stable!
4275 \begin_layout Standard
4276 rxvt is a nice console with history.
4277 Replace in your cygwin.bat the line
4280 \begin_layout LyX-Code
4285 \begin_layout Standard
4297 \begin_layout Standard
4301 \begin_layout LyX-Code
4302 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
4305 \begin_layout LyX-Code
4306 -bg black -fg white -geometry 100x65 -e bash -
4310 \begin_layout Standard
4322 \begin_layout Standard
4323 Text selected with the mouse is automatically copied to the clipboard, pasting
4324 works with shift-insert.
4328 The other good tip is to make sure you have no //c/-styl
4329 e paths anywhere, use /cygdrive/c/ instead.
4330 Using // invokes a network lookup which is very slow.
4332 \begin_inset Quotes sld
4336 \begin_inset Quotes srd
4339 is too long, you can change it with e.g.
4342 \begin_layout LyX-Code
4346 \begin_layout Standard
4347 SDCC sources use the unix line ending LF.
4348 Life is much easier, if you store the source tree on a drive which is mounted
4350 And use an editor which can handle LF-only line endings.
4351 Make sure not to commit files with windows line endings.
4352 The tabulator spacing
4353 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
4357 used in the project is 8.
4358 Although a tabulator spacing of 8 is a sensible choice for programmers
4359 (it's a power of 2 and allows to display 8/16 bit signed variables without
4360 loosing columns) the plan is to move towards using only spaces in the source.
4363 \begin_layout Subsection
4364 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
4367 \begin_layout Standard
4370 Download the source package
4372 either from the SDCC Subversion repository or from the
4373 \begin_inset LatexCommand \url[snapshot builds]{http://sdcc.sourceforge.net/snap.php}
4379 , it will be named something like sdcc
4383 -yyyymmdd-rrrr.tar.bz2.
4386 SDCC is distributed with all the projects, workspaces, and files you need
4387 to build it using Visual C++ 6.0/NET (except for SDCDB and ucSim).
4388 The workspace name is 'sdcc.dsw'.
4389 Please note that as it is now, all the executables are created in a folder
4393 Once built you need to copy the executables from sdcc
4397 bin before running SDCC.
4402 WARNING: Visual studio is very picky with line terminations; it expects
4403 the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
4404 When using the Subversion repository it's easiest to configure the svn
4405 client to convert automatically for you.
4406 If however you are getting a message such as "This makefile was not generated
4407 by Developer Studio etc.
4409 \begin_inset Quotes srd
4412 when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
4413 need to convert the Unix style line endings to DOS style line endings.
4414 To do so you can use the
4415 \begin_inset Quotes sld
4419 \begin_inset Quotes srd
4422 utility freely available on the internet.
4423 Doug Hawkins reported in the sdcc-user list that this works:
4431 SDCC> unix2dos sdcc.dsw
4437 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
4441 In order to build SDCC with MSVC
4442 you need win32 executables of bison.exe, flex.exe, and gawk.exe.
4443 One good place to get them is
4444 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
4452 Download the file UnxUtils
4453 \begin_inset LatexCommand \index{UnxUtils}
4458 Now you have to install the utilities and setup MSVC so it can locate the
4460 Here there are two alternatives (choose one!):
4463 \begin_layout Enumerate
4468 a) Extract UnxUtils.zip to your C:
4470 hard disk PRESERVING the original paths, otherwise bison won't work.
4471 (If you are using WinZip make certain that 'Use folder names' is selected)
4476 In the Visual C++ IDE click Tools, Options, select the Directory tab, in
4477 'Show directories for:' select 'Executable files', and in the directories
4478 window add a new path: 'C:
4488 (As a side effect, you get a bunch of Unix utilities that
4489 could be useful, such as diff and patch.)
4492 \begin_layout Enumerate
4497 This one avoids extracting a bunch of files you may not
4498 use, but requires some extra work:
4502 a) Create a directory were to put the
4503 tools needed, or use a directory already present.
4510 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and
4511 gawk.exe to such directory WITHOUT preserving the original paths.
4512 (If you are using WinZip make certain that 'Use folder names' is not selected)
4517 ) Rename bison.exe to '_bison.exe'.
4521 d) Create a batch file 'bison.bat' in 'C:
4525 ' and add these lines:
4545 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
4549 Steps 'c' and 'd' are needed
4550 because bison requires by default that the files 'bison.simple' and 'bison.hairy'
4551 reside in some weird Unix directory, '/usr/local/share/' I think.
4552 So it is necessary to tell bison where those files are located if they
4553 are not in such directory.
4554 That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
4559 ) In the Visual C++ IDE click Tools, Options, select the Directory tab,
4560 in 'Show directories for:' select 'Executable files', and in the directories
4561 window add a new path: 'c:
4564 Note that you can use any other path instead of 'c:
4566 util', even the path where the Visual C++ tools are, probably: 'C:
4570 Microsoft Visual Studio
4575 So you don't have to execute step 'e' :)
4578 \begin_layout Standard
4580 Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
4581 the executables from sdcc
4585 bin, and you can compile using SDCC.
4588 \begin_layout Subsection
4589 Building SDCC Using Borland
4592 \begin_layout Enumerate
4593 From the sdcc directory, run the command "make -f Makefile.bcc".
4594 This should regenerate all the .exe files in the bin directory except for
4598 \begin_layout Enumerate
4599 If you modify any source files and need to rebuild, be aware that the dependenci
4600 es may not be correctly calculated.
4601 The safest option is to delete all .obj files and run the build again.
4602 From a Cygwin BASH prompt, this can easily be done with the command (be
4603 sure you are in the sdcc directory):
4613 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
4615 ) -print -exec rm {}
4624 or on Windows NT/2000/XP from the command prompt with the command:
4631 del /s *.obj *.lib *.rul
4634 from the sdcc directory.
4637 \begin_layout Subsection
4638 Windows Install Using a ZIP Package
4641 \begin_layout Enumerate
4642 Download the binary zip package from
4643 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4647 and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
4648 This should unpack to a group of sub-directories.
4649 An example directory structure after unpacking the mingw32 package is:
4654 bin for the executables, c:
4662 lib for the include and libraries.
4665 \begin_layout Enumerate
4666 Adjust your environment variable PATH to include the location of the bin
4667 directory or start sdcc using the full path.
4670 \begin_layout Subsection
4671 Windows Install Using the Setup Program
4672 \begin_inset LatexCommand \label{sub:Windows-Install}
4679 \begin_layout Standard
4680 Download the setup program
4682 sdcc-x.y.z-setup.exe
4684 for an official release from
4687 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
4691 or a setup program for one of the snapshots
4693 sdcc-yyyymmdd-xxxx-setup.exe
4696 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4701 A windows typical installer will guide you through the installation process.
4704 \begin_layout Subsection
4706 \begin_inset LatexCommand \index{VPATH}
4713 \begin_layout Standard
4714 SDCC supports the VPATH feature provided by configure and make.
4715 It allows to separate the source and build trees.
4719 \begin_layout Standard
4746 \begin_layout Standard
4749 tar -xzf sdcc.src.tar.gz\InsetSpace ~
4750 # extract source to directory sdcc
4753 \begin_layout Standard
4756 mkdir sdcc.build\InsetSpace ~
4765 # put output in sdcc.build
4768 \begin_layout Standard
4774 \begin_layout Standard
4777 ../sdcc/configure\InsetSpace ~
4785 # configure is doing all the magic!
4788 \begin_layout Standard
4794 \begin_layout Standard
4800 will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
4801 It automagically computes the variables srcdir, top_srcdir and top_buildir
4807 the generated files will be in ~/sdcc.build, while the source files stay
4810 This is not only usefull for building different binaries, e.g.
4811 when cross compiling.
4812 It also gives you a much better overview in the source tree when all the
4813 generated files are not scattered between the source files.
4814 And the best thing is: if you want to change a file you can leave the original
4815 file untouched in the source directory.
4816 Simply copy it to the build directory, edit it, enter `make clean', `rm
4817 Makefile.dep' and `make'.
4822 will do the rest for you!
4825 \begin_layout Section
4826 Building the Documentation
4829 \begin_layout Standard
4834 \begin_layout Standard
4843 -enable-doc to the configure arguments to build the documentation together
4844 with all the other stuff.
4845 You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
4846 dvips and makeindex) to get the job done.
4847 Another possibility is to change to the doc directory and to type
4851 \begin_inset Quotes srd
4855 \begin_inset Quotes srd
4862 You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
4865 \begin_inset LatexCommand \url{http://www.lyx.org}
4869 as editor is straightforward.
4870 Prebuilt documentation in html and pdf format is available from
4871 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4878 \begin_layout Section
4879 Reading the Documentation
4880 \begin_inset LatexCommand \index{Documentation}
4887 \begin_layout Standard
4888 Currently reading the document in pdf format is recommended, as for unknown
4889 reason the hyperlinks are working there whereas in the html version they
4894 \begin_layout Standard
4895 If you should know why please drop us a note
4903 You'll find the pdf version
4904 \begin_inset LatexCommand \index{PDF version of this document}
4909 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
4917 \begin_inset LatexCommand \index{HTML version of this document}
4922 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
4928 This documentation is in some aspects different from a commercial documentation:
4932 \begin_layout Itemize
4933 It tries to document SDCC for several processor architectures in one document
4934 (commercially these probably would be separate documents/products).
4936 \begin_inset LatexCommand \index{Status of documentation}
4940 currently matches SDCC for mcs51 and DS390 best and does give too few informati
4942 Z80, PIC14, PIC16 and HC08.
4945 \begin_layout Itemize
4946 There are many references pointing away from this documentation.
4947 Don't let this distract you.
4949 was a reference like
4950 \begin_inset LatexCommand \url{http://www.opencores.org}
4954 together with a statement
4955 \begin_inset Quotes sld
4958 some processors which are targetted by SDCC can be implemented in a
4975 \begin_inset LatexCommand \index{FPGA (field programmable gate array)}
4980 \begin_inset Quotes srd
4984 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
4989 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
4994 \begin_inset Quotes sld
4997 have you ever heard of an open source compiler that compiles a subset of
4999 \begin_inset Quotes srd
5002 we expect you to have a quick look there and come back.
5003 If you read this you are on the right track.
5006 \begin_layout Itemize
5007 Some sections attribute more space to problems, restrictions and warnings
5008 than to the solution.
5011 \begin_layout Itemize
5012 The installation section and the section about the debugger is intimidating.
5015 \begin_layout Itemize
5016 There are still lots of typos and there are more different writing styles
5020 \begin_layout Section
5021 Testing the SDCC Compiler
5022 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
5029 \begin_layout Standard
5030 The first thing you should do after installing your SDCC compiler is to
5039 \begin_layout Standard
5049 \begin_inset LatexCommand \index{version}
5056 at the prompt, and the program should run and output its version like:
5061 SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
5065 \begin_layout Standard
5066 If it doesn't run, or gives a message about not finding sdcc program, then
5067 you need to check over your installation.
5068 Make sure that the sdcc bin directory is in your executable search path
5069 defined by the PATH environment setting (
5074 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
5081 Install trouble-shooting for suggestions
5084 Make sure that the sdcc program is in the bin folder, if not perhaps something
5085 did not install correctly.
5093 is commonly installed as described in section
5094 \begin_inset Quotes sld
5097 Install and search paths
5098 \begin_inset Quotes srd
5107 Make sure the compiler works on a very simple example.
5108 Type in the following test.c program using your favorite
5133 \begin_layout Standard
5136 Compile this using the following command:
5145 If all goes well, the compiler will generate a test.asm and test.rel file.
5146 Congratulations, you've just compiled your first program with SDCC.
5147 We used the -c option to tell SDCC not to link the generated code, just
5148 to keep things simple for this step.
5156 The next step is to try it with the linker.
5166 If all goes well the compiler will link with the libraries and produce
5167 a test.ihx output file.
5172 (no test.ihx, and the linker generates warnings), then the problem is most
5181 usr/local/share/sdcc/lib directory
5188 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
5195 Install trouble-shooting for suggestions).
5203 The final test is to ensure
5211 header files and libraries.
5212 Edit test.c and change it to the following:
5230 strcpy(str1, "testing");
5235 \begin_layout Standard
5238 Compile this by typing
5245 This should generate a test.ihx output file, and it should give no warnings
5246 such as not finding the string.h file.
5247 If it cannot find the string.h file, then the problem is that
5251 cannot find the /usr/local/share/sdcc/include directory
5258 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
5265 Install trouble-shooting section for suggestions).
5274 \begin_layout Standard
5286 \begin_inset LatexCommand \index{-\/-print-search-dirs}
5290 to find exactly where SDCC is looking for the include and lib files.
5293 \begin_layout Section
5294 Install Trouble-shooting
5295 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
5300 \begin_inset LatexCommand \index{Install trouble-shooting}
5307 \begin_layout Subsection
5308 If SDCC does not build correctly
5311 \begin_layout Standard
5312 A thing to try is starting from scratch by unpacking the .tgz source package
5313 again in an empty directory.
5321 ./configure 2>&1 | tee configure.log
5335 make 2>&1 | tee make.log
5342 If anything goes wrong, you can review the log files to locate the problem.
5343 Or a relevant part of this can be attached to an email that could be helpful
5344 when requesting help from the mailing list.
5347 \begin_layout Subsection
5349 \begin_inset Quotes sld
5353 \begin_inset Quotes srd
5359 \begin_layout Standard
5361 \begin_inset Quotes sld
5365 \begin_inset Quotes srd
5368 command is a script that analyzes your system and performs some configuration
5369 to ensure the source package compiles on your system.
5370 It will take a few minutes to run, and will compile a few tests to determine
5371 what compiler features are installed.
5374 \begin_layout Subsection
5376 \begin_inset Quotes sld
5380 \begin_inset Quotes srd
5386 \begin_layout Standard
5387 This runs the GNU make tool, which automatically compiles all the source
5388 packages into the final installed binary executables.
5391 \begin_layout Subsection
5393 \begin_inset Quotes sld
5397 \begin_inset Quotes erd
5403 \begin_layout Standard
5404 This will install the compiler, other executables libraries and include
5405 files into the appropriate directories.
5407 \begin_inset LatexCommand \ref{sub:Install-paths}
5413 \begin_inset LatexCommand \ref{sub:Search-Paths}
5418 about install and search paths.
5420 On most systems you will need super-user privilege
5424 \begin_layout Section
5428 \begin_layout Standard
5429 SDCC is not just a compiler, but a collection of tools by various developers.
5430 These include linkers, assemblers, simulators and other components.
5431 Here is a summary of some of the components.
5432 Note that the included simulator and assembler have separate documentation
5433 which you can find in the source package in their respective directories.
5434 As SDCC grows to include support for other processors, other packages from
5435 various developers are included and may have their own sets of documentation.
5440 might want to look at the files which are installed in <installdir>.
5441 At the time of this writing, we find the following programs for gcc-builds:
5446 In <installdir>/bin:
5449 \begin_layout Itemize
5450 sdcc - The compiler.
5453 \begin_layout Itemize
5454 sdcpp - The C preprocessor.
5457 \begin_layout Itemize
5458 asx8051 - The assembler for 8051 type processors.
5461 \begin_layout Itemize
5466 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
5469 \begin_layout Itemize
5470 aslink -The linker for 8051 type processors.
5473 \begin_layout Itemize
5478 link-gbz80 - The Z80 and GameBoy Z80 linkers.
5481 \begin_layout Itemize
5482 s51 - The ucSim 8051 simulator.
5485 \begin_layout Itemize
5486 sdcdb - The source debugger.
5489 \begin_layout Itemize
5490 packihx - A tool to pack (compress) Intel hex files.
5493 \begin_layout Standard
5494 In <installdir>/share/sdcc/include
5497 \begin_layout Itemize
5501 \begin_layout Standard
5502 In <installdir>/share/sdcc/lib
5505 \begin_layout Itemize
5506 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
5510 \begin_layout Standard
5511 In <installdir>/share/sdcc/doc
5514 \begin_layout Itemize
5518 \begin_layout Standard
5519 As development for other processors proceeds, this list will expand to include
5520 executables to support processors like AVR, PIC, etc.
5523 \begin_layout Subsection
5527 \begin_layout Standard
5528 This is the actual compiler, it in turn uses the c-preprocessor and invokes
5529 the assembler and linkage editor.
5532 \begin_layout Subsection
5533 sdcpp - The C-Preprocessor
5536 \begin_layout Standard
5538 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5542 is a modified version of the GNU cpp
5543 \begin_inset LatexCommand \index{cpp|see{sdcpp}}
5548 \begin_inset LatexCommand \url{http://gcc.gnu.org/}
5553 The C preprocessor is used to pull in #include sources, process #ifdef
5554 statements, #defines and so on.
5557 \begin_layout Subsection
5566 - The Assemblers and Linkage Editors
5569 \begin_layout Standard
5570 This is retargettable assembler & linkage editor, it was developed by Alan
5572 John Hartman created the version for 8051, and I (Sandeep) have made some
5573 enhancements and bug fixes for it to work properly with SDCC.
5576 \begin_layout Subsection
5580 \begin_layout Standard
5582 \begin_inset LatexCommand \index{s51}
5586 is a free open source simulator developed by Daniel Drotos.
5587 The simulator is built as part of the build process.
5588 For more information visit Daniel's web site at:
5589 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
5594 It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
5598 \begin_layout Subsection
5599 sdcdb - Source Level Debugger
5602 \begin_layout Standard
5604 \begin_inset LatexCommand \index{SDCDB (debugger)}
5608 is the companion source level debugger.
5609 More about SDCDB in section
5610 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
5615 The current version of the debugger uses Daniel's Simulator S51
5616 \begin_inset LatexCommand \index{s51}
5620 , but can be easily changed to use other simulators.
5623 \begin_layout Chapter
5627 \begin_layout Section
5631 \begin_layout Subsection
5632 Single Source File Projects
5635 \begin_layout Standard
5636 For single source file 8051 projects the process is very simple.
5637 Compile your programs with the following command
5640 "sdcc sourcefile.c".
5644 This will compile, assemble and link your source file.
5645 Output files are as follows:
5648 \begin_layout Itemize
5650 \begin_inset LatexCommand \index{<file>.asm}
5655 \begin_inset LatexCommand \index{Assembler source}
5659 file created by the compiler
5662 \begin_layout Itemize
5664 \begin_inset LatexCommand \index{<file>.lst}
5669 \begin_inset LatexCommand \index{Assembler listing}
5673 file created by the Assembler
5676 \begin_layout Itemize
5678 \begin_inset LatexCommand \index{<file>.rst}
5683 \begin_inset LatexCommand \index{Assembler listing}
5687 file updated with linkedit information, created by linkage editor
5690 \begin_layout Itemize
5692 \begin_inset LatexCommand \index{<file>.sym}
5697 \begin_inset LatexCommand \index{Symbol listing}
5701 for the sourcefile, created by the assembler
5704 \begin_layout Itemize
5706 \begin_inset LatexCommand \index{<file>.rel}
5711 \begin_inset LatexCommand \index{<file>.o}
5716 \begin_inset LatexCommand \index{Object file}
5720 created by the assembler, input to Linkage editor
5723 \begin_layout Itemize
5725 \begin_inset LatexCommand \index{<file>.map}
5730 \begin_inset LatexCommand \index{Memory map}
5734 for the load module, created by the Linker
5737 \begin_layout Itemize
5739 \begin_inset LatexCommand \index{<file>.mem}
5743 - A file with a summary of the memory usage
5746 \begin_layout Itemize
5748 \begin_inset LatexCommand \index{<file>.ihx}
5752 - The load module in Intel hex format
5753 \begin_inset LatexCommand \index{Intel hex format}
5757 (you can select the Motorola S19 format
5758 \begin_inset LatexCommand \index{Motorola S19 format}
5766 \begin_layout Standard
5776 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5781 If you need another format you might want to use
5788 \begin_inset LatexCommand \index{objdump (tool)}
5799 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5804 \begin_inset Note Note
5807 \begin_layout Standard
5814 \begin_inset LatexCommand \vref{sub:Postprocessing-the-Intel}
5819 Both formats are documented in the documentation of srecord
5820 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5827 \begin_layout Itemize
5829 \begin_inset LatexCommand \index{<file>.adb}
5833 - An intermediate file containing debug information needed to create the
5838 \begin_layout Standard
5848 \begin_inset LatexCommand \index{-\/-debug}
5855 \begin_layout Itemize
5857 \begin_inset LatexCommand \index{<file>.cdb}
5861 - An optional file (with -
5865 \begin_layout Standard
5874 -debug) containing debug information.
5875 The format is documented in cdbfileformat.pdf
5878 \begin_layout Itemize
5881 \begin_inset LatexCommand \index{<file> (no extension)}
5885 An optional AOMF or AOMF51
5886 \begin_inset LatexCommand \index{AOMF, AOMF51}
5891 \begin_inset LatexCommand \label{OMF file}
5895 file containing debug information (generated with option -
5899 \begin_layout Standard
5925 ormat is a subformat of the OMF51 format and is commonly used by third party
5927 \begin_inset LatexCommand \index{Debugger}
5931 , simulators, emulators).
5934 \begin_layout Itemize
5936 \begin_inset LatexCommand \index{<file>.dump*}
5940 - Dump file to debug the compiler it self (generated with option -
5944 \begin_layout Standard
5953 -dumpall) (see section
5954 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
5960 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
5966 \begin_inset Quotes sld
5969 Anatomy of the compiler
5970 \begin_inset Quotes srd
5976 \begin_layout Subsection
5977 Postprocessing the Intel Hex
5978 \begin_inset LatexCommand \index{Intel hex format}
5983 \begin_inset LatexCommand \label{sub:Postprocessing-the-Intel}
5990 \begin_layout Standard
5991 In most cases this won't be needed but the Intel Hex file
5992 \begin_inset LatexCommand \index{<file>.ihx}
5996 which is generated by SDCC might include lines of varying length and the
5997 addresses within the file are not guaranteed to be strictly ascending.
5998 If your toolchain or a bootloader does not like this you can use the tool
6004 \begin_inset LatexCommand \index{packihx (tool)}
6008 which is part of the SDCC distribution:
6015 packihx sourcefile.ihx >sourcefile.hex
6022 The separately available
6027 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
6031 package additionally allows to set undefined locations to a predefined
6032 value, to insert checksums
6033 \begin_inset LatexCommand \index{checksum}
6037 of various flavours (crc, add, xor) and to perform other manipulations
6038 (convert, split, crop, offset, ...).
6046 srec_cat\InsetSpace ~
6048 sourcefile.ihx -intel\InsetSpace ~
6050 -o sourcefile.hex -intel
6057 An example for a more complex command line
6061 \begin_layout Standard
6062 the command backfills
6063 \begin_inset LatexCommand \index{backfill unused memory}
6067 unused memory with 0x12 and the overall 16 bit sum of the complete 64 kByte
6069 If the program counter on an mcs51 runs wild the backfill pattern 0x12
6070 will be interpreted as an
6078 (where an emergency routine could sit).
6091 srec_cat\InsetSpace ~
6092 sourcefile.ihx -intel\InsetSpace ~
6094 -fill 0x12 0x0000 0xfffe\InsetSpace ~
6095 -little-endian-checksum-nega
6096 tive 0xfffe 0x02 0x02\InsetSpace ~
6098 -o sourcefile.hex -intel
6107 The srecord package is available at
6108 \begin_inset LatexCommand \url{http://sf.net/projects/srecord}
6115 \begin_layout Subsection
6116 Projects with Multiple Source Files
6119 \begin_layout Standard
6120 SDCC can compile only ONE file at a time.
6121 Let us for example assume that you have a project containing the following
6126 foo1.c (contains some functions)
6128 foo2.c (contains some more functions)
6131 n.c (contains more functions and the function main)
6139 The first two files will need to be compiled separately with the commands:
6171 Then compile the source file containing the
6176 \begin_inset LatexCommand \index{Linker}
6180 the files together with the following command:
6188 foomain.c\InsetSpace ~
6189 foo1.rel\InsetSpace ~
6194 \begin_inset LatexCommand \index{<file>.rel}
6206 can be separately compiled as well:
6217 sdcc foomain.rel foo1.rel foo2.rel
6224 The file containing the
6239 file specified in the command line, since the linkage editor processes
6240 file in the order they are presented to it.
6241 The linker is invoked from SDCC using a script file with extension .lnk
6242 \begin_inset LatexCommand \index{<file>.lnk}
6247 You can view this file to troubleshoot linking problems such as those arising
6248 from missing libraries.
6251 \begin_layout Subsection
6252 Projects with Additional Libraries
6253 \begin_inset LatexCommand \index{Libraries}
6260 \begin_layout Standard
6261 Some reusable routines may be compiled into a library, see the documentation
6262 for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
6266 \begin_inset LatexCommand \index{<file>.lib}
6273 Libraries created in this manner can be included in the command line.
6274 Make sure you include the -L <library-path> option to tell the linker where
6275 to look for these files if they are not in the current directory.
6276 Here is an example, assuming you have the source file
6288 (if that is not the same as your current project):
6295 sdcc foomain.c foolib.lib -L mylib
6306 must be an absolute path name.
6310 The most efficient way to use libraries is
6311 to keep separate modules in separate source files.
6312 The lib file now should name all the modules.rel
6313 \begin_inset LatexCommand \index{<file>.rel}
6318 For an example see the standard library file
6322 in the directory <installdir>/share/lib/small.
6325 \begin_layout Subsection
6326 Using sdcclib to Create and Manage Libraries
6327 \begin_inset LatexCommand \index{sdcclib}
6334 \begin_layout Standard
6335 Alternatively, instead of having a .rel file for each entry on the library
6336 file as described in the preceding section, sdcclib can be used to embed
6337 all the modules belonging to such library in the library file itself.
6338 This results in a larger library file, but it greatly reduces the number
6339 of disk files accessed by the linker.
6340 Additionally, the packed library file contains an index of all include
6341 modules and symbols that significantly speeds up the linking process.
6342 To display a list of options supported by sdcclib type:
6347 \begin_layout Standard
6352 \begin_inset LatexCommand \index{sdcclib}
6363 To create a new library file, start by compiling all the required modules.
6369 \begin_layout Standard
6376 \begin_layout Standard
6383 \begin_layout Standard
6390 \begin_layout Standard
6397 \begin_layout Standard
6406 \begin_layout Standard
6407 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
6409 The next step is to add the .rel files to the library file:
6414 \begin_layout Standard
6418 sdcclib libint.lib _divsint.rel
6421 \begin_inset LatexCommand \index{sdcclib}
6428 \begin_layout Standard
6432 sdcclib libint.lib _divuint.rel
6435 \begin_layout Standard
6439 sdcclib libint.lib _modsint.rel
6442 \begin_layout Standard
6446 sdcclib libint.lib _moduint.rel
6449 \begin_layout Standard
6453 sdcclib libint.lib _mulint.rel
6461 \begin_layout Standard
6470 \begin_layout Standard
6474 sdcclib libint.lib _divsint.rel _divuint.rel _modsint.rel _moduint.rel _mulint.rel
6482 \begin_layout Standard
6483 If the file already exists in the library, it will be replaced.
6484 If a list of .rel files is available, you can tell sdcclib to add those
6486 For example, if the file 'myliblist.txt' contains
6494 \begin_layout Standard
6501 \begin_layout Standard
6508 \begin_layout Standard
6515 \begin_layout Standard
6522 \begin_layout Standard
6534 \begin_layout Standard
6543 \begin_layout Standard
6547 sdcclib -l libint.lib myliblist.txt
6555 \begin_layout Standard
6556 Additionally, you can instruct sdcclib to compiles the files before adding
6557 them to the library.
6558 This is achieved using the environment variables SDCCLIB_CC and/or SDCCLIB_AS.
6567 \begin_layout Standard
6571 set SDCCLIB_CC=sdcc -c
6574 \begin_layout Standard
6578 sdcclib -l libint.lib myliblist.txt
6586 \begin_layout Standard
6587 To see what modules and symbols are included in the library, options -s
6588 and -m are available.
6596 sdcclib -s libint.lib
6599 \begin_inset LatexCommand \index{sdcclib}
6611 \begin_layout Standard
6617 \begin_layout Standard
6623 \begin_layout Standard
6631 \begin_layout Standard
6637 \begin_layout Standard
6643 \begin_layout Standard
6649 \begin_layout Standard
6655 \begin_layout Standard
6663 \begin_layout Standard
6669 \begin_layout Standard
6675 \begin_layout Standard
6683 \begin_layout Standard
6689 \begin_layout Standard
6695 \begin_layout Standard
6701 \begin_layout Standard
6709 \begin_layout Standard
6715 \begin_layout Standard
6726 \begin_layout Standard
6727 If the source files are compiled using -
6731 \begin_layout Standard
6741 \begin_inset LatexCommand \index{-\/-debug}
6745 , the corresponding debug information file .adb will be include in the library
6747 The library files created with sdcclib are plain text files, so they can
6748 be viewed with a text editor.
6749 It is not recomended to modify a library file created with sdcclib using
6750 a text editor, as there are file indexes numbers located accross the file
6751 used by the linker to quickly locate the required module to link.
6752 Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
6753 it can be safely deleted, since all the information required for linking
6754 is embedded in the library file itself.
6755 Library files created using sdcclib are used as described in the preceding
6757 \begin_inset VSpace bigskip
6763 \begin_layout Section
6764 Command Line Options
6765 \begin_inset LatexCommand \index{Command Line Options}
6770 \begin_inset LatexCommand \label{sec:Command-Line-Options}
6777 \begin_layout Subsection
6778 Processor Selection Options
6779 \begin_inset LatexCommand \index{Options processor selection}
6784 \begin_inset LatexCommand \index{Processor selection options}
6792 \labelwidthstring 00.00.0000
6796 \begin_inset LatexCommand \index{-mmcs51}
6802 Generate code for the Intel MCS51
6803 \begin_inset LatexCommand \index{MCS51}
6807 family of processors.
6808 This is the default processor target.
6812 \labelwidthstring 00.00.0000
6816 \begin_inset LatexCommand \index{-mds390}
6822 Generate code for the Dallas DS80C390
6823 \begin_inset LatexCommand \index{DS80C390}
6831 \labelwidthstring 00.00.0000
6835 \begin_inset LatexCommand \index{-mds400}
6841 Generate code for the Dallas DS80C400
6842 \begin_inset LatexCommand \index{DS80C400}
6850 \labelwidthstring 00.00.0000
6854 \begin_inset LatexCommand \index{-mhc08}
6860 Generate code for the Freescale/Motorola HC08
6861 \begin_inset LatexCommand \index{HC08}
6865 family of processors.
6869 \labelwidthstring 00.00.0000
6873 \begin_inset LatexCommand \index{-mz80}
6879 Generate code for the Zilog Z80
6880 \begin_inset LatexCommand \index{Z80}
6884 family of processors.
6888 \labelwidthstring 00.00.0000
6892 \begin_inset LatexCommand \index{-mgbz80}
6898 Generate code for the GameBoy Z80
6899 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
6903 processor (Not actively maintained).
6907 \labelwidthstring 00.00.0000
6911 \begin_inset LatexCommand \index{-mavr}
6917 Generate code for the Atmel AVR
6918 \begin_inset LatexCommand \index{AVR}
6922 processor (Not maintained, not complete).
6923 AVR users should probably have a look at winavr
6924 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
6929 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
6933 , which is based on AVR-port of the gcc compiler.
6936 \begin_layout Standard
6937 \begin_inset Note Note
6940 \begin_layout Standard
6941 I think it is fair to direct users there for now.
6942 Open source is also about avoiding unnecessary work .
6943 But I didn't find the 'official' link.
6952 \labelwidthstring 00.00.0000
6956 \begin_inset LatexCommand \index{-mpic14}
6962 Generate code for the Microchip PIC 14
6963 \begin_inset LatexCommand \index{PIC14}
6967 -bit processors (p16f84 and variants.
6968 In development, not complete).
6971 \begin_layout Standard
6972 \begin_inset Note Note
6975 \begin_layout Standard
6976 p16f627 p16f628 p16f84 p16f873 p16f877?
6985 \labelwidthstring 00.00.0000
6989 \begin_inset LatexCommand \index{-mpic16}
6995 Generate code for the Microchip PIC 16
6996 \begin_inset LatexCommand \index{PIC16}
7000 -bit processors (p18f452 and variants.
7001 In development, not complete).
7005 \labelwidthstring 00.00.0000
7010 Generate code for the Toshiba TLCS-900H
7011 \begin_inset LatexCommand \index{TLCS-900H}
7015 processor (Not maintained, not complete).
7019 \labelwidthstring 00.00.0000
7023 \begin_inset LatexCommand \index{-mxa51}
7029 Generate code for the Phillips XA51
7030 \begin_inset LatexCommand \index{XA51}
7034 processor (Not maintained, not complete).
7037 \begin_layout Standard
7038 \begin_inset VSpace bigskip
7044 \begin_layout Subsection
7045 Preprocessor Options
7046 \begin_inset LatexCommand \index{Options preprocessor}
7051 \begin_inset LatexCommand \index{Preprocessor options}
7056 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
7064 \labelwidthstring 00.00.0000
7068 \begin_inset LatexCommand \index{-I<path>}
7074 The additional location where the preprocessor will look for <..h> or
7075 \begin_inset Quotes eld
7079 \begin_inset Quotes erd
7086 \labelwidthstring 00.00.0000
7090 \begin_inset LatexCommand \index{-D<macro[=value]>}
7096 Command line definition of macros.
7097 Passed to the preprocessor.
7101 \labelwidthstring 00.00.0000
7105 \begin_inset LatexCommand \index{-M}
7111 Tell the preprocessor to output a rule suitable for make describing the
7112 dependencies of each object file.
7113 For each source file, the preprocessor outputs one make-rule whose target
7114 is the object file name for that source file and whose dependencies are
7115 all the files `#include'd in it.
7116 This rule may be a single line or may be continued with `
7118 '-newline if it is long.
7119 The list of rules is printed on standard output instead of the preprocessed
7122 \begin_inset LatexCommand \index{-E}
7130 \labelwidthstring 00.00.0000
7134 \begin_inset LatexCommand \index{-C}
7140 Tell the preprocessor not to discard comments.
7141 Used with the `-E' option.
7145 \labelwidthstring 00.00.0000
7149 \begin_inset LatexCommand \index{-MM}
7160 Like `-M' but the output mentions only the user header files included with
7162 \begin_inset Quotes eld
7166 System header files included with `#include <file>' are omitted.
7170 \labelwidthstring 00.00.0000
7174 \begin_inset LatexCommand \index{-Aquestion(answer)}
7180 Assert the answer answer for question, in case it is tested with a preprocessor
7181 conditional such as `#if #question(answer)'.
7182 `-A-' disables the standard assertions that normally describe the target
7187 \labelwidthstring 00.00.0000
7191 \begin_inset LatexCommand \index{-Umacro}
7197 Undefine macro macro.
7198 `-U' options are evaluated after all `-D' options, but before any `-include'
7199 and `-imacros' options.
7203 \labelwidthstring 00.00.0000
7207 \begin_inset LatexCommand \index{-dM}
7213 Tell the preprocessor to output only a list of the macro definitions that
7214 are in effect at the end of preprocessing.
7215 Used with the `-E' option.
7219 \labelwidthstring 00.00.0000
7223 \begin_inset LatexCommand \index{-dD}
7229 Tell the preprocessor to pass all macro definitions into the output, in
7230 their proper sequence in the rest of the output.
7234 \labelwidthstring 00.00.0000
7238 \begin_inset LatexCommand \index{-dN}
7249 Like `-dD' except that the macro arguments and contents are omitted.
7250 Only `#define name' is included in the output.
7254 \labelwidthstring 00.00.0000
7257 -pedantic-parse-number
7258 \begin_inset LatexCommand \index{pedantic}
7263 \begin_inset LatexCommand \index{-pedantic-parse-number}
7271 \begin_inset LatexCommand \label{lyx:-pedantic-parse-number}
7279 Pedantic parse numbers so that situations like 0xfe-LO_B(3) are parsed properly
7280 and the macro LO_B(3) gets expanded.
7281 See also #pragma pedantic_parse_number
7282 \begin_inset LatexCommand \vpageref{ite:pedantic_parse_number}
7287 \begin_inset LatexCommand \ref{sec:Pragmas}
7293 Note: this functionality is not in conformance with C99 standard!
7297 \labelwidthstring 00.00.0000
7301 preprocessorOption[,preprocessorOption]
7304 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
7309 Pass the preprocessorOption to the preprocessor
7314 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
7319 SDCC uses an adapted version of the preprocessor
7323 of the GNU Compiler Collection
7324 \begin_inset LatexCommand \index{gcc (GNU Compiler Collection)}
7333 \begin_inset LatexCommand \url{http://gcc.gnu.org/}
7337 ), if you need more dedicated options please refer to the GCC\InsetSpace ~
7342 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
7349 \begin_layout Standard
7350 \begin_inset VSpace bigskip
7356 \begin_layout Subsection
7358 \begin_inset LatexCommand \index{Options linker}
7363 \begin_inset LatexCommand \index{Linker options}
7371 \labelwidthstring 00.00.0000
7381 \begin_layout Standard
7393 \begin_inset LatexCommand \index{-\/-lib-path <path>}
7398 \begin_inset LatexCommand \index{-L -\/-lib-path}
7405 <absolute path to additional libraries> This option is passed to the linkage
7406 editor's additional libraries
7407 \begin_inset LatexCommand \index{Libraries}
7412 The path name must be absolute.
7413 Additional library files may be specified in the command line.
7414 See section Compiling programs for more details.
7418 \labelwidthstring 00.00.0000
7425 \begin_layout Standard
7437 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
7442 <Value> The start location of the external ram
7443 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
7447 , default value is 0.
7448 The value entered can be in Hexadecimal or Decimal format, e.g.: -
7452 \begin_layout Standard
7461 -xram-loc 0x8000 or -
7465 \begin_layout Standard
7478 \labelwidthstring 00.00.0000
7485 \begin_layout Standard
7497 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
7502 <Value> The start location of the code
7503 \begin_inset LatexCommand \index{code}
7507 segment, default value 0.
7508 Note when this option is used the interrupt vector table
7509 \begin_inset LatexCommand \index{interrupt vector table}
7513 is also relocated to the given address.
7514 The value entered can be in Hexadecimal or Decimal format, e.g.: -
7518 \begin_layout Standard
7527 -code-loc 0x8000 or -
7531 \begin_layout Standard
7544 \labelwidthstring 00.00.0000
7551 \begin_layout Standard
7563 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
7568 <Value> By default the stack
7569 \begin_inset LatexCommand \index{stack}
7573 is placed after the data segment.
7574 Using this option the stack can be placed anywhere in the internal memory
7576 The value entered can be in Hexadecimal or Decimal format, e.g.
7581 \begin_layout Standard
7590 -stack-loc 0x20 or -
7594 \begin_layout Standard
7604 Since the sp register is incremented before a push or call, the initial
7605 sp will be set to one byte prior the provided value.
7606 The provided value should not overlap any other memory areas such as used
7607 register banks or the data segment and with enough space for the current
7615 \begin_layout Standard
7628 \begin_inset LatexCommand \index{-\/-pack-iram}
7632 option (which is now a default setting) will override this setting, so
7633 you should also specify the
7639 \begin_layout Standard
7652 \begin_inset LatexCommand \index{-\/-no-pack-iram}
7656 option if you need to manually place the stack.
7660 \labelwidthstring 00.00.0000
7667 \begin_layout Standard
7679 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
7684 <Value> By default the external stack
7685 \begin_inset LatexCommand \index{xstack}
7689 is placed after the pdata
7690 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
7695 Using this option the xstack can be placed anywhere in the external memory
7697 The value entered can be in Hexadecimal or Decimal format, e.g.
7702 \begin_layout Standard
7711 -xstack-loc 0x8000 or -
7715 \begin_layout Standard
7725 The provided value should not overlap any other memory areas such as the
7726 pdata or xdata segment and with enough space for the current application.
7730 \labelwidthstring 00.00.0000
7737 \begin_layout Standard
7749 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
7754 <Value> The start location of the internal ram data
7755 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
7760 The value entered can be in Hexadecimal or Decimal format, eg.
7765 \begin_layout Standard
7778 \begin_layout Standard
7788 (By default, the start location of the internal ram data segment is set
7789 as low as possible in memory, taking into account the used register banks
7790 and the bit segment at address 0x20.
7791 For example if register banks 0 and 1 are used without bit variables, the
7792 data segment will be set, if -
7796 \begin_layout Standard
7805 -data-loc is not used, to location 0x10.)
7809 \labelwidthstring 00.00.0000
7816 \begin_layout Standard
7828 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
7833 <Value> The start location of the indirectly addressable internal ram
7834 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
7838 of the 8051, default value is 0x80.
7839 The value entered can be in Hexadecimal or Decimal format, eg.
7844 \begin_layout Standard
7853 -idata-loc 0x88 or -
7857 \begin_layout Standard
7870 \labelwidthstring 00.00.0000
7877 \begin_layout Standard
7889 <Value> The start location of the bit
7890 \begin_inset LatexCommand \index{bit}
7894 addressable internal ram of the 8051.
7900 Instead an option can be passed directly to the linker: -Wl\InsetSpace ~
7905 \labelwidthstring 00.00.0000
7912 \begin_layout Standard
7922 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
7931 The linker output (final object code) is in Intel Hex format.
7932 \begin_inset LatexCommand \index{Intel hex format}
7936 This is the default option.
7937 The format itself is documented in the documentation of srecord
7938 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
7946 \labelwidthstring 00.00.0000
7953 \begin_layout Standard
7963 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
7972 The linker output (final object code) is in Motorola S19 format
7973 \begin_inset LatexCommand \index{Motorola S19 format}
7978 The format itself is documented in the documentation of srecord.
7982 \labelwidthstring 00.00.0000
7989 \begin_layout Standard
7999 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
8004 \begin_inset LatexCommand \index{HC08!Options!-\/-out-fmt-elf}
8013 The linker output (final object code) is in ELF format
8014 \begin_inset LatexCommand \index{ELF format}
8019 (Currently only supported for the HC08
8020 \begin_inset LatexCommand \index{HC08}
8028 \labelwidthstring 00.00.0000
8032 linkOption[,linkOption]
8035 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
8040 \begin_inset LatexCommand \label{lyx:-Wl option}
8045 Pass the linkOption to the linker.
8046 If a bootloader is used an option like
8047 \begin_inset Quotes sld
8052 \begin_inset Quotes srd
8055 would be typical to set the start of the code segment.
8056 Either use the double quotes around this option or use no space (e.g.
8058 See also #pragma constseg and #pragma codeseg in section
8059 \begin_inset LatexCommand \ref{sec:Pragmas}
8064 File sdcc/as/doc/asxhtm.html has more on linker options.
8067 \begin_layout Standard
8068 \begin_inset VSpace bigskip
8074 \begin_layout Subsection
8076 \begin_inset LatexCommand \index{Options MCS51}
8081 \begin_inset LatexCommand \index{MCS51 options}
8089 \labelwidthstring 00.00.0000
8096 \begin_layout Standard
8106 \begin_inset LatexCommand \index{-\/-model-small}
8117 Generate code for Small Model programs, see section Memory Models for more
8119 This is the default model.
8123 \labelwidthstring 00.00.0000
8130 \begin_layout Standard
8140 \begin_inset LatexCommand \index{-\/-model-medium}
8146 Generate code for Medium model programs, see section Memory Models for
8148 If this option is used all source files in the project have to be compiled
8150 It must also be used when invoking the linker.
8154 \labelwidthstring 00.00.0000
8161 \begin_layout Standard
8171 \begin_inset LatexCommand \index{-\/-model-large}
8177 Generate code for Large model programs, see section Memory Models for more
8179 If this option is used all source files in the project have to be compiled
8181 It must also be used when invoking the linker.
8185 \labelwidthstring 00.00.0000
8192 \begin_layout Standard
8202 \begin_inset LatexCommand \index{-\/-xstack}
8208 Uses a pseudo stack in the pdata
8209 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8213 area (usually the first 256 bytes in the external ram) for allocating variables
8214 and passing parameters.
8216 \begin_inset LatexCommand \ref{sub:External-Stack}
8221 External Stack for more details.
8225 \labelwidthstring 00.00.0000
8232 \begin_layout Standard
8245 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
8249 Causes the linker to check if the internal ram usage is within limits of
8254 \labelwidthstring 00.00.0000
8261 \begin_layout Standard
8274 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
8278 Causes the linker to check if the external ram usage is within limits of
8283 \labelwidthstring 00.00.0000
8290 \begin_layout Standard
8303 \begin_inset LatexCommand \index{-\/-code-size <Value>}
8307 Causes the linker to check if the code memory usage is within limits of
8312 \labelwidthstring 00.00.0000
8319 \begin_layout Standard
8332 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
8336 Causes the linker to check if there is at minimum <Value> bytes for stack.
8340 \labelwidthstring 00.00.0000
8347 \begin_layout Standard
8360 \begin_inset LatexCommand \index{-\/-pack-iram}
8364 Causes the linker to use unused register banks for data variables and pack
8365 data, idata and stack together.
8366 This is the default now.
8370 \labelwidthstring 00.00.0000
8377 \begin_layout Standard
8390 \begin_inset LatexCommand \index{-\/-no-pack-iram}
8394 Causes the linker to use old style for allocating memory areas.
8398 \labelwidthstring 00.00.0000
8405 \begin_layout Standard
8418 \begin_inset LatexCommand \index{-\/-acall-ajmp}
8422 Replaces the three byte instructions lcall/ljmp with the two byte instructions
8424 Only use this option if your code is in the same 2k block of memory.
8425 You may need to use this option for some 8051 derivatives which lack the
8426 lcall/ljmp instructions..
8429 \begin_layout Standard
8430 \begin_inset VSpace bigskip
8436 \begin_layout Subsection
8437 DS390 / DS400 Options
8438 \begin_inset LatexCommand \index{Options DS390}
8443 \begin_inset LatexCommand \index{DS390}
8451 \labelwidthstring 00.00.0000
8458 \begin_layout Standard
8470 \begin_inset LatexCommand \index{DS390!Options!-\/-model-flat24}
8480 Generate 24-bit flat mode code.
8481 This is the one and only that the ds390 code generator supports right now
8482 and is default when using
8487 See section Memory Models for more details.
8491 \labelwidthstring 00.00.0000
8498 \begin_layout Standard
8508 \begin_inset LatexCommand \index{DS390!Options!-\/-protect-sp-update}
8514 disable interrupts during ESP:SP updates.
8518 \labelwidthstring 00.00.0000
8525 \begin_layout Standard
8537 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-10bit}
8541 Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
8542 This is the one and only that the ds390 code generator supports right now
8543 and is default when using
8548 In this mode, the stack is located in the lower 1K of the internal RAM,
8549 which is mapped to 0x400000.
8550 Note that the support is incomplete, since it still uses a single byte
8551 as the stack pointer.
8552 This means that only the lower 256 bytes of the potential 1K stack space
8553 will actually be used.
8554 However, this does allow you to reclaim the precious 256 bytes of low RAM
8555 for use for the DATA and IDATA segments.
8556 The compiler will not generate any code to put the processor into 10 bit
8558 It is important to ensure that the processor is in this mode before calling
8559 any re-entrant functions compiled with this option.
8560 In principle, this should work with the
8566 \begin_layout Standard
8576 \begin_inset LatexCommand \index{-\/-stack-auto}
8582 option, but that has not been tested.
8583 It is incompatible with the
8589 \begin_layout Standard
8599 \begin_inset LatexCommand \index{-\/-xstack}
8606 It also only makes sense if the processor is in 24 bit contiguous addressing
8613 \begin_layout Standard
8622 -model-flat24 option
8627 \begin_inset Note Note
8631 \labelwidthstring 00.00.0000
8638 \begin_layout Standard
8647 -stack-8-bit - switches off the 10-bit mode
8656 \labelwidthstring 00.00.0000
8663 \begin_layout Standard
8673 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-probe}
8679 insert call to function __stack_probe at each function prologue.
8683 \labelwidthstring 00.00.0000
8690 \begin_layout Standard
8700 \begin_inset LatexCommand \index{DS390!Options!-\/-tini-libid}
8706 <nnnn> LibraryID used in -mTININative.
8711 \labelwidthstring 00.00.0000
8718 \begin_layout Standard
8728 \begin_inset LatexCommand \index{DS390!Options!-\/-use-accelerator}
8734 generate code for DS390 Arithmetic Accelerator.
8738 \begin_layout Standard
8739 \begin_inset VSpace bigskip
8745 \begin_layout Subsection
8747 \begin_inset LatexCommand \index{Options Z80}
8752 \begin_inset LatexCommand \index{Z80}
8760 \labelwidthstring 00.00.0000
8767 \begin_layout Standard
8779 \begin_inset LatexCommand \index{Z80!Options!-\/-callee-saves-bc}
8789 Force a called function to always save BC.
8793 \labelwidthstring 00.00.0000
8800 \begin_layout Standard
8812 \begin_inset LatexCommand \index{Z80!Options!-\/-no-std-crt0}
8816 When linking, skip the standard crt0.o object file.
8817 You must provide your own crt0.o for your system when linking.
8821 \labelwidthstring 00.00.0000
8828 \begin_layout Standard
8840 \begin_inset LatexCommand \index{Z80!Options!-\/-portmode=<Value>}
8844 Determinate PORT I/O mode (<Value> is z80 or z180).
8848 \labelwidthstring 00.00.0000
8855 \begin_layout Standard
8867 \begin_inset LatexCommand \index{Z80!Options!-\/-asm=<Value>}
8871 Define assembler name (<Value> is rgbds, asxxxx, isas or z80asm).
8875 \labelwidthstring 00.00.0000
8882 \begin_layout Standard
8895 \begin_inset LatexCommand \index{Z80!Options!-\/-codeseg <Value>}
8899 Use <Value> for the code segment name.
8903 \labelwidthstring 00.00.0000
8910 \begin_layout Standard
8923 \begin_inset LatexCommand \index{Z80!Options!-\/-constseg <Value>}
8927 Use <Value> for the const segment name.
8931 \labelwidthstring 00.00.0000
8932 \begin_inset VSpace bigskip
8938 \begin_layout Subsection
8940 \begin_inset LatexCommand \index{Options GBZ80}
8945 \begin_inset LatexCommand \index{GBZ80}
8953 \labelwidthstring 00.00.0000
8960 \begin_layout Standard
8972 \begin_inset LatexCommand \index{GBZ80!Options!-\/-callee-saves-bc}
8982 Force a called function to always save BC.
8986 \labelwidthstring 00.00.0000
8993 \begin_layout Standard
9005 \begin_inset LatexCommand \index{Z80!Options!-\/-no-std-crt0}
9009 When linking, skip the standard crt0.o object file.
9010 You must provide your own crt0.o for your system when linking.
9014 \labelwidthstring 00.00.0000
9021 \begin_inset LatexCommand \index{GBZ80!Options!-bo <Num>}
9025 Use code bank <Num>.
9029 \labelwidthstring 00.00.0000
9036 \begin_inset LatexCommand \index{GBZ80!Options!-ba <Num>}
9040 Use data bank <Num>.
9044 \labelwidthstring 00.00.0000
9051 \begin_layout Standard
9064 \begin_inset LatexCommand \index{GBZ80!Options!-\/-codeseg <Value>}
9068 Use <Value> for the code segment name.
9072 \labelwidthstring 00.00.0000
9079 \begin_layout Standard
9092 \begin_inset LatexCommand \index{GBZ80!Options!-\/-constseg <Value>}
9096 Use <Value> for the const segment name.
9099 \begin_layout Standard
9100 \begin_inset VSpace bigskip
9106 \begin_layout Subsection
9107 Optimization Options
9108 \begin_inset LatexCommand \index{Options optimization}
9113 \begin_inset LatexCommand \index{Optimization options}
9121 \labelwidthstring 00.00.0000
9128 \begin_layout Standard
9138 \begin_inset LatexCommand \index{-\/-nogcse}
9144 Will not do global subexpression elimination, this option may be used when
9145 the compiler creates undesirably large stack/data spaces to store compiler
9155 \begin_inset LatexCommand \index{sloc (spill location)}
9160 A warning message will be generated when this happens and the compiler
9161 will indicate the number of extra bytes it allocated.
9162 It is recommended that this option NOT be used, #pragma\InsetSpace ~
9164 \begin_inset LatexCommand \index{\#pragma nogcse}
9168 can be used to turn off global subexpression elimination
9169 \begin_inset LatexCommand \index{Subexpression elimination}
9173 for a given function only.
9177 \labelwidthstring 00.00.0000
9184 \begin_layout Standard
9194 \begin_inset LatexCommand \index{-\/-noinvariant}
9200 Will not do loop invariant optimizations, this may be turned off for reasons
9201 explained for the previous option.
9202 For more details of loop optimizations performed see Loop Invariants in
9204 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
9209 It is recommended that this option NOT be used, #pragma\InsetSpace ~
9211 \begin_inset LatexCommand \index{\#pragma noinvariant}
9215 can be used to turn off invariant optimizations for a given function only.
9219 \labelwidthstring 00.00.0000
9226 \begin_layout Standard
9236 \begin_inset LatexCommand \index{-\/-noinduction}
9242 Will not do loop induction optimizations, see section strength reduction
9244 It is recommended that this option is NOT used, #pragma\InsetSpace ~
9246 \begin_inset LatexCommand \index{\#pragma noinduction}
9250 can be used to turn off induction optimizations for a given function only.
9254 \labelwidthstring 00.00.0000
9261 \begin_layout Standard
9271 \begin_inset LatexCommand \index{-\/-nojtbound}
9282 Will not generate boundary condition check when switch statements
9283 \begin_inset LatexCommand \index{switch statement}
9287 are implemented using jump-tables.
9289 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
9294 Switch Statements for more details.
9295 It is recommended that this option is NOT used, #pragma\InsetSpace ~
9297 \begin_inset LatexCommand \index{\#pragma nojtbound}
9301 can be used to turn off boundary checking for jump tables for a given function
9306 \labelwidthstring 00.00.0000
9313 \begin_layout Standard
9323 \begin_inset LatexCommand \index{-\/-noloopreverse}
9332 Will not do loop reversal
9333 \begin_inset LatexCommand \index{Loop reversing}
9341 \labelwidthstring 00.00.0000
9346 \begin_layout Standard
9360 \begin_inset LatexCommand \index{-\/-nolabelopt }
9364 Will not optimize labels (makes the dumpfiles more readable).
9368 \labelwidthstring 00.00.0000
9375 \begin_layout Standard
9385 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
9391 Will not memcpy initialized data from code space into xdata space.
9392 This saves a few bytes in code space if you don't have initialized data
9393 \begin_inset LatexCommand \index{Variable initialization}
9401 \labelwidthstring 00.00.0000
9408 \begin_layout Standard
9418 \begin_inset LatexCommand \index{-\/-nooverlay}
9424 The compiler will not overlay parameters and local variables of any function,
9425 see section Parameters and local variables for more details.
9429 \labelwidthstring 00.00.0000
9436 \begin_layout Standard
9446 \begin_inset LatexCommand \index{-\/-no-peep}
9452 Disable peep-hole optimization with built-in rules.
9456 \labelwidthstring 00.00.0000
9463 \begin_layout Standard
9475 \begin_inset LatexCommand \index{-\/-peep-file}
9480 <filename> This option can be used to use additional rules to be used by
9481 the peep hole optimizer.
9483 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
9488 Peep Hole optimizations for details on how to write these rules.
9492 \labelwidthstring 00.00.0000
9499 \begin_layout Standard
9509 \begin_inset LatexCommand \index{-\/-peep-asm}
9515 Pass the inline assembler code through the peep hole optimizer.
9516 This can cause unexpected changes to inline assembler code, please go through
9517 the peephole optimizer
9518 \begin_inset LatexCommand \index{Peephole optimizer}
9522 rules defined in the source file tree '<target>/peeph.def' before using
9527 \labelwidthstring 00.00.0000
9534 \begin_layout Standard
9544 \begin_inset LatexCommand \index{-\/-opt-code-speed}
9550 The compiler will optimize code generation towards fast code, possibly
9551 at the expense of code size.
9555 \labelwidthstring 00.00.0000
9562 \begin_layout Standard
9572 \begin_inset LatexCommand \index{-\/-opt-code-size}
9578 The compiler will optimize code generation towards compact code, possibly
9579 at the expense of code speed.
9582 \begin_layout Standard
9583 \begin_inset VSpace bigskip
9589 \begin_layout Subsection
9591 \begin_inset LatexCommand \index{Options other}
9599 \labelwidthstring 00.00.0000
9607 \begin_layout Standard
9617 \begin_inset LatexCommand \index{-\/-compile-only}
9622 \begin_inset LatexCommand \index{-c -\/-compile-only}
9628 will compile and assemble the source, but will not call the linkage editor.
9632 \labelwidthstring 00.00.0000
9641 \begin_layout Standard
9653 \begin_inset LatexCommand \index{-\/-c1mode}
9659 reads the preprocessed source from standard input and compiles it.
9660 The file name for the assembler output must be specified using the -o option.
9664 \labelwidthstring 00.00.0000
9668 \begin_inset LatexCommand \index{-E}
9674 Run only the C preprocessor.
9675 Preprocess all the C source files specified and output the results to standard
9680 \labelwidthstring 00.00.0000
9685 \begin_inset LatexCommand \index{-o <path/file>}
9691 The output path where everything will be placed or the file name used for
9692 all generated output files.
9693 If the parameter is a path, it must have a trailing slash (or backslash
9694 for the Windows binaries) to be recognized as a path.
9699 Note for Windows users: if the path contains spaces, it should be surrounded
9701 The trailing backslash should be doubled in order to prevent escaping the
9702 final quote, for example:
9705 \begin_inset Quotes sld
9719 \begin_inset Quotes srd
9724 or put after the final quote, for example:
9727 \begin_inset Quotes sld
9737 \begin_inset Quotes srd
9745 The path using slashes for directory delimiters can be used too, for example:
9749 \begin_inset Quotes sld
9752 F:/Projects/test3/output 1/
9753 \begin_inset Quotes srd
9762 \labelwidthstring 00.00.0000
9769 \begin_layout Standard
9779 \begin_inset LatexCommand \index{-\/-stack-auto}
9790 All functions in the source file will be compiled as
9795 \begin_inset LatexCommand \index{reentrant}
9800 the parameters and local variables will be allocated on the stack
9801 \begin_inset LatexCommand \index{stack}
9807 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
9811 Parameters and Local Variables for more details.
9812 If this option is used all source files in the project should be compiled
9814 It automatically implies -
9820 \begin_layout Standard
9831 -int-long-reent and -
9837 \begin_layout Standard
9853 \labelwidthstring 00.00.0000
9860 \begin_layout Standard
9870 \begin_inset LatexCommand \index{-\/-callee-saves}
9875 \begin_inset LatexCommand \label{lyx:--callee-saves-function1[,function2][,function3]...}
9879 function1[,function2][,function3]....
9882 The compiler by default uses a caller saves convention for register saving
9883 across function calls, however this can cause unnecessary register pushing
9884 and popping when calling small functions from larger functions.
9885 This option can be used to switch the register saving convention for the
9886 function names specified.
9887 The compiler will not save registers when calling these functions, no extra
9888 code will be generated at the entry and exit (function prologue
9891 \begin_inset LatexCommand \index{function prologue}
9900 \begin_inset LatexCommand \index{function epilogue}
9906 ) for these functions to save and restore the registers used by these functions,
9907 this can SUBSTANTIALLY reduce code and improve run time performance of
9909 In the future the compiler (with inter procedural analysis) will be able
9910 to determine the appropriate scheme to use for each function call.
9911 DO NOT use this option for built-in functions such as _mulint..., if this
9912 option is used for a library function the appropriate library function
9913 needs to be recompiled with the same option.
9914 If the project consists of multiple source files then all the source file
9915 should be compiled with the same -
9919 \begin_layout Standard
9928 -callee-saves option string.
9929 Also see #pragma\InsetSpace ~
9931 \begin_inset LatexCommand \index{\#pragma callee\_saves}
9936 \begin_inset LatexCommand \vpageref{ite:callee_saves-function1[,function2[,function3...]]--}
9944 \labelwidthstring 00.00.0000
9951 \begin_layout Standard
9961 \begin_inset LatexCommand \index{-\/-all-callee-saves}
9975 \begin_layout Standard
9984 -callee-saves will be applied to all functions by default.
9988 \labelwidthstring 00.00.0000
9995 \begin_layout Standard
10005 \begin_inset LatexCommand \index{-\/-debug}
10014 When this option is used the compiler will generate debug information.
10015 The debug information collected in a file with .cdb extension can be used
10017 For more information see documentation for SDCDB.
10018 Another file with no extension contains debug information in AOMF or AOMF51
10019 \begin_inset LatexCommand \index{AOMF, AOMF51}
10023 format which is commonly used by third party tools.
10027 \labelwidthstring 00.00.0000
10031 \begin_inset LatexCommand \index{-S}
10042 Stop after the stage of compilation proper; do not assemble.
10043 The output is an assembler code file for the input file specified.
10047 \labelwidthstring 00.00.0000
10054 \begin_layout Standard
10064 \begin_inset LatexCommand \index{-\/-int-long-reent}
10070 Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
10071 Note by default these libraries are compiled as non-reentrant.
10072 See section Installation for more details.
10076 \labelwidthstring 00.00.0000
10083 \begin_layout Standard
10093 \begin_inset LatexCommand \index{-\/-cyclomatic}
10102 This option will cause the compiler to generate an information message for
10103 each function in the source file.
10104 The message contains some
10108 information about the function.
10109 The number of edges and nodes the compiler detected in the control flow
10110 graph of the function, and most importantly the
10112 cyclomatic complexity
10113 \begin_inset LatexCommand \index{Cyclomatic complexity}
10119 see section on Cyclomatic Complexity for more details.
10123 \labelwidthstring 00.00.0000
10130 \begin_layout Standard
10140 \begin_inset LatexCommand \index{-\/-float-reent}
10146 Floating point library is compiled as reentrant
10147 \begin_inset LatexCommand \index{reentrant}
10152 See section Installation for more details.
10156 \labelwidthstring 00.00.0000
10163 \begin_layout Standard
10173 \begin_inset LatexCommand \index{-\/-funsigned-char}
10179 The default signedness for every type is
10184 In some embedded environments the default signedness of
10193 To set the signess for characters to unsigned, use the option -
10199 \begin_layout Standard
10211 If this option is set and no signedness keyword (unsigned/signed) is given,
10212 a char will be signed.
10213 All other types are unaffected.
10217 \labelwidthstring 00.00.0000
10224 \begin_layout Standard
10234 \begin_inset LatexCommand \index{-\/-main-return}
10240 This option can be used if the code generated is called by a monitor program
10241 or if the main routine includes an endless loop.
10242 This option results in slightly smaller code and saves two bytes of stack
10244 The return from the 'main'
10245 \begin_inset LatexCommand \index{main return}
10249 function will return to the function calling main.
10250 The default setting is to lock up i.e.
10259 \labelwidthstring 00.00.0000
10266 \begin_layout Standard
10276 \begin_inset LatexCommand \index{-\/-nostdinc}
10282 This will prevent the compiler from passing on the default include path
10283 to the preprocessor.
10287 \labelwidthstring 00.00.0000
10294 \begin_layout Standard
10304 \begin_inset LatexCommand \index{-\/-nostdlib}
10310 This will prevent the compiler from passing on the default library
10311 \begin_inset LatexCommand \index{Libraries}
10315 path to the linker.
10319 \labelwidthstring 00.00.0000
10326 \begin_layout Standard
10336 \begin_inset LatexCommand \index{-\/-verbose}
10342 Shows the various actions the compiler is performing.
10346 \labelwidthstring 00.00.0000
10350 \begin_inset LatexCommand \index{-V}
10356 Shows the actual commands the compiler is executing.
10360 \labelwidthstring 00.00.0000
10367 \begin_layout Standard
10377 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
10383 Hides your ugly and inefficient c-code from the asm file, so you can always
10384 blame the compiler :)
10388 \labelwidthstring 00.00.0000
10395 \begin_layout Standard
10405 \begin_inset LatexCommand \index{-\/-no-gen-comments}
10411 Include code generator and peep-hole comments in the generated asm files.
10415 \labelwidthstring 00.00.0000
10422 \begin_layout Standard
10432 \begin_inset LatexCommand \index{-\/-no-peep-comments}
10438 Don't include peep-hole comments in the generated asm files even if -
10444 \begin_layout Standard
10455 -fverbose-asm option is specified.
10459 \labelwidthstring 00.00.0000
10466 \begin_layout Standard
10476 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
10482 Include i-codes in the asm file.
10483 Sounds like noise but is most helpful for debugging the compiler itself.
10487 \labelwidthstring 00.00.0000
10494 \begin_layout Standard
10504 \begin_inset LatexCommand \index{pedantic}
10509 \begin_inset LatexCommand \index{-\/-less-pedantic}
10516 \begin_inset LatexCommand \label{lyx:--less-pedantic}
10520 Disable some of the more pedantic warnings
10521 \begin_inset LatexCommand \index{Warnings}
10526 For more details, see the less_pedantic pragma
10527 \begin_inset LatexCommand \vpageref{ite:less_pedantic}
10535 \labelwidthstring 00.00.0000
10542 \begin_layout Standard
10551 -disable-warning\InsetSpace ~
10553 \begin_inset LatexCommand \index{-\/-disable-warning}
10559 Disable specific warning with number <nnnn>.
10563 \labelwidthstring 00.00.0000
10570 \begin_layout Standard
10580 \begin_inset LatexCommand \index{-\/-Werror}
10586 Treat all warnings as errors.
10590 \labelwidthstring 00.00.0000
10597 \begin_layout Standard
10607 \begin_inset LatexCommand \index{-\/-print-search-dirs}
10613 Display the directories in the compiler's search path
10617 \labelwidthstring 00.00.0000
10624 \begin_layout Standard
10634 \begin_inset LatexCommand \index{-\/-vc}
10640 Display errors and warnings using MSVC style, so you can use SDCC with
10641 the visual studio IDE
10642 \begin_inset LatexCommand \index{IDE}
10647 With SDCC both offering a GCC-like (the default) and a MSVC-like
10648 \begin_inset LatexCommand \index{MSVC output style}
10652 output style, integration into most programming editors should be straightforwa
10657 \labelwidthstring 00.00.0000
10664 \begin_layout Standard
10674 \begin_inset LatexCommand \index{-\/-use-stdout}
10680 Send errors and warnings to stdout instead of stderr.
10684 \labelwidthstring 00.00.0000
10688 asmOption[,asmOption]
10691 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
10696 Pass the asmOption to the assembler
10697 \begin_inset LatexCommand \index{Options assembler}
10702 \begin_inset LatexCommand \index{Assembler options}
10707 See file sdcc/as/doc/asxhtm.html for assembler options.cd
10711 \labelwidthstring 00.00.0000
10718 \begin_layout Standard
10728 \begin_inset LatexCommand \index{-\/-std-sdcc89}
10734 Generally follow the C89 standard, but allow SDCC features that conflict
10735 with the standard (default).
10739 \labelwidthstring 00.00.0000
10746 \begin_layout Standard
10756 \begin_inset LatexCommand \index{-\/-std-c89}
10762 Follow the C89 standard and disable SDCC features that conflict with the
10767 \labelwidthstring 00.00.0000
10774 \begin_layout Standard
10784 \begin_inset LatexCommand \index{-\/-std-sdcc99}
10790 Generally follow the C99 standard, but allow SDCC features that conflict
10791 with the standard (incomplete support).
10795 \labelwidthstring 00.00.0000
10802 \begin_layout Standard
10812 \begin_inset LatexCommand \index{-\/-std-sdcc99}
10818 Follow the C99 standard and disable SDCC features that conflict with the
10819 standard (incomplete support).
10823 \labelwidthstring 00.00.0000
10830 \begin_layout Standard
10842 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
10847 \begin_inset LatexCommand \label{lyx:-codeseg}
10852 <Name> The name to be used for the code
10853 \begin_inset LatexCommand \index{code}
10857 segment, default CSEG.
10858 This is useful if you need to tell the compiler to put the code in a special
10859 segment so you can later on tell the linker to put this segment in a special
10861 Can be used for instance when using bank switching to put the code in a
10866 \labelwidthstring 00.00.0000
10873 \begin_layout Standard
10885 \begin_inset LatexCommand \index{-\/-constseg <Value>}
10890 <Name> The name to be used for the const
10891 \begin_inset LatexCommand \index{const}
10895 segment, default CONST.
10896 This is useful if you need to tell the compiler to put the const data in
10897 a special segment so you can later on tell the linker to put this segment
10898 in a special place in memory.
10899 Can be used for instance when using bank switching to put the const data
10904 \labelwidthstring 00.00.0000
10911 \begin_layout Standard
10920 -fdollars-in-identifiers
10921 \begin_inset LatexCommand \index{-\/-fdollars-in-identifiers}
10927 Permit '$' as an identifier character.
10931 \labelwidthstring 00.00.0000
10938 \begin_layout Standard
10950 \begin_inset LatexCommand \index{-\/-more-pedantic}
10955 \begin_inset LatexCommand \index{pedantic}
10965 a SDCC compiler option but if you want
10969 warnings you can use a separate tool dedicated to syntax checking like
10971 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
10976 \begin_inset LatexCommand \index{lint (syntax checking tool)}
10981 \begin_inset LatexCommand \url{http://www.splint.org}
10986 To make your source files parseable by splint you will have to include
10992 \begin_inset LatexCommand \index{splint (syntax checking tool)}
10996 in your source file and add brackets around extended keywords (like
10999 \begin_inset Quotes sld
11012 \begin_inset Quotes srd
11020 \begin_inset Quotes sld
11023 __interrupt\InsetSpace ~
11025 \begin_inset Quotes srd
11033 Splint has an excellent on line manual at
11034 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
11038 and it's capabilities go beyond pure syntax checking.
11039 You'll need to tell splint the location of SDCC's include files so a typical
11040 command line could look like this:
11044 splint\InsetSpace ~
11046 /usr/local/share/sdcc/include/mcs51/\InsetSpace ~
11052 \labelwidthstring 00.00.0000
11059 \begin_layout Standard
11071 \begin_inset LatexCommand \index{-\/-short-is-8bits}
11076 \begin_inset LatexCommand \label{lyx:--short-is-8bits}
11080 Treat short as 8-bit (for backward compatibility with older versions of
11081 compiler - see section
11082 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
11089 \begin_layout Standard
11090 \begin_inset VSpace bigskip
11096 \begin_layout Subsection
11097 Intermediate Dump Options
11098 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
11103 \begin_inset LatexCommand \index{Options intermediate dump}
11108 \begin_inset LatexCommand \index{Intermediate dump options}
11115 \begin_layout Standard
11116 The following options are provided for the purpose of retargetting and debugging
11118 They provide a means to dump the intermediate code (iCode
11119 \begin_inset LatexCommand \index{iCode}
11123 ) generated by the compiler in human readable form at various stages of
11124 the compilation process.
11125 More on iCodes see chapter
11126 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
11131 \begin_inset Quotes srd
11134 The anatomy of the compiler
11135 \begin_inset Quotes srd
11142 \labelwidthstring 00.00.0000
11149 \begin_layout Standard
11159 \begin_inset LatexCommand \index{-\/-dumpraw}
11165 This option will cause the compiler to dump the intermediate code into
11168 <source filename>.dumpraw
11170 just after the intermediate code has been generated for a function, i.e.
11171 before any optimizations are done.
11173 \begin_inset LatexCommand \index{Basic blocks}
11177 at this stage ordered in the depth first number, so they may not be in
11178 sequence of execution.
11182 \labelwidthstring 00.00.0000
11189 \begin_layout Standard
11199 \begin_inset LatexCommand \index{-\/-dumpgcse}
11205 Will create a dump of iCodes, after global subexpression elimination
11206 \begin_inset LatexCommand \index{Global subexpression elimination}
11210 , into a file named
11212 <source filename>.dumpgcse.
11216 \labelwidthstring 00.00.0000
11223 \begin_layout Standard
11233 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
11239 Will create a dump of iCodes, after deadcode elimination
11240 \begin_inset LatexCommand \index{Dead-code elimination}
11244 , into a file named
11246 <source filename>.dumpdeadcode.
11250 \labelwidthstring 00.00.0000
11257 \begin_layout Standard
11267 \begin_inset LatexCommand \index{-\/-dumploop}
11276 Will create a dump of iCodes, after loop optimizations
11277 \begin_inset LatexCommand \index{Loop optimization}
11281 , into a file named
11283 <source filename>.dumploop.
11287 \labelwidthstring 00.00.0000
11294 \begin_layout Standard
11304 \begin_inset LatexCommand \index{-\/-dumprange}
11313 Will create a dump of iCodes, after live range analysis
11314 \begin_inset LatexCommand \index{Live range analysis}
11318 , into a file named
11320 <source filename>.dumprange.
11324 \labelwidthstring 00.00.0000
11331 \begin_layout Standard
11341 \begin_inset LatexCommand \index{-\/-dumlrange}
11347 Will dump the life ranges
11348 \begin_inset LatexCommand \index{Live range analysis}
11356 \labelwidthstring 00.00.0000
11363 \begin_layout Standard
11373 \begin_inset LatexCommand \index{-\/-dumpregassign}
11382 Will create a dump of iCodes, after register assignment
11383 \begin_inset LatexCommand \index{Register assignment}
11387 , into a file named
11389 <source filename>.dumprassgn.
11393 \labelwidthstring 00.00.0000
11400 \begin_layout Standard
11410 \begin_inset LatexCommand \index{-\/-dumplrange}
11416 Will create a dump of the live ranges of iTemp's
11420 \labelwidthstring 00.00.0000
11427 \begin_layout Standard
11437 \begin_inset LatexCommand \index{-\/-dumpall}
11448 Will cause all the above mentioned dumps to be created.
11451 \begin_layout Standard
11452 \begin_inset VSpace bigskip
11458 \begin_layout Subsection
11459 Redirecting output on Windows Shells
11462 \begin_layout Standard
11463 By default SDCC writes its error messages to
11464 \begin_inset Quotes sld
11468 \begin_inset Quotes srd
11472 To force all messages to
11473 \begin_inset Quotes sld
11477 \begin_inset Quotes srd
11489 \begin_layout Standard
11504 \begin_inset LatexCommand \index{-\/-use-stdout}
11509 Additionally, if you happen to have visual studio installed in your windows
11510 machine, you can use it to compile your sources using a custom build and
11517 \begin_layout Standard
11529 \begin_inset LatexCommand \index{-\/-vc}
11534 Something like this should work:
11553 \begin_layout Standard
11572 \begin_layout Standard
11584 -model-large -c $(InputPath)
11587 \begin_inset VSpace bigskip
11593 \begin_layout Section
11594 Environment variables
11595 \begin_inset LatexCommand \index{Environment variables}
11602 \begin_layout Standard
11603 SDCC recognizes the following environment variables:
11607 \labelwidthstring 00.00.0000
11611 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
11617 SDCC installs a signal handler
11618 \begin_inset LatexCommand \index{signal handler}
11622 to be able to delete temporary files after an user break (^C) or an exception.
11623 If this environment variable is set, SDCC won't install the signal handler
11624 in order to be able to debug SDCC.
11628 \labelwidthstring 00.00.0000
11634 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
11640 Path, where temporary files will be created.
11641 The order of the variables is the search order.
11642 In a standard *nix environment these variables are not set, and there's
11643 no need to set them.
11644 On Windows it's recommended to set one of them.
11648 \labelwidthstring 00.00.0000
11652 \begin_inset LatexCommand \index{SDCC\_HOME}
11659 \begin_inset LatexCommand \ref{sub:Install-paths}
11665 \begin_inset Quotes sld
11669 \begin_inset Quotes srd
11676 \labelwidthstring 00.00.0000
11680 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
11687 \begin_inset LatexCommand \ref{sub:Search-Paths}
11693 \begin_inset Quotes sld
11697 \begin_inset Quotes srd
11704 \labelwidthstring 00.00.0000
11708 \begin_inset LatexCommand \index{SDCC\_LIB}
11715 \begin_inset LatexCommand \ref{sub:Search-Paths}
11721 \begin_inset Quotes sld
11725 \begin_inset Quotes srd
11731 \begin_layout Standard
11732 There are some more environment variables recognized by SDCC, but these
11733 are solely used for debugging purposes.
11734 They can change or disappear very quickly, and will never be documented.
11735 \begin_inset VSpace bigskip
11741 \begin_layout Section
11742 Storage Class Language Extensions
11745 \begin_layout Subsection
11746 MCS51/DS390 Storage Class
11747 \begin_inset LatexCommand \index{Storage class}
11751 Language Extensions
11754 \begin_layout Standard
11755 In addition to the ANSI storage classes SDCC allows the following MCS51
11756 specific storage classes:
11759 \begin_layout Subsubsection
11761 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
11766 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
11771 \begin_inset LatexCommand \index{near (storage class)}
11776 \begin_inset LatexCommand \index{\_\_near (storage class)}
11783 \begin_layout Standard
11788 storage class for the Small Memory model (
11796 or the more ANSI-C compliant forms
11804 can be used synonymously).
11805 Variables declared with this storage class will be allocated in the directly
11806 addressable portion of the internal RAM of a 8051, e.g.:
11809 \begin_layout Verse
11812 __data unsigned char test_data;
11815 \begin_layout Standard
11816 Writing 0x01 to this variable generates the assembly code:
11819 \begin_layout Verse
11822 75*00 01\InsetSpace ~
11830 \begin_layout Subsubsection
11832 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11837 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
11842 \begin_inset LatexCommand \index{far (storage class)}
11847 \begin_inset LatexCommand \index{\_\_far (storage class)}
11854 \begin_layout Standard
11855 Variables declared with this storage class will be placed in the external
11861 storage class for the Large Memory model, e.g.:
11864 \begin_layout Verse
11867 __xdata unsigned char test_xdata;
11870 \begin_layout Standard
11871 Writing 0x01 to this variable generates the assembly code:
11874 \begin_layout Verse
11877 90s00r00\InsetSpace ~
11908 \begin_layout Subsubsection
11910 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
11915 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
11922 \begin_layout Standard
11923 Variables declared with this storage class will be allocated into the indirectly
11924 addressable portion of the internal ram of a 8051, e.g.:
11927 \begin_layout Verse
11930 __idata unsigned char test_idata;
11933 \begin_layout Standard
11934 Writing 0x01 to this variable generates the assembly code:
11937 \begin_layout Verse
11964 \begin_layout Standard
11965 Please note, the first 128 byte of idata physically access the same RAM
11966 as the data memory.
11967 The original 8051 had 128 byte idata memory, nowadays most devices have
11968 256 byte idata memory.
11970 \begin_inset LatexCommand \index{stack}
11974 is located in idata memory.
11977 \begin_layout Subsubsection
11979 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
11984 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
11991 \begin_layout Standard
11992 Paged xdata access is just as straightforward as using the other addressing
11994 It is typically located at the start of xdata and has a maximum size of
11996 The following example writes 0x01 to the pdata variable.
11997 Please note, pdata access physically accesses xdata memory.
11998 The high byte of the address is determined by port P2
11999 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
12003 (or in case of some 8051 variants by a separate Special Function Register,
12005 \begin_inset LatexCommand \ref{sub:MCS51-variants}
12014 storage class for the Medium Memory model, e.g.:
12017 \begin_layout Verse
12020 __pdata unsigned char test_pdata;
12023 \begin_layout Standard
12024 Writing 0x01 to this variable generates the assembly code:
12027 \begin_layout Verse
12036 mov r0,#_test_pdata
12058 \begin_layout Standard
12063 \begin_layout Standard
12073 \begin_inset LatexCommand \index{-\/-xstack}
12077 option is used the pdata memory area is followed by the xstack memory area
12078 and the sum of their sizes is limited to 256 bytes.
12081 \begin_layout Subsubsection
12083 \begin_inset LatexCommand \index{code}
12088 \begin_inset LatexCommand \index{\_\_code}
12095 \begin_layout Standard
12096 'Variables' declared with this storage class will be placed in the code
12100 \begin_layout Verse
12103 __code unsigned char test_code;
12106 \begin_layout Standard
12107 Read access to this variable generates the assembly code:
12110 \begin_layout Verse
12113 90s00r6F\InsetSpace ~
12116 mov dptr,#_test_code
12141 \begin_layout Standard
12146 indexed arrays of characters in code memory can be accessed efficiently:
12149 \begin_layout Verse
12152 __code char test_array[] = {'c','h','e','a','p'};
12155 \begin_layout Standard
12156 Read access to this array using an 8-bit unsigned index generates the assembly
12160 \begin_layout Verse
12172 \begin_layout Verse
12175 90s00r41\InsetSpace ~
12178 mov dptr,#_test_array
12181 \begin_layout Verse
12196 \begin_layout Subsubsection
12198 \begin_inset LatexCommand \index{bit}
12203 \begin_inset LatexCommand \index{\_\_bit}
12210 \begin_layout Standard
12211 This is a data-type and a storage class specifier.
12212 When a variable is declared as a bit, it is allocated into the bit addressable
12213 memory of 8051, e.g.:
12216 \begin_layout Verse
12222 \begin_layout Standard
12223 Writing 1 to this variable generates the assembly code:
12226 \begin_layout Verse
12240 \begin_layout Standard
12241 The bit addressable memory consists of 128 bits which are located from 0x20
12242 to 0x2f in data memory.
12245 Apart from this 8051 specific storage class most architectures support
12247 \begin_inset LatexCommand \index{bitfields}
12255 \begin_layout Standard
12256 Not really meant as examples, but nevertheless showing what bitfields are
12257 about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
12263 In accordance with ISO/IEC 9899 bits and bitfields without an explicit
12264 signed modifier are implemented as unsigned.
12267 \begin_layout Subsubsection
12269 \begin_inset LatexCommand \index{sfr}
12274 \begin_inset LatexCommand \index{\_\_sfr}
12279 \begin_inset LatexCommand \index{sfr16}
12284 \begin_inset LatexCommand \index{\_\_sfr16}
12289 \begin_inset LatexCommand \index{sfr32}
12294 \begin_inset LatexCommand \index{\_\_sfr32}
12299 \begin_inset LatexCommand \index{\_\_sbit}
12304 \begin_inset LatexCommand \index{sbit}
12311 \begin_layout Standard
12312 Like the bit keyword,
12314 sfr / sfr16 / sfr32 / sbit
12316 signify both a data-type and storage class, they are used to describe the
12337 variables of a 8051, eg:
12340 \begin_layout Verse
12344 \begin_inset LatexCommand \index{at}
12349 \begin_inset LatexCommand \index{\_\_at}
12353 (0x80) P0;\InsetSpace ~
12354 /* special function register P0 at location 0x80 */
12359 special function register combination for timer 0
12363 with the high byte at
12364 location 0x8C and the low byte at location 0x8A */
12366 __sfr16 __at (0x8C8A)
12372 \begin_inset LatexCommand \index{at}
12377 \begin_inset LatexCommand \index{\_\_at}
12381 (0xd7) CY;\InsetSpace ~
12383 \begin_inset LatexCommand \index{Flags}
12388 \begin_inset LatexCommand \index{Carry flag}
12395 \begin_layout Standard
12396 Special function registers which are located on an address dividable by
12397 8 are bit-addressable, an
12401 addresses a specific bit within these sfr.
12403 16 Bit and 32 bit special function
12404 register combinations which require a certain access order are better not
12414 Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
12415 this is not guaranteed.
12420 \begin_layout Standard
12421 Please note, if you use a header file which was written for another compiler
12422 then the sfr / sfr16 / sfr32 / sbit Storage Class extensions will most
12428 Specifically the syntax
12431 sfr P0 = 0x80;\InsetSpace ~
12438 by SDCC to an assignment of 0x80 to a variable called P0
12441 \begin_inset Marginal
12444 \begin_layout Standard
12456 Nevertheless it is possible to write header files
12457 \begin_inset LatexCommand \index{Header files}
12462 \begin_inset LatexCommand \index{Include files}
12466 which can be shared among different compilers (see section
12467 \begin_inset LatexCommand \ref{sec:Porting-code-to-other-compilers}
12475 \begin_layout Subsubsection
12477 \begin_inset LatexCommand \index{Pointer}
12481 to MCS51/DS390 specific memory spaces
12484 \begin_layout Standard
12485 SDCC allows (via language extensions) pointers to explicitly point to any
12486 of the memory spaces
12487 \begin_inset LatexCommand \index{Memory model}
12492 In addition to the explicit pointers, the compiler uses (by default) generic
12493 pointers which can be used to point to any of the memory spaces.
12498 declaration examples:
12501 \begin_layout Verse
12504 /* pointer physically in internal ram pointing to object in external ram
12507 __xdata unsigned char * __data p;
12511 /* pointer physically in external ram
12512 pointing to object in internal ram */
12514 __data unsigned char * __xdata p;
12519 pointer physically in code rom pointing to data in xdata space */
12522 unsigned char * __code p;
12526 /* pointer physically in code space pointing to
12527 data in code space */
12529 __code unsigned char * __code p;
12534 physically located in xdata space */
12536 unsigned char * __xdata p;
12541 pointer physically located in default memory space */
12548 the following is a function pointer
12549 \begin_inset LatexCommand \index{function pointer}
12553 physically located in data space */
12555 char (* __data fp)(void);
12558 \begin_layout Standard
12559 Well you get the idea.
12564 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
12577 The highest order byte of the
12581 pointers contains the data space information.
12582 Assembler support routines are called whenever data is stored or retrieved
12588 These are useful for developing reusable library
12589 \begin_inset LatexCommand \index{Libraries}
12594 Explicitly specifying the pointer
12595 \begin_inset LatexCommand \index{pointer}
12599 type will generate the most efficient code.
12602 \begin_layout Subsubsection
12603 Notes on MCS51 memory
12604 \begin_inset LatexCommand \index{MCS51 memory}
12611 \begin_layout Standard
12612 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
12613 RAM memory which is structured as follows:
12617 - Bytes 00-1F - 32 bytes to hold
12618 up to 4 banks of the registers R0 to R7,
12620 - Bytes 20-2F - 16 bytes to hold
12622 \begin_inset LatexCommand \index{bit}
12628 - Bytes 30-7F - 80 bytes for general purpose use.
12633 \begin_layout Standard
12634 Additionally some members of the MCS51 family may have up to 128 bytes of
12635 additional, indirectly addressable, internal RAM memory (
12640 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
12645 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
12650 Furthermore, some chips may have some built in external memory (
12655 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
12660 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
12664 ) which should not be confused with the internal, directly addressable RAM
12670 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
12675 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
12680 Sometimes this built in
12684 memory has to be activated before using it (you can probably find this
12685 information on the datasheet of the microcontroller your are using, see
12687 \begin_inset LatexCommand \ref{sub:Startup-Code}
12695 \begin_layout Standard
12696 Normally SDCC will only use the first bank
12697 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
12701 of registers (register bank 0), but it is possible to specify that other
12702 banks of registers (keyword
12709 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12714 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12720 ) should be used for example in interrupt
12721 \begin_inset LatexCommand \index{interrupt}
12726 \begin_inset LatexCommand \index{\_\_interrupt}
12731 By default, the compiler will place the stack after the last byte of allocated
12732 memory for variables.
12733 For example, if the first 2 banks of registers are used, and only four
12738 variables, it will position the base of the internal stack at address 20
12740 This implies that as the stack
12741 \begin_inset LatexCommand \index{stack}
12745 grows, it will use up the remaining register banks, and the 16 bytes used
12746 by the 128 bit variables, and 80 bytes for general purpose use.
12747 If any bit variables are used, the data variables will be placed in unused
12748 register banks and after the byte holding the last bit variable.
12749 For example, if register banks 0 and 1 are used, and there are 9 bit variables
12754 variables will be placed starting from address 0x10 to 0x20 and continue
12760 \begin_layout Standard
12770 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
12774 to specify the start address of the
12782 \begin_layout Standard
12792 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
12796 to specify the size of the total internal RAM (
12810 \begin_layout Standard
12811 By default the 8051 linker will place the stack after the last byte of (i)data
12817 \begin_layout Standard
12827 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
12831 allows you to specify the start of the stack, i.e.
12832 you could start it after any data in the general purpose area.
12833 If your microcontroller has additional indirectly addressable internal
12838 ) you can place the stack on it.
12839 You may also need to use -
12843 \begin_layout Standard
12853 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
12857 to set the start address of the external RAM (
12865 \begin_layout Standard
12875 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
12879 to specify its size.
12880 Same goes for the code memory, using -
12884 \begin_layout Standard
12894 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
12902 \begin_layout Standard
12912 \begin_inset LatexCommand \index{-\/-code-size <Value>}
12917 If in doubt, don't specify any options and see if the resulting memory
12918 layout is appropriate, then you can adjust it.
12921 \begin_layout Standard
12922 The linker generates two files with memory allocation information.
12923 The first, with extension .map
12924 \begin_inset LatexCommand \index{<file>.map}
12928 shows all the variables and segments.
12929 The second with extension .mem
12930 \begin_inset LatexCommand \index{<file>.mem}
12934 shows the final memory layout.
12935 The linker will complain either if memory segments overlap, there is not
12936 enough memory, or there is not enough space for stack.
12937 If you get any linking warnings and/or errors related to stack or segments
12938 allocation, take a look at either the .map or .mem files to find out what
12940 The .mem file may even suggest a solution to the problem.
12941 \begin_inset VSpace bigskip
12947 \begin_layout Subsection
12948 Z80/Z180 Storage Class
12949 \begin_inset LatexCommand \index{Z80!Storage class}
12953 Language Extensions
12956 \begin_layout Subsubsection
12958 \begin_inset LatexCommand \index{sfr}
12963 \begin_inset LatexCommand \index{\_\_sfr}
12967 (in/out to 8-bit addresses)
12970 \begin_layout Standard
12972 \begin_inset LatexCommand \index{Z80}
12976 family has separate address spaces for memory and
12986 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
12991 \begin_inset LatexCommand \index{Z80!I/O memory}
12996 \begin_inset LatexCommand \index{Z180!I/O memory}
13000 is accessed with special instructions, e.g.:
13003 \begin_layout Verse
13006 sfr at 0x78 IoPort;\InsetSpace ~
13008 /* define a var in I/O space at 78h called IoPort */
13012 \begin_layout Standard
13013 Writing 0x01 to this variable generates the assembly code:
13016 \begin_layout Verse
13036 \begin_layout Subsubsection
13038 \begin_inset LatexCommand \index{sfr}
13043 \begin_inset LatexCommand \index{\_\_sfr}
13047 (in/out to 16-bit addresses)
13050 \begin_layout Standard
13055 is used to support 16 bit addresses in I/O memory e.g.:
13058 \begin_layout Verse
13062 \begin_inset LatexCommand \index{at}
13067 \begin_inset LatexCommand \index{\_\_at}
13074 \begin_layout Standard
13075 Writing 0x01 to this variable generates the assembly code:
13078 \begin_layout Verse
13081 01 23 01\InsetSpace ~
13103 \begin_layout Subsubsection
13105 \begin_inset LatexCommand \index{sfr}
13110 \begin_inset LatexCommand \index{\_\_sfr}
13114 (in0/out0 to 8 bit addresses on Z180
13115 \begin_inset LatexCommand \index{Z180}
13120 \begin_inset LatexCommand \index{HD64180 (see Z180)}
13127 \begin_layout Standard
13128 The compiler option -
13132 \begin_layout Standard
13142 \begin_inset LatexCommand \index{Z180!Options!-\/-portmode}
13146 =180 (80) and a compiler #pragma\InsetSpace ~
13148 \begin_inset LatexCommand \index{Z180!Pragmas!\#pragma portmode}
13152 z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
13162 If you include the file z180.h this will be set automatically.
13163 \begin_inset VSpace bigskip
13169 \begin_layout Subsection
13171 \begin_inset LatexCommand \index{HC08!Storage class}
13175 Language Extensions
13178 \begin_layout Subsubsection
13180 \begin_inset LatexCommand \index{data (hc08 storage class)}
13185 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
13192 \begin_layout Standard
13193 The data storage class declares a variable that resides in the first 256
13194 bytes of memory (the direct page).
13196 \begin_inset LatexCommand \index{HC08}
13200 is most efficient at accessing variables (especially pointers) stored here.
13203 \begin_layout Subsubsection
13205 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
13210 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
13217 \begin_layout Standard
13218 The xdata storage class declares a variable that can reside anywhere in
13220 This is the default if no storage class is specified.
13222 \begin_inset VSpace bigskip
13228 \begin_layout Section
13229 Other SDCC language extensions
13230 \begin_inset LatexCommand \index{Other SDCC language extensions}
13237 \begin_layout Subsection
13241 \begin_layout Standard
13242 SDCC supports the use of binary constants, such as 0b01100010.
13243 This feature is only enabled when the compiler is invoked using --std-sdccxx.
13246 \begin_layout Standard
13247 \begin_inset VSpace bigskip
13253 \begin_layout Section
13254 Absolute Addressing
13255 \begin_inset LatexCommand \index{Absolute addressing}
13262 \begin_layout Standard
13263 Data items can be assigned an absolute address with the
13266 \begin_inset LatexCommand \index{at}
13271 \begin_inset LatexCommand \index{\_\_at}
13277 keyword, in addition to a storage class, e.g.:
13280 \begin_layout Verse
13284 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
13289 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
13294 \begin_inset LatexCommand \index{at}
13299 \begin_inset LatexCommand \index{\_\_at}
13303 0x7ffe unsigned int chksum;
13306 \begin_layout Standard
13307 or, better conforming to ISO/IEC 9899 C:
13310 \begin_layout Verse
13313 __xdata __at (0x7ffe) unsigned int chksum;
13316 \begin_layout Standard
13317 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
13318 of the external ram.
13323 reserve any space for variables declared in this way
13324 \begin_inset Marginal
13327 \begin_layout Standard
13336 (they are implemented with an equate in the assembler).
13337 Thus it is left to the programmer to make sure there are no overlaps with
13338 other variables that are declared without the absolute address.
13339 The assembler listing file (.lst
13340 \begin_inset LatexCommand \index{<file>.lst}
13344 ) and the linker output files (.rst
13345 \begin_inset LatexCommand \index{<file>.rst}
13350 \begin_inset LatexCommand \index{<file>.map}
13354 ) are good places to look for such overlaps.
13357 \begin_layout Standard
13358 If however you provide an initializer
13359 \begin_inset LatexCommand \index{Variable initialization}
13363 actual memory allocation will take place and overlaps will be detected
13368 \begin_layout Verse
13371 __code __at (0x7ff0) char Id[5] =
13372 \begin_inset Quotes sld
13376 \begin_inset Quotes srd
13382 \begin_layout Standard
13383 In the above example the variable Id will be located from 0x7ff0 to 0x7ff4
13387 \begin_layout Standard
13388 In case of memory mapped I/O devices the keyword
13392 has to be used to tell the compiler that accesses might not be removed:
13395 \begin_layout Verse
13399 \begin_inset LatexCommand \index{volatile}
13404 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
13409 \begin_inset LatexCommand \index{at}
13413 (0x8000) unsigned char PORTA_8255;
13416 \begin_layout Standard
13417 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
13422 \begin_inset LatexCommand \index{Aligned array}
13429 starts at a block (256 byte) boundary
13430 \begin_inset LatexCommand \index{block boundary}
13435 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
13441 Absolute addresses can be specified for variables in all
13442 storage classes, e.g.:
13445 \begin_layout Verse
13449 \begin_inset LatexCommand \index{bit}
13454 \begin_inset LatexCommand \index{at}
13461 \begin_layout Standard
13462 The above example will allocate the variable at offset 0x02 in the bit-addressab
13464 There is no real advantage to assigning absolute addresses to variables
13465 in this manner, unless you want strict control over all the variables allocated.
13466 One possible use would be to write hardware portable code.
13467 For example, if you have a routine that uses one or more of the microcontroller
13468 I/O pins, and such pins are different for two different hardwares, you
13469 can declare the I/O pins in your routine using:
13472 \begin_layout Verse
13476 \begin_inset LatexCommand \index{volatile}
13480 __bit MOSI;\InsetSpace ~
13484 /* master out, slave in */
13486 extern volatile __bit MISO;\InsetSpace ~
13493 extern volatile __bit MCLK;\InsetSpace ~
13502 Output of a byte on a 3-wire serial bus.
13507 If needed adapt polarity of clock,
13508 polarity of data and bit order
13513 unsigned char spi_io(unsigned char out_byte)
13538 MOSI = out_byte & 0x80;
13569 /* _asm nop _endasm; */\InsetSpace ~
13577 /* for slow peripherals */
13629 \begin_layout Standard
13630 Then, someplace in the code for the first hardware you would use
13633 \begin_layout Verse
13637 \begin_inset LatexCommand \index{at}
13642 \begin_inset LatexCommand \index{\_\_at}
13646 (0x80) MOSI;\InsetSpace ~
13650 /* I/O port 0, bit 0 */
13652 __bit __at (0x81) MISO;\InsetSpace ~
13659 __bit __at (0x82) MCLK;\InsetSpace ~
13663 /* I/O port 0, bit 2 */
13666 \begin_layout Standard
13667 Similarly, for the second hardware you would use
13670 \begin_layout Verse
13673 __bit __at (0x83) MOSI;\InsetSpace ~
13677 /* I/O port 0, bit 3 */
13679 __bit __at (0x91) MISO;\InsetSpace ~
13684 I/O port 1, bit 1 */
13687 \begin_inset LatexCommand \index{bit}
13691 __at (0x92) MCLK;\InsetSpace ~
13695 /* I/O port 1, bit 2 */
13698 \begin_layout Standard
13699 and you can use the same hardware dependent routine without changes, as
13700 for example in a library.
13701 This is somehow similar to sbit, but only one absolute address has to be
13702 specified in the whole project.
13703 \begin_inset VSpace bigskip
13709 \begin_layout Section
13711 \begin_inset LatexCommand \index{Parameters}
13716 \begin_inset LatexCommand \index{function parameter}
13721 \begin_inset LatexCommand \index{local variables}
13726 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
13733 \begin_layout Standard
13734 Automatic (local) variables and parameters to functions can either be placed
13735 on the stack or in data-space.
13736 The default action of the compiler is to place these variables in the internal
13737 RAM (for small model) or external RAM (for medium or large model).
13738 This in fact makes them similar to
13741 \begin_inset LatexCommand \index{static}
13747 so by default functions are non-reentrant
13748 \begin_inset LatexCommand \index{reentrant}
13757 They can be placed on the stack
13758 \begin_inset LatexCommand \index{stack}
13768 \begin_layout Standard
13778 \begin_inset LatexCommand \index{-\/-stack-auto}
13786 #pragma\InsetSpace ~
13790 \begin_inset LatexCommand \index{\#pragma stackauto}
13797 \begin_inset LatexCommand \index{reentrant}
13803 keyword in the function declaration, e.g.:
13806 \begin_layout Verse
13809 unsigned char foo(char i) __reentrant
13823 \begin_layout Standard
13824 Since stack space on 8051 is limited, the
13834 \begin_layout Standard
13845 option should be used sparingly.
13846 Note that the reentrant keyword just means that the parameters & local
13847 variables will be allocated to the stack, it
13851 mean that the function is register bank
13852 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
13861 \begin_inset LatexCommand \index{local variables}
13865 can be assigned storage classes and absolute
13866 \begin_inset LatexCommand \index{Absolute addressing}
13873 \begin_layout Verse
13876 unsigned char foo()
13884 __xdata unsigned char i;
13897 \begin_inset LatexCommand \index{at}
13901 (0x31) unsigned char j;
13913 \begin_layout Standard
13914 In the above example the variable
13918 will be allocated in the external ram,
13922 in bit addressable space and
13933 \begin_layout Standard
13944 or when a function is declared as
13948 this should only be done for static variables.
13951 \begin_layout Standard
13953 \begin_inset LatexCommand \index{function parameter}
13957 however are not allowed any storage class
13958 \begin_inset LatexCommand \index{Storage class}
13962 , (storage classes for parameters will be ignored), their allocation is
13963 governed by the memory model in use, and the reentrancy options.
13966 \begin_layout Standard
13967 It is however allowed to use bit parameters in reentrant functions and also
13968 non-static local bit variables are supported.
13969 Efficient use is limited to 8 semi-bitregisters in bit space.
13970 They are pushed and popped to stack
13971 \begin_inset LatexCommand \index{stack}
13975 as a single byte just like the normal registers.
13978 \begin_layout Section
13980 \begin_inset LatexCommand \label{sub:Overlaying}
13985 \begin_inset LatexCommand \index{Overlaying}
13992 \begin_layout Standard
13994 \begin_inset LatexCommand \index{reentrant}
13998 functions SDCC will try to reduce internal ram space usage by overlaying
13999 parameters and local variables of a function (if possible).
14000 Parameters and local variables
14001 \begin_inset LatexCommand \index{local variables}
14005 of a function will be allocated to an overlayable segment if the function
14008 no other function calls and the function is non-reentrant and the memory
14010 \begin_inset LatexCommand \index{Memory model}
14017 If an explicit storage class
14018 \begin_inset LatexCommand \index{Storage class}
14022 is specified for a local variable, it will NOT be overlayed.
14025 \begin_layout Standard
14026 Note that the compiler (not the linkage editor) makes the decision for overlayin
14028 Functions that are called from an interrupt service routine
14029 \begin_inset Marginal
14032 \begin_layout Standard
14040 should be preceded by a #pragma\InsetSpace ~
14042 \begin_inset LatexCommand \index{\#pragma nooverlay}
14046 if they are not reentrant.
14049 \begin_layout Standard
14050 Also note that the compiler does not do any processing of inline assembler
14051 code, so the compiler might incorrectly assign local variables and parameters
14052 of a function into the overlay segment if the inline assembler code calls
14053 other c-functions that might use the overlay.
14054 In that case the #pragma\InsetSpace ~
14055 nooverlay should be used.
14058 \begin_layout Standard
14059 Parameters and local variables of functions that contain 16 or 32 bit multiplica
14061 \begin_inset LatexCommand \index{Multiplication}
14066 \begin_inset LatexCommand \index{Division}
14070 will NOT be overlayed since these are implemented using external functions,
14074 \begin_layout Verse
14080 \begin_inset LatexCommand \index{\#pragma nooverlay}
14086 void set_error(unsigned char errcd)
14103 some_isr () __interrupt
14104 \begin_inset LatexCommand \index{interrupt}
14134 \begin_layout Standard
14135 In the above example the parameter
14143 would be assigned to the overlayable segment if the #pragma\InsetSpace ~
14145 not present, this could cause unpredictable runtime behavior when called
14146 from an interrupt service routine.
14147 The #pragma\InsetSpace ~
14148 nooverlay ensures that the parameters and local variables for
14149 the function are NOT overlayed.
14150 \begin_inset VSpace bigskip
14156 \begin_layout Section
14157 Interrupt Service Routines
14158 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
14165 \begin_layout Subsection
14166 General Information
14169 \begin_layout Standard
14182 outines to be coded in C, with some extended keywords.
14185 \begin_layout Verse
14188 void timer_isr (void) __interrupt (1) __using (1)
14202 \begin_layout Standard
14203 The optional number following the
14206 \begin_inset LatexCommand \index{interrupt}
14211 \begin_inset LatexCommand \index{\_\_interrupt}
14217 keyword is the interrupt number this routine will service.
14218 When present, the compiler will insert a call to this routine in the interrupt
14220 \begin_inset LatexCommand \index{interrupt vector table}
14224 for the interrupt number specified.
14225 If you have multiple source files in your project, interrupt service routines
14226 can be present in any of them, but a prototype of the isr MUST be present
14227 or included in the file that contains the function
14232 The optional (8051 specific) keyword
14235 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
14240 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
14246 can be used to tell the compiler to use the specified register bank when
14247 generating code for this function.
14250 Interrupt service routines open the door for some very interesting bugs:
14253 \begin_layout Subsubsection
14254 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-volatile}
14258 Common interrupt pitfall: variable not declared
14263 \begin_layout Standard
14264 If an interrupt service routine changes variables which are accessed by
14265 other functions these variables have to be declared
14270 \begin_inset LatexCommand \index{volatile}
14276 \begin_inset LatexCommand \url{http://en.wikipedia.org/wiki/Volatile_variable}
14283 \begin_layout Subsubsection
14284 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-atomic}
14288 Common interrupt pitfall:
14293 \begin_layout Standard
14294 If the access to these variables is not
14297 \begin_inset LatexCommand \index{atomic}
14304 the processor needs more than one instruction for the access and could
14305 be interrupted while accessing the variable) the interrupt must be disabled
14306 during the access to avoid inconsistent data.
14309 Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
14310 and should be protected by disabling interrupts.
14311 You're not automatically on the safe side if you use 8 bit variables though.
14312 We need an example here: f.e.
14313 on the 8051 the harmless looking
14314 \begin_inset Quotes srd
14324 \begin_inset Quotes sld
14333 \begin_inset Quotes srd
14343 \begin_inset Quotes sld
14346 from within an interrupt routine might get lost if the interrupt occurs
14349 \begin_inset Quotes sld
14354 counter\InsetSpace ~
14359 \begin_inset Quotes srd
14362 is not atomic on the 8051 even if
14366 is located in data memory.
14368 Bugs like these are hard to reproduce and can
14369 cause a lot of trouble.
14373 \begin_layout Subsubsection
14374 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-stack-overflow}
14378 Common interrupt pitfall:
14383 \begin_layout Standard
14384 The return address and the registers used in the interrupt service routine
14385 are saved on the stack
14386 \begin_inset LatexCommand \index{stack}
14390 so there must be sufficient stack space.
14391 If there isn't variables or registers (or even the return address itself)
14398 \begin_inset LatexCommand \index{stack overflow}
14402 is most likely to happen if the interrupt occurs during the
14403 \begin_inset Quotes sld
14407 \begin_inset Quotes srd
14410 subroutine when the stack is already in use for f.e.
14411 many return addresses.
14414 \begin_layout Subsubsection
14415 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-reentrant}
14419 Common interrupt pitfall:
14421 use of non-reentrant functions
14424 \begin_layout Standard
14425 A special note here, int (16 bit) and long (32 bit) integer division
14426 \begin_inset LatexCommand \index{Division}
14431 \begin_inset LatexCommand \index{Multiplication}
14436 \begin_inset LatexCommand \index{Modulus}
14441 \begin_inset LatexCommand \index{Floating point support}
14445 operations are implemented using external support routines.
14446 If an interrupt service routine needs to do any of these operations then
14447 the support routines (as mentioned in a following section) will have to
14448 be recompiled using the
14454 \begin_layout Standard
14464 \begin_inset LatexCommand \index{-\/-stack-auto}
14470 option and the source file will need to be compiled using the
14476 \begin_layout Standard
14488 \begin_inset LatexCommand \index{-\/-int-long-reent}
14495 Note, the type promotion
14496 \begin_inset LatexCommand \index{type promotion}
14500 required by ANSI C can cause 16 bit routines to be used
14501 \begin_inset Marginal
14504 \begin_layout Standard
14513 without the programmer being aware of it.
14517 (unsigned char)(tail-1)
14519 within the if clause in section
14520 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
14527 \begin_layout Standard
14528 Calling other functions from an interrupt service routine is not recommended,
14529 avoid it if possible.
14530 Note that when some function is called from an interrupt service routine
14531 it should be preceded by a #pragma\InsetSpace ~
14533 \begin_inset LatexCommand \index{\#pragma nooverlay}
14537 if it is not reentrant.
14538 Furthermore nonreentrant functions should not be called from the main program
14539 while the interrupt service routine might be active.
14540 They also must not be called from low priority interrupt service routines
14541 while a high priority interrupt service routine might be active.
14542 You could use semaphores or make the function
14546 if all parameters are passed in registers.
14549 \begin_inset LatexCommand \ref{sub:Overlaying}
14554 about Overlaying and section
14555 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
14560 about Functions using private register banks.
14561 \begin_inset VSpace bigskip
14567 \begin_layout Subsection
14568 MCS51/DS390 Interrupt Service Routines
14571 \begin_layout Standard
14573 \begin_inset LatexCommand \index{interrupt}
14577 numbers and the corresponding address & descriptions for the Standard 8051/8052
14579 SDCC will automatically adjust the
14580 \begin_inset LatexCommand \index{interrupt vector table}
14584 to the maximum interrupt number specified.
14589 \begin_layout Standard
14591 \begin_inset Tabular
14592 <lyxtabular version="3" rows="9" columns="3">
14594 <column alignment="center" valignment="top" leftline="true" width="0in">
14595 <column alignment="left" valignment="top" leftline="true" width="0in">
14596 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
14597 <row topline="true" bottomline="true">
14598 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14601 \begin_layout Standard
14607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14610 \begin_layout Standard
14616 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14619 \begin_layout Standard
14626 <row topline="true">
14627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14630 \begin_layout Standard
14636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14639 \begin_layout Standard
14645 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14648 \begin_layout Standard
14655 <row topline="true">
14656 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14659 \begin_layout Standard
14665 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14668 \begin_layout Standard
14674 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14677 \begin_layout Standard
14684 <row topline="true">
14685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14688 \begin_layout Standard
14694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14697 \begin_layout Standard
14703 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14706 \begin_layout Standard
14713 <row topline="true">
14714 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14717 \begin_layout Standard
14723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14726 \begin_layout Standard
14732 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14735 \begin_layout Standard
14742 <row topline="true">
14743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14746 \begin_layout Standard
14752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14755 \begin_layout Standard
14761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14764 \begin_layout Standard
14771 <row topline="true">
14772 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14775 \begin_layout Standard
14781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14784 \begin_layout Standard
14790 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14793 \begin_layout Standard
14800 <row topline="true">
14801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14804 \begin_layout Standard
14810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14813 \begin_layout Standard
14819 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14822 \begin_layout Standard
14829 <row topline="true" bottomline="true">
14830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14833 \begin_layout Standard
14839 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14842 \begin_layout Standard
14848 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14851 \begin_layout Standard
14867 \begin_layout Standard
14868 If the interrupt service routine is defined without
14871 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
14876 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
14882 a register bank or with register bank 0 (
14886 0), the compiler will save the registers used by itself on the stack upon
14887 entry and restore them at exit, however if such an interrupt service routine
14888 calls another function then the entire register bank will be saved on the
14890 This scheme may be advantageous for small interrupt service routines which
14891 have low register usage.
14894 \begin_layout Standard
14895 If the interrupt service routine is defined to be using a specific register
14900 & psw are saved and restored, if such an interrupt service routine calls
14901 another function (using another register bank) then the entire register
14902 bank of the called function will be saved on the stack
14903 \begin_inset LatexCommand \index{stack}
14908 This scheme is recommended for larger interrupt service routines.
14909 \begin_inset VSpace bigskip
14915 \begin_layout Subsection
14917 \begin_inset LatexCommand \index{HC08}
14921 Interrupt Service Routines
14924 \begin_layout Standard
14925 Since the number of interrupts
14926 \begin_inset LatexCommand \index{HC08!interrupt}
14930 available is chip specific and the interrupt vector table always ends at
14931 the last byte of memory, the interrupt numbers corresponds to the interrupt
14932 vectors in reverse order of address.
14933 For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
14934 2 will use the interrupt vector at 0xfffa, and so on.
14935 However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
14936 this way; instead see section
14937 \begin_inset LatexCommand \ref{sub:Startup-Code}
14941 for details on customizing startup.
14942 \begin_inset VSpace bigskip
14948 \begin_layout Subsection
14949 Z80 Interrupt Service Routines
14952 \begin_layout Standard
14954 \begin_inset LatexCommand \index{Z80}
14958 uses several different methods for determining the correct interrupt
14959 \begin_inset LatexCommand \index{Z80!interrupt}
14963 vector depending on the hardware implementation.
14964 Therefore, SDCC ignores the optional interrupt number and does not attempt
14965 to generate an interrupt vector table.
14968 \begin_layout Standard
14969 By default, SDCC generates code for a maskable interrupt, which uses a RETI
14970 instruction to return from the interrupt.
14971 To write an interrupt handler for the non-maskable interrupt, which needs
14972 a RETN instruction instead, add the
14979 \begin_layout Verse
14982 void nmi_isr (void) critical interrupt
14996 \begin_layout Standard
14997 However if you need to create a non-interruptable interrupt service routine
14998 you would also require the
15003 To distinguish between this and an nmi_isr you must provide an interrupt
15005 \begin_inset VSpace bigskip
15011 \begin_layout Section
15012 Enabling and Disabling Interrupts
15015 \begin_layout Subsection
15016 Critical Functions and Critical Statements
15019 \begin_layout Standard
15020 A special keyword may be associated with a block or a function declaring
15026 SDCC will generate code to disable all interrupts
15027 \begin_inset LatexCommand \index{interrupt}
15031 upon entry to a critical function and restore the interrupt enable to the
15032 previous state before returning.
15033 Nesting critical functions will need one additional byte on the stack
15034 \begin_inset LatexCommand \index{stack}
15041 \begin_layout Verse
15044 int foo () __critical
15045 \begin_inset LatexCommand \index{critical}
15050 \begin_inset LatexCommand \index{\_\_critical}
15075 \begin_layout Standard
15076 The critical attribute maybe used with other attributes like
15086 may also be used to disable interrupts more locally:
15089 \begin_layout Verse
15095 \begin_layout Standard
15096 More than one statement could have been included in the block.
15099 \begin_layout Subsection
15100 Enabling and Disabling Interrupts directly
15103 \begin_layout Standard
15105 \begin_inset LatexCommand \index{interrupt}
15109 can also be disabled and enabled directly (8051):
15112 \begin_layout Verse
15115 EA = 0;\InsetSpace ~
15141 \begin_layout Verse
15177 \begin_layout Verse
15180 EA = 1;\InsetSpace ~
15209 \begin_layout Verse
15248 \begin_layout Standard
15249 On other architectures which have seperate opcodes for enabling and disabling
15250 interrupts you might want to make use of defines with inline assembly
15251 \begin_inset LatexCommand \index{Assembler routines}
15256 \begin_inset LatexCommand \index{HC08!interrupt}
15263 \begin_layout Verse
15267 \begin_inset LatexCommand \index{\_asm}
15276 \begin_inset LatexCommand \index{\_endasm}
15283 \begin_layout Verse
15286 #define SEI _asm\InsetSpace ~
15293 \begin_layout Verse
15299 \begin_layout Standard
15300 Note: it is sometimes sufficient to disable only a specific interrupt source
15302 a timer or serial interrupt by manipulating an
15305 \begin_inset LatexCommand \index{interrupt mask}
15315 \begin_layout Standard
15316 Usually the time during which interrupts are disabled should be kept as
15318 This minimizes both
15323 \begin_inset LatexCommand \index{interrupt latency}
15327 (the time between the occurrence of the interrupt and the execution of
15328 the first code in the interrupt routine) and
15333 \begin_inset LatexCommand \index{interrupt jitter}
15337 (the difference between the shortest and the longest interrupt latency).
15338 These really are something different, f.e.
15339 a serial interrupt has to be served before its buffer overruns so it cares
15340 for the maximum interrupt latency, whereas it does not care about jitter.
15341 On a loudspeaker driven via a digital to analog converter which is fed
15342 by an interrupt a latency of a few milliseconds might be tolerable, whereas
15343 a much smaller jitter will be very audible.
15346 \begin_layout Standard
15347 You can reenable interrupts within an interrupt routine and on some architecture
15348 s you can make use of two (or more) levels of
15350 interrupt priorities
15353 \begin_inset LatexCommand \index{interrupt priority}
15358 On some architectures which don't support interrupt priorities these can
15359 be implemented by manipulating the interrupt mask and reenabling interrupts
15360 within the interrupt routine.
15361 Check there is sufficient space on the stack
15362 \begin_inset LatexCommand \index{stack}
15366 and don't add complexity unless you have to.
15370 \begin_layout Subsection
15372 \begin_inset LatexCommand \index{semaphore}
15376 locking (mcs51/ds390)
15379 \begin_layout Standard
15380 Some architectures (mcs51/ds390) have an atomic
15381 \begin_inset LatexCommand \index{atomic}
15394 These type of instructions are typically used in preemptive multitasking
15395 systems, where a routine f.e.
15396 claims the use of a data structure ('acquires a lock
15397 \begin_inset LatexCommand \index{lock}
15401 on it'), makes some modifications and then releases the lock when the data
15402 structure is consistent again.
15403 The instruction may also be used if interrupt and non-interrupt code have
15404 to compete for a resource.
15405 With the atomic bit test and clear instruction interrupts
15406 \begin_inset LatexCommand \index{interrupt}
15410 don't have to be disabled for the locking operation.
15414 \begin_layout Standard
15415 SDCC generates this instruction if the source follows this pattern:
15418 \begin_layout Verse
15422 \begin_inset LatexCommand \index{volatile}
15426 bit resource_is_free;
15430 if (resource_is_free)
15440 resource_is_free=0;
15453 resource_is_free=1;
15460 \begin_layout Standard
15461 Note, mcs51 and ds390 support only an atomic
15462 \begin_inset LatexCommand \index{atomic}
15470 instruction (as opposed to atomic bit test and
15475 \begin_layout Section
15476 Functions using private register banks
15477 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
15484 \begin_layout Standard
15485 Some architectures have support for quickly changing register sets.
15486 SDCC supports this feature with the
15489 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
15494 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
15500 attribute (which tells the compiler to use a register bank
15501 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
15505 other than the default bank zero).
15506 It should only be applied to
15509 \begin_inset LatexCommand \index{interrupt}
15515 functions (see footnote below).
15516 This will in most circumstances make the generated ISR code more efficient
15517 since it will not have to save registers on the stack.
15520 \begin_layout Standard
15525 attribute will have no effect on the generated code for a
15529 function (but may occasionally be useful anyway
15533 \begin_layout Standard
15534 possible exception: if a function is called ONLY from 'interrupt' functions
15535 using a particular bank, it can be declared with the same 'using' attribute
15536 as the calling 'interrupt' functions.
15537 For instance, if you have several ISRs using bank one, and all of them
15538 call memcpy(), it might make sense to create a specialized version of memcpy()
15539 'using 1', since this would prevent the ISR from having to save bank zero
15540 to the stack on entry and switch to bank zero before calling the function
15549 (pending: Note, nowadays the
15553 attribute has an effect on
15557 the generated code for a
15568 \begin_layout Standard
15573 function using a non-zero bank will assume that it can trash that register
15574 bank, and will not save it.
15575 Since high-priority interrupts
15576 \begin_inset LatexCommand \index{interrupts}
15581 \begin_inset LatexCommand \index{interrupt priority}
15585 can interrupt low-priority ones on the 8051 and friends, this means that
15586 if a high-priority ISR
15590 a particular bank occurs while processing a low-priority ISR
15594 the same bank, terrible and bad things can happen.
15595 To prevent this, no single register bank should be
15599 by both a high priority and a low priority ISR.
15600 This is probably most easily done by having all high priority ISRs use
15601 one bank and all low priority ISRs use another.
15602 If you have an ISR which can change priority at runtime, you're on your
15603 own: I suggest using the default bank zero and taking the small performance
15607 \begin_layout Standard
15608 It is most efficient if your ISR calls no other functions.
15609 If your ISR must call other functions, it is most efficient if those functions
15610 use the same bank as the ISR (see note 1 below); the next best is if the
15611 called functions use bank zero.
15612 It is very inefficient to call a function using a different, non-zero bank
15615 \begin_inset VSpace bigskip
15621 \begin_layout Section
15623 \begin_inset LatexCommand \label{sub:Startup-Code}
15628 \begin_inset LatexCommand \index{Startup code}
15635 \begin_layout Subsection
15636 MCS51/DS390 Startup Code
15639 \begin_layout Standard
15640 The compiler triggers the linker to link certain initialization modules
15641 from the runtime library
15642 \begin_inset LatexCommand \index{Runtime library}
15646 called crt<something>.
15647 Only the necessary ones are linked, for instance crtxstack.asm (GSINIT1,
15648 GSINIT5) is not linked unless the -
15654 \begin_layout Standard
15665 -xstack option is used.
15666 These modules are highly entangled by the use of special segments/areas,
15667 but a common layout is shown below:
15670 \begin_layout Verse
15678 \begin_layout Verse
15702 ljmp __sdcc_gsinit_startup
15705 \begin_layout Verse
15713 \begin_layout Verse
15725 .area GSINIT0 (CODE)
15727 __sdcc_gsinit_startup::
15737 mov sp,#__start__stack - 1
15740 \begin_layout Verse
15748 \begin_layout Verse
15760 .area GSINIT1 (CODE)
15762 __sdcc_init_xstack::
15764 ; Need to initialize in GSINIT1 in
15765 case the user's __sdcc_external_startup uses the xstack.
15775 mov __XPAGE,#(__start__x
15786 mov _spx,#__start__xstack
15789 \begin_layout Verse
15797 \begin_layout Verse
15809 .area GSINIT2 (CODE)
15819 lcall __sdcc_external_startup
15839 jz __sdcc_init_data
15850 __sdcc_program_startup
15855 \begin_layout Verse
15863 \begin_layout Verse
15875 .area GSINIT3 (CODE)
15928 mov r2,#((l_XINIT+255) >> 8)
15959 __XPAGE,#(s_XISEG >> 8)
15961 00001$:\InsetSpace ~
16025 00002$:\InsetSpace ~
16052 \begin_layout Verse
16060 \begin_layout Verse
16072 .area GSINIT4 (CODE)
16074 __mcs51_genRAMCLEAR::
16096 00004$:\InsetSpace ~
16110 ; _mcs51_genRAMCLEAR() end
16113 \begin_layout Verse
16121 \begin_layout Verse
16133 .area GSINIT4 (CODE)
16135 __mcs51_genXRAMCLEAR::
16196 mov __XPAGE,#(s_PSEG >> 8)
16208 00005$:\InsetSpace ~
16283 mov r1,#((l_XSEG + 255) >> 8)
16305 00007$:\InsetSpace ~
16342 \begin_layout Verse
16350 \begin_layout Verse
16362 .area GSINIT5 (CODE)
16364 ; Need to initialize in GSINIT5 because __mcs51_genXINIT
16367 ; and __mcs51_genRAMCLEAR modifies _spx.
16377 mov __XPAGE,#(__start__x
16388 mov _spx,#__start__xstack
16391 \begin_layout Verse
16396 (application modules)
16399 \begin_layout Verse
16411 .area GSINIT (CODE)
16414 \begin_layout Verse
16422 \begin_layout Verse
16434 .area GSFINAL (CODE)
16444 ljmp __sdcc_program_startup
16446 ;---------------------------------
16447 -----------------------
16451 ;--------------------------------------------------
16474 __sdcc_program_startup:
16487 return from main will lock up
16500 \begin_layout Standard
16501 One of these modules (crtstart.asm) contains a call to the C routine
16503 _sdcc_external_startup()
16504 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
16513 at the start of the CODE area.
16514 This routine is also in the runtime library
16515 \begin_inset LatexCommand \index{Runtime library}
16519 and returns 0 by default.
16520 If this routine returns a non-zero value, the static & global variable
16521 initialization will be skipped and the function main will be invoked.
16522 Otherwise static & global variables will be initialized before the function
16526 _sdcc_external_startup()
16528 routine to your program to override the default if you need to setup hardware
16529 or perform some other critical operation prior to static & global variable
16531 \begin_inset LatexCommand \index{Variable initialization}
16536 On some mcs51 variants xdata
16537 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
16541 memory has to be explicitly enabled before it can be accessed or if the
16543 \begin_inset LatexCommand \index{watchdog}
16547 needs to be disabled, this is the place to do it.
16548 The startup code clears all internal data memory, 256 bytes by default,
16549 but from 0 to n-1 if
16555 \begin_layout Standard
16565 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
16572 (recommended for Chipcon CC1010).
16575 \begin_layout Standard
16576 See also the compiler options
16582 \begin_layout Standard
16598 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
16608 \begin_layout Standard
16620 \begin_inset LatexCommand \index{-\/-main-return}
16625 \begin_inset LatexCommand \ref{sub:MCS51-variants}
16629 about MCS51-variants.
16634 \begin_layout Standard
16635 While these initialization modules are meant as generic startup code there
16636 might be the need for customization.
16637 Let's assume the return value of
16639 _sdcc_external_startup()
16645 should not be checked (or
16647 _sdcc_external_startup()
16649 should not be called at all).
16650 The recommended way would be to copy
16656 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/device/lib/mcs51/crtstart.asm}
16660 ) into the source directory, adapt it there, then assemble it with
16666 \begin_layout Standard
16667 \begin_inset Quotes sld
16671 \begin_inset Quotes srd
16674 are the assembler options used in
16675 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/lib/mcs51/Makefile.in?view=markup }
16686 and when linking your project explicitely specify
16691 As a bonus a listing of the relocated object file
16698 \begin_layout Standard
16699 \begin_inset VSpace bigskip
16705 \begin_layout Subsection
16709 \begin_layout Standard
16711 \begin_inset LatexCommand \index{HC08}
16715 startup code follows the same scheme as the MCS51 startup code.
16716 \begin_inset VSpace bigskip
16722 \begin_layout Subsection
16726 \begin_layout Standard
16728 \begin_inset LatexCommand \index{Z80}
16732 the startup code is inserted by linking with crt0.o which is generated from
16733 sdcc/device/lib/z80/crt0.s.
16734 If you need a different startup code you can use the compiler option
16743 \begin_layout Standard
16758 \begin_inset LatexCommand \index{-\/-no-std-crt0}
16762 and provide your own crt0.o.
16764 \begin_inset VSpace bigskip
16770 \begin_layout Section
16771 Inline Assembler Code
16772 \begin_inset LatexCommand \index{Assembler routines}
16779 \begin_layout Subsection
16780 A Step by Step Introduction
16781 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
16788 \begin_layout Standard
16789 Starting from a small snippet of c-code this example shows for the MCS51
16790 how to use inline assembly, access variables, a function parameter and
16791 an array in xdata memory.
16792 The example uses an MCS51 here but is easily adapted for other architectures.
16793 This is a buffer routine which should be optimized:
16796 \begin_layout Verse
16800 unsigned char __far
16801 \begin_inset LatexCommand \index{far (storage class)}
16806 \begin_inset LatexCommand \index{\_\_far (storage class)}
16811 \begin_inset LatexCommand \index{at}
16816 \begin_inset LatexCommand \index{\_\_at}
16820 (0x7f00) buf[0x100];
16821 \begin_inset LatexCommand \index{Aligned array}
16827 unsigned char head, tail;\InsetSpace ~
16845 \begin_inset LatexCommand \index{interrupt}
16897 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
16909 void to_buffer( unsigned char c )
16917 if( head != (unsigned char)(tail-1)
16924 \begin_inset LatexCommand \index{promotion to signed int}
16929 \begin_inset LatexCommand \index{type promotion}
16934 \begin_inset Marginal
16937 \begin_layout Standard
16956 buf[ head++ ] = c;\InsetSpace ~
16972 /* access to a 256 byte aligned array */
16977 \begin_layout Standard
16978 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
16979 then a corresponding buffer.asm file is generated.
16980 We define a new function
16984 in file buffer.c in which we cut and paste the generated code, removing
16985 unwanted comments and some ':'.
16987 \begin_inset Quotes sld
16995 \begin_inset Quotes srd
16999 \begin_inset Quotes sld
17007 \begin_inset Quotes srd
17014 \begin_layout Standard
17015 Note, that the single underscore form (_asm and _endasm) are not C99-compatible,
17016 and for C-99 compatibility, the double-underscore form (__asm and __endasm)
17018 The latter is also used in the library functions.
17023 to the beginning and the end of the function body:
17026 \begin_layout Verse
17030 /* With a cut and paste from the .asm file, we have something to start with.
17036 function is not yet OK! (registers aren't saved) */
17038 void to_buffer_asm(
17048 \begin_inset LatexCommand \index{\_asm}
17053 \begin_inset LatexCommand \index{\_\_asm}
17067 ;buffer.c if( head != (unsigned char)(tail-1) ) \InsetSpace ~
17073 \begin_inset LatexCommand \index{promotion to signed int}
17078 \begin_inset LatexCommand \index{type promotion}
17131 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
17132 \begin_inset LatexCommand \index{Aligned array}
17198 \begin_inset LatexCommand \index{\_endasm}
17203 \begin_inset LatexCommand \index{\_\_endasm}
17212 \begin_layout Standard
17213 The new file buffer.c should compile with only one warning about the unreferenced
17214 function argument 'c'.
17215 Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
17216 (1) and finally have:
17219 \begin_layout Verse
17223 unsigned char __far __at(0x7f00) buf[0x100];
17225 unsigned char head, tail;
17236 void to_buffer( unsigned char c )
17245 head != (unsigned char)(tail-1) )
17274 c; // to avoid warning: unreferenced function argument
17281 \begin_inset LatexCommand \index{\_asm}
17286 \begin_inset LatexCommand \index{\_\_asm}
17300 ; save used registers here.
17311 ; If we were still using r2,r3 we would have to push them here.
17314 ; if( head != (unsigned char)(tail-1) )
17358 could do an ANL a,#0x0f here to use a smaller buffer (see below)
17394 a,dpl \InsetSpace ~
17401 ; dpl holds lower byte of function argument
17413 dpl,_head \InsetSpace ~
17416 ; buf is 0x100 byte aligned so head can be used directly
17459 ; we could do an ANL _head,#0x0f here to use a
17460 smaller buffer (see above)
17472 ; restore used registers here
17479 \begin_inset LatexCommand \index{\_endasm}
17484 \begin_inset LatexCommand \index{\_\_endasm}
17495 \begin_layout Standard
17496 The inline assembler code can contain any valid code understood by the assembler
17497 , this includes any assembler directives and comment lines.
17498 The assembler does not like some characters like ':' or ''' in comments.
17499 You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
17500 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
17505 \begin_inset LatexCommand \index{Assembler documentation}
17510 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html}
17518 \begin_layout Standard
17519 The compiler does not do any validation of the code within the
17522 \begin_inset LatexCommand \index{\_asm}
17527 \begin_inset LatexCommand \index{\_\_asm}
17535 \begin_inset LatexCommand \index{\_endasm}
17540 \begin_inset LatexCommand \index{\_\_endasm}
17549 Specifically it will not know which registers are used and thus register
17551 \begin_inset LatexCommand \index{push/pop}
17555 has to be done manually.
17559 \begin_layout Standard
17560 It is recommended that each assembly instruction (including labels) be placed
17561 in a separate line (as the example shows).
17566 \begin_layout Standard
17578 \begin_inset LatexCommand \index{-\/-peep-asm}
17584 command line option is used, the inline assembler code will be passed through
17585 the peephole optimizer
17586 \begin_inset LatexCommand \index{Peephole optimizer}
17591 There are only a few (if any) cases where this option makes sense, it might
17592 cause some unexpected changes in the inline assembler code.
17593 Please go through the peephole optimizer rules defined in file
17597 before using this option.
17600 \begin_layout Subsection
17602 \begin_inset LatexCommand \label{sub:Naked-Functions}
17607 \begin_inset LatexCommand \index{Naked functions}
17614 \begin_layout Standard
17615 A special keyword may be associated with a function declaring it as
17618 \begin_inset LatexCommand \index{\_naked}
17623 \begin_inset LatexCommand \index{\_\_naked}
17634 function modifier attribute prevents the compiler from generating prologue
17635 \begin_inset LatexCommand \index{function prologue}
17640 \begin_inset LatexCommand \index{function epilogue}
17644 code for that function.
17645 This means that the user is entirely responsible for such things as saving
17646 any registers that may need to be preserved, selecting the proper register
17647 bank, generating the
17651 instruction at the end, etc.
17652 Practically, this means that the contents of the function must be written
17653 in inline assembler.
17654 This is particularly useful for interrupt functions, which can have a large
17655 (and often unnecessary) prologue/epilogue.
17656 For example, compare the code generated by these two functions:
17659 \begin_layout Verse
17663 \begin_inset LatexCommand \index{volatile}
17667 data unsigned char counter;
17671 void simpleInterrupt(void) __interrupt
17672 \begin_inset LatexCommand \index{interrupt}
17677 \begin_inset LatexCommand \index{\_\_interrupt}
17695 void nakedInterrupt(void) __interrupt (2) __naked
17704 \begin_inset LatexCommand \index{\_asm}
17709 \begin_inset LatexCommand \index{\_\_asm}
17726 _counter ; does not change flags, no need to save psw
17739 include ret or reti in _naked function.
17746 \begin_inset LatexCommand \index{\_endasm}
17751 \begin_inset LatexCommand \index{\_\_endasm}
17760 \begin_layout Standard
17761 For an 8051 target, the generated simpleInterrupt looks like:
17764 \begin_layout Verse
17771 example, recent versions of SDCC generate
17777 code for simpleInterrupt() and nakedInterrupt()!
17918 \begin_layout Standard
17919 whereas nakedInterrupt looks like:
17922 \begin_layout Verse
17935 _counter ; does not change flags, no need to save psw
17954 MUST explicitly include ret or reti in _naked function
17957 \begin_layout Standard
17958 The related directive #pragma exclude
17959 \begin_inset LatexCommand \index{\#pragma exclude}
17963 allows a more fine grained control over pushing & popping
17964 \begin_inset LatexCommand \index{push/pop}
17971 \begin_layout Standard
17972 While there is nothing preventing you from writing C code inside a
17976 function, there are many ways to shoot yourself in the foot doing this,
17977 and it is recommended that you stick to inline assembler.
17980 \begin_layout Subsection
17981 Use of Labels within Inline Assembler
17984 \begin_layout Standard
17985 SDCC allows the use of in-line assembler with a few restrictions regarding
17987 All labels defined within inline assembler code have to be of the form
17992 where nnnnn is a number less than 100 (which implies a limit of utmost
17993 100 inline assembler labels
18004 \begin_layout Standard
18005 This is a slightly more stringent rule than absolutely necessary, but stays
18006 always on the safe side.
18007 Labels in the form of nnnnn$ are local labels in the assembler, locality
18008 of which is confined within two labels of the standard form.
18009 The compiler uses the same form for labels within a function (but starting
18010 from nnnnn=00100); and places always a standard label at the beginning
18011 of a function, thus limiting the locality of labels within the scope of
18013 So, if the inline assembler part would be embedded into C-code, an improperly
18014 placed non-local label in the assembler would break up the reference space
18015 for labels created by the compiler for the C-code, leading to an assembling
18019 \begin_layout Standard
18020 The numeric part of local labels does not need to have 5 digits (although
18021 this is the form of labels output by the compiler), any valid integer will
18023 Please refer to the assemblers documentation for further details.
18031 \begin_layout Verse
18035 \begin_inset LatexCommand \index{\_asm}
18040 \begin_inset LatexCommand \index{\_\_asm}
18070 \begin_inset LatexCommand \index{\_endasm}
18075 \begin_inset LatexCommand \index{\_\_endasm}
18082 \begin_layout Standard
18083 Inline assembler code cannot reference any C-labels, however it can reference
18085 \begin_inset LatexCommand \index{Labels}
18089 defined by the inline assembler, e.g.:
18092 \begin_layout Verse
18115 ; some assembler code
18136 /* some more c code */
18138 clabel:\InsetSpace ~
18140 /* inline assembler cannot reference this
18145 \begin_layout Standard
18150 is translated by the compiler into a local label, so the locality of labels
18151 within the function is not broken.
18168 0003$: ;label (can be referenced by inline assembler only)
18175 \begin_inset LatexCommand \index{\_endasm}
18180 \begin_inset LatexCommand \index{\_\_endasm}
18190 /* some more c code */
18195 \begin_layout Standard
18196 In other words inline assembly code can access labels defined in inline
18197 assembly within the scope of the function.
18198 The same goes the other way, i.e.
18199 labels defines in inline assembly can not be accessed by C statements.
18202 \begin_layout Section
18203 Interfacing with Assembler Code
18204 \begin_inset LatexCommand \index{Assembler routines}
18211 \begin_layout Subsection
18212 Global Registers used for Parameter Passing
18213 \begin_inset LatexCommand \index{Parameter passing}
18220 \begin_layout Standard
18221 The compiler always uses the global registers
18224 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
18229 \begin_inset LatexCommand \index{DPTR}
18234 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
18243 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
18249 to pass the first (non-bit) parameter to a function, and also to pass the
18251 \begin_inset LatexCommand \index{return value}
18255 of function; according to the following scheme: one byte return value in
18260 , two byte value in
18269 three byte values (generic pointers) in
18281 , and four byte values in
18299 \begin_inset LatexCommand \index{generic pointer}
18303 contain type of accessed memory in
18324 \begin_inset Note Note
18327 \begin_layout Standard
18328 This might not be the case of certain memory models (medium???)
18336 \begin_layout Standard
18337 The second parameter onwards is either allocated on the stack (for reentrant
18342 \begin_layout Standard
18351 -stack-auto is used) or in data/xdata memory (depending on the memory model).
18354 \begin_layout Standard
18355 Bit parameters are passed in a virtual register called 'bits' in bit-addressable
18356 space for reentrant functions or allocated directly in bit memory otherwise.
18359 \begin_layout Standard
18360 Functions (with two or more parameters or bit parameters) that are called
18361 through function pointers
18362 \begin_inset LatexCommand \index{function pointers}
18366 must therefor be reentrant so the compiler knows how to pass the parameters.
18369 \begin_layout Subsection
18373 \begin_layout Standard
18374 Unless the called function is declared as
18379 \begin_inset LatexCommand \index{naked}
18387 \begin_layout Standard
18397 \begin_inset LatexCommand \index{-\/-callee-saves}
18405 \begin_layout Standard
18414 -all-callee-saves command line option or the corresponding callee_saves
18415 pragma are used, the caller will save the registers (
18419 ) around the call, so the called function can destroy they content freely.
18422 \begin_layout Standard
18423 If the called function is not declared as
18427 , the caller will swap register banks around the call, if caller and callee
18428 use different register banks (having them defined by the
18436 \begin_layout Standard
18437 The called function can also use
18453 observing that they are used for parameter/return value passing.
18456 \begin_layout Subsection
18457 Assembler Routine (non-reentrant)
18460 \begin_layout Standard
18461 In the following example
18462 \begin_inset LatexCommand \index{reentrant}
18467 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
18471 the function c_func calls an assembler routine asm_func, which takes two
18473 \begin_inset LatexCommand \index{function parameter}
18480 \begin_layout Verse
18483 extern int asm_func(unsigned char, unsigned char);
18487 int c_func (unsigned char
18488 i, unsigned char j)
18496 return asm_func(i,j);
18510 return c_func(10,9);
18515 \begin_layout Standard
18516 The corresponding assembler function is:
18519 \begin_layout Verse
18522 .globl _asm_func_PARM_2
18624 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
18641 \begin_layout Standard
18642 The parameter naming convention is _<function_name>_PARM_<n>, where n is
18643 the parameter number starting from 1, and counting from the left.
18644 The first parameter is passed in
18660 according to the description above.
18661 The variable name for the second parameter will be _<function_name>_PARM_2.
18666 ble the assembler routine with the following command:
18673 asx8051 -losg asmfunc.asm
18680 Then compile and link the assembler routine to the C source file with the
18688 sdcc cfunc.c asmfunc.rel
18691 \begin_layout Subsection
18692 Assembler Routine (reentrant)
18695 \begin_layout Standard
18697 \begin_inset LatexCommand \index{reentrant}
18702 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
18706 the second parameter
18707 \begin_inset LatexCommand \index{function parameter}
18711 onwards will be passed on the stack, the parameters are pushed from right
18713 before the call the second leftmost parameter will be on the top of the
18714 stack (the leftmost parameter is passed in registers).
18715 Here is an example:
18718 \begin_layout Verse
18721 extern int asm_func(unsigned char, unsigned char, unsigned char) reentrant;
18726 c_func (unsigned char i, unsigned char j, unsigned char k) reentrant
18735 return asm_func(i,j,k);
18749 return c_func(10,9,8);
18754 \begin_layout Standard
18755 The corresponding (unoptimized) assembler routine is:
18758 \begin_layout Verse
18778 _bp,sp\InsetSpace ~
18784 ;stack contains: _bp, return
18785 address, second parameter, third parameter
18809 a,#0xfd\InsetSpace ~
18815 pointer to the second parameter
18839 a,#0xfc\InsetSpace ~
18845 to the rightmost parameter
18886 result (= sum of all three parameters)
18901 ;return value goes into dptr
18935 \begin_layout Standard
18936 The compiling and linking procedure remains the same, however note the extra
18937 entry & exit linkage required for the assembler code, _bp is the stack
18938 frame pointer and is used to compute the offset into the stack for parameters
18939 and local variables.
18940 \begin_inset VSpace bigskip
18946 \begin_layout Section
18948 \begin_inset LatexCommand \index{int (16 bit)}
18953 \begin_inset LatexCommand \index{long (32 bit)}
18960 \begin_layout Standard
18961 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
18962 multiplication and modulus operations are implemented by support routines.
18963 These support routines are all developed in ANSI-C to facilitate porting
18964 to other MCUs, although some model specific assembler optimizations are
18966 The following files contain the described routines, all of them can be
18967 found in <installdir>/share/sdcc/lib.
18972 \begin_layout Standard
18974 \begin_inset Tabular
18975 <lyxtabular version="3" rows="11" columns="2">
18977 <column alignment="left" valignment="top" leftline="true" width="0">
18978 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
18979 <row topline="true" bottomline="true">
18980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18983 \begin_layout Standard
18991 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18994 \begin_layout Standard
19003 <row topline="true">
19004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19007 \begin_layout Standard
19013 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19016 \begin_layout Standard
19017 16 bit multiplication
19023 <row topline="true">
19024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19027 \begin_layout Standard
19033 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19036 \begin_layout Standard
19037 signed 16 bit division (calls _divuint)
19043 <row topline="true">
19044 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19047 \begin_layout Standard
19053 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19056 \begin_layout Standard
19057 unsigned 16 bit division
19063 <row topline="true">
19064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19067 \begin_layout Standard
19073 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19076 \begin_layout Standard
19077 signed 16 bit modulus (calls _moduint)
19083 <row topline="true">
19084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19087 \begin_layout Standard
19093 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19096 \begin_layout Standard
19097 unsigned 16 bit modulus
19103 <row topline="true">
19104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19107 \begin_layout Standard
19113 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19116 \begin_layout Standard
19117 32 bit multiplication
19123 <row topline="true">
19124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19127 \begin_layout Standard
19133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19136 \begin_layout Standard
19137 signed 32 division (calls _divulong)
19143 <row topline="true">
19144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19147 \begin_layout Standard
19153 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19156 \begin_layout Standard
19157 unsigned 32 division
19163 <row topline="true">
19164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19167 \begin_layout Standard
19173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19176 \begin_layout Standard
19177 signed 32 bit modulus (calls _modulong)
19183 <row topline="true" bottomline="true">
19184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19187 \begin_layout Standard
19193 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19196 \begin_layout Standard
19197 unsigned 32 bit modulus
19212 \begin_layout Standard
19213 Since they are compiled as
19218 \begin_inset LatexCommand \index{reentrant}
19223 \begin_inset LatexCommand \index{interrupt}
19227 service routines should not do any of the above operations.
19228 If this is unavoidable then the above routines will need to be compiled
19235 \begin_layout Standard
19245 \begin_inset LatexCommand \index{-\/-stack-auto}
19251 option, after which the source program will have to be compiled with
19257 \begin_layout Standard
19267 \begin_inset LatexCommand \index{-\/-int-long-reent}
19274 Notice that you don't have to call these routines directly.
19275 The compiler will use them automatically every time an integer operation
19279 \begin_layout Section
19280 Floating Point Support
19281 \begin_inset LatexCommand \index{Floating point support}
19288 \begin_layout Standard
19289 SDCC supports IEEE (single precision 4 bytes) floating point numbers.
19290 The floating point support routines are derived from gcc's floatlib.c and
19291 consist of the following routines:
19296 \begin_layout Standard
19300 \begin_inset Tabular
19301 <lyxtabular version="3" rows="17" columns="2">
19303 <column alignment="left" valignment="top" leftline="true" width="0">
19304 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
19305 <row topline="true" bottomline="true">
19306 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19309 \begin_layout Standard
19324 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19327 \begin_layout Standard
19334 <row topline="true">
19335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19338 \begin_layout Standard
19353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19356 \begin_layout Standard
19366 add floating point numbers
19372 <row topline="true">
19373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19376 \begin_layout Standard
19391 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19394 \begin_layout Standard
19404 subtract floating point numbers
19410 <row topline="true">
19411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19414 \begin_layout Standard
19429 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19432 \begin_layout Standard
19442 divide floating point numbers
19448 <row topline="true">
19449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19452 \begin_layout Standard
19467 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19470 \begin_layout Standard
19480 multiply floating point numbers
19486 <row topline="true">
19487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19490 \begin_layout Standard
19505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19508 \begin_layout Standard
19518 convert floating point to unsigned char
19524 <row topline="true">
19525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19528 \begin_layout Standard
19543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19546 \begin_layout Standard
19556 convert floating point to signed char
19562 <row topline="true">
19563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19566 \begin_layout Standard
19581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19584 \begin_layout Standard
19594 convert floating point to unsigned int
19600 <row topline="true">
19601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19604 \begin_layout Standard
19619 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19622 \begin_layout Standard
19632 convert floating point to signed int
19638 <row topline="true">
19639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19642 \begin_layout Standard
19665 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19668 \begin_layout Standard
19678 convert floating point to unsigned long
19684 <row topline="true">
19685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19688 \begin_layout Standard
19703 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19706 \begin_layout Standard
19716 convert floating point to signed long
19722 <row topline="true">
19723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19726 \begin_layout Standard
19741 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19744 \begin_layout Standard
19754 convert unsigned char to floating point
19760 <row topline="true">
19761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19764 \begin_layout Standard
19779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19782 \begin_layout Standard
19792 convert char to floating point number
19798 <row topline="true">
19799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19802 \begin_layout Standard
19817 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19820 \begin_layout Standard
19830 convert unsigned int to floating point
19836 <row topline="true">
19837 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19840 \begin_layout Standard
19855 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19858 \begin_layout Standard
19868 convert int to floating point numbers
19874 <row topline="true">
19875 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19878 \begin_layout Standard
19893 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19896 \begin_layout Standard
19906 convert unsigned long to floating point number
19912 <row topline="true" bottomline="true">
19913 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19916 \begin_layout Standard
19931 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19934 \begin_layout Standard
19944 convert long to floating point number
19959 \begin_layout Standard
19960 These support routines are developed in ANSI-C so there is room for space
19961 and speed improvement
19965 \begin_layout Standard
19966 These floating point routines (
19970 sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
19977 Note if all these routines are used simultaneously the data space might
19979 For serious floating point usage the large model might be needed.
19980 Also notice that you don't have to call this routines directly.
19981 The compiler will use them automatically every time a floating point operation
19983 \begin_inset VSpace bigskip
19989 \begin_layout Section
19991 \begin_inset LatexCommand \index{Libraries}
19998 \begin_layout Standard
20001 <pending: this is messy and incomplete - a little more information is in
20002 sdcc/doc/libdoc.txt
20007 \begin_layout Subsection
20008 Compiler support routines (_gptrget, _mulint etc.)
20011 \begin_layout Subsection
20012 Stdclib functions (puts, printf, strcat etc.)
20015 \begin_layout Subsubsection
20019 \begin_layout Paragraph
20020 getchar(), putchar()
20023 \begin_layout Standard
20024 \begin_inset LatexCommand \index{<stdio.h>}
20028 As usual on embedded systems you have to provide your own
20031 \begin_inset LatexCommand \index{getchar()}
20040 \begin_inset LatexCommand \index{putchar()}
20047 SDCC does not know whether the system connects to a serial line with or
20048 without handshake, LCD, keyboard or other device.
20062 You'll find examples for serial routines f.e.
20063 in sdcc/device/lib.
20064 For the mcs51 this minimalistic polling
20068 routine might be a start:
20071 \begin_layout Verse
20074 void putchar (char c) {
20080 while (!TI)\InsetSpace ~
20083 /* assumes UART is initialized */
20111 \begin_layout Paragraph
20115 \begin_layout Standard
20119 \begin_inset LatexCommand \index{printf()}
20129 does not support float (except on ds390).
20130 To enable this recompile it with the option
20136 \begin_layout Standard
20146 \begin_inset LatexCommand \index{USE\_FLOATS}
20152 on the command line.
20159 \begin_layout Standard
20169 \begin_inset LatexCommand \index{-\/-model-large}
20175 for the mcs51 port, since this uses a lot of memory.
20178 \begin_layout Standard
20179 If you're short on code memory you might want to use
20182 \begin_inset LatexCommand \index{printf\_small()}
20197 For the mcs51 there additionally are assembly versions
20200 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
20206 (subset of printf using less than 270 bytes) and
20209 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
20218 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
20224 (floating-point aware version of printf_fast) which should fit the requirements
20225 of many embedded systems (printf_fast() can be customized by unsetting
20230 support long variables and field widths).
20231 Be sure to use only one of these printf options within a project.
20236 \begin_layout Standard
20237 Feature matrix of different
20244 \begin_layout Standard
20245 \begin_inset Tabular
20246 <lyxtabular version="3" rows="14" columns="7">
20247 <features islongtable="true">
20248 <column alignment="left" valignment="middle" leftline="true" width="14col%">
20249 <column alignment="center" valignment="top" leftline="true" width="0">
20250 <column alignment="center" valignment="top" leftline="true" width="12col%">
20251 <column alignment="center" valignment="top" leftline="true" width="10col%">
20252 <column alignment="center" valignment="top" leftline="true" width="0">
20253 <column alignment="center" valignment="top" leftline="true" rightline="true" width="12col%">
20254 <column alignment="center" valignment="top" rightline="true" width="0">
20255 <row topline="true" bottomline="true" endhead="true">
20256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20259 \begin_layout Standard
20268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20271 \begin_layout Standard
20273 \begin_inset LatexCommand \index{printf}
20282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20285 \begin_layout Standard
20293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20296 \begin_layout Standard
20302 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20305 \begin_layout Standard
20311 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20314 \begin_layout Standard
20320 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20323 \begin_layout Standard
20330 <row topline="true" endhead="true">
20331 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20334 \begin_layout Standard
20340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20343 \begin_layout Standard
20351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20354 \begin_layout Standard
20362 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20365 \begin_layout Standard
20373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20376 \begin_layout Standard
20384 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20387 \begin_layout Standard
20395 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20398 \begin_layout Standard
20407 <row topline="true" endhead="true">
20408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20411 \begin_layout Standard
20412 \begin_inset Quotes sld
20416 \begin_inset Quotes srd
20422 \begin_layout Standard
20428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20431 \begin_layout Standard
20437 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
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" rightline="true" usebox="none">
20476 \begin_layout Standard
20483 <row topline="true" endhead="true">
20484 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20487 \begin_layout Standard
20491 \begin_layout Standard
20497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20500 \begin_layout Standard
20506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20509 \begin_layout Standard
20515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20518 \begin_layout Standard
20519 0.45k / 0.47k (+ _ltoa)
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" rightline="true" usebox="none">
20536 \begin_layout Standard
20542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20545 \begin_layout Standard
20552 <row topline="true">
20553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20556 \begin_layout Standard
20562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20565 \begin_layout Standard
20575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20578 \begin_layout Standard
20625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20628 \begin_layout Standard
20667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20670 \begin_layout Standard
20676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20679 \begin_layout Standard
20685 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20688 \begin_layout Standard
20695 <row topline="true">
20696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20699 \begin_layout Standard
20700 long (32 bit) support
20705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20708 \begin_layout Standard
20714 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20717 \begin_layout Standard
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" rightline="true" usebox="none">
20744 \begin_layout Standard
20759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20762 \begin_layout Standard
20769 <row topline="true">
20770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20773 \begin_layout Standard
20774 byte arguments on stack
20779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20782 \begin_layout Standard
20788 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20791 \begin_layout Standard
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" rightline="true" usebox="none">
20818 \begin_layout Standard
20824 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20827 \begin_layout Standard
20834 <row topline="true">
20835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20838 \begin_layout Standard
20840 \begin_inset LatexCommand \index{Floating point support}
20849 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20852 \begin_layout Standard
20858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20861 \begin_layout Standard
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" rightline="true" usebox="none">
20888 \begin_layout Standard
20893 \begin_layout Standard
20894 Range limited to +/- 4294967040, precision limited to 8 digits past decimal
20904 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20907 \begin_layout Standard
20914 <row topline="true">
20915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20918 \begin_layout Standard
20919 float formats %e %g
20924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20927 \begin_layout Standard
20933 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20936 \begin_layout Standard
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" rightline="true" usebox="none">
20963 \begin_layout Standard
20969 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20972 \begin_layout Standard
20979 <row topline="true" bottomline="true">
20980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20983 \begin_layout Standard
20989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20992 \begin_layout Standard
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" rightline="true" usebox="none">
21028 \begin_layout Standard
21034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21037 \begin_layout Standard
21044 <row bottomline="true">
21045 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21048 \begin_layout Standard
21053 \begin_layout Standard
21054 Execution time of printf("%s%c%s%c%c%c", "Hello", ' ', "World", '!', '
21058 n'); standard 8051 @ 22.1184 MHz, empty putchar()
21066 \begin_layout Standard
21072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21075 \begin_layout Standard
21081 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
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" rightline="true" usebox="none">
21120 \begin_layout Standard
21127 <row bottomline="true">
21128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21131 \begin_layout Standard
21136 \begin_layout Standard
21137 Execution time of printf("%d", -12345); standard 8051 @ 22.1184 MHz, empty
21146 \begin_layout Standard
21152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21155 \begin_layout Standard
21161 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
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" rightline="true" usebox="none">
21200 \begin_layout Standard
21205 \begin_layout Standard
21206 printf_tiny integer speed is data dependent, worst case is 0.33 ms
21217 <row bottomline="true">
21218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21221 \begin_layout Standard
21226 \begin_layout Standard
21227 Execution time of printf("%ld", -123456789); standard 8051 @ 22.1184 MHz,
21236 \begin_layout Standard
21242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21245 \begin_layout Standard
21251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
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" rightline="true" usebox="none">
21290 \begin_layout Standard
21297 <row bottomline="true">
21298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21301 \begin_layout Standard
21306 \begin_layout Standard
21307 Execution time of printf("%.3f", -12345.678); standard 8051 @ 22.1184 MHz,
21316 \begin_layout Standard
21322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21325 \begin_layout Standard
21331 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
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" rightline="true" usebox="none">
21370 \begin_layout Standard
21384 \begin_layout Subsubsection
21386 \begin_inset LatexCommand \index{malloc.h}
21393 \begin_layout Standard
21394 As of SDCC 2.6.2 you no longer need to call an initialization routine before
21395 using dynamic memory allocation
21396 \begin_inset LatexCommand \index{dynamic memory allocation (malloc)}
21401 \begin_inset LatexCommand \index{heap (malloc)}
21405 space of 1024 bytes is provided for malloc to allocate memory from.
21406 If you need a different heap size you need to recompile _heap.c with the
21407 required size defined in HEAP_SIZE.
21408 It is recommended to make a copy of this file into your project directory
21409 and compile it there with:
21412 \begin_layout Verse
21415 sdcc -c _heap.c -D HEAD_SIZE=2048
21418 \begin_layout Standard
21419 And then link it with:
21422 \begin_layout Verse
21425 sdcc main.rel _heap.rel
21428 \begin_layout Subsection
21429 Math functions (sinf, powf, sqrtf etc.)
21432 \begin_layout Subsubsection
21436 \begin_layout Standard
21437 See definitions in file <math.h>.
21440 \begin_layout Subsection
21444 \begin_layout Standard
21446 \begin_inset LatexCommand \index{Libraries}
21450 included in SDCC should have a license at least as liberal as the GNU Lesser
21451 General Public License
21452 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
21463 \begin_layout Standard
21464 \begin_inset Note Note
21467 \begin_layout Standard
21468 license statements for the libraries are missing.
21469 sdcc/device/lib/ser_ir.c
21472 \begin_layout Standard
21474 come with a GPL (as opposed to LGPL) License - this will not be liberal
21475 enough for many embedded programmers.
21483 \begin_layout Standard
21484 If you have ported some library or want to share experience about some code
21486 falls into any of these categories Busses (I
21487 \begin_inset Formula $^{\textrm{2}}$
21490 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
21491 cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
21492 Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
21493 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
21498 would certainly like to hear about it.
21501 \begin_layout Standard
21502 Programmers coding for embedded systems are not especially famous for being
21503 enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
21504 e these references are very valuable.
21505 Let's help to create a climate where information is shared.
21506 \begin_inset VSpace bigskip
21512 \begin_layout Section
21516 \begin_layout Subsection
21517 MCS51 Memory Models
21518 \begin_inset LatexCommand \index{Memory model}
21523 \begin_inset LatexCommand \index{MCS51 memory model}
21530 \begin_layout Subsubsection
21531 Small, Medium and Large
21534 \begin_layout Standard
21535 SDCC allows three memory models for MCS51 code,
21544 Modules compiled with different memory models should
21548 be combined together or the results would be unpredictable.
21549 The library routines supplied with the compiler are compiled as small,
21551 The compiled library modules are contained in separate directories as small,
21552 medium and large so that you can link to the appropriate set.
21555 \begin_layout Standard
21556 When the medium or large model is used all variables declared without a
21557 storage class will be allocated into the external ram, this includes all
21558 parameters and local variables (for non-reentrant
21559 \begin_inset LatexCommand \index{reentrant}
21564 When the small model is used variables without storage class are allocated
21565 in the internal ram.
21568 \begin_layout Standard
21569 Judicious usage of the processor specific storage classes
21570 \begin_inset LatexCommand \index{Storage class}
21574 and the 'reentrant' function type will yield much more efficient code,
21575 than using the large model.
21576 Several optimizations are disabled when the program is compiled using the
21577 large model, it is therefore recommended that the small model be used unless
21578 absolutely required.
21581 \begin_layout Subsubsection
21583 \begin_inset LatexCommand \label{sub:External-Stack}
21588 \begin_inset LatexCommand \index{stack}
21593 \begin_inset LatexCommand \index{External stack (mcs51)}
21600 \begin_layout Standard
21601 The external stack (-
21605 \begin_layout Standard
21615 \begin_inset LatexCommand \index{-\/-xstack}
21619 ) is located in pdata
21620 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
21624 memory (usually at the start of the external ram segment) and uses all
21625 unused space in pdata (max.
21631 \begin_layout Standard
21640 -xstack option is used to compile the program, the parameters and local
21642 \begin_inset LatexCommand \index{local variables}
21646 of all reentrant functions are allocated in this area.
21647 This option is provided for programs with large stack space requirements.
21648 When used with the -
21652 \begin_layout Standard
21662 \begin_inset LatexCommand \index{-\/-stack-auto}
21666 option, all parameters and local variables are allocated on the external
21667 stack (note: support libraries will need to be recompiled with the same
21669 There is a predefined target in the library makefile).
21672 \begin_layout Standard
21673 The compiler outputs the higher order address byte of the external ram segment
21675 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
21680 \begin_inset LatexCommand \ref{sub:MCS51-variants}
21684 ), therefore when using the External Stack option, this port
21688 be used by the application program.
21691 \begin_layout Subsection
21693 \begin_inset LatexCommand \index{Memory model}
21698 \begin_inset LatexCommand \index{DS390 memory model}
21705 \begin_layout Standard
21706 The only model supported is Flat 24
21707 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
21712 This generates code for the 24 bit contiguous addressing mode of the Dallas
21714 In this mode, up to four meg of external RAM or code space can be directly
21716 See the data sheets at www.dalsemi.com for further information on this part.
21721 that the compiler does not generate any code to place the processor into
21722 24 bitmode (although
21726 in the ds390 libraries will do that for you).
21732 \begin_inset LatexCommand \index{Tinibios (DS390)}
21736 , the boot loader or similar code must ensure that the processor is in 24
21737 bit contiguous addressing mode before calling the SDCC startup code.
21748 \begin_layout Standard
21759 option, variables will by default be placed into the XDATA segment.
21764 Segments may be placed anywhere in the 4 meg address space using the usual
21769 \begin_layout Standard
21779 Note that if any segments are located above 64K, the -r flag must be passed
21780 to the linker to generate the proper segment relocations, and the Intel
21781 HEX output format must be used.
21782 The -r flag can be passed to the linker by using the option
21786 on the SDCC command line.
21787 However, currently the linker can not handle code segments > 64k.
21790 \begin_layout Section
21792 \begin_inset LatexCommand \label{sec:Pragmas}
21797 \begin_inset LatexCommand \index{Pragmas}
21804 \begin_layout Standard
21805 Pragmas are used to turn on and/or off certain compiler options.
21806 Some of them are closely related to corresponding command-line options
21808 \begin_inset LatexCommand \vref{sec:Command-Line-Options}
21814 Pragmas should be placed before and/or after a function, placing pragmas
21815 inside a function body could have unpredictable results.
21820 following #pragma directives:
21823 \begin_layout Itemize
21829 \begin_inset LatexCommand \index{\#pragma save}
21833 - this will save most current options to the save/restore stack.
21834 See #pragma\InsetSpace ~
21838 \begin_layout Itemize
21844 \begin_inset LatexCommand \index{\#pragma restore}
21848 - will restore saved options from the last save.
21849 saves & restores can be nested.
21850 SDCC uses a save/restore stack: save pushes current options to the stack,
21851 restore pulls current options from the stack.
21852 See #pragma\InsetSpace ~
21858 \begin_layout Itemize
21864 \begin_inset LatexCommand \index{\#pragma callee\_saves}
21869 \begin_inset LatexCommand \index{function prologue}
21873 function1[,function2[,function3...]]
21874 \begin_inset LatexCommand \label{ite:callee_saves-function1[,function2[,function3...]]--}
21878 - The compiler by default uses a caller saves convention for register saving
21879 across function calls, however this can cause unnecessary register pushing
21881 \begin_inset LatexCommand \index{push/pop}
21885 when calling small functions from larger functions.
21886 This option can be used to switch off the register saving convention for
21887 the function names specified.
21888 The compiler will not save registers when calling these functions, extra
21889 code need to be manually inserted at the entry and exit for these functions
21890 to save and restore the registers used by these functions, this can SUBSTANTIAL
21891 LY reduce code and improve run time performance of the generated code.
21892 In the future the compiler (with inter procedural analysis) may be able
21893 to determine the appropriate scheme to use for each function call.
21898 \begin_layout Standard
21907 -callee-saves command line option is used (see page
21908 \begin_inset LatexCommand \vpageref{lyx:--callee-saves-function1[,function2][,function3]...}
21912 ), the function names specified in #pragma\InsetSpace ~
21914 \begin_inset LatexCommand \index{\#pragma callee\_saves}
21918 is appended to the list of functions specified in the command line.
21921 \begin_layout Itemize
21927 \begin_inset LatexCommand \index{\#pragma exclude}
21931 none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
21932 of pairs of push/pop
21933 \begin_inset LatexCommand \index{push/pop}
21942 \begin_inset LatexCommand \index{interrupt}
21955 The directive should be placed immediately before the ISR function definition
21956 and it affects ALL ISR functions following it.
21957 To enable the normal register saving for ISR functions use #pragma\InsetSpace ~
21958 exclude\InsetSpace ~
21960 \begin_inset LatexCommand \index{\#pragma exclude}
21965 See also the related keyword _naked
21966 \begin_inset LatexCommand \index{\_naked}
21971 \begin_inset LatexCommand \index{\_\_naked}
21978 \begin_layout Itemize
21984 \begin_inset LatexCommand \index{pedantic}
21989 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
21994 \begin_inset LatexCommand \label{ite:less_pedantic}
21998 - the compiler will not warn you anymore for obvious mistakes, you're on
22000 See also the command line option -
22004 \begin_layout Standard
22014 \begin_inset LatexCommand \vpageref{lyx:--less-pedantic}
22021 More specifically, the following warnings will be disabled:
22023 comparison is always [true/false] due to limited range of data type
22027 overflow in implicit constant conversion
22029 (158); [the (in)famous]
22031 conditional flow changed by optimizer: so said EVELYN the modified DOG
22035 function '[function name]' must return value
22040 Furthermore, warnings of less importance (of PEDANTIC and INFO warning
22041 level) are disabled, too, namely:
22044 \begin_inset Note Note
22047 \begin_layout Standard
22048 dunno what comes here - this warning appears to be unused altogether
22057 [left/right] shifting more than size of object changed to zero
22065 integer overflow in expression
22069 unmatched #pragma save and #pragma restore
22073 comparison of 'signed char' with 'unsigned char' requires promotion to int
22077 ISO C90 does not support flexible array members
22081 extended stack by [number] bytes for compiler temp(s) :in function '[function\InsetSpace ~
22085 \begin_inset Note Note
22088 \begin_layout Standard
22089 appears to be always blank - what was supposed to be here?
22098 function '[function name]', # edges [number] , # nodes [number] , cyclomatic
22099 complexity [number]
22104 \begin_layout Itemize
22110 \begin_inset LatexCommand \index{\#pragma disable\_warning}
22114 - the compiler will not warn you anymore about warning number <nnnn>.
22117 \begin_layout Itemize
22123 \begin_inset LatexCommand \index{\#pragma nogcse}
22127 - will stop global common subexpression elimination.
22130 \begin_layout Itemize
22136 \begin_inset LatexCommand \index{\#pragma noinduction}
22140 - will stop loop induction optimizations.
22143 \begin_layout Itemize
22149 \begin_inset LatexCommand \index{\#pragma noinvariant}
22153 - will not do loop invariant optimizations.
22154 For more details see Loop Invariants in section
22155 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
22162 \begin_layout Itemize
22168 \begin_inset LatexCommand \index{\#pragma noiv}
22172 - Do not generate interrupt
22173 \begin_inset LatexCommand \index{interrupt}
22178 \begin_inset LatexCommand \index{interrupt vector table}
22182 entries for all ISR functions defined after the pragma.
22183 This is useful in cases where the interrupt vector table must be defined
22184 manually, or when there is a secondary, manually defined interrupt vector
22186 for the autovector feature of the Cypress EZ-USB FX2).
22187 More elegantly this can be achieved by obmitting the optional interrupt
22188 number after the interrupt keyword, see section
22189 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
22197 \begin_layout Itemize
22203 \begin_inset LatexCommand \index{\#pragma nojtbound}
22207 - will not generate code for boundary value checking, when switch statements
22208 are turned into jump-tables (dangerous).
22209 For more details see section
22210 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
22217 \begin_layout Itemize
22223 \begin_inset LatexCommand \index{\#pragma noloopreverse}
22227 - Will not do loop reversal optimization
22230 \begin_layout Itemize
22236 \begin_inset LatexCommand \index{\#pragma nooverlay}
22240 - the compiler will not overlay the parameters and local variables of a
22244 \begin_layout Itemize
22250 \begin_inset LatexCommand \index{\#pragma stackauto}
22258 \begin_layout Standard
22268 \begin_inset LatexCommand \index{-\/-stack-auto}
22273 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
22277 Parameters and Local Variables.
22280 \begin_layout Itemize
22286 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
22290 - The compiler will optimize code generation towards fast code, possibly
22291 at the expense of code size.
22292 Currently this has little effect.
22295 \begin_layout Itemize
22301 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
22305 - The compiler will optimize code generation towards compact code, possibly
22306 at the expense of code speed.
22307 Currently this has little effect.
22310 \begin_layout Itemize
22316 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
22320 - The compiler will attempt to generate code that is both compact and fast,
22321 as long as meeting one goal is not a detriment to the other (this is the
22326 \begin_layout Itemize
22332 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
22336 - Generally follow the C89 standard, but allow SDCC features that conflict
22337 with the standard (default).
22340 \begin_layout Itemize
22346 \begin_inset LatexCommand \index{\#pragma std\_c89}
22350 - Follow the C89 standard and disable SDCC features that conflict with the
22354 \begin_layout Itemize
22360 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
22364 - Generally follow the C99 standard, but allow SDCC features that conflict
22365 with the standard (incomplete support).
22368 \begin_layout Itemize
22374 \begin_inset LatexCommand \index{\#pragma std\_c99}
22378 - Follow the C99 standard and disable SDCC features that conflict with the
22379 standard (incomplete support).
22382 \begin_layout Itemize
22388 \begin_inset LatexCommand \index{\#pragma codeseg}
22392 - Use this name (max.
22393 8 characters) for the code segment.
22398 \begin_layout Standard
22410 \begin_layout Itemize
22416 \begin_inset LatexCommand \index{\#pragma constseg}
22420 - Use this name (max.
22421 8 characters) for the const segment.
22426 \begin_layout Standard
22438 \begin_layout Standard
22439 The preprocessor SDCPP
22440 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
22444 supports the following #pragma directives:
22447 \begin_layout Itemize
22450 pedantic_parse_number
22453 \begin_inset LatexCommand \index{pedantic}
22458 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
22463 \begin_inset LatexCommand \label{ite:pedantic_parse_number}
22467 - Pedantic parse numbers so that situations like 0xfe-LO_B(3) are parsed
22468 properly and the macro LO_B(3) gets expanded.
22474 \begin_layout Standard
22483 -pedantic-parse-number command line option
22484 \begin_inset LatexCommand \vpageref{lyx:-pedantic-parse-number}
22491 Below is an example on how to use this pragma.
22494 Note: this functionality is not in conformance with standard!
22497 \begin_layout Verse
22500 #pragma pedantic_parse_number +
22501 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
22509 #define LO_B(x) ((x) & 0xff)
22513 unsigned char foo(void)
22520 unsigned char c=0xfe-LO_B(3)
22535 \begin_layout Itemize
22541 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
22545 (+ | -) - switch _asm _endasm block preprocessing on / off.
22547 You use this prama to define multilines of assembly code.
22548 This will prevent the preprocessor from changing the formating required
22550 Below is an example on how to use this pragma.
22553 \begin_layout Verse
22556 #pragma preproc_asm -
22557 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
22563 #define MYDELAY _asm
22568 nop ;my assembly comment...
22582 #pragma preproc_asm
22613 \begin_layout Itemize
22619 \begin_inset LatexCommand \index{\#pragma sdcc\_hash}
22623 (+ | -) - Allow "naked" hash in macro definition, for example:
22627 #define DIR_LO(x) #(x & 0xff)
22632 Below is an example on how to use this pragma.
22635 \begin_layout Verse
22638 #pragma preproc_asm +
22640 #pragma sdcc_hash +
22641 \begin_inset LatexCommand \index{\#pragma sdcc\_hash}
22656 mov R6_B3, #(x & 0xff)
22663 mov R7_B3, #((x >> 8) & 0xff)
22687 \begin_layout Standard
22688 Some of the pragmas are intended to be used to turn-on or off certain optimizati
22689 ons which might cause the compiler to generate extra stack and/or data space
22690 to store compiler generated temporary variables.
22691 This usually happens in large functions.
22692 Pragma directives should be used as shown in the following example, they
22693 are used to control options and optimizations for a given function.
22697 \begin_layout Verse
22701 \begin_inset LatexCommand \index{\#pragma save}
22712 /* save the current settings */
22715 \begin_inset LatexCommand \index{\#pragma nogcse}
22724 /* turnoff global subexpression elimination */
22726 #pragma noinduction
22727 \begin_inset LatexCommand \index{\#pragma noinduction}
22731 /* turn off induction optimizations */
22754 \begin_inset LatexCommand \index{\#pragma restore}
22758 /* turn the optimizations back on */
22761 \begin_layout Standard
22762 The compiler will generate a warning message when extra space is allocated.
22763 It is strongly recommended that the save and restore pragmas be used when
22764 changing options for a function.
22773 \begin_layout Section
22774 Defines Created by the Compiler
22777 \begin_layout Standard
22778 The compiler creates the following #defines
22779 \begin_inset LatexCommand \index{\#defines}
22784 \begin_inset LatexCommand \index{Defines created by the compiler}
22793 \begin_layout Standard
22794 \begin_inset Tabular
22795 <lyxtabular version="3" rows="15" columns="2">
22797 <column alignment="left" valignment="top" leftline="true" width="3in">
22798 <column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
22799 <row topline="true" bottomline="true">
22800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22803 \begin_layout Standard
22811 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22814 \begin_layout Standard
22823 <row topline="true">
22824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22827 \begin_layout Standard
22829 \begin_inset LatexCommand \index{SDCC}
22838 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22841 \begin_layout Standard
22843 Since version 2.5.6 the version number as an int (ex.
22850 <row topline="true">
22851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22854 \begin_layout Standard
22856 \begin_inset LatexCommand \index{SDCC\_mcs51}
22861 \begin_inset LatexCommand \index{SDCC\_ds390}
22866 \begin_inset LatexCommand \index{SDCC\_z80}
22875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22878 \begin_layout Standard
22879 depending on the model used (e.g.: -mds390)
22885 <row topline="true">
22886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22889 \begin_layout Standard
22891 \begin_inset LatexCommand \index{\_\_mcs51}
22896 \begin_inset LatexCommand \index{\_\_ds390}
22901 \begin_inset LatexCommand \index{\_\_hc08}
22906 \begin_inset LatexCommand \index{\_\_z80}
22915 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22918 \begin_layout Standard
22919 depending on the model used (e.g.
22926 <row topline="true">
22927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22930 \begin_layout Standard
22932 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
22941 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22944 \begin_layout Standard
22951 \begin_layout Standard
22968 <row topline="true">
22969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22972 \begin_layout Standard
22974 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
22983 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22986 \begin_layout Standard
22993 \begin_layout Standard
23010 <row topline="true">
23011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23014 \begin_layout Standard
23016 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
23025 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23028 \begin_layout Standard
23035 \begin_layout Standard
23052 <row topline="true">
23053 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23056 \begin_layout Standard
23058 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
23067 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23070 \begin_layout Standard
23077 \begin_layout Standard
23094 <row topline="true">
23095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23098 \begin_layout Standard
23100 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
23109 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23112 \begin_layout Standard
23119 \begin_layout Standard
23136 <row topline="true">
23137 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23140 \begin_layout Standard
23142 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
23151 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23154 \begin_layout Standard
23165 <row topline="true">
23166 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23169 \begin_layout Standard
23171 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
23180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23183 \begin_layout Standard
23194 <row topline="true">
23195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23198 \begin_layout Standard
23200 \begin_inset LatexCommand \index{SDCC\_REVISION}
23209 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23212 \begin_layout Standard
23214 SDCC svn revision number
23220 <row topline="true">
23221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23224 \begin_layout Standard
23225 SDCC_PARMS_IN_BANK1
23226 \begin_inset LatexCommand \index{SDCC\_PARMS\_IN\_BANK1}
23235 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23238 \begin_layout Standard
23245 \begin_layout Standard
23262 <row topline="true">
23263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23266 \begin_layout Standard
23268 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
23277 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23280 \begin_layout Standard
23287 \begin_layout Standard
23304 <row topline="true" bottomline="true">
23305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23308 \begin_layout Standard
23309 SDCC_INT_LONG_REENT
23310 \begin_inset LatexCommand \index{SDCC\_INT\_LONG\_REENT}
23319 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23322 \begin_layout Standard
23329 \begin_layout Standard
23353 \begin_layout Chapter
23354 Notes on supported Processors
23357 \begin_layout Section
23359 \begin_inset LatexCommand \label{sub:MCS51-variants}
23364 \begin_inset LatexCommand \index{MCS51 variants}
23371 \begin_layout Standard
23372 MCS51 processors are available from many vendors and come in many different
23374 While they might differ considerably in respect to Special Function Registers
23375 the core MCS51 is usually not modified or is kept compatible.
23379 \begin_layout Subsection
23380 pdata access by SFR
23383 \begin_layout Standard
23384 With the upcome of devices with internal xdata and flash memory devices
23386 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
23390 as dedicated I/O port is becoming more popular.
23391 Switching the high byte for pdata
23392 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
23396 access which was formerly done by port P2 is then achieved by a Special
23398 \begin_inset LatexCommand \index{sfr}
23403 In well-established MCS51 tradition the address of this
23407 is where the chip designers decided to put it.
23408 Needless to say that they didn't agree on a common name either.
23409 So that the startup code can correctly initialize xdata variables, you
23410 should define an sfr with the name _XPAGE
23413 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
23419 at the appropriate location if the default, port P2, is not used for this.
23423 \begin_layout Verse
23426 __sfr __at (0x85) _XPAGE; /* Ramtron VRS51 family a.k.a.
23430 \begin_layout Verse
23433 __sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family, Texas Instruments (Chipcon)
23438 \begin_layout Verse
23441 __sfr __at (0x91) _XPAGE; /* Infineon (Siemens) C500 family a.k.a.
23445 \begin_layout Verse
23448 __sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
23452 \begin_layout Verse
23455 __sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
23459 \begin_layout Standard
23460 For more exotic implementations further customizations may be needed.
23462 \begin_inset LatexCommand \ref{sub:Startup-Code}
23466 for other possibilities.
23469 \begin_layout Subsection
23470 Other Features available by SFR
23473 \begin_layout Standard
23474 Some MCS51 variants offer features like Double DPTR
23475 \begin_inset LatexCommand \index{DPTR}
23479 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
23480 These are currently not used for the MCS51 port.
23481 If you absolutely need them you can fall back to inline assembly or submit
23485 \begin_layout Subsection
23489 \begin_layout Standard
23491 \begin_inset LatexCommand \index{Bankswitching}
23497 \begin_inset LatexCommand \index{code banking}
23501 ) is a technique to increase the code space above the 64k limit of the 8051.
23504 \begin_layout Subsubsection
23508 \begin_layout Standard
23509 \begin_inset Tabular
23510 <lyxtabular version="3" rows="3" columns="4">
23512 <column alignment="center" valignment="top" width="0">
23513 <column alignment="center" valignment="top" leftline="true" width="0">
23514 <column alignment="center" valignment="top" leftline="true" width="0">
23515 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
23516 <row topline="true" bottomline="true">
23517 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
23520 \begin_layout Standard
23526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23529 \begin_layout Standard
23535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23538 \begin_layout Standard
23544 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23547 \begin_layout Standard
23554 <row topline="true" bottomline="true">
23555 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
23558 \begin_layout Standard
23564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23567 \begin_layout Standard
23573 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
23576 \begin_layout Standard
23582 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23585 \begin_layout Standard
23593 <cell multicolumn="1" alignment="center" valignment="top" usebox="none">
23596 \begin_layout Standard
23597 SiLabs C8051F120 example
23602 <cell multicolumn="2" alignment="center" valignment="top" usebox="none">
23605 \begin_layout Standard
23611 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23614 \begin_layout Standard
23620 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23623 \begin_layout Standard
23638 Usually the hardware uses some sfr (an output port or an internal sfr) to
23639 select a bank and put it in the banked area of the memory map.
23640 The selected bank usually becomes active immediately upon assignment to
23641 this sfr and when running inside a bank it will switch out this code it
23642 is currently running.
23643 Therefor you cannot jump or call directly from one bank to another and
23644 need to use a so-called trampoline in the common area.
23645 For SDCC an example trampoline is in crtbank.asm and you may need to change
23646 it to your 8051 derivative or schematic.
23647 The presented code is written for the C8051F120.
23651 When calling a banked function
23652 SDCC will put the LSB of the functions address in register R0, the MSB
23653 in R1 and the bank in R2 and then call this trampoline
23658 The current selected bank is saved on the stack, the new bank is selected
23659 and an indirect jump is made.
23660 When the banked function returns it jumps to
23664 which restores the previous bank and returns to the caller.
23667 \begin_layout Subsubsection
23671 \begin_layout Standard
23672 When writing banked software using SDCC you need to use some special keywords
23674 You also need to take over a bit of work from the linker.
23678 To create a function
23679 that can be called from another bank it requires the keyword
23684 \begin_inset LatexCommand \index{banked}
23689 The caller must see this in the prototype of the callee and the callee
23690 needs it for a proper return.
23691 Called functions within the same bank as the caller do not need the
23695 keyword nor do functions in the common area.
23696 Beware: SDCC does not know or check if functions are in the same bank.
23697 This is your responsibility!
23701 Normally all functions you write end up in
23703 If you want a function explicitly to reside in the common area put it in
23705 This applies for instance to interrupt service routines as they should
23709 \begin_layout Standard
23710 Functions that need to be in a switched bank must be put in a named segment.
23711 The name can be mostly anything upto eight characters (e.g.
23713 To do this you either use -
23717 \begin_layout Standard
23726 -codeseg BANK1 (See
23727 \begin_inset LatexCommand \ref{lyx:-codeseg}
23731 ) on the command line when compiling or #pragma codeseg BANK1 (See
23732 \begin_inset LatexCommand \ref{sec:Pragmas}
23736 ) at the top of the C source file.
23737 The segment name always applies to the whole source file and generated
23738 object so functions for different banks need to be defined in different
23743 When linking your objects you need to tell the linker where
23744 to put your segments.
23745 To do this you use the following command line option to SDCC: -Wl-b BANK1=0x180
23747 \begin_inset LatexCommand \ref{lyx:-Wl option}
23752 This sets the virtual start address of this segment.
23753 It sets the banknumber to 0x01 and maps the bank to 0x8000 and up.
23754 The linker will not check for overflows, again this is your responsibility.
23757 \begin_layout Standard
23758 \begin_inset VSpace bigskip
23764 \begin_layout Section
23768 \begin_layout Standard
23770 \begin_inset LatexCommand \index{DS80C400}
23775 \begin_inset LatexCommand \index{DS400}
23779 microcontroller has a rich set of peripherals.
23780 In its built-in ROM library it includes functions to access some of the
23781 features, among them is a TCP stack with IP4 and IP6 support.
23782 Library headers (currently in beta status) and other files are provided
23786 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
23792 \begin_inset VSpace bigskip
23798 \begin_layout Section
23799 The Z80 and gbz80 port
23802 \begin_layout Standard
23803 SDCC can target both the Zilog Z80
23804 \begin_inset LatexCommand \index{Z80}
23808 and the Nintendo Gameboy's Z80-like gbz80
23809 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
23814 The Z80 port is passed through the same
23817 \begin_inset LatexCommand \index{Regression test}
23824 \begin_inset LatexCommand \ref{sec:Quality-control}
23828 ) as the MCS51 and DS390 ports, so floating point support, support for long
23829 variables and bitfield support is fine.
23830 See mailing lists and forums about interrupt routines.
23833 \begin_layout Standard
23834 As always, the code is the authoritative reference - see z80/ralloc.c and
23837 \begin_inset LatexCommand \index{Z80!stack}
23841 frame is similar to that generated by the IAR Z80 compiler.
23842 IX is used as the base pointer, HL and IY are used as a temporary registers,
23843 and BC and DE are available for holding variables.
23845 \begin_inset LatexCommand \index{Z80!return value}
23849 for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
23851 The gbz80 port use the same set of registers for the return values, but
23852 in a different order of significance: E (one byte), DE (two bytes), or
23854 \begin_inset VSpace bigskip
23860 \begin_layout Section
23864 \begin_layout Standard
23865 The port to the Freescale/Motorola HC08
23866 \begin_inset LatexCommand \index{HC08}
23870 family has been added in October 2003, and is still undergoing some basic
23872 The code generator is complete, but the register allocation is still quite
23874 Some of the SDCC's standard C library functions have embedded non-HC08
23875 inline assembly and so are not yet usable.
23878 \begin_layout Standard
23879 The HC08 port passes the regression test suite (see section
23880 \begin_inset LatexCommand \ref{sec:Quality-control}
23885 \begin_inset VSpace bigskip
23891 \begin_layout Section
23893 \begin_inset LatexCommand \index{PIC14}
23900 \begin_layout Standard
23901 The PIC14 port adds support for Microchip
23902 \begin_inset LatexCommand \index{Microchip}
23907 \begin_inset Formula $^{\text{TM}}$
23911 \begin_inset LatexCommand \index{PIC14}
23916 \begin_inset Formula $^{\text{TM}}$
23919 MCUs with 14 bit wide instructions.
23920 This port is not yet mature and still lacks many features.
23921 However, it can work for simple code.
23924 \begin_layout Standard
23925 Currently supported devices include:
23928 \begin_layout Standard
23929 12F: 629, 635, 675, 683
23932 \begin_layout Standard
23936 \begin_layout Standard
23940 \begin_layout Standard
23941 16C: 62, 620, 620a, 621, 621a, 622, 622a, 63a, 65b
23944 \begin_layout Standard
23945 16C: 71, 710, 711, 715, 717, 72, 73b, 745, 74b, 765, 770, 771, 773, 774,
23949 \begin_layout Standard
23953 \begin_layout Standard
23954 16CR: 620a, 73, 74, 76, 77
23957 \begin_layout Standard
23958 16F: 616, 627, 627a, 628, 628a, 630, 636, 639, 648, 648a, 676, 684, 685,
23962 \begin_layout Standard
23963 16F: 716, 72, 73, 737, 74, 747, 76, 767, 77, 777, 785
23966 \begin_layout Standard
23967 16F: 818, 819, 84, 84a, 87, 870, 871, 872, 873, 873a, 874, 874a, 876, 876a,
23968 877, 877a, 88, 886, 887
23971 \begin_layout Standard
23972 16F: 913, 914, 916, 917, 946
23975 \begin_layout Standard
23979 \begin_layout Standard
23980 An up-to-date list of currently supported devices can be obtained via
23982 sdcc -mpic14 -phelp foo.c
23984 (foo.c must exist...).
23987 \begin_layout Subsection
23989 \begin_inset LatexCommand \index{code page (pic14)}
23994 \begin_inset LatexCommand \index{Memory bank (pic14)}
24001 \begin_layout Standard
24002 The linker organizes allocation for the code page and RAM banks.
24003 It does not have intimate knowledge of the code flow.
24004 It will put all the code section of a single .asm file into a single code
24006 In order to make use of multiple code pages, separate asm files must be
24008 The compiler assigns all
24012 functions of a single .c file into the same code page.
24016 To get the best results,
24017 follow these guidelines:
24020 \begin_layout Enumerate
24021 Make local functions static, as non static functions require code page selection
24024 Due to the way sdcc handles functions, place called functions prior
24025 to calling functions in the file wherever possible: Otherwise sdcc will
24026 insert unneccessary pagesel directives around the call, believing that
24027 the called function is externally defined.
24030 \begin_layout Enumerate
24031 For devices that have multiple code pages it is more efficient to use the
24032 same number of files as pages: Use up to 4 separate .c files for the 16F877,
24033 but only 2 files for the 16F874.
24034 This way the linker can put the code for each file into different code
24035 pages and there will be less page selection overhead.
24038 \begin_layout Enumerate
24039 And as for any 8 bit micro (especially for PIC14 as they have a very simple
24040 instruction set), use `unsigned char' wherever possible instead of `int'.
24043 \begin_layout Subsection
24044 Adding New Devices to the Port
24047 \begin_layout Standard
24048 Adding support for a new 14
24052 \begin_layout Standard
24061 bit PIC MCU requires the following steps:
24064 \begin_layout Enumerate
24065 Create a new device description.
24067 Each device is described in two files: pic16f*.h
24069 These files primarily define SFRs, structs to access their bits, and symbolic
24070 configuration options.
24071 Both files can be generated from gputils' .inc files using the perl script
24074 support/scripts/inc2h.pl
24077 This file also contains further instructions on how to proceed.
24080 \begin_layout Enumerate
24081 Copy the .h file into SDCC's include path and either add the .c file to your
24082 project or copy it to
24084 device/lib/pic/libdev
24087 Afterwards, rebuild and install the libraries.
24090 \begin_layout Enumerate
24091 Edit pic14devices.txt in SDCC's include path (
24093 device/include/pic/
24095 in the source tree or
24097 /usr/local/share/sdcc/include/pic
24099 after installation).
24101 You need to add a device specification here to make
24102 the memory layout (code banks, RAM, aliased memory regions, ...) known to
24104 Probably you can copy and modify an existing entry.
24105 The file format is documented at the top of the file.
24108 \begin_layout Subsection
24112 \begin_layout Standard
24113 For the interrupt function, use the keyword `__interrupt'
24114 \begin_inset LatexCommand \index{PIC14!interrupt}
24118 with level number of 0 (PIC14 only has 1 interrupt so this number is only
24119 there to avoid a syntax error - it ought to be fixed).
24123 \begin_layout Verse
24126 void Intr(void) __interrupt 0
24132 T0IF = 0; /* Clear timer interrupt */
24137 \begin_layout Subsection
24138 Linking and Assembling
24141 \begin_layout Standard
24142 For assembling you can use either GPUTILS'
24143 \begin_inset LatexCommand \index{gputils (pic tools)}
24147 gpasm.exe or MPLAB's mpasmwin.exe.
24148 GPUTILS are available from
24149 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
24154 For linking you can use either GPUTILS' gplink or MPLAB's mplink.exe.
24155 If you use MPLAB and an interrupt function then the linker script file
24156 vectors section will need to be enlarged to link with mplink.
24167 \begin_layout Verse
24180 sdcc -V -mpic14 -p16f877 -c $<
24184 $(PRJ).hex: $(OBJS)
24194 gplink -m -s $(PRJ).lkr
24195 -o $(PRJ).hex $(OBJS) libsdcc.lib
24198 \begin_layout Standard
24206 \begin_layout Verse
24219 sdcc -S -V -mpic14 -p16f877 $<
24229 mpasmwin /q /o $*.asm
24233 $(PRJ).hex: $(OBJS)
24244 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
24247 \begin_layout Standard
24248 Please note that indentations within a
24252 have to be done with a tabulator character.
24255 \begin_layout Subsection
24256 Command-Line Options
24259 \begin_layout Standard
24260 Besides the switches common to all SDCC backends, the PIC14 port accepts
24261 the following options (for an updated list see sdcc -
24265 \begin_layout Standard
24277 \begin_layout Description
24282 \begin_layout Standard
24292 \begin_inset LatexCommand \index{PIC14!Options!-\/-debug-extra}
24296 emit debug info in assembly output
24299 \begin_layout Description
24304 \begin_layout Standard
24314 \begin_inset LatexCommand \index{PIC14!Options!-\/-no-pcode-opt}
24318 disable (slightly faulty) optimization on pCode
24321 \begin_layout Description
24326 \begin_layout Standard
24336 \begin_inset LatexCommand \index{PIC14!Options!-\/-stack-loc}
24340 sets the lowest address of the argument passing stack (defaults to a suitably
24341 large shared databank to reduce BANKSEL overhead)
24344 \begin_layout Description
24349 \begin_layout Standard
24359 \begin_inset LatexCommand \index{PIC14!Options!-\/-stack-size}
24363 sets the size if the argument passing stack (default: 16, minimum: 4)
24366 \begin_layout Subsection
24367 Environment Variables
24370 \begin_layout Standard
24371 The PIC14 port recognizes the following environment variables:
24374 \begin_layout Description
24375 SDCC_PIC14_SPLIT_LOCALS If set and not empty, sdcc will allocate each temporary
24376 register (the ones called r0xNNNN) in a section of its own.
24377 By default (if this variable is unset), sdcc tries to cluster registers
24378 in sections in order to reduce the BANKSEL overhead when accessing them.
24381 \begin_layout Subsection
24385 \begin_layout Standard
24386 The PIC14 library currently only contains support routines required by the
24387 compiler to implement multiplication, division, and floating point support.
24388 No libc-like replacement is available at the moment, though many of the
24389 common sdcc library sources (in
24393 ) should also compile with the PIC14 port.
24396 \begin_layout Subsubsection
24397 error: missing definition for symbol ``__gptrget1''
24400 \begin_layout Standard
24401 The PIC14 port uses library routines to provide more complex operations
24402 like multiplication, division/modulus and (generic) pointer dereferencing.
24403 In order to add these routines to your project, you must link with PIC14's
24409 For single source file projects this is done automatically, more complex
24414 to the linker's arguments.
24415 Make sure you also add an include path for the library (using the -I switch
24419 \begin_layout Subsubsection
24420 Processor mismatch in file ``XXX''.
24423 \begin_layout Standard
24424 This warning can usually be ignored due to the very good compatibility amongst
24429 \begin_layout Standard
24439 \begin_inset LatexCommand \index{PIC14}
24446 \begin_layout Standard
24447 You might also consider recompiling the library for your specific device
24448 by changing the ARCH=p16f877 (default target) entry in
24450 device/lib/pic/Makefile.in
24454 device/lib/pic/Makefile
24456 to reflect your device.
24457 This might even improve performance for smaller devices as unneccesary
24458 BANKSELs might be removed.
24461 \begin_layout Subsection
24465 \begin_layout Subsubsection
24469 \begin_layout Standard
24470 Functions with variable argument lists (like printf) are not yet supported.
24471 Similarly, taking the address of the first argument passed into a function
24472 does not work: It is currently passed in WREG and has no address...
24475 \begin_layout Subsubsection
24476 Regression tests fail
24479 \begin_layout Standard
24480 Though the small subset of regression tests in src/regression passes, SDCC
24481 regression test suite does not, indicating that there are still major bugs
24483 However, many smaller projects have successfully used SDCC in the past...
24486 \begin_layout Standard
24494 \begin_layout Section
24496 \begin_inset LatexCommand \index{PIC16}
24503 \begin_layout Standard
24504 The PIC16 port adds support for Microchip
24505 \begin_inset LatexCommand \index{Microchip}
24510 \begin_inset Formula $^{\text{TM}}$
24514 \begin_inset LatexCommand \index{PIC}
24519 \begin_inset Formula $^{\text{TM}}$
24522 MCUs with 16 bit wide instructions.
24523 Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx
24524 ; devices supported by the port include:
24527 \begin_layout Standard
24528 18F: 242, 248, 252, 258, 442, 448, 452, 458
24531 \begin_layout Standard
24535 \begin_layout Standard
24536 18F: 2220, 2221, 2320, 2321, 2331, 2420, 2423, 2431, 2455, 2480, 24j10
24539 \begin_layout Standard
24540 18F: 2520, 2523, 2525, 2550, 2580, 2585, 25j10, 2620, 2680, 2682, 2685
24543 \begin_layout Standard
24544 18F: 4220, 4221, 4320, 4321, 4331, 4420, 4423, 4431, 4455, 4480, 44j10
24547 \begin_layout Standard
24548 18F: 4520, 4523, 4525, 4550, 4580, 4585, 45j10, 4620, 4680, 4682, 4685
24551 \begin_layout Standard
24552 18F: 6520, 6585, 6620, 6680, 6720
24555 \begin_layout Standard
24556 18F: 8520, 8585, 8620, 8680, 8720
24559 \begin_layout Standard
24560 A list of supported devices is also available via '
24562 sdcc -mpic16 -plist
24567 \begin_layout Subsection
24571 \begin_layout Standard
24572 PIC16 port supports the standard command line arguments as supposed, with
24573 the exception of certain cases that will be mentioned in the following
24577 \begin_layout Description
24582 \begin_layout Standard
24592 \begin_inset LatexCommand \index{PIC16!Options!-\/-callee-saves}
24600 \begin_layout Standard
24612 \begin_layout Description
24617 \begin_layout Standard
24626 -fommit-frame-pointer
24627 \begin_inset LatexCommand \index{PIC16!Options!-\/-fommit-frame-pointer}
24631 Frame pointer will be omitted when the function uses no local variables.
24634 \begin_layout Subsection
24635 Port Specific Options
24636 \begin_inset LatexCommand \index{Options PIC16}
24643 \begin_layout Standard
24644 The port specific options appear after the global options in the sdcc -
24648 \begin_layout Standard
24660 \begin_layout Subsubsection
24661 Code Generation Options
24664 \begin_layout Standard
24665 These options influence the generated assembler code.
24668 \begin_layout Description
24673 \begin_layout Standard
24682 -pstack-model=[model] Used in conjuction with the command above.
24683 Defines the stack model to be used, valid stack models are:
24688 \labelwidthstring 00.00.0000
24693 Selects small stack model.
24694 8 bit stack and frame pointers.
24695 Supports 256 bytes stack size.
24699 \labelwidthstring 00.00.0000
24704 Selects large stack model.
24705 16 bit stack and frame pointers.
24706 Supports 65536 bytes stack size.
24710 \begin_layout Description
24715 \begin_layout Standard
24724 -pno-banksel Do not generate BANKSEL assembler directives.
24727 \begin_layout Description
24732 \begin_layout Standard
24741 -extended Enable extended instruction set/literal offset addressing mode.
24745 \begin_layout Subsubsection
24746 Optimization Options
24749 \begin_layout Description
24754 \begin_layout Standard
24763 -obanksel=n Set optimization level for inserting BANKSELs.
24770 \labelwidthstring 00.00.0000
24775 \labelwidthstring 00.00.0000
24776 1 checks previous used register and if it is the same then does not emit
24777 BANKSEL, accounts only for labels.
24781 \labelwidthstring 00.00.0000
24782 2 tries to check the location of (even different) symbols and removes BANKSELs
24783 if they are in the same bank.
24788 Important: There might be problems if the linker script has data sections
24789 across bank borders!
24793 \begin_layout Description
24798 \begin_layout Standard
24807 -denable-peeps Force the usage of peepholes.
24811 \begin_layout Description
24816 \begin_layout Standard
24825 -no-optimize-goto Do not use (conditional) BRA instead of GOTO.
24828 \begin_layout Description
24833 \begin_layout Standard
24842 -optimize-cmp Try to optimize some compares.
24845 \begin_layout Description
24850 \begin_layout Standard
24859 -optimize-df Analyze the dataflow of the generated code and improve it.
24862 \begin_layout Subsubsection
24866 \begin_layout Description
24871 \begin_layout Standard
24880 -asm= Sets the full path and name of an external assembler to call.
24883 \begin_layout Description
24888 \begin_layout Standard
24898 \begin_inset LatexCommand \index{PIC16!MPLAB}
24902 compatibility option.
24903 Currently only suppresses special gpasm directives.
24906 \begin_layout Subsubsection
24910 \begin_layout Description
24915 \begin_layout Standard
24924 -link= Sets the full path and name of an external linker to call.
24927 \begin_layout Description
24932 \begin_layout Standard
24941 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
24942 unitialized data variables with [kword].
24943 Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
24946 \begin_layout Description
24951 \begin_layout Standard
24960 -ivt-loc=n Place the interrupt vector table at address
24965 Useful for bootloaders.
24968 \begin_layout Description
24973 \begin_layout Standard
24982 -nodefaultlibs Do not link default libraries when linking.
24985 \begin_layout Description
24990 \begin_layout Standard
24999 -use-crt= Use a custom run-time module instead of the defaults.
25002 \begin_layout Description
25007 \begin_layout Standard
25016 -no-crt Don't link the default run-time modules
25019 \begin_layout Subsubsection
25023 \begin_layout Standard
25024 Debugging options enable extra debugging information in the output files.
25027 \begin_layout Description
25032 \begin_layout Standard
25041 -debug-xtra Similar to -
25045 \begin_layout Standard
25055 \begin_inset LatexCommand \index{-\/-debug}
25059 , but dumps more information.
25062 \begin_layout Description
25067 \begin_layout Standard
25076 -debug-ralloc Force register allocator to dump <source>.d file with debugging
25078 <source> is the name of the file being compiled.
25081 \begin_layout Description
25086 \begin_layout Standard
25095 -pcode-verbose Enable pcode debugging information in translation.
25098 \begin_layout Description
25103 \begin_layout Standard
25112 -calltree Dump call tree in .calltree file.
25115 \begin_layout Description
25120 \begin_layout Standard
25129 -gstack Trace push/pops for stack pointer overflow.
25132 \begin_layout Subsection
25133 Enviroment Variables
25136 \begin_layout Standard
25137 There is a number of enviromental variables that can be used when running
25138 SDCC to enable certain optimizations or force a specific program behaviour.
25139 these variables are primarily for debugging purposes so they can be enabled/dis
25143 \begin_layout Standard
25144 Currently there is only two such variables available:
25147 \begin_layout Description
25148 OPTIMIZE_BITFIELD_POINTER_GET When this variable exists, reading of structure
25149 bitfields is optimized by directly loading FSR0 with the address of the
25150 bitfield structure.
25151 Normally SDCC will cast the bitfield structure to a bitfield pointer and
25153 This step saves data ram and code space for functions that make heavy use
25155 (i.e., 80 bytes of code space are saved when compiling malloc.c with this
25160 \begin_layout Description
25161 NO_REG_OPT Do not perform pCode registers optimization.
25162 This should be used for debugging purposes.
25163 If bugs in the pcode optimizer are found, users can benefit from temporarily
25164 disabling the optimizer until the bug is fixed.
25167 \begin_layout Subsection
25168 Preprocessor Macros
25171 \begin_layout Standard
25173 \begin_inset LatexCommand \index{PIC16}
25177 port defines the following preprocessor macros while translating a source.
25180 \begin_layout Standard
25182 \begin_inset Tabular
25183 <lyxtabular version="3" rows="6" columns="2">
25185 <column alignment="center" valignment="top" leftline="true" width="0">
25186 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
25187 <row topline="true" bottomline="true">
25188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25191 \begin_layout Standard
25197 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25200 \begin_layout Standard
25207 <row topline="true">
25208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25211 \begin_layout Standard
25217 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25220 \begin_layout Standard
25221 Port identification
25227 <row topline="true">
25228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25231 \begin_layout Standard
25236 \begin_layout Standard
25250 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25253 \begin_layout Standard
25254 Port identification (same as above)
25260 <row topline="true">
25261 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25264 \begin_layout Standard
25270 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25273 \begin_layout Standard
25274 MCU Identification.
25279 is the microcontrol identification number, i.e.
25286 <row topline="true">
25287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25290 \begin_layout Standard
25295 \begin_layout Standard
25309 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25312 \begin_layout Standard
25313 MCU Identification (same as above)
25319 <row topline="true" bottomline="true">
25320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25323 \begin_layout Standard
25329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25332 \begin_layout Standard
25333 nnn = SMALL or LARGE respectively according to the stack model used
25346 \begin_layout Standard
25347 In addition the following macros are defined when calling assembler:
25350 \begin_layout Standard
25352 \begin_inset Tabular
25353 <lyxtabular version="3" rows="4" columns="2">
25355 <column alignment="center" valignment="top" leftline="true" width="0">
25356 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
25357 <row topline="true" bottomline="true">
25358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25361 \begin_layout Standard
25367 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25370 \begin_layout Standard
25377 <row topline="true">
25378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25381 \begin_layout Standard
25387 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25390 \begin_layout Standard
25391 MCU Identification.
25396 is the microcontrol identification number, i.e.
25403 <row topline="true">
25404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25407 \begin_layout Standard
25413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25416 \begin_layout Standard
25417 nnn = SMALL or LARGE respectively according to the memory model used for
25424 <row topline="true" bottomline="true">
25425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25428 \begin_layout Standard
25434 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25437 \begin_layout Standard
25438 nnn = SMALL or LARGE respectively according to the stack model used
25451 \begin_layout Subsection
25455 \begin_layout Standard
25457 \begin_inset LatexCommand \index{PIC16}
25461 port uses the following directories for searching header files and libraries.
25464 \begin_layout Standard
25466 \begin_inset Tabular
25467 <lyxtabular version="3" rows="3" columns="4">
25469 <column alignment="center" valignment="top" leftline="true" width="0">
25470 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
25471 <column alignment="center" valignment="top" width="0">
25472 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
25473 <row topline="true" bottomline="true">
25474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25477 \begin_layout Standard
25483 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25486 \begin_layout Standard
25492 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
25511 <row topline="true">
25512 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25515 \begin_layout Standard
25516 PREFIX/sdcc/include/pic16
25521 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25524 \begin_layout Standard
25525 PIC16 specific headers
25530 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25533 \begin_layout Standard
25539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25542 \begin_layout Standard
25549 <row topline="true" bottomline="true">
25550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25553 \begin_layout Standard
25554 PREFIX/sdcc/lib/pic16
25559 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25562 \begin_layout Standard
25563 PIC16 specific libraries
25568 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25571 \begin_layout Standard
25577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25580 \begin_layout Standard
25594 \begin_layout Subsection
25596 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
25603 \begin_layout Standard
25605 \begin_inset LatexCommand \index{PIC16}
25609 port currently supports the following pragmas:
25612 \begin_layout Description
25614 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma stack}
25618 This forces the code generator to initialize the stack & frame pointers
25619 at a specific address.
25620 This is an ad hoc solution for cases where no STACK directive is available
25621 in the linker script or gplink is not instructed to create a stack section.
25624 stack pragma should be used only once in a project.
25625 Multiple pragmas may result in indeterminate behaviour of the program.
25629 \begin_layout Standard
25630 The old format (ie.
25631 #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
25632 cross page boundaries (or even exceed the available data RAM) and crash
25634 Make sure that stack does not cross page boundaries when using the SMALL
25642 The format is as follows:
25647 \begin_layout LyX-Code
25648 #pragma stack bottom_address [stack_size]
25653 \begin_layout Standard
25658 is the lower bound of the stack section.
25659 The stack pointer initially will point at address (bottom_address+stack_size-1).
25662 \begin_layout LyX-Code
25666 \begin_layout LyX-Code
25670 \begin_layout LyX-Code
25671 /* initializes stack of 100 bytes at RAM address 0x200 */
25674 \begin_layout LyX-Code
25675 #pragma stack 0x200 100
25678 \begin_layout Standard
25679 If the stack_size field is omitted then a stack is created with the default
25681 This size might be enough for most programs, but its not enough for operations
25682 with deep function nesting or excessive stack usage.
25685 \begin_layout Description
25687 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma code}
25691 Force a function to a static FLASH address.
25694 \begin_layout LyX-Code
25698 \begin_layout LyX-Code
25702 \begin_layout LyX-Code
25703 /* place function test_func at 0x4000 */
25706 \begin_layout LyX-Code
25707 #pragma code test_func 0x4000
25710 \begin_layout LyX-Code
25714 \begin_layout Description
25715 library instructs the linker to use a library module.
25720 \begin_layout LyX-Code
25721 #pragma library module_name
25724 \begin_layout Standard
25729 can be any library or object file (including its path).
25730 Note that there are four reserved keywords which have special meaning.
25734 \begin_layout Standard
25736 \begin_inset Tabular
25737 <lyxtabular version="3" rows="6" columns="3">
25739 <column alignment="center" valignment="top" leftline="true" width="0">
25740 <column alignment="block" valignment="top" leftline="true" width="20page%">
25741 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
25742 <row topline="true" bottomline="true">
25743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25746 \begin_layout Standard
25752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25755 \begin_layout Standard
25761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25764 \begin_layout Standard
25771 <row topline="true">
25772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25775 \begin_layout Standard
25783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25786 \begin_layout Standard
25787 ignore all library pragmas
25792 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25795 \begin_layout Standard
25804 <row topline="true">
25805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25808 \begin_layout Standard
25816 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25819 \begin_layout Standard
25825 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25828 \begin_layout Standard
25839 <row topline="true">
25840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25843 \begin_layout Standard
25851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25854 \begin_layout Standard
25855 link the Math libarary
25860 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25863 \begin_layout Standard
25874 <row topline="true">
25875 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25878 \begin_layout Standard
25886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25889 \begin_layout Standard
25890 link the I/O library
25895 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25898 \begin_layout Standard
25909 <row topline="true" bottomline="true">
25910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25913 \begin_layout Standard
25921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25924 \begin_layout Standard
25925 link the debug library
25930 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25933 \begin_layout Standard
25950 * is the device number, i.e.
25951 452 for PIC18F452 MCU.
25954 \begin_layout Standard
25955 This feature allows for linking with specific libraries withoug having to
25956 explicit name them in the command line.
25961 keyword will reject all modules specified by the library pragma.
25964 \begin_layout Description
25965 udata The pragma udata instructs the compiler to emit code so that linker
25966 will place a variable at a specific memory bank.
25969 \begin_layout LyX-Code
25973 \begin_layout LyX-Code
25977 \begin_layout LyX-Code
25978 /* places variable foo at bank2 */
25981 \begin_layout LyX-Code
25982 #pragma udata bank2 foo
25985 \begin_layout LyX-Code
25989 \begin_layout Standard
25990 In order for this pragma to work extra SECTION directives should be added
25991 in the .lkr script.
25992 In the following example a sample .lkr file is shown:
25995 \begin_layout LyX-Code
25999 \begin_layout LyX-Code
26000 // Sample linker script for the PIC18F452 processor
26003 \begin_layout LyX-Code
26007 \begin_layout LyX-Code
26008 CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED
26011 \begin_layout LyX-Code
26012 CODEPAGE NAME=page START=0x2A END=0x7FFF
26015 \begin_layout LyX-Code
26016 CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED
26019 \begin_layout LyX-Code
26020 CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED
26023 \begin_layout LyX-Code
26024 CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED
26027 \begin_layout LyX-Code
26028 CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED
26031 \begin_layout LyX-Code
26032 ACCESSBANK NAME=accessram START=0x0 END=0x7F
26035 \begin_layout LyX-Code
26039 \begin_layout LyX-Code
26040 DATABANK NAME=gpr0 START=0x80 END=0xFF
26043 \begin_layout LyX-Code
26044 DATABANK NAME=gpr1 START=0x100 END=0x1FF
26047 \begin_layout LyX-Code
26048 DATABANK NAME=gpr2 START=0x200 END=0x2FF
26051 \begin_layout LyX-Code
26052 DATABANK NAME=gpr3 START=0x300 END=0x3FF
26055 \begin_layout LyX-Code
26056 DATABANK NAME=gpr4 START=0x400 END=0x4FF
26059 \begin_layout LyX-Code
26060 DATABANK NAME=gpr5 START=0x500 END=0x5FF
26063 \begin_layout LyX-Code
26064 ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED
26067 \begin_layout LyX-Code
26071 \begin_layout LyX-Code
26072 SECTION NAME=CONFIG ROM=config
26075 \begin_layout LyX-Code
26079 \begin_layout LyX-Code
26080 SECTION NAME=bank0 RAM=gpr0 # these SECTION directives
26083 \begin_layout LyX-Code
26084 SECTION NAME=bank1 RAM=gpr1 # should be added to link
26087 \begin_layout LyX-Code
26088 SECTION NAME=bank2 RAM=gpr2 # section name 'bank?' with
26091 \begin_layout LyX-Code
26092 SECTION NAME=bank3 RAM=gpr3 # a specific DATABANK name
26095 \begin_layout LyX-Code
26096 SECTION NAME=bank4 RAM=gpr4
26099 \begin_layout LyX-Code
26100 SECTION NAME=bank5 RAM=gpr5
26103 \begin_layout Standard
26104 The linker will recognise the section name set in the pragma statement and
26105 will position the variable at the memory bank set with the RAM field at
26106 the SECTION line in the linker script file.
26109 \begin_layout Subsection
26111 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
26118 \begin_layout Standard
26119 There is one main header file
26120 \begin_inset LatexCommand \index{PIC16!Header files}
26124 that can be included to the source files using the pic16
26125 \begin_inset LatexCommand \index{PIC16}
26135 This header file contains the definitions for the processor special registers,
26136 so it is necessary if the source accesses them.
26137 It can be included by adding the following line in the beginning of the
26141 \begin_layout LyX-Code
26142 #include <pic18fregs.h>
26145 \begin_layout Standard
26146 The specific microcontroller is selected within the pic18fregs.h automatically,
26147 so the same source can be used with a variety of devices.
26150 \begin_layout Subsection
26154 \begin_layout Standard
26156 \begin_inset LatexCommand \index{PIC16!Libraries}
26161 \begin_inset LatexCommand \index{PIC16}
26165 port depends on are the microcontroller device libraries which contain
26166 the symbol definitions for the microcontroller special function registers.
26167 These libraries have the format pic18fxxxx.lib, where
26171 is the microcontroller identification number.
26172 The specific library is selected automatically by the compiler at link
26173 stage according to the selected device.
26176 \begin_layout Standard
26177 Libraries are created with gplib which is part of the gputils package
26178 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
26185 \begin_layout Subsubsection*
26186 Building the libraries
26189 \begin_layout Standard
26190 Before using SDCC/pic16 there are some libraries that need to be compiled.
26191 This process is not done automatically by SDCC since not all users use
26192 SDCC for pic16 projects.
26193 So each user should compile the libraries separately.
26196 \begin_layout Standard
26197 The steps to compile the pic16 libraries under Linux and Mac OS X are:
26200 \begin_layout LyX-Code
26201 cd device/lib/pic16
26204 \begin_layout LyX-Code
26208 \begin_layout LyX-Code
26212 \begin_layout LyX-Code
26216 \begin_layout LyX-Code
26220 \begin_layout LyX-Code
26221 su -c 'make install' # install the libraries, you need the root password
26224 \begin_layout Standard
26225 If you need to install the headers too, do:
26228 \begin_layout LyX-Code
26232 \begin_layout LyX-Code
26233 su -c 'make install' # install the headers, you need the root password
26236 \begin_layout Standard
26237 There exist a special target to build the I/O libraries.
26238 This target is not automatically build because it will build the I/O library
26244 This way building will take quite a lot of time.
26245 Users are advised to edit the
26247 device/lib/pic16/pics.build
26249 file and then execute:
26252 \begin_layout LyX-Code
26256 \begin_layout Subsection
26257 Adding New Devices to the Port
26260 \begin_layout Standard
26261 Adding support for a new 16
26265 \begin_layout Standard
26274 bit PIC MCU requires the following steps:
26277 \begin_layout Enumerate
26278 Create picDEVICE.c and picDEVICE.h from pDEVICE.inc using
26282 perl /path/to/sdcc/support/scripts/inc2h-pic16.pl /path/to/gputils/header/pDEVICE.
26286 \begin_layout Enumerate
26289 mv picDEVICE.h /path/to/sdcc/device/include/pic16
26292 \begin_layout Enumerate
26295 mv picDEVICE.c /path/to/sdcc/device/lib/pic16/libdev
26298 \begin_layout Enumerate
26301 /path/to/sdcc/device/lib/pic16/pics.all
26309 Note: No 18f prefix here!
26312 \begin_layout Enumerate
26313 Set up the I/O library by doing
26321 \begin_layout Enumerate
26324 /path/to/sdcc/device/lib/pic16/libio/*.ignore
26328 Add your DEVICE if it does not compile in
26343 \begin_layout Enumerate
26346 /path/to/sdcc/device/include/pic16/adc.h
26350 Add the new devices to the correct ADC style class.
26354 \begin_layout Enumerate
26357 /path/to/sdcc/device/include/pic16/pic18fregs.h
26360 The file format is self-explanatory, just add
26364 #elif defined(picDEVICE)
26366 # include <picDEVICE.h>
26370 at the right place (keep it sorted).
26373 \begin_layout Enumerate
26376 /path/to/sdcc/device/include/pic16devices.txt
26380 Copy and modify an existing entry or create a new one and insert it at the
26381 correct place (keep the file sorted).
26384 \begin_layout Enumerate
26385 Recompile the pic16 libraries.
26388 \begin_layout Subsection
26392 \begin_layout Standard
26393 The following memory models are supported by the PIC16 port:
26396 \begin_layout Itemize
26400 \begin_layout Itemize
26404 \begin_layout Standard
26405 Memory model affects the default size of pointers within the source.
26406 The sizes are shown in the next table:
26409 \begin_layout Standard
26411 \begin_inset Tabular
26412 <lyxtabular version="3" rows="3" columns="3">
26414 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26415 <column alignment="center" valignment="top" leftline="true" width="0">
26416 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26417 <row topline="true" bottomline="true">
26418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26421 \begin_layout Standard
26422 Pointer sizes according to memory model
26427 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26430 \begin_layout Standard
26436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26439 \begin_layout Standard
26446 <row topline="true" bottomline="true">
26447 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26450 \begin_layout Standard
26456 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26459 \begin_layout Standard
26465 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26468 \begin_layout Standard
26475 <row topline="true" bottomline="true">
26476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26479 \begin_layout Standard
26485 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
26488 \begin_layout Standard
26494 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26497 \begin_layout Standard
26511 \begin_layout Standard
26512 It is advisable that all sources within a project are compiled with the
26514 If one wants to override the default memory model, this can be done by
26515 declaring a pointer as
26524 Far selects large memory model's pointers, while near selects small memory
26528 \begin_layout Standard
26529 The standard device libraries (see
26530 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
26534 ) contain no reference to pointers, so they can be used with both memory
26538 \begin_layout Subsection
26542 \begin_layout Standard
26544 \begin_inset LatexCommand \index{PIC16!stack}
26548 implementation for the PIC16 port uses two indirect registers, FSR1 and
26552 \begin_layout Description
26553 FSR1 is assigned as stack pointer
26556 \begin_layout Description
26557 FSR2 is assigned as frame pointer
26560 \begin_layout Standard
26561 The following stack models are supported by the PIC16 port
26564 \begin_layout Itemize
26572 \begin_layout Itemize
26580 \begin_layout Standard
26585 model means that only the FSRxL byte is used to access stack and frame,
26592 uses both FSRxL and FSRxH registers.
26593 The following table shows the stack/frame pointers sizes according to stack
26594 model and the maximum space they can address:
26597 \begin_layout Standard
26599 \begin_inset Tabular
26600 <lyxtabular version="3" rows="3" columns="3">
26602 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26603 <column alignment="center" valignment="top" leftline="true" width="0">
26604 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26605 <row topline="true" bottomline="true">
26606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26609 \begin_layout Standard
26610 Stack & Frame pointer sizes according to stack model
26615 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26618 \begin_layout Standard
26624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26627 \begin_layout Standard
26634 <row topline="true">
26635 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26638 \begin_layout Standard
26644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26647 \begin_layout Standard
26653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26656 \begin_layout Standard
26663 <row topline="true" bottomline="true">
26664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26667 \begin_layout Standard
26673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26676 \begin_layout Standard
26682 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26685 \begin_layout Standard
26699 \begin_layout Standard
26704 stack model is currently not working properly throughout the code generator.
26705 So its use is not advised.
26706 Also there are some other points that need special care:
26711 \begin_layout Enumerate
26712 Do not create stack sections with size more than one physical bank (that
26716 \begin_layout Enumerate
26717 Stack sections should no cross physical bank limits (i.e.
26718 #pragma stack 0x50 0x100)
26721 \begin_layout Standard
26722 These limitations are caused by the fact that only FSRxL is modified when
26723 using SMALL stack model, so no more than 256 bytes of stack can be used.
26724 This problem will disappear after LARGE model is fully implemented.
26727 \begin_layout Subsection
26731 \begin_layout Standard
26732 In addition to the standard SDCC function keywords, PIC16
26733 \begin_inset LatexCommand \index{PIC16}
26737 port makes available two more:
26740 \begin_layout Description
26742 \begin_inset LatexCommand \index{PIC16!wparam}
26746 Use the WREG to pass one byte of the first function argument.
26747 This improves speed but you may not use this for functions with arguments
26748 that are called via function pointers, otherwise the first byte of the
26749 first parameter will get lost.
26753 \begin_layout LyX-Code
26754 void func_wparam(int a) wparam
26757 \begin_layout LyX-Code
26761 \begin_layout LyX-Code
26762 /* WREG hold the lower part of a */
26765 \begin_layout LyX-Code
26766 /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
26770 \begin_layout LyX-Code
26774 \begin_layout LyX-Code
26778 \begin_layout Description
26780 \begin_inset LatexCommand \index{PIC16!shadowregs}
26784 When entering/exiting an ISR, it is possible to take advantage of the PIC18F
26785 hardware shadow registers which hold the values of WREG, STATUS and BSR
26787 This can be done by adding the keyword
26795 keyword in the function's header.
26798 \begin_layout LyX-Code
26799 void isr_shadow(void) shadowregs interrupt 1
26802 \begin_layout LyX-Code
26806 \begin_layout LyX-Code
26810 \begin_layout LyX-Code
26814 \begin_layout Standard
26819 instructs the code generator not to store/restore WREG, STATUS, BSR when
26820 entering/exiting the ISR.
26823 \begin_layout Subsection
26824 Function return values
26827 \begin_layout Standard
26828 Return values from functions are placed to the appropriate registers following
26829 a modified Microchip policy optimized for SDCC.
26830 The following table shows these registers:
26833 \begin_layout Standard
26835 \begin_inset Tabular
26836 <lyxtabular version="3" rows="6" columns="2">
26838 <column alignment="center" valignment="top" leftline="true" width="0">
26839 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
26840 <row topline="true" bottomline="true">
26841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26844 \begin_layout Standard
26850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26853 \begin_layout Standard
26854 destination register
26860 <row topline="true">
26861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26864 \begin_layout Standard
26870 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26873 \begin_layout Standard
26880 <row topline="true">
26881 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26884 \begin_layout Standard
26890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26893 \begin_layout Standard
26900 <row topline="true">
26901 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26904 \begin_layout Standard
26910 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26913 \begin_layout Standard
26920 <row topline="true">
26921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26924 \begin_layout Standard
26930 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26933 \begin_layout Standard
26934 FSR0L:PRODH:PRODL:WREG
26940 <row topline="true" bottomline="true">
26941 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
26944 \begin_layout Standard
26950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
26953 \begin_layout Standard
26954 on stack, FSR0 points to the beginning
26967 \begin_layout Subsection
26971 \begin_layout Standard
26973 \begin_inset LatexCommand \index{PIC16!interrupt}
26977 service routine (ISR) is declared using the
26984 \begin_layout LyX-Code
26985 void isr(void) interrupt
26990 \begin_layout LyX-Code
26994 \begin_layout LyX-Code
26998 \begin_layout LyX-Code
27002 \begin_layout Standard
27007 is the interrupt number, which for PIC18F devices can be:
27010 \begin_layout Standard
27012 \begin_inset Tabular
27013 <lyxtabular version="3" rows="4" columns="3">
27015 <column alignment="center" valignment="top" leftline="true" width="0">
27016 <column alignment="center" valignment="top" leftline="true" width="0">
27017 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27018 <row topline="true" bottomline="true">
27019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27022 \begin_layout Standard
27030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27033 \begin_layout Standard
27039 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27042 \begin_layout Standard
27043 Interrupt Vector Address
27049 <row topline="true">
27050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27053 \begin_layout Standard
27059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27062 \begin_layout Standard
27068 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27071 \begin_layout Standard
27078 <row topline="true">
27079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27082 \begin_layout Standard
27097 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27100 \begin_layout Standard
27110 HIGH priority interrupts
27115 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27118 \begin_layout Standard
27125 <row topline="true" bottomline="true">
27126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27129 \begin_layout Standard
27135 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27138 \begin_layout Standard
27139 LOW priority interrupts
27144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27147 \begin_layout Standard
27161 \begin_layout Standard
27162 When generating assembly code for ISR the code generator places a
27168 Interrupt Vector Address
27170 which points at the genetated ISR.
27171 This single GOTO instruction is part of an automatically generated
27173 interrupt entry point
27176 The actuall ISR code is placed as normally would in the code space.
27177 Upon interrupt request, the GOTO instruction is executed which jumps to
27179 When declaring interrupt functions as _naked this GOTO instruction is
27184 The whole interrupt functions is therefore placed at the Interrupt Vector
27185 Address of the specific interrupt.
27186 This is not a problem for the LOW priority interrupts, but it is a problem
27187 for the RESET and the HIGH priority interrupts because code may be written
27188 at the next interrupt's vector address and cause undeterminate program
27189 behaviour if that interrupt is raised.
27193 \begin_layout Standard
27194 This is not a problem when
27197 \begin_layout Enumerate
27198 this is a HIGH interrupt ISR and LOW interrupts are
27205 \begin_layout Enumerate
27206 when the ISR is small enough not to reach the next interrupt's vector address.
27214 \begin_layout Standard
27220 This way a function is generated similar to an ISR, but it is not assigned
27224 \begin_layout Standard
27225 When entering an interrupt, currently the PIC16
27226 \begin_inset LatexCommand \index{PIC16}
27230 port automatically saves the following registers:
27233 \begin_layout Itemize
27237 \begin_layout Itemize
27241 \begin_layout Itemize
27245 \begin_layout Itemize
27246 PROD (PRODL and PRODH)
27249 \begin_layout Itemize
27250 FSR0 (FSR0L and FSR0H)
27253 \begin_layout Standard
27254 These registers are restored upon return from the interrupt routine.
27258 \begin_layout Standard
27259 NOTE that when the _naked attribute is specified for an interrupt routine,
27260 then NO registers are stored or restored.
27268 \begin_layout Subsection
27272 \begin_layout Standard
27273 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
27274 There are 3 types of generic pointers currently implemented data, code
27275 and eeprom pointers.
27276 They are differentiated by the value of the 7th and 6th bits of the upper
27280 \begin_layout Standard
27282 \begin_inset Tabular
27283 <lyxtabular version="3" rows="5" columns="5">
27285 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27286 <column alignment="center" valignment="top" width="0">
27287 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27288 <column alignment="center" valignment="top" width="0">
27289 <column alignment="left" valignment="top" rightline="true" width="0">
27290 <row topline="true" bottomline="true">
27291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27294 \begin_layout Standard
27300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27303 \begin_layout Standard
27309 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27312 \begin_layout Standard
27318 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27321 \begin_layout Standard
27322 rest of the pointer
27327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27330 \begin_layout Standard
27337 <row topline="true" bottomline="true">
27338 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27341 \begin_layout Standard
27347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27350 \begin_layout Standard
27356 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27359 \begin_layout Standard
27365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27368 \begin_layout Standard
27373 uuuuuu uuuuxxxx xxxxxxxx
27378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27381 \begin_layout Standard
27382 a 12-bit data pointer in data RAM memory
27388 <row bottomline="true">
27389 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27392 \begin_layout Standard
27398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27401 \begin_layout Standard
27407 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27410 \begin_layout Standard
27416 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27419 \begin_layout Standard
27424 uxxxxx xxxxxxxx xxxxxxxx
27429 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27432 \begin_layout Standard
27433 a 21-bit code pointer in FLASH memory
27439 <row bottomline="true">
27440 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27443 \begin_layout Standard
27449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27452 \begin_layout Standard
27458 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27461 \begin_layout Standard
27467 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27470 \begin_layout Standard
27475 uuuuuu uuuuuuxx xxxxxxxx
27480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27483 \begin_layout Standard
27484 a 10-bit eeprom pointer in EEPROM memory
27490 <row bottomline="true">
27491 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27494 \begin_layout Standard
27500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27503 \begin_layout Standard
27509 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27512 \begin_layout Standard
27518 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27521 \begin_layout Standard
27526 xxxxxx xxxxxxxx xxxxxxxx
27531 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27534 \begin_layout Standard
27535 unimplemented pointer type
27548 \begin_layout Standard
27549 Generic pointer are read and written with a set of library functions which
27550 read/write 1, 2, 3, 4 bytes.
27553 \begin_layout Subsection
27557 \begin_layout Subsubsection
27558 Standard I/O Streams
27561 \begin_layout Standard
27566 the type FILE is defined as:
27569 \begin_layout LyX-Code
27570 typedef char * FILE;
27573 \begin_layout Standard
27574 This type is the stream type implemented I/O in the PIC18F devices.
27575 Also the standard input and output streams are declared in stdio.h:
27578 \begin_layout LyX-Code
27579 extern FILE * stdin;
27582 \begin_layout LyX-Code
27583 extern FILE * stdout;
27586 \begin_layout Standard
27587 The FILE type is actually a generic pointer which defines one more type
27588 of generic pointers, the
27593 This new type has the format:
27596 \begin_layout Standard
27598 \begin_inset Tabular
27599 <lyxtabular version="3" rows="2" columns="7">
27601 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27602 <column alignment="center" valignment="top" width="0">
27603 <column alignment="center" valignment="top" leftline="true" width="0">
27604 <column alignment="center" valignment="top" leftline="true" width="0">
27605 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27606 <column alignment="center" valignment="top" width="0">
27607 <column alignment="left" valignment="top" rightline="true" width="0">
27608 <row topline="true" bottomline="true">
27609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27612 \begin_layout Standard
27618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27621 \begin_layout Standard
27627 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27630 \begin_layout Standard
27636 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
27658 rest of the pointer
27663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27666 \begin_layout Standard
27673 <row topline="true" bottomline="true">
27674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27677 \begin_layout Standard
27683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27686 \begin_layout Standard
27692 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27695 \begin_layout Standard
27701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
27732 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27735 \begin_layout Standard
27736 upper byte high nubble is 0x2n, the rest are zeroes
27749 \begin_layout Standard
27750 Currently implemented there are 3 types of streams defined:
27753 \begin_layout Standard
27755 \begin_inset Tabular
27756 <lyxtabular version="3" rows="4" columns="4">
27758 <column alignment="center" valignment="top" leftline="true" width="0">
27759 <column alignment="center" valignment="top" leftline="true" width="0">
27760 <column alignment="center" valignment="top" leftline="true" width="0">
27761 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
27762 <row topline="true" bottomline="true">
27763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27766 \begin_layout Standard
27772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27775 \begin_layout Standard
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" rightline="true" usebox="none">
27793 \begin_layout Standard
27800 <row topline="true">
27801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27804 \begin_layout Standard
27810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27813 \begin_layout Standard
27821 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27824 \begin_layout Standard
27830 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27833 \begin_layout Standard
27834 Writes/Reads characters via the USART peripheral
27840 <row topline="true">
27841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27844 \begin_layout Standard
27850 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27853 \begin_layout Standard
27861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27864 \begin_layout Standard
27870 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27873 \begin_layout Standard
27874 Writes/Reads characters via the MSSP peripheral
27880 <row topline="true" bottomline="true">
27881 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27884 \begin_layout Standard
27890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27893 \begin_layout Standard
27901 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
27904 \begin_layout Standard
27910 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
27913 \begin_layout Standard
27914 Writes/Reads characters via used defined functions
27927 \begin_layout Standard
27928 The stream identifiers are declared as macros in the stdio.h header.
27931 \begin_layout Standard
27932 In the libc library there exist the functions that are used to write to
27933 each of the above streams.
27937 \begin_layout Description
27942 \begin_layout Standard
27951 _stream_usart_putchar writes a character at the USART stream
27954 \begin_layout Description
27959 \begin_layout Standard
27968 _stream_mssp_putchar writes a character at the MSSP stream
27971 \begin_layout Description
27972 putchar dummy function.
27973 This writes a character to a user specified manner.
27976 \begin_layout Standard
27977 In order to increase performance
27981 is declared in stdio.h as having its parameter in WREG (it has the wparam
27983 In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
27984 in a user-friendly way.
27989 is the name of the variable that holds the character to print.
27990 An example follows:
27993 \begin_layout LyX-Code
27994 #include <pic18fregs.h>
28003 \begin_layout LyX-Code
28007 \begin_layout LyX-Code
28008 PORTA = c; /* dump character c to PORTA */
28011 \begin_layout LyX-Code
28019 \begin_layout LyX-Code
28023 \begin_layout LyX-Code
28024 stdout = STREAM_USER; /* this is not necessary, since stdout points
28027 \begin_layout LyX-Code
28028 * by default to STREAM_USER */
28031 \begin_layout LyX-Code
28033 \begin_inset Quotes sld
28036 This is a printf test
28039 \begin_inset Quotes srd
28045 \begin_layout LyX-Code
28049 \begin_layout LyX-Code
28053 \begin_layout Subsubsection
28057 \begin_layout Standard
28058 PIC16 contains an implementation of the printf-family of functions.
28059 There exist the following functions:
28062 \begin_layout LyX-Code
28063 extern unsigned int sprintf(char *buf, char *fmt, ...);
28066 \begin_layout LyX-Code
28067 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
28070 \begin_layout LyX-Code
28074 \begin_layout LyX-Code
28075 extern unsigned int printf(char *fmt, ...);
28078 \begin_layout LyX-Code
28079 extern unsigned int vprintf(char *fmt, va_lista ap);
28082 \begin_layout LyX-Code
28086 \begin_layout LyX-Code
28087 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
28090 \begin_layout LyX-Code
28091 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
28094 \begin_layout Standard
28095 For sprintf and vsprintf
28099 should normally be a data pointer where the resulting string will be placed.
28100 No range checking is done so the user should allocate the necessery buffer.
28101 For fprintf and vfprintf
28105 should be a stream pointer (i.e.
28106 stdout, STREAM_MSSP, etc...).
28109 \begin_layout Subsubsection
28113 \begin_layout Standard
28114 The PIC18F family of microcontrollers supports a number of interrupt sources.
28115 A list of these interrupts is shown in the following table:
28118 \begin_layout Standard
28120 \begin_inset Tabular
28121 <lyxtabular version="3" rows="11" columns="4">
28123 <column alignment="left" valignment="top" leftline="true" width="0">
28124 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28125 <column alignment="left" valignment="top" leftline="true" width="0">
28126 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
28127 <row topline="true" bottomline="true">
28128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28131 \begin_layout Standard
28137 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28140 \begin_layout Standard
28146 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
28165 <row topline="true">
28166 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28169 \begin_layout Standard
28175 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28178 \begin_layout Standard
28179 PORTB change interrupt
28184 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28187 \begin_layout Standard
28193 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28196 \begin_layout Standard
28197 EEPROM/FLASH write complete interrupt
28203 <row topline="true">
28204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28207 \begin_layout Standard
28213 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28216 \begin_layout Standard
28217 INT0 external interrupt
28222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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 Bus collision interrupt
28241 <row topline="true">
28242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28245 \begin_layout Standard
28251 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28254 \begin_layout Standard
28255 INT1 external interrupt
28260 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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 Low voltage detect interrupt
28279 <row topline="true">
28280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28283 \begin_layout Standard
28289 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28292 \begin_layout Standard
28293 INT2 external interrupt
28298 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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 Parallel slave port interrupt
28317 <row topline="true">
28318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28321 \begin_layout Standard
28327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28330 \begin_layout Standard
28331 CCP1 module interrupt
28336 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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 AD convertion complete interrupt
28355 <row topline="true">
28356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28359 \begin_layout Standard
28365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28368 \begin_layout Standard
28369 CCP2 module interrupt
28374 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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 USART receive interrupt
28393 <row topline="true">
28394 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28397 \begin_layout Standard
28403 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28406 \begin_layout Standard
28407 TMR0 overflow interrupt
28412 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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 USART transmit interrupt
28431 <row topline="true">
28432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28435 \begin_layout Standard
28441 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28444 \begin_layout Standard
28445 TMR1 overflow interrupt
28450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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 SSP receive/transmit interrupt
28469 <row topline="true">
28470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28473 \begin_layout Standard
28479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28482 \begin_layout Standard
28483 TMR2 matches PR2 interrupt
28488 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
28507 <row topline="true" bottomline="true">
28508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
28511 \begin_layout Standard
28517 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
28520 \begin_layout Standard
28521 TMR3 overflow interrupt
28526 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
28552 \begin_layout Standard
28553 The prototypes for these names are defined in the header file
28560 \begin_layout Standard
28561 In order to simplify signal handling, a number of macros is provided:
28565 \labelwidthstring 00.00.0000
28566 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
28567 high priority interrupts.
28572 is the function name to use.
28576 \labelwidthstring 00.00.0000
28577 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
28578 low priority interrupt.
28583 is the function name to use.
28587 \labelwidthstring 00.00.0000
28588 DEF_HANDLER(sig,handler) define a handler for signal
28594 \labelwidthstring 00.00.0000
28595 END_DEF end the declaration of the dispatch table.
28598 \begin_layout Standard
28599 Additionally there are two more macros to simplify the declaration of the
28604 \labelwidthstring 00.00.0000
28607 SIGHANDLER(handler)
28609 this declares the function prototype for the
28617 \labelwidthstring 00.00.0000
28618 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
28621 \begin_layout Standard
28622 An example of using the macros above is shown below:
28625 \begin_layout LyX-Code
28626 #include <pic18fregs.h>
28629 \begin_layout LyX-Code
28630 #include <signal.h>
28634 DEF_INTHIGH(high_int)
28637 \begin_layout LyX-Code
28638 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
28641 \begin_layout LyX-Code
28642 DEF_HANDLER(SIG_BCOL, _bcol_handler)
28645 \begin_layout LyX-Code
28650 SIGHANDLER(_tmr0_handler)
28653 \begin_layout LyX-Code
28657 \begin_layout LyX-Code
28658 /* action to be taken when timer 0 overflows */
28661 \begin_layout LyX-Code
28666 SIGHANDLERNAKED(_bcol_handler)
28669 \begin_layout LyX-Code
28673 \begin_layout LyX-Code
28677 \begin_layout LyX-Code
28678 /* action to be taken when bus collision occurs */
28681 \begin_layout LyX-Code
28685 \begin_layout LyX-Code
28689 \begin_layout LyX-Code
28693 \begin_layout Standard
28698 Special care should be taken when using the above scheme:
28701 \begin_layout Itemize
28702 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
28705 \begin_layout Itemize
28706 when declaring SIGHANDLERNAKED handler never forget to use
28710 for proper returning.
28713 \begin_layout Subsection
28717 \begin_layout Standard
28718 Here you can find some general tips for compiling programs with SDCC/pic16.
28721 \begin_layout Subsubsection
28725 \begin_layout Standard
28727 \begin_inset LatexCommand \index{PIC16!stack}
28731 size (that is 64 bytes) probably is enough for many programs.
28732 One must take care that when there are many levels of function nesting,
28733 or there is excessive usage of stack, its size should be extended.
28734 An example of such a case is the printf/sprintf family of functions.
28735 If you encounter problems like not being able to print integers, then you
28736 need to set the stack size around the maximum (256 for small stack model).
28737 The following diagram shows what happens when calling printf to print an
28741 \begin_layout LyX-Code
28742 printf () --> ltoa () --> ultoa () --> divschar ()
28745 \begin_layout Standard
28746 It is should be understood that stack is easily consumed when calling complicate
28748 Using command line arguments like -
28752 \begin_layout Standard
28761 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
28763 Other ways to reduce stack usage may exist.
28766 \begin_layout Subsection
28770 \begin_layout Standard
28771 The PIC16 Port currently does not pass SDCC's regression test
28772 \begin_inset LatexCommand \index{Regression test (PIC16)}
28777 \begin_inset LatexCommand \ref{sec:Quality-control}
28781 ) and thus the snapshot build regression tests for the PIC16 target are
28782 currently disabled for all hosts
28787 \begin_layout Chapter
28791 \begin_layout Standard
28792 There are several approaches to debugging your code.
28793 This chapter is meant to show your options and to give detail on some of
28798 When writing your code:
28801 \begin_layout Itemize
28802 write your code with debugging in mind (avoid duplicating code, put conceptually
28803 similar variables into structs, use structured code, have strategic points
28804 within your code where all variables are consistent, ...)
28807 \begin_layout Itemize
28808 run a syntax-checking tool like splint
28809 \begin_inset LatexCommand \index{splint (syntax checking tool)}
28814 \begin_inset LatexCommand \index{lint (syntax checking tool)}
28822 \begin_layout Standard
28832 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
28839 \begin_layout Itemize
28840 for the high level code use a C-compiler (like f.e.
28841 GCC) to compile run and debug the code on your host.
28846 \begin_layout Standard
28856 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
28860 ) on how to handle syntax extensions like __xdata, __at(), ...
28864 \begin_layout Itemize
28865 use another C-compiler to compile code for your target.
28866 Always an option but not recommended:) And not very likely to help you.
28867 If you seriously consider walking this path you should at least occasionally
28868 check portability of your code.
28869 Most commercial compiler vendors will offer an evaluation version so you
28870 can test compile your code or snippets of your code.
28873 \begin_layout Standard
28874 Debugging on a simulator:
28877 \begin_layout Itemize
28878 there is a separate section about SDCDB (section
28879 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
28886 \begin_layout Itemize
28887 or (8051 specific) use a freeware/commercial simulator which interfaces
28889 \begin_inset LatexCommand \index{AOMF, AOMF51}
28894 \begin_inset LatexCommand \ref{OMF file}
28898 ) optionally generated by SDCC.
28901 \begin_layout Standard
28902 Debugging On-target:
28905 \begin_layout Itemize
28906 use a MCU port pin to serially output debug data to the RS232 port of your
28908 You'll probably want some level shifting device typically involving a MAX232
28910 If the hardware serial port of the MCU is not available search for 'Software
28911 UART' in your favourite search machine.
28914 \begin_layout Itemize
28915 use an on-target monitor.
28916 In this context a monitor is a small program which usually accepts commands
28917 via a serial line and allows to set program counter, to single step through
28918 a program and read/write memory locations.
28919 For the 8051 good examples of monitors are paulmon and cmon51 (see section
28921 \begin_inset LatexCommand \ref{sec:Related-open-source-tools}
28928 \begin_layout Itemize
28929 toggle MCU port pins at strategic points within your code and use an oscilloscop
28933 digital oscilloscope
28936 \begin_inset LatexCommand \index{Oscilloscope}
28940 with deep trace memory is really helpful especially if you have to debug
28941 a realtime application.
28942 If you need to monitor more pins than your oscilloscope provides you can
28943 sometimes get away with a small R-2R network.
28944 On a single channel oscilloscope you could f.e.
28945 monitor 2 push-pull driven pins by connecting one via a 10\InsetSpace ~
28947 \begin_inset Formula $\Omega$
28950 resistor and the other one by a 5\InsetSpace ~
28952 \begin_inset Formula $\Omega$
28955 resistor to the oscilloscope probe (check output drive capability of the
28956 pins you want to monitor).
28957 If you need to monitor many more pins a
28964 \begin_layout Itemize
28978 \begin_inset LatexCommand \index{ICE (in circuit emulator)}
28983 Usually very expensive.
28984 And very nice to have too.
28985 And usually locks you (for years...) to the devices the ICE can emulate.
28989 \begin_layout Itemize
28990 use a remote debugger.
28991 In most 8-bit systems the symbol information is not available on the target,
28992 and a complete debugger is too bulky for the target system.
28993 Therefore usually a debugger on the host system connects to an on-target
28994 debugging stub which accepts only primitive commands.
28997 Terms to enter into your favourite search engine could be 'remote debugging',
28998 'gdb stub' or 'inferior debugger'.
29002 \begin_layout Itemize
29003 use an on target hardware debugger.
29004 Some of the more modern MCUs include hardware support for setting break
29005 points and monitoring/changing variables by using dedicated hardware pins.
29006 This facility doesn't require additional code to run on the target and
29011 doesn't affect runtime behaviour until a breakpoint is hit.
29012 For the mcs51 most hardware debuggers use the AOMF
29013 \begin_inset LatexCommand \index{AOMF, AOMF51}
29018 \begin_inset LatexCommand \ref{OMF file}
29026 \begin_layout Standard
29030 \begin_layout Itemize
29031 if you are not familiar with any of the following terms you're likely to
29032 run into problems rather sooner than later:
29049 As an embedded programmer you
29053 to know them so why not look them up
29057 you have problems?)
29060 \begin_layout Itemize
29061 tell someone else about your problem (actually this is a surprisingly effective
29062 means to hunt down the bug even if the listener is not familiar with your
29064 As 'failure to communicate' is probably one of the job-induced deformations
29065 of an embedded programmer this is highly encouraged.
29068 \begin_layout Section
29069 Debugging with SDCDB
29070 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
29075 \begin_inset LatexCommand \index{SDCDB (debugger)}
29082 \begin_layout Standard
29083 SDCC is distributed with a source level debugger
29084 \begin_inset LatexCommand \index{Debugger}
29089 The debugger uses a command line interface, the command repertoire of the
29090 debugger has been kept as close to gdb
29091 \begin_inset LatexCommand \index{gdb}
29095 (the GNU debugger) as possible.
29096 The configuration and build process is part of the standard compiler installati
29097 on, which also builds and installs the debugger in the target directory
29098 specified during configuration.
29099 The debugger allows you debug BOTH at the C source and at the ASM source
29103 \begin_layout Subsection
29104 Compiling for Debugging
29107 \begin_layout Standard
29112 \begin_layout Standard
29122 \begin_inset LatexCommand \index{-\/-debug}
29126 option must be specified for all files for which debug information is to
29128 The compiler generates a .adb file for each of these files.
29129 The linker creates the .cdb
29130 \begin_inset LatexCommand \index{<file>.cdb}
29135 \begin_inset LatexCommand \index{<file>.adb}
29139 files and the address information.
29140 This .cdb is used by the debugger.
29143 \begin_layout Subsection
29144 How the Debugger Works
29147 \begin_layout Standard
29152 \begin_layout Standard
29161 -debug option is specified the compiler generates extra symbol information
29162 some of which are put into the assembler source and some are put into the
29164 Then the linker creates the .cdb file from the individual .adb files with
29165 the address information for the symbols.
29166 The debugger reads the symbolic information generated by the compiler &
29167 the address information generated by the linker.
29168 It uses the SIMULATOR (Daniel's S51) to execute the program, the program
29169 execution is controlled by the debugger.
29170 When a command is issued for the debugger, it translates it into appropriate
29171 commands for the simulator.
29172 (Currently SDCDM only connects to the simulator but
29177 \begin_inset LatexCommand \url{http://ec2drv.sf.net/}
29181 is an effort to connect directly to the hardware.)
29184 \begin_layout Subsection
29185 Starting the Debugger SDCDB
29188 \begin_layout Standard
29189 The debugger can be started using the following command line.
29190 (Assume the file you are debugging has the file name foo).
29204 The debugger will look for the following files.
29207 \begin_layout Itemize
29208 foo.c - the source file.
29211 \begin_layout Itemize
29212 foo.cdb - the debugger symbol information file.
29215 \begin_layout Itemize
29216 foo.ihx - the Intel hex format
29217 \begin_inset LatexCommand \index{Intel hex format}
29224 \begin_layout Subsection
29225 SDCDB Command Line Options
29228 \begin_layout Itemize
29233 \begin_layout Standard
29242 -directory=<source file directory> this option can used to specify the directory
29244 The debugger will look into the directory list specified for source, cdb
29246 The items in the directory list must be separated by ':', e.g.
29247 if the source files can be in the directories /home/src1 and /home/src2,
29252 \begin_layout Standard
29261 -directory option should be -
29265 \begin_layout Standard
29274 -directory=/home/src1:/home/src2.
29275 Note there can be no spaces in the option.
29279 \begin_layout Itemize
29280 -cd <directory> - change to the <directory>.
29283 \begin_layout Itemize
29284 -fullname - used by GUI front ends.
29287 \begin_layout Itemize
29288 -cpu <cpu-type> - this argument is passed to the simulator please see the
29289 simulator docs for details.
29292 \begin_layout Itemize
29293 -X <Clock frequency > this options is passed to the simulator please see
29294 the simulator docs for details.
29297 \begin_layout Itemize
29298 -s <serial port file> passed to simulator see the simulator docs for details.
29301 \begin_layout Itemize
29302 -S <serial in,out> passed to simulator see the simulator docs for details.
29305 \begin_layout Itemize
29306 -k <port number> passed to simulator see the simulator docs for details.
29309 \begin_layout Subsection
29310 SDCDB Debugger Commands
29313 \begin_layout Standard
29314 As mentioned earlier the command interface for the debugger has been deliberatel
29315 y kept as close the GNU debugger gdb, as possible.
29316 This will help the integration with existing graphical user interfaces
29317 (like ddd, xxgdb or xemacs) existing for the GNU debugger.
29318 If you use a graphical user interface for the debugger you can skip this
29322 \begin_layout Subsubsection*
29323 break [line | file:line | function | file:function]
29326 \begin_layout Standard
29327 Set breakpoint at specified line or function:
29336 sdcdb>break foo.c:100
29338 sdcdb>break funcfoo
29340 sdcdb>break foo.c:funcfoo
29343 \begin_layout Subsubsection*
29344 clear [line | file:line | function | file:function ]
29347 \begin_layout Standard
29348 Clear breakpoint at specified line or function:
29357 sdcdb>clear foo.c:100
29359 sdcdb>clear funcfoo
29361 sdcdb>clear foo.c:funcfoo
29364 \begin_layout Subsubsection*
29368 \begin_layout Standard
29369 Continue program being debugged, after breakpoint.
29372 \begin_layout Subsubsection*
29376 \begin_layout Standard
29377 Execute till the end of the current function.
29380 \begin_layout Subsubsection*
29384 \begin_layout Standard
29385 Delete breakpoint number 'n'.
29386 If used without any option clear ALL user defined break points.
29389 \begin_layout Subsubsection*
29390 info [break | stack | frame | registers ]
29393 \begin_layout Itemize
29394 info break - list all breakpoints
29397 \begin_layout Itemize
29398 info stack - show the function call stack.
29401 \begin_layout Itemize
29402 info frame - show information about the current execution frame.
29405 \begin_layout Itemize
29406 info registers - show content of all registers.
29409 \begin_layout Subsubsection*
29413 \begin_layout Standard
29414 Step program until it reaches a different source line.
29415 Note: pressing <return> repeats the last command.
29418 \begin_layout Subsubsection*
29422 \begin_layout Standard
29423 Step program, proceeding through subroutine calls.
29426 \begin_layout Subsubsection*
29430 \begin_layout Standard
29431 Start debugged program.
29434 \begin_layout Subsubsection*
29438 \begin_layout Standard
29439 Print type information of the variable.
29442 \begin_layout Subsubsection*
29446 \begin_layout Standard
29447 print value of variable.
29450 \begin_layout Subsubsection*
29454 \begin_layout Standard
29455 load the given file name.
29456 Note this is an alternate method of loading file for debugging.
29459 \begin_layout Subsubsection*
29463 \begin_layout Standard
29464 print information about current frame.
29467 \begin_layout Subsubsection*
29471 \begin_layout Standard
29472 Toggle between C source & assembly source.
29475 \begin_layout Subsubsection*
29476 ! simulator command
29479 \begin_layout Standard
29480 Send the string following '!' to the simulator, the simulator response is
29482 Note the debugger does not interpret the command being sent to the simulator,
29483 so if a command like 'go' is sent the debugger can loose its execution
29484 context and may display incorrect values.
29487 \begin_layout Subsubsection*
29491 \begin_layout Standard
29494 My name is Bobby Brown"
29497 \begin_layout Subsection
29498 Interfacing SDCDB with DDD
29501 \begin_layout Standard
29502 \begin_inset Note Note
29505 \begin_layout Standard
29506 The screenshot was converted from png to eps with:
29507 \begin_inset Quotes sld
29510 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
29511 \begin_inset Quotes srd
29514 which produces a pretty compact eps file which is free from compression
29518 \begin_layout Standard
29519 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
29520 as this broke the build system on Sourceforge (pdf-file was broken.
29521 pdflatex does not accept eps files).
29529 \begin_layout Standard
29545 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png}
29551 shows a screenshot of a debugging session with DDD
29552 \begin_inset LatexCommand \index{DDD (debugger)}
29556 (Unix only) on a simulated 8032.
29557 The debugging session might not run as smoothly as the screenshot suggests.
29558 The debugger allows setting of breakpoints, displaying and changing variables,
29559 single stepping through C and assembler code.
29562 The source was compiled with
29576 \begin_layout Standard
29588 -debug ddd_example.c
29601 and DDD was invoked with
29608 ddd -debugger "sdcdb -cpu 8032 ddd_example"
29611 \begin_layout Standard
29612 \begin_inset Note Note
29615 \begin_layout Standard
29616 Check that the double quotes or an apostroph within the command line survive
29617 the LyX tool chain.
29618 Previously the apostrophs got slanted in the PDF output so a cut and paste
29627 \begin_layout Subsection
29628 Interfacing SDCDB with XEmacs
29629 \begin_inset LatexCommand \index{XEmacs}
29634 \begin_inset LatexCommand \index{Emacs}
29641 \begin_layout Standard
29642 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
29643 sdcdb.el and sdcdbsrc.el.
29644 These two files can be found in the $(prefix)/bin directory after the installat
29646 These files need to be loaded into XEmacs for the interface to work.
29647 This can be done at XEmacs startup time by inserting the following into
29648 your '.xemacs' file (which can be found in your HOME directory):
29654 (load-file sdcdbsrc.el)
29660 .xemacs is a lisp file so the () around the command is REQUIRED.
29661 The files can also be loaded dynamically while XEmacs is running, set the
29662 environment variable 'EMACSLOADPATH' to the installation bin directory
29663 (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
29664 To start the interface enter the following command:
29678 You will prompted to enter the file name to be debugged.
29683 The command line options that are passed to the simulator directly are
29684 bound to default values in the file sdcdbsrc.el.
29685 The variables are listed below, these values maybe changed as required.
29688 \begin_layout Itemize
29689 sdcdbsrc-cpu-type '51
29692 \begin_layout Itemize
29693 sdcdbsrc-frequency '11059200
29696 \begin_layout Itemize
29697 sdcdbsrc-serial nil
29700 \begin_layout Standard
29701 The following is a list of key mapping for the debugger interface.
29704 \begin_layout Standard
29727 binding\InsetSpace ~
29765 -------\InsetSpace ~
29836 sdcdb-back-from-src\InsetSpace ~
29865 rom-src\InsetSpace ~
29875 SDCDB continue command
29893 sdcdb-step-from-src\InsetSpace ~
29922 hatis-c-sexp\InsetSpace ~
29932 SDCDB ptypecommand for data at
29999 sdcdbsrc-delete\InsetSpace ~
30014 B Delete all breakpoints if no arg
30063 given or delete arg (C-u arg x)
30082 -frame\InsetSpace ~
30097 SDCDB Display current frame if no arg,
30146 given or display frame arg
30214 sdcdbsrc-goto-sdcdb\InsetSpace ~
30224 Goto the SDCDB output buffer
30243 t-c-sexp\InsetSpace ~
30254 SDCDB print command for data at
30321 sdcdbsrc-goto-sdcdb\InsetSpace ~
30332 o the SDCDB output buffer
30350 sdcdbsrc-mode\InsetSpace ~
30366 Toggles Sdcdbsrc mode (turns it
30382 sdcdb-finish-from-src\InsetSpace ~
30390 SDCDB finish command
30424 Set break for line with point
30439 sdcdbsrc-mode\InsetSpace ~
30455 Toggle Sdcdbsrc mode
30471 dbsrc-srcmode\InsetSpace ~
30495 \begin_layout Chapter
30499 \begin_layout Standard
30500 Here are a few guidelines that will help the compiler generate more efficient
30501 code, some of the tips are specific to this compiler others are generally
30502 good programming practice.
30505 \begin_layout Itemize
30506 Use the smallest data type to represent your data-value.
30507 If it is known in advance that the value is going to be less than 256 then
30508 use an 'unsigned char' instead of a 'short' or 'int'.
30509 Please note, that ANSI C requires both signed and unsigned chars to be
30510 promoted to 'signed int'
30511 \begin_inset LatexCommand \index{promotion to signed int}
30516 \begin_inset Marginal
30519 \begin_layout Standard
30528 before doing any operation.
30530 \begin_inset LatexCommand \index{type promotion}
30535 \begin_inset LatexCommand \label{type promotion}
30539 can be omitted, if the result is the same.
30540 The effect of the promotion rules together with the sign-extension is often
30545 \begin_layout Verse
30548 unsigned char uc = 0xfe;
30550 if (uc * uc < 0) /* this is true! */
30563 \begin_layout Standard
30570 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
30578 \begin_layout Verse
30581 (unsigned char) -12 / (signed char) -3 = ...
30584 \begin_layout Standard
30585 No, the result is not 4:
30588 \begin_layout Verse
30591 (int) (unsigned char) -12 / (int) (signed char) -3 =
30593 (int) (unsigned char)
30594 0xf4 / (int) (signed char) 0xfd =
30596 (int) 0x00f4 / (int) 0xfffd =
30601 (int) 244 / (int) -3 =
30603 (int) -81 = (int) 0xffaf;
30606 \begin_layout Standard
30607 Don't complain, that gcc gives you a different result.
30608 gcc uses 32 bit ints, while SDCC uses 16 bit ints.
30609 Therefore the results are different.
30612 \begin_inset Quotes sld
30616 \begin_inset Quotes srd
30622 \begin_layout Quote
30625 If well-defined overflow characteristics are important and negative values
30626 are not, or if you want to steer clear of sign-extension problems when
30627 manipulating bits or bytes, use one of the corresponding unsigned types.
30628 (Beware when mixing signed and unsigned values in expressions, though.)
30631 character types (especially unsigned char) can be used as "tiny" integers,
30632 doing so is sometimes more trouble than it's worth, due to unpredictable
30633 sign extension and increased code size.
30637 \begin_layout Itemize
30638 Use unsigned when it is known in advance that the value is not going to
30640 This helps especially if you are doing division or multiplication, bit-shifting
30641 or are using an array index.
30644 \begin_layout Itemize
30645 NEVER jump into a LOOP.
30648 \begin_layout Itemize
30649 Declare the variables to be local
30650 \begin_inset LatexCommand \index{local variables}
30654 whenever possible, especially loop control variables (induction).
30657 \begin_layout Itemize
30658 Have a look at the assembly listing to get a
30659 \begin_inset Quotes sld
30663 \begin_inset Quotes srd
30666 for the code generation.
30669 \begin_layout Section
30670 Porting code from or to other compilers
30671 \begin_inset LatexCommand \label{sec:Porting-code-to-other-compilers}
30678 \begin_layout Itemize
30679 check whether endianness of the compilers differs and adapt where needed.
30682 \begin_layout Itemize
30683 check the device specific header files
30684 \begin_inset LatexCommand \index{Header files}
30689 \begin_inset LatexCommand \index{Include files}
30693 for compiler specific syntax.
30694 Eventually include the file <compiler.h
30695 \begin_inset LatexCommand \index{compiler.h (include file)}
30700 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/compiler.h?view=markup}
30704 to allow using common header files.
30707 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/cc2510fx.h?view=markup}
30714 \begin_layout Itemize
30715 check whether the startup code contains the correct initialization (watchdog,
30719 \begin_layout Itemize
30720 check whether the sizes of short, int, long match.
30723 \begin_layout Itemize
30724 check if some 16 or 32 bit hardware registers require a specific addressing
30725 order (least significant or most significant byte first) and adapt if needed
30734 relate to time and not to lower/upper memory location here, so this is
30739 the same as endianness).
30742 \begin_layout Itemize
30743 check whether the keyword
30747 is used where needed.
30748 The compilers might differ in their optimization characteristics (as different
30749 versions of the same compiler might also use more clever optimizations
30750 this is good idea anyway).
30752 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
30759 \begin_layout Itemize
30760 check that the compilers are not told to supress warnings.
30763 \begin_layout Itemize
30764 check and convert compiler specific extensions (interrupts, memory areas,
30768 \begin_layout Itemize
30769 check for differences in type promotion.
30770 Especially check for math operations on
30779 For the sake of C99 compatibility SDCC will probably promote these to
30783 more often than other compilers.
30784 Eventually insert explicit casts to
30793 Also check that the ~\InsetSpace ~
30795 \begin_inset LatexCommand \index{\~\/ Operator}
30802 \begin_inset LatexCommand \index{bit}
30808 variables, use the !\InsetSpace ~
30811 \begin_inset LatexCommand \ref{type promotion}
30816 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
30823 \begin_layout Itemize
30824 check the assembly code generated for interrupt routines (f.e.
30825 for calls to possibly non-reentrant library functions).
30828 \begin_layout Itemize
30829 check whether timing loops result in proper timing (or preferably consider
30830 a rewrite of the code with timer based delays instead).
30833 \begin_layout Itemize
30834 check for differences in printf parameters (some compilers push (va_arg
30835 \begin_inset LatexCommand \index{vararg, va\_arg}
30839 ) char variables as
30843 others push them as
30849 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
30856 \begin_layout Itemize
30857 check the resulting memory map
30858 \begin_inset LatexCommand \index{Memory map}
30863 Usage of different memory spaces: code, stack, data (for mcs51/ds390 additional
30864 ly idata, pdata, xdata).
30865 Eventually check if unexpected library functions are included.
30868 \begin_layout Section
30870 \begin_inset LatexCommand \index{Tools}
30874 included in the distribution
30877 \begin_layout Standard
30879 \begin_inset Tabular
30880 <lyxtabular version="3" rows="12" columns="3">
30882 <column alignment="left" valignment="top" leftline="true" width="0pt">
30883 <column alignment="left" valignment="top" leftline="true" width="0pt">
30884 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
30885 <row topline="true" bottomline="true">
30886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30889 \begin_layout Standard
30897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30900 \begin_layout Standard
30908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30911 \begin_layout Standard
30920 <row topline="true">
30921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30924 \begin_layout Standard
30926 \begin_inset LatexCommand \index{uCsim}
30935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30938 \begin_layout Standard
30939 Simulator for various architectures
30944 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30947 \begin_layout Standard
30954 <row topline="true">
30955 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30958 \begin_layout Standard
30964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30967 \begin_layout Standard
30969 \begin_inset LatexCommand \index{Header files}
30974 \begin_inset LatexCommand \index{Include files}
30983 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30986 \begin_layout Standard
30987 sdcc/support/scripts
30993 <row topline="true">
30994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30997 \begin_layout Standard
31003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31006 \begin_layout Standard
31007 header file conversion
31012 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31015 \begin_layout Standard
31016 sdcc/support/scripts
31022 <row topline="true">
31023 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31026 \begin_layout Standard
31032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31035 \begin_layout Standard
31041 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31044 \begin_layout Standard
31060 <row topline="true">
31061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31064 \begin_layout Standard
31070 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31073 \begin_layout Standard
31079 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31082 \begin_layout Standard
31098 <row topline="true">
31099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31102 \begin_layout Standard
31108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31111 \begin_layout Standard
31117 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31120 \begin_layout Standard
31136 <row topline="true">
31137 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31140 \begin_layout Standard
31146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31149 \begin_layout Standard
31155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31158 \begin_layout Standard
31174 <row topline="true">
31175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31178 \begin_layout Standard
31184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31187 \begin_layout Standard
31193 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31196 \begin_layout Standard
31212 <row topline="true">
31213 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31216 \begin_layout Standard
31222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31225 \begin_layout Standard
31231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31234 \begin_layout Standard
31250 <row topline="true">
31251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31254 \begin_layout Standard
31260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31263 \begin_layout Standard
31269 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31272 \begin_layout Standard
31288 <row topline="true" bottomline="true">
31289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31292 \begin_layout Standard
31298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31301 \begin_layout Standard
31303 \begin_inset LatexCommand \index{packihx (tool)}
31312 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31315 \begin_layout Standard
31340 \begin_layout Section
31342 \begin_inset LatexCommand \index{Documentation}
31346 included in the distribution
31349 \begin_layout Standard
31351 \begin_inset Tabular
31352 <lyxtabular version="3" rows="10" columns="2">
31354 <column alignment="block" valignment="top" leftline="true" width="40col%">
31355 <column alignment="block" valignment="top" leftline="true" rightline="true" width="60col%">
31356 <row topline="true" bottomline="true" endhead="true">
31357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31360 \begin_layout Standard
31368 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31371 \begin_layout Standard
31374 Filename / Where to get
31380 <row topline="true">
31381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31384 \begin_layout Standard
31385 SDCC Compiler User Guide
31390 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31393 \begin_layout Standard
31394 You're reading it right now
31406 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
31416 <row topline="true">
31417 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31420 \begin_layout Standard
31426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31429 \begin_layout Standard
31442 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/ChangeLog}
31452 <row topline="true">
31453 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31456 \begin_layout Standard
31458 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
31463 \begin_inset LatexCommand \index{Assembler documentation}
31470 \begin_inset LatexCommand \index{aslink}
31475 \begin_inset LatexCommand \index{Linker documentation}
31484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31487 \begin_layout Standard
31488 sdcc/as/doc/asxhtm.html
31500 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html}
31510 <row topline="true">
31511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31514 \begin_layout Standard
31515 SDCC regression test
31516 \begin_inset LatexCommand \index{Regression test}
31525 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31528 \begin_layout Standard
31529 sdcc/doc/test_suite_spec.pdf
31541 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf}
31551 <row topline="true">
31552 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31555 \begin_layout Standard
31561 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31564 \begin_layout Standard
31577 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/doc/}
31587 <row topline="true">
31588 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31591 \begin_layout Standard
31592 Notes on debugging with SDCDB
31593 \begin_inset LatexCommand \index{SDCDB (debugger)}
31602 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31605 \begin_layout Standard
31606 sdcc/debugger/README
31618 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/debugger/README}
31628 <row topline="true">
31629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31632 \begin_layout Standard
31634 \begin_inset LatexCommand \index{uCsim}
31638 Software simulator for microcontrollers
31643 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31646 \begin_layout Standard
31676 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/sim/ucsim/doc/index.html}
31686 <row topline="true">
31687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31690 \begin_layout Standard
31691 Temporary notes on the pic16
31692 \begin_inset LatexCommand \index{PIC16}
31701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31704 \begin_layout Standard
31705 sdcc/src/pic16/NOTES
31717 \begin_inset LatexCommand \url{http://sdcc.svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/src/pic16/NOTES}
31727 <row topline="true" bottomline="true">
31728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31731 \begin_layout Standard
31732 SDCC internal documentation (debugging file format)
31737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31740 \begin_layout Standard
31770 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/cdbfileformat.pdf}
31789 \begin_layout Section
31790 Related open source tools
31791 \begin_inset LatexCommand \label{sec:Related-open-source-tools}
31796 \begin_inset LatexCommand \index{Related tools}
31803 \begin_layout Standard
31805 \begin_inset Tabular
31806 <lyxtabular version="3" rows="16" columns="3">
31808 <column alignment="left" valignment="top" leftline="true" width="0pt">
31809 <column alignment="block" valignment="top" leftline="true" width="30line%">
31810 <column alignment="left" valignment="top" leftline="true" rightline="true" width="40col%">
31811 <row topline="true" bottomline="true">
31812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31815 \begin_layout Standard
31823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31826 \begin_layout Standard
31834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31837 \begin_layout Standard
31846 <row topline="true">
31847 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31850 \begin_layout Standard
31852 \begin_inset LatexCommand \index{gpsim (pic simulator)}
31861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31864 \begin_layout Standard
31870 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31873 \begin_layout Standard
31874 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
31884 <row topline="true">
31885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31888 \begin_layout Standard
31890 \begin_inset LatexCommand \index{gputils (pic tools)}
31899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31902 \begin_layout Standard
31908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31911 \begin_layout Standard
31912 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
31922 <row topline="true">
31923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31926 \begin_layout Standard
31932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31935 \begin_layout Standard
31941 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31944 \begin_layout Standard
31945 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
31955 <row topline="true">
31956 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31959 \begin_layout Standard
31965 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31968 \begin_layout Standard
31969 Tools for Silicon Laboratories JTAG debug adapter, partly based on SDCDB
31975 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31978 \begin_layout Standard
31979 \begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
31989 <row topline="true">
31990 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31993 \begin_layout Standard
31995 \begin_inset LatexCommand \index{indent (source formatting tool)}
32004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32007 \begin_layout Standard
32008 Formats C source - Master of the white spaces
32013 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32016 \begin_layout Standard
32017 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
32027 <row topline="true">
32028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32031 \begin_layout Standard
32033 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
32042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32045 \begin_layout Standard
32046 Object file conversion, checksumming, ...
32051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32054 \begin_layout Standard
32055 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
32065 <row topline="true">
32066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32069 \begin_layout Standard
32071 \begin_inset LatexCommand \index{objdump (tool)}
32080 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32083 \begin_layout Standard
32084 Object file conversion, ...
32089 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32092 \begin_layout Standard
32093 Part of binutils (should be there anyway)
32099 <row topline="true">
32100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32103 \begin_layout Standard
32109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32112 \begin_layout Standard
32113 8051 monitor (hex up-/download, single step, disassemble)
32118 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32121 \begin_layout Standard
32122 \begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51}
32132 <row topline="true">
32133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32136 \begin_layout Standard
32138 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
32147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32150 \begin_layout Standard
32151 Source code documentation system
32156 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32159 \begin_layout Standard
32160 \begin_inset LatexCommand \url{http://www.doxygen.org}
32170 <row topline="true">
32171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32174 \begin_layout Standard
32180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32183 \begin_layout Standard
32184 IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
32189 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32192 \begin_layout Standard
32193 \begin_inset LatexCommand \url{http://www.kdevelop.org}
32203 <row topline="true">
32204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32207 \begin_layout Standard
32213 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32216 \begin_layout Standard
32217 8051 monitor (hex up-/download, single step, disassemble)
32222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32225 \begin_layout Standard
32226 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
32236 <row topline="true">
32237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32240 \begin_layout Standard
32242 \begin_inset LatexCommand \index{splint (syntax checking tool)}
32251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32254 \begin_layout Standard
32255 Statically checks c sources (see
32256 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
32265 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32268 \begin_layout Standard
32269 \begin_inset LatexCommand \url{http://www.splint.org}
32279 <row topline="true" bottomline="true">
32280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32283 \begin_layout Standard
32285 \begin_inset LatexCommand \index{DDD (debugger)}
32294 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32297 \begin_layout Standard
32298 Debugger, serves nicely as GUI to SDCDB
32299 \begin_inset LatexCommand \index{SDCDB (debugger)}
32308 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32311 \begin_layout Standard
32312 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
32322 <row bottomline="true">
32323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32326 \begin_layout Standard
32328 \begin_inset LatexCommand \index{d52}
32333 \begin_inset LatexCommand \index{d52 (disassembler)}
32342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32345 \begin_layout Standard
32346 Disassembler, can count instruction cycles
32347 \begin_inset LatexCommand \index{instruction cycles (count)}
32351 , use with options -pnd
32356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32359 \begin_layout Standard
32360 \begin_inset LatexCommand \url{http://www.8052.com/users/disasm/}
32370 <row bottomline="true">
32371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32374 \begin_layout Standard
32376 \begin_inset LatexCommand \index{cmake}
32385 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32388 \begin_layout Standard
32389 Cross platform build system, generates Makefiles
32390 \begin_inset LatexCommand \index{Makefile}
32394 and project workspaces
32395 \begin_inset LatexCommand \index{project workspace}
32404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32407 \begin_layout Standard
32408 \begin_inset LatexCommand \url{http://www.cmake.org}
32416 and a dedicated wiki entry:
32417 \begin_inset LatexCommand \url{http://www.cmake.org/Wiki/CmakeSdcc}
32436 \begin_layout Section
32437 Related documentation / recommended reading
32440 \begin_layout Standard
32442 \begin_inset Tabular
32443 <lyxtabular version="3" rows="7" columns="3">
32445 <column alignment="left" valignment="top" leftline="true" width="0pt">
32446 <column alignment="left" valignment="top" leftline="true" width="0">
32447 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
32448 <row topline="true" bottomline="true">
32449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32452 \begin_layout Standard
32460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32463 \begin_layout Standard
32471 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32474 \begin_layout Standard
32483 <row topline="true">
32484 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32487 \begin_layout Standard
32502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32505 \begin_layout Standard
32507 \begin_inset LatexCommand \index{C Reference card}
32516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32519 \begin_layout Standard
32520 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
32530 <row topline="true">
32531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32534 \begin_layout Standard
32540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32543 \begin_layout Standard
32545 \begin_inset LatexCommand \index{C FAQ}
32554 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32557 \begin_layout Standard
32558 \begin_inset LatexCommand \url{http://www.c-faq.com}
32568 <row topline="true">
32569 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32572 \begin_layout Standard
32578 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32581 \begin_layout Standard
32582 \begin_inset Quotes sld
32586 \begin_inset Quotes srd
32594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32597 \begin_layout Standard
32600 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
32610 <row topline="true">
32611 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32614 \begin_layout Standard
32620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32623 \begin_layout Standard
32624 \begin_inset Quotes sld
32627 Extensions for Embedded C
32628 \begin_inset Quotes srd
32636 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32639 \begin_layout Standard
32642 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf}
32652 <row topline="true">
32653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32656 \begin_layout Standard
32662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32665 \begin_layout Standard
32666 Latest datasheet of target CPU
32671 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32674 \begin_layout Standard
32681 <row topline="true" bottomline="true">
32682 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32685 \begin_layout Standard
32691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32694 \begin_layout Standard
32695 Revision history of datasheet
32700 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32703 \begin_layout Standard
32719 \begin_layout Section
32720 Application notes specifically for SDCC
32723 \begin_layout Standard
32724 SDCC makes no claims about the completeness of this list and about up-to-datenes
32725 s or correctness of the application notes
32726 \begin_inset LatexCommand \index{Application notes}
32733 \begin_layout Standard
32737 \begin_inset Tabular
32738 <lyxtabular version="3" rows="7" columns="3">
32740 <column alignment="block" valignment="top" leftline="true" width="17col%">
32741 <column alignment="block" valignment="top" leftline="true" width="27col%">
32742 <column alignment="block" valignment="top" leftline="true" rightline="true" width="57col%">
32743 <row topline="true" bottomline="true">
32744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32747 \begin_layout Standard
32756 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
32759 \begin_layout Standard
32768 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32771 \begin_layout Standard
32781 <row topline="true">
32782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32785 \begin_layout Standard
32793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32796 \begin_layout Standard
32799 Using the SDCC Compiler for the DS80C400
32800 \begin_inset LatexCommand \index{DS80C400}
32809 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32812 \begin_layout Standard
32815 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3346.pdf}
32825 <row topline="true">
32826 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32829 \begin_layout Standard
32837 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none" width="30line%">
32840 \begin_layout Standard
32843 Using the Free SDCC C Compiler to Develop Firmware for the DS89C420/430/440/450
32844 \begin_inset LatexCommand \index{DS89C4x0}
32848 Family of Microcontrollers
32853 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32856 \begin_layout Standard
32859 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3477.pdf}
32869 <row topline="true">
32870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32873 \begin_layout Standard
32876 Silicon Laboratories / Cygnal
32881 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32884 \begin_layout Standard
32887 Integrating SDCC 8051 Tools Into The Silicon Labs IDE
32888 \begin_inset LatexCommand \index{IDE}
32897 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32900 \begin_layout Standard
32903 \begin_inset LatexCommand \url{http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/en/an198.pdf}
32913 <row topline="true">
32914 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32917 \begin_layout Standard
32920 Ramtron / Goal Semiconductor
32925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32928 \begin_layout Standard
32931 Interfacing SDCC to Syn and Textpad
32936 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32939 \begin_layout Standard
32942 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
32952 <row topline="true">
32953 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32956 \begin_layout Standard
32959 Ramtron / Goal Semiconductor
32964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32967 \begin_layout Standard
32970 Installing and Configuring SDCC and Crimson Editor
32975 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
32978 \begin_layout Standard
32981 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
32991 <row topline="true" bottomline="true">
32992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
32995 \begin_layout Standard
33003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
33006 \begin_layout Standard
33009 MSC12xx Programming with SDCC
33014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
33017 \begin_layout Standard
33020 \begin_inset LatexCommand \url{http://focus.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=sbaa109&fileType=pdf}
33037 \begin_layout Section
33041 \begin_layout Standard
33042 Some questions answered, some pointers given - it might be time to in turn
33050 \begin_layout Itemize
33051 can you solve your project with the selected microcontroller? Would you
33052 find out early or rather late that your target is too small/slow/whatever?
33053 Can you switch to a slightly better device if it doesn't fit?
33056 \begin_layout Itemize
33057 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
33058 and/or another programming language be more adequate? Would an operating
33059 system on the target device help?
33062 \begin_layout Itemize
33063 if you solved the problem, will the marketing department be happy?
33066 \begin_layout Itemize
33067 if the marketing department is happy, will customers be happy?
33070 \begin_layout Itemize
33071 if you're the project manager, marketing department and maybe even the customer
33072 in one person, have you tried to see the project from the outside?
33075 \begin_layout Itemize
33076 is the project done if you think it is done? Or is just that other interface/pro
33077 tocol/feature/configuration/option missing? How about website, manual(s),
33078 internationali(z|s)ation, packaging, labels, 2nd source for components,
33079 electromagnetic compatability/interference, documentation for production,
33080 production test software, update mechanism, patent issues?
33083 \begin_layout Itemize
33084 is your project adequately positioned in that magic triangle: fame, fortune,
33088 \begin_layout Standard
33089 Maybe not all answers to these questions are known and some answers may
33094 , nevertheless knowing these questions may help you to avoid burnout
33098 \begin_layout Standard
33099 burnout is bad for electronic devices, programmers and motorcycle tyres
33105 Chances are you didn't want to hear some of them...
33108 \begin_layout Chapter
33110 \begin_inset LatexCommand \index{Support}
33117 \begin_layout Standard
33118 SDCC has grown to be a large project.
33119 The compiler alone (without the preprocessor, assembler and linker) is
33120 well over 150,000 lines of code (blank stripped).
33121 The open source nature of this project is a key to its continued growth
33123 You gain the benefit and support of many active software developers and
33125 Is SDCC perfect? No, that's why we need your help.
33126 The developers take pride in fixing reported bugs.
33127 You can help by reporting the bugs and helping other SDCC users.
33128 There are lots of ways to contribute, and we encourage you to take part
33129 in making SDCC a great software package.
33133 \begin_layout Standard
33134 The SDCC project is hosted on the SDCC sourceforge site at
33135 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
33140 You'll find the complete set of mailing lists
33141 \begin_inset LatexCommand \index{Mailing list(s)}
33145 , forums, bug reporting system, patch submission
33146 \begin_inset LatexCommand \index{Patch submission}
33151 \begin_inset LatexCommand \index{download}
33155 area and Subversion code repository
33156 \begin_inset LatexCommand \index{Subversion code repository}
33163 \begin_layout Section
33165 \begin_inset LatexCommand \index{Bug reporting}
33170 \begin_inset LatexCommand \index{Reporting bugs}
33177 \begin_layout Standard
33178 The recommended way of reporting bugs is using the infrastructure of the
33180 You can follow the status of bug reports there and have an overview about
33184 \begin_layout Standard
33185 Bug reports are automatically forwarded to the developer mailing list and
33186 will be fixed ASAP.
33187 When reporting a bug, it is very useful to include a small test program
33188 (the smaller the better) which reproduces the problem.
33189 If you can isolate the problem by looking at the generated assembly code,
33190 this can be very helpful.
33191 Compiling your program with the -
33195 \begin_layout Standard
33205 \begin_inset LatexCommand \index{-\/-dumpall}
33209 option can sometimes be useful in locating optimization problems.
33210 When reporting a bug please make sure you:
33213 \begin_layout Enumerate
33214 Attach the code you are compiling with SDCC.
33218 \begin_layout Enumerate
33219 Specify the exact command you use to run SDCC, or attach your Makefile.
33223 \begin_layout Enumerate
33224 Specify the SDCC version (type "
33230 "), your platform, and operating system.
33234 \begin_layout Enumerate
33235 Provide an exact copy of any error message or incorrect output.
33239 \begin_layout Enumerate
33240 Put something meaningful in the subject of your message.
33243 \begin_layout Standard
33244 Please attempt to include these 5 important parts, as applicable, in all
33245 requests for support or when reporting any problems or bugs with SDCC.
33246 Though this will make your message lengthy, it will greatly improve your
33247 chance that SDCC users and developers will be able to help you.
33248 Some SDCC developers are frustrated by bug reports without code provided
33249 that they can use to reproduce and ultimately fix the problem, so please
33250 be sure to provide sample code if you are reporting a bug!
33253 \begin_layout Standard
33254 Please have a short check that you are using a recent version of SDCC and
33255 the bug is not yet known.
33256 This is the link for reporting bugs:
33257 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
33262 With SDCC on average having more than 200 downloads
33263 \begin_inset LatexCommand \index{download}
33267 on sourceforge per day
33271 \begin_layout Standard
33272 220 daily downloads on average Jan-Sept 2006 and about 150 daily downloads
33273 between 2002 and 2005.
33274 This does not include other methods of distribution.
33279 there must be some users.
33280 So it's not exactly easy to find a new bug.
33281 If you find one we need it:
33283 reporting bugs is good
33288 \begin_layout Section
33289 Requesting Features
33290 \begin_inset LatexCommand \label{sub:Requesting-Features}
33295 \begin_inset LatexCommand \index{Feature request}
33300 \begin_inset LatexCommand \index{Requesting features}
33307 \begin_layout Standard
33308 Like bug reports feature requests are forwarded to the developer mailing
33310 This is the link for requesting features:
33311 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
33318 \begin_layout Section
33322 \begin_layout Standard
33323 Like bug reports contributed patches are forwarded to the developer mailing
33325 This is the link for submitting patches
33326 \begin_inset LatexCommand \index{Patch submission}
33331 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
33338 \begin_layout Standard
33339 You need to specify some parameters to the
33343 command for the patches to be useful.
33344 If you modified more than one file a patch created f.e.
33349 \begin_inset Quotes sld
33352 diff -Naur unmodified_directory modified_directory >my_changes.patch
33353 \begin_inset Quotes srd
33359 will be fine, otherwise
33363 \begin_inset Quotes sld
33366 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
33367 \begin_inset Quotes srd
33377 \begin_layout Section
33381 \begin_layout Standard
33382 These links should take you directly to the
33383 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
33391 \begin_layout Standard
33392 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
33393 automated messages (mid 2003)
33399 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
33404 \begin_inset LatexCommand \index{Mailing list(s)}
33408 and forums are archived and searchable so if you are lucky someone already
33409 had a similar problem.
33410 While mails to the lists themselves are delivered promptly their web front
33411 end on sourceforge sometimes shows a severe time lag (up to several weeks),
33412 if you're seriously using SDCC please consider subscribing to the lists.
33415 \begin_layout Section
33419 \begin_layout Standard
33420 You can follow the status of the Subversion version
33421 \begin_inset LatexCommand \index{version}
33425 of SDCC by watching the Changelog
33426 \begin_inset LatexCommand \index{Changelog}
33430 in the Subversion repository
33433 \begin_inset LatexCommand \htmlurl{http://sdcc.svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
33440 \begin_layout Section
33441 Subversion Source Code Repository
33444 \begin_layout Standard
33454 \begin_layout Standard
33468 or the filenames of the snapshot versions of SDCC include date and its
33470 \begin_inset LatexCommand \index{Subversion code repository}
33475 Subversion allows to download the source of recent or previous versions
33477 \begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599}
33481 (by number or by date).
33482 An on-line source code browser and detailled instructions are also available
33484 SDCC versions starting from 1999 up to now are available (currently the
33485 versions prior to the conversion from cvs
33486 \begin_inset LatexCommand \index{cvs|see{Subversion}}
33490 to Subversion (April 2006) are either by accessible by Subversion or by
33494 \begin_layout Section
33496 \begin_inset LatexCommand \index{Release policy}
33503 \begin_layout Standard
33504 Historically there often were long delays between official releases and
33505 the sourceforge download area tends to get not updated at all.
33506 Excuses in the past might have referred to problems with live range analysis,
33507 but as this was fixed a while ago, the current problem is that another
33508 excuse has to be found.
33509 Kidding aside, we have to get better there! On the other hand there are
33510 daily snapshots available at
33511 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
33515 , and you can always build the very last version (hopefully with many bugs
33516 fixed, and features added) from the source code available at
33517 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
33523 \begin_inset LatexCommand \index{wiki}
33528 \begin_inset LatexCommand \index{SDCC Wiki}
33533 \begin_inset LatexCommand \url{http://sdcc.wiki.sourceforge.net/}
33537 also holds some information about past and future releases.
33540 \begin_layout Section
33542 \begin_inset LatexCommand \index{Examples}
33549 \begin_layout Standard
33550 You'll find some small examples in the directory
33552 sdcc/device/examples/.
33555 More examples and libraries are available at
33557 The SDCC Open Knowledge Resource
33558 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
33565 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
33572 \begin_layout Standard
33573 \begin_inset Note Note
33576 \begin_layout Standard
33577 I did insert a reference to Paul's web site here although it seems rather
33578 dedicated to a specific 8032 board (I think it's okay because it f.e.
33579 shows LCD/Harddisc interface and has a free 8051 monitor.
33580 Independent 8032 board vendors face hard competition of heavily subsidized
33581 development boards anyway).
33584 \begin_layout Standard
33585 Maybe we should include some links to real world applications.
33586 Preferably pointer to pointers (one for each architecture) so this stays
33595 \begin_layout Section
33597 \begin_inset LatexCommand \label{sec:Quality-control}
33602 \begin_inset LatexCommand \index{Quality control}
33609 \begin_layout Standard
33610 The compiler is passed through snaphot build compile and build checks.
33616 \begin_inset LatexCommand \index{Regression test}
33620 check that SDCC itself compiles flawlessly on several host platforms (i386,
33621 Opteron, 64 bit Alpha, ppc64, Mac OS X on ppc and i386, Solaris on Sparc)
33622 and checks the quality of the code generated by SDCC by running the code
33623 for several target platforms through simulators.
33624 The regression test suite comprises more than 100 files which expand to
33625 more than 500 test cases which include more than 4500 tests.
33626 The results of these tests are published daily on SDCC's snapshot page
33627 (click on the red or green symbols on the right side of
33628 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
33635 \begin_layout Standard
33636 There is a separate document
33639 \begin_inset LatexCommand \index{Test suite}
33646 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf}
33650 about the regression test suite.
33653 \begin_layout Standard
33654 You'll find the test code in the directory
33656 sdcc/support/regression
33659 You can run these tests manually by running
33663 in this directory (or f.e.
33668 \begin_inset Quotes sld
33672 \begin_inset Quotes srd
33678 if you don't want to run the complete tests).
33679 The test code might also be interesting if you want to look for examples
33680 \begin_inset LatexCommand \index{Examples}
33684 checking corner cases of SDCC or if you plan to submit patches
33685 \begin_inset LatexCommand \index{Patch submission}
33692 \begin_layout Standard
33693 The PIC14 port uses a different set of regression tests
33694 \begin_inset LatexCommand \index{Regression test (PIC14)}
33698 , you'll find them in the directory
33700 sdcc/src/regression
33705 \begin_layout Section
33706 Use of SDCC in Education
33709 \begin_layout Standard
33718 \begin_layout Standard
33719 the phrase "use in education" might evoke the association "
33723 fit for use in education".
33724 This connotation is not intended but nevertheless risked as the licensing
33725 of SDCC makes it difficult to offer educational discounts
33731 If your rationales are to:
33734 \begin_layout Enumerate
33735 give students a chance to understand the
33739 steps of code generation
33742 \begin_layout Enumerate
33743 have a curriculum that can be extended for years.
33744 Then you could use an fpga board as target and your curriculum will seamlessly
33745 extend from logic synthesis (
33746 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
33751 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
33755 ), over assembly programming, to C to FPGA compilers (
33756 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
33763 \begin_layout Enumerate
33764 be able to insert excursions about skills like using a revision control
33765 system, submitting/applying patches, using a type-setting (as opposed to
33766 word-processing) engine LyX/LaTeX, using
33767 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
33772 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
33776 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
33777 Source Software, CPU simulation, compiler regression tests
33778 \begin_inset LatexCommand \index{Regression test}
33785 And if there should be a shortage of ideas then you can always point students
33786 to the ever-growing feature request list
33787 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
33794 \begin_layout Enumerate
33795 not tie students to a specific host platform and instead allow them to use
33800 choice (among them Alpha, i386, i386_64, Mac OS X, Mips, Sparc, Windows
33802 \begin_inset LatexCommand \url[OLPC]{http://www.laptop.org}
33809 \begin_layout Enumerate
33810 not encourage students to use illegal copies of educational software
33813 \begin_layout Enumerate
33814 be immune to licensing/availability/price changes of the chosen tool chain
33817 \begin_layout Enumerate
33818 be able to change to a new target platform without having to adopt a new
33822 \begin_layout Enumerate
33823 have complete control over and insight into the tool chain
33826 \begin_layout Enumerate
33827 make your students aware about the pros and cons of open source software
33831 \begin_layout Enumerate
33832 give back to the public as you are probably at least partially publically
33836 \begin_layout Enumerate
33837 give students a chance to publically prove their skills and to possibly
33838 see a world wide impact
33841 \begin_layout Standard
33842 then SDCC is probably among the first choices.
33843 Well, probably SDCC might be the only choice.
33848 \begin_layout Chapter
33849 SDCC Technical Data
33852 \begin_layout Section
33854 \begin_inset LatexCommand \index{Optimizations}
33861 \begin_layout Standard
33862 SDCC performs a host of standard optimizations in addition to some MCU specific
33867 \begin_layout Subsection
33868 Sub-expression Elimination
33869 \begin_inset LatexCommand \index{Subexpression elimination}
33876 \begin_layout Standard
33877 The compiler does local and
33896 \begin_layout Verse
33904 \begin_layout Standard
33905 will be translated to
33908 \begin_layout Verse
33918 \begin_layout Standard
33919 Some subexpressions are not as obvious as the above example, e.g.:
33922 \begin_layout Verse
33930 \begin_layout Standard
33931 In this case the address arithmetic a->b[i] will be computed only once;
33932 the equivalent code in C would be.
33935 \begin_layout Verse
33945 \begin_layout Standard
33946 The compiler will try to keep these temporary variables in registers.
33949 \begin_layout Subsection
33950 Dead-Code Elimination
33951 \begin_inset LatexCommand \index{Dead-code elimination}
33958 \begin_layout Verse
33973 i = 1; \InsetSpace ~
33982 global = 1;\InsetSpace ~
33996 global = 3;\InsetSpace ~
34002 \begin_layout Standard
34006 \begin_layout Verse
34022 \begin_layout Subsection
34024 \begin_inset LatexCommand \index{Copy propagation}
34031 \begin_layout Verse
34055 \begin_layout Standard
34059 \begin_layout Verse
34083 \begin_layout Standard
34084 Note: the dead stores created by this copy propagation will be eliminated
34085 by dead-code elimination.
34088 \begin_layout Subsection
34090 \begin_inset LatexCommand \index{Loop optimization}
34095 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
34102 \begin_layout Standard
34103 Two types of loop optimizations are done by SDCC
34111 of loop induction variables.
34112 In addition to the strength reduction the optimizer marks the induction
34113 variables and the register allocator tries to keep the induction variables
34114 in registers for the duration of the loop.
34115 Because of this preference of the register allocator
34116 \begin_inset LatexCommand \index{Register allocation}
34120 , loop induction optimization causes an increase in register pressure, which
34121 may cause unwanted spilling of other temporary variables into the stack
34122 \begin_inset LatexCommand \index{stack}
34127 The compiler will generate a warning message when it is forced to allocate
34128 extra space either on the stack or data space.
34129 If this extra space allocation is undesirable then induction optimization
34130 can be eliminated either for the entire source file (with -
34134 \begin_layout Standard
34143 -noinduction option) or for a given function only using #pragma\InsetSpace ~
34145 \begin_inset LatexCommand \index{\#pragma noinduction}
34156 \begin_layout Verse
34159 for (i = 0 ; i < 100 ; i ++)
34168 \begin_layout Standard
34172 \begin_layout Verse
34177 for (i = 0; i < 100; i++)
34186 \begin_layout Standard
34187 As mentioned previously some loop invariants are not as apparent, all static
34188 address computations are also moved out of the loop.
34193 \begin_inset LatexCommand \index{Strength reduction}
34197 , this optimization substitutes an expression by a cheaper expression:
34200 \begin_layout Verse
34203 for (i=0;i < 100; i++)
34212 \begin_layout Standard
34216 \begin_layout Verse
34223 for (i=0;i< 100;i++) {
34229 ar[itemp1] = itemp2;
34247 \begin_layout Standard
34248 The more expensive multiplication
34249 \begin_inset LatexCommand \index{Multiplication}
34253 is changed to a less expensive addition.
34256 \begin_layout Subsection
34258 \begin_inset LatexCommand \index{Loop reversing}
34265 \begin_layout Standard
34266 This optimization is done to reduce the overhead of checking loop boundaries
34267 for every iteration.
34268 Some simple loops can be reversed and implemented using a
34269 \begin_inset Quotes eld
34272 decrement and jump if not zero
34273 \begin_inset Quotes erd
34277 SDCC checks for the following criterion to determine if a loop is reversible
34278 (note: more sophisticated compilers use data-dependency analysis to make
34279 this determination, SDCC uses a more simple minded analysis).
34282 \begin_layout Itemize
34283 The 'for' loop is of the form
34289 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
34299 \begin_layout Itemize
34300 The <for body> does not contain
34301 \begin_inset Quotes eld
34305 \begin_inset Quotes erd
34309 \begin_inset Quotes erd
34315 \begin_layout Itemize
34316 All goto's are contained within the loop.
34319 \begin_layout Itemize
34320 No function calls within the loop.
34323 \begin_layout Itemize
34324 The loop control variable <sym> is not assigned any value within the loop
34327 \begin_layout Itemize
34328 The loop control variable does NOT participate in any arithmetic operation
34332 \begin_layout Itemize
34333 There are NO switch statements in the loop.
34336 \begin_layout Subsection
34337 Algebraic Simplifications
34340 \begin_layout Standard
34341 SDCC does numerous algebraic simplifications, the following is a small sub-set
34342 of these optimizations.
34345 \begin_layout Verse
34348 i = j + 0;\InsetSpace ~
34352 /* changed to: */\InsetSpace ~
34358 i /= 2;\InsetSpace ~
34365 /* changed to: */\InsetSpace ~
34372 = j - j;\InsetSpace ~
34376 /* changed to: */\InsetSpace ~
34382 i = j / 1;\InsetSpace ~
34386 /* changed to: */\InsetSpace ~
34393 \begin_layout Standard
34394 Note the subexpressions
34395 \begin_inset LatexCommand \index{Subexpression}
34399 given above are generally introduced by macro expansions or as a result
34400 of copy/constant propagation.
34403 \begin_layout Subsection
34404 'switch' Statements
34405 \begin_inset LatexCommand \label{sub:'switch'-Statements}
34410 \begin_inset LatexCommand \index{switch statement}
34417 \begin_layout Standard
34418 SDCC can optimize switch statements to jump tables
34419 \begin_inset LatexCommand \index{jump tables}
34424 It makes the decision based on an estimate of the generated code size.
34425 SDCC is quite liberal in the requirements for jump table generation:
34428 \begin_layout Itemize
34429 The labels need not be in order, and the starting number need not be one
34430 or zero, the case labels are in numerical sequence or not too many case
34431 labels are missing.
34435 \begin_layout Verse
34438 switch(i) {\InsetSpace ~
34469 case 4: ...\InsetSpace ~
34501 case 5: ...\InsetSpace ~
34533 case 3: ...\InsetSpace ~
34564 case 6: ...\InsetSpace ~
34596 case 7: ...\InsetSpace ~
34628 case 8: ...\InsetSpace ~
34660 case 9: ...\InsetSpace ~
34692 case 10: ...\InsetSpace ~
34723 case 11: ...\InsetSpace ~
34790 \begin_layout Standard
34791 Both the above switch statements will be implemented using a jump-table.
34792 The example to the right side is slightly more efficient as the check for
34793 the lower boundary of the jump-table is not needed.
34797 \begin_layout Itemize
34798 The number of case labels is not larger than supported by the target architectur
34802 \begin_layout Itemize
34803 If the case labels are not in numerical sequence ('gaps' between cases)
34804 SDCC checks whether a jump table with additionally inserted dummy cases
34805 is still attractive.
34809 \begin_layout Itemize
34810 If the starting number is not zero and a check for the lower boundary of
34811 the jump-table can thus be eliminated SDCC might insert dummy cases 0,
34816 \begin_layout Standard
34817 Switch statements which have large gaps in the numeric sequence or those
34818 that have too many case labels can be split into more than one switch statement
34819 for efficient code generation, e.g.:
34822 \begin_layout Verse
34900 \begin_layout Standard
34901 If the above switch statement is broken down into two switch statements
34904 \begin_layout Verse
34947 \begin_layout Standard
34951 \begin_layout Verse
34994 \begin_layout Standard
34995 then both the switch statements will be implemented using jump-tables whereas
34996 the unmodified switch statement will not be.
34999 \begin_layout Standard
35000 \begin_inset Note Note
35003 \begin_layout Standard
35004 There might be reasons which SDCC cannot know about to either favour or
35005 not favour jump tables.
35006 If the target system has to be as quick for the last switch case as for
35007 the first (pro jump table), or if the switch argument is known to be zero
35008 in the majority of the cases (contra jump table).
35016 \begin_layout Standard
35017 The pragma nojtbound
35018 \begin_inset LatexCommand \index{\#pragma nojtbound}
35022 can be used to turn off checking the
35035 It has no effect if a default label is supplied.
35036 Use of this pragma is dangerous: if the switch
35037 \begin_inset LatexCommand \index{switch statement}
35041 argument is not matched by a case statement the processor will happily
35045 \begin_layout Subsection
35046 Bit-shifting Operations
35047 \begin_inset LatexCommand \index{Bit shifting}
35054 \begin_layout Standard
35055 Bit shifting is one of the most frequently used operation in embedded programmin
35057 SDCC tries to implement bit-shift operations in the most efficient way
35061 \begin_layout Verse
35074 \begin_layout Standard
35075 generates the following code:
35078 \begin_layout Verse
35093 \begin_layout Standard
35094 In general SDCC will never setup a loop if the shift count is known.
35098 \begin_layout Verse
35111 \begin_layout Standard
35115 \begin_layout Verse
35139 \begin_layout Subsection
35141 \begin_inset LatexCommand \index{Bit rotation}
35148 \begin_layout Standard
35149 A special case of the bit-shift operation is bit rotation
35150 \begin_inset LatexCommand \index{rotating bits}
35154 , SDCC recognizes the following expression to be a left bit-rotation:
35157 \begin_layout Verse
35165 char i;\InsetSpace ~
35176 /* unsigned is needed for rotation */
35181 i = ((i << 1) | (i >> 7));
35190 \begin_layout Standard
35191 will generate the following code:
35194 \begin_layout Verse
35211 \begin_layout Standard
35212 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
35213 ns of this case will also be recognized as bit-rotation, i.e.:
35216 \begin_layout Verse
35219 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
35222 \begin_layout Subsection
35223 Nibble and Byte Swapping
35226 \begin_layout Standard
35227 Other special cases of the bit-shift operations are nibble or byte swapping
35228 \begin_inset LatexCommand \index{swapping nibbles/bytes}
35232 , SDCC recognizes the following expressions:
35235 \begin_layout Verse
35256 i = ((i << 4) | (i >> 4));
35262 j = ((j << 8) | (j >> 8));
35265 \begin_layout Standard
35266 and generates a swap instruction for the nibble swapping
35267 \begin_inset LatexCommand \index{Nibble swapping}
35271 or move instructions for the byte swapping
35272 \begin_inset LatexCommand \index{Byte swapping}
35278 \begin_inset Quotes sld
35282 \begin_inset Quotes srd
35285 example can be used to convert from little to big-endian or vice versa.
35286 If you want to change the endianness of a
35290 integer you have to cast to
35297 \begin_layout Standard
35298 Note that SDCC stores numbers in little-endian
35302 \begin_layout Standard
35303 Usually 8-bit processors don't care much about endianness.
35304 This is not the case for the standard 8051 which only has an instruction
35310 \begin_inset LatexCommand \index{DPTR}
35318 so little-endian is the more efficient byte order.
35324 \begin_inset LatexCommand \index{little-endian}
35329 \begin_inset LatexCommand \index{Endianness}
35334 lowest order first).
35337 \begin_layout Subsection
35339 \begin_inset LatexCommand \index{Highest Order Bit}
35344 \begin_inset LatexCommand \index{Any Order Bit}
35351 \begin_layout Standard
35352 It is frequently required to obtain the highest order bit of an integral
35353 type (long, int, short or char types).
35354 Also obtaining any other order bit is not uncommon.
35355 SDCC recognizes the following expressions to yield the highest order bit
35356 and generates optimized code for it, e.g.:
35359 \begin_layout Verse
35370 unsigned char hob1, aob1;
35374 bit hob2, hob3, aob2,
35384 hob1 = (gint >> 15) & 1;
35388 hob2 = (gint >> 15) & 1;
35392 hob3 = gint & 0x8000;
35397 aob1 = (gint >> 9) & 1;
35401 aob2 = (gint >> 8) & 1;
35405 aob3 = gint & 0x0800;
35415 \begin_layout Standard
35416 will generate the following code:
35419 \begin_layout Verse
35450 000A E5*01\InsetSpace ~
35477 000C 23\InsetSpace ~
35508 000D 54 01\InsetSpace ~
35536 000F F5*02\InsetSpace ~
35591 0011 E5*01\InsetSpace ~
35619 0013 33\InsetSpace ~
35649 0014 92*00\InsetSpace ~
35705 0016 E5*01\InsetSpace ~
35732 0018 33\InsetSpace ~
35762 0019 92*01\InsetSpace ~
35818 001B E5*01\InsetSpace ~
35877 001E 54 01\InsetSpace ~
35904 0020 F5*03\InsetSpace ~
35960 0022 E5*01\InsetSpace ~
35987 0024 13\InsetSpace ~
36017 0025 92*02\InsetSpace ~
36073 0027 E5*01\InsetSpace ~
36128 002B 92*03\InsetSpace ~
36156 \begin_layout Standard
36157 Other variations of these cases however will
36162 They are standard C expressions, so I heartily recommend these be the only
36163 way to get the highest order bit, (it is portable).
36164 Of course it will be recognized even if it is embedded in other expressions,
36168 \begin_layout Verse
36171 xyz = gint + ((gint >> 15) & 1);
36174 \begin_layout Standard
36175 will still be recognized.
36178 \begin_layout Subsection
36180 \begin_inset LatexCommand \index{Higher Order Byte}
36184 / Higher Order Word
36185 \begin_inset LatexCommand \index{Higher Order Word}
36192 \begin_layout Standard
36193 It is also frequently required to obtain a higher order byte or word of
36194 a larger integral type (long, int or short types).
36195 SDCC recognizes the following expressions to yield the higher order byte
36196 or word and generates optimized code for it, e.g.:
36199 \begin_layout Verse
36204 unsigned long int glong;
36212 unsigned char hob1,
36217 unsigned int how1, how2;
36226 hob1 = (gint >> 8) & 0xFF;
36230 hob2 = glong >> 24;
36234 how1 = (glong >> 16) & 0xFFFF;
36249 \begin_layout Standard
36250 will generate the following code:
36253 \begin_layout Verse
36284 0037 85*01*06\InsetSpace ~
36306 _foo_hob1_1_1,(_gint + 1)
36337 003A 85*05*07\InsetSpace ~
36359 _foo_hob2_1_1,(_glong + 3)
36389 003D 85*04*08\InsetSpace ~
36412 _foo_how1_1_1,(_glong + 2)
36414 0040 85*05*09\InsetSpace ~
36439 0043 85*03*0A\InsetSpace ~
36461 _foo_how2_1_1,(_glong + 1)
36463 0046 85*04*0B\InsetSpace ~
36486 (_foo_how2_1_1 + 1),(_glong + 2)
36489 \begin_layout Standard
36490 Again, variations of these cases may
36495 They are standard C expressions, so I heartily recommend these be the only
36496 way to get the higher order byte/word, (it is portable).
36497 Of course it will be recognized even if it is embedded in other expressions,
36501 \begin_layout Verse
36504 xyz = gint + ((gint >> 8) & 0xFF);
36507 \begin_layout Standard
36508 will still be recognized.
36511 \begin_layout Subsection
36513 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
36518 \begin_inset LatexCommand \index{Peephole optimizer}
36525 \begin_layout Standard
36526 The compiler uses a rule based, pattern matching and re-writing mechanism
36527 for peep-hole optimization.
36532 a peep-hole optimizer by Christopher W.
36533 Fraser (cwfraser\InsetSpace ~
36536 A default set of rules are compiled into the compiler, additional rules
36537 may be added with the
36543 \begin_layout Standard
36553 \begin_inset LatexCommand \index{-\/-peep-file}
36560 The rule language is best illustrated with examples.
36563 \begin_layout Verse
36585 \begin_layout Standard
36586 The above rule will change the following assembly
36587 \begin_inset LatexCommand \index{Assembler routines}
36594 \begin_layout Verse
36602 \begin_layout Standard
36606 \begin_layout Verse
36612 \begin_layout Standard
36613 Note: All occurrences of a
36617 (pattern variable) must denote the same string.
36618 With the above rule, the assembly sequence:
36621 \begin_layout Verse
36629 \begin_layout Standard
36630 will remain unmodified.
36634 Other special case optimizations may be added by the
36641 \begin_layout Standard
36654 some variants of the 8051 MCU
36655 \begin_inset LatexCommand \index{MCS51 variants}
36668 The following two rules will change all
36685 \begin_layout Verse
36688 replace { lcall %1 } by { acall %1 }
36690 replace { ljmp %1 } by { ajmp %1 }
36693 \begin_layout Standard
36694 (NOTE: from version 2.7.3 on, you can use option -
36700 \begin_layout Standard
36712 \begin_inset LatexCommand \index{-\/-acall-ajmp}
36716 , which also takes care of aligning the interrupt vectors properly.)
36721 \begin_layout Standard
36724 inline-assembler code
36726 is also passed through the peep hole optimizer, thus the peephole optimizer
36727 can also be used as an assembly level macro expander.
36728 The rules themselves are MCU dependent whereas the rule language infra-structur
36729 e is MCU independent.
36730 Peephole optimization rules for other MCU can be easily programmed using
36735 The syntax for a rule is as follows:
36738 \begin_layout Verse
36741 rule := replace [ restart ] '{' <assembly sequence> '
36779 <assembly sequence> '
36797 '}' [if <functionName> ] '
36802 \begin_layout Standard
36803 <assembly sequence> := assembly instruction (each instruction including
36804 labels must be on a separate line).
36808 The optimizer will apply to the rules
36809 one by one from the top in the sequence of their appearance, it will terminate
36810 when all rules are exhausted.
36811 If the 'restart' option is specified, then the optimizer will start matching
36812 the rules again from the top, this option for a rule is expensive (performance)
36813 , it is intended to be used in situations where a transformation will trigger
36814 the same rule again.
36815 An example of this (not a good one, it has side effects) is the following
36819 \begin_layout Verse
36839 \begin_layout Standard
36840 Note that the replace pattern cannot be a blank, but can be a comment line.
36841 Without the 'restart' option only the innermost 'pop' 'push' pair would
36842 be eliminated, i.e.:
36845 \begin_layout Verse
36857 \begin_layout Standard
36861 \begin_layout Verse
36871 \begin_layout Standard
36876 the restart option the rule will be applied again to the resulting code
36877 and then all the pop-push pairs will be eliminated to yield:
36880 \begin_layout Verse
36888 \begin_layout Standard
36889 A conditional function can be attached to a rule.
36890 Attaching rules are somewhat more involved, let me illustrate this with
36894 \begin_layout Verse
36918 \begin_layout Standard
36919 The optimizer does a look-up of a function name table defined in function
36924 in the source file SDCCpeeph.c, with the name
36929 If it finds a corresponding entry the function is called.
36930 Note there can be no parameters specified for these functions, in this
36935 is crucial, since the function
36939 expects to find the label in that particular variable (the hash table containin
36940 g the variable bindings is passed as a parameter).
36941 If you want to code more such functions, take a close look at the function
36942 labelInRange and the calling mechanism in source file SDCCpeeph.c.
36943 Currently implemented are
36945 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
36946 24bitMode, portIsDS390, 24bitModeAndPortDS390
36955 \begin_layout Standard
36956 I know this whole thing is a little kludgey, but maybe some day we will
36957 have some better means.
36958 If you are looking at this file, you will see the default rules that are
36959 compiled into the compiler, you can add your own rules in the default set
36960 there if you get tired of specifying the -
36964 \begin_layout Standard
36976 \begin_layout Section
36978 \begin_inset LatexCommand \index{ANSI-compliance}
36983 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
36990 \begin_layout Standard
36991 The latest publically available version of the standard
36993 ISO/IEC 9899 - Programming languages - C
36995 should be available at:
36996 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
37005 \begin_layout Standard
37006 Deviations from the compliance:
37009 \begin_layout Itemize
37010 functions are not reentrant
37011 \begin_inset LatexCommand \index{reentrant}
37015 unless explicitly declared as such or the
37021 \begin_layout Standard
37031 \begin_inset LatexCommand \index{-\/-stack-auto}
37037 command line option is specified.
37040 \begin_layout Itemize
37042 \begin_inset LatexCommand \index{struct}
37047 \begin_inset LatexCommand \index{union}
37051 cannot be assigned values directly, cannot be passed as function parameters
37052 or assigned to each other and cannot be a return value
37053 \begin_inset LatexCommand \index{return value}
37057 from a function, e.g.:
37061 \begin_layout Verse
37084 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
37103 s parms) /* invalid in SDCC although allowed in ANSI */
37125 return rets; /* is invalid in SDCC although allowed in ANSI */
37131 \begin_layout Itemize
37132 initialization of structure arrays must be fully braced.
37136 \begin_layout Verse
37139 struct s { char x } a[] = {1, 2};\InsetSpace ~
37144 /* invalid in SDCC */
37147 } a[] = {{1}, {2}}; /* OK */
37151 \begin_layout Itemize
37153 \begin_inset LatexCommand \index{long long (not supported)}
37158 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
37165 \begin_layout Itemize
37167 \begin_inset LatexCommand \index{double (not supported)}
37171 ' precision floating point
37172 \begin_inset LatexCommand \index{Floating point support}
37179 \begin_layout Itemize
37181 \begin_inset LatexCommand \index{K\&R style}
37185 function declarations are NOT allowed.
37189 \begin_layout Verse
37192 foo(i,j) /* this old style of function declarations */
37194 int i,j; /* is valid
37195 in ANSI but not valid in SDCC */
37210 \begin_layout Itemize
37211 Most enhancements in C99 are not supported, e.g.:
37215 \begin_layout Verse
37222 i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
37226 \begin_layout Itemize
37227 But some have been added recently in SDCC 2.7.0.
37228 They must be considered alpha quality however.
37232 \begin_layout Verse
37237 \begin_inset LatexCommand \index{inline (not supported)}
37243 int increment (int a) { return a+1; } /* inlines the increment without
37244 function call overhead */
37249 \begin_inset LatexCommand \index{inline (not supported)}
37255 p; /* accepted but ignored */
37259 \begin_layout Itemize
37260 Certain words that are valid identifiers in the standard may be reserved
37261 words in SDCC unless the
37267 \begin_layout Standard
37277 \begin_inset LatexCommand \index{-\/-std-c89}
37289 \begin_layout Standard
37299 \begin_inset LatexCommand \index{-\/-std-c99}
37305 command line options are used.
37306 These may include (depending on the selected processor): 'at', 'banked',
37307 'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
37308 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
37309 'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
37311 Compliant equivalents of these keywords are always available in a form
37312 that begin with two underscores
37313 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
37318 '__data' instead of 'data'.
37321 \begin_layout Itemize
37322 Integer promotion of variable arguments is not performed if the argument
37323 is explicitly taypecasted unless the
37329 \begin_layout Standard
37339 \begin_inset LatexCommand \index{-\/-std-c89}
37351 \begin_layout Standard
37361 \begin_inset LatexCommand \index{-\/-std-c99}
37367 command line options are used.
37371 \begin_layout Verse
37374 void vararg_func (char *str, ...) { str; }
37391 u is promoted to int before
37396 * passing to function */
37400 vararg_func ("%c", c);
37407 argument u is not promoted to int,
37412 * it is passed as char to function
37418 --std-cXX is not defined;
37423 * is promoted to int before passing
37429 if --std-cXX is defined */
37433 vararg_func ("%bc", (char)u);
37439 \begin_layout Section
37440 Cyclomatic Complexity
37441 \begin_inset LatexCommand \index{Cyclomatic complexity}
37448 \begin_layout Standard
37449 Cyclomatic complexity of a function is defined as the number of independent
37450 paths the program can take during execution of the function.
37451 This is an important number since it defines the number test cases you
37452 have to generate to validate the function.
37453 The accepted industry standard for complexity number is 10, if the cyclomatic
37454 complexity reported by SDCC exceeds 10 you should think about simplification
37455 of the function logic.
37456 Note that the complexity level is not related to the number of lines of
37457 code in a function.
37458 Large functions can have low complexity, and small functions can have large
37464 SDCC uses the following formula to compute the complexity:
37469 \begin_layout Standard
37470 complexity = (number of edges in control flow graph) - (number of nodes
37471 in control flow graph) + 2;
37475 Having said that the industry standard is 10,
37476 you should be aware that in some cases it be may unavoidable to have a
37477 complexity level of less than 10.
37478 For example if you have switch statement with more than 10 case labels,
37479 each case label adds one to the complexity level.
37480 The complexity level is by no means an absolute measure of the algorithmic
37481 complexity of the function, it does however provide a good starting point
37482 for which functions you might look at for further optimization.
37485 \begin_layout Section
37486 Retargetting for other Processors
37489 \begin_layout Standard
37490 The issues for retargetting the compiler are far too numerous to be covered
37492 What follows is a brief description of each of the seven phases of the
37493 compiler and its MCU dependency.
37496 \begin_layout Itemize
37497 Parsing the source and building the annotated parse tree.
37498 This phase is largely MCU independent (except for the language extensions).
37499 Syntax & semantic checks are also done in this phase, along with some initial
37500 optimizations like back patching labels and the pattern matching optimizations
37501 like bit-rotation etc.
37504 \begin_layout Itemize
37505 The second phase involves generating an intermediate code which can be easy
37506 manipulated during the later phases.
37507 This phase is entirely MCU independent.
37508 The intermediate code generation assumes the target machine has unlimited
37509 number of registers, and designates them with the name iTemp.
37510 The compiler can be made to dump a human readable form of the code generated
37515 \begin_layout Standard
37527 \begin_layout Itemize
37528 This phase does the bulk of the standard optimizations and is also MCU independe
37530 This phase can be broken down into several sub-phases:
37534 Break down intermediate
37535 code (iCode) into basic blocks.
37537 Do control flow & data flow analysis on the
37540 Do local common subexpression elimination, then global subexpressio
37543 Dead code elimination
37547 If loop optimizations
37548 caused any changes then do 'global subexpression elimination' and 'dead
37549 code elimination' again.
37552 \begin_layout Itemize
37553 This phase determines the live-ranges; by live range I mean those iTemp
37554 variables defined by the compiler that still survive after all the optimization
37556 Live range analysis
37557 \begin_inset LatexCommand \index{Live range analysis}
37561 is essential for register allocation, since these computation determines
37562 which of these iTemps will be assigned to registers, and for how long.
37565 \begin_layout Itemize
37566 Phase five is register allocation.
37567 There are two parts to this process.
37571 The first part I call 'register packing'
37572 (for lack of a better term).
37573 In this case several MCU specific expression folding is done to reduce
37578 The second part is more MCU independent and deals with
37579 allocating registers to the remaining live ranges.
37580 A lot of MCU specific code does creep into this phase because of the limited
37581 number of index registers available in the 8051.
37584 \begin_layout Itemize
37585 The Code generation phase is (unhappily), entirely MCU dependent and very
37586 little (if any at all) of this code can be reused for other MCU.
37587 However the scheme for allocating a homogenized assembler operand for each
37588 iCode operand may be reused.
37591 \begin_layout Itemize
37592 As mentioned in the optimization section the peep-hole optimizer is rule
37593 based system, which can reprogrammed for other MCUs.
37596 \begin_layout Standard
37597 More information is available on SDCC Wiki
37598 \begin_inset LatexCommand \index{wiki}
37603 \begin_inset LatexCommand \url{http://sdcc.wiki.sourceforge.net/SDCC+internals+and+porting}
37607 ) and in the thread
37608 \begin_inset LatexCommand \url{http://sf.net/mailarchive/message.php?msg_id=13954144}
37615 \begin_layout Chapter
37617 \begin_inset LatexCommand \index{Compiler internals}
37624 \begin_layout Section
37625 The anatomy of the compiler
37626 \begin_inset LatexCommand \label{sub:The-anatomy-of}
37633 \begin_layout Standard
37636 This is an excerpt from an article published in Circuit Cellar Magazine
37642 It's a little outdated (the compiler is much more efficient now and user/develo
37643 per friendly), but pretty well exposes the guts of it all.
37649 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
37650 It is fairly easy to retarget for other 8-bit MCU.
37651 Here we take a look at some of the internals of the compiler.
37655 \begin_layout Paragraph*
37657 \begin_inset LatexCommand \index{Parsing}
37664 \begin_layout Standard
37665 Parsing the input source file and creating an AST (Annotated Syntax Tree
37666 \begin_inset LatexCommand \index{Annotated syntax tree}
37671 This phase also involves propagating types (annotating each node of the
37672 parse tree with type information) and semantic analysis.
37673 There are some MCU specific parsing rules.
37674 For example the storage classes, the extended storage classes are MCU specific
37675 while there may be a xdata storage class for 8051 there is no such storage
37676 class for z80 or Atmel AVR.
37677 SDCC allows MCU specific storage class extensions, i.e.
37678 xdata will be treated as a storage class specifier when parsing 8051 C
37679 code but will be treated as a C identifier when parsing z80 or ATMEL AVR
37683 \begin_layout Paragraph*
37685 \begin_inset LatexCommand \index{iCode}
37692 \begin_layout Standard
37693 Intermediate code generation.
37694 In this phase the AST is broken down into three-operand form (iCode).
37695 These three operand forms are represented as doubly linked lists.
37696 ICode is the term given to the intermediate form generated by the compiler.
37697 ICode example section shows some examples of iCode generated for some simple
37698 C source functions.
37701 \begin_layout Paragraph*
37703 \begin_inset LatexCommand \index{Optimizations}
37710 \begin_layout Standard
37711 Bulk of the target independent optimizations is performed in this phase.
37712 The optimizations include constant propagation, common sub-expression eliminati
37713 on, loop invariant code movement, strength reduction of loop induction variables
37714 and dead-code elimination.
37717 \begin_layout Paragraph*
37718 Live range analysis
37719 \begin_inset LatexCommand \index{Live range analysis}
37726 \begin_layout Standard
37727 During intermediate code generation phase, the compiler assumes the target
37728 machine has infinite number of registers and generates a lot of temporary
37730 The live range computation determines the lifetime of each of these compiler-ge
37731 nerated temporaries.
37732 A picture speaks a thousand words.
37733 ICode example sections show the live range annotations for each of the
37735 It is important to note here, each iCode is assigned a number in the order
37736 of its execution in the function.
37737 The live ranges are computed in terms of these numbers.
37738 The from number is the number of the iCode which first defines the operand
37739 and the to number signifies the iCode which uses this operand last.
37742 \begin_layout Paragraph*
37743 Register Allocation
37744 \begin_inset LatexCommand \index{Register allocation}
37751 \begin_layout Standard
37752 The register allocation determines the type and number of registers needed
37754 In most MCUs only a few registers can be used for indirect addressing.
37755 In case of 8051 for example the registers R0 & R1 can be used to indirectly
37756 address the internal ram and DPTR to indirectly address the external ram.
37757 The compiler will try to allocate the appropriate register to pointer variables
37759 ICode example section shows the operands annotated with the registers assigned
37761 The compiler will try to keep operands in registers as much as possible;
37762 there are several schemes the compiler uses to do achieve this.
37763 When the compiler runs out of registers the compiler will check to see
37764 if there are any live operands which is not used or defined in the current
37765 basic block being processed, if there are any found then it will push that
37766 operand and use the registers in this block, the operand will then be popped
37767 at the end of the basic block.
37771 \begin_layout Standard
37772 There are other MCU specific considerations in this phase.
37773 Some MCUs have an accumulator; very short-lived operands could be assigned
37774 to the accumulator instead of a general-purpose register.
37777 \begin_layout Paragraph*
37781 \begin_layout Standard
37782 Figure II gives a table of iCode
37783 \begin_inset LatexCommand \index{iCode}
37787 operations supported by the compiler.
37788 The code generation involves translating these operations into corresponding
37789 assembly code for the processor.
37790 This sounds overly simple but that is the essence of code generation.
37791 Some of the iCode operations are generated on a MCU specific manner for
37792 example, the z80 port does not use registers to pass parameters so the
37793 SEND and RECV iCode operations will not be generated, and it also does
37794 not support JUMPTABLES.
37800 \begin_layout Standard
37804 \begin_inset Tabular
37805 <lyxtabular version="3" rows="39" columns="4">
37806 <features islongtable="true" headBottomDL="true">
37807 <column alignment="block" valignment="top" leftline="true" width="13col%">
37808 <column alignment="left" valignment="top" leftline="true" width="13col%">
37809 <column alignment="block" valignment="top" leftline="true" width="22col%">
37810 <column alignment="block" valignment="top" leftline="true" rightline="true" width="40col%">
37811 <row topline="true" bottomline="true" endhead="true">
37812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37815 \begin_layout Standard
37821 \begin_inset LatexCommand \index{iCode}
37830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37833 \begin_layout Standard
37841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37844 \begin_layout Standard
37852 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
37855 \begin_layout Standard
37864 <row topline="true">
37865 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37868 \begin_layout Standard
37876 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37879 \begin_layout Standard
37882 IC_LEFT() IC_RESULT()
37887 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37890 \begin_layout Standard
37898 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
37901 \begin_layout Standard
37904 IC_RESULT = ! IC_LEFT;
37910 <row topline="true">
37911 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37914 \begin_layout Standard
37922 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37925 \begin_layout Standard
37928 IC_LEFT() IC_RESULT()
37933 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37936 \begin_layout Standard
37939 Bitwise complement of
37944 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
37947 \begin_layout Standard
37950 IC_RESULT = ~IC_LEFT;
37956 <row topline="true">
37957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37960 \begin_layout Standard
37968 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37971 \begin_layout Standard
37974 IC_LEFT() IC_RESULT()
37979 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
37982 \begin_layout Standard
37985 Rotate right with carry
37990 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
37993 \begin_layout Standard
37996 IC_RESULT = (IC_LEFT << 1) | (IC_LEFT >> (sizeof(IC_LEFT)*8-1));
38002 <row topline="true">
38003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38006 \begin_layout Standard
38014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38017 \begin_layout Standard
38020 IC_LEFT() IC_RESULT()
38025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38028 \begin_layout Standard
38031 Rotate left with carry
38036 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38039 \begin_layout Standard
38042 IC_RESULT = (IC_LEFT << (sizeof(LC_LEFT)*8-1) ) | (IC_LEFT >> 1);
38048 <row topline="true">
38049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38052 \begin_layout Standard
38060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38063 \begin_layout Standard
38066 IC_LEFT() IC_RESULT()
38071 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38074 \begin_layout Standard
38077 Get the highest order bit of IC_LEFT
38082 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38085 \begin_layout Standard
38088 IC_RESULT = (IC_LEFT >> (sizeof(IC_LEFT)*8 -1));
38094 <row topline="true">
38095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38098 \begin_layout Standard
38106 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38109 \begin_layout Standard
38112 IC_LEFT() IC_RESULT()
38117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38120 \begin_layout Standard
38128 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38131 \begin_layout Standard
38134 IC_RESULT = - IC_LEFT;
38140 <row topline="true">
38141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38144 \begin_layout Standard
38152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38155 \begin_layout Standard
38163 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38166 \begin_layout Standard
38169 Push the operand into stack
38174 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38177 \begin_layout Standard
38186 <row topline="true">
38187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38190 \begin_layout Standard
38198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38201 \begin_layout Standard
38209 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38212 \begin_layout Standard
38215 Pop the operand from the stack
38220 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38223 \begin_layout Standard
38232 <row topline="true">
38233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38236 \begin_layout Standard
38244 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38247 \begin_layout Standard
38250 IC_LEFT() IC_RESULT()
38255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38258 \begin_layout Standard
38261 Call the function represented by IC_LEFT
38266 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38269 \begin_layout Standard
38272 IC_RESULT = IC_LEFT();
38278 <row topline="true">
38279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38282 \begin_layout Standard
38290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38293 \begin_layout Standard
38296 IC_LEFT() IC_RESULT()
38301 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38304 \begin_layout Standard
38307 Call via function pointer
38312 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38315 \begin_layout Standard
38318 IC_RESULT = (*IC_LEFT)();
38324 <row topline="true">
38325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38328 \begin_layout Standard
38336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38339 \begin_layout Standard
38347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38350 \begin_layout Standard
38353 Return the value in operand IC_LEFT
38358 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38361 \begin_layout Standard
38370 <row topline="true">
38371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38374 \begin_layout Standard
38382 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38385 \begin_layout Standard
38393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38396 \begin_layout Standard
38404 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38407 \begin_layout Standard
38416 <row topline="true">
38417 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38420 \begin_layout Standard
38428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38431 \begin_layout Standard
38439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38442 \begin_layout Standard
38450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38453 \begin_layout Standard
38462 <row topline="true">
38463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38466 \begin_layout Standard
38474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38477 \begin_layout Standard
38480 IC_LEFT() IC_RIGHT() IC_RESULT()
38485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38488 \begin_layout Standard
38496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38499 \begin_layout Standard
38502 IC_RESULT = IC_LEFT + IC_RIGHT
38508 <row topline="true">
38509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38512 \begin_layout Standard
38520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38523 \begin_layout Standard
38526 IC_LEFT() IC_RIGHT() IC_RESULT()
38531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38534 \begin_layout Standard
38542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38545 \begin_layout Standard
38548 IC_RESULT = IC_LEFT - IC_RIGHT
38554 <row topline="true">
38555 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38558 \begin_layout Standard
38566 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38569 \begin_layout Standard
38572 IC_LEFT() IC_RIGHT() IC_RESULT()
38577 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38580 \begin_layout Standard
38588 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38591 \begin_layout Standard
38594 IC_RESULT = IC_LEFT * IC_RIGHT;
38600 <row topline="true">
38601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38604 \begin_layout Standard
38612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38615 \begin_layout Standard
38618 IC_LEFT() IC_RIGHT() IC_RESULT()
38623 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38626 \begin_layout Standard
38634 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38637 \begin_layout Standard
38640 IC_RESULT = IC_LEFT / IC_RIGHT;
38646 <row topline="true">
38647 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38650 \begin_layout Standard
38658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38661 \begin_layout Standard
38664 IC_LEFT() IC_RIGHT() IC_RESULT()
38669 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38672 \begin_layout Standard
38680 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38683 \begin_layout Standard
38686 IC_RESULT = IC_LEFT % IC_RIGHT;
38692 <row topline="true">
38693 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38696 \begin_layout Standard
38704 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38707 \begin_layout Standard
38710 IC_LEFT() IC_RIGHT() IC_RESULT()
38715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38718 \begin_layout Standard
38726 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38729 \begin_layout Standard
38732 IC_RESULT = IC_LEFT < IC_RIGHT;
38738 <row topline="true">
38739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38742 \begin_layout Standard
38750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38753 \begin_layout Standard
38756 IC_LEFT() IC_RIGHT() IC_RESULT()
38761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38764 \begin_layout Standard
38772 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38775 \begin_layout Standard
38778 IC_RESULT = IC_LEFT > IC_RIGHT;
38784 <row topline="true">
38785 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38788 \begin_layout Standard
38796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38799 \begin_layout Standard
38802 IC_LEFT() IC_RIGHT() IC_RESULT()
38807 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38810 \begin_layout Standard
38818 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38821 \begin_layout Standard
38824 IC_RESULT = IC_LEFT == IC_RIGHT;
38830 <row topline="true">
38831 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38834 \begin_layout Standard
38842 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38845 \begin_layout Standard
38848 IC_LEFT() IC_RIGHT() IC_RESULT()
38853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38856 \begin_layout Standard
38859 Logical and operation
38864 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38867 \begin_layout Standard
38870 IC_RESULT = IC_LEFT && IC_RIGHT;
38876 <row topline="true">
38877 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38880 \begin_layout Standard
38888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38891 \begin_layout Standard
38894 IC_LEFT() IC_RIGHT() IC_RESULT()
38899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38902 \begin_layout Standard
38905 Logical or operation
38910 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38913 \begin_layout Standard
38916 IC_RESULT = IC_LEFT || IC_RIGHT;
38922 <row topline="true">
38923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38926 \begin_layout Standard
38934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38937 \begin_layout Standard
38940 IC_LEFT() IC_RIGHT() IC_RESULT()
38945 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38948 \begin_layout Standard
38956 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
38959 \begin_layout Standard
38962 IC_RESULT = IC_LEFT ^ IC_RIGHT;
38968 <row topline="true">
38969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38972 \begin_layout Standard
38980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38983 \begin_layout Standard
38986 IC_LEFT() IC_RIGHT() IC_RESULT()
38991 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
38994 \begin_layout Standard
39002 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39005 \begin_layout Standard
39008 IC_RESULT = IC_LEFT | IC_RIGHT;
39014 <row topline="true">
39015 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39018 \begin_layout Standard
39026 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39029 \begin_layout Standard
39032 IC_LEFT() IC_RIGHT() IC_RESULT()
39037 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39040 \begin_layout Standard
39048 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39051 \begin_layout Standard
39054 IC_RESULT = IC_LEFT & IC_RIGHT;
39060 <row topline="true">
39061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39064 \begin_layout Standard
39072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39075 \begin_layout Standard
39078 IC_LEFT() IC_RIGHT() IC_RESULT()
39083 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39086 \begin_layout Standard
39094 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39097 \begin_layout Standard
39100 IC_RESULT = IC_LEFT << IC_RIGHT
39106 <row topline="true">
39107 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39110 \begin_layout Standard
39118 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39121 \begin_layout Standard
39124 IC_LEFT() IC_RIGHT() IC_RESULT()
39129 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39132 \begin_layout Standard
39140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39143 \begin_layout Standard
39146 IC_RESULT = IC_LEFT >> IC_RIGHT
39152 <row topline="true">
39153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39156 \begin_layout Standard
39166 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39169 \begin_layout Standard
39172 IC_LEFT() IC_RESULT()
39177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39180 \begin_layout Standard
39188 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39191 \begin_layout Standard
39194 IC_RESULT = (*IC_LEFT);
39200 <row topline="true">
39201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39204 \begin_layout Standard
39212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39215 \begin_layout Standard
39218 IC_RIGHT() IC_RESULT()
39223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39226 \begin_layout Standard
39234 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39237 \begin_layout Standard
39240 (*IC_RESULT) = IC_RIGHT;
39246 <row topline="true">
39247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39250 \begin_layout Standard
39258 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39261 \begin_layout Standard
39264 IC_RIGHT() IC_RESULT()
39269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39272 \begin_layout Standard
39280 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39283 \begin_layout Standard
39286 IC_RESULT = IC_RIGHT;
39292 <row topline="true">
39293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39296 \begin_layout Standard
39304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39307 \begin_layout Standard
39310 IC_COND IC_TRUE IC_LABEL
39315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39318 \begin_layout Standard
39322 If true label is present then jump to true label if condition is true else
39323 jump to false label if condition is false
39328 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39331 \begin_layout Standard
39334 if (IC_COND) goto IC_TRUE;
39340 If (!IC_COND) goto IC_FALSE;
39346 <row topline="true">
39347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39350 \begin_layout Standard
39358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39361 \begin_layout Standard
39364 IC_LEFT() IC_RESULT()
39369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39372 \begin_layout Standard
39380 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39383 \begin_layout Standard
39386 IC_RESULT = &IC_LEFT();
39392 <row topline="true">
39393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39396 \begin_layout Standard
39404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39407 \begin_layout Standard
39410 IC_JTCOND IC_JTLABELS
39415 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39418 \begin_layout Standard
39421 Jump to list of labels depending on the value of JTCOND
39426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39429 \begin_layout Standard
39438 <row topline="true">
39439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39442 \begin_layout Standard
39450 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39453 \begin_layout Standard
39456 IC_RIGHT() IC_LEFT() IC_RESULT()
39461 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39464 \begin_layout Standard
39472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39475 \begin_layout Standard
39478 IC_RESULT = (typeof IC_LEFT) IC_RIGHT;
39484 <row topline="true">
39485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39488 \begin_layout Standard
39496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39499 \begin_layout Standard
39507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39510 \begin_layout Standard
39513 This is used for passing parameters in registers;
39515 move IC_LEFT to the next
39516 available parameter register.
39521 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39524 \begin_layout Standard
39533 <row topline="true">
39534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39537 \begin_layout Standard
39545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39548 \begin_layout Standard
39556 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39559 \begin_layout Standard
39562 This is used for receiving parameters passed in registers;
39565 in the next parameter register to IC_RESULT
39570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39573 \begin_layout Standard
39582 <row topline="true" bottomline="true">
39583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39586 \begin_layout Standard
39590 (some more have been added)
39595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39598 \begin_layout Standard
39604 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
39607 \begin_layout Standard
39613 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
39616 \begin_layout Standard
39640 \begin_layout Standard
39641 \begin_inset Note Note
39644 \begin_layout Standard
39645 In the original article Figure II was announced to be downloadable on
39650 ftp://ftp.circuitcellar.com/pub/Circuit_Cellar/2000/121/dutta.ZIP
39658 \begin_layout Paragraph*
39660 \begin_inset LatexCommand \index{iCode}
39667 \begin_layout Standard
39668 This section shows some details of iCode.
39669 The example C code does not do anything useful; it is used as an example
39670 to illustrate the intermediate code generated by the compiler.
39673 \begin_layout Verse
39683 /* This function does nothing useful.
39690 for the purpose of explaining iCode */
39693 short function (data
39702 short i=10; \InsetSpace ~
39704 /* dead initialization eliminated */
39710 /* dead initialization eliminated */
39738 /* compiler detects i,j to be induction
39743 for (i = 0, j = 10 ; i < 10 ; i++, j
39749 \begin_layout Standard
39772 mul += i * 3; \InsetSpace ~
39774 /* this multiplication remains */
39781 j * 3;\InsetSpace ~
39783 /* this multiplication changed to addition */
39797 \begin_layout Standard
39798 In addition to the operands each iCode contains information about the filename
39799 and line it corresponds to in the source file.
39800 The first field in the listing should be interpreted as follows:
39805 Filename(linenumber: iCode Execution sequence number : ICode hash table
39806 key : loop depth of the iCode).
39811 Then follows the human readable form of the ICode operation.
39812 Each operand of this triplet form can be of three basic types a) compiler
39813 generated temporary b) user defined variable c) a constant value.
39814 Note that local variables and parameters are replaced by compiler generated
39817 \begin_inset LatexCommand \index{Live range analysis}
39821 are computed only for temporaries (i.e.
39822 live ranges are not computed for global variables).
39824 \begin_inset LatexCommand \index{Register allocation}
39828 are allocated for temporaries only.
39829 Operands are formatted in the following manner:
39834 Operand Name [lr live-from : live-to ] { type information } [ registers
39840 As mentioned earlier the live ranges are computed in terms of the execution
39841 sequence number of the iCodes, for example
39843 the iTemp0 is live from (i.e.
39844 first defined in iCode with execution sequence number 3, and is last used
39845 in the iCode with sequence number 5).
39846 For induction variables such as iTemp21 the live range computation extends
39847 the lifetime from the start to the end of the loop.
39849 The register allocator
39850 used the live range information to allocate registers, the same registers
39851 may be used for different temporaries if their live ranges do not overlap,
39852 for example r0 is allocated to both iTemp6 and to iTemp17 since their live
39853 ranges do not overlap.
39854 In addition the allocator also takes into consideration the type and usage
39855 of a temporary, for example itemp6 is a pointer to near space and is used
39856 as to fetch data from (i.e.
39857 used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
39858 Some short lived temporaries are allocated to special registers which have
39859 meaning to the code generator e.g.
39860 iTemp13 is allocated to a pseudo register CC which tells the back end that
39861 the temporary is used only for a conditional jump the code generation makes
39862 use of this information to optimize a compare and jump ICode.
39866 \begin_inset LatexCommand \index{Loop optimization}
39870 performed by the compiler.
39871 It can detect induction variables iTemp21(i) and iTemp23(j).
39872 Also note the compiler does selective strength reduction
39873 \begin_inset LatexCommand \index{Strength reduction}
39878 the multiplication of an induction variable in line 18 (gint = j * 3) is
39879 changed to addition, a new temporary iTemp17 is allocated and assigned
39880 a initial value, a constant 3 is then added for each iteration of the loop.
39881 The compiler does not change the multiplication
39882 \begin_inset LatexCommand \index{Multiplication}
39886 in line 17 however since the processor does support an 8 * 8 bit multiplication.
39889 Note the dead code elimination
39890 \begin_inset LatexCommand \index{Dead-code elimination}
39894 optimization eliminated the dead assignments in line 7 & 8 to I and sum
39900 \begin_layout Standard
39903 Sample.c (5:1:0:0) _entry($9) :
39906 \begin_layout Standard
39909 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
39912 \begin_layout Standard
39915 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
39918 \begin_layout Standard
39921 Sample.c(11:4:53:0) preHeaderLbl0($11) :
39924 \begin_layout Standard
39927 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
39931 \begin_layout Standard
39934 Sample.c(11:6:5:1) _whilecontinue_0($1) :
39937 \begin_layout Standard
39940 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
39944 \begin_layout Standard
39947 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
39950 \begin_layout Standard
39953 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
39957 \begin_layout Standard
39960 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
39964 \begin_layout Standard
39967 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
39971 \begin_layout Standard
39974 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
39978 \begin_layout Standard
39981 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
39982 * int}[r0] + 0x2 {short}
39985 \begin_layout Standard
39988 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
39991 \begin_layout Standard
39994 Sample.c(11:17:21:0)_whilebreak_0($3) :
39997 \begin_layout Standard
40000 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
40003 \begin_layout Standard
40006 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
40009 \begin_layout Standard
40012 Sample.c(15:20:54:0)preHeaderLbl1($13) :
40015 \begin_layout Standard
40018 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
40021 \begin_layout Standard
40024 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
40027 \begin_layout Standard
40030 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
40033 \begin_layout Standard
40036 Sample.c(15:24:26:1)_forcond_0($4) :
40039 \begin_layout Standard
40042 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
40046 \begin_layout Standard
40049 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
40052 \begin_layout Standard
40055 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
40056 + ITemp21 [lr21:38]{short}[r4]
40059 \begin_layout Standard
40062 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
40066 \begin_layout Standard
40069 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
40070 + iTemp15 [lr29:30]{short}[r1]
40073 \begin_layout Standard
40076 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
40080 \begin_layout Standard
40083 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
40087 \begin_layout Standard
40090 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
40094 \begin_layout Standard
40097 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
40101 \begin_layout Standard
40104 Sample.c(19:38:47:1) goto _forcond_0($4)
40107 \begin_layout Standard
40110 Sample.c(19:39:48:0)_forbreak_0($7) :
40113 \begin_layout Standard
40116 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
40117 + ITemp11 [lr19:40]{short}[r3]
40120 \begin_layout Standard
40123 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
40126 \begin_layout Standard
40129 Sample.c(20:42:51:0)_return($8) :
40132 \begin_layout Standard
40135 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
40141 Finally the code generated for this function:
40146 \begin_layout Standard
40152 \begin_layout Standard
40158 \begin_layout Standard
40166 \begin_layout Standard
40172 \begin_layout Standard
40180 \begin_layout Standard
40186 \begin_layout Standard
40189 ; ----------------------------------------------
40192 \begin_layout Standard
40195 ; function function
40198 \begin_layout Standard
40201 ; ----------------------------------------------
40204 \begin_layout Standard
40210 \begin_layout Standard
40213 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
40216 \begin_layout Standard
40224 \begin_layout Standard
40227 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
40230 \begin_layout Standard
40238 \begin_layout Standard
40241 ;_whilecontinue_0($1) :
40244 \begin_layout Standard
40250 \begin_layout Standard
40253 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
40256 \begin_layout Standard
40259 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
40262 \begin_layout Standard
40270 \begin_layout Standard
40278 \begin_layout Standard
40286 \begin_layout Standard
40294 \begin_layout Standard
40302 \begin_layout Standard
40310 \begin_layout Standard
40318 \begin_layout Standard
40324 \begin_layout Standard
40327 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
40330 \begin_layout Standard
40338 \begin_layout Standard
40346 \begin_layout Standard
40349 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
40352 \begin_layout Standard
40360 \begin_layout Standard
40368 \begin_layout Standard
40376 \begin_layout Standard
40384 \begin_layout Standard
40392 \begin_layout Standard
40400 \begin_layout Standard
40403 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
40406 \begin_layout Standard
40414 \begin_layout Standard
40422 \begin_layout Standard
40430 \begin_layout Standard
40438 \begin_layout Standard
40446 \begin_layout Standard
40449 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
40452 \begin_layout Standard
40460 \begin_layout Standard
40468 \begin_layout Standard
40476 \begin_layout Standard
40479 ; iTemp6 [lr5:16]{_near * int}[r0] =
40482 \begin_layout Standard
40485 ; iTemp6 [lr5:16]{_near * int}[r0] +
40488 \begin_layout Standard
40494 \begin_layout Standard
40502 \begin_layout Standard
40505 ; goto _whilecontinue_0($1)
40508 \begin_layout Standard
40516 \begin_layout Standard
40519 ; _whilebreak_0($3) :
40522 \begin_layout Standard
40528 \begin_layout Standard
40531 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
40534 \begin_layout Standard
40542 \begin_layout Standard
40545 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
40548 \begin_layout Standard
40556 \begin_layout Standard
40559 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
40562 \begin_layout Standard
40570 \begin_layout Standard
40573 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
40576 \begin_layout Standard
40584 \begin_layout Standard
40592 \begin_layout Standard
40595 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
40598 \begin_layout Standard
40606 \begin_layout Standard
40614 \begin_layout Standard
40620 \begin_layout Standard
40626 \begin_layout Standard
40629 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
40632 \begin_layout Standard
40635 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
40638 \begin_layout Standard
40646 \begin_layout Standard
40654 \begin_layout Standard
40662 \begin_layout Standard
40670 \begin_layout Standard
40678 \begin_layout Standard
40684 \begin_layout Standard
40687 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
40690 \begin_layout Standard
40693 ; iTemp21 [lr21:38]{short}[r4]
40696 \begin_layout Standard
40704 \begin_layout Standard
40712 \begin_layout Standard
40720 \begin_layout Standard
40723 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
40726 \begin_layout Standard
40734 \begin_layout Standard
40742 \begin_layout Standard
40750 \begin_layout Standard
40758 \begin_layout Standard
40761 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
40764 \begin_layout Standard
40767 ; iTemp15 [lr29:30]{short}[r1]
40770 \begin_layout Standard
40778 \begin_layout Standard
40786 \begin_layout Standard
40789 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
40792 \begin_layout Standard
40800 \begin_layout Standard
40808 \begin_layout Standard
40816 \begin_layout Standard
40824 \begin_layout Standard
40832 \begin_layout Standard
40840 \begin_layout Standard
40843 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
40846 \begin_layout Standard
40854 \begin_layout Standard
40862 \begin_layout Standard
40870 \begin_layout Standard
40878 \begin_layout Standard
40886 \begin_layout Standard
40894 \begin_layout Standard
40897 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
40900 \begin_layout Standard
40908 \begin_layout Standard
40911 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
40914 \begin_layout Standard
40922 \begin_layout Standard
40927 cjne r5,#0xff,00104$
40930 \begin_layout Standard
40938 \begin_layout Standard
40941 ; goto _forcond_0($4)
40944 \begin_layout Standard
40952 \begin_layout Standard
40955 ; _forbreak_0($7) :
40958 \begin_layout Standard
40964 \begin_layout Standard
40967 ; ret iTemp24 [lr40:41]{short}
40970 \begin_layout Standard
40978 \begin_layout Standard
40986 \begin_layout Standard
40994 \begin_layout Standard
41000 \begin_layout Standard
41006 \begin_layout Standard
41016 \begin_layout Section
41017 A few words about basic block successors, predecessors and dominators
41020 \begin_layout Standard
41021 Successors are basic blocks
41022 \begin_inset LatexCommand \index{Basic blocks}
41026 that might execute after this basic block.
41028 Predecessors are basic blocks
41029 that might execute before reaching this basic block.
41031 Dominators are basic
41032 blocks that WILL execute before reaching this basic block.
41037 \begin_layout Standard
41041 \begin_layout Standard
41045 \begin_layout Standard
41053 \begin_layout Standard
41057 \begin_layout Standard
41065 \begin_layout Standard
41071 \begin_layout Standard
41072 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
41075 \begin_layout Standard
41076 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
41079 \begin_layout Standard
41080 c) domVect of [BB4] = BB1 ...
41081 here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
41085 \begin_layout Chapter
41089 \begin_layout Standard
41090 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/#Who}
41100 Thanks to all the other volunteer developers who have helped with coding,
41101 testing, web-page creation, distribution sets, etc.
41102 You know who you are :-)
41110 Thanks to Sourceforge
41111 \begin_inset LatexCommand \url{http://www.sf.net}
41115 which has hosted the project since 1999 and donates significant download
41124 Also thanks to all SDCC Distributed Compile Farm members for donating CPU
41125 cycles and bandwidth for snapshot builds.
41130 \begin_layout Standard
41131 This document was initially written by Sandeep Dutta
41134 \begin_layout Standard
41135 All product names mentioned herein may be trademarks
41136 \begin_inset LatexCommand \index{Trademarks}
41140 of their respective companies.
41144 \begin_layout Section*
41148 \begin_layout Standard
41149 To avoid confusion, the installation and building options for SDCC itself
41150 (chapter 2) are not part of the index.
41153 \begin_layout Standard
41154 \begin_inset LatexCommand \printindex{}