#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}
\date{}
\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 Title
SDCC Compiler User Guide
-\layout Comment
+\layout Date
-The strings enclosed in $ are automatically updated by cvs:
-\layout Standard
-\align center
+\size normal
+2.3.6
\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
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
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
-\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
\layout Standard
..
-\backslash
-
\end_inset
</cell>
</row>
\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
+\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}
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
+\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
Win32-binary can be built, which will not need the Cygwin-DLL.
For the necessary 'configure' options see section 'configure options' or
- the script 'sdcc/support/scripts/sdcc_cygwinmingw32'.
+ the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
\newline
\newline
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
+\layout Subsection
Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
\layout Standard
\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}
\layout Enumerate
-Download the binary package and unpack it using your favorite unpacking
- tool (gunzip, WinZip, etc).
+Download the binary package from
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
+
+\end_inset
+
+ and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
This should unpack to a group of sub-directories.
An example directory structure after unpacking the mingw32 package is:
c:
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
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}
+\begin_inset LatexCommand \url{http://www.knoppix.net}
\end_inset
.
-\layout Subsection
+ Prebuilt documentation in html and pdf format is available from
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
+
+\end_inset
+
+.
+\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.
+\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, PIC 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
\layout Standard
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
\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.
\layout Standard
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
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}
The 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
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
\begin_inset LatexCommand \index{s51}
.
It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
XA51 family.
-\layout Subsubsection
+\layout Subsection
sdcdb
\begin_inset LatexCommand \index{sdcdb}
\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
\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
\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
\layout Itemize
sourcefile.cdb
-\begin_inset LatexCommand \index{.cdb}
+\begin_inset LatexCommand \index{<file>.cdb}
\end_inset
sourcefile.
- (no extension)
-\begin_inset LatexCommand \index{. (no extension)}
+\begin_inset LatexCommand \index{<file> (no extension)}
\end_inset
\layout Itemize
sourcefile.dump*
-\begin_inset LatexCommand \index{.dump*}
+\begin_inset LatexCommand \index{<file>.dump*}
\end_inset
\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
\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
+ The linker is invoked from SDCC using a script file with extension .lnk
\begin_inset LatexCommand \index{.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}
libsdcc.lib
\emph default
in the directory <installdir>/share/lib/small.
-\layout Subsection
+\layout Section
Command Line Options
\begin_inset LatexCommand \index{Command Line Options}
\end_inset
-\layout Subsubsection
+\layout Subsection
Processor Selection Options
\begin_inset LatexCommand \index{Options processor selection}
\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}
\series default
Generate code for the GameBoy Z80
-\begin_inset LatexCommand \index{GameBoy Z80}
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
\end_inset
\end_inset
processor (In development, not complete).
-\layout Subsubsection
+\layout Subsection
Preprocessor Options
\begin_inset LatexCommand \index{Options preprocessor}
\bar default
Like `-dD' except that the macro arguments and contents are omitted.
Only `#define name' is included in the output.
-\layout Subsubsection
-
-Linker Options
-\begin_inset LatexCommand \index{Options linker}
+\layout List
+\labelwidthstring 00.00.0000
-\end_inset
+\series bold
+-Wp\SpecialChar ~
+preprocessorOption[,preprocessorOption]
+\series default
-\begin_inset LatexCommand \index{Linker options}
+\begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
\end_inset
-
+...
+ Pass the preprocessorOption to the preprocessor.
+\layout Subsection
+
+Linker Options
+\begin_inset LatexCommand \index{Options linker}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Linker options}
+
+\end_inset
+
+
\layout List
\labelwidthstring 00.00.0000
\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}
-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}
-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}
\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
.
-\layout Subsubsection
+\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.
+\layout Subsection
MCS51 Options
\begin_inset LatexCommand \index{Options MCS51}
\series default
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 Subsection
DS390 Options
\begin_inset LatexCommand \index{Options DS390}
\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}
\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}
\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
+\layout Subsection
Other Options
\begin_inset LatexCommand \index{Options other}
\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
-.See section Installation for more details.
+.
+ See section Installation for more details.
\layout List
\labelwidthstring 00.00.0000
\end_inset
function.
- The default option is to lock up i.e.
- generate a 'ljmp '.
+ The default setting is to lock up i.e.
+ generate a '
+\family typewriter
+ljmp .
+\family default
+'.
\layout List
\labelwidthstring 00.00.0000
\end_inset
+\SpecialChar ~
<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.
+ 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 default
- Disable peep-hole optimization.
+ Disable peep-hole optimization.
\layout List
\labelwidthstring 00.00.0000
\series default
- Disable some of the more pedantic warnings (jwk burps: please be more specific
- here, please!)
+ Disable some of the more pedantic warnings
+\begin_inset LatexCommand \index{Warnings}
+
+\end_inset
+
+ (jwk burps: please be more specific here, please!).
+ If you want rather more than less warnings you should consider using a
+ separate tool dedicated to syntax checking like
+\begin_inset LatexCommand \url{www.splint.org}
+
+\end_inset
+
+.
\layout List
\labelwidthstring 00.00.0000
\series default
Send errors and warnings to stdout instead of stderr.
-\layout Subsubsection
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-Wa\SpecialChar ~
+asmOption[,asmOption]
+\series default
+
+\begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
+
+\end_inset
+
+...
+ Pass the asmOption to the assembler.
+\layout Subsection
Intermediate Dump Options
+\begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
+
+\end_inset
+
+
\begin_inset LatexCommand \index{Options intermediate dump}
\end_inset
\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
\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
\series bold
default
\series default
- storage class for Small Memory model.
+ storage class for the Small Memory model.
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
\series bold
default
\series default
- storage class for Large Memory model, e.g.:
+ storage class for the Large Memory model, e.g.:
\layout Verse
\SpecialChar ~
mov\SpecialChar ~
\SpecialChar ~
-@r0,#0x01
-\layout Subsubsection
+@r0,#0x01
+\layout Standard
-pdata
-\begin_inset LatexCommand \index{pdata}
+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}
\end_inset
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).
+ 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 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.
+
+\layout Standard
+
+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
+
+.
\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
\family typewriter
-/* pointer physically in xternal ram pointing to object in internal ram
+/* pointer physically in internal ram pointing to object in external ram
+ */
+\newline
+xdata unsigned char * data p;
+\newline
+
+\newline
+/* pointer physically in external ram pointing to object in internal ram
*/
\newline
data unsigned char * xdata p;
code.
\layout Subsection
+Z80/Z180 Storage Class
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ Language Extensions
+\layout Subsubsection
+
+sfr
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+ (in/out to 8-bit addresses)
+\layout Standard
+
+The Z80
+\begin_inset LatexCommand \index{Z80}
+
+\end_inset
+
+ family has separate address spaces for memory and
+\emph on
+i
+\emph default
+nput/
+\emph on
+o
+\emph default
+utput memory.
+ I/O memory
+\begin_inset LatexCommand \index{I/O memory (Z80/Z180)}
+
+\end_inset
+
+ is accessed with special instructions, e.g.:
+\layout Verse
+
+
+\family typewriter
+sfr at 0x78 IoPort;\SpecialChar ~
+\SpecialChar ~
+/* define a var in I/O space at 78h called IoPort */
+
+\layout Standard
+
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
+
+
+\family typewriter
+3E 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ld a,#0x01
+\newline
+D3 78\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out (_IoPort),a
+\layout Subsubsection
+
+banked sfr
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+ (in/out to 16-bit addresses)
+\layout Standard
+
+The keyword
+\emph on
+banked
+\emph default
+ is used to support 16 bit addresses in I/O memory e.g.:
+\layout Verse
+
+
+\family typewriter
+sfr banked at 0x123 IoPort;
+\layout Standard
+
+Writing 0x01 to this variable generates the assembly code:
+\layout Verse
+
+
+\family typewriter
+01 23 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ld bc,#_IoPort
+\newline
+3E 01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ld a,#0x01
+\newline
+ED 79\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+out (c),a
+\layout Subsubsection
+
+sfr
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+ (in0/out0 to 8 bit addresses on Z180
+\begin_inset LatexCommand \index{Z180}
+
+\end_inset
+
+/HD64180
+\begin_inset LatexCommand \index{HD64180}
+
+\end_inset
+
+)
+\layout Standard
+
+The compiler option -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\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 Section
+
Absolute Addressing
\begin_inset LatexCommand \index{Absolute addressing}
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).
+ The compiler does
+\emph on
+not
+\emph default
+ 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}
+\begin_inset LatexCommand \index{<file>.lst}
\end_inset
) and the linker output files (.rst
-\begin_inset LatexCommand \index{.rst}
+\begin_inset LatexCommand \index{<file>.rst}
\end_inset
) and (.map
-\begin_inset LatexCommand \index{.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
+ initialized.
\layout Standard
In case of memory mapped I/O devices the keyword
\SpecialChar ~
/* I/O port 1, bit 1 */
\newline
-bit CPOL;\SpecialChar ~
+bit
+\begin_inset LatexCommand \index{bit}
+
+\end_inset
+
+ CPOL;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
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
+\layout Section
Parameters
\begin_inset LatexCommand \index{Parameters}
+\end_inset
+
+
+\begin_inset LatexCommand \index{function parameter}
+
\end_inset
& Local Variables
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
+ This in fact makes them similar to
\emph on
static
\begin_inset LatexCommand \index{static}
\end_inset
.
+
\newline
\newline
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
+Parameters
+\begin_inset LatexCommand \index{function parameter}
+
+\end_inset
+
+ however are not allowed any storage class
+\begin_inset LatexCommand \index{storage class}
+
+\end_inset
+
+, (storage classes for parameters will be ignored), their allocation is
+ governed by the memory model in use, and the reentrancy options.
+\layout Section
Overlaying
\begin_inset LatexCommand \label{sub:Overlaying}
if they are not reentrant.
\layout Standard
-Also note that the compiler does not do any processing of inline
-\begin_inset LatexCommand \index{inline}
-
-\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.
+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
-Parameters and Local variables of functions that contain 16 or 32 bit multiplica
+Parameters and local variables of functions that contain 16 or 32 bit multiplica
tion
\begin_inset LatexCommand \index{Multiplication}
The #pragma\SpecialChar ~
NOOVERLAY ensures that the parameters and local variables for
the function are NOT overlayed.
-\layout Subsection
+\layout Section
Interrupt Service Routines
+\begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
+
+\end_inset
+
+
\layout Standard
SDCC allows interrupt service routines to be coded in C, with some extended
\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}
+
+\newline
-\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}
-
-\end_inset
-
-.
-
-\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
-
- 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-ren
-\emph default
-t
-\begin_inset LatexCommand \index{-\/-int-long-rent}
-
-\end_inset
-
- compiler option.
-\layout Standard
+\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
This scheme is recommended for larger interrupt service routines.
\layout Standard
+Using interrupts opens the door for some very interesting bugs:
+\layout Standard
+
+If the interrupt service routines changes variables which are accessed by
+ other functions these variables should be declared
+\emph on
+volatile
+\emph default
+
+\begin_inset LatexCommand \index{volatile}
+
+\end_inset
+
+.
+ 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 disabled
+ during the access to avoid inconsistent data.
+ Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
+ and should be protected by disabling interrupts.
+ You're not automatically on the safe side if you use 8 bit variables though.
+ We need an example here: f.e.
+ on the 8051 the harmless looking
+\begin_inset Quotes srd
+\end_inset
+
+
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x80;
+\family default
+
+\begin_inset Quotes sld
+\end_inset
+
+ is not atomic if
+\family typewriter
+flags
+\family default
+ resides in xdata.
+ Setting
+\begin_inset Quotes srd
+\end_inset
+
+
+\family typewriter
+flags\SpecialChar ~
+|=\SpecialChar ~
+0x40;
+\family default
+
+\begin_inset Quotes sld
+\end_inset
+
+ from within an interrupt routine might get lost if the interrupt occurs
+ at the wrong time.
+
+\begin_inset Quotes sld
+\end_inset
+
+
+\family typewriter
+counter\SpecialChar ~
++=\SpecialChar ~
+8;
+\family default
+
+\begin_inset Quotes srd
+\end_inset
+
+ is not atomic on the 8051 even if
+\family typewriter
+counter
+\family default
+ is located in data memory.
+ Bugs like these are hard to reproduce and can cause a lot of trouble.
+
+\layout Standard
+
+A special note here, int (16 bit) and long (32 bit) integer division
+\begin_inset LatexCommand \index{Division}
+
+\end_inset
+
+, multiplication
+\begin_inset LatexCommand \index{Multiplication}
+
+\end_inset
+
+ & modulus
+\begin_inset LatexCommand \index{Modulus}
+
+\end_inset
+
+ and floating-point
+\begin_inset LatexCommand \index{Floating point support}
+
+\end_inset
+
+ operations are implemented using external support routines developed in
+ ANSI-C.
+ If an interrupt service routine needs to do any of these operations then
+ the support routines (as mentioned in a following section) will have to
+ be recompiled using the
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
+
+\end_inset
+
+
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-int-long-reent
+\emph default
+
+\begin_inset LatexCommand \index{-\/-int-long-reent}
+
+\end_inset
+
+ compiler option.
+\layout Standard
+
Calling other functions from an interrupt service routine is not recommended,
avoid it if possible.
+ Note that when some function is called from an interrupt service routine
+ it should be preceded by a #pragma\SpecialChar ~
+NOOVERLAY
+\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+
+\end_inset
+
+ if it is not reentrant.
+ Furthermore nonreentrant functions should not be called from the main program
+ while the interrupt service routine might be active.
+
+\newline
+
\newline
-For some pitfalls see section
+Also see section
\begin_inset LatexCommand \ref{sub:Overlaying}
\end_inset
+\SpecialChar ~
about Overlaying and section
\begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
\end_inset
+\SpecialChar ~
about Functions using private banks.
-\newline
+\layout Section
+Enabling and Disabling Interrupts
\layout Subsection
-Critical Functions
+Critical Functions and Critical Statements
\layout Standard
-
-\shape italic
-<TODO: this isn't implemented at all!>
-\shape default
-
-\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.
+ 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
+int foo () critical
+\begin_inset LatexCommand \index{critical}
+
+\end_inset
+
+
\newline
{
\newline
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
-Naked Functions
-\begin_inset LatexCommand \label{sub:Naked-Functions}
+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
-\begin_inset LatexCommand \index{Naked functions}
-\end_inset
+\family typewriter
+EA = 0;
+\layout Verse
+
+
+\family typewriter
+...
+\layout Verse
+\family typewriter
+EA = 1;
\layout Standard
-A special keyword may be associated with a function declaring it as
-\emph on
-_naked
-\begin_inset LatexCommand \index{\_naked}
+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
-.
-
-\emph default
-The
+ (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.
+ 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 architectures which don't support interrupt priorities these can be
+ implemented by manipulating the interrupt mask and reenabling interrupts
+ within the interrupt routine.
+ Don't add complexity unless you have to.
+
+\layout Section
+
+Functions using private banks
+\begin_inset LatexCommand \label{sub:Functions-using-private-banks}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{bank}
+
+\end_inset
+
+
+\layout Standard
+
+The
+\emph on
+using
+\begin_inset LatexCommand \index{using}
+
+\end_inset
+
+
+\emph default
+ attribute (which tells the compiler to use a register bank other than the
+ default bank zero) should only be applied to
+\emph on
+interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\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.
+\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.
+ 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
+\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.
+ This is a buffer routine which should be optimized:
+\layout Verse
+
+
+\family typewriter
+\size footnotesize
+unsigned char xdata at 0x7f00 buf[0x100];
+\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;
+\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
+ret 00106$:
+\newline
+;buffer.c buf[ head++ ] = c;
+\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 ~
+a,r3
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add\SpecialChar ~
+\SpecialChar ~
+a,#_buf
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+clr\SpecialChar ~
+\SpecialChar ~
+a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+addc\SpecialChar ~
+a,#(_buf >> 8)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+dph,a
+\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
+ and finally have:
+\layout Verse
+
+
+\family typewriter
+\size footnotesize
+unsigned char xdata at 0x7f00 buf[0x100];
+\newline
+unsigned char head,tail;
+\newline
+#define USE_ASSEMBLY
+\newline
+
+\newline
+#ifndef USE_ASSEMBLY
+\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.
+\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 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
+
+\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
+ carefully 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
\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
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-reti\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-; MUST explicitly include ret or reti in _naked function.
-\layout Standard
-
-The #pragma directive EXCLUDE
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
-
-\end_inset
-
- also allows to reduce pushing & popping the registers.
-\layout Standard
-
-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
-
-Functions using private banks
-\begin_inset LatexCommand \label{sub:Functions-using-private-banks}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{bank}
-
-\end_inset
-
-
-\layout Standard
-
-The
-\emph on
-using
-\begin_inset LatexCommand \index{using}
-
-\end_inset
-
-
-\emph default
- attribute (which tells the compiler to use a register bank other than the
- default bank zero) should only be applied to
-\emph on
-interrupt
-\begin_inset LatexCommand \index{interrupt}
-
-\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.
-\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
-
-).
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dph
\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.
+\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
-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
-
-Startup Code
-\begin_inset LatexCommand \index{Startup code}
-
-\end_inset
+whereas nakedInterrupt looks like:
+\layout Verse
+\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
-The compiler inserts a call to the C routine
-\emph on
-_sdcc_external_startup()
-\begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
+The #pragma directive EXCLUDE
+\begin_inset LatexCommand \index{\#pragma EXCLUDE}
\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}
+ allows a more fine grained control over pushing & popping
+\begin_inset LatexCommand \index{push/pop}
\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.
- See also the compiler option
-\emph on
--
-\begin_inset ERT
-status Collapsed
-
+ the registers.
\layout Standard
-\backslash
-/
-\end_inset
-
--no-xinit
-\emph default
--
-\emph on
-opt
-\emph default
-
-\begin_inset LatexCommand \index{-\/-no-xinit-opt}
-
-\end_inset
-
-.
+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
-Inline Assembler Code
-\begin_inset LatexCommand \index{Assembler routines}
-
-\end_inset
-
-
+Use of Labels within Inline Assembler
\layout Standard
SDCC allows the use of in-line assembler with a few restriction as regards
labels.
- All labels defined within inline assembler code
+ In older versions of the compiler all labels defined within inline assembler
+ code
\emph on
-has to be
+had to be
\emph default
of the form
\emph 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
-
-\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
-
-.
- This 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
- carefully before using this option.
+
\layout Verse
;
\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}
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.
-\layout Standard
-
-An example acessing a C variable is in section
-\begin_inset LatexCommand \ref{sub:Naked-Functions}
-
-\end_inset
-
-.
-\layout Subsection
+ 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 Subsubsection
+\layout Subsection
Global Registers used for Parameter Passing
\begin_inset LatexCommand \index{Parameter passing}
\end_inset
+
+\begin_inset LatexCommand \index{DPTR}
+
+\end_inset
+
, B
\begin_inset LatexCommand \index{B (register)}
-stack-auto is used) or in data / xdata memory (depending on the memory
model).
-\layout Subsubsection
+\layout Subsection
Assembler Routine(non-reentrant
\begin_inset LatexCommand \index{reentrant}
\layout Standard
In the following example the function c_func calls an assembler routine
- asm_func, which takes two parameters.
+ asm_func, which takes two parameters
+\begin_inset LatexCommand \index{function parameter}
+
+\end_inset
+
+.
\layout Verse
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-.ds 1
+.ds 1
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-dpl
+dph
\begin_inset LatexCommand \index{DPTR, DPH, DPL}
\end_inset
ret
\layout Standard
-Note here that the return values are placed in 'dpl' - One byte return value,
- 'dpl' LSB & 'dph' MSB for two byte values.
+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
\family sans
\series bold
sdcc cfunc.c asmfunc.rel
-\layout Subsubsection
+\layout Subsection
Assembler Routine(reentrant
\begin_inset LatexCommand \index{reentrant}
\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.
+In this case the second parameter
+\begin_inset LatexCommand \index{function parameter}
+
+\end_inset
+
+ onwards will be passed on the stack, the parameters are pushed from right
+ to left i.e.
after the call the left most parameter will be on the top of the stack.
Here is an example:
\layout Verse
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
+\layout Section
int (16 bit)
\begin_inset LatexCommand \index{int (16 bit)}
\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)">
+<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
/
\end_inset
--int-long-rent
-\begin_inset LatexCommand \index{-\/-int-long-rent}
+-int-long-reent
+\begin_inset LatexCommand \index{-\/-int-long-reent}
\end_inset
\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
+ The compiler will use them automatically every time an integer operation
is required.
-\layout Subsection
+\layout Section
Floating Point Support
\begin_inset LatexCommand \index{Floating point support}
\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
+ floating point support routines are derived from gcc's floatlib.c and consist
of the following routines:
\newline
\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)">
+<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
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
+\layout Section
MCS51 Memory Models
\begin_inset LatexCommand \index{Memory 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
+\layout Section
DS390 Memory Models
\begin_inset LatexCommand \index{Memory model}
\emph on
-Wl-r
\emph default
- on the sdcc command line.
+ on the SDCC command line.
However, currently the linker can not handle code segments > 64k.
-\layout Subsection
+\layout Section
Pragmas
\begin_inset LatexCommand \index{Pragmas}
- 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
NOOVERLAY
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
CALLEE-SAVES
\end_inset
is appended to the list of functions specified in the command line.
+\layout Itemize
+
+preproc_asm
+\begin_inset LatexCommand \index{\#pragma preproc\_asm}
+
+\end_inset
+
+ (+ | -) - switch _asm _endasm block preprocessing on / off.
+ Default is on.
\layout Standard
-The pragma's are intended to be used to turn-off certain optimizations which
- might cause the compiler to generate extra stack / data space to store
- compiler generated temporary variables.
+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
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
+\layout Section
Defines Created by the Compiler
\begin_inset LatexCommand \index{Defines created by the compiler}
\begin_inset Tabular
<lyxtabular version="3" rows="10" 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)">
+<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
\end_inset
- or __ds390
+, __ds390
\begin_inset LatexCommand \index{\_\_ds390}
\end_inset
- or __z80
+, __hc08
+\begin_inset LatexCommand \index{\_\_hc08}
+
+\end_inset
+
+, __z80
\begin_inset LatexCommand \index{\_\_z80}
\end_inset
\newline
-\layout Section
-\pagebreak_top
+\layout Chapter
+
Debugging with SDCDB
\begin_inset LatexCommand \index{sdcdb}
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 complier generates a .adb file for each of these files.
The linker creates the .cdb file from the .adb 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
"Watch me now.
Iam going Down.
My name is Bobby Brown"
-\layout Subsection
+\layout Section
Interfacing with XEmacs
\begin_inset LatexCommand \index{XEmacs}
;;
\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
+ supprising:
+\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
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char ch1 = p1 % ch ;
+unsigned char ch1 = p1 * ch ;
\newline
\SpecialChar ~
\SpecialChar ~
}
\layout Standard
-For the modulus operation the variable ch will be promoted to unsigned int
- first then the modulus operation will be performed (this will lead to a
- call to support routine _moduint()), and the result will be casted to a
- char.
+For the multiplication the variable ch will be promoted to int first then
+ the modulus operation will be performed (this will lead to a call to support
+ routine _mulint()), and the result will be casted to a char.
If the code is changed to
\layout Verse
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char ch1 = (unsigned char)p1 % ch ;
+unsigned char ch1 = (unsigned char)p1 * ch ;
\newline
\SpecialChar ~
\SpecialChar ~
}
\layout Standard
-It would substantially reduce the code generated (future versions of the
+it would substantially reduce the code generated (future versions of the
compiler will be smart enough to detect such optimization opportunities).
\end_deeper
\layout Itemize
\end_inset
for the code generation.
-\layout Subsection
+\layout Section
Notes on MCS51 memory
\begin_inset LatexCommand \index{MCS51 memory}
- 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 variables and,
+- 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
\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).
+ 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
Normally SDCC will only use the first bank
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
+\layout Section
Tools
\begin_inset LatexCommand \index{Tools}
\newline
-\layout Subsection
+\layout Section
Related open source tools
\begin_inset LatexCommand \index{Related tools}
\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="8" columns="3">
+<lyxtabular version="3" rows="9" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="block" valignment="top" leftline="true" width="30line%">
\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
+
+indent
+\begin_inset LatexCommand \index{indent}
+
+\end_inset
+
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Formats C source - Master of the white spaces
+\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://home.hccnet.nl/d.ingamells/beautify.html}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\newline
-\layout Subsection
+\layout Section
Related documentation / recommended reading
\layout Standard
\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
+S.
+ S.
+ Muchnick
\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
+Advanced Compiler Design and Implementation
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
-
-\end_inset
-
-
+bookstore
\end_inset
</cell>
</row>
\newline
-\layout Section
+\layout Chapter
\pagebreak_top
Support
\begin_inset LatexCommand \index{Support}
SDCC has grown to be a large project.
The compiler alone (without the preprocessor, assembler and linker) is
- about 40,000 lines of code (blank stripped).
+ well over 100,000 lines of code (blank stripped).
The open source nature of this project is a key to its continued growth
and support.
You gain the benefit and support of many active software developers and
\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
\end_inset
there.
-\layout Subsection
+\layout Section
Reporting Bugs
-\begin_inset LatexCommand \index{Bugs}
+\begin_inset LatexCommand \index{Bug reporting}
\end_inset
\end_inset
.
-\layout Subsection
+\layout Section
Requesting Features
\begin_inset LatexCommand \label{sub:Requesting-Features}
\end_inset
.
-\layout Subsection
+\layout Section
Getting Help
\layout Standard
, lists and forums are archived so if you are lucky someone already had
a similar problem.
-\layout Subsection
+\layout Section
ChangeLog
\begin_inset LatexCommand \index{Changelog}
\end_inset
in the cvs-repository.
-\layout Subsection
+\layout Section
Release policy
\begin_inset LatexCommand \index{Release policy}
\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}
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 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
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
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
Both the above switch statements will be implemented using a jump-table.
The example to the right side is slightly more efficient as the check for
- the lower bound of the jump-table is not needed.
+ the lower boundary of the jump-table is not needed.
\end_deeper
\layout Itemize
\newline
\SpecialChar ~
\SpecialChar ~
-case 9: \SpecialChar ~
+case 9:\SpecialChar ~
+\SpecialChar ~
...
\newline
\SpecialChar ~
\SpecialChar ~
-case 10: ...
+case 10:\SpecialChar ~
+...
\newline
\SpecialChar ~
\SpecialChar ~
-case 11: ...
+case 11:\SpecialChar ~
+...
\newline
\SpecialChar ~
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
+
+\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}
\family typewriter
-mov a,_i
+mov\SpecialChar ~
+ a,_i
\newline
swap a
\newline
-anl a,#0x0f
+anl\SpecialChar ~
+ a,#0x0f
\newline
-mov _i,a
+mov\SpecialChar ~
+ _i,a
\layout Standard
In general SDCC will never setup a loop if the shift count is known.
mov\SpecialChar ~
\SpecialChar ~
_i,a
-\layout Standard
-
-Note that SDCC stores numbers in little-endian 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
...
\family typewriter
i = ((i >> 7) | (i << 1)); /* left-bit rotation */
-\layout Subsubsection
+\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
+
+ 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
\end_inset
-peep-file option.
-\layout Subsection
+\layout Section
Library Routines
\emph on
\layout Comment
license statements for the libraries are missing.
- sdcc/device/lib/ser_ir.c f.e.
- comes with a GPL (as opposed to LGPL) License - this will not be liberal
+ 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
+\layout Standard
+
+If you have ported some library or want to share experience about some code
+ which f.e.
+ falls into any of these categories Busses (I
+\begin_inset Formula $^{\textrm{2}}$
+\end_inset
+
+C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
+ cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
+ Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
+\begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
+
+\end_inset
+
+\SpecialChar ~
+would certainly like to hear about it.
+ Programmers coding for embedded systems are not especially famous for being
+ enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
+e these references are very valuable.
+\layout Section
External Stack
\begin_inset LatexCommand \label{sub:External-Stack}
\layout Standard
-The external stack is located at the start of the external ram segment,
- and is 256 bytes in size.
+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
/
\end_inset
--stack-auto option, all parameters and local variables are allocated on
- the external stack (note support libraries will need to be recompiled with
- the same options).
+-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
+\layout Section
ANSI-Compliance
\begin_inset LatexCommand \index{ANSI-compliance}
\end_inset
+\begin_inset LatexCommand \label{sub:ANSI-Compliance}
+
+\end_inset
+
+
\layout Standard
Deviations from the compliance:
\layout Itemize
-functions are not always reentrant.
+functions are not always reentrant
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+.
\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
\end_deeper
\layout Itemize
-functions declared as pointers must be dereferenced during the call.
+functions declared as pointers
+\begin_inset LatexCommand \index{Pointers}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{function pointers}
+
+\end_inset
+
+ must be dereferenced during the call.
\begin_deeper
\layout Verse
\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
+\layout Section
Other Processors
-\layout Subsubsection
+\layout Subsection
+
+MCS51 variants
+\begin_inset LatexCommand \label{sub:MCS51-variants}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{MCS51 variants}
+
+\end_inset
+
+
+\layout Standard
+
+MCS51 processors are available from many vendors and come in many different
+ flavours.
+ While they might differ considerably in respect to Special Function Registers
+ the core MCS51 is usually not modified or is kept compatible.
+
+\layout Subsubsection*
+
+pdata access by SFR
+\begin_inset LatexCommand \index{sfr}
+
+\end_inset
+
+
+\layout Standard
+
+With the upcome of devices with internal xdata and flash memory devices
+ using port P2 as dedicated I/O port is becoming more popular.
+ Switching the high byte for pdata
+\begin_inset LatexCommand \index{pdata}
+
+\end_inset
+
+ access which was formerly done by port P2 is then achieved by a Special
+ Function Register.
+ In well-established MCS51 tradition the address of this
+\emph on
+sfr
+\emph default
+ is where the chip designers decided to put it.
+ As pdata addressing is used in the startup code for the initialization
+ of xdata variables a separate startup code should be used as described
+ in section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
+
+\end_inset
+
+.
+\layout Subsubsection*
+
+Other Features available by SFR
+\layout Standard
+
+Some MCS51 variants offer features like Double DPTR
+\begin_inset LatexCommand \index{DPTR}
+
+\end_inset
+
+, multiple DPTR, decrementing DPTR, 16x16 Multiply.
+ These are currently not used for the MCS51 port.
+ If you absolutely need them you can fall back to inline assembly or submit
+ a patch to SDCC.
+\layout Subsection
The Z80 and gbz80 port
\layout Standard
\end_inset
and the Nintendo Gameboy's Z80-like gbz80
-\begin_inset LatexCommand \index{GameBoy Z80}
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
\end_inset
\emph default
as MCS51 and DS390 ports, so floating point support, support for long variables
and bitfield support is fine.
+ See mailing lists and forums about interrupt routines and access to I/O
+ memory.
\layout Standard
As always, the code is the authoritative reference - see z80/ralloc.c and
z80/gen.c.
- The stack frame is similar to that generated by the IAR Z80 compiler.
+ The stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ frame is similar to that generated by the IAR Z80 compiler.
IX is used as the base pointer, HL is used as a temporary register, and
BC and DE are available for holding variables.
IY is currently unused.
- Return values are stored in HL.
+ Return values
+\begin_inset LatexCommand \index{return value}
+
+\end_inset
+
+ are stored in HL.
One bad side effect of using IX as the base pointer is that a functions
stack frame is limited to 127 bytes - this will be fixed in a later version.
\layout Subsection
+The HC08 port
+\layout Standard
+
+The port to the Motorola HC08
+\begin_inset LatexCommand \index{HC08}
+
+\end_inset
+
+ family has been added in October 2003, thank you Erik!
+\layout Section
+
Retargetting for other MCUs.
\layout Standard
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
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