\textclass book
\begin_preamble
+
\usepackage[
pdftitle={SDCC Compiler User Guide},
pdfauthor={SDCC development team},
\size normal
-SDCC 2.4.3
+SDCC 2.4.6
\size footnotesize
\newline
\emph on
C
\emph default
-ompiler) is a Freeware, retargettable, optimizing ANSI-C compiler by
+ompiler) is an open source, retargettable, optimizing ANSI-C compiler by
+
\series bold
Sandeep Dutta
\series default
It can be retargetted for other microprocessors, support for Microchip
PIC, Atmel AVR is under development.
The entire source code for the compiler is distributed under GPL.
- SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
+ SDCC uses ASXXXX
+\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
+
+\end_inset
+
+ & ASLINK
+\begin_inset LatexCommand \index{aslink}
+
+\end_inset
+
+, an open source retargettable assembler & linker.
SDCC has extensive language extensions suitable for utilizing various microcont
rollers and underlying hardware effectively.
All packages used in this compiler system are
\emph on
-opensource
+open source
\emph default
and
\emph on
\layout Standard
Of course this doesn't change the search paths compiled into the binaries.
+\newline
+
+\newline
+Moreover the install path can be changed by defining DESTDIR
+\begin_inset LatexCommand \index{DESTDIR}
+
+\end_inset
+
+:
+\layout LyX-Code
+
+make install DESTDIR=$(HOME)/sdcc.rpm/
+\layout Standard
+
+Please note that DESTDIR must have a trailing slash!
\layout Section
Search Paths
And use an editor which can handle LF-only line endings.
Make sure not to commit files with windows line endings.
The tabulator spacing
-\begin_inset LatexCommand \index{tabulator spacing (8)}
+\begin_inset LatexCommand \index{tabulator spacing (8 columns)}
\end_inset
used in the project is 8.
+ Although a tabulator spacing of 8 is a sensible choice for programmers
+ (it's a power of 2 and allows to display 8/16 bit signed variables without
+ loosing columns) the plan is to move towards using only spaces in the source.
\layout Subsection
Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
\series default
- Pass the inline assembler code through the peep hole optimizer.
+ Pass the inline assembler code through the peep hole optimizer.
This can cause unexpected changes to inline assembler code, please go through
the peephole optimizer
\begin_inset LatexCommand \index{Peephole optimizer}
rules defined in the source file tree '<target>/peeph.def' before using
this option.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-opt-code-speed
+\begin_inset LatexCommand \index{-\/-opt-code-speed}
+
+\end_inset
+
+
+\series default
+ The compiler will optimize code generation towards fast code, possibly
+ at the expense of code size.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-opt-code-size
+\begin_inset LatexCommand \index{-\/-opt-code-size}
+
+\end_inset
+
+
+\series default
+ The compiler will optimize code generation towards compact code, possibly
+ at the expense of code speed.
\layout Subsection
Other Options
\series bold
-
\begin_inset ERT
-status Open
+status Collapsed
\layout Standard
\labelwidthstring 00.00.0000
+\series bold
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-disable-warning\SpecialChar ~
+<nnnn>
+\begin_inset LatexCommand \index{-\/-disable-warning}
+
+\end_inset
+
+
+\series default
+ Disable specific warning with number <nnnn>.
+\layout List
+\labelwidthstring 00.00.0000
+
+
\series bold
-
\begin_inset ERT
0x7ffe unsigned int chksum;
\layout Standard
-In the above example the variable chksum will located at 0x7ffe and 0x7fff
+In the above example the variable chksum will be located at 0x7ffe and 0x7fff
of the external ram.
The compiler does
\emph on
\emph on
volatile
\emph default
- have to be used to tell the compiler that accesses might not be optimized
- away:
+ has to be used to tell the compiler that accesses might not be removed:
\layout Verse
If the access to these variables is not
\emph on
atomic
-\begin_inset LatexCommand \index{atomic access}
+\begin_inset LatexCommand \index{atomic}
\end_inset
\end_inset
for details on customizing startup.
+\layout Subsection
+
+Z80 Interrupt Service Routines
+\layout Standard
+
+The Z80 uses several different methods for determining the correct interrupt
+ vector depending on the hardware implementation.
+ Therefore, SDCC ignores the optional interrupt number and does not attempt
+ to generate an interrupt vector table.
+\layout Standard
+
+By default, SDCC generates code for a maskable interrupt, which uses an
+ RETI instruction to return from the interrupt.
+ To write an interrupt handler for the non-maskable interrupt, which needs
+ an RETN instruction instead, add the
+\emph on
+critical
+\emph default
+ keyword:
+\layout Verse
+
+
+\family typewriter
+void nmi_isr (void) critical interrupt
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
\layout Section
Enabling and Disabling Interrupts
and don't add complexity unless you have to.
+\layout Subsection
+
+Semaphore
+\begin_inset LatexCommand \index{semaphore}
+
+\end_inset
+
+ locking (mcs51/ds390)
+\layout Standard
+
+Some architectures (mcs51/ds390) have an atomic
+\begin_inset LatexCommand \index{atomic}
+
+\end_inset
+
+ bit test and
+\emph on
+
+\emph default
+clear
+\emph on
+
+\emph default
+instruction.
+ These type of instructions are typically used in preemptive multitasking
+ systems, where a routine f.e.
+ claims the use of a data structure ('acquires a lock
+\begin_inset LatexCommand \index{lock}
+
+\end_inset
+
+ on it'), makes some modifications and then releases the lock when the data
+ structure is consistent again.
+ The instruction may also be used if interrupt and non-interrupt code have
+ to compete for a resource.
+ With the atomic bit test and clear instruction interrupts
+\begin_inset LatexCommand \index{interrupt}
+
+\end_inset
+
+ don't have to be disabled for the locking operation.
+
+\layout Standard
+
+SDCC generates this instruction if the source follows this pattern:
+\layout Verse
+
+
+\family typewriter
+volatile bit resource_is_free;
+\newline
+
+\newline
+if (resource_is_free)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+resource_is_free=0;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+resource_is_free=1;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+}
+\layout Standard
+
+Note, mcs51 and ds390 support only an atomic
+\begin_inset LatexCommand \index{atomic}
+
+\end_inset
+
+ bit test and
+\emph on
+clear
+\emph default
+ instruction (as opposed to atomic bit test and
+\emph on
+set).
\layout Section
Functions using private register banks
in sdcc/device/lib.
\layout Standard
+The default
+\family typewriter
+ printf()
+\begin_inset LatexCommand \index{printf()}
+
+\end_inset
+
+
+\family default
+implementation in
+\family typewriter
+ printf_large.c
+\family default
+ does not support float (except on ds390).
+ To enable this recompile it with the option
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+DUSE_FLOATS=1
+\begin_inset LatexCommand \index{USE\_FLOATS}
+
+\end_inset
+
+
+\emph default
+ on the command line.
+ Use
+\emph on
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-model-large
+\begin_inset LatexCommand \index{-\/-model-large}
+
+\end_inset
+
+
+\emph default
+ for the mcs51 port, since this uses a lot of memory.
+\layout Standard
+
If you're short on memory you might want to use
\family typewriter
printf_small()
\emph default
of
\family typewriter
- printf()
-\begin_inset LatexCommand \index{printf()}
-
-\end_inset
-
-.
+ printf().
\family default
For the mcs51 there is an assembly version
your own now ;-(
\layout Itemize
+disable_warning <nnnn>
+\begin_inset LatexCommand \index{\#pragma disable\_warning}
+
+\end_inset
+
+ - the compiler will not warn you anymore about warning number <nnnn>.
+\layout Itemize
+
nogcse
\begin_inset LatexCommand \index{\#pragma nogcse}
\end_inset
Parameters and Local Variables.
+\layout Itemize
+
+opt_code_speed
+\begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
+
+\end_inset
+
+- The compiler will optimize code generation towards fast code, possibly
+ at the expense of code size.
+\layout Itemize
+
+opt_code_size
+\begin_inset LatexCommand \index{\#pragma opt\_code\_size}
+
+\end_inset
+
+- The compiler will optimize code generation towards compact code, possibly
+ at the expense of code speed.
+\layout Itemize
+
+opt_code_balanced
+\begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
+
+\end_inset
+
+- The compiler will attempt to generate code that is both compact and fast,
+ as long as meeting one goal is not a detriment to the other (this is the
+ default).
+
\layout Standard
SDCPP supports the following #pragma directives:
/
\end_inset
--stack-auto Auto variables that are function parameters, will be saved on
- stack by default.
-
-\emph on
-There is no need to specify this in the command line.
-\layout List
-\labelwidthstring 00.00.0000
-
--
+-callee-saves See -
\begin_inset ERT
status Collapsed
/
\end_inset
--float-reent All floating point functions are reentrant by default.
-
-\emph on
-There is no need to specifiy this in the command line.
-\layout List
-\labelwidthstring 00.00.0000
-
--
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--callee-saves See -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
-
-\backslash
-/
-\end_inset
-
--all-callee-saves
+-all-callee-saves
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--pgen-bank Instructs the port to insert BANKSEL directives before instructions
- that use the Bank Select Register (BSR).
+-nodefaultlibs do not link default libraries when linking.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--pomit-config-words Instructs the port to omit the generation of the configurati
-on words.
+-obanksel=# Set optimization level for inserting BANKSELs.
+\begin_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+0 is no optimization
+\layout List
+\labelwidthstring 00.00.0000
+
+1 checkes previous used register and if it is the same then doesn't emit
+ BANKSEL, accounts only for labels.
+\end_deeper
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--pomit-ivt Instructs the port to omit the generation of the interrupt vectors
+-pomit-config-words Omit the generation of the configuration words.
\layout List
\labelwidthstring 00.00.0000
/
\end_inset
--pleave-reset-vector Used in conjuction with the previous command, instructs
- the port NOT to omit the reset vector.
+-pomit-ivt Omit the generation of the interrupt vectors.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pleave-reset-vector Used in conjuction with -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pomit-ivt, instructs the port NOT to omit the reset vector.
\layout List
\labelwidthstring 00.00.0000
\end_inset
-link= sets the full path and name of an external linker to call.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-call-tree dump call tree in .calltree file
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-mplab-comp MPLAB compatibility option.
+ Currently only suppresses special gpasm directives.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-use-crt= Use a custom run-time module instead of the defaults.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-no-crt Don't link the default run-time modules
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-flr-support When entering/leaving a function, call support functions to
+ store/restore used registers
\layout Subsubsection
Debugging Options
\end_inset
-pcode-verbose Enable pcode debugging information in translation.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-denable-peeps Force the usage of peepholes.
+ Use with care.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-gstack Trace push/pops for stack pointer overflow
\layout Subsection
Preprocessor Macros
\layout List
\labelwidthstring 00.00.0000
+code place a function symbol at static FLASH address
+\layout LyX-Code
+
+Example:
+\layout LyX-Code
+
+\layout LyX-Code
+
+/* place function test_func at 0x4000 */
+\layout LyX-Code
+
+#pragma code test_func 0x4000
+\layout List
+\labelwidthstring 00.00.0000
+
udata pragma udata instructs the compiler to emit code so that linker will
place a variable at a specific memory bank
\layout LyX-Code
\layout Standard
-ASXXXX Assemblers and ASLINK Relocating Linker
+ASXXXX
+\begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Assembler documentation}
+
+\end_inset
+
+ Assemblers and ASLINK
+\begin_inset LatexCommand \index{aslink}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Linker documentation}
+
+\end_inset
+
+ Relocating Linker
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\SpecialChar ~
global = 2;
\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
}
\layout Subsection
\layout Standard
-SDCC changes switch statements to jump tables
+SDCC can optimize switch statements to jump tables
\begin_inset LatexCommand \index{jump tables}
\end_inset
- when the following conditions are true.
-
+.
+ It makes the decision based on an estimate of the generated code size.
+ SDCC is quite liberal in the requirements for jump table generation:
\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.
+The labels need not be in order, and the starting number need not be one
+ or zero, the case labels are in numerical sequence or not too many case
+ labels are missing.
\begin_deeper
\layout Verse
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-case 2: ...
-
+
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
case 3: ...
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...\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 4: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 8: ...\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 5: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 9: ...\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 6: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 10: ...\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 7: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 11: ...\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 8: ...
+
\newline
}\SpecialChar ~
\SpecialChar ~
\end_deeper
\layout Itemize
-The number of case labels is at least three, since it takes two conditional
- statements to handle the boundary conditions.
+The number of case labels is not larger than supported by the target architectur
+e.
+\layout Itemize
+
+If the case labels are not in numerical sequence ('gaps' between cases)
+ SDCC checks whether a jump table with additionally inserted dummy cases
+ is still attractive.
+
\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.
+If the starting number is not zero and a check for the lower boundary of
+ the jump-table can thus be eliminated SDCC might insert dummy cases 0,
+ ...
+ .
\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
+Switch statements which have large gaps in the numeric sequence or those
+ that have too many case labels can be split into more than one switch statement
for efficient code generation, e.g.:
\layout Verse
\newline
\SpecialChar ~
\SpecialChar ~
-case 9: ...
+case 5: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 101: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 10: ...
+case 102: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 11: ...
+case 103: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 12: ...
+case 104: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 105: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 106: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 107: ...
\newline
}
\SpecialChar ~
case 4: ...
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 5: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 6: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 7: ...
+
\newline
}
\layout Standard
\newline
\SpecialChar ~
\SpecialChar ~
-case 9:\SpecialChar ~
+case 101: ...
+
+\newline
\SpecialChar ~
-...
+\SpecialChar ~
+case 102: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 10:\SpecialChar ~
-...
+case 103: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 11:\SpecialChar ~
-...
+case 104: ...
\newline
\SpecialChar ~
\SpecialChar ~
-case 12:\SpecialChar ~
-...
+case 105: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 106: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 107: ...
\newline
}
then both the switch statements will be implemented using jump-tables whereas
the unmodified switch statement will not be.
- You might also consider inserting dummy cases 0 and 5 to 8 in this example.
-
-\newline
+\layout Comment
+
+There might be reasons which SDCC cannot know about to either favour or
+ not favour jump tables.
+ If the target system has to be as quick for the last switch case as for
+ the first (pro jump table), or if the switch argument is known to be zero
+ in the majority of the cases (contra jump table).
+\layout Standard
+
The pragma nojtbound
\begin_inset LatexCommand \index{\#pragma nojtbound}
\series bold
\shape italic
\color red
-<Where is Figure II ?>
+<Where is Figure II?>
+\layout Comment
+
+In the original article Figure II was announced to be downloadable on
+\shape italic
+Circuit Cellar
+\shape default
+'s web site.
+ Unfortunately it never seemed to have shown up there, so: where is Figure
+ II?
\layout Paragraph*
ICode Example
projects / fw / sdcc / blobdiff