#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
-\textclass article
+\textclass book
\begin_preamble
+
\usepackage[
pdftitle={SDCC Compiler User Guide},
pdfauthor={SDCC development team},
pdfsubject={installation, user manual},
pdfkeywords={8032, 8051, ansi, c, compiler, CPU, DS390,
- embedded, GPL, manual, mcs51, PIC, small, Z80},
+ embedded, GPL, HC08, manual, mcs51, PIC, Z80},
colorlinks=true,
linkcolor=blue] {hyperref}
+%
+\sloppy
+\tolerance=500
+\emergencystretch=30pt
+%
\date{}
\end_preamble
\language english
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 30mm
-\topmargin 10mm
+\topmargin 20mm
\rightmargin 25mm
-\bottommargin 15mm
+\bottommargin 20mm
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\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
-\layout Comment
+\layout Date
-The strings enclosed in $ are automatically updated by cvs:
-\layout Standard
-\align center
+\size normal
+SDCC 2.4.3
\size footnotesize
-$Date$
-\layout Standard
-\align center
-\size footnotesize
+\newline
+$Date$
+\newline
$Revision$
+\layout Comment
+
+The above strings enclosed in $ are automatically updated by cvs
\layout Standard
\end_inset
-\layout Section
-\pagebreak_top
+\layout Chapter
+
Introduction
-\layout Subsection
+\layout Section
About SDCC
\layout Standard
\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 a Freeware, retargettable, optimizing ANSI-C compiler by
\series bold
Sandeep Dutta
\series default
designed for 8 bit Microprocessors.
The current version targets Intel MCS51 based Microprocessors (8031, 8032,
8051, 8052
-\begin_inset LatexCommand \index{8031, 8032, 8051, 8052 CPU}
+\begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
\end_inset
-, etc), Zilog Z80 based MCUs, and the Dallas DS80C390 variant.
+, etc.), Dallas DS80C390 variants, Motorola HC08 and Zilog Z80 based MCUs.
It can be retargetted for other microprocessors, support for Microchip
PIC, Atmel AVR is under development.
The entire source code for the compiler is distributed under GPL.
\end_inset
.
-\layout Subsection
+\layout Section
Open Source
\layout Standard
You are forbidden to forbid anyone else to use, share and improve what
you give them.
Help stamp out software-hoarding!
-\layout Subsection
+\layout Section
Typographic conventions
\begin_inset LatexCommand \index{Typographic conventions}
Interesting items and new terms are printed in
\emph on
italic.
-\layout Subsection
+\layout Section
Compatibility with previous versions
\layout Standard
\end_inset
-.
+ (see section
+\begin_inset LatexCommand \ref{sub:ANSI-Compliance}
+
+\end_inset
+
+ for ANSI-Compliance).
\newline
\emph on
<pending: more incompatibilities?>
-\layout Subsection
+\layout Section
System Requirements
\layout Standard
For Windows some pre-compiled binary distributions are available for your
convenience.
You should have some experience with command line tools and compiler use.
-\layout Subsection
+\layout Section
Other Resources
\layout Standard
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
is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
-\layout Subsection
+\layout Section
Wishes for the future
\layout Standard
\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
.
\newline
-\layout Section
-\pagebreak_top
+\layout Chapter
+
Installing SDCC
\begin_inset LatexCommand \index{Installation}
.
More detailled instructions follow below.
-\layout Subsection
+\layout Section
Configure Options
\begin_inset LatexCommand \index{Options SDCC configuration}
/
\end_inset
--z80-port Excludes the z80 port
+-disable-z80-port Excludes the z80 port
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
+-disable-hc08-port Excludes the HC08 port
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
-disable-pic-port Excludes the PIC port
\layout List
\labelwidthstring 00.00.0000
STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
At the moment it's not possible to change the default settings (it was
- simply never required.
+ simply never required).
\newline
\newline
\begin_inset Quotes srd
\end_inset
-compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32)
-:
+compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
+):
\layout LyX-Code
./configure -C
-C' turns on caching, which gives a little bit extra speed.
However if options are changed, it can be necessary to delete the config.cache
file.
-\layout Subsection
+\layout Section
Install paths
+\begin_inset LatexCommand \label{sub:Install-paths}
+
+\end_inset
+
+
\begin_inset LatexCommand \index{Install paths}
\end_inset
\begin_inset Tabular
<lyxtabular version="3" rows="5" columns="4">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
Of course this doesn't change the search paths compiled into the binaries.
-\layout Subsection
+\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
+\begin_inset LatexCommand \label{sub:Search-Paths}
+
+\end_inset
+
+
\begin_inset LatexCommand \index{Search path}
\end_inset
\end_inset
-nostdlib disables the last two search paths.
-\layout Subsection
+\layout Section
Building SDCC
\begin_inset LatexCommand \index{Building SDCC}
\end_inset
-\layout Subsubsection
+\layout Subsection
Building SDCC on Linux
\begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
\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
Unpack the file using a command like:
\family sans
\series bold
-"tar -xzf sdcc.src.tar.gz
+"tar -xvzf sdcc.src.tar.gz
\family default
\series default
"
\series default
This copies the binary executables, the include files, the libraries and
the documentation to the install directories.
-\layout Subsubsection
+ Proceed with section
+\begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
+
+\end_inset
+
+.
+\layout Subsection
Building SDCC on OSX 2.x
\layout Standard
\layout LyX-Code
./configure CC=gcc2 CXX=g++2
-\layout Subsubsection
+\layout Subsection
Cross compiling SDCC on Linux for Windows
\layout Standard
With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
See section 'Configure Options'.
-\layout Subsubsection
+\layout Subsection
Building SDCC on Windows
\layout Standard
With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
built on Windows.
They use Unix-sockets, which are not available on Win32.
-\layout Subsubsection
+\layout Subsection
Building SDCC using Cygwin and Mingw32
\layout Standard
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.
-\layout Subsubsection
+ The tabulator spacing
+\begin_inset LatexCommand \index{tabulator spacing (8)}
+
+\end_inset
+
+ used in the project is 8.
+\layout Subsection
Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
\layout Standard
\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.
\backslash
bin_vc to sdcc
\backslash
-bin, and you can compile using sdcc.
-\layout Subsubsection
+bin, and you can compile using SDCC.
+\layout Subsection
Building SDCC Using Borland
\layout Enumerate
\family default
\series default
from the sdcc directory.
-\layout Subsubsection
+\layout Subsection
Windows Install Using a Binary Package
\begin_inset LatexCommand \label{sub:Windows-Install}
Adjust your environment variable PATH to include the location of the bin
directory or start sdcc using the full path.
-\layout Subsection
+\layout Section
Building the Documentation
\layout Standard
-If the necessary tools are installed it is as easy as changing into the
- doc directory and typing
+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.knopper.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}
\end_inset
.
-\layout Subsection
+\layout Section
+
+Reading the Documentation
+\layout Standard
+
+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
+\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:
+
+\layout Itemize
+
+It tries to document SDCC for several processor architectures in one document
+ (commercially these probably would be separate documents/products).
+ This document
+\begin_inset LatexCommand \index{Status of documentation}
+
+\end_inset
+
+ currently matches SDCC for mcs51 and DS390 best and does give too few informati
+on about f.e.
+ Z80, PIC14, PIC16 and HC08.
+\layout Itemize
+
+There are many references pointing away from this documentation.
+ Don't let this distract you.
+ If there f.e.
+ was a reference like
+\begin_inset LatexCommand \url{www.opencores.org}
+
+\end_inset
+
+ together with a statement
+\begin_inset Quotes sld
+\end_inset
+
+some processors which are targetted by SDCC can be implemented in a
+\emph on
+f
+\emph default
+ield
+\emph on
+p
+\emph default
+rogrammable
+\emph on
+g
+\emph default
+ate
+\emph on
+a
+\emph default
+rray
+\begin_inset LatexCommand \index{fpga (field programmable gate array)}
+
+\end_inset
+
+
+\begin_inset Quotes srd
+\end_inset
+
+ we expect you to have a quick look there and come back.
+ If you read this you are on the right track.
+\layout Itemize
+
+Some sections attribute more space to problems, restrictions and warnings
+ than to the solution.
+\layout Itemize
+
+The installation section and the section about the debugger is intimidating.
+\layout Itemize
+
+There are still lots of typos and there are more different writing styles
+ than pictures.
+\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
If it doesn't run, or gives a message about not finding sdcc program, then
you need to check over your installation.
Make sure that the sdcc bin directory is in your executable search path
- defined by the PATH environment setting (see the Trouble-shooting section
- for suggestions).
+ defined by the PATH environment setting (
+\series medium
+see
+\series default
+section
+\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
+
+\end_inset
+
+\SpecialChar ~
+
+\series medium
+Install trouble-shooting for suggestions
+\series default
+).
Make sure that the sdcc program is in the bin folder, if not perhaps something
did not install correctly.
\newline
\begin_inset Quotes srd
\end_inset
-
+.
\newline
\newline
\series medium
(no test.ihx, and the linker generates warnings), then the problem is most
- likely that sdcc cannot find the
+ likely that
+\series default
+SDCC
+\series medium
+ cannot find the
\series default
/
\series medium
\series default
\series medium
-(see the Install trouble-shooting section for suggestions).
+(see
+\series default
+section
+\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
+
+\end_inset
+
+\SpecialChar ~
+
+\series medium
+Install trouble-shooting for suggestions).
\series default
\newline
\newline
\series medium
-The final test is to ensure sdcc can use the
+The final test is to ensure
+\series default
+SDCC
+\series medium
+ can use the
\series default
standard
\series medium
.
This should generate a test.ihx output file, and it should give no warnings
such as not finding the string.h file.
- If it cannot find the string.h file, then the problem is that sdcc cannot
- find the /usr/local/share/sdcc/include directory
+ If it cannot find the string.h file, then the problem is that
+\series default
+SDCC
+\series medium
+ cannot find the /usr/local/share/sdcc/include directory
\series default
\series medium
-(see the Install trouble-shooting section for suggestions).
+(see the
+\series default
+section
+\begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
+
+\end_inset
+
+\SpecialChar ~
+
+\series medium
+Install trouble-shooting section for suggestions).
\series default
Use option
\end_inset
to find exactly where SDCC is looking for the include and lib files.
-\layout Subsection
+\layout Section
Install Trouble-shooting
+\begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
+
+\end_inset
+
+
\begin_inset LatexCommand \index{Install trouble-shooting}
\end_inset
-\layout Subsubsection
+\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
If anything goes wrong, you can review the log files to locate the problem.
Or a relevant part of this can be attached to an email that could be helpful
when requesting help from the mailing list.
-\layout Subsubsection
+\layout Subsection
What the
\begin_inset Quotes sld
to ensure the source package compiles on your system.
It will take a few minutes to run, and will compile a few tests to determine
what compiler features are installed.
-\layout Subsubsection
+\layout Subsection
What the
\begin_inset Quotes sld
\begin_inset Quotes srd
\end_inset
- does.
+ does
\layout Standard
This runs the GNU make tool, which automatically compiles all the source
packages into the final installed binary executables.
-\layout Subsubsection
+\layout Subsection
What the
\begin_inset Quotes sld
This will install the compiler, other executables libraries and include
files into the appropriate directories.
- See section
-\begin_inset Quotes sld
+ See sections
+\begin_inset LatexCommand \ref{sub:Install-paths}
+
\end_inset
-Install and Search PATHS
-\begin_inset Quotes srd
+,\SpecialChar ~
+
+\begin_inset LatexCommand \ref{sub:Search-Paths}
+
\end_inset
-.
+\SpecialChar ~
+about install and search paths.
\newline
On most systems you will need super-user privileges to do this.
-\layout Subsection
+\layout Section
Components of SDCC
\layout Standard
As development for other processors proceeds, this list will expand to include
executables to support processors like AVR, PIC, etc.
-\layout Subsubsection
+\layout Subsection
sdcc - The Compiler
\layout Standard
This is the actual compiler, it in turn uses the c-preprocessor and invokes
the assembler and linkage editor.
-\layout Subsubsection
+\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 Subsubsection
+\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
Baldwin.
John Hartman created the version for 8051, and I (Sandeep) have made some
enhancements and bug fixes for it to work properly with SDCC.
-\layout Subsubsection
+\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
.
It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
XA51 family.
-\layout Subsubsection
+\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}
-Sdcdb is the companion source level debugger.
+\end_inset
+
+.
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 Section
-\pagebreak_top
+
+\layout Chapter
+
Using SDCC
-\layout Subsection
+\layout Section
Compiling
-\layout Subsubsection
+\layout Subsection
Single Source File Projects
\layout Standard
\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
-\begin_inset LatexCommand \index{.asm}
+\begin_inset LatexCommand \index{<file>.asm}
\end_inset
\layout Itemize
sourcefile.lst
-\begin_inset LatexCommand \index{.lst}
+\begin_inset LatexCommand \index{<file>.lst}
\end_inset
\layout Itemize
sourcefile.rst
-\begin_inset LatexCommand \index{.rst}
+\begin_inset LatexCommand \index{<file>.rst}
\end_inset
\layout Itemize
sourcefile.sym
-\begin_inset LatexCommand \index{.sym}
+\begin_inset LatexCommand \index{<file>.sym}
\end_inset
\layout Itemize
sourcefile.rel
-\begin_inset LatexCommand \index{.rel}
+\begin_inset LatexCommand \index{<file>.rel}
+
+\end_inset
+
+ or sourcefile.o
+\begin_inset LatexCommand \index{<file>.o}
\end_inset
\layout Itemize
sourcefile.map
-\begin_inset LatexCommand \index{.map}
+\begin_inset LatexCommand \index{<file>.map}
\end_inset
\layout Itemize
sourcefile.mem
-\begin_inset LatexCommand \index{.mem}
+\begin_inset LatexCommand \index{<file>.mem}
\end_inset
\layout Itemize
sourcefile.ihx
-\begin_inset LatexCommand \index{.ihx}
+\begin_inset LatexCommand \index{<file>.ihx}
\end_inset
\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
\layout Itemize
sourcefile.cdb
-\begin_inset LatexCommand \index{.cdb}
+\begin_inset LatexCommand \index{<file>.cdb}
\end_inset
/
\end_inset
--debug) containing debug information
+-debug) containing debug information.
+ The format is documented in cdbfileformat.pdf.
\layout Itemize
sourcefile.
- (no extension)
-\begin_inset LatexCommand \index{. (no extension)}
+\begin_inset LatexCommand \index{<file> (no extension)}
\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
\layout Itemize
sourcefile.dump*
-\begin_inset LatexCommand \index{.dump*}
+\begin_inset LatexCommand \index{<file>.dump*}
\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
\end_inset
-dumpall) (see section
+\begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
+
+\end_inset
+
+\SpecialChar ~
+ and section
+\begin_inset LatexCommand \ref{sub:The-anatomy-of}
+
+\end_inset
+
+\SpecialChar ~
+
\begin_inset Quotes sld
\end_inset
\end_inset
).
-\layout Subsubsection
+\layout Subsection
Projects with Multiple Source Files
\layout Standard
\family default
\series default
-\begin_inset LatexCommand \index{.rel}
+\begin_inset LatexCommand \index{<file>.rel}
\end_inset
\noun default
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}
+ The linker is invoked from SDCC using a script file with extension .lnk
+\begin_inset LatexCommand \index{<file>.lnk}
\end_inset
.
You can view this file to troubleshoot linking problems such as those arising
from missing libraries.
-\layout Subsubsection
+\layout Subsection
Projects with Additional Libraries
\begin_inset LatexCommand \index{Libraries}
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
in the directory <installdir>/share/lib/small.
\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 Subsubsection
+\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
-
-
-\series bold
--mmcs51
-\begin_inset LatexCommand \index{-mmcs51}
-
-\end_inset
+\newline
+\newline
+\family default
\series default
- Generate code for the Intel MCS51
-\begin_inset LatexCommand \index{MCS51}
-
-\end_inset
+To create a new library file, start by compiling all the required modules.
+ For example:
+\newline
- family of processors.
- This is the default processor target.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+\family sans
\series bold
--mds390
-\begin_inset LatexCommand \index{-mds390}
-
-\end_inset
+sdcc -c _divsint.c
+\layout Standard
-\series default
- Generate code for the Dallas DS80C390
-\begin_inset LatexCommand \index{DS80C390}
+\family sans
+\series bold
+sdcc -c _divuint.c
+\layout Standard
-\end_inset
- processor.
-\layout List
-\labelwidthstring 00.00.0000
+\family sans
+\series bold
+sdcc -c _modsint.c
+\layout Standard
+\family sans
\series bold
--mds400
-\begin_inset LatexCommand \index{-mds400}
+sdcc -c _moduint.c
+\layout Standard
-\end_inset
+\family sans
+\series bold
+sdcc -c _mulint.c
+\newline
-\series default
- Generate code for the Dallas DS80C400
-\begin_inset LatexCommand \index{DS80C400}
+\layout Standard
-\end_inset
+This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
+ and _mulint.rel.
+ The next step is to add the .rel files to the library file:
+\newline
- processor.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+\family sans
\series bold
--mz80
-\begin_inset LatexCommand \index{-mz80}
+sdcclib libint.lib _divsint.rel
+\family default
+
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\series default
- Generate code for the Zilog Z80
-\begin_inset LatexCommand \index{Z80}
+\layout Standard
-\end_inset
- family of processors.
-\layout List
-\labelwidthstring 00.00.0000
+\family sans
+\series bold
+sdcclib libint.lib _divuint.rel
+\layout Standard
+\family sans
\series bold
--mgbz80
-\begin_inset LatexCommand \index{-mgbz80}
+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 GameBoy Z80
-\begin_inset LatexCommand \index{GameBoy Z80}
-\end_inset
+\newline
- processor.
-\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
--mavr
-\begin_inset LatexCommand \index{-mavr}
+sdcclib -s libint.lib
+\family default
+
+\begin_inset LatexCommand \index{sdcclib}
\end_inset
-\series default
- Generate code for the Atmel AVR
-\begin_inset LatexCommand \index{AVR}
+\newline
-\end_inset
+\family typewriter
+\series default
+_divsint.rel:
+\layout Standard
- processor (In development, not complete).
- AVR users should probably have a look at avr-gcc
-\begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
-\end_inset
+\family typewriter
+__divsint_a_1_1
+\layout Standard
-.
-\layout Comment
-I think it is fair to direct users there for now.
- Open source is also about avoiding unnecessary work .
- But I didn't find the 'official' link.
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__divsint_PARM_2
+\layout Standard
-\series bold
--mpic14
-\begin_inset LatexCommand \index{-mpic14}
+\family typewriter
+__divsint
+\newline
+_divuint.rel:
+\layout Standard
-\end_inset
+\family typewriter
+__divuint_a_1_1
+\layout Standard
-\series default
- Generate code for the Microchip PIC 14
-\begin_inset LatexCommand \index{PIC14}
-\end_inset
+\family typewriter
+__divuint_PARM_2
+\layout Standard
--bit processors (p16f84 and variants).
-\layout Comment
-p16f627 p16f628 p16f84 p16f873 p16f877?
-\layout List
-\labelwidthstring 00.00.0000
+\family typewriter
+__divuint_reste_1_1
+\layout Standard
-\series bold
--mpic16
-\begin_inset LatexCommand \index{-mpic16}
+\family typewriter
+__divuint_count_1_1
+\layout Standard
-\end_inset
+\family typewriter
+__divuint
+\newline
+_modsint.rel:
+\layout Standard
-\series default
- Generate code for the Microchip PIC 16
-\begin_inset LatexCommand \index{PIC16}
+
+\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
--bit processors (p18f452 and variants).
+ processor.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mhc08
+\begin_inset LatexCommand \index{-mhc08}
+
+\end_inset
+
+
+\series default
+ Generate code for the Motorola HC08
+\begin_inset LatexCommand \index{HC08}
+
+\end_inset
+
+ family of processors (added Oct 2003).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mz80
+\begin_inset LatexCommand \index{-mz80}
+
+\end_inset
+
+
+\series default
+ Generate code for the Zilog Z80
+\begin_inset LatexCommand \index{Z80}
+
+\end_inset
+
+ family of processors.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mgbz80
+\begin_inset LatexCommand \index{-mgbz80}
+
+\end_inset
+
+
+\series default
+ Generate code for the GameBoy Z80
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
+
+\end_inset
+
+ processor (Not actively maintained).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mavr
+\begin_inset LatexCommand \index{-mavr}
+
+\end_inset
+
+
+\series default
+ Generate code for the Atmel AVR
+\begin_inset LatexCommand \index{AVR}
+
+\end_inset
+
+ processor (In development, not complete).
+ AVR users should probably have a look at avr-gcc
+\begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
+
+\end_inset
+
+ or winavr
+\begin_inset LatexCommand \url{http://winavr.sourceforge.net}
+
+\end_inset
+
+.
+\layout Comment
+
+I think it is fair to direct users there for now.
+ Open source is also about avoiding unnecessary work .
+ But I didn't find the 'official' link.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mpic14
+\begin_inset LatexCommand \index{-mpic14}
+
+\end_inset
+
+
+\series default
+ Generate code for the Microchip PIC 14
+\begin_inset LatexCommand \index{PIC14}
+
+\end_inset
+
+-bit processors (p16f84 and variants.
+ In development, not complete).
+\layout Comment
+
+p16f627 p16f628 p16f84 p16f873 p16f877?
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-mpic16
+\begin_inset LatexCommand \index{-mpic16}
+
+\end_inset
+
+
+\series default
+ Generate code for the Microchip PIC 16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+-bit processors (p18f452 and variants.
+ In development, not complete).
\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).
-\layout Subsubsection
+ processor (Not maintained, not complete).
+\layout Subsection
Preprocessor Options
\begin_inset LatexCommand \index{Options preprocessor}
\end_inset
+\begin_inset LatexCommand \index{sdcpp (preprocessor)}
+
+\end_inset
+
+
\layout List
\labelwidthstring 00.00.0000
\bar default
Like `-dD' except that the macro arguments and contents are omitted.
Only `#define name' is included in the output.
-\layout Subsubsection
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-Wp\SpecialChar ~
+preprocessorOption[,preprocessorOption]
+\series default
+
+\begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
+
+\end_inset
+
+...
+ 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
\begin_inset LatexCommand \index{Options linker}
\series bold
-lib-path
-\begin_inset LatexCommand \index{-\/-lib-path}
+\begin_inset LatexCommand \index{-\/-lib-path <path>}
\end_inset
\end_inset
-\bar under
-
\series default
-\bar default
+\SpecialChar ~
<absolute path to additional libraries> This option is passed to the linkage
editor's additional libraries
\begin_inset LatexCommand \index{Libraries}
-xram-loc
\series default
-\begin_inset LatexCommand \index{-\/-xram-loc}
+\begin_inset LatexCommand \index{-\/-xram-loc <Value>}
\end_inset
+\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
-code-loc
\series default
-\begin_inset LatexCommand \index{-\/-code-loc}
+\begin_inset LatexCommand \index{-\/-code-loc <Value>}
\end_inset
+\SpecialChar ~
<Value> The start location of the code
\begin_inset LatexCommand \index{code}
-stack-loc
\series default
-\begin_inset LatexCommand \index{-\/-stack-loc}
+\begin_inset LatexCommand \index{-\/-stack-loc <Value>}
\end_inset
+\SpecialChar ~
<Value> By default the stack
\begin_inset LatexCommand \index{stack}
-data-loc
\series default
-\begin_inset LatexCommand \index{-\/-data-loc}
+\begin_inset LatexCommand \index{-\/-data-loc <Value>}
\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
-idata-loc
\series default
-\begin_inset LatexCommand \index{-\/-idata-loc}
+\begin_inset LatexCommand \index{-\/-idata-loc <Value>}
\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
-, default value is 0x80.
+ of the 8051, default value is 0x80.
The value entered can be in Hexadecimal or Decimal format, eg.
-
\begin_inset ERT
\labelwidthstring 00.00.0000
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-bit-loc
+\series default
+\SpecialChar ~
+<Value> The start location of the bit
+\begin_inset LatexCommand \index{bit}
+
+\end_inset
+
+ addressable internal ram of the 8051.
+ This is
+\emph on
+not
+\emph default
+ implemented yet.
+ Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
+-bBSEG=<Value>.
+\layout List
+\labelwidthstring 00.00.0000
+
+
\series bold
-
\begin_inset ERT
\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
.
-\layout Subsubsection
+ The format itself is documented in the documentation of srecord.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-Wl\SpecialChar ~
+linkOption[,linkOption]
+\series default
+
+\begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
+
+\end_inset
+
+...
+ Pass the linkOption to the linker.
+ See file sdcc/as/doc/asxhtm.html for more on linker options.
+\layout Subsection
MCS51 Options
\begin_inset LatexCommand \index{Options MCS51}
\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 should be compiled
+ If this option is used all source files in the project have to be compiled
with this option.
\layout List
\labelwidthstring 00.00.0000
\series default
Uses a pseudo stack in the first 256 bytes in the external ram for allocating
variables and passing parameters.
- See section on external stack for more details.
+ See section
+\begin_inset LatexCommand \ref{sub:External-Stack}
+
+\end_inset
+
+\SpecialChar ~
+ External Stack for more details.
\layout List
\labelwidthstring 00.00.0000
-iram-size
\series default
+\SpecialChar ~
<Value>
-\begin_inset LatexCommand \index{-\/-iram-size<Value>}
+\begin_inset LatexCommand \index{-\/-iram-size <Value>}
\end_inset
-xram-size
\series default
+\SpecialChar ~
<Value>
-\begin_inset LatexCommand \index{-\/-xram-size<Value>}
+\begin_inset LatexCommand \index{-\/-xram-size <Value>}
\end_inset
-code-size
\series default
+\SpecialChar ~
<Value>
-\begin_inset LatexCommand \index{-\/-data-loc}
+\begin_inset LatexCommand \index{-\/-code-size <Value>}
\end_inset
Causes the linker to check if the code memory usage is within limits of
the given value.
-\layout Subsubsection
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-size
+\series default
+\SpecialChar ~
+<Value>
+\begin_inset LatexCommand \index{-\/-stack-size <Value>}
+
+\end_inset
+
+ Causes the linker to check if there is at minimum <Value> bytes for stack.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pack-iram
+\series default
+\SpecialChar ~
+
+\begin_inset LatexCommand \index{-\/-pack-iram}
+
+\end_inset
+
+ Causes the linker use unused register banks for data variables or stack.
+\layout Subsection
-DS390 Options
+DS390 / DS400 Options
\begin_inset LatexCommand \index{Options DS390}
\end_inset
\labelwidthstring 00.00.0000
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-protect-sp-update
+\begin_inset LatexCommand \index{-\/-protect-sp-update}
+
+\end_inset
+
+
+\series default
+ disable interrupts during ESP:SP updates.
+\layout List
+\labelwidthstring 00.00.0000
+
+
\series bold
-
\begin_inset ERT
-model-flat24 option
\emph default
).
-\layout Subsubsection
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-probe
+\begin_inset LatexCommand \index{-\/-stack-probe}
+
+\end_inset
+
+
+\series default
+ insert call to function __stack_probe at each function prologue.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-tini-libid
+\begin_inset LatexCommand \index{-\/-tini-libid}
+
+\end_inset
+
+
+\series default
+ <nnnn> LibraryID used in -mTININative.
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-use-accelerator
+\begin_inset LatexCommand \index{-\/-use-accelerator}
+
+\end_inset
+
+
+\series default
+ generate code for DS390 Arithmetic Accelerator.
+
+\layout Subsection
Z80 Options
\begin_inset LatexCommand \index{Options Z80}
When linking, skip the standard crt0.o object file.
You must provide your own crt0.o for your system when linking.
-\layout Subsubsection
+\layout Subsection
Optimization Options
\begin_inset LatexCommand \index{Options optimization}
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
\end_inset
are implemented using jump-tables.
- See section Switch Statements for more details.
+ See section
+\begin_inset LatexCommand \ref{sub:'switch'-Statements}
+
+\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 Subsubsection
-
-Other Options
-\begin_inset LatexCommand \index{Options other}
-
-\end_inset
-
-
\layout List
\labelwidthstring 00.00.0000
\series bold
--c\SpecialChar ~
-
\begin_inset ERT
status Collapsed
/
\end_inset
--compile-only
-\begin_inset LatexCommand \index{-\/-compile-only}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{-c -\/-compile-only}
+-nooverlay
+\begin_inset LatexCommand \index{-\/-nooverlay}
\end_inset
\series default
- will compile and assemble the source, but will not call the linkage editor.
+ 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
-
-\series default
-
\begin_inset ERT
status Collapsed
/
\end_inset
-
-\series bold
--c1mode
-\begin_inset LatexCommand \index{-\/-c1mode}
+-no-peep
+\begin_inset LatexCommand \index{-\/-no-peep}
\end_inset
\series default
- reads the preprocessed source from standard input and compiles it.
- The file name for the assembler output must be specified using the -o option.
+ Disable peep-hole optimization.
\layout List
\labelwidthstring 00.00.0000
\series bold
--E
+-
+\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 Subsection
+
+Other Options
+\begin_inset LatexCommand \index{Options other}
+
+\end_inset
+
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-c\SpecialChar ~
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-compile-only
+\begin_inset LatexCommand \index{-\/-compile-only}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{-c -\/-compile-only}
+
+\end_inset
+
+
+\series default
+ will compile and assemble the source, but will not call the linkage editor.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\series default
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+
+\series bold
+-c1mode
+\begin_inset LatexCommand \index{-\/-c1mode}
+
+\end_inset
+
+
+\series default
+ reads the preprocessed source from standard input and compiles it.
+ The file name for the assembler output must be specified using the -o option.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-E
\begin_inset LatexCommand \index{-E}
\end_inset
\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.
-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 bold
-
\begin_inset ERT
-status Collapsed
+status Open
\layout Standard
\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
\labelwidthstring 00.00.0000
-\series bold
--Wa_asmOption[,asmOption]
-\series default
-
-\begin_inset LatexCommand \index{-Wa\_asmOption[,asmOption]}
-
-\end_inset
-
-...
- Pass the asmOption to the assembler.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--Wl_linkOption[,linkOption]
-\series default
-
-\begin_inset LatexCommand \index{-Wl\_linkOption[,linkOption]}
-
-\end_inset
-
-...
- Pass the linkOption to the linker.
-\layout List
-\labelwidthstring 00.00.0000
-
-
\series bold
-
\begin_inset ERT
\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}
+-nostdincl
+\begin_inset LatexCommand \index{-\/-nostdincl}
\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 option 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
+-nostdlib
+\begin_inset LatexCommand \index{-\/-nostdlib}
-\begin_inset LatexCommand \index{-\/-peep-file}
+\end_inset
+
+
+\series default
+ This will prevent the compiler from passing on the default library
+\begin_inset LatexCommand \index{Libraries}
\end_inset
-<filename> This option can be used to use additional rules to be used by
- the peep hole optimizer.
- See section 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
+-V
+\begin_inset LatexCommand \index{-V}
+
+\end_inset
+
+
+\series default
+ Shows the actual commands the compiler is executing.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--peep-asm
-\begin_inset LatexCommand \index{-\/-peep-asm}
+-no-c-code-in-asm
+\begin_inset LatexCommand \index{-\/-no-c-code-in-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.
+ 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
--nostdincl
-\begin_inset LatexCommand \index{-\/-nostdincl}
+-no-peep-comments
+\begin_inset LatexCommand \index{-\/-no-peep-comments}
\end_inset
\series default
- This will prevent the compiler from passing on the default include path
- to the preprocessor.
+ Will not include peep-hole comments in the generated files.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--nostdlib
-\begin_inset LatexCommand \index{-\/-nostdlib}
+-i-code-in-asm
+\begin_inset LatexCommand \index{-\/-i-code-in-asm}
\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.
+ 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
--verbose
-\begin_inset LatexCommand \index{-\/-verbose}
+-less-pedantic
+\begin_inset LatexCommand \index{-\/-less-pedantic}
\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}
-
-\end_inset
-
-
-\series default
- Shows the actual commands the compiler is executing.
-\layout List
-\labelwidthstring 00.00.0000
+ Disable some of the more pedantic warnings
+\begin_inset LatexCommand \index{Warnings}
-
-\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
\end_inset
--no-c-code-in-asm
-\begin_inset LatexCommand \index{-\/-no-c-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
- 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
--i-code-in-asm
-\begin_inset LatexCommand \index{-\/-i-code-in-asm}
+-print-search-dirs
+\begin_inset LatexCommand \index{-\/-print-search-dirs}
\end_inset
\series default
- Include i-codes in the asm file.
- Sounds like noise but is most helpful for debugging the compiler itself.
+ Display the directories in the compiler's search path
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--less-pedantic
-\begin_inset LatexCommand \index{-\/-less-pedantic}
+-vc
+\begin_inset LatexCommand \index{-\/-vc}
\end_inset
\series default
- Disable some of the more pedantic warnings (jwk burps: please be more specific
- here, please!)
+ Display errors and warnings using MSVC style, so you can use SDCC with
+ visual studio.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--print-search-dirs
-\begin_inset LatexCommand \index{-\/-print-search-dirs}
+-use-stdout
+\begin_inset LatexCommand \index{-\/-use-stdout}
\end_inset
\series default
- Display the directories in the compiler's search path
+ Send errors and warnings to stdout instead of stderr.
\layout List
\labelwidthstring 00.00.0000
\series bold
--
-\begin_inset ERT
-status Collapsed
+-Wa\SpecialChar ~
+asmOption[,asmOption]
+\series default
-\layout Standard
+\begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
-\backslash
-/
\end_inset
--vc
-\begin_inset LatexCommand \index{-\/-vc}
+...
+ Pass the asmOption to the assembler
+\begin_inset LatexCommand \index{Options assembler}
\end_inset
-\series default
- Display errors and warnings using MSVC style, so you can use SDCC with
- visual studio.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+\begin_inset LatexCommand \index{Assembler options}
-\backslash
-/
\end_inset
--use-stdout
-\begin_inset LatexCommand \index{-\/-use-stdout}
+.
+ See file sdcc/as/doc/asxhtm.html for assembler options.
+\layout Subsection
-\end_inset
+Intermediate Dump Options
+\begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
+\end_inset
-\series default
- Send errors and warnings to stdout instead of stderr.
-\layout Subsubsection
-Intermediate Dump Options
\begin_inset LatexCommand \index{Options intermediate dump}
\end_inset
) 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
\size default
\bar default
Will cause all the above mentioned dumps to be created.
-\layout Subsubsection
+\layout Subsection
Redirecting output on Windows Shells
\layout Standard
\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
\series bold
\emph default
-model-large -c $(InputPath)
-\layout Subsection
+\layout Section
Environment variables
\begin_inset LatexCommand \index{Environment variables}
\series default
- Path, see
+ Path, see section
+\begin_inset LatexCommand \ref{sub:Install-paths}
+
+\end_inset
+
+\SpecialChar ~
+
\begin_inset Quotes sld
\end_inset
-2.3 Install and search paths
+ Install Paths
\begin_inset Quotes srd
\end_inset
\series default
- Path, see
+ Path, see section
+\begin_inset LatexCommand \ref{sub:Search-Paths}
+
+\end_inset
+
+\SpecialChar ~
+
\begin_inset Quotes sld
\end_inset
-2.3 Install and search paths
+Search Paths
\begin_inset Quotes srd
\end_inset
\series default
- Path, see
+ Path, see section
+\begin_inset LatexCommand \ref{sub:Search-Paths}
+
+\end_inset
+
+\SpecialChar ~
+
\begin_inset Quotes sld
\end_inset
-2.3 Install and search paths
+Search Paths
\begin_inset Quotes srd
\end_inset
-.
+..
\layout Standard
There are some more environment variables recognized by SDCC, but these
are solely used for debugging purposes.
They can change or disappear very quickly, and will never be documented.
+\layout Section
+
+Storage Class Language Extensions
\layout Subsection
MCS51/DS390 Storage Class
\layout Standard
In addition to the ANSI storage classes SDCC allows the following MCS51
- specific storage classes.
+ specific storage classes:
\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 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
\series bold
default
\series default
- storage class for Large Memory model, e.g.:
+ storage class for the Large Memory model, e.g.:
\layout Verse
\layout Subsubsection
idata
-\begin_inset LatexCommand \index{idata}
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
\end_inset
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
-@r0,#0x01
+@r0,#0x01
+\layout Standard
+
+Please note, the first 128 byte of idata physically access the same RAM
+ as the data memory.
+ The original 8051 had 128 byte idata memory, nowadays most devices have
+ 256 byte idata memory.
+ The stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ is located in idata memory.
\layout Subsubsection
pdata
-\begin_inset LatexCommand \index{pdata}
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
\end_inset
addressing modes of a 8051.
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).
+ 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
+
+).
\layout Verse
\SpecialChar ~
\SpecialChar ~
movc a,@a+dptr
+\layout Standard
+
+
+\family typewriter
+char
+\family default
+ indexed arrays of characters in code memory can be accessed efficiently:
+\layout Verse
+
+
+\family typewriter
+code char test_array[] = {'c','h','e','a','p'};
+\layout Standard
+
+Read access to this array using an 8-bit unsigned index generates the assembly
+ code:
+\layout Verse
+
+
+\family typewriter
+E5*00\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov a,_index
+\layout Verse
+
+
+\family typewriter
+90s00r41\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov dptr,#_test_array
+\layout Verse
+
+
+\family typewriter
+93\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+movc a,@a+dptr
\layout Subsubsection
bit
\SpecialChar ~
setb\SpecialChar ~
_test_bit
+\layout Standard
+
+The bit addressable memory consists of 128 bits which are located from 0x20
+ to 0x2f in data memory.
+
+\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
+
+\layout Standard
+
+Not really meant as examples, but nevertheless showing what bitfields are
+ about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
+\end_inset
+
+.
+ In accordance with ISO/IEC 9899 bits and bitfields without an explicit
+ signed modifier are implemented as unsigned.
\layout Subsubsection
sfr
sfr / sbit
\emph default
signifies both a data-type and storage class, they are used to describe
- the special function registers and special bit variables of a 8051, eg:
+ the
+\emph on
+s
+\emph default
+pecial
+\emph on
+f
+\emph default
+unction
+\emph on
+r
+\emph default
+egisters and
+\emph on
+s
+\emph default
+pecial
+\emph on
+bit
+\emph default
+ variables of a 8051, eg:
\layout Verse
\end_inset
) */
+\layout Standard
+
+Special function registers which are located on an address dividable by
+ 8 are bit-addressable, an
+\emph on
+ sbit
+\emph default
+ addresses a specific bit within these 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
-Absolute Addressing
-\begin_inset LatexCommand \index{Absolute addressing}
+Notes on MCS51 memory
+\begin_inset LatexCommand \index{MCS51 memory}
\end_inset
-
+ layout
\layout Standard
-Data items can be assigned an absolute address with the
-\emph on
-at
-\begin_inset LatexCommand \index{at}
+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
- <address>
+ variables and,
+\newline
+- Bytes 30-7F - 80 bytes for general purpose use.
+\newline
+
+\layout Standard
+
+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
- keyword, in addition to a storage class, e.g.:
-\layout Verse
+\begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
-\family typewriter
+\end_inset
+
+).
+ Furthermore, some chips may have some built in external memory (
+\emph on
xdata
-\begin_inset LatexCommand \index{xdata}
+\emph default
+
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
\end_inset
- at
-\begin_inset LatexCommand \index{at}
+) 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)}
\end_inset
- 0x7ffe unsigned int chksum;
+).
+ 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
+
+\SpecialChar ~
+Startup-Code).
\layout Standard
-In the above example the variable chksum will located at 0x7ffe and 0x7fff
- of the external ram.
- The compiler does not actually reserve any space for variables declared
- in this way (they are implemented with an equate in the assembler).
- Thus it is left to the programmer to make sure there are no overlaps with
- other variables that are declared without the absolute address.
- The assembler listing file (.lst
-\begin_inset LatexCommand \index{.lst}
+Normally SDCC will only use the first bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
\end_inset
-) and the linker output files (.rst
-\begin_inset LatexCommand \index{.rst}
+ 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
-) and (.map
-\begin_inset LatexCommand \index{.map}
+ 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
-) are good places to look for such overlaps.
+ 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
+
\layout Standard
-In case of memory mapped I/O devices the keyword
+\backslash
+/
+\end_inset
+
+-data-loc
+\begin_inset LatexCommand \index{-\/-data-loc<Value>}
+
+\end_inset
+
+ to specify the start address of the
\emph on
-volatile
+data
\emph default
- should be used to tell the compiler that accesses might not be optimized
- away:
-\layout Verse
+ and -
+\begin_inset ERT
+status Collapsed
+\layout Standard
-\family typewriter
-volatile
-\begin_inset LatexCommand \index{volatile}
+\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 data
+ variables.
+ Option -
+\begin_inset ERT
+status Collapsed
+\layout Standard
+
+\backslash
+/
\end_inset
- xdata
-\begin_inset LatexCommand \index{xdata}
+-stack-loc
+\begin_inset LatexCommand \index{-\/-stack-loc<Value>}
\end_inset
- at
-\begin_inset LatexCommand \index{at}
+ 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
- 0x8000 unsigned char PORTA_8255;
+-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
-Absolute address can be specified for variables in all storage classes,
- e.g.:
-\layout Verse
+\backslash
+/
+\end_inset
+-xram-size
+\begin_inset LatexCommand \index{-\/-data-loc}
-\family typewriter
-bit
-\begin_inset LatexCommand \index{bit}
+\end_inset
+
+ to specify its size.
+ Same goes for the code memory, using -
+\begin_inset ERT
+status Collapsed
+\layout Standard
+
+\backslash
+/
\end_inset
- at
-\begin_inset LatexCommand \index{at}
+-code-loc
+\begin_inset LatexCommand \index{-\/-data-loc}
\end_inset
- 0x02 bvar;
+ and -
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-The above example will allocate the variable at offset 0x02 in the bit-addressab
-le space.
- There is no real advantage to assigning absolute addresses to variables
- in this manner, unless you want strict control over all the variables allocated.
- One possible use would be to write hardware portable code.
- For example, if you have a routine that uses one or more of the microcontroller
- I/O pins, and such pins are different for two different hardwares, you
- can declare the I/O pins in your routine using:
+\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
-extern volatile bit SDI;
-\newline
-extern volatile bit SCLK;
-\newline
-extern volatile bit CPOL;
-\newline
-
-\newline
-void DS1306_put(unsigned char value)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
+sfr at 0x78 IoPort;\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-unsigned char mask=0x80;
-\newline
+/* define a var in I/O space at 78h called IoPort */
+
+\layout Standard
-\newline
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
+
+
+\family typewriter
+3E 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-while(mask)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SDI=(value & mask)?1:0;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SCLK=!CPOL;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SCLK=CPOL;
+\SpecialChar ~
+ld a,#0x01
\newline
+D3 78\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mask/=2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-}
-\newline
-}
+out (_IoPort),a
+\layout Subsubsection
+
+banked sfr
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+ (in/out to 16-bit addresses)
\layout Standard
-Then, someplace in the code for the first hardware you would use
+The keyword
+\emph on
+banked
+\emph default
+ is used to support 16 bit addresses in I/O memory e.g.:
\layout Verse
\family typewriter
-bit at 0x80 SDI;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* I/O port 0, bit 0 */
-\newline
-bit at 0x81 SCLK;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* I/O port 0, bit 1 */
-\newline
-bit CPOL;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* This is a variable, let the linker allocate this one */
+sfr banked at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x123 IoPort;
\layout Standard
-Similarly, for the second hardware you would use
+Writing 0x01 to this variable generates the assembly code:
\layout Verse
\family typewriter
-bit at 0x83 SDI;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* I/O port 0, bit 3 */
-\newline
-bit at 0x91 SCLK;\SpecialChar ~
+01 23 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* I/O port 1, bit 1 */
+ld bc,#_IoPort
\newline
-bit CPOL;\SpecialChar ~
+3E 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ld a,#0x01
+\newline
+ED 79\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* This is a variable, let the linker allocate this one */
-\layout Standard
+out (c),a
+\layout Subsubsection
-and you can use the same hardware dependent routine without changes, as
- for example in a library.
- This is somehow similar to sbit, but only one absolute address has to be
- specified in the whole project.
-\layout Subsection
+sfr
+\begin_inset LatexCommand \index{sfr}
-Parameters
-\begin_inset LatexCommand \index{Parameters}
+\end_inset
+
+ (in0/out0 to 8 bit addresses on Z180
+\begin_inset LatexCommand \index{Z180}
\end_inset
- & Local Variables
-\begin_inset LatexCommand \index{Local variable}
+/HD64180
+\begin_inset LatexCommand \index{HD64180}
\end_inset
+)
+\layout Standard
+
+The compiler option -
+\begin_inset ERT
+status Collapsed
\layout Standard
-Automatic (local) variables and parameters to functions can either be placed
- on the stack or in data-space.
- The default action of the compiler is to place these variables in the internal
- RAM (for small model) or external RAM (for large model).
- This in fact makes them
-\emph on
-static
-\begin_inset LatexCommand \index{static}
+\backslash
+/
+\end_inset
+
+-portmode=180 (80) and a compiler #pragma\SpecialChar ~
+portmode
+\begin_inset LatexCommand \index{\#pragma portmode}
\end_inset
+=z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
+ns
+\family typewriter
+in0/out0
+\family default
+ instead of
+\family typewriter
+in/out
+\family default
+.
+ If you include the file z180.h this will be set automatically.
+\layout Subsection
-\emph default
- so by default functions are non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+HC08 Storage Class
+\begin_inset LatexCommand \index{Storage class}
\end_inset
-.
-\newline
+ Language Extensions
+\layout Subsubsection
-\newline
-They can be placed on the stack
-\begin_inset LatexCommand \index{stack}
+data
+\begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
\end_inset
- either by using the
-\emph on
- -
-\begin_inset ERT
-status Collapsed
\layout Standard
-\backslash
-/
+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
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\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
-\emph default
- option or by using the
+\layout Standard
+
+Data items can be assigned an absolute address with the
\emph on
-reentrant
-\begin_inset LatexCommand \index{reentrant}
+at
+\begin_inset LatexCommand \index{at}
\end_inset
-
+ <address>
\emph default
- keyword in the function declaration, e.g.:
+ keyword, in addition to a storage class, e.g.:
\layout Verse
\family typewriter
-unsigned char foo(char i) reentrant
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
+xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x7ffe unsigned int chksum;
\layout Standard
-Since stack space on 8051 is limited, the
+In the above example the variable chksum will located at 0x7ffe and 0x7fff
+ of the external ram.
+ The compiler does
\emph on
-reentrant
+not
\emph default
-keyword or the
-\emph on
- -
-\begin_inset ERT
-status Collapsed
+ reserve any space for variables declared in this way (they are implemented
+ with an equate in the assembler).
+ Thus it is left to the programmer to make sure there are no overlaps with
+ other variables that are declared without the absolute address.
+ The assembler listing file (.lst
+\begin_inset LatexCommand \index{<file>.lst}
-\layout Standard
+\end_inset
+
+) and the linker output files (.rst
+\begin_inset LatexCommand \index{<file>.rst}
-\backslash
-/
\end_inset
--stack-auto
+) and (.map
+\begin_inset LatexCommand \index{<file>.map}
+
+\end_inset
+
+) are good places to look for such overlaps.
+ Variables with an absolute address are
+\emph on
+not
\emph default
- option should be used sparingly.
- Note that the reentrant keyword just means that the parameters & local
- variables will be allocated to the stack, it
+ initialized
+\begin_inset LatexCommand \index{Variable initialization}
+
+\end_inset
+
+.
+\layout Standard
+
+In case of memory mapped I/O devices the keyword
\emph on
-does not
+volatile
\emph default
- mean that the function is register bank independent.
-\newline
+ have to be used to tell the compiler that accesses might not be optimized
+ away:
+\layout Verse
-\newline
-Local variables can be assigned storage classes and absolute
-\begin_inset LatexCommand \index{Absolute addressing}
+
+\family typewriter
+volatile
+\begin_inset LatexCommand \index{volatile}
\end_inset
- addresses, e.g.:
-\layout Verse
+ xdata
+\begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
+
+\end_inset
+
+ at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+ 0x8000 unsigned char PORTA_8255;
+\layout Standard
+For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
+r) array
\family typewriter
-unsigned char foo()
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-xdata unsigned char i;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-bit bvar;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-data at 0x31 unsigned char j;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
-\layout Standard
-
-In the above example the variable
-\emph on
-i
-\emph default
- will be allocated in the external ram,
-\emph on
-bvar
-\emph default
- in bit addressable space and
-\emph on
- j
-\emph default
- in internal ram.
- When compiled with
-\emph on
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--stack-auto
-\emph default
- or when a function is declared as
-\emph on
-reentrant
-\emph default
- this should only be done for static variables.
-\layout Standard
-
-Parameters however are not allowed any storage class, (storage classes for
- parameters will be ignored), their allocation is governed by the memory
- model in use, and the reentrancy options.
-\layout Subsection
-
-Overlaying
-\begin_inset LatexCommand \label{sub:Overlaying}
-
-\end_inset
-
+\size footnotesize
-\begin_inset LatexCommand \index{Overlaying}
+\begin_inset LatexCommand \index{Aligned array}
\end_inset
-\layout Standard
-
-For non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+\family default
+\size default
+ starts at a block (256 byte) boundary
+\begin_inset LatexCommand \index{block boundary}
\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
-\emph on
-no other function calls and the function is non-reentrant and the memory
- model
-\begin_inset LatexCommand \index{Memory model}
+ (section
+\begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
\end_inset
- is small.
-
-\emph default
- If an explicit storage class
-\begin_inset LatexCommand \index{Storage class}
-
-\end_inset
+ has an example).
+\newline
+Absolute addresses can be specified for variables in all storage classes,
+ e.g.:
+\layout Verse
- is specified for a local variable, it will NOT be overlayed.
-\layout Standard
-Note that the compiler (not the linkage editor) makes the decision for overlayin
-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}
+\family typewriter
+bit
+\begin_inset LatexCommand \index{bit}
\end_inset
- if they are not reentrant.
-\layout Standard
-
-Also note that the compiler does not do any processing of inline
-\begin_inset LatexCommand \index{inline}
+ at
+\begin_inset LatexCommand \index{at}
\end_inset
- assembler code, so the compiler might incorrectly assign local variables
- and parameters 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.
+ 0x02 bvar;
\layout Standard
-Parameters and Local variables of functions that contain 16 or 32 bit multiplica
-tion
-\begin_inset LatexCommand \index{Multiplication}
-
-\end_inset
-
- or division
-\begin_inset LatexCommand \index{Division}
-
-\end_inset
-
- will NOT be overlayed since these are implemented using external functions,
- e.g.:
+The above example will allocate the variable at offset 0x02 in the bit-addressab
+le space.
+ There is no real advantage to assigning absolute addresses to variables
+ in this manner, unless you want strict control over all the variables allocated.
+ One possible use would be to write hardware portable code.
+ For example, if you have a routine that uses one or more of the microcontroller
+ I/O pins, and such pins are different for two different hardwares, you
+ can declare the I/O pins in your routine using:
\layout Verse
\family typewriter
-#pragma SAVE
+extern volatile bit MOSI;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master out, slave in */
+\newline
+extern volatile bit MISO;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master in, slave out */
+\newline
+extern volatile bit MCLK;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* master clock */
\newline
-#pragma NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
-
-\end_inset
-
\newline
-void set_error(unsigned char errcd)
+/* 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 ~
-P3 = errcd;
+unsigned char i=8;
\newline
-}
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+do {
\newline
-#pragma RESTORE
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+MOSI = out_byte & 0x80;
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out_byte <<= 1;
\newline
-void some_isr () interrupt
-\begin_inset LatexCommand \index{interrupt}
-
-\end_inset
-
- 2
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+MCLK = 1;
\newline
-{
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* _asm nop _endasm; */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* for slow peripherals */
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+if(MISO)
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-set_error(10);
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out_byte += 1;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+MCLK = 0;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+} while(--i);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return out_byte;
\newline
}
\layout Standard
-In the above example the parameter
-\emph on
-errcd
-\emph default
- for the function
-\emph on
-set_error
-\emph default
- would be assigned to the overlayable segment if the #pragma\SpecialChar ~
-NOOVERLAY was
- not present, this could cause unpredictable runtime behavior when called
- from an ISR.
- The #pragma\SpecialChar ~
-NOOVERLAY ensures that the parameters and local variables for
- the function are NOT overlayed.
-\layout Subsection
-
-Interrupt Service Routines
-\layout Standard
-
-SDCC allows interrupt service routines to be coded in C, with some extended
- keywords.
+Then, someplace in the code for the first hardware you would use
\layout Verse
\family typewriter
-void timer_isr (void) interrupt 1 using 1
-\newline
-{
-\newline
+bit at 0x80 MOSI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-...
-
+/* I/O port 0, bit 0 */
\newline
-}
+bit at 0x81 MISO;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* I/O port 0, bit 1 */
+\newline
+bit at 0x82 MCLK;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* I/O port 0, bit 2 */
\layout Standard
-The optional number following the
-\emph on
-interrupt
-\begin_inset LatexCommand \index{interrupt}
+Similarly, for the second hardware you would use
+\layout Verse
+
+
+\family typewriter
+bit at 0x83 MOSI;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* I/O port 0, bit 3 */
+\newline
+bit at 0x91 MISO;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* I/O port 1, bit 1 */
+\newline
+bit
+\begin_inset LatexCommand \index{bit}
\end_inset
+ at 0x92 MCLK;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* I/O port 1, bit 2 */
+\layout Standard
+
+and you can use the same hardware dependent routine without changes, as
+ for example in a library.
+ This is somehow similar to sbit, but only one absolute address has to be
+ specified in the whole project.
+\layout Section
-\emph default
- keyword is the interrupt number this routine will service.
- When present, the compiler will insert a call to this routine in the interrupt
- vector table for the interrupt number specified.
- The
-\emph on
-using
-\emph default
- keyword can be used to tell the compiler to use the specified register
- bank (8051 specific) when generating code for this function.
- 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}
+Parameters
+\begin_inset LatexCommand \index{Parameters}
\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.
- 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}
+\begin_inset LatexCommand \index{function parameter}
\end_inset
-.
-
+ & Local Variables
+\begin_inset LatexCommand \index{local variables}
+
+\end_inset
+
+
+\begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
+
+\end_inset
+
+
\layout Standard
-A special note here, int (16 bit) and long (32 bit) integer division
-\begin_inset LatexCommand \index{Division}
+Automatic (local) variables and parameters to functions can either be placed
+ on the stack or in data-space.
+ The default action of the compiler is to place these variables in the internal
+ RAM (for small model) or external RAM (for large model).
+ This in fact makes them similar to
+\emph on
+static
+\begin_inset LatexCommand \index{static}
\end_inset
-, multiplication
-\begin_inset LatexCommand \index{Multiplication}
+
+\emph default
+ so by default functions are non-reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
- & modulus
-\begin_inset LatexCommand \index{Modulus}
+.
+
+\newline
+
+\newline
+They can be placed on the stack
+\begin_inset LatexCommand \index{stack}
\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
+ by using the
\emph on
-
\begin_inset ERT
\emph default
- option and the source file will need to be compiled using the
+ option, by using
\emph on
--
-\begin_inset ERT
-status Collapsed
+#pragma\SpecialChar ~
+stackauto
+\emph default
-\layout Standard
+\begin_inset LatexCommand \index{\#pragma stackauto}
-\backslash
-/
\end_inset
--int-long-ren
-\emph default
-t
-\begin_inset LatexCommand \index{-\/-int-long-rent}
+ or by using the
+\emph on
+reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
- compiler option.
-\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
-\emph on
-main
\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
+ keyword in the function declaration, e.g.:
+\layout Verse
-\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
+\family typewriter
+unsigned char foo(char i) reentrant
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
\layout Standard
-Interrupt #
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Since stack space on 8051 is limited, the
+\emph on
+reentrant
+\emph default
+keyword or the
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
\layout Standard
-Description
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-stack-auto
+\emph default
+ option should be used sparingly.
+ Note that the reentrant keyword just means that the parameters & local
+ variables will be allocated to the stack, it
+\emph on
+does not
+\emph default
+ mean that the function is register bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
-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
+ independent.
+\newline
-\layout Standard
+\newline
+Local variables
+\begin_inset LatexCommand \index{local variables}
-External 0
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ can be assigned storage classes and absolute
+\begin_inset LatexCommand \index{Absolute addressing}
-0x0003
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ addresses, e.g.:
+\layout Verse
-1
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\family typewriter
+unsigned char foo()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+xdata unsigned char i;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+bit bvar;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+data at
+\begin_inset LatexCommand \index{at}
-Timer 0
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+ 0x31 unsigned char j;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
\layout Standard
-0x000B
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+In the above example the variable
+\emph on
+i
+\emph default
+ will be allocated in the external ram,
+\emph on
+bvar
+\emph default
+ in bit addressable space and
+\emph on
+ j
+\emph default
+ in internal ram.
+ When compiled with
+\emph on
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-2
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-stack-auto
+\emph default
+ or when a function is declared as
+\emph on
+reentrant
+\emph default
+ this should only be done for static variables.
\layout Standard
-External 1
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+Parameters
+\begin_inset LatexCommand \index{function parameter}
-0x0013
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ however are not allowed any storage class
+\begin_inset LatexCommand \index{Storage class}
-3
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-Timer 1
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+, (storage classes for parameters will be ignored), their allocation is
+ governed by the memory model in use, and the reentrancy options.
+\layout Section
-\layout Standard
+Overlaying
+\begin_inset LatexCommand \label{sub:Overlaying}
-0x001B
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-4
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{Overlaying}
-Serial
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-
-0x0023
-\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
-5
+For non-reentrant
+\begin_inset LatexCommand \index{reentrant}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ 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
+\begin_inset LatexCommand \index{local variables}
-Timer 2 (8052)
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ 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
+\begin_inset LatexCommand \index{Memory model}
-0x002B
\end_inset
-</cell>
-</row>
-</lyxtabular>
-\end_inset
+ is small.
+\emph default
+ If an explicit storage class
+\begin_inset LatexCommand \index{Storage class}
-\newline
+\end_inset
+ is specified for a local variable, it will NOT be overlayed.
\layout Standard
-If the interrupt service routine is defined without
-\emph on
-using
-\begin_inset LatexCommand \index{using}
+Note that the compiler (not the linkage editor) makes the decision for overlayin
+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}
\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.
- This scheme may be advantageous for small interrupt service routines which
- have low register usage.
+ if they are not reentrant.
\layout Standard
-If the interrupt service routine is defined to be using a specific register
- bank then only
-\emph on
-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.
- This scheme is recommended for larger interrupt service routines.
+Also note that the compiler does not do any processing of inline assembler
+ code, so the compiler might incorrectly assign local variables and parameters
+ 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.
\layout Standard
-Calling other functions from an interrupt service routine is not recommended,
- avoid it if possible.
-\newline
-For some pitfalls see section
-\begin_inset LatexCommand \ref{sub:Overlaying}
+Parameters and local variables of functions that contain 16 or 32 bit multiplica
+tion
+\begin_inset LatexCommand \index{Multiplication}
\end_inset
-about Overlaying and section
-\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
+ or division
+\begin_inset LatexCommand \index{Division}
\end_inset
-about Functions using private banks.
-\newline
-
-\layout Subsection
+ will NOT be overlayed since these are implemented using external functions,
+ e.g.:
+\layout Verse
-Critical Functions
-\layout Standard
+\family typewriter
+#pragma save
+\newline
+#pragma nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
-\shape italic
-<TODO: this isn't implemented at all!>
-\shape default
+\end_inset
+
+\newline
+void set_error(unsigned char errcd)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+P3 = errcd;
+\newline
+}
+\newline
+#pragma restore
\newline
\newline
-A special keyword may be associated with a function declaring it as
-\emph on
-critical
-\emph default
-.
- SDCC will generate code to disable all interrupts upon entry to a critical
- function and enable them back before returning.
- Note that nesting critical functions may cause unpredictable results.
-\layout Verse
+void some_isr () interrupt
+\begin_inset LatexCommand \index{interrupt}
+\end_inset
-\family typewriter
-int foo () critical
+ 2
\newline
-{
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
...
-
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+set_error(10);
\newline
\SpecialChar ~
\SpecialChar ~
}
\layout Standard
-The critical attribute maybe used with other attributes like
+In the above example the parameter
\emph on
-reentrant.
-\layout Subsection
+errcd
+\emph default
+ for the function
+\emph on
+set_error
+\emph default
+ would be assigned to the overlayable segment if the #pragma\SpecialChar ~
+nooverlay was
+ not present, this could cause unpredictable runtime behavior when called
+ from an interrupt service routine.
+ The #pragma\SpecialChar ~
+nooverlay ensures that the parameters and local variables for
+ the function are NOT overlayed.
+\layout Section
-Naked Functions
-\begin_inset LatexCommand \label{sub:Naked-Functions}
+Interrupt Service Routines
+\begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
\end_inset
-\begin_inset LatexCommand \index{Naked functions}
-
-\end_inset
-
+\layout Subsection
+General Information
\layout Standard
-A special keyword may be associated with a function declaring it as
+SDCC allows
\emph on
-_naked
-\begin_inset LatexCommand \index{\_naked}
-
-\end_inset
-
-.
-
+i
\emph default
-The
+nterrupt
\emph on
-_naked
+s
\emph default
- function modifier attribute prevents the compiler from generating prologue
-\begin_inset LatexCommand \index{function prologue}
-
-\end_inset
-
- and epilogue
-\begin_inset LatexCommand \index{function epilogue}
-
-\end_inset
-
- code for that function.
- This means that the user is entirely responsible for such things as saving
- any registers that may need to be preserved, selecting the proper register
- bank, generating the
+ervice
\emph on
-return
+r
\emph default
- instruction at the end, etc.
- Practically, this means that the contents of the function must be written
- in inline assembler.
- This is particularly useful for interrupt functions, which can have a large
- (and often unnecessary) prologue/epilogue.
- For example, compare the code generated by these two functions:
+outines to be coded in C, with some extended keywords.
\layout Verse
\family typewriter
-volatile
-\begin_inset LatexCommand \index{volatile}
-
-\end_inset
-
- data unsigned char counter;
-\newline
-
-\newline
-void simpleInterrupt(void) interrupt
-\begin_inset LatexCommand \index{interrupt}
-
-\end_inset
-
- 1
+void timer_isr (void) interrupt 1 using 1
\newline
-{
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-counter++;
+...
+
\newline
}
-\newline
+\layout Standard
+The optional number following the
+\emph on
+interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\emph default
+ keyword is the interrupt number this routine will service.
+ When present, the compiler will insert a call to this routine in the interrupt
+ 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
+\emph default
+ keyword can be used to tell the compiler to use the specified register
+ bank (8051 specific) when generating code for this function.
+
\newline
-void nakedInterrupt(void) interrupt 2 _naked
-\newline
-{
+
+\layout Standard
+
+Interrupt service routines open the door for some very interesting bugs:
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_asm
-\begin_inset LatexCommand \index{\_asm}
+If an interrupt service routine changes variables which are accessed by
+ other functions these variables have to be declared
+\emph on
+volatile
+\emph default
+
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+.
+
+\layout Standard
+
+If the access to these variables is not
+\emph on
+atomic
+\begin_inset LatexCommand \index{atomic access}
+
+\end_inset
+
+
+\emph default
+ (i.e.
+ the processor needs more than one instruction for the access and could
+ be interrupted while accessing the variable) the interrupt must be disabled
+ during the access to avoid inconsistent data.
+ Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
+ and should be protected by disabling interrupts.
+ You're not automatically on the safe side if you use 8 bit variables though.
+ We need an example here: f.e.
+ on the 8051 the harmless looking
+\begin_inset Quotes srd
+\end_inset
+
+
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x80;
+\family default
+
+\begin_inset Quotes sld
+\end_inset
+
+ is not atomic if
+\family typewriter
+flags
+\family default
+ resides in xdata.
+ Setting
+\begin_inset Quotes srd
+\end_inset
+
+
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x40;
+\family default
+
+\begin_inset Quotes sld
+\end_inset
+
+ from within an interrupt routine might get lost if the interrupt occurs
+ at the wrong time.
+
+\begin_inset Quotes sld
+\end_inset
+
+
+\family typewriter
+counter\SpecialChar ~
++=\SpecialChar ~
+8;
+\family default
+
+\begin_inset Quotes srd
+\end_inset
+
+ is not atomic on the 8051 even if
+\family typewriter
+counter
+\family default
+ is located in data memory.
+ Bugs like these are hard to reproduce and can cause a lot of trouble.
+
+\layout Standard
+
+The return address and the registers used in the interrupt service routine
+ are saved on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ so there must be sufficient stack space.
+ If there isn't variables or registers (or even the return address itself)
+ will be corrupted.
+ This
+\emph on
+stack overflow
+\emph default
+
+\begin_inset LatexCommand \index{stack overflow}
+
+\end_inset
+
+ is most likely to happen if the interrupt occurs during the
+\begin_inset Quotes sld
+\end_inset
+
+deepest
+\begin_inset Quotes srd
+\end_inset
+
+ subroutine when the stack is already in use for f.e.
+ many return addresses.
+\layout Standard
+
+A special note here, int (16 bit) and long (32 bit) integer division
+\begin_inset LatexCommand \index{Division}
+
+\end_inset
+
+, multiplication
+\begin_inset LatexCommand \index{Multiplication}
+
+\end_inset
+
+ & modulus
+\begin_inset LatexCommand \index{Modulus}
+
+\end_inset
+
+ and floating-point
+\begin_inset LatexCommand \index{Floating point support}
+
+\end_inset
+
+ operations are implemented using external support routines developed in
+ ANSI-C.
+ If an interrupt service routine needs to do any of these operations then
+ the support routines (as mentioned in a following section) will have to
+ be recompiled using the
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-int-long-reent
+\emph default
+
+\begin_inset LatexCommand \index{-\/-int-long-reent}
\end_inset
+ compiler option.
+\layout Standard
+
+Calling other functions from an interrupt service routine is not recommended,
+ avoid it if possible.
+ Note that when some function is called from an interrupt service routine
+ it should be preceded by a #pragma\SpecialChar ~
+nooverlay
+\begin_inset LatexCommand \index{\#pragma nooverlay}
+
+\end_inset
+ if it is not reentrant.
+ Furthermore nonreentrant functions should not be called from the main program
+ while the interrupt service routine might be active.
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-inc\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_counter
+
\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 ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-reti\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-; MUST explicitly include ret or reti in _naked function.
+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
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_endasm
-\begin_inset LatexCommand \index{\_endasm}
+
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="7" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Interrupt #
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Vector Address
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+External 0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0003
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Timer 0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x000B
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+External 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0013
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Timer 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x001B
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Serial
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0023
+\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
+
+5
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Timer 2 (8052)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x002B
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Standard
+
+If the interrupt service routine is defined without
+\emph on
+using
+\begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
+
+\end_inset
+
+
+\emph default
+ 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
+\emph default
+ & psw are saved and restored, if such an interrupt service routine calls
+ another function (using another register bank) then the entire register
+ bank of the called function will be saved on the stack.
+ This scheme is recommended for larger interrupt service routines.
+\layout Subsection
+
+HC08 Interrupt Service Routines
+\layout Standard
+
+Since the number of interrupts available is chip specific and the interrupt
+ vector table always ends at the last byte of memory, the interrupt numbers
+ corresponds to the interrupt vectors in reverse order of address.
+ For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
+ 2 will use the interrupt vector at 0xfffa, and so on.
+ However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
+ this way; instead see section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
+\end_inset
+
+ for details on customizing startup.
+\layout Subsection
+
+Z80 Interrupt Service Routines
+\layout Standard
+
+The Z80 uses several different methods for determining the correct interrupt
+ vector depending on the hardware implementation.
+ Therefore, SDCC ignores the optional interrupt number and does not attempt
+ to generate an interrupt vector table.
+\layout Standard
+
+By default, SDCC generates code for a maskable interrupt, which uses an
+ RETI instruction to return from the interrupt.
+ To write an interrupt handler for the non-maskable interrupt, which needs
+ an RETN instruction instead, add the
+\emph on
+critical
+\emph default
+ keyword:
+\layout Verse
+
+
+\family typewriter
+void nmi_isr (void) critical interrupt
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Section
+
+Enabling and Disabling Interrupts
+\layout Subsection
+
+Critical Functions and Critical Statements
+\layout Standard
+
+A special keyword may be associated with a block or a function declaring
+ it as
+\emph on
+critical
+\emph default
+.
+ SDCC will generate code to disable all interrupts
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ upon entry to a critical function and restore the interrupt enable to the
+ previous state before returning.
+ Nesting critical functions will need one additional byte on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ for each call.
+\layout Verse
+
+
+\family typewriter
+int foo () critical
+\begin_inset LatexCommand \index{critical}
+
+\end_inset
+
+
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Standard
+
+The critical attribute maybe used with other attributes like
+\emph on
+reentrant.
+\emph default
+
+\newline
+The keyword
+\emph on
+critical
+\emph default
+ may also be used to disable interrupts more locally:
+\layout Verse
+
+
+\family typewriter
+critical{ i++; }
+\layout Standard
+
+More than one statement could have been included in the block.
+\layout Subsection
+
+Enabling and Disabling Interrupts directly
+\layout Standard
+
+Interrupts
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ can also be disabled and enabled directly (8051):
+\layout Verse
+
+
+\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
+\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
+ interrupts you might want to make use of defines with inline assembly
+\begin_inset LatexCommand \index{Assembler routines}
+
+\end_inset
+
+ (HC08):
+\layout Verse
+
+
+\family typewriter
+#define CLI _asm
+\begin_inset LatexCommand \index{\_asm}
+
+\end_inset
+
+\SpecialChar ~
+\SpecialChar ~
+cli\SpecialChar ~
+\SpecialChar ~
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+;
+\layout Verse
+
+
+\family typewriter
+#define SEI _asm\SpecialChar ~
+\SpecialChar ~
+sei\SpecialChar ~
+\SpecialChar ~
+_endasm;
+\layout Verse
+
+
+\family typewriter
+...
+\layout Standard
+
+Note: it is sometimes sufficient to disable only a specific interrupt source
+ like f.e.
+ a timer or serial interrupt by manipulating an
+\emph on
+interrupt mask
+\begin_inset LatexCommand \index{interrupt mask}
+
+\end_inset
+
+
+\emph default
+ register.
+
+\layout Standard
+
+Usually the time during which interrupts are disabled should be kept as
+ short as possible.
+ This minimizes both
+\emph on
+interrupt latency
+\emph default
+
+\begin_inset LatexCommand \index{interrupt latency}
+
+\end_inset
+
+ (the time between the occurrence of the interrupt and the execution of
+ the first code in the interrupt routine) and
+\emph on
+interrupt jitter
+\emph default
+
+\begin_inset LatexCommand \index{interrupt jitter}
+
+\end_inset
+
+ (the difference between the shortest and the longest interrupt latency).
+ These really are something different, f.e.
+ a serial interrupt has to be served before its buffer overruns so it cares
+ for the maximum interrupt latency, whereas it does not care about jitter.
+ On a loudspeaker driven via a digital to analog converter which is fed
+ by an interrupt a latency of a few milliseconds might be tolerable, whereas
+ a much smaller jitter will be very audible.
+\layout Standard
+
+You can reenable interrupts within an interrupt routine and on some architecture
+s you can make use of two (or more) levels of
+\emph on
+interrupt priorities
+\emph default
+
+\begin_inset LatexCommand \index{interrupt priority}
+
+\end_inset
+
+.
+ On some architectures which don't support interrupt priorities these can
+ be implemented by manipulating the interrupt mask and reenabling interrupts
+ within the interrupt routine.
+ Check there is sufficient space on the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ and don't add complexity unless you have to.
+
+\layout Section
+
+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 (mcs51, ds390 register bank)}
+
+\end_inset
+
+
+\emph default
+ attribute (which tells the compiler to use a register bank
+\begin_inset LatexCommand \index{register bank (mcs51, ds390)}
+
+\end_inset
+
+ other than the default bank zero).
+ It should only be applied to
+\emph on
+interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\emph default
+ 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
+
+The
+\emph on
+using
+\emph default
+ attribute will have no effect on the generated code for a
+\emph on
+non-interrupt
+\emph default
+ function (but may occasionally be useful anyway
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+possible exception: if a function is called ONLY from 'interrupt' functions
+ using a particular bank, it can be declared with the same 'using' attribute
+ as the calling 'interrupt' functions.
+ For instance, if you have several ISRs using bank one, and all of them
+ call memcpy(), it might make sense to create a specialized version of memcpy()
+ 'using 1', since this would prevent the ISR from having to save bank zero
+ to the stack on entry and switch to bank zero before calling the function
+\end_inset
+
+).
+\newline
+
+\emph on
+(pending: I don't think this has been done yet)
+\layout Standard
+
+An
+\emph on
+interrupt
+\emph default
+ function using a non-zero bank will assume that it can trash that register
+ bank, and will not save it.
+ Since high-priority interrupts
+\begin_inset LatexCommand \index{interrupt priority}
+
+\end_inset
+
+ can interrupt low-priority ones on the 8051 and friends, this means that
+ if a high-priority ISR
+\emph on
+using
+\emph default
+ a particular bank occurs while processing a low-priority ISR
+\emph on
+using
+\emph default
+ the same bank, terrible and bad things can happen.
+ To prevent this, no single register bank should be
+\emph on
+used
+\emph default
+ by both a high priority and a low priority ISR.
+ This is probably most easily done by having all high priority ISRs use
+ one bank and all low priority ISRs use another.
+ If you have an ISR which can change priority at runtime, you're on your
+ own: I suggest using the default bank zero and taking the small performance
+ hit.
+\layout Standard
+
+It is most efficient if your ISR calls no other functions.
+ If your ISR must call other functions, it is most efficient if those functions
+ use the same bank as the ISR (see note 1 below); the next best is if the
+ called functions use bank zero.
+ It is very inefficient to call a function using a different, non-zero bank
+ from an ISR.
+
+\layout Section
+
+Startup Code
+\begin_inset LatexCommand \label{sub:Startup-Code}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Startup code}
+
+\end_inset
+
+
+\layout Subsection
+
+MCS51/DS390 Startup Code
+\layout Standard
+
+The compiler inserts a call to the C routine
+\emph on
+_sdcc_external_startup()
+\begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
+
+\end_inset
+
+
+\series bold
+\emph default
+
+\series default
+at the start of the CODE area.
+ This routine is in the runtime library
+\begin_inset LatexCommand \index{Runtime library}
+
+\end_inset
+
+.
+ By default this routine returns 0, if this routine returns a non-zero value,
+ the static & global variable initialization will be skipped and the function
+ main will be invoked.
+ Otherwise static & global variables will be initialized before the function
+ main is invoked.
+ You could add a
+\emph on
+_sdcc_external_startup()
+\emph default
+ routine to your program to override the default if you need to setup hardware
+ or perform some other critical operation prior to static & global variable
+ initialization.
+ On some mcs51 variants xdata has to be explicitly enabled before it can
+ be accessed, this is the place to do it.
+ The startup code clears the complete 256 byte of idata memory, this might
+ cause problems for 128 byte devices (endless loop reported for Chipcon
+ CC1010).
+\layout Standard
+
+See also the compiler option
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-xinit
+\emph default
+-
+\emph on
+opt
+\emph default
+
+\begin_inset LatexCommand \index{-\/-no-xinit-opt}
+
+\end_inset
+
+ and section
+\begin_inset LatexCommand \ref{sub:MCS51-variants}
+
+\end_inset
+
+\SpecialChar ~
+about MCS51-variants.
+\layout Subsection
+
+HC08 Startup Code
+\layout Standard
+
+The HC08 startup code follows the same scheme as the MCS51 startup code.
+\layout Subsection
+
+Z80 Startup Code
+\layout Standard
+
+On the Z80 the startup code is inserted by linking with crt0.o which is generated
+ from sdcc/device/lib/z80/crt0.s.
+ If you need a different startup code you can use the compiler option
+\emph on
+-
+\series bold
+\emph default
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+
+\series default
+\emph on
+-no-std-crt0
+\emph default
+
+\begin_inset LatexCommand \index{-\/-no-std-crt0}
+
+\end_inset
+
+ and provide your own crt0.o.
+
+\layout Section
+
+Inline Assembler Code
+\begin_inset LatexCommand \index{Assembler routines}
+
+\end_inset
+
+
+\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 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
+
+\newline
+void to_buffer( unsigned char c )
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+if( head != tail-1 )
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+buf[ head++ ] = c;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* access to a 256 byte aligned array */
+\newline
+}
+\layout Standard
+
+If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
+ then a corresponding buffer.asm file is generated.
+ We define a new function
+\family typewriter
+to_buffer_asm()
+\family default
+ in file buffer.c in which we cut and paste the generated code, removing
+ unwanted comments and some ':'.
+ Then add
+\begin_inset Quotes sld
+\end_inset
+
+_asm
+\begin_inset Quotes srd
+\end_inset
+
+ and
+\begin_inset Quotes sld
+\end_inset
+
+_endasm;
+\begin_inset Quotes srd
+\end_inset
+
+ to the beginning and the end of the function body:
+\layout Verse
+
+
+\family typewriter
+\size footnotesize
+/* With a cut and paste from the .asm file, we have something to start with.
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+The function is not yet OK! (registers aren't saved) */
+\newline
+void to_buffer_asm( unsigned char c )
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
+\begin_inset LatexCommand \index{\_asm}
+
+\end_inset
+
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+r2,dpl
+\newline
+;buffer.c if( head != tail-1 )
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+a,_tail
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dec\SpecialChar ~
+\SpecialChar ~
+a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+r3,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+a,_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+cjne a,ar3,00106$
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
+\newline
+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 ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+r3,_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+inc\SpecialChar ~
+\SpecialChar ~
+_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+dpl,r3
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+dph,#(_buf >> 8)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+a,r2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+movx @dptr,a
+\newline
+00103$:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm;
+\newline
+}
+\layout Standard
+
+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
+ (1) and finally have:
+\layout Verse
+
+
+\family typewriter
+\size footnotesize
+unsigned char far at 0x7f00 buf[0x100];
+\newline
+unsigned char head,tail;
+\newline
+#define USE_ASSEMBLY (1)
+\newline
+
+\newline
+#if !USE_ASSEMBLY
+\newline
+
+\newline
+void to_buffer( unsigned char c )
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+if( head != tail-1 )
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+buf[ head++ ] = c;
+\newline
+}
+\newline
+
+\newline
+#else
+\newline
+
+\newline
+void to_buffer( unsigned char c )
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+c; // to avoid warning: unreferenced function argument
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
+\begin_inset LatexCommand \index{\_asm}
+
+\end_inset
+
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; save used registers here.
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; If we were still using r2,r3 we would have to push them here.
+
+\newline
+; if( head != tail-1 )
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+ a,_tail
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dec\SpecialChar ~
+ a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+xrl\SpecialChar ~
+ a,_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+jz\SpecialChar ~
+\SpecialChar ~
+ t_b_end$
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+;
+\newline
+; buf[ head++ ] = c;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+ a,dpl \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; dpl holds lower byte of function argument
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+ dpl,_head \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; buf is 0x100 byte aligned so head can be used directly
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+ dph,#(_buf>>8)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+movx @dptr,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+inc \SpecialChar ~
+_head
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
+\newline
+t_b_end$:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; restore used registers here
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm;
+\newline
+}
+\newline
+#endif
+\layout Standard
+
+The inline assembler code can contain any valid code understood by the assembler
+, this includes any assembler directives and comment lines
+\begin_inset Foot
+collapsed false
+
+\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
+
+.
+ The compiler does not do any validation of the code within the
+\family typewriter
+_asm
+\begin_inset LatexCommand \index{\_asm}
+
+\end_inset
+
+ ...
+ _endasm;
+\family default
+ keyword pair.
+ Specifically it will not know which registers are used and thus register
+ pushing/popping
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
+
+ has to be done manually.
+
+\layout Standard
+
+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
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-
+\emph on
+peep-asm
+\begin_inset LatexCommand \index{-\/-peep-asm}
+
+\end_inset
+
+
+\emph default
+ command line option is used, the inline assembler code will be passed through
+ the peephole optimizer
+\begin_inset LatexCommand \index{Peephole optimizer}
+
+\end_inset
+
+.
+ There are only a few (if any) cases where this option makes sense, it might
+ cause some unexpected changes in the inline assembler code.
+ Please go through the peephole optimizer rules defined in file
+\emph on
+SDCCpeeph.def
+\emph default
+ before using this option.
+\layout Subsection
+
+Naked Functions
+\begin_inset LatexCommand \label{sub:Naked-Functions}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Naked functions}
+
+\end_inset
+
+
+\layout Standard
+
+A special keyword may be associated with a function declaring it as
+\emph on
+_naked
+\begin_inset LatexCommand \index{\_naked}
+
+\end_inset
+
+.
+
+\emph default
+The
+\emph on
+_naked
+\emph default
+ function modifier attribute prevents the compiler from generating prologue
+\begin_inset LatexCommand \index{function prologue}
+
+\end_inset
+
+ and epilogue
+\begin_inset LatexCommand \index{function epilogue}
+
+\end_inset
+
+ code for that function.
+ This means that the user is entirely responsible for such things as saving
+ any registers that may need to be preserved, selecting the proper register
+ bank, generating the
+\emph on
+return
+\emph default
+ instruction at the end, etc.
+ Practically, this means that the contents of the function must be written
+ in inline assembler.
+ This is particularly useful for interrupt functions, which can have a large
+ (and often unnecessary) prologue/epilogue.
+ For example, compare the code generated by these two functions:
+\layout Verse
+
+
+\family typewriter
+volatile
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+ data unsigned char counter;
+\newline
+
+\newline
+void simpleInterrupt(void) interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ 1
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+counter++;
+\newline
+}
+\newline
+
+\newline
+void nakedInterrupt(void) interrupt 2 _naked
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
+\begin_inset LatexCommand \index{\_asm}
+
+\end_inset
+
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+inc\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_counter ; does not change flags, no need to save psw
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+reti\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; MUST explicitly include ret or reti in _naked function.
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+;
+\newline
+}
+\layout Standard
+
+For an 8051 target, the generated simpleInterrupt looks like:
+\layout Verse
+
+
+\family typewriter
+_simpleInterrupt:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+push\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+acc
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+push\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+push\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dpl
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+push\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dph
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+push\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+psw
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+psw,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+inc\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_counter
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+pop\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+psw
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+pop\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dph
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+pop\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dpl
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+pop\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+pop\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+acc
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+reti
+\layout Standard
+
+whereas nakedInterrupt looks like:
+\layout Verse
+
+
+\family typewriter
+_nakedInterrupt:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+inc\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_counter ; does not change flags, no need to save psw
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+reti\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; MUST explicitly include ret or reti in _naked function
+\layout Standard
+
+The related directive #pragma exclude
+\begin_inset LatexCommand \index{\#pragma exclude}
+
+\end_inset
+
+ allows a more fine grained control over pushing & popping
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
+
+ the registers.
+\layout Standard
+
+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 restrictions regarding
+ labels.
+ In older versions of the compiler all labels defined within inline assembler
+ code
+\emph on
+had to be
+\emph default
+ of the form
+\emph on
+nnnnn$
+\emph default
+ where nnnn is a number less than 100 (which implies a limit of utmost 100
+ inline assembler labels
+\emph on
+per function
+\emph default
+\noun on
+)
+\noun default
+.
+
+\layout Verse
+
+
+\family typewriter
+_asm
+\begin_inset LatexCommand \index{\_asm}
+
+\end_inset
+
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b,#10
+\newline
+00001$:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+djnz\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b,00001$
+\newline
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+ ;
+\layout Standard
+
+Inline assembler code cannot reference any C-Labels, however it can reference
+ labels
+\begin_inset LatexCommand \index{Labels}
+
+\end_inset
+
+ defined by the inline assembler, e.g.:
+\layout Verse
+
+
+\family typewriter
+foo() {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* some c code */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; some assembler code
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ljmp $0003
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* some more c code */
+\newline
+clabel:\SpecialChar ~
+\SpecialChar ~
+/* inline assembler cannot reference this label */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+$0003: ;label (can be referenced by inline assembler only)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* some more c code */
+\newline
+}
+\layout Standard
+
+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, i.e.
+ labels defines in inline assembly can not be accessed by C statements.
+\layout Section
+
+Interfacing with Assembler Code
+\begin_inset LatexCommand \index{Assembler routines}
+
+\end_inset
+
+
+\layout Subsection
+
+Global Registers used for Parameter Passing
+\begin_inset LatexCommand \index{Parameter passing}
+
+\end_inset
+
+
+\layout Standard
+
+The compiler always uses the global registers
+\emph on
+DPL, DPH
+\begin_inset LatexCommand \index{DPTR, DPH, DPL}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{DPTR}
+
+\end_inset
+
+, B
+\begin_inset LatexCommand \index{B (mcs51, ds390 register)}
+
+\end_inset
+
+
+\emph default
+and
+\emph on
+ ACC
+\begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
+
+\end_inset
+
+
+\emph default
+ to pass the first parameter to a routine.
+ The second parameter onwards is either allocated on the stack (for reentrant
+ routines or if -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto is used) or in data / xdata memory (depending on the memory
+ model).
+
+\layout Subsection
+
+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
+
+ the function c_func calls an assembler routine asm_func, which takes two
+ parameters
+\begin_inset LatexCommand \index{function parameter}
+
+\end_inset
+
+.
+\layout Verse
+
+
+\family typewriter
+extern int asm_func(unsigned char, unsigned char);
+\newline
+
+\newline
+int c_func (unsigned char i, unsigned char j)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return asm_func(i,j);
+\newline
+}
+\newline
+
+\newline
+int main()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c_func(10,9);
+\newline
+}
+\layout Standard
+
+The corresponding assembler function is:
+\layout Verse
+
+
+\family typewriter
+.globl _asm_func_PARM_2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+.globl _asm_func
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+.area OSEG
+\newline
+_asm_func_PARM_2:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+.ds 1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+.area CSEG
+\newline
+_asm_func:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+a,dpl
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+a,_asm_func_PARM_2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dph
+\begin_inset LatexCommand \index{DPTR, DPH, DPL}
+
+\end_inset
+
+,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
+\layout Standard
+
+Note here that the return values
+\begin_inset LatexCommand \index{return value}
+
+\end_inset
+
+ are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
+ two byte values.
+ 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
+b' & 'acc' for four byte values.
+\layout Standard
+
+The parameter naming convention is _<function_name>_PARM_<n>, where n is
+ the parameter number starting from 1, and counting from the left.
+ The first parameter is passed in
+\begin_inset Quotes eld
+\end_inset
+
+dpl
+\begin_inset Quotes erd
+\end_inset
+
+ for a one byte parameter,
+\begin_inset Quotes eld
+\end_inset
+
+dptr
+\begin_inset Quotes erd
+\end_inset
+
+ for two bytes,
+\begin_inset Quotes eld
+\end_inset
+
+b,dptr
+\begin_inset Quotes erd
+\end_inset
+
+ for three bytes and
+\begin_inset Quotes eld
+\end_inset
+
+acc,b,dptr
+\begin_inset Quotes erd
+\end_inset
+
+ for a four bytes parameter.
+ The variable name for the second parameter will be _<function_name>_PARM_2.
+\newline
+
+\newline
+Assemble the assembler routine with the following command:
+\newline
+
+\newline
+
+\family sans
+\series bold
+asx8051 -losg asmfunc.asm
+\newline
+
+\newline
+
+\family default
+\series default
+Then compile and link the assembler routine to the C source file with the
+ following command:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcc cfunc.c asmfunc.rel
+\layout Subsection
+
+Assembler Routine (reentrant)
+\layout Standard
+
+In this case
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Assembler routines (reentrant)}
+
+\end_inset
+
+ 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 leftmost parameter will be on the top of the stack.
+ Here is an example:
+\layout Verse
+
+
+\family typewriter
+extern int asm_func(unsigned char, unsigned char);
+\newline
+
+\newline
+int c_func (unsigned char i, unsigned char j) reentrant
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return asm_func(i,j);
+\newline
+}
+\newline
+
+\newline
+int main()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c_func(10,9);
+\newline
+}
+\layout Standard
+
+The corresponding assembler routine is:
+\layout Verse
+
+
+\family typewriter
+.globl _asm_func
+\newline
+_asm_func:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+push _bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov _bp,sp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov r2,dpl
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov a,_bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add a,#0xfd
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov r0,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add a,#0xfc ;?
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov r1,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov a,@r0
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add a,r2 ;?
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov dph,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov sp,_bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+pop _bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
+\layout Standard
+
+The compiling and linking procedure remains the same, however note the extra
+ entry & exit linkage required for the assembler code, _bp is the stack
+ frame pointer and is used to compute the offset into the stack for parameters
+ and local variables.
+\layout Section
+
+int (16 bit)
+\begin_inset LatexCommand \index{int (16 bit)}
+
+\end_inset
+
+ and long (32 bit)
+\begin_inset LatexCommand \index{long (32 bit)}
+
+\end_inset
+
+ Support
+\layout Standard
+
+For signed & unsigned int (16 bit) and long (32 bit) variables, division,
+ multiplication and modulus operations are implemented by support routines.
+ These support routines are all developed in ANSI-C to facilitate porting
+ to other MCUs, although some model specific assembler optimizations are
+ used.
+ The following files contain the described routines, all of them can be
+ found in <installdir>/share/sdcc/lib.
+\newline
+
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" 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
+Function
+\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
+
+_mulint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16 bit multiplication
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_divsint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ signed 16 bit division (calls _divuint)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_divuint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ unsigned 16 bit division
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_modsint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+signed 16 bit modulus (calls _moduint)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_moduint.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+unsigned 16 bit modulus
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_mullong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+32 bit multiplication
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_divslong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ signed 32 division (calls _divulong)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_divulong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+unsigned 32 division
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+_modslong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ signed 32 bit modulus (calls _modulong)
+\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
+
+_modulong.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+unsigned 32 bit modulus
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Standard
+
+Since they are compiled as
+\emph on
+non-reentrant
+\emph default
+
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+, interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ service routines should not do any of the above operations.
+ If this is unavoidable then the above routines will need to be compiled
+ with 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, after which the source program will have to be compiled with
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-int-long-reent
+\begin_inset LatexCommand \index{-\/-int-long-reent}
+
+\end_inset
+
+
+\emph default
+ option.
+ 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
+
+Floating Point Support
+\begin_inset LatexCommand \index{Floating point support}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
+ floating point support routines are derived from gcc's floatlib.c and consist
+ of the following routines:
+\newline
+
+\layout Standard
+\align center
+
+\size footnotesize
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="17" 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
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+Function
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fsadd.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
+add floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fssub.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
+subtract floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fsdiv.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
+divide floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fsmul.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
+multiply floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2uchar.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 floating point to unsigned char
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2char.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 floating point to signed char
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2uint.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 floating point to unsigned int
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2int.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 floating point to signed int
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2ulong.
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+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 floating point to unsigned long
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_fs2long.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 floating point to signed long
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_uchar2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert unsigned char to floating point
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_char2fs.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 char to floating point number
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_uint2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert unsigned int to floating point
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_int2fs.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 int to floating point numbers
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_ulong2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert unsigned long to floating point number
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+_long2fs.c
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+convert long to floating point number
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Standard
+
+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
+
+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()
+\begin_inset LatexCommand \index{printf()}
+
+\end_inset
+
+.
+
+\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
+
+
+\series bold
+Attention
+\series default
+: this option wasn't maintained for a long time and is quite buggy.
+ Small programs might work.
+ You've been warned!
+\layout Standard
+
+The external stack (-
+\begin_inset ERT
+status Collapsed
+
+\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 is 256 bytes
+ in size.
+ 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).
+\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
+
+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 Standard
+
+SDCPP supports the following #pragma directives:
+\layout Itemize
+
+preproc_asm
+\begin_inset LatexCommand \index{\#pragma preproc\_asm}
\end_inset
-;
-\newline
-}
+ (+ | -) - switch _asm _endasm block preprocessing on / off.
+ Default is on.
\layout Standard
-For an 8051 target, the generated simpleInterrupt looks like:
+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
-_simpleInterrupt:
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-push\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-acc
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-push\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b
-\newline
-\SpecialChar ~
+#pragma save
+\begin_inset LatexCommand \index{\#pragma save}
+
+\end_inset
+
+ \SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-push\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-dpl
+/* save the current settings */
\newline
+#pragma nogcse
+\begin_inset LatexCommand \index{\#pragma nogcse}
+
+\end_inset
+
+ \SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-push\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-dph
+/* turnoff global subexpression elimination */
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-push\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-psw
+#pragma noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+
+\end_inset
+
+ /* turn off induction optimizations */
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-psw,#0x00
+int foo ()
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-inc\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_counter
+{
\newline
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-psw
+ \SpecialChar ~
+ ...
+
\newline
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-dph
+ \SpecialChar ~
+ /* large code */
\newline
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-dpl
+ \SpecialChar ~
+ ...
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b
+}
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-acc
+#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
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-reti
+
+\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
-whereas nakedInterrupt looks like:
-\layout Verse
+__mcs51
+\begin_inset LatexCommand \index{\_\_mcs51}
+\end_inset
-\family typewriter
-_nakedInterrupt:
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-inc\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_counter
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-reti\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-; MUST explicitly include ret or reti in _naked function.
-\layout Standard
+, __ds390
+\begin_inset LatexCommand \index{\_\_ds390}
+
+\end_inset
-The #pragma directive EXCLUDE
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+, __hc08
+\begin_inset LatexCommand \index{\_\_hc08}
\end_inset
- also allows to reduce pushing & popping the registers.
-\layout Standard
+, __z80
+\begin_inset LatexCommand \index{\_\_z80}
-While there is nothing preventing you from writing C code inside a _naked
- 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
+\end_inset
-Functions using private banks
-\begin_inset LatexCommand \label{sub:Functions-using-private-banks}
+, 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
-\begin_inset LatexCommand \index{bank}
+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
-The
+when
\emph on
-using
-\begin_inset LatexCommand \index{using}
+-
+\begin_inset ERT
+status Collapsed
-\end_inset
+\layout Standard
+\backslash
+/
+\end_inset
+-stack-auto
\emph default
- attribute (which tells the compiler to use a register bank other than the
- default bank zero) should only be applied to
-\emph on
-interrupt
-\begin_inset LatexCommand \index{interrupt}
+ 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
-\emph default
- functions (see note 1 below).
- This will in most circumstances make the generated ISR code more efficient
- since it will not have to save registers on the stack.
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
\layout Standard
-The
-\emph on
-using
-\emph default
- attribute will have no effect on the generated code for a
+when
\emph on
-non-interrupt
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-small
\emph default
- function (but may occasionally be useful anyway
-\begin_inset Foot
-collapsed false
+ 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
-possible exception: if a function is called ONLY from 'interrupt' functions
- using a particular bank, it can be declared with the same 'using' attribute
- as the calling 'interrupt' functions.
- For instance, if you have several ISRs using bank one, and all of them
- call memcpy(), it might make sense to create a specialized version of memcpy()
- 'using 1', since this would prevent the ISR from having to save bank zero
- to the stack on entry and switch to bank zero before calling the function
+SDCC_MODEL_LARGE
+\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
+
\end_inset
-).
-\newline
-\emph on
-(pending: I don't think this has been done yet)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
\layout Standard
-An
+when
\emph on
-interrupt
-\emph default
- function using a non-zero bank will assume that it can trash that register
- bank, and will not save it.
- Since high-priority interrupts
-\begin_inset LatexCommand \index{interrupt priority}
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- can interrupt low-priority ones on the 8051 and friends, this means that
- if a high-priority ISR
-\emph on
-using
-\emph default
- a particular bank occurs while processing a low-priority ISR
-\emph on
-using
-\emph default
- the same bank, terrible and bad things can happen.
- To prevent this, no single register bank should be
-\emph on
-used
+-model-large
\emph default
- by both a high priority and a low priority ISR.
- This is probably most easily done by having all high priority ISRs use
- one bank and all low priority ISRs use another.
- If you have an ISR which can change priority at runtime, you're on your
- own: I suggest using the default bank zero and taking the small performance
- hit.
+ 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
-It is most efficient if your ISR calls no other functions.
- If your ISR must call other functions, it is most efficient if those functions
- use the same bank as the ISR (see note 1 below); the next best is if the
- called functions use bank zero.
- It is very inefficient to call a function using a different, non-zero bank
- from an ISR.
-
-\layout Subsection
+SDCC_USE_XSTACK
+\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
+
+\end_inset
-Startup Code
-\begin_inset LatexCommand \label{sub:Startup-Code}
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{Startup code}
+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
-The compiler inserts a call to the C routine
-\emph on
-_sdcc_external_startup()
-\begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
+SDCC_STACK_TENBIT
+\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
\end_inset
-
-\series bold
-\emph default
-\series default
-at the start of the CODE area.
- This routine is in the runtime library
-\begin_inset LatexCommand \index{Runtime library}
-
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-.
- By default this routine returns 0, if this routine returns a non-zero value,
- the static & global variable initialization will be skipped and the function
- main will be invoked.
- Otherwise static & global variables will be initialized before the function
- main is invoked.
- You could add a
-\emph on
-_sdcc_external_startup()
-\emph default
- routine to your program to override the default if you need to setup hardware
- or perform some other critical operation prior to static & global variable
- initialization.
- See also the compiler option
+\layout Standard
+
+when
\emph on
--
-\begin_inset ERT
-status Collapsed
+-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
-\backslash
-/
+SDCC_MODEL_FLAT24
+\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
+
\end_inset
--no-xinit
-\emph default
--
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+when
\emph on
-opt
+-mds390
\emph default
+ is used
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-\begin_inset LatexCommand \index{-\/-no-xinit-opt}
+\end_inset
+
+
+\layout Chapter
+
+Notes on supported Processors
+\layout Section
+
+MCS51 variants
+\begin_inset LatexCommand \label{sub:MCS51-variants}
\end_inset
-.
-\layout Subsection
-Inline Assembler Code
-\begin_inset LatexCommand \index{Assembler routines}
+\begin_inset LatexCommand \index{MCS51 variants}
\end_inset
\layout Standard
-SDCC allows the use of in-line assembler with a few restriction as regards
- labels.
- All labels defined within inline assembler code
-\emph on
-has to be
-\emph default
- of the form
-\emph on
-nnnnn$
-\emph default
- where nnnn is a number less than 100 (which implies a limit of utmost 100
- inline assembler labels
-\emph on
-per function
-\emph default
-\noun on
-)
-\noun default
-.
- It is strongly recommended that each assembly instruction (including labels)
- be placed in a separate line (as the example shows).
- When the -
-\begin_inset ERT
-status Collapsed
+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
-\backslash
-/
+With the upcome of devices with internal xdata and flash memory devices
+ using port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
+
\end_inset
--
-\emph on
-peep-asm
-\begin_inset LatexCommand \index{-\/-peep-asm}
+ 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
-
-\emph default
- command line option is used, the inline assembler code will be passed through
- the peephole optimizer
-\begin_inset LatexCommand \index{Peephole optimizer}
+ access which was formerly done by port P2 is then achieved by a Special
+ Function Register
+\begin_inset LatexCommand \index{sfr}
\end_inset
.
- This might cause some unexpected changes in the inline assembler code.
- Please go through the peephole optimizer rules defined in file
+ In well-established MCS51 tradition the address of this
\emph on
-SDCCpeeph.def
+sfr
\emph default
- carefully before using this option.
-\layout Verse
-
-
+ 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
-_asm
-\begin_inset LatexCommand \index{\_asm}
-\end_inset
-
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b,#10
-\newline
-00001$:
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-djnz\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b,00001$
-\newline
-_endasm
-\begin_inset LatexCommand \index{\_endasm}
+\begin_inset LatexCommand \index{\_XPAGE (mcs51)}
\end_inset
- ;
-\layout Standard
-The inline assembler code can contain any valid code understood by the assembler
-, this includes any assembler directives and comment lines.
- The compiler does not do any validation of the code within the
-\family typewriter
-_asm ...
- _endasm;
\family default
- keyword pair.
-
-\newline
-
-\newline
-Inline assembler code cannot reference any C-Labels, however it can reference
- labels
-\begin_inset LatexCommand \index{Labels}
+ at the appropriate location if the default, port P2, is not used for this.
+ Some examples are:
+\layout Verse
-\end_inset
- defined by the inline assembler, e.g.:
+\family typewriter
+sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
\layout Verse
\family typewriter
-foo() {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* some c code */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_asm
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-; some assembler code
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ljmp $0003
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_endasm;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* some more c code */
-\newline
-clabel:\SpecialChar ~
-\SpecialChar ~
-/* inline assembler cannot reference this label */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_asm
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-$0003: ;label (can be reference by inline assembler only)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_endasm ;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* some more c code */
-\newline
-}
-\layout Standard
+sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
+\layout Verse
-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.
- labels defines in inline assembly CANNOT be accessed by C statements.
+
+\family typewriter
+sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
\layout Standard
-An example acessing a C variable is in section
-\begin_inset LatexCommand \ref{sub:Naked-Functions}
+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
-Interfacing with Assembler Code
-\begin_inset LatexCommand \index{Assembler routines}
+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
-\layout Subsubsection
+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
-Global Registers used for Parameter Passing
-\begin_inset LatexCommand \index{Parameter passing}
+\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
-The compiler always uses the global registers
-\emph on
-DPL, DPH
-\begin_inset LatexCommand \index{DPTR, DPH, DPL}
+SDCC can target both the Zilog
+\begin_inset LatexCommand \index{Z80}
\end_inset
-, B
-\begin_inset LatexCommand \index{B (register)}
+ and the Nintendo Gameboy's Z80-like gbz80
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
\end_inset
-
-\emph default
-and
+.
+ The Z80 port is passed through the same
\emph on
- ACC
-\begin_inset LatexCommand \index{ACC}
+regressions tests
+\begin_inset LatexCommand \index{Regression test}
\end_inset
\emph default
- to pass the first parameter to a routine.
- The second parameter onwards is either allocated on the stack (for reentrant
- routines or if -
-\begin_inset ERT
-status Collapsed
-
+ 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
-\backslash
-/
-\end_inset
-
--stack-auto is used) or in data / xdata memory (depending on the memory
- model).
-
-\layout Subsubsection
-
-Assembler Routine(non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+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
-)
-\begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
+ 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
-In the following example the function c_func calls an assembler routine
- asm_func, which takes two parameters.
-\layout Verse
-
-
-\family typewriter
-extern int asm_func(unsigned char, unsigned char);
-\newline
+The port to the Motorola HC08
+\begin_inset LatexCommand \index{HC08}
-\newline
-int c_func (unsigned char i, unsigned char j)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return asm_func(i,j);
-\newline
-}
-\newline
+\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
-int main()
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return c_func(10,9);
-\newline
-}
-\layout Standard
-
-The corresponding assembler function is:
-\layout Verse
-
-\family typewriter
-.globl _asm_func_PARM_2
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-.globl _asm_func
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-.area OSEG
-\newline
-_asm_func_PARM_2:
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-.ds 1
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-.area CSEG
-\newline
-_asm_func:
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov a,dpl
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-add a,_asm_func_PARM_2
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov dpl,a
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-dpl
-\begin_inset LatexCommand \index{DPTR, DPH, DPL}
-\end_inset
-
-,#0x00
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ret
-\layout Standard
+\layout Section
-Note here that the return values are placed in 'dpl' - One byte return value,
- 'dpl' LSB & 'dph' MSB for two byte values.
- 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
-b' & 'acc' for four byte values.
+The PIC14 port
\layout Standard
-The parameter naming convention is _<function_name>_PARM_<n>, where n is
- the parameter number starting from 1, and counting from the left.
- The first parameter is passed in
-\begin_inset Quotes eld
-\end_inset
-
-dpl
-\begin_inset Quotes erd
-\end_inset
+The 14bit PIC
+\begin_inset LatexCommand \index{PIC14}
- for One bye parameter,
-\begin_inset Quotes eld
\end_inset
-dptr
-\begin_inset Quotes erd
-\end_inset
+ port still requires a major effort from the development community.
+ However it can work for very simple code.
+\layout Subsection
- if two bytes,
-\begin_inset Quotes eld
-\end_inset
+C code and 14bit PIC code page
+\begin_inset LatexCommand \index{code page (pic14)}
-b,dptr
-\begin_inset Quotes erd
\end_inset
- for three bytes and
-\begin_inset Quotes eld
-\end_inset
+ and RAM banks
+\begin_inset LatexCommand \index{RAM bank (pic14)}
-acc,b,dptr
-\begin_inset Quotes erd
\end_inset
- for four bytes, the variable name for the second parameter will be _<function_n
-ame>_PARM_2.
-\newline
-\newline
-Assemble the assembler routine with the following command:
-\newline
+\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
-\family sans
-\series bold
-asx8051 -losg asmfunc.asm
\newline
+To get the best follow these guide lines:
+\layout Enumerate
-\newline
+make local functions static, as non static functions require code page selection
+ overhead.
+\layout Enumerate
-\family default
-\series default
-Then compile and link the assembler routine to the C source file with the
- following command:
-\newline
+Make local variables static as extern variables require RAM bank selection
+ overhead.
+\layout Enumerate
-\newline
+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
-\family sans
-\series bold
-sdcc cfunc.c asmfunc.rel
-\layout Subsubsection
+Creating a device include file
+\layout Standard
-Assembler Routine(reentrant
-\begin_inset LatexCommand \index{reentrant}
+For generating a device include file use the support perl script inc2h.pl
+ kept in directory support/script.
+\layout Subsection
-\end_inset
+Interrupt code
+\layout Standard
-)
-\begin_inset LatexCommand \index{Assembler routines (reentrant)}
+For the interrupt function, use the keyword 'interrupt'
+\begin_inset LatexCommand \index{interrupt}
\end_inset
-
-\layout Standard
-
-In this case the second parameter 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.
- Here is an example:
+ 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
-extern int asm_func(unsigned char, unsigned char);
-\newline
-
-\newline
-int c_func (unsigned char i, unsigned char j) reentrant
-\newline
-{
+void Intr(void) interrupt 0
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return asm_func(i,j);
-\newline
-}
-\newline
-
-\newline
-int main()
-\newline
-{
+{
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return c_func(10,9);
+T0IF = 0; /* Clear timer interrupt */
\newline
}
+\layout Subsection
+
+Linking and assembling
\layout Standard
-The corresponding assembler routine is:
+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
-.globl _asm_func
-\newline
-_asm_func:
+.c.o:
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-push _bp
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov _bp,sp
+sdcc -S -V -mpic14 -p16F877 $<
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov r2,dpl
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov a,_bp
+gpasm -c $*.asm
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-clr c
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-add a,#0xfd
+$(PRJ).hex: $(OBJS)
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov r0,a
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,#0xfc
+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 ~
-mov r1,a
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov a,@r0
+sdcc -S -V -mpic14 -p16F877 $<
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,r2
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov dpl,a
+mpasmwin /q /o $*.asm
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov dph,#0x00
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov sp,_bp
+$(PRJ).hex: $(OBJS)
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-pop _bp
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ret
-\layout Standard
-
-The compiling and linking procedure remains the same, however note the extra
- entry & exit linkage required for the assembler code, _bp is the stack
- frame pointer and is used to compute the offset into the stack for parameters
- and local variables.
-\layout Subsection
-
-int (16 bit)
-\begin_inset LatexCommand \index{int (16 bit)}
-
-\end_inset
-
- and long (32 bit)
-\begin_inset LatexCommand \index{long (32 bit)}
-
-\end_inset
-
- Support
-\layout Standard
-
-For signed & unsigned int (16 bit) and long (32 bit) variables, division,
- multiplication and modulus operations are implemented by support routines.
- These support routines are all developed in ANSI-C to facilitate porting
- to other MCUs, although some model specific assembler optimizations are
- used.
- The following files contain the described routines, all of them can be
- found in <installdir>/share/sdcc/lib.
-\newline
-
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="11" columns="2">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-
-\series bold
-Function
-\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
-
-_mulint.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-16 bit multiplication
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-_divsint.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
- signed 16 bit division (calls _divuint)
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-_divuint.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
- unsigned 16 bit division
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-_modsint.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-signed 16 bit modulus (calls _moduint)
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-_moduint.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-unsigned 16 bit modulus
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-_mullong.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-32 bit multiplication
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-_divslong.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
- signed 32 division (calls _divulong)
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-_divulong.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
+mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
\layout Standard
-unsigned 32 division
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Please note that indentations within a
+\family typewriter
+ Makefile
+\family default
+ have to be done with a tabulator character.
+\layout Section
-\layout Standard
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
-_modslong.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+ port
\layout Standard
- signed 32 bit modulus (calls _modulong)
-\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
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
-_modulong.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ port is the portion of SDCC that is responsible to produce code for the
+ Microchip
+\begin_inset LatexCommand \index{Microchip}
-unsigned 32 bit modulus
\end_inset
-</cell>
-</row>
-</lyxtabular>
-\end_inset
+(TM) microcontrollers with 16 bit core.
+ Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
+\layout Subsection
+Global Options
+\layout Standard
-\newline
+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
-Since they are compiled as
-\emph on
-non-reentrant
-\emph default
+\backslash
+/
+\end_inset
-\begin_inset LatexCommand \index{reentrant}
+-stack-auto Auto variables that are function parameters, will be saved on
+ stack by default.
+
+\emph on
+There is no need to specify this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+-
+\begin_inset ERT
+status Collapsed
-, interrupt
-\begin_inset LatexCommand \index{interrupt}
+\layout Standard
+\backslash
+/
\end_inset
- service routines should not do any of the above operations.
- If this is unavoidable then the above routines will need to be compiled
- with the
+-float-reent All floating point functions are reentrant by default.
+
\emph on
+There is no need to specifiy this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
+
-
\begin_inset ERT
status Collapsed
/
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+-callee-saves See -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-all-callee-saves
+\layout List
+\labelwidthstring 00.00.0000
-\emph default
- option, after which the source program will have to be compiled with
-\emph on
-
\begin_inset ERT
status Collapsed
/
\end_inset
--int-long-rent
-\begin_inset LatexCommand \index{-\/-int-long-rent}
+-all-callee-saves All function arguments are passed on stack by default.
+
+\emph on
+There is no need to specify this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+-
+\begin_inset ERT
+status Collapsed
+\layout Standard
-\emph default
- option.
- Notice that you don't have to call this routines directly.
- The compiler will use them automatically every time a integer operation
- is required.
+\backslash
+/
+\end_inset
+
+-fommit-frame-pointer Frame pointer will be omitted when the function uses
+ no local variables.
\layout Subsection
-Floating Point Support
-\begin_inset LatexCommand \index{Floating point support}
+Port Specific Options
+\begin_inset LatexCommand \index{Options PIC16}
\end_inset
\layout Standard
-SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
- floating point support routines are derived from gcc's floatlib.c and consists
- of the following routines:
-\newline
+The port specific options appear after the global options in the sdcc --help
+ output.
+\layout Subsubsection
+General Options
\layout Standard
-\align center
-\size footnotesize
+General options enable certain port features and optimizations.
+\layout List
+\labelwidthstring 00.00.0000
-\begin_inset Tabular
-<lyxtabular version="3" rows="17" columns="2">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-Function
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+-pgen-bank Instructs the port to insert BANKSEL directives before instructions
+ that use the Bank Select Register (BSR).
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-Description
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-pomit-config-words Instructs the port to omit the generation of the configurati
+on words.
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fsadd.c
+\layout Standard
+
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-pomit-ivt Instructs the port to omit the generation of the interrupt vectors
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-add floating point numbers
+\layout Standard
+
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-pleave-reset-vector Used in conjuction with the previous command, instructs
+ the port NOT to omit the reset vector.
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fssub.c
+\layout Standard
+
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-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
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-subtract floating point numbers
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\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
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fsdiv.c
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+-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
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-divide floating point numbers
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fsmul.c
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+-ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
+ Useful for bootloaders.
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-multiply floating point numbers
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2uchar.c
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-asm= sets the full path and name of an external assembler to call.
+\layout List
+\labelwidthstring 00.00.0000
+-
+\begin_inset ERT
+status Collapsed
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to unsigned char
+\layout Standard
+
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+-link= sets the full path and name of an external linker to call.
+\layout Subsubsection
+
+Debugging Options
\layout Standard
+Debugging options enable extra debugging information in the output files.
+\layout List
+\labelwidthstring 00.00.0000
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2char.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+-
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to signed char
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+-debug-xtra Similar to -
+\begin_inset ERT
+status Collapsed
\layout Standard
+\backslash
+/
+\end_inset
+
+-debug
+\begin_inset LatexCommand \index{-\/-debug}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2uint.c
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+, but dumps more information.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+\layout Standard
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to unsigned int
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-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
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2int.c
+\layout Standard
+
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+-pcode-verbose Enable pcode debugging information in translation.
+\layout Subsection
+
+Preprocessor Macros
\layout Standard
+PIC16 port defines the following preprocessor macros while translating a
+ source.
+\layout Standard
+\align center
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert floating point to signed int
-\end_inset
-</cell>
-</row>
-<row topline="true">
+\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
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2ulong.
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color default
-c
+Macro
\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
-convert floating point to unsigned long
+Description
\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
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_fs2long.c
+pic18fxxxx
\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
-convert floating point to signed long
+MCU Identification.
+
+\emph on
+xxxx
+\emph default
+ is the microcontrol identification number, i.e.
+ 452, 6620, etc
\end_inset
</cell>
</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+</lyxtabular>
-\layout Standard
+\end_inset
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_uchar2fs.c
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\layout Subsection
+Directories
\layout Standard
+PIC16
+\begin_inset LatexCommand \index{PIC16}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-convert unsigned char to floating point
\end_inset
-</cell>
-</row>
-<row topline="true">
+
+ 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
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_char2fs.c
+Directory
\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
-convert char to floating point number
+Description
\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
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_uint2fs.c
+Target
\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
-convert unsigned int to floating point
+Command prefix
\end_inset
</cell>
</row>
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_int2fs.c
+PREFIX/sdcc/include/pic16
\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
-convert int to floating point numbers
+PIC16 specific headers
\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
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_ulong2fs.c
+Compiler
\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
-convert unsigned long to floating point number
+-I
\end_inset
</cell>
</row>
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-_long2fs.c
+PREFIX/sdcc/lib/pic16
\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
-convert long to floating point number
+PIC16 specific libraries
\end_inset
</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\newline
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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 Subsection
-
-MCS51 Memory Models
-\begin_inset LatexCommand \index{Memory model}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{MCS51 memory}
-
+Linker
\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
-\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}
-
+-L
\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}
+</cell>
+</row>
+</lyxtabular>
\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 strongly recommended that the small model
- be used unless absolutely required.
+
\layout Subsection
-DS390 Memory Models
-\begin_inset LatexCommand \index{Memory model}
+Pragmas
+\begin_inset LatexCommand \label{sub:PIC16_Pragmas}
\end_inset
-\begin_inset LatexCommand \index{DS390 memory model}
+\layout Standard
-\end_inset
+PIC16 port currently supports the following pragmas:
+\layout List
+\labelwidthstring 00.00.0000
+stack pragma stack forces the code generator to initialize the stack & frame
+ pointers at a specific address.
+ This is an adhoc solution since gplink does not support yet stack.
+ When the gplink issue is resolved the pragma will be deprecated
+\begin_inset Foot
+collapsed true
\layout Standard
-The only model supported is Flat 24
-\begin_inset LatexCommand \index{Flat 24 (memory model)}
+\emph on
+It is important to initialize the stack, otherwise strange things can happen.
+ Stack is not initialized by default because there are some sources that
+ do not require it.
+ (like library sources)
\end_inset
.
- 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
+The stack pragma should be used only once in a project.
+ Multiple pragmas may result in indeterminate behaviour of the program.
+\layout LyX-Code
-\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
+Example:
+\layout LyX-Code
-\begin_inset LatexCommand \index{Tinibios (DS390)}
+\layout LyX-Code
-\end_inset
+/* initializes stack at RAM address 0x5ff */
+\layout LyX-Code
-, 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
+#pragma stack 0x5ff
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-Like the
-\emph on
--
-\begin_inset ERT
-status Collapsed
+udata pragma udata instructs the compiler to emit code so that linker will
+ place a variable at a specific memory bank
+\layout LyX-Code
-\layout Standard
+Example:
+\layout LyX-Code
-\backslash
-/
-\end_inset
+\layout LyX-Code
--model-large
-\emph default
- option, variables will by default be placed into the XDATA segment.
-
-\newline
+/* places variable foo at bank2 */
+\layout LyX-Code
-\newline
-Segments may be placed anywhere in the 4 meg address space using the usual
- -
-\begin_inset ERT
-status Collapsed
+#pragma udata bank2 foo
+\layout LyX-Code
+char foo;
\layout Standard
-\backslash
-/
-\end_inset
+In order for this pragma to work there are some changes that must be made
+ in the .lkr script used in link stage.
+ In the following example a sample .lkr file is shown:
+\layout LyX-Code
--*-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 Subsection
+\layout LyX-Code
-Pragmas
-\begin_inset LatexCommand \index{Pragmas}
+// Sample linker script for the PIC18F452 processor
+\layout LyX-Code
-\end_inset
+LIBPATH .
+\layout LyX-Code
+CODEPAGE NAME=vectors START=0x0 END=0x29 PROTECTED
+\layout LyX-Code
-\layout Standard
+CODEPAGE NAME=page START=0x2A END=0x7FFF
+\layout LyX-Code
-SDCC supports the following #pragma directives.
-\layout Itemize
+CODEPAGE NAME=idlocs START=0x200000 END=0x200007 PROTECTED
+\layout LyX-Code
-SAVE
-\begin_inset LatexCommand \index{\#pragma SAVE}
+CODEPAGE NAME=config START=0x300000 END=0x30000D PROTECTED
+\layout LyX-Code
-\end_inset
+CODEPAGE NAME=devid START=0x3FFFFE END=0x3FFFFF PROTECTED
+\layout LyX-Code
- - this will save all current options to the SAVE/RESTORE stack.
- See RESTORE.
-\layout Itemize
+CODEPAGE NAME=eedata START=0xF00000 END=0xF000FF PROTECTED
+\layout LyX-Code
-RESTORE
-\begin_inset LatexCommand \index{\#pragma RESTORE}
+ACCESSBANK NAME=accessram START=0x0 END=0x7F
+\layout LyX-Code
-\end_inset
+\layout LyX-Code
- - 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
+DATABANK NAME=gpr0 START=0x80 END=0xFF
+\layout LyX-Code
-NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+DATABANK NAME=gpr1 START=0x100 END=0x1FF
+\layout LyX-Code
-\end_inset
+DATABANK NAME=gpr2 START=0x200 END=0x2FF
+\layout LyX-Code
- - will stop global common subexpression elimination.
-\layout Itemize
+DATABANK NAME=gpr3 START=0x300 END=0x3FF
+\layout LyX-Code
-NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+DATABANK NAME=gpr4 START=0x400 END=0x4FF
+\layout LyX-Code
-\end_inset
+DATABANK NAME=gpr5 START=0x500 END=0x5FF
+\layout LyX-Code
- - will stop loop induction optimizations.
-\layout Itemize
+ACCESSBANK NAME=accesssfr START=0xF80 END=0xFFF PROTECTED
+\layout LyX-Code
-NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+\layout LyX-Code
-\end_inset
+SECTION NAME=CONFIG ROM=config
+\layout LyX-Code
- - will not generate code for boundary value checking, when switch statements
- are turned into jump-tables (dangerous).
-
-\layout Itemize
+\layout LyX-Code
-NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+SECTION NAME=bank0 RAM=gpr0
+\layout LyX-Code
-\end_inset
+SECTION NAME=bank1 RAM=gpr1
+\layout LyX-Code
- - the compiler will not overlay the parameters and local variables of a
- function.
-\layout Itemize
+SECTION NAME=bank2 RAM=gpr2
+\layout LyX-Code
-LESS_PEDANTIC
-\begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
+SECTION NAME=bank3 RAM=gpr3
+\layout LyX-Code
-\end_inset
+SECTION NAME=bank4 RAM=gpr4
+\layout LyX-Code
- - the compiler will not warn you anymore for obvious mistakes, you'r on
- your own now ;-(
-\layout Itemize
+SECTION NAME=bank5 RAM=gpr5
+\layout Standard
+
+The linker will recognise the section name set in the pragma statement and
+ will position the variable at the memory bank set with the RAM field at
+ the SECTION line in the linker script file.
+\layout Subsection
-NOLOOPREVERSE
-\begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
+Header Files
+\begin_inset LatexCommand \label{sub:PIC16_Header-Files}
\end_inset
- - Will not do loop reversal optimization
-\layout Itemize
-EXCLUDE
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+\layout Standard
-\end_inset
+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
- NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
- pair of push/pop
-\begin_inset LatexCommand \index{push/pop}
+#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
- instruction in ISR function (using interrupt
-\begin_inset LatexCommand \index{interrupt}
+Libraries
+\layout Standard
+
+The libraries that PIC16
+\begin_inset LatexCommand \index{PIC16}
\end_inset
- keyword).
- The directive should be placed immediately before the ISR function definition
- and it affects ALL ISR functions following it.
- To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
-EXCLUDE\SpecialChar ~
-none
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+ port depends on are the microcontroller device libraries which contain
+ the symbol definitions for the microcontroller special function registers.
+ These libraries have the format pic18fxxxx.lib, where
+\emph on
+xxxx
+\emph default
+ is the microcontroller identification number.
+ The specific library is selected automatically by the compiler at link
+ stage according to the selected device.
+\layout Standard
+
+Libraries are created with gplib which is part of the gputils package
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net}
\end_inset
.
-\layout Itemize
+\layout Subsection
-NOIV
-\begin_inset LatexCommand \index{\#pragma NOIV}
+Memory Models
+\layout Standard
-\end_inset
+The following memory models are supported by the PIC16 port:
+\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).
+small model
\layout Itemize
-CALLEE-SAVES
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+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
+\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
-\begin_inset LatexCommand \index{function prologue}
+\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
- 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
+\layout Standard
+
+small model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\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 Standard
-The pragma's are intended to be used to turn-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
+16-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+24-bits
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\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 Subsection
+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
+small model
+\layout Itemize
+
+large model
\layout Standard
+\noun on
+Small
+\noun default
+ model means that only the FSRxL byte is used to access stack and frame,
+ while
+\emph on
+\noun on
+large
+\emph default
+\noun default
+ uses both FSRxL and FSRxH registers.
+ The following table shows the stack/frame pointers sizes according to stack
+ model and the maximum space they can address:
+\layout Standard
+\align center
+
\begin_inset Tabular
-<lyxtabular version="3" rows="10" columns="2">
+<lyxtabular version="3" rows="3" columns="3">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-
-\series bold
-#define
+Stack & Frame pointer sizes according to stack model
\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
+small
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
-\series bold
-Description
+large
\end_inset
</cell>
</row>
\layout Standard
-SDCC
-\begin_inset LatexCommand \index{SDCC}
-
-\end_inset
-
-
+Stack pointer FSR1
\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
+8-bits
\end_inset
</cell>
-</row>
-<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-SDCC_mcs51
-\begin_inset LatexCommand \index{SDCC\_mcs51}
-
+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
- or SDCC_ds390
-\begin_inset LatexCommand \index{SDCC\_ds390}
+\layout Standard
+Frame pointer FSR2
\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}
-
-\end_inset
+\layout Standard
-, etc
+8-bits
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-depending on the model used (e.g.: -mds390
+16-bits
\end_inset
</cell>
</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+</lyxtabular>
+
+\end_inset
+
\layout Standard
-__mcs51
-\begin_inset LatexCommand \index{\_\_mcs51}
+
+\series bold
+Currently stack and frame pointers should be initialized explicit by the
+ user at the desired Data RAM position (see
+\begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
\end_inset
- or __ds390
-\begin_inset LatexCommand \index{\_\_ds390}
+ Pragma stack).
+ Uninitialized stack and frame pointers can result in unexpected behavior
+ of the resulting binary.
+\layout Subsection
-\end_inset
+Function return values
+\layout Standard
- or __z80
-\begin_inset LatexCommand \index{\_\_z80}
+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
-, etc
+\layout Standard
+
+size
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-depending on the model used (e.g.
- -mz80)
+destination register
\end_inset
</cell>
</row>
\layout Standard
-SDCC_STACK_AUTO
-\begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
-
-\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
-
--stack-auto
-\emph default
- option is used
+WREG
\end_inset
</cell>
</row>
\layout Standard
-SDCC_MODEL_SMALL
-\begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
-
-\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-small
-\emph default
- is used
+PRODL:WREG
\end_inset
</cell>
</row>
\layout Standard
-SDCC_MODEL_LARGE
-\begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
-
-\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
-
--model-large
-\emph default
- is used
+PRODH:PRODL:WREG
\end_inset
</cell>
</row>
\layout Standard
-SDCC_USE_XSTACK
-\begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
-
-\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
--
-\begin_inset ERT
-status Collapsed
+FSR0L:PRODH:PRODL:WREG
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+>32 bits
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--xstack
-\emph default
- option is used
+\layout Standard
+
+on stack, FSR0 points to the beginning
\end_inset
</cell>
</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+</lyxtabular>
+
+\end_inset
+
+\layout Subsection
+
+Interrupts
\layout Standard
-SDCC_STACK_TENBIT
-\begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
+When entering an interrupt, currently the PIC16
+\begin_inset LatexCommand \index{PIC16}
\end_inset
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+ 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
-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
+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
-SDCC_MODEL_FLAT24
-\begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
-\end_inset
+\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
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+\layout Chapter
-when
-\emph on
--mds390
-\emph default
- is used
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+Debugging with SDCDB
+\begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
\end_inset
-\newline
-
-\layout Section
-\pagebreak_top
-Debugging with SDCDB
-\begin_inset LatexCommand \index{sdcdb}
+\begin_inset LatexCommand \index{sdcdb (debugger)}
\end_inset
The debugger allows you debug BOTH at the C source and at the ASM source
level.
Sdcdb is available on Unix platforms only.
-\layout Subsection
+\layout Section
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 Subsection
+\layout Section
How the Debugger Works
\layout Standard
\end_inset
-debug option is specified the compiler generates extra symbol information
- some of which are put into the the assembler source and some are put into
- the .adb file.
+ some of which are put into the assembler source and some are put into the
+ .adb file.
Then the linker creates the .cdb file from the individual .adb files with
the address information for the symbols.
The debugger reads the symbolic information generated by the compiler &
execution is controlled by the debugger.
When a command is issued for the debugger, it translates it into appropriate
commands for the simulator.
-\layout Subsection
+\layout Section
Starting the Debugger
\layout Standard
\end_inset
object file.
-\layout Subsection
+\layout Section
Command Line Options.
\layout Itemize
\layout Itemize
-S <serial in,out> passed to simulator see the simulator docs for details.
-\layout Subsection
+\layout Itemize
+
+-k <port number> passed to simulator see the simulator docs for details.
+\layout Section
Debugger Commands.
\layout Standard
\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.
Iam going Down.
My name is Bobby Brown"
-\layout Subsection
+\layout Section
Interfacing with XEmacs
\begin_inset LatexCommand \index{XEmacs}
\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
-\layout Section
+\layout Chapter
\pagebreak_top
TIPS
\layout Standard
Use the smallest data type to represent your data-value.
If it is known in advance that the value is going to be less than 256 then
use an 'unsigned char' instead of a 'short' or 'int'.
+ Please note, that ANSI C requires both signed and unsigned chars to be
+ promoted to 'signed int' before doing any operation.
+ This promotion can be omitted, if the result is the same.
+ The effect of the promotion rules together with the sign-extension is often
+ surprising:
+\begin_deeper
+\layout Verse
+
+
+\family typewriter
+unsigned char uc = 0xfe;
+\newline
+if (uc * uc < 0) /* this is true! */
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....
+\newline
+}
+\layout Standard
+
+
+\family typewriter
+uc * uc
+\family default
+ is evaluated as
+\family typewriter
+(int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
+\family default
+.
+
+\newline
+Another one:
+\layout Verse
+
+
+\family typewriter
+(unsigned char) -12 / (signed char) -3 = ...
+\layout Standard
+
+No, the result is not 4:
+\layout Verse
+
+
+\family typewriter
+(int) (unsigned char) -12 / (int) (signed char) -3 =
+\newline
+(int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
+\newline
+(int) 0x00f4 / (int) 0xfffd =
+\newline
+(int) 0x00f4 / (int) 0xfffd =
+\newline
+(int) 244 / (int) -3 =
+\newline
+(int) -81 = (int) 0xffaf;
+\layout Standard
+
+Don't complain, that gcc gives you a different result.
+ gcc uses 32 bit ints, while SDCC uses 16 bit ints.
+ Therefore the results are different.
+\newline
+From
+\begin_inset Quotes sld
+\end_inset
+
+comp.lang.c FAQ
+\begin_inset Quotes srd
+\end_inset
+
+:
+\layout Quote
+
+If well-defined overflow characteristics are important and negative values
+ are not, or if you want to steer clear of sign-extension problems when
+ manipulating bits or bytes, use one of the corresponding unsigned types.
+ (Beware when mixing signed and unsigned values in expressions, though.)
+\newline
+Although character types (especially unsigned char) can be used as "tiny"
+ integers, doing so is sometimes more trouble than it's worth, due to unpredicta
+ble sign extension and increased code size.
+\end_deeper
\layout Itemize
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
....
\newline
}
-\layout Standard
-
-It would substantially reduce the code generated (future versions of the
- compiler will be smart enough to detect such optimization opportunities).
-\end_deeper
-\layout Itemize
-
-Have a look at the assembly listing to get a
-\begin_inset Quotes sld
-\end_inset
-
-feeling
-\begin_inset Quotes srd
-\end_inset
-
- for the code generation.
-\layout Subsection
-
-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}
-
-\end_inset
-
- variables and,
-\newline
-- Bytes 30-7F - 80 bytes for general purpose use.
-\newline
-
-\layout Standard
-
-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).
-\layout Standard
-
-Normally SDCC will only use the first bank
-\begin_inset LatexCommand \index{bank}
-
-\end_inset
+\layout Standard
- 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}
+It would substantially reduce the code generated (future versions of the
+ compiler will be smart enough to detect such optimization opportunities).
+\end_deeper
+\layout Itemize
+Have a look at the assembly listing to get a
+\begin_inset Quotes sld
\end_inset
- 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}
-
+feeling
+\begin_inset Quotes srd
\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
+ for the code generation.
+\layout Section
-\layout Standard
+Tools
+\begin_inset LatexCommand \index{Tools}
-\backslash
-/
\end_inset
--data-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
-
-\end_inset
+ included in the distribution
+\layout Standard
+\align center
- to specify the start address of the
-\emph on
-data
-\emph default
- and -
-\begin_inset ERT
-status Collapsed
+\begin_inset Tabular
+<lyxtabular version="3" rows="12" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+Name
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--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
+Purpose
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+Directory
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--stack-loc
-\begin_inset LatexCommand \index{-\/-stack-loc}
+\layout Standard
+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
-/
+Simulator for various architectures
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--xdata-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
+\layout Standard
+sdcc/sim/ucsim
\end_inset
-
- to set the start address of the external RAM (
-\emph on
-xdata
-\emph default
-) and -
-\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
-/
+keil2sdcc.pl
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--xram-size
-\begin_inset LatexCommand \index{-\/-data-loc}
+\layout Standard
+header file conversion
\end_inset
-
- to specify its size.
- Same goes for the code memory, using -
-\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
-/
+sdcc/support/scripts
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
--code-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
+\layout Standard
+mh2h.c
\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 Subsection
+as-gbz80
+\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
+Assembler
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- included in the distribution
\layout Standard
-\align center
-\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">
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
+as-z80
\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
+asx8051
\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
+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
-mh2h.c
+aslink
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-header file conversion
+Linker
\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
+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
-as-z80
+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
-asx8051
+packihx
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Assembler
+ihx packer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\end_inset
</cell>
</row>
-<row topline="true">
+</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
-sdcdb
+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
-Simulator
+SDCC Compiler User Guide
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\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
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+\layout Standard
+
+sdcc/Changelog
\end_inset
</cell>
</row>
\layout Standard
-aslink
+ASXXXX Assemblers and ASLINK 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
-Linker
+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">
\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
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+\layout Standard
+
+Various notes
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/doc/*
\end_inset
</cell>
</row>
\layout Standard
-link-z80
+Notes on debugging with sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/debugger/README
\end_inset
</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-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
+Temporary notes on the pic16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/src/pic16/NOTES
\end_inset
</cell>
+</row>
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Linker
+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>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\layout Section
+
+Related open source tools
+\begin_inset LatexCommand \index{Related tools}
+
+\end_inset
+
+
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="block" valignment="top" leftline="true" width="30line%">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-packihx
+Name
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-ihx packer
+Purpose
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
+Where to get
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+gpsim
+\begin_inset LatexCommand \index{gpsim (pic simulator)}
+
+\end_inset
+
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
</cell>
-</row>
-</lyxtabular>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\end_inset
+\layout Standard
+PIC simulator
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\layout Subsection
-Related open source tools
-\begin_inset LatexCommand \index{Related tools}
+\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
\end_inset
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="8" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="block" valignment="top" leftline="true" width="30line%">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
+\end_inset
+</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
+gputils
+\begin_inset LatexCommand \index{gputils (pic tools)}
+
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Purpose
+GNU PIC utilities
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Where to get
+
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-gpsim
-\begin_inset LatexCommand \index{gpsim}
-
-\end_inset
-
-
+flP5
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-PIC simulator
+PIC programmer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
+\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
\end_inset
\layout Standard
-flP5
+indent
+\begin_inset LatexCommand \index{indent (source formatting tool)}
+
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-PIC programmer
+Formats C source - Master of the white spaces
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
+\begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
\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
\newline
-\layout Subsection
+\layout Section
Related documentation / recommended reading
\layout Standard
\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
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+c-refcard.pdf
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Advanced Compiler Design and Implementation
+C Reference Card
+\begin_inset LatexCommand \index{C Reference card}
+
+\end_inset
+
+, 2 pages
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-bookstore
+
+\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-c-refcard.pdf
+c-faq
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-C Reference Card
-\begin_inset LatexCommand \index{C Reference card}
-
-\end_inset
-
-, 2 pages
+C-FAQ-list
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
+\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
\end_inset
\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
-\pagebreak_top
+
+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
+
Support
\begin_inset LatexCommand \index{Support}
\layout Standard
-The SDCC project is hosted on the sdcc sourceforge site at
+The SDCC project is hosted on the SDCC sourceforge site at
\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
\end_inset
.
You'll find the complete set of mailing lists
-\begin_inset LatexCommand \index{Mailing list}
+\begin_inset LatexCommand \index{Mailing list(s)}
\end_inset
\end_inset
there.
-\layout Subsection
+\layout Section
Reporting Bugs
-\begin_inset LatexCommand \index{Bugs}
+\begin_inset LatexCommand \index{Bug reporting}
\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
.
-\layout Subsection
+\layout Section
Requesting Features
\begin_inset LatexCommand \label{sub:Requesting-Features}
\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
+\family default
+\series default
+ will be fine, otherwise
+\family sans
+\series bold
-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}
+\begin_inset Quotes sld
+\end_inset
+diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
+\begin_inset Quotes srd
\end_inset
-.
-\layout Subsection
+
+\series default
+
+\family default
+will do.
+\layout Section
Getting Help
\layout Standard
\end_inset
-, lists and forums are archived so if you are lucky someone already had
- a similar problem.
-\layout Subsection
-
-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 Subsection
+.
+\layout Section
Release policy
\begin_inset LatexCommand \index{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}
\end_inset
.
-\layout Subsection
+\layout Section
Examples
\begin_inset LatexCommand \index{Examples}
\layout Standard
-You'll find some small examples in the directory sdcc/device/examples/
+You'll find some small examples in the directory
+\emph on
+sdcc/device/examples/.
+
+\emph default
+More examples and libraries are available at
+\emph on
+ The SDCC Open Knowledge Resource
+\begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
+
+\end_inset
+
+
+\emph default
+web site or at
+\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
+
+\end_inset
+
+.
+\layout Comment
+
+I did insert a reference to Paul's web site here although it seems rather
+ dedicated to a specific 8032 board (I think it's okay because it f.e.
+ shows LCD/Harddisc interface and has a free 8051 monitor.
+ Independent 8032 board vendors face hard competition of heavily subsidized
+ development boards anyway).
\layout Comment
Maybe we should include some links to real world applications.
Preferably pointer to pointers (one for each architecture) so this stays
manageable here?
-\layout Subsection
+\layout Section
Quality control
\begin_inset LatexCommand \index{Quality control}
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}
sdcc/src/regression
\shape default
.
-\layout Section
+\layout Chapter
\pagebreak_top
SDCC Technical Data
-\layout Subsection
+\layout Section
Optimizations
\begin_inset LatexCommand \index{Optimizations}
SDCC performs a host of standard optimizations in addition to some MCU specific
optimizations.
-\layout Subsubsection
+\layout Subsection
Sub-expression Elimination
\begin_inset LatexCommand \index{Subexpression elimination}
\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
\layout Standard
The compiler will try to keep these temporary variables in registers.
-\layout Subsubsection
+\layout Subsection
Dead-Code Elimination
\begin_inset LatexCommand \index{Dead-code elimination}
return;
\newline
}
-\layout Subsubsection
+\layout Subsection
Copy-Propagation
\begin_inset LatexCommand \index{Copy propagation}
Note: the dead stores created by this copy propagation will be eliminated
by dead-code elimination.
-\layout Subsubsection
+\layout Subsection
Loop Optimizations
\begin_inset LatexCommand \index{Loop optimization}
\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
\end_inset
is changed to a less expensive addition.
-\layout Subsubsection
+\layout Subsection
Loop Reversing
\begin_inset LatexCommand \index{Loop reversing}
\layout Itemize
There are NO switch statements in the loop.
-\layout Subsubsection
+\layout Subsection
Algebraic Simplifications
\layout Standard
\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
given above are generally introduced by macro expansions or as a result
of copy/constant propagation.
-\layout Subsubsection
+\layout Subsection
'switch' Statements
+\begin_inset LatexCommand \label{sub:'switch'-Statements}
+
+\end_inset
+
+
\begin_inset LatexCommand \index{switch statement}
\end_inset
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.
- The pragma NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+ You might also consider inserting dummy cases 0 and 5 to 8 in this example.
+
+\newline
+The pragma nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
\end_inset
bound
\emph default
aries.
-\layout Subsubsection
+ It has no effect if a default label is supplied.
+ Use of this pragma is dangerous: if the switch argument is not matched
+ by a case statement the processor will happily jump into Nirvana.
+\layout Subsection
Bit-shifting Operations
\begin_inset LatexCommand \index{Bit shifting}
mov\SpecialChar ~
\SpecialChar ~
_i,a
-\layout Standard
-
-Note that SDCC stores numbers in little-endian
-\begin_inset LatexCommand \index{little-endian}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{Endianness}
-
-\end_inset
-
- format (i.e.
- lowest order first).
-\layout Subsubsection
+\layout Subsection
Bit-rotation
\begin_inset LatexCommand \index{Bit rotation}
\layout Standard
-A special case of the bit-shift operation is bit rotation, SDCC recognizes
- the following expression to be a left bit-rotation:
+A special case of the bit-shift operation is bit rotation
+\begin_inset LatexCommand \index{rotating bits}
+
+\end_inset
+
+, SDCC recognizes the following expression to be a left bit-rotation:
\layout Verse
\family typewriter
-unsigned char i;
+\series bold
+unsigned
+\series default
+\SpecialChar ~
+\SpecialChar ~
+char i;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* unsigned is needed for rotation */
\newline
...
_i,a
\layout Standard
-SDCC uses pattern matching on the parse tree to determine this operation.Variatio
-ns of this case will also be recognized as bit-rotation, i.e.:
-\layout Verse
+SDCC uses pattern matching on the parse tree to determine this operation.Variatio
+ns of this case will also be recognized as bit-rotation, i.e.:
+\layout Verse
+
+
+\family typewriter
+i = ((i >> 7) | (i << 1)); /* left-bit rotation */
+\layout Subsection
+
+Nibble and Byte Swapping
+\layout Standard
+
+Other special cases of the bit-shift operations are nibble or byte swapping
+\begin_inset LatexCommand \index{swapping nibbles/bytes}
+
+\end_inset
+
+, SDCC recognizes the following expressions:
+\layout Verse
+
+
+\family typewriter
+\series bold
+unsigned
+\series default
+\SpecialChar ~
+\SpecialChar ~
+char i;
+\newline
+
+\series bold
+unsigned
+\series default
+\SpecialChar ~
+\SpecialChar ~
+int j;
+\newline
+...
+
+\newline
+i = ((i << 4) | (i >> 4));
+\family default
+
+\newline
+
+\family typewriter
+j = ((j << 8) | (j >> 8));
+\layout Standard
+
+and generates a swap instruction for the nibble swapping
+\begin_inset LatexCommand \index{Nibble swapping}
+
+\end_inset
+
+ or move instructions for the byte swapping
+\begin_inset LatexCommand \index{Byte swapping}
+
+\end_inset
+
+.
+ The
+\begin_inset Quotes sld
+\end_inset
+
+j
+\begin_inset Quotes srd
+\end_inset
+
+ example can be used to convert from little to big-endian or vice versa.
+ If you want to change the endianness of a
+\emph on
+signed
+\emph default
+ integer you have to cast to
+\family typewriter
+(unsigned int)
+\family default
+ first.
+\layout Standard
+
+Note that SDCC stores numbers in little-endian
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+Usually 8-bit processors don't care much about endianness.
+ This is not the case for the standard 8051 which only has an instruction
+ to increment its
+\emph on
+dptr
+\emph default
+
+\begin_inset LatexCommand \index{DPTR}
+
+\end_inset
+
+-datapointer
+\emph on
+
+\emph default
+so little-endian is the more efficient byte order.
+\end_inset
+
+
+\begin_inset LatexCommand \index{little-endian}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Endianness}
+\end_inset
-\family typewriter
-i = ((i >> 7) | (i << 1)); /* left-bit rotation */
-\layout Subsubsection
+ format (i.e.
+ lowest order first).
+\layout Subsection
Highest Order Bit
\begin_inset LatexCommand \index{Highest Order Bit}
\layout Standard
will still be recognized.
-\layout Subsubsection
+\layout Subsection
Peephole Optimizer
+\begin_inset LatexCommand \label{sub:Peephole-Optimizer}
+
+\end_inset
+
+
\begin_inset LatexCommand \index{Peephole optimizer}
\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
\end_inset
-peep-file option.
-\layout Subsection
-
-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 Subsection
-
-External Stack
-\begin_inset LatexCommand \label{sub:External-Stack}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{stack}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{External stack}
-
-\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 at the start of the external ram segment, and is 256 bytes
- in size.
- When -
-\begin_inset ERT
-status Collapsed
+\layout Section
-\layout Standard
+ANSI-Compliance
+\begin_inset LatexCommand \index{ANSI-compliance}
-\backslash
-/
\end_inset
--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 -
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\begin_inset LatexCommand \label{sub:ANSI-Compliance}
-\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).
\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.
-\layout Subsection
+Deviations from the compliance:
+\layout Itemize
-ANSI-Compliance
-\begin_inset LatexCommand \index{ANSI-compliance}
+functions are not always reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
-
-\layout Standard
-
-Deviations from the compliance:
-\layout Itemize
-
-functions are not always reentrant.
+.
\layout Itemize
structures cannot be assigned values directly, cannot be passed as function
not supported.
\layout Itemize
-No support for setjmp and longjmp (for now).
+No support for setjmp
+\begin_inset LatexCommand \index{setjmp (not supported)}
+
+\end_inset
+
+ and longjmp
+\begin_inset LatexCommand \index{longjmp (not supported)}
+
+\end_inset
+
+ (for now).
\layout Itemize
Old K&R style
\newline
}
\end_deeper
-\layout Itemize
-
-functions declared as pointers 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 Subsection
+\layout Section
Cyclomatic Complexity
\begin_inset LatexCommand \index{Cyclomatic complexity}
The complexity level is by no means an absolute measure of the algorithmic
complexity of the function, it does however provide a good starting point
for which functions you might look at for further optimization.
-\layout Subsection
-
-Other Processors
-\layout Subsubsection
-
-MCS51 variants
-\begin_inset LatexCommand \index{MCS51 variants}
-
-\end_inset
-
-
-\layout Standard
-
-MCS51 processors are available from many vendors and come in many different
- flavours.
- While they might differ considerably in respect to Special Function Registers
- the core MCS51 is usually not modified or is kept compatible.
-
-\layout Subsubsection*
-
-pdata access by SFR
-\layout Standard
-
-With the upcome of devices with internal xdata and flash memory devices
- using port P2 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 Subsubsection
-
-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{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.
-\layout Standard
-
-As always, the code is the authoritative reference - see z80/ralloc.c and
- z80/gen.c.
- The stack 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 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
+\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
As mentioned in the optimization section the peep-hole optimizer is rule
based system, which can reprogrammed for other MCUs.
-\layout Section
-\pagebreak_top
+\layout Chapter
+
Compiler internals
\begin_inset LatexCommand \index{Compiler internals}
\end_inset
-\layout Subsection
+\layout Section
The anatomy of the compiler
+\begin_inset LatexCommand \label{sub:The-anatomy-of}
+
+\end_inset
+
+
\layout Standard
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
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
ret
\newline
-\layout Subsection
+\layout Section
A few words about basic block successors, predecessors and dominators
\layout Standard
c) domVect of [BB4] = BB1 ...
here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
was executed.
-\layout Section
+\layout Chapter
Acknowledgments
\layout Standard
of their respective companies.
-\layout Section
+\layout Section*
Alphabetical index
\layout Standard
-To avoid confusion, the installation and building options for sdcc itself
+To avoid confusion, the installation and building options for SDCC itself
(chapter 2) are not part of the index.
\layout Standard
projects / fw / sdcc / blobdiff