\lyxformat 221
\textclass book
\begin_preamble
+
+
\usepackage[
pdftitle={SDCC Compiler User Guide},
pdfauthor={SDCC development team},
embedded, GPL, HC08, manual, mcs51, PIC, Z80},
colorlinks=true,
linkcolor=blue] {hyperref}
+%
+\sloppy
+\tolerance=500
+\emergencystretch=30pt
+%
\date{}
\end_preamble
\language english
\layout Comment
Architecture specific stuff (like memory models, code examples) should maybe
- go
+ later go
\layout Comment
into seperate sections/chapters/appendices (it is hard to document PIC or
Z80 in
\layout Comment
-a 8051 centered document)
+a 8051 centered document) - for now simply add.
\layout Title
SDCC Compiler User Guide
\size normal
-2.3.6
+SDCC 2.4.7
\size footnotesize
\newline
\series bold
SDCC
\series default
- is a Freeware, retargettable, optimizing ANSI-C compiler by
+ (
+\emph on
+S
+\emph default
+mall
+\emph on
+D
+\emph default
+evice
+\emph on
+C
+\emph default
+
+\emph on
+C
+\emph default
+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
\series medium
Download the source package
\series default
- either from the SDCC CVS repository or from the
-\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
-
-\end_inset
-
-
+ either from the SDCC CVS repository or from the nightly snapshots
\series medium
, it will be named something like sdcc
\series default
\series default
ar.
\series medium
-gz.
+gz
+\series default
+
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
+
+\end_inset
+
+.
\layout Enumerate
\series default
This copies the binary executables, the include files, the libraries and
the documentation to the install directories.
+ Proceed with section
+\begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
+
+\end_inset
+
+.
\layout Subsection
Building SDCC on OSX 2.x
in binary mode.
And use an editor which can handle LF-only line endings.
Make sure not to commit files with windows line endings.
- The tabulator spacing used in the project is 8.
+ The tabulator spacing
+\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.
- 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}
+ 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.
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.
\layout Section
Testing the SDCC Compiler
+\begin_inset LatexCommand \label{sec:Testing-the-SDCC}
+
+\end_inset
+
+
\layout Standard
The first thing you should do after installing your SDCC compiler is to
\begin_inset Quotes srd
\end_inset
-
+.
\newline
\newline
\layout Subsection
-SDCC does not build correctly.
+If SDCC does not build correctly
\layout Standard
A thing to try is starting from scratch by unpacking the .tgz source package
\begin_inset Quotes srd
\end_inset
- does.
+ does
\layout Standard
This runs the GNU make tool, which automatically compiles all the source
the assembler and linkage editor.
\layout Subsection
-sdcpp
-\begin_inset LatexCommand \index{sdcpp}
+sdcpp - The C-Preprocessor
+\layout Standard
-\end_inset
+The preprocessor
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
- - The C-Preprocessor
-\layout Standard
+\end_inset
-The preprocessor is a modified version of the GNU preprocessor.
+ is a modified version of the GNU preprocessor.
The C preprocessor is used to pull in #include sources, process #ifdef
statements, #defines and so on.
\layout Subsection
-asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 - The Assemblers
- and Linkage Editors
+as
+\emph on
+xxxx
+\emph default
+, aslink, link-
+\emph on
+xxx
+\emph default
+ - The Assemblers and Linkage Editors
\layout Standard
This is retargettable assembler & linkage editor, it was developed by Alan
\layout Subsection
s51 - The Simulator
+\layout Standard
+
+S51
\begin_inset LatexCommand \index{s51}
\end_inset
-
-\layout Standard
-
-S51 is a freeware, opensource simulator developed by Daniel Drotos (
+ is a freeware, opensource simulator developed by Daniel Drotos (
\begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
\end_inset
XA51 family.
\layout Subsection
-sdcdb
-\begin_inset LatexCommand \index{sdcdb}
+sdcdb - Source Level Debugger
+\layout Standard
+
+Sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
\end_inset
- - Source Level Debugger
-\layout Standard
+ is the companion source level debugger.
+ More about sdcdb in section
+\begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
+
+\end_inset
-Sdcdb is the companion source level debugger.
+.
The current version of the debugger uses Daniel's Simulator S51
\begin_inset LatexCommand \index{s51}
\end_inset
, but can be easily changed to use other simulators.
+
\layout Chapter
Using SDCC
\family default
\series default
This will compile, assemble and link your source file.
- Output files are as follows
+ Output files are as follows:
\layout Itemize
sourcefile.asm
sourcefile.rel
\begin_inset LatexCommand \index{<file>.rel}
+\end_inset
+
+ or sourcefile.o
+\begin_inset LatexCommand \index{<file>.o}
+
\end_inset
- Object file
\family default
\shape default
-\begin_inset LatexCommand \index{objdump}
+\begin_inset LatexCommand \index{objdump (tool)}
\end_inset
\family default
\shape default
-\begin_inset LatexCommand \index{srecord}
+\begin_inset LatexCommand \index{srecord (tool)}
\end_inset
-)
+).
+ 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
/
\end_inset
--debug) containing debug information
+-debug) containing debug information.
+ The format is documented in cdbfileformat.pdf.
\layout Itemize
sourcefile.
\end_inset
- An optional AOMF51
-\begin_inset LatexCommand \index{AOMF51}
+ An optional AOMF or AOMF51
+\begin_inset LatexCommand \index{AOMF, AOMF51}
\end_inset
- file containing debug information (with -
+ file containing debug information (generated with option -
\begin_inset ERT
status Collapsed
\end_inset
-debug).
- This format is commonly used by third party tools (debuggers
+ The (Intel)
+\emph on
+ a
+\emph default
+bsolute
+\emph on
+o
+\emph default
+bject
+\emph on
+m
+\emph default
+odule
+\emph on
+f
+\emph default
+ormat is commonly used by third party tools (debuggers
\begin_inset LatexCommand \index{Debugger}
\end_inset
\end_inset
- - Dump file to debug the compiler it self (with -
+ - Dump file to debug the compiler it self (generated with option -
\begin_inset ERT
status Collapsed
\family default
\series default
-\begin_inset LatexCommand \index{.rel}
+\begin_inset LatexCommand \index{<file>.rel}
\end_inset
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
The most efficient way to use libraries is to keep separate modules in separate
source files.
The lib file now should name all the modules.rel
-\begin_inset LatexCommand \index{rel}
+\begin_inset LatexCommand \index{<file>.rel}
\end_inset
libsdcc.lib
\emph default
in the directory <installdir>/share/lib/small.
-\layout Section
+\layout Subsection
-Command Line Options
-\begin_inset LatexCommand \index{Command Line Options}
+Using sdcclib to Create and Manage Libraries
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\layout Subsection
+\layout Standard
-Processor Selection Options
-\begin_inset LatexCommand \index{Options processor selection}
+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
-\end_inset
+\layout Standard
-\begin_inset LatexCommand \index{Processor selection options}
+\family sans
+\series bold
+sdcclib -?
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+\newline
-\series bold
--mmcs51
-\begin_inset LatexCommand \index{-mmcs51}
+\family default
+\series default
+To create a new library file, start by compiling all the required modules.
+ For example:
+\newline
-\end_inset
+\layout Standard
-\series default
- Generate code for the Intel MCS51
-\begin_inset LatexCommand \index{MCS51}
+\family sans
+\series bold
+sdcc -c _divsint.c
+\layout Standard
-\end_inset
- family of processors.
- This is the default processor target.
-\layout List
-\labelwidthstring 00.00.0000
+\family sans
+\series bold
+sdcc -c _divuint.c
+\layout Standard
+\family sans
\series bold
--mds390
-\begin_inset LatexCommand \index{-mds390}
+sdcc -c _modsint.c
+\layout Standard
-\end_inset
+\family sans
+\series bold
+sdcc -c _moduint.c
+\layout Standard
-\series default
- Generate code for the Dallas DS80C390
-\begin_inset LatexCommand \index{DS80C390}
-\end_inset
+\family sans
+\series bold
+sdcc -c _mulint.c
+\newline
- processor.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+
+This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
+ and _mulint.rel.
+ The next step is to add the .rel files to the library file:
+\newline
+
+\layout Standard
+\family sans
\series bold
--mds400
-\begin_inset LatexCommand \index{-mds400}
+sdcclib libint.lib _divsint.rel
+\family default
+
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\series default
- Generate code for the Dallas DS80C400
-\begin_inset LatexCommand \index{DS80C400}
+\layout Standard
-\end_inset
- processor.
-\layout List
-\labelwidthstring 00.00.0000
+\family sans
+\series bold
+sdcclib libint.lib _divuint.rel
+\layout Standard
+\family sans
\series bold
--mhc08
-\begin_inset LatexCommand \index{-mhc08}
+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 Motorola HC08
-\begin_inset LatexCommand \index{HC08}
-\end_inset
+\newline
- family of processors (added Oct 2003).
-\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
--mz80
-\begin_inset LatexCommand \index{-mz80}
+sdcclib -s libint.lib
+\family default
+
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
+\newline
+
+\family typewriter
\series default
- Generate code for the Zilog Z80
-\begin_inset LatexCommand \index{Z80}
+_divsint.rel:
+\layout Standard
-\end_inset
- family of processors.
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__divsint_a_1_1
+\layout Standard
+
+
+\family typewriter
+__divsint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__divsint
+\newline
+_divuint.rel:
+\layout Standard
+
+
+\family typewriter
+__divuint_a_1_1
+\layout Standard
+
+
+\family typewriter
+__divuint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__divuint_reste_1_1
+\layout Standard
+
+
+\family typewriter
+__divuint_count_1_1
+\layout Standard
+
+
+\family typewriter
+__divuint
+\newline
+_modsint.rel:
+\layout Standard
+
+
+\family typewriter
+__modsint_a_1_1
+\layout Standard
+
+
+\family typewriter
+__modsint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__modsint
+\newline
+_moduint.rel:
+\layout Standard
+
+
+\family typewriter
+__moduint_a_1_1
+\layout Standard
+
+
+\family typewriter
+__moduint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__moduint_count_1_1
+\layout Standard
+
+
+\family typewriter
+__moduint
+\newline
+_mulint.rel:
+\layout Standard
+
+
+\family typewriter
+__mulint_PARM_2
+\layout Standard
+
+
+\family typewriter
+__mulint
+\family default
+\series bold
+
+\newline
+
+\layout Standard
+
+If the source files are compiled using -
+\begin_inset ERT
+status Open
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
+
+\end_inset
+
+, the corresponding debug information file .adb will be include in the library
+ file as well.
+ The library files created with sdcclib are plain text files, so they can
+ be viewed with a text editor.
+ It is not recomended to modify a library file created with sdcclib using
+ a text editor, as there are file indexes numbers located accross the file
+ used by the linker to quickly locate the required module to link.
+ Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
+ it can be safely deleted, since all the information required for linking
+ is embedded in the library file itself.
+ Library files created using sdcclib are used as described in the preceding
+ sections.
+\layout Section
+
+Command Line Options
+\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
\end_inset
- processor.
+ processor (Not actively maintained).
\layout List
\labelwidthstring 00.00.0000
AVR users should probably have a look at avr-gcc
\begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
+\end_inset
+
+ or winavr
+\begin_inset LatexCommand \url{http://winavr.sourceforge.net}
+
\end_inset
.
\end_inset
--bit processors (p16f84 and variants).
+-bit processors (p16f84 and variants.
+ In development, not complete).
\layout Comment
p16f627 p16f628 p16f84 p16f873 p16f877?
\end_inset
--bit processors (p18f452 and variants).
+-bit processors (p18f452 and variants.
+ In development, not complete).
\layout List
\labelwidthstring 00.00.0000
\end_inset
- processor (In development, not complete).
+ processor (Not maintained, not complete).
\layout List
\labelwidthstring 00.00.0000
\end_inset
- processor (In development, not complete).
+ processor (Not maintained, not complete).
\layout Subsection
Preprocessor Options
\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
\SpecialChar ~
<Value> The start location of the external ram
-\begin_inset LatexCommand \index{xdata}
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
\end_inset
\SpecialChar ~
<Value> The start location of the internal ram data
-\begin_inset LatexCommand \index{data}
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
\end_inset
\SpecialChar ~
<Value> The start location of the indirectly addressable internal ram
-\begin_inset LatexCommand \index{idata}
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
\end_inset
\end_inset
- (This is the default option).
+ This is the default option.
+ The format itself is documented in the documentation of srecord
+\begin_inset LatexCommand \index{srecord (tool)}
+
+\end_inset
+
+.
\layout List
\labelwidthstring 00.00.0000
\end_inset
.
+ The format itself is documented in the documentation of srecord.
\layout List
\labelwidthstring 00.00.0000
...
Pass the linkOption to the linker.
+ See file sdcc/as/doc/asxhtm.html for more on linker options.
\layout Subsection
MCS51 Options
\size default
\emph default
-Generate code for Small Model programs see section Memory Models for more
+Generate code for Small Model programs, see section Memory Models for more
details.
This is the default model.
\layout List
\series default
- Generate code for Large model programs see section Memory Models for more
+ Generate code for Large model programs, see section Memory Models for more
details.
If this option is used all source files in the project have to be compiled
with this option.
Causes the linker to check if the code memory usage is within limits of
the given value.
-\layout Subsection
-
-DS390 Options
-\begin_inset LatexCommand \index{Options DS390}
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-
+\begin_inset ERT
+status Collapsed
-\begin_inset LatexCommand \index{DS390 options}
+\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
/
\end_inset
--model-flat24
+-pack-iram
\series default
+\SpecialChar ~
-\begin_inset LatexCommand \index{-\/-model-flat24}
+\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
-\size large
-\emph on
-
-\size default
-\emph default
+
+\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
+\begin_inset LatexCommand \index{Options DS390}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{DS390 options}
+
+\end_inset
+
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-flat24
+\series default
+
+\begin_inset LatexCommand \index{-\/-model-flat24}
+
+\end_inset
+
+
+\size large
+\emph on
+
+\size default
+\emph default
Generate 24-bit flat mode code.
This is the one and only that the ds390 code generator supports right now
and is default when using
\series default
- disable interrupts during ESP:SP updates
+ disable interrupts during ESP:SP updates.
\layout List
\labelwidthstring 00.00.0000
\series default
- insert call to function __stack_probe at each function prologue
+ insert call to function __stack_probe at each function prologue.
\layout List
\labelwidthstring 00.00.0000
\series default
- <nnnn> LibraryID used in -mTININative
+ <nnnn> LibraryID used in -mTININative.
+
\layout List
\labelwidthstring 00.00.0000
\series default
- generate code for DS390 Arithmetic Accelerator
+ generate code for DS390 Arithmetic Accelerator.
+
\layout Subsection
Z80 Options
temporaries.
A warning message will be generated when this happens and the compiler
will indicate the number of extra bytes it allocated.
- It recommended that this option NOT be used, #pragma\SpecialChar ~
-NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+ It is recommended that this option NOT be used, #pragma\SpecialChar ~
+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.It
- recommended that this option NOT be used, #pragma\SpecialChar ~
-NOINVARIANT
-\begin_inset LatexCommand \index{\#pragma NOINVARIANT}
+ For more details of loop optimizations performed see Loop Invariants in
+ section
+\begin_inset LatexCommand \ref{sub:Loop-Optimizations}
+
+\end_inset
+
+.
+ It is recommended that this option NOT be used, #pragma\SpecialChar ~
+noinvariant
+\begin_inset LatexCommand \index{\#pragma noinvariant}
\end_inset
\series default
Will not do loop induction optimizations, see section strength reduction
- for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
-NOINDUCT
-ION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+ for more details.
+ It is recommended that this option is NOT used, #pragma\SpecialChar ~
+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
Will not memcpy initialized data from code space into xdata space.
This saves a few bytes in code space if you don't have initialized data.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-nooverlay
+\begin_inset LatexCommand \index{-\/-nooverlay}
+
+\end_inset
+
+
+\series default
+ The compiler will not overlay parameters and local variables of any function,
+ see section Parameters and local variables for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-peep
+\begin_inset LatexCommand \index{-\/-no-peep}
+
+\end_inset
+
+
+\series default
+ Disable peep-hole optimization.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-peep-file
+\series default
+
+\begin_inset LatexCommand \index{-\/-peep-file}
+
+\end_inset
+
+\SpecialChar ~
+<filename> This option can be used to use additional rules to be used by
+ the peep hole optimizer.
+ See section
+\begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
+
+\end_inset
+
+\SpecialChar ~
+Peep Hole optimizations for details on how to write these rules.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-peep-asm
+\begin_inset LatexCommand \index{-\/-peep-asm}
+
+\end_inset
+
+
+\series default
+ 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}
+
+\end_inset
+
+ 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
\bar default
-When this option is used the compiler will generate debug information, that
- can be used with the SDCDB.
- The debug information is collected in a file with .cdb extension.
+When this option is used the compiler will generate debug information.
+ The debug information collected in a file with .cdb extension can be used
+ with the SDCDB.
For more information see documentation for SDCDB.
+ Another file with no extension contains debug information in AOMF or AOMF51
+\begin_inset LatexCommand \index{AOMF, AOMF51}
+
+\end_inset
+
+ format which is commonly used by third party tools.
\layout List
\labelwidthstring 00.00.0000
\end_inset
-\bar under
-
\series default
-\bar default
Floating point library is compiled as reentrant
\begin_inset LatexCommand \index{reentrant}
/
\end_inset
--nooverlay
-\begin_inset LatexCommand \index{-\/-nooverlay}
+-main-return
+\begin_inset LatexCommand \index{-\/-main-return}
\end_inset
\series default
- The compiler will not overlay parameters and local variables of any function,
- see section Parameters and local variables for more details.
+ 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 will return to the function calling main.
+ The default setting is to lock up i.e.
+ generate a '
+\family typewriter
+sjmp .
+\family default
+'.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--main-return
-\begin_inset LatexCommand \index{-\/-main-return}
+-nostdinc
+\begin_inset LatexCommand \index{-\/-nostdinc}
\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'
-\begin_inset LatexCommand \index{main return}
-
-\end_inset
-
- function.
- The default setting is to lock up i.e.
- generate a '
-\family typewriter
-ljmp .
-\family default
-'.
+ This will prevent the compiler from passing on the default include path
+ to the preprocessor.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--peep-file
-\series default
-
-\begin_inset LatexCommand \index{-\/-peep-file}
+-nostdlib
+\begin_inset LatexCommand \index{-\/-nostdlib}
\end_inset
-\SpecialChar ~
-<filename> This option can be used to use additional rules to be used by
- the peep hole optimizer.
- See section
-\begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
+
+\series default
+ This will prevent the compiler from passing on the default library
+\begin_inset LatexCommand \index{Libraries}
\end_inset
-\SpecialChar ~
-Peep Hole optimizations for details on how to write these rules.
+ path to the linker.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--no-peep
-\begin_inset LatexCommand \index{-\/-no-peep}
+-verbose
+\begin_inset LatexCommand \index{-\/-verbose}
\end_inset
\series default
- Disable peep-hole optimization.
+ Shows the various actions the compiler is performing.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--peep-asm
-\begin_inset LatexCommand \index{-\/-peep-asm}
+-V
+\begin_inset LatexCommand \index{-V}
\end_inset
\series default
- 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}
-
-\end_inset
-
- rules defined in the source file tree '<target>/peeph.def' before using
- this option.
+ Shows the actual commands the compiler is executing.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--nostdincl
-\begin_inset LatexCommand \index{-\/-nostdincl}
+-no-c-code-in-asm
+\begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
\end_inset
\series default
- This will prevent the compiler from passing on the default include path
- to the preprocessor.
+ Hides your ugly and inefficient c-code from the asm file, so you can always
+ blame the compiler :)
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--nostdlib
-\begin_inset LatexCommand \index{-\/-nostdlib}
+-no-peep-comments
+\begin_inset LatexCommand \index{-\/-no-peep-comments}
\end_inset
\series default
- This will prevent the compiler from passing on the default library
-\begin_inset LatexCommand \index{Libraries}
-
-\end_inset
-
- path to the linker.
+ Will not include peep-hole comments in the generated files.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--verbose
-\begin_inset LatexCommand \index{-\/-verbose}
-
-\end_inset
-
-
-\series default
- Shows the various actions the compiler is performing.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--V
-\begin_inset LatexCommand \index{-V}
+-i-code-in-asm
+\begin_inset LatexCommand \index{-\/-i-code-in-asm}
\end_inset
\series default
- Shows the actual commands the compiler is executing.
+ Include i-codes in the asm file.
+ Sounds like noise but is most helpful for debugging the compiler itself.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--no-c-code-in-asm
-\begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
+-less-pedantic
+\begin_inset LatexCommand \index{-\/-less-pedantic}
\end_inset
\series default
- Hides your ugly and inefficient c-code from the asm file, so you can always
- blame the compiler :).
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+ Disable some of the more pedantic warnings
+\begin_inset LatexCommand \index{Warnings}
-\backslash
-/
\end_inset
--i-code-in-asm
-\begin_inset LatexCommand \index{-\/-i-code-in-asm}
+ (jwk burps: please be more specific here, please!).
+ If you want rather more than less warnings you should consider using a
+ separate tool dedicated to syntax checking like splint
+\begin_inset LatexCommand \url{www.splint.org}
\end_inset
-
-\series default
- Include i-codes in the asm file.
- Sounds like noise but is most helpful for debugging the compiler itself.
+.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--less-pedantic
-\begin_inset LatexCommand \index{-\/-less-pedantic}
+-disable-warning\SpecialChar ~
+<nnnn>
+\begin_inset LatexCommand \index{-\/-disable-warning}
\end_inset
\series default
- Disable some of the more pedantic warnings
-\begin_inset LatexCommand \index{Warnings}
-
-\end_inset
-
- (jwk burps: please be more specific here, please!).
- If you want rather more than less warnings you should consider using a
- separate tool dedicated to syntax checking like
-\begin_inset LatexCommand \url{www.splint.org}
-
-\end_inset
-
-.
+ Disable specific warning with number <nnnn>.
\layout List
\labelwidthstring 00.00.0000
\end_inset
...
- Pass the asmOption to the assembler.
+ Pass the asmOption to the assembler
+\begin_inset LatexCommand \index{Options assembler}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Assembler options}
+
+\end_inset
+
+.
+ See file sdcc/as/doc/asxhtm.html for assembler options.
\layout Subsection
Intermediate Dump Options
) generated by the compiler in human readable form at various stages of
the compilation process.
+ More on iCodes see chapter
+\begin_inset LatexCommand \ref{sub:The-anatomy-of}
+
+\end_inset
+
+\begin_inset Quotes srd
+\end_inset
+
+The anatomy of the compiler
+\begin_inset Quotes srd
+\end_inset
+
+.
\layout List
\labelwidthstring 00.00.0000
\end_inset
.
- Aditionaly, if you happen to have visual studio installed in your windows
+ Additionally, if you happen to have visual studio installed in your windows
machine, you can use it to compile your sources using a custom build and
the SDCC -
\emph on
\layout Subsubsection
data
-\begin_inset LatexCommand \index{data}
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
+
+\end_inset
+
+ / near
+\begin_inset LatexCommand \index{near (storage class)}
\end_inset
\series bold
default
\series default
- storage class for the Small Memory model.
+ storage class for the Small Memory model (
+\emph on
+data
+\emph default
+ and
+\emph on
+near
+\emph default
+ can be used synonymously).
Variables declared with this storage class will be allocated in the directly
addressable portion of the internal RAM of a 8051, e.g.:
\layout Verse
\layout Subsubsection
xdata
-\begin_inset LatexCommand \index{xdata}
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ / far
+\begin_inset LatexCommand \index{far (storage class)}
\end_inset
\layout Subsubsection
idata
-\begin_inset LatexCommand \index{idata}
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
\end_inset
\layout Subsubsection
pdata
-\begin_inset LatexCommand \index{pdata}
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
\end_inset
\layout Standard
-Paged xdata access is currently not as straightforward as using the other
- addressing modes of a 8051.
+Paged xdata access is just as straightforward as using the other addressing
+ modes of a 8051.
+ It is typically located at the start of xdata and has a maximum size of
+ 256 bytes.
The following example writes 0x01 to the address pointed to.
Please note, pdata access physically accesses xdata memory.
- The high byte of the address is determined by port P2 (or in case of some
- 8051 variants by a separate Special Function Register, see section
+ The high byte of the address is determined by port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
+
+\end_inset
+
+(or in case of some 8051 variants by a separate Special Function Register,
+ 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
code char test_array[] = {'c','h','e','a','p'};
\layout Standard
-Read access to this array using an 8-bit index generates the assembly code:
+Read access to this array using an 8-bit unsigned index generates the assembly
+ code:
\layout Verse
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
\layout Subsubsection
Pointers
-\begin_inset LatexCommand \index{Pointers}
+\begin_inset LatexCommand \index{Pointer}
\end_inset
routines.
Explicitly specifying the pointer type will generate the most efficient
code.
-\layout Subsection
+\layout Subsubsection
-Z80/Z180 Storage Class
-\begin_inset LatexCommand \index{Storage class}
+Notes on MCS51 memory
+\begin_inset LatexCommand \index{MCS51 memory}
\end_inset
- Language Extensions
-\layout Subsubsection
+ layout
+\layout Standard
-sfr
-\begin_inset LatexCommand \index{sfr}
+The 8051 family of microcontrollers have a minimum of 128 bytes of internal
+ RAM memory which is structured as follows:
+\newline
+
+\newline
+- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
+
+\newline
+- Bytes 20-2F - 16 bytes to hold 128 bit
+\begin_inset LatexCommand \index{bit}
\end_inset
- (in/out to 8-bit addresses)
+ variables and,
+\newline
+- Bytes 30-7F - 80 bytes for general purpose use.
+\newline
+
\layout Standard
-The Z80
-\begin_inset LatexCommand \index{Z80}
+Additionally some members of the MCS51 family may have up to 128 bytes of
+ additional, indirectly addressable, internal RAM memory (
+\emph on
+idata
+\emph default
+
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
\end_inset
- family has separate address spaces for memory and
-\emph on
-i
-\emph default
-nput/
+).
+ Furthermore, some chips may have some built in external memory (
\emph on
-o
+xdata
\emph default
-utput memory.
- I/O memory
-\begin_inset LatexCommand \index{I/O memory (Z80/Z180)}
+
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
\end_inset
- is accessed with special instructions, e.g.:
-\layout Verse
+) which should not be confused with the internal, directly addressable RAM
+ memory (
+\emph on
+data
+\emph default
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
-\family typewriter
-sfr at 0x78 IoPort;\SpecialChar ~
-\SpecialChar ~
-/* define a var in I/O space at 78h called IoPort */
-
-\layout Standard
+\end_inset
-Writing 0x01 to this variable generates the assembly code:
-\layout Verse
+).
+ Sometimes this built in
+\emph on
+xdata
+\emph default
+ memory has to be activated before using it (you can probably find this
+ information on the datasheet of the microcontroller your are using, see
+ also section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+\end_inset
-\family typewriter
-3E 01\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
-ld a,#0x01
-\newline
-D3 78\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-out (_IoPort),a
-\layout Subsubsection
+Startup-Code).
+\layout Standard
-banked sfr
-\begin_inset LatexCommand \index{sfr}
+Normally SDCC will only use the first bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
\end_inset
- (in/out to 16-bit addresses)
+ of registers (register bank 0), but it is possible to specify that other
+ banks of registers should be used in interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ routines.
+ By default, the compiler will place the stack after the last byte of allocated
+ memory for variables.
+ For example, if the first 2 banks of registers are used, and only four
+ bytes are used for
+\emph on
+data
+\emph default
+ variables, it will position the base of the internal stack at address 20
+ (0x14).
+ This implies that as the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ 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 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 from address 0x10 to 0x20 and continue
+ at address 0x22.
+ You can also use -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-data-loc
+\begin_inset LatexCommand \index{-\/-data-loc<Value>}
+
+\end_inset
+
+ to specify the start address of the
+\emph on
+data
+\emph default
+ and -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-iram-size to specify the size of the total internal RAM (
+\emph on
+data
+\emph default
++
+\emph on
+idata
+\emph default
+).
+
+\layout Standard
+
+By default the 8051 linker will place the stack after the last byte of (i)data
+ variables.
+ Option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-loc
+\begin_inset LatexCommand \index{-\/-stack-loc<Value>}
+
+\end_inset
+
+ allows you to specify the start of the stack, i.e.
+ you could start it after any data in the general purpose area.
+ If your microcontroller has additional indirectly addressable internal
+ RAM (
+\emph on
+idata
+\emph default
+) you can place the stack on it.
+ You may also need to use -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xdata-loc
+\begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
+
+\end_inset
+
+ to set the start address of the external RAM (
+\emph on
+xdata
+\emph default
+) and -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xram-size
+\begin_inset LatexCommand \index{-\/-data-loc}
+
+\end_inset
+
+ to specify its size.
+ Same goes for the code memory, using -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-code-loc
+\begin_inset LatexCommand \index{-\/-data-loc}
+
+\end_inset
+
+ and -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-code-size
+\begin_inset LatexCommand \index{-\/-data-loc}
+
+\end_inset
+
+.
+ If in doubt, don't specify any options and see if the resulting memory
+ layout is appropriate, then you can adjust it.
+\layout Standard
+
+The linker generates two files with memory allocation information.
+ The first, with extension .map
+\begin_inset LatexCommand \index{<file>.map}
+
+\end_inset
+
+ shows all the variables and segments.
+ The second with extension .mem
+\begin_inset LatexCommand \index{<file>.mem}
+
+\end_inset
+
+ shows the final memory layout.
+ The linker will complain either if memory segments overlap, there is not
+ enough memory, or there is not enough space for stack.
+ If you get any linking warnings and/or errors related to stack or segments
+ allocation, take a look at either the .map or .mem files to find out what
+ the problem is.
+ The .mem file may even suggest a solution to the problem.
+\layout Subsection
+
+Z80/Z180 Storage Class
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ Language Extensions
+\layout Subsubsection
+
+sfr
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+ (in/out to 8-bit addresses)
+\layout Standard
+
+The Z80
+\begin_inset LatexCommand \index{Z80}
+
+\end_inset
+
+ family has separate address spaces for memory and
+\emph on
+i
+\emph default
+nput/
+\emph on
+o
+\emph default
+utput memory.
+ I/O memory
+\begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
+
+\end_inset
+
+ is accessed with special instructions, e.g.:
+\layout Verse
+
+
+\family typewriter
+sfr at 0x78 IoPort;\SpecialChar ~
+\SpecialChar ~
+/* define a var in I/O space at 78h called IoPort */
+
+\layout Standard
+
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
+
+
+\family typewriter
+3E 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ld a,#0x01
+\newline
+D3 78\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out (_IoPort),a
+\layout Subsubsection
+
+banked sfr
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+ (in/out to 16-bit addresses)
\layout Standard
The keyword
\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 Section
+\layout Subsection
-Absolute Addressing
-\begin_inset LatexCommand \index{Absolute addressing}
+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
+\begin_inset LatexCommand \index{Absolute addressing}
\end_inset
\family typewriter
xdata
-\begin_inset LatexCommand \index{xdata}
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
\end_inset
0x7ffe unsigned int chksum;
\layout Standard
-In the above example the variable chksum will located at 0x7ffe and 0x7fff
+In the above example the variable chksum will be located at 0x7ffe and 0x7fff
of the external ram.
The compiler does
\emph on
\emph on
not
\emph default
- initialized.
+ initialized
+\begin_inset LatexCommand \index{Variable initialization}
+
+\end_inset
+
+.
\layout Standard
In case of memory mapped I/O devices the keyword
\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
\end_inset
xdata
-\begin_inset LatexCommand \index{xdata}
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
\end_inset
0x8000 unsigned char PORTA_8255;
\layout Standard
-Absolute address can be specified for variables in all storage classes,
+For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
+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.:
\layout Verse
\family typewriter
-extern volatile bit SDI;
+extern volatile bit MOSI;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master out, slave in */
\newline
-extern volatile bit SCLK;
+extern volatile bit MISO;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master in, slave out */
\newline
-extern volatile bit CPOL;
+extern volatile bit MCLK;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master clock */
\newline
\newline
-void DS1306_put(unsigned char value)
+/* Input and Output of a byte on a 3-wire serial bus.
\newline
-{
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+If needed adapt polarity of clock, polarity of data and bit order
+\newline
+\SpecialChar ~
+*/
+\newline
+unsigned char spi_io(unsigned char out_byte)
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char mask=0x80;
+unsigned char i=8;
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+do {
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-while(mask)
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+MOSI = out_byte & 0x80;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-{
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out_byte <<= 1;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDI=(value & mask)?1:0;
+MCLK = 1;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SCLK=!CPOL;
+/* _asm nop _endasm; */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* for slow peripherals */
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SCLK=CPOL;
+if(MISO)
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mask/=2;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out_byte += 1;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-}
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+MCLK = 0;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+} while(--i);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return out_byte;
\newline
}
\layout Standard
\family typewriter
-bit at 0x80 SDI;\SpecialChar ~
+bit at 0x80 MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 0, bit 0 */
\newline
-bit at 0x81 SCLK;\SpecialChar ~
+bit at 0x81 MISO;\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
/* I/O port 0, bit 1 */
\newline
-bit CPOL;\SpecialChar ~
-\SpecialChar ~
-\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
& Local Variables
-\begin_inset LatexCommand \index{Local variable}
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+
+\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
\end_inset
\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}
\emph on
does not
\emph default
- mean that the function is register bank independent.
+ mean that the function is register bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
+
+\end_inset
+
+ independent.
\newline
\newline
-Local variables can be assigned storage classes and absolute
+Local variables
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+ can be assigned storage classes and absolute
\begin_inset LatexCommand \index{Absolute addressing}
\end_inset
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-data at 0x31 unsigned char j;
+data at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x31 unsigned char j;
\newline
\SpecialChar ~
\SpecialChar ~
\end_inset
however are not allowed any storage class
-\begin_inset LatexCommand \index{storage class}
+\begin_inset LatexCommand \index{Storage class}
\end_inset
functions SDCC will try to reduce internal ram space usage by overlaying
parameters and local variables of a function (if possible).
- Parameters and local variables of a function will be allocated to an overlayabl
-e segment if the function has
+ Parameters and local variables
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+ of a function will be allocated to an overlayable segment if the function
+ has
\emph on
no other function calls and the function is non-reentrant and the memory
model
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 ISR.
+ 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 interrupt service routines to be coded in C, with some extended
- keywords.
+SDCC allows
+\emph on
+i
+\emph default
+nterrupt
+\emph on
+s
+\emph default
+ervice
+\emph on
+r
+\emph default
+outines to be coded in C, with some extended keywords.
\layout Verse
keyword is the interrupt number this routine will service.
When present, the compiler will insert a call to this routine in the interrupt
vector table for the interrupt number specified.
+ If you have multiple source files in your project, interrupt service routines
+ can be present in any of them, but a prototype of the isr MUST be present
+ or included in the file that contains the function
+\emph on
+main
+\emph default
+.
The
\emph on
using
\layout Standard
-If you have multiple source files in your project, interrupt service routines
- can be present in any of them, but a prototype of the isr MUST be present
- or included in the file that contains the function
+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
-main
+volatile
\emph default
-.
-\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 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
+
+ from within an interrupt routine might get lost if the interrupt occurs
+ at the wrong time.
+
+\begin_inset Quotes sld
+\end_inset
+
+
+\family typewriter
+counter\SpecialChar ~
++=\SpecialChar ~
+8;
+\family default
+
+\begin_inset Quotes srd
+\end_inset
+
+ is not atomic on the 8051 even if
+\family typewriter
+counter
+\family default
+ is located in data memory.
+ Bugs like these are hard to reproduce and can cause a lot of trouble.
+
+\layout Standard
+
+The return address and the registers used in the interrupt service routine
+ are saved on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ so there must be sufficient stack space.
+ If there isn't variables or registers (or even the return address itself)
+ will be corrupted.
+ This
+\emph on
+stack overflow
+\emph default
+
+\begin_inset LatexCommand \index{stack overflow}
+
+\end_inset
+
+ is most likely to happen if the interrupt occurs during the
+\begin_inset Quotes sld
+\end_inset
+
+deepest
+\begin_inset Quotes srd
+\end_inset
+
+ subroutine when the stack is already in use for f.e.
+ many return addresses.
+\layout Standard
+
+A special note here, int (16 bit) and long (32 bit) integer division
+\begin_inset LatexCommand \index{Division}
+
+\end_inset
+
+, multiplication
+\begin_inset LatexCommand \index{Multiplication}
+
+\end_inset
+
+ & modulus
+\begin_inset LatexCommand \index{Modulus}
+
+\end_inset
+
+ and floating-point
+\begin_inset LatexCommand \index{Floating point support}
+
+\end_inset
+
+ operations are implemented using external support routines developed in
+ ANSI-C.
+ If an interrupt service routine needs to do any of these operations then
+ the support routines (as mentioned in a following section) will have to
+ be recompiled using the
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-int-long-reent
+\emph default
+
+\begin_inset LatexCommand \index{-\/-int-long-reent}
+
+\end_inset
+
+ compiler option.
+\layout Standard
+
+Calling other functions from an interrupt service routine is not recommended,
+ avoid it if possible.
+ Note that when some function is called from an interrupt service routine
+ it should be preceded by a #pragma\SpecialChar ~
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+
+ if it is not reentrant.
+ Furthermore nonreentrant functions should not be called from the main program
+ while the interrupt service routine might be active.
+
+\newline
+
+\newline
+Also see section
+\begin_inset LatexCommand \ref{sub:Overlaying}
+
+\end_inset
+
+\SpecialChar ~
+about Overlaying and section
+\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
+
+\end_inset
+
+\SpecialChar ~
+about Functions using private register banks.
+\layout Subsection
+
+MCS51/DS390 Interrupt Service Routines
+\layout Standard
+
+Interrupt numbers and the corresponding address & descriptions for the Standard
+ 8051/8052 are listed below.
+ SDCC will automatically adjust the interrupt vector table to the maximum
+ 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
If the interrupt service routine is defined without
\emph on
using
-\begin_inset LatexCommand \index{using}
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
\end_inset
\emph default
- a register bank or with register bank 0 (using 0), the compiler will save
- the registers used by itself on the stack upon entry and restore them at
- exit, however if such an interrupt service routine calls another function
- then the entire register bank will be saved on the stack.
+ a register bank or with register bank 0 (
+\emph on
+using
+\emph default
+ 0), the compiler will save the registers used by itself on the stack upon
+ entry and restore them at exit, however if such an interrupt service routine
+ calls another function then the entire register bank will be saved on the
+ stack.
This scheme may be advantageous for small interrupt service routines which
have low register usage.
\layout Standard
If the interrupt service routine is defined to be using a specific register
bank then only
\emph on
-a, b & dptr
+a, b, dptr
\emph default
- are save 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.
+ & 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 Standard
+\layout Subsection
-Using interrupts opens the door for some very interesting bugs:
+HC08 Interrupt Service Routines
\layout Standard
-If the interrupt service routines changes variables which are accessed by
- other functions these variables should be declared
-\emph on
-volatile
-\emph default
-
-\begin_inset LatexCommand \index{volatile}
+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
-.
- If the access to these variables is not
-\emph on
-atomic
-\begin_inset LatexCommand \index{atomic access}
+ for details on customizing startup.
+\layout Subsection
-\end_inset
+Z80 Interrupt Service Routines
+\layout Standard
+The Z80 uses several different methods for determining the correct interrupt
+ vector depending on the hardware implementation.
+ Therefore, SDCC ignores the optional interrupt number and does not attempt
+ to generate an interrupt vector table.
+\layout Standard
+By default, SDCC generates code for a maskable interrupt, which uses an
+ RETI instruction to return from the interrupt.
+ To write an interrupt handler for the non-maskable interrupt, which needs
+ an RETN instruction instead, add the
+\emph on
+critical
\emph default
- (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
+ keyword:
+\layout Verse
\family typewriter
-flags\SpecialChar ~
-|=\SpecialChar ~
-0x80;
-\family default
+void nmi_isr (void) critical interrupt
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Section
-\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 banks.
-\layout Section
-
-Enabling and Disabling Interrupts
-\layout Subsection
+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
+A special keyword may be associated with a block or a function declaring
+ it as
\emph on
critical
\emph default
\family typewriter
+EA = 0;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+or:\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+EA_SAVE = EA;
+\layout Verse
+
+
+\family typewriter
+...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
EA = 0;
\layout Verse
\family typewriter
+EA = 1;\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 ~
...
\layout Verse
\family typewriter
-EA = 1;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+EA = EA_SAVE;
\layout Standard
On other architectures which have seperate opcodes for enabling and disabling
\emph default
register.
- Usually the time during which interrupts are disabled should be kept as
+
+\layout Standard
+
+Usually the time during which interrupts are disabled should be kept as
short as possible.
This minimizes both
\emph on
\end_inset
.
- On architectures which don't support interrupt priorities these can be
- implemented by manipulating the interrupt mask and reenabling interrupts
+ 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.
-
-\layout Section
+ Check there is sufficient space on the stack
+\begin_inset LatexCommand \index{stack}
-Functions using private banks
-\begin_inset LatexCommand \label{sub:Functions-using-private-banks}
+\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
-\begin_inset LatexCommand \index{bank}
+ 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
-The
+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
+\begin_inset LatexCommand \label{sub:Functions-using-private-banks}
+
+\end_inset
+
+ (mcs51/ds390)
+\layout Standard
+
+Some architectures have support for quickly changing register sets.
+ SDCC supports this feature with the
\emph on
using
-\begin_inset LatexCommand \index{using}
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
\end_inset
\emph default
- attribute (which tells the compiler to use a register bank other than the
- default bank zero) should only be applied to
+ attribute (which tells the compiler to use a register bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
+
+\end_inset
+
+ other than the default bank zero).
+ It should only be applied to
\emph on
interrupt
\begin_inset LatexCommand \index{interrupt}
\emph default
- functions (see note 1 below).
+ functions (see footnote below).
This will in most circumstances make the generated ISR code more efficient
since it will not have to save registers on the stack.
\layout Standard
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
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-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
\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
how to use inline assembly, access variables, a function parameter and
an array in xdata memory.
+ The example uses an MCS51 here but is easily adapted for other architectures.
This is a buffer routine which should be optimized:
\layout Verse
\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
\layout Standard
The assembler does not like some characters like ':' or ''' in comments.
+ You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
\end_inset
.
\layout Standard
-It is strongly recommended that each assembly instruction (including labels)
- be placed in a separate line (as the example shows).
+It is recommended that each assembly instruction (including labels) be placed
+ in a separate line (as the example shows).
When the -
\begin_inset ERT
status Collapsed
\emph on
SDCCpeeph.def
\emph default
- carefully before using this option.
+ before using this option.
\layout Subsection
Naked Functions
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_counter
+_counter ; does not change flags, no need to save psw
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_counter
+_counter ; does not change flags, no need to save psw
\newline
\SpecialChar ~
\SpecialChar ~
reti\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-; MUST explicitly include ret or reti in _naked function.
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; MUST explicitly include ret or reti in _naked function
\layout Standard
-The #pragma directive EXCLUDE
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+The related directive #pragma exclude
+\begin_inset LatexCommand \index{\#pragma exclude}
\end_inset
the registers.
\layout Standard
-While there is nothing preventing you from writing C code inside a _naked
+While there is nothing preventing you from writing C code inside a
+\family typewriter
+_naked
+\family default
function, there are many ways to shoot yourself in the foot doing this,
and it is recommended that you stick to inline assembler.
\layout Subsection
Use of Labels within Inline Assembler
\layout Standard
-SDCC allows the use of in-line assembler with a few restriction as regards
+SDCC allows the use of in-line assembler with a few restrictions regarding
labels.
In older versions of the compiler all labels defined within inline assembler
code
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-$0003: ;label (can be reference by inline assembler only)
+$0003: ;label (can be referenced by inline assembler only)
\newline
\SpecialChar ~
\SpecialChar ~
In other words inline assembly code can access labels defined in inline
assembly within the scope of the function.
- The same goes the other way, ie.
+ The same goes the other way, i.e.
labels defines in inline assembly can not be accessed by C statements.
\layout Section
\end_inset
, B
-\begin_inset LatexCommand \index{B (register)}
+\begin_inset LatexCommand \index{B (mcs51, ds390 register)}
\end_inset
and
\emph on
ACC
-\begin_inset LatexCommand \index{ACC}
+\begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
\end_inset
\layout Subsection
-Assembler Routine(non-reentrant
+Assembler Routine (non-reentrant)
+\layout Standard
+
+In the following example
\begin_inset LatexCommand \index{reentrant}
\end_inset
-)
+
\begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
\end_inset
-
-\layout Standard
-
-In the following example the function c_func calls an assembler routine
- asm_func, which takes two parameters
+ the function c_func calls an assembler routine asm_func, which takes two
+ parameters
\begin_inset LatexCommand \index{function parameter}
\end_inset
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov a,dpl
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+a,dpl
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,_asm_func_PARM_2
+add\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+a,_asm_func_PARM_2
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov dpl,a
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dpl,a
\newline
\SpecialChar ~
\SpecialChar ~
\begin_inset Quotes erd
\end_inset
- for One bye parameter,
+ for a one byte parameter,
\begin_inset Quotes eld
\end_inset
\begin_inset Quotes erd
\end_inset
- if two bytes,
+ for two bytes,
\begin_inset Quotes eld
\end_inset
\begin_inset Quotes erd
\end_inset
- for four bytes, the variable name for the second parameter will be _<function_n
-ame>_PARM_2.
+ for a four bytes parameter.
+ The variable name for the second parameter will be _<function_name>_PARM_2.
\newline
\newline
sdcc cfunc.c asmfunc.rel
\layout Subsection
-Assembler Routine(reentrant
+Assembler Routine (reentrant)
+\layout Standard
+
+In this case
\begin_inset LatexCommand \index{reentrant}
\end_inset
-)
+
\begin_inset LatexCommand \index{Assembler routines (reentrant)}
\end_inset
-
-\layout Standard
-
-In this case the second parameter
+ the second parameter
\begin_inset LatexCommand \index{function parameter}
\end_inset
onwards will be passed on the stack, the parameters are pushed from right
to left i.e.
- after the call the left most parameter will be on the top of the stack.
+ after the call the leftmost parameter will be on the top of the stack.
Here is an example:
\layout Verse
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov r2,dpl
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov a,_bp
+mov r2,dpl
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-clr c
+mov a,_bp
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,#0xfd
+add a,#0xfd
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov r0,a
+mov r0,a
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,#0xfc
+add a,#0xfc ;?
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,r2
+add a,r2 ;?
\newline
\SpecialChar ~
\SpecialChar ~
\emph default
option.
- Notice that you don't have to call this routines directly.
+ Notice that you don't have to call these routines directly.
The compiler will use them automatically every time an integer operation
is required.
\layout Section
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert unsigned long to floating point number
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert unsigned long to floating point number
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_long2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert long to floating point number
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Standard
+
+These support routines are developed in ANSI-C so there is room for space
+ and speed improvement.
+ Note if all these routines are used simultaneously the data space might
+ overflow.
+ For serious floating point usage it is recommended that the large model
+ be used.
+ Also notice that you don't have to call this routines directly.
+ The compiler will use them automatically every time a floating point operation
+ is required.
+\layout Section
+
+Library Routines
+\begin_inset LatexCommand \index{Libraries}
+
+\end_inset
+
+
+\layout Standard
+
+
+\emph on
+<pending: this is messy and incomplete - a little more information is in
+ sdcc/doc/libdoc.txt
+\emph default
+ >
+\layout Subsection
+
+Compiler support routines (_gptrget, _mulint etc.)
+\layout Subsection
+
+Stdclib functions (puts, printf, strcat etc.)
+\layout Subsubsection
+
+<stdio.h>
+\layout Standard
+
+
+\begin_inset LatexCommand \index{<stdio.h>}
+
+\end_inset
+
+As usual on embedded systems you have to provide your own
+\family typewriter
+getchar()
+\begin_inset LatexCommand \index{getchar()}
+
+\end_inset
+
+
+\family default
+and
+\family typewriter
+putchar()
+\begin_inset LatexCommand \index{putchar()}
+
+\end_inset
+
+
+\family default
+ routines.
+ SDCC does not know whether the system connects to a serial line with or
+ without handshake, LCD, keyboard or other device.
+ You'll find examples for serial routines f.e.
+ 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()
+\family default
+
+\emph on
+instead
+\emph default
+ of
+\family typewriter
+ 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 (by unsetting
+ #defines it can be customized to
+\emph on
+not
+\emph default
+ support long variables and field widths).
+\layout Subsection
+
+Math functions (sin, pow, sqrt etc.)
+\layout Subsection
+
+Other libraries
+\layout Standard
+
+Libraries
+\begin_inset LatexCommand \index{Libraries}
+
+\end_inset
+
+ included in SDCC should have a license at least as liberal as the GNU Lesser
+ General Public License
+\begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
+
+\end_inset
+
+
+\emph on
+LGPL
+\emph default
+.
+\layout Comment
+
+license statements for the libraries are missing.
+ sdcc/device/lib/ser_ir.c
+\layout Comment
+
+or _decdptr f.e.
+ come with a GPL (as opposed to LGPL) License - this will not be liberal
+ enough for many embedded programmers.
+\layout Standard
+
+If you have ported some library or want to share experience about some code
+ which f.e.
+ falls into any of these categories Busses (I
+\begin_inset Formula $^{\textrm{2}}$
+\end_inset
+
+C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
+ cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
+ Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
+\begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
+
+\end_inset
+
+\SpecialChar ~
+would certainly like to hear about it.
+ Programmers coding for embedded systems are not especially famous for being
+ enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
+e these references are very valuable.
+ Let's help to create a climate where information is shared.
+\layout Section
+
+Memory Models
+\layout Subsection
+
+MCS51 Memory Models
+\begin_inset LatexCommand \index{Memory model}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{MCS51 memory model}
+
+\end_inset
+
+
+\layout Subsubsection
+
+Small and Large
+\layout Standard
+
+SDCC allows two memory models for MCS51 code,
+\shape slanted
+small
+\shape default
+ and
+\shape slanted
+large
+\shape default
+.
+ Modules compiled with different memory models should
+\emph on
+never
+\emph default
+ be combined together or the results would be unpredictable.
+ The library routines supplied with the compiler are compiled as both small
+ and large.
+ The compiled library modules are contained in separate directories as small
+ and large so that you can link to either set.
+
+\layout Standard
+
+When the large model is used all variables declared without a storage class
+ will be allocated into the external ram, this includes all parameters and
+ local variables (for non-reentrant
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+ functions).
+ When the small model is used variables without storage class are allocated
+ in the internal ram.
+\layout Standard
+
+Judicious usage of the processor specific storage classes
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ and the 'reentrant' function type will yield much more efficient code,
+ than using the large model.
+ Several optimizations are disabled when the program is compiled using the
+ large model, it is therefore recommended that the small model be used unless
+ absolutely required.
+\layout Subsubsection
+
+External Stack
+\begin_inset LatexCommand \label{sub:External-Stack}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{External stack (mcs51)}
+
+\end_inset
+
+
+\layout Standard
+
+The external stack (-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xstack option
+\begin_inset LatexCommand \index{-\/-xstack}
+
+\end_inset
+
+) is located in pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ memory (usually at the start of the external ram segment) and uses all
+ unused space in pdata (max.
+ 256 bytes).
+ When -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-xstack option is used to compile the program, the parameters and local
+ variables
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+ of all reentrant functions are allocated in this area.
+ This option is provided for programs with large stack space requirements.
+ When used with the -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+ option, all parameters and local variables are allocated on the external
+ stack (note: support libraries will need to be recompiled with the same
+ options.
+ There is a predefined target in the library makefile).
+\layout Standard
+
+The compiler outputs the higher order address byte of the external ram segment
+ into port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
+
+\end_inset
+
+ (see also section
+\begin_inset LatexCommand \ref{sub:MCS51-variants}
+
+\end_inset
+
+), therefore when using the External Stack option, this port
+\emph on
+may not
+\emph default
+ be used by the application program.
+\layout Subsection
+
+DS390 Memory Model
+\begin_inset LatexCommand \index{Memory model}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{DS390 memory model}
+
+\end_inset
+
+
+\layout Standard
+
+The only model supported is Flat 24
+\begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
+
+\end_inset
+
+.
+ This generates code for the 24 bit contiguous addressing mode of the Dallas
+ DS80C390 part.
+ In this mode, up to four meg of external RAM or code space can be directly
+ addressed.
+ See the data sheets at www.dalsemi.com for further information on this part.
+\newline
+
+\newline
+Note that the compiler does not generate any code to place the processor
+ into 24 bitmode (although
+\emph on
+tinibios
+\emph default
+ in the ds390 libraries will do that for you).
+ If you don't use
+\emph on
+tinibios
+\emph default
+
+\begin_inset LatexCommand \index{Tinibios (DS390)}
+
+\end_inset
+
+, the boot loader or similar code must ensure that the processor is in 24
+ bit contiguous addressing mode before calling the SDCC startup code.
+\newline
+
+\newline
+Like the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-large
+\emph default
+ option, variables will by default be placed into the XDATA segment.
+
+\newline
+
+\newline
+Segments may be placed anywhere in the 4 meg address space using the usual
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-*-loc options.
+ Note that if any segments are located above 64K, the -r flag must be passed
+ to the linker to generate the proper segment relocations, and the Intel
+ HEX output format must be used.
+ The -r flag can be passed to the linker by using the option
+\emph on
+-Wl-r
+\emph default
+ on the SDCC command line.
+ However, currently the linker can not handle code segments > 64k.
+\layout Section
+
+Pragmas
+\begin_inset LatexCommand \index{Pragmas}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC supports the following #pragma directives:
+\layout Itemize
+
+save
+\begin_inset LatexCommand \index{\#pragma save}
+
+\end_inset
+
+ - this will save all current options to the save/restore stack.
+ See #pragma\SpecialChar ~
+restore.
+\layout Itemize
+
+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 #pragma\SpecialChar ~
+save.
+\newline
+
+\layout Itemize
+
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{function prologue}
+
+\end_inset
+
+ function1[,function2[,function3...]] - The compiler by default uses a caller
+ saves convention for register saving across function calls, however this
+ can cause unnecessary register pushing & popping
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
+
+ when calling small functions from larger functions.
+ This option can be used to switch off the register saving convention for
+ the function names specified.
+ The compiler will not save registers when calling these functions, extra
+ code need to be manually inserted at the entry & exit for these functions
+ to save & restore the registers used by these functions, this can SUBSTANTIALLY
+ reduce code & improve run time performance of the generated code.
+ In the future the compiler (with inter procedural analysis) may be able
+ to determine the appropriate scheme to use for each function call.
+ If -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-callee-saves command line option is used, the function names specified
+ in #pragma\SpecialChar ~
+callee_saves
+\begin_inset LatexCommand \index{\#pragma callee\_saves}
+
+\end_inset
+
+ is appended to the list of functions specified in the command line.
+\layout Itemize
+
+exclude
+\begin_inset LatexCommand \index{\#pragma exclude}
+
+\end_inset
+
+ none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
+ of pairs of push/pop
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
+
+ instructions in
+\emph on
+I
+\emph default
+nterrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\emph on
+S
+\emph default
+ervice
+\emph on
+R
+\emph default
+outines.
+ The directive should be placed immediately before the ISR function definition
+ and it affects ALL ISR functions following it.
+ To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
+exclude\SpecialChar ~
+none
+\begin_inset LatexCommand \index{\#pragma exclude}
+
+\end_inset
+
+.
+ See also the related keyword _naked
+\begin_inset LatexCommand \index{\_naked}
+
+\end_inset
+
+.
+\layout Itemize
+
+less_pedantic
+\begin_inset LatexCommand \index{\#pragma less\_pedantic}
+
+\end_inset
+
+ - the compiler will not warn you anymore for obvious mistakes, you'r on
+ your own now ;-(
+\layout Itemize
+
+disable_warning <nnnn>
+\begin_inset LatexCommand \index{\#pragma disable\_warning}
+
+\end_inset
+
+ - the compiler will not warn you anymore about warning number <nnnn>.
+\layout Itemize
+
+nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
+
+\end_inset
+
+ - will stop global common subexpression elimination.
+\layout Itemize
+
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+
+\end_inset
+
+ - will stop loop induction optimizations.
+\layout Itemize
+
+noinvariant
+\begin_inset LatexCommand \index{\#pragma noinvariant}
+
+\end_inset
+
+ - will not do loop invariant optimizations.
+ For more details see Loop Invariants in section
+\begin_inset LatexCommand \ref{sub:Loop-Optimizations}
+
+\end_inset
+
+.
+\layout Itemize
+
+noiv
+\begin_inset LatexCommand \index{\#pragma noiv}
+
+\end_inset
+
+ - Do not generate interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ vector table entries for all ISR functions defined after the pragma.
+ This is useful in cases where the interrupt vector table must be defined
+ manually, or when there is a secondary, manually defined interrupt vector
+ table (e.g.
+ for the autovector feature of the Cypress EZ-USB FX2).
+ More elegantly this can be achieved by obmitting the optional interrupt
+ number after the interrupt keyword, see section
+\begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
+
+\end_inset
+
+\SpecialChar ~
+about interrupts.
+\layout Itemize
+
+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
+
+noloopreverse
+\begin_inset LatexCommand \index{\#pragma noloopreverse}
+
+\end_inset
+
+ - Will not do loop reversal optimization
+\layout Itemize
+
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+
+ - 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
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+ and section
+\begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+ Parameters and Local Variables.
+\layout Itemize
+
+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
+\begin_inset LatexCommand \index{\#pragma preproc\_asm}
+
+\end_inset
+
+ (+ | -) - switch _asm _endasm block preprocessing on / off.
+ Default is on.
+\layout Standard
+
+The pragma's are intended to be used to turn-on or off certain optimizations
+ which might cause the compiler to generate extra stack / data space to
+ store compiler generated temporary variables.
+ This usually happens in large functions.
+ Pragma directives should be used as shown in the following example, they
+ are used to control options & optimizations for a given function; pragmas
+ should be placed before and/or after a function, placing pragma's inside
+ a function body could have unpredictable results.
+\layout Verse
+
+
+\family typewriter
+#pragma save
+\begin_inset LatexCommand \index{\#pragma save}
+
+\end_inset
+
+ \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* save the current settings */
+\newline
+#pragma nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
+
+\end_inset
+
+ \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* turnoff global subexpression elimination */
+\newline
+#pragma noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+
+\end_inset
+
+ /* turn off induction optimizations */
+\newline
+int foo ()
+\newline
+{
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ /* large code */
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+}
+\newline
+#pragma restore
+\begin_inset LatexCommand \index{\#pragma restore}
+
+\end_inset
+
+ /* turn the optimizations back on */
+\layout Standard
+
+The compiler will generate a warning message when extra space is allocated.
+ It is strongly recommended that the save and restore pragma's be used when
+ changing options for a function.
+\layout Section
+
+Defines Created by the Compiler
+\layout Standard
+
+The compiler creates the following #defines
+\begin_inset LatexCommand \index{\#defines}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Defines created by the compiler}
+
+\end_inset
+
+:
+\newline
+
+\layout Standard
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="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" bottomline="true">
+<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
-_long2fs.c
+\series bold
+ignore
\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
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert long to floating point number
+ignore all library pragmas
\end_inset
</cell>
-</row>
-</lyxtabular>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\end_inset
+\layout Standard
-\newline
+\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
-Note if all these routines are used simultaneously the data space might
- overflow.
- For serious floating point usage it is strongly recommended that the large
- model be used.
- Also notice that you don't have to call this routines directly.
- The compiler will use them automatically every time a floating point operation
- is required.
-\layout Section
-
-MCS51 Memory Models
-\begin_inset LatexCommand \index{Memory model}
+\series bold
+c
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{MCS51 memory}
-
+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
-SDCC allows two memory models for MCS51 code,
-\shape slanted
-small
-\shape default
- and
-\shape slanted
-large
-\shape default
-.
- Modules compiled with different memory models should
+
\emph on
-never
+libc18f
\emph default
- be combined together or the results would be unpredictable.
- The library routines supplied with the compiler are compiled as both small
- and large.
- The compiled library modules are contained in separate directories as small
- and large so that you can link to either set.
-
+.lib
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
\layout Standard
-When the large model is used all variables declared without a storage class
- will be allocated into the external ram, this includes all parameters and
- local variables (for non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+\series bold
+math
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- functions).
- When the small model is used variables without storage class are allocated
- in the internal ram.
\layout Standard
-Judicious usage of the processor specific storage classes
-\begin_inset LatexCommand \index{Storage class}
-
+link the Math libarary
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- and the 'reentrant' function type will yield much more efficient code,
- than using the large model.
- Several optimizations are disabled when the program is compiled using the
- large model, it is therefore strongly recommended that the small model
- be used unless absolutely required.
-\layout Section
+\layout Standard
-DS390 Memory Models
-\begin_inset LatexCommand \index{Memory model}
+\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
-\begin_inset LatexCommand \index{DS390 memory model}
+\series bold
+io
\end_inset
-
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-The only model supported is Flat 24
-\begin_inset LatexCommand \index{Flat 24 (memory model)}
-
+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
-.
- This generates code for the 24 bit contiguous addressing mode of the Dallas
- DS80C390 part.
- In this mode, up to four meg of external RAM or code space can be directly
- addressed.
- See the data sheets at www.dalsemi.com for further information on this part.
-\newline
-\newline
-Note that the compiler does not generate any code to place the processor
- into 24 bitmode (although
-\emph on
-tinibios
-\emph default
- in the ds390 libraries will do that for you).
- If you don't use
\emph on
-tinibios
+libio18f*
\emph default
-
-\begin_inset LatexCommand \index{Tinibios (DS390)}
-
+.lib
\end_inset
-
-, the boot loader or similar code must ensure that the processor is in 24
- bit contiguous addressing mode before calling the SDCC startup code.
-\newline
-
-\newline
-Like the
-\emph on
--
-\begin_inset ERT
-status Collapsed
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+
+\series bold
+debug
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--model-large
-\emph default
- option, variables will by default be placed into the XDATA segment.
-
-\newline
+\layout Standard
-\newline
-Segments may be placed anywhere in the 4 meg address space using the usual
- -
-\begin_inset ERT
-status Collapsed
+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
-\backslash
-/
-\end_inset
--*-loc options.
- Note that if any segments are located above 64K, the -r flag must be passed
- to the linker to generate the proper segment relocations, and the Intel
- HEX output format must be used.
- The -r flag can be passed to the linker by using the option
\emph on
--Wl-r
+libdebug
\emph default
- on the SDCC command line.
- However, currently the linker can not handle code segments > 64k.
-\layout Section
-
-Pragmas
-\begin_inset LatexCommand \index{Pragmas}
-
+.lib
\end_inset
-
-
-\layout Standard
-
-SDCC supports the following #pragma directives.
-\layout Itemize
-
-SAVE
-\begin_inset LatexCommand \index{\#pragma SAVE}
+</cell>
+</row>
+</lyxtabular>
\end_inset
- - this will save all current options to the SAVE/RESTORE stack.
- See RESTORE.
-\layout Itemize
-
-RESTORE
-\begin_inset LatexCommand \index{\#pragma RESTORE}
-\end_inset
+\newline
+* is the device number, i.e.
+ 452 for PIC18F452 MCU.
+\layout Standard
- - 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.
-\layout Itemize
+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
-NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+Header Files
+\begin_inset LatexCommand \label{sub:PIC16_Header-Files}
\end_inset
- - will stop global common subexpression elimination.
-\layout Itemize
-NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
-
-\end_inset
+\layout Standard
- - will stop loop induction optimizations.
-\layout Itemize
+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
-NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+#include <pic18fregs.h>
+\layout Standard
-\end_inset
+The specific microcontroller is selected within the pic18fregs.h automatically,
+ so the same source can be used with a variety of devices.
+\layout Subsection
- - 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}
+Libraries
+\layout Standard
+
+The libraries that PIC16
+\begin_inset LatexCommand \index{PIC16}
\end_inset
-.
-\layout Itemize
+ 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
-NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+Libraries are created with gplib which is part of the gputils package
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net}
\end_inset
- - the compiler will not overlay the parameters and local variables of a
- function.
-\layout Itemize
+.
+\layout Subsubsection
-LESS_PEDANTIC
-\begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
+Building the libraries
+\layout Standard
-\end_inset
+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 compiler will not warn you anymore for obvious mistakes, you'r on
- your own now ;-(
-\layout Itemize
+The steps to compile the pic16 libraries under Linux are:
+\layout LyX-Code
-NOLOOPREVERSE
-\begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
+cd device/lib/pic16
+\layout LyX-Code
-\end_inset
+./configure
+\layout LyX-Code
- - Will not do loop reversal optimization
-\layout Itemize
+make
+\layout LyX-Code
-EXCLUDE
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+cd ..
+\layout LyX-Code
-\end_inset
+make model-pic16
+\layout LyX-Code
- NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
- pair of push/pop
-\begin_inset LatexCommand \index{push/pop}
+su -c 'make install' # install the libraries, you need the root password
+\layout Standard
-\end_inset
+If you need to install the headers to, do:
+\layout LyX-Code
- instruction in ISR function (using interrupt
-\begin_inset LatexCommand \index{interrupt}
+cd device/include
+\layout LyX-Code
-\end_inset
+su -c 'make install' # install the headers, you need the root password
+\layout LyX-Code
- 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}
+\layout Subsection
-\end_inset
+Memory Models
+\layout Standard
-.
+The following memory models are supported by the PIC16 port:
\layout Itemize
-NOIV
-\begin_inset LatexCommand \index{\#pragma NOIV}
-
-\end_inset
+small model
+\layout Itemize
- - Do not generate interrupt vector table entries for all ISR functions
- defined after the pragma.
- This is useful in cases where the interrupt vector table must be defined
- manually, or when there is a secondary, manually defined interrupt vector
- table (e.g.
- for the autovector feature of the Cypress EZ-USB FX2).
- More elegantly this can be achieved by obmitting the optional interrupt
- number after the interrupt keyword, see section
-\begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
+large model
+\layout Standard
-\end_inset
+Memory model affects the default size of pointers within the source.
+ The sizes are shown in the next table:
+\layout Standard
+\align center
-\SpecialChar ~
-about interrupts.
-\layout Itemize
+\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
-CALLEE-SAVES
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+\layout Standard
+Pointer sizes according to memory model
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{function prologue}
-
+small model
\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 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
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+large model
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--callee-saves command line option is used, the function names specified
- in #pragma\SpecialChar ~
-CALLEE-SAVES
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+\layout Standard
+code pointers
\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- is appended to the list of functions specified in the command line.
-\layout Itemize
-
-preproc_asm
-\begin_inset LatexCommand \index{\#pragma preproc\_asm}
+\layout Standard
+16-bits
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- (+ | -) - switch _asm _endasm block preprocessing on / off.
- Default is on.
\layout Standard
-The pragma's are intended to be used to turn-on or off certain optimizations
- which might cause the compiler to generate extra stack / data space to
- store compiler generated temporary variables.
- This usually happens in large functions.
- Pragma directives should be used as shown in the following example, they
- are used to control options & optimizations for a given function; pragmas
- should be placed before and/or after a function, placing pragma's inside
- a function body could have unpredictable results.
-\layout Verse
-
+24-bits
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family typewriter
-#pragma SAVE
-\begin_inset LatexCommand \index{\#pragma SAVE}
+\layout Standard
+data pointers
\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
- \SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* save the current settings */
-\newline
-#pragma NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+\layout Standard
+16-bits
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- \SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* turnoff global subexpression elimination */
-\newline
-#pragma NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+\layout Standard
+16-bits
\end_inset
-
- /* turn off induction optimizations */
-\newline
-int foo ()
-\newline
-{
-\newline
-\SpecialChar ~
- \SpecialChar ~
- ...
-
-\newline
-\SpecialChar ~
- \SpecialChar ~
- /* large code */
-\newline
-\SpecialChar ~
- \SpecialChar ~
- ...
-
-\newline
-}
-\newline
-#pragma RESTORE
-\begin_inset LatexCommand \index{\#pragma RESTORE}
+</cell>
+</row>
+</lyxtabular>
\end_inset
- /* turn the optimizations back on */
+
\layout Standard
-The compiler will generate a warning message when extra space is allocated.
- It is strongly recommended that the SAVE and RESTORE pragma's be used when
- changing options for a function.
-\layout Section
+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
-Defines Created by the Compiler
-\begin_inset LatexCommand \index{Defines created by the compiler}
+The standard device libraries (see
+\begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
\end_inset
+) contain no reference to pointers, so they can be used with both memory
+ models.
+\layout Subsection
+Stack
\layout Standard
-The compiler creates the following #defines
-\begin_inset LatexCommand \index{\#defines}
+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
-:
-\newline
+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="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
-
-\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
+Stack & Frame pointer sizes according to stack model
\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}
+\begin_inset Text
-\end_inset
+\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
-this Symbol is always defined
+large
\end_inset
</cell>
</row>
\layout Standard
-SDCC_mcs51
-\begin_inset LatexCommand \index{SDCC\_mcs51}
-
+Stack pointer FSR1
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- or SDCC_ds390
-\begin_inset LatexCommand \index{SDCC\_ds390}
+\layout Standard
+8-bits
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- or SDCC_z80
-\begin_inset LatexCommand \index{SDCC\_z80}
+\layout Standard
+16-bits
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-, etc
+\layout Standard
+
+Frame pointer FSR2
\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.: -mds390
+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
-__mcs51
-\begin_inset LatexCommand \index{\_\_mcs51}
-
+16-bits
\end_inset
-
-, __ds390
-\begin_inset LatexCommand \index{\_\_ds390}
+</cell>
+</row>
+</lyxtabular>
\end_inset
-, __hc08
-\begin_inset LatexCommand \index{\_\_hc08}
-\end_inset
+\layout Standard
-, __z80
-\begin_inset LatexCommand \index{\_\_z80}
-\end_inset
+\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
-, etc
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\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
-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
+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
-SDCC_STACK_AUTO
-\begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
+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
-\end_inset
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+size
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-when
-\emph on
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--stack-auto
-\emph default
- option is used
+destination register
\end_inset
</cell>
</row>
\layout Standard
-SDCC_MODEL_SMALL
-\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
-
-\end_inset
-
-
+8 bits
\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
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--model-small
-\emph default
- is used
+WREG
\end_inset
</cell>
</row>
\layout Standard
-SDCC_MODEL_LARGE
-\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
-
-\end_inset
-
-
+16 bits
\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
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--model-large
-\emph default
- is used
+PRODL:WREG
\end_inset
</cell>
</row>
\layout Standard
-SDCC_USE_XSTACK
-\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
-
-\end_inset
-
-
+24 bits
\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
-
-\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
-\begin_inset LatexCommand \index{sdcdb}
+\begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{sdcdb (debugger)}
\end_inset
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
\layout Standard
Step program until it reaches a different source line.
+ Note: pressing <return> repeats the last command.
\layout Subsubsection*
next
context and may display incorrect values.
\layout Subsubsection*
-quit.
+quit
\layout Standard
"Watch me now.
\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
Use unsigned when it is known in advance that the value is not going to
be negative.
- This helps especially if you are doing division or multiplication.
+ This helps especially if you are doing division or multiplication, bit-shifting
+ or are using an array index.
\layout Itemize
NEVER jump into a LOOP.
\layout Itemize
-Declare the variables to be local whenever possible, especially loop control
- variables (induction).
+Declare the variables to be local
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+ whenever possible, especially loop control variables (induction).
\layout Itemize
Since the compiler does not always do implicit integral promotion, the programme
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char ch1 = p1 * ch ;
+unsigned char ch1 = p1 % ch ;
\newline
\SpecialChar ~
\SpecialChar ~
}
\layout Standard
-For the multiplication the variable ch will be promoted to int first then
- the modulus operation will be performed (this will lead to a call to support
- routine _mulint()), and the result will be casted to a char.
+For the modulus operation the variable ch will be promoted to unsigned int
+ first then the modulus operation will be performed (this will lead to a
+ call to support routine _moduint()), and the result will be casted to a
+ char.
If the code is changed to
\layout Verse
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char ch1 = (unsigned char)p1 * ch ;
+unsigned char ch1 = (unsigned char)p1 % ch ;
\newline
\SpecialChar ~
\SpecialChar ~
}
\layout Standard
-it would substantially reduce the code generated (future versions of the
+It would substantially reduce the code generated (future versions of the
compiler will be smart enough to detect such optimization opportunities).
\end_deeper
\layout Itemize
for the code generation.
\layout Section
-Notes on MCS51 memory
-\begin_inset LatexCommand \index{MCS51 memory}
-
-\end_inset
-
- layout
-\layout Standard
-
-The 8051 family of microcontrollers have a minimum of 128 bytes of internal
- RAM memory which is structured as follows
-\newline
-
-\newline
-- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
-
-\newline
-- Bytes 20-2F - 16 bytes to hold 128 bit
-\begin_inset LatexCommand \index{bit}
+Tools
+\begin_inset LatexCommand \index{Tools}
\end_inset
- variables and,
-\newline
-- Bytes 30-7F - 80 bytes for general purpose use.
-\newline
-
+ included in the distribution
\layout Standard
+\align center
-Additionally some members of the MCS51 family may have up to 128 bytes of
- additional, indirectly addressable, internal RAM memory (
-\emph on
-idata
-\emph default
-
-\begin_inset LatexCommand \index{idata}
-
-\end_inset
-
-).
- Furthermore, some chips may have some built in external memory (
-\emph on
-xdata
-\emph default
-
-\begin_inset LatexCommand \index{xdata}
-
-\end_inset
-
-) which should not be confused with the internal, directly addressable RAM
- memory (
-\emph on
-data
-\emph default
-
-\begin_inset LatexCommand \index{data}
-
-\end_inset
-
-).
- Sometimes this built in
-\emph on
-xdata
-\emph default
- memory has to be activated before using it (you can probably find this
- information on the datasheet of the microcontroller your are using, see
- also section
-\begin_inset LatexCommand \ref{sub:Startup-Code}
-
-\end_inset
+\begin_inset Tabular
+<lyxtabular version="3" rows="12" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\SpecialChar ~
-Startup-Code).
\layout Standard
-Normally SDCC will only use the first bank
-\begin_inset LatexCommand \index{bank}
-
-\end_inset
-
- of registers (register bank 0), but it is possible to specify that other
- banks of registers should be used in interrupt
-\begin_inset LatexCommand \index{interrupt}
-
-\end_inset
-
- routines.
- By default, the compiler will place the stack after the last byte of allocated
- memory for variables.
- For example, if the first 2 banks of registers are used, and only four
- bytes are used for
-\emph on
-data
-\emph default
- variables, it will position the base of the internal stack at address 20
- (0x14).
- This implies that as the stack
-\begin_inset LatexCommand \index{stack}
-
+Name
\end_inset
-
- 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.
- 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.
- You can also use -
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
-
--data-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
-
+Purpose
\end_inset
-
- to specify the start address of the
-\emph on
-data
-\emph default
- and -
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+Directory
\end_inset
-
--iram-size to specify the size of the total internal RAM (
-\emph on
-data
-\emph default
-+
-\emph on
-idata
-\emph default
-).
-
-\layout Standard
-
-By default the 8051 linker will place the stack after the last byte of data
- variables.
- Option -
-\begin_inset ERT
-status Collapsed
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
-
--stack-loc
-\begin_inset LatexCommand \index{-\/-stack-loc}
-
+uCsim
\end_inset
-
- allows you to specify the start of the stack, i.e.
- you could start it after any data in the general purpose area.
- If your microcontroller has additional indirectly addressable internal
- RAM (
-\emph on
-idata
-\emph default
-) you can place the stack on it.
- You may also need to use -
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
-
--xdata-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
-
+Simulator for various architectures
\end_inset
-
- to set the start address of the external RAM (
-\emph on
-xdata
-\emph default
-) and -
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
-
--xram-size
-\begin_inset LatexCommand \index{-\/-data-loc}
-
+sdcc/sim/ucsim
\end_inset
-
- to specify its size.
- Same goes for the code memory, using -
-\begin_inset ERT
-status Collapsed
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
-
--code-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
-
+keil2sdcc.pl
\end_inset
-
- and -
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+header file conversion
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--code-size
-\begin_inset LatexCommand \index{-\/-data-loc}
+\layout Standard
+sdcc/support/scripts
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
- If in doubt, don't specify any options and see if the resulting memory
- layout is appropriate, then you can adjust it.
\layout Standard
-The 8051 linker generates two files with memory allocation information.
- The first, with extension .map shows all the variables and segments.
- The second with extension .mem shows the final memory layout.
- The linker will complaint either if memory segments overlap, there is not
- enough memory, or there is not enough space for stack.
- If you get any linking warnings and/or errors related to stack or segments
- allocation, take a look at either the .map or .mem files to find out what
- the problem is.
- The .mem file may even suggest a solution to the problem.
-\layout Section
+mh2h.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Tools
-\begin_inset LatexCommand \index{Tools}
+\layout Standard
+header file conversion
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- included in the distribution
\layout Standard
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="12" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
+sdcc/support/scripts
+\end_inset
+</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
+as-gbz80
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Purpose
+Assembler
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Directory
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
</cell>
</row>
\layout Standard
-uCsim
+as-z80
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Simulator for various architectures
+Assembler
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/sim/ucsim
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
</cell>
</row>
\layout Standard
-keil2sdcc.pl
+asx8051
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-header file conversion
+Assembler
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/support/scripts
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
</cell>
</row>
\layout Standard
-mh2h.c
+sdcdb
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-header file conversion
+Simulator
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/support/scripts
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
</cell>
</row>
\layout Standard
-as-gbz80
+aslink
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Assembler
+Linker
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-as-z80
+link-z80
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Assembler
+Linker
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-asx8051
+link-gbz80
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Assembler
+Linker
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\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
-sdcdb
+packihx
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Simulator
+ihx packer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\end_inset
</cell>
</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Section
+
+Documentation
+\begin_inset LatexCommand \index{Documentation}
+
+\end_inset
+
+ included in the distribution
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="10" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Subject / Title
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Where to get / filename
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC Compiler User Guide
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+You're reading it right now
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Changelog of SDCC
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/Changelog
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/as/doc/asxhtm.html
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+SDCC regression test
+\begin_inset LatexCommand \index{Regression test}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/doc/test_suite_spec.pdf
+\end_inset
+</cell>
+</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-aslink
+Various notes
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-Linker
+sdcc/doc/*
\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
+Notes on debugging with sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
+\end_inset
+
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-link-z80
+sdcc/debugger/README
\end_inset
</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Linker
+Software simulator for microcontrollers
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\bar no
\noun off
\color none
-sdcc/bin
+sdcc/sim/ucsim/doc
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+/index.html
\end_inset
</cell>
</row>
\layout Standard
-link-gbz80
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Temporary notes on the pic16
+\begin_inset LatexCommand \index{PIC16}
-\layout Standard
+\end_inset
-Linker
+ port
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+sdcc/src/pic16/NOTES
\end_inset
</cell>
</row>
\layout Standard
-packihx
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-ihx packer
+SDCC internal documentation (debugging file format)
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
+sdcc/doc/
\family roman
\series medium
\shape up
\bar no
\noun off
\color none
-sdcc/bin
+cdbfileformat.pd
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+f
\end_inset
</cell>
</row>
\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="9" 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}
+\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
indent
-\begin_inset LatexCommand \index{indent}
+\begin_inset LatexCommand \index{indent (source formatting tool)}
\end_inset
\layout Standard
srecord
-\begin_inset LatexCommand \index{srecord}
+\begin_inset LatexCommand \index{srecord (tool)}
\end_inset
\layout Standard
objdump
-\begin_inset LatexCommand \index{objdump}
+\begin_inset LatexCommand \index{objdump (tool)}
\end_inset
\layout Standard
doxygen
-\begin_inset LatexCommand \index{doxygen}
+\begin_inset LatexCommand \index{doxygen (source documentation tool)}
\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
+
+kdevelop
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://www.kdevelop.org}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
splint
-\begin_inset LatexCommand \index{splint}
+\begin_inset LatexCommand \index{splint (syntax checking tool)}
\end_inset
\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">
\layout Standard
ddd
-\begin_inset LatexCommand \index{ddd}
+\begin_inset LatexCommand \index{ddd (debugger)}
\end_inset
\layout Standard
Debugger, serves nicely as GUI to sdcdb
-\begin_inset LatexCommand \index{sdcdb}
+\begin_inset LatexCommand \index{sdcdb (debugger)}
\end_inset
\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="5" 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
-S.
- S.
- Muchnick
+c-faq
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Advanced Compiler Design and Implementation
+C-FAQ-list
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-bookstore
+
+\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-test_suite_spec.pdf
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-sdcc regression test
-\begin_inset LatexCommand \index{Regression test}
+Latest datasheet of the target CPU
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+vendor
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+Revision history of datasheet
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/doc
+vendor
\end_inset
</cell>
</row>
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-cdbfileformat.pd
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color default
-f
+S.
+ S.
+ Muchnick
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-sdcc internal documentation
+Advanced Compiler Design and Implementation
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/doc
+bookstore (very dedicated, probably read other books first)
\end_inset
</cell>
</row>
\newline
+\layout Section
+
+Some Questions
+\layout Standard
+
+Some questions answered, some pointers given - it might be time to in turn
+ ask
+\emph on
+you
+\emph default
+ some questions:
+\layout Itemize
+
+can you solve your project with the selected microcontroller? Would you
+ find out early or rather late that your target is too small/slow/whatever?
+ Can you switch to a slightly better device if it doesn't fit?
+\layout Itemize
+
+should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
+ and/or another programming language be more adequate? Would an operating
+ system on the target device help?
+\layout Itemize
+
+if you solved the problem, will the marketing department be happy?
+\layout Itemize
+
+if the marketing department is happy, will customers be happy?
+\layout Itemize
+
+if you're the project manager, marketing department and maybe even the customer
+ in one person, have you tried to see the project from the outside?
+\layout Itemize
+
+is the project done if you think it is done? Or is just that other interface/pro
+tocol/feature/configuration/option missing? How about website, manual(s),
+ internationali(z|s)ation, packaging, labels, 2nd source for components,
+ electromagnetic compatability/interference, documentation for production,
+ production test software, update mechanism, patent issues?
+\layout Itemize
+
+is your project adequately positioned in that magic triangle: fame, fortune,
+ fun?
+\layout Standard
+
+Maybe not all answers to these questions are known and some answers may
+ even be
+\emph on
+no
+\emph default
+, nevertheless knowing these questions may help you to avoid burnout
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+burnout is bad for electronic devices, programmers and motorcycle tyres
+\end_inset
+
+.
+ Chances are you didn't want to hear some of them...
\layout Chapter
-\pagebreak_top
+
Support
\begin_inset LatexCommand \index{Support}
.
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
\end_inset
-\begin_inset LatexCommand \index{Requesting features}
+\begin_inset LatexCommand \index{Requesting features}
+
+\end_inset
+
+
+\layout Standard
+
+Like bug reports feature requests are forwarded to the developer mailing
+ list.
+ This is the link for requesting features:
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
+
+\end_inset
+
+.
+\layout Section
+
+Submitting patches
+\layout Standard
+
+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
-\layout Standard
-Like bug reports feature requests are forwarded to the developer mailing
- list.
- This is the link for requesting features:
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
+\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
\end_inset
-, lists and forums are archived so if you are lucky someone already had
- a similar problem.
-\layout Section
-
-ChangeLog
-\begin_inset LatexCommand \index{Changelog}
+, 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
\layout Standard
You can follow the status of the cvs version
\end_inset
- of SDCC by watching the file
-\begin_inset LatexCommand \htmlurl[ChangeLog]{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
+ of SDCC by watching the Changelog
+\begin_inset LatexCommand \index{Changelog}
+
+\end_inset
+
+ in the cvs-repository
+\newline
+
+\size footnotesize
+
+\begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
\end_inset
- in the cvs-repository.
+.
\layout Section
Release policy
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}
\layout Standard
-The compiler does local and global common subexpression elimination, e.g.:
-
+The compiler does local and
+\emph on
+g
+\emph default
+lobal
+\emph on
+c
+\emph default
+ommon
+\emph on
+s
+\emph default
+ubexpression
+\emph on
+e
+\emph default
+limination, e.g.:
\layout Verse
\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
\family typewriter
-i = j + 0 ; /* changed to */ i = j;
+i = j + 0;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = j;
\newline
i /= 2;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- /* changed to */ i >>= 1;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i >>= 1;
\newline
-i = j - j ; /* changed to */ i = 0;
+i = j - j;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = 0;
\newline
-i = j / 1 ; /* changed to */ i = j;
+i = j / 1;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = j;
\layout Standard
Note the subexpressions
\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 case labels are in numerical sequence, the labels need not be in order,
- and the starting number need not be one or zero.
+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
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 2: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...\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 4: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 8: ...\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 5: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 9: ...\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 6: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 10: ...\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 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 10:\SpecialChar ~
-...
+case 103: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 11:\SpecialChar ~
-...
+case 104: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 12:\SpecialChar ~
-...
+case 105: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 106: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 107: ...
\newline
}
then both the switch statements will be implemented using jump-tables whereas
the unmodified switch statement will not be.
- You might also consider 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
\layout Standard
Note that the replace pattern cannot be a blank, but can be a comment line.
- Without the 'restart' option only the inner most 'pop' 'push' pair would
+ Without the 'restart' option only the innermost 'pop' 'push' pair would
be eliminated, i.e.:
\layout Verse
\newline
pop ar2
\newline
-push ar2
-\newline
-push ar1
-\layout Standard
-
-would result in:
-\layout Verse
-
-
-\family typewriter
-pop ar1
-\newline
-; nop
-\newline
-push ar1
-\layout Standard
-
-
-\emph on
-with
-\emph default
- the restart option the rule will be applied again to the resulting code
- and then all the pop-push pairs will be eliminated to yield:
-\layout Verse
-
-
-\family typewriter
-; nop
-\newline
-; nop
-\layout Standard
-
-A conditional function can be attached to a rule.
- Attaching rules are somewhat more involved, let me illustrate this with
- an example.
-\layout Verse
-
-
-\family typewriter
-replace {
-\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-ljmp %5
-\newline
-%2:
-\newline
-} by {
-\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-sjmp %5
-\newline
-%2:
-\newline
-} if labelInRange
-\layout Standard
-
-The optimizer does a look-up of a function name table defined in function
-
-\emph on
-callFuncByName
-\emph default
- in the source file SDCCpeeph.c, with the name
-\emph on
-labelInRange
-\emph default
-.
- If it finds a corresponding entry the function is called.
- Note there can be no parameters specified for these functions, in this
- case the use of
-\emph on
-%5
-\emph default
- is crucial, since the function
-\emph on
-labelInRange
-\emph default
- expects to find the label in that particular variable (the hash table containin
-g the variable bindings is passed as a parameter).
- If you want to code more such functions, take a close look at the function
- labelInRange and the calling mechanism in source file SDCCpeeph.c.
- Currently implemented are
-\emph on
-labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
- 24bitMode, portIsDS390, 24bitModeAndPortDS390
-\emph default
-and
-\emph on
- notVolatile
-\emph default
-.
-\layout Standard
-
-I know this whole thing is a little kludgey, but maybe some day we will
- have some better means.
- If you are looking at this file, you will see the default rules that are
- compiled into the compiler, you can add your own rules in the default set
- there if you get tired of specifying the -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--peep-file option.
-\layout Section
-
-Library Routines
-\emph on
-
-\layout Standard
-
-
-\emph on
-<pending: this is messy and incomplete>
-\emph default
-
-\layout Enumerate
-
-Compiler support routines (_gptrget, _mulint etc)
-\layout Enumerate
-
-Stdclib functions (puts, printf, strcat etc)
-\layout Enumerate
-
-Math functions (sin, pow, sqrt etc)
-\layout Standard
-
-Libraries
-\begin_inset LatexCommand \index{Libraries}
-
-\end_inset
-
- included in SDCC should have a license at least as liberal as the GNU Lesser
- General Public License
-\begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
-
-\end_inset
-
-
-\emph on
-LGPL
-\emph default
-.
-\layout Comment
-
-license statements for the libraries are missing.
- sdcc/device/lib/ser_ir.c
-\layout Comment
-
-or _decdptr f.e.
- come with a GPL (as opposed to LGPL) License - this will not be liberal
- enough for many embedded programmers.
-\layout Standard
-
-If you have ported some library or want to share experience about some code
- which f.e.
- falls into any of these categories Busses (I
-\begin_inset Formula $^{\textrm{2}}$
-\end_inset
-
-C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
- cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
- Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
-\begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
-
-\end_inset
-
-\SpecialChar ~
-would certainly like to hear about it.
- Programmers coding for embedded systems are not especially famous for being
- enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
-e these references are very valuable.
-\layout Section
-
-External Stack
-\begin_inset LatexCommand \label{sub:External-Stack}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{stack}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{External stack}
+push ar2
+\newline
+push ar1
+\layout Standard
-\end_inset
+would result in:
+\layout Verse
+\family typewriter
+pop ar1
+\newline
+; nop
+\newline
+push ar1
\layout Standard
-The external stack (-
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\emph on
+with
+\emph default
+ the restart option the rule will be applied again to the resulting code
+ and then all the pop-push pairs will be eliminated to yield:
+\layout Verse
-\backslash
-/
-\end_inset
--xstack option
-\begin_inset LatexCommand \index{-\/-xstack}
+\family typewriter
+; nop
+\newline
+; nop
+\layout Standard
-\end_inset
+A conditional function can be attached to a rule.
+ Attaching rules are somewhat more involved, let me illustrate this with
+ an example.
+\layout Verse
-) is located at the start of the external ram segment, and is 256 bytes
- in size.
- When -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+replace {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ljmp %5
+\newline
+%2:
+\newline
+} by {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+sjmp %5
+\newline
+%2:
+\newline
+} if labelInRange
\layout Standard
-\backslash
-/
-\end_inset
+The optimizer does a look-up of a function name table defined in function
+
+\emph on
+callFuncByName
+\emph default
+ in the source file SDCCpeeph.c, with the name
+\emph on
+labelInRange
+\emph default
+.
+ If it finds a corresponding entry the function is called.
+ Note there can be no parameters specified for these functions, in this
+ case the use of
+\emph on
+%5
+\emph default
+ is crucial, since the function
+\emph on
+labelInRange
+\emph default
+ expects to find the label in that particular variable (the hash table containin
+g the variable bindings is passed as a parameter).
+ If you want to code more such functions, take a close look at the function
+ labelInRange and the calling mechanism in source file SDCCpeeph.c.
+ Currently implemented are
+\emph on
+labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
+ 24bitMode, portIsDS390, 24bitModeAndPortDS390
+\emph default
+and
+\emph on
+ notVolatile
+\emph default
+.
+\layout Standard
--xstack option is used to compile the program, the parameters and local
- variables of all reentrant functions are allocated in this area.
- This option is provided for programs with large stack space requirements.
- When used with the -
+I know this whole thing is a little kludgey, but maybe some day we will
+ have some better means.
+ If you are looking at this file, you will see the default rules that are
+ compiled into the compiler, you can add your own rules in the default set
+ there if you get tired of specifying the -
\begin_inset ERT
status Collapsed
/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
-
-\end_inset
-
- option, all parameters and local variables are allocated on the external
- stack (note support libraries will need to be recompiled with the same
- options).
-\layout Standard
-
-The compiler outputs the higher order address byte of the external ram segment
- into PORT P2, therefore when using the External Stack option, this port
- MAY NOT be used by the application program.
+-peep-file option.
\layout Section
ANSI-Compliance
\newline
}
\end_deeper
-\layout Itemize
-
-functions declared as pointers
-\begin_inset LatexCommand \index{Pointers}
-
-\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
-Other 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
-\begin_inset LatexCommand \index{sfr}
-
-\end_inset
-
-
-\layout Standard
-
-With the upcome of devices with internal xdata and flash memory devices
- using port P2 as dedicated I/O port is becoming more popular.
- Switching the high byte for pdata
-\begin_inset LatexCommand \index{pdata}
-
-\end_inset
-
- access which was formerly done by port P2 is then achieved by a Special
- Function Register.
- In well-established MCS51 tradition the address of this
-\emph on
-sfr
-\emph default
- is where the chip designers decided to put it.
- 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 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 and access to I/O
- memory.
-\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 Section
-
-Retargetting for other MCUs.
+Retargetting for other Processors
\layout Standard
The issues for retargetting the compiler are far too numerous to be covered
There are other MCU specific considerations in this phase.
Some MCUs have an accumulator; very short-lived operands could be assigned
- to the accumulator instead of general-purpose register.
+ to the accumulator instead of a general-purpose register.
\layout Paragraph*
Code generation
\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
7.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-short i=10; /* dead initialization eliminated */
+short i=10; \SpecialChar ~
+\SpecialChar ~
+/* dead initialization eliminated */
\newline
8.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mul += i * 3; /* this multiplication remains */
+mul += i * 3; \SpecialChar ~
+\SpecialChar ~
+/* this multiplication remains */
\newline
18.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-gint += j * 3;/* this multiplication changed to addition */
+gint += j * 3;\SpecialChar ~
+\SpecialChar ~
+/* this multiplication changed to addition */
\newline
19.\SpecialChar ~
\SpecialChar ~
In addition the allocator also takes into consideration the type and usage
of a temporary, for example itemp6 is a pointer to near space and is used
as to fetch data from (i.e.
- used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
+ used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
Some short lived temporaries are allocated to special registers which have
meaning to the code generator e.g.
iTemp13 is allocated to a pseudo register CC which tells the back end that
projects / fw / sdcc / blobdiff