doc/cdbfile.html: removed, replaced by cdbfileformat.lyx

[fw/sdcc] / doc / sdccman.lyx

diff --git a/doc/sdccman.lyx b/doc/sdccman.lyx
index 24700fe32e046979f108888f6c918f8fa0fb6403..895701693d4d5fbe47f98d670c439a964b1e9913 100644 (file)
--- a/doc/sdccman.lyx
+++ b/doc/sdccman.lyx
@@ -226,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
 
  (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 Itemize
 
 char type parameters to vararg functions are casted to int unless explicitly


@@ -333,7 +333,7 @@ Installation
 Install and search paths
 \layout Standard
 
 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.
  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.


@@ -482,7 +482,7 @@ So, for windoze it is highly recommended to set the environment variable
 rd paths.
 \layout Subsection
 
 rd paths.
 \layout Subsection
 

-Linux and other gcc-based systems (cygwin, mingw, osx)
+Linux and other gcc-based systems (cygwin, mingw32, osx)

 \layout Enumerate
 
 
 \layout Enumerate
 
 


@@ -583,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.
 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 
 \backslash 
 usr
 \backslash 


@@ -616,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
 
  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 
 \layout Standard
 
 Follow the instruction in 


@@ -1713,16 +1714,6 @@ Linker Options
 \labelwidthstring 00.00.0000
 
 
 \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
 \series bold 
 -L\SpecialChar ~
 ---lib-path


@@ -1995,12 +1986,20 @@ Will not do loop reversal optimization.
 \layout List
 \labelwidthstring 00.00.0000
 
 \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 
 
 \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
 \layout Subsubsection
 
 Other Options


@@ -2017,6 +2016,15 @@ Other Options
 \labelwidthstring 00.00.0000
 
 
 \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 
 \series bold 
 -E
 \series default 


@@ -2027,6 +2035,19 @@ Other Options
 \labelwidthstring 00.00.0000
 
 
 \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 
 \series bold 
 ---stack-auto
 \series default 


@@ -2286,6 +2307,24 @@ cyclomatic complexity
 -V
 \series default 
  Shows the actual commands the compiler is executing.
 -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
 \layout Subsubsection
 
 Intermediate Dump Options


@@ -2408,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
 
 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
 
 MCS51/DS390 Storage Class Language Extensions
 \layout Standard
 


@@ -2892,9 +3041,9 @@ Interrupt Numbers and the corresponding address & descriptions for the Standard
 \begin_inset  Tabular
 <lyxtabular version="3" rows="6" columns="3">
 <features>
 \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
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text


@@ -3755,7 +3904,7 @@ The same goes the other way, ie.
  labels defines in inline assembly CANNOT be accessed by C statements.
 \layout Subsection
 
  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 Standard
 
 For signed & unsigned int (16 bit) and long (32 bit) variables, division,


@@ -6192,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 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
 \layout Itemize
 
 Use unsigned when it is known in advance that the value is not going to


@@ -6207,8 +6356,8 @@ Declare the variables to be local whenever possible, especially loop control
  variables (induction).
 \layout Itemize
 
  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
 \layout Itemize
 
 Reducing the size of division, multiplication & modulus operations can reduce


@@ -7542,6 +7691,9 @@ cc@sdcc.sourceforge.net'.
  in locating optimization problems.
 \layout Section
 
  in locating optimization problems.
 \layout Section
 

+Compiler internals
+\layout Subsection
+

 The anatomy of the compiler
 \layout Standard
 
 The anatomy of the compiler
 \layout Standard
 


@@ -7909,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
 
 \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
 
 
 \layout Standard
 
 


@@ -7976,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]
 
 \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
 
 
 \layout Standard
 
 


@@ -7993,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]
 
 \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
 
 
 \layout Standard
 
 


@@ -8038,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]
 
 \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 
 \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 
 \layout Standard
 
 
 \size footnotesize 

-sample.c(20:42:51:0)_return($8) :
+Sample.c(20:42:51:0)_return($8) :

 \layout Standard
 
 
 \size footnotesize 
 \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 
 \size default 
 
 \newline 


@@ -8814,10 +8946,53 @@ mov dpl,a
 \SpecialChar ~
 \SpecialChar ~
 ret
 \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 
 \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
 \layout Section
 
 Acknowledgments