X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fsdccman.lyx;h=895701693d4d5fbe47f98d670c439a964b1e9913;hb=af4543dc2f303b737749b72a2441efa0686288e4;hp=45a0ff2c6df8776a547868e2addea4a58365e2c8;hpb=09378dae3d3c28be594d132f910029bc387cbc2a;p=fw%2Fsdcc diff --git a/doc/sdccman.lyx b/doc/sdccman.lyx index 45a0ff2c..89570169 100644 --- a/doc/sdccman.lyx +++ b/doc/sdccman.lyx @@ -24,6 +24,11 @@ \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 @@ -128,7 +133,7 @@ inline assembler code \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. @@ -143,7 +148,7 @@ SDCC also comes with a companion source level debugger SDCDB, the debugger \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 @@ -221,8 +226,8 @@ short is now equivalent to int (16 bits), it used to be equivalent to char (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 @@ -275,7 +280,7 @@ Other Resources \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 @@ -328,7 +333,7 @@ Installation 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. @@ -387,12 +392,16 @@ SDCC_INCLUDE_PATH \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 @@ -446,7 +455,7 @@ model \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 @@ -468,10 +477,12 @@ SDCCHOME \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 @@ -572,7 +583,8 @@ Windows Install Using a Binary Package 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 @@ -605,7 +617,7 @@ Adjust your environment variable PATH to include the location of the bin 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 @@ -788,12 +800,49 @@ bin_vc to sdcc 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 - +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 @@ -820,92 +869,14 @@ The first thing you should do after installing your SDCC compiler is to \newline \series medium -SDCC binaries are commonly installed in a directory arrangement like this: -\series default - -\newline - -\newline - -\begin_inset Tabular - - - - - - -\begin_inset Text - -\layout Standard - -/ -\series medium -usr/local/bin -\end_inset - - -\begin_inset Text - -\layout Standard - - -\series medium -Holds executables(sdcc, s51, aslink, -\series default -... -\series medium -) -\end_inset - - - - -\begin_inset Text - -\layout Standard - -/ -\series medium -usr/local/share/sdcc/lib -\end_inset - - -\begin_inset Text - -\layout Standard - - -\series medium -Holds common C +SDCC \series default -libraries -\end_inset - - - - -\begin_inset Text - -\layout Standard - -/ -\series medium -usr/local/share/sdcc/include -\end_inset - - -\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 - - - +Install and search paths +\begin_inset Quotes srd \end_inset @@ -915,7 +886,11 @@ Holds common C header files \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 @@ -1063,9 +1038,11 @@ A thing to try is starting from scratch by unpacking the .tgz source package \newline -\family typewriter +\family sans +\series bold ./configure 2>&1 | tee configure.log \family default +\series default \newline @@ -1075,9 +1052,11 @@ and build it like: \newline -\family typewriter +\family sans +\series bold make 2>&1 | tee make.log \family default +\series default \newline @@ -1138,67 +1117,19 @@ make install 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=, where 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 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 @@ -1215,7 +1146,7 @@ SDCC is not just a compiler, but a collection of tools by various developers. \newline You might want to look at the files which are installed in . - 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 @@ -1266,8 +1197,8 @@ the include files In /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 /share/sdcc/doc @@ -1331,7 +1262,7 @@ sdcdb - Source Level Debugger \family typewriter \shape italic - + \newline \newline @@ -1383,7 +1314,16 @@ sourcefile.ihx - The load module in Intel hex format (you can select the \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 @@ -1774,16 +1714,6 @@ Linker Options \labelwidthstring 00.00.0000 -\series bold --o\SpecialChar ~ - -\series default -the output path resp. - file where everything will be placed -\layout List -\labelwidthstring 00.00.0000 - - \series bold -L\SpecialChar ~ ---lib-path @@ -2056,12 +1986,20 @@ 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 - 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 @@ -2078,6 +2016,15 @@ 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 @@ -2088,6 +2035,19 @@ Other Options \labelwidthstring 00.00.0000 +\series bold +-o\SpecialChar ~ + +\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 @@ -2347,6 +2307,24 @@ cyclomatic complexity -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 @@ -2469,6 +2447,116 @@ Will create a dump of iCode's, after register assignment, into a file named 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 @@ -2953,9 +3041,9 @@ Interrupt Numbers and the corresponding address & descriptions for the Standard \begin_inset Tabular - - - + + + \begin_inset Text @@ -3816,7 +3904,7 @@ The same goes the other way, ie. 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, @@ -5571,10 +5659,11 @@ 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). + 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 @@ -6252,7 +6341,7 @@ Here are a few guidelines that will help the compiler generate more efficient 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 @@ -6267,8 +6356,8 @@ Declare the variables to be local whenever possible, especially loop control 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 @@ -7602,6 +7691,9 @@ cc@sdcc.sourceforge.net'. in locating optimization problems. \layout Section +Compiler internals +\layout Subsection + The anatomy of the compiler \layout Standard @@ -7969,12 +8061,7 @@ Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{in \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 @@ -8036,12 +8123,7 @@ Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7) \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 @@ -8053,12 +8135,7 @@ Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] \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 @@ -8098,27 +8175,22 @@ Sample.c(19:39:48:0)_forbreak_0($7) : \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 @@ -8874,10 +8946,53 @@ mov dpl,a \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