\lyxformat 221
\textclass book
\begin_preamble
+
+
\usepackage[
pdftitle={SDCC Compiler User Guide},
pdfauthor={SDCC development team},
\size normal
-SDCC 2.3.7
+SDCC 2.4.7
\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
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
Web links to other SDCC related sites can also be found here.
This document can be found in the DOC directory of the source package as
a text or HTML file.
+ A pdf version of this document is available at
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
+
+\end_inset
+
+.
Some of the other tools (simulator and assembler) included with SDCC contain
their own documentation and can be found in the source distribution.
If you want the latest unreleased software, the complete source package
\newline
\family default
-If you can think of some more, please see the chapter
+If you can think of some more, please see the section
\begin_inset LatexCommand \ref{sub:Requesting-Features}
\end_inset
\layout Standard
Of course this doesn't change the search paths compiled into the binaries.
+\newline
+
+\newline
+Moreover the install path can be changed by defining DESTDIR
+\begin_inset LatexCommand \index{DESTDIR}
+
+\end_inset
+
+:
+\layout LyX-Code
+
+make install DESTDIR=$(HOME)/sdcc.rpm/
+\layout Standard
+
+Please note that DESTDIR must have a trailing slash!
\layout Section
Search Paths
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)
\newline
+\newline
+WARNING: Visual studio is very picky with line terminations; it expects
+ the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
+ If you are getting a message such as "This makefile was not generated by
+ Developer Studio etc.
+ etc.
+\begin_inset Quotes srd
+\end_inset
+
+ when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
+ need to convert the Unix style line endings to DOS style line endings.
+ To do so you can use the
+\begin_inset Quotes sld
+\end_inset
+
+unix2dos
+\begin_inset Quotes srd
+\end_inset
+
+ utility freely available on the internet.
+ Doug Hawkins reported in the sdcc-user list that this works:
+\newline
+
+\newline
+C:
+\backslash
+Programming
+\backslash
+SDCC> unix2dos sdcc.dsw
+\newline
+C:
+\backslash
+Programming
+\backslash
+SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
+\newline
+
\newline
In order to build SDCC with MSVC you need win32 executables of bison.exe,
flex.exe, and gawk.exe.
Building the Documentation
\layout Standard
-If the necessary tools (LyX, LaTeX, latex2html) are installed it is as easy
+If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
as changing into the doc directory and typing
\family sans
\series bold
\family default
\series default
there.
- You're invited to make changes and additions to this manual.
+ You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
+x).
Using LyX
\begin_inset LatexCommand \url{www.lyx.org}
\end_inset
as editor this is straightforward.
- If you want to avoid installing the tools you will have some success with
- a bootable Knoppix CD
-\begin_inset LatexCommand \url{http://www.knoppix.net}
-
-\end_inset
-
-.
Prebuilt documentation in html and pdf format is available from
\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
Currently reading the document in pdf format is recommended, as for unknown
reason the hyperlinks are working there whereas in the html version they
- are not.
+ are not
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+If you should know why please drop us a note
+\end_inset
+
+.
+ You'll find the pdf version at
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
+
+\end_inset
+
+.
\newline
This documentation is in some aspects different from a commercial documentation:
currently matches SDCC for mcs51 and DS390 best and does give too few informati
on about f.e.
- Z80, PIC and HC08.
+ Z80, PIC14, PIC16 and HC08.
\layout Itemize
There are many references pointing away from this documentation.
\end_inset
).
- Both formats are documented in the the documentation of srecord
+ Both formats are documented in the documentation of srecord
\begin_inset LatexCommand \index{srecord (tool)}
\end_inset
\layout Itemize
sourcefile.adb
-\begin_inset LatexCommand \index{.adb}
+\begin_inset LatexCommand \index{<file>.adb}
\end_inset
- An intermediate file containing debug information needed to create the
.cdb file (with -
\begin_inset ERT
-status Collapsed
+status Open
\layout Standard
file specified in the command line, since the linkage editor processes
file in the order they are presented to it.
The linker is invoked from SDCC using a script file with extension .lnk
-\begin_inset LatexCommand \index{.lnk}
+\begin_inset LatexCommand \index{<file>.lnk}
\end_inset
for how to create a
\emph on
.lib
-\begin_inset LatexCommand \index{.lib}
+\begin_inset LatexCommand \index{<file>.lib}
\end_inset
libsdcc.lib
\emph default
in the directory <installdir>/share/lib/small.
-\layout Section
-
-Command Line Options
-\begin_inset LatexCommand \index{Command Line Options}
-
-\end_inset
-
-
\layout Subsection
-Processor Selection Options
-\begin_inset LatexCommand \index{Options processor selection}
+Using sdcclib to Create and Manage Libraries
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\begin_inset LatexCommand \index{Processor selection options}
-
-\end_inset
+\layout Standard
+Alternatively, instead of having a .rel file for each entry on the library
+ file as described in the preceding section, sdcclib can be used to embed
+ all the modules belonging to such library in the library file itself.
+ This results in a larger library file, but it greatly reduces the number
+ of disk files accessed by the linker.
+ Additionally, the packed library file contains an index of all include
+ modules and symbols that significantly speeds up the linking process.
+ To display a list of options supported by sdcclib type:
+\newline
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+\family sans
\series bold
--mmcs51
-\begin_inset LatexCommand \index{-mmcs51}
+sdcclib -?
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\series default
- Generate code for the Intel MCS51
-\begin_inset LatexCommand \index{MCS51}
+\newline
-\end_inset
+\newline
- family of processors.
- This is the default processor target.
-\layout List
-\labelwidthstring 00.00.0000
+\family default
+\series default
+To create a new library file, start by compiling all the required modules.
+ For example:
+\newline
+
+\layout Standard
+\family sans
\series bold
--mds390
-\begin_inset LatexCommand \index{-mds390}
-
-\end_inset
+sdcc -c _divsint.c
+\layout Standard
-\series default
- Generate code for the Dallas DS80C390
-\begin_inset LatexCommand \index{DS80C390}
+\family sans
+\series bold
+sdcc -c _divuint.c
+\layout Standard
-\end_inset
- processor.
-\layout List
-\labelwidthstring 00.00.0000
+\family sans
+\series bold
+sdcc -c _modsint.c
+\layout Standard
+\family sans
\series bold
--mds400
-\begin_inset LatexCommand \index{-mds400}
+sdcc -c _moduint.c
+\layout Standard
-\end_inset
+\family sans
+\series bold
+sdcc -c _mulint.c
+\newline
-\series default
- Generate code for the Dallas DS80C400
-\begin_inset LatexCommand \index{DS80C400}
+\layout Standard
-\end_inset
+This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
+ and _mulint.rel.
+ The next step is to add the .rel files to the library file:
+\newline
- processor.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+\family sans
\series bold
--mhc08
-\begin_inset LatexCommand \index{-mhc08}
+sdcclib libint.lib _divsint.rel
+\family default
+
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\series default
- Generate code for the Motorola HC08
-\begin_inset LatexCommand \index{HC08}
+\layout Standard
-\end_inset
- family of processors (added Oct 2003).
-\layout List
-\labelwidthstring 00.00.0000
+\family sans
+\series bold
+sdcclib libint.lib _divuint.rel
+\layout Standard
+\family sans
\series bold
--mz80
-\begin_inset LatexCommand \index{-mz80}
+sdcclib libint.lib _modsint.rel
+\layout Standard
-\end_inset
+
+\family sans
+\series bold
+sdcclib libint.lib _moduint.rel
+\layout Standard
+\family sans
+\series bold
+sdcclib libint.lib _mulint.rel
\series default
- Generate code for the Zilog Z80
-\begin_inset LatexCommand \index{Z80}
-\end_inset
+\newline
- family of processors.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+
+If the file already exists in the library, it will be replaced.
+ To see what modules and symbols are included in the library, options -s
+ and -m are available.
+ For example:
+\newline
+\newline
+\family sans
\series bold
--mgbz80
-\begin_inset LatexCommand \index{-mgbz80}
+sdcclib -s libint.lib
+\family default
+
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\series default
- Generate code for the GameBoy Z80
-\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
+\newline
-\end_inset
+\family typewriter
+\series default
+_divsint.rel:
+\layout Standard
- processor (Not actively maintained).
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__divsint_a_1_1
+\layout Standard
-\series bold
--mavr
-\begin_inset LatexCommand \index{-mavr}
-\end_inset
+\family typewriter
+__divsint_PARM_2
+\layout Standard
-\series default
- Generate code for the Atmel AVR
-\begin_inset LatexCommand \index{AVR}
+\family typewriter
+__divsint
+\newline
+_divuint.rel:
+\layout Standard
-\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/}
+\family typewriter
+__divuint_a_1_1
+\layout Standard
-\end_inset
-.
-\layout Comment
+\family typewriter
+__divuint_PARM_2
+\layout Standard
-I think it is fair to direct users there for now.
- Open source is also about avoiding unnecessary work .
- But I didn't find the 'official' link.
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__divuint_reste_1_1
+\layout Standard
-\series bold
--mpic14
-\begin_inset LatexCommand \index{-mpic14}
-\end_inset
+\family typewriter
+__divuint_count_1_1
+\layout Standard
-\series default
- Generate code for the Microchip PIC 14
-\begin_inset LatexCommand \index{PIC14}
+\family typewriter
+__divuint
+\newline
+_modsint.rel:
+\layout Standard
-\end_inset
--bit processors (p16f84 and variants.
- In development, not complete).
-\layout Comment
+\family typewriter
+__modsint_a_1_1
+\layout Standard
-p16f627 p16f628 p16f84 p16f873 p16f877?
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__modsint_PARM_2
+\layout Standard
-\series bold
--mpic16
-\begin_inset LatexCommand \index{-mpic16}
-\end_inset
+\family typewriter
+__modsint
+\newline
+_moduint.rel:
+\layout Standard
-\series default
- Generate code for the Microchip PIC 16
-\begin_inset LatexCommand \index{PIC16}
+\family typewriter
+__moduint_a_1_1
+\layout Standard
-\end_inset
+
+\family typewriter
+__moduint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__moduint_count_1_1
+\layout Standard
+
+
+\family typewriter
+__moduint
+\newline
+_mulint.rel:
+\layout Standard
+
+
+\family typewriter
+__mulint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__mulint
+\family default
+\series bold
+
+\newline
+
+\layout Standard
+
+If the source files are compiled using -
+\begin_inset ERT
+status Open
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
+
+\end_inset
+
+, the corresponding debug information file .adb will be include in the library
+ file as well.
+ The library files created with sdcclib are plain text files, so they can
+ be viewed with a text editor.
+ It is not recomended to modify a library file created with sdcclib using
+ a text editor, as there are file indexes numbers located accross the file
+ used by the linker to quickly locate the required module to link.
+ Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
+ it can be safely deleted, since all the information required for linking
+ is embedded in the library file itself.
+ Library files created using sdcclib are used as described in the preceding
+ sections.
+\layout Section
+
+Command Line Options
+\begin_inset LatexCommand \index{Command Line Options}
+
+\end_inset
+
+
+\layout Subsection
+
+Processor Selection Options
+\begin_inset LatexCommand \index{Options processor selection}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Processor selection options}
+
+\end_inset
+
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mmcs51
+\begin_inset LatexCommand \index{-mmcs51}
+
+\end_inset
+
+
+\series default
+ Generate code for the Intel MCS51
+\begin_inset LatexCommand \index{MCS51}
+
+\end_inset
+
+ family of processors.
+ This is the default processor target.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mds390
+\begin_inset LatexCommand \index{-mds390}
+
+\end_inset
+
+
+\series default
+ Generate code for the Dallas DS80C390
+\begin_inset LatexCommand \index{DS80C390}
+
+\end_inset
+
+ processor.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mds400
+\begin_inset LatexCommand \index{-mds400}
+
+\end_inset
+
+
+\series default
+ Generate code for the Dallas DS80C400
+\begin_inset LatexCommand \index{DS80C400}
+
+\end_inset
+
+ processor.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mhc08
+\begin_inset LatexCommand \index{-mhc08}
+
+\end_inset
+
+
+\series default
+ Generate code for the Motorola HC08
+\begin_inset LatexCommand \index{HC08}
+
+\end_inset
+
+ family of processors (added Oct 2003).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mz80
+\begin_inset LatexCommand \index{-mz80}
+
+\end_inset
+
+
+\series default
+ Generate code for the Zilog Z80
+\begin_inset LatexCommand \index{Z80}
+
+\end_inset
+
+ family of processors.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mgbz80
+\begin_inset LatexCommand \index{-mgbz80}
+
+\end_inset
+
+
+\series default
+ Generate code for the GameBoy Z80
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
+
+\end_inset
+
+ processor (Not actively maintained).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mavr
+\begin_inset LatexCommand \index{-mavr}
+
+\end_inset
+
+
+\series default
+ Generate code for the Atmel AVR
+\begin_inset LatexCommand \index{AVR}
+
+\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/}
+
+\end_inset
+
+ or winavr
+\begin_inset LatexCommand \url{http://winavr.sourceforge.net}
+
+\end_inset
+
+.
+\layout Comment
+
+I think it is fair to direct users there for now.
+ Open source is also about avoiding unnecessary work .
+ But I didn't find the 'official' link.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mpic14
+\begin_inset LatexCommand \index{-mpic14}
+
+\end_inset
+
+
+\series default
+ Generate code for the Microchip PIC 14
+\begin_inset LatexCommand \index{PIC14}
+
+\end_inset
+
+-bit processors (p16f84 and variants.
+ In development, not complete).
+\layout Comment
+
+p16f627 p16f628 p16f84 p16f873 p16f877?
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mpic16
+\begin_inset LatexCommand \index{-mpic16}
+
+\end_inset
+
+
+\series default
+ Generate code for the Microchip PIC 16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
-bit processors (p18f452 and variants.
In development, not complete).
\end_inset
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
+
+\end_inset
+
+
\layout List
\labelwidthstring 00.00.0000
\end_inset
...
- Pass the preprocessorOption to the preprocessor.
+ Pass the preprocessorOption to the preprocessor
+\family typewriter
+sdcpp
+\family default
+
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
+
+\end_inset
+
+.
+ SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
+ Collection (gcc), if you need more dedicated options please refer to the
+ documentation at
+\begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
+
+\end_inset
+
+.
\layout Subsection
Linker Options
Causes the linker to check if the code memory usage is within limits of
the given value.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-size
+\series default
+\SpecialChar ~
+<Value>
+\begin_inset LatexCommand \index{-\/-stack-size <Value>}
+
+\end_inset
+
+ Causes the linker to check if there is at minimum <Value> bytes for stack.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pack-iram
+\series default
+\SpecialChar ~
+
+\begin_inset LatexCommand \index{-\/-pack-iram}
+
+\end_inset
+
+ Causes the linker 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{-\/-pack-iram}
+
+\end_inset
+
+ Causes the linker to use old style for allocating memory areas.
\layout Subsection
DS390 / DS400 Options
\layout Subsection
-PIC Options
-\begin_inset LatexCommand \index{Options PIC}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{PIC options}
-
-\end_inset
-
-
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--gen-banksel
-\begin_inset LatexCommand \index{-\/-gen-banksel}
-
-\end_inset
-
-
-\series default
- enable the generation of banksel assembler directives in the PIC16 port.
-\layout Subsection
-
Z80 Options
\begin_inset LatexCommand \index{Options Z80}
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 ~
-NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
\end_inset
\series default
Will not do loop invariant optimizations, this may be turned off for reasons
explained for the previous option.
- For more details of loop optimizations performed see section Loop Invariants.
+ For more details of loop optimizations performed see Loop Invariants in
+ section
+\begin_inset LatexCommand \ref{sub:Loop-Optimizations}
+
+\end_inset
+
+.
It is recommended that this option NOT be used, #pragma\SpecialChar ~
-NOINVARIANT
-\begin_inset LatexCommand \index{\#pragma NOINVARIANT}
+noinvariant
+\begin_inset LatexCommand \index{\#pragma noinvariant}
\end_inset
Will not do loop induction optimizations, see section strength reduction
for more details.
It is recommended that this option is NOT used, #pragma\SpecialChar ~
-NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
\end_inset
\SpecialChar ~
Switch Statements for more details.
It is recommended that this option is NOT used, #pragma\SpecialChar ~
-NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
\end_inset
\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
\end_inset
.
- see section Parameters and Local Variables for more details.
+ See section
+\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+ Parameters and Local Variables for more details.
If this option is used all source files in the project should be compiled
with this option.
+ It automatically implies --int-long-reent and --float-reent.
\layout List
\labelwidthstring 00.00.0000
-callee-saves option string.
Also see #pragma\SpecialChar ~
-CALLEE-SAVES
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
\end_inset
\series default
- This option can be used when the code generated is called by a monitor
- program.
- The compiler will generate a 'ret' upon return from the 'main'
+ This option can be used if the code generated is called by a monitor program
+ or if the main routine includes an endless loop.
+ This option might result in slightly smaller code and save two bytes of
+ stack space.
+ The return from the 'main'
\begin_inset LatexCommand \index{main return}
\end_inset
- function.
+ function will return to the function calling main.
The default setting is to lock up i.e.
generate a '
\family typewriter
/
\end_inset
--nostdincl
-\begin_inset LatexCommand \index{-\/-nostdincl}
+-nostdinc
+\begin_inset LatexCommand \index{-\/-nostdinc}
\end_inset
\series default
Hides your ugly and inefficient c-code from the asm file, so you can always
- blame the compiler :).
+ blame the compiler :)
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-peep-comments
+\begin_inset LatexCommand \index{-\/-no-peep-comments}
+
+\end_inset
+
+
+\series default
+ Will not include peep-hole comments in the generated files.
\layout List
\labelwidthstring 00.00.0000
\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
\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
\end_inset
(or in case of some 8051 variants by a separate Special Function Register,
- see section
+ see section
\begin_inset LatexCommand \ref{sub:MCS51-variants}
\end_inset
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
The bit addressable memory consists of 128 bits which are located from 0x20
to 0x2f in data memory.
-\layout Standard
-
+\newline
Apart from this 8051 specific storage class most architectures support ANSI-C
bitfields
\begin_inset LatexCommand \index{bitfields}
\end_inset
-
+
\begin_inset Foot
collapsed false
\end_inset
.
+ In accordance with ISO/IEC 9899 bits and bitfields without an explicit
+ signed modifier are implemented as unsigned.
\layout Subsubsection
sfr
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
\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
\family typewriter
-sfr banked at 0x123 IoPort;
+sfr banked at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x123 IoPort;
\layout Standard
Writing 0x01 to this variable generates the assembly code:
\family default
.
If you include the file z180.h this will be set automatically.
+\layout Subsection
+
+HC08 Storage Class
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ Language Extensions
+\layout Subsubsection
+
+data
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
+
+\end_inset
+
+
+\layout Standard
+
+The data storage class declares a variable that resides in the first 256
+ bytes of memory (the direct page).
+ The HC08 is most efficient at accessing variables (especially pointers)
+ stored here.
+\layout Subsubsection
+
+xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+
+\layout Standard
+
+The xdata storage class declares a variable that can reside anywhere in
+ memory.
+ This is the default if no storage class is specified.
+
\layout Section
Absolute Addressing
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
- should 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
\layout Standard
For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
-r) array starts at a block (256 byte) boundary
+r) array
+\family typewriter
+\size footnotesize
+
+\begin_inset LatexCommand \index{Aligned array}
+
+\end_inset
+
+
+\family default
+\size default
+ starts at a block (256 byte) boundary
\begin_inset LatexCommand \index{block boundary}
\end_inset
-.
+ (section
+\begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
+
+\end_inset
+
+ has an example).
\newline
Absolute addresses can be specified for variables in all storage classes,
e.g.:
\family typewriter
-extern volatile bit SDI;
+extern volatile bit MOSI;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master out, slave in */
\newline
-extern volatile bit SCLK;
+extern volatile bit MISO;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master in, slave out */
\newline
-extern volatile bit CPOL;
+extern volatile bit MCLK;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master clock */
\newline
\newline
-void DS1306_put(unsigned char value)
-\newline
-{
+/* Input and Output of a byte on a 3-wire serial bus.
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+If needed adapt polarity of clock, polarity of data and bit order
+\newline
\SpecialChar ~
-unsigned char mask=0x80;
+*/
\newline
-
+unsigned char spi_io(unsigned char out_byte)
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-while(mask)
+unsigned char i=8;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-{
+do {
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDI=(value & mask)?1:0;
+MOSI = out_byte & 0x80;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SCLK=!CPOL;
+out_byte <<= 1;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SCLK=CPOL;
+MCLK = 1;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mask/=2;
-\newline
+/* _asm nop _endasm; */\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-}
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* for slow peripherals */
\newline
-}
-\layout Standard
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+if(MISO)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out_byte += 1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+MCLK = 0;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+} while(--i);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return out_byte;
+\newline
+}
+\layout Standard
Then, someplace in the code for the first hardware you would use
\layout Verse
\family typewriter
-bit at 0x80 SDI;\SpecialChar ~
+bit at 0x80 MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 0, bit 0 */
\newline
-bit at 0x81 SCLK;\SpecialChar ~
+bit at 0x81 MISO;\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 0, bit 1 */
\newline
-bit CPOL;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+bit at 0x82 MCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* This is a variable, let the linker allocate this one */
+/* I/O port 0, bit 2 */
\layout Standard
Similarly, for the second hardware you would use
\family typewriter
-bit at 0x83 SDI;\SpecialChar ~
+bit at 0x83 MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 0, bit 3 */
\newline
-bit at 0x91 SCLK;\SpecialChar ~
+bit at 0x91 MISO;\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 1, bit 1 */
\end_inset
- CPOL;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+ at 0x92 MCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* This is a variable, let the linker allocate this one */
+/* I/O port 1, bit 2 */
\layout Standard
and you can use the same hardware dependent routine without changes, as
\end_inset
+\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+
\layout Standard
Automatic (local) variables and parameters to functions can either be placed
\end_inset
- either by using the
+ by using the
\emph on
-
\begin_inset ERT
\emph default
- option or by using the
+ option, by using
+\emph on
+#pragma\SpecialChar ~
+stackauto
+\emph default
+
+\begin_inset LatexCommand \index{\#pragma stackauto}
+
+\end_inset
+
+ or by using the
\emph on
reentrant
\begin_inset LatexCommand \index{reentrant}
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-data at 0x31 unsigned char j;
+data at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x31 unsigned char j;
\newline
\SpecialChar ~
\SpecialChar ~
g the data items.
Functions that are called from an interrupt service routine should be preceded
by a #pragma\SpecialChar ~
-NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
\end_inset
of a function into the overlay segment if the inline assembler code calls
other c-functions that might use the overlay.
In that case the #pragma\SpecialChar ~
-NOOVERLAY should be used.
+nooverlay should be used.
\layout Standard
Parameters and local variables of functions that contain 16 or 32 bit multiplica
\family typewriter
-#pragma SAVE
+#pragma save
\newline
-#pragma NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+#pragma nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
\end_inset
\newline
}
\newline
-#pragma RESTORE
+#pragma restore
\newline
\newline
set_error
\emph default
would be assigned to the overlayable segment if the #pragma\SpecialChar ~
-NOOVERLAY was
+nooverlay was
not present, this could cause unpredictable runtime behavior when called
from an interrupt service routine.
The #pragma\SpecialChar ~
-NOOVERLAY ensures that the parameters and local variables for
+nooverlay ensures that the parameters and local variables for
the function are NOT overlayed.
\layout Section
\end_inset
+\layout Subsection
+
+General Information
\layout Standard
SDCC allows
\layout Standard
-Interrupt numbers and the corresponding address & descriptions for the Standard
- 8051/8052 are listed below.
- SDCC will automatically adjust the interrupt vector table to the maximum
- interrupt number specified.
+Interrupt service routines open the door for some very interesting bugs:
\newline
+If an interrupt service routine changes variables which are accessed by
+ other functions these variables have to be declared
+\emph on
+volatile
+\emph default
-\layout Standard
-\align center
+\begin_inset LatexCommand \index{volatile}
-\begin_inset Tabular
-<lyxtabular version="3" rows="7" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0in">
-<column alignment="center" valignment="top" leftline="true" width="0in">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\end_inset
+.
+
\layout Standard
-Interrupt #
+If the access to these variables is not
+\emph on
+atomic
+\begin_inset LatexCommand \index{atomic}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Description
+\emph default
+ (i.e.
+ the processor needs more than one instruction for the access and could
+ be interrupted while accessing the variable) the interrupt must be disabled
+ during the access to avoid inconsistent data.
+ Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
+ and should be protected by disabling interrupts.
+ You're not automatically on the safe side if you use 8 bit variables though.
+ We need an example here: f.e.
+ on the 8051 the harmless looking
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Vector Address
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x80;
+\family default
-\layout Standard
+\begin_inset Quotes sld
+\end_inset
-0
+ is not atomic if
+\family typewriter
+flags
+\family default
+ resides in xdata.
+ Setting
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-External 0
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x40;
+\family default
-\layout Standard
+\begin_inset Quotes sld
+\end_inset
-0x0003
+ from within an interrupt routine might get lost if the interrupt occurs
+ at the wrong time.
+
+\begin_inset Quotes sld
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-1
+\family typewriter
+counter\SpecialChar ~
++=\SpecialChar ~
+8;
+\family default
+
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ is not atomic on the 8051 even if
+\family typewriter
+counter
+\family default
+ is located in data memory.
+ Bugs like these are hard to reproduce and can cause a lot of trouble.
+
\layout Standard
-Timer 0
+The return address and the registers used in the interrupt service routine
+ are saved on the stack
+\begin_inset LatexCommand \index{stack}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ so there must be sufficient stack space.
+ If there isn't variables or registers (or even the return address itself)
+ will be corrupted.
+ This
+\emph on
+stack overflow
+\emph default
+
+\begin_inset LatexCommand \index{stack overflow}
-0x000B
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ is most likely to happen if the interrupt occurs during the
+\begin_inset Quotes sld
+\end_inset
-2
+deepest
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ subroutine when the stack is already in use for f.e.
+ many return addresses.
\layout Standard
-External 1
+A special note here, int (16 bit) and long (32 bit) integer division
+\begin_inset LatexCommand \index{Division}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+, multiplication
+\begin_inset LatexCommand \index{Multiplication}
-0x0013
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ & modulus
+\begin_inset LatexCommand \index{Modulus}
-3
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ and floating-point
+\begin_inset LatexCommand \index{Floating point support}
-Timer 1
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+ operations are implemented using external support routines developed in
+ ANSI-C.
+ If an interrupt service routine needs to do any of these operations then
+ the support routines (as mentioned in a following section) will have to
+ be recompiled using the
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
\layout Standard
-0x001B
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-int-long-reent
+\emph default
+
+\begin_inset LatexCommand \index{-\/-int-long-reent}
+
+\end_inset
+
+ compiler option.
+\layout Standard
+
+Calling other functions from an interrupt service routine is not recommended,
+ avoid it if possible.
+ Note that when some function is called from an interrupt service routine
+ it should be preceded by a #pragma\SpecialChar ~
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+
+ if it is not reentrant.
+ Furthermore nonreentrant functions should not be called from the main program
+ while the interrupt service routine might be active.
+
+\newline
+
+\newline
+Also see section
+\begin_inset LatexCommand \ref{sub:Overlaying}
+
+\end_inset
+
+\SpecialChar ~
+about Overlaying and section
+\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
+
+\end_inset
+
+\SpecialChar ~
+about Functions using private register banks.
+\layout Subsection
+
+MCS51/DS390 Interrupt Service Routines
+\layout Standard
+
+Interrupt numbers and the corresponding address & descriptions for the Standard
+ 8051/8052 are listed below.
+ SDCC will automatically adjust the interrupt vector table to the maximum
+ interrupt number specified.
+\newline
+
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="7" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Interrupt #
+\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
+
+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
+
+External 0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0003
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<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" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Timer 0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x000B
+\end_inset
+</cell>
+</row>
+<row topline="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
+
+External 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0013
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Timer 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x001B
\end_inset
</cell>
</row>
\emph on
a, b, dptr
\emph default
- & psw are save and restored, if such an interrupt service routine calls
+ & psw are saved and restored, if such an interrupt service routine calls
another function (using another register bank) then the entire register
bank of the called function will be saved on the stack.
This scheme is recommended for larger interrupt service routines.
+\layout Subsection
+
+HC08 Interrupt Service Routines
\layout Standard
-Interrupt service routines open the door for some very interesting bugs:
-
+Since the number of interrupts available is chip specific and the interrupt
+ vector table always ends at the last byte of memory, the interrupt numbers
+ corresponds to the interrupt vectors in reverse order of address.
+ For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
+ 2 will use the interrupt vector at 0xfffa, and so on.
+ However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
+ this way; instead see section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
+\end_inset
+
+ for details on customizing startup.
+\layout Subsection
+
+Z80 Interrupt Service Routines
\layout Standard
-If the interrupt service routines changes variables which are accessed by
- other functions these variables should be declared
+The Z80 uses several different methods for determining the correct interrupt
+ vector depending on the hardware implementation.
+ Therefore, SDCC ignores the optional interrupt number and does not attempt
+ to generate an interrupt vector table.
+\layout Standard
+
+By default, SDCC generates code for a maskable interrupt, which uses an
+ RETI instruction to return from the interrupt.
+ To write an interrupt handler for the non-maskable interrupt, which needs
+ an RETN instruction instead, add the
\emph on
-volatile
+critical
\emph default
+ keyword:
+\layout Verse
-\begin_inset LatexCommand \index{volatile}
-
-\end_inset
-.
+\family typewriter
+void nmi_isr (void) critical interrupt
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+\newline
+}
+\layout Section
+
+Enabling and Disabling Interrupts
+\layout Subsection
+
+Critical Functions and Critical Statements
\layout Standard
-If the access to these variables is not
+A special keyword may be associated with a block or a function declaring
+ it as
\emph on
-atomic
-\begin_inset LatexCommand \index{atomic access}
+critical
+\emph default
+.
+ SDCC will generate code to disable all interrupts
+\begin_inset LatexCommand \index{interrupt}
\end_inset
-
-\emph default
- (i.e.
- the processor needs more than one instruction for the access and could
- be interrupted while accessing the variable) the interrupt must disabled
- during the access to avoid inconsistent data.
- Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
- and should be protected by disabling interrupts.
- You're not automatically on the safe side if you use 8 bit variables though.
- We need an example here: f.e.
- on the 8051 the harmless looking
-\begin_inset Quotes srd
-\end_inset
-
-
-\family typewriter
-flags\SpecialChar ~
-|=\SpecialChar ~
-0x80;
-\family default
-
-\begin_inset Quotes sld
-\end_inset
-
- is not atomic if
-\family typewriter
-flags
-\family default
- resides in xdata.
- Setting
-\begin_inset Quotes srd
-\end_inset
-
-
-\family typewriter
-flags\SpecialChar ~
-|=\SpecialChar ~
-0x40;
-\family default
-
-\begin_inset Quotes sld
-\end_inset
-
- from within an interrupt routine might get lost if the interrupt occurs
- at the wrong time.
-
-\begin_inset Quotes sld
-\end_inset
-
-
-\family typewriter
-counter\SpecialChar ~
-+=\SpecialChar ~
-8;
-\family default
-
-\begin_inset Quotes srd
-\end_inset
-
- is not atomic on the 8051 even if
-\family typewriter
-counter
-\family default
- is located in data memory.
- Bugs like these are hard to reproduce and can cause a lot of trouble.
-
-\layout Standard
-
-A special note here, int (16 bit) and long (32 bit) integer division
-\begin_inset LatexCommand \index{Division}
-
-\end_inset
-
-, multiplication
-\begin_inset LatexCommand \index{Multiplication}
-
-\end_inset
-
- & modulus
-\begin_inset LatexCommand \index{Modulus}
-
-\end_inset
-
- and floating-point
-\begin_inset LatexCommand \index{Floating point support}
-
-\end_inset
-
- operations are implemented using external support routines developed in
- ANSI-C.
- If an interrupt service routine needs to do any of these operations then
- the support routines (as mentioned in a following section) will have to
- be recompiled using the
-\emph on
- -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
-
-\end_inset
-
-
-\emph default
- option and the source file will need to be compiled using the
-\emph on
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--int-long-reent
-\emph default
-
-\begin_inset LatexCommand \index{-\/-int-long-reent}
-
-\end_inset
-
- compiler option.
-\layout Standard
-
-Calling other functions from an interrupt service routine is not recommended,
- avoid it if possible.
- Note that when some function is called from an interrupt service routine
- it should be preceded by a #pragma\SpecialChar ~
-NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
-
-\end_inset
-
- if it is not reentrant.
- Furthermore nonreentrant functions should not be called from the main program
- while the interrupt service routine might be active.
-
-\newline
-
-\newline
-Also see section
-\begin_inset LatexCommand \ref{sub:Overlaying}
-
-\end_inset
-
-\SpecialChar ~
-about Overlaying and section
-\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
-
-\end_inset
-
-\SpecialChar ~
-about Functions using private register banks.
-\layout Section
-
-Enabling and Disabling Interrupts
-\layout Subsection
-
-Critical Functions and Critical Statements
-\layout Standard
-
-A special keyword may be associated with a function declaring it as
-\emph on
-critical
-\emph default
-.
- SDCC will generate code to disable all interrupts
-\begin_inset LatexCommand \index{interrupt}
-
-\end_inset
-
- upon entry to a critical function and restore the interrupt enable to the
- previous state before returning.
- Nesting critical functions will need one additional byte on the stack
-\begin_inset LatexCommand \index{stack}
+ upon entry to a critical function and restore the interrupt enable to the
+ previous state before returning.
+ Nesting critical functions will need one additional byte on the stack
+\begin_inset LatexCommand \index{stack}
\end_inset
On some architectures which don't support interrupt priorities these can
be implemented by manipulating the interrupt mask and reenabling interrupts
within the interrupt routine.
- Don't add complexity unless you have to.
+ Check there is sufficient space on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ and don't add complexity unless you have to.
+
+\layout 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 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
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.
- See also the compiler option
+ 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
/
\end_inset
--no-xinit
+-iram-size
+\begin_inset LatexCommand \index{-\/-iram-size}
+
+\end_inset
+
+n
\emph default
--
+ is used.
+ (recommended for Chipcon CC1010).
+\layout Standard
+
+See also the compiler option
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-xinit
+\emph default
+-
\emph on
opt
\emph default
\layout Subsection
A Step by Step Introduction
+\begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
+
+\end_inset
+
+
\layout Standard
Starting from a small snippet of c-code this example shows for the MCS51
\family typewriter
\size footnotesize
-unsigned char xdata at 0x7f00 buf[0x100];
+unsigned char far
+\begin_inset LatexCommand \index{far (storage class)}
+
+\end_inset
+
+ at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x7f00 buf[0x100];
+\begin_inset LatexCommand \index{Aligned array}
+
+\end_inset
+
+
\newline
unsigned char head,tail;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-buf[ head++ ] = c;
+buf[ head++ ] = c;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* access to a 256 byte aligned array */
\newline
}
\layout Standard
\SpecialChar ~
cjne a,ar3,00106$
\newline
-ret 00106$:
-\newline
-;buffer.c buf[ head++ ] = c;
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov\SpecialChar ~
-\SpecialChar ~
-r3,_head
+ret
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-inc\SpecialChar ~
-\SpecialChar ~
-_head
+00106$:
+\newline
+;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
+\begin_inset LatexCommand \index{Aligned array}
+
+\end_inset
+
+
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
-a,r3
+r3,_head
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add\SpecialChar ~
+inc\SpecialChar ~
\SpecialChar ~
-a,#_buf
+_head
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
-dpl,a
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-clr\SpecialChar ~
-\SpecialChar ~
-a
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-addc\SpecialChar ~
-a,#(_buf >> 8)
+dpl,r3
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
-dph,a
+dph,#(_buf >> 8)
\newline
\SpecialChar ~
\SpecialChar ~
The new file buffer.c should compile with only one warning about the unreferenced
function argument 'c'.
Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
- and finally have:
+ (1) and finally have:
\layout Verse
\family typewriter
\size footnotesize
-unsigned char xdata at 0x7f00 buf[0x100];
+unsigned char far at 0x7f00 buf[0x100];
\newline
unsigned char head,tail;
\newline
-#define USE_ASSEMBLY
+#define USE_ASSEMBLY (1)
\newline
\newline
-#ifndef USE_ASSEMBLY
+#if !USE_ASSEMBLY
+\newline
+
\newline
void to_buffer( unsigned char c )
\newline
; MUST explicitly include ret or reti in _naked function
\layout Standard
-The related #pragma directive EXCLUDE
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+The related directive #pragma exclude
+\begin_inset LatexCommand \index{\#pragma exclude}
\end_inset
in sdcc/device/lib.
\layout Standard
+The default
+\family typewriter
+ printf()
+\begin_inset LatexCommand \index{printf()}
+
+\end_inset
+
+
+\family default
+implementation in
+\family typewriter
+ printf_large.c
+\family default
+ does not support float (except on ds390).
+ To enable this recompile it with the option
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+DUSE_FLOATS=1
+\begin_inset LatexCommand \index{USE\_FLOATS}
+
+\end_inset
+
+
+\emph default
+ on the command line.
+ Use
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-large
+\begin_inset LatexCommand \index{-\/-model-large}
+
+\end_inset
+
+
+\emph default
+ for the mcs51 port, since this uses a lot of memory.
+\layout Standard
+
If you're short on memory you might want to use
\family typewriter
printf_small()
\emph default
of
\family typewriter
- printf()
-\begin_inset LatexCommand \index{printf()}
-
-\end_inset
-
-.
+ printf().
\family default
For the mcs51 there is an assembly version
\family typewriter
printf_fast()
\family default
- which should fit the requirements of many embedded systems.
+ which should fit the requirements of many embedded systems (by unsetting
+ #defines it can be customized to
+\emph on
+not
+\emph default
+ support long variables and field widths).
\layout Subsection
Math functions (sin, pow, sqrt etc.)
\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
-, therefore when using the External Stack option, this port
+ (see also section
+\begin_inset LatexCommand \ref{sub:MCS51-variants}
+
+\end_inset
+
+), therefore when using the External Stack option, this port
\emph on
may not
\emph default
SDCC supports the following #pragma directives:
\layout Itemize
-SAVE
-\begin_inset LatexCommand \index{\#pragma SAVE}
+save
+\begin_inset LatexCommand \index{\#pragma save}
\end_inset
- - this will save all current options to the SAVE/RESTORE stack.
- See RESTORE.
+ - this will save all current options to the save/restore stack.
+ See #pragma\SpecialChar ~
+restore.
\layout Itemize
-RESTORE
-\begin_inset LatexCommand \index{\#pragma RESTORE}
+restore
+\begin_inset LatexCommand \index{\#pragma restore}
\end_inset
- will restore saved options from the last save.
- SAVEs & RESTOREs can be nested.
- SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
- RESTORE pulls current options from the stack.
- See SAVE.
+ saves & restores can be nested.
+ SDCC uses a save/restore stack: save pushes current options to the stack,
+ restore pulls current options from the stack.
+ See #pragma\SpecialChar ~
+save.
+\newline
+
\layout Itemize
-NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
\end_inset
- - will stop global common subexpression elimination.
-\layout Itemize
-NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+\begin_inset LatexCommand \index{function prologue}
\end_inset
- - will stop loop induction optimizations.
-\layout Itemize
+ function1[,function2[,function3...]] - The compiler by default uses a caller
+ saves convention for register saving across function calls, however this
+ can cause unnecessary register pushing & popping
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
-NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+ when calling small functions from larger functions.
+ This option can be used to switch off the register saving convention for
+ the function names specified.
+ The compiler will not save registers when calling these functions, extra
+ code need to be manually inserted at the entry & exit for these functions
+ to save & restore the registers used by these functions, this can SUBSTANTIALLY
+ reduce code & improve run time performance of the generated code.
+ In the future the compiler (with inter procedural analysis) may be able
+ to determine the appropriate scheme to use for each function call.
+ If -
+\begin_inset ERT
+status Collapsed
+\layout Standard
+
+\backslash
+/
\end_inset
- - will not generate code for boundary value checking, when switch statements
- are turned into jump-tables (dangerous).
- For more details see section
-\begin_inset LatexCommand \ref{sub:'switch'-Statements}
+-callee-saves command line option is used, the function names specified
+ in #pragma\SpecialChar ~
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
\end_inset
-.
+ is appended to the list of functions specified in the command line.
\layout Itemize
-NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+exclude
+\begin_inset LatexCommand \index{\#pragma exclude}
\end_inset
- - the compiler will not overlay the parameters and local variables of a
- function.
+ none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
+ of pairs of push/pop
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
+
+ instructions in
+\emph on
+I
+\emph default
+nterrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\emph on
+S
+\emph default
+ervice
+\emph on
+R
+\emph default
+outines.
+ The directive should be placed immediately before the ISR function definition
+ and it affects ALL ISR functions following it.
+ To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
+exclude\SpecialChar ~
+none
+\begin_inset LatexCommand \index{\#pragma exclude}
+
+\end_inset
+
+.
+ See also the related keyword _naked
+\begin_inset LatexCommand \index{\_naked}
+
+\end_inset
+
+.
\layout Itemize
-LESS_PEDANTIC
-\begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
+less_pedantic
+\begin_inset LatexCommand \index{\#pragma less\_pedantic}
\end_inset
your own now ;-(
\layout Itemize
-NOLOOPREVERSE
-\begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
+disable_warning <nnnn>
+\begin_inset LatexCommand \index{\#pragma disable\_warning}
\end_inset
- - Will not do loop reversal optimization
+ - the compiler will not warn you anymore about warning number <nnnn>.
\layout Itemize
-EXCLUDE
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
\end_inset
- NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
- pair of push/pop
-\begin_inset LatexCommand \index{push/pop}
+ - will stop global common subexpression elimination.
+\layout Itemize
+
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
\end_inset
- instruction in ISR function (using interrupt
-\begin_inset LatexCommand \index{interrupt}
+ - will stop loop induction optimizations.
+\layout Itemize
+
+noinvariant
+\begin_inset LatexCommand \index{\#pragma noinvariant}
\end_inset
- keyword).
- The directive should be placed immediately before the ISR function definition
- and it affects ALL ISR functions following it.
- To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
-EXCLUDE\SpecialChar ~
-none
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+ - will not do loop invariant optimizations.
+ For more details see Loop Invariants in section
+\begin_inset LatexCommand \ref{sub:Loop-Optimizations}
\end_inset
.
\layout Itemize
-NOIV
-\begin_inset LatexCommand \index{\#pragma NOIV}
+noiv
+\begin_inset LatexCommand \index{\#pragma noiv}
\end_inset
about interrupts.
\layout Itemize
-CALLEE-SAVES
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
+
+\end_inset
+
+ - will not generate code for boundary value checking, when switch statements
+ are turned into jump-tables (dangerous).
+ For more details see section
+\begin_inset LatexCommand \ref{sub:'switch'-Statements}
\end_inset
+.
+\layout Itemize
-\begin_inset LatexCommand \index{function prologue}
+noloopreverse
+\begin_inset LatexCommand \index{\#pragma noloopreverse}
\end_inset
- function1[,function2[,function3...]] - The compiler by default uses a caller
- saves convention for register saving across function calls, however this
- can cause unnecessary register pushing & popping
-\begin_inset LatexCommand \index{push/pop}
+ - Will not do loop reversal optimization
+\layout Itemize
+
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
\end_inset
- when calling small functions from larger functions.
- This option can be used to switch off the register saving convention for
- the function names specified.
- The compiler will not save registers when calling these functions, extra
- code need to be manually inserted at the entry & exit for these functions
- to save & restore the registers used by these functions, this can SUBSTANTIALLY
- reduce code & improve run time performance of the generated code.
- In the future the compiler (with inter procedural analysis) may be able
- to determine the appropriate scheme to use for each function call.
- If -
+ - the compiler will not overlay the parameters and local variables of a
+ function.
+\layout Itemize
+
+stackauto
+\begin_inset LatexCommand \index{\#pragma stackauto}
+
+\end_inset
+
+- See option -
\begin_inset ERT
status Collapsed
/
\end_inset
--callee-saves command line option is used, the function names specified
- in #pragma\SpecialChar ~
-CALLEE-SAVES
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
- is appended to the list of functions specified in the command line.
+ and section
+\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+ Parameters and Local Variables.
+\layout 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 Standard
+
+SDCPP supports the following #pragma directives:
\layout Itemize
preproc_asm
\family typewriter
-#pragma SAVE
-\begin_inset LatexCommand \index{\#pragma SAVE}
+#pragma save
+\begin_inset LatexCommand \index{\#pragma save}
\end_inset
\SpecialChar ~
/* save the current settings */
\newline
-#pragma NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+#pragma nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
\end_inset
\SpecialChar ~
/* turnoff global subexpression elimination */
\newline
-#pragma NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+#pragma noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
\end_inset
\newline
}
\newline
-#pragma RESTORE
-\begin_inset LatexCommand \index{\#pragma RESTORE}
+#pragma restore
+\begin_inset LatexCommand \index{\#pragma restore}
\end_inset
\layout Standard
The compiler will generate a warning message when extra space is allocated.
- It is strongly recommended that the SAVE and RESTORE pragma's be used when
+ It is strongly recommended that the save and restore pragma's be used when
changing options for a function.
\layout Section
-Defines Created by the Compiler
+Defines Created by the Compiler
+\layout Standard
+
+The compiler creates the following #defines
+\begin_inset LatexCommand \index{\#defines}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Defines created by the compiler}
+
+\end_inset
+
+:
+\newline
+
+\layout Standard
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="10" 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
+
+
+\series bold
+#define
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC
+\begin_inset LatexCommand \index{SDCC}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+this Symbol is always defined
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_mcs51
+\begin_inset LatexCommand \index{SDCC\_mcs51}
+
+\end_inset
+
+ or SDCC_ds390
+\begin_inset LatexCommand \index{SDCC\_ds390}
+
+\end_inset
+
+ or SDCC_z80
+\begin_inset LatexCommand \index{SDCC\_z80}
+
+\end_inset
+
+, etc
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+depending on the model used (e.g.: -mds390
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+__mcs51
+\begin_inset LatexCommand \index{\_\_mcs51}
+
+\end_inset
+
+, __ds390
+\begin_inset LatexCommand \index{\_\_ds390}
+
+\end_inset
+
+, __hc08
+\begin_inset LatexCommand \index{\_\_hc08}
+
+\end_inset
+
+, __z80
+\begin_inset LatexCommand \index{\_\_z80}
+
+\end_inset
+
+, etc
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+depending on the model used (e.g.
+ -mz80)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_STACK_AUTO
+\begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\emph default
+ option is used
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_MODEL_SMALL
+\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-small
+\emph default
+ is used
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_MODEL_LARGE
+\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-large
+\emph default
+ is used
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_USE_XSTACK
+\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xstack
+\emph default
+ option is used
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_STACK_TENBIT
+\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-mds390
+\emph default
+ is used
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC_MODEL_FLAT24
+\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
+\emph on
+-mds390
+\emph default
+ is used
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Chapter
+
+Notes on supported Processors
+\layout Section
+
+MCS51 variants
+\begin_inset LatexCommand \label{sub:MCS51-variants}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{MCS51 variants}
+
+\end_inset
+
+
+\layout Standard
+
+MCS51 processors are available from many vendors and come in many different
+ flavours.
+ While they might differ considerably in respect to Special Function Registers
+ the core MCS51 is usually not modified or is kept compatible.
+
+\layout Subsection
+
+pdata access by SFR
+\layout Standard
+
+With the upcome of devices with internal xdata and flash memory devices
+ using port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
+
+\end_inset
+
+ as dedicated I/O port is becoming more popular.
+ Switching the high byte for pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ access which was formerly done by port P2 is then achieved by a Special
+ Function Register
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+.
+ In well-established MCS51 tradition the address of this
+\emph on
+sfr
+\emph default
+ is where the chip designers decided to put it.
+ Needless to say that they didn't agree on a common name either.
+ So that the startup code can correctly initialize xdata variables, you
+ should define an sfr with the name _XPAGE
+\family typewriter
+
+\begin_inset LatexCommand \index{\_XPAGE (mcs51)}
+
+\end_inset
+
+
+\family default
+ at the appropriate location if the default, port P2, is not used for this.
+ Some examples are:
+\layout Verse
+
+
+\family typewriter
+sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
+\layout Verse
+
+
+\family typewriter
+sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
+\layout Verse
+
+
+\family typewriter
+sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
+\layout Standard
+
+For more exotic implementations further customizations may be needed.
+ See section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
+\end_inset
+
+ for other possibilities.
+\layout Subsection
+
+Other Features available by SFR
+\layout Standard
+
+Some MCS51 variants offer features like Double DPTR
+\begin_inset LatexCommand \index{DPTR}
+
+\end_inset
+
+, multiple DPTR, decrementing DPTR, 16x16 Multiply.
+ These are currently not used for the MCS51 port.
+ If you absolutely need them you can fall back to inline assembly or submit
+ a patch to SDCC.
+\layout Section
+
+DS400 port
+\layout Standard
+
+The DS80C400 microcontroller has a rich set of peripherals.
+ In its built-in ROM library it includes functions to access some of the
+ features, among them is a TCP stack with IP4 and IP6 support.
+ Library headers (currently in beta status) and other files are provided
+ at
+\size footnotesize
+
+\begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
+
+\end_inset
+
+.
+
+\layout Section
+
+The Z80 and gbz80 port
+\layout Standard
+
+SDCC can target both the Zilog
+\begin_inset LatexCommand \index{Z80}
+
+\end_inset
+
+ and the Nintendo Gameboy's Z80-like gbz80
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
+
+\end_inset
+
+.
+ The Z80 port is passed through the same
+\emph on
+regressions tests
+\begin_inset LatexCommand \index{Regression test}
+
+\end_inset
+
+
+\emph default
+ as the MCS51 and DS390 ports, so floating point support, support for long
+ variables and bitfield support is fine.
+ See mailing lists and forums about interrupt routines.
+\layout Standard
+
+As always, the code is the authoritative reference - see z80/ralloc.c and
+ z80/gen.c.
+ The stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ frame is similar to that generated by the IAR Z80 compiler.
+ IX is used as the base pointer, HL and IY are used as a temporary registers,
+ and BC and DE are available for holding variables.
+ Return values
+\begin_inset LatexCommand \index{return value}
+
+\end_inset
+
+ for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
+ bytes).
+ The gbz80 port use the same set of registers for the return values, but
+ in a different order of significance: E (one byte), DE (two bytes), or
+ HLDE (four bytes).
+\layout Section
+
+The HC08 port
+\layout Standard
+
+The port to the Motorola HC08
+\begin_inset LatexCommand \index{HC08}
+
+\end_inset
+
+ family has been added in October 2003, and is still undergoing some basic
+ development.
+ The code generator is complete, but the register allocation is still quite
+ unoptimized.
+ Some of the SDCC's standard C library functions have embedded non-HC08
+ inline assembly and so are not yet usable.
+\newline
+
+\newline
+
+\layout Section
+
+The PIC14 port
+\layout Standard
+
+The 14bit PIC
+\begin_inset LatexCommand \index{PIC14}
+
+\end_inset
+
+ port still requires a major effort from the development community.
+ However it can work for very simple code.
+\layout Subsection
+
+C code and 14bit PIC code page
+\begin_inset LatexCommand \index{code page (pic14)}
+
+\end_inset
+
+ and RAM banks
+\begin_inset LatexCommand \index{RAM bank (pic14)}
+
+\end_inset
+
+
+\layout Standard
+
+The linker organizes allocation for the code page and RAM banks.
+ It does not have intimate knowledge of the code flow.
+ It will put all the code section of a single asm file into a single code
+ page.
+ In order to make use of multiple code pages, separate asm files must be
+ used.
+ The compiler treats all functions of a single C file as being in the same
+ code page unless it is non static.
+ The compiler treats all local variables of a single C file as being in
+ the same RAM bank unless it is an extern.
+\newline
+
+\newline
+To get the best follow these guide lines:
+\layout Enumerate
+
+make local functions static, as non static functions require code page selection
+ overhead.
+\layout Enumerate
+
+Make local variables static as extern variables require RAM bank selection
+ overhead.
+\layout Enumerate
+
+For devices that have multiple code pages it is more efficient to use the
+ same number of files as pages, i.e.
+ for the 16F877 use 4 separate files and i.e.
+ for the 16F874 use 2 separate files.
+ This way the linker can put the code for each file into different code
+ pages and the compiler can allocate reusable variables more efficiently
+ and there's less page selection overhead.
+ And as for any 8 bit micro (especially for PIC 14 as they have a very simple
+ instruction set) use 'unsigned char' whereever possible instead of 'int'.
+\layout Subsection
+
+Creating a device include file
+\layout Standard
+
+For generating a device include file use the support perl script inc2h.pl
+ kept in directory support/script.
+\layout Subsection
+
+Interrupt code
+\layout Standard
+
+For the interrupt function, use the keyword 'interrupt'
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ with level number of 0 (PIC14 only has 1 interrupt so this number is only
+ there to avoid a syntax error - it ought to be fixed).
+ E.g.:
+\layout Verse
+
+
+\family typewriter
+void Intr(void) interrupt 0
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+T0IF = 0; /* Clear timer interrupt */
+\newline
+}
+\layout Subsection
+
+Linking and assembling
+\layout Standard
+
+For assembling you can use either GPUTILS'
+\begin_inset LatexCommand \index{gputils (pic tools)}
+
+\end_inset
+
+ gpasm.exe or MPLAB's mpasmwin.exe.
+ GPUTILS is available from
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
+
+\end_inset
+
+.
+ For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
+ If you use MPLAB and an interrupt function then the linker script file
+ vectors section will need to be enlarged to link with mplink.
+\newline
+
+\newline
+Here is a
+\family typewriter
+Makefile
+\family default
+ using GPUTILS:
+\layout Verse
+
+
+\family typewriter
+.c.o:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcc -S -V -mpic14 -p16F877 $<
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+gpasm -c $*.asm
+\newline
+
+\newline
+$(PRJ).hex: $(OBJS)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
+\layout Standard
+
+Here is a
+\family typewriter
+Makefile
+\family default
+ using MPLAB:
+\layout Verse
+
+
+\family typewriter
+.c.o:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+sdcc -S -V -mpic14 -p16F877 $<
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mpasmwin /q /o $*.asm
+\newline
+
+\newline
+$(PRJ).hex: $(OBJS)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
+\layout Standard
+
+Please note that indentations within a
+\family typewriter
+ Makefile
+\family default
+ have to be done with a tabulator character.
+\layout Section
+
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port
+\layout Standard
+
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port is the portion of SDCC that is responsible to produce code for the
+ Microchip
+\begin_inset LatexCommand \index{Microchip}
+
+\end_inset
+
+(TM) microcontrollers with 16 bit core.
+ Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
+\layout Subsection
+
+Global Options
+\layout Standard
+
+PIC16 port supports the standard command line arguments as supposed, with
+ the exception of certain cases that will be mentioned in the following
+ list:
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-callee-saves See -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-all-callee-saves
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-all-callee-saves All function arguments are passed on stack by default.
+
+\emph on
+There is no need to specify this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-fommit-frame-pointer Frame pointer will be omitted when the function uses
+ no local variables.
+\layout Subsection
+
+Port Specific Options
+\begin_inset LatexCommand \index{Options PIC16}
+
+\end_inset
+
+
+\layout Standard
+
+The port specific options appear after the global options in the sdcc --help
+ output.
+\layout Subsubsection
+
+General Options
+\layout Standard
+
+General options enable certain port features and optimizations.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-nodefaultlibs do not link default libraries when linking.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-obanksel=# Set optimization level for inserting BANKSELs.
+\begin_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+0 is no optimization
+\layout List
+\labelwidthstring 00.00.0000
+
+1 checks previous used register and if it is the same then does not emit
+ BANKSEL, accounts only for labels.
+\layout List
+\labelwidthstring 00.00.0000
+
+2 tries to check the location of (even different) symbols and removes BANKSELs
+ if they are in the same bank.
+ Important: This will only work properly if the linker script does not have
+ sections across bank borders!
+\end_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pomit-config-words Omit the generation of the configuration words.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pomit-ivt Omit the generation of the interrupt vectors.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pleave-reset-vector Used in conjuction with -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pomit-ivt, instructs the port NOT to omit the reset vector.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-model=[model] Used in conjuction with the command above.
+ Defines the stack model to be used, valid stack models are :
+\begin_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\emph on
+small
+\emph default
+ Selects small stack model.
+ 8 bit stack and frame pointers.
+ Supports 256 bytes stack size.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\emph on
+large
+\emph default
+ Selects large stack model.
+ 16 bit stack and frame pointers.
+ Supports 65536 bytes stack size.
+\end_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-preplace-udata-with=[kword] Replaces the default udata keyword for allocating
+ unitialized data variables with [kword].
+ Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
+ Useful for bootloaders.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-asm= sets the full path and name of an external assembler to call.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-link= sets the full path and name of an external linker to call.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-call-tree dump call tree in .calltree file
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-mplab-comp MPLAB compatibility option.
+ Currently only suppresses special gpasm directives.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-use-crt= Use a custom run-time module instead of the defaults.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-crt Don't link the default run-time modules
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-optimize-goto Try to use (conditional) BRA instead of GOTO
+\layout Subsubsection
+
+Debugging Options
+\layout Standard
+
+Debugging options enable extra debugging information in the output files.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug-xtra Similar to -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
+
+\end_inset
+
+, but dumps more information.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug-ralloc Force register allocator to dump <source>.d file with debugging
+ information.
+ <source> is the name of the file compiled.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pcode-verbose Enable pcode debugging information in translation.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-denable-peeps Force the usage of peepholes.
+ Use with care.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-gstack Trace push/pops for stack pointer overflow
+\layout Subsection
+
+Preprocessor Macros
+\layout Standard
+
+PIC16 port defines the following preprocessor macros while translating a
+ source.
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Macro
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+pic18fxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+MCU Identification.
+
+\emph on
+xxxx
+\emph default
+ is the microcontrol identification number, i.e.
+ 452, 6620, etc
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Directories
+\layout Standard
+
+PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port uses the following directories for searching header files and libraries.
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="4">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Directory
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Target
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Command prefix
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PREFIX/sdcc/include/pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC16 specific headers
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Compiler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-I
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PREFIX/sdcc/lib/pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC16 specific libraries
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Linker
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-L
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Pragmas
+\begin_inset LatexCommand \label{sub:PIC16_Pragmas}
+
+\end_inset
+
+
+\layout Standard
+
+PIC16 port currently supports the following pragmas:
+\layout List
+\labelwidthstring 00.00.0000
+
+stack pragma stack forces the code generator to initialize the stack & frame
+ pointers at a specific address.
+ This is an adhoc solution 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.
+\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 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 one byte of the first
+ parameter will get lost.
+ This pragma should be placed in the header file to propagate the calling
+ convention to all callers.
+\layout LyX-Code
+
+#pragma wparam function1[, function2, ...]
+\layout LyX-Code
+
+\layout LyX-Code
+
+Example:
+\layout LyX-Code
+
+\layout LyX-Code
+
+/* pass one byte via stack and one byte via WREG */
+\layout LyX-Code
+
+#pragma wparam foo
+\layout LyX-Code
+
+void foo(int x);
+\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 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 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 Subsection
+
+Header Files
+\begin_inset LatexCommand \label{sub:PIC16_Header-Files}
+
+\end_inset
+
+
+\layout Standard
+
+There is one main header file that can be included to the source files using
+ the pic16 port.
+ That file is the
+\series bold
+pic18fregs.h
+\series default
+.
+ This header file contains the definitions for the processor special registers,
+ so it is necessary if the source accesses them.
+ It can be included by adding the following line in the beginning of the
+ file:
+\layout LyX-Code
+
+#include <pic18fregs.h>
+\layout Standard
+
+The specific microcontroller is selected within the pic18fregs.h automatically,
+ so the same source can be used with a variety of devices.
+\layout Subsection
+
+Libraries
+\layout Standard
+
+The libraries that PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port depends on are the microcontroller device libraries which contain
+ the symbol definitions for the microcontroller special function registers.
+ These libraries have the format pic18fxxxx.lib, where
+\emph on
+xxxx
+\emph default
+ is the microcontroller identification number.
+ The specific library is selected automatically by the compiler at link
+ stage according to the selected device.
+\layout Standard
+
+Libraries are created with gplib which is part of the gputils package
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net}
+
+\end_inset
+
+.
+\layout 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
-The compiler creates the following #defines
-\begin_inset LatexCommand \index{\#defines}
+If you need to install the headers to, do:
+\layout LyX-Code
-\end_inset
+cd device/include
+\layout LyX-Code
+su -c 'make install' # install the headers, you need the root password
+\layout LyX-Code
-\begin_inset LatexCommand \index{Defines created by the compiler}
+\layout Subsection
-\end_inset
+Memory Models
+\layout Standard
-:
-\newline
+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="10" columns="2">
+<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">
\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
-\series bold
-#define
+\layout Standard
+
+small model
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\series bold
-Description
+large model
\end_inset
</cell>
</row>
-<row topline="true">
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-SDCC
-\begin_inset LatexCommand \index{SDCC}
-
+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">
\layout Standard
-this Symbol is always defined
+24-bits
\end_inset
</cell>
</row>
-<row topline="true">
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-SDCC_mcs51
-\begin_inset LatexCommand \index{SDCC\_mcs51}
-
-\end_inset
-
- or SDCC_ds390
-\begin_inset LatexCommand \index{SDCC\_ds390}
-
+data pointers
\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
- or SDCC_z80
-\begin_inset LatexCommand \index{SDCC\_z80}
-
-\end_inset
+\layout Standard
-, etc
+16-bits
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-depending on the model used (e.g.: -mds390
+16-bits
\end_inset
</cell>
</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+</lyxtabular>
+
+\end_inset
+
\layout Standard
-__mcs51
-\begin_inset LatexCommand \index{\_\_mcs51}
+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
-, __ds390
-\begin_inset LatexCommand \index{\_\_ds390}
+) contain no reference to pointers, so they can be used with both memory
+ models.
+\layout Subsection
-\end_inset
+Stack
+\layout Standard
-, __hc08
-\begin_inset LatexCommand \index{\_\_hc08}
+The stack implementation for the PIC16 port uses two indirect registers,
+ FSR1 and FSR2.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+FSR1 is assigned as stack pointer
+\layout List
+\labelwidthstring 00.00.0000
-, __z80
-\begin_inset LatexCommand \index{\_\_z80}
+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
-, etc
+\layout Standard
+
+small
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-depending on the model used (e.g.
- -mz80)
+large
\end_inset
</cell>
</row>
\layout Standard
-SDCC_STACK_AUTO
-\begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
-
+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" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-when
-\emph on
--
-\begin_inset ERT
-status Collapsed
+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
-\backslash
-/
+Frame pointer FSR2
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--stack-auto
-\emph default
- option is used
+\layout Standard
+
+8-bits
\end_inset
</cell>
-</row>
-<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-SDCC_MODEL_SMALL
-\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
+16-bits
+\end_inset
+</cell>
+</row>
+</lyxtabular>
\end_inset
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\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
-when
-\emph on
--
-\begin_inset ERT
-status Collapsed
+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
+Function return values
\layout Standard
-\backslash
-/
-\end_inset
+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
--model-small
-\emph default
- is used
-\end_inset
-</cell>
-</row>
-<row topline="true">
+\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
-SDCC_MODEL_LARGE
-\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
-
-\end_inset
-
-
+size
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-when
-\emph on
--
-\begin_inset ERT
-status Collapsed
+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
-\backslash
-/
+8 bits
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--model-large
-\emph default
- is used
+\layout Standard
+
+WREG
\end_inset
</cell>
</row>
\layout Standard
-SDCC_USE_XSTACK
-\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
-
+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>
-<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
-when
-\emph on
--
-\begin_inset ERT
-status Collapsed
+24 bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
-
--xstack
-\emph default
- option is used
+PRODH:PRODL:WREG
\end_inset
</cell>
</row>
\layout Standard
-SDCC_STACK_TENBIT
-\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
-
-\end_inset
-
-
+32 bits
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-when
-\emph on
--mds390
-\emph default
- is used
+FSR0L:PRODH:PRODL:WREG
\end_inset
</cell>
</row>
\layout Standard
-SDCC_MODEL_FLAT24
-\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
-
-\end_inset
-
-
+>32 bits
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-when
-\emph on
--mds390
-\emph default
- is used
+on stack, FSR0 points to the beginning
\end_inset
</cell>
</row>
\end_inset
-\newline
+\layout Subsection
+
+Interrupts
+\layout Standard
+
+When entering an interrupt, currently the PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port automatically saves the following registers:
+\layout Itemize
+
+WREG
+\layout Itemize
+
+STATUS
+\layout Itemize
+
+BSR
+\layout Itemize
+
+PROD (PRODL and PRODH)
+\layout Itemize
+
+FSR0 (FSR0L and FSR0H)
+\layout Standard
+
+These registers are restored upon return from the interrupt routine.
+
+\layout Standard
+
+When entering a high priority interrupt WREG, STATUS and BSR are not explicit
+ saved by software.
+ The hardware shadow registers for WREG, STATUS and BSR are used in these
+ cases.
+\layout Standard
+
+
+\begin_inset Foot
+collapsed false
+\layout Standard
+
+NOTE that when the _naked attribute is specified for an interrupt routine,
+ then NO registers are stored or restored.
+\end_inset
+
+.
\layout Chapter
Debugging with SDCDB
Compiling for Debugging
\layout Standard
-The \SpecialChar \-
-\SpecialChar \-
-debug option must be specified for all files for which debug information
- is to be generated.
+The -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
+
+\end_inset
+
+ option must be specified for all files for which debug information is to
+ be generated.
The complier generates a .adb file for each of these files.
- The linker creates the .cdb file from the .adb files and the address information.
+ The linker creates the .cdb
+\begin_inset LatexCommand \index{<file>.cdb}
+
+\end_inset
+
+ file from the .adb
+\begin_inset LatexCommand \index{<file>.adb}
+
+\end_inset
+
+ files and the address information.
This .cdb is used by the debugger.
\layout Section
\family typewriter
\newline
-;; Current Listing ::
+;;\SpecialChar ~
+Current Listing ::
\newline
;;key\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
binding\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+-------\SpecialChar ~
\SpecialChar ~
-------\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
---------
+-------
\newline
;;
\newline
-;; n\SpecialChar ~
+;;\SpecialChar ~
+n\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-next-from-src\SpecialChar ~
+\SpecialChar ~
+sdcdb-next-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
SDCDB next command
\newline
-;; b\SpecialChar ~
+;;\SpecialChar ~
+b\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-back-from-src\SpecialChar ~
+\SpecialChar ~
+sdcdb-back-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
SDCDB back command
\newline
-;; c\SpecialChar ~
+;;\SpecialChar ~
+c\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-cont-from-src\SpecialChar ~
+\SpecialChar ~
+sdcdb-cont-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
SDCDB continue command
\newline
-;; s\SpecialChar ~
+;;\SpecialChar ~
+s\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-step-from-src\SpecialChar ~
+\SpecialChar ~
+sdcdb-step-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
SDCDB step command
\newline
-;; ?\SpecialChar ~
+;;\SpecialChar ~
+?\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-whatis-c-sexp\SpecialChar ~
+\SpecialChar ~
+sdcdb-whatis-c-sexp\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- buffer point
+\SpecialChar ~
+buffer point
\newline
-;; x\SpecialChar ~
+;;\SpecialChar ~
+x\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-delete\SpecialChar ~
+\SpecialChar ~
+sdcdbsrc-delete\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+\SpecialChar ~
given or delete arg (C-u arg x)
\newline
-;; m\SpecialChar ~
+;;\SpecialChar ~
+m\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-frame\SpecialChar ~
+sdcdbsrc-frame\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
buffer point
\newline
-;; !\SpecialChar ~
+;;\SpecialChar ~
+!\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-goto-sdcdb\SpecialChar ~
+sdcdbsrc-goto-sdcdb\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
Goto the SDCDB output buffer
\newline
-;; p\SpecialChar ~
+;;\SpecialChar ~
+p\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-print-c-sexp\SpecialChar ~
+sdcdb-print-c-sexp\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- buffer point
+\SpecialChar ~
+buffer point
\newline
-;; g\SpecialChar ~
+;;\SpecialChar ~
+g\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-goto-sdcdb\SpecialChar ~
+sdcdbsrc-goto-sdcdb\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
Goto the SDCDB output buffer
\newline
-;; t\SpecialChar ~
+;;\SpecialChar ~
+t\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-mode\SpecialChar ~
+sdcdbsrc-mode\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\newline
;;
\newline
-;; C-c C-f\SpecialChar ~
+;;\SpecialChar ~
+C-c\SpecialChar ~
+C-f\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-finish-from-src\SpecialChar ~
+sdcdb-finish-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\newline
;;
\newline
-;; C-x SPC\SpecialChar ~
+;;\SpecialChar ~
+C-x\SpecialChar ~
+SPC\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-break\SpecialChar ~
+sdcdb-break\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
Set break for line with point
\newline
-;; ESC t\SpecialChar ~
+;;\SpecialChar ~
+ESC\SpecialChar ~
+t\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-mode\SpecialChar ~
+sdcdbsrc-mode\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
Toggle Sdcdbsrc mode
\newline
-;; ESC m\SpecialChar ~
+;;\SpecialChar ~
+ESC\SpecialChar ~
+m\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-srcmode\SpecialChar ~
+sdcdbsrc-srcmode\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- Toggle list mode
+\SpecialChar ~
+Toggle list mode
\newline
;;
\newline
promoted to 'signed int' before doing any operation.
This promotion can be omitted, if the result is the same.
The effect of the promotion rules together with the sign-extension is often
- supprising:
+ surprising:
\begin_deeper
\layout Verse
\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">
\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="10" columns="3">
+<lyxtabular version="3" rows="11" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="block" valignment="top" leftline="true" width="30line%">
\layout Standard
gpsim
-\begin_inset LatexCommand \index{gpsim (PIC simulator)}
+\begin_inset LatexCommand \index{gpsim (pic simulator)}
\end_inset
\end_inset
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+gputils
+\begin_inset LatexCommand \index{gputils (pic tools)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+GNU PIC utilities
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-Statically checks c sources
+Statically checks c sources (has anyone adapted splint for SDCC?)
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="3">
+<lyxtabular version="3" rows="6" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="block" valignment="top" leftline="true" width="30line%">
\layout Standard
-Where to get
+Where to get
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+c-refcard.pdf
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+C Reference Card
+\begin_inset LatexCommand \index{C Reference card}
+
+\end_inset
+
+, 2 pages
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
+
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+c-faq
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+C-FAQ-list
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-c-refcard.pdf
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-C Reference Card
-\begin_inset LatexCommand \index{C Reference card}
-
-\end_inset
-
-, 2 pages
+Latest datasheet of the target CPU
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
-
-\end_inset
-
-
+vendor
\end_inset
</cell>
</row>
\layout Standard
-c-faq
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-C-FAQ-list
+Revision history of datasheet
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
-
-\end_inset
-
-
+vendor
\end_inset
</cell>
</row>
is the project done if you think it is done? Or is just that other interface/pro
tocol/feature/configuration/option missing? How about website, manual(s),
- internationalization, packaging, labels, electromagnetic compatability/interfer
-ence, documentation for production, production test software, update mechanism,
- patent issues?
+ internationali(z|s)ation, packaging, labels, 2nd source for components,
+ electromagnetic compatability/interference, documentation for production,
+ production test software, update mechanism, patent issues?
\layout Itemize
is your project adequately positioned in that magic triangle: fame, fortune,
.
You'll find the complete set of mailing lists
-\begin_inset LatexCommand \index{Mailing list}
+\begin_inset LatexCommand \index{Mailing list(s)}
\end_inset
\layout Enumerate
-Specify the SDCC version (type "sdcc -v"), your platform, and operating
- system.
+Specify the SDCC version (type "
+\family sans
+\series bold
+sdcc -v
+\family default
+\series default
+"), your platform, and operating system.
\layout Enumerate
.
\layout Section
+Submitting patches
+\layout Standard
+
+Like bug reports contributed patches are forwarded to the developer mailing
+ list.
+ This is the link for submitting patches
+\begin_inset LatexCommand \index{Patch submission}
+
+\end_inset
+
+:
+\begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
+
+\end_inset
+
+.
+\layout Standard
+
+You need to specify some parameters to the
+\family typewriter
+diff
+\family default
+ command for the patches to be useful.
+ If you modified more than one file a patch created f.e.
+ with
+\family sans
+\series bold
+
+\begin_inset Quotes sld
+\end_inset
+
+diff -Naur unmodified_directory modified_directory >my_changes.patch
+\begin_inset Quotes srd
+\end_inset
+
+
+\family default
+\series default
+ will be fine, otherwise
+\family sans
+\series bold
+
+\begin_inset Quotes sld
+\end_inset
+
+diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
+\begin_inset Quotes srd
+\end_inset
+
+
+\series default
+
+\family default
+will do.
+\layout Section
+
Getting Help
\layout Standard
\end_inset
-, lists and forums are archived and searchable so if you are lucky someone
- already had a similar problem.
+, lists
+\begin_inset LatexCommand \index{Mailing list(s)}
+
+\end_inset
+
+ and forums are archived and searchable so if you are lucky someone already
+ had a similar problem.
+ While mails to the lists themselves are delivered promptly their web front
+ end on sourceforge sometimes shows a severe time lag (up to several weeks),
+ if you're seriously using SDCC please consider subscribing to the lists.
\layout Section
ChangeLog
Historically there often were long delays between official releases and
the sourceforge download area tends to get not updated at all.
- Current excuses might refer to problems with live range analysis, but if
- this is fixed, the next problem rising is that another excuse will have
- to be found.
+ Excuses in the past might have referred to problems with live range analysis,
+ but as this was fixed a while ago, the current problem is that another
+ excuse has to be found.
Kidding aside, we have to get better there! On the other hand there are
daily snapshots available at
\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
\end_inset
-, and you can always built the very last version (hopefully with many bugs
+, and you can always build the very last version (hopefully with many bugs
fixed, and features added) from the source code available at
\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
in this directory (or f.e.
\family sans
+\series bold
+
+\begin_inset Quotes sld
+\end_inset
+
make test-mcs51
+\begin_inset Quotes srd
+\end_inset
+
+
\family default
+\series default
if you don't want to run the complete tests).
The test code might also be interesting if you want to look for examples
\begin_inset LatexCommand \index{Examples}
\SpecialChar ~
global = 2;
\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
}
\layout Subsection
\end_inset
+\begin_inset LatexCommand \label{sub:Loop-Optimizations}
+
+\end_inset
+
+
\layout Standard
-Two types of loop optimizations are done by SDCC loop invariant lifting
- and strength reduction of loop induction variables.
+Two types of loop optimizations are done by SDCC
+\emph on
+loop invariant
+\emph default
+ lifting and
+\emph on
+ strength reduction
+\emph default
+ of loop induction variables.
In addition to the strength reduction the optimizer marks the induction
variables and the register allocator tries to keep the induction variables
in registers for the duration of the loop.
\end_inset
-noinduction option) or for a given function only using #pragma\SpecialChar ~
-NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
\end_inset
\layout Standard
-SDCC changes switch statements to jump tables
+SDCC can optimize switch statements to jump tables
\begin_inset LatexCommand \index{jump tables}
\end_inset
- when the following conditions are true.
+.
+ 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 ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
-\layout 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
+
+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
-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 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 103: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 10:\SpecialChar ~
-...
+case 104: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 11:\SpecialChar ~
-...
+case 105: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 12:\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
-The pragma NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+\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}
\end_inset
\emph default
).
E.g.
- some variants of the 8051 MCU allow only
+ some variants of the 8051 MCU
+\begin_inset LatexCommand \index{MCS51 variants}
+
+\end_inset
+
+ allow only
\family typewriter
ajmp
\family default
\newline
}
\end_deeper
-\layout Itemize
-
-functions declared as pointers
-\begin_inset LatexCommand \index{Pointer (to function)}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{function pointers}
-
-\end_inset
-
- must be dereferenced during the call.
-\begin_deeper
-\layout Verse
-
-
-\family typewriter
-int (*foo)();
-\newline
-...
-
-\newline
-/* has to be called like this */
-\newline
-(*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
-\end_deeper
\layout Section
Cyclomatic Complexity
for which functions you might look at for further optimization.
\layout Section
-Notes on supported Processors
-\layout Subsection
-
-MCS51 variants
-\begin_inset LatexCommand \label{sub:MCS51-variants}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{MCS51 variants}
-
-\end_inset
-
-
-\layout Standard
-
-MCS51 processors are available from many vendors and come in many different
- flavours.
- While they might differ considerably in respect to Special Function Registers
- the core MCS51 is usually not modified or is kept compatible.
-
-\layout Subsubsection*
-
-pdata access by SFR
-\layout Standard
-
-With the upcome of devices with internal xdata and flash memory devices
- using port P2
-\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
-
-\end_inset
-
- as dedicated I/O port is becoming more popular.
- Switching the high byte for pdata
-\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
-
-\end_inset
-
- access which was formerly done by port P2 is then achieved by a Special
- Function Register
-\begin_inset LatexCommand \index{sfr}
-
-\end_inset
-
-.
- In well-established MCS51 tradition the address of this
-\emph on
-sfr
-\emph default
- is where the chip designers decided to put it.
- Needless to say that they didn't agree on a common name either.
- As pdata addressing is used in the startup code for the initialization
- of xdata variables a separate startup code should be used as described
- in section
-\begin_inset LatexCommand \ref{sub:Startup-Code}
-
-\end_inset
-
-.
-\layout Subsubsection*
-
-Other Features available by SFR
-\layout Standard
-
-Some MCS51 variants offer features like Double DPTR
-\begin_inset LatexCommand \index{DPTR}
-
-\end_inset
-
-, multiple DPTR, decrementing DPTR, 16x16 Multiply.
- These are currently not used for the MCS51 port.
- If you absolutely need them you can fall back to inline assembly or submit
- a patch to SDCC.
-\layout Subsection
-
-The Z80 and gbz80 port
-\layout Standard
-
-SDCC can target both the Zilog
-\begin_inset LatexCommand \index{Z80}
-
-\end_inset
-
- and the Nintendo Gameboy's Z80-like gbz80
-\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
-
-\end_inset
-
-.
- The Z80 port is passed through the same
-\emph on
-regressions tests
-\begin_inset LatexCommand \index{Regression test}
-
-\end_inset
-
-
-\emph default
- as the MCS51 and DS390 ports, so floating point support, support for long
- variables and bitfield support is fine.
- See mailing lists and forums about interrupt routines.
-\layout Standard
-
-As always, the code is the authoritative reference - see z80/ralloc.c and
- z80/gen.c.
- The stack
-\begin_inset LatexCommand \index{stack}
-
-\end_inset
-
- frame is similar to that generated by the IAR Z80 compiler.
- IX is used as the base pointer, HL is used as a temporary register, and
- BC and DE are available for holding variables.
- IY is currently unused.
- Return values
-\begin_inset LatexCommand \index{return value}
-
-\end_inset
-
- are stored in HL.
- One bad side effect of using IX as the base pointer is that a functions
- stack frame is limited to 127 bytes - this will be fixed in a later version.
-\layout Subsection
-
-The HC08 port
-\layout Standard
-
-The port to the Motorola HC08
-\begin_inset LatexCommand \index{HC08}
-
-\end_inset
-
- family has been added in October 2003, thank you Erik!
-\layout Subsection
-
-The PIC16 port
-\layout Standard
-
-You'll find some additional notes about this port in the file src/pic16/NOTES.
-\layout Section
-
Retargetting for other Processors
\layout Standard
\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