+\layout Standard
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert int to floating point numbers
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_ulong2fs.c
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert unsigned long to floating point number
+
+\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
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_long2fs.c
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert long to floating point number
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+
+\layout Standard
+\added_space_bottom bigskip
+These support routines are developed in ANSI-C so there is room for space
+ and speed improvement
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+These floating point routines (
+\emph on
+not
+\emph default
+ sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
+
+
+\end_inset
+
+.
+ Note if all these routines are used simultaneously the data space might
+ overflow.
+ For serious floating point usage the large model might be needed.
+ Also notice that you don't have to call this routines directly.
+ The compiler will use them automatically every time a floating point operation
+ is required.
+
+
+
+\layout Section
+Library Routines
+\begin_inset LatexCommand \index{Libraries}
+
+\end_inset
+
+
+
+\layout Standard
+
+\emph on
+<pending: this is messy and incomplete - a little more information is in
+ sdcc/doc/libdoc.txt
+\emph default
+ >
+
+\layout Subsection
+Compiler support routines (_gptrget, _mulint etc.)
+
+\layout Subsection
+Stdclib functions (puts, printf, strcat etc.)
+
+\layout Subsubsection
+<stdio.h>
+
+\layout Paragraph
+getchar(), putchar()
+
+\layout Standard
+\begin_inset LatexCommand \index{<stdio.h>}
+
+\end_inset
+
+As usual on embedded systems you have to provide your own
+\family typewriter
+getchar()
+\begin_inset LatexCommand \index{getchar()}
+
+\end_inset
+
+
+\family default
+and
+\family typewriter
+putchar()
+\begin_inset LatexCommand \index{putchar()}
+
+\end_inset
+
+
+\family default
+ routines.
+ SDCC does not know whether the system connects to a serial line with or
+ without handshake, LCD, keyboard or other device.
+ And whether a
+\family typewriter
+lf
+\family default
+ to
+\family typewriter
+crlf
+\family default
+ conversion within
+\family typewriter
+putchar()
+\family default
+ is intended.
+ You'll find examples for serial routines f.e.
+ in sdcc/device/lib.
+ For the mcs51 this minimalistic polling
+\family typewriter
+putchar()
+\family default
+ routine might be a start:
+
+\layout Verse
+
+\family typewriter
+void putchar (char c) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+while (!TI)\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* assumes UART is initialized */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+TI
+ = 0;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SBUF = c;
+\newline
+}
+
+\layout Paragraph
+printf()
+
+\layout Standard
+The default
+\family typewriter
+ printf()
+\begin_inset LatexCommand \index{printf()}
+
+\end_inset
+
+
+\family default
+ implementation in
+\family typewriter
+ printf_large.c
+\family default
+ does not support float (except on ds390).
+ To enable this recompile it with the option
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+DUSE_FLOATS=1
+\begin_inset LatexCommand \index{USE\_FLOATS}
+
+\end_inset
+
+
+\emph default
+ on the command line.
+ Use
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-model-large
+\begin_inset LatexCommand \index{-\/-model-large}
+
+\end_inset
+
+
+\emph default
+ for the mcs51 port, since this uses a lot of memory.
+
+\layout Standard
+If you're short on code memory you might want to use
+\family typewriter
+printf_small()
+\begin_inset LatexCommand \index{printf\_small()}
+
+\end_inset
+
+
+\family default
+
+\emph on
+instead
+\emph default
+ of
+\family typewriter
+ printf().
+
+\family default
+ For the mcs51 there additionally are assembly versions
+\family typewriter
+printf_tiny()
+\begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
+
+\end_inset
+
+
+\family default
+ (subset of printf using less than 270 bytes) and
+\family typewriter
+printf_fast()
+\begin_inset LatexCommand \index{printf\_fast() (mcs51)}
+
+\end_inset
+
+
+\family default
+and
+\family typewriter
+ printf_fast_f()
+\begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
+
+\end_inset
+
+
+\family default
+ (floating-point aware version of printf_fast) which should fit the requirements
+ of many embedded systems (printf_fast() can be customized by unsetting
+ #defines to
+\emph on
+not
+\emph default
+ support long variables and field widths).
+ Be sure to use only one of these printf options within a project.
+\newline
+
+
+\layout Standard
+Feature matrix of different
+\emph on
+printf
+\emph default
+ options on mcs51.
+
+\layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="14" columns="7">
+<features islongtable="true">
+<column alignment="left" valignment="center" leftline="true" width="14col%">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="12col%">
+<column alignment="center" valignment="top" leftline="true" width="10col%">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="12col%">
+<column alignment="center" valignment="top" rightline="true" width="0">
+<row topline="true" bottomline="true" endhead="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\series bold
+\size large
+mcs51
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+printf
+\begin_inset LatexCommand \index{printf}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+printf
+\size scriptsize
+USE_FLOATS=1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+printf_small
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+printf_fast
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+printf_fast_f
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+printf_tiny
+
+\end_inset
+</cell>
+</row>
+<row topline="true" endhead="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+filename
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\size scriptsize
+printf_large.c
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\size scriptsize
+printf_large.c
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\size scriptsize
+printfl.c
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\size scriptsize
+printf_fast.c
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\size scriptsize
+printf_fast_f.c
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\size scriptsize
+printf_tiny.c
+
+\end_inset
+</cell>
+</row>
+<row topline="true" endhead="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+\begin_inset Quotes sld
+\end_inset
+
+Hello World
+\begin_inset Quotes srd
+\end_inset
+
+ size
+
+\layout Standard
+small / large
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.7k / 2.4k
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+4.3k / 5.6k
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.2k / 1.8k
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.3k / 1.3k
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.9k / 1.9k
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.44k / 0.44k
+
+\end_inset
+</cell>
+</row>
+<row topline="true" endhead="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+code size
+
+\layout Standard
+small / large
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.4k / 2.0k
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+2.8k / 3.7k
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.45k / 0.47k (+ _ltoa)
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.2k / 1.2k
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.6k / 1.6k
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.26k / 0.26k
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+formats
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+cdi
+\emph on
+o
+\emph default
+psux
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+cd
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+f
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+i
+\family default
+\series default
+\shape default
+\size default
+\emph on
+\bar default
+\noun default
+o
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+psux
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+c
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+d
+\family default
+\series default
+\shape default
+\size default
+\emph on
+\bar default
+\noun default
+o
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+s
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+cdsux
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+cdfsux
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+cdsux
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+long (32 bit) support
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+byte arguments on stack
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+b
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+b
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+float format
+\begin_inset LatexCommand \index{Floating point support}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+%f
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+%f
+\begin_inset Foot
+collapsed true
+
+\layout Standard
+Range limited to +/- 4294967040, precision limited to 8 digits past decimal
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+float formats %e %g
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\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
+field width
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+x
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+string speed
+\begin_inset Foot
+collapsed true
+
+\layout Standard
+Execution time of printf("%s%c%s%c%c%c", "Hello", ' ', "World", '!', '
+\backslash
+r', '
+\backslash
+n'); standard 8051 @ 22.1184 MHz, empty putchar()
+
+\end_inset
+
+,
+
+\layout Standard
+small / large
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.52 / 2.59 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.53 / 2.62 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.92 / 0.93 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.45 / 0.45 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.46 / 0.46 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.45 / 0.45 ms
+
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+int speed
+\begin_inset Foot
+collapsed true
+
+\layout Standard
+Execution time of printf("%d", -12345); standard 8051 @ 22.1184 MHz, empty
+ putchar()
+
+\end_inset
+
+,
+
+\layout Standard
+small / large
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+3.01 / 3.61 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+3.01 / 3.61 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+3.51 / 18.13 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.22 / 0.22 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.23 / 0.23 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.25 / 0.25 ms
+\begin_inset Foot
+collapsed true
+
+\layout Standard
+printf_tiny integer speed is data dependent, worst case is 0.33 ms
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+long speed
+\begin_inset Foot
+collapsed true
+
+\layout Standard
+Execution time of printf("%ld", -123456789); standard 8051 @ 22.1184 MHz,
+ empty putchar()
+
+\end_inset
+
+,
+
+\layout Standard
+small / large
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+5.37 / 6.31 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+5.37 / 6.31 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+8.71 / 40.65 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.40 / 0.40 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0.40 / 0.40 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+float speed
+\begin_inset Foot
+collapsed true
+
+\layout Standard
+Execution time of printf("%.3f", -12345.678); standard 8051 @ 22.1184 MHz,
+ empty putchar()
+
+\end_inset
+
+,
+
+\layout Standard
+small / large
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+7.49 / 22.47 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1.04 / 1.04 ms
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+-
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+
+\layout Subsubsection
+<malloc.h>
+\begin_inset LatexCommand \index{malloc.h}
+
+\end_inset
+
+
+
+\layout Standard
+As of SDCC 2.6.2 you no longer need to call an initialization routine before
+ using dynamic memory allocation
+\begin_inset LatexCommand \index{dynamic memory allocation (malloc)}
+
+\end_inset
+
+ and a default heap
+\begin_inset LatexCommand \index{heap (malloc)}
+
+\end_inset
+
+ space of 1024 bytes is provided for malloc to allocate memory from.
+ If you need a different heap size you need to recompile _heap.c with the
+ required size defined in HEAP_SIZE.
+ It is recommended to make a copy of this file into your project directory
+ and compile it there with:
+
+\layout Verse
+
+\family typewriter
+sdcc -c _heap.c -D HEAD_SIZE=2048
+
+\layout Standard
+And then link it with:
+
+\layout Verse
+
+\family typewriter
+sdcc main.rel _heap.rel
+
+\layout Subsection
+Math functions (sinf, powf, sqrtf etc.)
+
+\layout Subsubsection
+<math.h>
+
+\layout Standard
+See definitions in file <math.h>.
+
+\layout Subsection
+Other libraries
+
+\layout Standard
+Libraries
+\begin_inset LatexCommand \index{Libraries}
+
+\end_inset
+
+ included in SDCC should have a license at least as liberal as the GNU Lesser
+ General Public License
+\begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
+
+\end_inset
+
+
+\emph on
+LGPL
+\emph default
+.
+
+\layout Standard
+\begin_inset Note
+collapsed true
+
+\layout Standard
+license statements for the libraries are missing.
+ sdcc/device/lib/ser_ir.c
+
+\layout Standard
+or _decdptr f.e.
+ come with a GPL (as opposed to LGPL) License - this will not be liberal
+ enough for many embedded programmers.
+
+\end_inset
+
+
+
+\layout Standard
+If you have ported some library or want to share experience about some code
+ which f.e.
+ falls into any of these categories Busses (I
+\begin_inset Formula $^{\textrm{2}}$
+\end_inset
+
+C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
+ cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
+ Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
+\begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
+
+\end_inset
+
+\SpecialChar ~
+would certainly like to hear about it.
+
+\layout Standard
+\added_space_bottom bigskip
+Programmers coding for embedded systems are not especially famous for being
+ enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
+e these references are very valuable.
+ Let's help to create a climate where information is shared.
+
+
+
+\layout Section
+Memory Models
+
+\layout Subsection
+MCS51 Memory Models
+\begin_inset LatexCommand \index{Memory model}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{MCS51 memory model}
+
+\end_inset
+
+
+
+\layout Subsubsection
+Small, Medium and Large
+
+\layout Standard
+SDCC allows three memory models for MCS51 code,
+\shape slanted
+small, medium
+\shape default
+ and
+\shape slanted
+large
+\shape default
+.
+ Modules compiled with different memory models should
+\emph on
+never
+\emph default
+ be combined together or the results would be unpredictable.
+ The library routines supplied with the compiler are compiled as small,
+ medium and large.
+ The compiled library modules are contained in separate directories as small,
+ medium and large so that you can link to the appropriate set.
+
+\layout Standard
+When the medium or large model is used all variables declared without a
+ storage class will be allocated into the external ram, this includes all
+ parameters and local variables (for non-reentrant
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+ functions).
+ When the small model is used variables without storage class are allocated
+ in the internal ram.
+
+\layout Standard
+Judicious usage of the processor specific storage classes
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ and the 'reentrant' function type will yield much more efficient code,
+ than using the large model.
+ Several optimizations are disabled when the program is compiled using the
+ large model, it is therefore recommended that the small model be used unless
+ absolutely required.
+
+\layout Subsubsection
+External Stack
+\begin_inset LatexCommand \label{sub:External-Stack}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{External stack (mcs51)}
+
+\end_inset
+
+
+
+\layout Standard
+The external stack (-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-xstack option
+\begin_inset LatexCommand \index{-\/-xstack}
+
+\end_inset
+
+) is located in pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ memory (usually at the start of the external ram segment) and uses all
+ unused space in pdata (max.
+ 256 bytes).
+ When -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-xstack option is used to compile the program, the parameters and local
+ variables
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+ of all reentrant functions are allocated in this area.
+ This option is provided for programs with large stack space requirements.
+ When used with the -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+ option, all parameters and local variables are allocated on the external
+ stack (note: support libraries will need to be recompiled with the same
+ options.
+ There is a predefined target in the library makefile).
+
+\layout Standard
+The compiler outputs the higher order address byte of the external ram segment
+ into port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
+
+\end_inset
+
+ (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
+ be used by the application program.
+
+\layout Subsection
+DS390 Memory Model
+\begin_inset LatexCommand \index{Memory model}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{DS390 memory model}
+
+\end_inset
+
+
+
+\layout Standard
+The only model supported is Flat 24
+\begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
+
+\end_inset
+
+.
+ This generates code for the 24 bit contiguous addressing mode of the Dallas
+ DS80C390 part.
+ In this mode, up to four meg of external RAM or code space can be directly
+ addressed.
+ See the data sheets at www.dalsemi.com for further information on this part.
+\newline
+
+\newline
+Note
+ that the compiler does not generate any code to place the processor into
+ 24 bitmode (although
+\emph on
+tinibios
+\emph default
+ in the ds390 libraries will do that for you).
+ If you don't use
+\emph on
+tinibios
+\emph default
+
+\begin_inset LatexCommand \index{Tinibios (DS390)}
+
+\end_inset
+
+, the boot loader or similar code must ensure that the processor is in 24
+ bit contiguous addressing mode before calling the SDCC startup code.
+\newline
+
+\newline
+Like
+ the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-model-large
+\emph default
+ option, variables will by default be placed into the XDATA segment.
+
+\newline
+
+\newline
+Segments may be placed anywhere in the 4 meg address space using the usual
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-*-loc options.
+ Note that if any segments are located above 64K, the -r flag must be passed
+ to the linker to generate the proper segment relocations, and the Intel
+ HEX output format must be used.
+ The -r flag can be passed to the linker by using the option
+\emph on
+-Wl-r
+\emph default
+ on the SDCC command line.
+ However, currently the linker can not handle code segments > 64k.
+
+\layout Section
+Pragmas
+\begin_inset LatexCommand \label{sec:Pragmas}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Pragmas}
+
+\end_inset
+
+
+
+\layout Standard
+SDCC supports the following #pragma directives:
+
+\layout Itemize
+
+\series bold
+save
+\series default
+
+\begin_inset LatexCommand \index{\#pragma save}
+
+\end_inset
+
+ - this will save most current options to the save/restore stack.
+ See #pragma\SpecialChar ~
+restore.
+
+\layout Itemize
+
+\series bold
+restore
+\series default
+
+\begin_inset LatexCommand \index{\#pragma restore}
+
+\end_inset
+
+ - will restore saved options from the last save.
+ 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 #pragma\SpecialChar ~
+save.
+\newline
+
+
+\layout Itemize
+
+\series bold
+callee_saves
+\series default
+
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{function prologue}
+
+\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}
+
+\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
+
+-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
+
+\series bold
+exclude
+\series default
+
+\begin_inset LatexCommand \index{\#pragma exclude}
+
+\end_inset
+
+ 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
+
+
+\begin_inset LatexCommand \index{\_\_naked}
+
+\end_inset
+
+.
+
+\layout Itemize
+
+\series bold
+less_pedantic
+\series default
+
+\begin_inset LatexCommand \index{\#pragma less\_pedantic}
+
+\end_inset
+
+ - the compiler will not warn you anymore for obvious mistakes, you'r on
+ your own now ;-(
+
+\layout Itemize
+
+\series bold
+disable_warning
+\series default
+ <nnnn>
+\begin_inset LatexCommand \index{\#pragma disable\_warning}
+
+\end_inset
+
+ - the compiler will not warn you anymore about warning number <nnnn>.
+
+\layout Itemize
+
+\series bold
+nogcse
+\series default
+
+\begin_inset LatexCommand \index{\#pragma nogcse}
+
+\end_inset
+
+ - will stop global common subexpression elimination.
+
+\layout Itemize
+
+\series bold
+noinduction
+\series default
+
+\begin_inset LatexCommand \index{\#pragma noinduction}
+
+\end_inset
+
+ - will stop loop induction optimizations.
+
+\layout Itemize
+
+\series bold
+noinvariant
+\series default
+
+\begin_inset LatexCommand \index{\#pragma noinvariant}
+
+\end_inset
+
+ - will not do loop invariant optimizations.
+ For more details see Loop Invariants in section
+\begin_inset LatexCommand \ref{sub:Loop-Optimizations}
+
+\end_inset
+
+.
+
+\layout Itemize
+
+\series bold
+noiv
+\series default
+
+\begin_inset LatexCommand \index{\#pragma noiv}
+
+\end_inset
+
+ - Do not generate interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ vector table
+\begin_inset LatexCommand \index{interrupt vector table}
+
+\end_inset
+
+ entries for all ISR functions defined after the pragma.
+ This is useful in cases where the interrupt vector table must be defined
+ manually, or when there is a secondary, manually defined interrupt vector
+ table (e.g.
+ for the autovector feature of the Cypress EZ-USB FX2).
+ More elegantly this can be achieved by obmitting the optional interrupt
+ number after the interrupt keyword, see section
+\begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
+
+\end_inset
+
+\SpecialChar ~
+about interrupts.
+
+\layout Itemize
+
+\series bold
+nojtbound
+\series default
+
+\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
+
+\series bold
+noloopreverse
+\series default
+
+\begin_inset LatexCommand \index{\#pragma noloopreverse}
+
+\end_inset
+
+ - Will not do loop reversal optimization
+
+\layout Itemize
+
+\series bold
+nooverlay
+\series default
+
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+
+ - the compiler will not overlay the parameters and local variables of a
+ function.
+
+\layout Itemize
+
+\series bold
+stackauto
+\series default
+
+\begin_inset LatexCommand \index{\#pragma stackauto}
+
+\end_inset
+
+- See option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+ and section
+\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+ Parameters and Local Variables.
+
+\layout Itemize
+
+\series bold
+opt_code_speed
+\series default
+
+\begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
+
+\end_inset
+
+- The compiler will optimize code generation towards fast code, possibly
+ at the expense of code size.
+ Currently this has little effect.
+
+\layout Itemize
+
+\series bold
+opt_code_size
+\series default
+
+\begin_inset LatexCommand \index{\#pragma opt\_code\_size}
+
+\end_inset
+
+- The compiler will optimize code generation towards compact code, possibly
+ at the expense of code speed.
+ Currently this has little effect.
+
+\layout Itemize
+
+\series bold
+opt_code_balanced
+\series default
+
+\begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
+
+\end_inset
+
+- The compiler will attempt to generate code that is both compact and fast,
+ as long as meeting one goal is not a detriment to the other (this is the
+ default).
+
+
+\layout Itemize
+
+\series bold
+std_sdcc89
+\series default
+
+\begin_inset LatexCommand \index{\#pragma std\_sdcc89}
+
+\end_inset
+
+- Generally follow the C89 standard, but allow SDCC features that conflict
+ with the standard (default).
+
+\layout Itemize
+
+\series bold
+std_c89
+\series default
+
+\begin_inset LatexCommand \index{\#pragma std\_c89}
+
+\end_inset
+
+- Follow the C89 standard and disable SDCC features that conflict with the
+ standard.
+
+\layout Itemize
+
+\series bold
+std_sdcc99
+\series default
+
+\begin_inset LatexCommand \index{\#pragma std\_sdcc99}
+
+\end_inset
+
+- Generally follow the C99 standard, but allow SDCC features that conflict
+ with the standard (incomplete support).
+
+\layout Itemize
+
+\series bold
+std_c99
+\series default
+
+\begin_inset LatexCommand \index{\#pragma std\_c99}
+
+\end_inset
+
+- Follow the C99 standard and disable SDCC features that conflict with the
+ standard (incomplete support).
+
+\layout Itemize
+
+\series bold
+codeseg
+\series default
+ <name>
+\begin_inset LatexCommand \index{\#pragma codeseg}
+
+\end_inset
+
+- Use this name (max.
+ 8 characters) for the code segment.
+ See option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-codeseg.
+
+\layout Itemize
+
+\series bold
+constseg
+\series default
+ <name>
+\begin_inset LatexCommand \index{\#pragma constseg}
+
+\end_inset
+
+- Use this name (max.
+ 8 characters) for the const segment.
+ See option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-constseg.
+
+\layout Standard
+The preprocessor SDCPP
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
+
+\end_inset
+
+ supports the following #pragma directives:
+
+\layout Itemize
+
+\series bold
+pedantic_parse_number
+\series default
+
+\begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
+
+\end_inset
+
+ (+ | -) - Pedantic parse numbers so that situations like 0xfe-LO_B(3) are
+ parsed properly and the macro LO_B(3) gets expanded.
+ Default is off.
+ Below is an example on how to use this pragma.
+
+\emph on
+ Note: this functionality is not in conformance with standard!
+
+\layout Verse
+
+\family typewriter
+#pragma pedantic_parse_number +
+\begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
+
+\end_inset
+
+
+\newline
+
+\newline
+#define LO_B(x) ((x) & 0xff)
+\newline
+
+\newline
+unsigned char foo(void)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+unsigned char c=0xfe-LO_B(3)
+;
+\newline
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c;
+\newline
+}
+\newline
+
+
+\layout Itemize
+
+\series bold
+preproc_asm
+\series default
+
+\begin_inset LatexCommand \index{\#pragma preproc\_asm}
+
+\end_inset
+
+ (+ | -) - switch _asm _endasm block preprocessing on / off.
+ Default is on.
+ You use this prama to define multilines of assembly code.
+ This will prevent the preprocessor from changing the formating required
+ by assembly code.
+ Below is an example on how to use this pragma.
+
+\layout Verse
+
+\family typewriter
+#pragma preproc_asm -
+\begin_inset LatexCommand \index{\#pragma preproc\_asm}
+
+\end_inset
+
+
+\newline
+#define MYDELAY _asm
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+nop ;my assembly comment...
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+nop
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+nop
+\newline
+_endasm
+\newline
+#pragma preproc_asm
+ +
+\newline
+
+\newline
+void foo (void)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ MYDELAY;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ...
+
+\newline
+}
+\newline
+
+
+\layout Itemize
+
+\series bold
+sdcc_hash
+\series default
+
+\begin_inset LatexCommand \index{\#pragma sdcc\_hash}
+
+\end_inset
+
+ (+ | -) - Allow "naked" hash in macro definition, for example:
+\newline
+
+\family typewriter
+#define DIR_LO(x) #(x & 0xff)
+\family default
+
+\newline
+Default is off.
+ Below is an example on how to use this pragma.
+
+\layout Verse
+
+\family typewriter
+#pragma preproc_asm +
+\newline
+#pragma sdcc_hash +
+\begin_inset LatexCommand \index{\#pragma sdcc\_hash}
+
+\end_inset
+
+
+\newline
+
+\newline
+#define ROMCALL(x)
+\backslash
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov R6_B3, #(x & 0xff)
+\backslash
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov R7_B3, #((x >> 8) & 0xff)
+\backslash
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+lcall __romcall
+\newline
+
+\newline
+...
+\newline
+_asm
+\newline
+ROMCALL(72)
+\newline
+_endasm;
+\newline
+...
+\newline
+
+
+\layout Standard
+The pragma's are intended to be used to turn-on or off certain optimizations
+ which might cause the compiler to generate extra stack / data space to
+ store compiler generated temporary variables.
+ This usually happens in large functions.
+ Pragma directives should be used as shown in the following example, they
+ are used to control options & optimizations for a given function; pragmas
+ should be placed before and/or after a function, placing pragma's inside
+ a function body could have unpredictable results.
+
+\layout Verse
+
+\family typewriter
+#pragma save
+\begin_inset LatexCommand \index{\#pragma save}
+
+\end_inset
+
+ \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* save the current settings */
+\newline
+#pragma nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
+
+\end_inset
+
+ \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* turnoff global subexpression elimination */
+\newline
+#pragma noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+
+\end_inset
+
+ /* turn off induction optimizations */
+\newline
+int foo ()
+\newline
+{
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ /* large code */
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+}
+\newline
+#pragma restore
+\begin_inset LatexCommand \index{\#pragma restore}
+
+\end_inset
+
+ /* turn the optimizations back on */
+
+\layout Standard
+The compiler will generate a warning message when extra space is allocated.
+ It is strongly recommended that the save and restore pragma's be used when
+ changing options for a function.
+\newline
+
+\newline
+
+\newline
+
+
+\layout Section
+Defines Created by the Compiler
+
+\layout Standard
+The compiler creates the following #defines
+\begin_inset LatexCommand \index{\#defines}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Defines created by the compiler}
+
+\end_inset
+
+:
+\newline
+
+
+\layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="3in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\series bold
+#define
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\series bold
+Description
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC
+\begin_inset LatexCommand \index{SDCC}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Always defined.
+ Since version 2.5.6 the version number as an int (ex.
+ 256)
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC_mcs51
+\begin_inset LatexCommand \index{SDCC\_mcs51}
+
+\end_inset
+
+ or SDCC_ds390
+\begin_inset LatexCommand \index{SDCC\_ds390}
+
+\end_inset
+
+ or SDCC_z80
+\begin_inset LatexCommand \index{SDCC\_z80}
+
+\end_inset
+
+, etc.
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+depending on the model used (e.g.: -mds390)
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+__mcs51
+\begin_inset LatexCommand \index{\_\_mcs51}
+
+\end_inset
+
+, __ds390
+\begin_inset LatexCommand \index{\_\_ds390}
+
+\end_inset
+
+, __hc08
+\begin_inset LatexCommand \index{\_\_hc08}
+
+\end_inset
+
+, __z80
+\begin_inset LatexCommand \index{\_\_z80}
+
+\end_inset
+
+, etc
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+depending on the model used (e.g.
+ -mz80)
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC_STACK_AUTO
+\begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-stack-auto
+\emph default
+ option is used
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC_MODEL_SMALL
+\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-model-small
+\emph default
+ is used
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC_MODEL_MEDIUM
+\begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-model-medium
+\emph default
+ is used
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC_MODEL_LARGE
+\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-model-large
+\emph default
+ is used
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC_USE_XSTACK
+\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-xstack
+\emph default
+ option is used
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC_STACK_TENBIT
+\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+when
+\emph on
+-mds390
+\emph default
+ is used
+
+\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
+SDCC_MODEL_FLAT24
+\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
+
+\end_inset
+
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+when
+\emph on
+-mds390
+\emph default
+ is used
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+
+\layout Chapter
+Notes on supported Processors
+
+\layout Section
+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 Subsection
+pdata access by SFR
+
+\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
+\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
+
+
+\family default
+ at the appropriate location if the default, port P2, is not used for this.
+ Some examples are:
+
+\layout Verse
+
+\family typewriter
+__sfr __at (0x85) _XPAGE; /* Ramtron VRS51 family a.k.a.
+ MPAGE */
+
+\layout Verse
+
+\family typewriter
+__sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family, Texas Instruments (Chipcon)
+ a.k.a.
+ MPAGE */
+
+\layout Verse
+
+\family typewriter
+__sfr __at (0x91) _XPAGE; /* Infineon (Siemens) C500 family a.k.a.
+ XPAGE */
+
+\layout Verse
+
+\family typewriter
+__sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
+ EMI0CN */
+
+\layout Verse
+
+\family typewriter
+__sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips a.k.a.
+ EMI0CN */
+
+\layout Standard
+For more exotic implementations further customizations may be needed.
+ See section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
+\end_inset
+
+ for other possibilities.
+
+\layout Subsection
+Other Features available by SFR
+
+\layout Standard
+\added_space_bottom bigskip
+Some MCS51 variants offer features like Double DPTR
+\begin_inset LatexCommand \index{DPTR}
+
+\end_inset
+
+, 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
+DS400 port
+
+\layout Standard
+\added_space_bottom bigskip
+The DS80C400
+\begin_inset LatexCommand \index{DS80C400}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{DS400}
+
+\end_inset
+
+ 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
+
+\begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
+
+\end_inset
+
+.
+
+
+
+
+\layout Section
+The Z80 and gbz80 port
+
+\layout Standard
+SDCC can target both the Zilog Z80
+\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 Z80 port is passed through the same
+\emph on
+regressions tests
+\begin_inset LatexCommand \index{Regression test}
+
+\end_inset
+
+
+\emph default
+ (see section
+\begin_inset LatexCommand \ref{sec:Quality-control}
+
+\end_inset
+
+) 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
+\added_space_bottom bigskip
+As always, the code is the authoritative reference - see z80/ralloc.c and
+ z80/gen.c.
+ The stack
+\begin_inset LatexCommand \index{Z80!stack}
+
+\end_inset
+
+ 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{Z80!return value}
+
+\end_inset
+
+ 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
+The HC08 port
+
+\layout Standard
+The port to the Freescale/Motorola HC08
+\begin_inset LatexCommand \index{HC08}
+
+\end_inset
+
+ 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.
+
+\layout Standard
+\pagebreak_bottom
+\added_space_bottom bigskip
+The HC08 port passes the regression test suite (see section
+\begin_inset LatexCommand \ref{sec:Quality-control}
+
+\end_inset
+
+).
+
+
+
+
+\layout Section
+The PIC14 port
+
+\layout Standard
+The 14bit PIC
+\begin_inset LatexCommand \index{PIC14}
+
+\end_inset
+
+ port still requires a major effort from the development community.
+ However it can work for simple code.
+ It passes its (smaller set of) regression tests
+\begin_inset LatexCommand \index{Regression test (PIC14)}
+
+\end_inset
+
+ in the directory
+\shape italic
+sdcc/src/regression
+\shape default
+.
+
+\layout Subsection
+C code and 14bit PIC code page
+\begin_inset LatexCommand \index{code page (pic14)}
+
+\end_inset
+
+ and RAM banks
+\begin_inset LatexCommand \index{RAM bank (pic14)}
+
+\end_inset
+
+
+
+\layout Standard
+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.
+\newline
+
+\newline
+To get the best follow these guide lines:
+
+\layout Enumerate
+Make local functions static, as non static functions require code page 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 there's less page selection overhead.
+
+\layout Enumerate
+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
+Creating a device include file
+
+\layout Standard
+For generating a device include file
+\begin_inset LatexCommand \index{PIC14!Header files}
+
+\end_inset
+
+ use the support perl script inc2h.pl kept in directory support/script.
+
+\layout Subsection
+Interrupt code
+
+\layout Standard
+For the interrupt function, use the keyword '__interrupt'
+\begin_inset LatexCommand \index{PIC14!interrupt}
+
+\end_inset
+
+ 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
+
+\family typewriter
+void Intr(void) __interrupt 0
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+T0IF = 0; /* Clear timer interrupt */
+\newline
+}
+
+\layout Subsection
+Linking and assembling
+
+\layout Standard
+For assembling you can use either GPUTILS'
+\begin_inset LatexCommand \index{gputils (pic tools)}
+
+\end_inset
+
+ gpasm.exe or MPLAB's mpasmwin.exe.
+ GPUTILS is available from
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
+
+\end_inset
+
+.
+ 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
+Makefile
+\family default
+ using GPUTILS:
+
+\layout Verse
+
+\family typewriter
+.c.o:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcc -S -V -mpic14 -p16F877 $<
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+gpasm -c $*.asm
+\newline
+
+\newline
+$(PRJ).hex: $(OBJS)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+gplink
+ -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
+
+\layout Standard
+Here is a
+\family typewriter
+Makefile
+\family default
+ using MPLAB:
+
+\layout Verse
+
+\family typewriter
+.c.o:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcc -S -V -mpic14 -p16F877 $<
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mpasmwin /q /o $*.asm
+\newline
+
+\newline
+$(PRJ).hex: $(OBJS)
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
+
+\layout Standard
+Please note that indentations within a
+\family typewriter
+ Makefile
+\family default
+ have to be done with a tabulator character.
+
+\layout Subsection
+Command-line options
+
+\layout Standard
+Besides the switches common to all SDCC backends, the PIC14 port accepts
+ the following options (for an updated list see sdcc -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-help):
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-debug-extra
+\begin_inset LatexCommand \index{PIC14!Options!-\/-debug-extra}
+
+\end_inset
+
+ emit debug info in assembly output
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-no-pcode-opt
+\begin_inset LatexCommand \index{PIC14!Options!-\/-no-pcode-opt}
+
+\end_inset
+
+ disable (slightly faulty) optimization on pCode
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-stack-loc
+\begin_inset LatexCommand \index{PIC14!Options!-\/-stack-loc}
+
+\end_inset
+
+ sets the lowest address of the argument passing stack (defaults to a suitably
+ large shared databank to reduce BANKSEL overhead)
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-stack-size
+\begin_inset LatexCommand \index{PIC14!Options!-\/-stack-size}
+
+\end_inset
+
+ sets the size if the argument passing stack (default: 16, minimum: 4)
+
+\layout Subsection
+The library
+
+\layout Subsubsection
+error: missing definition for symbol
+\begin_inset Quotes sld
+\end_inset
+
+__gptrget1
+\begin_inset Quotes srd
+\end_inset
+
+
+
+\layout Standard
+The PIC14 port uses library routines to provide more complex operations
+ like multiplication, division/modulus and (generic) pointer dereferencing.
+ In order to add these routines to your project, you must link with PIC14's
+
+\family typewriter
+libsdcc.lib
+\family default
+.
+ For single source file projects this is done automatically, more complex
+ projects must add
+\family typewriter
+libsdcc.lib
+\family default
+ to the linker's arguments.
+ Make sure you also add an include path for the library (using the -I switch
+ to the linker)!
+
+\layout Subsubsection
+Processor mismatch in file
+\begin_inset Quotes sld
+\end_inset
+
+XXX
+\begin_inset Quotes srd
+\end_inset
+
+.
+
+\layout Standard
+This warning can usually be ignored due to the very good compatibility amongst
+ 14 bit PIC
+\begin_inset LatexCommand \index{PIC14}
+
+\end_inset
+
+ devices.
+
+\layout Standard
+You might also consider recompiling the library for your specific device
+ by changing the ARCH=p16f877 (default target) entry in
+\family typewriter
+device/lib/pic/Makefile.in
+\family default
+ and
+\family typewriter
+device/lib/pic/Makefile
+\family default
+ to reflect your device.
+ This might even improve performance for smaller devices as unneccesary
+ BANKSELs migth be removed.
+
+\layout Subsection
+Known bugs
+
+\layout Subsubsection
+initialized data
+
+\layout Standard
+\pagebreak_bottom
+Currently, data can only be initialized if it resides in the source file
+ together with
+\emph on
+main()
+\emph default
+.
+ Data in other source files will silently
+\series bold
+not
+\series default
+ be initialized.
+\family typewriter
+\size footnotesize
+
+\begin_inset Marginal
+collapsed true
+
+\layout Standard
+
+\series bold
+\SpecialChar ~
+!
+
+\end_inset
+
+
+\family default
+
+
+
+\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.
+ Currently supported devices are:
+
+\layout Standard
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="6">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="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">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F242
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F248
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F252
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F258
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F442
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F448
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F452
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F458
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F1220
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F2220
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F2550
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F4331
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F4455
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F6520
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F6620
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F6680
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F6720
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F8520
+
+\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
+18F8620
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F8680
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+18F8720
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+
+\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
+
+-callee-saves
+\begin_inset LatexCommand \index{PIC16!Options!-\/-callee-saves}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{PIC16!Options!-\/-all-callee-saves}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{PIC16!Options!-\/-fommit-frame-pointer}
+
+\end_inset
+
+ 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
+
+-pstack-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 List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-mplab-comp MPLAB
+\begin_inset LatexCommand \index{PIC16!MPLAB}
+
+\end_inset
+
+ compatibility option.
+ Currently only suppresses special gpasm directives.
+
+\layout Subsubsection
+Optimization Options
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-optimize-goto Try to use (conditional) BRA instead of GOTO
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-optimize-cmp Try to optimize some compares.
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-optimize-df Analyze the dataflow of the generated code and improve it.
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-obanksel=nn Set optimization level for inserting BANKSELs.
+\newline
+
+
+\begin_deeper
+\layout List
+\labelwidthstring 00.00.0000
+0 no optimization
+
+\layout List
+\labelwidthstring 00.00.0000
+1 checks previous used register and if it is the same then does not emit
+ BANKSEL, accounts only for labels.
+
+\layout List
+\labelwidthstring 00.00.0000
+2 tries to check the location of (even different) symbols and removes BANKSELs
+ if they are in the same bank.
+
+\newline
+
+\emph on
+Important: There might be problems if the linker script has data sections
+ across bank borders!
+
+\end_deeper
+\layout Subsubsection
+Linking Options
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-nodefaultlibs do not link default libraries when linking
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-no-crt Don't link the default run-time modules
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-use-crt= Use a custom run-time module instead of the defaults.
+
+\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 List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-denable-peeps Force the usage of peepholes.
+ Use with care.
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-gstack Trace push/pops for stack pointer overflow
+
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-call-tree dump call tree in .calltree file
+
+\layout Subsection
+Enviromental Variables
+
+\layout Standard
+There is a number of enviromental variables that can be used when running
+ SDCC to enable certain optimizations or force a specific program behaviour.
+ these variables are primarily for debugging purposes so they can be enabled/dis
+abled at will.
+
+\layout Standard
+Currently there is only two such variables available:
+
+\layout List
+\labelwidthstring 00.00.0000
+OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
+ bitfields is optimized by directly loading FSR0 with the address of the
+ bitfield structure.
+ Normally SDCC will cast the bitfield structure to a bitfield pointer and
+ then load FSR0.
+ This step saves data ram and code space for functions that perform heavy
+ use of bitfields.
+ (ie.
+ 80 bytes of code space are saved when compiling malloc.c with this option).
+
+
+\layout List
+\labelwidthstring 00.00.0000
+NO_REG_OPT do not perform pCode registers optimization.
+ This should be used for debugging purposes.
+ In some where bugs in the pcode optimizer are found, users can benefit
+ from temporarily disabling the optimizer until the bug is fixed.
+
+\layout Subsection
+Preprocessor Macros
+
+\layout Standard
+PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port defines the following preprocessor macros while translating a source.
+
+\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
+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">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC_pic16
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Port identification
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+_
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+_pic16
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Port identification (same as above)
+
+\end_inset
+</cell>
+</row>
+<row topline="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>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+_
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+_18Fxxxx
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+MCU Identification (same as above)
+
+\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
+STACK_MODEL_nnn
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+nnn = SMALL or LARGE respectively according to the stack model used
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+
+\layout Standard
+In addition the following macros are defined when calling assembler:
+
+\layout Standard
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" 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">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+__18Fxxxx
+
+\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>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SDCC_MODEL_nnn
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+nnn = SMALL or LARGE respectively according to the memory model used for
+ SDCC
+
+\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
+STACK_MODEL_nnn
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+nnn = SMALL or LARGE respectively according to the stack model used
+
+\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
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port currently supports the following pragmas:
+
+\layout List
+\labelwidthstring 00.00.0000
+stack
+\begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma stack}
+
+\end_inset
+
+ pragma stack
+\begin_inset LatexCommand \index{PIC16!stack}
+
+\end_inset
+
+ forces the code generator to initialize the stack & frame pointers at a
+ specific address.
+ This is an adhoc solution for cases where no STACK directive is available
+ in the linker script or gplink is not instructed to create a stack section.
+\newline
+The
+ stack pragma should be used only once in a project.
+ Multiple pragmas may result in indeterminate behaviour of the program.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+The old format (ie.
+ #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
+ cross page boundaries (or even exceed the available data RAM) and crash
+ the program.
+ Make sure that stack does not cross page boundaries when using the SMALL
+ stack model.
+
+\end_inset
+
+
+\newline
+The format is as follows:
+
+\layout LyX-Code
+#pragma stack bottom_address [stack_size]
+
+\layout Standard
+
+\emph on
+bottom_address
+\emph default
+ is the lower bound of the stack section.
+ The stack pointer initially will point at address (bottom_address+stack_size-1).
+
+\layout LyX-Code
+Example:
+
+\layout LyX-Code
+
+
+\layout LyX-Code
+/* initializes stack of 100 bytes at RAM address 0x200 */
+
+\layout LyX-Code
+#pragma stack 0x200 100
+
+\layout Standard
+If the stack_size field is omitted then a stack is created with the default
+ size of 64.
+ This size might be enough for most programs, but its not enough for operations
+ with deep function nesting or excessive stack usage.
+
+\layout List
+\labelwidthstring 00.00.0000
+code
+\begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma code}
+
+\end_inset
+
+ place a function symbol at static FLASH address
+
+\layout LyX-Code
+Example:
+
+\layout LyX-Code
+
+
+\layout LyX-Code
+/* place function test_func at 0x4000 */
+
+\layout LyX-Code
+#pragma code test_func 0x4000
+
+\layout LyX-Code
+
+
+\layout List
+\labelwidthstring 00.00.0000
+library instructs the linker to use a library module.
+\newline
+Usage:
+
+\layout LyX-Code
+#pragma library module_name
+
+\layout Standard
+
+\emph on
+module_name
+\emph default
+ can be any library or object file (including its path).
+ Note that there are four reserved keywords which have special meaning.
+ These are:
+
+\layout Standard
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="block" valignment="top" leftline="true" width="20page%">
+<column alignment="left" 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
+Keyword
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="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
+Module to link
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\series bold
+ignore
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+ignore all library pragmas
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\emph on
+(none)
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\series bold
+c
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+link the C library
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\emph on
+libc18f
+\emph default
+.lib
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\series bold
+math
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+link the Math libarary
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\emph on
+libm18f
+\emph default
+.lib
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\series bold
+io
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+link the I/O library
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\emph on
+libio18f*
+\emph default
+.lib
+
+\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
+
+\series bold
+debug
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+link the debug library
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\emph on
+libdebug
+\emph default
+.lib
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+* is the device number, i.e.
+ 452 for PIC18F452 MCU.
+
+\layout Standard
+This feature allows for linking with specific libraries withoug having to
+ explicit name them in the command line.
+ Note that the
+\noun on
+ignore
+\noun default
+ keyword will reject all modules specified by the library pragma.
+
+\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 extra SECTION directives should be added
+ in the .lkr script.
+ 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 # these SECTION directives
+
+\layout LyX-Code
+SECTION NAME=bank1 RAM=gpr1 # should be added to link
+
+\layout LyX-Code
+SECTION NAME=bank2 RAM=gpr2 # section name 'bank?' with
+
+\layout LyX-Code
+SECTION NAME=bank3 RAM=gpr3 # a specific DATABANK name
+
+\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
+\begin_inset LatexCommand \index{PIC16!Header files}
+
+\end_inset
+
+ that can be included to the source files using the pic16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{PIC16!Libraries}
+
+\end_inset
+
+ 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://sourceforge.net/projects/gputils}
+
+\end_inset
+
+.
+
+\layout Subsubsection*
+Building the libraries
+
+\layout Standard
+Before using SDCC/pic16 there are some libraries that need to be compiled.
+ This process is not done automatically by SDCC since not all users use
+ SDCC for pic16 projects.
+ So each user should compile the libraries separately.
+
+\layout Standard
+The steps to compile the pic16 libraries under Linux are:
+
+\layout LyX-Code
+cd device/lib/pic16
+
+\layout LyX-Code
+./configure
+
+\layout LyX-Code
+make
+
+\layout LyX-Code
+cd ..
+
+\layout LyX-Code
+make model-pic16
+
+\layout LyX-Code
+su -c 'make install' # install the libraries, you need the root password
+
+\layout Standard
+If you need to install the headers too, do:
+
+\layout LyX-Code
+cd device/include
+
+\layout LyX-Code
+su -c 'make install' # install the headers, you need the root password
+
+\layout Standard
+There exist a special target to build the I/O libraries.
+ This target is not automatically build because it will build the I/O library
+ for
+\emph on
+every
+\emph default
+ supported device.
+ This way building will take quite a lot of time.
+ Users are advised to edit the
+\series bold
+device/lib/pic16/pics.build
+\series default
+ file and then execute:
+
+\layout LyX-Code
+make lib-io
+
+\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
+\begin_inset LatexCommand \index{PIC16!stack}
+
+\end_inset
+
+ 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
+
+\noun on
+small
+\noun default
+ model
+
+\layout Itemize
+
+\noun on
+large
+\noun default
+ 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
+
+\noun on
+Large
+\noun default
+stack model is currently not working properly throughout the code generator.
+ So its use is not advised.
+ Also there are some other points that need special care:
+\newline
+
+
+\layout Enumerate
+Do not create stack sections with size more than one physical bank (that
+ is 256 bytes)
+
+\layout Enumerate
+Stack sections should no cross physical bank limits (i.e.
+ #pragma stack 0x50 0x100)
+
+\layout Standard
+These limitations are caused by the fact that only FSRxL is modified when
+ using SMALL stack model, so no more than 256 bytes of stack can be used.
+ This problem will disappear after LARGE model is fully implemented.
+
+\layout Subsection
+Functions
+
+\layout Standard
+In addition to the standard SDCC function keywords, PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port makes available two more:
+
+\layout List
+\labelwidthstring 00.00.0000
+wparam
+\begin_inset LatexCommand \index{PIC16!wparam}
+
+\end_inset
+
+ Use the WREG to pass one byte of the first function argument.
+ This improves speed but you may not use this for functions with arguments
+ that are called via function pointers, otherwise the first byte of the
+ first parameter will get lost.
+ Usage:
+
+\layout LyX-Code
+void func_wparam(int a) wparam
+
+\layout LyX-Code
+{
+
+\layout LyX-Code
+ /* WREG hold the lower part of a */
+
+\layout LyX-Code
+ /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
+ */
+
+\layout LyX-Code
+...
+
+\layout LyX-Code
+}
+
+\layout List
+\labelwidthstring 00.00.0000
+shadowregs
+\begin_inset LatexCommand \index{PIC16!shadowregs}
+
+\end_inset
+
+ When entering/exiting an ISR, it is possible to take advantage of the PIC18F
+ hardware shadow registers which hold the values of WREG, STATUS and BSR
+ registers.
+ This can be done by adding the keyword
+\emph on
+shadowregs
+\emph default
+ before the
+\emph on
+interrupt
+\emph default
+ keyword in the function's header.
+
+\layout LyX-Code
+void isr_shadow(void) shadowregs interrupt 1
+
+\layout LyX-Code
+{
+
+\layout LyX-Code
+...
+
+\layout LyX-Code
+}
+
+\layout Standard
+
+\emph on
+shadowregs
+\emph default
+ instructs the code generator not to store/restore WREG, STATUS, BSR when
+ entering/exiting the ISR.
+
+\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
+An interrupt
+\begin_inset LatexCommand \index{PIC16!interrupt}
+
+\end_inset
+
+ service routine (ISR) is declared using the
+\emph on
+interrupt
+\emph default
+ keyword.
+
+\layout LyX-Code
+void isr(void) interrupt
+\emph on
+n
+
+\layout LyX-Code
+{
+
+\layout LyX-Code
+...
+
+\layout LyX-Code
+}
+
+\layout Standard
+
+\emph on
+n
+\emph default
+ is the interrupt number, which for PIC18F devices can be:
+
+\layout Standard
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="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
+
+\emph on
+n
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Interrupt Vector
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Interrupt Vector Address
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+RESET vector
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0x000000
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+HIGH priority interrupts
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0x000008
+
+\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
+2
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+LOW priority interrupts
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0x000018
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+
+\layout Standard
+When generating assembly code for ISR the code generator places a
+\noun on
+goto
+\noun default
+instruction at the
+\emph on
+Interrupt Vector Address
+\emph default
+ which points at the genetated ISR.
+ This single GOTO instruction is part of an automatically generated
+\emph on
+interrupt entry point
+\emph default
+ function.
+ The actuall ISR code is placed as normally would in the code space.
+ Upon interrupt request, the GOTO instruction is executed which jumps to
+ the ISR code.
+ When declaring interrupt functions as _naked this GOTO instruction is
+\series bold
+not
+\series default
+ generated.
+ The whole interrupt functions is therefore placed at the Interrupt Vector
+ Address of the specific interrupt.
+ This is not a problem for the LOW priority interrupts, but it is a problem
+ for the RESET and the HIGH priority interrupts because code may be written
+ at the next interrupt´s vector address and cause undeterminate program
+ behaviour if that interrupt is raised.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+This is not a problem when
+
+\layout Enumerate
+this is a HIGH interrupt ISR and LOW interrupts are
+\emph on
+disabled
+\emph default
+ or not used.
+
+\layout Enumerate
+when the ISR is small enough not to reach the next interrupt´s vector address.
+
+\end_inset
+
+
+
+\layout Standard
+
+\emph on
+n
+\emph default
+ is possible to be omitted.
+ This way a function is generated similar to an ISR, but it is not assigned
+ to any interrupt.
+
+\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.
+\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 Subsection
+Generic Pointers
+
+\layout Standard
+Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
+ There are 3 types of generic pointers currently implemented data, code
+ and eeprom pointers.
+ They are differentiated by the value of the 7th and 6th bits of the upper
+ byte:
+
+\layout Standard
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="5">
+<features>
+<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">
+<column alignment="center" valignment="top" width="0">
+<column alignment="left" valignment="top" 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 type
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+7th bit
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+6th bit
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+rest of the pointer
+
+\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
+data
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family typewriter
+\shape slanted
+\emph on
+uuuuuu uuuuxxxx xxxxxxxx
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+a 12-bit data pointer in data RAM memory
+
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+code
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family typewriter
+\shape slanted
+\emph on
+uxxxxx xxxxxxxx xxxxxxxx
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+a 21-bit code pointer in FLASH memory
+
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+eeprom
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family typewriter
+\shape slanted
+\emph on
+uuuuuu uuuuuuxx xxxxxxxx
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+a 10-bit eeprom pointer in EEPROM memory
+
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+(unimplemented)
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family typewriter
+\shape slanted
+\emph on
+xxxxxx xxxxxxxx xxxxxxxx
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+unimplemented pointer type
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+
+\layout Standard
+Generic pointer are read and written with a set of library functions which
+ read/write 1, 2, 3, 4 bytes.
+
+\layout Subsection
+PIC16 C Libraries
+
+\layout Subsubsection
+Standard I/O Streams
+
+\layout Standard
+In the
+\emph on
+stdio.h
+\emph default
+ the type FILE is defined as:
+
+\layout LyX-Code
+typedef char * FILE;
+
+\layout Standard
+This type is the stream type implemented I/O in the PIC18F devices.
+ Also the standard input and output streams are declared in stdio.h:
+
+\layout LyX-Code
+extern FILE * stdin;
+
+\layout LyX-Code
+extern FILE * stdout;
+
+\layout Standard
+The FILE type is actually a generic pointer which defines one more type
+ of generic pointers, the
+\emph on
+stream
+\emph default
+pointer.
+ This new type has the format:
+
+\layout Standard
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="7">
+<features>
+<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" width="0">
+<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="left" valignment="top" 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 type
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+<7:6>
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+<5>
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+<4>
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+<3:0>
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+rest of the pointer
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+descrption
+
+\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
+stream
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+00
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+0
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+nnnn
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family typewriter
+\shape slanted
+\emph on
+uuuuuuuu uuuuuuuu
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+upper byte high nubble is 0x2n, the rest are zeroes
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+
+\layout Standard
+Currently implemented there are 3 types of streams defined:
+
+\layout Standard
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="4">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="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
+stream type
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+value
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+module
+
+\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">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+STREAM_USART
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family typewriter
+0x200000UL
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+USART
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Writes/Reads characters via the USART peripheral
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+STREAM_MSSP
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family typewriter
+0x210000UL
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+MSSP
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Writes/Reads characters via the MSSP peripheral
+
+\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
+STREAM_USER
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\family typewriter
+0x2f0000UL
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+(none)
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Writes/Reads characters via used defined functions
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+
+\layout Standard
+The stream identifiers are declared as macros in the stdio.h header.
+
+\layout Standard
+In the libc library there exist the functions that are used to write to
+ each of the above streams.
+ These are
+
+\layout List
+\labelwidthstring 00.00.0000
+_
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+_stream_usart_putchar writes a character at the USART stream
+
+\layout List
+\labelwidthstring 00.00.0000
+_
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+_stream_mssp_putchar writes a character at the MSSP stream
+
+\layout List
+\labelwidthstring 00.00.0000
+putchar dummy function.
+ This writes a character to a user specified manner.
+
+\layout Standard
+In order to increase performance
+\emph on
+putchar
+\emph default
+is declared in stdio.h as having its parameter in WREG (it has the wparam
+ keyword).
+ In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
+ in a user-friendly way.
+
+\emph on
+arg
+\emph default
+ is the name of the variable that holds the character to print.
+ An example follows:
+
+\layout LyX-Code
+#include <pic18fregs.h>
+\newline
+#include <stdio.h>
+\newline
+
+\newline
+PUTCHAR( c )
+
+\layout LyX-Code
+{
+
+\layout LyX-Code
+ PORTA = c; /* dump character c to PORTA */
+
+\layout LyX-Code
+}
+\newline
+
+\newline
+void main(void)
+
+\layout LyX-Code
+{
+
+\layout LyX-Code
+ stdout = STREAM_USER; /* this is not necessary, since stdout points
+
+\layout LyX-Code
+ * by default to STREAM_USER */
+
+\layout LyX-Code
+ printf (¨This is a printf test
+\backslash
+n¨);
+
+\layout LyX-Code
+}
+
+\layout LyX-Code
+
+
+\layout Subsubsection
+Printing functions
+
+\layout Standard
+PIC16 contains an implementation of the printf-family of functions.
+ There exist the following functions:
+
+\layout LyX-Code
+extern unsigned int sprintf(char *buf, char *fmt, ...);
+
+\layout LyX-Code
+extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
+
+\layout LyX-Code
+
+
+\layout LyX-Code
+extern unsigned int printf(char *fmt, ...);
+
+\layout LyX-Code
+extern unsigned int vprintf(char *fmt, va_lista ap);
+
+\layout LyX-Code
+
+
+\layout LyX-Code
+extern unsigned int fprintf(FILE *fp, char *fmt, ...);
+
+\layout LyX-Code
+extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
+
+\layout Standard
+For sprintf and vsprintf
+\emph on
+buf
+\emph default
+should normally be a data pointer where the resulting string will be placed.
+ No range checking is done so the user should allocate the necessery buffer.
+ For fprintf and vfprintf
+\emph on
+fp
+\emph default
+ should be a stream pointer (i.e.
+ stdout, STREAM_MSSP, etc...).
+
+\layout Subsubsection
+Signals
+
+\layout Standard
+The PIC18F family of microcontrollers supports a number of interrupt sources.
+ A list of these interrupts is shown in the following table:
+
+\layout Standard
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" columns="4">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="left" 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
+signal name
+
+\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
+signal name
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+descritpion
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_RB
+
+\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+PORTB change interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_EE
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+EEPROM/FLASH write complete interrupt
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_INT0
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+INT0 external interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_BCOL
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Bus collision interrupt
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_INT1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+INT1 external interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_LVD
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Low voltage detect interrupt
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_INT2
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+INT2 external interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_PSP
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+Parallel slave port interrupt
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_CCP1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+CCP1 module interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_AD
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+AD convertion complete interrupt
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_CCP2
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+CCP2 module interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_RC
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+USART receive interrupt
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_TMR0
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+TMR0 overflow interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_TX
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+USART transmit interrupt
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_TMR1
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+TMR1 overflow interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_MSSP
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SSP receive/transmit interrupt
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+SIG_TMR2
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+TMR2 matches PR2 interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\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
+SIG_TMR3
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+TMR3 overflow interrupt
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+
+\layout Standard
+The prototypes for these names are defined in the header file
+\emph on
+signal.h
+\emph default
+ .
+
+\layout Standard
+In order to simplify signal handling, a number of macros is provided:
+
+\layout List
+\labelwidthstring 00.00.0000
+DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
+ high priority interrupts.
+
+\emph on
+name
+\emph default
+ is the function name to use.
+
+\layout List
+\labelwidthstring 00.00.0000
+DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
+ low priority interrupt.
+
+\emph on
+name
+\emph default
+ is the function name to use.
+
+\layout List
+\labelwidthstring 00.00.0000
+DEF_HANDLER(sig,handler) define a handler for signal
+\emph on
+sig.
+
+\layout List
+\labelwidthstring 00.00.0000
+END_DEF end the declaration of the dispatch table.
+
+\layout Standard
+Additionally there are two more macros to simplify the declaration of the
+ signal handler:
+
+\layout List
+\labelwidthstring 00.00.0000
+
+\series medium
+SIGHANDLER(handler)
+\series default
+this declares the function prototype for the
+\emph on
+handler
+\emph default
+ function.
+
+\layout List
+\labelwidthstring 00.00.0000
+SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
+
+\layout Standard
+An example of using the macros above is shown below:
+
+\layout LyX-Code
+#include <pic18fregs.h>
+
+\layout LyX-Code
+#include <signal.h>
+\newline
+
+\newline
+DEF_INTHIGH(high_int)
+
+\layout LyX-Code
+DEF_HANDLER(SIG_TMR0, _tmr0_handler)
+
+\layout LyX-Code
+DEF_HANDLER(SIG_BCOL, _bcol_handler)
+
+\layout LyX-Code
+END_DEF
+\newline
+
+\newline
+SIGHANDLER(_tmr0_handler)
+
+\layout LyX-Code
+{
+
+\layout LyX-Code
+ /* action to be taken when timer 0 overflows */
+
+\layout LyX-Code
+}
+\newline
+
+\newline
+SIGHANDLERNAKED(_bcol_handler)
+
+\layout LyX-Code
+{
+
+\layout LyX-Code
+ _asm
+
+\layout LyX-Code
+ /* action to be taken when bus collision occurs */
+
+\layout LyX-Code
+ retfie
+
+\layout LyX-Code
+ _endasm;
+
+\layout LyX-Code
+}
+
+\layout Standard
+
+\series bold
+NOTES:
+\series default
+ Special care should be taken when using the above scheme:
+
+\layout Itemize
+do not place a colon (;) at the end of the DEF_* and END_DEF macros.
+
+\layout Itemize
+when declaring SIGHANDLERNAKED handler never forget to use
+\emph on
+retfie
+\emph default
+ for proper returning.
+
+\layout Subsection
+PIC16 Port -- Tips
+
+\layout Standard
+Here you can find some general tips for compiling programs with SDCC/pic16.
+
+\layout Subsubsection
+Stack size
+
+\layout Standard
+The default stack
+\begin_inset LatexCommand \index{PIC16!stack}
+
+\end_inset
+
+ size (that is 64 bytes) probably is enough for many programs.
+ One must take care that when there are many levels of function nesting,
+ or there is excessive usage of stack, its size should be extended.
+ An example of such a case is the printf/sprintf family of functions.
+ If you encounter problems like not being able to print integers, then you
+ need to set the stack size around the maximum (256 for small stack model).
+ The following diagram shows what happens when calling printf to print an
+ integer:
+
+\layout LyX-Code
+printf () --> ltoa () --> ultoa () --> divschar ()
+
+\layout Standard
+It is should be understood that stack is easily consumed when calling complicate
+d functions.
+ Using command line arguments like -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-fommit-frame-pointer might reduce stack usage by not creating unnecessery
+ stack frames.
+ Other ways to reduce stack usage may exist.
+
+\layout Subsection
+Known bugs
+
+\layout Standard
+The PIC16 Port currently does not pass SDCC's regression test
+\begin_inset LatexCommand \index{Regression test (PIC16)}
+
+\end_inset
+
+ suite (see section
+\begin_inset LatexCommand \ref{sec:Quality-control}
+
+\end_inset
+
+) and thus the nightly regression tests for the PIC16 target are currently
+ disabled for all hosts except for
+\emph on
+Linux on Opteron.
+
+\emph default
+ This means you can see the result of the PIC16 regression tests f.e.
+ by checking the log files in
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/regression_test_results/amd64-unknown-linux2.3/}
+
+\end_inset
+
+ (pick the most up to date file there, scroll down, lend a hand).
+
+\layout Chapter
+Debugging
+
+\layout Standard
+There are several approaches to debugging your code.
+ This chapter is meant to show your options and to give detail on some of
+ them:
+\newline
+
+\newline
+When writing your code:
+
+\layout Itemize
+write your code with debugging in mind (avoid duplicating code, put conceptually
+ similar variables into structs, use structured code, have strategic points
+ within your code where all variables are consistent, ...)
+
+\layout Itemize
+run a syntax-checking tool like splint
+\begin_inset LatexCommand \index{splint (syntax checking tool)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{lint (syntax checking tool)}
+
+\end_inset
+
+ (see -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-more-pedantic
+\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
+
+\end_inset
+
+) over the code.
+
+\layout Itemize
+for the high level code use a C-compiler (like f.e.
+ GCC) to compile run and debug the code on your host.
+ See (see -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+-more-pedantic
+\begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
+
+\end_inset
+
+ ) on howto handle syntax extensions like __xdata, __at(), ...
+
+
+\layout Itemize
+use another C-compiler to compile code for your target.
+ Always an option but not recommended:) And not very likely to help you.
+ If you seriously consider walking this path you should at least occasionally
+ check portability of your code.
+ Most commercial compiler vendors will offer an evaluation version so you
+ can test compile your code or snippets of your code.
+
+\layout Standard
+Debugging on a simulator:
+
+\layout Itemize
+there is a separate section about SDCDB (section
+\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
+
+\end_inset
+
+) below.
+
+\layout Itemize
+or (8051 specific) use a freeware/commercial simulator which interfaces
+ to the AOMF
+\begin_inset LatexCommand \index{AOMF, AOMF51}
+
+\end_inset
+
+ file (see
+\begin_inset LatexCommand \ref{OMF file}
+
+\end_inset
+
+) optionally generated by SDCC.
+
+\layout Standard
+Debugging On-target:
+
+\layout Itemize
+use a MCU port pin to serially output debug data to the RS232 port of your
+ host.
+ You'll probably want some level shifting device typically involving a MAX232
+ or similar IC.
+ If the hardware serial port of the MCU is not available search for 'Software
+ UART' in your favourite search machine.
+
+\layout Itemize
+use an on-target monitor.
+ In this context a monitor is a small program which usually accepts commands
+ via a serial line and allows to set program counter, to single step through
+ a program and read/write memory locations.
+ For the 8051 good examples of monitors are paulmon and cmon51 (see section
+
+\begin_inset LatexCommand \ref{sec:Related-open-source-tools}
+
+\end_inset
+
+).
+
+\layout Itemize
+toggle MCU port pins at strategic points within your code and use an oscilloscop
+e.
+ A
+\emph on
+digital oscilloscope
+\emph default
+
+\begin_inset LatexCommand \index{Oscilloscope}
+
+\end_inset
+
+ with deep trace memory is really helpful especially if you have to debug
+ a realtime application.
+ If you need to monitor more pins than your oscilloscope provides you can
+ sometimes get away with a small R-2R network.
+ On a single channel oscilloscope you could f.e.
+ monitor 2 push-pull driven pins by connecting one via a 10\SpecialChar ~
+k
+\begin_inset Formula $\Omega$
+\end_inset
+
+ resistor and the other one by a 5\SpecialChar ~
+k
+\begin_inset Formula $\Omega$
+\end_inset
+
+ resistor to the oscilloscope probe (check output drive capability of the
+ pins you want to monitor).
+ If you need to monitor many more pins a
+\emph on
+logic analyzer
+\emph default
+ will be handy.
+
+\layout Itemize
+use an ICE (
+\emph on
+i
+\emph default
+n
+\emph on
+c
+\emph default
+ircuit
+\emph on
+e
+\emph default
+mulator
+\begin_inset LatexCommand \index{ICE (in circuit emulator)}
+
+\end_inset
+
+).
+ Usually very expensive.
+ And very nice to have too.
+ And usually locks you (for years...) to the devices the ICE can emulate.
+
+
+\layout Itemize
+use a remote debugger.
+ In most 8-bit systems the symbol information is not available on the target,
+ and a complete debugger is too bulky for the target system.
+ Therefore usually a debugger on the host system connects to an on-target
+ debugging stub which accepts only primitive commands.
+
+\newline
+Terms to enter into your favourite search engine could be 'remote debugging',
+ 'gdb stub' or 'inferior debugger'.
+ (is there one?)
+
+\layout Itemize
+use an on target hardware debugger.
+ Some of the more modern MCUs include hardware support for setting break
+ points and monitoring/changing variables by using dedicated hardware pins.
+ This facility doesn't require additional code to run on the target and
+
+\emph on
+usually
+\emph default
+ doesn't affect runtime behaviour until a breakpoint is hit.
+ For the mcs51 most hardware debuggers use the AOMF
+\begin_inset LatexCommand \index{AOMF, AOMF51}
+
+\end_inset
+
+ file (see
+\begin_inset LatexCommand \ref{OMF file}
+
+\end_inset
+
+) as input file.
+
+
+\layout Standard
+Last not least:
+
+\layout Itemize
+if you are not familiar with any of the following terms you're likely to
+ run into problems rather sooner than later:
+\emph on
+volatile
+\emph default
+,
+\emph on
+atomic
+\emph default
+,
+\emph on
+memory map
+\emph default
+,
+\emph on
+overlay
+\emph default
+.
+ As an embedded programmer you
+\emph on
+have
+\emph default
+ to know them so why not look them up
+\emph on
+before
+\emph default
+ you have problems?)
+
+\layout Itemize
+tell someone else about your problem (actually this is a surprisingly effective
+ means to hunt down the bug even if the listener is not familiar with your
+ environment).
+ As 'failure to communicate' is probably one of the job-induced deformations
+ of an embedded programmer this is highly encouraged.
+
+\layout Section
+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.
+
+\layout Subsection
+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 compiler 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 Subsection
+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.
+ (Currently SDCDM only connects to the simulator but
+\emph on
+newcdb
+\emph default
+ at
+\begin_inset LatexCommand \url{http://ec2drv.sf.net/}
+
+\end_inset
+
+ is an effort to connect directly to the hardware.)
+
+\layout Subsection
+Starting the Debugger SDCDB
+
+\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 Subsection
+SDCDB 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 Subsection
+SDCDB 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 this
+ section.
+
+\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 Subsection
+Interfacing SDCDB with DDD
+
+\layout Standard
+\begin_inset Note
+collapsed true
+
+\layout Standard
+The screenshot was converted from png to eps with:
+\begin_inset Quotes sld
+\end_inset
+
+bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
+\begin_inset Quotes srd
+\end_inset
+
+ which produces a pretty compact eps file which is free from compression
+ artifacts.
+
+\layout Standard
+The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
+ as this broke the build system on Sourceforge (pdf-file was broken.
+ pdflatex does not accept eps files).
+
+\end_inset
+
+
+
+\layout Standard
+The
+\emph on
+p
+\emph default
+ortable
+\emph on
+n
+\emph default
+etwork
+\emph on
+g
+\emph default
+raphics File
+\size footnotesize
+
+\begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png}
+
+\end_inset
+
+
+\size default
+ shows a screenshot of a debugging session with DDD
+\begin_inset LatexCommand \index{DDD (debugger)}
+
+\end_inset
+
+ (Unix only) on a simulated 8032.
+ The debugging session might not run as smoothly as the screenshot suggests.
+ The debugger allows setting of breakpoints, displaying and changing variables,
+ single stepping through C and assembler code.
+
+\newline
+The source was compiled with
+\family sans
+\series bold
+
+\newline
+
+\newline
+sdcc -
+\family default
+\series default
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+
+\backslash
+/
+
+\end_inset
+
+
+\family sans
+\series bold
+-debug ddd_example.c
+\family default
+\series default
+
+\family sans
+\series bold
+
+\newline
+
+\family default
+\series default
+
+\newline
+and DDD was invoked with
+\family sans
+\series bold
+
+\newline
+
+\newline
+ddd -debugger "sdcdb -cpu 8032 ddd_example"
+
+\layout Standard
+\begin_inset Note
+collapsed false
+
+\layout Standard
+Check that the double quotes or an apostroph within the command line survive
+ the LyX tool chain.
+ Previously the apostrophs got slanted in the PDF output so a cut and paste
+ did not work.
+
+\end_inset
+
+
+
+\layout Subsection
+Interfacing SDCDB 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
+\pagebreak_bottom
+\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-fro
+m-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-f
+rom-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-w
+hatis-c-sexp\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB ptypecommand for data at
+\newline
+;;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~