\lyxformat 221
\textclass book
\begin_preamble
-
+\pdfoptionpdfminorversion=3
\usepackage[
pdftitle={SDCC Compiler User Guide},
pdfauthor={SDCC development team},
pdfsubject={installation, user manual},
- pdfkeywords={8032, 8051, ansi, c, compiler, CPU, DS390,
- embedded, GPL, HC08, manual, mcs51, PIC, Z80},
+ pdfkeywords={8032 8051 ansi c compiler CPU DS390
+ embedded GPL HC08 manual mcs51 microcontroller PIC Z80},
colorlinks=true,
linkcolor=blue] {hyperref}
%
\size normal
-SDCC 2.4.3
+SDCC 2.5.0
\size footnotesize
\newline
\emph on
C
\emph default
-ompiler) is a Freeware, retargettable, optimizing ANSI-C compiler by
+ompiler) is an open source, retargettable, optimizing ANSI-C compiler by
+
\series bold
Sandeep Dutta
\series default
\end_inset
-, etc.), Dallas DS80C390 variants, Motorola HC08 and Zilog Z80 based MCUs.
+, etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
+ Zilog Z80 based MCUs.
It can be retargetted for other microprocessors, support for Microchip
PIC, Atmel AVR is under development.
The entire source code for the compiler is distributed under GPL.
- SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
+ SDCC uses ASXXXX
+\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
+
+\end_inset
+
+ & ASLINK
+\begin_inset LatexCommand \index{aslink}
+
+\end_inset
+
+, an open source retargettable assembler & linker.
SDCC has extensive language extensions suitable for utilizing various microcont
rollers and underlying hardware effectively.
All packages used in this compiler system are
\emph on
-opensource
+open source
\emph default
and
\emph on
\layout Section
Compatibility with previous versions
+\begin_inset LatexCommand \index{Compatibility with previous versions}
+
+\end_inset
+
+
\layout Standard
This version has numerous bug fixes compared with the previous version.
\layout Itemize
short is now equivalent to int (16 bits), it used to be equivalent to char
- (8 bits) which is not ANSI compliant
+ (8 bits) which is not ANSI compliant.
\layout Itemize
the default directory for gcc-builds where include, library and documentation
- files are stored is now in /usr/local/share
+ files are stored is now in /usr/local/share.
\layout Itemize
char type parameters to vararg functions are casted to int unless explicitly
/
\end_inset
--regextend has been removed
+-regextend has been removed.
\layout Itemize
option -
/
\end_inset
--noregparms has been removed
+-noregparms has been removed.
\layout Itemize
option -
/
\end_inset
--stack-after-data has been removed
+-stack-after-data has been removed.
+\layout Itemize
+
+bit
+\begin_inset LatexCommand \index{bit}
+
+\end_inset
+
+ and sbit
+\begin_inset LatexCommand \index{sbit}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_sbit}
+
+\end_inset
+
+ types now consistently behave like the C99 _Bool type with respect to type
+ conversion
+\begin_inset LatexCommand \index{type conversion}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{type promotion}
+
+\end_inset
+
+.
+ The most common incompatibility resulting from this change is related to
+ bit toggling
+\begin_inset LatexCommand \index{Bit toggling}
+
+\end_inset
+
+ idioms, e.g.:
+\newline
+
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
+bit b;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+b = ~b; /* equivalent to b=1 instead of toggling b */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+b = !b; /* toggles b */
+\newline
+
+\family default
+In previous versions, both forms would have toggled the bit.
\layout Standard
\layout Standard
Of course this doesn't change the search paths compiled into the binaries.
+\newline
+
+\newline
+Moreover the install path can be changed by defining DESTDIR
+\begin_inset LatexCommand \index{DESTDIR}
+
+\end_inset
+
+:
+\layout LyX-Code
+
+make install DESTDIR=$(HOME)/sdcc.rpm/
+\layout Standard
+
+Please note that DESTDIR must have a trailing slash!
\layout Section
Search Paths
And use an editor which can handle LF-only line endings.
Make sure not to commit files with windows line endings.
The tabulator spacing
-\begin_inset LatexCommand \index{tabulator spacing (8)}
+\begin_inset LatexCommand \index{tabulator spacing (8 columns)}
\end_inset
used in the project is 8.
+ Although a tabulator spacing of 8 is a sensible choice for programmers
+ (it's a power of 2 and allows to display 8/16 bit signed variables without
+ loosing columns) the plan is to move towards using only spaces in the source.
\layout Subsection
Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
from the sdcc directory.
\layout Subsection
-Windows Install Using a Binary Package
-\begin_inset LatexCommand \label{sub:Windows-Install}
-
-\end_inset
-
-
+Windows Install Using a ZIP Package
\layout Enumerate
-Download the binary package from
-\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
+Download the binary zip package from
+\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
\end_inset
Adjust your environment variable PATH to include the location of the bin
directory or start sdcc using the full path.
+\layout Subsection
+
+Windows Install Using the Setup Program
+\begin_inset LatexCommand \label{sub:Windows-Install}
+
+\end_inset
+
+
+\layout Standard
+
+Download the setup program
+\emph on
+sdcc-x.y.z-setup.exe
+\emph default
+ for an official release from
+\newline
+
+\begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
+
+\end_inset
+
+ or a setup program for one of the snapshots
+\emph on
+sdcc_yyyymmdd_setup.exe
+\emph default
+ from
+\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
+
+\end_inset
+
+ and execute it.
+ A windows typical installer will guide you through the installation process.
\layout Section
Building the Documentation
You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
x).
Using LyX
-\begin_inset LatexCommand \url{www.lyx.org}
+\begin_inset LatexCommand \url{http://www.lyx.org}
\end_inset
as editor this is straightforward.
Prebuilt documentation in html and pdf format is available from
-\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
+\begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
\end_inset
\end_inset
.
- You'll find the pdf version at
-\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
+
+\newline
+You'll find the pdf version
+\begin_inset LatexCommand \index{PDF version of this document}
+
+\end_inset
+
+ at
+\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
+
+\end_inset
+
+.
+
+\newline
+A html version
+\begin_inset LatexCommand \index{HTML version of this document}
+
+\end_inset
+
+ should be online at
+\begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
\end_inset
Don't let this distract you.
If there f.e.
was a reference like
-\begin_inset LatexCommand \url{www.opencores.org}
+\begin_inset LatexCommand \url{http://www.opencores.org}
\end_inset
\end_inset
- is a freeware, opensource simulator developed by Daniel Drotos (
-\begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
-
-\end_inset
-
-).
+ is a freeware, opensource simulator developed by Daniel Drotos.
The simulator is built as part of the build process.
For more information visit Daniel's web site at:
\begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
\family default
\shape default
-\begin_inset LatexCommand \index{srecord (tool)}
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
\end_inset
).
Both formats are documented in the documentation of srecord
-\begin_inset LatexCommand \index{srecord (tool)}
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
\end_inset
\end_inset
-debug) containing debug information.
- The format is documented in cdbfileformat.pdf.
+ The format is documented in cdbfileformat.pdf
\layout Itemize
sourcefile.
\series default
- Generate code for the Motorola HC08
+ Generate code for the Freescale/Motorola HC08
\begin_inset LatexCommand \index{HC08}
\end_inset
- family of processors (added Oct 2003).
+ family of processors.
\layout List
\labelwidthstring 00.00.0000
\end_inset
processor (In development, not complete).
- AVR users should probably have a look at avr-gcc
-\begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
+ AVR users should probably have a look at winavr
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
\end_inset
- or winavr
-\begin_inset LatexCommand \url{http://winavr.sourceforge.net}
+ or
+\begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
\end_inset
The provided value should not overlap any other memory areas such as used
register banks or the data segment and with enough space for the current
application.
+ The
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pack-iram
+\series default
+\SpecialChar ~
+
+\begin_inset LatexCommand \index{-\/-pack-iram}
+
+\end_inset
+
+ option (which is now a default setting) will override this setting, so
+ you should also specify the
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-pack-iram
+\series default
+\SpecialChar ~
+
+\begin_inset LatexCommand \index{-\/-no-pack-iram}
+
+\end_inset
+
+ option if you need to manually place the stack.
\layout List
\labelwidthstring 00.00.0000
This is the default option.
The format itself is documented in the documentation of srecord
-\begin_inset LatexCommand \index{srecord (tool)}
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
\end_inset
\labelwidthstring 00.00.0000
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-out-fmt-elf
+\begin_inset LatexCommand \index{-\/-out-fmt-s19}
+
+\end_inset
+
+
+\bar under
+
+\series default
+\bar default
+The linker output (final object code) is in ELF format
+\begin_inset LatexCommand \index{ELF format}
+
+\end_inset
+
+.
+ (Currently only supported for the HC08 processors)
+\layout List
+\labelwidthstring 00.00.0000
+
+
\series bold
-Wl\SpecialChar ~
linkOption[,linkOption]
\end_inset
- Causes the linker use unused register banks for data variables or stack.
+ Causes the linker to use unused register banks for data variables and pack
+ data, idata and stack together.
+ This is the default now.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-pack-iram
+\series default
+\SpecialChar ~
+
+\begin_inset LatexCommand \index{-\/-no-pack-iram}
+
+\end_inset
+
+ Causes the linker to use old style for allocating memory areas.
\layout Subsection
DS390 / DS400 Options
\series default
Will not do global subexpression elimination, this option may be used when
the compiler creates undesirably large stack/data spaces to store compiler
- temporaries.
+ temporaries (
+\emph on
+s
+\emph default
+pill
+\emph on
+loc
+\emph default
+ations, sloc
+\begin_inset LatexCommand \index{sloc (spill location)}
+
+\end_inset
+
+).
A warning message will be generated when this happens and the compiler
will indicate the number of extra bytes it allocated.
It is recommended that this option NOT be used, #pragma\SpecialChar ~
\series default
Will not memcpy initialized data from code space into xdata space.
- This saves a few bytes in code space if you don't have initialized data.
+ This saves a few bytes in code space if you don't have initialized data
+\begin_inset LatexCommand \index{Variable initialization}
+
+\end_inset
+
+.
\layout List
\labelwidthstring 00.00.0000
\series default
- Pass the inline assembler code through the peep hole optimizer.
+ Pass the inline assembler code through the peep hole optimizer.
This can cause unexpected changes to inline assembler code, please go through
the peephole optimizer
\begin_inset LatexCommand \index{Peephole optimizer}
rules defined in the source file tree '<target>/peeph.def' before using
this option.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-opt-code-speed
+\begin_inset LatexCommand \index{-\/-opt-code-speed}
+
+\end_inset
+
+
+\series default
+ The compiler will optimize code generation towards fast code, possibly
+ at the expense of code size.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-opt-code-size
+\begin_inset LatexCommand \index{-\/-opt-code-size}
+
+\end_inset
+
+
+\series default
+ The compiler will optimize code generation towards compact code, possibly
+ at the expense of code speed.
\layout Subsection
Other Options
Parameters and Local Variables for more details.
If this option is used all source files in the project should be compiled
with this option.
+ It automatically implies --int-long-reent and --float-reent.
\layout List
\labelwidthstring 00.00.0000
\series bold
-
\begin_inset ERT
-status Open
+status Collapsed
\layout Standard
/
\end_inset
--nostdincl
-\begin_inset LatexCommand \index{-\/-nostdincl}
+-nostdinc
+\begin_inset LatexCommand \index{-\/-nostdinc}
\end_inset
(jwk burps: please be more specific here, please!).
If you want rather more than less warnings you should consider using a
separate tool dedicated to syntax checking like splint
-\begin_inset LatexCommand \url{www.splint.org}
+\begin_inset LatexCommand \url{http://www.splint.org}
\end_inset
\labelwidthstring 00.00.0000
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-disable-warning\SpecialChar ~
+<nnnn>
+\begin_inset LatexCommand \index{-\/-disable-warning}
+
+\end_inset
+
+
+\series default
+ Disable specific warning with number <nnnn>.
+\layout List
+\labelwidthstring 00.00.0000
+
+
\series bold
-
\begin_inset ERT
.
See file sdcc/as/doc/asxhtm.html for assembler options.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-std-sdcc89
+\begin_inset LatexCommand \index{-\/-std-sdcc89}
+
+\end_inset
+
+
+\series default
+ Generally follow the C89 standard, but allow SDCC features that conflict
+ with the standard (default).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-std-c89
+\begin_inset LatexCommand \index{-\/-std-c89}
+
+\end_inset
+
+
+\series default
+ Follow the C89 standard and disable SDCC features that conflict with the
+ standard.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-std-sdcc99
+\begin_inset LatexCommand \index{-\/-std-sdcc99}
+
+\end_inset
+
+
+\series default
+ Generally follow the C99 standard, but allow SDCC features that conflict
+ with the standard (incomplete support).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-std-c99
+\begin_inset LatexCommand \index{-\/-std-sdcc99}
+
+\end_inset
+
+
+\series default
+ Follow the C99 standard and disable SDCC features that conflict with the
+ standard (incomplete support).
\layout Subsection
Intermediate Dump Options
The following options are provided for the purpose of retargetting and debugging
the compiler.
- These provided a means to dump the intermediate code (iCode
+ They provide a means to dump the intermediate code (iCode
\begin_inset LatexCommand \index{iCode}
\end_inset
data
\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
+
\end_inset
/ near
\end_inset
+\begin_inset LatexCommand \index{\_\_near (storage class)}
+
+\end_inset
+
+
\layout Standard
This is the
xdata
\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
+
\end_inset
/ far
\end_inset
+\begin_inset LatexCommand \index{\_\_far (storage class)}
+
+\end_inset
+
+
\layout Standard
Variables declared with this storage class will be placed in the external
\end_inset
+\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
+
+\end_inset
+
+
\layout Standard
Variables declared with this storage class will be allocated into the indirectly
\end_inset
+\begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+
\layout Standard
-Paged xdata access is currently not as straightforward as using the other
- addressing modes of a 8051.
+Paged xdata access is just as straightforward as using the other addressing
+ modes of a 8051.
+ It is typically located at the start of xdata and has a maximum size of
+ 256 bytes.
The following example writes 0x01 to the address pointed to.
Please note, pdata access physically accesses xdata memory.
The high byte of the address is determined by port P2
movx @r0,a
\layout Standard
-Be extremely carefull if you use pdata together with the -
+If the -
\begin_inset ERT
status Collapsed
\end_inset
- option.
+ option is used the pdata memory area is followed by the xstack memory area
+ and the sum of their sizes is limited to 256 bytes.
\layout Subsubsection
code
\end_inset
+\begin_inset LatexCommand \index{\_\_code}
+
+\end_inset
+
+
\layout Standard
'Variables' declared with this storage class will be placed in the code
\end_inset
+\begin_inset LatexCommand \index{\_\_bit}
+
+\end_inset
+
+
\layout Standard
This is a data-type and a storage class specifier.
sfr
\begin_inset LatexCommand \index{sfr}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_sfr}
+
\end_inset
/ sbit
-\begin_inset LatexCommand \index{sbit}
+\begin_inset LatexCommand \index{\_\_sbit}
\end_inset
sfr at
\begin_inset LatexCommand \index{at}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
\end_inset
0x80 P0;\SpecialChar ~
\end_inset
+
+\begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
+
+\end_inset
+
).
Furthermore, some chips may have some built in external memory (
\emph on
\end_inset
+
+\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
) which should not be confused with the internal, directly addressable RAM
memory (
\emph on
\end_inset
+
+\begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
+
+\end_inset
+
).
Sometimes this built in
\emph on
\end_inset
of registers (register bank 0), but it is possible to specify that other
- banks of registers should be used in interrupt
+ banks of registers (keyword
+\emph on
+using
+\emph default
+
+\emph on
+
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
+\emph default
+) should be used in interrupt
\begin_inset LatexCommand \index{interrupt}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_interrupt}
+
\end_inset
routines.
grows, it will use up the remaining register banks, and the 16 bytes used
by the 128 bit variables, and 80 bytes for general purpose use.
- If any bit variables are used, the data variables will be placed after
- the byte holding the last bit variable.
+ If any bit variables are used, the data variables will be placed in unused
+ register banks and after the byte holding the last bit variable.
For example, if register banks 0 and 1 are used, and there are 9 bit variables
(two bytes used),
\emph on
data
\emph default
- variables will be placed starting at address 0x22.
+ variables will be placed starting from address 0x10 to 0x20 and continue
+ at address 0x22.
You can also use -
\begin_inset ERT
status Collapsed
\end_inset
-data-loc
-\begin_inset LatexCommand \index{-\/-data-loc<Value>}
+\begin_inset LatexCommand \index{-\/-data-loc <Value>}
\end_inset
/
\end_inset
--iram-size to specify the size of the total internal RAM (
+-iram-size
+\begin_inset LatexCommand \index{-\/-iram-size <Value>}
+
+\end_inset
+
+ to specify the size of the total internal RAM (
\emph on
data
\emph default
\layout Standard
-By default the 8051 linker will place the stack after the last byte of data
+By default the 8051 linker will place the stack after the last byte of (i)data
variables.
Option -
\begin_inset ERT
\end_inset
-stack-loc
-\begin_inset LatexCommand \index{-\/-stack-loc<Value>}
+\begin_inset LatexCommand \index{-\/-stack-loc <Value>}
\end_inset
\end_inset
-xram-size
-\begin_inset LatexCommand \index{-\/-data-loc}
+\begin_inset LatexCommand \index{-\/-xram-size <Value>}
\end_inset
\end_inset
-code-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
+\begin_inset LatexCommand \index{-\/-code-loc <Value>}
\end_inset
\end_inset
-code-size
-\begin_inset LatexCommand \index{-\/-data-loc}
+\begin_inset LatexCommand \index{-\/-code-size <Value>}
\end_inset
sfr
\begin_inset LatexCommand \index{sfr}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_sfr}
+
\end_inset
(in/out to 8-bit addresses)
banked sfr
\begin_inset LatexCommand \index{sfr}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_sfr}
+
\end_inset
(in/out to 16-bit addresses)
sfr banked at
\begin_inset LatexCommand \index{at}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
\end_inset
0x123 IoPort;
sfr
\begin_inset LatexCommand \index{sfr}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_sfr}
+
\end_inset
(in0/out0 to 8 bit addresses on Z180
\layout Subsubsection
data
-\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
+\begin_inset LatexCommand \index{data (hc08 storage class)}
\end_inset
+\begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
+
+\end_inset
+
+
\layout Standard
The data storage class declares a variable that resides in the first 256
\layout Subsubsection
xdata
-\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+\begin_inset LatexCommand \index{xdata (hc08 storage class)}
\end_inset
+\begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
+
+\end_inset
+
+
\layout Standard
The xdata storage class declares a variable that can reside anywhere in
at
\begin_inset LatexCommand \index{at}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
\end_inset
<address>
xdata
\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
+
\end_inset
at
\begin_inset LatexCommand \index{at}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
\end_inset
0x7ffe unsigned int chksum;
\layout Standard
-In the above example the variable chksum will located at 0x7ffe and 0x7fff
+In the above example the variable chksum will be located at 0x7ffe and 0x7fff
of the external ram.
The compiler does
\emph on
\emph on
volatile
\emph default
- have to be used to tell the compiler that accesses might not be optimized
- away:
+ has to be used to tell the compiler that accesses might not be removed:
\layout Verse
\family typewriter
-extern volatile bit MOSI;\SpecialChar ~
+extern volatile
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+ bit MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\family typewriter
-bit at 0x80 MOSI;\SpecialChar ~
+bit at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
+\end_inset
+
+ 0x80 MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\end_inset
+\begin_inset LatexCommand \index{\_\_interrupt}
+
+\end_inset
+
+
\emph default
keyword is the interrupt number this routine will service.
When present, the compiler will insert a call to this routine in the interrupt
main
\emph default
.
- The
+ The optional
\emph on
using
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
\emph default
keyword can be used to tell the compiler to use the specified register
bank (8051 specific) when generating code for this function.
If the access to these variables is not
\emph on
atomic
-\begin_inset LatexCommand \index{atomic access}
+\begin_inset LatexCommand \index{atomic}
\end_inset
\end_inset
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
\emph default
a register bank or with register bank 0 (
\emph on
\end_inset
for details on customizing startup.
-\layout Section
-
-Enabling and Disabling Interrupts
+\layout Subsection
+
+Z80 Interrupt Service Routines
+\layout Standard
+
+The Z80 uses several different methods for determining the correct interrupt
+ vector depending on the hardware implementation.
+ Therefore, SDCC ignores the optional interrupt number and does not attempt
+ to generate an interrupt vector table.
+\layout Standard
+
+By default, SDCC generates code for a maskable interrupt, which uses an
+ RETI instruction to return from the interrupt.
+ To write an interrupt handler for the non-maskable interrupt, which needs
+ an RETN instruction instead, add the
+\emph on
+critical
+\emph default
+ keyword:
+\layout Verse
+
+
+\family typewriter
+void nmi_isr (void) critical interrupt
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Section
+
+Enabling and Disabling Interrupts
\layout Subsection
Critical Functions and Critical Statements
\end_inset
+
+\begin_inset LatexCommand \index{\_\_critical}
+
+\end_inset
+
\newline
{
and don't add complexity unless you have to.
+\layout Subsection
+
+Semaphore
+\begin_inset LatexCommand \index{semaphore}
+
+\end_inset
+
+ locking (mcs51/ds390)
+\layout Standard
+
+Some architectures (mcs51/ds390) have an atomic
+\begin_inset LatexCommand \index{atomic}
+
+\end_inset
+
+ bit test and
+\emph on
+
+\emph default
+clear
+\emph on
+
+\emph default
+instruction.
+ These type of instructions are typically used in preemptive multitasking
+ systems, where a routine f.e.
+ claims the use of a data structure ('acquires a lock
+\begin_inset LatexCommand \index{lock}
+
+\end_inset
+
+ on it'), makes some modifications and then releases the lock when the data
+ structure is consistent again.
+ The instruction may also be used if interrupt and non-interrupt code have
+ to compete for a resource.
+ With the atomic bit test and clear instruction interrupts
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ don't have to be disabled for the locking operation.
+
+\layout Standard
+
+SDCC generates this instruction if the source follows this pattern:
+\layout Verse
+
+
+\family typewriter
+volatile
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+ bit resource_is_free;
+\newline
+
+\newline
+if (resource_is_free)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+resource_is_free=0;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+resource_is_free=1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+}
+\layout Standard
+
+Note, mcs51 and ds390 support only an atomic
+\begin_inset LatexCommand \index{atomic}
+
+\end_inset
+
+ bit test and
+\emph on
+clear
+\emph default
+ instruction (as opposed to atomic bit test and
+\emph on
+set).
\layout Section
Functions using private register banks
\end_inset
+\begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
\emph default
attribute (which tells the compiler to use a register bank
\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
function using a non-zero bank will assume that it can trash that register
bank, and will not save it.
Since high-priority interrupts
+\begin_inset LatexCommand \index{interrupts}
+
+\end_inset
+
+
\begin_inset LatexCommand \index{interrupt priority}
\end_inset
\emph default
routine to your program to override the default if you need to setup hardware
or perform some other critical operation prior to static & global variable
- initialization.
- On some mcs51 variants xdata has to be explicitly enabled before it can
- be accessed, this is the place to do it.
- The startup code clears the complete 256 byte of idata memory, this might
- cause problems for 128 byte devices (endless loop reported for Chipcon
- CC1010).
+ initialization
+\begin_inset LatexCommand \index{Variable initialization}
+
+\end_inset
+
+.
+ On some mcs51 variants xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ memory has to be explicitly enabled before it can be accessed or if the
+ watchdog needs to be disabled, this is the place to do it.
+ The startup code clears all internal data memory, 256 bytes by default,
+ but from 0 to n-1 if
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-iram-size
+\begin_inset LatexCommand \index{-\/-iram-size <Value>}
+
+\end_inset
+
+n
+\emph default
+ is used.
+ (recommended for Chipcon CC1010).
\layout Standard
See also the compiler option
unsigned char far
\begin_inset LatexCommand \index{far (storage class)}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_far (storage class)}
+
\end_inset
at
\begin_inset LatexCommand \index{at}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_at}
+
\end_inset
0x7f00 buf[0x100];
\end_inset
+\begin_inset LatexCommand \index{\_\_asm}
+
+\end_inset
+
+
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_endasm;
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
+\end_inset
+
+;
\newline
}
\layout Standard
\end_inset
+\begin_inset LatexCommand \index{\_\_asm}
+
+\end_inset
+
+
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_endasm;
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
+\end_inset
+
+;
\newline
}
\newline
The assembler does not like some characters like ':' or ''' in comments.
You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
+\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Assembler documentation}
+
+\end_inset
+
+
\end_inset
.
_asm
\begin_inset LatexCommand \index{\_asm}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_asm}
+
\end_inset
...
- _endasm;
+ _endasm
+\size footnotesize
+
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
+\end_inset
+
+
+\size default
+;
\family default
keyword pair.
Specifically it will not know which registers are used and thus register
\end_inset
+
+\begin_inset LatexCommand \index{\_\_naked}
+
+\end_inset
+
.
\emph default
void simpleInterrupt(void) interrupt
\begin_inset LatexCommand \index{interrupt}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_interrupt}
+
\end_inset
1
\end_inset
+\begin_inset LatexCommand \index{\_\_asm}
+
+\end_inset
+
+
\newline
\SpecialChar ~
\SpecialChar ~
\end_inset
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
+\end_inset
+
;
\newline
}
\end_inset
+
+\begin_inset LatexCommand \index{\_\_asm}
+
+\end_inset
+
\newline
\SpecialChar ~
_endasm
\begin_inset LatexCommand \index{\_endasm}
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
\end_inset
;
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_endasm ;
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{\_\_endasm}
+
+\end_inset
+
+ ;
\newline
\SpecialChar ~
\SpecialChar ~
\layout Standard
These support routines are developed in ANSI-C so there is room for space
- and speed improvement.
+ and speed improvement
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+The floating point routines 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 it is recommended that the large model
- be used.
+ 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.
in sdcc/device/lib.
\layout Standard
-If you're short on memory you might want to use
-\family typewriter
-printf_small()
-\family default
-
-\emph on
-instead
-\emph default
- of
+The default
\family typewriter
printf()
\begin_inset LatexCommand \index{printf()}
\end_inset
-.
\family default
- For the mcs51 there is an assembly version
+implementation in
\family typewriter
-printf_fast()
+ printf_large.c
\family default
- which should fit the requirements of many embedded systems (by unsetting
- #defines it can be customized to
+ does not support float (except on ds390).
+ To enable this recompile it with the option
\emph on
-not
-\emph default
- support long variables and field widths).
-\layout Subsection
+-
+\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 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
+ 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
+ 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).
+\layout Subsection
Math functions (sin, pow, sqrt etc.)
\layout Subsection
\layout Standard
-
-\series bold
-Attention
-\series default
-: this option wasn't maintained for a long time and is quite buggy.
- Small programs might work.
- You've been warned!
-\layout Standard
-
The external stack (-
\begin_inset ERT
status Collapsed
\end_inset
- memory (usually at the start of the external ram segment) and is 256 bytes
- in size.
+ 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
option, all parameters and local variables are allocated on the external
stack (note: support libraries will need to be recompiled with the same
- options).
+ 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
\end_inset
+
+\begin_inset LatexCommand \index{\_\_naked}
+
+\end_inset
+
.
\layout Itemize
your own now ;-(
\layout Itemize
+disable_warning <nnnn>
+\begin_inset LatexCommand \index{\#pragma disable\_warning}
+
+\end_inset
+
+ - the compiler will not warn you anymore about warning number <nnnn>.
+\layout Itemize
+
nogcse
\begin_inset LatexCommand \index{\#pragma nogcse}
\end_inset
Parameters and Local Variables.
+\layout Itemize
+
+opt_code_speed
+\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.
+\layout Itemize
+
+opt_code_size
+\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.
+\layout Itemize
+
+opt_code_balanced
+\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
+
+std_sdcc89
+\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
+
+std_c89
+\begin_inset LatexCommand \index{\#pragma std\_c89}
+
+\end_inset
+
+- Follow the C89 standard and disable SDCC features that conflict with the
+ standard.
+\layout Itemize
+
+std_sdcc99
+\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
+
+std_c99
+\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 Standard
SDCPP supports the following #pragma directives:
gpasm.exe or MPLAB's mpasmwin.exe.
GPUTILS is available from
-\begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
\end_inset
(TM) microcontrollers with 16 bit core.
Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
-\layout Subsection
-
-Global Options
+ Currently supported devices are:
\layout Standard
+\align center
-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
+\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
-\backslash
-/
+18F242
\end_inset
-
--stack-auto Auto variables that are function parameters, will be saved on
- stack by default.
-
-\emph on
-There is no need to specify this in the command line.
-\layout List
-\labelwidthstring 00.00.0000
-
--
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+18F248
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--float-reent All floating point functions are reentrant by default.
-
-\emph on
-There is no need to specifiy this in the command line.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
--
-\begin_inset ERT
-status Collapsed
+18F252
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+18F258
\end_inset
-
--callee-saves See -
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+18F442
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--all-callee-saves
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
--
-\begin_inset ERT
-status Collapsed
+18F448
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+18F452
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--all-callee-saves All function arguments are passed on stack by default.
-
-\emph on
-There is no need to specify this in the command line.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
--
-\begin_inset ERT
-status Collapsed
+18F458
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+18F1220
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--fommit-frame-pointer Frame pointer will be omitted when the function uses
- no local variables.
-\layout Subsection
-
-Port Specific Options
-\begin_inset LatexCommand \index{Options PIC16}
+\layout Standard
+18F2220
\end_inset
-
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-The port specific options appear after the global options in the sdcc --help
- output.
-\layout Subsubsection
+18F2550
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-General Options
\layout Standard
-General options enable certain port features and optimizations.
-\layout List
-\labelwidthstring 00.00.0000
+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
/
\end_inset
--pgen-bank Instructs the port to insert BANKSEL directives before instructions
- that use the Bank Select Register (BSR).
-\layout List
-\labelwidthstring 00.00.0000
-
--
+-callee-saves See -
\begin_inset ERT
status Collapsed
/
\end_inset
--pomit-config-words Instructs the port to omit the generation of the configurati
-on words.
+-all-callee-saves
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--pomit-ivt Instructs the port to omit the generation of the interrupt vectors
+-all-callee-saves All function arguments are passed on stack by default.
+
+\emph on
+There is no need to specify this in the command line.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--pleave-reset-vector Used in conjuction with the previous command, instructs
- the port NOT to omit the reset vector.
+-fommit-frame-pointer Frame pointer will be omitted when the function uses
+ no local variables.
+\layout Subsection
+
+Port Specific Options
+\begin_inset LatexCommand \index{Options PIC16}
+
+\end_inset
+
+
+\layout Standard
+
+The port specific options appear after the global options in the sdcc --help
+ output.
+\layout Subsubsection
+
+General Options
+\layout Standard
+
+General options enable certain port features and optimizations.
\layout List
\labelwidthstring 00.00.0000
\end_inset
-link= sets the full path and name of an external linker to call.
-\layout Subsubsection
-
-Debugging Options
-\layout Standard
-
-Debugging options enable extra debugging information in the output files.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--debug-xtra Similar to -
+-mplab-comp MPLAB compatibility option.
+ Currently only suppresses special gpasm directives.
+\layout Subsubsection
+
+Optimization Options
+\layout List
+\labelwidthstring 00.00.0000
+
+-
\begin_inset ERT
status Collapsed
/
\end_inset
--debug
-\begin_inset LatexCommand \index{-\/-debug}
-
-\end_inset
-
-, but dumps more information.
+-optimize-goto Try to use (conditional) BRA instead of GOTO
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--debug-ralloc Force register allocator to dump <source>.d file with debugging
- information.
- <source> is the name of the file compiled.
+-optimize-cmp Try to optimize some compares.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--pcode-verbose Enable pcode debugging information in translation.
-\layout Subsection
+-obanksel=nn Set optimization level for inserting BANKSELs.
+\newline
-Preprocessor Macros
-\layout Standard
+\begin_deeper
+\layout List
+\labelwidthstring 00.00.0000
-PIC16 port defines the following preprocessor macros while translating a
- source.
-\layout Standard
-\align center
+0 no optimization
+\layout List
+\labelwidthstring 00.00.0000
-\begin_inset Tabular
-<lyxtabular version="3" rows="2" columns="2">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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
-\layout Standard
+2 tries to check the location of (even different) symbols and removes BANKSELs
+ if they are in the same bank.
+
+\newline
-Macro
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\emph on
+Important: There might be problems if the linker script has data sections
+ across bank borders!
+\end_deeper
+\layout Subsubsection
-\layout Standard
+Linking Options
+\layout List
+\labelwidthstring 00.00.0000
-Description
-\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-pic18fxxxx
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-nodefaultlibs do not link default libraries when linking
+\layout List
+\labelwidthstring 00.00.0000
-MCU Identification.
-
-\emph on
-xxxx
-\emph default
- is the microcontrol identification number, i.e.
- 452, 6620, etc
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+-
+\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
-\layout Subsection
+-
+\begin_inset ERT
+status Collapsed
-Directories
\layout Standard
-PIC16
-\begin_inset LatexCommand \index{PIC16}
-
+\backslash
+/
\end_inset
- port uses the following directories for searching header files and libraries.
+-use-crt= Use a custom run-time module instead of the defaults.
+\layout Subsubsection
+
+Debugging Options
\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">
+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 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">
\layout Standard
-Directory
+Macro
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
Description
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Target
+SDCC_pic16
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Command prefix
+Port identification
\end_inset
</cell>
</row>
\layout Standard
-PREFIX/sdcc/include/pic16
+_
+\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">
\layout Standard
-PIC16 specific headers
+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">
\layout Standard
-Compiler
+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">
\layout Standard
--I
+MCU Identification (same as above)
\end_inset
</cell>
</row>
\layout Standard
-PREFIX/sdcc/lib/pic16
+STACK_MODEL_nnn
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-PIC16 specific libraries
+nnn = SMALL or LARGE respectively according to the stack model used
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</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
-Linker
+Macro
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
--L
+Description
\end_inset
</cell>
</row>
-</lyxtabular>
+<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
-\layout Subsection
+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
-Pragmas
-\begin_inset LatexCommand \label{sub:PIC16_Pragmas}
+\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
-PIC16 port currently supports the following pragmas:
-\layout List
-\labelwidthstring 00.00.0000
+STACK_MODEL_nnn
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-stack pragma stack forces the code generator to initialize the stack & frame
- pointers at a specific address.
- This is an adhoc solution since gplink does not support yet stack.
- When the gplink issue is resolved the pragma will be deprecated
-\begin_inset Foot
-collapsed true
+\layout Standard
+
+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 port currently supports the following pragmas:
+\layout List
+\labelwidthstring 00.00.0000
+
+stack pragma stack forces the code generator to initialize the stack & frame
+ pointers at a specific address.
+ This is an adhoc solution 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
+
+wparam
+\emph on
+This pragma is deprecated.
+ Its use will cause a warning message to be issued.
+\emph default
+
+\newline
+
+\layout List
+\labelwidthstring 00.00.0000
+
+code 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 that can be included to the source files using
+ the pic16 port.
+ That file is the
+\series bold
+pic18fregs.h
+\series default
+.
+ This header file contains the definitions for the processor special registers,
+ so it is necessary if the source accesses them.
+ It can be included by adding the following line in the beginning of the
+ file:
+\layout LyX-Code
+
+#include <pic18fregs.h>
+\layout Standard
+
+The specific microcontroller is selected within the pic18fregs.h automatically,
+ so the same source can be used with a variety of devices.
+\layout Subsection
+
+Libraries
+\layout Standard
+
+The libraries that PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port depends on are the microcontroller device libraries which contain
+ the symbol definitions for the microcontroller special function registers.
+ These libraries have the format pic18fxxxx.lib, where
+\emph on
+xxxx
+\emph default
+ is the microcontroller identification number.
+ The specific library is selected automatically by the compiler at link
+ stage according to the selected device.
+\layout Standard
+
+Libraries are created with gplib which is part of the gputils package
+\begin_inset LatexCommand \url{http://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 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 port makes available
+ two more:
+\layout List
+\labelwidthstring 00.00.0000
+
+wparam 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 Standard
+
+This keyword replaces the deprecated wparam pragma.
+\layout List
+\labelwidthstring 00.00.0000
+
+shadowregs 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 servive 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
+
+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
+
+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
-\emph on
-It is important to initialize the stack, otherwise strange things can happen.
- Stack is not initialized by default because there are some sources that
- do not require it.
- (like library sources)
+Writes/Reads characters via used defined functions
\end_inset
+</cell>
+</row>
+</lyxtabular>
-.
-\newline
-The stack pragma should be used only once in a project.
- Multiple pragmas may result in indeterminate behaviour of the program.
-\layout LyX-Code
+\end_inset
-Example:
-\layout LyX-Code
-\layout LyX-Code
+\layout Standard
-/* initializes stack at RAM address 0x5ff */
-\layout LyX-Code
+The stream identifiers are declared as macros in the stdio.h header.
+\layout Standard
-#pragma stack 0x5ff
+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
-udata pragma udata instructs the compiler to emit code so that linker will
- place a variable at a specific memory bank
-\layout LyX-Code
+_
+\begin_inset ERT
+status Collapsed
-Example:
-\layout LyX-Code
+\layout Standard
-\layout LyX-Code
+\backslash
+/
+\end_inset
-/* places variable foo at bank2 */
-\layout LyX-Code
+_stream_usart_putchar writes a character at the USART stream
+\layout List
+\labelwidthstring 00.00.0000
-#pragma udata bank2 foo
-\layout LyX-Code
+_
+\begin_inset ERT
+status Collapsed
-char foo;
\layout Standard
-In order for this pragma to work there are some changes that must be made
- in the .lkr script used in link stage.
- In the following example a sample .lkr file is shown:
-\layout LyX-Code
-
-\layout LyX-Code
-
-// Sample linker script for the PIC18F452 processor
-\layout LyX-Code
-
-LIBPATH .
-\layout LyX-Code
+\backslash
+/
+\end_inset
-CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED
-\layout LyX-Code
+_stream_mssp_putchar writes a character at the MSSP stream
+\layout List
+\labelwidthstring 00.00.0000
-CODEPAGE NAME=page START=0x2A END=0x7FFF
-\layout LyX-Code
+putchar dummy function.
+ This writes a character to a user specified manner.
+\layout Standard
-CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED
+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
-CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED
-\layout LyX-Code
+#include <pic18fregs.h>
+\newline
+#include <stdio.h>
+\newline
-CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED
+\newline
+PUTCHAR( c )
\layout LyX-Code
-CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED
+{
\layout LyX-Code
-ACCESSBANK NAME=accessram START=0x0 END=0x7F
+ PORTA = c; /* dump character c to PORTA */
\layout LyX-Code
-\layout LyX-Code
+}
+\newline
-DATABANK NAME=gpr0 START=0x80 END=0xFF
+\newline
+void main(void)
\layout LyX-Code
-DATABANK NAME=gpr1 START=0x100 END=0x1FF
+{
\layout LyX-Code
-DATABANK NAME=gpr2 START=0x200 END=0x2FF
+ stdout = STREAM_USER; /* this is not necessery, since stdout points
\layout LyX-Code
-DATABANK NAME=gpr3 START=0x300 END=0x3FF
+ * by default to STREAM_USER */
\layout LyX-Code
-DATABANK NAME=gpr4 START=0x400 END=0x4FF
+ printf (¨This is a printf test
+\backslash
+n¨);
\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 Subsubsection
-\layout LyX-Code
+Printing functions
+\layout Standard
-SECTION NAME=CONFIG ROM=config
+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
-SECTION NAME=bank0 RAM=gpr0
+extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
\layout LyX-Code
-SECTION NAME=bank1 RAM=gpr1
\layout LyX-Code
-SECTION NAME=bank2 RAM=gpr2
+extern unsigned int printf(char *fmt, ...);
\layout LyX-Code
-SECTION NAME=bank3 RAM=gpr3
+extern unsigned int vprintf(char *fmt, va_lista ap);
\layout LyX-Code
-SECTION NAME=bank4 RAM=gpr4
\layout LyX-Code
-SECTION NAME=bank5 RAM=gpr5
-\layout Standard
-
-The linker will recognise the section name set in the pragma statement and
- will position the variable at the memory bank set with the RAM field at
- the SECTION line in the linker script file.
-\layout Subsection
-
-Header Files
-\begin_inset LatexCommand \label{sub:PIC16_Header-Files}
-
-\end_inset
-
-
-\layout Standard
-
-There is one main header file that can be included to the source files using
- the pic16 port.
- That file is the
-\series bold
-pic18fregs.h
-\series default
-.
- This header file contains the definitions for the processor special registers,
- so it is necessary if the source accesses them.
- It can be included by adding the following line in the beginning of the
- file:
+extern unsigned int fprintf(FILE *fp, char *fmt, ...);
\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
+extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
\layout Standard
-The libraries that PIC16
-\begin_inset LatexCommand \index{PIC16}
-
-\end_inset
-
- port depends on are the microcontroller device libraries which contain
- the symbol definitions for the microcontroller special function registers.
- These libraries have the format pic18fxxxx.lib, where
+For sprintf and vsprintf
\emph on
-xxxx
+buf
\emph default
- is the microcontroller identification number.
- The specific library is selected automatically by the compiler at link
- stage according to the selected device.
-\layout Standard
-
-Libraries are created with gplib which is part of the gputils package
-\begin_inset LatexCommand \url{http://gputils.sourceforge.net}
-
-\end_inset
-
-.
-\layout Subsection
-
-Memory Models
-\layout Standard
-
-The following memory models are supported by the PIC16 port:
-\layout Itemize
-
-small model
-\layout Itemize
+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
-large model
+Signals
\layout Standard
-Memory model affects the default size of pointers within the source.
- The sizes are shown in the next table:
+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="3" columns="3">
+<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="center" valignment="top" leftline="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">
\layout Standard
-Pointer sizes according to memory model
+signal name
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-small model
+description
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-large model
+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" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-code pointers
+SIG_RB
\end_inset
</cell>
-<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-16-bits
+PORTB change interrupt
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-24-bits
+SIG_EE
\end_inset
</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-data pointers
+EEPROM/FLASH write complete interrupt
\end_inset
</cell>
-<cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-16-bits
+SIG_INT0
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-16-bits
+INT0 external interrupt
\end_inset
</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\layout Standard
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-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}
-
+SIG_BCOL
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-) contain no reference to pointers, so they can be used with both memory
- models.
-\layout Subsection
-
-Stack
-\layout Standard
-
-The stack implementation for the PIC16 port uses two indirect registers,
- FSR1 and FSR2.
-\layout List
-\labelwidthstring 00.00.0000
-
-FSR1 is assigned as stack pointer
-\layout List
-\labelwidthstring 00.00.0000
-
-FSR2 is assigned as frame pointer
-\layout Standard
-
-The following stack models are supported by the PIC16 port
-\layout Itemize
-
-small model
-\layout Itemize
-
-large model
\layout Standard
+Bus collision interrupt
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\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">
+SIG_INT1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-Stack & Frame pointer sizes according to stack model
+INT1 external interrupt
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-small
+SIG_LVD
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-large
+Low voltage detect interrupt
\end_inset
</cell>
</row>
\layout Standard
-Stack pointer FSR1
+SIG_INT2
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-8-bits
+INT2 external interrupt
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-16-bits
+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" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Frame pointer FSR2
+SIG_CCP1
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-8-bits
+CCP1 module interrupt
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-16-bits
+SIG_AD
\end_inset
</cell>
-</row>
-</lyxtabular>
+<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
-\series bold
-Currently stack and frame pointers should be initialized explicit by the
- user at the desired Data RAM position (see
-\begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
+\layout Standard
+SIG_RC
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- Pragma stack).
- Uninitialized stack and frame pointers can result in unexpected behavior
- of the resulting binary.
-\layout Subsection
+\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
-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:
+SIG_TMR0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
\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">
+TMR0 overflow interrupt
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-size
+SIG_TX
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-destination register
+USART transmit interrupt
\end_inset
</cell>
</row>
\layout Standard
-8 bits
+SIG_TMR1
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-WREG
+TMR1 overflow interrupt
\end_inset
</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-16 bits
+SIG_MSSP
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-PRODL:WREG
+SSP receive/transmit interrupt
\end_inset
</cell>
</row>
\layout Standard
-24 bits
+SIG_TMR2
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-PRODH:PRODL:WREG
+TMR2 matches PR2 interrupt
\end_inset
</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-32 bits
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-FSR0L:PRODH:PRODL:WREG
\end_inset
</cell>
</row>
\layout Standard
->32 bits
+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">
\layout Standard
-on stack, FSR0 points to the beginning
\end_inset
</cell>
</row>
\end_inset
-\layout Subsection
+\layout Standard
-Interrupts
+The prototypes for these names are defined in the header file
+\emph on
+signal.h
+\emph default
+ .
\layout Standard
-When entering an interrupt, currently the PIC16
-\begin_inset LatexCommand \index{PIC16}
+In order to simplify signal handling, a number of macros is provided:
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+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
- port automatically saves the following registers:
-\layout Itemize
+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
-WREG
-\layout Itemize
+DEF_HANDLER(sig,handler) define a handler for signal
+\emph on
+sig.
+\layout List
+\labelwidthstring 00.00.0000
-STATUS
-\layout Itemize
+END_DEF end the declaration of the dispatch table.
+\layout Standard
-BSR
+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
-PROD (PRODL and PRODH)
+do not place a colon (;) at the end of the DEF_* and END_DEF macros.
\layout Itemize
-FSR0 (FSR0L and FSR0H)
+when declaring SIGHANDLERNAKED handler never forget to use
+\emph on
+retfie
+\emph default
+ for proper returning.
+\layout Subsection
+
+PIC16 Port -- Tips
\layout Standard
-These registers are restored upon return from the interrupt routine.
-
+Here you can find some general tips for compiling programs with SDCC/pic16.
+\layout Subsubsection
+
+Stack size
\layout Standard
-When entering a high priority interrupt WREG, STATUS and BSR are not explicit
- saved by software.
- The hardware shadow registers for WREG, STATUS and BSR are used in these
- cases.
+The default stack 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
-
-\begin_inset Foot
-collapsed false
+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
-NOTE that when the _naked attribute is specified for an interrupt routine,
- then NO registers are stored or restored.
+\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 Chapter
Debugging with SDCDB
use an 'unsigned char' instead of a 'short' or 'int'.
Please note, that ANSI C requires both signed and unsigned chars to be
promoted to 'signed int' before doing any operation.
- This promotion can be omitted, if the result is the same.
+ This promotion
+\begin_inset LatexCommand \index{type promotion}
+
+\end_inset
+
+ can be omitted, if the result is the same.
The effect of the promotion rules together with the sign-extension is often
surprising:
\begin_deeper
\layout Standard
-ASXXXX Assemblers and ASLINK Relocating Linker
+ASXXXX
+\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Assembler documentation}
+
+\end_inset
+
+ Assemblers and ASLINK
+\begin_inset LatexCommand \index{aslink}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Linker documentation}
+
+\end_inset
+
+ Relocating Linker
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
\end_inset
\layout Standard
-\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
+\begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
\end_inset
\layout Standard
-\begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
+\begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
\end_inset
\layout Standard
srecord
-\begin_inset LatexCommand \index{srecord (tool)}
+\begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
\end_inset
\layout Standard
-\begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
\end_inset
\layout Standard
-\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
+\begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
\end_inset
\size footnotesize
-\begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
+\begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
\end_inset
More examples and libraries are available at
\emph on
The SDCC Open Knowledge Resource
-\begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
+\begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
\end_inset
\SpecialChar ~
global = 2;
\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
}
\layout Subsection
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-<for body>
-\layout Itemize
-
-The <for body> does not contain
-\begin_inset Quotes eld
-\end_inset
-
-continue
-\begin_inset Quotes erd
-\end_inset
-
- or 'break
-\begin_inset Quotes erd
-\end_inset
-
-.
-\layout Itemize
-
-All goto's are contained within the loop.
-\layout Itemize
-
-No function calls within the loop.
-\layout Itemize
-
-The loop control variable <sym> is not assigned any value within the loop
-\layout Itemize
-
-The loop control variable does NOT participate in any arithmetic operation
- within the loop.
-\layout Itemize
-
-There are NO switch statements in the loop.
-\layout Subsection
-
-Algebraic Simplifications
-\layout Standard
-
-SDCC does numerous algebraic simplifications, the following is a small sub-set
- of these optimizations.
-\layout Verse
-
-
-\family typewriter
-i = j + 0;\SpecialChar ~
+<for body>
+\layout Itemize
+
+The <for body> does not contain
+\begin_inset Quotes eld
+\end_inset
+
+continue
+\begin_inset Quotes erd
+\end_inset
+
+ or 'break
+\begin_inset Quotes erd
+\end_inset
+
+.
+\layout Itemize
+
+All goto's are contained within the loop.
+\layout Itemize
+
+No function calls within the loop.
+\layout Itemize
+
+The loop control variable <sym> is not assigned any value within the loop
+\layout Itemize
+
+The loop control variable does NOT participate in any arithmetic operation
+ within the loop.
+\layout Itemize
+
+There are NO switch statements in the loop.
+\layout Subsection
+
+Algebraic Simplifications
+\layout Standard
+
+SDCC does numerous algebraic simplifications, the following is a small sub-set
+ of these optimizations.
+\layout Verse
+
+
+\family typewriter
+i = j + 0;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = j;
+\newline
+i /= 2;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i >>= 1;
+\newline
+i = j - j;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = 0;
+\newline
+i = j / 1;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = j;
+\layout Standard
+
+Note the subexpressions
+\begin_inset LatexCommand \index{Subexpression}
+
+\end_inset
+
+ given above are generally introduced by macro expansions or as a result
+ of copy/constant propagation.
+\layout Subsection
+
+'switch' Statements
+\begin_inset LatexCommand \label{sub:'switch'-Statements}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{switch statement}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC can optimize switch statements to jump tables
+\begin_inset LatexCommand \index{jump tables}
+
+\end_inset
+
+.
+ It makes the decision based on an estimate of the generated code size.
+ SDCC is quite liberal in the requirements for jump table generation:
+\layout Itemize
+
+The labels need not be in order, and the starting number need not be one
+ or zero, the case labels are in numerical sequence or not too many case
+ labels are missing.
+\begin_deeper
+\layout Verse
+
+
+\family typewriter
+switch(i) {\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+switch (i) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 0: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 5: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- /* changed to: */\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- i = j;
-\newline
-i /= 2;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- /* changed to: */\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- i >>= 1;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+
\newline
-i = j - j;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- /* changed to: */\SpecialChar ~
+case 6: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- i = 0;
-\newline
-i = j / 1;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- /* changed to: */\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- i = j;
-\layout Standard
-
-Note the subexpressions
-\begin_inset LatexCommand \index{Subexpression}
-
-\end_inset
-
- given above are generally introduced by macro expansions or as a result
- of copy/constant propagation.
-\layout Subsection
-
-'switch' Statements
-\begin_inset LatexCommand \label{sub:'switch'-Statements}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{switch statement}
-
-\end_inset
-
-
-\layout Standard
-
-SDCC changes switch statements to jump tables
-\begin_inset LatexCommand \index{jump tables}
-
-\end_inset
-
- when the following conditions are true.
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
-\layout Itemize
-
-The case labels are in numerical sequence, the labels need not be in order,
- and the starting number need not be one or zero.
-\begin_deeper
-\layout Verse
-
-
-\family typewriter
-switch(i) {\SpecialChar ~
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+case 7: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-switch (i) {
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...
+
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 4: ...\SpecialChar ~
+case 8: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 0: ...
+case 5: ...
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 5: ...\SpecialChar ~
+case 9: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 1: ...
+case 6: ...
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 3: ...\SpecialChar ~
-\SpecialChar ~
+case 10: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 2: ...
+case 7: ...
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 6: ...\SpecialChar ~
-\SpecialChar ~
+case 11: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 3: ...
+case 8: ...
\newline
}\SpecialChar ~
\end_deeper
\layout Itemize
-The number of case labels is at least three, since it takes two conditional
- statements to handle the boundary conditions.
+The number of case labels is not larger than supported by the target architectur
+e.
\layout Itemize
-The number of case labels is less than 84, since each label takes 3 bytes
- and a jump-table can be utmost 256 bytes long.
+If the case labels are not in numerical sequence ('gaps' between cases)
+ SDCC checks whether a jump table with additionally inserted dummy cases
+ is still attractive.
+
+\layout Itemize
+
+If the starting number is not zero and a check for the lower boundary of
+ the jump-table can thus be eliminated SDCC might insert dummy cases 0,
+ ...
+ .
\layout Standard
-Switch statements which have gaps in the numeric sequence or those that
- have more that 84 case labels can be split into more than one switch statement
+Switch statements which have large gaps in the numeric sequence or those
+ that have too many case labels can be split into more than one switch statement
for efficient code generation, e.g.:
\layout Verse
\newline
\SpecialChar ~
\SpecialChar ~
-case 9: ...
+case 5: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 101: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 102: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 103: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 104: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 10: ...
+case 105: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 11: ...
+case 106: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 12: ...
+case 107: ...
\newline
}
\SpecialChar ~
case 4: ...
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 5: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...
+
\newline
}
\layout Standard
\newline
\SpecialChar ~
\SpecialChar ~
-case 9:\SpecialChar ~
+case 101: ...
+
+\newline
\SpecialChar ~
-...
+\SpecialChar ~
+case 102: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 10:\SpecialChar ~
-...
+case 103: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 11:\SpecialChar ~
-...
+case 104: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 12:\SpecialChar ~
-...
+case 105: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 106: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 107: ...
\newline
}
then both the switch statements will be implemented using jump-tables whereas
the unmodified switch statement will not be.
- You might also consider inserting dummy cases 0 and 5 to 8 in this example.
-
-\newline
+\layout Comment
+
+There might be reasons which SDCC cannot know about to either favour or
+ not favour jump tables.
+ If the target system has to be as quick for the last switch case as for
+ the first (pro jump table), or if the switch argument is known to be zero
+ in the majority of the cases (contra jump table).
+\layout Standard
+
The pragma nojtbound
\begin_inset LatexCommand \index{\#pragma nojtbound}
\emph default
aries.
It has no effect if a default label is supplied.
- Use of this pragma is dangerous: if the switch argument is not matched
- by a case statement the processor will happily jump into Nirvana.
+ Use of this pragma is dangerous: if the switch
+\begin_inset LatexCommand \index{switch statement}
+
+\end_inset
+
+ argument is not matched by a case statement the processor will happily
+ jump into Nirvana.
\layout Subsection
Bit-shifting Operations
copt
\emph default
a peep-hole optimizer by Christopher W.
- Fraser (cwfraser@microsoft.com).
+ Fraser (cwfraser\SpecialChar ~
+@\SpecialChar ~
+microsoft.com).
A default set of rules are compiled into the compiler, additional rules
may be added with the
\emph on
Deviations from the compliance:
\layout Itemize
-functions are not always reentrant
+functions are not reentrant
\begin_inset LatexCommand \index{reentrant}
\end_inset
-.
+ unless explicitly declared as such or the
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+
+\series default
+ command line option is specified.
\layout Itemize
-structures cannot be assigned values directly, cannot be passed as function
- parameters or assigned to each other and cannot be a return value from
- a function, e.g.:
+structures and unions cannot be assigned values directly, cannot be passed
+ as function parameters or assigned to each other and cannot be a return
+ value from a function, e.g.:
\begin_deeper
\layout Verse
\newline
}
\end_deeper
+\layout Itemize
+
+Certain words that are valid identifiers in the standard may be reserved
+ words in SDCC unless the
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-std-c89
+\begin_inset LatexCommand \index{-\/-std-c89}
+
+\end_inset
+
+ or -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-std-c99
+\begin_inset LatexCommand \index{-\/-std-c99}
+
+\end_inset
+
+
+\series default
+ command line options are used.
+ These may include (depending on the selected processor): 'at', 'banked',
+ 'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
+t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
+ 'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
+ '_naked'.
+ Compliant equivalents of these keywords are always available in a form
+ that begin with two underscores
+\begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
+
+\end_inset
+
+, f.e.
+ '__data' instead of 'data'.
\layout Section
Cyclomatic Complexity
\shape italic
This is an excerpt from an article published in Circuit Cellar Magazine
- in august 2000.
+ in
+\series bold
+August 2000
+\series default
+.
It's a little outdated (the compiler is much more efficient now and user/develo
per friendly), but pretty well exposes the guts of it all.
\shape default
\series bold
\shape italic
\color red
-<Where is Figure II ?>
+<Where is Figure II?>
+\layout Comment
+
+In the original article Figure II was announced to be downloadable on
+\shape italic
+Circuit Cellar
+\shape default
+'s web site.
+ Unfortunately it never seemed to have shown up there, so: where is Figure
+ II?
\layout Paragraph*
ICode Example
projects / fw / sdcc / blobdiff