\newline
\family default
-If you can think of some more, please see the chapter 9 about filing feature
- requests
+If you can think of some more, please see the chapter
+\begin_inset LatexCommand \ref{sub:Requesting-Features}
+
+\end_inset
+
+ about filing feature requests
\begin_inset LatexCommand \index{Requesting features}
\end_inset
\layout Section
\pagebreak_top
-Installation
+Installing SDCC
\begin_inset LatexCommand \index{Installation}
\end_inset
\layout Standard
..
-\backslash
\end_inset
</cell>
\begin_inset Tabular
<lyxtabular version="3" rows="5" columns="4">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\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="block" valignment="top" leftline="true" rightline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<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
+
+\size small
$SDCC_INCLUDE
\end_inset
</cell>
\layout Standard
-$SDCC_HOME/
-\newline
+\size footnotesize
+$SDCC_HOME/
\emph on
-$PREFIX2DATA_DIR/
-\newline
-$INCLUDE_DIR_SUFFIX
+$PREFIX2DATA_DIR/$INCLUDE_DIR_SUFFIX
\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-$SDCC_ HOME/
-\newline
-share/sdcc/
-\newline
-include
+
+\size small
+$SDCC_ HOME/share/sdcc/include
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
+
+\size small
$SDCC_HOME
\backslash
include
\layout Standard
-path(argv[0])/
-\newline
-
-\emph on
-$BIN2DATADIR/
-\emph default
-
-\newline
+\size small
+path(argv[0])/
\emph on
-$INCLUDE_DIR_SUFFIX
+$BIN2DATADIR/$INCLUDE_DIR_SUFFIX
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-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 ~
-
+path(argv[0])/../sdcc/include
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
+\size small
\emph on
-$DATADIR/
-\emph default
-
-\newline
-
-\emph on
-$INCLUDE_DIR_SUFFIX
+$DATADIR/$INCLUDE_DIR_SUFFIX
\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-/usr/local/share/sdcc/
-\newline
-include
+/usr/local/share/sdcc/include
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Enumerate
-Download the binary package and unpack it using your favorite unpacking
- tool (gunzip, WinZip, etc).
+Download the binary package from
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
+
+\end_inset
+
+ and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
This should unpack to a group of sub-directories.
An example directory structure after unpacking the mingw32 package is:
c:
\series default
- Generate code for the MCS51
+ Generate code for the Intel MCS51
\begin_inset LatexCommand \index{MCS51}
\end_inset
Causes the linker to check if the external ram usage is within limits of
the given value.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-code-size
+\series default
+<Value>
+\begin_inset LatexCommand \index{-\/-data-loc}
+
+\end_inset
+
+ Causes the linker to check if the code memory usage is within limits of
+ the given value.
\layout Subsubsection
DS390 Options
\end_inset
-.See section Installation for more details.
+.
+ See section Installation for more details.
\layout List
\labelwidthstring 00.00.0000
function.
The default option is to lock up i.e.
- generate a 'ljmp '.
+ generate a '
+\family typewriter
+ljmp .
+\family default
+'.
\layout List
\labelwidthstring 00.00.0000
\labelwidthstring 00.00.0000
-\series bold
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--code-size
-\series default
-<Value>
-\begin_inset LatexCommand \index{-\/-code-size<Value>}
-
-\end_inset
-
- Causes the linker to check if the code usage is within limits of the given
- value.
-\layout List
-\labelwidthstring 00.00.0000
-
-
\series bold
-
\begin_inset ERT
\series default
Display errors and warnings using MSVC style, so you can use SDCC with
- visual studio
+ visual studio.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--use-stderr
+-use-stdout
\begin_inset LatexCommand \index{-\/-use-stdout}
\end_inset
\series default
- Send errors and warnings to stdout instead of stderr
+ Send errors and warnings to stdout instead of stderr.
\layout Subsubsection
Intermediate Dump Options
\size default
\bar default
Will cause all the above mentioned dumps to be created.
+\layout Subsubsection
+
+Redirecting output on Windows Shells
+\layout Standard
+
+By default SDCC writes it's error messages to
+\begin_inset Quotes sld
+\end_inset
+
+standard error
+\begin_inset Quotes srd
+\end_inset
+
+.
+ To force all messages to
+\begin_inset Quotes sld
+\end_inset
+
+standard output
+\begin_inset Quotes srd
+\end_inset
+
+ use
+\series bold
+-
+\series default
+\emph on
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+
+\series bold
+\emph default
+-
+\series default
+use-stdout
+\begin_inset LatexCommand \index{-\/-use-stdout}
+
+\end_inset
+
+.
+ Aditionaly, if you happen to have visual studio installed in your windows
+ machine, you can use it to compile your sources using a custom build and
+ the SDCC -
+\emph on
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+
+\emph default
+-vc
+\begin_inset LatexCommand \index{-\/-vc}
+
+\end_inset
+
+ option.
+ Something like this should work:
+\newline
+
+\newline
+
+\series bold
+c:
+\backslash
+sdcc
+\backslash
+bin
+\backslash
+sdcc.exe -
+\series default
+\emph on
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+
+\series bold
+\emph default
+-vc -
+\series default
+\emph on
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+
+\series bold
+\emph default
+-model-large -c $(InputPath)
\layout Subsection
Environment variables
\end_inset
) */
-\layout Subsection
+\layout Subsubsection
Pointers
\begin_inset LatexCommand \index{Pointers}
\end_inset
-
+ to MCS51/DS390 specific memory spaces
\layout Standard
SDCC allows (via language extensions) pointers to explicitly point to any
\family typewriter
-/* pointer physically in xternal ram pointing to object in internal ram
+/* pointer physically in internal ram pointing to object in external ram
*/
\newline
-data unsigned char * xdata p;
+xdata unsigned char * data p;
+\newline
+
+\newline
+/* pointer physically in external ram pointing to object in internal ram
+ */
+\newline
+data unsigned char * xdata p;
\newline
\newline
code.
\layout Subsection
-Parameters
-\begin_inset LatexCommand \index{Parameters}
-
-\end_inset
-
- & Local Variables
-\begin_inset LatexCommand \index{Local variable}
+Absolute Addressing
+\begin_inset LatexCommand \index{Absolute addressing}
\end_inset
\layout Standard
-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
+Data items can be assigned an absolute address with the
\emph on
-static
-\begin_inset LatexCommand \index{static}
+at
+\begin_inset LatexCommand \index{at}
\end_inset
-
+ <address>
\emph default
- so by default functions are non-reentrant
-\begin_inset LatexCommand \index{reentrant}
-
-\end_inset
+ keyword, in addition to a storage class, e.g.:
+\layout Verse
-.
-\newline
-\newline
-They can be placed on the stack
-\begin_inset LatexCommand \index{stack}
+\family typewriter
+xdata
+\begin_inset LatexCommand \index{xdata}
\end_inset
- either by using the
-\emph on
- -
-\begin_inset ERT
-status Collapsed
+ at
+\begin_inset LatexCommand \index{at}
+\end_inset
+
+ 0x7ffe unsigned int chksum;
\layout Standard
-\backslash
-/
+In the above example the variable chksum will located at 0x7ffe and 0x7fff
+ of the external ram.
+ The compiler does not actually reserve any space for variables declared
+ in this way (they are implemented with an equate in the assembler).
+ Thus it is left to the programmer to make sure there are no overlaps with
+ other variables that are declared without the absolute address.
+ The assembler listing file (.lst
+\begin_inset LatexCommand \index{.lst}
+
\end_inset
--stack-auto
-\begin_inset LatexCommand \index{-\/-stack-auto}
+) and the linker output files (.rst
+\begin_inset LatexCommand \index{.rst}
\end_inset
-
-\emph default
- option or by using the
-\emph on
-reentrant
-\begin_inset LatexCommand \index{reentrant}
+) and (.map
+\begin_inset LatexCommand \index{.map}
\end_inset
+) are good places to look for such overlaps.
+\layout Standard
+In case of memory mapped I/O devices the keyword
+\emph on
+volatile
\emph default
- keyword in the function declaration, e.g.:
+ should be used to tell the compiler that accesses might not be optimized
+ away:
\layout Verse
\family typewriter
-unsigned char foo(char i) reentrant
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-...
-
-\newline
-}
-\layout Standard
+volatile
+\begin_inset LatexCommand \index{volatile}
-Since stack space on 8051 is limited, the
-\emph on
-reentrant
-\emph default
-keyword or the
-\emph on
- -
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
+ xdata
+\begin_inset LatexCommand \index{xdata}
-\backslash
-/
\end_inset
--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
+ at
+\begin_inset LatexCommand \index{at}
-\newline
-Local variables can be assigned storage classes and absolute
-\begin_inset LatexCommand \index{Absolute addressing}
+\end_inset
+
+ 0x8000 unsigned char PORTA_8255;
+\layout Standard
+
+Absolute address can be specified for variables in all storage classes,
+ e.g.:
+\layout Verse
+
+
+\family typewriter
+bit
+\begin_inset LatexCommand \index{bit}
\end_inset
- addresses, e.g.:
+ at
+\begin_inset LatexCommand \index{at}
+
+\end_inset
+
+ 0x02 bvar;
+\layout Standard
+
+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.
+ One possible use would be to write hardware portable code.
+ For example, if you have a routine that uses one or more of the microcontroller
+ I/O pins, and such pins are different for two different hardwares, you
+ can declare the I/O pins in your routine using:
\layout Verse
\family typewriter
-unsigned char foo()
+extern volatile bit SDI;
+\newline
+extern volatile bit SCLK;
+\newline
+extern volatile bit CPOL;
+\newline
+
+\newline
+void DS1306_put(unsigned char value)
\newline
{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-xdata unsigned char i;
+unsigned char mask=0x80;
+\newline
+
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-bit bvar;
+while(mask)
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-data at 0x31 unsigned char j;
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDI=(value & mask)?1:0;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SCLK=!CPOL;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SCLK=CPOL;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mask/=2;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+}
\newline
}
\layout Standard
-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
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--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
+Then, someplace in the code for the first hardware you would use
+\layout Verse
-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
-\begin_inset LatexCommand \label{sub:Overlaying}
+\family typewriter
+bit at 0x80 SDI;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* I/O port 0, bit 0 */
+\newline
+bit at 0x81 SCLK;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* I/O port 0, bit 1 */
+\newline
+bit CPOL;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* This is a variable, let the linker allocate this one */
+\layout Standard
-\end_inset
+Similarly, for the second hardware you would use
+\layout Verse
-\begin_inset LatexCommand \index{Overlaying}
+\family typewriter
+bit at 0x83 SDI;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* I/O port 0, bit 3 */
+\newline
+bit at 0x91 SCLK;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* I/O port 1, bit 1 */
+\newline
+bit CPOL;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* This is a variable, let the linker allocate this one */
+\layout Standard
-\end_inset
+and you can use the same hardware dependent routine without changes, as
+ for example in a library.
+ This is somehow similar to sbit, but only one absolute address has to be
+ specified in the whole project.
+\layout Subsection
+Parameters
+\begin_inset LatexCommand \index{Parameters}
-\layout Standard
+\end_inset
-For non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+ & Local Variables
+\begin_inset LatexCommand \index{Local variable}
\end_inset
- 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
+
+\layout Standard
+
+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
-no other function calls and the function is non-reentrant and the memory
- model
-\begin_inset LatexCommand \index{Memory model}
+static
+\begin_inset LatexCommand \index{static}
\end_inset
- is small.
\emph default
- If an explicit storage class
-\begin_inset LatexCommand \index{Storage class}
+ so by default functions are non-reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
- is specified for a local variable, it will NOT be overlayed.
-\layout Standard
+.
+\newline
-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
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+\newline
+They can be placed on the stack
+\begin_inset LatexCommand \index{stack}
\end_inset
- if they are not reentrant.
-\layout Standard
+ either by using the
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
-Also note that the compiler does not do any processing of inline
-\begin_inset LatexCommand \index{inline}
+\layout Standard
+\backslash
+/
\end_inset
- assembler code, so the compiler might incorrectly assign local variables
- and parameters of a function into the overlay segment if the inline assembler
- code calls other c-functions that might use the overlay.
- In that case the #pragma\SpecialChar ~
-NOOVERLAY should be used.
-\layout Standard
-
-Parameters and Local variables of functions that contain 16 or 32 bit multiplica
-tion
-\begin_inset LatexCommand \index{Multiplication}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
- or division
-\begin_inset LatexCommand \index{Division}
+
+\emph default
+ option or by using the
+\emph on
+reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
- will NOT be overlayed since these are implemented using external functions,
- e.g.:
+
+\emph default
+ keyword in the function declaration, e.g.:
\layout Verse
\family typewriter
-#pragma SAVE
-\newline
-#pragma NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
-
-\end_inset
-
-
-\newline
-void set_error(unsigned char errcd)
+unsigned char foo(char i) reentrant
\newline
-{
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-P3 = errcd;
-\newline
-}
+...
+
\newline
-#pragma RESTORE
+}
+\layout Standard
+
+Since stack space on 8051 is limited, the
+\emph on
+reentrant
+\emph default
+keyword or the
+\emph on
+ -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-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
-void some_isr () interrupt
-\begin_inset LatexCommand \index{interrupt}
+Local variables can be assigned storage classes and absolute
+\begin_inset LatexCommand \index{Absolute addressing}
\end_inset
- 2
+ addresses, e.g.:
+\layout Verse
+
+
+\family typewriter
+unsigned char foo()
\newline
{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
+xdata unsigned char i;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-set_error(10);
+bit bvar;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
-\newline
-}
-\layout Standard
-
-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.
-\layout Verse
-
-
-\family typewriter
-void timer_isr (void) interrupt 1 using 1
-\newline
-{
+data at 0x31 unsigned char j;
\newline
\SpecialChar ~
\SpecialChar ~
}
\layout Standard
-The optional number following the
+In the above example the variable
\emph on
-interrupt
-\begin_inset LatexCommand \index{interrupt}
-
-\end_inset
-
-
+i
\emph default
- keyword is the interrupt number this routine will service.
- When present, the compiler will insert a call to this routine in the interrupt
- vector table for the interrupt number specified.
- The
+ will be allocated in the external ram,
\emph on
-using
+bvar
\emph default
- keyword can be used to tell the compiler to use the specified register
- bank (8051 specific) when generating code for this function.
+ in bit addressable space and
+\emph on
+ j
+\emph default
+ in internal ram.
+ When compiled with
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-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
+
+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
+\begin_inset LatexCommand \label{sub:Overlaying}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Overlaying}
+
+\end_inset
+
+
+\layout Standard
+
+For non-reentrant
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{Memory model}
+
+\end_inset
+
+ is small.
+
+\emph default
+ If an explicit storage class
+\begin_inset LatexCommand \index{Storage class}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+
+\end_inset
+
+ if they are not reentrant.
+\layout Standard
+
+Also note that the compiler does not do any processing of inline
+\begin_inset LatexCommand \index{inline}
+
+\end_inset
+
+ assembler code, so the compiler might incorrectly assign local variables
+ and parameters of a function into the overlay segment if the inline assembler
+ code calls other c-functions that might use the overlay.
+ In that case the #pragma\SpecialChar ~
+NOOVERLAY should be used.
+\layout Standard
+
+Parameters and Local variables of functions that contain 16 or 32 bit multiplica
+tion
+\begin_inset LatexCommand \index{Multiplication}
+
+\end_inset
+
+ or division
+\begin_inset LatexCommand \index{Division}
+
+\end_inset
+
+ will NOT be overlayed since these are implemented using external functions,
+ e.g.:
+\layout Verse
+
+
+\family typewriter
+#pragma SAVE
+\newline
+#pragma NOOVERLAY
+\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+
+\end_inset
+
+
+\newline
+void set_error(unsigned char errcd)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+P3 = errcd;
+\newline
+}
+\newline
+#pragma RESTORE
+\newline
+
+\newline
+void some_isr () interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ 2
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+set_error(10);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Standard
+
+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.
+\layout Verse
+
+
+\family typewriter
+void timer_isr (void) interrupt 1 using 1
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\layout Standard
+
+The optional number following the
+\emph on
+interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+
+\emph default
+ keyword is the interrupt number this routine will service.
+ When present, 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 can be used to tell the compiler to use the specified register
+ bank (8051 specific) when generating code for this function.
Note that when some function is called from an interrupt service routine
it should be preceded by a #pragma\SpecialChar ~
NOOVERLAY
<lyxtabular version="3" rows="7" 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">
+<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 Subsection
-Absolute Addressing
-\begin_inset LatexCommand \index{Absolute addressing}
+Startup Code
+\begin_inset LatexCommand \label{sub:Startup-Code}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Startup code}
\end_inset
\layout Standard
-Data items can be assigned an absolute address with the
+The compiler inserts a call to the C routine
\emph on
-at
-\begin_inset LatexCommand \index{at}
+_sdcc_external_startup()
+\begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
\end_inset
- <address>
-\emph default
- keyword, in addition to a storage class, e.g.:
-\layout Verse
-
-\family typewriter
-xdata
-\begin_inset LatexCommand \index{xdata}
+\series bold
+\emph default
+
+\series default
+at the start of the CODE area.
+ This routine is in the runtime library
+\begin_inset LatexCommand \index{Runtime library}
\end_inset
- at
-\begin_inset LatexCommand \index{at}
-
-\end_inset
+.
+ By default this routine returns 0, if this routine returns a non-zero value,
+ the static & global variable initialization will be skipped and the function
+ main will be invoked.
+ Otherwise static & global variables will be initialized before the function
+ main is invoked.
+ You could add a
+\emph on
+_sdcc_external_startup()
+\emph default
+ routine to your program to override the default if you need to setup hardware
+ or perform some other critical operation prior to static & global variable
+ initialization.
+ See also the compiler option
+\emph on
+-
+\begin_inset ERT
+status Collapsed
- 0x7ffe unsigned int chksum;
\layout Standard
-In the above example the variable chksum will located at 0x7ffe and 0x7fff
- of the external ram.
- The compiler does not actually reserve any space for variables declared
- in this way (they are implemented with an equate in the assembler).
- Thus it is left to the programmer to make sure there are no overlaps with
- other variables that are declared without the absolute address.
- The assembler listing file (.lst
-\begin_inset LatexCommand \index{.lst}
-
+\backslash
+/
\end_inset
-) and the linker output files (.rst
-\begin_inset LatexCommand \index{.rst}
+-no-xinit
+\emph default
+-
+\emph on
+opt
+\emph default
+
+\begin_inset LatexCommand \index{-\/-no-xinit-opt}
\end_inset
-) and (.map
-\begin_inset LatexCommand \index{.map}
+.
+\layout Subsection
+
+Inline Assembler Code
+\begin_inset LatexCommand \index{Assembler routines}
\end_inset
-) are good places to look for such overlaps.
+
\layout Standard
-In case of memory mapped I/O devices the keyword
+SDCC allows the use of in-line assembler with a few restriction as regards
+ labels.
+ All labels defined within inline assembler code
\emph on
-volatile
+has to be
\emph default
- should be used to tell the compiler that accesses might not be optimized
- away:
-\layout Verse
-
+ 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 -
+\begin_inset ERT
+status Collapsed
-\family typewriter
-volatile
-\begin_inset LatexCommand \index{volatile}
+\layout Standard
+\backslash
+/
\end_inset
- xdata
-\begin_inset LatexCommand \index{xdata}
+-
+\emph on
+peep-asm
+\begin_inset LatexCommand \index{-\/-peep-asm}
\end_inset
- at
-\begin_inset LatexCommand \index{at}
-\end_inset
+\emph default
+ command line option is used, the inline assembler code will be passed through
+ the peephole optimizer
+\begin_inset LatexCommand \index{Peephole optimizer}
- 0x8000 unsigned char PORTA_8255;
-\layout Standard
+\end_inset
-Absolute address can be specified for variables in all storage classes,
- e.g.:
+.
+ This might cause some unexpected changes in the inline assembler code.
+ Please go through the peephole optimizer rules defined in file
+\emph on
+SDCCpeeph.def
+\emph default
+ carefully before using this option.
\layout Verse
\family typewriter
-bit
-\begin_inset LatexCommand \index{bit}
-
-\end_inset
-
- at
-\begin_inset LatexCommand \index{at}
+_asm
+\begin_inset LatexCommand \index{\_asm}
\end_inset
- 0x02 bvar;
-\layout Standard
-
-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.
- One possible use would be to write hardware portable code.
- For example, if you have a routine that uses one or more of the microcontroller
- I/O pins, and such pins are different for two different hardwares, you
- can declare the I/O pins in your routine using:
-\layout Verse
-
-
-\family typewriter
-extern bit SDI;
-\newline
-extern bit SCLK;
-\newline
-extern bit CPOL;
-\newline
-
-\newline
-void DS1306_put(unsigned char value)
-\newline
-{
+
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char mask=0x80;
-\newline
-
-\newline
+mov\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-while(mask)
+b,#10
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-{
+00001$:
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+djnz\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-SDI=(value & mask)?1:0;
+b,00001$
+\newline
+_endasm
+\begin_inset LatexCommand \index{\_endasm}
+
+\end_inset
+
+ ;
+\layout Standard
+
+The inline assembler code can contain any valid code understood by the assembler
+, this includes any assembler directives and comment lines.
+ The compiler does not do any validation of the code within the
+\family typewriter
+_asm ...
+ _endasm;
+\family default
+ keyword pair.
+
+\newline
+
+\newline
+Inline assembler code cannot reference any C-Labels, however it can reference
+ labels
+\begin_inset LatexCommand \index{Labels}
+
+\end_inset
+
+ defined by the inline assembler, e.g.:
+\layout Verse
+
+
+\family typewriter
+foo() {
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+/* some c code */
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SCLK=!CPOL;
+_asm
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SCLK=CPOL;
+; some assembler code
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mask/=2;
+ljmp $0003
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-}
+_endasm;
\newline
-}
-\layout Standard
-
-Then, someplace in the code for the first hardware you would use
-\layout Verse
-
-
-\family typewriter
-bit at 0x80 SDI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* I/O port 0, bit 0 */
-\newline
-bit at 0x81 SCLK;\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
-/* I/O port 0, bit 1 */
+/* some more c code */
\newline
-bit CPOL;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+clabel:\SpecialChar ~
\SpecialChar ~
+/* inline assembler cannot reference this label */
+\newline
\SpecialChar ~
-/* This is a variable, let the linker allocate this one */
-\layout Standard
-
-Similarly, for the second hardware you would use
-\layout Verse
-
-
-\family typewriter
-bit at 0x83 SDI;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* I/O port 0, bit 3 */
+_asm
\newline
-bit at 0x91 SCLK;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* I/O port 1, bit 1 */
-\newline
-bit CPOL;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+$0003: ;label (can be reference by inline assembler only)
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+_endasm ;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* This is a variable, let the linker allocate this one */
+/* some more c code */
+\newline
+}
\layout Standard
-and you can use the same hardware dependent routine without changes, as
- for example in a library.
- This is somehow similar to sbit, but only one absolute address has to be
- specified in the whole project.
-\layout Subsection
+In other words inline assembly code can access labels defined in inline
+ assembly within the scope of the function.
+ The same goes the other way, ie.
+ labels defines in inline assembly CANNOT be accessed by C statements.
+\layout Standard
-Startup Code
-\begin_inset LatexCommand \index{Startup code}
+An example acessing a C variable is in section
+\begin_inset LatexCommand \ref{sub:Naked-Functions}
\end_inset
+.
+\layout Subsection
-\layout Standard
-
-The compiler inserts a call to the C routine
-\emph on
-_sdcc_external_startup()
-\begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
+Interfacing with Assembler Code
+\begin_inset LatexCommand \index{Assembler routines}
\end_inset
-\series bold
-\emph default
-
-\series default
-at the start of the CODE area.
- This routine is in the runtime library
-\begin_inset LatexCommand \index{Runtime library}
+\layout Subsubsection
+
+Global Registers used for Parameter Passing
+\begin_inset LatexCommand \index{Parameter passing}
\end_inset
-.
- By default this routine returns 0, if this routine returns a non-zero value,
- the static & global variable initialization will be skipped and the function
- main will be invoked.
- Otherwise static & global variables will be initialized before the function
- main is invoked.
- You could add a
-\emph on
-_sdcc_external_startup()
-\emph default
- routine to your program to override the default if you need to setup hardware
- or perform some other critical operation prior to static & global variable
- initialization.
- See also the compiler option
-\emph on
--
-\begin_inset ERT
-status Collapsed
\layout Standard
-\backslash
-/
-\end_inset
-
--no-xinit
-\emph default
--
+The compiler always uses the global registers
\emph on
-opt
-\emph default
-
-\begin_inset LatexCommand \index{-\/-no-xinit-opt}
+DPL, DPH
+\begin_inset LatexCommand \index{DPTR, DPH, DPL}
\end_inset
-.
-\layout Subsection
-
-Inline Assembler Code
-\begin_inset LatexCommand \index{Assembler routines}
+, B
+\begin_inset LatexCommand \index{B (register)}
\end_inset
-
-\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
+and
\emph on
-per function
+ ACC
+\begin_inset LatexCommand \index{ACC}
+
+\end_inset
+
+
\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 -
+ to pass the first parameter to a routine.
+ The second parameter onwards is either allocated on the stack (for reentrant
+ routines or if -
\begin_inset ERT
status Collapsed
/
\end_inset
--
-\emph on
-peep-asm
-\begin_inset LatexCommand \index{-\/-peep-asm}
+-stack-auto is used) or in data / xdata memory (depending on the memory
+ model).
+
+\layout Subsubsection
-\end_inset
+Assembler Routine(non-reentrant
+\begin_inset LatexCommand \index{reentrant}
+\end_inset
-\emph default
- command line option is used, the inline assembler code will be passed through
- the peephole optimizer
-\begin_inset LatexCommand \index{Peephole optimizer}
+)
+\begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
\end_inset
-.
- This might cause some unexpected changes in the inline assembler code.
- Please go through the peephole optimizer rules defined in file
-\emph on
-SDCCpeeph.def
-\emph default
- carefully before using this option.
+
+\layout Standard
+
+In the following example the function c_func calls an assembler routine
+ asm_func, which takes two parameters.
\layout Verse
\family typewriter
-_asm
-\begin_inset LatexCommand \index{\_asm}
-
-\end_inset
+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 ~
-mov\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b,#10
+return asm_func(i,j);
\newline
-00001$:
+}
+\newline
+
+\newline
+int main()
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-djnz\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-b,00001$
+return c_func(10,9);
\newline
-_endasm
-\begin_inset LatexCommand \index{\_endasm}
-
-\end_inset
-
- ;
+}
\layout Standard
-The inline assembler code can contain any valid code understood by the assembler
-, this includes any assembler directives and comment lines.
- The compiler does not do any validation of the code within the
-\family typewriter
-_asm ...
- _endasm;
-\family default
- keyword pair.
-
-\newline
-
-\newline
-Inline assembler code cannot reference any C-Labels, however it can reference
- labels
-\begin_inset LatexCommand \index{Labels}
-
-\end_inset
-
- defined by the inline assembler, e.g.:
+The corresponding assembler function is:
\layout Verse
\family typewriter
-foo() {
+.globl _asm_func_PARM_2
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* some c code */
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_asm
+.globl _asm_func
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-; some assembler code
+\SpecialChar ~
+\SpecialChar ~
+.area OSEG
+\newline
+_asm_func_PARM_2:
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ljmp $0003
+\SpecialChar ~
+\SpecialChar ~
+.ds 1
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_endasm;
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* some more c code */
+.area CSEG
\newline
-clabel:\SpecialChar ~
-\SpecialChar ~
-/* inline assembler cannot reference this label */
+_asm_func:
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_asm
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-$0003: ;label (can be reference by inline assembler only)
+mov a,dpl
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-_endasm ;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+add a,_asm_func_PARM_2
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* some more c code */
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov dpl,a
\newline
-}
-\layout Standard
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mov\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+dpl
+\begin_inset LatexCommand \index{DPTR, DPH, DPL}
-In other words inline assembly code can access labels defined in inline
- assembly within the scope of the function.
- The same goes the other way, ie.
- labels defines in inline assembly CANNOT be accessed by C statements.
+\end_inset
+
+,#0x00
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ret
\layout Standard
-An example acessing a C variable is in section
-\begin_inset LatexCommand \ref{sub:Naked-Functions}
+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 variable name for the second parameter will be _<function_n
+ame>_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
+\begin_inset LatexCommand \index{reentrant}
+
+\end_inset
+
+)
+\begin_inset LatexCommand \index{Assembler routines (reentrant)}
+
+\end_inset
+
+
+\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:
+\layout Verse
+
+
+\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
+}
+\layout Standard
+
+The corresponding assembler routine is:
+\layout Verse
+
+
+\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
+\layout Standard
+
+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
int (16 bit)
\begin_inset Tabular
<lyxtabular version="3" rows="11" columns="2">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_inset Tabular
<lyxtabular version="3" rows="17" columns="2">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
However, currently the linker can not handle code segments > 64k.
\layout Subsection
-Defines Created by the Compiler
-\begin_inset LatexCommand \index{Defines created by the compiler}
+Pragmas
+\begin_inset LatexCommand \index{Pragmas}
\end_inset
\layout Standard
-The compiler creates the following #defines
-\begin_inset LatexCommand \index{\#defines}
+SDCC supports the following #pragma directives.
+\layout Itemize
-\end_inset
+SAVE
+\begin_inset LatexCommand \index{\#pragma SAVE}
+
+\end_inset
+
+ - this will save all current options to the SAVE/RESTORE stack.
+ See RESTORE.
+\layout Itemize
+
+RESTORE
+\begin_inset LatexCommand \index{\#pragma RESTORE}
+
+\end_inset
+
+ - 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
+\begin_inset LatexCommand \index{\#pragma NOGCSE}
+
+\end_inset
+
+ - will stop global common subexpression elimination.
+\layout Itemize
+
+NOINDUCTION
+\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+
+\end_inset
+
+ - will stop loop induction optimizations.
+\layout Itemize
+
+NOJTBOUND
+\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+
+\end_inset
+
+ - will not generate code for boundary value checking, when switch statements
+ are turned into jump-tables (dangerous).
+
+\layout Itemize
+
+NOOVERLAY
+\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+
+\end_inset
+
+ - the compiler will not overlay the parameters and local variables of a
+ function.
+\layout Itemize
+
+LESS_PEDANTIC
+\begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
+
+\end_inset
+
+ - the compiler will not warn you anymore for obvious mistakes, you'r on
+ your own now ;-(
+\layout Itemize
+
+NOLOOPREVERSE
+\begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
+
+\end_inset
+
+ - Will not do loop reversal optimization
+\layout Itemize
+
+EXCLUDE
+\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+
+\end_inset
+
+ NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
+ pair of push/pop
+\begin_inset LatexCommand \index{push/pop}
+
+\end_inset
+
+ instruction in ISR function (using interrupt
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ 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
+\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+
+\end_inset
+
+.
+\layout Itemize
+
+NOIV
+\begin_inset LatexCommand \index{\#pragma NOIV}
+
+\end_inset
+
+ - 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
+\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{function prologue}
+
+\end_inset
+
+ function1[,function2[,function3...]] - The compiler by default uses a caller
+ saves convention for register saving across function calls, however this
+ can cause unnecessary 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 inter procedural analysis) may be able
+ to determine the appropriate scheme to use for each function call.
+ If -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-callee-saves command line option is used, the function names specified
+ in #pragma\SpecialChar ~
+CALLEE-SAVES
+\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+
+\end_inset
+
+ 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.
+\layout Verse
+
+
+\family typewriter
+#pragma SAVE
+\begin_inset LatexCommand \index{\#pragma SAVE}
+
+\end_inset
+
+ \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* save the current settings */
+\newline
+#pragma NOGCSE
+\begin_inset LatexCommand \index{\#pragma NOGCSE}
+
+\end_inset
+
+ \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* turnoff global subexpression elimination */
+\newline
+#pragma NOINDUCTION
+\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+
+\end_inset
+
+ /* turn off induction optimizations */
+\newline
+int foo ()
+\newline
+{
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ /* large code */
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ ...
+
+\newline
+}
+\newline
+#pragma RESTORE
+\begin_inset LatexCommand \index{\#pragma RESTORE}
+
+\end_inset
+
+ /* turn the optimizations back on */
+\layout Standard
+
+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
+
+Defines Created by the Compiler
+\begin_inset LatexCommand \index{Defines created by the compiler}
+
+\end_inset
+
+
+\layout Standard
+
+The compiler creates the following #defines
+\begin_inset LatexCommand \index{\#defines}
+
+\end_inset
:
\newline
\begin_inset Tabular
<lyxtabular version="3" rows="10" columns="2">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\newline
-\layout Subsection
-
-Redirecting output on Windows Shells
-\layout Standard
+\layout Section
+\pagebreak_top
+Debugging with SDCDB
+\begin_inset LatexCommand \index{sdcdb}
-By default SDCC writes it's error messages to
-\begin_inset Quotes sld
\end_inset
-standard error
-\begin_inset Quotes srd
+
+\layout Standard
+
+SDCC is distributed with a source level debugger
+\begin_inset LatexCommand \index{Debugger}
+
\end_inset
.
- To force all messages to
-\begin_inset Quotes sld
-\end_inset
+ The debugger uses a command line interface, the command repertoire of the
+ debugger has been kept as close to gdb
+\begin_inset LatexCommand \index{gdb}
-standard output
-\begin_inset Quotes srd
\end_inset
- use
-\series bold
--
-\series default
-\emph on
+ (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.
+ Sdcdb is available on Unix platforms only.
+\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 .adb file for each of these files.
+ The linker creates the .cdb file from the .adb files and the address information.
+ This .cdb is used by the debugger.
+\layout Subsection
+How the Debugger Works
+\layout Standard
+
+When the -
\begin_inset ERT
status Collapsed
/
\end_inset
+-debug option is specified the compiler generates extra symbol information
+ some of which are put into the the assembler source and some are put into
+ the .adb file.
+ Then the linker creates the .cdb file from the individual .adb files with
+ the address information for the symbols.
+ The debugger reads the symbolic information generated by the compiler &
+ 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
-\emph default
--
+sdcdb foo
+\newline
+
+\family default
\series default
-use-stdout
-\begin_inset LatexCommand \index{-\/-use-stdout}
-\end_inset
+\newline
+The debugger will look for the following files.
+\layout Itemize
-.
- Aditionaly, if you happen to have visual studio installed in your windows
- machine, you can use it to compile your sources using a custom build and
- the SDCC -
-\emph on
+foo.c - the source file.
+\layout Itemize
-\begin_inset ERT
-status Collapsed
+foo.cdb - the debugger symbol information file.
+\layout Itemize
-\layout Standard
+foo.ihx - the Intel hex format
+\begin_inset LatexCommand \index{Intel hex format}
-\backslash
-/
\end_inset
+ object file.
+\layout Subsection
-\emph default
--vc
-\begin_inset LatexCommand \index{-\/-vc}
-
-\end_inset
+Command Line Options.
+\layout Itemize
- option.
- Something like this should work:
-\newline
+-
+\begin_inset ERT
+status Collapsed
-\newline
+\layout Standard
-\series bold
-c:
-\backslash
-sdcc
-\backslash
-bin
\backslash
-sdcc.exe -
-\series default
-\emph on
+/
+\end_inset
+-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 -
\begin_inset ERT
status Collapsed
/
\end_inset
-
-\series bold
-\emph default
--vc -
-\series default
-\emph on
-
+-directory option should be -
\begin_inset ERT
status Collapsed
/
\end_inset
+-directory=/home/src1:/home/src2.
+ Note there can be no spaces in the option.
+
+\layout Itemize
-\series bold
-\emph default
--model-large -c $(InputPath)
-\layout Section
-\pagebreak_top
-SDCC Technical Data
-\layout Subsection
-
-Optimizations
-\begin_inset LatexCommand \index{Optimizations}
+-cd <directory> - change to the <directory>.
+\layout Itemize
-\end_inset
+-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
-\layout Standard
+-X <Clock frequency > this options is passed to the simulator please see
+ the simulator docs for details.
+\layout Itemize
-SDCC performs a host of standard optimizations in addition to some MCU specific
- optimizations.
-
-\layout Subsubsection
+-s <serial port file> passed to simulator see the simulator docs for details.
+\layout Itemize
-Sub-expression Elimination
-\begin_inset LatexCommand \index{Subexpression elimination}
+-S <serial in,out> passed to simulator see the simulator docs for details.
+\layout Subsection
-\end_inset
+Debugger Commands.
+\layout Standard
+As mentioned earlier the command interface for the debugger has been deliberatel
+y 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.
+ If you use a graphical user interface for the debugger you can skip the
+ next sections.
+\layout Subsubsection*
+break [line | file:line | function | file:function]
\layout Standard
-The compiler does local and global common subexpression elimination, e.g.:
-
-\layout Verse
+Set breakpoint at specified line or function:
+\newline
+\newline
-\family typewriter
-i = x + y + 1;
+\family sans
+\series bold
+sdcdb>break 100
\newline
-j = x + y;
+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
-will be translated to
-\layout Verse
+Clear breakpoint at specified line or function:
+\newline
+\newline
-\family typewriter
-iTemp = x + y;
+\family sans
+\series bold
+sdcdb>clear 100
\newline
-i = iTemp + 1;
+sdcdb>clear foo.c:100
\newline
-j = iTemp;
-\layout Standard
+sdcdb>clear funcfoo
+\newline
+sdcdb>clear foo.c:funcfoo
+\layout Subsubsection*
-Some subexpressions are not as obvious as the above example, e.g.:
-\layout Verse
+continue
+\layout Standard
+Continue program being debugged, after breakpoint.
+\layout Subsubsection*
-\family typewriter
-a->b[i].c = 10;
-\newline
-a->b[i].d = 11;
+finish
\layout Standard
-In this case the address arithmetic a->b[i] will be computed only once;
- the equivalent code in C would be.
-\layout Verse
-
+Execute till the end of the current function.
+\layout Subsubsection*
-\family typewriter
-iTemp = a->b[i];
-\newline
-iTemp.c = 10;
-\newline
-iTemp.d = 11;
+delete [n]
\layout Standard
-The compiler will try to keep these temporary variables in registers.
-\layout Subsubsection
+Delete breakpoint number 'n'.
+ If used without any option clear ALL user defined break points.
+\layout Subsubsection*
-Dead-Code Elimination
-\begin_inset LatexCommand \index{Dead-code elimination}
+info [break | stack | frame | registers ]
+\layout Itemize
-\end_inset
+info break - list all breakpoints
+\layout Itemize
+info stack - show the function call stack.
+\layout Itemize
-\layout Verse
+info frame - show information about the current execution frame.
+\layout Itemize
+info registers - show content of all registers.
+\layout Subsubsection*
-\family typewriter
-int global;
-\newline
-
-\newline
-void f () {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-int i;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-i = 1; \SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\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
-}
+step
\layout Standard
-will be changed to
-\layout Verse
+Step program until it reaches a different source line.
+\layout Subsubsection*
+next
+\layout Standard
-\family typewriter
-int global;
-\newline
+Step program, proceeding through subroutine calls.
+\layout Subsubsection*
-\newline
-void f () {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
-}
-\layout Subsubsection
+run
+\layout Standard
-Copy-Propagation
-\begin_inset LatexCommand \index{Copy propagation}
+Start debugged program.
+\layout Subsubsection*
-\end_inset
+ptype variable
+\layout Standard
+Print type information of the variable.
+\layout Subsubsection*
-\layout Verse
+print variable
+\layout Standard
+print value of variable.
+\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
-}
+file filename
\layout Standard
-will be changed to
-\layout Verse
-
+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 = 10;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return 10;
-\newline
-}
+frame
\layout Standard
-Note: the dead stores created by this copy propagation will be eliminated
- by dead-code elimination.
-\layout Subsubsection
-
-Loop Optimizations
-\begin_inset LatexCommand \index{Loop optimization}
+print information about current frame.
+\layout Subsubsection*
-\end_inset
+set srcmode
+\layout Standard
+Toggle between C source & assembly source.
+\layout Subsubsection*
+! simulator command
\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
-\begin_inset LatexCommand \index{Register allocation}
+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*
-\end_inset
+quit.
+\layout Standard
-, loop induction optimization causes an increase in register pressure, which
- may cause unwanted spilling of other temporary variables into the stack
-\begin_inset LatexCommand \index{stack}
+"Watch me now.
+ Iam going Down.
+ My name is Bobby Brown"
+\layout Subsection
+
+Interfacing with XEmacs
+\begin_inset LatexCommand \index{XEmacs}
\end_inset
- / 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 -
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\begin_inset LatexCommand \index{Emacs}
-\backslash
-/
\end_inset
--noinduction option) or for a given function only using #pragma\SpecialChar ~
-NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+.
+\layout Standard
-\end_inset
+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
-Loop Invariant:
-\layout Verse
+\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
-\family typewriter
-for (i = 0 ; i < 100 ; i ++)
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-f += k + l;
-\layout Standard
-changed to
-\layout Verse
+\family sans
+\series bold
+ESC-x sdcdbsrc
+\family default
+\series default
+\newline
-\family typewriter
-itemp = k + l;
\newline
-for (i = 0; i < 100; i++)
+You will prompted to enter the file name to be debugged.
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-f += itemp;
-\layout Standard
-As mentioned previously some loop invariants are not as apparent, all static
- address computations are also moved out of the loop.
\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
-\newline
-Strength Reduction
-\begin_inset LatexCommand \index{Strength reduction}
+sdcdbsrc-cpu-type '51
+\layout Itemize
-\end_inset
+sdcdbsrc-frequency '11059200
+\layout Itemize
-, this optimization substitutes an expression by a cheaper expression:
-\layout Verse
+sdcdbsrc-serial nil
+\layout Standard
+
+The following is a list of key mapping for the debugger interface.
+\layout Standard
+\SpecialChar ~
\family typewriter
-for (i=0;i < 100; i++)
+
+\newline
+;; Current Listing ::
\newline
+;;key\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ar[i*5] = i*3;
-\layout Standard
-
-changed to
-\layout Verse
-
-
-\family typewriter
-itemp1 = 0;
-\newline
-itemp2 = 0;
-\newline
-for (i=0;i< 100;i++) {
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-ar[itemp1] = itemp2;
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-itemp1 += 5;
-\newline
\SpecialChar ~
\SpecialChar ~
+binding\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-itemp2 += 3;
-\newline
-}
-\layout Standard
-
-The more expensive multiplication
-\begin_inset LatexCommand \index{Multiplication}
-
-\end_inset
-
- is changed to a less expensive addition.
-\layout Subsubsection
-
-Loop Reversing
-\begin_inset LatexCommand \index{Loop reversing}
-
-\end_inset
-
-
-\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.
-\layout Verse
-
-
-\family typewriter
-i = j + 0 ; /* changed to */ i = j;
-\newline
-i /= 2;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- /* changed to */ i >>= 1;
-\newline
-i = j - j ; /* changed to */ i = 0;
-\newline
-i = j / 1 ; /* changed to */ i = j;
-\layout Standard
-
-Note the subexpressions
-\begin_inset LatexCommand \index{Subexpression}
-
-\end_inset
-
- given above are generally introduced by macro expansions or as a result
- of copy/constant propagation.
-\layout Subsubsection
-
-'switch' Statements
-\begin_inset LatexCommand \index{switch statement}
-
-\end_inset
-
-
-\layout Standard
-
-SDCC changes switch statements to jump tables
-\begin_inset LatexCommand \index{jump tables}
-
-\end_inset
-
- 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.
-\begin_deeper
-\layout Verse
-
-
-\family typewriter
-switch(i) {\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+Comment
+\newline
+;;---\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-switch (i) {
-\newline
\SpecialChar ~
+------\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 4: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+--------
+\newline
+;;
+\newline
+;; n\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 0: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 5: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdb-next-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+SDCDB next command
+\newline
+;; b\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 1: ...
-
-\newline
\SpecialChar ~
+ sdcdb-back-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 3: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+SDCDB back command
+\newline
+;; c\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdb-cont-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 2: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 6: ...\SpecialChar ~
\SpecialChar ~
+SDCDB continue command
+\newline
+;; s\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdb-step-from-src\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+SDCDB step command
+\newline
+;; ?\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 3: ...
-
-\newline
-}\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdb-whatis-c-sexp\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+SDCDB ptypecommand for data at
+\newline
+;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-}
-\layout Standard
-
-Both the above switch statements will be implemented using a jump-table.
- The example to the right side is slightly more efficient as the check for
- the lower bound of the jump-table is not needed.
-\end_deeper
-\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.:
-\layout Verse
-
-
-\family typewriter
-switch (i) {
-\newline
\SpecialChar ~
\SpecialChar ~
-case 1: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 2: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 3: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 4: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 9: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 10: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 11: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 12: ...
-
-\newline
-}
-\layout Standard
-
-If the above switch statement is broken down into two switch statements
-\layout Verse
-
-
-\family typewriter
-switch (i) {
-\newline
\SpecialChar ~
\SpecialChar ~
-case 1: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 2: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 3: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 4: ...
-
-\newline
-}
-\layout Standard
-
-and
-\layout Verse
-
-
-\family typewriter
-switch (i) {
-\newline
\SpecialChar ~
\SpecialChar ~
-case 9: \SpecialChar ~
-...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 10: ...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-case 11: ...
-
+ buffer point
\newline
+;; x\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 12:\SpecialChar ~
-...
-
-\newline
-}
-\layout Standard
-
-then both the switch statements will be implemented using jump-tables whereas
- the unmodified switch statement will not be.
- You might also consider dummy cases 0 and 5 to 8 in this example.
- The pragma NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
-
-\end_inset
-
- can be used to turn off checking the
-\emph on
-j
-\emph default
-ump
-\emph on
-t
-\emph default
-able
-\emph on
-bound
-\emph default
-aries.
-\layout Subsubsection
-
-Bit-shifting Operations
-\begin_inset LatexCommand \index{Bit shifting}
-
-\end_inset
-
-.
-\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.:
-\layout Verse
-
-
-\family typewriter
-unsigned char i;
-\newline
-...
-
-\newline
-i >>= 4;
-\newline
-...
-\layout Standard
-
-generates the following code:
-\layout Verse
-
-
-\family typewriter
-mov a,_i
-\newline
-swap a
-\newline
-anl a,#0x0f
-\newline
-mov _i,a
-\layout Standard
-
-In general SDCC will never setup a loop if the shift count is known.
- Another example:
-\layout Verse
-
-
-\family typewriter
-unsigned int i;
-\newline
-...
-
-\newline
-i >>= 9;
-\newline
-...
-\layout Standard
-
-will generate:
-\layout Verse
-
-
-\family typewriter
-mov\SpecialChar ~
\SpecialChar ~
-a,(_i + 1)
-\newline
-mov\SpecialChar ~
\SpecialChar ~
-(_i + 1),#0x00
-\newline
-clr\SpecialChar ~
\SpecialChar ~
-c
-\newline
-rrc\SpecialChar ~
\SpecialChar ~
-a
-\newline
-mov\SpecialChar ~
\SpecialChar ~
-_i,a
-\layout Standard
-
-Note that SDCC stores numbers in little-endian format (i.e.
- lowest order first).
-\layout Subsubsection
-
-Bit-rotation
-\begin_inset LatexCommand \index{Bit rotation}
-
-\end_inset
-
-
-\layout Standard
-
-A special case of the bit-shift operation is bit rotation, SDCC recognizes
- the following expression to be a left bit-rotation:
-\layout Verse
-
-
-\family typewriter
-unsigned char i;
-\newline
-...
-
-\newline
-i = ((i << 1) | (i >> 7));
-\family default
-
-\newline
-
-\family typewriter
-...
-\layout Standard
-
-will generate the following code:
-\layout Verse
-
-
-\family typewriter
-mov\SpecialChar ~
\SpecialChar ~
-a,_i
-\newline
-rl\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-a
-\newline
-mov\SpecialChar ~
\SpecialChar ~
-_i,a
-\layout Standard
-
-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.:
-\layout Verse
-
-
-\family typewriter
-i = ((i >> 7) | (i << 1)); /* left-bit rotation */
-\layout Subsubsection
-
-Highest Order Bit
-\begin_inset LatexCommand \index{Highest Order Bit}
-
-\end_inset
-
-
-\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.:
-\layout Verse
-
-
-\family typewriter
-unsigned int gint;
-\newline
-
-\newline
-foo () {
-\newline
\SpecialChar ~
\SpecialChar ~
-unsigned char hob;
-\newline
+ sdcdbsrc-delete\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-hob = (gint >> 15) & 1;
-\newline
\SpecialChar ~
\SpecialChar ~
-..
-
-\newline
-}
-\layout Standard
-
-will generate the following code:
-\layout Verse
-
-
-\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+SDCDB Delete all breakpoints if no arg
+\newline
+;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 61 ;\SpecialChar ~
- hob.c 7
-\newline
-000A E5*01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 62\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- mov\SpecialChar ~
\SpecialChar ~
- a,(_gint + 1)
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+given or delete arg (C-u arg x)
\newline
-000C 23\SpecialChar ~
+;; m\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ sdcdbsrc-frame\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 63\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- rl\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- a
+SDCDB Display current frame if no arg,
\newline
-000D 54 01\SpecialChar ~
+;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 64\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- anl\SpecialChar ~
\SpecialChar ~
- a,#0x01
+\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
-000F F5*02\SpecialChar ~
+;;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 65\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- mov\SpecialChar ~
\SpecialChar ~
- _foo_hob_1_1,a
-\layout Standard
-
-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.:
-\layout Verse
-
-
-\family typewriter
-xyz = gint + ((gint >> 15) & 1);
-\layout Standard
-
-will still be recognized.
-\layout Subsubsection
-
-Peephole Optimizer
-\begin_inset LatexCommand \index{Peephole optimizer}
-
-\end_inset
-
-
-\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
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--peep-file
-\begin_inset LatexCommand \index{-\/-peep-file}
-
-\end_inset
-
- <filename>
-\emph default
- option.
- The rule language is best illustrated with examples.
-\layout Verse
-
-
-\family typewriter
-replace {
+\SpecialChar ~
+\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
+;; !\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov %1,a
+\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 ~
-mov a,%1
+\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
-} by {
+;;\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 ~
+ buffer point
\newline
+;; g\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-mov %1,a
+\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
-}
-\layout Standard
-
-The above rule will change the following assembly
-\begin_inset LatexCommand \index{Assembler routines}
-
-\end_inset
-
- sequence:
-\layout Verse
-
-
-\family typewriter
-mov r1,a
+;; t\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-mode\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Toggles Sdcdbsrc mode (turns it off)
\newline
-mov a,r1
+;;
+\newline
+;; C-c C-f\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-finish-from-src\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+SDCDB finish command
+\newline
+;;
+\newline
+;; C-x SPC\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdb-break\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Set break for line with point
+\newline
+;; ESC t\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-mode\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Toggle Sdcdbsrc mode
+\newline
+;; ESC m\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ sdcdbsrc-srcmode\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ Toggle list mode
+\newline
+;;
+\newline
+
+\layout Section
+\pagebreak_top
+TIPS
\layout Standard
-to
+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.
+\begin_deeper
\layout Verse
\family typewriter
-mov r1,a
+foobar(unsigned int p1, unsigned char ch)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+unsigned char ch1 = p1 % ch ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....
+\newline
+}
\layout Standard
-Note: All occurrences of a
-\emph on
-%n
-\emph default
- (pattern variable) must denote the same string.
- With the above rule, the assembly sequence:
+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
\layout Verse
\family typewriter
-mov r1,a
+foobar(unsigned int p1, unsigned char ch)
\newline
-mov a,r2
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+unsigned char ch1 = (unsigned char)p1 % ch ;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+....
+\newline
+}
\layout Standard
-will remain unmodified.
-\newline
+It would substantially reduce the code generated (future versions of the
+ compiler will be smart enough to detect such optimization opportunities).
+\end_deeper
+\layout Itemize
-\newline
-Other special case optimizations may be added by the user (via
-\emph on
--
-\begin_inset ERT
-status Collapsed
+Have a look at the assembly listing to get a
+\begin_inset Quotes sld
+\end_inset
-\layout Standard
+feeling
+\begin_inset Quotes srd
+\end_inset
+
+ for the code generation.
+\layout Subsection
+
+Notes on MCS51 memory
+\begin_inset LatexCommand \index{MCS51 memory}
-\backslash
-/
\end_inset
--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
-\layout Verse
-
-
-\family typewriter
-replace { lcall %1 } by { acall %1 }
-\newline
-replace { ljmp %1 } by { ajmp %1 }
+ layout
\layout Standard
-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:
-\layout Verse
-
-
-\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'
+The 8051 family of microcontrollers have a minimum of 128 bytes of internal
+ RAM memory which is structured as follows
\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- '}' [if <functionName> ] '
-\backslash
-n'
-\layout Standard
-<assembly sequence> := assembly instruction (each instruction including
- labels must be on a separate line).
\newline
-
+- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
+
\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:
-\layout Verse
+- Bytes 20-2F - 16 bytes to hold 128 bit
+\begin_inset LatexCommand \index{bit}
+\end_inset
-\family typewriter
-replace restart {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-pop %1
-\newline
-\SpecialChar ~
-\SpecialChar ~
-push %1 } by {
+ variables and,
\newline
-\SpecialChar ~
-\SpecialChar ~
-; nop
+- Bytes 30-7F - 80 bytes for general purpose use.
\newline
-}
-\layout Standard
-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.:
-\layout Verse
+\layout Standard
+Additionally some members of the MCS51 family may have up to 128 bytes of
+ additional, indirectly addressable, internal RAM memory (
+\emph on
+idata
+\emph default
-\family typewriter
-pop ar1
-\newline
-pop ar2
-\newline
-push ar2
-\newline
-push ar1
-\layout Standard
+\begin_inset LatexCommand \index{idata}
-would result in:
-\layout Verse
+\end_inset
+).
+ Furthermore, some chips may have some built in external memory (
+\emph on
+xdata
+\emph default
-\family typewriter
-pop ar1
-\newline
-; nop
-\newline
-push ar1
-\layout Standard
+\begin_inset LatexCommand \index{xdata}
+\end_inset
+) which should not be confused with the internal, directly addressable RAM
+ memory (
\emph on
-with
+data
\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:
-\layout Verse
+\begin_inset LatexCommand \index{data}
-\family typewriter
-; nop
-\newline
-; nop
+\end_inset
+
+).
+ Sometimes this built in
+\emph on
+xdata
+\emph default
+ memory has to be activated before using it (you can probably find this
+ information on the datasheet of the microcontroller your are using).
\layout Standard
-A conditional function can be attached to a rule.
- Attaching rules are somewhat more involved, let me illustrate this with
- an example.
-\layout Verse
+Normally SDCC will only use the first bank
+\begin_inset LatexCommand \index{bank}
+\end_inset
-\family typewriter
-replace {
-\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-ljmp %5
-\newline
-%2:
-\newline
-} by {
-\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-sjmp %5
-\newline
-%2:
-\newline
-} if labelInRange
-\layout Standard
+ of registers (register bank 0), but it is possible to specify that other
+ banks of registers should be used in interrupt
+\begin_inset LatexCommand \index{interrupt}
-The optimizer does a look-up of a function name table defined in function
-
+\end_inset
+
+ routines.
+ By default, the compiler will place the stack after the last byte of allocated
+ memory for variables.
+ For example, if the first 2 banks of registers are used, and only four
+ bytes are used for
\emph on
-callFuncByName
+data
\emph default
- in the source file SDCCpeeph.c, with the name
+ variables, it will position the base of the internal stack at address 20
+ (0x14).
+ This implies that as the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ grows, it will use up the remaining register banks, and the 16 bytes used
+ by the 128 bit variables, and 80 bytes for general purpose use.
+ If any bit variables are used, the data variables will be placed after
+ the byte holding the last bit variable.
+ For example, if register banks 0 and 1 are used, and there are 9 bit variables
+ (two bytes used),
\emph on
-labelInRange
+data
\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
+ variables will be placed starting at address 0x22.
+ You can also use -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-data-loc
+\begin_inset LatexCommand \index{-\/-data-loc}
+
+\end_inset
+
+ to specify the start address of the
\emph on
-labelInRange
+data
\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.
- Currently implemented are
+ and -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-iram-size to specify the size of the total internal RAM (
\emph on
-labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
- 24bitMode, portIsDS390, 24bitModeAndPortDS390
+data
\emph default
-and
++
\emph on
- notVolatile
+idata
\emph default
-.
+).
+
\layout Standard
-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 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 -
+By default the 8051 linker will place the stack after the last byte of data
+ variables.
+ Option -
\begin_inset ERT
status Collapsed
/
\end_inset
--peep-file option.
-\layout Subsection
-
-Pragmas
-\begin_inset LatexCommand \index{Pragmas}
+-stack-loc
+\begin_inset LatexCommand \index{-\/-stack-loc}
\end_inset
+ allows you to specify the start of the stack, i.e.
+ you could start it after any data in the general purpose area.
+ If your microcontroller has additional indirectly addressable internal
+ RAM (
+\emph on
+idata
+\emph default
+) you can place the stack on it.
+ You may also need to use -
+\begin_inset ERT
+status Collapsed
\layout Standard
-SDCC supports the following #pragma directives.
-\layout Itemize
+\backslash
+/
+\end_inset
-SAVE
-\begin_inset LatexCommand \index{\#pragma SAVE}
+-xdata-loc
+\begin_inset LatexCommand \index{-\/-data-loc}
\end_inset
- - this will save all current options to the SAVE/RESTORE stack.
- See RESTORE.
-\layout Itemize
+ to set the start address of the external RAM (
+\emph on
+xdata
+\emph default
+) and -
+\begin_inset ERT
+status Collapsed
-RESTORE
-\begin_inset LatexCommand \index{\#pragma RESTORE}
+\layout Standard
+\backslash
+/
\end_inset
- - 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
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+-xram-size
+\begin_inset LatexCommand \index{-\/-data-loc}
\end_inset
- - will stop global common subexpression elimination.
-\layout Itemize
+ to specify its size.
+ Same goes for the code memory, using -
+\begin_inset ERT
+status Collapsed
-NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+\layout Standard
+\backslash
+/
\end_inset
- - will stop loop induction optimizations.
-\layout Itemize
-
-NOJTBOUND
-\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
+-code-loc
+\begin_inset LatexCommand \index{-\/-data-loc}
\end_inset
- - will not generate code for boundary value checking, when switch statements
- are turned into jump-tables (dangerous).
-
-\layout Itemize
+ and -
+\begin_inset ERT
+status Collapsed
-NOOVERLAY
-\begin_inset LatexCommand \index{\#pragma NOOVERLAY}
+\layout Standard
+\backslash
+/
\end_inset
- - the compiler will not overlay the parameters and local variables of a
- function.
-\layout Itemize
-
-LESS_PEDANTIC
-\begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
+-code-size
+\begin_inset LatexCommand \index{-\/-data-loc}
\end_inset
- - the compiler will not warn you anymore for obvious mistakes, you'r on
- your own now ;-(
-\layout Itemize
+.
+ If in doubt, don't specify any options and see if the resulting memory
+ layout is appropriate, then you can adjust it.
+\layout Standard
-NOLOOPREVERSE
-\begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
+The 8051 linker generates two files with memory allocation information.
+ The first, with extension .map shows all the variables and segments.
+ The second with extension .mem shows the final memory layout.
+ The linker will complaint either if memory segments overlap, there is not
+ enough memory, or there is not enough space for stack.
+ If you get any linking warnings and/or errors related to stack or segments
+ allocation, take a look at either the .map or .mem files to find out what
+ the problem is.
+ The .mem file may even suggest a solution to the problem.
+\layout Subsection
+
+Tools
+\begin_inset LatexCommand \index{Tools}
\end_inset
- - Will not do loop reversal optimization
-\layout Itemize
+ included in the distribution
+\layout Standard
+\align center
-EXCLUDE
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+\begin_inset Tabular
+<lyxtabular version="3" rows="12" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0pt">
+<column alignment="left" valignment="top" leftline="true" width="0pt">
+<column alignment="left" 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
+
+\layout Standard
+Name
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
- pair of push/pop
-\begin_inset LatexCommand \index{push/pop}
+\layout Standard
+Purpose
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- instruction in ISR function (using interrupt
-\begin_inset LatexCommand \index{interrupt}
+\layout Standard
+Directory
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- 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
-\begin_inset LatexCommand \index{\#pragma EXCLUDE}
+\layout Standard
+uCsim
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-\layout Itemize
-
-NOIV
-\begin_inset LatexCommand \index{\#pragma NOIV}
+\layout Standard
+Simulator for various architectures
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- - 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
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+\layout Standard
+sdcc/sim/ucsim
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{function prologue}
-
+keil2sdcc.pl
\end_inset
-
- function1[,function2[,function3...]] - The compiler by default uses a caller
- saves convention for register saving across function calls, however this
- can cause unnecessary 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 inter procedural analysis) may be able
- to determine the appropriate scheme to use for each function call.
- If -
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+header file conversion
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--callee-saves command line option is used, the function names specified
- in #pragma\SpecialChar ~
-CALLEE-SAVES
-\begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
+\layout Standard
+sdcc/support/scripts
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- 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.
-\layout Verse
-
-
-\family typewriter
-#pragma SAVE
-\begin_inset LatexCommand \index{\#pragma SAVE}
-
+mh2h.c
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- \SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* save the current settings */
-\newline
-#pragma NOGCSE
-\begin_inset LatexCommand \index{\#pragma NOGCSE}
+\layout Standard
+header file conversion
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- \SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* turnoff global subexpression elimination */
-\newline
-#pragma NOINDUCTION
-\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
+\layout Standard
+sdcc/support/scripts
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- /* turn off induction optimizations */
-\newline
-int foo ()
-\newline
-{
-\newline
-\SpecialChar ~
- \SpecialChar ~
- ...
-
-\newline
-\SpecialChar ~
- \SpecialChar ~
- /* large code */
-\newline
-\SpecialChar ~
- \SpecialChar ~
- ...
-
-\newline
-}
-\newline
-#pragma RESTORE
-\begin_inset LatexCommand \index{\#pragma RESTORE}
+\layout Standard
+as-gbz80
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- /* turn the optimizations back on */
\layout Standard
-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
+Assembler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-Library Routines
-\emph on
-
\layout Standard
-\emph on
-<pending: this is messy and incomplete>
-\emph default
-
-\layout Enumerate
-
-Compiler support routines (_gptrget, _mulint etc)
-\layout Enumerate
-
-Stdclib functions (puts, printf, strcat etc)
-\layout Enumerate
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Math functions (sin, pow, sqrt etc)
\layout Standard
-Libraries included in SDCC should have a license at least as liberal as
- the GNU Lesser General Public License
-\begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
-
+as-z80
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\emph on
-LGPL
-\emph default
-.
-\layout Comment
-
-license statements for the libraries are missing.
- sdcc/device/lib/ser_ir.c f.e.
- comes with a GPL (as opposed to LGPL) License - this will not be liberal
- enough for many embedded programmers.
-\layout Subsection
-
-Interfacing with Assembly Routines
-\begin_inset LatexCommand \index{Assembler routines}
+\layout Standard
+Assembler
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\layout Subsubsection
-
-Global Registers used for Parameter Passing
-\begin_inset LatexCommand \index{Parameter passing}
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
-
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-The compiler always uses the global registers
-\emph on
-DPL, DPH
-\begin_inset LatexCommand \index{DPTR, DPH, DPL}
-
+asx8051
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-, B
-\begin_inset LatexCommand \index{B (register)}
+\layout Standard
+Assembler
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-
-\emph default
-and
-\emph on
- ACC
-\begin_inset LatexCommand \index{ACC}
+\layout Standard
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\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 -
-\begin_inset ERT
-status Collapsed
+sdcdb
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+Simulator
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--stack-auto is used) or in data / xdata memory (depending on the memory
- model).
-
-\layout Subsubsection
+\layout Standard
-Assembler Routine(non-reentrant
-\begin_inset LatexCommand \index{reentrant}
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-)
-\begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
+\layout Standard
+aslink
\end_inset
-
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-In the following example the function c_func calls an assembler routine
- asm_func, which takes two parameters.
-\layout Verse
+Linker
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\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
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\newline
-int main()
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-return c_func(10,9);
-\newline
-}
\layout Standard
-The corresponding assembler function is:
-\layout Verse
-
+link-z80
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\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\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-dpl
-\begin_inset LatexCommand \index{DPTR, DPH, DPL}
+\layout Standard
+Linker
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-,#0x00
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ret
\layout Standard
-Note here that the return values are placed in 'dpl' - One byte return value,
- 'dpl' LSB & 'dph' MSB for two byte values.
- '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
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-dpl
-\begin_inset Quotes erd
-\end_inset
+\layout Standard
- for One bye parameter,
-\begin_inset Quotes eld
+link-gbz80
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-dptr
-\begin_inset Quotes erd
-\end_inset
+\layout Standard
- if two bytes,
-\begin_inset Quotes eld
+Linker
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-b,dptr
-\begin_inset Quotes erd
-\end_inset
+\layout Standard
- for three bytes and
-\begin_inset Quotes eld
-\end_inset
-acc,b,dptr
-\begin_inset Quotes erd
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- for four bytes, the variable name for the second parameter will be _<function_n
-ame>_PARM_2.
-\newline
-
-\newline
-Assemble the assembler routine with the following command:
-\newline
-
-\newline
-
-\family sans
-\series bold
-asx8051 -losg asmfunc.asm
-\newline
+\layout Standard
-\newline
+packihx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\family default
-\series default
-Then compile and link the assembler routine to the C source file with the
- following command:
-\newline
+\layout Standard
-\newline
+ihx packer
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-\family sans
-\series bold
-sdcc cfunc.c asmfunc.rel
-\layout Subsubsection
+\layout Standard
-Assembler Routine(reentrant
-\begin_inset LatexCommand \index{reentrant}
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/bin
\end_inset
-
-)
-\begin_inset LatexCommand \index{Assembler routines (reentrant)}
+</cell>
+</row>
+</lyxtabular>
\end_inset
-\layout Standard
+\newline
-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:
-\layout Verse
+\layout Subsection
+Related open source tools
+\begin_inset LatexCommand \index{Related tools}
-\family typewriter
-extern int asm_func(unsigned char, unsigned char);
-\newline
+\end_inset
-\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
-}
\layout Standard
+\align center
-The corresponding assembler routine is:
-\layout Verse
-
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0pt">
+<column alignment="left" valignment="top" leftline="true" width="30line%">
+<column alignment="left" 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
-\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
\layout Standard
-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
+Name
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-External Stack
-\begin_inset LatexCommand \label{sub:External-Stack}
+\layout Standard
+Purpose
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{stack}
-
+Where to get
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{External stack}
+gpsim
+\begin_inset LatexCommand \index{gpsim}
\end_inset
-\layout Standard
-
-The external stack is located at the start of the external ram segment,
- and is 256 bytes in size.
- When -
-\begin_inset ERT
-status Collapsed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+PIC simulator
\end_inset
-
--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 -
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
--stack-auto option, all parameters and local variables are allocated on
- the external stack (note support libraries will need to be recompiled with
- the same options).
-\layout Standard
+\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
-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
+\end_inset
-ANSI-Compliance
-\begin_inset LatexCommand \index{ANSI-compliance}
\end_inset
-
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-Deviations from the compliance:
-\layout Itemize
+flP5
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-functions are not always reentrant.
-\layout Itemize
+\layout Standard
-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.:
-\begin_deeper
-\layout Verse
+PIC programmer
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\family typewriter
-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) /* 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
-}
-\end_deeper
-\layout Itemize
-'long long
-\begin_inset LatexCommand \index{long long (not supported)}
+\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
\end_inset
-' (64 bit integers
-\begin_inset LatexCommand \index{int (64 bit) (not supported)}
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-) not supported.
-\layout Itemize
+\layout Standard
-'double
-\begin_inset LatexCommand \index{double (not supported)}
+srecord
+\begin_inset LatexCommand \index{srecord}
\end_inset
-' precision floating point
-\begin_inset LatexCommand \index{Floating point support}
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-not supported.
-\layout Itemize
-
-No support for setjmp and longjmp (for now).
-\layout Itemize
-
-Old K&R style
-\begin_inset LatexCommand \index{K\&R style}
+\layout Standard
+Object file conversion, checksumming, ...
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- function declarations are NOT allowed.
-\begin_deeper
-\layout Verse
+\layout Standard
-\family typewriter
-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
-}
-\end_deeper
-\layout Itemize
+\begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
-functions declared as pointers must be dereferenced during the call.
-\begin_deeper
-\layout Verse
+\end_inset
-\family typewriter
-int (*foo)();
-\newline
-...
-
-\newline
-/* has to be called like this */
-\newline
-(*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
-\end_deeper
-\layout Subsection
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Cyclomatic Complexity
-\begin_inset LatexCommand \index{Cyclomatic complexity}
+\layout Standard
+
+objdump
+\begin_inset LatexCommand \index{objdump}
\end_inset
-\layout Standard
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-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
+\layout Standard
-\newline
-SDCC uses the following formula to compute the complexity:
-\newline
+Object file conversion, ...
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-complexity = (number of edges in control flow graph) - (number of nodes
- in control flow graph) + 2;
-\newline
+Part of binutils (should be there anyway)
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-\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
-\pagebreak_top
-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
+doxygen
+\begin_inset LatexCommand \index{doxygen}
-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
+\end_inset
-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
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Declare the variables to be local whenever possible, especially loop control
- variables (induction).
-\layout Itemize
+\layout Standard
-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
+Source code documentation system
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-Reducing the size of division, multiplication & modulus operations can reduce
- code size substantially.
- Take the following code for example.
-\begin_deeper
-\layout Verse
+\layout Standard
-\family typewriter
-foobar(unsigned int p1, unsigned char ch)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-unsigned char ch1 = p1 % ch ;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-....
-\newline
-}
-\layout Standard
+\begin_inset LatexCommand \url{http://www.doxygen.org}
-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
-\layout Verse
+\end_inset
-\family typewriter
-foobar(unsigned int p1, unsigned char ch)
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-unsigned char ch1 = (unsigned char)p1 % ch ;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-....
-\newline
-}
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
\layout Standard
-It would substantially reduce the code generated (future versions of the
- compiler will be smart enough to detect such optimization opportunities).
-\end_deeper
-\layout Itemize
+splint
+\begin_inset LatexCommand \index{splint}
-Have a look at the assembly listing to get a
-\begin_inset Quotes sld
\end_inset
-feeling
-\begin_inset Quotes srd
-\end_inset
- for the code generation.
-\layout Subsection
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Notes on MCS51 memory
-\begin_inset LatexCommand \index{MCS51 memory}
+\layout Standard
+Statically checks c sources
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- layout
\layout Standard
-The 8051 family of microcontrollers have a minimum of 128 bytes of internal
- RAM memory which is structured as follows
-\newline
-\newline
-- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
-
-\newline
-- Bytes 20-2F - 16 bytes to hold 128 bit variables and,
-\newline
-- Bytes 30-7F - 80 bytes for general purpose use.
-\newline
+\begin_inset LatexCommand \url{http://www.splint.org}
-\layout Standard
+\end_inset
+
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Additionally some members of the MCS51 family may have up to 128 bytes of
- additional, indirectly addressable, internal RAM memory (
-\emph on
-idata
-\emph default
-).
- Furthermore, some chips may have some built in external memory (
-\emph on
-xdata
-\emph default
-) which should not be confused with the internal, directly addressable RAM
- memory (
-\emph on
-data
-\emph default
-).
- Sometimes this built in
-\emph on
-xdata
-\emph default
- memory has to be activated before using it (you can probably find this
- information on the datasheet of the microcontroller your are using).
\layout Standard
-Normally SDCC will only use the first bank
-\begin_inset LatexCommand \index{bank}
+ddd
+\begin_inset LatexCommand \index{ddd}
\end_inset
- of registers (register bank 0), but it is possible to specify that other
- banks of registers should be used in interrupt
-\begin_inset LatexCommand \index{interrupt}
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- routines.
- By default, the compiler will place the stack after the last byte of allocated
- memory for variables.
- For example, if the first 2 banks of registers are used, and only four
- bytes are used for
-\emph on
-data
-\emph default
- variables, it will position the base of the internal stack at address 20
- (0x14).
- This implies that as the stack
-\begin_inset LatexCommand \index{stack}
+\layout Standard
+
+Debugger, serves nicely as GUI to sdcdb
+\begin_inset LatexCommand \index{sdcdb}
\end_inset
- grows, it will use up the remaining register banks, and the 16 bytes used
- by the 128 bit variables, and 80 bytes for general purpose use.
- If any bit variables are used, the data variables will be placed after
- the byte holding the last bit variable.
- For example, if register banks 0 and 1 are used, and there are 9 bit variables
- (two bytes used),
-\emph on
-data
-\emph default
- variables will be placed starting at address 0x22.
- You can also use -
-\begin_inset ERT
-status Collapsed
+ (Unix only)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
-\end_inset
--data-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
+\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
\end_inset
- to specify the start address of the
-\emph on
-data
-\emph default
- and -
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\end_inset
+</cell>
+</row>
+</lyxtabular>
-\backslash
-/
\end_inset
--iram-size to specify the size of the total internal RAM (
-\emph on
-data
-\emph default
-+
-\emph on
-idata
-\emph default
-).
-
-\layout Standard
-By default the 8051 linker will place the stack after the last byte of data
- variables.
- Option -
-\begin_inset ERT
-status Collapsed
+\newline
+
+\layout Subsection
+Related documentation / recommended reading
\layout Standard
+\align center
-\backslash
-/
-\end_inset
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0pt">
+<column alignment="left" valignment="top" leftline="true" width="30line%">
+<column alignment="left" 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
--stack-loc
-\begin_inset LatexCommand \index{-\/-stack-loc}
+\layout Standard
+Name
\end_inset
-
- allows you to specify the start of the stack, i.e.
- you could start it after any data in the general purpose area.
- If your microcontroller has additional indirectly addressable internal
- RAM (
-\emph on
-idata
-\emph default
-) you can place the stack on it.
- You may also need to use -
-\begin_inset ERT
-status Collapsed
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-\backslash
-/
+Subject / Title
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
--xdata-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
+\layout Standard
+Where to get
\end_inset
-
- to set the start address of the external RAM (
-\emph on
-xdata
-\emph default
-) and -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--xram-size
-\begin_inset LatexCommand \index{-\/-data-loc}
-
-\end_inset
-
- to specify its size.
- Same goes for the code memory, using -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--code-loc
-\begin_inset LatexCommand \index{-\/-data-loc}
-
-\end_inset
-
- and -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--code-size
-\begin_inset LatexCommand \index{-\/-data-loc}
-
-\end_inset
-
-.
- If in doubt, don't specify any options and see if the resulting memory
- layout is appropriate, then you can adjust it.
-\layout Standard
-
-The 8051 linker generates two files with memory allocation information.
- The first, with extension .map shows all the variables and segments.
- The second with extension .mem shows the final memory layout.
- The linker will complaint either if memory segments overlap, there is not
- enough memory, or there is not enough space for stack.
- If you get any linking warnings and/or errors related to stack or segments
- allocation, take a look at either the .map or .mem files to find out what
- the problem is.
- The .mem file may even suggest a solution to the problem.
-\layout Subsection
-
-Tools
-\begin_inset LatexCommand \index{Tools}
-
-\end_inset
-
- included in the distribution
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="12" columns="3">
-<features>
-<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>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
+S.
+ S.
+ Muchnick
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Purpose
+Advanced Compiler Design and Implementation
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Directory
+bookstore
\end_inset
</cell>
</row>
\layout Standard
-uCsim
+
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+c-refcard.pdf
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Simulator for various architectures
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+C Reference Card
+\begin_inset LatexCommand \index{C Reference card}
-\layout Standard
+\end_inset
-sdcc/sim/ucsim
+, 2 pages
\end_inset
</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-keil2sdcc.pl
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
-header file conversion
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-sdcc/support/scripts
\end_inset
</cell>
</row>
\layout Standard
-mh2h.c
+test_suite_spec.pdf
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-header file conversion
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+sdcc regression test
+\begin_inset LatexCommand \index{Regression test}
-sdcc/support/scripts
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-as-gbz80
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-Assembler
+sdcc/doc
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
\bar no
\noun off
\color none
-sdcc/bin
+cdbfileformat.pd
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+f
\end_inset
</cell>
-</row>
-<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-as-z80
+sdcc internal documentation
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-Assembler
+sdcc/doc
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+</row>
+</lyxtabular>
-\layout Standard
+\end_inset
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\newline
-\layout Standard
+\layout Section
+\pagebreak_top
+Support
+\begin_inset LatexCommand \index{Support}
-asx8051
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Assembler
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\layout Standard
+SDCC has grown to be a large project.
+ The compiler alone (without the preprocessor, assembler and linker) is
+ well over 100,000 lines of code (blank stripped).
+ The open source nature of this project is a key to its continued growth
+ and support.
+ You gain the benefit and support of many active software developers and
+ 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 Standard
+The SDCC project is hosted on the sdcc sourceforge site at
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+ You'll find the complete set of mailing lists
+\begin_inset LatexCommand \index{Mailing list}
-sdcdb
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+, forums, bug reporting system, patch submission
+\begin_inset LatexCommand \index{Patch submission}
-Simulator
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+ system, download
+\begin_inset LatexCommand \index{download}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ area and cvs code repository
+\begin_inset LatexCommand \index{cvs code repository}
-aslink
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ there.
+\layout Subsection
+
+Reporting Bugs
+\begin_inset LatexCommand \index{Bugs}
-Linker
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\begin_inset LatexCommand \index{Reporting bugs}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-link-z80
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\layout Standard
+The recommended way of reporting bugs is using the infrastructure of the
+ sourceforge site.
+ You can follow the status of bug reports there and have an overview about
+ the known bugs.
\layout Standard
-Linker
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+Bug reports are automatically forwarded to the developer mailing list and
+ will be fixed ASAP.
+ When reporting a bug, it is very useful to include a small test program
+ (the smaller the better) 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 -
+\begin_inset ERT
+status Collapsed
\layout Standard
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
+\backslash
+/
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+-dumpall
+\begin_inset LatexCommand \index{-\/-dumpall}
-link-gbz80
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ option can sometimes be useful in locating optimization problems.
+ When reporting a bug please maker sure you:
+\layout Enumerate
-Linker
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+Attach the code you are compiling with SDCC.
+
+\layout Enumerate
-\layout Standard
+Specify the exact command you use to run SDCC, or attach your Makefile.
+
+\layout Enumerate
+Specify the SDCC version (type "sdcc -v"), your platform, and operating
+ system.
+
+\layout Enumerate
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
-\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Provide an exact copy of any error message or incorrect output.
+
+\layout Enumerate
+Put something meaningful in the subject of your message.
\layout Standard
-packihx
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
+Please attempt to include these 5 important parts, as applicable, in all
+ requests for support or when reporting any problems or bugs with SDCC.
+ Though this will make your message lengthy, it will greatly improve your
+ chance that SDCC users and developers will be able to help you.
+ Some SDCC developers are frustrated by bug reports without code provided
+ that they can use to reproduce and ultimately fix the problem, so please
+ be sure to provide sample code if you are reporting a bug!
\layout Standard
-ihx packer
+Please have a short check that you are using a recent version of SDCC and
+ the bug is not yet known.
+ This is the link for reporting bugs:
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+\layout Subsection
+Requesting Features
+\begin_inset LatexCommand \label{sub:Requesting-Features}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
\end_inset
-</cell>
-</row>
-</lyxtabular>
-\end_inset
+\begin_inset LatexCommand \index{Feature request}
-\newline
+\end_inset
-\layout Subsection
-Related open source tools
-\begin_inset LatexCommand \index{Related tools}
+\begin_inset LatexCommand \index{Requesting features}
\end_inset
\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="8" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="block" valignment="top" leftline="true" width="30line%">
-<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
-\layout Standard
+Like bug reports feature requests are forwarded to the developer mailing
+ list.
+ This is the link for requesting features:
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
-Name
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+.
+\layout Subsection
+
+Getting Help
\layout Standard
-Purpose
+These links should take you directly to the
+\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
+
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Where to get
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_inset Foot
+collapsed false
\layout Standard
-gpsim
-\begin_inset LatexCommand \index{gpsim}
-
+Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
+ automated messages (mid 2003)
\end_inset
+ and the
+\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+, lists and forums are archived so if you are lucky someone already had
+ a similar problem.
+\layout Subsection
+
+ChangeLog
+\begin_inset LatexCommand \index{Changelog}
-PIC simulator
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\layout Standard
-\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
+You can follow the status of the cvs version
+\begin_inset LatexCommand \index{version}
\end_inset
+ of SDCC by watching the file
+\begin_inset LatexCommand \htmlurl[ChangeLog]{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-flP5
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ in the cvs-repository.
+\layout Subsection
-\layout Standard
+Release policy
+\begin_inset LatexCommand \index{Release policy}
-PIC programmer
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\layout Standard
-\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
+Historically there often were long delays between official releases and
+ the sourceforge download area tends to get not updated at all.
+ Current excuses might refer to problems with live range analysis, but if
+ this is fixed, the next problem rising is that another excuse will have
+ to be found.
+ Kidding aside, we have to get better there! On the other hand there are
+ daily snapshots available at
+\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
\end_inset
+, and you can always built the very last version (hopefully with many bugs
+ fixed, and features added) from the source code available at
+\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+.
+\layout Subsection
-srecord
-\begin_inset LatexCommand \index{srecord}
+Examples
+\begin_inset LatexCommand \index{Examples}
\end_inset
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
\layout Standard
-Object file conversion, checksumming, ...
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+You'll find some small examples in the directory sdcc/device/examples/
+\layout Comment
+Maybe we should include some links to real world applications.
+ Preferably pointer to pointers (one for each architecture) so this stays
+ manageable here?
+\layout Subsection
-\begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
+Quality control
+\begin_inset LatexCommand \index{Quality control}
\end_inset
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
\layout Standard
-objdump
-\begin_inset LatexCommand \index{objdump}
-
-\end_inset
+The compiler is passed through nightly compile and build checks.
+ The so called
+\shape italic
+regression tests
+\shape default
+\begin_inset LatexCommand \index{Regression test}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ check that SDCC itself compiles flawlessly on several platforms and checks
+ the quality of the code generated by SDCC by running the code through simulator
+s.
+ There is a separate document
+\shape italic
+test_suite.pdf
+\begin_inset LatexCommand \index{Test suite}
-Object file conversion, ...
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-
-Part of binutils (should be there anyway)
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\shape default
+ about this.
\layout Standard
-doxygen
-\begin_inset LatexCommand \index{doxygen}
-
-\end_inset
-
+You'll find the test code in the directory
+\shape italic
+sdcc/support/regression
+\shape default
+.
+ You can run these tests manually by running
+\family sans
+make
+\family default
+ in this directory (or f.e.
+
+\family sans
+make test-mcs51
+\family default
+ if you don't want to run the complete tests).
+ The test code might also be interesting if you want to look for examples
+\begin_inset LatexCommand \index{Examples}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+ checking corner cases of SDCC or if you plan to submit patches
+\begin_inset LatexCommand \index{Patch submission}
-Source code documentation system
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+.
\layout Standard
+The pic port uses a different set of regression tests, you'll find them
+ in the directory
+\shape italic
+sdcc/src/regression
+\shape default
+.
+\layout Section
+\pagebreak_top
+SDCC Technical Data
+\layout Subsection
-\begin_inset LatexCommand \url{http://www.doxygen.org}
+Optimizations
+\begin_inset LatexCommand \index{Optimizations}
\end_inset
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
\layout Standard
-splint
-\begin_inset LatexCommand \index{splint}
-
-\end_inset
+SDCC performs a host of standard optimizations in addition to some MCU specific
+ optimizations.
+
+\layout Subsubsection
+Sub-expression Elimination
+\begin_inset LatexCommand \index{Subexpression elimination}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-Statically checks c sources
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
\layout Standard
+The compiler does local and global common subexpression elimination, e.g.:
+
+\layout Verse
-\begin_inset LatexCommand \url{http://www.splint.org}
-\end_inset
+\family typewriter
+i = x + y + 1;
+\newline
+j = x + y;
+\layout Standard
+will be translated to
+\layout Verse
-\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+iTemp = x + y;
+\newline
+i = iTemp + 1;
+\newline
+j = iTemp;
\layout Standard
-ddd
-\begin_inset LatexCommand \index{ddd}
-
-\end_inset
-
+Some subexpressions are not as obvious as the above example, e.g.:
+\layout Verse
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+a->b[i].c = 10;
+\newline
+a->b[i].d = 11;
\layout Standard
-Debugger, serves nicely as GUI to sdcdb
-\begin_inset LatexCommand \index{sdcdb}
-
-\end_inset
+In this case the address arithmetic a->b[i] will be computed only once;
+ the equivalent code in C would be.
+\layout Verse
- (Unix only)
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+iTemp = a->b[i];
+\newline
+iTemp.c = 10;
+\newline
+iTemp.d = 11;
\layout Standard
+The compiler will try to keep these temporary variables in registers.
+\layout Subsubsection
-\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
+Dead-Code Elimination
+\begin_inset LatexCommand \index{Dead-code elimination}
\end_inset
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
+\layout Verse
+\family typewriter
+int global;
\newline
-\layout Subsection
-
-Related documentation / recommended reading
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="5" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="block" valignment="top" leftline="true" width="30line%">
-<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
-
+\newline
+void f () {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+int i;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+i = 1; \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\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
+}
\layout Standard
-Name
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+will be changed to
+\layout Verse
-Subject / Title
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\family typewriter
+int global;
+\newline
-Where to get
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\newline
+void f () {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+global = 2;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+return;
+\newline
+}
+\layout Subsubsection
-\layout Standard
+Copy-Propagation
+\begin_inset LatexCommand \index{Copy propagation}
-S.
- S.
- Muchnick
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-Advanced Compiler Design and Implementation
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\layout Verse
-bookstore
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\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
+}
\layout Standard
+will be changed to
+\layout Verse
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-c-refcard.pdf
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\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
+}
\layout Standard
-C Reference Card
-\begin_inset LatexCommand \index{C Reference card}
+Note: the dead stores created by this copy propagation will be eliminated
+ by dead-code elimination.
+\layout Subsubsection
-\end_inset
+Loop Optimizations
+\begin_inset LatexCommand \index{Loop optimization}
-, 2 pages
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+\layout Standard
-\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
+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
+\begin_inset LatexCommand \index{Register allocation}
\end_inset
+, loop induction optimization causes an increase in register pressure, which
+ may cause unwanted spilling of other temporary variables into the stack
+\begin_inset LatexCommand \index{stack}
\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+ / 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 -
+\begin_inset ERT
+status Collapsed
\layout Standard
-test_suite_spec.pdf
+\backslash
+/
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-sdcc regression test
-\begin_inset LatexCommand \index{Regression test}
+-noinduction option) or for a given function only using #pragma\SpecialChar ~
+NOINDUCTION
+\begin_inset LatexCommand \index{\#pragma NOINDUCTION}
\end_inset
+.
+\newline
+
+\newline
+Loop Invariant:
+\layout Verse
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+for (i = 0 ; i < 100 ; i ++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+f += k + l;
\layout Standard
-sdcc/doc
-\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+changed to
+\layout Verse
+
+\family typewriter
+itemp = k + l;
+\newline
+for (i = 0; i < 100; i++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+f += itemp;
\layout Standard
+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
+\begin_inset LatexCommand \index{Strength reduction}
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-cdbfileformat.pd
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color default
-f
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
+, this optimization substitutes an expression by a cheaper expression:
+\layout Verse
-sdcc internal documentation
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\family typewriter
+for (i=0;i < 100; i++)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ar[i*5] = i*3;
\layout Standard
-sdcc/doc
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
+changed to
+\layout Verse
+\family typewriter
+itemp1 = 0;
\newline
-
-\layout Section
-\pagebreak_top
-Retargetting for other MCUs.
+itemp2 = 0;
+\newline
+for (i=0;i< 100;i++) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ar[itemp1] = itemp2;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+itemp1 += 5;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+itemp2 += 3;
+\newline
+}
\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
+The more expensive multiplication
+\begin_inset LatexCommand \index{Multiplication}
-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
+\end_inset
+
+ is changed to a less expensive addition.
+\layout Subsubsection
+
+Loop Reversing
+\begin_inset LatexCommand \index{Loop reversing}
+
+\end_inset
-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 -
-\begin_inset ERT
-status Collapsed
\layout Standard
-\backslash
-/
+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
--dumpraw option.
+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
-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:
+The 'for' loop is of the form
\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
+
+\family typewriter
+for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
+ += 1])
\newline
-If loop optimizations caused any changes then do 'global subexpression eliminati
-on' and 'dead code elimination' again.
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+<for body>
\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
-\begin_inset LatexCommand \index{Live range analysis}
+The <for body> does not contain
+\begin_inset Quotes eld
+\end_inset
+continue
+\begin_inset Quotes erd
\end_inset
- is essential for register allocation, since these computation determines
- which of these iTemps will be assigned to registers, and for how long.
-\layout Itemize
+ or 'break
+\begin_inset Quotes erd
+\end_inset
-Phase five is register allocation.
- There are two parts to this process.
-\newline
+.
+\layout Itemize
-\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
+All goto's are contained within the loop.
+\layout Itemize
-\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.
+No function calls within the loop.
\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.
+The loop control variable <sym> is not assigned any value within the loop
\layout Itemize
-As mentioned in the optimization section the peep-hole optimizer is rule
- based system, which can reprogrammed for other MCUs.
-\layout Section
-\pagebreak_top
-SDCDB
-\begin_inset LatexCommand \index{sdcdb}
+The loop control variable does NOT participate in any arithmetic operation
+ within the loop.
+\layout Itemize
-\end_inset
+There are NO switch statements in the loop.
+\layout Subsubsection
- - Source Level Debugger
-\begin_inset LatexCommand \index{Debugger}
+Algebraic Simplifications
+\layout Standard
-\end_inset
+SDCC does numerous algebraic simplifications, the following is a small sub-set
+ of these optimizations.
+\layout Verse
+\family typewriter
+i = j + 0 ; /* changed to */ i = j;
+\newline
+i /= 2;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to */ i >>= 1;
+\newline
+i = j - j ; /* changed to */ i = 0;
+\newline
+i = j / 1 ; /* changed to */ i = j;
\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
-\begin_inset LatexCommand \index{gdb}
+Note the subexpressions
+\begin_inset LatexCommand \index{Subexpression}
\end_inset
- (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.
- Sdcdb is available on Unix platforms only.
-\layout Subsection
-
-Compiling for Debugging
-\layout Standard
+ given above are generally introduced by macro expansions or as a result
+ of copy/constant propagation.
+\layout Subsubsection
-The \SpecialChar \-
-\SpecialChar \-
-debug option must be specified for all files for which debug information
- is to be generated.
- The complier generates a .adb file for each of these files.
- The linker creates the .cdb file from the .adb files and the address information.
- This .cdb is used by the debugger.
-\layout Subsection
+'switch' Statements
+\begin_inset LatexCommand \index{switch statement}
-How the Debugger Works
-\layout Standard
+\end_inset
-When the -
-\begin_inset ERT
-status Collapsed
\layout Standard
-\backslash
-/
+SDCC changes switch statements to jump tables
+\begin_inset LatexCommand \index{jump tables}
+
\end_inset
--debug option is specified the compiler generates extra symbol information
- some of which are put into the the assembler source and some are put into
- the .adb file.
- Then the linker creates the .cdb file from the individual .adb files with
- the address information for the symbols.
- The debugger reads the symbolic information generated by the compiler &
- 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
+ when the following conditions are true.
+
+\layout Itemize
-Starting the Debugger
-\layout Standard
+The case labels are in numerical sequence, the labels need not be in order,
+ and the starting number need not be one or zero.
+\begin_deeper
+\layout Verse
-The debugger can be started using the following command line.
- (Assume the file you are debugging has the file name foo).
-\newline
+\family typewriter
+switch(i) {\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 ~
+switch (i) {
\newline
-
-\family sans
-\series bold
-sdcdb foo
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...\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 ~
+case 0: ...
+
\newline
-
-\family default
-\series default
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 5: ...\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 ~
+case 1: ...
+
\newline
-The debugger will look for the following files.
-\layout Itemize
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...\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 ~
+case 2: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...\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 ~
+case 3: ...
+
+\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 ~
+}
+\layout Standard
-foo.c - the source file.
+Both the above switch statements will be implemented using a jump-table.
+ The example to the right side is slightly more efficient as the check for
+ the lower boundary of the jump-table is not needed.
+\end_deeper
\layout Itemize
-foo.cdb - the debugger symbol information file.
+The number of case labels is at least three, since it takes two conditional
+ statements to handle the boundary conditions.
\layout Itemize
-foo.ihx - the Intel hex format
-\begin_inset LatexCommand \index{Intel hex format}
-
-\end_inset
-
- object file.
-\layout Subsection
-
-Command Line Options.
-\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
--
-\begin_inset ERT
-status Collapsed
+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.:
+\layout Verse
-\layout Standard
-\backslash
-/
-\end_inset
+\family typewriter
+switch (i) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 2: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 9: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 10: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 11: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 12: ...
+
+\newline
+}
+\layout Standard
+
+If the above switch statement is broken down into two switch statements
+\layout Verse
--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 -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+switch (i) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 2: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...
+
+\newline
+}
\layout Standard
-\backslash
-/
-\end_inset
+and
+\layout Verse
--directory option should be -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+switch (i) {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 9:\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 10:\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 11:\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 12:\SpecialChar ~
+...
+
+\newline
+}
\layout Standard
-\backslash
-/
-\end_inset
+then both the switch statements will be implemented using jump-tables whereas
+ the unmodified switch statement will not be.
+ You might also consider dummy cases 0 and 5 to 8 in this example.
+ The pragma NOJTBOUND
+\begin_inset LatexCommand \index{\#pragma NOJTBOUND}
--directory=/home/src1:/home/src2.
- Note there can be no spaces in the option.
-
-\layout Itemize
+\end_inset
--cd <directory> - change to the <directory>.
-\layout Itemize
+ can be used to turn off checking the
+\emph on
+j
+\emph default
+ump
+\emph on
+t
+\emph default
+able
+\emph on
+bound
+\emph default
+aries.
+\layout Subsubsection
--fullname - used by GUI front ends.
-\layout Itemize
+Bit-shifting Operations
+\begin_inset LatexCommand \index{Bit shifting}
--cpu <cpu-type> - this argument is passed to the simulator please see the
- simulator docs for details.
-\layout Itemize
+\end_inset
--X <Clock frequency > this options is passed to the simulator please see
- the simulator docs for details.
-\layout Itemize
+.
+\layout Standard
--s <serial port file> passed to simulator see the simulator docs for details.
-\layout Itemize
+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.:
+\layout Verse
--S <serial in,out> passed to simulator see the simulator docs for details.
-\layout Subsection
-Debugger Commands.
+\family typewriter
+unsigned char i;
+\newline
+...
+
+\newline
+i >>= 4;
+\newline
+...
\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
+generates the following code:
+\layout Verse
-break [line | file:line | function | file:function]
-\layout Standard
-Set breakpoint at specified line or function:
+\family typewriter
+mov\SpecialChar ~
+ a,_i
\newline
-
+swap a
+\newline
+anl\SpecialChar ~
+ a,#0x0f
\newline
+mov\SpecialChar ~
+ _i,a
+\layout Standard
-\family sans
-\series bold
-sdcdb>break 100
+In general SDCC will never setup a loop if the shift count is known.
+ Another example:
+\layout Verse
+
+
+\family typewriter
+unsigned int i;
\newline
-sdcdb>break foo.c:100
+...
+
\newline
-sdcdb>break funcfoo
+i >>= 9;
\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
+will generate:
+\layout Verse
-\newline
-\family sans
-\series bold
-sdcdb>clear 100
+\family typewriter
+mov\SpecialChar ~
+\SpecialChar ~
+a,(_i + 1)
\newline
-sdcdb>clear foo.c:100
+mov\SpecialChar ~
+\SpecialChar ~
+(_i + 1),#0x00
\newline
-sdcdb>clear funcfoo
+clr\SpecialChar ~
+\SpecialChar ~
+c
\newline
-sdcdb>clear foo.c:funcfoo
-\layout Subsubsection
-
-continue
+rrc\SpecialChar ~
+\SpecialChar ~
+a
+\newline
+mov\SpecialChar ~
+\SpecialChar ~
+_i,a
\layout Standard
-Continue program being debugged, after breakpoint.
-\layout Subsubsection
+Note that SDCC stores numbers in little-endian
+\begin_inset LatexCommand \index{little-endian}
-finish
-\layout Standard
+\end_inset
-Execute till the end of the current function.
-\layout Subsubsection
-delete [n]
-\layout Standard
+\begin_inset LatexCommand \index{Endianness}
-Delete breakpoint number 'n'.
- If used without any option clear ALL user defined break points.
-\layout Subsubsection
+\end_inset
-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.
+ format (i.e.
+ lowest order first).
\layout Subsubsection
-step
-\layout Standard
-
-Step program until it reaches a different source line.
-\layout Subsubsection
+Bit-rotation
+\begin_inset LatexCommand \index{Bit rotation}
-next
-\layout Standard
+\end_inset
-Step program, proceeding through subroutine calls.
-\layout Subsubsection
-run
\layout Standard
-Start debugged program.
-\layout Subsubsection
-
-ptype variable
-\layout Standard
+A special case of the bit-shift operation is bit rotation, SDCC recognizes
+ the following expression to be a left bit-rotation:
+\layout Verse
-Print type information of the variable.
-\layout Subsubsection
-print variable
-\layout Standard
+\family typewriter
+unsigned char i;
+\newline
+...
+
+\newline
+i = ((i << 1) | (i >> 7));
+\family default
-print value of variable.
-\layout Subsubsection
+\newline
-file filename
+\family typewriter
+...
\layout Standard
-load the given file name.
- Note this is an alternate method of loading file for debugging.
-\layout Subsubsection
-
-frame
-\layout Standard
+will generate the following code:
+\layout Verse
-print information about current frame.
-\layout Subsubsection
-set srcmode
+\family typewriter
+mov\SpecialChar ~
+\SpecialChar ~
+a,_i
+\newline
+rl\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+a
+\newline
+mov\SpecialChar ~
+\SpecialChar ~
+_i,a
\layout Standard
-Toggle between C source & assembly source.
-\layout Subsubsection
+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.:
+\layout Verse
-! 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.
+\family typewriter
+i = ((i >> 7) | (i << 1)); /* left-bit rotation */
\layout Subsubsection
-quit.
-\layout Standard
-
-"Watch me now.
- Iam going Down.
- My name is Bobby Brown"
-\layout Subsection
-
-Interfacing with XEmacs
-\begin_inset LatexCommand \index{XEmacs}
+Highest Order Bit
+\begin_inset LatexCommand \index{Highest Order Bit}
\end_inset
-\begin_inset LatexCommand \index{Emacs}
-
-\end_inset
-
-.
\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
+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.:
+\layout Verse
-\newline
\family typewriter
-(load-file sdcdbsrc.el)
-\family default
-
+unsigned int gint;
\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:
+foo () {
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+unsigned char hob;
\newline
-
-\family sans
-\series bold
-ESC-x sdcdbsrc
-\family default
-\series default
-
+\SpecialChar ~
+\SpecialChar ~
+...
+
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+hob = (gint >> 15) & 1;
\newline
-You will prompted to enter the file name to be debugged.
+\SpecialChar ~
+\SpecialChar ~
+..
\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
+will generate the following code:
+\layout Verse
-\SpecialChar ~
\family typewriter
-
-\newline
-;; Current Listing ::
-\newline
-;;key\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 ~
-Comment
+ 61 ;\SpecialChar ~
+ hob.c 7
\newline
-;;---\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+000A E5*01\SpecialChar ~
\SpecialChar ~
-------\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 62\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
---------
-\newline
-;;
+ a,(_gint + 1)
\newline
-;; n\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdb-next-from-src\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+000C 23\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB next command
-\newline
-;; b\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-back-from-src\SpecialChar ~
+ 63\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ rl\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-SDCDB back command
+ a
\newline
-;; c\SpecialChar ~
+000D 54 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- sdcdb-cont-from-src\SpecialChar ~
\SpecialChar ~
+ 64\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ anl\SpecialChar ~
\SpecialChar ~
-SDCDB continue command
+ a,#0x01
\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
-;; ?\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdb-whatis-c-sexp\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SDCDB ptypecommand 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 ~
-\SpecialChar ~
-\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
-;; x\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdbsrc-delete\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-SDCDB Delete all breakpoints 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 ~
-given or delete arg (C-u arg x)
-\newline
-;; m\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdbsrc-frame\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\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 ~
-\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 ~
-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 ~
-\SpecialChar ~
-\SpecialChar ~
+000F F5*02\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ 65\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ mov\SpecialChar ~
\SpecialChar ~
- buffer point
+ _foo_hob_1_1,a
+\layout Standard
+
+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.:
+\layout Verse
+
+
+\family typewriter
+xyz = gint + ((gint >> 15) & 1);
+\layout Standard
+
+will still be recognized.
+\layout Subsubsection
+
+Peephole Optimizer
+\begin_inset LatexCommand \index{Peephole optimizer}
+
+\end_inset
+
+
+\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
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-peep-file
+\begin_inset LatexCommand \index{-\/-peep-file}
+
+\end_inset
+
+ <filename>
+\emph default
+ option.
+ The rule language is best illustrated with examples.
+\layout Verse
+
+
+\family typewriter
+replace {
\newline
-;; g\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
+mov %1,a
\newline
-;; t\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdbsrc-mode\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+mov a,%1
+\newline
+} by {
+\newline
\SpecialChar ~
\SpecialChar ~
+mov %1,a
+\newline
+}
+\layout Standard
+
+The above rule will change the following assembly
+\begin_inset LatexCommand \index{Assembler routines}
+
+\end_inset
+
+ sequence:
+\layout Verse
+
+
+\family typewriter
+mov r1,a
+\newline
+mov a,r1
+\layout Standard
+
+to
+\layout Verse
+
+
+\family typewriter
+mov r1,a
+\layout Standard
+
+Note: All occurrences of a
+\emph on
+%n
+\emph default
+ (pattern variable) must denote the same string.
+ With the above rule, the assembly sequence:
+\layout Verse
+
+
+\family typewriter
+mov r1,a
+\newline
+mov a,r2
+\layout Standard
+
+will remain unmodified.
+\newline
+
+\newline
+Other special case optimizations may be added by the user (via
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-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
+\layout Verse
+
+
+\family typewriter
+replace { lcall %1 } by { acall %1 }
+\newline
+replace { ljmp %1 } by { ajmp %1 }
+\layout Standard
+
+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:
+\layout Verse
+
+
+\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 ~
-Toggles Sdcdbsrc mode (turns it off)
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' [if <functionName> ] '
+\backslash
+n'
+\layout Standard
+
+<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:
+\layout Verse
+
+
+\family typewriter
+replace restart {
\newline
-;; C-c C-f\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdb-finish-from-src\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+pop %1
+\newline
\SpecialChar ~
\SpecialChar ~
+push %1 } by {
+\newline
\SpecialChar ~
\SpecialChar ~
-SDCDB finish command
+; nop
\newline
-;;
+}
+\layout Standard
+
+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.:
+\layout Verse
+
+
+\family typewriter
+pop ar1
\newline
-;; C-x SPC\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdb-break\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-Set break for line with point
+pop ar2
\newline
-;; ESC t\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdbsrc-mode\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-Toggle Sdcdbsrc mode
+push ar2
+\newline
+push ar1
+\layout Standard
+
+would result in:
+\layout Verse
+
+
+\family typewriter
+pop ar1
+\newline
+; nop
+\newline
+push ar1
+\layout Standard
+
+
+\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:
+\layout Verse
+
+
+\family typewriter
+; nop
+\newline
+; nop
+\layout Standard
+
+A conditional function can be attached to a rule.
+ Attaching rules are somewhat more involved, let me illustrate this with
+ an example.
+\layout Verse
+
+
+\family typewriter
+replace {
\newline
-;; ESC m\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- sdcdbsrc-srcmode\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ljmp %5
+\newline
+%2:
+\newline
+} by {
+\newline
\SpecialChar ~
- Toggle list mode
+ \SpecialChar ~
+ \SpecialChar ~
+sjmp %5
\newline
-;;
-\family default
-
+%2:
\newline
+} if labelInRange
+\layout Standard
-\layout Section
+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.
+ Currently implemented are
+\emph on
+labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
+ 24bitMode, portIsDS390, 24bitModeAndPortDS390
+\emph default
+and
+\emph on
+ notVolatile
+\emph default
+.
+\layout Standard
+
+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 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 -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-peep-file option.
+\layout Subsection
+
+Library Routines
+\emph on
+
+\layout Standard
+
+
+\emph on
+<pending: this is messy and incomplete>
+\emph default
+
+\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 Standard
+
+Libraries
+\begin_inset LatexCommand \index{Libraries}
+
+\end_inset
+
+ included in SDCC should have a license at least as liberal as the GNU Lesser
+ General Public License
+\begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
+
+\end_inset
+
+
+\emph on
+LGPL
+\emph default
+.
+\layout Comment
+
+license statements for the libraries are missing.
+ sdcc/device/lib/ser_ir.c
+\layout Comment
-Other Processors
+or _decdptr f.e.
+ come with a GPL (as opposed to LGPL) License - this will not be liberal
+ enough for many embedded programmers.
\layout Subsection
-The Z80 and gbz80 port
-\layout Standard
-
-SDCC can target both the Zilog
-\begin_inset LatexCommand \index{Z80}
+External Stack
+\begin_inset LatexCommand \label{sub:External-Stack}
\end_inset
- and the Nintendo Gameboy's Z80-like gbz80
-\begin_inset LatexCommand \index{GameBoy Z80}
+
+\begin_inset LatexCommand \index{stack}
\end_inset
-.
- The port is incomplete - long support is incomplete (mul, div and mod are
- unimplemented), and both float and bitfield support is missing.
- Apart from that the code generated is correct.
-\layout Standard
-As always, the code is the authoritative reference - see z80/ralloc.c and
- z80/gen.c.
- The stack frame is similar to that generated by the IAR Z80 compiler.
- IX is used as the base pointer, HL is used as a temporary register, and
- BC and DE are available for holding variables.
- IY is currently unused.
- Return values are stored in HL.
- 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
-\pagebreak_top
-Support
-\begin_inset LatexCommand \index{Support}
+\begin_inset LatexCommand \index{External stack}
\end_inset
\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 Standard
+The external stack (-
+\begin_inset ERT
+status Collapsed
-The SDCC project is hosted on the sdcc sourceforge site at
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
+\layout Standard
+\backslash
+/
\end_inset
-.
- You'll find the complete set of mailing lists
-\begin_inset LatexCommand \index{Mailing list}
+-xstack option
+\begin_inset LatexCommand \index{-\/-xstack}
\end_inset
-, forums, bug reporting system, patch submission
-\begin_inset LatexCommand \index{Patch submission}
+) is located at the start of the external ram segment, and is 256 bytes
+ in size.
+ When -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- system, download
-\begin_inset LatexCommand \index{download}
+-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 -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
- area and cvs code repository
-\begin_inset LatexCommand \index{cvs code repository}
+-stack-auto
+\begin_inset LatexCommand \index{-\/-stack-auto}
\end_inset
- there.
+ 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
-Reporting Bugs
-\begin_inset LatexCommand \index{Bugs}
+ANSI-Compliance
+\begin_inset LatexCommand \index{ANSI-compliance}
\end_inset
-\begin_inset LatexCommand \index{Reporting bugs}
+\layout Standard
-\end_inset
+Deviations from the compliance:
+\layout Itemize
+functions are not always reentrant.
+\layout Itemize
-\layout Standard
+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.:
+\begin_deeper
+\layout Verse
-The recommended way of reporting bugs is using the infrastructure of the
- sourceforge site.
- You can follow the status of bug reports there and have an overview about
- the known bugs.
-\layout Standard
-Bug reports are automatically forwarded to the developer mailing list and
- will be fixed ASAP.
- When reporting a bug, it is very useful to include a small test program
- (the smaller the better) 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 -
-\begin_inset ERT
-status Collapsed
+\family typewriter
+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) /* 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
+}
+\end_deeper
+\layout Itemize
-\layout Standard
+'long long
+\begin_inset LatexCommand \index{long long (not supported)}
-\backslash
-/
\end_inset
--dumpall
-\begin_inset LatexCommand \index{-\/-dumpall}
+' (64 bit integers
+\begin_inset LatexCommand \index{int (64 bit) (not supported)}
\end_inset
- option can sometimes be useful in locating optimization problems.
- When reporting a bug please maker sure you:
-\layout Enumerate
+) not supported.
+\layout Itemize
-Attach the code you are compiling with SDCC.
-
-\layout Enumerate
+'double
+\begin_inset LatexCommand \index{double (not supported)}
-Specify the exact command you use to run SDCC, or attach your Makefile.
-
-\layout Enumerate
+\end_inset
-Specify the SDCC version (type "sdcc -v"), your platform, and operating
- system.
-
-\layout Enumerate
+' precision floating point
+\begin_inset LatexCommand \index{Floating point support}
-Provide an exact copy of any error message or incorrect output.
-
-\layout Enumerate
+\end_inset
-Put something meaningful in the subject of your message.
-\layout Standard
+not supported.
+\layout Itemize
-Please attempt to include these 5 important parts, as applicable, in all
- requests for support or when reporting any problems or bugs with SDCC.
- Though this will make your message lengthy, it will greatly improve your
- chance that SDCC users and developers will be able to help you.
- Some SDCC developers are frustrated by bug reports without code provided
- that they can use to reproduce and ultimately fix the problem, so please
- be sure to provide sample code if you are reporting a bug!
-\layout Standard
+No support for setjmp and longjmp (for now).
+\layout Itemize
-Please have a short check that you are using a recent version of SDCC and
- the bug is not yet known.
- This is the link for reporting bugs:
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
+Old K&R style
+\begin_inset LatexCommand \index{K\&R style}
\end_inset
-.
-\layout Subsection
-
-Requesting Features
-\begin_inset LatexCommand \index{Feature request}
-
-\end_inset
+ function declarations are NOT allowed.
+\begin_deeper
+\layout Verse
-\begin_inset LatexCommand \index{Requesting features}
+\family typewriter
+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
+}
+\end_deeper
+\layout Itemize
-\end_inset
+functions declared as pointers must be dereferenced during the call.
+\begin_deeper
+\layout Verse
-\layout Standard
+\family typewriter
+int (*foo)();
+\newline
+...
+
+\newline
+/* has to be called like this */
+\newline
+(*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
+\end_deeper
+\layout Subsection
-Like bug reports feature requests are forwarded to the developer mailing
- list.
- This is the link for requesting features:
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
+Cyclomatic Complexity
+\begin_inset LatexCommand \index{Cyclomatic complexity}
\end_inset
-.
-\layout Subsection
-Getting Help
\layout Standard
-These links should take you directly to the
-\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
+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
-\end_inset
+\newline
+SDCC uses the following formula to compute the complexity:
+\newline
+\layout Standard
-\begin_inset Foot
-collapsed false
+complexity = (number of edges in control flow graph) - (number of nodes
+ in control flow graph) + 2;
+\newline
-\layout Standard
+\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 Subsection
-Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
- automated messages (mid 2003)
-\end_inset
+Other Processors
+\layout Subsubsection
- and the
-\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
+MCS51 variants
+\begin_inset LatexCommand \index{MCS51 variants}
\end_inset
-, lists and forums are archived so if you are lucky someone already had
- a similar problem.
-\layout Subsection
-
-ChangeLog
-\begin_inset LatexCommand \index{Changelog}
-\end_inset
+\layout Standard
+MCS51 processors are available from many vendors and come in many different
+ flavours.
+ While they might differ considerably in respect to Special Function Registers
+ the core MCS51 is usually not modified or is kept compatible.
+
+\layout Subsubsection*
+pdata access by SFR
\layout Standard
-You can follow the status of the cvs version
-\begin_inset LatexCommand \index{version}
+With the upcome of devices with internal xdata and flash memory devices
+ using port P2 as dedicated I/O port is becoming more popular.
+ Switching the high byte for pdata
+\begin_inset LatexCommand \index{pdata}
\end_inset
- of SDCC by watching the file
-\begin_inset LatexCommand \htmlurl[ChangeLog]{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
+ access which was formerly done by port P2 is then achieved by a Special
+ Function Register.
+ In well-established MCS51 tradition the address of this
+\emph on
+sfr
+\emph default
+ is where the chip designers decided to put it.
+ As pdata addressing is used in the startup code for the initialization
+ of xdata variables a separate startup code should be used as described
+ in section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
\end_inset
- in the cvs-repository.
-\layout Subsection
+.
+\layout Subsubsection*
-Release policy
-\begin_inset LatexCommand \index{Release policy}
+Other Features available by SFR
+\layout Standard
+
+Some MCS51 variants offer features like Double DPTR
+\begin_inset LatexCommand \index{DPTR}
\end_inset
+, multiple DPTR, decrementing DPTR, 16x16 Multiply.
+ These are currently not used for the MCS51 port.
+ If you absolutely need them you can fall back to inline assembly or submit
+ a patch to SDCC.
+\layout Subsubsection
+The Z80 and gbz80 port
\layout Standard
-Historically there often were long delays between official releases and
- the sourceforge download area tends to get not updated at all.
- Current excuses might refer to problems with live range analysis, but if
- this is fixed, the next problem rising is that another excuse will have
- to be found.
- Kidding aside, we have to get better there! On the other hand there are
- daily snapshots available at
-\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
+SDCC can target both the Zilog
+\begin_inset LatexCommand \index{Z80}
\end_inset
-, and you can always built the very last version (hopefully with many bugs
- fixed, and features added) from the source code available at
-\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
+ and the Nintendo Gameboy's Z80-like gbz80
+\begin_inset LatexCommand \index{GameBoy Z80}
\end_inset
.
-\layout Subsection
-
-Examples
-\begin_inset LatexCommand \index{Examples}
+ The Z80 port is passed through the same
+\emph on
+regressions tests
+\begin_inset LatexCommand \index{Regression test}
\end_inset
+\emph default
+ as MCS51 and DS390 ports, so floating point support, support for long variables
+ and bitfield support is fine.
\layout Standard
-You'll find some small examples in the directory sdcc/device/examples/
-\layout Comment
-
-Maybe we should include some links to real world applications.
- Preferably pointer to pointers (one for each architecture) so this stays
- manageable here?
+As always, the code is the authoritative reference - see z80/ralloc.c and
+ z80/gen.c.
+ The stack frame is similar to that generated by the IAR Z80 compiler.
+ IX is used as the base pointer, HL is used as a temporary register, and
+ BC and DE are available for holding variables.
+ IY is currently unused.
+ Return values are stored in HL.
+ One bad side effect of using IX as the base pointer is that a functions
+ stack frame is limited to 127 bytes - this will be fixed in a later version.
\layout Subsection
-Quality control
-\begin_inset LatexCommand \index{Quality control}
+Retargetting for other MCUs.
+\layout Standard
-\end_inset
+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 -
+\begin_inset ERT
+status Collapsed
\layout Standard
-The compiler is passed through nightly compile and build checks.
- The so called
-\shape italic
-regression tests
-\shape default
+\backslash
+/
+\end_inset
-\begin_inset LatexCommand \index{Regression test}
+-dumpraw option.
+\layout Itemize
-\end_inset
+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
- check that SDCC itself compiles flawlessly on several platforms and checks
- the quality of the code generated by SDCC by running the code through simulator
+\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.
- There is a separate document
-\shape italic
-test_suite.pdf
-\begin_inset LatexCommand \index{Test suite}
+ Live range analysis
+\begin_inset LatexCommand \index{Live range analysis}
\end_inset
+ is essential for register allocation, since these computation determines
+ which of these iTemps will be assigned to registers, and for how long.
+\layout Itemize
-\shape default
- about this.
-\layout Standard
-
-You'll find the test code in the directory
-\shape italic
-sdcc/support/regression
-\shape default
-.
- You can run these tests manually by running
-\family sans
-make
-\family default
- in this directory (or f.e.
-
-\family sans
-make test-mcs51
-\family default
- if you don't want to run the complete tests).
- The test code might also be interesting if you want to look for examples
-\begin_inset LatexCommand \index{Examples}
-
-\end_inset
+Phase five is register allocation.
+ There are two parts to this process.
+\newline
- checking corner cases of SDCC or if you plan to submit patches
-\begin_inset LatexCommand \index{Patch submission}
+\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
-\end_inset
+\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
-.
-\layout Standard
+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
-The pic port uses a different set of regression tests, you'll find them
- in the directory
-\shape italic
-sdcc/src/regression
-\shape default
-.
+As mentioned in the optimization section the peep-hole optimizer is rule
+ based system, which can reprogrammed for other MCUs.
\layout Section
\pagebreak_top
Compiler internals