\lyxformat 221
\textclass book
\begin_preamble
+
\usepackage[
pdftitle={SDCC Compiler User Guide},
pdfauthor={SDCC development team},
\size normal
-SDCC 2.3.7
+SDCC 2.4.3
\size footnotesize
\newline
Web links to other SDCC related sites can also be found here.
This document can be found in the DOC directory of the source package as
a text or HTML file.
+ A pdf version of this document is available at
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
+
+\end_inset
+
+.
Some of the other tools (simulator and assembler) included with SDCC contain
their own documentation and can be found in the source distribution.
If you want the latest unreleased software, the complete source package
\newline
\family default
-If you can think of some more, please see the chapter
+If you can think of some more, please see the section
\begin_inset LatexCommand \ref{sub:Requesting-Features}
\end_inset
\layout Standard
Of course this doesn't change the search paths compiled into the binaries.
+\newline
+
+\newline
+Moreover the install path can be changed by defining DESTDIR
+\begin_inset LatexCommand \index{DESTDIR}
+
+\end_inset
+
+:
+\layout LyX-Code
+
+make install DESTDIR=$(HOME)/sdcc.rpm/
+\layout Standard
+
+Please note that DESTDIR must have a trailing slash!
\layout Section
Search Paths
\newline
+\newline
+WARNING: Visual studio is very picky with line terminations; it expects
+ the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
+ If you are getting a message such as "This makefile was not generated by
+ Developer Studio etc.
+ etc.
+\begin_inset Quotes srd
+\end_inset
+
+ when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
+ need to convert the Unix style line endings to DOS style line endings.
+ To do so you can use the
+\begin_inset Quotes sld
+\end_inset
+
+unix2dos
+\begin_inset Quotes srd
+\end_inset
+
+ utility freely available on the internet.
+ Doug Hawkins reported in the sdcc-user list that this works:
+\newline
+
+\newline
+C:
+\backslash
+Programming
+\backslash
+SDCC> unix2dos sdcc.dsw
+\newline
+C:
+\backslash
+Programming
+\backslash
+SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
+\newline
+
\newline
In order to build SDCC with MSVC you need win32 executables of bison.exe,
flex.exe, and gawk.exe.
Building the Documentation
\layout Standard
-If the necessary tools (LyX, LaTeX, latex2html) are installed it is as easy
+If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
as changing into the doc directory and typing
\family sans
\series bold
\family default
\series default
there.
- You're invited to make changes and additions to this manual.
+ You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
+x).
Using LyX
\begin_inset LatexCommand \url{www.lyx.org}
\end_inset
as editor this is straightforward.
- If you want to avoid installing the tools you will have some success with
- a bootable Knoppix CD
-\begin_inset LatexCommand \url{http://www.knoppix.net}
-
-\end_inset
-
-.
Prebuilt documentation in html and pdf format is available from
\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
Currently reading the document in pdf format is recommended, as for unknown
reason the hyperlinks are working there whereas in the html version they
- are not.
+ are not
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+If you should know why please drop us a note
+\end_inset
+
+.
+ You'll find the pdf version at
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
+
+\end_inset
+
+.
\newline
This documentation is in some aspects different from a commercial documentation:
currently matches SDCC for mcs51 and DS390 best and does give too few informati
on about f.e.
- Z80, PIC and HC08.
+ Z80, PIC14, PIC16 and HC08.
\layout Itemize
There are many references pointing away from this documentation.
\end_inset
).
- Both formats are documented in the the documentation of srecord
+ Both formats are documented in the documentation of srecord
\begin_inset LatexCommand \index{srecord (tool)}
\end_inset
\layout Itemize
sourcefile.adb
-\begin_inset LatexCommand \index{.adb}
+\begin_inset LatexCommand \index{<file>.adb}
\end_inset
- An intermediate file containing debug information needed to create the
.cdb file (with -
\begin_inset ERT
-status Collapsed
+status Open
\layout Standard
file specified in the command line, since the linkage editor processes
file in the order they are presented to it.
The linker is invoked from SDCC using a script file with extension .lnk
-\begin_inset LatexCommand \index{.lnk}
+\begin_inset LatexCommand \index{<file>.lnk}
\end_inset
for how to create a
\emph on
.lib
-\begin_inset LatexCommand \index{.lib}
+\begin_inset LatexCommand \index{<file>.lib}
\end_inset
libsdcc.lib
\emph default
in the directory <installdir>/share/lib/small.
+\layout Subsection
+
+Using sdcclib to Create and Manage Libraries
+\begin_inset LatexCommand \index{sdcclib}
+
+\end_inset
+
+
+\layout Standard
+
+Alternatively, instead of having a .rel file for each entry on the library
+ file as described in the preceding section, sdcclib can be used to embed
+ all the modules belonging to such library in the library file itself.
+ This results in a larger library file, but it greatly reduces the number
+ of disk files accessed by the linker.
+ Additionally, the packed library file contains an index of all include
+ modules and symbols that significantly speeds up the linking process.
+ To display a list of options supported by sdcclib type:
+\newline
+
+\layout Standard
+
+
+\family sans
+\series bold
+sdcclib -?
+\begin_inset LatexCommand \index{sdcclib}
+
+\end_inset
+
+
+\newline
+
+\newline
+
+\family default
+\series default
+To create a new library file, start by compiling all the required modules.
+ For example:
+\newline
+
+\layout Standard
+
+
+\family sans
+\series bold
+sdcc -c _divsint.c
+\layout Standard
+
+
+\family sans
+\series bold
+sdcc -c _divuint.c
+\layout Standard
+
+
+\family sans
+\series bold
+sdcc -c _modsint.c
+\layout Standard
+
+
+\family sans
+\series bold
+sdcc -c _moduint.c
+\layout Standard
+
+
+\family sans
+\series bold
+sdcc -c _mulint.c
+\newline
+
+\layout Standard
+
+This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
+ and _mulint.rel.
+ The next step is to add the .rel files to the library file:
+\newline
+
+\layout Standard
+
+
+\family sans
+\series bold
+sdcclib libint.lib _divsint.rel
+\family default
+
+\begin_inset LatexCommand \index{sdcclib}
+
+\end_inset
+
+
+\layout Standard
+
+
+\family sans
+\series bold
+sdcclib libint.lib _divuint.rel
+\layout Standard
+
+
+\family sans
+\series bold
+sdcclib libint.lib _modsint.rel
+\layout Standard
+
+
+\family sans
+\series bold
+sdcclib libint.lib _moduint.rel
+\layout Standard
+
+
+\family sans
+\series bold
+sdcclib libint.lib _mulint.rel
+\series default
+
+\newline
+
+\layout Standard
+
+If the file already exists in the library, it will be replaced.
+ To see what modules and symbols are included in the library, options -s
+ and -m are available.
+ For example:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcclib -s libint.lib
+\family default
+
+\begin_inset LatexCommand \index{sdcclib}
+
+\end_inset
+
+
+\newline
+
+\family typewriter
+\series default
+_divsint.rel:
+\layout Standard
+
+
+\family typewriter
+__divsint_a_1_1
+\layout Standard
+
+
+\family typewriter
+__divsint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__divsint
+\newline
+_divuint.rel:
+\layout Standard
+
+
+\family typewriter
+__divuint_a_1_1
+\layout Standard
+
+
+\family typewriter
+__divuint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__divuint_reste_1_1
+\layout Standard
+
+
+\family typewriter
+__divuint_count_1_1
+\layout Standard
+
+
+\family typewriter
+__divuint
+\newline
+_modsint.rel:
+\layout Standard
+
+
+\family typewriter
+__modsint_a_1_1
+\layout Standard
+
+
+\family typewriter
+__modsint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__modsint
+\newline
+_moduint.rel:
+\layout Standard
+
+
+\family typewriter
+__moduint_a_1_1
+\layout Standard
+
+
+\family typewriter
+__moduint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__moduint_count_1_1
+\layout Standard
+
+
+\family typewriter
+__moduint
+\newline
+_mulint.rel:
+\layout Standard
+
+
+\family typewriter
+__mulint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__mulint
+\family default
+\series bold
+
+\newline
+
+\layout Standard
+
+If the source files are compiled using -
+\begin_inset ERT
+status Open
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
+
+\end_inset
+
+, the corresponding debug information file .adb will be include in the library
+ file as well.
+ The library files created with sdcclib are plain text files, so they can
+ be viewed with a text editor.
+ It is not recomended to modify a library file created with sdcclib using
+ a text editor, as there are file indexes numbers located accross the file
+ used by the linker to quickly locate the required module to link.
+ Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
+ it can be safely deleted, since all the information required for linking
+ is embedded in the library file itself.
+ Library files created using sdcclib are used as described in the preceding
+ sections.
\layout Section
Command Line Options
AVR users should probably have a look at avr-gcc
\begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
+\end_inset
+
+ or winavr
+\begin_inset LatexCommand \url{http://winavr.sourceforge.net}
+
\end_inset
.
\end_inset
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
+
+\end_inset
+
+
\layout List
\labelwidthstring 00.00.0000
\end_inset
...
- Pass the preprocessorOption to the preprocessor.
+ Pass the preprocessorOption to the preprocessor
+\family typewriter
+sdcpp
+\family default
+
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
+
+\end_inset
+
+.
+ SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
+ Collection (gcc), if you need more dedicated options please refer to the
+ documentation at
+\begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
+
+\end_inset
+
+.
\layout Subsection
Linker Options
Causes the linker to check if the code memory usage is within limits of
the given value.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-size
+\series default
+\SpecialChar ~
+<Value>
+\begin_inset LatexCommand \index{-\/-stack-size <Value>}
+
+\end_inset
+
+ Causes the linker to check if there is at minimum <Value> bytes for stack.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pack-iram
+\series default
+\SpecialChar ~
+
+\begin_inset LatexCommand \index{-\/-pack-iram}
+
+\end_inset
+
+ Causes the linker use unused register banks for data variables or stack.
\layout Subsection
DS390 / DS400 Options
\layout Subsection
-PIC Options
-\begin_inset LatexCommand \index{Options PIC}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{PIC options}
-
-\end_inset
-
-
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--gen-banksel
-\begin_inset LatexCommand \index{-\/-gen-banksel}
-
-\end_inset
-
-
-\series default
- enable the generation of banksel assembler directives in the PIC16 port.
-\layout Subsection
-
Z80 Options
\begin_inset LatexCommand \index{Options Z80}
\series default
Will not do loop invariant optimizations, this may be turned off for reasons
explained for the previous option.
- For more details of loop optimizations performed see section Loop Invariants.
+ For more details of loop optimizations performed see Loop Invariants in
+ section
+\begin_inset LatexCommand \ref{sub:Loop-Optimizations}
+
+\end_inset
+
+.
It is recommended that this option NOT be used, #pragma\SpecialChar ~
noinvariant
\begin_inset LatexCommand \index{\#pragma noinvariant}
\end_inset
.
- see section Parameters and Local Variables for more details.
+ See section
+\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+ Parameters and Local Variables for more details.
If this option is used all source files in the project should be compiled
with this option.
\series bold
-
\begin_inset ERT
-status Collapsed
+status Open
\layout Standard
\series default
- This option can be used when the code generated is called by a monitor
- program.
- The compiler will generate a 'ret' upon return from the 'main'
+ This option can be used if the code generated is called by a monitor program
+ or if the main routine includes an endless loop.
+ This option might result in slightly smaller code and save two bytes of
+ stack space.
+ The return from the 'main'
\begin_inset LatexCommand \index{main return}
\end_inset
- function.
+ function will return to the function calling main.
The default setting is to lock up i.e.
generate a '
\family typewriter
\series default
Hides your ugly and inefficient c-code from the asm file, so you can always
- blame the compiler :).
+ blame the compiler :)
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-peep-comments
+\begin_inset LatexCommand \index{-\/-no-peep-comments}
+
+\end_inset
+
+
+\series default
+ Will not include peep-hole comments in the generated files.
\layout List
\labelwidthstring 00.00.0000
\end_inset
(or in case of some 8051 variants by a separate Special Function Register,
- see section
+ see section
\begin_inset LatexCommand \ref{sub:MCS51-variants}
\end_inset
The bit addressable memory consists of 128 bits which are located from 0x20
to 0x2f in data memory.
-\layout Standard
-
+\newline
Apart from this 8051 specific storage class most architectures support ANSI-C
bitfields
\begin_inset LatexCommand \index{bitfields}
\end_inset
-
+
\begin_inset Foot
collapsed false
\end_inset
.
+ In accordance with ISO/IEC 9899 bits and bitfields without an explicit
+ signed modifier are implemented as unsigned.
\layout Subsubsection
sfr
\family typewriter
-sfr banked at 0x123 IoPort;
+sfr banked at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x123 IoPort;
\layout Standard
Writing 0x01 to this variable generates the assembly code:
\family default
.
If you include the file z180.h this will be set automatically.
+\layout Subsection
+
+HC08 Storage Class
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ Language Extensions
+\layout Subsubsection
+
+data
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
+
+\end_inset
+
+
+\layout Standard
+
+The data storage class declares a variable that resides in the first 256
+ bytes of memory (the direct page).
+ The HC08 is most efficient at accessing variables (especially pointers)
+ stored here.
+\layout Subsubsection
+
+xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+
+\layout Standard
+
+The xdata storage class declares a variable that can reside anywhere in
+ memory.
+ This is the default if no storage class is specified.
+
\layout Section
Absolute Addressing
\emph on
volatile
\emph default
- should be used to tell the compiler that accesses might not be optimized
+ have to be used to tell the compiler that accesses might not be optimized
away:
\layout Verse
\layout Standard
For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
-r) array starts at a block (256 byte) boundary
+r) array
+\family typewriter
+\size footnotesize
+
+\begin_inset LatexCommand \index{Aligned array}
+
+\end_inset
+
+
+\family default
+\size default
+ starts at a block (256 byte) boundary
\begin_inset LatexCommand \index{block boundary}
\end_inset
-.
+ (section
+\begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
+
+\end_inset
+
+ has an example).
\newline
Absolute addresses can be specified for variables in all storage classes,
e.g.:
\family typewriter
-extern volatile bit SDI;
+extern volatile bit MOSI;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master out, slave in */
\newline
-extern volatile bit SCLK;
+extern volatile bit MISO;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master in, slave out */
\newline
-extern volatile bit CPOL;
+extern volatile bit MCLK;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master clock */
\newline
\newline
-void DS1306_put(unsigned char value)
+/* Input and Output of a byte on a 3-wire serial bus.
\newline
-{
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+If needed adapt polarity of clock, polarity of data and bit order
+\newline
+\SpecialChar ~
+*/
+\newline
+unsigned char spi_io(unsigned char out_byte)
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char mask=0x80;
+unsigned char i=8;
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+do {
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-while(mask)
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+MOSI = out_byte & 0x80;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-{
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out_byte <<= 1;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDI=(value & mask)?1:0;
+MCLK = 1;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SCLK=!CPOL;
+/* _asm nop _endasm; */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* for slow peripherals */
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SCLK=CPOL;
+if(MISO)
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mask/=2;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out_byte += 1;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-}
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+MCLK = 0;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+} while(--i);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return out_byte;
\newline
}
\layout Standard
\family typewriter
-bit at 0x80 SDI;\SpecialChar ~
+bit at 0x80 MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 0, bit 0 */
\newline
-bit at 0x81 SCLK;\SpecialChar ~
+bit at 0x81 MISO;\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 0, bit 1 */
\newline
-bit CPOL;\SpecialChar ~
-\SpecialChar ~
+bit at 0x82 MCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* This is a variable, let the linker allocate this one */
+/* I/O port 0, bit 2 */
\layout Standard
Similarly, for the second hardware you would use
\family typewriter
-bit at 0x83 SDI;\SpecialChar ~
+bit at 0x83 MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 0, bit 3 */
\newline
-bit at 0x91 SCLK;\SpecialChar ~
+bit at 0x91 MISO;\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 1, bit 1 */
\end_inset
- CPOL;\SpecialChar ~
-\SpecialChar ~
+ at 0x92 MCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* This is a variable, let the linker allocate this one */
+/* I/O port 1, bit 2 */
\layout Standard
and you can use the same hardware dependent routine without changes, as
\end_inset
+\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+
\layout Standard
Automatic (local) variables and parameters to functions can either be placed
\end_inset
- either by using the
+ by using the
\emph on
-
\begin_inset ERT
\emph default
- option or by using the
+ option, by using
+\emph on
+#pragma\SpecialChar ~
+stackauto
+\emph default
+
+\begin_inset LatexCommand \index{\#pragma stackauto}
+
+\end_inset
+
+ or by using the
\emph on
reentrant
\begin_inset LatexCommand \index{reentrant}
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-data at 0x31 unsigned char j;
+data at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x31 unsigned char j;
\newline
\SpecialChar ~
\SpecialChar ~
\end_inset
+\layout Subsection
+
+General Information
\layout Standard
SDCC allows
\layout Standard
+Interrupt service routines open the door for some very interesting bugs:
+\newline
+If an interrupt service routine changes variables which are accessed by
+ other functions these variables have to be declared
+\emph on
+volatile
+\emph default
+
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+.
+
+\layout Standard
+
+If the access to these variables is not
+\emph on
+atomic
+\begin_inset LatexCommand \index{atomic access}
+
+\end_inset
+
+
+\emph default
+ (i.e.
+ the processor needs more than one instruction for the access and could
+ be interrupted while accessing the variable) the interrupt must be disabled
+ during the access to avoid inconsistent data.
+ Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
+ and should be protected by disabling interrupts.
+ You're not automatically on the safe side if you use 8 bit variables though.
+ We need an example here: f.e.
+ on the 8051 the harmless looking
+\begin_inset Quotes srd
+\end_inset
+
+
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x80;
+\family default
+
+\begin_inset Quotes sld
+\end_inset
+
+ is not atomic if
+\family typewriter
+flags
+\family default
+ resides in xdata.
+ Setting
+\begin_inset Quotes srd
+\end_inset
+
+
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x40;
+\family default
+
+\begin_inset Quotes sld
+\end_inset
+
+ from within an interrupt routine might get lost if the interrupt occurs
+ at the wrong time.
+
+\begin_inset Quotes sld
+\end_inset
+
+
+\family typewriter
+counter\SpecialChar ~
++=\SpecialChar ~
+8;
+\family default
+
+\begin_inset Quotes srd
+\end_inset
+
+ is not atomic on the 8051 even if
+\family typewriter
+counter
+\family default
+ is located in data memory.
+ Bugs like these are hard to reproduce and can cause a lot of trouble.
+
+\layout Standard
+
+The return address and the registers used in the interrupt service routine
+ are saved on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ so there must be sufficient stack space.
+ If there isn't variables or registers (or even the return address itself)
+ will be corrupted.
+ This
+\emph on
+stack overflow
+\emph default
+
+\begin_inset LatexCommand \index{stack overflow}
+
+\end_inset
+
+ is most likely to happen if the interrupt occurs during the
+\begin_inset Quotes sld
+\end_inset
+
+deepest
+\begin_inset Quotes srd
+\end_inset
+
+ subroutine when the stack is already in use for f.e.
+ many return addresses.
+\layout Standard
+
+A special note here, int (16 bit) and long (32 bit) integer division
+\begin_inset LatexCommand \index{Division}
+
+\end_inset
+
+, multiplication
+\begin_inset LatexCommand \index{Multiplication}
+
+\end_inset
+
+ & modulus
+\begin_inset LatexCommand \index{Modulus}
+
+\end_inset
+
+ and floating-point
+\begin_inset LatexCommand \index{Floating point support}
+
+\end_inset
+
+ operations are implemented using external support routines developed in
+ ANSI-C.
+ If an interrupt service routine needs to do any of these operations then
+ the support routines (as mentioned in a following section) will have to
+ be recompiled using the
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-int-long-reent
+\emph default
+
+\begin_inset LatexCommand \index{-\/-int-long-reent}
+
+\end_inset
+
+ compiler option.
+\layout Standard
+
+Calling other functions from an interrupt service routine is not recommended,
+ avoid it if possible.
+ Note that when some function is called from an interrupt service routine
+ it should be preceded by a #pragma\SpecialChar ~
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+
+ if it is not reentrant.
+ Furthermore nonreentrant functions should not be called from the main program
+ while the interrupt service routine might be active.
+
+\newline
+
+\newline
+Also see section
+\begin_inset LatexCommand \ref{sub:Overlaying}
+
+\end_inset
+
+\SpecialChar ~
+about Overlaying and section
+\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
+
+\end_inset
+
+\SpecialChar ~
+about Functions using private register banks.
+\layout Subsection
+
+MCS51/DS390 Interrupt Service Routines
+\layout Standard
+
Interrupt numbers and the corresponding address & descriptions for the Standard
8051/8052 are listed below.
SDCC will automatically adjust the interrupt vector table to the maximum
\emph on
a, b, dptr
\emph default
- & psw are save and restored, if such an interrupt service routine calls
+ & psw are saved and restored, if such an interrupt service routine calls
another function (using another register bank) then the entire register
bank of the called function will be saved on the stack.
This scheme is recommended for larger interrupt service routines.
+\layout Subsection
+
+HC08 Interrupt Service Routines
\layout Standard
-Interrupt service routines open the door for some very interesting bugs:
-
+Since the number of interrupts available is chip specific and the interrupt
+ vector table always ends at the last byte of memory, the interrupt numbers
+ corresponds to the interrupt vectors in reverse order of address.
+ For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
+ 2 will use the interrupt vector at 0xfffa, and so on.
+ However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
+ this way; instead see section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
+\end_inset
+
+ for details on customizing startup.
+\layout Subsection
+
+Z80 Interrupt Service Routines
\layout Standard
-If the interrupt service routines changes variables which are accessed by
- other functions these variables should be declared
+The Z80 uses several different methods for determining the correct interrupt
+ vector depending on the hardware implementation.
+ Therefore, SDCC ignores the optional interrupt number and does not attempt
+ to generate an interrupt vector table.
+\layout Standard
+
+By default, SDCC generates code for a maskable interrupt, which uses an
+ RETI instruction to return from the interrupt.
+ To write an interrupt handler for the non-maskable interrupt, which needs
+ an RETN instruction instead, add the
\emph on
-volatile
+critical
\emph default
+ keyword:
+\layout Verse
-\begin_inset LatexCommand \index{volatile}
-
-\end_inset
-.
+\family typewriter
+void nmi_isr (void) critical interrupt
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+\newline
+}
+\layout Section
+
+Enabling and Disabling Interrupts
+\layout Subsection
+
+Critical Functions and Critical Statements
\layout Standard
-If the access to these variables is not
+A special keyword may be associated with a block or a function declaring
+ it as
\emph on
-atomic
-\begin_inset LatexCommand \index{atomic access}
-
-\end_inset
-
-
-\emph default
- (i.e.
- the processor needs more than one instruction for the access and could
- be interrupted while accessing the variable) the interrupt must disabled
- during the access to avoid inconsistent data.
- Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
- and should be protected by disabling interrupts.
- You're not automatically on the safe side if you use 8 bit variables though.
- We need an example here: f.e.
- on the 8051 the harmless looking
-\begin_inset Quotes srd
-\end_inset
-
-
-\family typewriter
-flags\SpecialChar ~
-|=\SpecialChar ~
-0x80;
-\family default
-
-\begin_inset Quotes sld
-\end_inset
-
- is not atomic if
-\family typewriter
-flags
-\family default
- resides in xdata.
- Setting
-\begin_inset Quotes srd
-\end_inset
-
-
-\family typewriter
-flags\SpecialChar ~
-|=\SpecialChar ~
-0x40;
-\family default
-
-\begin_inset Quotes sld
-\end_inset
-
- from within an interrupt routine might get lost if the interrupt occurs
- at the wrong time.
-
-\begin_inset Quotes sld
-\end_inset
-
-
-\family typewriter
-counter\SpecialChar ~
-+=\SpecialChar ~
-8;
-\family default
-
-\begin_inset Quotes srd
-\end_inset
-
- is not atomic on the 8051 even if
-\family typewriter
-counter
-\family default
- is located in data memory.
- Bugs like these are hard to reproduce and can cause a lot of trouble.
-
-\layout Standard
-
-A special note here, int (16 bit) and long (32 bit) integer division
-\begin_inset LatexCommand \index{Division}
-
-\end_inset
-
-, multiplication
-\begin_inset LatexCommand \index{Multiplication}
-
-\end_inset
-
- & modulus
-\begin_inset LatexCommand \index{Modulus}
-
-\end_inset
-
- and floating-point
-\begin_inset LatexCommand \index{Floating point support}
-
-\end_inset
-
- operations are implemented using external support routines developed in
- ANSI-C.
- If an interrupt service routine needs to do any of these operations then
- the support routines (as mentioned in a following section) will have to
- be recompiled using the
-\emph on
- -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
-
-\end_inset
-
-
-\emph default
- option and the source file will need to be compiled using the
-\emph on
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--int-long-reent
-\emph default
-
-\begin_inset LatexCommand \index{-\/-int-long-reent}
-
-\end_inset
-
- compiler option.
-\layout Standard
-
-Calling other functions from an interrupt service routine is not recommended,
- avoid it if possible.
- Note that when some function is called from an interrupt service routine
- it should be preceded by a #pragma\SpecialChar ~
-nooverlay
-\begin_inset LatexCommand \index{\#pragma nooverlay}
-
-\end_inset
-
- if it is not reentrant.
- Furthermore nonreentrant functions should not be called from the main program
- while the interrupt service routine might be active.
-
-\newline
-
-\newline
-Also see section
-\begin_inset LatexCommand \ref{sub:Overlaying}
-
-\end_inset
-
-\SpecialChar ~
-about Overlaying and section
-\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
-
-\end_inset
-
-\SpecialChar ~
-about Functions using private register banks.
-\layout Section
-
-Enabling and Disabling Interrupts
-\layout Subsection
-
-Critical Functions and Critical Statements
-\layout Standard
-
-A special keyword may be associated with a function declaring it as
-\emph on
-critical
-\emph default
-.
- SDCC will generate code to disable all interrupts
-\begin_inset LatexCommand \index{interrupt}
+critical
+\emph default
+.
+ SDCC will generate code to disable all interrupts
+\begin_inset LatexCommand \index{interrupt}
\end_inset
On some architectures which don't support interrupt priorities these can
be implemented by manipulating the interrupt mask and reenabling interrupts
within the interrupt routine.
- Don't add complexity unless you have to.
+ Check there is sufficient space on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ and don't add complexity unless you have to.
\layout Section
initialization.
On some mcs51 variants xdata has to be explicitly enabled before it can
be accessed, this is the place to do it.
- See also the compiler option
+ The startup code clears the complete 256 byte of idata memory, this might
+ cause problems for 128 byte devices (endless loop reported for Chipcon
+ CC1010).
+\layout Standard
+
+See also the compiler option
\emph on
-
\begin_inset ERT
\layout Subsection
A Step by Step Introduction
+\begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
+
+\end_inset
+
+
\layout Standard
Starting from a small snippet of c-code this example shows for the MCS51
\family typewriter
\size footnotesize
-unsigned char xdata at 0x7f00 buf[0x100];
+unsigned char far
+\begin_inset LatexCommand \index{far (storage class)}
+
+\end_inset
+
+ at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x7f00 buf[0x100];
+\begin_inset LatexCommand \index{Aligned array}
+
+\end_inset
+
+
\newline
unsigned char head,tail;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-buf[ head++ ] = c;
+buf[ head++ ] = c;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* access to a 256 byte aligned array */
\newline
}
\layout Standard
\SpecialChar ~
cjne a,ar3,00106$
\newline
-ret 00106$:
-\newline
-;buffer.c buf[ head++ ] = c;
-\newline
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov\SpecialChar ~
\SpecialChar ~
-r3,_head
+ret
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-inc\SpecialChar ~
-\SpecialChar ~
-_head
+00106$:
+\newline
+;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
+\begin_inset LatexCommand \index{Aligned array}
+
+\end_inset
+
+
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
-a,r3
+r3,_head
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add\SpecialChar ~
+inc\SpecialChar ~
\SpecialChar ~
-a,#_buf
+_head
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
-dpl,a
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-clr\SpecialChar ~
-\SpecialChar ~
-a
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-addc\SpecialChar ~
-a,#(_buf >> 8)
+dpl,r3
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
-dph,a
+dph,#(_buf >> 8)
\newline
\SpecialChar ~
\SpecialChar ~
The new file buffer.c should compile with only one warning about the unreferenced
function argument 'c'.
Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
- and finally have:
+ (1) and finally have:
\layout Verse
\family typewriter
\size footnotesize
-unsigned char xdata at 0x7f00 buf[0x100];
+unsigned char far at 0x7f00 buf[0x100];
\newline
unsigned char head,tail;
\newline
-#define USE_ASSEMBLY
+#define USE_ASSEMBLY (1)
\newline
\newline
-#ifndef USE_ASSEMBLY
+#if !USE_ASSEMBLY
+\newline
+
\newline
void to_buffer( unsigned char c )
\newline
\family typewriter
printf_fast()
\family default
- which should fit the requirements of many embedded systems.
+ which should fit the requirements of many embedded systems (by unsetting
+ #defines it can be customized to
+\emph on
+not
+\emph default
+ support long variables and field widths).
\layout Subsection
Math functions (sin, pow, sqrt etc.)
\layout Standard
+
+\series bold
+Attention
+\series default
+: this option wasn't maintained for a long time and is quite buggy.
+ Small programs might work.
+ You've been warned!
+\layout Standard
+
The external stack (-
\begin_inset ERT
status Collapsed
\end_inset
-, therefore when using the External Stack option, this port
+ (see also section
+\begin_inset LatexCommand \ref{sub:MCS51-variants}
+
+\end_inset
+
+), therefore when using the External Stack option, this port
\emph on
may not
\emph default
\end_inset
- this will save all current options to the save/restore stack.
- See restore.
+ See #pragma\SpecialChar ~
+restore.
\layout Itemize
restore
saves & restores can be nested.
SDCC uses a save/restore stack: save pushes current options to the stack,
restore pulls current options from the stack.
- See save.
+ See #pragma\SpecialChar ~
+save.
+\newline
+
\layout Itemize
-nogcse
-\begin_inset LatexCommand \index{\#pragma nogcse}
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
\end_inset
- - will stop global common subexpression elimination.
-\layout Itemize
-noinduction
-\begin_inset LatexCommand \index{\#pragma noinduction}
+\begin_inset LatexCommand \index{function prologue}
\end_inset
- - will stop loop induction optimizations.
-\layout Itemize
+ function1[,function2[,function3...]] - The compiler by default uses a caller
+ saves convention for register saving across function calls, however this
+ can cause unnecessary register pushing & popping
+\begin_inset LatexCommand \index{push/pop}
-nojtbound
-\begin_inset LatexCommand \index{\#pragma nojtbound}
+\end_inset
+
+ when calling small functions from larger functions.
+ This option can be used to switch off the register saving convention for
+ the function names specified.
+ The compiler will not save registers when calling these functions, extra
+ code need to be manually inserted at the entry & exit for these functions
+ to save & restore the registers used by these functions, this can SUBSTANTIALLY
+ reduce code & improve run time performance of the generated code.
+ In the future the compiler (with inter procedural analysis) may be able
+ to determine the appropriate scheme to use for each function call.
+ If -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- - will not generate code for boundary value checking, when switch statements
- are turned into jump-tables (dangerous).
- For more details see section
-\begin_inset LatexCommand \ref{sub:'switch'-Statements}
+-callee-saves command line option is used, the function names specified
+ in #pragma\SpecialChar ~
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
\end_inset
-.
+ is appended to the list of functions specified in the command line.
\layout Itemize
-nooverlay
-\begin_inset LatexCommand \index{\#pragma nooverlay}
+exclude
+\begin_inset LatexCommand \index{\#pragma exclude}
\end_inset
- - the compiler will not overlay the parameters and local variables of a
- function.
+ none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
+ of pairs of push/pop
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
+
+ instructions in
+\emph on
+I
+\emph default
+nterrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\emph on
+S
+\emph default
+ervice
+\emph on
+R
+\emph default
+outines.
+ The directive should be placed immediately before the ISR function definition
+ and it affects ALL ISR functions following it.
+ To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
+exclude\SpecialChar ~
+none
+\begin_inset LatexCommand \index{\#pragma exclude}
+
+\end_inset
+
+.
+ See also the related keyword _naked
+\begin_inset LatexCommand \index{\_naked}
+
+\end_inset
+
+.
\layout Itemize
less_pedantic
your own now ;-(
\layout Itemize
-noloopreverse
-\begin_inset LatexCommand \index{\#pragma noloopreverse}
+nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
\end_inset
- - Will not do loop reversal optimization
+ - will stop global common subexpression elimination.
\layout Itemize
-exclude
-\begin_inset LatexCommand \index{\#pragma exclude}
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
\end_inset
- none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
- pair of push/pop
-\begin_inset LatexCommand \index{push/pop}
-
-\end_inset
+ - will stop loop induction optimizations.
+\layout Itemize
- instruction in ISR function (using interrupt
-\begin_inset LatexCommand \index{interrupt}
+noinvariant
+\begin_inset LatexCommand \index{\#pragma noinvariant}
\end_inset
- keyword).
- The directive should be placed immediately before the ISR function definition
- and it affects ALL ISR functions following it.
- To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
-exclude\SpecialChar ~
-none
-\begin_inset LatexCommand \index{\#pragma exclude}
+ - will not do loop invariant optimizations.
+ For more details see Loop Invariants in section
+\begin_inset LatexCommand \ref{sub:Loop-Optimizations}
\end_inset
about interrupts.
\layout Itemize
-callee_saves
-\begin_inset LatexCommand \index{\#pragma callee\_saves}
+nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
+
+\end_inset
+
+ - will not generate code for boundary value checking, when switch statements
+ are turned into jump-tables (dangerous).
+ For more details see section
+\begin_inset LatexCommand \ref{sub:'switch'-Statements}
\end_inset
+.
+\layout Itemize
-\begin_inset LatexCommand \index{function prologue}
+noloopreverse
+\begin_inset LatexCommand \index{\#pragma noloopreverse}
\end_inset
- function1[,function2[,function3...]] - The compiler by default uses a caller
- saves convention for register saving across function calls, however this
- can cause unnecessary register pushing & popping
-\begin_inset LatexCommand \index{push/pop}
+ - Will not do loop reversal optimization
+\layout Itemize
+
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
\end_inset
- when calling small functions from larger functions.
- This option can be used to switch off the register saving convention for
- the function names specified.
- The compiler will not save registers when calling these functions, extra
- code need to be manually inserted at the entry & exit for these functions
- to save & restore the registers used by these functions, this can SUBSTANTIALLY
- reduce code & improve run time performance of the generated code.
- In the future the compiler (with inter procedural analysis) may be able
- to determine the appropriate scheme to use for each function call.
- If -
+ - the compiler will not overlay the parameters and local variables of a
+ function.
+\layout Itemize
+
+stackauto
+\begin_inset LatexCommand \index{\#pragma stackauto}
+
+\end_inset
+
+- See option -
\begin_inset ERT
status Collapsed
/
\end_inset
--callee-saves command line option is used, the function names specified
- in #pragma\SpecialChar ~
-callee_saves
-\begin_inset LatexCommand \index{\#pragma callee\_saves}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
- is appended to the list of functions specified in the command line.
+ and section
+\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+ Parameters and Local Variables.
\layout Standard
SDCPP supports the following #pragma directives:
\end_inset
-\newline
-
\layout Chapter
-Debugging with SDCDB
-\begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
+Notes on supported Processors
+\layout Section
+
+MCS51 variants
+\begin_inset LatexCommand \label{sub:MCS51-variants}
\end_inset
-\begin_inset LatexCommand \index{sdcdb (debugger)}
+\begin_inset LatexCommand \index{MCS51 variants}
\end_inset
+
+\layout Standard
+
+MCS51 processors are available from many vendors and come in many different
+ flavours.
+ While they might differ considerably in respect to Special Function Registers
+ the core MCS51 is usually not modified or is kept compatible.
+\layout Subsection
+
+pdata access by SFR
\layout Standard
-SDCC is distributed with a source level debugger
-\begin_inset LatexCommand \index{Debugger}
+With the upcome of devices with internal xdata and flash memory devices
+ using port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
+
+\end_inset
+
+ as dedicated I/O port is becoming more popular.
+ Switching the high byte for pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ access which was formerly done by port P2 is then achieved by a Special
+ Function Register
+\begin_inset LatexCommand \index{sfr}
\end_inset
.
- The debugger uses a command line interface, the command repertoire of the
- debugger has been kept as close to gdb
-\begin_inset LatexCommand \index{gdb}
+ In well-established MCS51 tradition the address of this
+\emph on
+sfr
+\emph default
+ is where the chip designers decided to put it.
+ Needless to say that they didn't agree on a common name either.
+ So that the startup code can correctly initialize xdata variables, you
+ should define an sfr with the name _XPAGE
+\family typewriter
+
+\begin_inset LatexCommand \index{\_XPAGE (mcs51)}
\end_inset
- (the GNU debugger) as possible.
- The configuration and build process is part of the standard compiler installati
-on, which also builds and installs the debugger in the target directory
- specified during configuration.
- The debugger allows you debug BOTH at the C source and at the ASM source
- level.
- Sdcdb is available on Unix platforms only.
-\layout Section
-Compiling for Debugging
-\layout Standard
+\family default
+ at the appropriate location if the default, port P2, is not used for this.
+ Some examples are:
+\layout Verse
-The \SpecialChar \-
-\SpecialChar \-
-debug option must be specified for all files for which debug information
- is to be generated.
- The complier generates a .adb file for each of these files.
- The linker creates the .cdb file from the .adb files and the address information.
- This .cdb is used by the debugger.
-\layout Section
-How the Debugger Works
-\layout Standard
+\family typewriter
+sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
+\layout Verse
+
+
+\family typewriter
+sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
+\layout Verse
-When the -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
\layout Standard
-\backslash
-/
+For more exotic implementations further customizations may be needed.
+ See section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
\end_inset
--debug option is specified the compiler generates extra symbol information
- some of which are put into the assembler source and some are put into the
- .adb file.
- Then the linker creates the .cdb file from the individual .adb files with
- the address information for the symbols.
- The debugger reads the symbolic information generated by the compiler &
- the address information generated by the linker.
- It uses the SIMULATOR (Daniel's S51) to execute the program, the program
- execution is controlled by the debugger.
- When a command is issued for the debugger, it translates it into appropriate
- commands for the simulator.
-\layout Section
+ for other possibilities.
+\layout Subsection
-Starting the Debugger
+Other Features available by SFR
\layout Standard
-The debugger can be started using the following command line.
- (Assume the file you are debugging has the file name foo).
-\newline
-
-\newline
-
-\family sans
-\series bold
-sdcdb foo
-\newline
+Some MCS51 variants offer features like Double DPTR
+\begin_inset LatexCommand \index{DPTR}
-\family default
-\series default
+\end_inset
-\newline
-The debugger will look for the following files.
-\layout Itemize
+, multiple DPTR, decrementing DPTR, 16x16 Multiply.
+ These are currently not used for the MCS51 port.
+ If you absolutely need them you can fall back to inline assembly or submit
+ a patch to SDCC.
+\layout Section
-foo.c - the source file.
-\layout Itemize
+DS400 port
+\layout Standard
-foo.cdb - the debugger symbol information file.
-\layout Itemize
+The DS80C400 microcontroller has a rich set of peripherals.
+ In its built-in ROM library it includes functions to access some of the
+ features, among them is a TCP stack with IP4 and IP6 support.
+ Library headers (currently in beta status) and other files are provided
+ at
+\size footnotesize
-foo.ihx - the Intel hex format
-\begin_inset LatexCommand \index{Intel hex format}
+\begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
\end_inset
- object file.
+.
+
\layout Section
-Command Line Options.
-\layout Itemize
-
--
-\begin_inset ERT
-status Collapsed
-
+The Z80 and gbz80 port
\layout Standard
-\backslash
-/
-\end_inset
+SDCC can target both the Zilog
+\begin_inset LatexCommand \index{Z80}
--directory=<source file directory> this option can used to specify the directory
- search list.
- The debugger will look into the directory list specified for source, cdb
- & ihx files.
- The items in the directory list must be separated by ':', e.g.
- if the source files can be in the directories /home/src1 and /home/src2,
- the -
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
+ and the Nintendo Gameboy's Z80-like gbz80
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
-\backslash
-/
\end_inset
--directory option should be -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+.
+ The Z80 port is passed through the same
+\emph on
+regressions tests
+\begin_inset LatexCommand \index{Regression test}
-\backslash
-/
\end_inset
--directory=/home/src1:/home/src2.
- Note there can be no spaces in the option.
-
-\layout Itemize
-
--cd <directory> - change to the <directory>.
-\layout Itemize
--fullname - used by GUI front ends.
-\layout Itemize
+\emph default
+ as the MCS51 and DS390 ports, so floating point support, support for long
+ variables and bitfield support is fine.
+ See mailing lists and forums about interrupt routines.
+\layout Standard
--cpu <cpu-type> - this argument is passed to the simulator please see the
- simulator docs for details.
-\layout Itemize
+As always, the code is the authoritative reference - see z80/ralloc.c and
+ z80/gen.c.
+ The stack
+\begin_inset LatexCommand \index{stack}
--X <Clock frequency > this options is passed to the simulator please see
- the simulator docs for details.
-\layout Itemize
+\end_inset
--s <serial port file> passed to simulator see the simulator docs for details.
-\layout Itemize
+ frame is similar to that generated by the IAR Z80 compiler.
+ IX is used as the base pointer, HL and IY are used as a temporary registers,
+ and BC and DE are available for holding variables.
+ Return values
+\begin_inset LatexCommand \index{return value}
--S <serial in,out> passed to simulator see the simulator docs for details.
-\layout Itemize
+\end_inset
--k <port number> passed to simulator see the simulator docs for details.
+ for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
+ bytes).
+ The gbz80 port use the same set of registers for the return values, but
+ in a different order of significance: E (one byte), DE (two bytes), or
+ HLDE (four bytes).
\layout Section
-Debugger Commands.
+The HC08 port
\layout Standard
-As mentioned earlier the command interface for the debugger has been deliberatel
-y kept as close the GNU debugger gdb, as possible.
- This will help the integration with existing graphical user interfaces
- (like ddd, xxgdb or xemacs) existing for the GNU debugger.
- If you use a graphical user interface for the debugger you can skip the
- next sections.
-\layout Subsubsection*
+The port to the Motorola HC08
+\begin_inset LatexCommand \index{HC08}
-break [line | file:line | function | file:function]
-\layout Standard
+\end_inset
-Set breakpoint at specified line or function:
+ family has been added in October 2003, and is still undergoing some basic
+ development.
+ The code generator is complete, but the register allocation is still quite
+ unoptimized.
+ Some of the SDCC's standard C library functions have embedded non-HC08
+ inline assembly and so are not yet usable.
\newline
\newline
-\family sans
-\series bold
-sdcdb>break 100
-\newline
-sdcdb>break foo.c:100
-\newline
-sdcdb>break funcfoo
-\newline
-sdcdb>break foo.c:funcfoo
-\layout Subsubsection*
+\layout Section
-clear [line | file:line | function | file:function ]
+The PIC14 port
\layout Standard
-Clear breakpoint at specified line or function:
-\newline
+The 14bit PIC
+\begin_inset LatexCommand \index{PIC14}
-\newline
+\end_inset
-\family sans
-\series bold
-sdcdb>clear 100
-\newline
-sdcdb>clear foo.c:100
-\newline
-sdcdb>clear funcfoo
-\newline
-sdcdb>clear foo.c:funcfoo
-\layout Subsubsection*
+ port still requires a major effort from the development community.
+ However it can work for very simple code.
+\layout Subsection
-continue
-\layout Standard
+C code and 14bit PIC code page
+\begin_inset LatexCommand \index{code page (pic14)}
-Continue program being debugged, after breakpoint.
-\layout Subsubsection*
+\end_inset
-finish
-\layout Standard
+ and RAM banks
+\begin_inset LatexCommand \index{RAM bank (pic14)}
-Execute till the end of the current function.
-\layout Subsubsection*
+\end_inset
-delete [n]
-\layout Standard
-Delete breakpoint number 'n'.
- If used without any option clear ALL user defined break points.
-\layout Subsubsection*
+\layout Standard
-info [break | stack | frame | registers ]
-\layout Itemize
+The linker organizes allocation for the code page and RAM banks.
+ It does not have intimate knowledge of the code flow.
+ It will put all the code section of a single asm file into a single code
+ page.
+ In order to make use of multiple code pages, separate asm files must be
+ used.
+ The compiler treats all functions of a single C file as being in the same
+ code page unless it is non static.
+ The compiler treats all local variables of a single C file as being in
+ the same RAM bank unless it is an extern.
+\newline
-info break - list all breakpoints
-\layout Itemize
+\newline
+To get the best follow these guide lines:
+\layout Enumerate
-info stack - show the function call stack.
-\layout Itemize
+make local functions static, as non static functions require code page selection
+ overhead.
+\layout Enumerate
-info frame - show information about the current execution frame.
-\layout Itemize
+Make local variables static as extern variables require RAM bank selection
+ overhead.
+\layout Enumerate
-info registers - show content of all registers.
-\layout Subsubsection*
+For devices that have multiple code pages it is more efficient to use the
+ same number of files as pages, i.e.
+ for the 16F877 use 4 separate files and i.e.
+ for the 16F874 use 2 separate files.
+ This way the linker can put the code for each file into different code
+ pages and the compiler can allocate reusable variables more efficiently
+ and there's less page selection overhead.
+ And as for any 8 bit micro (especially for PIC 14 as they have a very simple
+ instruction set) use 'unsigned char' whereever possible instead of 'int'.
+\layout Subsection
-step
+Creating a device include file
\layout Standard
-Step program until it reaches a different source line.
- Note: pressing <return> repeats the last command.
-\layout Subsubsection*
+For generating a device include file use the support perl script inc2h.pl
+ kept in directory support/script.
+\layout Subsection
-next
+Interrupt code
\layout Standard
-Step program, proceeding through subroutine calls.
-\layout Subsubsection*
+For the interrupt function, use the keyword 'interrupt'
+\begin_inset LatexCommand \index{interrupt}
-run
-\layout Standard
+\end_inset
-Start debugged program.
-\layout Subsubsection*
+ with level number of 0 (PIC14 only has 1 interrupt so this number is only
+ there to avoid a syntax error - it ought to be fixed).
+ E.g.:
+\layout Verse
-ptype variable
-\layout Standard
-Print type information of the variable.
-\layout Subsubsection*
+\family typewriter
+void Intr(void) interrupt 0
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+T0IF = 0; /* Clear timer interrupt */
+\newline
+}
+\layout Subsection
-print variable
+Linking and assembling
\layout Standard
-print value of variable.
-\layout Subsubsection*
+For assembling you can use either GPUTILS'
+\begin_inset LatexCommand \index{gputils (pic tools)}
-file filename
-\layout Standard
+\end_inset
-load the given file name.
- Note this is an alternate method of loading file for debugging.
-\layout Subsubsection*
+ gpasm.exe or MPLAB's mpasmwin.exe.
+ GPUTILS is available from
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
-frame
-\layout Standard
-
-print information about current frame.
-\layout Subsubsection*
-
-set srcmode
-\layout Standard
-
-Toggle between C source & assembly source.
-\layout Subsubsection*
-
-! simulator command
-\layout Standard
-
-Send the string following '!' to the simulator, the simulator response is
- displayed.
- Note the debugger does not interpret the command being sent to the simulator,
- so if a command like 'go' is sent the debugger can loose its execution
- context and may display incorrect values.
-\layout Subsubsection*
-
-quit
-\layout Standard
-
-"Watch me now.
- Iam going Down.
- My name is Bobby Brown"
-\layout Section
-
-Interfacing with XEmacs
-\begin_inset LatexCommand \index{XEmacs}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{Emacs}
-
-\end_inset
+\end_inset
.
-\layout Standard
-
-Two files (in emacs lisp) are provided for the interfacing with XEmacs,
- sdcdb.el and sdcdbsrc.el.
- These two files can be found in the $(prefix)/bin directory after the installat
-ion is complete.
- These files need to be loaded into XEmacs for the interface to work.
- This can be done at XEmacs startup time by inserting the following into
- your '.xemacs' file (which can be found in your HOME directory):
+ For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
+ If you use MPLAB and an interrupt function then the linker script file
+ vectors section will need to be enlarged to link with mplink.
\newline
\newline
-
+Here is a
\family typewriter
-(load-file sdcdbsrc.el)
-\family default
-
-\newline
-
-\newline
-.xemacs is a lisp file so the () around the command is REQUIRED.
- The files can also be loaded dynamically while XEmacs is running, set the
- environment variable 'EMACSLOADPATH' to the installation bin directory
- (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
- To start the interface enter the following command:
-\newline
-
-\newline
-
-\family sans
-\series bold
-ESC-x sdcdbsrc
+Makefile
\family default
-\series default
-
-\newline
-
-\newline
-You will prompted to enter the file name to be debugged.
-
-\newline
-
-\newline
-The command line options that are passed to the simulator directly are bound
- to default values in the file sdcdbsrc.el.
- The variables are listed below, these values maybe changed as required.
-\layout Itemize
-
-sdcdbsrc-cpu-type '51
-\layout Itemize
-
-sdcdbsrc-frequency '11059200
-\layout Itemize
-
-sdcdbsrc-serial nil
-\layout Standard
-
-The following is a list of key mapping for the debugger interface.
-\layout Standard
+ using GPUTILS:
+\layout Verse
-\SpecialChar ~
\family typewriter
-
-\newline
-;; Current Listing ::
+.c.o:
\newline
-;;key\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-binding\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-Comment
+sdcc -S -V -mpic14 -p16F877 $<
\newline
-;;---\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-------\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
---------
+gpasm -c $*.asm
\newline
-;;
+
\newline
-;; n\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdb-next-from-src\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SDCDB next command
+$(PRJ).hex: $(OBJS)
\newline
-;; b\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-back-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SDCDB back command
+gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
+\layout Standard
+
+Here is a
+\family typewriter
+Makefile
+\family default
+ using MPLAB:
+\layout Verse
+
+
+\family typewriter
+.c.o:
\newline
-;; c\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-cont-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SDCDB continue command
+sdcc -S -V -mpic14 -p16F877 $<
\newline
-;; s\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-step-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SDCDB step command
+mpasmwin /q /o $*.asm
+\newline
+
+\newline
+$(PRJ).hex: $(OBJS)
\newline
-;; ?\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-whatis-c-sexp\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
+\layout Standard
+
+Please note that indentations within a
+\family typewriter
+ Makefile
+\family default
+ have to be done with a tabulator character.
+\layout Section
+
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port
+\layout Standard
+
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port is the portion of SDCC that is responsible to produce code for the
+ Microchip
+\begin_inset LatexCommand \index{Microchip}
+
+\end_inset
+
+(TM) microcontrollers with 16 bit core.
+ Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
+\layout Subsection
+
+Global Options
+\layout Standard
+
+PIC16 port supports the standard command line arguments as supposed, with
+ the exception of certain cases that will be mentioned in the following
+ list:
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto Auto variables that are function parameters, will be saved on
+ stack by default.
+
+\emph on
+There is no need to specify this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-float-reent All floating point functions are reentrant by default.
+
+\emph on
+There is no need to specifiy this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-callee-saves See -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-all-callee-saves
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-all-callee-saves All function arguments are passed on stack by default.
+
+\emph on
+There is no need to specify this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-fommit-frame-pointer Frame pointer will be omitted when the function uses
+ no local variables.
+\layout Subsection
+
+Port Specific Options
+\begin_inset LatexCommand \index{Options PIC16}
+
+\end_inset
+
+
+\layout Standard
+
+The port specific options appear after the global options in the sdcc --help
+ output.
+\layout Subsubsection
+
+General Options
+\layout Standard
+
+General options enable certain port features and optimizations.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pgen-bank Instructs the port to insert BANKSEL directives before instructions
+ that use the Bank Select Register (BSR).
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pomit-config-words Instructs the port to omit the generation of the configurati
+on words.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pomit-ivt Instructs the port to omit the generation of the interrupt vectors
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pleave-reset-vector Used in conjuction with the previous command, instructs
+ the port NOT to omit the reset vector.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-model=[model] Used in conjuction with the command above.
+ Defines the stack model to be used, valid stack models are :
+\begin_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\emph on
+small
+\emph default
+ Selects small stack model.
+ 8 bit stack and frame pointers.
+ Supports 256 bytes stack size.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\emph on
+large
+\emph default
+ Selects large stack model.
+ 16 bit stack and frame pointers.
+ Supports 65536 bytes stack size.
+\end_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-preplace-udata-with=[kword] Replaces the default udata keyword for allocating
+ unitialized data variables with [kword].
+ Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
+ Useful for bootloaders.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-asm= sets the full path and name of an external assembler to call.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-link= sets the full path and name of an external linker to call.
+\layout Subsubsection
+
+Debugging Options
+\layout Standard
+
+Debugging options enable extra debugging information in the output files.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug-xtra Similar to -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
+
+\end_inset
+
+, but dumps more information.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug-ralloc Force register allocator to dump <source>.d file with debugging
+ information.
+ <source> is the name of the file compiled.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pcode-verbose Enable pcode debugging information in translation.
+\layout Subsection
+
+Preprocessor Macros
+\layout Standard
+
+PIC16 port defines the following preprocessor macros while translating a
+ source.
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Macro
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+pic18fxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+MCU Identification.
+
+\emph on
+xxxx
+\emph default
+ is the microcontrol identification number, i.e.
+ 452, 6620, etc
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Directories
+\layout Standard
+
+PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port uses the following directories for searching header files and libraries.
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="4">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Directory
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Target
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Command prefix
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PREFIX/sdcc/include/pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC16 specific headers
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Compiler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-I
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PREFIX/sdcc/lib/pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC16 specific libraries
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Linker
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-L
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Pragmas
+\begin_inset LatexCommand \label{sub:PIC16_Pragmas}
+
+\end_inset
+
+
+\layout Standard
+
+PIC16 port currently supports the following pragmas:
+\layout List
+\labelwidthstring 00.00.0000
+
+stack pragma stack forces the code generator to initialize the stack & frame
+ pointers at a specific address.
+ This is an adhoc solution since gplink does not support yet stack.
+ When the gplink issue is resolved the pragma will be deprecated
+\begin_inset Foot
+collapsed true
+
+\layout Standard
+
+
+\emph on
+It is important to initialize the stack, otherwise strange things can happen.
+ Stack is not initialized by default because there are some sources that
+ do not require it.
+ (like library sources)
+\end_inset
+
+.
+\newline
+The stack pragma should be used only once in a project.
+ Multiple pragmas may result in indeterminate behaviour of the program.
+\layout LyX-Code
+
+Example:
+\layout LyX-Code
+
+\layout LyX-Code
+
+/* initializes stack at RAM address 0x5ff */
+\layout LyX-Code
+
+#pragma stack 0x5ff
+\layout List
+\labelwidthstring 00.00.0000
+
+udata pragma udata instructs the compiler to emit code so that linker will
+ place a variable at a specific memory bank
+\layout LyX-Code
+
+Example:
+\layout LyX-Code
+
+\layout LyX-Code
+
+/* places variable foo at bank2 */
+\layout LyX-Code
+
+#pragma udata bank2 foo
+\layout LyX-Code
+
+char foo;
+\layout Standard
+
+In order for this pragma to work there are some changes that must be made
+ in the .lkr script used in link stage.
+ In the following example a sample .lkr file is shown:
+\layout LyX-Code
+
+\layout LyX-Code
+
+// Sample linker script for the PIC18F452 processor
+\layout LyX-Code
+
+LIBPATH .
+\layout LyX-Code
+
+CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED
+\layout LyX-Code
+
+CODEPAGE NAME=page START=0x2A END=0x7FFF
+\layout LyX-Code
+
+CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED
+\layout LyX-Code
+
+CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED
+\layout LyX-Code
+
+CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED
+\layout LyX-Code
+
+CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED
+\layout LyX-Code
+
+ACCESSBANK NAME=accessram START=0x0 END=0x7F
+\layout LyX-Code
+
+\layout LyX-Code
+
+DATABANK NAME=gpr0 START=0x80 END=0xFF
+\layout LyX-Code
+
+DATABANK NAME=gpr1 START=0x100 END=0x1FF
+\layout LyX-Code
+
+DATABANK NAME=gpr2 START=0x200 END=0x2FF
+\layout LyX-Code
+
+DATABANK NAME=gpr3 START=0x300 END=0x3FF
+\layout LyX-Code
+
+DATABANK NAME=gpr4 START=0x400 END=0x4FF
+\layout LyX-Code
+
+DATABANK NAME=gpr5 START=0x500 END=0x5FF
+\layout LyX-Code
+
+ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED
+\layout LyX-Code
+
+\layout LyX-Code
+
+SECTION NAME=CONFIG ROM=config
+\layout LyX-Code
+
+\layout LyX-Code
+
+SECTION NAME=bank0 RAM=gpr0
+\layout LyX-Code
+
+SECTION NAME=bank1 RAM=gpr1
+\layout LyX-Code
+
+SECTION NAME=bank2 RAM=gpr2
+\layout LyX-Code
+
+SECTION NAME=bank3 RAM=gpr3
+\layout LyX-Code
+
+SECTION NAME=bank4 RAM=gpr4
+\layout LyX-Code
+
+SECTION NAME=bank5 RAM=gpr5
+\layout Standard
+
+The linker will recognise the section name set in the pragma statement and
+ will position the variable at the memory bank set with the RAM field at
+ the SECTION line in the linker script file.
+\layout Subsection
+
+Header Files
+\begin_inset LatexCommand \label{sub:PIC16_Header-Files}
+
+\end_inset
+
+
+\layout Standard
+
+There is one main header file that can be included to the source files using
+ the pic16 port.
+ That file is the
+\series bold
+pic18fregs.h
+\series default
+.
+ This header file contains the definitions for the processor special registers,
+ so it is necessary if the source accesses them.
+ It can be included by adding the following line in the beginning of the
+ file:
+\layout LyX-Code
+
+#include <pic18fregs.h>
+\layout Standard
+
+The specific microcontroller is selected within the pic18fregs.h automatically,
+ so the same source can be used with a variety of devices.
+\layout Subsection
+
+Libraries
+\layout Standard
+
+The libraries that PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port depends on are the microcontroller device libraries which contain
+ the symbol definitions for the microcontroller special function registers.
+ These libraries have the format pic18fxxxx.lib, where
+\emph on
+xxxx
+\emph default
+ is the microcontroller identification number.
+ The specific library is selected automatically by the compiler at link
+ stage according to the selected device.
+\layout Standard
+
+Libraries are created with gplib which is part of the gputils package
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net}
+
+\end_inset
+
+.
+\layout Subsection
+
+Memory Models
+\layout Standard
+
+The following memory models are supported by the PIC16 port:
+\layout Itemize
+
+small model
+\layout Itemize
+
+large model
+\layout Standard
+
+Memory model affects the default size of pointers within the source.
+ The sizes are shown in the next table:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Pointer sizes according to memory model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+small model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+large model
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+code pointers
+\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+24-bits
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+data pointers
+\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+It is advisable that all sources within a project are compiled with the
+ same memory model.
+ If one wants to override the default memory model, this can be done by
+ declaring a pointer as
+\series bold
+far
+\series default
+ or
+\series bold
+near
+\series default
+.
+ Far selects large memory model's pointers, while near selects small memory
+ model's pointers.
+\layout Standard
+
+The standard device libraries (see
+\begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
+
+\end_inset
+
+) contain no reference to pointers, so they can be used with both memory
+ models.
+\layout Subsection
+
+Stack
+\layout Standard
+
+The stack implementation for the PIC16 port uses two indirect registers,
+ FSR1 and FSR2.
+\layout List
+\labelwidthstring 00.00.0000
+
+FSR1 is assigned as stack pointer
+\layout List
+\labelwidthstring 00.00.0000
+
+FSR2 is assigned as frame pointer
+\layout Standard
+
+The following stack models are supported by the PIC16 port
+\layout Itemize
+
+small model
+\layout Itemize
+
+large model
+\layout Standard
+
+
+\noun on
+Small
+\noun default
+ model means that only the FSRxL byte is used to access stack and frame,
+ while
+\emph on
+\noun on
+large
+\emph default
+\noun default
+ uses both FSRxL and FSRxH registers.
+ The following table shows the stack/frame pointers sizes according to stack
+ model and the maximum space they can address:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Stack & Frame pointer sizes according to stack model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+small
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+large
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Stack pointer FSR1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Frame pointer FSR2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Standard
+
+
+\series bold
+Currently stack and frame pointers should be initialized explicit by the
+ user at the desired Data RAM position (see
+\begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
+
+\end_inset
+
+ Pragma stack).
+ Uninitialized stack and frame pointers can result in unexpected behavior
+ of the resulting binary.
+\layout Subsection
+
+Function return values
+\layout Standard
+
+Return values from functions are placed to the appropriate registers following
+ a modified Microchip policy optimized for SDCC.
+ The following table shows these registers:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+size
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+destination register
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+WREG
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PRODL:WREG
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+24 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PRODH:PRODL:WREG
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+32 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+FSR0L:PRODH:PRODL:WREG
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+>32 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+on stack, FSR0 points to the beginning
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Interrupts
+\layout Standard
+
+When entering an interrupt, currently the PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port automatically saves the following registers:
+\layout Itemize
+
+WREG
+\layout Itemize
+
+STATUS
+\layout Itemize
+
+BSR
+\layout Itemize
+
+PROD (PRODL and PRODH)
+\layout Itemize
+
+FSR0 (FSR0L and FSR0H)
+\layout Standard
+
+These registers are restored upon return from the interrupt routine.
+
+\layout Standard
+
+When entering a high priority interrupt WREG, STATUS and BSR are not explicit
+ saved by software.
+ The hardware shadow registers for WREG, STATUS and BSR are used in these
+ cases.
+\layout Standard
+
+
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+NOTE that when the _naked attribute is specified for an interrupt routine,
+ then NO registers are stored or restored.
+\end_inset
+
+.
+\layout Chapter
+
+Debugging with SDCDB
+\begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC is distributed with a source level debugger
+\begin_inset LatexCommand \index{Debugger}
+
+\end_inset
+
+.
+ The debugger uses a command line interface, the command repertoire of the
+ debugger has been kept as close to gdb
+\begin_inset LatexCommand \index{gdb}
+
+\end_inset
+
+ (the GNU debugger) as possible.
+ The configuration and build process is part of the standard compiler installati
+on, which also builds and installs the debugger in the target directory
+ specified during configuration.
+ The debugger allows you debug BOTH at the C source and at the ASM source
+ level.
+ Sdcdb is available on Unix platforms only.
+\layout Section
+
+Compiling for Debugging
+\layout Standard
+
+The -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
+
+\end_inset
+
+ option must be specified for all files for which debug information is to
+ be generated.
+ The complier generates a .adb file for each of these files.
+ The linker creates the .cdb
+\begin_inset LatexCommand \index{<file>.cdb}
+
+\end_inset
+
+ file from the .adb
+\begin_inset LatexCommand \index{<file>.adb}
+
+\end_inset
+
+ files and the address information.
+ This .cdb is used by the debugger.
+\layout Section
+
+How the Debugger Works
+\layout Standard
+
+When the -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug option is specified the compiler generates extra symbol information
+ some of which are put into the assembler source and some are put into the
+ .adb file.
+ Then the linker creates the .cdb file from the individual .adb files with
+ the address information for the symbols.
+ The debugger reads the symbolic information generated by the compiler &
+ the address information generated by the linker.
+ It uses the SIMULATOR (Daniel's S51) to execute the program, the program
+ execution is controlled by the debugger.
+ When a command is issued for the debugger, it translates it into appropriate
+ commands for the simulator.
+\layout Section
+
+Starting the Debugger
+\layout Standard
+
+The debugger can be started using the following command line.
+ (Assume the file you are debugging has the file name foo).
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcdb foo
+\newline
+
+\family default
+\series default
+
+\newline
+The debugger will look for the following files.
+\layout Itemize
+
+foo.c - the source file.
+\layout Itemize
+
+foo.cdb - the debugger symbol information file.
+\layout Itemize
+
+foo.ihx - the Intel hex format
+\begin_inset LatexCommand \index{Intel hex format}
+
+\end_inset
+
+ object file.
+\layout Section
+
+Command Line Options.
+\layout Itemize
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-directory=<source file directory> this option can used to specify the directory
+ search list.
+ The debugger will look into the directory list specified for source, cdb
+ & ihx files.
+ The items in the directory list must be separated by ':', e.g.
+ if the source files can be in the directories /home/src1 and /home/src2,
+ the -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-directory option should be -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-directory=/home/src1:/home/src2.
+ Note there can be no spaces in the option.
+
+\layout Itemize
+
+-cd <directory> - change to the <directory>.
+\layout Itemize
+
+-fullname - used by GUI front ends.
+\layout Itemize
+
+-cpu <cpu-type> - this argument is passed to the simulator please see the
+ simulator docs for details.
+\layout Itemize
+
+-X <Clock frequency > this options is passed to the simulator please see
+ the simulator docs for details.
+\layout Itemize
+
+-s <serial port file> passed to simulator see the simulator docs for details.
+\layout Itemize
+
+-S <serial in,out> passed to simulator see the simulator docs for details.
+\layout Itemize
+
+-k <port number> passed to simulator see the simulator docs for details.
+\layout Section
+
+Debugger Commands.
+\layout Standard
+
+As mentioned earlier the command interface for the debugger has been deliberatel
+y kept as close the GNU debugger gdb, as possible.
+ This will help the integration with existing graphical user interfaces
+ (like ddd, xxgdb or xemacs) existing for the GNU debugger.
+ If you use a graphical user interface for the debugger you can skip the
+ next sections.
+\layout Subsubsection*
+
+break [line | file:line | function | file:function]
+\layout Standard
+
+Set breakpoint at specified line or function:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcdb>break 100
+\newline
+sdcdb>break foo.c:100
+\newline
+sdcdb>break funcfoo
+\newline
+sdcdb>break foo.c:funcfoo
+\layout Subsubsection*
+
+clear [line | file:line | function | file:function ]
+\layout Standard
+
+Clear breakpoint at specified line or function:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcdb>clear 100
+\newline
+sdcdb>clear foo.c:100
+\newline
+sdcdb>clear funcfoo
+\newline
+sdcdb>clear foo.c:funcfoo
+\layout Subsubsection*
+
+continue
+\layout Standard
+
+Continue program being debugged, after breakpoint.
+\layout Subsubsection*
+
+finish
+\layout Standard
+
+Execute till the end of the current function.
+\layout Subsubsection*
+
+delete [n]
+\layout Standard
+
+Delete breakpoint number 'n'.
+ If used without any option clear ALL user defined break points.
+\layout Subsubsection*
+
+info [break | stack | frame | registers ]
+\layout Itemize
+
+info break - list all breakpoints
+\layout Itemize
+
+info stack - show the function call stack.
+\layout Itemize
+
+info frame - show information about the current execution frame.
+\layout Itemize
+
+info registers - show content of all registers.
+\layout Subsubsection*
+
+step
+\layout Standard
+
+Step program until it reaches a different source line.
+ Note: pressing <return> repeats the last command.
+\layout Subsubsection*
+
+next
+\layout Standard
+
+Step program, proceeding through subroutine calls.
+\layout Subsubsection*
+
+run
+\layout Standard
+
+Start debugged program.
+\layout Subsubsection*
+
+ptype variable
+\layout Standard
+
+Print type information of the variable.
+\layout Subsubsection*
+
+print variable
+\layout Standard
+
+print value of variable.
+\layout Subsubsection*
+
+file filename
+\layout Standard
+
+load the given file name.
+ Note this is an alternate method of loading file for debugging.
+\layout Subsubsection*
+
+frame
+\layout Standard
+
+print information about current frame.
+\layout Subsubsection*
+
+set srcmode
+\layout Standard
+
+Toggle between C source & assembly source.
+\layout Subsubsection*
+
+! simulator command
+\layout Standard
+
+Send the string following '!' to the simulator, the simulator response is
+ displayed.
+ Note the debugger does not interpret the command being sent to the simulator,
+ so if a command like 'go' is sent the debugger can loose its execution
+ context and may display incorrect values.
+\layout Subsubsection*
+
+quit
+\layout Standard
+
+"Watch me now.
+ Iam going Down.
+ My name is Bobby Brown"
+\layout Section
+
+Interfacing with XEmacs
+\begin_inset LatexCommand \index{XEmacs}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Emacs}
+
+\end_inset
+
+.
+\layout Standard
+
+Two files (in emacs lisp) are provided for the interfacing with XEmacs,
+ sdcdb.el and sdcdbsrc.el.
+ These two files can be found in the $(prefix)/bin directory after the installat
+ion is complete.
+ These files need to be loaded into XEmacs for the interface to work.
+ This can be done at XEmacs startup time by inserting the following into
+ your '.xemacs' file (which can be found in your HOME directory):
+\newline
+
+\newline
+
+\family typewriter
+(load-file sdcdbsrc.el)
+\family default
+
+\newline
+
+\newline
+.xemacs is a lisp file so the () around the command is REQUIRED.
+ The files can also be loaded dynamically while XEmacs is running, set the
+ environment variable 'EMACSLOADPATH' to the installation bin directory
+ (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
+ To start the interface enter the following command:
+\newline
+
+\newline
+
+\family sans
+\series bold
+ESC-x sdcdbsrc
+\family default
+\series default
+
+\newline
+
+\newline
+You will prompted to enter the file name to be debugged.
+
+\newline
+
+\newline
+The command line options that are passed to the simulator directly are bound
+ to default values in the file sdcdbsrc.el.
+ The variables are listed below, these values maybe changed as required.
+\layout Itemize
+
+sdcdbsrc-cpu-type '51
+\layout Itemize
+
+sdcdbsrc-frequency '11059200
+\layout Itemize
+
+sdcdbsrc-serial nil
+\layout Standard
+
+The following is a list of key mapping for the debugger interface.
+\layout Standard
+
+\SpecialChar ~
+
+\family typewriter
+
+\newline
+;;\SpecialChar ~
+Current Listing ::
+\newline
+;;key\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+binding\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Comment
+\newline
+;;---\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+-------\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+-------
+\newline
+;;
+\newline
+;;\SpecialChar ~
+n\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcdb-next-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB next command
+\newline
+;;\SpecialChar ~
+b\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcdb-back-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB back command
+\newline
+;;\SpecialChar ~
+c\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcdb-cont-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB continue command
+\newline
+;;\SpecialChar ~
+s\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcdb-step-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB step command
+\newline
+;;\SpecialChar ~
+?\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcdb-whatis-c-sexp\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- buffer point
+\SpecialChar ~
+buffer point
\newline
-;; x\SpecialChar ~
+;;\SpecialChar ~
+x\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-delete\SpecialChar ~
+\SpecialChar ~
+sdcdbsrc-delete\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+\SpecialChar ~
given or delete arg (C-u arg x)
\newline
-;; m\SpecialChar ~
+;;\SpecialChar ~
+m\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-frame\SpecialChar ~
+sdcdbsrc-frame\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
buffer point
\newline
-;; !\SpecialChar ~
+;;\SpecialChar ~
+!\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-goto-sdcdb\SpecialChar ~
+sdcdbsrc-goto-sdcdb\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
Goto the SDCDB output buffer
\newline
-;; p\SpecialChar ~
+;;\SpecialChar ~
+p\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-print-c-sexp\SpecialChar ~
+sdcdb-print-c-sexp\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- buffer point
+\SpecialChar ~
+buffer point
\newline
-;; g\SpecialChar ~
+;;\SpecialChar ~
+g\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-goto-sdcdb\SpecialChar ~
+sdcdbsrc-goto-sdcdb\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
Goto the SDCDB output buffer
\newline
-;; t\SpecialChar ~
+;;\SpecialChar ~
+t\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-mode\SpecialChar ~
+sdcdbsrc-mode\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\newline
;;
\newline
-;; C-c C-f\SpecialChar ~
+;;\SpecialChar ~
+C-c\SpecialChar ~
+C-f\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-finish-from-src\SpecialChar ~
+sdcdb-finish-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\newline
;;
\newline
-;; C-x SPC\SpecialChar ~
+;;\SpecialChar ~
+C-x\SpecialChar ~
+SPC\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-break\SpecialChar ~
+sdcdb-break\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
Set break for line with point
\newline
-;; ESC t\SpecialChar ~
+;;\SpecialChar ~
+ESC\SpecialChar ~
+t\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-mode\SpecialChar ~
+sdcdbsrc-mode\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
Toggle Sdcdbsrc mode
\newline
-;; ESC m\SpecialChar ~
+;;\SpecialChar ~
+ESC\SpecialChar ~
+m\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-srcmode\SpecialChar ~
+sdcdbsrc-srcmode\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- Toggle list mode
+\SpecialChar ~
+Toggle list mode
\newline
;;
\newline
promoted to 'signed int' before doing any operation.
This promotion can be omitted, if the result is the same.
The effect of the promotion rules together with the sign-extension is often
- supprising:
+ surprising:
\begin_deeper
\layout Verse
or are using an array index.
\layout Itemize
-NEVER jump into a LOOP.
-\layout Itemize
-
-Declare the variables to be local
-\begin_inset LatexCommand \index{local variables}
-
-\end_inset
-
- whenever possible, especially loop control variables (induction).
-\layout Itemize
-
-Since the compiler does not always do implicit integral promotion, the programme
-r should do an explicit cast when integral promotion is required.
-\layout Itemize
-
-Reducing the size of division, multiplication & modulus operations can reduce
- code size substantially.
- Take the following code for example.
-\begin_deeper
-\layout Verse
-
-
-\family typewriter
-foobar(unsigned int p1, unsigned char ch)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-unsigned char ch1 = p1 % ch ;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-....
-\newline
-}
-\layout Standard
-
-For the modulus operation the variable ch will be promoted to unsigned int
- first then the modulus operation will be performed (this will lead to a
- call to support routine _moduint()), and the result will be casted to a
- char.
- If the code is changed to
-\layout Verse
-
-
-\family typewriter
-foobar(unsigned int p1, unsigned char ch)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-unsigned char ch1 = (unsigned char)p1 % ch ;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-....
-\newline
-}
-\layout Standard
-
-It would substantially reduce the code generated (future versions of the
- compiler will be smart enough to detect such optimization opportunities).
-\end_deeper
-\layout Itemize
-
-Have a look at the assembly listing to get a
-\begin_inset Quotes sld
-\end_inset
-
-feeling
-\begin_inset Quotes srd
-\end_inset
-
- for the code generation.
-\layout Section
-
-Tools
-\begin_inset LatexCommand \index{Tools}
-
-\end_inset
-
- included in the distribution
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="12" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Name
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Purpose
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Directory
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-uCsim
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Simulator for various architectures
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/sim/ucsim
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-keil2sdcc.pl
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-header file conversion
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/support/scripts
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-mh2h.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-header file conversion
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/support/scripts
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-as-gbz80
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+NEVER jump into a LOOP.
+\layout Itemize
-\layout Standard
+Declare the variables to be local
+\begin_inset LatexCommand \index{local variables}
-Assembler
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+ whenever possible, especially loop control variables (induction).
+\layout Itemize
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Since the compiler does not always do implicit integral promotion, the programme
+r should do an explicit cast when integral promotion is required.
+\layout Itemize
-\layout Standard
+Reducing the size of division, multiplication & modulus operations can reduce
+ code size substantially.
+ Take the following code for example.
+\begin_deeper
+\layout Verse
-as-z80
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+foobar(unsigned int p1, unsigned char ch)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+unsigned char ch1 = p1 % ch ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....
+\newline
+}
\layout Standard
-Assembler
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+For the modulus operation the variable ch will be promoted to unsigned int
+ first then the modulus operation will be performed (this will lead to a
+ call to support routine _moduint()), and the result will be casted to a
+ char.
+ If the code is changed to
+\layout Verse
+
+\family typewriter
+foobar(unsigned int p1, unsigned char ch)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+unsigned char ch1 = (unsigned char)p1 % ch ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....
+\newline
+}
\layout Standard
+It would substantially reduce the code generated (future versions of the
+ compiler will be smart enough to detect such optimization opportunities).
+\end_deeper
+\layout Itemize
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+Have a look at the assembly listing to get a
+\begin_inset Quotes sld
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-asx8051
+feeling
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ for the code generation.
+\layout Section
+
+Tools
+\begin_inset LatexCommand \index{Tools}
-Assembler
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+ included in the distribution
\layout Standard
+\align center
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
-\end_inset
-</cell>
-</row>
-<row topline="true">
+\begin_inset Tabular
+<lyxtabular version="3" rows="12" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-sdcdb
+Name
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Simulator
+Purpose
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+Directory
\end_inset
</cell>
</row>
\layout Standard
-aslink
+uCsim
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Linker
+Simulator for various architectures
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+sdcc/sim/ucsim
\end_inset
</cell>
</row>
\layout Standard
-link-z80
+keil2sdcc.pl
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Linker
+header file conversion
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+sdcc/support/scripts
\end_inset
</cell>
</row>
\layout Standard
-link-gbz80
+mh2h.c
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Linker
+header file conversion
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+sdcc/support/scripts
\end_inset
</cell>
</row>
-<row topline="true" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-packihx
+as-gbz80
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-ihx packer
+Assembler
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\end_inset
</cell>
</row>
-</lyxtabular>
-
-\end_inset
-
-
-\newline
-
-\layout Section
-
-Documentation
-\begin_inset LatexCommand \index{Documentation}
-
-\end_inset
-
- included in the distribution
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="10" columns="2">
-<features>
-<column alignment="left" valignment="top" leftline="true" width="0">
-<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Subject / Title
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Where to get / filename
+as-z80
\end_inset
</cell>
-</row>
-<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-SDCC Compiler User Guide
+Assembler
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-You're reading it right now
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
</cell>
</row>
\layout Standard
-Changelog of SDCC
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/Changelog
+asx8051
\end_inset
</cell>
-</row>
-<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-ASXXXX Assemblers and ASLINK Relocating Linker
+Assembler
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/as/doc/asxhtm.html
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
</cell>
</row>
\layout Standard
-SDCC regression test
-\begin_inset LatexCommand \index{Regression test}
-
+sdcdb
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+Simulator
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/doc/test_suite_spec.pdf
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
</cell>
</row>
\layout Standard
-Various notes
+aslink
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-sdcc/doc/*
+Linker
\end_inset
</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-Notes on debugging with sdcdb
-\begin_inset LatexCommand \index{sdcdb (debugger)}
-
-\end_inset
-
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-sdcc/debugger/README
+link-z80
\end_inset
</cell>
-</row>
-<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Software simulator for microcontrollers
+Linker
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\bar no
\noun off
\color none
-sdcc/sim/ucsim/doc
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color default
-/index.html
+sdcc/bin
\end_inset
</cell>
</row>
\layout Standard
-Temporary notes on the pic16
-\begin_inset LatexCommand \index{PIC16}
-
+link-gbz80
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- port
+\layout Standard
+
+Linker
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/src/pic16/NOTES
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
</cell>
</row>
\layout Standard
-SDCC internal documentation (debugging file format)
+packihx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ihx packer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/doc/
+
\family roman
\series medium
\shape up
\bar no
\noun off
\color none
-cdbfileformat.pd
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color default
-f
+sdcc/bin
\end_inset
</cell>
</row>
\layout Section
-Related open source tools
-\begin_inset LatexCommand \index{Related tools}
+Documentation
+\begin_inset LatexCommand \index{Documentation}
\end_inset
-
+ included in the distribution
\layout Standard
\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="10" columns="3">
+<lyxtabular version="3" rows="10" columns="2">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="block" valignment="top" leftline="true" width="30line%">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Purpose
+Subject / Title
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Where to get
+Where to get / filename
\end_inset
</cell>
</row>
\layout Standard
-gpsim
-\begin_inset LatexCommand \index{gpsim (PIC simulator)}
-
+SDCC Compiler User Guide
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+You're reading it right now
\end_inset
</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-PIC simulator
+Changelog of SDCC
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
-
-\end_inset
-
-
+sdcc/Changelog
\end_inset
</cell>
</row>
\layout Standard
-flP5
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-PIC programmer
+ASXXXX Assemblers and ASLINK Relocating Linker
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
-
-\end_inset
-
-
+sdcc/as/doc/asxhtm.html
\end_inset
</cell>
</row>
\layout Standard
-indent
-\begin_inset LatexCommand \index{indent (source formatting tool)}
-
-\end_inset
-
+SDCC regression test
+\begin_inset LatexCommand \index{Regression test}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Formats C source - Master of the white spaces
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
-
-\end_inset
-
-
+sdcc/doc/test_suite_spec.pdf
\end_inset
</cell>
</row>
\layout Standard
-srecord
-\begin_inset LatexCommand \index{srecord (tool)}
-
-\end_inset
-
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Object file conversion, checksumming, ...
+Various notes
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
-
-\end_inset
-
-
+sdcc/doc/*
\end_inset
</cell>
</row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
-\layout Standard
+\layout Standard
+
+Notes on debugging with sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
+\end_inset
-objdump
-\begin_inset LatexCommand \index{objdump (tool)}
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+sdcc/debugger/README
\end_inset
</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Object file conversion, ...
+Software simulator for microcontrollers
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Part of binutils (should be there anyway)
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/sim/ucsim/doc
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+/index.html
\end_inset
</cell>
</row>
\layout Standard
-doxygen
-\begin_inset LatexCommand \index{doxygen (source documentation tool)}
+Temporary notes on the pic16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+ port
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+sdcc/src/pic16/NOTES
\end_inset
</cell>
+</row>
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Source code documentation system
+SDCC internal documentation (debugging file format)
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.doxygen.org}
+sdcc/doc/
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+cdbfileformat.pd
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+f
+\end_inset
+</cell>
+</row>
+</lyxtabular>
\end_inset
+\newline
+
+\layout Section
+
+Related open source tools
+\begin_inset LatexCommand \index{Related tools}
+
\end_inset
-</cell>
-</row>
-<row topline="true">
+
+
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="block" valignment="top" leftline="true" width="30line%">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-kdevelop
+Name
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
+Purpose
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.kdevelop.org}
-
-\end_inset
-
-
+Where to get
\end_inset
</cell>
</row>
\layout Standard
-splint
-\begin_inset LatexCommand \index{splint (syntax checking tool)}
+gpsim
+\begin_inset LatexCommand \index{gpsim (pic simulator)}
\end_inset
\layout Standard
-Statically checks c sources
+PIC simulator
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.splint.org}
+\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
\end_inset
\end_inset
</cell>
</row>
-<row topline="true" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-ddd
-\begin_inset LatexCommand \index{ddd (debugger)}
+gputils
+\begin_inset LatexCommand \index{gputils (pic tools)}
\end_inset
\layout Standard
-Debugger, serves nicely as GUI to sdcdb
-\begin_inset LatexCommand \index{sdcdb (debugger)}
-
-\end_inset
-
- (Unix only)
+GNU PIC utilities
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
\end_inset
\end_inset
</cell>
</row>
-</lyxtabular>
-
-\end_inset
-
-
-\newline
-
-\layout Section
-
-Related documentation / recommended reading
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="block" valignment="top" leftline="true" width="30line%">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
+flP5
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Subject / Title
+PIC programmer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Where to get
+
+\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
+indent
+\begin_inset LatexCommand \index{indent (source formatting tool)}
+
+\end_inset
+
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-c-refcard.pdf
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-C Reference Card
-\begin_inset LatexCommand \index{C Reference card}
-
-\end_inset
-
-, 2 pages
+Formats C source - Master of the white spaces
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
+\begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
\end_inset
\layout Standard
-c-faq
+srecord
+\begin_inset LatexCommand \index{srecord (tool)}
+
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-C-FAQ-list
+Object file conversion, checksumming, ...
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
+\begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
\end_inset
\end_inset
</cell>
</row>
-<row topline="true" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-S.
- S.
- Muchnick
+objdump
+\begin_inset LatexCommand \index{objdump (tool)}
+
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Advanced Compiler Design and Implementation
+Object file conversion, ...
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-bookstore (very dedicated, probably read other books first)
+Part of binutils (should be there anyway)
\end_inset
</cell>
</row>
-</lyxtabular>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\end_inset
+\layout Standard
+doxygen
+\begin_inset LatexCommand \index{doxygen (source documentation tool)}
-\newline
+\end_inset
-\layout Section
-Some Questions
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
\layout Standard
-Some questions answered, some pointers given - it might be time to in turn
- ask
-\emph on
-you
-\emph default
- some questions:
-\layout Itemize
+Source code documentation system
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-can you solve your project with the selected microcontroller? Would you
- find out early or rather late that your target is too small/slow/whatever?
- Can you switch to a slightly better device if it doesn't fit?
-\layout Itemize
+\layout Standard
-should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
- and/or another programming language be more adequate? Would an operating
- system on the target device help?
-\layout Itemize
-if you solved the problem, will the marketing department be happy?
-\layout Itemize
+\begin_inset LatexCommand \url{http://www.doxygen.org}
-if the marketing department is happy, will customers be happy?
-\layout Itemize
+\end_inset
-if you're the project manager, marketing department and maybe even the customer
- in one person, have you tried to see the project from the outside?
-\layout Itemize
-is the project done if you think it is done? Or is just that other interface/pro
-tocol/feature/configuration/option missing? How about website, manual(s),
- internationalization, packaging, labels, electromagnetic compatability/interfer
-ence, documentation for production, production test software, update mechanism,
- patent issues?
-\layout Itemize
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-is your project adequately positioned in that magic triangle: fame, fortune,
- fun?
\layout Standard
-Maybe not all answers to these questions are known and some answers may
- even be
-\emph on
-no
-\emph default
-, nevertheless knowing these questions may help you to avoid burnout
-\begin_inset Foot
-collapsed false
+kdevelop
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-burnout is bad for electronic devices, programmers and motorcycle tyres
+IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-.
- Chances are you didn't want to hear some of them...
-\layout Chapter
+\layout Standard
-Support
-\begin_inset LatexCommand \index{Support}
+
+\begin_inset LatexCommand \url{http://www.kdevelop.org}
\end_inset
-\layout Standard
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-SDCC has grown to be a large project.
- The compiler alone (without the preprocessor, assembler and linker) is
- well over 100,000 lines of code (blank stripped).
- The open source nature of this project is a key to its continued growth
- and support.
- You gain the benefit and support of many active software developers and
- end users.
- Is SDCC perfect? No, that's why we need your help.
- The developers take pride in fixing reported bugs.
- You can help by reporting the bugs and helping other SDCC users.
- There are lots of ways to contribute, and we encourage you to take part
- in making SDCC a great software package.
-
\layout Standard
-The SDCC project is hosted on the SDCC sourceforge site at
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
+splint
+\begin_inset LatexCommand \index{splint (syntax checking tool)}
\end_inset
-.
- You'll find the complete set of mailing lists
-\begin_inset LatexCommand \index{Mailing list}
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-, forums, bug reporting system, patch submission
-\begin_inset LatexCommand \index{Patch submission}
+\layout Standard
+Statically checks c sources (has anyone adapted splint for SDCC?)
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- system, download
-\begin_inset LatexCommand \index{download}
+\layout Standard
-\end_inset
- area and cvs code repository
-\begin_inset LatexCommand \index{cvs code repository}
+\begin_inset LatexCommand \url{http://www.splint.org}
\end_inset
- there.
-\layout Section
-
-Reporting Bugs
-\begin_inset LatexCommand \index{Bug reporting}
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{Reporting bugs}
+ddd
+\begin_inset LatexCommand \index{ddd (debugger)}
\end_inset
-\layout Standard
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-The recommended way of reporting bugs is using the infrastructure of the
- sourceforge site.
- You can follow the status of bug reports there and have an overview about
- the known bugs.
\layout Standard
-Bug reports are automatically forwarded to the developer mailing list and
- will be fixed ASAP.
- When reporting a bug, it is very useful to include a small test program
- (the smaller the better) which reproduces the problem.
- If you can isolate the problem by looking at the generated assembly code,
- this can be very helpful.
- Compiling your program with the -
-\begin_inset ERT
-status Collapsed
+Debugger, serves nicely as GUI to sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
+\end_inset
+
+ (Unix only)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+
+\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
+
\end_inset
--dumpall
-\begin_inset LatexCommand \index{-\/-dumpall}
\end_inset
+</cell>
+</row>
+</lyxtabular>
- option can sometimes be useful in locating optimization problems.
- When reporting a bug please maker sure you:
-\layout Enumerate
+\end_inset
-Attach the code you are compiling with SDCC.
-
-\layout Enumerate
-Specify the exact command you use to run SDCC, or attach your Makefile.
-
-\layout Enumerate
+\newline
-Specify the SDCC version (type "sdcc -v"), your platform, and operating
- system.
-
-\layout Enumerate
+\layout Section
-Provide an exact copy of any error message or incorrect output.
-
-\layout Enumerate
+Related documentation / recommended reading
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="block" valignment="top" leftline="true" width="30line%">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Put something meaningful in the subject of your message.
\layout Standard
-Please attempt to include these 5 important parts, as applicable, in all
- requests for support or when reporting any problems or bugs with SDCC.
- Though this will make your message lengthy, it will greatly improve your
- chance that SDCC users and developers will be able to help you.
- Some SDCC developers are frustrated by bug reports without code provided
- that they can use to reproduce and ultimately fix the problem, so please
- be sure to provide sample code if you are reporting a bug!
+Name
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
\layout Standard
-Please have a short check that you are using a recent version of SDCC and
- the bug is not yet known.
- This is the link for reporting bugs:
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
+Subject / Title
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+
+Where to get
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-\layout Section
+\layout Standard
-Requesting Features
-\begin_inset LatexCommand \label{sub:Requesting-Features}
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+c-refcard.pdf
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{Feature request}
+C Reference Card
+\begin_inset LatexCommand \index{C Reference card}
\end_inset
+, 2 pages
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\begin_inset LatexCommand \index{Requesting features}
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
\end_inset
-\layout Standard
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Like bug reports feature requests are forwarded to the developer mailing
- list.
- This is the link for requesting features:
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
+\layout Standard
+c-faq
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-\layout Section
+\layout Standard
+
+C-FAQ-list
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-Getting Help
\layout Standard
-These links should take you directly to the
-\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
+
+\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
\end_inset
-\begin_inset Foot
-collapsed false
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
- automated messages (mid 2003)
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- and the
-\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
+\layout Standard
+Latest datasheet of the target CPU
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-, lists and forums are archived and searchable so if you are lucky someone
- already had a similar problem.
-\layout Section
-
-ChangeLog
\layout Standard
-You can follow the status of the cvs version
-\begin_inset LatexCommand \index{version}
-
+vendor
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- of SDCC by watching the Changelog
-\begin_inset LatexCommand \index{Changelog}
+\layout Standard
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- in the cvs-repository
-\newline
+\layout Standard
-\size footnotesize
+Revision history of datasheet
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
+\layout Standard
+vendor
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-\layout Section
-
-Release policy
-\begin_inset LatexCommand \index{Release policy}
+\layout Standard
+S.
+ S.
+ Muchnick
\end_inset
-
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-Historically there often were long delays between official releases and
- the sourceforge download area tends to get not updated at all.
- Current excuses might refer to problems with live range analysis, but if
- this is fixed, the next problem rising is that another excuse will have
- to be found.
- Kidding aside, we have to get better there! On the other hand there are
- daily snapshots available at
-\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
-
+Advanced Compiler Design and Implementation
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-, and you can always built the very last version (hopefully with many bugs
- fixed, and features added) from the source code available at
-\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
+\layout Standard
+bookstore (very dedicated, probably read other books first)
\end_inset
+</cell>
+</row>
+</lyxtabular>
-.
-\layout Section
+\end_inset
-Examples
-\begin_inset LatexCommand \index{Examples}
-\end_inset
+\newline
+\layout Section
+Some Questions
\layout Standard
-You'll find some small examples in the directory
-\emph on
-sdcc/device/examples/.
-
-\emph default
-More examples and libraries are available at
+Some questions answered, some pointers given - it might be time to in turn
+ ask
\emph on
- The SDCC Open Knowledge Resource
-\begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
-
-\end_inset
-
-
+you
\emph default
-web site or at
-\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
-
-\end_inset
+ some questions:
+\layout Itemize
-.
-\layout Comment
+can you solve your project with the selected microcontroller? Would you
+ find out early or rather late that your target is too small/slow/whatever?
+ Can you switch to a slightly better device if it doesn't fit?
+\layout Itemize
-I did insert a reference to Paul's web site here although it seems rather
- dedicated to a specific 8032 board (I think it's okay because it f.e.
- shows LCD/Harddisc interface and has a free 8051 monitor.
- Independent 8032 board vendors face hard competition of heavily subsidized
- development boards anyway).
-\layout Comment
+should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
+ and/or another programming language be more adequate? Would an operating
+ system on the target device help?
+\layout Itemize
-Maybe we should include some links to real world applications.
- Preferably pointer to pointers (one for each architecture) so this stays
- manageable here?
-\layout Section
+if you solved the problem, will the marketing department be happy?
+\layout Itemize
-Quality control
-\begin_inset LatexCommand \index{Quality control}
+if the marketing department is happy, will customers be happy?
+\layout Itemize
-\end_inset
+if you're the project manager, marketing department and maybe even the customer
+ in one person, have you tried to see the project from the outside?
+\layout Itemize
+is the project done if you think it is done? Or is just that other interface/pro
+tocol/feature/configuration/option missing? How about website, manual(s),
+ internationali(z|s)ation, packaging, labels, 2nd source for components,
+ electromagnetic compatability/interference, documentation for production,
+ production test software, update mechanism, patent issues?
+\layout Itemize
+is your project adequately positioned in that magic triangle: fame, fortune,
+ fun?
\layout Standard
-The compiler is passed through nightly compile and build checks.
- The so called
-\shape italic
-regression tests
-\shape default
+Maybe not all answers to these questions are known and some answers may
+ even be
+\emph on
+no
+\emph default
+, nevertheless knowing these questions may help you to avoid burnout
+\begin_inset Foot
+collapsed false
-\begin_inset LatexCommand \index{Regression test}
+\layout Standard
+burnout is bad for electronic devices, programmers and motorcycle tyres
\end_inset
- check that SDCC itself compiles flawlessly on several platforms and checks
- the quality of the code generated by SDCC by running the code through simulator
-s.
- There is a separate document
-\shape italic
-test_suite.pdf
-\begin_inset LatexCommand \index{Test suite}
+.
+ Chances are you didn't want to hear some of them...
+\layout Chapter
+
+Support
+\begin_inset LatexCommand \index{Support}
\end_inset
-\shape default
- about this.
\layout Standard
-You'll find the test code in the directory
-\shape italic
-sdcc/support/regression
-\shape default
-.
- You can run these tests manually by running
-\family sans
-make
-\family default
- in this directory (or f.e.
+SDCC has grown to be a large project.
+ The compiler alone (without the preprocessor, assembler and linker) is
+ well over 100,000 lines of code (blank stripped).
+ The open source nature of this project is a key to its continued growth
+ and support.
+ You gain the benefit and support of many active software developers and
+ end users.
+ Is SDCC perfect? No, that's why we need your help.
+ The developers take pride in fixing reported bugs.
+ You can help by reporting the bugs and helping other SDCC users.
+ There are lots of ways to contribute, and we encourage you to take part
+ in making SDCC a great software package.
-\family sans
-make test-mcs51
-\family default
- if you don't want to run the complete tests).
- The test code might also be interesting if you want to look for examples
-\begin_inset LatexCommand \index{Examples}
-
-\end_inset
+\layout Standard
- checking corner cases of SDCC or if you plan to submit patches
-\begin_inset LatexCommand \index{Patch submission}
+The SDCC project is hosted on the SDCC sourceforge site at
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
\end_inset
.
-\layout Standard
-
-The pic port uses a different set of regression tests, you'll find them
- in the directory
-\shape italic
-sdcc/src/regression
-\shape default
-.
-\layout Chapter
-\pagebreak_top
-SDCC Technical Data
-\layout Section
-
-Optimizations
-\begin_inset LatexCommand \index{Optimizations}
+ You'll find the complete set of mailing lists
+\begin_inset LatexCommand \index{Mailing list(s)}
\end_inset
+, forums, bug reporting system, patch submission
+\begin_inset LatexCommand \index{Patch submission}
-\layout Standard
-
-SDCC performs a host of standard optimizations in addition to some MCU specific
- optimizations.
-
-\layout Subsection
+\end_inset
-Sub-expression Elimination
-\begin_inset LatexCommand \index{Subexpression elimination}
+ system, download
+\begin_inset LatexCommand \index{download}
\end_inset
+ area and cvs code repository
+\begin_inset LatexCommand \index{cvs code repository}
-\layout Standard
-
-The compiler does local and
-\emph on
-g
-\emph default
-lobal
-\emph on
-c
-\emph default
-ommon
-\emph on
-s
-\emph default
-ubexpression
-\emph on
-e
-\emph default
-limination, e.g.:
-\layout Verse
+\end_inset
+ there.
+\layout Section
-\family typewriter
-i = x + y + 1;
-\newline
-j = x + y;
-\layout Standard
+Reporting Bugs
+\begin_inset LatexCommand \index{Bug reporting}
-will be translated to
-\layout Verse
+\end_inset
-\family typewriter
-iTemp = x + y;
-\newline
-i = iTemp + 1;
-\newline
-j = iTemp;
-\layout Standard
+\begin_inset LatexCommand \index{Reporting bugs}
-Some subexpressions are not as obvious as the above example, e.g.:
-\layout Verse
+\end_inset
-\family typewriter
-a->b[i].c = 10;
-\newline
-a->b[i].d = 11;
\layout Standard
-In this case the address arithmetic a->b[i] will be computed only once;
- the equivalent code in C would be.
-\layout Verse
+The recommended way of reporting bugs is using the infrastructure of the
+ sourceforge site.
+ You can follow the status of bug reports there and have an overview about
+ the known bugs.
+\layout Standard
+Bug reports are automatically forwarded to the developer mailing list and
+ will be fixed ASAP.
+ When reporting a bug, it is very useful to include a small test program
+ (the smaller the better) which reproduces the problem.
+ If you can isolate the problem by looking at the generated assembly code,
+ this can be very helpful.
+ Compiling your program with the -
+\begin_inset ERT
+status Collapsed
-\family typewriter
-iTemp = a->b[i];
-\newline
-iTemp.c = 10;
-\newline
-iTemp.d = 11;
\layout Standard
-The compiler will try to keep these temporary variables in registers.
-\layout Subsection
+\backslash
+/
+\end_inset
-Dead-Code Elimination
-\begin_inset LatexCommand \index{Dead-code elimination}
+-dumpall
+\begin_inset LatexCommand \index{-\/-dumpall}
\end_inset
+ option can sometimes be useful in locating optimization problems.
+ When reporting a bug please maker sure you:
+\layout Enumerate
-\layout Verse
+Attach the code you are compiling with SDCC.
+
+\layout Enumerate
+Specify the exact command you use to run SDCC, or attach your Makefile.
+
+\layout Enumerate
-\family typewriter
-int global;
-\newline
+Specify the SDCC version (type "
+\family sans
+\series bold
+sdcc -v
+\family default
+\series default
+"), your platform, and operating system.
+
+\layout Enumerate
-\newline
-void f () {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-int i;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-i = 1; \SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* dead store */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 1;\SpecialChar ~
-/* dead store */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 3;\SpecialChar ~
-/* unreachable */
-\newline
-}
+Provide an exact copy of any error message or incorrect output.
+
+\layout Enumerate
+
+Put something meaningful in the subject of your message.
\layout Standard
-will be changed to
-\layout Verse
+Please attempt to include these 5 important parts, as applicable, in all
+ requests for support or when reporting any problems or bugs with SDCC.
+ Though this will make your message lengthy, it will greatly improve your
+ chance that SDCC users and developers will be able to help you.
+ Some SDCC developers are frustrated by bug reports without code provided
+ that they can use to reproduce and ultimately fix the problem, so please
+ be sure to provide sample code if you are reporting a bug!
+\layout Standard
+Please have a short check that you are using a recent version of SDCC and
+ the bug is not yet known.
+ This is the link for reporting bugs:
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
-\family typewriter
-int global;
-\newline
+\end_inset
-\newline
-void f () {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
-}
-\layout Subsection
+.
+\layout Section
-Copy-Propagation
-\begin_inset LatexCommand \index{Copy propagation}
+Requesting Features
+\begin_inset LatexCommand \label{sub:Requesting-Features}
\end_inset
-\layout Verse
+\begin_inset LatexCommand \index{Feature request}
+\end_inset
-\family typewriter
-int f() {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-int i, j;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-i = 10;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-j = i;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return j;
-\newline
-}
-\layout Standard
-will be changed to
-\layout Verse
+\begin_inset LatexCommand \index{Requesting features}
+\end_inset
-\family typewriter
-int f() {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-int i, j;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-i = 10;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-j = 10;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return 10;
-\newline
-}
-\layout Standard
-Note: the dead stores created by this copy propagation will be eliminated
- by dead-code elimination.
-\layout Subsection
+\layout Standard
-Loop Optimizations
-\begin_inset LatexCommand \index{Loop optimization}
+Like bug reports feature requests are forwarded to the developer mailing
+ list.
+ This is the link for requesting features:
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
\end_inset
+.
+\layout Section
+Submitting patches
\layout Standard
-Two types of loop optimizations are done by SDCC loop invariant lifting
- and strength reduction of loop induction variables.
- In addition to the strength reduction the optimizer marks the induction
- variables and the register allocator tries to keep the induction variables
- in registers for the duration of the loop.
- Because of this preference of the register allocator
-\begin_inset LatexCommand \index{Register allocation}
+Like bug reports contributed patches are forwarded to the developer mailing
+ list.
+ This is the link for submitting patches
+\begin_inset LatexCommand \index{Patch submission}
\end_inset
-, loop induction optimization causes an increase in register pressure, which
- may cause unwanted spilling of other temporary variables into the stack
-\begin_inset LatexCommand \index{stack}
+:
+\begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
\end_inset
- / data space.
- The compiler will generate a warning message when it is forced to allocate
- extra space either on the stack or data space.
- If this extra space allocation is undesirable then induction optimization
- can be eliminated either for the entire source file (with -
-\begin_inset ERT
-status Collapsed
-
+.
\layout Standard
-\backslash
-/
+You need to specify some parameters to the
+\family typewriter
+diff
+\family default
+ command for the patches to be useful.
+ If you modified more than one file a patch created f.e.
+ with
+\family sans
+\series bold
+
+\begin_inset Quotes sld
\end_inset
--noinduction option) or for a given function only using #pragma\SpecialChar ~
-noinduction
-\begin_inset LatexCommand \index{\#pragma noinduction}
+diff -Naur unmodified_directory modified_directory >my_changes.patch
+\begin_inset Quotes srd
+\end_inset
+
+
+\family default
+\series default
+ will be fine, otherwise
+\family sans
+\series bold
+\begin_inset Quotes sld
\end_inset
-.
-\newline
+diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
+\begin_inset Quotes srd
+\end_inset
-\newline
-Loop Invariant:
-\layout Verse
+\series default
+
+\family default
+will do.
+\layout Section
-\family typewriter
-for (i = 0 ; i < 100 ; i ++)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-f += k + l;
+Getting Help
\layout Standard
-changed to
-\layout Verse
+These links should take you directly to the
+\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
+\end_inset
+
+
+\begin_inset Foot
+collapsed false
-\family typewriter
-itemp = k + l;
-\newline
-for (i = 0; i < 100; i++)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-f += itemp;
\layout Standard
-As mentioned previously some loop invariants are not as apparent, all static
- address computations are also moved out of the loop.
-\newline
+Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
+ automated messages (mid 2003)
+\end_inset
-\newline
-Strength Reduction
-\begin_inset LatexCommand \index{Strength reduction}
+ and the
+\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
\end_inset
-, this optimization substitutes an expression by a cheaper expression:
-\layout Verse
+, lists
+\begin_inset LatexCommand \index{Mailing list(s)}
+\end_inset
-\family typewriter
-for (i=0;i < 100; i++)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ar[i*5] = i*3;
+ and forums are archived and searchable so if you are lucky someone already
+ had a similar problem.
+ While mails to the lists themselves are delivered promptly their web front
+ end on sourceforge sometimes shows a severe time lag (up to several weeks),
+ if you're seriously using SDCC please consider subscribing to the lists.
+\layout Section
+
+ChangeLog
\layout Standard
-changed to
-\layout Verse
+You can follow the status of the cvs version
+\begin_inset LatexCommand \index{version}
+\end_inset
-\family typewriter
-itemp1 = 0;
-\newline
-itemp2 = 0;
-\newline
-for (i=0;i< 100;i++) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ar[itemp1] = itemp2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-itemp1 += 5;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-itemp2 += 3;
+ of SDCC by watching the Changelog
+\begin_inset LatexCommand \index{Changelog}
+
+\end_inset
+
+ in the cvs-repository
\newline
-}
-\layout Standard
-The more expensive multiplication
-\begin_inset LatexCommand \index{Multiplication}
+\size footnotesize
+
+\begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
\end_inset
- is changed to a less expensive addition.
-\layout Subsection
+.
+\layout Section
-Loop Reversing
-\begin_inset LatexCommand \index{Loop reversing}
+Release policy
+\begin_inset LatexCommand \index{Release policy}
\end_inset
\layout Standard
-This optimization is done to reduce the overhead of checking loop boundaries
- for every iteration.
- Some simple loops can be reversed and implemented using a
-\begin_inset Quotes eld
-\end_inset
+Historically there often were long delays between official releases and
+ the sourceforge download area tends to get not updated at all.
+ Excuses in the past might have referred to problems with live range analysis,
+ but as this was fixed a while ago, the current problem is that another
+ excuse has to be found.
+ Kidding aside, we have to get better there! On the other hand there are
+ daily snapshots available at
+\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
-decrement and jump if not zero
-\begin_inset Quotes erd
\end_inset
- instruction.
- SDCC checks for the following criterion to determine if a loop is reversible
- (note: more sophisticated compilers use data-dependency analysis to make
- this determination, SDCC uses a more simple minded analysis).
-\layout Itemize
+, and you can always build the very last version (hopefully with many bugs
+ fixed, and features added) from the source code available at
+\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
-The 'for' loop is of the form
-\newline
+\end_inset
-\newline
+.
+\layout Section
-\family typewriter
-for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
- += 1])
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-<for body>
-\layout Itemize
+Examples
+\begin_inset LatexCommand \index{Examples}
-The <for body> does not contain
-\begin_inset Quotes eld
\end_inset
-continue
-\begin_inset Quotes erd
+
+\layout Standard
+
+You'll find some small examples in the directory
+\emph on
+sdcc/device/examples/.
+
+\emph default
+More examples and libraries are available at
+\emph on
+ The SDCC Open Knowledge Resource
+\begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
+
\end_inset
- or 'break
-\begin_inset Quotes erd
+
+\emph default
+web site or at
+\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
+
\end_inset
.
-\layout Itemize
+\layout Comment
-All goto's are contained within the loop.
-\layout Itemize
+I did insert a reference to Paul's web site here although it seems rather
+ dedicated to a specific 8032 board (I think it's okay because it f.e.
+ shows LCD/Harddisc interface and has a free 8051 monitor.
+ Independent 8032 board vendors face hard competition of heavily subsidized
+ development boards anyway).
+\layout Comment
-No function calls within the loop.
-\layout Itemize
+Maybe we should include some links to real world applications.
+ Preferably pointer to pointers (one for each architecture) so this stays
+ manageable here?
+\layout Section
-The loop control variable <sym> is not assigned any value within the loop
-\layout Itemize
+Quality control
+\begin_inset LatexCommand \index{Quality control}
-The loop control variable does NOT participate in any arithmetic operation
- within the loop.
-\layout Itemize
+\end_inset
-There are NO switch statements in the loop.
-\layout Subsection
-Algebraic Simplifications
\layout Standard
-SDCC does numerous algebraic simplifications, the following is a small sub-set
- of these optimizations.
-\layout Verse
-
-
-\family typewriter
-i = j + 0;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- /* changed to: */\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- i = j;
-\newline
-i /= 2;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- /* changed to: */\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- i >>= 1;
-\newline
-i = j - j;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- /* changed to: */\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- i = 0;
-\newline
-i = j / 1;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- /* changed to: */\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- i = j;
-\layout Standard
+The compiler is passed through nightly compile and build checks.
+ The so called
+\shape italic
+regression tests
+\shape default
-Note the subexpressions
-\begin_inset LatexCommand \index{Subexpression}
+\begin_inset LatexCommand \index{Regression test}
\end_inset
- given above are generally introduced by macro expansions or as a result
- of copy/constant propagation.
-\layout Subsection
+ check that SDCC itself compiles flawlessly on several platforms and checks
+ the quality of the code generated by SDCC by running the code through simulator
+s.
+ There is a separate document
+\shape italic
+test_suite.pdf
+\begin_inset LatexCommand \index{Test suite}
-'switch' Statements
-\begin_inset LatexCommand \label{sub:'switch'-Statements}
+\end_inset
+
+
+\shape default
+ about this.
+\layout Standard
+
+You'll find the test code in the directory
+\shape italic
+sdcc/support/regression
+\shape default
+.
+ You can run these tests manually by running
+\family sans
+make
+\family default
+ in this directory (or f.e.
+
+\family sans
+\series bold
+\begin_inset Quotes sld
\end_inset
+make test-mcs51
+\begin_inset Quotes srd
+\end_inset
-\begin_inset LatexCommand \index{switch statement}
+
+\family default
+\series default
+ if you don't want to run the complete tests).
+ The test code might also be interesting if you want to look for examples
+\begin_inset LatexCommand \index{Examples}
\end_inset
+ checking corner cases of SDCC or if you plan to submit patches
+\begin_inset LatexCommand \index{Patch submission}
+
+\end_inset
+.
\layout Standard
-SDCC changes switch statements to jump tables
-\begin_inset LatexCommand \index{jump tables}
+The pic port uses a different set of regression tests, you'll find them
+ in the directory
+\shape italic
+sdcc/src/regression
+\shape default
+.
+\layout Chapter
+\pagebreak_top
+SDCC Technical Data
+\layout Section
+
+Optimizations
+\begin_inset LatexCommand \index{Optimizations}
\end_inset
- when the following conditions are true.
+
+\layout Standard
+
+SDCC performs a host of standard optimizations in addition to some MCU specific
+ optimizations.
-\layout Itemize
+\layout Subsection
-The case labels are in numerical sequence, the labels need not be in order,
- and the starting number need not be one or zero.
-\begin_deeper
-\layout Verse
+Sub-expression Elimination
+\begin_inset LatexCommand \index{Subexpression elimination}
+\end_inset
-\family typewriter
-switch(i) {\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-switch (i) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 4: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 0: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 5: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 1: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 3: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 2: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 6: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 3: ...
-
+
+\layout Standard
+
+The compiler does local and
+\emph on
+g
+\emph default
+lobal
+\emph on
+c
+\emph default
+ommon
+\emph on
+s
+\emph default
+ubexpression
+\emph on
+e
+\emph default
+limination, e.g.:
+\layout Verse
+
+
+\family typewriter
+i = x + y + 1;
\newline
-}\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-}
+j = x + y;
\layout Standard
-Both the above switch statements will be implemented using a jump-table.
- The example to the right side is slightly more efficient as the check for
- the lower boundary of the jump-table is not needed.
-\end_deeper
-\layout Itemize
+will be translated to
+\layout Verse
-The number of case labels is at least three, since it takes two conditional
- statements to handle the boundary conditions.
-\layout Itemize
-The number of case labels is less than 84, since each label takes 3 bytes
- and a jump-table can be utmost 256 bytes long.
+\family typewriter
+iTemp = x + y;
+\newline
+i = iTemp + 1;
+\newline
+j = iTemp;
\layout Standard
-Switch statements which have gaps in the numeric sequence or those that
- have more that 84 case labels can be split into more than one switch statement
- for efficient code generation, e.g.:
+Some subexpressions are not as obvious as the above example, e.g.:
\layout Verse
\family typewriter
-switch (i) {
+a->b[i].c = 10;
+\newline
+a->b[i].d = 11;
+\layout Standard
+
+In this case the address arithmetic a->b[i] will be computed only once;
+ the equivalent code in C would be.
+\layout Verse
+
+
+\family typewriter
+iTemp = a->b[i];
+\newline
+iTemp.c = 10;
+\newline
+iTemp.d = 11;
+\layout Standard
+
+The compiler will try to keep these temporary variables in registers.
+\layout Subsection
+
+Dead-Code Elimination
+\begin_inset LatexCommand \index{Dead-code elimination}
+
+\end_inset
+
+
+\layout Verse
+
+
+\family typewriter
+int global;
+\newline
+
+\newline
+void f () {
\newline
\SpecialChar ~
\SpecialChar ~
-case 1: ...
-
+int i;
\newline
\SpecialChar ~
\SpecialChar ~
-case 2: ...
-
+i = 1; \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* dead store */
\newline
\SpecialChar ~
\SpecialChar ~
-case 3: ...
-
+global = 1;\SpecialChar ~
+/* dead store */
\newline
\SpecialChar ~
\SpecialChar ~
-case 4: ...
-
+global = 2;
\newline
\SpecialChar ~
\SpecialChar ~
-case 9: ...
-
+return;
\newline
\SpecialChar ~
\SpecialChar ~
-case 10: ...
-
+global = 3;\SpecialChar ~
+/* unreachable */
+\newline
+}
+\layout Standard
+
+will be changed to
+\layout Verse
+
+
+\family typewriter
+int global;
+\newline
+
+\newline
+void f () {
\newline
\SpecialChar ~
\SpecialChar ~
-case 11: ...
-
+global = 2;
\newline
\SpecialChar ~
\SpecialChar ~
-case 12: ...
-
+return;
\newline
}
-\layout Standard
+\layout Subsection
+
+Copy-Propagation
+\begin_inset LatexCommand \index{Copy propagation}
+
+\end_inset
+
-If the above switch statement is broken down into two switch statements
\layout Verse
\family typewriter
-switch (i) {
+int f() {
\newline
\SpecialChar ~
\SpecialChar ~
-case 1: ...
-
+int i, j;
\newline
\SpecialChar ~
\SpecialChar ~
-case 2: ...
-
+i = 10;
\newline
\SpecialChar ~
\SpecialChar ~
-case 3: ...
-
+j = i;
\newline
\SpecialChar ~
\SpecialChar ~
-case 4: ...
-
+return j;
\newline
}
\layout Standard
-and
+will be changed to
\layout Verse
\family typewriter
-switch (i) {
+int f() {
\newline
\SpecialChar ~
\SpecialChar ~
-case 9:\SpecialChar ~
-\SpecialChar ~
-...
-
+int i, j;
\newline
\SpecialChar ~
\SpecialChar ~
-case 10:\SpecialChar ~
-...
-
+i = 10;
\newline
\SpecialChar ~
\SpecialChar ~
-case 11:\SpecialChar ~
-...
-
+j = 10;
\newline
\SpecialChar ~
\SpecialChar ~
-case 12:\SpecialChar ~
-...
-
+return 10;
\newline
}
\layout Standard
-then both the switch statements will be implemented using jump-tables whereas
- the unmodified switch statement will not be.
- You might also consider inserting dummy cases 0 and 5 to 8 in this example.
-
-\newline
-The pragma nojtbound
-\begin_inset LatexCommand \index{\#pragma nojtbound}
+Note: the dead stores created by this copy propagation will be eliminated
+ by dead-code elimination.
+\layout Subsection
+
+Loop Optimizations
+\begin_inset LatexCommand \index{Loop optimization}
\end_inset
- can be used to turn off checking the
-\emph on
-j
-\emph default
-ump
+
+\begin_inset LatexCommand \label{sub:Loop-Optimizations}
+
+\end_inset
+
+
+\layout Standard
+
+Two types of loop optimizations are done by SDCC
\emph on
-t
+loop invariant
\emph default
-able
+ lifting and
\emph on
-bound
+ strength reduction
\emph default
-aries.
- It has no effect if a default label is supplied.
- Use of this pragma is dangerous: if the switch argument is not matched
- by a case statement the processor will happily jump into Nirvana.
-\layout Subsection
+ of loop induction variables.
+ In addition to the strength reduction the optimizer marks the induction
+ variables and the register allocator tries to keep the induction variables
+ in registers for the duration of the loop.
+ Because of this preference of the register allocator
+\begin_inset LatexCommand \index{Register allocation}
-Bit-shifting Operations
-\begin_inset LatexCommand \index{Bit shifting}
+\end_inset
+
+, loop induction optimization causes an increase in register pressure, which
+ may cause unwanted spilling of other temporary variables into the stack
+\begin_inset LatexCommand \index{stack}
\end_inset
-.
+ / data space.
+ The compiler will generate a warning message when it is forced to allocate
+ extra space either on the stack or data space.
+ If this extra space allocation is undesirable then induction optimization
+ can be eliminated either for the entire source file (with -
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-Bit shifting is one of the most frequently used operation in embedded programmin
-g.
- SDCC tries to implement bit-shift operations in the most efficient way
- possible, e.g.:
-\layout Verse
+\backslash
+/
+\end_inset
+
+-noinduction option) or for a given function only using #pragma\SpecialChar ~
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+\end_inset
-\family typewriter
-unsigned char i;
-\newline
-...
-
-\newline
-i >>= 4;
+.
\newline
-...
-\layout Standard
-generates the following code:
+\newline
+Loop Invariant:
\layout Verse
\family typewriter
-mov\SpecialChar ~
- a,_i
-\newline
-swap a
-\newline
-anl\SpecialChar ~
- a,#0x0f
+for (i = 0 ; i < 100 ; i ++)
\newline
-mov\SpecialChar ~
- _i,a
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+f += k + l;
\layout Standard
-In general SDCC will never setup a loop if the shift count is known.
- Another example:
+changed to
\layout Verse
\family typewriter
-unsigned int i;
-\newline
-...
-
+itemp = k + l;
\newline
-i >>= 9;
+for (i = 0; i < 100; i++)
\newline
-...
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+f += itemp;
\layout Standard
-will generate:
+As mentioned previously some loop invariants are not as apparent, all static
+ address computations are also moved out of the loop.
+\newline
+
+\newline
+Strength Reduction
+\begin_inset LatexCommand \index{Strength reduction}
+
+\end_inset
+
+, this optimization substitutes an expression by a cheaper expression:
\layout Verse
\family typewriter
-mov\SpecialChar ~
-\SpecialChar ~
-a,(_i + 1)
+for (i=0;i < 100; i++)
\newline
-mov\SpecialChar ~
\SpecialChar ~
-(_i + 1),#0x00
-\newline
-clr\SpecialChar ~
\SpecialChar ~
-c
-\newline
-rrc\SpecialChar ~
\SpecialChar ~
-a
-\newline
-mov\SpecialChar ~
\SpecialChar ~
-_i,a
-\layout Subsection
-
-Bit-rotation
-\begin_inset LatexCommand \index{Bit rotation}
-
-\end_inset
-
-
+ar[i*5] = i*3;
\layout Standard
-A special case of the bit-shift operation is bit rotation
-\begin_inset LatexCommand \index{rotating bits}
-
-\end_inset
-
-, SDCC recognizes the following expression to be a left bit-rotation:
+changed to
\layout Verse
\family typewriter
-\series bold
-unsigned
-\series default
+itemp1 = 0;
+\newline
+itemp2 = 0;
+\newline
+for (i=0;i< 100;i++) {
+\newline
\SpecialChar ~
\SpecialChar ~
-char i;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ar[itemp1] = itemp2;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+itemp1 += 5;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* unsigned is needed for rotation */
-\newline
-...
-
+itemp2 += 3;
\newline
-i = ((i << 1) | (i >> 7));
-\family default
+}
+\layout Standard
+
+The more expensive multiplication
+\begin_inset LatexCommand \index{Multiplication}
+
+\end_inset
+
+ is changed to a less expensive addition.
+\layout Subsection
+
+Loop Reversing
+\begin_inset LatexCommand \index{Loop reversing}
+
+\end_inset
-\newline
-\family typewriter
-...
\layout Standard
-will generate the following code:
-\layout Verse
+This optimization is done to reduce the overhead of checking loop boundaries
+ for every iteration.
+ Some simple loops can be reversed and implemented using a
+\begin_inset Quotes eld
+\end_inset
+
+decrement and jump if not zero
+\begin_inset Quotes erd
+\end_inset
+
+ instruction.
+ SDCC checks for the following criterion to determine if a loop is reversible
+ (note: more sophisticated compilers use data-dependency analysis to make
+ this determination, SDCC uses a more simple minded analysis).
+\layout Itemize
+
+The 'for' loop is of the form
+\newline
+\newline
\family typewriter
-mov\SpecialChar ~
-\SpecialChar ~
-a,_i
+for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
+ += 1])
\newline
-rl\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-a
-\newline
-mov\SpecialChar ~
\SpecialChar ~
-_i,a
-\layout Standard
+\SpecialChar ~
+<for body>
+\layout Itemize
-SDCC uses pattern matching on the parse tree to determine this operation.Variatio
-ns of this case will also be recognized as bit-rotation, i.e.:
-\layout Verse
+The <for body> does not contain
+\begin_inset Quotes eld
+\end_inset
+continue
+\begin_inset Quotes erd
+\end_inset
-\family typewriter
-i = ((i >> 7) | (i << 1)); /* left-bit rotation */
-\layout Subsection
+ or 'break
+\begin_inset Quotes erd
+\end_inset
-Nibble and Byte Swapping
-\layout Standard
+.
+\layout Itemize
-Other special cases of the bit-shift operations are nibble or byte swapping
-\begin_inset LatexCommand \index{swapping nibbles/bytes}
+All goto's are contained within the loop.
+\layout Itemize
-\end_inset
+No function calls within the loop.
+\layout Itemize
-, SDCC recognizes the following expressions:
+The loop control variable <sym> is not assigned any value within the loop
+\layout Itemize
+
+The loop control variable does NOT participate in any arithmetic operation
+ within the loop.
+\layout Itemize
+
+There are NO switch statements in the loop.
+\layout Subsection
+
+Algebraic Simplifications
+\layout Standard
+
+SDCC does numerous algebraic simplifications, the following is a small sub-set
+ of these optimizations.
\layout Verse
\family typewriter
-\series bold
-unsigned
-\series default
+i = j + 0;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-char i;
-\newline
-
-\series bold
-unsigned
-\series default
\SpecialChar ~
+ /* changed to: */\SpecialChar ~
\SpecialChar ~
-int j;
+\SpecialChar ~
+\SpecialChar ~
+ i = j;
\newline
-...
-
+i /= 2;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i >>= 1;
\newline
-i = ((i << 4) | (i >> 4));
-\family default
-
+i = j - j;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = 0;
\newline
-
-\family typewriter
-j = ((j << 8) | (j >> 8));
+i = j / 1;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = j;
\layout Standard
-and generates a swap instruction for the nibble swapping
-\begin_inset LatexCommand \index{Nibble swapping}
-
-\end_inset
-
- or move instructions for the byte swapping
-\begin_inset LatexCommand \index{Byte swapping}
-
-\end_inset
-
-.
- The
-\begin_inset Quotes sld
-\end_inset
+Note the subexpressions
+\begin_inset LatexCommand \index{Subexpression}
-j
-\begin_inset Quotes srd
\end_inset
- example can be used to convert from little to big-endian or vice versa.
- If you want to change the endianness of a
-\emph on
-signed
-\emph default
- integer you have to cast to
-\family typewriter
-(unsigned int)
-\family default
- first.
-\layout Standard
-
-Note that SDCC stores numbers in little-endian
-\begin_inset Foot
-collapsed false
-
-\layout Standard
-
-Usually 8-bit processors don't care much about endianness.
- This is not the case for the standard 8051 which only has an instruction
- to increment its
-\emph on
-dptr
-\emph default
-
-\begin_inset LatexCommand \index{DPTR}
+ given above are generally introduced by macro expansions or as a result
+ of copy/constant propagation.
+\layout Subsection
-\end_inset
+'switch' Statements
+\begin_inset LatexCommand \label{sub:'switch'-Statements}
--datapointer
-\emph on
-
-\emph default
-so little-endian is the more efficient byte order.
\end_inset
-\begin_inset LatexCommand \index{little-endian}
+\begin_inset LatexCommand \index{switch statement}
\end_inset
-\begin_inset LatexCommand \index{Endianness}
-
-\end_inset
-
- format (i.e.
- lowest order first).
-\layout Subsection
+\layout Standard
-Highest Order Bit
-\begin_inset LatexCommand \index{Highest Order Bit}
+SDCC changes switch statements to jump tables
+\begin_inset LatexCommand \index{jump tables}
\end_inset
+ when the following conditions are true.
+
+\layout Itemize
-\layout Standard
-
-It is frequently required to obtain the highest order bit of an integral
- type (long, int, short or char types).
- SDCC recognizes the following expression to yield the highest order bit
- and generates optimized code for it, e.g.:
+The case labels are in numerical sequence, the labels need not be in order,
+ and the starting number need not be one or zero.
+\begin_deeper
\layout Verse
\family typewriter
-unsigned int gint;
-\newline
-
-\newline
-foo () {
-\newline
+switch(i) {\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char hob;
-\newline
\SpecialChar ~
\SpecialChar ~
-...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-hob = (gint >> 15) & 1;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+switch (i) {
\newline
\SpecialChar ~
\SpecialChar ~
-..
+\SpecialChar ~
+case 4: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 0: ...
\newline
-}
-\layout Standard
-
-will generate the following code:
-\layout Verse
-
-
-\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+case 5: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 61 ;\SpecialChar ~
- hob.c 7
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
\newline
-000A E5*01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+case 3: ...\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 62\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- mov\SpecialChar ~
\SpecialChar ~
- a,(_gint + 1)
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 2: ...
+
\newline
-000C 23\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+case 6: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 63\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- rl\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- a
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
\newline
-000D 54 01\SpecialChar ~
+}\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 64\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- anl\SpecialChar ~
\SpecialChar ~
- a,#0x01
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+}
+\layout Standard
+
+Both the above switch statements will be implemented using a jump-table.
+ The example to the right side is slightly more efficient as the check for
+ the lower boundary of the jump-table is not needed.
+\end_deeper
+\layout Itemize
+
+The number of case labels is at least three, since it takes two conditional
+ statements to handle the boundary conditions.
+\layout Itemize
+
+The number of case labels is less than 84, since each label takes 3 bytes
+ and a jump-table can be utmost 256 bytes long.
+\layout Standard
+
+Switch statements which have gaps in the numeric sequence or those that
+ have more that 84 case labels can be split into more than one switch statement
+ for efficient code generation, e.g.:
+\layout Verse
+
+
+\family typewriter
+switch (i) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 2: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...
+
\newline
-000F F5*02\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+case 9: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 10: ...
+
+\newline
+\SpecialChar ~
\SpecialChar ~
+case 11: ...
+
+\newline
\SpecialChar ~
\SpecialChar ~
+case 12: ...
+
+\newline
+}
+\layout Standard
+
+If the above switch statement is broken down into two switch statements
+\layout Verse
+
+
+\family typewriter
+switch (i) {
+\newline
\SpecialChar ~
\SpecialChar ~
+case 1: ...
+
+\newline
\SpecialChar ~
\SpecialChar ~
+case 2: ...
+
+\newline
\SpecialChar ~
\SpecialChar ~
+case 3: ...
+
+\newline
\SpecialChar ~
\SpecialChar ~
+case 4: ...
+
+\newline
+}
+\layout Standard
+
+and
+\layout Verse
+
+
+\family typewriter
+switch (i) {
+\newline
\SpecialChar ~
- 65\SpecialChar ~
\SpecialChar ~
+case 9:\SpecialChar ~
\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
\SpecialChar ~
+case 10:\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
\SpecialChar ~
+case 11:\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
- mov\SpecialChar ~
\SpecialChar ~
- _foo_hob_1_1,a
-\layout Standard
-
-Variations of this case however will
-\emph on
-not
-\emph default
- be recognized.
- It is a standard C expression, so I heartily recommend this be the only
- way to get the highest order bit, (it is portable).
- Of course it will be recognized even if it is embedded in other expressions,
- e.g.:
-\layout Verse
-
-
-\family typewriter
-xyz = gint + ((gint >> 15) & 1);
+case 12:\SpecialChar ~
+...
+
+\newline
+}
\layout Standard
-will still be recognized.
-\layout Subsection
-
-Peephole Optimizer
-\begin_inset LatexCommand \label{sub:Peephole-Optimizer}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{Peephole optimizer}
+then both the switch statements will be implemented using jump-tables whereas
+ the unmodified switch statement will not be.
+ You might also consider inserting dummy cases 0 and 5 to 8 in this example.
+
+\newline
+The pragma nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
\end_inset
-
-\layout Standard
-
-The compiler uses a rule based, pattern matching and re-writing mechanism
- for peep-hole optimization.
- It is inspired by
+ can be used to turn off checking the
\emph on
-copt
+j
\emph default
- a peep-hole optimizer by Christopher W.
- Fraser (cwfraser@microsoft.com).
- A default set of rules are compiled into the compiler, additional rules
- may be added with the
+ump
\emph on
--
-\begin_inset ERT
-status Collapsed
+t
+\emph default
+able
+\emph on
+bound
+\emph default
+aries.
+ It has no effect if a default label is supplied.
+ Use of this pragma is dangerous: if the switch argument is not matched
+ by a case statement the processor will happily jump into Nirvana.
+\layout Subsection
-\layout Standard
+Bit-shifting Operations
+\begin_inset LatexCommand \index{Bit shifting}
-\backslash
-/
\end_inset
--peep-file
-\begin_inset LatexCommand \index{-\/-peep-file}
-
-\end_inset
+.
+\layout Standard
- <filename>
-\emph default
- option.
- The rule language is best illustrated with examples.
+Bit shifting is one of the most frequently used operation in embedded programmin
+g.
+ SDCC tries to implement bit-shift operations in the most efficient way
+ possible, e.g.:
\layout Verse
\family typewriter
-replace {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-mov %1,a
-\newline
-\SpecialChar ~
-\SpecialChar ~
-mov a,%1
+unsigned char i;
\newline
-} by {
+...
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-mov %1,a
+i >>= 4;
\newline
-}
+...
\layout Standard
-The above rule will change the following assembly
-\begin_inset LatexCommand \index{Assembler routines}
-
-\end_inset
-
- sequence:
+generates the following code:
\layout Verse
\family typewriter
-mov r1,a
+mov\SpecialChar ~
+ a,_i
\newline
-mov a,r1
+swap a
+\newline
+anl\SpecialChar ~
+ a,#0x0f
+\newline
+mov\SpecialChar ~
+ _i,a
\layout Standard
-to
+In general SDCC will never setup a loop if the shift count is known.
+ Another example:
\layout Verse
\family typewriter
-mov r1,a
+unsigned int i;
+\newline
+...
+
+\newline
+i >>= 9;
+\newline
+...
\layout Standard
-Note: All occurrences of a
-\emph on
-%n
-\emph default
- (pattern variable) must denote the same string.
- With the above rule, the assembly sequence:
+will generate:
\layout Verse
\family typewriter
-mov r1,a
+mov\SpecialChar ~
+\SpecialChar ~
+a,(_i + 1)
\newline
-mov a,r2
-\layout Standard
-
-will remain unmodified.
+mov\SpecialChar ~
+\SpecialChar ~
+(_i + 1),#0x00
\newline
-
+clr\SpecialChar ~
+\SpecialChar ~
+c
\newline
-Other special case optimizations may be added by the user (via
-\emph on
--
-\begin_inset ERT
-status Collapsed
+rrc\SpecialChar ~
+\SpecialChar ~
+a
+\newline
+mov\SpecialChar ~
+\SpecialChar ~
+_i,a
+\layout Subsection
-\layout Standard
+Bit-rotation
+\begin_inset LatexCommand \index{Bit rotation}
-\backslash
-/
\end_inset
--peep-file option
-\emph default
-).
- E.g.
- some variants of the 8051 MCU allow only
-\family typewriter
-ajmp
-\family default
- and
-\family typewriter
-acall
-\family default
-.
- The following two rules will change all
-\family typewriter
-ljmp
-\family default
- and
-\family typewriter
-lcall
-\family default
- to
-\family typewriter
-ajmp
-\family default
- and
-\family typewriter
-acall
+
+\layout Standard
+
+A special case of the bit-shift operation is bit rotation
+\begin_inset LatexCommand \index{rotating bits}
+
+\end_inset
+
+, SDCC recognizes the following expression to be a left bit-rotation:
\layout Verse
\family typewriter
-replace { lcall %1 } by { acall %1 }
+\series bold
+unsigned
+\series default
+\SpecialChar ~
+\SpecialChar ~
+char i;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* unsigned is needed for rotation */
\newline
-replace { ljmp %1 } by { ajmp %1 }
-\layout Standard
-
-The
-\emph on
-inline-assembler code
-\emph default
- is also passed through the peep hole optimizer, thus the peephole optimizer
- can also be used as an assembly level macro expander.
- The rules themselves are MCU dependent whereas the rule language infra-structur
-e is MCU independent.
- Peephole optimization rules for other MCU can be easily programmed using
- the rule language.
+...
+
\newline
+i = ((i << 1) | (i >> 7));
+\family default
\newline
-The syntax for a rule is as follows:
+
+\family typewriter
+...
+\layout Standard
+
+will generate the following code:
\layout Verse
\family typewriter
-rule := replace [ restart ] '{' <assembly sequence> '
-\backslash
-n'
-\newline
+mov\SpecialChar ~
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- '}' by '{' '
-\backslash
-n'
+a,_i
\newline
+rl\SpecialChar ~
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- <assembly sequence> '
-\backslash
-n'
+\SpecialChar ~
+a
\newline
+mov\SpecialChar ~
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- '}' [if <functionName> ] '
-\backslash
-n'
+_i,a
\layout Standard
-<assembly sequence> := assembly instruction (each instruction including
- labels must be on a separate line).
-\newline
+SDCC uses pattern matching on the parse tree to determine this operation.Variatio
+ns of this case will also be recognized as bit-rotation, i.e.:
+\layout Verse
-\newline
-The optimizer will apply to the rules one by one from the top in the sequence
- of their appearance, it will terminate when all rules are exhausted.
- If the 'restart' option is specified, then the optimizer will start matching
- the rules again from the top, this option for a rule is expensive (performance)
-, it is intended to be used in situations where a transformation will trigger
- the same rule again.
- An example of this (not a good one, it has side effects) is the following
- rule:
+
+\family typewriter
+i = ((i >> 7) | (i << 1)); /* left-bit rotation */
+\layout Subsection
+
+Nibble and Byte Swapping
+\layout Standard
+
+Other special cases of the bit-shift operations are nibble or byte swapping
+\begin_inset LatexCommand \index{swapping nibbles/bytes}
+
+\end_inset
+
+, SDCC recognizes the following expressions:
\layout Verse
\family typewriter
-replace restart {
-\newline
+\series bold
+unsigned
+\series default
\SpecialChar ~
\SpecialChar ~
-pop %1
+char i;
\newline
+
+\series bold
+unsigned
+\series default
\SpecialChar ~
\SpecialChar ~
-push %1 } by {
+int j;
\newline
-\SpecialChar ~
-\SpecialChar ~
-; nop
+...
+
\newline
-}
-\layout Standard
-
-Note that the replace pattern cannot be a blank, but can be a comment line.
- Without the 'restart' option only the innermost 'pop' 'push' pair would
- be eliminated, i.e.:
-\layout Verse
+i = ((i << 4) | (i >> 4));
+\family default
+\newline
\family typewriter
-pop ar1
-\newline
-pop ar2
-\newline
-push ar2
-\newline
-push ar1
+j = ((j << 8) | (j >> 8));
\layout Standard
-would result in:
-\layout Verse
+and generates a swap instruction for the nibble swapping
+\begin_inset LatexCommand \index{Nibble swapping}
+
+\end_inset
+
+ or move instructions for the byte swapping
+\begin_inset LatexCommand \index{Byte swapping}
+
+\end_inset
+
+.
+ The
+\begin_inset Quotes sld
+\end_inset
+j
+\begin_inset Quotes srd
+\end_inset
+ example can be used to convert from little to big-endian or vice versa.
+ If you want to change the endianness of a
+\emph on
+signed
+\emph default
+ integer you have to cast to
\family typewriter
-pop ar1
-\newline
-; nop
-\newline
-push ar1
+(unsigned int)
+\family default
+ first.
\layout Standard
+Note that SDCC stores numbers in little-endian
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+Usually 8-bit processors don't care much about endianness.
+ This is not the case for the standard 8051 which only has an instruction
+ to increment its
\emph on
-with
+dptr
\emph default
- the restart option the rule will be applied again to the resulting code
- and then all the pop-push pairs will be eliminated to yield:
+
+\begin_inset LatexCommand \index{DPTR}
+
+\end_inset
+
+-datapointer
+\emph on
+
+\emph default
+so little-endian is the more efficient byte order.
+\end_inset
+
+
+\begin_inset LatexCommand \index{little-endian}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Endianness}
+
+\end_inset
+
+ format (i.e.
+ lowest order first).
+\layout Subsection
+
+Highest Order Bit
+\begin_inset LatexCommand \index{Highest Order Bit}
+
+\end_inset
+
+
+\layout Standard
+
+It is frequently required to obtain the highest order bit of an integral
+ type (long, int, short or char types).
+ SDCC recognizes the following expression to yield the highest order bit
+ and generates optimized code for it, e.g.:
\layout Verse
\family typewriter
-; nop
+unsigned int gint;
\newline
-; nop
+
+\newline
+foo () {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+unsigned char hob;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+hob = (gint >> 15) & 1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+..
+
+\newline
+}
\layout Standard
-A conditional function can be attached to a rule.
- Attaching rules are somewhat more involved, let me illustrate this with
- an example.
+will generate the following code:
\layout Verse
\family typewriter
-replace {
-\newline
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-ljmp %5
-\newline
-%2:
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 61 ;\SpecialChar ~
+ hob.c 7
\newline
-} by {
+000A E5*01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 62\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ a,(_gint + 1)
\newline
+000C 23\SpecialChar ~
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-sjmp %5
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 63\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ rl\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ a
\newline
-%2:
+000D 54 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 64\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ anl\SpecialChar ~
+\SpecialChar ~
+ a,#0x01
\newline
-} if labelInRange
+000F F5*02\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 65\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ _foo_hob_1_1,a
\layout Standard
-The optimizer does a look-up of a function name table defined in function
-
-\emph on
-callFuncByName
-\emph default
- in the source file SDCCpeeph.c, with the name
-\emph on
-labelInRange
-\emph default
-.
- If it finds a corresponding entry the function is called.
- Note there can be no parameters specified for these functions, in this
- case the use of
-\emph on
-%5
-\emph default
- is crucial, since the function
-\emph on
-labelInRange
-\emph default
- expects to find the label in that particular variable (the hash table containin
-g the variable bindings is passed as a parameter).
- If you want to code more such functions, take a close look at the function
- labelInRange and the calling mechanism in source file SDCCpeeph.c.
- Currently implemented are
-\emph on
-labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
- 24bitMode, portIsDS390, 24bitModeAndPortDS390
-\emph default
-and
+Variations of this case however will
\emph on
- notVolatile
+not
\emph default
-.
-\layout Standard
+ be recognized.
+ It is a standard C expression, so I heartily recommend this be the only
+ way to get the highest order bit, (it is portable).
+ Of course it will be recognized even if it is embedded in other expressions,
+ e.g.:
+\layout Verse
-I know this whole thing is a little kludgey, but maybe some day we will
- have some better means.
- If you are looking at this file, you will see the default rules that are
- compiled into the compiler, you can add your own rules in the default set
- there if you get tired of specifying the -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+xyz = gint + ((gint >> 15) & 1);
\layout Standard
-\backslash
-/
-\end_inset
-
--peep-file option.
-\layout Section
+will still be recognized.
+\layout Subsection
-ANSI-Compliance
-\begin_inset LatexCommand \index{ANSI-compliance}
+Peephole Optimizer
+\begin_inset LatexCommand \label{sub:Peephole-Optimizer}
\end_inset
-\begin_inset LatexCommand \label{sub:ANSI-Compliance}
+\begin_inset LatexCommand \index{Peephole optimizer}
\end_inset
\layout Standard
-Deviations from the compliance:
-\layout Itemize
+The compiler uses a rule based, pattern matching and re-writing mechanism
+ for peep-hole optimization.
+ It is inspired by
+\emph on
+copt
+\emph default
+ a peep-hole optimizer by Christopher W.
+ Fraser (cwfraser@microsoft.com).
+ A default set of rules are compiled into the compiler, additional rules
+ may be added with the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
-functions are not always reentrant
-\begin_inset LatexCommand \index{reentrant}
+-peep-file
+\begin_inset LatexCommand \index{-\/-peep-file}
\end_inset
-.
-\layout Itemize
-
-structures cannot be assigned values directly, cannot be passed as function
- parameters or assigned to each other and cannot be a return value from
- a function, e.g.:
-\begin_deeper
+ <filename>
+\emph default
+ option.
+ The rule language is best illustrated with examples.
\layout Verse
\family typewriter
-struct s { ...
- };
-\newline
-struct s s1, s2;
-\newline
-foo()
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
+replace {
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
-\newline
-struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
- */
-\newline
-{
+mov %1,a
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-struct s rets;
+mov a,%1
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
+} by {
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return rets;/* is invalid in SDCC although allowed in ANSI */
+mov %1,a
\newline
}
-\end_deeper
-\layout Itemize
+\layout Standard
-'long long
-\begin_inset LatexCommand \index{long long (not supported)}
+The above rule will change the following assembly
+\begin_inset LatexCommand \index{Assembler routines}
\end_inset
-' (64 bit integers
-\begin_inset LatexCommand \index{int (64 bit) (not supported)}
+ sequence:
+\layout Verse
-\end_inset
-) not supported.
-\layout Itemize
+\family typewriter
+mov r1,a
+\newline
+mov a,r1
+\layout Standard
-'double
-\begin_inset LatexCommand \index{double (not supported)}
+to
+\layout Verse
-\end_inset
-' precision floating point
-\begin_inset LatexCommand \index{Floating point support}
+\family typewriter
+mov r1,a
+\layout Standard
-\end_inset
+Note: All occurrences of a
+\emph on
+%n
+\emph default
+ (pattern variable) must denote the same string.
+ With the above rule, the assembly sequence:
+\layout Verse
-not supported.
-\layout Itemize
-No support for setjmp
-\begin_inset LatexCommand \index{setjmp (not supported)}
+\family typewriter
+mov r1,a
+\newline
+mov a,r2
+\layout Standard
+
+will remain unmodified.
+\newline
+
+\newline
+Other special case optimizations may be added by the user (via
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- and longjmp
-\begin_inset LatexCommand \index{longjmp (not supported)}
+-peep-file option
+\emph default
+).
+ E.g.
+ some variants of the 8051 MCU
+\begin_inset LatexCommand \index{MCS51 variants}
\end_inset
- (for now).
-\layout Itemize
+ allow only
+\family typewriter
+ajmp
+\family default
+ and
+\family typewriter
+acall
+\family default
+.
+ The following two rules will change all
+\family typewriter
+ljmp
+\family default
+ and
+\family typewriter
+lcall
+\family default
+ to
+\family typewriter
+ajmp
+\family default
+ and
+\family typewriter
+acall
+\layout Verse
-Old K&R style
-\begin_inset LatexCommand \index{K\&R style}
-\end_inset
+\family typewriter
+replace { lcall %1 } by { acall %1 }
+\newline
+replace { ljmp %1 } by { ajmp %1 }
+\layout Standard
+
+The
+\emph on
+inline-assembler code
+\emph default
+ is also passed through the peep hole optimizer, thus the peephole optimizer
+ can also be used as an assembly level macro expander.
+ The rules themselves are MCU dependent whereas the rule language infra-structur
+e is MCU independent.
+ Peephole optimization rules for other MCU can be easily programmed using
+ the rule language.
+\newline
+
+\newline
+The syntax for a rule is as follows:
+\layout Verse
+
+
+\family typewriter
+rule := replace [ restart ] '{' <assembly sequence> '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' by '{' '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ <assembly sequence> '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' [if <functionName> ] '
+\backslash
+n'
+\layout Standard
+
+<assembly sequence> := assembly instruction (each instruction including
+ labels must be on a separate line).
+\newline
- function declarations are NOT allowed.
-\begin_deeper
+\newline
+The optimizer will apply to the rules one by one from the top in the sequence
+ of their appearance, it will terminate when all rules are exhausted.
+ If the 'restart' option is specified, then the optimizer will start matching
+ the rules again from the top, this option for a rule is expensive (performance)
+, it is intended to be used in situations where a transformation will trigger
+ the same rule again.
+ An example of this (not a good one, it has side effects) is the following
+ rule:
\layout Verse
\family typewriter
-foo(i,j) /* this old style of function declarations */
-\newline
-int i,j; /* are valid in ANSI but not valid in SDCC */
+replace restart {
\newline
-{
+\SpecialChar ~
+\SpecialChar ~
+pop %1
\newline
\SpecialChar ~
\SpecialChar ~
+push %1 } by {
+\newline
\SpecialChar ~
\SpecialChar ~
-...
-
+; nop
\newline
}
-\end_deeper
-\layout Itemize
-
-functions declared as pointers
-\begin_inset LatexCommand \index{Pointer (to function)}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{function pointers}
-
-\end_inset
+\layout Standard
- must be dereferenced during the call.
-\begin_deeper
+Note that the replace pattern cannot be a blank, but can be a comment line.
+ Without the 'restart' option only the innermost 'pop' 'push' pair would
+ be eliminated, i.e.:
\layout Verse
\family typewriter
-int (*foo)();
+pop ar1
\newline
-...
-
+pop ar2
\newline
-/* has to be called like this */
+push ar2
\newline
-(*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
-\end_deeper
-\layout Section
-
-Cyclomatic Complexity
-\begin_inset LatexCommand \index{Cyclomatic complexity}
-
-\end_inset
-
-
+push ar1
\layout Standard
-Cyclomatic complexity of a function is defined as the number of independent
- paths the program can take during execution of the function.
- This is an important number since it defines the number test cases you
- have to generate to validate the function.
- The accepted industry standard for complexity number is 10, if the cyclomatic
- complexity reported by SDCC exceeds 10 you should think about simplification
- of the function logic.
- Note that the complexity level is not related to the number of lines of
- code in a function.
- Large functions can have low complexity, and small functions can have large
- complexity levels.
-
-\newline
-
-\newline
-SDCC uses the following formula to compute the complexity:
-\newline
+would result in:
+\layout Verse
-\layout Standard
-complexity = (number of edges in control flow graph) - (number of nodes
- in control flow graph) + 2;
+\family typewriter
+pop ar1
\newline
-
+; nop
\newline
-Having said that the industry standard is 10, you should be aware that in
- some cases it be may unavoidable to have a complexity level of less than
- 10.
- For example if you have switch statement with more than 10 case labels,
- each case label adds one to the complexity level.
- The complexity level is by no means an absolute measure of the algorithmic
- complexity of the function, it does however provide a good starting point
- for which functions you might look at for further optimization.
-\layout Section
-
-Notes on supported Processors
-\layout Subsection
-
-MCS51 variants
-\begin_inset LatexCommand \label{sub:MCS51-variants}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{MCS51 variants}
-
-\end_inset
-
-
-\layout Standard
-
-MCS51 processors are available from many vendors and come in many different
- flavours.
- While they might differ considerably in respect to Special Function Registers
- the core MCS51 is usually not modified or is kept compatible.
-
-\layout Subsubsection*
-
-pdata access by SFR
+push ar1
\layout Standard
-With the upcome of devices with internal xdata and flash memory devices
- using port P2
-\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
-
-\end_inset
-
- as dedicated I/O port is becoming more popular.
- Switching the high byte for pdata
-\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
-
-\end_inset
-
- access which was formerly done by port P2 is then achieved by a Special
- Function Register
-\begin_inset LatexCommand \index{sfr}
-
-\end_inset
-.
- In well-established MCS51 tradition the address of this
\emph on
-sfr
+with
\emph default
- is where the chip designers decided to put it.
- Needless to say that they didn't agree on a common name either.
- As pdata addressing is used in the startup code for the initialization
- of xdata variables a separate startup code should be used as described
- in section
-\begin_inset LatexCommand \ref{sub:Startup-Code}
-
-\end_inset
+ the restart option the rule will be applied again to the resulting code
+ and then all the pop-push pairs will be eliminated to yield:
+\layout Verse
-.
-\layout Subsubsection*
-Other Features available by SFR
+\family typewriter
+; nop
+\newline
+; nop
\layout Standard
-Some MCS51 variants offer features like Double DPTR
-\begin_inset LatexCommand \index{DPTR}
-
-\end_inset
+A conditional function can be attached to a rule.
+ Attaching rules are somewhat more involved, let me illustrate this with
+ an example.
+\layout Verse
-, multiple DPTR, decrementing DPTR, 16x16 Multiply.
- These are currently not used for the MCS51 port.
- If you absolutely need them you can fall back to inline assembly or submit
- a patch to SDCC.
-\layout Subsection
-The Z80 and gbz80 port
+\family typewriter
+replace {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ljmp %5
+\newline
+%2:
+\newline
+} by {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+sjmp %5
+\newline
+%2:
+\newline
+} if labelInRange
\layout Standard
-SDCC can target both the Zilog
-\begin_inset LatexCommand \index{Z80}
-
-\end_inset
-
- and the Nintendo Gameboy's Z80-like gbz80
-\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
-
-\end_inset
-
+The optimizer does a look-up of a function name table defined in function
+
+\emph on
+callFuncByName
+\emph default
+ in the source file SDCCpeeph.c, with the name
+\emph on
+labelInRange
+\emph default
.
- The Z80 port is passed through the same
+ If it finds a corresponding entry the function is called.
+ Note there can be no parameters specified for these functions, in this
+ case the use of
\emph on
-regressions tests
-\begin_inset LatexCommand \index{Regression test}
-
-\end_inset
-
-
+%5
\emph default
- as the MCS51 and DS390 ports, so floating point support, support for long
- variables and bitfield support is fine.
- See mailing lists and forums about interrupt routines.
+ is crucial, since the function
+\emph on
+labelInRange
+\emph default
+ expects to find the label in that particular variable (the hash table containin
+g the variable bindings is passed as a parameter).
+ If you want to code more such functions, take a close look at the function
+ labelInRange and the calling mechanism in source file SDCCpeeph.c.
+ Currently implemented are
+\emph on
+labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
+ 24bitMode, portIsDS390, 24bitModeAndPortDS390
+\emph default
+and
+\emph on
+ notVolatile
+\emph default
+.
\layout Standard
-As always, the code is the authoritative reference - see z80/ralloc.c and
- z80/gen.c.
- The stack
-\begin_inset LatexCommand \index{stack}
-
-\end_inset
-
- frame is similar to that generated by the IAR Z80 compiler.
- IX is used as the base pointer, HL is used as a temporary register, and
- BC and DE are available for holding variables.
- IY is currently unused.
- Return values
-\begin_inset LatexCommand \index{return value}
-
-\end_inset
-
- are stored in HL.
- One bad side effect of using IX as the base pointer is that a functions
- stack frame is limited to 127 bytes - this will be fixed in a later version.
-\layout Subsection
+I know this whole thing is a little kludgey, but maybe some day we will
+ have some better means.
+ If you are looking at this file, you will see the default rules that are
+ compiled into the compiler, you can add your own rules in the default set
+ there if you get tired of specifying the -
+\begin_inset ERT
+status Collapsed
-The HC08 port
\layout Standard
-The port to the Motorola HC08
-\begin_inset LatexCommand \index{HC08}
-
+\backslash
+/
\end_inset
- family has been added in October 2003, thank you Erik!
-\layout Subsection
-
-The PIC14 port
-\layout Standard
-
-The 14bit PIC port still requires a major effort from the development community.
- However it can work for very simple code.
-\newline
+-peep-file option.
+\layout Section
-\newline
+ANSI-Compliance
+\begin_inset LatexCommand \index{ANSI-compliance}
-\bar under
-C code and 14bit PIC code page and RAM banks
-\bar default
+\end_inset
-\newline
-The linker organizes allocation for the code page and RAM banks.
- It does not have intimate knowledge of the code flow.
- It will put all the code section of a single asm file into a single code
- page.
- In order to make use of multiple code pages, separate asm files must be
- used.
- The compiler treats all functions of a single C file as being in the same
- code page unless it is non static.
- The compiler treats all local variables of a single C file as being in
- the same RAM bank unless it is an extern.
-\newline
-\newline
-To get the best follow these guide lines:
-\layout Enumerate
+\begin_inset LatexCommand \label{sub:ANSI-Compliance}
-make local functions static, as non static functions require code page selection
- overhead.
-\layout Enumerate
+\end_inset
-Make local variables static as extern variables require RAM bank selection
- overhead.
-\layout Enumerate
-For devices that have multiple code pages it is more efficient to use the
- same number of files as pages, i.e.
- for the 16F877 use 4 separate files and i.e.
- for the 16F874 use 2 separate files.
- This way the linker can put the code for each file into different code
- pages and the compiler can allocate reusable variables more efficiently
- and there's less page selection overhead.
- And as for any 8 bit micro (especially for PIC 14 as they have a very simple
- instruction set) use 'unsigned char' whereever possible instead of 'int'.
\layout Standard
+Deviations from the compliance:
+\layout Itemize
-\bar under
-Creating a device include file
-\bar default
-
-\newline
-For generating a device include file use the support pearl script inc2h.pl
- kept in directory support/script.
-\newline
+functions are not always reentrant
+\begin_inset LatexCommand \index{reentrant}
-\newline
+\end_inset
-\bar under
-Interrupt code
-\bar default
+.
+\layout Itemize
-\newline
-For the interrupt function, use the keyword 'interrupt' with level number
- of 0 (PIC14 only has 1 interrupt so this number is only there to avoid
- a syntax error - it ought to be fixed).
- E.g.:
+structures cannot be assigned values directly, cannot be passed as function
+ parameters or assigned to each other and cannot be a return value from
+ a function, e.g.:
+\begin_deeper
\layout Verse
\family typewriter
-void Intr(void) interrupt 0
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-T0IF = 0; /* Clear timer interrupt */
-\newline
-}
-\layout Standard
-
-
-\bar under
-Linking and assembling
-\bar default
-
+struct s { ...
+ };
\newline
-For assembling you can use either GPUTILS' gpasm.exe or MPLAB's mpasmwin.exe.
- For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
- If you use MPLAB and an interrupt function then the linker script file
- vectors section will need to be enlarged to link with mplink.
+struct s s1, s2;
\newline
-
+foo()
\newline
-Here is a makefile using GPUTILS:
-\layout Verse
-
-
-\family typewriter
-.c.o:
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-sdcc -S -V -mpic14 -p16F877 $<
+s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+...
+
+\newline
+}
+\newline
+struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
+ */
+\newline
+{
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-gpasm -c $*.asm
-\newline
-
-\newline
-$(PRJ).hex: $(OBJS)
+struct s rets;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
-\layout Standard
+return rets;/* is invalid in SDCC although allowed in ANSI */
+\newline
+}
+\end_deeper
+\layout Itemize
+
+'long long
+\begin_inset LatexCommand \index{long long (not supported)}
+
+\end_inset
+
+' (64 bit integers
+\begin_inset LatexCommand \index{int (64 bit) (not supported)}
+
+\end_inset
+
+) not supported.
+\layout Itemize
+
+'double
+\begin_inset LatexCommand \index{double (not supported)}
+
+\end_inset
+
+' precision floating point
+\begin_inset LatexCommand \index{Floating point support}
-Here is a makefile using MPLAB:
+\end_inset
+
+not supported.
+\layout Itemize
+
+No support for setjmp
+\begin_inset LatexCommand \index{setjmp (not supported)}
+
+\end_inset
+
+ and longjmp
+\begin_inset LatexCommand \index{longjmp (not supported)}
+
+\end_inset
+
+ (for now).
+\layout Itemize
+
+Old K&R style
+\begin_inset LatexCommand \index{K\&R style}
+
+\end_inset
+
+ function declarations are NOT allowed.
+\begin_deeper
\layout Verse
\family typewriter
-.c.o:
+foo(i,j) /* this old style of function declarations */
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-sdcc -S -V -mpic14 -p16F877 $<
+int i,j; /* are valid in ANSI but not valid in SDCC */
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mpasmwin /q /o $*.asm
+...
+
+\newline
+}
+\end_deeper
+\layout Section
+
+Cyclomatic Complexity
+\begin_inset LatexCommand \index{Cyclomatic complexity}
+
+\end_inset
+
+
+\layout Standard
+
+Cyclomatic complexity of a function is defined as the number of independent
+ paths the program can take during execution of the function.
+ This is an important number since it defines the number test cases you
+ have to generate to validate the function.
+ The accepted industry standard for complexity number is 10, if the cyclomatic
+ complexity reported by SDCC exceeds 10 you should think about simplification
+ of the function logic.
+ Note that the complexity level is not related to the number of lines of
+ code in a function.
+ Large functions can have low complexity, and small functions can have large
+ complexity levels.
+
\newline
\newline
-$(PRJ).hex: $(OBJS)
+SDCC uses the following formula to compute the complexity:
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
-\layout Subsection
-The PIC16 port
\layout Standard
-You'll find some additional notes about this port in the file src/pic16/NOTES.
+complexity = (number of edges in control flow graph) - (number of nodes
+ in control flow graph) + 2;
+\newline
+
+\newline
+Having said that the industry standard is 10, you should be aware that in
+ some cases it be may unavoidable to have a complexity level of less than
+ 10.
+ For example if you have switch statement with more than 10 case labels,
+ each case label adds one to the complexity level.
+ The complexity level is by no means an absolute measure of the algorithmic
+ complexity of the function, it does however provide a good starting point
+ for which functions you might look at for further optimization.
\layout Section
Retargetting for other Processors
projects / fw / sdcc / blobdiff