\papersides 1
\paperpagestyle fancy
+\layout Comment
+
+Please note: double dashed longoptions (e.g.
+ --version) need three dashes in this document to be visable in html and
+ pdf output.
\layout Title
SDCC Compiler User Guide
\newline
The latest version can be downloaded from
-\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
\end_inset
(8 bits) which is not ANSI compliant
\layout Itemize
-the default directory where include, library and documention files are stored
- is now in /usr/local/share
+the default directory for gcc-builds where include, library and documention
+ files are stored is now in /usr/local/share
\layout Itemize
char type parameters to vararg functions are casted to int unless explicitly
will push a as an int and as a char resp.
\layout Itemize
-option --regextend has been removed
+option ---regextend has been removed
\layout Itemize
-option --noregparms has been removed
+option ---noregparms has been removed
\layout Itemize
-option --stack-after-data has been removed
+option ---stack-after-data has been removed
\layout Standard
\layout Standard
The SDCC home page at
-\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
\end_inset
Installation
\layout Subsection
-Install and search paths
+Configure Options
\layout Standard
-Linux (and other gcc-builds like Solaris, Cygwin, Mingw and OSX) by default
- install in /usr/local.
- You can override this when configuring with --prefix-path.
- Subdirs used will be bin, share/sdcc/include, share/sdcc/lib and share/sdcc/doc.
-\newline
-Windows MSVC and Borland builds will install in one single tree (e.g.
- /sdcc) with subdirs bin, lib, include and doc.
-\newline
+The install paths, search paths and other options are defined when running
+ 'configure'.
+ The defaults can be overriden by:
+\layout List
+\labelwidthstring 00.00.0000
+
+---prefix see tabel below
+\layout List
+\labelwidthstring 00.00.0000
+
+---exec_prefix see tabel below
+\layout List
+\labelwidthstring 00.00.0000
+
+---bindir see tabel below
+\layout List
+\labelwidthstring 00.00.0000
+
+---datadir see tabel below
+\layout List
+\labelwidthstring 00.00.0000
+
+docdir environment variable, see tabel below
+\layout List
+\labelwidthstring 00.00.0000
+
+include_dir_suffix environment variable, see tabel below
+\layout List
+\labelwidthstring 00.00.0000
+
+lib_dir_suffix environment variable, see tabel below
+\layout List
+\labelwidthstring 00.00.0000
+
+sdccconf_h_dir_separator environment variable, either / or
+\backslash
+
+\backslash
+ makes sense here.
+ This character will only be used in sdccconf.h; don't forget it's a C-header,
+ therefore a double-backslash is needed there.
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-mcs51-port Excludes the Intel mcs51 port
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-gbz80-port Excludes the Gameboy gbz80 port
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-z80-port Excludes the z80 port
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-avr-port Excludes the AVR port
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-ds390-port Excludes the DS390 port
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-pic-port Excludes the PIC port
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-xa51-port Excludes the XA51 port
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-ucsim Disables configuring and building of ucsim
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-device-lib-build Disables automatically building device libraries
+\layout List
+\labelwidthstring 00.00.0000
+
+---disable-packihx Disables building packihx
+\layout List
+\labelwidthstring 00.00.0000
+
+---enable-libgc Use the Bohem memory allocator.
+ Lower runtime footprint.
+\layout Standard
+Furthermore the environment variables CC, CFLAGS, ...
+ the tools and their arguments can be influenced.
+ Please see `configure ---help` and the man/info pages of `configure` for
+ details.
\newline
-The paths searched when running the compiler are as follows (the first catch
- wins):
-\layout Enumerate
-Binary files (preprocessor, assembler and linker):
\newline
-- the path of argv[0] (if available)
+The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
+ 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.
\newline
-- getenv(
-\begin_inset Quotes sld
-\end_inset
-SDCC_BIN_PATH
-\begin_inset Quotes srd
-\end_inset
+\newline
+These configure options are compiled into the binaries, and can only be
+ changed by rerunning 'configure' and recompiling SDCC.
+ The configure options are written in
+\emph on
+italics
+\emph default
+ to distinguish them from run time environment variables (see section search
+ paths).
+\newline
-)
\newline
-- getenv(
+The settings for
\begin_inset Quotes sld
\end_inset
-SDCCHOME
+Win32 builds
\begin_inset Quotes srd
\end_inset
-)/bin
-\newline
-- $PATH
+ are used by the SDCC team to build the official Win32 binaries.
+ The SDCC team uses Mingw32 to build the official Windows binaries, because
+ it's
\layout Enumerate
-Include files:
-\newline
-- -I dir
-\newline
-- getenv(
-\begin_inset Quotes sld
-\end_inset
+open source,
+\layout Enumerate
-SDCC_INCLUDE_PATH
-\begin_inset Quotes srd
-\end_inset
+a gcc compiler and last but not least
+\layout Enumerate
-)
+the binaries can be built by cross compiling on Sourceforge's compile farm.
+\layout Standard
+
+See the examples, how to pass the Win32 settings to 'configure'.
+ The other Win32 builds using Borland, VC or whatever don't use 'configure',
+ but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
+ for Win32.
\newline
-- getenv(
-\begin_inset Quotes sld
-\end_inset
-SDCCHOME)/include
\newline
-- /usr/local/share/sdcc/include (gcc builds)
+These defaults are:
\newline
-- path(arv[0])/../include and then /sdcc/include (windoze msvc and borland
- builds)
-\layout Enumerate
-Library files (the
-\shape italic
-model
-\shape default
- is auto-appended by the compiler, e.g.
- small, large, z80, ds390 etc.):
-\newline
-- -L dir
\newline
-- getenv(
-\begin_inset Quotes sld
-\end_inset
-SDCC_LIB_PATH
-\begin_inset Quotes srd
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Variable
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-)/
-\shape italic
-model
-\shape default
+\layout Standard
-\newline
-- getenv(
-\begin_inset Quotes sld
+default
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-SDCCHOME
-\begin_inset Quotes srd
+\layout Standard
+
+Win32 builds
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-)/lib/
-\shape italic
-model
-\shape default
+\layout Standard
-\newline
-- /usr/local/share/sdcc/lib/
-\shape italic
-model
-\shape default
- (gcc builds)
-\newline
-- path(argv[0])/../lib/
-\shape italic
-model
-\shape default
- and then /sdcc/lib/
-\shape italic
-model
-\shape default
- (windoze msvc and borland builds)
-\layout Enumerate
-Documentation (although never really searched for, you have to do that yourself
- :):
-\newline
-- getenv(
-\begin_inset Quotes sld
+\emph on
+PREFIX
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-SDCCHOME
-\begin_inset Quotes srd
+\layout Standard
+
+/usr/local
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-)/doc
-\newline
-- /usr/local/share/sdcc/doc (gcc builds)
-\newline
-- /sdcc/doc (windoze msvc and borland builds)
\layout Standard
-So, for windoze it is highly recommended to set the environment variable
- SDCCHOME to prevent needless usage of -I and -L.
-\layout Subsection
-Linux and other gcc-based systems (cygwin, mingw, osx)
-\layout Enumerate
+\backslash
+sdcc
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series medium
-Download the source package
-\series default
- either from the SDCC CVS repository or from the
-\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
+\emph on
+EXEC_PREFIX
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series medium
-, it will be named something like sdcc
-\series default
-.src
-\series medium
-.tgz.
-\layout Enumerate
-
-
-\series medium
-Bring up a command line terminal, such as xterm.
-\layout Enumerate
+\emph on
+$PREFIX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series medium
-Unpack the file using a command like:
-\family sans
-\series bold
-"tar -xzf sdcc.src.tgz
-\family default
-\series default
-"
-\series medium
-, this will create a sub-directory called sdcc with all of the sources.
-\layout Enumerate
+\layout Standard
-Change directory into the main SDCC directory, for example type:
-\family sans
-\series bold
-"cd sdcc
-\series default
-".
-\layout Enumerate
+\emph on
+$PREFIX
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series medium
-Type
-\family sans
-\series bold
-"./configure
-\family default
-\series default
-".
- This configures the package for compilation on your system.
-\layout Enumerate
+\layout Standard
-\series medium
-Type
-\family sans
-\series bold
-"make
-\family default
-\series default
-"
-\series medium
-.
+\emph on
+BINDIR
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series default
- All of the source packages will compile, this can take a while.
-\layout Enumerate
+\layout Standard
-\series medium
-Type
-\family sans
-\series bold
-"make install"
-\family default
-\series default
- as root
-\series medium
-.
+\emph on
+$EXECPREFIX
+\emph default
+/bin
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series default
- This copies the binary executables, the include files, the libraries and
- the documentation to the install directories.
-\layout Subsection
+\layout Standard
-Windows
-\layout Subsubsection
-Windows Install Using a Binary Package
-\layout Enumerate
+\emph on
+$EXECPREFIX
+\emph default
-Download the binary package 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 mingw package is: c:
-\backslash
-usr
-\backslash
-local
-\backslash
-bin for the executables, c:
-\backslash
-usr
\backslash
-local
-\backslash
-share
-\backslash
-sdcc
-\backslash
-include and c:
-\backslash
-usr
-\backslash
-local
-\backslash
-share
-\backslash
-sdcc
-\backslash
-lib for the include and libraries.
-\layout Enumerate
+bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Adjust your environment variable PATH to include the location of the bin
- directory or start sdcc using the full path.
-\layout Subsubsection
+\layout Standard
+
+
+\emph on
+DATADIR
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Windows Install Using Cygwin and Mingw
\layout Standard
-Follow the instruction in
-\series bold
-Linux and other gcc-based systems
-\series default
-.
-\layout Subsubsection
-Windows Install Using Microsoft Visual C++ 6.0/NET
+\emph on
+$PREFIX
+\emph default
+/share
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
\layout Standard
-\series medium
-Download the source package
-\series default
- either from the SDCC CVS repository or from the
-\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
+\emph on
+$PREFIX
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on
+DOCDIR
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\emph on
+$DATADIR
+\emph default
+/sdcc/doc
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series medium
-, it will be named something like sdcc
-\series default
-.src
-\series medium
-.tgz.
-\series default
- SDCC is distributed with all the projects, workspaces, and files you need
- to build it using Visual C++ 6.0/NET.
- The workspace name is 'sdcc.dsw'.
- Please note that as it is now, all the executables are created in a folder
- called sdcc
-\backslash
-bin_vc.
- Once built you need to copy the executables from sdcc
-\backslash
-bin_vc to sdcc
+\emph on
+$DATADIR
+\emph default
+
\backslash
-bin before runnng SDCC.
-
-\newline
+doc
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
-\newline
-In order to build SDCC with Visual C++ 6.0/NET you need win32 executables
- of bison.exe, flex.exe, and gawk.exe.
- One good place to get them is
-\begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
+\emph on
+INCLUDE_DIR_SUFFIX
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\newline
+sdcc/include
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
-Download the file UnxUtils.zip.
- Now you have to install the utilities and setup Visual C++ so it can locate
- the required programs.
- Here there are two alternatives (choose one!):
-\layout Enumerate
+\layout Standard
-The easy way:
-\newline
+include
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-a) Extract UnxUtils.zip to your C:
-\backslash
- hard disk PRESERVING the original paths, otherwise bison won't work.
- (If you are using WinZip make certain that 'Use folder names' is selected)
-\newline
+\layout Standard
-\newline
-b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
- in 'Show directories for:' select 'Executable files', and in the directories
- window add a new path: 'C:
-\backslash
-user
-\backslash
-local
-\backslash
-wbin', click ok.
-\newline
-\newline
-(As a side effect, you get a bunch of Unix utilities that could be useful,
- such as diff and patch.)
-\layout Enumerate
+\emph on
+LIB_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-A more compact way:
-\newline
+\layout Standard
-\newline
-This one avoids extracting a bunch of files you may not use, but requires
- some extra work:
-\newline
+sdcc/lib
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
-a) Create a directory were to put the tools needed, or use a directory already
- present.
- Say for example 'C:
-\backslash
-util'.
-\newline
+\layout Standard
-\newline
-b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
- to such directory WITHOUT preserving the original paths.
- (If you are using WinZip make certain that 'Use folder names' is not selected)
-\newline
+lib
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
-\newline
-c) Rename bison.exe to '_bison.exe'.
-\newline
\newline
-d) Create a batch file 'bison.bat' in 'C:
-\backslash
-util
-\backslash
-' and add these lines:
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-set BISON_SIMPLE=C:
-\backslash
-util
-\backslash
-bison.simple
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-set BISON_HAIRY=C:
-\backslash
-util
-\backslash
-bison.hairy
+'configure' also computes relative paths.
+ This is needed for full relocatability of a binary package and to complete
+ search paths (see section search paths below):
\newline
-\SpecialChar ~
-\SpecialChar ~
-_bison %1 %2 %3 %4 %5 %6 %7 %8 %9
+
\newline
-\newline
-Steps 'c' and 'd' are needed because bison requires by default that the
- files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
- '/usr/local/share/' I think.
- So it is necessary to tell bison where those files are located if they
- are not in such directory.
- That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
-\newline
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
- in 'Show directories for:' select 'Executable files', and in the directories
- window add a new path: 'c:
-\backslash
-util', click ok.
- Note that you can use any other path instead of 'c:
-\backslash
-util', even the path where the Visual C++ tools are, probably: 'C:
-\backslash
-Program Files
-\backslash
-Microsoft Visual Studio
-\backslash
-Common
-\backslash
-Tools'.
- So you don't have to execute step 'e' :)
\layout Standard
-That is it.
- Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
- the executables from sdcc
-\backslash
-bin_vc to sdcc
-\backslash
-bin, and you can compile using sdcc.
-\layout Subsubsection
+Variable (computed)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Windows Install Using Borland ......
\layout Standard
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\shape italic
-<pending>
-\layout Subsection
-
-Testing out the SDCC Compiler
\layout Standard
-The first thing you should do after installing your SDCC compiler is to
- see if it runs.
- Type
-\family sans
-\series bold
-"sdcc --version"
-\family default
-\series default
- at the prompt, and the program should run and tell you the version.
- 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).
- Make sure that the sdcc program is in the bin folder, if not perhaps something
- did not install correctly.
-\newline
-
-\newline
-
-\series medium
-SDCC binaries are commonly installed in a directory arrangement like this:
-\series default
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\newline
-\begin_inset Tabular
-<lyxtabular version="3" rows="3" columns="2">
-<features>
-<column alignment="left" valignment="top" leftline="true" width="0(null)">
-<column alignment="left" valignment="top" leftline="true" rightline="true" width="0(null)">
-<row topline="true" bottomline="true">
+\emph on
+BIN2DATA_DIR
+\end_inset
+</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-/
-\series medium
-usr/local/bin
+../share
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
+..
+\backslash
-\series medium
-Holds executables(sdcc, s51, aslink,
-\series default
-...
-\series medium
-)
\end_inset
</cell>
</row>
-<row topline="true">
+<row bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-/
-\series medium
-usr/local/share/sdcc/lib
+
+\emph on
+PREFIX2BIN_DIR
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
+bin
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
-\series medium
-Holds common C
-\series default
-libraries
+bin
\end_inset
</cell>
</row>
-<row topline="true" bottomline="true">
+<row bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-/
-\series medium
-usr/local/share/sdcc/include
+
+\emph on
+PREFIX2DATA_DIR
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
+share/sdcc
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
-\series medium
-Holds common C header files
\end_inset
</cell>
</row>
\newline
\newline
+Examples:
+\layout LyX-Code
-\series medium
-Make sure the compiler works on a very simple example.
- Type in the following test.c program using your favorite editor:
-\series default
+./configure
+\layout LyX-Code
-\newline
+./configure ---prefix=
+\begin_inset Quotes srd
+\end_inset
-\family typewriter
+/usr/bin
+\begin_inset Quotes srd
+\end_inset
-\newline
-char test;
-\newline
+ ---datadir=
+\begin_inset Quotes srd
+\end_inset
-\newline
-void main(void) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-test=0;
-\newline
-}
-\family default
+/usr/share
+\begin_inset Quotes srd
+\end_inset
-\newline
-\emph on
+\layout LyX-Code
-\newline
+./configure ---disable-avr-port ---disable-xa51-port
+\layout Standard
-\series medium
-\emph default
-Compile this using the following command:
-\family sans
-\series bold
-"sdcc -c test.c".
+To crosscompile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw3
+2'):
+\layout LyX-Code
-\family default
-\series default
-
-\series medium
-If all goes well, the compiler will generate a test.asm and test.rel file.
- Congratulations, you've just compiled your first program with SDCC.
- We used the -c option to tell SDCC not to link the generated code, just
- to keep things simple for this step.
-\series default
+./configure
+\backslash
-\newline
+\layout LyX-Code
-\newline
+ CC=
+\begin_inset Quotes srd
+\end_inset
+
+i586-mingw32msvc-gcc
+\begin_inset Quotes srd
+\end_inset
+
+ CXX=
+\begin_inset Quotes srd
+\end_inset
+
+i586-mingw32msvc-g++
+\begin_inset Quotes srd
+\end_inset
-\series medium
-The next step is to try it with the linker.
- Type in
-\family sans
-\series bold
-"sdcc test.c
-\family default
-\series default
-"
-\series medium
-.
- If all goes well the compiler will link with the libraries and produce
- a test.ihx output file.
- If this step fails
-\series default
-
-\series medium
-(no test.ihx, and the linker generates warnings), then the problem is most
- likely that sdcc cannot find the
-\series default
-/
-\series medium
-usr/local/share/sdcc/lib directory
-\series default
-\series medium
-(see the Install trouble-shooting section for suggestions).
-\series default
+\backslash
-\newline
+\layout LyX-Code
-\newline
+ RANLIB=
+\begin_inset Quotes srd
+\end_inset
-\series medium
-The final test is to ensure sdcc can use the
-\series default
-standard
-\series medium
- header files and libraries.
- Edit test.c and change it to the following:
-\series default
+i586-mingw32msvc-ranlib
+\begin_inset Quotes srd
+\end_inset
-\newline
+
+\backslash
-\newline
+\layout LyX-Code
-\family typewriter
-#include <string.h>
-\newline
+ STRIP=
+\begin_inset Quotes srd
+\end_inset
-\newline
-char str1[10];
-\newline
+i586-mingw32msvc-strip
+\begin_inset Quotes srd
+\end_inset
-\newline
-void main(void) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-strcpy(str1, "testing");
-\newline
-}
-\newline
+
+\backslash
-\newline
+\layout LyX-Code
-\family default
-\series medium
-Compile this by typing
-\family sans
-\series bold
-"sdcc test.c"
-\family default
-\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
-\series default
-
-\series medium
-(see the Install trouble-shooting section for suggestions).
-\layout Subsection
+ ---prefix=
+\begin_inset Quotes srd
+\end_inset
-Install Trouble-shooting
-\layout Subsubsection
+/sdcc
+\begin_inset Quotes srd
+\end_inset
-SDCC does not build correctly.
-\layout Standard
+
+\backslash
-A thing to try is starting from scratch by unpacking the .tgz source package
- again in an empty directory.
- Confure it like:
-\newline
+\layout LyX-Code
-\newline
+ ---datadir=
+\begin_inset Quotes srd
+\end_inset
-\family typewriter
-./configure 2&>1 | tee configure.log
-\family default
+/sdcc
+\begin_inset Quotes srd
+\end_inset
-\newline
+
+\backslash
-\newline
-and build it like:
-\newline
+\layout LyX-Code
-\newline
+ docdir=
+\begin_inset Quotes srd
+\end_inset
-\family typewriter
-make 2&>1 | tee make.log
-\family default
+/sdcc/doc
+\begin_inset Quotes srd
+\end_inset
-\newline
+
+\backslash
-\newline
-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 LyX-Code
-What the
-\begin_inset Quotes sld
+ include_dir_suffix=
+\begin_inset Quotes srd
\end_inset
-./configure
+include
\begin_inset Quotes srd
\end_inset
- does
-\layout Standard
+
+\backslash
-The
-\begin_inset Quotes sld
+\layout LyX-Code
+
+ lib_dir_suffix=
+\begin_inset Quotes srd
\end_inset
-./configure
+lib
\begin_inset Quotes srd
\end_inset
- command is a script that analyzes your system and performs some configuration
- 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
+
+\backslash
-What the
-\begin_inset Quotes sld
+\layout LyX-Code
+
+ sdccconf_h_dir_separator=
+\begin_inset Quotes srd
\end_inset
-make
+
+\backslash
+
+\backslash
+
+\backslash
+
+\backslash
+
\begin_inset Quotes srd
\end_inset
- does.
-\layout Standard
+
+\backslash
-This runs the GNU make tool, which automatically compiles all the source
- packages into the final installed binary executables.
-\layout Subsubsection
+\layout LyX-Code
-What the
+ ---disable-device-lib-build
+\backslash
+
+\layout LyX-Code
+
+ ---disable-ucsim
+\backslash
+
+\layout LyX-Code
+
+ ---host=i586-mingw32msvc ---build=unknown-unknown-linux-gnu
+\layout Standard
+
+To
\begin_inset Quotes sld
\end_inset
-make install
-\begin_inset Quotes erd
+cross
+\begin_inset Quotes srd
\end_inset
- command does.
-\layout Standard
+compile on Cygwin for Mingw32(see also sdcc/support/scripts/sdcc_cygwin_mingw32)
+:
+\layout LyX-Code
-This will install the compiler, other executables and libraries in to the
- appropriate system directories.
- The default is to copy the executables to /usr/local/bin and the libraries
- and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
- On most systems you will need super-user privilages to do this.
-\layout Subsection
+./configure -C
+\backslash
-Advanced Install Options
-\layout Standard
+\layout LyX-Code
-The
-\begin_inset Quotes eld
+ CFLAGS=
+\begin_inset Quotes srd
\end_inset
-configure
-\begin_inset Quotes erd
+-mno-cygwin -O2
+\begin_inset Quotes srd
\end_inset
- command has several options.
- The most commonly used option is --prefix=<directory name>, where <directory
- name> is the final location for the sdcc executables and libraries, (default
- location is /usr/local).
- The installation process will create the following directory structure
- under the <directory name> specified (if they do not already exist).
-\newline
-
-\newline
-bin/ - binary exectables (add to PATH environment variable)
-\newline
-bin/share/
-\newline
-bin/share/sdcc/include/ - include header files
-\newline
-bin/share/sdcc/lib/
-\newline
-bin/share/sdcc/lib/small/ - Object & library files for small model library
-\newline
-bin/share/sdcc/lib/large/ - Object & library files for large model library
-\newline
-bin/share/sdcc/lib/ds390/ - Object & library files for DS80C390 library
-\newline
-bin/share/sdcc/lib/z80/ - Object & library files for Z80 library
-\newline
+\backslash
-\newline
-The command
-\family sans
-\series bold
+\layout LyX-Code
-\begin_inset Quotes sld
+ LDFLAGS=
+\begin_inset Quotes srd
\end_inset
-./configure --prefix=/usr/local
-\begin_inset Quotes erd
+-mno-cygwin
+\begin_inset Quotes srd
\end_inset
-\family default
-\series default
-will configure the compiler to be installed in directory /usr/local.
-\layout Subsection
+\backslash
-Components of SDCC
-\layout Standard
+\layout LyX-Code
-SDCC is not just a compiler, but a collection of tools by various developers.
- These include linkers, assemblers, simulators and other components.
- Here is a summary of some of the components.
- Note that the included simulator and assembler have separate documentation
- which you can find in the source package in their respective directories.
- As SDCC grows to include support for other processors, other packages from
- various developers are included and may have their own sets of documentation.
-\newline
+ ---prefix=
+\begin_inset Quotes srd
+\end_inset
-\newline
-You might want to look at the files which are installed in <installdir>.
- At the time of this writing, we find the following programs:
-\newline
-
-\newline
-In <installdir>/bin:
-\layout Itemize
+/sdcc
+\begin_inset Quotes srd
+\end_inset
-sdcc - The compiler.
-\layout Itemize
+
+\backslash
-sdcpp - The C preprocessor.
-\layout Itemize
+\layout LyX-Code
-asx8051 - The assembler for 8051 type processors.
-\layout Itemize
+ ---datadir=
+\begin_inset Quotes srd
+\end_inset
-as-z80
-\series bold
-,
-\series default
-as-gbz80 - The Z80 and GameBoy Z80 assemblers.
-\layout Itemize
+/sdcc
+\begin_inset Quotes srd
+\end_inset
-aslink -The linker for 8051 type processors.
-\layout Itemize
+
+\backslash
-link-z80
-\series bold
-,
-\series default
-link-gbz80 - The Z80 and GameBoy Z80 linkers.
-\layout Itemize
+\layout LyX-Code
-s51 - The ucSim 8051 simulator.
-\layout Itemize
+ docdir=
+\begin_inset Quotes srd
+\end_inset
-sdcdb - The source debugger.
-\layout Itemize
+/sdcc/doc
+\begin_inset Quotes srd
+\end_inset
-packihx - A tool to pack (compress) Intel hex files.
-\layout Standard
+
+\backslash
-In <installdir>/share/sdcc/include
-\layout Itemize
+\layout LyX-Code
-the include files
-\layout Standard
+ include_dir_suffix=
+\begin_inset Quotes srd
+\end_inset
-In <installdir>/share/sdcc/lib
-\layout Itemize
+include
+\begin_inset Quotes srd
+\end_inset
-the sources of the runtime library and the subdirs small large and ds390
- with the precompiled relocatables.
-\layout Standard
+
+\backslash
-In <installdir>/share/sdcc/doc
-\layout Itemize
+\layout LyX-Code
-the documentation
-\layout Standard
+ lib_dir_suffix=
+\begin_inset Quotes srd
+\end_inset
-As development for other processors proceeds, this list will expand to include
- executables to support processors like AVR, PIC, etc.
-\layout Subsubsection
+lib
+\begin_inset Quotes srd
+\end_inset
-sdcc - The Compiler
-\layout Standard
+
+\backslash
-This is the actual compiler, it in turn uses the c-preprocessor and invokes
- the assembler and linkage editor.
-\layout Subsubsection
+\layout LyX-Code
-sdcpp - The C-Preprocessor)
-\layout Standard
+ sdccconf_h_dir_separator=
+\begin_inset Quotes srd
+\end_inset
-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
-asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 - The Assemblers
- and Linkage Editors
-\layout Standard
+\backslash
-This is retargettable assembler & linkage editor, it was developed by Alan
- Baldwin.
- John Hartman created the version for 8051, and I (Sandeep) have made some
- enhancements and bug fixes for it to work properly with the SDCC.
-\layout Subsubsection
+\backslash
-s51 - The Simulator
-\layout Standard
+\backslash
-S51 is a freeware, opensource simulator developed by Daniel Drotos (
-\begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
+\backslash
+\begin_inset Quotes srd
\end_inset
-).
- The simulator is built as part of the build process.
- For more information visit Daniel's website at:
-\begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
+
+\backslash
-\end_inset
+\layout LyX-Code
-.
- It currently support the core mcs51, the Dallas DS80C390 and the Philips
- XA51 family.
-\layout Subsubsection
+ ---disable-ucsim
+\layout Standard
-sdcdb - Source Level Debugger
+'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
+ The option '--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
+
+Install paths
\layout Standard
+1.
+ Binary files (preprocessor, assembler and linker)
+\layout Standard
-\family typewriter
-\shape italic
-<todo: is this thing alive?>
-\newline
-\newline
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family default
-\shape default
-Sdcdb is the companion source level debugger.
- The current version of the debugger uses Daniel's Simulator S51, but can
- be easily changed to use other simulators.
-\layout Section
+\layout Standard
-Using SDCC
-\layout Subsection
+Path
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Compiling
-\layout Subsubsection
+\layout Standard
+
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-Single Source File Projects
\layout Standard
-For single source file 8051 projects the process is very simple.
- Compile your programs with the following command
-\family sans
-\series bold
-"sdcc sourcefile.c".
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family default
-\series default
- This will compile, assemble and link your source file.
- Output files are as follows
-\newline
+\layout Standard
-\newline
-sourcefile.asm - Assembler source file created by the compiler
-\newline
-sourcefile.lst - Assembler listing file created by the Assembler
-\newline
-sourcefile.rst - Assembler listing file updated with linkedit information,
- created by linkage editor
-\newline
-sourcefile.sym - symbol listing for the sourcefile, created by the assembler
-\newline
-sourcefile.rel - Object file created by the assembler, input to Linkage editor
-\newline
-sourcefile.map - The memory map for the load module, created by the Linker
-\newline
-sourcefile.ihx - The load module in Intel hex format (you can select the
- Motorola S19 format with --out-fmt-s19)
-\newline
-sourcefile.cdb - An optional file (with --debug) containing debug information
-\newline
-\layout Subsubsection
+\emph on
+$EXEC_PREFIX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Projects with Multiple Source Files
\layout Standard
-SDCC can compile only ONE file at a time.
- Let us for example assume that you have a project containing the following
- files:
-\newline
+/usr/local/bin
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
-foo1.c (contains some functions)
-\newline
-foo2.c (contains some more functions)
-\newline
-foomain.c (contains more functions and the function main)
-\newline
+\layout Standard
-\size footnotesize
-\newline
+\backslash
+sdcc
+\backslash
+bin
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-\size default
-The first two files will need to be compiled separately with the commands:
-\size footnotesize
-
-\size default
+\end_inset
+
\newline
\newline
+2.
+ Include files
+\layout Standard
-\family sans
-\series bold
-sdcc\SpecialChar ~
--c\SpecialChar ~
-foo1.c
-\family default
-\series default
-\size footnotesize
-\newline
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="1.6in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family sans
-\series bold
-\size default
-sdcc\SpecialChar ~
--c\SpecialChar ~
-foo2.c
-\family default
-\series default
+\layout Standard
+
+Path
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
-\newline
-\newline
-Then compile the source file containing the
\emph on
-main()
-\emph default
- function and link the files together with the following command:
+$DATADIR/
\newline
+$INCLUDE_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\family sans
-\series bold
-sdcc\SpecialChar ~
-foomain.c\SpecialChar ~
-foo1.rel\SpecialChar ~
-foo2.rel
-\family default
-\series default
+/usr/local/share/sdcc/include
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\newline
-Alternatively,
-\emph on
-foomain.c
-\emph default
-can be separately compiled as well:
-\family sans
-\series bold
-\newline
+\backslash
+sdcc
+\backslash
+include
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
-\newline
-sdcc\SpecialChar ~
--c\SpecialChar ~
-foomain.c
-\newline
-sdcc foomain.rel foo1.rel foo2.rel
\newline
\newline
+3.
+ Library files (the
+\shape italic
+model
+\shape default
+ is auto-appended by the compiler, e.g.
+ small, large, z80, ds390 etc.)
+\layout Standard
-\family default
-\series default
-The file containing the
-\emph on
-main()
-\emph default
- function
-\emph on
-
-\emph default
-\noun on
-must
-\noun default
- be the
-\noun on
-first
-\noun default
- file specified in the command line, since the linkage editor processes
- file in the order they are presented to it.
-\layout Subsubsection
-Projects with Additional Libraries
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
\layout Standard
-Some reusable routines may be compiled into a library, see the documentation
- for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
- for how to create a
-\emph on
-.lib
-\emph default
- library file.
- Libraries created in this manner can be included in the command line.
- Make sure you include the -L <library-path> option to tell the linker where
- to look for these files if they are not in the current directory.
- Here is an example, assuming you have the source file
-\emph on
-foomain.c
-\emph default
- and a library
-\emph on
- foolib.lib
-\emph default
- in the directory
-\emph on
-mylib
-\emph default
- (if that is not the same as your current project):
-\newline
+Path
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\family sans
-\series bold
-sdcc foomain.c foolib.lib -L mylib
-\newline
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\family default
-\series default
-Note here that
-\emph on
- mylib
-\emph default
- must be an absolute path name.
-\newline
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-The most efficient way to use libraries is to keep seperate modules in seperate
- source files.
- The lib file now should name all the modules.rel files.
- For an example see the standard library file
-\emph on
-libsdcc.lib
-\emph default
- in the directory <installdir>/share/lib/small.
-\layout Subsection
+\layout Standard
-Command Line Options
-\layout Subsubsection
-Processor Selection Options
-\layout List
-\labelwidthstring 00.00.0000
+\emph on
+$DATADIR/$LIB_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
--mmcs51
-\series default
- Generate code for the MCS51 (8051) family of processors.
- This is the default processor target.
-\layout List
-\labelwidthstring 00.00.0000
+/usr/local/share/sdcc/lib
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
--mds390
-\series default
- Generate code for the DS80C390 processor.
-\layout List
-\labelwidthstring 00.00.0000
+\backslash
+sdcc
+\backslash
+lib
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-\series bold
--mz80
-\series default
- Generate code for the Z80 family of processors.
-\layout List
-\labelwidthstring 00.00.0000
+\end_inset
-\series bold
--mgbz80
-\series default
- Generate code for the GameBoy Z80 processor.
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+\newline
+4.
+ Documentation
+\layout Standard
-\series bold
--mavr
-\series default
- Generate code for the Atmel AVR processor (In development, not complete).
-\layout List
-\labelwidthstring 00.00.0000
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
--mpic14
-\series default
- Generate code for the PIC 14-bit processors (In development, not complete).
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+Path
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
--mtlcs900h
-\series default
- Generate code for the Toshiba TLCS-900H processor (In development, not
- complete).
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
--mxa51
-\series default
- Generate code for the Philips XA51 processor (In development, not complete).
-\layout Subsubsection
+\layout Standard
-Preprocessor Options
-\layout List
-\labelwidthstring 00.00.0000
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
--I<path>
-\series default
- The additional location where the pre processor will look for <..h> or
-\begin_inset Quotes eld
-\end_inset
-..h
-\begin_inset Quotes erd
+\emph on
+$DOCDIR
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- files.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+/usr/local/share/sdcc/doc
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
--D<macro[=value]>
-\series default
- Command line definition of macros.
- Passed to the pre processor.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
-\series bold
--M
-\series default
- Tell the preprocessor to output a rule suitable for make describing the
- dependencies of each object file.
- For each source file, the preprocessor outputs one make-rule whose target
- is the object file name for that source file and whose dependencies are
- all the files `#include'd in it.
- This rule may be a single line or may be continued with `
\backslash
-'-newline if it is long.
- The list of rules is printed on standard output instead of the preprocessed
- C program.
- `-M' implies `-E'.
-\layout List
-\labelwidthstring 00.00.0000
-
+sdcc
+\backslash
+doc
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-\series bold
--C
-\series default
- Tell the preprocessor not to discard comments.
- Used with the `-E' option.
-\layout List
-\labelwidthstring 00.00.0000
+\end_inset
-\series bold
--MM
-\size large
-\bar under
-
-\series default
-\size default
-\bar default
-Like `-M' but the output mentions only the user header files included with
- `#include
-\begin_inset Quotes eld
-\end_inset
+\newline
-file"'.
- System header files included with `#include <file>' are omitted.
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+The install paths can still be changed during `make install` with e.g.:
+\layout LyX-Code
+make install prefix=$(HOME)/local/sdcc
+\layout Standard
-\series bold
--Aquestion(answer)
-\series default
- Assert the answer answer for question, in case it is tested with a preprocessor
- conditional such as `#if #question(answer)'.
- `-A-' disables the standard assertions that normally describe the target
- machine.
-\layout List
-\labelwidthstring 00.00.0000
+Of course this doesn't change the search paths compiled into the binaries.
+\layout Subsection
+Search Paths
+\layout Standard
-\series bold
--Aquestion
-\series default
- (answer) Assert the answer answer for question, in case it is tested with
- a preprocessor conditional such as `#if #question(answer)'.
- `-A-' disables the standard assertions that normally describe the target
- machine.
-\layout List
-\labelwidthstring 00.00.0000
+Some search paths or parts of them are determined by configure variables
+ (in
+\emph on
+italics
+\emph default
+, see section above).
+ Further search paths are determined by environment variables during runtime.
+
+\newline
+The paths searched when running the compiler are as follows (the first catch
+ wins):
+\newline
+\newline
+1.
+ Binary files (preprocessor, assembler and linker)
+\newline
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
--Umacro
-\series default
- Undefine macro macro.
- `-U' options are evaluated after all `-D' options, but before any `-include'
- and `-imacros' options.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+Search path
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
--dM
-\series default
- Tell the preprocessor to output only a list of the macro definitions that
- are in effect at the end of preprocessing.
- Used with the `-E' option.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
--dD
-\series default
- Tell the preprocessor to pass all macro definitions into the output, in
- their proper sequence in the rest of the output.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
--dN
-\size large
-\bar under
-
-\series default
-\size default
-\bar default
-Like `-dD' except that the macro arguments and contents are omitted.
- Only `#define name' is included in the output.
-\layout Subsubsection
+\layout Standard
-Linker Options
-\layout List
-\labelwidthstring 00.00.0000
+$SDCC_HOME/
+\emph on
+$PPREFIX2BIN_DIR
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
--o\SpecialChar ~
-<path/file>
-\series default
-the output path resp.
- file where everything will be placed
-\layout List
-\labelwidthstring 00.00.0000
+$SDCC_HOME/bin
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
--L\SpecialChar ~
---lib-path
-\bar under
-
-\series default
-\bar default
-<absolute path to additional libraries> This option is passed to the linkage
- editor's additional libraries search path.
- The path name must be absolute.
- Additional library files may be specified in the command line.
- See section Compiling programs for more details.
-\layout List
-\labelwidthstring 00.00.0000
+$SDCC_HOME
+\backslash
+bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---xram-loc
-\series default
-<Value> The start location of the external ram, default value is 0.
- The value entered can be in Hexadecimal or Decimal format, e.g.: --xram-loc
- 0x8000 or --xram-loc 32768.
-\layout List
-\labelwidthstring 00.00.0000
+Path of argv[0] (if available)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---code-loc
-\series default
-<Value> The start location of the code segment, default value 0.
- Note when this option is used the interrupt vector table is also relocated
- to the given address.
- The value entered can be in Hexadecimal or Decimal format, e.g.: --code-loc
- 0x8000 or --code-loc 32768.
-\layout List
-\labelwidthstring 00.00.0000
+Path of argv[0]
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---stack-loc
-\series default
-<Value> By default the stack is placed after the data segment.
- Using this option the stack can be placed anywhere in the internal memory
- space of the 8051.
- The value entered can be in Hexadecimal or Decimal format, e.g.
- --stack-loc 0x20 or --stack-loc 32.
- Since the sp register is incremented before a push or call, the initial
- sp will be set to one byte prior the provided value.
- The provided value should not overlap any other memory areas such as used
- register banks or the data segment and with enough space for the current
- application.
-\layout List
-\labelwidthstring 00.00.0000
+Path of argv[0]
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---data-loc
-\series default
-<Value> The start location of the internal ram data segment, the default
- value is 0x30.The value entered can be in Hexadecimal or Decimal format,
- eg.
- --data-loc 0x20 or --data-loc 32.
-\layout List
-\labelwidthstring 00.00.0000
+$PATH
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---idata-loc
-\series default
-<Value> The start location of the indirectly addressable internal ram, default
- value is 0x80.
- The value entered can be in Hexadecimal or Decimal format, eg.
- --idata-loc 0x88 or --idata-loc 136.
-\layout List
-\labelwidthstring 00.00.0000
+$PATH
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---out-fmt-ihx
-\bar under
-
-\series default
-\bar default
-The linker output (final object code) is in Intel Hex format.
- (This is the default option).
-\layout List
-\labelwidthstring 00.00.0000
+$PATH
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+\end_inset
-\series bold
---out-fmt-s19
-\bar under
-\series default
-\bar default
-The linker output (final object code) is in Motorola S19 format.
-\layout Subsubsection
+\newline
-MCS51 Options
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+2.
+ Include files
+\newline
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="1.5in">
+<column alignment="block" valignment="top" leftline="true" width="1.5in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---model-large
-\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
- with this option.
- In addition the standard library routines are compiled with small model,
- they will need to be recompiled.
-\layout List
-\labelwidthstring 00.00.0000
+Search path
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---model-small
-\series default
-\size large
-\emph on
-
-\size default
-\emph default
-Generate code for Small Model programs see section Memory Models for more
- details.
- This is the default model.
-\layout Subsubsection
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-DS390 Options
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---model-flat24
-\series default
-\size large
-\emph on
-
-\size default
-\emph default
-Generate 24-bit flat mode code.
- This is the one and only that the ds390 code generator supports right now
- and is default when using
-\emph on
--mds390
-\emph default
-.
- See section Memory Models for more details.
-\layout List
-\labelwidthstring 00.00.0000
-
+\layout Standard
-\series bold
---stack-10bit
-\series default
- Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
- This is the one and only that the ds390 code generator supports right now
- and is default when using
-\emph on
--mds390
-\emph default
-.
- In this mode, the stack is located in the lower 1K of the internal RAM,
- which is mapped to 0x400000.
- Note that the support is incomplete, since it still uses a single byte
- as the stack pointer.
- This means that only the lower 256 bytes of the potential 1K stack space
- will actually be used.
- However, this does allow you to reclaim the precious 256 bytes of low RAM
- for use for the DATA and IDATA segments.
- The compiler will not generate any code to put the processor into 10 bit
- stack mode.
- It is important to ensure that the processor is in this mode before calling
- any re-entrant functions compiled with this option.
- In principle, this should work with the
-\emph on
---stack-auto
-\emph default
- option, but that has not been tested.
- It is incompatible with the
-\emph on
---xstack
-\emph default
- option.
- It also only makes sense if the processor is in 24 bit contiguous addressing
- mode (see the
-\emph on
---model-flat24 option
-\emph default
-).
-\layout Subsubsection
+---I dir
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Optimization Options
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+---I dir
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
---nogcse
-\series default
- Will not do global subexpression elimination, this option may be used when
- the compiler creates undesirably large stack/data spaces to store compiler
- temporaries.
- A warning message will be generated when this happens and the compiler
- will indicate the number of extra bytes it allocated.
- It recommended that this option NOT be used, #pragma\SpecialChar ~
-NOGCSE can be used
- to turn off global subexpression elimination for a given function only.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+---I dir
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---noinvariant
-\series default
- Will not do loop invariant optimizations, this may be turned off for reasons
- explained for the previous option.
- For more details of loop optimizations performed see section Loop Invariants.It
- recommended that this option NOT be used, #pragma\SpecialChar ~
-NOINVARIANT can be used
- to turn off invariant optimizations for a given function only.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+$SDCC_INCLUDE
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---noinduction
-\series default
- Will not do loop induction optimizations, see section strength reduction
- for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
-NOINDUCT
-ION can be used to turn off induction optimizations for a given function
- only.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+$SDCC_INCLUDE
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
---nojtbound
-\size large
-\bar under
-
-\series default
-\size default
-\bar default
- Will not generate boundary condition check when switch statements are implement
-ed using jump-tables.
- See section Switch Statements for more details.
- It is recommended that this option is NOT used, #pragma\SpecialChar ~
-NOJTBOUND can be
- used to turn off boundary checking for jump tables for a given function
- only.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+$SDCC_INCLUDE
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---noloopreverse
-\series default
-\size large
-
-\size default
-Will not do loop reversal optimization.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+$SDCC_HOME/
+\newline
-\series bold
---no-xinit-opt
-\series default
- This will disable the memcpy of initialized data in far space from code
- space
-\layout Subsubsection
+\emph on
+$PREFIX2DATA_DIR/
+\newline
+$INCLUDE_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Other Options
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+$SDCC_ HOME/
+\newline
+share/sdcc/
+\newline
+include
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
--c\SpecialChar ~
---compile-only
-\series default
- will compile and assemble the source, but will not call the linkage editor.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+$SDCC_HOME
+\backslash
+include
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
--E
-\series default
- Run only the C preprocessor.
- Preprocess all the C source files specified and output the results to standard
- output.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+path(argv[0])/
+\newline
-\series bold
---stack-auto
-\series default
-\size large
-\emph on
-
-\size default
-\emph default
-All functions in the source file will be compiled as
\emph on
-reentrant
+$BIN2DATADIR/
\emph default
-, i.e.
- the parameters and local variables will be allocated on the stack.
- see section Parameters and Local Variables for more details.
- If this option is used all source files in the project should be compiled
- with this option.
-
-\layout List
-\labelwidthstring 00.00.0000
+\newline
-\series bold
---xstack
-\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.
-\layout List
-\labelwidthstring 00.00.0000
+\emph on
+$INCLUDE_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---callee-saves function1[,function2][,function3]....
+path(argv[0])/
+\newline
+../sdcc/include
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
-\series default
- The compiler by default uses a caller saves convention for register saving
- across function calls, however this can cause unneccessary register pushing
- & popping when calling small functions from larger functions.
- This option can be used to switch the register saving convention for the
- function names specified.
- The compiler will not save registers when calling these functions, no extra
- code will be generated at the entry & exit for these functions to save
- & restore the registers used by these functions, this can SUBSTANTIALLY
- reduce code & improve run time performance of the generated code.
- In the future the compiler (with interprocedural analysis) will be able
- to determine the appropriate scheme to use for each function call.
- DO NOT use this option for built-in functions such as _muluint..., if this
- option is used for a library function the appropriate library function
- needs to be recompiled with the same option.
- If the project consists of multiple source files then all the source file
- should be compiled with the same --callee-saves option string.
- Also see #pragma\SpecialChar ~
-CALLEE-SAVES.
-\layout List
-\labelwidthstring 00.00.0000
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---debug
-\bar under
-
-\series default
-\bar default
-When this option is used the compiler will generate debug information, that
- can be used with the SDCDB.
- The debug information is collected in a file with .cdb extension.
- For more information see documentation for SDCDB.
-\layout List
-\labelwidthstring 00.00.0000
+path(argv[0])
+\backslash
+..
+\backslash
+include
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---peep-file
-\series default
-<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.
-\layout List
-\labelwidthstring 00.00.0000
+\emph on
+$DATADIR/
+\emph default
-\series bold
--S
-\size large
-\bar under
-
-\series default
-\size default
-\bar default
-Stop after the stage of compilation proper; do not assemble.
- The output is an assembler code file for the input file specified.
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+\emph on
+$INCLUDE_DIR_SUFFIX
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
--Wa_asmOption[,asmOption]
-\series default
-...
- Pass the asmOption to the assembler.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+/usr/local/share/sdcc/
+\newline
+include
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
--Wl_linkOption[,linkOption]
-\series default
-...
- Pass the linkOption to the linker.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+(not on Win32)
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
-\series bold
---int-long-reent
-\series default
-\size large
-\size default
- Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
- Note by default these libraries are compiled as non-reentrant.
- See section Installation for more details.
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+\newline
+ The option ---nostdinc disables the last two search paths.
+\newline
-\series bold
---cyclomatic
-\bar under
-
-\series default
-\bar default
-This option will cause the compiler to generate an information message for
- each function in the source file.
- The message contains some
-\emph on
-important
-\emph default
- information about the function.
- The number of edges and nodes the compiler detected in the control flow
- graph of the function, and most importantly the
-\emph on
-cyclomatic complexity
-\emph default
- see section on Cyclomatic Complexity for more details.
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+3.
+ Library files
+\newline
+With the exception of
+\begin_inset Quotes sld
+\end_inset
+---L dir
+\begin_inset Quotes srd
+\end_inset
-\series bold
---float-reent
-\bar under
+ the
+\shape italic
+model
+\shape default
+ is auto-appended by the compiler (e.g.
+ small, large, z80, ds390 etc.).
-\series default
-\bar default
- Floating point library is compiled as reentrant.See section Installation
- for more details.
-\layout List
-\labelwidthstring 00.00.0000
+\newline
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="1.7in">
+<column alignment="left" valignment="top" leftline="true" width="1.2in">
+<column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
+<row topline="true" bottomline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---nooverlay
-\series default
- The compiler will not overlay parameters and local variables of any function,
- see section Parameters and local variables for more details.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+Search path
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---main-return
-\series default
- This option can be used when the code generated is called by a monitor
- program.
- The compiler will generate a 'ret' upon return from the 'main' function.
- The default option is to lock up i.e.
- generate a 'ljmp '.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+default
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
---no-peep
-\series default
- Disable peep-hole optimization.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+Win32 builds
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---peep-asm
-\series default
- Pass the inline assembler code through the peep hole optimizer.
- This can cause unexpected changes to inline assembler code, please go through
- the peephole optimizer rules defined in the source file tree '<target>/peeph.def
-' before using this option.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+---L dir
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---iram-size
-\series default
-<Value> Causes the linker to check if the internal ram usage is within limits
- of the given value.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+---L dir
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
---xram-size
-\series default
-<Value> Causes the linker to check if the external ram usage is within limits
- of the given value.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+---L dir
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---code-size
-\series default
-<Value> Causes the linker to check if the code usage is within limits of
- the given value.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+$SDCC_LIB/
+\newline
-\series bold
---nostdincl
-\series default
- This will prevent the compiler from passing on the default include path
- to the preprocessor.
-\layout List
-\labelwidthstring 00.00.0000
+\emph on
+<model>
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series bold
---nostdlib
-\series default
- This will prevent the compiler from passing on the default library path
- to the linker.
-\layout List
-\labelwidthstring 00.00.0000
+$SDCC_LIB/
+\newline
+\emph on
+<model>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\series bold
---verbose
-\series default
- Shows the various actions the compiler is performing.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
--V
-\series default
- Shows the actual commands the compiler is executing.
-\layout Subsubsection
-
-Intermediate Dump Options
\layout Standard
-The following options are provided for the purpose of retargetting and debugging
- the compiler.
- These provided a means to dump the intermediate code (iCode) generated
- by the compiler in human readable form at various stages of the compilation
- process.
-
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
---dumpraw
-\series default
- This option will cause the compiler to dump the intermediate code into
- a file of named
-\emph on
-<source filename>.dumpraw
-\emph default
- just after the intermediate code has been generated for a function, i.e.
- before any optimizations are done.
- The basic blocks at this stage ordered in the depth first number, so they
- may not be in sequence of execution.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
---dumpgcse
-\series default
- Will create a dump of iCode's, after global subexpression elimination,
- into a file named
-\emph on
-<source filename>.dumpgcse.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
---dumpdeadcode
-\series default
- Will create a dump of iCode's, after deadcode elimination, into a file
- named
-\emph on
-<source filename>.dumpdeadcode.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
---dumploop
-\series default
-\size large
-
-\size default
-Will create a dump of iCode's, after loop optimizations, into a file named
-
-\emph on
-<source filename>.dumploop.
-\layout List
-\labelwidthstring 00.00.0000
+$SDCC_LIB
+\backslash
+\newline
-\series bold
---dumprange
-\series default
-\size large
-
-\size default
-Will create a dump of iCode's, after live range analysis, into a file named
-
\emph on
-<source filename>.dumprange.
-\layout List
-\labelwidthstring 00.00.0000
-
+<model>
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\series bold
---dumlrange
-\series default
- Will dump the life ranges for all symbols.
-\layout List
-\labelwidthstring 00.00.0000
+\layout Standard
+$SDCC_HOME/
+\newline
-\series bold
---dumpregassign
-\bar under
-
-\series default
-\bar default
-Will create a dump of iCode's, after register assignment, into a file named
-
\emph on
-<source filename>.dumprassgn.
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
---dumplrange
-\series default
- Will create a dump of the live ranges of iTemp's
-\layout List
-\labelwidthstring 00.00.0000
-
-
-\series bold
---dumpall
-\size large
-\bar under
-
-\series default
-\size default
-\bar default
-Will cause all the above mentioned dumps to be created.
-\layout Subsection
-
-MCS51/DS390 Storage Class Language Extensions
-\layout Standard
-
-In addition to the ANSI storage classes SDCC allows the following MCS51
- specific storage classes.
-\layout Subsubsection
+$PREFIX2DATA_DIR/
+\newline
+$LIB_DIR_SUFFIX/<model>
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-xdata
\layout Standard
-Variables declared with this storage class will be placed in the extern
- RAM.
- This is the
-\series bold
-default
-\series default
- storage class for Large Memory model, e.g.:
+$SDCC_HOME/
\newline
-
+share/sdcc/
\newline
+lib/
+\emph on
+<model>
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\family typewriter
-xdata unsigned char xduc;
-\layout Subsubsection
-
-data
\layout Standard
-This is the
-\series bold
-default
-\series default
- storage class for Small Memory model.
- Variables declared with this storage class will be allocated in the internal
- RAM, e.g.:
-\newline
+$SDCC_HOME
+\backslash
+lib
+\backslash
-\newline
+\emph on
-\family typewriter
-data int iramdata;
-\layout Subsubsection
+\newline
+<model>
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-idata
\layout Standard
-Variables declared with this storage class will be allocated into the indirectly
- addressable portion of the internal ram of a 8051, e.g.:
+path(argv[0])/
\newline
+\emph on
+$BIN2DATADIR/
+\emph default
+
\newline
-\family typewriter
-idata int idi;
-\layout Subsubsection
+\emph on
+$LIB_DIR_SUFFIX/<model>
+\end_inset
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-bit
\layout Standard
-This is a data-type and a storage class specifier.
- When a variable is declared as a bit, it is allocated into the bit addressable
- memory of 8051, e.g.:
+path(argv[0])/
\newline
-
+../sdcc/lib/
+\emph on
+<model>
\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
-\family typewriter
-bit iFlag;
-\layout Subsubsection
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-sfr / sbit
\layout Standard
-Like the bit keyword,
-\emph on
-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:
-\newline
+path(argv[0])
+\backslash
\newline
+..
+\backslash
+lib
+\backslash
-\family typewriter
-sfr at 0x80 P0; /* special function register P0 at location 0x80 */
+\emph on
+<model>
\newline
-sbit at 0xd7 CY; /* CY (Carry Flag) */
-\layout Subsection
-
-Pointers
-\layout Standard
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
-SDCC allows (via language extensions) pointers to explicitly point to any
- of the memory spaces of the 8051.
- In addition to the explicit pointers, the compiler uses (by default) generic
- pointers which can be used to point to any of the memory spaces.
-\newline
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-Pointer declaration examples:
-\newline
+\layout Standard
-\size small
+\emph on
+$DATADIR/
\newline
+$LIB_DIR_SUFFIX/<model>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family typewriter
-\size default
-/* pointer physically in xternal ram pointing to object in internal ram
- */
-\newline
-data unsigned char * xdata p;
-\newline
+\layout Standard
+/usr/local/share/sdcc/
\newline
-/* pointer physically in code rom pointing to data in xdata space */
-\newline
-xdata unsigned char * code p;
-\newline
+lib/
+\emph on
+<model>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
-/* pointer physically in code space pointing to data in code space */
-\newline
-code unsigned char * code p;
-\newline
+\layout Standard
-\newline
-/* the folowing is a generic pointer physically located in xdata space */
-\newline
-char * xdata p;
-\family default
-\size small
+(not on Win32)
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-\newline
+\end_inset
-\newline
-\size default
-Well you get the idea.
-
-\newline
+\layout Comment
-\newline
-All unqualified pointers are treated as 3-byte (4-byte for the ds390)
-\emph on
-generic
-\emph default
- pointers.
-
-\size small
+Don't delete any of the stray spaces in the table above without checking
+ the HTML output (last line)!
+\layout Standard
-\newline
+\SpecialChar ~
\newline
-
-\size default
-The highest order byte of the
-\emph on
-generic
-\emph default
- pointers contains the data space information.
- Assembler support routines are called whenever data is stored or retrieved
- using
-\emph on
-generic
-\emph default
- pointers.
- These are useful for developing reusable library routines.
- Explicitly specifying the pointer type will generate the most efficient
- code.
+The option ---nostdlib disables the last two search paths.
\layout Subsection
-Parameters & Local Variables
-\layout Standard
+Building SDCC
+\layout Subsubsection
-Automatic (local) variables and parameters to functions can either be placed
- on the stack or in data-space.
- The default action of the compiler is to place these variables in the internal
- RAM (for small model) or external RAM (for large model).
- This in fact makes them
-\emph on
-static
-\emph default
- so by default functions are non-reentrant.
-\newline
+Building SDCC on Linux
+\layout Enumerate
-\newline
-They can be placed on the stack either by using the
-\emph on
- --stack-auto
-\emph default
- option or by using the
-\emph on
-reentrant
-\emph default
- keyword in the function declaration, e.g.:
-\newline
-\size small
+\series medium
+Download the source package
+\series default
+ either from the SDCC CVS repository or from the
+\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
-\newline
+\end_inset
-\family typewriter
-\size default
-unsigned char foo(char i) reentrant
-\newline
-{
-\newline
-...
-
-\newline
-}
-\newline
-\family default
+\series medium
+, it will be named something like sdcc
+\series default
+.src
+\series medium
+.t
+\series default
+ar.
+\series medium
+gz.
+\layout Enumerate
-\newline
-Since stack space on 8051 is limited, the
-\emph on
-reentrant
-\emph default
-keyword or the
-\emph on
- --stack-auto
-\emph default
- option should be used sparingly.
- Note that the reentrant keyword just means that the parameters & local
- variables will be allocated to the stack, it
-\emph on
-does not
-\emph default
- mean that the function is register bank independent.
-\newline
-\newline
-Local variables can be assigned storage classes and absolute addresses,
- e.g.:
-\newline
+\series medium
+Bring up a command line terminal, such as xterm.
+\layout Enumerate
-\newline
-\family typewriter
-unsigned char foo() {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-xdata unsigned char i;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-bit bvar;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-data at 0x31 unsiged char j;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
-\newline
+\series medium
+Unpack the file using a command like:
+\family sans
+\series bold
+"tar -xzf sdcc.src.tar.gz
+\family default
+\series default
+"
+\series medium
+, this will create a sub-directory called sdcc with all of the sources.
+\layout Enumerate
-\newline
+Change directory into the main SDCC directory, for example type:
+\family sans
+\series bold
+"cd sdcc
+\series default
+".
+\layout Enumerate
+
+\series medium
+Type
+\family sans
+\series bold
+"./configure
\family default
-In the above example the variable
-\emph on
-i
-\emph default
- will be allocated in the external ram,
-\emph on
-bvar
-\emph default
- in bit addressable space and
-\emph on
- j
-\emph default
- in internal ram.
- When compiled with
-\emph on
---stack-auto
-\emph default
- or when a function is declared as
-\emph on
-reentrant
-\emph default
- this should only be done for static variables.
-\layout Standard
+\series default
+".
+ This configures the package for compilation on your system.
+\layout Enumerate
-Parameters however are not allowed any storage class, (storage classes for
- parameters will be ignored), their allocation is governed by the memory
- model in use, and the reentrancy options.
-\layout Subsection
-Overlaying
-\layout Standard
+\series medium
+Type
+\family sans
+\series bold
+"make
+\family default
+\series default
+"
+\series medium
+.
-For non-reentrant functions SDCC will try to reduce internal ram space usage
- by overlaying parameters and local variables of a function (if possible).
- Parameters and local variables of a function will be allocated to an overlayabl
-e segment if the function has
-\emph on
-no other function calls and the function is non-reentrant and the memory
- model is small.
+\series default
+ All of the source packages will compile, this can take a while.
+\layout Enumerate
-\emph default
- If an explicit storage class is specified for a local variable, it will
- NOT be overlayed.
-\layout Standard
-Note that the compiler (not the linkage editor) makes the decision for overlayin
-g the data items.
- Functions that are called from an interrupt service routine should be preceded
- by a #pragma\SpecialChar ~
-NOOVERLAY if they are not reentrant.
-\layout Standard
+\series medium
+Type
+\family sans
+\series bold
+"make install"
+\family default
+\series default
+ as root
+\series medium
+.
-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.
+\series default
+ This copies the binary executables, the include files, the libraries and
+ the documentation to the install directories.
+\layout Subsubsection
+
+Building SDCC on OSX 2.x
\layout Standard
-Parameters and Local variables of functions that contain 16 or 32 bit multiplica
-tion or division will NOT be overlayed since these are implemented using
- external functions, e.g.:
+Follow the instruction for Linux.
\newline
\newline
+On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
+)) fails to compile SDCC.
+ Fortunately there's also gcc 2.9.x installed, which works fine.
+ This compiler can be selected by running 'configure' with:
+\layout LyX-Code
-\family typewriter
-#pragma SAVE
-\newline
-#pragma NOOVERLAY
-\newline
-void set_error(unsigned char errcd)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-P3 = errcd;
-\newline
-}
-\newline
-#pragma RESTORE
-\newline
+./configure CC=gcc2 CXX=g++2
+\layout Subsubsection
-\newline
-void some_isr () interrupt 2 using 1
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-set_error(10);
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
-\newline
+Crosscompiling SDCC on Linux for Windows
+\layout Standard
-\newline
+With the Mingw32 gcc crosscompiler it's easy to compile SDCC for Win32.
+ See section 'Configure Options'.
+\layout Subsubsection
-\family default
-In the above example the parameter
-\emph on
-errcd
-\emph default
- for the function
-\emph on
-set_error
-\emph default
- would be assigned to the overlayable segment if the #pragma\SpecialChar ~
-NOOVERLAY was
- not present, this could cause unpredictable runtime behavior when called
- from an ISR.
- The #pragma\SpecialChar ~
-NOOVERLAY ensures that the parameters and local variables for
- the function are NOT overlayed.
-\layout Subsection
+Building SDCC on Windows
+\layout Standard
-Interrupt Service Routines
+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
+
+Windows Install Using a Binary Package
+\layout Enumerate
+
+Download the binary package 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:
+\backslash
+sdcc
+\backslash
+bin for the executables, c:
+\backslash
+sdcc
+\backslash
+include and c:
+\backslash
+sdcc
+\backslash
+lib for the include and libraries.
+\layout Enumerate
+
+Adjust your environment variable PATH to include the location of the bin
+ directory or start sdcc using the full path.
+\layout Subsubsection
+
+Building SDCC using Cygwin and Mingw32
\layout Standard
-SDCC allows interrupt service routines to be coded in C, with some extended
- keywords.
+For building and installing a Cygwin executable follow the instructions
+ for Linux.
\newline
\newline
+On Cygwin a
+\begin_inset Quotes sld
+\end_inset
-\family typewriter
-void timer_isr (void) interrupt 2 using 1
-\newline
-{
-\newline
-..
-
-\newline
-}
+native
+\begin_inset Quotes srd
+\end_inset
+
+ 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'.
\newline
\newline
+In order to install Cygwin on Windows download setup.exe from
+\begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
-\family default
-The number following the
-\emph on
-interrupt
-\emph default
- keyword is the interrupt number this routine will service.
- The compiler will insert a call to this routine in the interrupt vector
- table for the interrupt number specified.
- The
-\emph on
-using
-\emph default
- keyword is 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 if it is not reentrant.
- A special note here, int (16 bit) and long (32 bit) integer division, multiplic
-ation & modulus 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
- --stack-auto
-\emph default
- option and the source file will need to be compiled using the
-\emph on
---int-long-ren
-\emph default
-t compiler option.
-\layout Standard
+\end_inset
-If you have multiple source files in your project, interrupt service routines
- can be present in any of them, but a prototype of the isr MUST be present
- or included in the file that contains the function
-\emph on
-main
-\emph default
.
-\layout Standard
+ Run it, set the
+\begin_inset Quotes sld
+\end_inset
-Interrupt Numbers and the corresponding address & descriptions for the Standard
- 8051 are listed below.
- SDCC will automatically adjust the interrupt vector table to the maximum
- interrupt number specified.
-\newline
+default text file type
+\begin_inset Quotes srd
+\end_inset
-\layout Standard
+ to
+\begin_inset Quotes sld
+\end_inset
+unix
+\begin_inset Quotes srd
+\end_inset
-\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
-<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" rightline="true" width="0(null)">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ and download/install at least the following packages.
+ Some packages are selected by default, others will be automatically selected
+ because of dependencies with the manually selected packages.
+ Never deselect these packages!
+\layout Itemize
-\layout Standard
+flex
+\layout Itemize
-Interrupt #
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+bison
+\layout Itemize
-\layout Standard
+gcc ; version 3.x is fine, no need to use the old 2.9x
+\layout Itemize
-Description
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+binutils ; selected with gcc
+\layout Itemize
-\layout Standard
+make
+\layout Itemize
-Vector Address
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+rxvt ; a nice console, which makes life much easier under windoze (see below)
+\layout Itemize
-\layout Standard
+man ; not really needed for building SDCC, but you'll miss it sooner or
+ later
+\layout Itemize
-0
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+less ; not really needed for building SDCC, but you'll miss it sooner or
+ later
+\layout Itemize
+cvs ; only if you use CVS access
\layout Standard
-External 0
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+If you want to develop something you'll need:
+\layout Itemize
-\layout Standard
+python ; for the regression tests
+\layout Itemize
-0x0003
+gdb ; the gnu debugger, together with the nice GUI
+\begin_inset Quotes sld
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-1
+insight
+\begin_inset Quotes srd
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-Timer 0
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\layout Itemize
-0x000B
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+openssh ; to access the CF or commit changes
+\layout Itemize
+autoconf and autoconf-devel ; if you want to fight with 'configure', don't
+ use autoconf-stable!
\layout Standard
-2
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+rxvt is a nice console with history.
+ Replace in your cygwin.bat the line
+\layout LyX-Code
+bash --login -i
\layout Standard
-External 1
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+with (one line):
+\layout LyX-Code
-0x0013
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
+\layout LyX-Code
+ -bg black -fg white -geometry 100x65 -e bash --login
\layout Standard
-3
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+Text selected with the mouse is automatically copied to the clipboard, pasting
+ works with shift-insert.
+\newline
-Timer 1
+\newline
+The other good tip is to make sure you have no //c/-style paths anywhere,
+ use /cygdrive/c/ instead.
+ Using // invokes a network lookup which is very slow.
+ If you think
+\begin_inset Quotes sld
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-
-0x001B
+cygdrive
+\begin_inset Quotes srd
\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ is too long, you can change it with e.g.
+\layout LyX-Code
+
+mount -s -u -c /mnt
\layout Standard
-4
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+SDCC sources use the unix line ending LF.
+ Life is much easier, if you store the source tree on a drive, which is
+ mount in binary mode.
+ And use an editor which can handle LF-only line endings.
+ Make sure not to commit files with windows line endings.
+\layout Subsubsection
+Windows Install Using Microsoft Visual C++ 6.0/NET
\layout Standard
-Serial
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\series medium
+Download the source package
+\series default
+ either from the SDCC CVS repository or from the
+\begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
-0x0023
\end_inset
-</cell>
-</row>
-</lyxtabular>
-\end_inset
+\series medium
+, it will be named something like sdcc
+\series default
+.src
+\series medium
+.tgz.
+\series default
+ SDCC is distributed with all the projects, workspaces, and files you need
+ to build it using Visual C++ 6.0/NET.
+ The workspace name is 'sdcc.dsw'.
+ Please note that as it is now, all the executables are created in a folder
+ called sdcc
+\backslash
+bin_vc.
+ Once built you need to copy the executables from sdcc
+\backslash
+bin_vc to sdcc
+\backslash
+bin before runnng SDCC.
+
\newline
\newline
-If the interrupt service routine is defined without
-\emph on
-using
-\emph default
- a register bank or with register bank 0 (using 0), the compiler will save
- the registers used by itself on the stack upon entry and restore them at
- exit, however if such an interrupt service routine calls another function
- then the entire register bank will be saved on the stack.
- This scheme may be advantageous for small interrupt service routines which
- have low register usage.
-\layout Standard
+In order to build SDCC with Visual C++ 6.0/NET you need win32 executables
+ of bison.exe, flex.exe, and gawk.exe.
+ One good place to get them is
+\begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
-If the interrupt service routine is defined to be using a specific register
- bank then only
-\emph on
-a, b & dptr
-\emph default
- are save and restored, if such an interrupt service routine calls another
- function (using another register bank) then the entire register bank of
- the called function will be saved on the stack.
- This scheme is recommended for larger interrupt service routines.
-\layout Standard
+\end_inset
-Calling other functions from an interrupt service routine is not recommended,
- avoid it if possible.
-\newline
\newline
-Also see the _naked modifier.
-\layout Subsection
-
-Critical Functions
-\layout Standard
+\newline
+Download the file UnxUtils.zip.
+ Now you have to install the utilities and setup Visual C++ so it can locate
+ the required programs.
+ Here there are two alternatives (choose one!):
+\layout Enumerate
-\shape italic
-<TODO: this isn't implemented at all!>
-\shape default
+The easy way:
+\newline
\newline
+a) Extract UnxUtils.zip to your C:
+\backslash
+ hard disk PRESERVING the original paths, otherwise bison won't work.
+ (If you are using WinZip make certain that 'Use folder names' is selected)
+\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.
+b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
+ in 'Show directories for:' select 'Executable files', and in the directories
+ window add a new path: 'C:
+\backslash
+user
+\backslash
+local
+\backslash
+wbin', click ok.
\newline
-\size small
+\newline
+(As a side effect, you get a bunch of Unix utilities that could be useful,
+ such as diff and patch.)
+\layout Enumerate
+A more compact way:
\newline
-\family typewriter
-\size default
-int foo () critical
\newline
-{
+This one avoids extracting a bunch of files you may not use, but requires
+ some extra work:
\newline
-...
-
+
\newline
-...
-
+a) Create a directory were to put the tools needed, or use a directory already
+ present.
+ Say for example 'C:
+\backslash
+util'.
\newline
-}
+
+\newline
+b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
+ to such directory WITHOUT preserving the original paths.
+ (If you are using WinZip make certain that 'Use folder names' is not selected)
\newline
-\family default
+\newline
+c) Rename bison.exe to '_bison.exe'.
+\newline
\newline
-The critical attribute maybe used with other attributes like
-\emph on
-reentrant.
-\layout Subsection
-
-Naked Functions
-\layout Standard
-
-A special keyword may be associated with a function declaring it as
-\emph on
-_naked.
-
-\emph default
-The
-\emph on
-_naked
-\emph default
- function modifier attribute prevents the compiler from generating prologue
- and epilogue code for that function.
- This means that the user is entirely responsible for such things as saving
- any registers that may need to be preserved, selecting the proper register
- bank, generating the
-\emph on
-return
-\emph default
- instruction at the end, etc.
- Practically, this means that the contents of the function must be written
- in inline assembler.
- This is particularly useful for interrupt functions, which can have a large
- (and often unnecessary) prologue/epilogue.
- For example, compare the code generated by these two functions:
-\newline
-
-\newline
-
-\family typewriter
-data unsigned char counter;
-\newline
-void simpleInterrupt(void) interrupt 1
+d) Create a batch file 'bison.bat' in 'C:
+\backslash
+util
+\backslash
+' and add these lines:
\newline
-{
+\SpecialChar ~
+\SpecialChar ~
+set BISON_SIMPLE=C:
+\backslash
+util
+\backslash
+bison.simple
\newline
\SpecialChar ~
\SpecialChar ~
+set BISON_HAIRY=C:
+\backslash
+util
+\backslash
+bison.hairy
+\newline
\SpecialChar ~
\SpecialChar ~
-counter++;
+_bison %1 %2 %3 %4 %5 %6 %7 %8 %9
\newline
-}
+
+\newline
+Steps 'c' and 'd' are needed because bison requires by default that the
+ files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
+ '/usr/local/share/' I think.
+ So it is necessary to tell bison where those files are located if they
+ are not in such directory.
+ That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
\newline
\newline
-void nakedInterrupt(void) interrupt 2 _naked
+e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
+ in 'Show directories for:' select 'Executable files', and in the directories
+ window add a new path: 'c:
+\backslash
+util', click ok.
+ Note that you can use any other path instead of 'c:
+\backslash
+util', even the path where the Visual C++ tools are, probably: 'C:
+\backslash
+Program Files
+\backslash
+Microsoft Visual Studio
+\backslash
+Common
+\backslash
+Tools'.
+ So you don't have to execute step 'e' :)
+\layout Standard
+
+That is it.
+ Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
+ the executables from sdcc
+\backslash
+bin_vc to sdcc
+\backslash
+bin, and you can compile using sdcc.
+\layout Subsubsection
+
+Windows Install Using Borland
+\layout Enumerate
+
+From the sdcc directory, run the command "make -f Makefile.bcc".
+ This should regenerate all the .exe files in the bin directory except for
+ sdcdb.exe (which currently doesn't build under Borland C++).
+\layout Enumerate
+
+If you modify any source files and need to rebuild, be aware that the dependanci
+es may not be correctly calculated.
+ The safest option is to delete all .obj files and run the build again.
+ From a Cygwin BASH prompt, this can easily be done with the commmand:
\newline
-{
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_asm
+
+\family sans
+\series bold
+find .
+
+\backslash
+( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
+\backslash
+) -print -exec rm {}
+\backslash
+;
+\family default
+\series default
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-inc\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_counter
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-reti\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-; MUST explicitly include ret in _naked function.
+or on Windows NT/2000/XP from the command prompt with the commmand:
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_endasm;
+
+\family sans
+\series bold
+
\newline
-}
+del /s *.obj *.lib *.rul
+\family default
+\series default
+ from the sdcc directory.
+\layout Subsection
+
+Building the Documentation
+\layout Standard
+
+...
+ coming soon
+\layout Subsection
+
+Testing out the SDCC Compiler
+\layout Standard
+
+The first thing you should do after installing your SDCC compiler is to
+ see if it runs.
+ Type
+\family sans
+\series bold
+"sdcc ---version"
\family default
+\series default
+ at the prompt, and the program should run and tell you the version.
+ 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).
+ Make sure that the sdcc program is in the bin folder, if not perhaps something
+ did not install correctly.
+\newline
\newline
+\series medium
+SDCC
+\series default
+is commonly installed as described in section
+\begin_inset Quotes sld
+\end_inset
+
+Install and search paths
+\begin_inset Quotes srd
+\end_inset
+
+
\newline
-For an 8051 target, the generated simpleInterrupt looks like:
+
\newline
+\series medium
+Make sure the compiler works on a very simple example.
+ Type in the following test.c program using your favorite
+\series default
+ascii
+\series medium
+editor:
+\series default
+
\newline
\family typewriter
-_simpleIterrupt:
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-push\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-acc
+char test;
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-push\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-push\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-dpl
+void main(void) {
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-push\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-dph
+test=0;
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-push\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-psw
+}
+\family default
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-psw,#0x00
+
+\emph on
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-inc\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_counter
+
+\series medium
+\emph default
+Compile this using the following command:
+\family sans
+\series bold
+"sdcc -c test.c".
+
+\family default
+\series default
+
+\series medium
+If all goes well, the compiler will generate a test.asm and test.rel file.
+ Congratulations, you've just compiled your first program with SDCC.
+ We used the -c option to tell SDCC not to link the generated code, just
+ to keep things simple for this step.
+\series default
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-psw
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-dph
+
+\series medium
+The next step is to try it with the linker.
+ Type in
+\family sans
+\series bold
+"sdcc test.c
+\family default
+\series default
+"
+\series medium
+.
+ If all goes well the compiler will link with the libraries and produce
+ a test.ihx output file.
+ If this step fails
+\series default
+
+\series medium
+(no test.ihx, and the linker generates warnings), then the problem is most
+ likely that sdcc cannot find the
+\series default
+/
+\series medium
+usr/local/share/sdcc/lib directory
+\series default
+
+\series medium
+(see the Install trouble-shooting section for suggestions).
+\series default
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-dpl
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b
+
+\series medium
+The final test is to ensure sdcc can use the
+\series default
+standard
+\series medium
+ header files and libraries.
+ Edit test.c and change it to the following:
+\series default
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-pop\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-acc
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-reti
-\family default
+\family typewriter
+#include <string.h>
\newline
\newline
-whereas nakedInterrupt looks like:
+char str1[10];
\newline
\newline
-
-\family typewriter
-_nakedInterrupt:
+void main(void) {
\newline
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-inc\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_counter
+strcpy(str1, "testing");
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-reti\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-; MUST explicitly include ret(i) in _naked function.
-\family default
-
+}
\newline
\newline
-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 is is recommended that you stick to inline assembler.
+
+\family default
+\series medium
+Compile this by typing
+\family sans
+\series bold
+"sdcc test.c"
+\family default
+\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
+\series default
+
+\series medium
+(see the Install trouble-shooting section for suggestions).
\layout Subsection
-Functions using private banks
-\layout Standard
+Install Trouble-shooting
+\layout Subsubsection
-The
-\emph on
-using
-\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
-\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.
+SDCC does not build correctly.
\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 true
+A thing to try is starting from scratch by unpacking the .tgz source package
+ again in an empty directory.
+ Configure it like:
+\newline
-\layout Standard
+\newline
-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
+\family sans
+\series bold
+./configure 2>&1 | tee configure.log
+\family default
+\series default
-).
\newline
-\emph on
-(pending: I don't think this has been done yet)
+\newline
+and build it like:
+\newline
+
+\newline
+
+\family sans
+\series bold
+make 2>&1 | tee make.log
+\family default
+\series default
+
+\newline
+
+\newline
+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
+
+What the
+\begin_inset Quotes sld
+\end_inset
+
+./configure
+\begin_inset Quotes srd
+\end_inset
+
+ does
\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 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.
+The
+\begin_inset Quotes sld
+\end_inset
+
+./configure
+\begin_inset Quotes srd
+\end_inset
+
+ command is a script that analyzes your system and performs some configuration
+ 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
+
+What the
+\begin_inset Quotes sld
+\end_inset
+
+make
+\begin_inset Quotes srd
+\end_inset
+
+ does.
\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
+This runs the GNU make tool, which automatically compiles all the source
+ packages into the final installed binary executables.
+\layout Subsubsection
-Absolute Addressing
+What the
+\begin_inset Quotes sld
+\end_inset
+
+make install
+\begin_inset Quotes erd
+\end_inset
+
+ command does.
\layout Standard
-Data items can be assigned an absolute address with the
-\emph on
-at <address>
-\emph default
- keyword, in addition to a storage class, e.g.:
-\newline
+This will install the compiler, other executables libraries and include
+ files in to the appropriate directories.
+ See section
+\begin_inset Quotes sld
+\end_inset
-\newline
+Install and Search PATHS
+\begin_inset Quotes srd
+\end_inset
-\family typewriter
-xdata at 0x8000 unsigned char PORTA_8255 ;
+.
\newline
+On most systems you will need super-user privilages to do this.
+\layout Subsection
-\family default
+Components of SDCC
+\layout Standard
-\newline
-In the above example the PORTA_8255 will be allocated to the location 0x8000
- of the external ram.
- Note that this feature is provided to give the programmer access to
-\emph on
-memory mapped
-\emph default
- devices attached to the controller.
- The compiler does not actually reserve any space for variables declared
- in this way (they are implemented with an equate in the assembler).
- Thus it is left to the programmer to make sure there are no overlaps with
- other variables that are declared without the absolute address.
- The assembler listing file (.lst) and the linker output files (.rst) and
- (.map) are a good places to look for such overlaps.
+SDCC is not just a compiler, but a collection of tools by various developers.
+ These include linkers, assemblers, simulators and other components.
+ Here is a summary of some of the components.
+ Note that the included simulator and assembler have separate documentation
+ which you can find in the source package in their respective directories.
+ As SDCC grows to include support for other processors, other packages from
+ various developers are included and may have their own sets of documentation.
\newline
\newline
-Absolute address can be specified for variables in all storage classes,
- e.g.:
+You might want to look at the files which are installed in <installdir>.
+ At the time of this writing, we find the following programs for gcc-builds:
\newline
-
+
\newline
+In <installdir>/bin:
+\layout Itemize
-\family typewriter
-bit at 0x02 bvar;
-\newline
+sdcc - The compiler.
+\layout Itemize
-\newline
+sdcpp - The C preprocessor.
+\layout Itemize
-\family default
-The above example will allocate the variable at offset 0x02 in the bit-addressab
-le space.
- There is no real advantage to assigning absolute addresses to variables
- in this manner, unless you want strict control over all the variables allocated.
-\layout Subsection
+asx8051 - The assembler for 8051 type processors.
+\layout Itemize
-Startup Code
-\layout Standard
+as-z80
+\series bold
+,
+\series default
+as-gbz80 - The Z80 and GameBoy Z80 assemblers.
+\layout Itemize
-The compiler inserts a call to the C routine
-\emph on
-_sdcc__external__startup()
+aslink -The linker for 8051 type processors.
+\layout Itemize
+
+link-z80
\series bold
-\emph default
-
+,
\series default
-at the start of the CODE area.
- This routine is in the runtime library.
- 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 Other wise 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.
-\layout Subsection
+link-gbz80 - The Z80 and GameBoy Z80 linkers.
+\layout Itemize
-Inline Assembler Code
-\layout Standard
+s51 - The ucSim 8051 simulator.
+\layout Itemize
-SDCC allows the use of in-line assembler with a few restriction as regards
- labels.
- All labels defined within inline assembler code
-\emph on
-has to be
-\emph default
- of the form
-\emph on
-nnnnn$
-\emph default
- where nnnn is a number less than 100 (which implies a limit of utmost 100
- inline assembler labels
-\emph on
-per function
-\emph default
-\noun on
-)
-\noun default
-.
- It is strongly recommended that each assembly instruction (including labels)
- be placed in a separate line (as the example shows).
- When the
-\emph on
---peep-asm
-\emph default
- command line option is used, the inline assembler code will be passed through
- the peephole optimizer.
- This might cause some unexpected changes in the inline assembler code.
- Please go throught the peephole optimizer rules defined in file
-\emph on
-SDCCpeeph.def
-\emph default
- carefully before using this option.
-\newline
+sdcdb - The source debugger.
+\layout Itemize
-\newline
+packihx - A tool to pack (compress) Intel hex files.
+\layout Standard
-\family typewriter
-_asm
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b,#10
-\newline
-00001$:
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-djnz\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b,00001$
-\newline
-_endasm ;
-\family default
-\size small
+In <installdir>/share/sdcc/include
+\layout Itemize
-\newline
+the include files
+\layout Standard
-\newline
+In <installdir>/share/sdcc/lib
+\layout Itemize
-\size default
-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
+the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
+ relocatables.
+\layout Standard
-\newline
-Inline assembler code cannot reference any C-Labels, however it can reference
- labels defined by the inline assembler, e.g.:
-\newline
+In <installdir>/share/sdcc/doc
+\layout Itemize
+
+the documentation
+\layout Standard
+
+As development for other processors proceeds, this list will expand to include
+ executables to support processors like AVR, PIC, etc.
+\layout Subsubsection
+
+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
+
+sdcpp - The C-Preprocessor
+\layout Standard
+
+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
+
+asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 - The Assemblers
+ and Linkage Editors
+\layout Standard
+
+This is retargettable assembler & linkage editor, it was developed by Alan
+ Baldwin.
+ John Hartman created the version for 8051, and I (Sandeep) have made some
+ enhancements and bug fixes for it to work properly with the SDCC.
+\layout Subsubsection
+
+s51 - The Simulator
+\layout Standard
+
+S51 is a freeware, opensource simulator developed by Daniel Drotos (
+\begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
+
+\end_inset
+
+).
+ The simulator is built as part of the build process.
+ For more information visit Daniel's website at:
+\begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
+
+\end_inset
+
+.
+ It currently support the core mcs51, the Dallas DS80C390 and the Philips
+ XA51 family.
+\layout Subsubsection
+
+sdcdb - Source Level Debugger
+\layout Standard
-\newline
\family typewriter
-foo() {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* some c code */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_asm
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-; some assembler code
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ljmp $0003
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_endasm;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* some more c code */
-\newline
-clabel:\SpecialChar ~
-\SpecialChar ~
-/* inline assembler cannot reference this label */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_asm
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-$0003: ;label (can be reference by inline assembler only)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-_endasm ;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* some more c code */
-\newline
-}
+\shape italic
+<todo: is this thing still alive?>
\newline
\newline
\family default
-In other words inline assembly code can access labels defined in inline
- assembly within the scope of the funtion.
-
-\layout Standard
+\shape default
+Sdcdb is the companion source level debugger.
+ The current version of the debugger uses Daniel's Simulator S51, but can
+ be easily changed to use other simulators.
+\layout Section
-The same goes the other way, ie.
- labels defines in inline assembly CANNOT be accessed by C statements.
+Using SDCC
\layout Subsection
-int(16 bit) and long (32 bit) Support
+Compiling
+\layout Subsubsection
+
+Single Source File Projects
\layout Standard
-For signed & unsigned int (16 bit) and long (32 bit) variables, division,
- multiplication and modulus operations are implemented by support routines.
- These support routines are all developed in ANSI-C to facilitate porting
- to other MCUs, although some model specific assembler optimations are used.
- The following files contain the described routine, all of them can be found
- in <installdir>/share/sdcc/lib.
-\newline
+For single source file 8051 projects the process is very simple.
+ Compile your programs with the following command
+\family sans
+\series bold
+"sdcc sourcefile.c".
+\family default
+\series default
+ This will compile, assemble and link your source file.
+ Output files are as follows
\newline
-\emph on
-<pending: tabularise this>
-\emph default
-
\newline
-
+sourcefile.asm - Assembler source file created by the compiler
\newline
-_mulsint.c - signed 16 bit multiplication (calls _muluint)
+sourcefile.lst - Assembler listing file created by the Assembler
\newline
-_muluint.c - unsigned 16 bit multiplication
+sourcefile.rst - Assembler listing file updated with linkedit information,
+ created by linkage editor
\newline
-_divsint.c - signed 16 bit division (calls _divuint)
+sourcefile.sym - symbol listing for the sourcefile, created by the assembler
\newline
-_divuint.c - unsigned 16 bit division
+sourcefile.rel - Object file created by the assembler, input to Linkage editor
\newline
-_modsint.c - signed 16 bit modulus (call _moduint)
+sourcefile.map - The memory map for the load module, created by the Linker
\newline
-_moduint.c - unsigned 16 bit modulus
+sourcefile.ihx - The load module in Intel hex format (you can select the
+ Motorola S19 format with ---out-fmt-s19)
\newline
-_mulslong.c - signed 32 bit multiplication (calls _mululong)
+sourcefile.cdb - An optional file (with ---debug) containing debug information
\newline
-_mululong.c - unsigned32 bit multiplication
+sourcefile.dump* - Dump file to debug the compiler it self (with ---dumpall)
+ (see section
+\begin_inset Quotes sld
+\end_inset
+
+Anatomy of the compiler
+\begin_inset Quotes srd
+\end_inset
+
+).
+\layout Subsubsection
+
+Projects with Multiple Source Files
+\layout Standard
+
+SDCC can compile only ONE file at a time.
+ Let us for example assume that you have a project containing the following
+ files:
\newline
-_divslong.c - signed 32 division (calls _divulong)
+
\newline
-_divulong.c - unsigned 32 division
+foo1.c (contains some functions)
\newline
-_modslong.c - signed 32 bit modulus (calls _modulong)
+foo2.c (contains some more functions)
\newline
-_modulong.c - unsigned 32 bit modulus
-\size footnotesize
-
+foomain.c (contains more functions and the function main)
\newline
+\size footnotesize
+
\newline
\size default
-Since they are compiled as
-\emph on
-non-reentrant
-\emph default
-, interrupt service routines should not do any of the above operations.
- If this is unavoidable then the above routines will need to be compiled
- with the
-\emph on
---stack-auto
-\emph default
- option, after which the source program will have to be compiled with
-\emph on
---int-long-rent
-\emph default
- option.
-\layout Subsection
-
-Floating Point Support
-\layout Standard
+The first two files will need to be compiled separately with the commands:
+\size footnotesize
+
+\size default
-SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
- point support routines are derived from gcc's floatlib.c and consists of
- the following routines:
\newline
\newline
-\emph on
-<pending: tabularise this>
-\emph default
+\family sans
+\series bold
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foo1.c
+\family default
+\series default
+\size footnotesize
\newline
+\family sans
+\series bold
+\size default
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foo2.c
+\family default
+\series default
+
\newline
-_fsadd.c - add floating point numbers
-\newline
-_fssub.c - subtract floating point numbers
-\newline
-_fsdiv.c - divide floating point numbers
-\newline
-_fsmul.c - multiply floating point numbers
-\newline
-_fs2uchar.c - convert floating point to unsigned char
-\newline
-_fs2char.c - convert floating point to signed char
-\newline
-_fs2uint.c - convert floating point to unsigned int
-\newline
-_fs2int.c - convert floating point to signed int
+
\newline
-_fs2ulong.c - convert floating point to unsigned long
+Then compile the source file containing the
+\emph on
+main()
+\emph default
+ function and link the files together with the following command:
\newline
-_fs2long.c - convert floating point to signed long
+
\newline
-_uchar2fs.c - convert unsigned char to floating point
+
+\family sans
+\series bold
+sdcc\SpecialChar ~
+foomain.c\SpecialChar ~
+foo1.rel\SpecialChar ~
+foo2.rel
+\family default
+\series default
+
\newline
-_char2fs.c - convert char to floating point number
+
\newline
-_uint2fs.c - convert unsigned int to floating point
+Alternatively,
+\emph on
+foomain.c
+\emph default
+can be separately compiled as well:
+\family sans
+\series bold
+
\newline
-_int2fs.c - convert int to floating point numbers
+
\newline
-_ulong2fs.c - convert unsigned long to floating point number
+sdcc\SpecialChar ~
+-c\SpecialChar ~
+foomain.c
\newline
-_long2fs.c - convert long to floating point number
-\size footnotesize
-
+sdcc foomain.rel foo1.rel foo2.rel
\newline
\newline
-\size default
-Note if all these routines are used simultaneously the data space might
- overflow.
- For serious floating point usage it is strongly recommended that the large
- model be used.
-\layout Subsection
-
-MCS51 Memory Models
-\layout Standard
-
-SDCC allows two memory models for MCS51 code, small and large.
- Modules compiled with different memory models should
+\family default
+\series default
+The file containing the
\emph on
-never
+main()
\emph default
- be combined together or the results would be unpredictable.
- The library routines supplied with the compiler are compiled as both small
- and large.
- The compiled library modules are contained in seperate directories as small
- and large so that you can link to either set.
+ function
+\emph on
-\layout Standard
-
-When the large model is used all variables declared without a storage class
- will be allocated into the external ram, this includes all parameters and
- local variables (for non-reentrant functions).
- When the small model is used variables without storage class are allocated
- in the internal ram.
-\layout Standard
-
-Judicious usage of the processor specific storage classes and the 'reentrant'
- function type will yield much more efficient code, than using the large
- model.
- Several optimizations are disabled when the program is compiled using the
- large model, it is therefore strongly recommdended that the small model
- be used unless absolutely required.
-\layout Subsection
+\emph default
+\noun on
+must
+\noun default
+ be the
+\noun on
+first
+\noun default
+ file specified in the command line, since the linkage editor processes
+ file in the order they are presented to it.
+\layout Subsubsection
-DS390 Memory Models
+Projects with Additional Libraries
\layout Standard
-The only model supported is Flat 24.
- This generates code for the 24 bit contiguous addressing mode of the Dallas
- DS80C390 part.
- In this mode, up to four meg of external RAM or code space can be directly
- addressed.
- See the data sheets at www.dalsemi.com for further information on this part.
-\newline
-
-\newline
-In older versions of the compiler, this option was used with the MCS51 code
- generator (
+Some reusable routines may be compiled into a library, see the documentation
+ for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
+ for how to create a
\emph on
--mmcs51
+.lib
\emph default
-).
- Now, however, the '390 has it's own code generator, selected by the
+ library file.
+ Libraries created in this manner can be included in the command line.
+ Make sure you include the -L <library-path> option to tell the linker where
+ to look for these files if they are not in the current directory.
+ Here is an example, assuming you have the source file
\emph on
--mds390
+foomain.c
\emph default
- switch.
-
-\newline
-
-\newline
-Note that the compiler does not generate any code to place the processor
- into 24 bitmode (although
+ and a library
\emph on
-tinibios
+ foolib.lib
\emph default
- in the ds390 libraries will do that for you).
- If you don't use
+ in the directory
\emph on
-tinibios
+mylib
\emph default
-, the boot loader or similar code must ensure that the processor is in 24
- bit contiguous addressing mode before calling the SDCC startup code.
+ (if that is not the same as your current project):
\newline
\newline
-Like the
+
+\family sans
+\series bold
+sdcc foomain.c foolib.lib -L mylib
+\newline
+
+\newline
+
+\family default
+\series default
+Note here that
\emph on
---model-large
+ mylib
\emph default
- option, variables will by default be placed into the XDATA segment.
-
+ must be an absolute path name.
\newline
\newline
-Segments may be placed anywhere in the 4 meg address space using the usual
- --*-loc options.
- Note that if any segments are located above 64K, the -r flag must be passed
- to the linker to generate the proper segment relocations, and the Intel
- HEX output format must be used.
- The -r flag can be passed to the linker by using the option
+The most efficient way to use libraries is to keep seperate modules in seperate
+ source files.
+ The lib file now should name all the modules.rel files.
+ For an example see the standard library file
\emph on
--Wl-r
+libsdcc.lib
\emph default
- on the sdcc command line.
- However, currently the linker can not handle code segments > 64k.
+ in the directory <installdir>/share/lib/small.
\layout Subsection
-Defines Created by the Compiler
-\layout Standard
+Command Line Options
+\layout Subsubsection
-The compiler creates the following #defines.
-\layout Itemize
+Processor Selection Options
+\layout List
+\labelwidthstring 00.00.0000
-SDCC - this Symbol is always defined.
-\layout Itemize
-SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model used
- (e.g.: -mds390)
-\layout Itemize
+\series bold
+-mmcs51
+\series default
+ Generate code for the MCS51 (8051) family of processors.
+ This is the default processor target.
+\layout List
+\labelwidthstring 00.00.0000
-__mcs51 or __ds390 or __z80, etc - depending on the model used (e.g.
- -mz80)
-\layout Itemize
-SDCC_STACK_AUTO - this symbol is defined when
-\emph on
---stack-auto
-\emph default
- option is used.
-\layout Itemize
+\series bold
+-mds390
+\series default
+ Generate code for the DS80C390 processor.
+\layout List
+\labelwidthstring 00.00.0000
-SDCC_MODEL_SMALL - when
-\emph on
---model-small
-\emph default
- is used.
-\layout Itemize
-SDCC_MODEL_LARGE - when
-\emph on
---model-large
-\emph default
- is used.
-\layout Itemize
+\series bold
+-mz80
+\series default
+ Generate code for the Z80 family of processors.
+\layout List
+\labelwidthstring 00.00.0000
-SDCC_USE_XSTACK - when
-\emph on
---xstack
-\emph default
- option is used.
-\layout Itemize
-SDCC_STACK_TENBIT - when
-\emph on
--mds390
-\emph default
- is used
-\layout Itemize
+\series bold
+-mgbz80
+\series default
+ Generate code for the GameBoy Z80 processor.
+\layout List
+\labelwidthstring 00.00.0000
-SDCC_MODEL_FLAT24 - when
-\emph on
--mds390
-\emph default
- is used
-\layout Section
-SDCC Technical Data
-\layout Subsection
+\series bold
+-mavr
+\series default
+ Generate code for the Atmel AVR processor (In development, not complete).
+\layout List
+\labelwidthstring 00.00.0000
-Optimizations
-\layout Standard
-SDCC performs a host of standard optimizations in addition to some MCU specific
- optimizations.
-
-\layout Subsubsection
+\series bold
+-mpic14
+\series default
+ Generate code for the PIC 14-bit processors (In development, not complete).
+\layout List
+\labelwidthstring 00.00.0000
-Sub-expression Elimination
-\layout Standard
-The compiler does local and global common subexpression elimination, e.g.:
-
-\newline
+\series bold
+-mtlcs900h
+\series default
+ Generate code for the Toshiba TLCS-900H processor (In development, not
+ complete).
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-i = x + y + 1;
-\newline
-j = x + y;
-\family default
+\series bold
+-mxa51
+\series default
+ Generate code for the Philips XA51 processor (In development, not complete).
+\layout Subsubsection
-\newline
+Preprocessor Options
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-will be translated to
-\newline
-\newline
+\series bold
+-I<path>
+\series default
+ The additional location where the pre processor will look for <..h> or
+\begin_inset Quotes eld
+\end_inset
-\family typewriter
-iTemp = x + y
-\newline
-i = iTemp + 1
-\newline
-j = iTemp
-\newline
+..h
+\begin_inset Quotes erd
+\end_inset
-\family default
+ files.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-Some subexpressions are not as obvious as the above example, e.g.:
-\newline
-\newline
+\series bold
+-D<macro[=value]>
+\series default
+ Command line definition of macros.
+ Passed to the pre processor.
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-a->b[i].c = 10;
-\newline
-a->b[i].d = 11;
-\family default
-\newline
+\series bold
+-M
+\series default
+ Tell the preprocessor to output a rule suitable for make describing the
+ dependencies of each object file.
+ For each source file, the preprocessor outputs one make-rule whose target
+ is the object file name for that source file and whose dependencies are
+ all the files `#include'd in it.
+ This rule may be a single line or may be continued with `
+\backslash
+'-newline if it is long.
+ The list of rules is printed on standard output instead of the preprocessed
+ C program.
+ `-M' implies `-E'.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-In this case the address arithmetic a->b[i] will be computed only once;
- the equivalent code in C would be.
-\newline
-\newline
+\series bold
+-C
+\series default
+ Tell the preprocessor not to discard comments.
+ Used with the `-E' option.
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-iTemp = a->b[i];
-\newline
-iTemp.c = 10;
-\newline
-iTemp.d = 11;
-\family default
-\newline
+\series bold
+-MM
+\size large
+\bar under
+
+\series default
+\size default
+\bar default
+Like `-M' but the output mentions only the user header files included with
+ `#include
+\begin_inset Quotes eld
+\end_inset
-\newline
-The compiler will try to keep these temporary variables in registers.
-\layout Subsubsection
+file"'.
+ System header files included with `#include <file>' are omitted.
+\layout List
+\labelwidthstring 00.00.0000
-Dead-Code Elimination
-\layout Standard
+\series bold
+-Aquestion(answer)
+\series default
+ Assert the answer answer for question, in case it is tested with a preprocessor
+ conditional such as `#if #question(answer)'.
+ `-A-' disables the standard assertions that normally describe the target
+ machine.
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-int global;
-\newline
-void f () {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-int i;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-i = 1; \SpecialChar ~
-/* dead store */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 1;\SpecialChar ~
-/* dead store */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 3;\SpecialChar ~
-/* unreachable */
-\newline
-}
-\family default
-\newline
+\series bold
+-Aquestion
+\series default
+ (answer) Assert the answer answer for question, in case it is tested with
+ a preprocessor conditional such as `#if #question(answer)'.
+ `-A-' disables the standard assertions that normally describe the target
+ machine.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-will be changed to
-\newline
-\newline
+\series bold
+-Umacro
+\series default
+ Undefine macro macro.
+ `-U' options are evaluated after all `-D' options, but before any `-include'
+ and `-imacros' options.
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-int global; void f ()
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
-}
-\layout Subsubsection
-Copy-Propagation
-\layout Standard
+\series bold
+-dM
+\series default
+ Tell the preprocessor to output only a list of the macro definitions that
+ are in effect at the end of preprocessing.
+ Used with the `-E' option.
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-int f() {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-int i, j;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-i = 10;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-j = i;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return j;
-\newline
-}
-\family default
-
-\newline
-
-\newline
-will be changed to
-\newline
-
-\newline
-
-\family typewriter
-int f() {
-\newline
-\SpecialChar ~
- \SpecialChar ~
- int i,j;
-\newline
-\SpecialChar ~
- \SpecialChar ~
- i = 10;
-\newline
-\SpecialChar ~
- \SpecialChar ~
- j = 10;
-\newline
-\SpecialChar ~
- \SpecialChar ~
- return 10;
-\newline
-}
-\newline
+\series bold
+-dD
+\series default
+ Tell the preprocessor to pass all macro definitions into the output, in
+ their proper sequence in the rest of the output.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family default
-Note: the dead stores created by this copy propagation will be eliminated
- by dead-code elimination.
+\series bold
+-dN
+\size large
+\bar under
+
+\series default
+\size default
+\bar default
+Like `-dD' except that the macro arguments and contents are omitted.
+ Only `#define name' is included in the output.
\layout Subsubsection
-Loop Optimizations
-\layout Standard
-
-Two types of loop optimizations are done by SDCC loop invariant lifting
- and strength reduction of loop induction variables.
- In addition to the strength reduction the optimizer marks the induction
- variables and the register allocator tries to keep the induction variables
- in registers for the duration of the loop.
- Because of this preference of the register allocator, loop induction optimizati
-on causes an increase in register pressure, which may cause unwanted spilling
- of other temporary variables into the stack / data space.
- The compiler will generate a warning message when it is forced to allocate
- extra space either on the stack or data space.
- If this extra space allocation is undesirable then induction optimization
- can be eliminated either for the entire source file (with --noinduction
- option) or for a given function only using #pragma\SpecialChar ~
-NOINDUCTION.
-\newline
-
-\newline
-Loop Invariant:
-\newline
-
-\newline
+Linker Options
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-for (i = 0 ; i < 100 ; i ++)
-\newline
- \SpecialChar ~
- \SpecialChar ~
-f += k + l;
-\family default
-\newline
+\series bold
+-L\SpecialChar ~
+---lib-path
+\bar under
+
+\series default
+\bar default
+<absolute path to additional libraries> This option is passed to the linkage
+ editor's additional libraries search path.
+ The path name must be absolute.
+ Additional library files may be specified in the command line.
+ See section Compiling programs for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-changed to
-\newline
-\newline
+\series bold
+---xram-loc
+\series default
+<Value> The start location of the external ram, default value is 0.
+ The value entered can be in Hexadecimal or Decimal format, e.g.: ---xram-loc
+ 0x8000 or ---xram-loc 32768.
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-itemp = k + l;
-\newline
-for (i = 0; i < 100; i++)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-f += itemp;
-\family default
-\newline
+\series bold
+---code-loc
+\series default
+<Value> The start location of the code segment, default value 0.
+ Note when this option is used the interrupt vector table is also relocated
+ to the given address.
+ The value entered can be in Hexadecimal or Decimal format, e.g.: ---code-loc
+ 0x8000 or ---code-loc 32768.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-As mentioned previously some loop invariants are not as apparent, all static
- address computations are also moved out of the loop.
-\newline
-\newline
-Strength Reduction, this optimization substitutes an expression by a cheaper
- expression:
-\newline
+\series bold
+---stack-loc
+\series default
+<Value> By default the stack is placed after the data segment.
+ Using this option the stack can be placed anywhere in the internal memory
+ space of the 8051.
+ The value entered can be in Hexadecimal or Decimal format, e.g.
+ ---stack-loc 0x20 or ---stack-loc 32.
+ Since the sp register is incremented before a push or call, the initial
+ sp will be set to one byte prior the provided value.
+ The provided value should not overlap any other memory areas such as used
+ register banks or the data segment and with enough space for the current
+ application.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-for (i=0;i < 100; i++)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-ar[i*5] = i*3;
-\family default
+\series bold
+---data-loc
+\series default
+<Value> The start location of the internal ram data segment.
+ The value entered can be in Hexadecimal or Decimal format, eg.
+ ---data-loc 0x20 or ---data-loc 32.
+ (By default, the start location of the internal ram data segment is set
+ as low as possible in memory, taking into account the used register banks
+ and the bit segment at address 0x20.
+ For example if register banks 0 and 1 are used without bit variables, the
+ data segment will be set, if ---data-loc is not used, to location 0x10.)
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-changed to
-\newline
+\series bold
+---idata-loc
+\series default
+<Value> The start location of the indirectly addressable internal ram, default
+ value is 0x80.
+ The value entered can be in Hexadecimal or Decimal format, eg.
+ ---idata-loc 0x88 or ---idata-loc 136.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-itemp1 = 0;
-\newline
-itemp2 = 0;
-\newline
-for (i=0;i< 100;i++) {
-\newline
- \SpecialChar ~
- \SpecialChar ~
-ar[itemp1] = itemp2;
-\newline
- \SpecialChar ~
- \SpecialChar ~
-itemp1 += 5;
-\newline
- \SpecialChar ~
- \SpecialChar ~
-itemp2 += 3;
-\newline
-}
-\family default
+\series bold
+---out-fmt-ihx
+\bar under
+
+\series default
+\bar default
+The linker output (final object code) is in Intel Hex format.
+ (This is the default option).
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-The more expensive multiplication is changed to a less expensive addition.
+\series bold
+---out-fmt-s19
+\bar under
+
+\series default
+\bar default
+The linker output (final object code) is in Motorola S19 format.
\layout Subsubsection
-Loop Reversing
-\layout Standard
+MCS51 Options
+\layout List
+\labelwidthstring 00.00.0000
-This optimization is done to reduce the overhead of checking loop boundaries
- for every iteration.
- Some simple loops can be reversed and implemented using a
-\begin_inset Quotes eld
-\end_inset
-decrement and jump if not zero
-\begin_inset Quotes erd
-\end_inset
+\series bold
+---model-large
+\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
+ with this option.
+ In addition the standard library routines are compiled with small model,
+ they will need to be recompiled.
+\layout List
+\labelwidthstring 00.00.0000
- instruction.
- SDCC checks for the following criterion to determine if a loop is reversible
- (note: more sophisticated compilers use data-dependency analysis to make
- this determination, SDCC uses a more simple minded analysis).
-\layout Itemize
-The 'for' loop is of the form
-\newline
+\series bold
+---model-small
+\series default
+\size large
+\emph on
+
+\size default
+\emph default
+Generate code for Small Model programs see section Memory Models for more
+ details.
+ This is the default model.
+\layout Subsubsection
-\newline
+DS390 Options
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-for (<symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
- <sym> += 1])
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-<for body>
-\layout Itemize
-
-The <for body> does not contain
-\begin_inset Quotes eld
-\end_inset
-continue
-\begin_inset Quotes erd
-\end_inset
+\series bold
+---model-flat24
+\series default
+\size large
+\emph on
+
+\size default
+\emph default
+Generate 24-bit flat mode code.
+ This is the one and only that the ds390 code generator supports right now
+ and is default when using
+\emph on
+-mds390
+\emph default
+.
+ See section Memory Models for more details.
+\layout List
+\labelwidthstring 00.00.0000
- or 'break
-\begin_inset Quotes erd
-\end_inset
+\series bold
+---stack-10bit
+\series default
+ Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
+ This is the one and only that the ds390 code generator supports right now
+ and is default when using
+\emph on
+-mds390
+\emph default
.
-\layout Itemize
+ In this mode, the stack is located in the lower 1K of the internal RAM,
+ which is mapped to 0x400000.
+ Note that the support is incomplete, since it still uses a single byte
+ as the stack pointer.
+ This means that only the lower 256 bytes of the potential 1K stack space
+ will actually be used.
+ However, this does allow you to reclaim the precious 256 bytes of low RAM
+ for use for the DATA and IDATA segments.
+ The compiler will not generate any code to put the processor into 10 bit
+ stack mode.
+ It is important to ensure that the processor is in this mode before calling
+ any re-entrant functions compiled with this option.
+ In principle, this should work with the
+\emph on
+---stack-auto
+\emph default
+ option, but that has not been tested.
+ It is incompatible with the
+\emph on
+---xstack
+\emph default
+ option.
+ It also only makes sense if the processor is in 24 bit contiguous addressing
+ mode (see the
+\emph on
+---model-flat24 option
+\emph default
+).
+\layout Subsubsection
-All goto's are contained within the loop.
-\layout Itemize
+Optimization Options
+\layout List
+\labelwidthstring 00.00.0000
-No function calls within the loop.
-\layout Itemize
-The loop control variable <sym> is not assigned any value within the loop
-\layout Itemize
+\series bold
+---nogcse
+\series default
+ Will not do global subexpression elimination, this option may be used when
+ the compiler creates undesirably large stack/data spaces to store compiler
+ temporaries.
+ A warning message will be generated when this happens and the compiler
+ will indicate the number of extra bytes it allocated.
+ It recommended that this option NOT be used, #pragma\SpecialChar ~
+NOGCSE can be used
+ to turn off global subexpression elimination for a given function only.
+\layout List
+\labelwidthstring 00.00.0000
-The loop control variable does NOT participate in any arithmetic operation
- within the loop.
-\layout Itemize
-There are NO switch statements in the loop.
-\layout Subsubsection
+\series bold
+---noinvariant
+\series default
+ Will not do loop invariant optimizations, this may be turned off for reasons
+ explained for the previous option.
+ For more details of loop optimizations performed see section Loop Invariants.It
+ recommended that this option NOT be used, #pragma\SpecialChar ~
+NOINVARIANT can be used
+ to turn off invariant optimizations for a given function only.
+\layout List
+\labelwidthstring 00.00.0000
-Algebraic Simplifications
-\layout Standard
-SDCC does numerous algebraic simplifications, the following is a small sub-set
- of these optimizations.
-\newline
+\series bold
+---noinduction
+\series default
+ Will not do loop induction optimizations, see section strength reduction
+ for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
+NOINDUCT
+ION can be used to turn off induction optimizations for a given function
+ only.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-i = j + 0 ; /* changed to */ i = j;
-\newline
-i /= 2; /* changed to */ i >>= 1;
-\newline
-i = j - j ; /* changed to */ i = 0;
-\newline
-i = j / 1 ; /* changed to */ i = j;
-\family default
+\series bold
+---nojtbound
+\size large
+\bar under
+
+\series default
+\size default
+\bar default
+ Will not generate boundary condition check when switch statements are implement
+ed using jump-tables.
+ See section Switch Statements for more details.
+ It is recommended that this option is NOT used, #pragma\SpecialChar ~
+NOJTBOUND can be
+ used to turn off boundary checking for jump tables for a given function
+ only.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-Note the subexpressions given above are generally introduced by macro expansions
- or as a result of copy/constant propagation.
+\series bold
+---noloopreverse
+\series default
+\size large
+
+\size default
+Will not do loop reversal optimization.
+\layout List
+\labelwidthstring 00.00.0000
+
+---
+\series bold
+nolabelopt
+\series default
+ Will not optimize labels (makes the dumpfiles more readable).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---no-xinit-opt
+\series default
+ Will not memcpy initialized data in far space from code space.
+ This saves a few bytes in code space if you don't have initialized data.
\layout Subsubsection
-'switch' Statements
-\layout Standard
+Other Options
+\layout List
+\labelwidthstring 00.00.0000
-SDCC changes switch statements to jump tables when the following conditions
- are true.
-
-\layout Itemize
-The case labels are in numerical sequence, the labels need not be in order,
- and the starting number need not be one or zero.
-\newline
+\series bold
+-c\SpecialChar ~
+---compile-only
+\series default
+ will compile and assemble the source, but will not call the linkage editor.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-switch(i) {\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-switch (i) {
-\newline
-case 4:...
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-case 1: ...
-
-\newline
-case 5:...
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-case 2: ...
+\series bold
+--c1mode
+\series default
+ reads the preprocessed source from standard input and compiles it.
+ The file name for the assembler output must be specified using the -o option.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-E
+\series default
+ Run only the C preprocessor.
+ Preprocess all the C source files specified and output the results to standard
+ output.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-o\SpecialChar ~
+<path/file>
+\series default
+The output path resp.
+ file where everything will be placed.
+ If the parameter is a path, it must have a trailing slash (or backslash
+ for the Windows binaries) to be recognized as a path.
-\newline
-case 3:...
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-case 3: ...
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---stack-auto
+\series default
+\size large
+\emph on
-\newline
-case 6:...
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-case 4: ...
+\size default
+\emph default
+All functions in the source file will be compiled as
+\emph on
+reentrant
+\emph default
+, i.e.
+ the parameters and local variables will be allocated on the stack.
+ see section Parameters and Local Variables for more details.
+ If this option is used all source files in the project should be compiled
+ with this option.
-\newline
-}\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-}
-\newline
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family default
-Both the above switch statements will be implemented using a jump-table.
-\layout Itemize
+\series bold
+---xstack
+\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.
+\layout List
+\labelwidthstring 00.00.0000
-The number of case labels is at least three, since it takes two conditional
- statements to handle the boundary conditions.
-\layout Itemize
-The number of case labels is less than 84, since each label takes 3 bytes
- and a jump-table can be utmost 256 bytes long.
-
-\layout Standard
+\series bold
+---callee-saves function1[,function2][,function3]....
-Switch statements which have gaps in the numeric sequence or those that
- have more that 84 case labels can be split into more than one switch statement
- for efficient code generation, e.g.:
-\newline
+\series default
+ The compiler by default uses a caller saves convention for register saving
+ across function calls, however this can cause unneccessary register pushing
+ & popping when calling small functions from larger functions.
+ This option can be used to switch the register saving convention for the
+ function names specified.
+ The compiler will not save registers when calling these functions, no extra
+ code will be generated at the entry & exit for these functions to save
+ & restore the registers used by these functions, this can SUBSTANTIALLY
+ reduce code & improve run time performance of the generated code.
+ In the future the compiler (with interprocedural analysis) will be able
+ to determine the appropriate scheme to use for each function call.
+ DO NOT use this option for built-in functions such as _muluint..., if this
+ option is used for a library function the appropriate library function
+ needs to be recompiled with the same option.
+ If the project consists of multiple source files then all the source file
+ should be compiled with the same ---callee-saves option string.
+ Also see #pragma\SpecialChar ~
+CALLEE-SAVES.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-switch (i) {
-\newline
-case 1: ...
-
-\newline
-case 2: ...
-
-\newline
-case 3: ...
-
-\newline
-case 4: ...
-
-\newline
-case 9: ...
-
-\newline
-case 10: ...
-
-\newline
-case 11: ...
-
-\newline
-case 12: ...
+\series bold
+---debug
+\bar under
-\newline
-}
-\family default
+\series default
+\bar default
+When this option is used the compiler will generate debug information, that
+ can be used with the SDCDB.
+ The debug information is collected in a file with .cdb extension.
+ For more information see documentation for SDCDB.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-If the above switch statement is broken down into two switch statements
-\newline
+\series bold
+---peep-file
+\series default
+<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.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-switch (i) {
-\newline
-case 1: ...
-
-\newline
-case 2: ...
-
-\newline
-case 3: ...
-
-\newline
-case 4: ...
+\series bold
+-S
+\size large
+\bar under
-\newline
-}
-\newline
-
-\newline
-
-\family default
-and
-\family typewriter
+\series default
+\size default
+\bar default
+Stop after the stage of compilation proper; do not assemble.
+ The output is an assembler code file for the input file specified.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-switch (i) {
-\newline
-case 9: \SpecialChar ~
-...
-
-\newline
-case 10: ...
-
-\newline
-case 11: ...
-
-\newline
-case 12:\SpecialChar ~
+\series bold
+-Wa_asmOption[,asmOption]
+\series default
...
-
-\newline
-}
-\newline
+ Pass the asmOption to the assembler.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family default
-then both the switch statements will be implemented using jump-tables whereas
- the unmodified switch statement will not be.
-\layout Subsubsection
+\series bold
+-Wl_linkOption[,linkOption]
+\series default
+...
+ Pass the linkOption to the linker.
+\layout List
+\labelwidthstring 00.00.0000
-Bit-shifting Operations.
-\layout Standard
-Bit shifting is one of the most frequently used operation in embedded programmin
-g.
- SDCC tries to implement bit-shift operations in the most efficient way
- possible, e.g.:
-\newline
+\series bold
+---int-long-reent
+\series default
+\size large
+
+\size default
+ Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
+ Note by default these libraries are compiled as non-reentrant.
+ See section Installation for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-\newline
-unsigned char i;
-\newline
-...
+\series bold
+---cyclomatic
+\bar under
-\newline
-i>>= 4;
-\newline
-...
-\newline
+\series default
+\bar default
+This option will cause the compiler to generate an information message for
+ each function in the source file.
+ The message contains some
+\emph on
+important
+\emph default
+ information about the function.
+ The number of edges and nodes the compiler detected in the control flow
+ graph of the function, and most importantly the
+\emph on
+cyclomatic complexity
+\emph default
+ see section on Cyclomatic Complexity for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\family default
-\newline
-generates the following code:
-\newline
+\series bold
+---float-reent
+\bar under
+
+\series default
+\bar default
+ Floating point library is compiled as reentrant.See section Installation
+ for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-\newline
-mov a,_i
-\newline
-swap a
-\newline
-anl a,#0x0f
-\newline
-mov _i,a
-\family default
+\series bold
+---nooverlay
+\series default
+ The compiler will not overlay parameters and local variables of any function,
+ see section Parameters and local variables for more details.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-In general SDCC will never setup a loop if the shift count is known.
- Another example:
-\newline
+\series bold
+---main-return
+\series default
+ This option can be used when the code generated is called by a monitor
+ program.
+ The compiler will generate a 'ret' upon return from the 'main' function.
+ The default option is to lock up i.e.
+ generate a 'ljmp '.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-unsigned int i;
-\newline
-...
-
-\newline
-i >>= 9;
-\newline
-...
-\family default
+\series bold
+---no-peep
+\series default
+ Disable peep-hole optimization.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-will generate:
-\newline
+\series bold
+---peep-asm
+\series default
+ Pass the inline assembler code through the peep hole optimizer.
+ This can cause unexpected changes to inline assembler code, please go through
+ the peephole optimizer rules defined in the source file tree '<target>/peeph.def
+' before using this option.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-mov a,(_i + 1)
-\newline
-mov (_i + 1),#0x00
-\newline
-clr c
-\newline
-rrc a
-\newline
-mov _i,a
-\family default
+\series bold
+---iram-size
+\series default
+<Value> Causes the linker to check if the internal ram usage is within limits
+ of the given value.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-Note that SDCC stores numbers in little-endian format (i.e.
- lowest order first).
-\layout Subsubsection
+\series bold
+---xram-size
+\series default
+<Value> Causes the linker to check if the external ram usage is within limits
+ of the given value.
+\layout List
+\labelwidthstring 00.00.0000
-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:
-\newline
+\series bold
+---code-size
+\series default
+<Value> Causes the linker to check if the code usage is within limits of
+ the given value.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-unsigned char i;
-\newline
-...
-
-\newline
-i = ((i << 1) | (i >> 7));
-\family default
+\series bold
+---nostdincl
+\series default
+ This will prevent the compiler from passing on the default include path
+ to the preprocessor.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-...
-\newline
-\newline
-will generate the following code:
-\newline
+\series bold
+---nostdlib
+\series default
+ This will prevent the compiler from passing on the default library path
+ to the linker.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-mov a,_i
-\newline
-rl a
-\newline
-mov _i,a
-\family default
+\series bold
+---verbose
+\series default
+ Shows the various actions the compiler is performing.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-SDCC uses pattern matching on the parse tree to determine this operation.Variatio
-ns of this case will also be recognized as bit-rotation, i.e.:
-\newline
+\series bold
+-V
+\series default
+ Shows the actual commands the compiler is executing.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-i = ((i >> 7) | (i << 1)); /* left-bit rotation */
-\layout Subsubsection
+\series bold
+---no-c-code-in-asm
+\series default
+ Hides your ugly and inefficient c-code from the asm file, so you can always
+ blame the compiler :).
+\layout List
+\labelwidthstring 00.00.0000
-Highest Order Bit
-\layout Standard
-It is frequently required to obtain the highest order bit of an integral
- type (long, int, short or char types).
- SDCC recognizes the following expression to yield the highest order bit
- and generates optimized code for it, e.g.:
-\newline
+\series bold
+---i-code-in-asm
+\series default
+ Include i-codes in the asm file.
+ Sounds like noise but is most helpfull for debugging the compiler itself.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-
-\family typewriter
-unsigned int gint;
-\newline
-\newline
-foo () {
-\newline
-unsigned char hob;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-hob = (gint >> 15) & 1;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-..
-
-\newline
-}
-\family default
+\series bold
+---less-pedantic
+\series default
+ Disable some of the more pedantic warnings (jwk burps: please be more specific
+ here, please!)
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-will generate the following code:
-\newline
+\series bold
+---print-search-dirs
+\series default
+ Display the directories in the compiler's search path
+\layout Subsubsection
-\family typewriter
+Intermediate Dump Options
+\layout Standard
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- 61 ;\SpecialChar ~
- hob.c 7
-\newline
-\SpecialChar ~
-\SpecialChar ~
- 000A E5*01\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- 62\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- mov\SpecialChar ~
- a,(_gint + 1)
-\newline
-\SpecialChar ~
-\SpecialChar ~
- 000C 33\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- 63\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- rlc\SpecialChar ~
- a
-\newline
-\SpecialChar ~
-\SpecialChar ~
- 000D E4\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- 64\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- clr\SpecialChar ~
- a
-\newline
-\SpecialChar ~
-\SpecialChar ~
- 000E 13\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- 65\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- rrc\SpecialChar ~
- a
-\newline
-\SpecialChar ~
-\SpecialChar ~
- 000F F5*02\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- 66\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- mov\SpecialChar ~
- _foo_hob_1_1,a
-\newline
+The following options are provided for the purpose of retargetting and debugging
+ the compiler.
+ These provided a means to dump the intermediate code (iCode) generated
+ by the compiler in human readable form at various stages of the compilation
+ process.
+
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family default
-Variations of this case however will
+\series bold
+---dumpraw
+\series default
+ This option will cause the compiler to dump the intermediate code into
+ a file of named
\emph on
-not
+<source filename>.dumpraw
\emph default
- be recognized.
- It is a standard C expression, so I heartily recommend this be the only
- way to get the highest order bit, (it is portable).
- Of course it will be recognized even if it is embedded in other expressions,
- e.g.:
-\newline
+ just after the intermediate code has been generated for a function, i.e.
+ before any optimizations are done.
+ The basic blocks at this stage ordered in the depth first number, so they
+ may not be in sequence of execution.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-xyz = gint + ((gint >> 15) & 1);
-\family default
+\series bold
+---dumpgcse
+\series default
+ Will create a dump of iCode's, after global subexpression elimination,
+ into a file named
+\emph on
+<source filename>.dumpgcse.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\newline
-will still be recognized.
-\layout Subsubsection
+\series bold
+---dumpdeadcode
+\series default
+ Will create a dump of iCode's, after deadcode elimination, into a file
+ named
+\emph on
+<source filename>.dumpdeadcode.
+\layout List
+\labelwidthstring 00.00.0000
-Peep-hole Optimizer
-\layout Standard
-The compiler uses a rule based, pattern matching and re-writing mechanism
- for peep-hole optimization.
- It is inspired by
-\emph on
-copt
-\emph default
- a peep-hole optimizer by Christopher W.
- Fraser (cwfraser@microsoft.com).
- A default set of rules are compiled into the compiler, additional rules
- may be added with the
+\series bold
+---dumploop
+\series default
+\size large
+
+\size default
+Will create a dump of iCode's, after loop optimizations, into a file named
+
\emph on
---peep-file <filename>
-\emph default
- option.
- The rule language is best illustrated with examples.
-\newline
+<source filename>.dumploop.
+\layout List
+\labelwidthstring 00.00.0000
-\newline
-\family typewriter
-replace {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-mov %1,a
+\series bold
+---dumprange
+\series default
+\size large
+
+\size default
+Will create a dump of iCode's, after live range analysis, into a file named
+
+\emph on
+<source filename>.dumprange.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumlrange
+\series default
+ Will dump the life ranges for all symbols.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumpregassign
+\bar under
+
+\series default
+\bar default
+Will create a dump of iCode's, after register assignment, into a file named
+
+\emph on
+<source filename>.dumprassgn.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumplrange
+\series default
+ Will create a dump of the live ranges of iTemp's
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumpall
+\size large
+\bar under
+
+\series default
+\size default
+\bar default
+Will cause all the above mentioned dumps to be created.
+\layout Subsection
+
+Environment variables
+\layout Standard
+
+SDCC recognizes the following environment variables:
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+SDCC_LEAVE_SIGNALS
+\series default
+ SDCC installs a signal handler to be able to delete temporary files after
+ an user break (^C) or an exception.
+ If this environment variable is set, SDCC won't install the signal handler
+ in order to be able to debug SDCC.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+TMP,\SpecialChar ~
+TEMP,\SpecialChar ~
+TMPDIR
+\series default
+ Path, where temporary files will be created.
+ The order of the variables is the search order.
+ In a standard *nix environment these variables are not set, and there's
+ no need to set them.
+ On Windows it's recommended to set one of them.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+SDCC_HOME
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.3 Install and search paths
+\begin_inset Quotes srd
+\end_inset
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+SDCC_INCLUDE
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.3 Install and search paths
+\begin_inset Quotes srd
+\end_inset
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+SDCC_LIB
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.3 Install and 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 documentated.
+\layout Subsection
+
+MCS51/DS390 Storage Class Language Extensions
+\layout Standard
+
+In addition to the ANSI storage classes SDCC allows the following MCS51
+ specific storage classes.
+\layout Subsubsection
+
+xdata
+\layout Standard
+
+Variables declared with this storage class will be placed in the extern
+ RAM.
+ This is the
+\series bold
+default
+\series default
+ storage class for Large Memory model, e.g.:
\newline
-\SpecialChar ~
-\SpecialChar ~
-mov a,%1
+
\newline
-} by {
+
+\family typewriter
+xdata unsigned char xduc;
+\layout Subsubsection
+
+data
+\layout Standard
+
+This is the
+\series bold
+default
+\series default
+ storage class for Small Memory model.
+ Variables declared with this storage class will be allocated in the internal
+ RAM, e.g.:
\newline
-\SpecialChar ~
-\SpecialChar ~
-mov %1,a
+
\newline
-}
-\family default
+\family typewriter
+data int iramdata;
+\layout Subsubsection
+
+idata
+\layout Standard
+
+Variables declared with this storage class will be allocated into the indirectly
+ addressable portion of the internal ram of a 8051, e.g.:
\newline
\newline
-The above rule will change the following assembly sequence:
+
+\family typewriter
+idata int idi;
+\layout Subsubsection
+
+bit
+\layout Standard
+
+This is a data-type and a storage class specifier.
+ When a variable is declared as a bit, it is allocated into the bit addressable
+ memory of 8051, e.g.:
\newline
\newline
\family typewriter
-\SpecialChar ~
-\SpecialChar ~
-mov r1,a
+bit iFlag;
+\layout Subsubsection
+
+sfr / sbit
+\layout Standard
+
+Like the bit keyword,
+\emph on
+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:
\newline
-\SpecialChar ~
-\SpecialChar ~
-mov a,r1
-\family default
\newline
+\family typewriter
+sfr at 0x80 P0; /* special function register P0 at location 0x80 */
\newline
-to
+sbit at 0xd7 CY; /* CY (Carry Flag) */
+\layout Subsection
+
+Pointers
+\layout Standard
+
+SDCC allows (via language extensions) pointers to explicitly point to any
+ of the memory spaces of the 8051.
+ In addition to the explicit pointers, the compiler uses (by default) generic
+ pointers which can be used to point to any of the memory spaces.
\newline
+\newline
+Pointer declaration examples:
\newline
-\family typewriter
-mov r1,a
-\family default
+\size small
\newline
+\family typewriter
+\size default
+/* pointer physically in xternal ram pointing to object in internal ram
+ */
\newline
-Note: All occurrences of a
-\emph on
-%n
-\emph default
- (pattern variable) must denote the same string.
- With the above rule, the assembly sequence:
+data unsigned char * xdata p;
+\newline
+
+\newline
+/* pointer physically in code rom pointing to data in xdata space */
+\newline
+xdata unsigned char * code p;
\newline
+\newline
+/* pointer physically in code space pointing to data in code space */
+\newline
+code unsigned char * code p;
\newline
-\family typewriter
-\SpecialChar ~
-\SpecialChar ~
-mov r1,a
\newline
-\SpecialChar ~
-\SpecialChar ~
-mov a,r2
+/* the folowing is a generic pointer physically located in xdata space */
+\newline
+char * xdata p;
\family default
+\size small
\newline
\newline
-will remain unmodified.
+
+\size default
+Well you get the idea.
+
\newline
\newline
-Other special case optimizations may be added by the user (via
+All unqualified pointers are treated as 3-byte (4-byte for the ds390)
\emph on
---peep-file option
+generic
\emph default
-).
- E.g.
- some variants of the 8051 MCU allow only
-\family typewriter
-ajmp
-\family default
- and
-\family typewriter
-acall
-\family default
-.
- The following two rules will change all
-\family typewriter
-ljmp
-\family default
- and
-\family typewriter
-lcall
-\family default
- to
-\family typewriter
-ajmp
-\family default
- and
-\family typewriter
-acall
-\family default
+ pointers.
+
+\size small
\newline
\newline
-\family typewriter
-replace { lcall %1 } by { acall %1 }
-\newline
-replace { ljmp %1 } by { ajmp %1 }
-\family default
+\size default
+The highest order byte of the
+\emph on
+generic
+\emph default
+ pointers contains the data space information.
+ Assembler support routines are called whenever data is stored or retrieved
+ using
+\emph on
+generic
+\emph default
+ pointers.
+ These are useful for developing reusable library routines.
+ Explicitly specifying the pointer type will generate the most efficient
+ code.
+\layout Subsection
-\newline
+Parameters & Local Variables
+\layout Standard
-\newline
-The
+Automatic (local) variables and parameters to functions can either be placed
+ on the stack or in data-space.
+ The default action of the compiler is to place these variables in the internal
+ RAM (for small model) or external RAM (for large model).
+ This in fact makes them
\emph on
-inline-assembler code
+static
\emph default
- is also passed through the peep hole optimizer, thus the peephole optimizer
- can also be used as an assembly level macro expander.
- The rules themselves are MCU dependent whereas the rule language infra-structur
-e is MCU independent.
- Peephole optimization rules for other MCU can be easily programmed using
- the rule language.
+ so by default functions are non-reentrant.
\newline
\newline
-The syntax for a rule is as follows:
+They can be placed on the stack either by using the
+\emph on
+ ---stack-auto
+\emph default
+ option or by using the
+\emph on
+reentrant
+\emph default
+ keyword in the function declaration, e.g.:
\newline
+\size small
+
\newline
\family typewriter
-rule := replace [ restart ] '{' <assembly sequence> '
-\backslash
-n'
+\size default
+unsigned char foo(char i) reentrant
\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- '}' by '{' '
-\backslash
-n'
+{
\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- <assembly sequence> '
-\backslash
-n'
+...
+
\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- '}' [if <functionName> ] '
-\backslash
-n'
+}
\newline
\family default
\newline
-<assembly sequence> := assembly instruction (each instruction including
- labels must be on a separate line).
+Since stack space on 8051 is limited, the
+\emph on
+reentrant
+\emph default
+keyword or the
+\emph on
+ ---stack-auto
+\emph default
+ option should be used sparingly.
+ Note that the reentrant keyword just means that the parameters & local
+ variables will be allocated to the stack, it
+\emph on
+does not
+\emph default
+ mean that the function is register bank independent.
\newline
\newline
-The optimizer will apply to the rules one by one from the top in the sequence
- of their appearance, it will terminate when all rules are exhausted.
- If the 'restart' option is specified, then the optimizer will start matching
- the rules again from the top, this option for a rule is expensive (performance)
-, it is intended to be used in situations where a transformation will trigger
- the same rule again.
- An example of this (not a good one, it has side effects) is the following
- rule:
+Local variables can be assigned storage classes and absolute addresses,
+ e.g.:
\newline
\newline
\family typewriter
-replace restart {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-pop %1
+unsigned char foo() {
\newline
\SpecialChar ~
\SpecialChar ~
-push %1 } by {
-\newline
\SpecialChar ~
\SpecialChar ~
-; nop
-\newline
-}
-\family default
-
-\newline
-
-\newline
-Note that the replace pattern cannot be a blank, but can be a comment line.
- Without the 'restart' option only the inner most 'pop' 'push' pair would
- be eliminated, i.e.:
-\newline
-
+xdata unsigned char i;
\newline
-
-\family typewriter
\SpecialChar ~
\SpecialChar ~
-pop ar1
-\newline
\SpecialChar ~
\SpecialChar ~
-pop ar2
+bit bvar;
\newline
\SpecialChar ~
\SpecialChar ~
-push ar2
-\newline
\SpecialChar ~
\SpecialChar ~
-push ar1
-\family default
-
-\newline
-
-\newline
-would result in:
-\newline
-
+data at 0x31 unsiged char j;
\newline
-
-\family typewriter
\SpecialChar ~
\SpecialChar ~
-pop ar1
-\newline
\SpecialChar ~
\SpecialChar ~
-; nop
+...
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-push ar1
-\family default
-
+}
\newline
\newline
+\family default
+In the above example the variable
\emph on
-with
+i
\emph default
- the restart option the rule will be applied again to the resulting code
- and then all the pop-push pairs will be eliminated to yield:
-\newline
+ will be allocated in the external ram,
+\emph on
+bvar
+\emph default
+ in bit addressable space and
+\emph on
+ j
+\emph default
+ in internal ram.
+ When compiled with
+\emph on
+---stack-auto
+\emph default
+ or when a function is declared as
+\emph on
+reentrant
+\emph default
+ this should only be done for static variables.
+\layout Standard
-\newline
+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
-\family typewriter
-\SpecialChar ~
-\SpecialChar ~
-; nop
-\newline
-\SpecialChar ~
-\SpecialChar ~
-; nop
-\family default
-
-\newline
-
-\newline
-A conditional function can be attached to a rule.
- Attaching rules are somewhat more involved, let me illustrate this with
- an example.
-\newline
-
-\newline
-
-\family typewriter
-replace {
-\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-ljmp %5
-\newline
-%2:
-\newline
-} by {
-\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-sjmp %5
-\newline
-%2:
-\newline
-} if labelInRange
-\family default
-
-\newline
+Overlaying
+\layout Standard
-\newline
-The optimizer does a look-up of a function name table defined in function
-
-\emph on
-callFuncByName
-\emph default
- in the source file SDCCpeeph.c, with the name
-\emph on
-labelInRange
-\emph default
-.
- If it finds a corresponding entry the function is called.
- Note there can be no parameters specified for these functions, in this
- case the use of
-\emph on
-%5
-\emph default
- is crucial, since the function
+For non-reentrant functions SDCC will try to reduce internal ram space usage
+ by overlaying parameters and local variables of a function (if possible).
+ Parameters and local variables of a function will be allocated to an overlayabl
+e segment if the function has
\emph on
-labelInRange
-\emph default
- expects to find the label in that particular variable (the hash table containin
-g the variable bindings is passed as a parameter).
- If you want to code more such functions, take a close look at the function
- labelInRange and the calling mechanism in source file SDCCpeeph.c.
- I know this whole thing is a little kludgey, but maybe some day we will
- have some better means.
- If you are looking at this file, you will also see the default rules that
- are compiled into the compiler, you can add your own rules in the default
- set there if you get tired of specifying the --peep-file option.
-\layout Subsection
+no other function calls and the function is non-reentrant and the memory
+ model is small.
-Pragmas
+\emph default
+ If an explicit storage class is specified for a local variable, it will
+ NOT be overlayed.
\layout Standard
-SDCC supports the following #pragma directives.
- This directives are applicable only at a function level.
-\layout Itemize
-
-SAVE - this will save all the current options.
-\layout Itemize
-
-RESTORE - will restore the saved options from the last save.
- Note that SAVES & RESTOREs cannot be nested.
- SDCC uses the same buffer to save the options each time a SAVE is called.
-\layout Itemize
-
-NOGCSE - will stop global subexpression elimination.
-\layout Itemize
-
-NOINDUCTION - will stop loop induction optimizations.
-\layout Itemize
-
-NOJTBOUND - will not generate code for boundary value checking, when switch
- statements are turned into jump-tables.
-\layout Itemize
-
-NOOVERLAY - the compiler will not overlay the parameters and local variables
- of a function.
-\layout Itemize
-
-NOLOOPREVERSE - Will not do loop reversal optimization
-\layout Itemize
-
-EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation
- of pair of push/pop instruction in ISR function (using interrupt keyword).
- The directive should be placed immediately before the ISR function definition
- and it affects ALL ISR functions following it.
- To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
-EXCLUDE\SpecialChar ~
-none.
-\layout Itemize
+Note that the compiler (not the linkage editor) makes the decision for overlayin
+g the data items.
+ Functions that are called from an interrupt service routine should be preceded
+ by a #pragma\SpecialChar ~
+NOOVERLAY if they are not reentrant.
+\layout Standard
-CALLEE-SAVES function1[,function2[,function3...]] - The compiler by default
- uses a caller saves convention for register saving across function calls,
- however this can cause unneccessary register pushing & popping when calling
- small functions from larger functions.
- This option can be used to switch the register saving convention for the
- function names specified.
- The compiler will not save registers when calling these functions, extra
- code will be generated at the entry & exit for these functions to save
- & restore the registers used by these functions, this can SUBSTANTIALLY
- reduce code & improve run time performance of the generated code.
- In future the compiler (with interprocedural analysis) will be able to
- determine the appropriate scheme to use for each function call.
- If --callee-saves command line option is used, the function names specified
- in #pragma\SpecialChar ~
-CALLEE-SAVES is appended to the list of functions specified inthe
- command line.
+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
-The pragma's are intended to be used to turn-off certain optimizations which
- might cause the compiler to generate extra stack / data space to store
- compiler generated temporary variables.
- This usually happens in large functions.
- Pragma directives should be used as shown in the following example, they
- are used to control options & optimizations for a given function; pragmas
- should be placed before and/or after a function, placing pragma's inside
- a function body could have unpredictable results.
+Parameters and Local variables of functions that contain 16 or 32 bit multiplica
+tion or division will NOT be overlayed since these are implemented using
+ external functions, e.g.:
\newline
\newline
\family typewriter
-#pragma SAVE /* save the current settings */
-\newline
-#pragma NOGCSE /* turnoff global subexpression elimination */
+#pragma SAVE
\newline
-#pragma NOINDUCTION /* turn off induction optimizations */
+#pragma NOOVERLAY
\newline
-int foo ()
+void set_error(unsigned char errcd)
\newline
-{
+{
\newline
\SpecialChar ~
- \SpecialChar ~
- ...
-
-\newline
\SpecialChar ~
- \SpecialChar ~
- /* large code */
-\newline
\SpecialChar ~
- \SpecialChar ~
- ...
-
+\SpecialChar ~
+P3 = errcd;
\newline
}
\newline
-#pragma RESTORE /* turn the optimizations back on */
-\family default
-
-\newline
-
-\newline
-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
-
-
-\emph on
-<pending: this is messy and incomplete>
-\emph default
- Library Routines
-\layout Enumerate
-
-Compiler support routines (_gptrget, _mulint etc)
-\layout Enumerate
-
-Stdclib functions (puts, printf, strcat etc)
-\layout Enumerate
-
-Math functions (sin, pow, sqrt etc)
-\layout Subsection
-
-Interfacing with Assembly Routines
-\layout Subsubsection
-
-Global Registers used for Parameter Passing
-\layout Standard
-
-The compiler always uses the global registers
-\emph on
-DPL,DPH,B
-\emph default
-and
-\emph on
- ACC
-\emph default
- to pass the first parameter to a routine.
- The second parameter onwards is either allocated on the stack (for reentrant
- routines or if --stack-auto is used) or in the internal / external ram
- (depending on the memory model).
-
-\layout Subsubsection
-
-Assembler Routine(non-reentrant)
-\layout Standard
-
-In the following example the function cfunc calls an assembler routine asm_func,
- which takes two parameters.
-\newline
-
-\newline
-
-\family typewriter
-extern int asm_func(unsigned char, unsigned char);
+#pragma RESTORE
\newline
\newline
-int c_func (unsigned char i, unsigned char j)
+void some_isr () interrupt 2 using 1
\newline
{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-return asm_func(i,j);
-\newline
-}
-\newline
-
-\newline
-int main()
+...
\newline
-{
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+set_error(10);
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-return c_func(10,9);
+...
+
\newline
}
\newline
\newline
\family default
-The corresponding assembler function is:
-\newline
-
-\newline
-
-\family typewriter
-.globl _asm_func_PARM_2
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-.globl _asm_func
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-.area OSEG
-\newline
-_asm_func_PARM_2:
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-.ds 1
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-.area CSEG
-\newline
-_asm_func:
+In the above example the parameter
+\emph on
+errcd
+\emph default
+ for the function
+\emph on
+set_error
+\emph default
+ would be assigned to the overlayable segment if the #pragma\SpecialChar ~
+NOOVERLAY was
+ not present, this could cause unpredictable runtime behavior when called
+ from an ISR.
+ The #pragma\SpecialChar ~
+NOOVERLAY ensures that the parameters and local variables for
+ the function are NOT overlayed.
+\layout Subsection
+
+Interrupt Service Routines
+\layout Standard
+
+SDCC allows interrupt service routines to be coded in C, with some extended
+ keywords.
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov a,dpl
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-add a,_asm_func_PARM_2
+
+\family typewriter
+void timer_isr (void) interrupt 2 using 1
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov dpl,a
+{
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mov dpl,#0x00
+..
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ret
+}
\newline
\newline
\family default
-Note here that the return values are placed in 'dpl' - One byte return value,
- 'dpl' LSB & 'dph' MSB for two byte values.
- 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
-b' & 'acc' for four byte values.
+The number following the
+\emph on
+interrupt
+\emph default
+ keyword is the interrupt number this routine will service.
+ The compiler will insert a call to this routine in the interrupt vector
+ table for the interrupt number specified.
+ The
+\emph on
+using
+\emph default
+ keyword is 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 if it is not reentrant.
+ A special note here, int (16 bit) and long (32 bit) integer division, multiplic
+ation & modulus 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
+ ---stack-auto
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+---int-long-ren
+\emph default
+t compiler option.
\layout Standard
-The parameter naming convention is _<function_name>_PARM_<n>, where n is
- the parameter number starting from 1, and counting from the left.
- The first parameter is passed in
-\begin_inset Quotes eld
-\end_inset
+If you have multiple source files in your project, interrupt service routines
+ can be present in any of them, but a prototype of the isr MUST be present
+ or included in the file that contains the function
+\emph on
+main
+\emph default
+.
+\layout Standard
-dpl
-\begin_inset Quotes erd
-\end_inset
+Interrupt Numbers and the corresponding address & descriptions for the Standard
+ 8051 are listed below.
+ SDCC will automatically adjust the interrupt vector table to the maximum
+ interrupt number specified.
+\newline
- for One bye parameter,
-\begin_inset Quotes eld
-\end_inset
+\layout Standard
-dptr
-\begin_inset Quotes erd
-\end_inset
- if two bytes,
-\begin_inset Quotes eld
-\end_inset
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-b,dptr
-\begin_inset Quotes erd
+\layout Standard
+
+Interrupt #
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- for three bytes and
-\begin_inset Quotes eld
+\layout Standard
+
+Description
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-acc,b,dptr
-\begin_inset Quotes erd
+\layout Standard
+
+Vector Address
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- for four bytes, the varible name for the second parameter will be _<function_na
-me>_PARM_2.
-\newline
+\layout Standard
-\newline
-Assemble the assembler routine with the following command:
-\newline
+0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\family sans
-\series bold
-asx8051 -losg asmfunc.asm
-\newline
+External 0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\family default
-\series default
-Then compile and link the assembler routine to the C source file with the
- following command:
-\newline
+0x0003
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
+\layout Standard
-\family sans
-\series bold
-sdcc cfunc.c asmfunc.rel
-\layout Subsubsection
+1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Assembler Routine(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.
- after the call the left most parameter will be on the top of the stack.
- Here is an example:
-\newline
+Timer 0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x000B
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+External 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0013
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Timer 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x001B
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Serial
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0023
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
\newline
-\family typewriter
-extern int asm_func(unsigned char, unsigned char);
\newline
+If the interrupt service routine is defined without
+\emph on
+using
+\emph default
+ a register bank or with register bank 0 (using 0), the compiler will save
+ the registers used by itself on the stack upon entry and restore them at
+ exit, however if such an interrupt service routine calls another function
+ then the entire register bank will be saved on the stack.
+ This scheme may be advantageous for small interrupt service routines which
+ have low register usage.
+\layout Standard
+
+If the interrupt service routine is defined to be using a specific register
+ bank then only
+\emph on
+a, b & dptr
+\emph default
+ are save and restored, if such an interrupt service routine calls another
+ function (using another register bank) then the entire register bank of
+ the called function will be saved on the stack.
+ This scheme is recommended for larger interrupt service routines.
+\layout Standard
+Calling other functions from an interrupt service routine is not recommended,
+ avoid it if possible.
\newline
-int c_func (unsigned char i, unsigned char j) reentrant
+
\newline
-{
+Also see the _naked modifier.
+\layout Subsection
+
+Critical Functions
+\layout Standard
+
+
+\shape italic
+<TODO: this isn't implemented at all!>
+\shape default
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return asm_func(i,j);
+
\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.
\newline
+\size small
+
\newline
-int main()
+
+\family typewriter
+\size default
+int foo () critical
\newline
{
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return c_func(10,9);
+...
+
+\newline
+...
+
\newline
}
\newline
\family default
\newline
-The corresponding assembler routine is:
+The critical attribute maybe used with other attributes like
+\emph on
+reentrant.
+\layout Subsection
+
+Naked Functions
+\layout Standard
+
+A special keyword may be associated with a function declaring it as
+\emph on
+_naked.
+
+\emph default
+The
+\emph on
+_naked
+\emph default
+ function modifier attribute prevents the compiler from generating prologue
+ and epilogue code for that function.
+ This means that the user is entirely responsible for such things as saving
+ any registers that may need to be preserved, selecting the proper register
+ bank, generating the
+\emph on
+return
+\emph default
+ instruction at the end, etc.
+ Practically, this means that the contents of the function must be written
+ in inline assembler.
+ This is particularly useful for interrupt functions, which can have a large
+ (and often unnecessary) prologue/epilogue.
+ For example, compare the code generated by these two functions:
\newline
\newline
\family typewriter
-.globl _asm_func
+data unsigned char counter;
\newline
-_asm_func:
+void simpleInterrupt(void) interrupt 1
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-push _bp
+counter++;
+\newline
+}
+\newline
+
+\newline
+void nakedInterrupt(void) interrupt 2 _naked
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov _bp,sp
+_asm
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov r2,dpl
-\newline
\SpecialChar ~
\SpecialChar ~
+inc\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov a,_bp
+\SpecialChar ~
+\SpecialChar ~
+_counter
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-clr c
-\newline
\SpecialChar ~
\SpecialChar ~
+reti\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,#0xfd
+; MUST explicitly include ret in _naked function.
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov r0,a
+_endasm;
+\newline
+}
+\family default
+
+\newline
+
+\newline
+For an 8051 target, the generated simpleInterrupt looks like:
+\newline
+
+\newline
+
+\family typewriter
+_simpleIterrupt:
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,#0xfc
-\newline
-\SpecialChar ~
+push\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov r1,a
+acc
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov a,@r0
+push\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-add a,r2
+push\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dpl
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov dpl,a
+push\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dph
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov dph,#0x00
+push\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+psw
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov sp,_bp
-\newline
+mov\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-pop _bp
+psw,#0x00
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ret
-\newline
-
-\newline
-
-\family default
-The compiling and linking procedure remains the same, however note the extra
- entry & exit linkage required for the assembler code, _bp is the stack
- frame pointer and is used to compute the offset into the stack for parameters
- and local variables.
-\layout Subsection
-
-External Stack
-\layout Standard
-
-The external stack is located at the start of the external ram segment,
- and is 256 bytes in size.
- When --xstack option is used to compile the program, the parameters and
- local variables of all reentrant functions are allocated in this area.
- This option is provided for programs with large stack space requirements.
- When used with the --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).
-\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
-
-ANSI-Compliance
-\layout Standard
-
-Deviations from the compliancy.
-\layout Itemize
-
-functions are not always reentrant.
-\layout Itemize
-
-structures cannot be assigned values directly, cannot be passed as function
- parameters or assigned to each other and cannot be a return value from
- a function, e.g.:
-\family typewriter
-
-\newline
-
-\newline
-struct s { ...
- };
-\newline
-struct s s1, s2;
-\newline
-foo()
-\newline
-{
-\newline
+inc\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
+_counter
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
-\newline
+pop\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
-\newline
-}
-\newline
-struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
- ANSI */
+psw
\newline
-{
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+pop\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dph
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-struct s rets;
+pop\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dpl
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
+pop\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-return rets;/* is invalid in SDCC although allowed in ANSI */
+pop\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+acc
\newline
-}
-\layout Itemize
-
-'long long' (64 bit integers) not supported.
-\layout Itemize
-
-'double' precision floating point not supported.
-\layout Itemize
-
-No support for setjmp and longjmp (for now).
-\layout Itemize
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+reti
+\family default
-Old K&R style function declarations are NOT allowed.
\newline
-\family typewriter
-
\newline
-foo(i,j) /* this old style of function declarations */
+whereas nakedInterrupt looks like:
\newline
-int i,j; /* are valid in ANSI but not valid in SDCC */
+
\newline
-{
+
+\family typewriter
+_nakedInterrupt:
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
+inc\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_counter
\newline
-}
-\layout Itemize
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+reti\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; MUST explicitly include ret(i) in _naked function.
+\family default
-functions declared as pointers must be dereferenced during the call.
\newline
-\family typewriter
-
-\newline
-int (*foo)();
-\newline
-...
-
\newline
-/* has to be called like this */
-\newline
-(*foo)(); /* ansi standard allows calls to be made like 'foo()' */
+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
-Cyclomatic Complexity
+Functions using private banks
\layout Standard
-Cyclomatic complexity of a function is defined as the number of independent
- paths the program can take during execution of the function.
- This is an important number since it defines the number test cases you
- have to generate to validate the function.
- The accepted industry standard for complexity number is 10, if the cyclomatic
- complexity reported by SDCC exceeds 10 you should think about simplification
- of the function logic.
- Note that the complexity level is not related to the number of lines of
- code in a function.
- Large functions can have low complexity, and small functions can have large
- complexity levels.
-
-\newline
+The
+\emph on
+using
+\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
+\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
-\newline
-SDCC uses the following formula to compute the complexity:
-\newline
+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 true
\layout Standard
-complexity = (number of edges in control flow graph) - (number of nodes
- in control flow graph) + 2;
-\newline
+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
-Having said that the industry standard is 10, you should be aware that in
- some cases it be may unavoidable to have a complexity level of less than
- 10.
- For example if you have switch statement with more than 10 case labels,
- each case label adds one to the complexity level.
- 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 Section
-TIPS
+\emph on
+(pending: I don't think this has been done yet)
\layout Standard
-Here are a few guidelines that will help the compiler generate more efficient
- code, some of the tips are specific to this compiler others are generally
- good programming practice.
-\layout Itemize
-
-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 a 'char' instead of a 'short' or 'int'.
-\layout Itemize
+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 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
-Use unsigned when it is known in advance that the value is not going to
- be negative.
- This helps especially if you are doing division or multiplication.
-\layout Itemize
+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
-NEVER jump into a LOOP.
-\layout Itemize
+Absolute Addressing
+\layout Standard
-Declare the variables to be local whenever possible, especially loop control
- variables (induction).
-\layout Itemize
+Data items can be assigned an absolute address with the
+\emph on
+at <address>
+\emph default
+ keyword, in addition to a storage class, e.g.:
+\newline
-Since the compiler does not do implicit integral promotion, the programmer
- should do an explicit cast when integral promotion is required.
-\layout Itemize
+\newline
-Reducing the size of division, multiplication & modulus operations can reduce
- code size substantially.
- Take the following code for example.
\family typewriter
-
+xdata at 0x8000 unsigned char PORTA_8255 ;
\newline
+\family default
+
\newline
-foobar(unsigned int p1, unsigned char ch)
+In the above example the PORTA_8255 will be allocated to the location 0x8000
+ of the external ram.
+ Note that this feature is provided to give the programmer access to
+\emph on
+memory mapped
+\emph default
+ devices attached to the controller.
+ The compiler does not actually reserve any space for variables declared
+ in this way (they are implemented with an equate in the assembler).
+ Thus it is left to the programmer to make sure there are no overlaps with
+ other variables that are declared without the absolute address.
+ The assembler listing file (.lst) and the linker output files (.rst) and
+ (.map) are a good places to look for such overlaps.
\newline
-{
+
\newline
- unsigned char ch1 = p1 % ch ;
+Absolute address can be specified for variables in all storage classes,
+ e.g.:
\newline
- ....
-
+
\newline
-}
+
+\family typewriter
+bit at 0x02 bvar;
+\newline
+
\newline
\family default
+The above example will allocate the variable at offset 0x02 in the bit-addressab
+le space.
+ There is no real advantage to assigning absolute addresses to variables
+ in this manner, unless you want strict control over all the variables allocated.
+\layout Subsection
+
+Startup Code
+\layout Standard
+
+The compiler inserts a call to the C routine
+\emph on
+_sdcc__external__startup()
+\series bold
+\emph default
+
+\series default
+at the start of the CODE area.
+ This routine is in the runtime library.
+ 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 Other wise 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.
+\layout Subsection
+
+Inline Assembler Code
+\layout Standard
+SDCC allows the use of in-line assembler with a few restriction as regards
+ labels.
+ All labels defined within inline assembler code
+\emph on
+has to be
+\emph default
+ of the form
+\emph on
+nnnnn$
+\emph default
+ where nnnn is a number less than 100 (which implies a limit of utmost 100
+ inline assembler labels
+\emph on
+per function
+\emph default
+\noun on
+)
+\noun default
+.
+ It is strongly recommended that each assembly instruction (including labels)
+ be placed in a separate line (as the example shows).
+ When the
+\emph on
+---peep-asm
+\emph default
+ command line option is used, the inline assembler code will be passed through
+ the peephole optimizer.
+ This might cause some unexpected changes in the inline assembler code.
+ Please go throught the peephole optimizer rules defined in file
+\emph on
+SDCCpeeph.def
+\emph default
+ carefully before using this option.
\newline
-For the modulus operation the variable ch will be promoted to unsigned int
- first then the modulus operation will be performed (this will lead to a
- call to support routine _moduint()), and the result will be casted to a
- char.
- If the code is changed to
+
\newline
\family typewriter
-
+_asm
\newline
-foobar(unsigned int p1, unsigned char ch)
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b,#10
\newline
-{
+00001$:
\newline
- unsigned char ch1 = (unsigned char)p1 % ch ;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+djnz\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+b,00001$
\newline
- ....
-
+_endasm ;
+\family default
+\size small
+
\newline
-}
+
\newline
+\size default
+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
-It would substantially reduce the code generated (future versions of the
- compiler will be smart enough to detect such optimization oppurtunities).
-\layout Subsection
-Notes on MCS51 memory layout
-\layout Standard
+\newline
+Inline assembler code cannot reference any C-Labels, however it can reference
+ labels defined by the inline assembler, e.g.:
+\newline
-The 8051 family of micro controller have a minimum of 128 bytes of internal
- memory which is structured as follows
\newline
+\family typewriter
+foo() {
\newline
-- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* some c code */
\newline
-- Bytes 20-2F - 16 bytes to hold 128 bit variables and
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
\newline
-- Bytes 30-7F - 60 bytes for general purpose use.
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+; some assembler code
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ljmp $0003
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* some more c code */
+\newline
+clabel:\SpecialChar ~
+\SpecialChar ~
+/* inline assembler cannot reference this label */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_asm
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+$0003: ;label (can be reference by inline assembler only)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+_endasm ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* some more c code */
+\newline
+}
\newline
-Normally the SDCC compiler will only utilise the first bank of registers,
- but it is possible to specify that other banks of registers should be used
- in interrupt routines.
- By default, the compiler will place the stack after the last bank of used
- registers, i.e.
- if the first 2 banks of registers are used, it will position the base of
- the internal stack at address 16 (0X10).
- This implies that as the stack grows, it will use up the remaining register
- banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
- general purpose use.
-\layout Standard
-By default, the compiler uses the 60 general purpose bytes to hold "near
- data".
- The compiler/optimiser may also declare some Local Variables in this area
- to hold local data.
+\newline
+
+\family default
+In other words inline assembly code can access labels defined in inline
+ assembly within the scope of the funtion.
\layout Standard
-If any of the 128 bit variables are used, or near data is being used then
- care needs to be taken to ensure that the stack does not grow so much that
- it starts to over write either your bit variables or "near data".
- There is no runtime checking to prevent this from happening.
-\layout Standard
+The same goes the other way, ie.
+ labels defines in inline assembly CANNOT be accessed by C statements.
+\layout Subsection
-The amount of stack being used is affected by the use of the "internal stack"
- to save registers before a subroutine call is made (--stack-auto will declare
- parameters and local variables on the stack) and the number of nested subroutin
-es.
+int (16 bit) and long (32 bit) Support
\layout Standard
-If you detect that the stack is over writing you data, then the following
- can be done.
- --xstack will cause an external stack to be used for saving registers and
- (if --stack-auto is being used) storing parameters and local variables.
- However this will produce more code which will be slower to execute.
-
-\layout Standard
+For signed & unsigned int (16 bit) and long (32 bit) variables, division,
+ multiplication and modulus operations are implemented by support routines.
+ These support routines are all developed in ANSI-C to facilitate porting
+ to other MCUs, although some model specific assembler optimations are used.
+ The following files contain the described routine, all of them can be found
+ in <installdir>/share/sdcc/lib.
+\newline
---stack-loc will allow you specify the start of the stack, i.e.
- you could start it after any data in the general purpose area.
- However this may waste the memory not used by the register banks and if
- the size of the "near data" increases, it may creep into the bottom of
- the stack.
-\layout Standard
+\newline
---stack-after-data, similar to the --stack-loc, but it automatically places
- the stack after the end of the "near data".
- Again this could waste any spare register space.
-\layout Standard
+\emph on
+<pending: tabularise this>
+\emph default
---data-loc allows you to specify the start address of the near data.
- This could be used to move the "near data" further away from the stack
- giving it more room to grow.
- This will only work if no bit variables are being used and the stack can
- grow to use the bit variable space.
\newline
\newline
-Conclusion.
+_mulsint.c - signed 16 bit multiplication (calls _muluint)
+\newline
+_muluint.c - unsigned 16 bit multiplication
+\newline
+_divsint.c - signed 16 bit division (calls _divuint)
+\newline
+_divuint.c - unsigned 16 bit division
+\newline
+_modsint.c - signed 16 bit modulus (call _moduint)
+\newline
+_moduint.c - unsigned 16 bit modulus
+\newline
+_mulslong.c - signed 32 bit multiplication (calls _mululong)
+\newline
+_mululong.c - unsigned32 bit multiplication
+\newline
+_divslong.c - signed 32 division (calls _divulong)
+\newline
+_divulong.c - unsigned 32 division
+\newline
+_modslong.c - signed 32 bit modulus (calls _modulong)
\newline
+_modulong.c - unsigned 32 bit modulus
+\size footnotesize
\newline
-If you find that the stack is over writing your bit variables or "near data"
- then the approach which best utilised the internal memory is to position
- the "near data" after the last bank of used registers or, if you use bit
- variables, after the last bit variable by using the --data-loc, e.g.
- if two register banks are being used and no bit variables, --data-loc 16,
- and use the --stack-after-data option.
-\layout Standard
-If bit variables are being used, another method would be to try and squeeze
- the data area in the unused register banks if it will fit, and start the
- stack after the last bit variable.
-\layout Section
+\newline
-Retargetting for other MCUs.
+\size default
+Since they are compiled as
+\emph on
+non-reentrant
+\emph default
+, interrupt service routines should not do any of the above operations.
+ If this is unavoidable then the above routines will need to be compiled
+ with the
+\emph on
+---stack-auto
+\emph default
+ option, after which the source program will have to be compiled with
+\emph on
+---int-long-rent
+\emph default
+ option.
+\layout Subsection
+
+Floating Point Support
\layout Standard
-The issues for retargetting the compiler are far too numerous to be covered
- by this document.
- What follows is a brief description of each of the seven phases of the
- compiler and its MCU dependency.
-\layout Itemize
+SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
+ point support routines are derived from gcc's floatlib.c and consists of
+ the following routines:
+\newline
-Parsing the source and building the annotated parse tree.
- This phase is largely MCU independent (except for the language extensions).
- Syntax & semantic checks are also done in this phase, along with some initial
- optimizations like back patching labels and the pattern matching optimizations
- like bit-rotation etc.
-\layout Itemize
+\newline
-The second phase involves generating an intermediate code which can be easy
- manipulated during the later phases.
- This phase is entirely MCU independent.
- The intermediate code generation assumes the target machine has unlimited
- number of registers, and designates them with the name iTemp.
- The compiler can be made to dump a human readable form of the code generated
- by using the --dumpraw option.
-\layout Itemize
+\emph on
+<pending: tabularise this>
+\emph default
-This phase does the bulk of the standard optimizations and is also MCU independe
-nt.
- This phase can be broken down into several sub-phases:
\newline
\newline
-Break down intermediate code (iCode) into basic blocks.
+_fsadd.c - add floating point numbers
\newline
-Do control flow & data flow analysis on the basic blocks.
+_fssub.c - subtract floating point numbers
\newline
-Do local common subexpression elimination, then global subexpression elimination
+_fsdiv.c - divide floating point numbers
\newline
-Dead code elimination
+_fsmul.c - multiply floating point numbers
\newline
-Loop optimizations
+_fs2uchar.c - convert floating point to unsigned char
\newline
-If loop optimizations caused any changes then do 'global subexpression eliminati
-on' and 'dead code elimination' again.
-\layout Itemize
-
-This phase determines the live-ranges; by live range I mean those iTemp
- variables defined by the compiler that still survive after all the optimization
-s.
- Live range analysis is essential for register allocation, since these computati
-on determines which of these iTemps will be assigned to registers, and for
- how long.
-\layout Itemize
-
-Phase five is register allocation.
- There are two parts to this process.
+_fs2char.c - convert floating point to signed char
\newline
-
+_fs2uint.c - convert floating point to unsigned int
\newline
-The first part I call 'register packing' (for lack of a better term).
- In this case several MCU specific expression folding is done to reduce
- register pressure.
+_fs2int.c - convert floating point to signed int
\newline
-
+_fs2ulong.c - convert floating point to unsigned long
\newline
-The second part is more MCU independent and deals with allocating registers
- to the remaining live ranges.
- A lot of MCU specific code does creep into this phase because of the limited
- number of index registers available in the 8051.
-\layout Itemize
-
-The Code generation phase is (unhappily), entirely MCU dependent and very
- little (if any at all) of this code can be reused for other MCU.
- However the scheme for allocating a homogenized assembler operand for each
- iCode operand may be reused.
-\layout Itemize
+_fs2long.c - convert floating point to signed long
+\newline
+_uchar2fs.c - convert unsigned char to floating point
+\newline
+_char2fs.c - convert char to floating point number
+\newline
+_uint2fs.c - convert unsigned int to floating point
+\newline
+_int2fs.c - convert int to floating point numbers
+\newline
+_ulong2fs.c - convert unsigned long to floating point number
+\newline
+_long2fs.c - convert long to floating point number
+\size footnotesize
-As mentioned in the optimization section the peep-hole optimizer is rule
- based system, which can reprogrammed for other MCUs.
-\layout Section
+\newline
-SDCDB - Source Level Debugger
-\layout Standard
+\newline
-SDCC is distributed with a source level debugger.
- The debugger uses a command line interface, the command repertoire of the
- debugger has been kept as close to gdb (the GNU debugger) as possible.
- The configuration and build process is part of the standard compiler installati
-on, which also builds and installs the debugger in the target directory
- specified during configuration.
- The debugger allows you debug BOTH at the C source and at the ASM source
- level.
+\size default
+Note if all these routines are used simultaneously the data space might
+ overflow.
+ For serious floating point usage it is strongly recommended that the large
+ model be used.
\layout Subsection
-Compiling for Debugging
+MCS51 Memory Models
\layout Standard
-The \SpecialChar \-
-\SpecialChar \-
-debug option must be specified for all files for which debug information
- is to be generated.
- The complier generates a .cdb file for each of these files.
- The linker updates the .cdb file with the address information.
- This .cdb is used by the debugger.
-\layout Subsection
+SDCC allows two memory models for MCS51 code, small and large.
+ Modules compiled with different memory models should
+\emph on
+never
+\emph default
+ be combined together or the results would be unpredictable.
+ The library routines supplied with the compiler are compiled as both small
+ and large.
+ The compiled library modules are contained in seperate directories as small
+ and large so that you can link to either set.
+
+\layout Standard
-How the Debugger Works
+When the large model is used all variables declared without a storage class
+ will be allocated into the external ram, this includes all parameters and
+ local variables (for non-reentrant functions).
+ When the small model is used variables without storage class are allocated
+ in the internal ram.
\layout Standard
-When the --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 .cdb file, the linker updates the .cdb file with the address
- information for the symbols.
- The debugger reads the symbolic information generated by the compiler &
- the address information generated by the linker.
- It uses the SIMULATOR (Daniel's S51) to execute the program, the program
- execution is controlled by the debugger.
- When a command is issued for the debugger, it translates it into appropriate
- commands for the simulator.
+Judicious usage of the processor specific storage classes and the 'reentrant'
+ function type will yield much more efficient code, than using the large
+ model.
+ Several optimizations are disabled when the program is compiled using the
+ large model, it is therefore strongly recommdended that the small model
+ be used unless absolutely required.
\layout Subsection
-Starting the Debugger
+DS390 Memory Models
\layout Standard
-The debugger can be started using the following command line.
- (Assume the file you are debugging has the file name foo).
+The only model supported is Flat 24.
+ This generates code for the 24 bit contiguous addressing mode of the Dallas
+ DS80C390 part.
+ In this mode, up to four meg of external RAM or code space can be directly
+ addressed.
+ See the data sheets at www.dalsemi.com for further information on this part.
\newline
+\newline
+In older versions of the compiler, this option was used with the MCS51 code
+ generator (
+\emph on
+-mmcs51
+\emph default
+).
+ Now, however, the '390 has it's own code generator, selected by the
+\emph on
+-mds390
+\emph default
+ switch.
+
\newline
-\family sans
-\series bold
-sdcdb foo
+\newline
+Note that the compiler does not generate any code to place the processor
+ into 24 bitmode (although
+\emph on
+tinibios
+\emph default
+ in the ds390 libraries will do that for you).
+ If you don't use
+\emph on
+tinibios
+\emph default
+, the boot loader or similar code must ensure that the processor is in 24
+ bit contiguous addressing mode before calling the SDCC startup code.
\newline
-\family default
-\series default
+\newline
+Like the
+\emph on
+---model-large
+\emph default
+ option, variables will by default be placed into the XDATA segment.
+
+\newline
\newline
-The debugger will look for the following files.
-\layout Itemize
+Segments may be placed anywhere in the 4 meg address space using the usual
+ ---*-loc options.
+ Note that if any segments are located above 64K, the -r flag must be passed
+ to the linker to generate the proper segment relocations, and the Intel
+ HEX output format must be used.
+ The -r flag can be passed to the linker by using the option
+\emph on
+-Wl-r
+\emph default
+ on the sdcc command line.
+ However, currently the linker can not handle code segments > 64k.
+\layout Subsection
-foo.c - the source file.
-\layout Itemize
+Defines Created by the Compiler
+\layout Standard
-foo.cdb - the debugger symbol information file.
+The compiler creates the following #defines.
\layout Itemize
-foo.ihx - the intel hex format object file.
-\layout Subsection
+SDCC - this Symbol is always defined.
+\layout Itemize
-Command Line Options.
+SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model used
+ (e.g.: -mds390)
\layout Itemize
---directory=<source file directory> this option can used to specify the
- directory search list.
- The debugger will look into the directory list specified for source, cdb
- & ihx files.
- The items in the directory list must be separated by ':', e.g.
- if the source files can be in the directories /home/src1 and /home/src2,
- the --directory option should be --directory=/home/src1:/home/src2.
- Note there can be no spaces in the option.
-
+__mcs51 or __ds390 or __z80, etc - depending on the model used (e.g.
+ -mz80)
\layout Itemize
--cd <directory> - change to the <directory>.
+SDCC_STACK_AUTO - this symbol is defined when
+\emph on
+---stack-auto
+\emph default
+ option is used.
\layout Itemize
--fullname - used by GUI front ends.
+SDCC_MODEL_SMALL - when
+\emph on
+---model-small
+\emph default
+ is used.
\layout Itemize
--cpu <cpu-type> - this argument is passed to the simulator please see the
- simulator docs for details.
+SDCC_MODEL_LARGE - when
+\emph on
+---model-large
+\emph default
+ is used.
\layout Itemize
--X <Clock frequency > this options is passed to the simulator please see
- the simulator docs for details.
+SDCC_USE_XSTACK - when
+\emph on
+---xstack
+\emph default
+ option is used.
\layout Itemize
--s <serial port file> passed to simulator see the simulator docs for details.
+SDCC_STACK_TENBIT - when
+\emph on
+-mds390
+\emph default
+ is used
\layout Itemize
--S <serial in,out> passed to simulator see the simulator docs for details.
+SDCC_MODEL_FLAT24 - when
+\emph on
+-mds390
+\emph default
+ is used
+\layout Section
+
+SDCC Technical Data
\layout Subsection
-Debugger Commands.
+Optimizations
\layout Standard
-As mention earlier the command interface for the debugger has been deliberately
- kept as close the GNU debugger gdb, as possible.
- This will help the integration with existing graphical user interfaces
- (like ddd, xxgdb or xemacs) existing for the GNU debugger.
+SDCC performs a host of standard optimizations in addition to some MCU specific
+ optimizations.
+
\layout Subsubsection
-break [line | file:line | function | file:function]
+Sub-expression Elimination
\layout Standard
-Set breakpoint at specified line or function:
+The compiler does local and global common subexpression elimination, e.g.:
+
\newline
\newline
-\family sans
-\series bold
-sdcdb>break 100
-\newline
-sdcdb>break foo.c:100
-\newline
-sdcdb>break funcfoo
+\family typewriter
+i = x + y + 1;
\newline
-sdcdb>break foo.c:funcfoo
-\layout Subsubsection
+j = x + y;
+\family default
-clear [line | file:line | function | file:function ]
-\layout Standard
+\newline
-Clear breakpoint at specified line or function:
+\newline
+will be translated to
\newline
\newline
-\family sans
-\series bold
-sdcdb>clear 100
+\family typewriter
+iTemp = x + y
\newline
-sdcdb>clear foo.c:100
+i = iTemp + 1
\newline
-sdcdb>clear funcfoo
+j = iTemp
\newline
-sdcdb>clear foo.c:funcfoo
-\layout Subsubsection
-continue
-\layout Standard
-
-Continue program being debugged, after breakpoint.
-\layout Subsubsection
+\family default
-finish
-\layout Standard
+\newline
+Some subexpressions are not as obvious as the above example, e.g.:
+\newline
-Execute till the end of the current function.
-\layout Subsubsection
+\newline
-delete [n]
-\layout Standard
+\family typewriter
+a->b[i].c = 10;
+\newline
+a->b[i].d = 11;
+\family default
-Delete breakpoint number 'n'.
- If used without any option clear ALL user defined break points.
-\layout Subsubsection
+\newline
-info [break | stack | frame | registers ]
-\layout Itemize
+\newline
+In this case the address arithmetic a->b[i] will be computed only once;
+ the equivalent code in C would be.
+\newline
-info break - list all breakpoints
-\layout Itemize
+\newline
-info stack - show the function call stack.
-\layout Itemize
+\family typewriter
+iTemp = a->b[i];
+\newline
+iTemp.c = 10;
+\newline
+iTemp.d = 11;
+\family default
-info frame - show information about the current execution frame.
-\layout Itemize
+\newline
-info registers - show content of all registers.
+\newline
+The compiler will try to keep these temporary variables in registers.
\layout Subsubsection
-step
+Dead-Code Elimination
\layout Standard
-Step program until it reaches a different source line.
-\layout Subsubsection
-
-next
-\layout Standard
-Step program, proceeding through subroutine calls.
-\layout Subsubsection
+\family typewriter
+int global;
+\newline
+void f () {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+int i;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+i = 1; \SpecialChar ~
+/* dead store */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+global = 1;\SpecialChar ~
+/* dead store */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+global = 2;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+return;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+global = 3;\SpecialChar ~
+/* unreachable */
+\newline
+}
+\family default
-run
-\layout Standard
+\newline
-Start debugged program.
-\layout Subsubsection
+\newline
+will be changed to
+\newline
-ptype variable
-\layout Standard
+\newline
-Print type information of the variable.
+\family typewriter
+int global; void f ()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+global = 2;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+return;
+\newline
+}
\layout Subsubsection
-print variable
+Copy-Propagation
\layout Standard
-print value of variable.
-\layout Subsubsection
-
-file filename
-\layout Standard
-load the given file name.
- Note this is an alternate method of loading file for debugging.
-\layout Subsubsection
+\family typewriter
+int f() {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+int i, j;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+i = 10;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+j = i;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+return j;
+\newline
+}
+\family default
-frame
-\layout Standard
+\newline
-print information about current frame.
-\layout Subsubsection
+\newline
+will be changed to
+\newline
-set srcmode
-\layout Standard
+\newline
-Toggle between C source & assembly source.
-\layout Subsubsection
+\family typewriter
+int f() {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ int i,j;
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ i = 10;
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ j = 10;
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ return 10;
+\newline
+}
+\newline
-! simulator command
-\layout Standard
+\newline
-Send the string following '!' to the simulator, the simulator response is
- displayed.
- Note the debugger does not interpret the command being sent to the simulator,
- so if a command like 'go' is sent the debugger can loose its execution
- context and may display incorrect values.
+\family default
+Note: the dead stores created by this copy propagation will be eliminated
+ by dead-code elimination.
\layout Subsubsection
-quit.
+Loop Optimizations
\layout Standard
-"Watch me now.
- Iam going Down.
- My name is Bobby Brown"
-\layout Subsection
-
-Interfacing with XEmacs.
-\layout Standard
+Two types of loop optimizations are done by SDCC loop invariant lifting
+ and strength reduction of loop induction variables.
+ In addition to the strength reduction the optimizer marks the induction
+ variables and the register allocator tries to keep the induction variables
+ in registers for the duration of the loop.
+ Because of this preference of the register allocator, loop induction optimizati
+on causes an increase in register pressure, which may cause unwanted spilling
+ of other temporary variables into the stack / data space.
+ The compiler will generate a warning message when it is forced to allocate
+ extra space either on the stack or data space.
+ If this extra space allocation is undesirable then induction optimization
+ can be eliminated either for the entire source file (with ---noinduction
+ option) or for a given function only using #pragma\SpecialChar ~
+NOINDUCTION.
+\newline
-Two files (in emacs lisp) are provided for the interfacing with XEmacs,
- sdcdb.el and sdcdbsrc.el.
- These two files can be found in the $(prefix)/bin directory after the installat
-ion is complete.
- These files need to be loaded into XEmacs for the interface to work.
- This can be done at XEmacs startup time by inserting the following into
- your '.xemacs' file (which can be found in your HOME directory):
+\newline
+Loop Invariant:
\newline
\newline
\family typewriter
-(load-file sdcdbsrc.el)
+for (i = 0 ; i < 100 ; i ++)
+\newline
+ \SpecialChar ~
+ \SpecialChar ~
+f += k + l;
\family default
\newline
\newline
-.xemacs is a lisp file so the () around the command is REQUIRED.
- The files can also be loaded dynamically while XEmacs is running, set the
- environment variable 'EMACSLOADPATH' to the installation bin directory
- (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
- To start the interface enter the following command:
+changed to
\newline
\newline
-\family sans
-\series bold
-ESC-x sdcdbsrc
+\family typewriter
+itemp = k + l;
+\newline
+for (i = 0; i < 100; i++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+f += itemp;
\family default
-\series default
\newline
\newline
-You will prompted to enter the file name to be debugged.
-
+As mentioned previously some loop invariants are not as apparent, all static
+ address computations are also moved out of the loop.
\newline
\newline
-The command line options that are passed to the simulator directly are bound
- to default values in the file sdcdbsrc.el.
- The variables are listed below, these values maybe changed as required.
-\layout Itemize
+Strength Reduction, this optimization substitutes an expression by a cheaper
+ expression:
+\newline
-sdcdbsrc-cpu-type '51
-\layout Itemize
+\newline
-sdcdbsrc-frequency '11059200
-\layout Itemize
+\family typewriter
+for (i=0;i < 100; i++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ar[i*5] = i*3;
+\family default
-sdcdbsrc-serial nil
-\layout Standard
+\newline
-The following is a list of key mapping for the debugger interface.
-\layout Standard
+\newline
+changed to
+\newline
-\SpecialChar ~
+\newline
\family typewriter
+itemp1 = 0;
+\newline
+itemp2 = 0;
+\newline
+for (i=0;i< 100;i++) {
+\newline
+ \SpecialChar ~
+ \SpecialChar ~
+ar[itemp1] = itemp2;
+\newline
+ \SpecialChar ~
+ \SpecialChar ~
+itemp1 += 5;
+\newline
+ \SpecialChar ~
+ \SpecialChar ~
+itemp2 += 3;
+\newline
+}
+\family default
\newline
-;; Current Listing ::
+
\newline
-;;key\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+The more expensive multiplication is changed to a less expensive addition.
+\layout Subsubsection
+
+Loop Reversing
+\layout Standard
+
+This optimization is done to reduce the overhead of checking loop boundaries
+ for every iteration.
+ Some simple loops can be reversed and implemented using a
+\begin_inset Quotes eld
+\end_inset
+
+decrement and jump if not zero
+\begin_inset Quotes erd
+\end_inset
+
+ instruction.
+ SDCC checks for the following criterion to determine if a loop is reversible
+ (note: more sophisticated compilers use data-dependency analysis to make
+ this determination, SDCC uses a more simple minded analysis).
+\layout Itemize
+
+The 'for' loop is of the form
+\newline
+
+\newline
+
+\family typewriter
+for (<symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
+ <sym> += 1])
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+<for body>
+\layout Itemize
+
+The <for body> does not contain
+\begin_inset Quotes eld
+\end_inset
+
+continue
+\begin_inset Quotes erd
+\end_inset
+
+ or 'break
+\begin_inset Quotes erd
+\end_inset
+
+.
+\layout Itemize
+
+All goto's are contained within the loop.
+\layout Itemize
+
+No function calls within the loop.
+\layout Itemize
+
+The loop control variable <sym> is not assigned any value within the loop
+\layout Itemize
+
+The loop control variable does NOT participate in any arithmetic operation
+ within the loop.
+\layout Itemize
+
+There are NO switch statements in the loop.
+\layout Subsubsection
+
+Algebraic Simplifications
+\layout Standard
+
+SDCC does numerous algebraic simplifications, the following is a small sub-set
+ of these optimizations.
+\newline
+
+\newline
+
+\family typewriter
+i = j + 0 ; /* changed to */ i = j;
+\newline
+i /= 2; /* changed to */ i >>= 1;
+\newline
+i = j - j ; /* changed to */ i = 0;
+\newline
+i = j / 1 ; /* changed to */ i = j;
+\family default
+
+\newline
+
+\newline
+Note the subexpressions given above are generally introduced by macro expansions
+ or as a result of copy/constant propagation.
+\layout Subsubsection
+
+'switch' Statements
+\layout Standard
+
+SDCC changes switch statements to jump tables when the following conditions
+ are true.
+
+\layout Itemize
+
+The case labels are in numerical sequence, the labels need not be in order,
+ and the starting number need not be one or zero.
+\newline
+
+\newline
+
+\family typewriter
+switch(i) {\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+switch (i) {
+\newline
+case 4:...
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+case 1: ...
+
+\newline
+case 5:...
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+case 2: ...
+
+\newline
+case 3:...
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+case 3: ...
+
+\newline
+case 6:...
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+case 4: ...
+
+\newline
+}\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+}
+\newline
+
+\newline
+
+\family default
+Both the above switch statements will be implemented using a jump-table.
+\layout Itemize
+
+The number of case labels is at least three, since it takes two conditional
+ statements to handle the boundary conditions.
+\layout Itemize
+
+The number of case labels is less than 84, since each label takes 3 bytes
+ and a jump-table can be utmost 256 bytes long.
+
+\layout Standard
+
+Switch statements which have gaps in the numeric sequence or those that
+ have more that 84 case labels can be split into more than one switch statement
+ for efficient code generation, e.g.:
+\newline
+
+\newline
+
+\family typewriter
+switch (i) {
+\newline
+case 1: ...
+
+\newline
+case 2: ...
+
+\newline
+case 3: ...
+
+\newline
+case 4: ...
+
+\newline
+case 9: ...
+
+\newline
+case 10: ...
+
+\newline
+case 11: ...
+
+\newline
+case 12: ...
+
+\newline
+}
+\family default
+
+\newline
+
+\newline
+If the above switch statement is broken down into two switch statements
+\newline
+
+\newline
+
+\family typewriter
+switch (i) {
+\newline
+case 1: ...
+
+\newline
+case 2: ...
+
+\newline
+case 3: ...
+
+\newline
+case 4: ...
+
+\newline
+}
+\newline
+
+\newline
+
+\family default
+and
+\family typewriter
+
+\newline
+
+\newline
+switch (i) {
+\newline
+case 9: \SpecialChar ~
+...
+
+\newline
+case 10: ...
+
+\newline
+case 11: ...
+
+\newline
+case 12:\SpecialChar ~
+...
+
+\newline
+}
+\newline
+
+\newline
+
+\family default
+then both the switch statements will be implemented using jump-tables whereas
+ the unmodified switch statement will not be.
+\layout Subsubsection
+
+Bit-shifting Operations.
+\layout Standard
+
+Bit shifting is one of the most frequently used operation in embedded programmin
+g.
+ SDCC tries to implement bit-shift operations in the most efficient way
+ possible, e.g.:
+\newline
+
+\family typewriter
+
+\newline
+unsigned char i;
+\newline
+...
+
+\newline
+i>>= 4;
+\newline
+...
+\newline
+
+\family default
+
+\newline
+generates the following code:
+\newline
+
+\family typewriter
+
+\newline
+mov a,_i
+\newline
+swap a
+\newline
+anl a,#0x0f
+\newline
+mov _i,a
+\family default
+
+\newline
+
+\newline
+In general SDCC will never setup a loop if the shift count is known.
+ Another example:
+\newline
+
+\newline
+
+\family typewriter
+unsigned int i;
+\newline
+...
+
+\newline
+i >>= 9;
+\newline
+...
+\family default
+
+\newline
+
+\newline
+will generate:
+\newline
+
+\newline
+
+\family typewriter
+mov a,(_i + 1)
+\newline
+mov (_i + 1),#0x00
+\newline
+clr c
+\newline
+rrc a
+\newline
+mov _i,a
+\family default
+
+\newline
+
+\newline
+Note that SDCC stores numbers in little-endian format (i.e.
+ lowest order first).
+\layout Subsubsection
+
+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:
+\newline
+
+\newline
+
+\family typewriter
+unsigned char i;
+\newline
+...
+
+\newline
+i = ((i << 1) | (i >> 7));
+\family default
+
+\newline
+...
+\newline
+
+\newline
+will generate the following code:
+\newline
+
+\newline
+
+\family typewriter
+mov a,_i
+\newline
+rl a
+\newline
+mov _i,a
+\family default
+
+\newline
+
+\newline
+SDCC uses pattern matching on the parse tree to determine this operation.Variatio
+ns of this case will also be recognized as bit-rotation, i.e.:
+\newline
+
+\newline
+
+\family typewriter
+i = ((i >> 7) | (i << 1)); /* left-bit rotation */
+\layout Subsubsection
+
+Highest Order Bit
+\layout Standard
+
+It is frequently required to obtain the highest order bit of an integral
+ type (long, int, short or char types).
+ SDCC recognizes the following expression to yield the highest order bit
+ and generates optimized code for it, e.g.:
+\newline
+
+\newline
+
+\family typewriter
+unsigned int gint;
+\newline
+
+\newline
+foo () {
+\newline
+unsigned char hob;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+hob = (gint >> 15) & 1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+..
+
+\newline
+}
+\family default
+
+\newline
+
+\newline
+will generate the following code:
+\newline
+
+\family typewriter
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 61 ;\SpecialChar ~
+ hob.c 7
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ 000A E5*01\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 62\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ a,(_gint + 1)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ 000C 33\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 63\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ rlc\SpecialChar ~
+ a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ 000D E4\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 64\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ clr\SpecialChar ~
+ a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ 000E 13\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 65\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ rrc\SpecialChar ~
+ a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+ 000F F5*02\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 66\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+ _foo_hob_1_1,a
+\newline
+
+\newline
+
+\family default
+Variations of this case however will
+\emph on
+not
+\emph default
+ be recognized.
+ It is a standard C expression, so I heartily recommend this be the only
+ way to get the highest order bit, (it is portable).
+ Of course it will be recognized even if it is embedded in other expressions,
+ e.g.:
+\newline
+
+\newline
+
+\family typewriter
+xyz = gint + ((gint >> 15) & 1);
+\family default
+
+\newline
+
+\newline
+will still be recognized.
+\layout Subsubsection
+
+Peep-hole Optimizer
+\layout Standard
+
+The compiler uses a rule based, pattern matching and re-writing mechanism
+ for peep-hole optimization.
+ It is inspired by
+\emph on
+copt
+\emph default
+ a peep-hole optimizer by Christopher W.
+ Fraser (cwfraser@microsoft.com).
+ A default set of rules are compiled into the compiler, additional rules
+ may be added with the
+\emph on
+---peep-file <filename>
+\emph default
+ option.
+ The rule language is best illustrated with examples.
+\newline
+
+\newline
+
+\family typewriter
+replace {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+mov %1,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+mov a,%1
+\newline
+} by {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+mov %1,a
+\newline
+}
+\family default
+
+\newline
+
+\newline
+The above rule will change the following assembly sequence:
+\newline
+
+\newline
+
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
+mov r1,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+mov a,r1
+\family default
+
+\newline
+
+\newline
+to
+\newline
+
+\newline
+
+\family typewriter
+mov r1,a
+\family default
+
+\newline
+
+\newline
+Note: All occurrences of a
+\emph on
+%n
+\emph default
+ (pattern variable) must denote the same string.
+ With the above rule, the assembly sequence:
+\newline
+
+\newline
+
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
+mov r1,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+mov a,r2
+\family default
+
+\newline
+
+\newline
+will remain unmodified.
+\newline
+
+\newline
+Other special case optimizations may be added by the user (via
+\emph on
+---peep-file option
+\emph default
+).
+ E.g.
+ some variants of the 8051 MCU allow only
+\family typewriter
+ajmp
+\family default
+ and
+\family typewriter
+acall
+\family default
+.
+ The following two rules will change all
+\family typewriter
+ljmp
+\family default
+ and
+\family typewriter
+lcall
+\family default
+ to
+\family typewriter
+ajmp
+\family default
+ and
+\family typewriter
+acall
+\family default
+
+\newline
+
+\newline
+
+\family typewriter
+replace { lcall %1 } by { acall %1 }
+\newline
+replace { ljmp %1 } by { ajmp %1 }
+\family default
+
+\newline
+
+\newline
+The
+\emph on
+inline-assembler code
+\emph default
+ is also passed through the peep hole optimizer, thus the peephole optimizer
+ can also be used as an assembly level macro expander.
+ The rules themselves are MCU dependent whereas the rule language infra-structur
+e is MCU independent.
+ Peephole optimization rules for other MCU can be easily programmed using
+ the rule language.
+\newline
+
+\newline
+The syntax for a rule is as follows:
+\newline
+
+\newline
+
+\family typewriter
+rule := replace [ restart ] '{' <assembly sequence> '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' by '{' '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ <assembly sequence> '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' [if <functionName> ] '
+\backslash
+n'
+\newline
+
+\family default
+
+\newline
+<assembly sequence> := assembly instruction (each instruction including
+ labels must be on a separate line).
+\newline
+
+\newline
+The optimizer will apply to the rules one by one from the top in the sequence
+ of their appearance, it will terminate when all rules are exhausted.
+ If the 'restart' option is specified, then the optimizer will start matching
+ the rules again from the top, this option for a rule is expensive (performance)
+, it is intended to be used in situations where a transformation will trigger
+ the same rule again.
+ An example of this (not a good one, it has side effects) is the following
+ rule:
+\newline
+
+\newline
+
+\family typewriter
+replace restart {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+pop %1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+push %1 } by {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+; nop
+\newline
+}
+\family default
+
+\newline
+
+\newline
+Note that the replace pattern cannot be a blank, but can be a comment line.
+ Without the 'restart' option only the inner most 'pop' 'push' pair would
+ be eliminated, i.e.:
+\newline
+
+\newline
+
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
+pop ar1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+pop ar2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+push ar2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+push ar1
+\family default
+
+\newline
+
+\newline
+would result in:
+\newline
+
+\newline
+
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
+pop ar1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+; nop
+\newline
+\SpecialChar ~
+\SpecialChar ~
+push ar1
+\family default
+
+\newline
+
+\newline
+
+\emph on
+with
+\emph default
+ the restart option the rule will be applied again to the resulting code
+ and then all the pop-push pairs will be eliminated to yield:
+\newline
+
+\newline
+
+\family typewriter
+\SpecialChar ~
+\SpecialChar ~
+; nop
+\newline
+\SpecialChar ~
+\SpecialChar ~
+; nop
+\family default
+
+\newline
+
+\newline
+A conditional function can be attached to a rule.
+ Attaching rules are somewhat more involved, let me illustrate this with
+ an example.
+\newline
+
+\newline
+
+\family typewriter
+replace {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ljmp %5
+\newline
+%2:
+\newline
+} by {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+sjmp %5
+\newline
+%2:
+\newline
+} if labelInRange
+\family default
+
+\newline
+
+\newline
+The optimizer does a look-up of a function name table defined in function
+
+\emph on
+callFuncByName
+\emph default
+ in the source file SDCCpeeph.c, with the name
+\emph on
+labelInRange
+\emph default
+.
+ If it finds a corresponding entry the function is called.
+ Note there can be no parameters specified for these functions, in this
+ case the use of
+\emph on
+%5
+\emph default
+ is crucial, since the function
+\emph on
+labelInRange
+\emph default
+ expects to find the label in that particular variable (the hash table containin
+g the variable bindings is passed as a parameter).
+ If you want to code more such functions, take a close look at the function
+ labelInRange and the calling mechanism in source file SDCCpeeph.c.
+ I know this whole thing is a little kludgey, but maybe some day we will
+ have some better means.
+ If you are looking at this file, you will also see the default rules that
+ are compiled into the compiler, you can add your own rules in the default
+ set there if you get tired of specifying the ---peep-file option.
+\layout Subsection
+
+Pragmas
+\layout Standard
+
+SDCC supports the following #pragma directives.
+\layout Itemize
+
+SAVE - this will save all current options to the SAVE/RESTORE stack.
+ See RESTORE.
+\layout Itemize
+
+RESTORE - will restore saved options from the last save.
+ SAVEs & RESTOREs can be nested.
+ SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
+ RESTORE pulls current options from the stack.
+ See SAVE.
+\layout Itemize
+
+NOGCSE - will stop global subexpression elimination.
+\layout Itemize
+
+NOINDUCTION - will stop loop induction optimizations.
+\layout Itemize
+
+NOJTBOUND - will not generate code for boundary value checking, when switch
+ statements are turned into jump-tables.
+\layout Itemize
+
+NOOVERLAY - the compiler will not overlay the parameters and local variables
+ of a function.
+\layout Itemize
+
+LESS_PEDANTIC - the compiler will not warn you anymore for obvious mistakes,
+ you'r on your own now ;-(
+\layout Itemize
+
+NOLOOPREVERSE - Will not do loop reversal optimization
+\layout Itemize
+
+EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation
+ of pair of push/pop instruction in ISR function (using interrupt keyword).
+ The directive should be placed immediately before the ISR function definition
+ and it affects ALL ISR functions following it.
+ To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
+EXCLUDE\SpecialChar ~
+none.
+\layout Itemize
+
+NOIV - Do not generate interrupt vector table entries for all ISR functions
+ defined after the pragma.
+ This is useful in cases where the interrupt vector table must be defined
+ manually, or when there is a secondary, manually defined interrupt vector
+ table (e.g.
+ for the autovector feature of the Cypress EZ-USB FX2).
+\layout Itemize
+
+CALLEE-SAVES function1[,function2[,function3...]] - The compiler by default
+ uses a caller saves convention for register saving across function calls,
+ however this can cause unneccessary register pushing & popping when calling
+ small functions from larger functions.
+ This option can be used to switch off the register saving convention for
+ the function names specified.
+ The compiler will not save registers when calling these functions, extra
+ code need to be manually inserted at the entry & exit for these functions
+ to save & restore the registers used by these functions, this can SUBSTANTIALLY
+ reduce code & improve run time performance of the generated code.
+ In the future the compiler (with interprocedural analysis) may be able
+ to determine the appropriate scheme to use for each function call.
+ If ---callee-saves command line option is used, the function names specified
+ in #pragma\SpecialChar ~
+CALLEE-SAVES is appended to the list of functions specified in
+ the command line.
+\layout Standard
+
+The pragma's are intended to be used to turn-off certain optimizations which
+ might cause the compiler to generate extra stack / data space to store
+ compiler generated temporary variables.
+ This usually happens in large functions.
+ Pragma directives should be used as shown in the following example, they
+ are used to control options & optimizations for a given function; pragmas
+ should be placed before and/or after a function, placing pragma's inside
+ a function body could have unpredictable results.
+\newline
+
+\newline
+
+\family typewriter
+#pragma SAVE /* save the current settings */
+\newline
+#pragma NOGCSE /* turnoff global subexpression elimination */
+\newline
+#pragma NOINDUCTION /* turn off induction optimizations */
+\newline
+int foo ()
+\newline
+{
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ /* large code */
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+}
+\newline
+#pragma RESTORE /* turn the optimizations back on */
+\family default
+
+\newline
+
+\newline
+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
+
+
+\emph on
+<pending: this is messy and incomplete>
+\emph default
+ Library Routines
+\layout Enumerate
+
+Compiler support routines (_gptrget, _mulint etc)
+\layout Enumerate
+
+Stdclib functions (puts, printf, strcat etc)
+\layout Enumerate
+
+Math functions (sin, pow, sqrt etc)
+\layout Subsection
+
+Interfacing with Assembly Routines
+\layout Subsubsection
+
+Global Registers used for Parameter Passing
+\layout Standard
+
+The compiler always uses the global registers
+\emph on
+DPL,DPH,B
+\emph default
+and
+\emph on
+ ACC
+\emph default
+ to pass the first parameter to a routine.
+ The second parameter onwards is either allocated on the stack (for reentrant
+ routines or if ---stack-auto is used) or in the internal / external ram
+ (depending on the memory model).
+
+\layout Subsubsection
+
+Assembler Routine(non-reentrant)
+\layout Standard
+
+In the following example the function cfunc calls an assembler routine asm_func,
+ which takes two parameters.
+\newline
+
+\newline
+
+\family typewriter
+extern int asm_func(unsigned char, unsigned char);
+\newline
+
+\newline
+int c_func (unsigned char i, unsigned char j)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return asm_func(i,j);
+\newline
+}
+\newline
+
+\newline
+int main()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c_func(10,9);
+\newline
+}
+\newline
+
+\newline
+
+\family default
+The corresponding assembler function is:
+\newline
+
+\newline
+
+\family typewriter
+.globl _asm_func_PARM_2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+.globl _asm_func
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+.area OSEG
+\newline
+_asm_func_PARM_2:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+.ds 1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+.area CSEG
+\newline
+_asm_func:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov a,dpl
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add a,_asm_func_PARM_2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov dpl,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
+\newline
+
+\newline
+
+\family default
+Note here that the return values are placed in 'dpl' - One byte return value,
+ 'dpl' LSB & 'dph' MSB for two byte values.
+ 'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
+b' & 'acc' for four byte values.
+\layout Standard
+
+The parameter naming convention is _<function_name>_PARM_<n>, where n is
+ the parameter number starting from 1, and counting from the left.
+ The first parameter is passed in
+\begin_inset Quotes eld
+\end_inset
+
+dpl
+\begin_inset Quotes erd
+\end_inset
+
+ for One bye parameter,
+\begin_inset Quotes eld
+\end_inset
+
+dptr
+\begin_inset Quotes erd
+\end_inset
+
+ if two bytes,
+\begin_inset Quotes eld
+\end_inset
+
+b,dptr
+\begin_inset Quotes erd
+\end_inset
+
+ for three bytes and
+\begin_inset Quotes eld
+\end_inset
+
+acc,b,dptr
+\begin_inset Quotes erd
+\end_inset
+
+ for four bytes, the varible name for the second parameter will be _<function_na
+me>_PARM_2.
+\newline
+
+\newline
+Assemble the assembler routine with the following command:
+\newline
+
+\newline
+
+\family sans
+\series bold
+asx8051 -losg asmfunc.asm
+\newline
+
+\newline
+
+\family default
+\series default
+Then compile and link the assembler routine to the C source file with the
+ following command:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcc cfunc.c asmfunc.rel
+\layout Subsubsection
+
+Assembler Routine(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.
+ after the call the left most parameter will be on the top of the stack.
+ Here is an example:
+\newline
+
+\newline
+
+\family typewriter
+extern int asm_func(unsigned char, unsigned char);
+\newline
+
+\newline
+int c_func (unsigned char i, unsigned char j) reentrant
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return asm_func(i,j);
+\newline
+}
+\newline
+
+\newline
+int main()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return c_func(10,9);
+\newline
+}
+\newline
+
+\family default
+
+\newline
+The corresponding assembler routine is:
+\newline
+
+\newline
+
+\family typewriter
+.globl _asm_func
+\newline
+_asm_func:
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+push _bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov _bp,sp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov r2,dpl
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov a,_bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+clr c
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add a,#0xfd
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov r0,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add a,#0xfc
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov r1,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov a,@r0
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add a,r2
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov dpl,a
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov dph,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov sp,_bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+pop _bp
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
+\newline
+
+\newline
+
+\family default
+The compiling and linking procedure remains the same, however note the extra
+ entry & exit linkage required for the assembler code, _bp is the stack
+ frame pointer and is used to compute the offset into the stack for parameters
+ and local variables.
+\layout Subsection
+
+External Stack
+\layout Standard
+
+The external stack is located at the start of the external ram segment,
+ and is 256 bytes in size.
+ When ---xstack option is used to compile the program, the parameters and
+ local variables of all reentrant functions are allocated in this area.
+ This option is provided for programs with large stack space requirements.
+ When used with the ---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).
+\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
+
+ANSI-Compliance
+\layout Standard
+
+Deviations from the compliancy.
+\layout Itemize
+
+functions are not always reentrant.
+\layout Itemize
+
+structures cannot be assigned values directly, cannot be passed as function
+ parameters or assigned to each other and cannot be a return value from
+ a function, e.g.:
+\family typewriter
+
+\newline
+
+\newline
+struct s { ...
+ };
+\newline
+struct s s1, s2;
+\newline
+foo()
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\newline
+struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
+ ANSI */
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+struct s rets;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+return rets;/* is invalid in SDCC although allowed in ANSI */
+\newline
+}
+\layout Itemize
+
+'long long' (64 bit integers) not supported.
+\layout Itemize
+
+'double' precision floating point not supported.
+\layout Itemize
+
+No support for setjmp and longjmp (for now).
+\layout Itemize
+
+Old K&R style function declarations are NOT allowed.
+\newline
+
+\family typewriter
+
+\newline
+foo(i,j) /* this old style of function declarations */
+\newline
+int i,j; /* are valid in ANSI but not valid in SDCC */
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Itemize
+
+functions declared as pointers must be dereferenced during the call.
+\newline
+
+\family typewriter
+
+\newline
+int (*foo)();
+\newline
+...
+
+\newline
+/* has to be called like this */
+\newline
+(*foo)(); /* ansi standard allows calls to be made like 'foo()' */
+\layout Subsection
+
+Cyclomatic Complexity
+\layout Standard
+
+Cyclomatic complexity of a function is defined as the number of independent
+ paths the program can take during execution of the function.
+ This is an important number since it defines the number test cases you
+ have to generate to validate the function.
+ The accepted industry standard for complexity number is 10, if the cyclomatic
+ complexity reported by SDCC exceeds 10 you should think about simplification
+ of the function logic.
+ Note that the complexity level is not related to the number of lines of
+ code in a function.
+ Large functions can have low complexity, and small functions can have large
+ complexity levels.
+
+\newline
+
+\newline
+SDCC uses the following formula to compute the complexity:
+\newline
+
+\layout Standard
+
+complexity = (number of edges in control flow graph) - (number of nodes
+ in control flow graph) + 2;
+\newline
+
+\newline
+Having said that the industry standard is 10, you should be aware that in
+ some cases it be may unavoidable to have a complexity level of less than
+ 10.
+ For example if you have switch statement with more than 10 case labels,
+ each case label adds one to the complexity level.
+ 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 Section
+
+TIPS
+\layout Standard
+
+Here are a few guidelines that will help the compiler generate more efficient
+ code, some of the tips are specific to this compiler others are generally
+ good programming practice.
+\layout Itemize
+
+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'.
+\layout Itemize
+
+Use unsigned when it is known in advance that the value is not going to
+ be negative.
+ This helps especially if you are doing division or multiplication.
+\layout Itemize
+
+NEVER jump into a LOOP.
+\layout Itemize
+
+Declare the variables to be local whenever possible, especially loop control
+ variables (induction).
+\layout Itemize
+
+Since the compiler does not always do implicit integral promotion, the programme
+r should do an explicit cast when integral promotion is required.
+\layout Itemize
+
+Reducing the size of division, multiplication & modulus operations can reduce
+ code size substantially.
+ Take the following code for example.
+\family typewriter
+
+\newline
+
+\newline
+foobar(unsigned int p1, unsigned char ch)
+\newline
+{
+\newline
+ unsigned char ch1 = p1 % ch ;
+\newline
+ ....
+
+\newline
+}
+\newline
+
+\family default
+
+\newline
+For the modulus operation the variable ch will be promoted to unsigned int
+ first then the modulus operation will be performed (this will lead to a
+ call to support routine _moduint()), and the result will be casted to a
+ char.
+ If the code is changed to
+\newline
+
+\family typewriter
+
+\newline
+foobar(unsigned int p1, unsigned char ch)
+\newline
+{
+\newline
+ unsigned char ch1 = (unsigned char)p1 % ch ;
+\newline
+ ....
+
+\newline
+}
+\newline
+
+\family default
+
+\newline
+It would substantially reduce the code generated (future versions of the
+ compiler will be smart enough to detect such optimization oppurtunities).
+\layout Subsection
+
+Notes on MCS51 memory layout
+\layout Standard
+
+The 8051 family of micro controller have a minimum of 128 bytes of internal
+ memory which is structured as follows
+\newline
+
+\newline
+- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
+
+\newline
+- Bytes 20-2F - 16 bytes to hold 128 bit variables and
+\newline
+- Bytes 30-7F - 60 bytes for general purpose use.
+\newline
+
+\newline
+Normally the SDCC compiler will only utilise the first bank of registers,
+ but it is possible to specify that other banks of registers should be used
+ in interrupt routines.
+ By default, the compiler will place the stack after the last bank of used
+ registers, i.e.
+ if the first 2 banks of registers are used, it will position the base of
+ the internal stack at address 16 (0X10).
+ This implies that as the stack grows, it will use up the remaining register
+ banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
+ general purpose use.
+\layout Standard
+
+By default, the compiler uses the 60 general purpose bytes to hold "near
+ data".
+ The compiler/optimiser may also declare some Local Variables in this area
+ to hold local data.
+
+\layout Standard
+
+If any of the 128 bit variables are used, or near data is being used then
+ care needs to be taken to ensure that the stack does not grow so much that
+ it starts to over write either your bit variables or "near data".
+ There is no runtime checking to prevent this from happening.
+\layout Standard
+
+The amount of stack being used is affected by the use of the "internal stack"
+ to save registers before a subroutine call is made (---stack-auto will
+ declare parameters and local variables on the stack) and the number of
+ nested subroutines.
+\layout Standard
+
+If you detect that the stack is over writing you data, then the following
+ can be done.
+ ---xstack will cause an external stack to be used for saving registers
+ and (if ---stack-auto is being used) storing parameters and local variables.
+ However this will produce more code which will be slower to execute.
+
+\layout Standard
+
+---stack-loc will allow you specify the start of the stack, i.e.
+ you could start it after any data in the general purpose area.
+ However this may waste the memory not used by the register banks and if
+ the size of the "near data" increases, it may creep into the bottom of
+ the stack.
+\layout Standard
+
+---stack-after-data, similar to the ---stack-loc, but it automatically places
+ the stack after the end of the "near data".
+ Again this could waste any spare register space.
+\layout Standard
+
+---data-loc allows you to specify the start address of the near data.
+ This could be used to move the "near data" further away from the stack
+ giving it more room to grow.
+ This will only work if no bit variables are being used and the stack can
+ grow to use the bit variable space.
+\newline
+
+\newline
+Conclusion.
+\newline
+
+\newline
+If you find that the stack is over writing your bit variables or "near data"
+ then the approach which best utilised the internal memory is to position
+ the "near data" after the last bank of used registers or, if you use bit
+ variables, after the last bit variable by using the ---data-loc, e.g.
+ if two register banks are being used and no bit variables, ---data-loc
+ 16, and use the ---stack-after-data option.
+\layout Standard
+
+If bit variables are being used, another method would be to try and squeeze
+ the data area in the unused register banks if it will fit, and start the
+ stack after the last bit variable.
+\layout Section
+
+Retargetting for other MCUs.
+\layout Standard
+
+The issues for retargetting the compiler are far too numerous to be covered
+ by this document.
+ What follows is a brief description of each of the seven phases of the
+ compiler and its MCU dependency.
+\layout Itemize
+
+Parsing the source and building the annotated parse tree.
+ This phase is largely MCU independent (except for the language extensions).
+ Syntax & semantic checks are also done in this phase, along with some initial
+ optimizations like back patching labels and the pattern matching optimizations
+ like bit-rotation etc.
+\layout Itemize
+
+The second phase involves generating an intermediate code which can be easy
+ manipulated during the later phases.
+ This phase is entirely MCU independent.
+ The intermediate code generation assumes the target machine has unlimited
+ number of registers, and designates them with the name iTemp.
+ The compiler can be made to dump a human readable form of the code generated
+ by using the ---dumpraw option.
+\layout Itemize
+
+This phase does the bulk of the standard optimizations and is also MCU independe
+nt.
+ This phase can be broken down into several sub-phases:
+\newline
+
+\newline
+Break down intermediate code (iCode) into basic blocks.
+\newline
+Do control flow & data flow analysis on the basic blocks.
+\newline
+Do local common subexpression elimination, then global subexpression elimination
+\newline
+Dead code elimination
+\newline
+Loop optimizations
+\newline
+If loop optimizations caused any changes then do 'global subexpression eliminati
+on' and 'dead code elimination' again.
+\layout Itemize
+
+This phase determines the live-ranges; by live range I mean those iTemp
+ variables defined by the compiler that still survive after all the optimization
+s.
+ Live range analysis is essential for register allocation, since these computati
+on determines which of these iTemps will be assigned to registers, and for
+ how long.
+\layout Itemize
+
+Phase five is register allocation.
+ There are two parts to this process.
+\newline
+
+\newline
+The first part I call 'register packing' (for lack of a better term).
+ In this case several MCU specific expression folding is done to reduce
+ register pressure.
+\newline
+
+\newline
+The second part is more MCU independent and deals with allocating registers
+ to the remaining live ranges.
+ A lot of MCU specific code does creep into this phase because of the limited
+ number of index registers available in the 8051.
+\layout Itemize
+
+The Code generation phase is (unhappily), entirely MCU dependent and very
+ little (if any at all) of this code can be reused for other MCU.
+ However the scheme for allocating a homogenized assembler operand for each
+ iCode operand may be reused.
+\layout Itemize
+
+As mentioned in the optimization section the peep-hole optimizer is rule
+ based system, which can reprogrammed for other MCUs.
+\layout Section
+
+SDCDB - Source Level Debugger
+\layout Standard
+
+SDCC is distributed with a source level debugger.
+ The debugger uses a command line interface, the command repertoire of the
+ debugger has been kept as close to gdb (the GNU debugger) as possible.
+ The configuration and build process is part of the standard compiler installati
+on, which also builds and installs the debugger in the target directory
+ specified during configuration.
+ The debugger allows you debug BOTH at the C source and at the ASM source
+ level.
+\layout Subsection
+
+Compiling for Debugging
+\layout Standard
+
+The \SpecialChar \-
+\SpecialChar \-
+debug option must be specified for all files for which debug information
+ is to be generated.
+ The complier generates a .cdb file for each of these files.
+ The linker updates the .cdb file with the address information.
+ This .cdb is used by the debugger.
+\layout Subsection
+
+How the Debugger Works
+\layout Standard
+
+When the ---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 .cdb file, the linker updates the .cdb file with the address
+ information for the symbols.
+ The debugger reads the symbolic information generated by the compiler &
+ the address information generated by the linker.
+ It uses the SIMULATOR (Daniel's S51) to execute the program, the program
+ 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
+
+Starting the Debugger
+\layout Standard
+
+The debugger can be started using the following command line.
+ (Assume the file you are debugging has the file name foo).
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcdb foo
+\newline
+
+\family default
+\series default
+
+\newline
+The debugger will look for the following files.
+\layout Itemize
+
+foo.c - the source file.
+\layout Itemize
+
+foo.cdb - the debugger symbol information file.
+\layout Itemize
+
+foo.ihx - the intel hex format object file.
+\layout Subsection
+
+Command Line Options.
+\layout Itemize
+
+---directory=<source file directory> this option can used to specify the
+ directory search list.
+ The debugger will look into the directory list specified for source, cdb
+ & ihx files.
+ The items in the directory list must be separated by ':', e.g.
+ if the source files can be in the directories /home/src1 and /home/src2,
+ the ---directory option should be ---directory=/home/src1:/home/src2.
+ Note there can be no spaces in the option.
+
+\layout Itemize
+
+-cd <directory> - change to the <directory>.
+\layout Itemize
+
+-fullname - used by GUI front ends.
+\layout Itemize
+
+-cpu <cpu-type> - this argument is passed to the simulator please see the
+ simulator docs for details.
+\layout Itemize
+
+-X <Clock frequency > this options is passed to the simulator please see
+ the simulator docs for details.
+\layout Itemize
+
+-s <serial port file> passed to simulator see the simulator docs for details.
+\layout Itemize
+
+-S <serial in,out> passed to simulator see the simulator docs for details.
+\layout Subsection
+
+Debugger Commands.
+\layout Standard
+
+As mention earlier the command interface for the debugger has been deliberately
+ kept as close the GNU debugger gdb, as possible.
+ This will help the integration with existing graphical user interfaces
+ (like ddd, xxgdb or xemacs) existing for the GNU debugger.
+\layout Subsubsection
+
+break [line | file:line | function | file:function]
+\layout Standard
+
+Set breakpoint at specified line or function:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcdb>break 100
+\newline
+sdcdb>break foo.c:100
+\newline
+sdcdb>break funcfoo
+\newline
+sdcdb>break foo.c:funcfoo
+\layout Subsubsection
+
+clear [line | file:line | function | file:function ]
+\layout Standard
+
+Clear breakpoint at specified line or function:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcdb>clear 100
+\newline
+sdcdb>clear foo.c:100
+\newline
+sdcdb>clear funcfoo
+\newline
+sdcdb>clear foo.c:funcfoo
+\layout Subsubsection
+
+continue
+\layout Standard
+
+Continue program being debugged, after breakpoint.
+\layout Subsubsection
+
+finish
+\layout Standard
+
+Execute till the end of the current function.
+\layout Subsubsection
+
+delete [n]
+\layout Standard
+
+Delete breakpoint number 'n'.
+ If used without any option clear ALL user defined break points.
+\layout Subsubsection
+
+info [break | stack | frame | registers ]
+\layout Itemize
+
+info break - list all breakpoints
+\layout Itemize
+
+info stack - show the function call stack.
+\layout Itemize
+
+info frame - show information about the current execution frame.
+\layout Itemize
+
+info registers - show content of all registers.
+\layout Subsubsection
+
+step
+\layout Standard
+
+Step program until it reaches a different source line.
+\layout Subsubsection
+
+next
+\layout Standard
+
+Step program, proceeding through subroutine calls.
+\layout Subsubsection
+
+run
+\layout Standard
+
+Start debugged program.
+\layout Subsubsection
+
+ptype variable
+\layout Standard
+
+Print type information of the variable.
+\layout Subsubsection
+
+print variable
+\layout Standard
+
+print value of variable.
+\layout Subsubsection
+
+file filename
+\layout Standard
+
+load the given file name.
+ Note this is an alternate method of loading file for debugging.
+\layout Subsubsection
+
+frame
+\layout Standard
+
+print information about current frame.
+\layout Subsubsection
+
+set srcmode
+\layout Standard
+
+Toggle between C source & assembly source.
+\layout Subsubsection
+
+! simulator command
+\layout Standard
+
+Send the string following '!' to the simulator, the simulator response is
+ displayed.
+ Note the debugger does not interpret the command being sent to the simulator,
+ so if a command like 'go' is sent the debugger can loose its execution
+ context and may display incorrect values.
+\layout Subsubsection
+
+quit.
+\layout Standard
+
+"Watch me now.
+ Iam going Down.
+ My name is Bobby Brown"
+\layout Subsection
+
+Interfacing with XEmacs.
+\layout Standard
+
+Two files (in emacs lisp) are provided for the interfacing with XEmacs,
+ sdcdb.el and sdcdbsrc.el.
+ These two files can be found in the $(prefix)/bin directory after the installat
+ion is complete.
+ These files need to be loaded into XEmacs for the interface to work.
+ This can be done at XEmacs startup time by inserting the following into
+ your '.xemacs' file (which can be found in your HOME directory):
+\newline
+
+\newline
+
+\family typewriter
+(load-file sdcdbsrc.el)
+\family default
+
+\newline
+
+\newline
+.xemacs is a lisp file so the () around the command is REQUIRED.
+ The files can also be loaded dynamically while XEmacs is running, set the
+ environment variable 'EMACSLOADPATH' to the installation bin directory
+ (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
+ To start the interface enter the following command:
+\newline
+
+\newline
+
+\family sans
+\series bold
+ESC-x sdcdbsrc
+\family default
+\series default
+
+\newline
+
+\newline
+You will prompted to enter the file name to be debugged.
+
+\newline
+
+\newline
+The command line options that are passed to the simulator directly are bound
+ to default values in the file sdcdbsrc.el.
+ The variables are listed below, these values maybe changed as required.
+\layout Itemize
+
+sdcdbsrc-cpu-type '51
+\layout Itemize
+
+sdcdbsrc-frequency '11059200
+\layout Itemize
+
+sdcdbsrc-serial nil
+\layout Standard
+
+The following is a list of key mapping for the debugger interface.
+\layout Standard
+
+\SpecialChar ~
+
+\family typewriter
+
+\newline
+;; Current Listing ::
+\newline
+;;key\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+binding\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Comment
+\newline
+;;---\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+------\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-binding\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+--------
+\newline
+;;
+\newline
+;; n\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdb-next-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-Comment
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB next command
\newline
-;;---\SpecialChar ~
+;; b\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+\SpecialChar ~
+ sdcdb-back-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+SDCDB back command
+\newline
+;; c\SpecialChar ~
\SpecialChar ~
--------\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdb-cont-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
--------
+SDCDB continue command
\newline
-;;
+;; s\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-step-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB step command
\newline
-;; n\SpecialChar ~
+;; ?\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-next-from-src\SpecialChar ~
+ sdcdb-whatis-c-sexp\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB next command
+SDCDB ptypecommand for data at
\newline
-;; b\SpecialChar ~
+;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-back-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB back command
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ buffer point
\newline
-;; c\SpecialChar ~
+;; x\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-cont-from-src\SpecialChar ~
+ sdcdbsrc-delete\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB continue command
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB Delete all breakpoints if no arg
\newline
-;; s\SpecialChar ~
+;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-step-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB step command
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+given or delete arg (C-u arg x)
\newline
-;; ?\SpecialChar ~
+;; m\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-whatis-c-sexp\SpecialChar ~
+ sdcdbsrc-frame\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB ptypecommand for data at
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB Display current frame if no arg,
+\newline
+;;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+given or display frame arg
\newline
;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- buffer point
-\newline
-;; x\SpecialChar ~
+\SpecialChar ~
+buffer point
+\newline
+;; !\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-goto-sdcdb\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Goto the SDCDB output buffer
+\newline
+;; p\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-print-c-sexp\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB print command for data at
+\newline
+;;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-delete\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB Delete all breakpoints if no arg
-\newline
-;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ buffer point
+\newline
+;; g\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdbsrc-goto-sdcdb\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+Goto the SDCDB output buffer
+\newline
+;; t\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdbsrc-mode\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-given or delete arg (C-u arg x)
-\newline
-;; m\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+Toggles Sdcdbsrc mode (turns it off)
+\newline
+;;
+\newline
+;; C-c C-f\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-frame\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdb-finish-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+SDCDB finish command
+\newline
+;;
+\newline
+;; C-x SPC\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB Display current frame if no arg,
-\newline
-;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdb-break\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+Set break for line with point
+\newline
+;; ESC t\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdbsrc-mode\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+Toggle Sdcdbsrc mode
+\newline
+;; ESC m\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-given or display frame arg
-\newline
-;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdbsrc-srcmode\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ Toggle list mode
+\newline
+;;
+\family default
+
+\newline
+
+\layout Section
+
+Other Processors
+\layout Subsection
+
+The Z80 and gbz80 port
+\layout Standard
+
+SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
+ The port is incomplete - long support is incomplete (mul, div and mod are
+ unimplimented), and both float and bitfield support is missing.
+ Apart from that the code generated is correct.
+\layout Standard
+
+As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
+ The stack frame is similar to that generated by the IAR Z80 compiler.
+ IX is used as the base pointer, HL is used as a temporary register, and
+ BC and DE are available for holding varibles.
+ IY is currently unusued.
+ Return values are stored in HL.
+ One bad side effect of using IX as the base pointer is that a functions
+ stack frame is limited to 127 bytes - this will be fixed in a later version.
+\layout Section
+
+Support
+\layout Standard
+
+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).
+ 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
+ end users.
+ Is SDCC perfect? No, that's why we need your help.
+ The developers take pride in fixing reported bugs.
+ You can help by reporting the bugs and helping other SDCC users.
+ There are lots of ways to contribute, and we encourage you to take part
+ in making SDCC a great software package.
+\layout Subsection
+
+Reporting Bugs
+\layout Standard
+
+Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd
+cc@sdcc.sourceforge.net'.
+ Bugs will be fixed ASAP.
+ When reporting a bug, it is very useful to include a small test program
+ which reproduces the problem.
+ If you can isolate the problem by looking at the generated assembly code,
+ this can be very helpful.
+ Compiling your program with the ---dumpall option can sometimes be useful
+ in locating optimization problems.
+\layout Section
+
+Compiler internals
+\layout Subsection
+
+The anatomy of the compiler
+\layout Standard
+
+
+\shape italic
+This is an excerpt from an atricle published in Circuit Cellar MagaZine
+ in august 2000.
+ It's a little outdated (the compiler is much more efficient now and user/devell
+oper friendly), but pretty well exposes the guts of it all.
+\shape default
+
+\newline
+
+\newline
+The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
+ It is fairly easy to retarget for other 8-bit MCU.
+ Here we take a look at some of the internals of the compiler.
+
+\layout Paragraph*
+
+Parsing
+\layout Standard
+
+Parsing the input source file and creating an AST (Annotated Syntax Tree).
+ This phase also involves propagating types (annotating each node of the
+ parse tree with type information) and semantic analysis.
+ There are some MCU specific parsing rules.
+ For example the storage classes, the extended storage classes are MCU specific
+ while there may be a xdata storage class for 8051 there is no such storage
+ class for z80 or Atmel AVR.
+ SDCC allows MCU specific storage class extensions, i.e.
+ xdata will be treated as a storage class specifier when parsing 8051 C
+ code but will be treated as a C identifier when parsing z80 or ATMEL AVR
+ C code.
+\layout Paragraph*
+
+Generating iCode
+\layout Standard
+
+Intermediate code generation.
+ In this phase the AST is broken down into three-operand form (iCode).
+ These three operand forms are represented as doubly linked lists.
+ ICode is the term given to the intermediate form generated by the compiler.
+ ICode example section shows some examples of iCode generated for some simple
+ C source functions.
+\layout Paragraph*
+
+Optimizations.
+\layout Standard
+
+Bulk of the target independent optimizations is performed in this phase.
+ The optimizations include constant propagation, common sub-expression eliminati
+on, loop invariant code movement, strength reduction of loop induction variables
+ and dead-code elimination.
+\layout Paragraph*
+
+Live range analysis
+\layout Standard
+
+During intermediate code generation phase, the compiler assumes the target
+ machine has infinite number of registers and generates a lot of temporary
+ variables.
+ The live range computation determines the lifetime of each of these compiler-ge
+nerated temporaries.
+ A picture speaks a thousand words.
+ ICode example sections show the live range annotations for each of the
+ operand.
+ It is important to note here, each iCode is assigned a number in the order
+ of its execution in the function.
+ The live ranges are computed in terms of these numbers.
+ The from number is the number of the iCode which first defines the operand
+ and the to number signifies the iCode which uses this operand last.
+\layout Paragraph*
+
+Register Allocation
+\layout Standard
+
+The register allocation determines the type and number of registers needed
+ by each operand.
+ In most MCUs only a few registers can be used for indirect addressing.
+ In case of 8051 for example the registers R0 & R1 can be used to indirectly
+ address the internal ram and DPTR to indirectly address the external ram.
+ The compiler will try to allocate the appropriate register to pointer variables
+ if it can.
+ ICode example section shows the operands annotated with the registers assigned
+ to them.
+ The compiler will try to keep operands in registers as much as possible;
+ there are several schemes the compiler uses to do achieve this.
+ When the compiler runs out of registers the compiler will check to see
+ if there are any live operands which is not used or defined in the current
+ basic block being processed, if there are any found then it will push that
+ operand and use the registers in this block, the operand will then be popped
+ at the end of the basic block.
+
+\layout Standard
+
+There are other MCU specific considerations in this phase.
+ Some MCUs have an accumulator; very short-lived operands could be assigned
+ to the accumulator instead of general-purpose register.
+\layout Paragraph*
+
+Code generation
+\layout Standard
+
+Figure II gives a table of iCode operations supported by the compiler.
+ The code generation involves translating these operations into corresponding
+ assembly code for the processor.
+ This sounds overly simple but that is the essence of code generation.
+ Some of the iCode operations are generated on a MCU specific manner for
+ example, the z80 port does not use registers to pass parameters so the
+ SEND and RECV iCode operations will not be generated, and it also does
+ not support JUMPTABLES.
+
+\newline
+
+\series bold
+\shape italic
+\color red
+<Where is Figure II ?>
+\layout Paragraph*
+
+ICode Example
+\layout Standard
+
+This section shows some details of iCode.
+ The example C code does not do anything useful; it is used as an example
+ to illustrate the intermediate code generated by the compiler.
+\newline
+
+\newline
+
+\family typewriter
+1.\SpecialChar ~
+xdata int * p;
+\newline
+2.\SpecialChar ~
+int gint;
+\newline
+3.\SpecialChar ~
+/* This function does nothing useful.
+ It is used
+\newline
+4.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+for the purpose of explaining iCode */
+\newline
+5.\SpecialChar ~
+short function (data int *x)
+\newline
+6.\SpecialChar ~
+{
+\newline
+7.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+short i=10; /* dead initialization eliminated */
+\newline
+8.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+short sum=10; /* dead initialization eliminated */
+\newline
+9.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+short mul;
+\newline
+10.\SpecialChar ~
\SpecialChar ~
+int j ;
+\newline
+11.\SpecialChar ~
\SpecialChar ~
+while (*x) *x++ = *p++;
+\newline
+12.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+sum = 0 ;
+\newline
+13.\SpecialChar ~
\SpecialChar ~
+mul = 0;
+\newline
+14.\SpecialChar ~
\SpecialChar ~
+/* compiler detects i,j to be induction variables */
+\newline
+15.\SpecialChar ~
\SpecialChar ~
+for (i = 0, j = 10 ; i < 10 ; i++, j---) {
+\newline
+16.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+sum += i;
+\newline
+17.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+mul += i * 3; /* this multiplication remains */
+\newline
+18.\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+gint += j * 3;/* this multiplication changed to addition */
+\newline
+19.\SpecialChar ~
\SpecialChar ~
+}
+\newline
+20.\SpecialChar ~
\SpecialChar ~
-buffer point
+return sum+mul;
+\newline
+21.\SpecialChar ~
+}
+\newline
+
+\newline
+
+\family default
+In addition to the operands each iCode contains information about the filename
+ and line it corresponds to in the source file.
+ The first field in the listing should be interpreted as follows:
+\newline
+
+\shape italic
+\size footnotesize
+Filename(linenumber: iCode Execution sequence number : ICode hash table
+ key : loop depth of the iCode).
+\shape default
+\size default
+
+\newline
+Then follows the human readable form of the ICode operation.
+ Each operand of this triplet form can be of three basic types a) compiler
+ generated temporary b) user defined variable c) a constant value.
+ Note that local variables and parameters are replaced by compiler generated
+ temporaries.
+ Live ranges are computed only for temporaries (i.e.
+ live ranges are not computed for global variables).
+ Registers are allocated for temporaries only.
+ Operands are formatted in the following manner:
+\newline
+
+\shape italic
+\size footnotesize
+Operand Name [lr live-from : live-to ] { type information } [ registers
+ allocated ].
+\shape default
+\size default
+
+\newline
+As mentioned earlier the live ranges are computed in terms of the execution
+ sequence number of the iCodes, for example
+\newline
+the iTemp0 is live from (i.e.
+ first defined in iCode with execution sequence number 3, and is last used
+ in the iCode with sequence number 5).
+ For induction variables such as iTemp21 the live range computation extends
+ the lifetime from the start to the end of the loop.
+\newline
+The register allocator used the live range information to allocate registers,
+ the same registers may be used for different temporaries if their live
+ ranges do not overlap, for example r0 is allocated to both iTemp6 and to
+ iTemp17 since their live ranges do not overlap.
+ In addition the allocator also takes into consideration the type and usage
+ of a temporary, for example itemp6 is a pointer to near space and is used
+ as to fetch data from (i.e.
+ used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
+ Some short lived temporaries are allocated to special registers which have
+ meaning to the code generator e.g.
+ iTemp13 is allocated to a pseudo register CC which tells the back end that
+ the temporary is used only for a conditional jump the code generation makes
+ use of this information to optimize a compare and jump ICode.
+\newline
+There are several loop optimizations performed by the compiler.
+ It can detect induction variables iTemp21(i) and iTemp23(j).
+ Also note the compiler does selective strength reduction, i.e.
+ the multiplication of an induction variable in line 18 (gint = j * 3) is
+ changed to addition, a new temporary iTemp17 is allocated and assigned
+ a initial value, a constant 3 is then added for each iteration of the loop.
+ The compiler does not change the multiplication in line 17 however since
+ the processor does support an 8 * 8 bit multiplication.
+\newline
+Note the dead code elimination optimization eliminated the dead assignments
+ in line 7 & 8 to I and sum respectively.
+\newline
+
+\layout Standard
+
+
+\size footnotesize
+Sample.c (5:1:0:0) _entry($9) :
+\layout Standard
+
+
+\size footnotesize
+Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:4:53:0) preHeaderLbl0($11) :
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
+ * int}[r2]
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:6:5:1) _whilecontinue_0($1) :
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
+ int}[r0]]
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
+ * int}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
+ {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
+ * int}[DPTR]]
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
+}[r2 r3]
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
+ * int}[r0] + 0x2 {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:16:20:1) goto _whilecontinue_0($1)
+\layout Standard
+
+
+\size footnotesize
+Sample.c(11:17:21:0)_whilebreak_0($3) :
+\layout Standard
+
+
+\size footnotesize
+Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(15:20:54:0)preHeaderLbl1($13) :
+\layout Standard
+
+
+\size footnotesize
+Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(15:24:26:1)_forcond_0($4) :
+\layout Standard
+
+
+\size footnotesize
+Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
+ < 0xa {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
+\layout Standard
+
+
+\size footnotesize
+Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
+ + ITemp21 [lr21:38]{short}[r4]
+\layout Standard
+
+
+\size footnotesize
+Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
+ * 0x3 {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
+ + iTemp15 [lr29:30]{short}[r1]
+\layout Standard
+
+
+\size footnotesize
+Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
+ r0]- 0x3 {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
+int}[r7 r0]
+\layout Standard
+
+
+\size footnotesize
+Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
+ + 0x1 {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
+ r6]- 0x1 {short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(19:38:47:1) goto _forcond_0($4)
+\layout Standard
+
+
+\size footnotesize
+Sample.c(19:39:48:0)_forbreak_0($7) :
+\layout Standard
+
+
+\size footnotesize
+Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
+ + ITemp11 [lr19:40]{short}[r3]
+\layout Standard
+
+
+\size footnotesize
+Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
+\layout Standard
+
+
+\size footnotesize
+Sample.c(20:42:51:0)_return($8) :
+\layout Standard
+
+
+\size footnotesize
+Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
+\size default
+
\newline
-;; !\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdbsrc-goto-sdcdb\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-Goto the SDCDB output buffer
+
\newline
-;; p\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdb-print-c-sexp\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SDCDB print command for data at
+Finally the code generated for this function:
\newline
-;;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+
+\layout Standard
+
+
+\size footnotesize
+.area DSEG (DATA)
+\layout Standard
+
+
+\size footnotesize
+_p::
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+.ds 2
+\layout Standard
+
+
+\size footnotesize
+_gint::
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+.ds 2
+\layout Standard
+
+
+\size footnotesize
+; sample.c 5
+\layout Standard
+
+
+\size footnotesize
+; ----------------------------------------------
+\layout Standard
+
+
+\size footnotesize
+; function function
+\layout Standard
+
+
+\size footnotesize
+; ----------------------------------------------
+\layout Standard
+
+
+\size footnotesize
+_function:
+\layout Standard
+
+
+\size footnotesize
+; iTemp0 [lr3:5]{_near * int}[r2] = recv
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r2,dpl
+\layout Standard
+
+
+\size footnotesize
+; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
- buffer point
-\newline
-;; g\SpecialChar ~
+mov ar0,r2
+\layout Standard
+
+
+\size footnotesize
+;_whilecontinue_0($1) :
+\layout Standard
+
+
+\size footnotesize
+00101$:
+\layout Standard
+
+
+\size footnotesize
+; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
+\layout Standard
+
+
+\size footnotesize
+; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov ar2,@r0
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+inc r0
+\layout Standard
+
+
+\size footnotesize
+\SpecialChar ~
\SpecialChar ~
+mov ar3,@r0
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+dec r0
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov a,r2
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+orl a,r3
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
- sdcdbsrc-goto-sdcdb\SpecialChar ~
+jz 00103$
+\layout Standard
+
+
+\size footnotesize
+00114$:
+\layout Standard
+
+
+\size footnotesize
+; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
+\layout Standard
+
+
+\size footnotesize
+\SpecialChar ~
\SpecialChar ~
+mov dpl,_p
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov dph,(_p + 1)
+\layout Standard
+
+
+\size footnotesize
+; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov a,#0x02
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+add a,_p
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
-Goto the SDCDB output buffer
-\newline
-;; t\SpecialChar ~
+mov _p,a
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+clr a
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+addc a,(_p + 1)
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov (_p + 1),a
+\layout Standard
+
+
+\size footnotesize
+; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+movx a,@dptr
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r2,a
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+inc dptr
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
- sdcdbsrc-mode\SpecialChar ~
\SpecialChar ~
+movx a,@dptr
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r3,a
+\layout Standard
+
+
+\size footnotesize
+; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov @r0,ar2
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+inc r0
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov @r0,ar3
+\layout Standard
+
+
+\size footnotesize
+; iTemp6 [lr5:16]{_near * int}[r0] =
+\layout Standard
+
+
+\size footnotesize
+; iTemp6 [lr5:16]{_near * int}[r0] +
+\layout Standard
+
+
+\size footnotesize
+; 0x2 {short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+inc r0
+\layout Standard
+
+
+\size footnotesize
+; goto _whilecontinue_0($1)
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+sjmp 00101$
+\layout Standard
+
+
+\size footnotesize
+; _whilebreak_0($3) :
+\layout Standard
+
+
+\size footnotesize
+00103$:
+\layout Standard
+
+
+\size footnotesize
+; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
-Toggles Sdcdbsrc mode (turns it off)
-\newline
-;;
-\newline
-;; C-c C-f\SpecialChar ~
+mov r2,#0x00
+\layout Standard
+
+
+\size footnotesize
+; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r3,#0x00
+\layout Standard
+
+
+\size footnotesize
+; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r4,#0x00
+\layout Standard
+
+
+\size footnotesize
+; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r5,#0x0A
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
- sdcdb-finish-from-src\SpecialChar ~
\SpecialChar ~
+mov r6,#0x00
+\layout Standard
+
+
+\size footnotesize
+; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r7,#0x1E
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r0,#0x00
+\layout Standard
+
+
+\size footnotesize
+; _forcond_0($4) :
+\layout Standard
+
+
+\size footnotesize
+00104$:
+\layout Standard
+
+
+\size footnotesize
+; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
+\layout Standard
+
+
+\size footnotesize
+; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
-SDCDB finish command
-\newline
-;;
-\newline
-;; C-x SPC\SpecialChar ~
+clr c
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov a,r4
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+xrl a,#0x80
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+subb a,#0x8a
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
- sdcdb-break\SpecialChar ~
\SpecialChar ~
+jnc 00107$
+\layout Standard
+
+
+\size footnotesize
+00115$:
+\layout Standard
+
+
+\size footnotesize
+; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
+\layout Standard
+
+
+\size footnotesize
+; iTemp21 [lr21:38]{short}[r4]
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov a,r4
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+add a,r2
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r2,a
+\layout Standard
+
+
+\size footnotesize
+; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov b,#0x03
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov a,r4
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mul ab
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r1,a
+\layout Standard
+
+
+\size footnotesize
+; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
+\layout Standard
+
+
+\size footnotesize
+; iTemp15 [lr29:30]{short}[r1]
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
-Set break for line with point
-\newline
-;; ESC t\SpecialChar ~
+add a,r3
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r3,a
+\layout Standard
+
+
+\size footnotesize
+; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov a,r7
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+add a,#0xfd
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r7,a
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
- sdcdbsrc-mode\SpecialChar ~
\SpecialChar ~
+mov a,r0
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+addc a,#0xff
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov r0,a
+\layout Standard
+
+
+\size footnotesize
+; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov a,r7
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+add a,_gint
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov _gint,a
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov a,r0
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
-Toggle Sdcdbsrc mode
-\newline
-;; ESC m\SpecialChar ~
+addc a,(_gint + 1)
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov (_gint + 1),a
+\layout Standard
+
+
+\size footnotesize
+; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+inc r4
+\layout Standard
+
+
+\size footnotesize
+; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+dec r5
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+cjne r5,#0xff,00104$
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
- sdcdbsrc-srcmode\SpecialChar ~
\SpecialChar ~
+dec r6
+\layout Standard
+
+
+\size footnotesize
+; goto _forcond_0($4)
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+sjmp 00104$
+\layout Standard
+
+
+\size footnotesize
+; _forbreak_0($7) :
+\layout Standard
+
+
+\size footnotesize
+00107$:
+\layout Standard
+
+
+\size footnotesize
+; ret iTemp24 [lr40:41]{short}
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov a,r3
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+add a,r2
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
+mov dpl,a
+\layout Standard
+
+
+\size footnotesize
+; _return($8) :
+\layout Standard
+
+
+\size footnotesize
+00108$:
+\layout Standard
+
+
+\size footnotesize
\SpecialChar ~
\SpecialChar ~
- Toggle list mode
+ret
\newline
-;;
-\family default
+\layout Subsection
+
+A few words about basic block successors, predecessors and dominators
+\layout Standard
+
+Successors are basic blocks that might execute after this basic block.
+\newline
+Predecessors are basic blocks that might execute before reaching this basic
+ block.
+\newline
+Dominators are basic blocks that WILL execute before reaching this basic
+ block.
\newline
-\layout Section
+\layout Standard
-Other Processors
-\layout Subsection
+[basic block 1]
+\layout Standard
-The Z80 and gbz80 port
+if (something)
\layout Standard
-SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
- The port is incomplete - long support is incomplete (mul, div and mod are
- unimplimented), and both float and bitfield support is missing.
- Apart from that the code generated is correct.
+[basic block 2]
\layout Standard
-As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
- The stack frame is similar to that generated by the IAR Z80 compiler.
- IX is used as the base pointer, HL is used as a temporary register, and
- BC and DE are available for holding varibles.
- IY is currently unusued.
- Return values are stored in HL.
- One bad side effect of using IX as the base pointer is that a functions
- stack frame is limited to 127 bytes - this will be fixed in a later version.
-\layout Section
+else
+\layout Standard
-Support
+[basic block 3]
\layout Standard
-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).
- 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
- end users.
- Is SDCC perfect? No, that's why we need your help.
- The developers take pride in fixing reported bugs.
- You can help by reporting the bugs and helping other SDCC users.
- There are lots of ways to contribute, and we encourage you to take part
- in making SDCC a great software package.
-\layout Subsection
+[basic block 4]
+\newline
-Reporting Bugs
\layout Standard
-Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd
-cc@sdcc.sourceforge.net'.
- Bugs will be fixed ASAP.
- When reporting a bug, it is very useful to include a small test program
- which reproduces the problem.
- If you can isolate the problem by looking at the generated assembly code,
- this can be very helpful.
- Compiling your program with the --dumpall option can sometimes be useful
- in locating optimization problems.
+a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
+\layout Standard
+
+b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
+\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
Acknowledgments
\layout Standard
-Sandeep Dutta (sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code generator,
- Debugger, AVR port
-\newline
-Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX & ASLINK.
-
-\newline
-John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for 8051
-\newline
-Dmitry S.
- Obukhov (dso@usa.net) - malloc & serial i/o routines.
-
-\newline
-Daniel Drotos (drdani@mazsola.iit.uni-miskolc.hu) - for his Freeware simulator
-\newline
-Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience and support.
-\newline
-Unknown - for the GNU C - preprocessor.
-\newline
-Michael Hope - The Z80 and Z80GB port, 186 development
-\newline
-Kevin Vigor - The DS390 port.
-\newline
-Johan Knol - Lots of fixes and enhancements, DS390/TINI libs.
-\newline
-Scott Datallo - The PIC port.
+
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
+
+\end_inset
+
+
\newline
\newline
projects / fw / sdcc / blobdiff