\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
\newline
-SDCC also provides an option (---cyclomatic) to report the relative complexity
+SDCC also provides an option (--cyclomatic) to report the relative complexity
of a function.
These functions can then be further optimized, or hand coded in assembly
if needed.
\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
\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
Install and search paths
\layout Standard
-Linux (and other gcc-builds like Solaris, Cygwin, Mingw and OSX) by default
+Linux (and other gcc-builds like Solaris, Cygwin, Mingw32 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.
\begin_inset Quotes sld
\end_inset
-SDCCHOME)/include
+SDCCHOME
+\begin_inset Quotes srd
+\end_inset
+
+)/include
\newline
- /usr/local/share/sdcc/include (gcc builds)
\newline
-- path(arv[0])/../include and then /sdcc/include (windoze msvc and borland
- builds)
+- path(arv[0])/../include and then /sdcc/include (as a last resort for windoze
+ msvc and borland builds)
\layout Enumerate
Library files (the
\shape italic
model
\shape default
- (windoze msvc and borland builds)
+ (as a last resort for windoze msvc and borland builds)
\layout Enumerate
Documentation (although never really searched for, you have to do that yourself
\layout Standard
So, for windoze it is highly recommended to set the environment variable
- SDCCHOME to prevent needless usage of -I and -L.
+ SDCCHOME to prevent needless usage of -I and -L options.
+ For gcc-builds SDCCHOME should only be set when sdcc is installed in non-standa
+rd paths.
\layout Subsection
-Linux and other gcc-based systems (cygwin, mingw, osx)
+Linux and other gcc-based systems (cygwin, mingw32, osx)
\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 mingw package is: c:
+ An example directory structure after unpacking the mingw32 package is:
+ c:
\backslash
usr
\backslash
directory or start sdcc using the full path.
\layout Subsubsection
-Windows Install Using Cygwin and Mingw
+Windows Install Using Cygwin and Mingw32
\layout Standard
Follow the instruction in
bin, and you can compile using sdcc.
\layout Subsubsection
-Windows Install Using Borland ......
-\layout Standard
+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
-\shape italic
-<pending>
+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
+
+\family sans
+\series bold
+find .
+
+\backslash
+( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
+\backslash
+) -print -exec rm {}
+\backslash
+;
+\family default
+\series default
+
+\newline
+
+\newline
+or on Windows NT/2000/XP from the command prompt with the commmand:
+\newline
+
+\family sans
+\series bold
+
+\newline
+del /s *.obj *.lib *.rul
+\family default
+\series default
+ from the sdcc directory.
\layout Subsection
Testing out the SDCC Compiler
\newline
\series medium
-SDCC binaries are commonly installed in a directory arrangement like this:
-\series default
-
-\newline
-
-\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">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-/
-\series medium
-usr/local/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 executables(sdcc, s51, aslink,
-\series default
-...
-\series medium
-)
-\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
-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 medium
-Holds common C
+SDCC
\series default
-libraries
-\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 medium
-usr/local/share/sdcc/include
-\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
+is commonly installed as described in section
+\begin_inset Quotes sld
\end_inset
-</cell>
-</row>
-</lyxtabular>
+Install and search paths
+\begin_inset Quotes srd
\end_inset
\series medium
Make sure the compiler works on a very simple example.
- Type in the following test.c program using your favorite editor:
+ Type in the following test.c program using your favorite
+\series default
+ascii
+\series medium
+editor:
\series default
\newline
\newline
-\family typewriter
+\family sans
+\series bold
./configure 2>&1 | tee configure.log
\family default
+\series default
\newline
\newline
-\family typewriter
+\family sans
+\series bold
make 2>&1 | tee make.log
\family default
+\series default
\newline
command does.
\layout Standard
-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
-
-Advanced Install Options
-\layout Standard
-
-The
-\begin_inset Quotes eld
-\end_inset
-
-configure
-\begin_inset Quotes erd
-\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
-
-\newline
-The command
-\family sans
-\series bold
-
+This will install the compiler, other executables libraries and include
+ files in to the appropriate directories.
+ See section
\begin_inset Quotes sld
\end_inset
-./configure ---prefix=/usr/local
-\begin_inset Quotes erd
+Install and Search PATHS
+\begin_inset Quotes srd
\end_inset
-
-\family default
-\series default
-will configure the compiler to be installed in directory /usr/local.
+.
+\newline
+On most systems you will need super-user privilages to do this.
\layout Subsection
Components of SDCC
\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:
+ At the time of this writing, we find the following programs for gcc-builds:
\newline
\newline
In <installdir>/share/sdcc/lib
\layout Itemize
-the sources of the runtime library and the subdirs small large and ds390
- with the precompiled relocatables.
+the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
+ relocatables.
\layout Standard
In <installdir>/share/sdcc/doc
\family typewriter
\shape italic
-<todo: is this thing alive?>
+<todo: is this thing still alive?>
\newline
\newline
\newline
sourcefile.cdb - An optional file (with ---debug) containing debug information
\newline
+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
\labelwidthstring 00.00.0000
-\series bold
--o\SpecialChar ~
-<path/file>
-\series default
-the output path resp.
- file where everything will be placed
-\layout List
-\labelwidthstring 00.00.0000
-
-
\series bold
-L\SpecialChar ~
---lib-path
\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
- This will disable the memcpy of initialized data in far space from code
- space
+ 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
Other Options
\labelwidthstring 00.00.0000
+\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
\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.
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
\series bold
---stack-auto
\series default
-V
\series default
Shows the actual commands the compiler is executing.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\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
+
+
+\series bold
+---i-code-in-asm
+\series default
+ Include i-codes in the asm file.
+ Looks like noise but is most helpfull for debugging the compiler itself.
\layout Subsubsection
Intermediate Dump Options
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
+(coming\SpecialChar ~
+soon:\SpecialChar ~
+SDCC_BIN_PATH)
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.1 Install and search paths
+\begin_inset Quotes srd
+\end_inset
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+(coming\SpecialChar ~
+soon:\SpecialChar ~
+SDCC_INCLUDE_PATH)
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.1 Install and search paths
+\begin_inset Quotes srd
+\end_inset
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+(coming\SpecialChar ~
+soon:\SpecialChar ~
+SDCC_LIB_PATH)
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.1 Install and search paths
+\begin_inset Quotes srd
+\end_inset
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+SDCCDIR\SpecialChar ~
+(soon\SpecialChar ~
+replaced\SpecialChar ~
+by:\SpecialChar ~
+SDCCPATH)
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.1 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
\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)">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
labels defines in inline assembly CANNOT be accessed by C statements.
\layout Subsection
-int(16 bit) and long (32 bit) Support
+int (16 bit) and long (32 bit) Support
\layout Standard
For signed & unsigned int (16 bit) and long (32 bit) variables, division,
\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).
+ 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
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'.
+ 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
variables (induction).
\layout Itemize
-Since the compiler does not do implicit integral promotion, the programmer
- should do an explicit cast when integral promotion is required.
+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
in locating optimization problems.
\layout Section
+Compiler internals
+\layout Subsection
+
The anatomy of the compiler
\layout Standard
\size footnotesize
Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
- * int}[r0] +
-\layout Standard
-
-
-\size footnotesize
-0x2 {short}
+ * int}[r0] + 0x2 {short}
\layout Standard
\size footnotesize
Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
- +
-\layout Standard
-
-
-\size footnotesize
-ITemp21 [lr21:38]{short}[r4]
+ + ITemp21 [lr21:38]{short}[r4]
\layout Standard
\size footnotesize
Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
- +
-\layout Standard
-
-
-\size footnotesize
-iTemp15 [lr29:30]{short}[r1]
+ + iTemp15 [lr29:30]{short}[r1]
\layout Standard
\size footnotesize
Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
- +
-\layout Standard
-
-
-\size footnotesize
-ITemp11 [lr19:40]{short}[r3]
+ + ITemp11 [lr19:40]{short}[r3]
\layout Standard
\size footnotesize
-sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
+Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
\layout Standard
\size footnotesize
-sample.c(20:42:51:0)_return($8) :
+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}
+Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
\size default
\newline
\SpecialChar ~
\SpecialChar ~
ret
-\size default
+\newline
+
+\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 Standard
+
+[basic block 1]
+\layout Standard
+
+if (something)
+\layout Standard
+
+[basic block 2]
+\layout Standard
+
+else
+\layout Standard
+
+[basic block 3]
+\layout Standard
+
+[basic block 4]
+\newline
+
+\layout Standard
+
+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