SDCC Compiler User Guide

Table of Contents

1  Introduction

1.1  About SDCC

• global sub expression elimination,
• loop optimizations (loop invariant, strength reduction of induction variables and loop reversing),
• constant folding & propagation,
• copy propagation,
• dead code elimination
• jump tables for switch statements.

• char (8 bits, 1 byte),
• short and int (16 bits, 2 bytes),
• long (32 bit, 4 bytes)
• float (4 byte IEEE).

1.2  Open Source

1.3  Typographic conventions

1.4  Compatibility with previous versions

• short is now equivalent to int (16 bits), it used to be equivalent to char (8 bits) which is not ANSI compliant
• the default directory for gcc-builds where include, library and documentation files are stored is now in /usr/local/share
• char type parameters to vararg functions are casted to int unless explicitly casted, e.g.:
    char a=3; 
    printf ("%d %cn", a, (char)a);
  will push a as an int and as a char resp.
• option --regextend has been removed
• option --noregparms has been removed
• option --stack-after-data has been removed

1.5  System Requirements

1.6  Other Resources

1.7  Wishes for the future

2  Installing SDCC

2.1  Configure Options

--prefix

see table below

--exec_prefix

see table below

--bindir

see table below

--datadir

see table below

docdir

environment variable, see table below

include_dir_suffix

environment variable, see table below

lib_dir_suffix

environment variable, see table below

sdccconf_h_dir_separator

environment variable, either / or makes sense here. This character will only be used in sdccconf.h; don't forget it's a C-header, therefore a double-backslash is needed there.

--disable-mcs51-port

Excludes the Intel mcs51 port

--disable-gbz80-port

Excludes the Gameboy gbz80 port

--z80-port

Excludes the z80 port

--disable-avr-port

Excludes the AVR port

--disable-ds390-port

Excludes the DS390 port

--disable-pic-port

Excludes the PIC port

--disable-xa51-port

Excludes the XA51 port

--disable-ucsim

Disables configuring and building of ucsim

--disable-device-lib-build

Disables automatically building device libraries

--disable-packihx

Disables building packihx

--enable-libgc

Use the Bohem memory allocator. Lower runtime footprint.

1. open source,
2. a gcc compiler and last but not least
3. the binaries can be built by cross compiling on Sourceforge's compile farm.

2.2  Install paths

2.3  Search Paths

2.4  Building SDCC

2.4.1  Building SDCC on Linux

1. Download the source package either from the SDCC CVS repository or from the nightly snapshots http://sdcc.sourceforge.net/snap.php, it will be named something like sdcc.src.tar.gz.
2. Bring up a command line terminal, such as xterm.
3. Unpack the file using a command like: "tar -xvzf sdcc.src.tar.gz", this will create a sub-directory called sdcc with all of the sources.
4. Change directory into the main SDCC directory, for example type: "cd sdcc".
5. Type "./configure". This configures the package for compilation on your system.
6. Type "make". All of the source packages will compile, this can take a while.
7. Type "make install" as root. This copies the binary executables, the include files, the libraries and the documentation to the install directories.

2.4.2  Building SDCC on OSX 2.x

2.4.3  Cross compiling SDCC on Linux for Windows

2.4.4  Building SDCC on Windows

2.4.5  Building SDCC using Cygwin and Mingw32

• flex
• bison
• gcc ; version 3.x is fine, no need to use the old 2.9x
• binutils ; selected with gcc
• make
• rxvt ; a nice console, which makes life much easier under windoze (see below)
• man ; not really needed for building SDCC, but you'll miss it sooner or later
• less ; not really needed for building SDCC, but you'll miss it sooner or later
• cvs ; only if you use CVS access

• python ; for the regression tests
• gdb ; the gnu debugger, together with the nice GUI ''insight''
• openssh ; to access the CF or commit changes
• autoconf and autoconf-devel ; if you want to fight with 'configure', don't use autoconf-stable!

2.4.6  Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)

1. The easy way:
   
   a) Extract UnxUtils.zip to your C: hard disk PRESERVING the original paths, otherwise bison won't work. (If you are using WinZip make certain that 'Use folder names' is selected)
   
   b) In the Visual C++ IDE click Tools, Options, select the Directory tab, in 'Show directories for:' select 'Executable files', and in the directories window add a new path: 'C:userlocalwbin', click ok.
   
   (As a side effect, you get a bunch of Unix utilities that could be useful, such as diff and patch.)
2. A more compact way:
   
   This one avoids extracting a bunch of files you may not use, but requires some extra work:
   
   a) Create a directory were to put the tools needed, or use a directory already present. Say for example 'C:util'.
   
   b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe to such directory WITHOUT preserving the original paths. (If you are using WinZip make certain that 'Use folder names' is not selected)
   
   c) Rename bison.exe to '_bison.exe'.
   
   d) Create a batch file 'bison.bat' in 'C:util' and add these lines:
     set BISON_SIMPLE=C:utilbison.simple
     set BISON_HAIRY=C:utilbison.hairy
     _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
   
   Steps 'c' and 'd' are needed because bison requires by default that the files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory, '/usr/local/share/' I think. So it is necessary to tell bison where those files are located if they are not in such directory. That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
   
   e) In the Visual C++ IDE click Tools, Options, select the Directory tab, in 'Show directories for:' select 'Executable files', and in the directories window add a new path: 'c:util', click ok. Note that you can use any other path instead of 'c:util', even the path where the Visual C++ tools are, probably: 'C:Program FilesMicrosoft Visual StudioCommonTools'. So you don't have to execute step 'e' :)

2.4.7  Building SDCC Using Borland

1. From the sdcc directory, run the command "make -f Makefile.bcc". This should regenerate all the .exe files in the bin directory except for sdcdb.exe (which currently doesn't build under Borland C++).
2. If you modify any source files and need to rebuild, be aware that the dependencies may not be correctly calculated. The safest option is to delete all .obj files and run the build again. From a Cygwin BASH prompt, this can easily be done with the command (be sure you are in the sdcc directory):
   
   find . ( -name '*.obj' -o -name '*.lib' -o -name '*.rul' ) -print -exec rm {} ;
   
   or on Windows NT/2000/XP from the command prompt with the command:
   
   del /s *.obj *.lib *.rul from the sdcc directory.

2.4.8  Windows Install Using a Binary Package

1. Download the binary package from http://sdcc.sourceforge.net/snap.php 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:sdccbin for the executables, c:sdccinclude and c:sdcclib for the include and libraries.
2. Adjust your environment variable PATH to include the location of the bin directory or start sdcc using the full path.

2.5  Building the Documentation

2.6  Reading the Documentation

• It tries to document SDCC for several processor architectures in one document (commercially these probably would be separate documents/products). This document currently matches SDCC for mcs51 and DS390 best and does give too few information about f.e. Z80 and PIC.
• There are many references pointing away from this documentation. Don't let this distract you. If there f.e. was a reference like www.opencores.org together with a statement ''some processors which are targetted by SDCC can be implemented in a field programmable array'' we expect you to have a quick look there and come back. If you read this you are on the right track.
• Some sections attribute more space to problems, restrictions and warnings than to the solution.
• The installation section and the section about the debugger is intimidating.
• There are still lots of typos and there are more different writing styles than pictures.

2.7  Testing the SDCC Compiler

2.8  Install Trouble-shooting

2.8.1  SDCC does not build correctly.

2.8.2  What the ''./configure'' does

2.8.3  What the ''make'' does.

2.8.4  What the ''make install'' command does.

2.9  Components of SDCC

• sdcc - The compiler.
• sdcpp - The C preprocessor.
• asx8051 - The assembler for 8051 type processors.
• as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers.
• aslink -The linker for 8051 type processors.
• link-z80, link-gbz80 - The Z80 and GameBoy Z80 linkers.
• s51 - The ucSim 8051 simulator.
• sdcdb - The source debugger.
• packihx - A tool to pack (compress) Intel hex files.

• the include files

• the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled relocatables.

• the documentation

2.9.1  sdcc - The Compiler

2.9.2  sdcpp - The C-Preprocessor

2.9.3  asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 - The Assemblers and Linkage Editors

2.9.4  s51 - The Simulator

2.9.5  sdcdb - Source Level Debugger

3  Using SDCC

3.1  Compiling

3.1.1  Single Source File Projects

• sourcefile.asm - Assembler source file created by the compiler
• sourcefile.lst - Assembler listing file created by the Assembler
• sourcefile.rst - Assembler listing file updated with linkedit information, created by linkage editor
• sourcefile.sym - symbol listing for the sourcefile, created by the assembler
• sourcefile.rel - Object file created by the assembler, input to Linkage editor
• sourcefile.map - The memory map for the load module, created by the Linker
• sourcefile.mem - A file with a summary of the memory usage
• sourcefile.ihx - The load module in Intel hex format (you can select the Motorola S19 format with --out-fmt-s19. If you need another format you might want to use objdump or srecord)
• sourcefile.adb - An intermediate file containing debug information needed to create the .cdb file (with --debug)
• sourcefile.cdb - An optional file (with --debug) containing debug information
• sourcefile. - (no extension) An optional AOMF51 file containing debug information (with --debug). This format is commonly used by third party tools (debuggers, simulators, emulators)
• sourcefile.dump* - Dump file to debug the compiler it self (with --dumpall) (see section 3.2.918Intermediate Dump Options<A NAME="sub:Intermediate-Dump-Options"></A><A NAME="@default3"></A><A NAME="@default4"></A>subsubsection.3.2.9  and section 8.151The anatomy of the compiler<A NAME="sub:The-anatomy-of"></A>subsection.8.1 ''Anatomy of the compiler'').

3.1.2  Projects with Multiple Source Files

3.1.3  Projects with Additional Libraries

3.2  Command Line Options

3.2.1  Processor Selection Options

-mmcs51

Generate code for the Intel MCS51 family of processors. This is the default processor target.

-mds390

Generate code for the Dallas DS80C390 processor.

-mds400

Generate code for the Dallas DS80C400 processor.

-mz80

Generate code for the Zilog Z80 family of processors.

-mgbz80

Generate code for the GameBoy Z80 processor.

-mavr

Generate code for the Atmel AVR processor (In development, not complete). AVR users should probably have a look at avr-gcc http://savannah.nongnu.org/download/avr-libc/snapshots/.

-mpic14

Generate code for the Microchip PIC 14-bit processors (p16f84 and variants).

-mpic16

Generate code for the Microchip PIC 16-bit processors (p18f452 and variants).

-mtlcs900h

Generate code for the Toshiba TLCS-900H processor (In development, not complete).

-mxa51

Generate code for the Phillips XA51 processor (In development, not complete).

3.2.2  Preprocessor Options

-Ipath

The additional location where the pre processor will look for ..h or ``..h'' files.

-Dmacro[=value]

Command line definition of macros. Passed to the preprocessor.

-M

Tell the preprocessor to output a rule suitable for make describing the dependencies of each object file. For each source file, the preprocessor outputs one make-rule whose target is the object file name for that source file and whose dependencies are all the files `#include'd in it. This rule may be a single line or may be continued with `'-newline if it is long. The list of rules is printed on standard output instead of the preprocessed C program. `-M' implies `-E'.

-C

Tell the preprocessor not to discard comments. Used with the `-E' option.

-MM

Like `-M' but the output mentions only the user header files included with `#include ``file"'. System header files included with `#include file' are omitted.

-Aquestion(answer)

Assert the answer answer for question, in case it is tested with a preprocessor conditional such as `#if #question(answer)'. `-A-' disables the standard assertions that normally describe the target machine.

-Umacro

Undefine macro macro. `-U' options are evaluated after all `-D' options, but before any `-include' and `-imacros' options.

-dM

Tell the preprocessor to output only a list of the macro definitions that are in effect at the end of preprocessing. Used with the `-E' option.

-dD

Tell the preprocessor to pass all macro definitions into the output, in their proper sequence in the rest of the output.

-dN

Like `-dD' except that the macro arguments and contents are omitted. Only `#define name' is included in the output.

3.2.3  Linker Options

-L --lib-path

absolute path to additional libraries This option is passed to the linkage editor's additional libraries search path. The path name must be absolute. Additional library files may be specified in the command line. See section Compiling programs for more details.

--xram-locValue

The start location of the external ram, default value is 0. The value entered can be in Hexadecimal or Decimal format, e.g.: --xram-loc 0x8000 or --xram-loc 32768.

--code-locValue

The start location of the code segment, default value 0. Note when this option is used the interrupt vector table is also relocated to the given address. The value entered can be in Hexadecimal or Decimal format, e.g.: --code-loc 0x8000 or --code-loc 32768.

--stack-locValue

By default the stack is placed after the data segment. Using this option the stack can be placed anywhere in the internal memory space of the 8051. The value entered can be in Hexadecimal or Decimal format, e.g. --stack-loc 0x20 or --stack-loc 32. Since the sp register is incremented before a push or call, the initial sp will be set to one byte prior the provided value. The provided value should not overlap any other memory areas such as used register banks or the data segment and with enough space for the current application.

--data-locValue

The start location of the internal ram data segment. The value entered can be in Hexadecimal or Decimal format, eg. --data-loc 0x20 or --data-loc 32. (By default, the start location of the internal ram data segment is set as low as possible in memory, taking into account the used register banks and the bit segment at address 0x20. For example if register banks 0 and 1 are used without bit variables, the data segment will be set, if --data-loc is not used, to location 0x10.)

--idata-locValue

The start location of the indirectly addressable internal ram, default value is 0x80. The value entered can be in Hexadecimal or Decimal format, eg. --idata-loc 0x88 or --idata-loc 136.

--out-fmt-ihx

The linker output (final object code) is in Intel Hex format. (This is the default option).

--out-fmt-s19

The linker output (final object code) is in Motorola S19 format.

3.2.4  MCS51 Options

--model-small

Generate code for Small Model programs see section Memory Models for more details. This is the default model.

--model-large

Generate code for Large model programs see section Memory Models for more details. If this option is used all source files in the project have to be compiled with this option.

--xstack

Uses a pseudo stack in the first 256 bytes in the external ram for allocating variables and passing parameters. See section 7.347External Stack<A NAME="sub:External-Stack"></A><A NAME="@default13"></A><A NAME="@default14"></A>subsection.7.3  External Stack for more details.

--iram-sizeValue

Causes the linker to check if the internal ram usage is within limits of the given value.

--xram-sizeValue

Causes the linker to check if the external ram usage is within limits of the given value.

--code-sizeValue

Causes the linker to check if the code memory usage is within limits of the given value.

3.2.5  DS390 Options

--model-flat24

Generate 24-bit flat mode code. This is the one and only that the ds390 code generator supports right now and is default when using -mds390. See section Memory Models for more details.

--stack-10bit

Generate code for the 10 bit stack mode of the Dallas DS80C390 part. This is the one and only that the ds390 code generator supports right now and is default when using -mds390. In this mode, the stack is located in the lower 1K of the internal RAM, which is mapped to 0x400000. Note that the support is incomplete, since it still uses a single byte as the stack pointer. This means that only the lower 256 bytes of the potential 1K stack space will actually be used. However, this does allow you to reclaim the precious 256 bytes of low RAM for use for the DATA and IDATA segments. The compiler will not generate any code to put the processor into 10 bit stack mode. It is important to ensure that the processor is in this mode before calling any re-entrant functions compiled with this option. In principle, this should work with the --stack-auto option, but that has not been tested. It is incompatible with the --xstack option. It also only makes sense if the processor is in 24 bit contiguous addressing mode (see the --model-flat24 option).

3.2.6  Z80 Options

--callee-saves-bc

Force a called function to always save BC.

--no-std-crt0

When linking, skip the standard crt0.o object file. You must provide your own crt0.o for your system when linking.

3.2.7  Optimization Options

--nogcse

Will not do global subexpression elimination, this option may be used when the compiler creates undesirably large stack/data spaces to store compiler temporaries. A warning message will be generated when this happens and the compiler will indicate the number of extra bytes it allocated. It recommended that this option NOT be used, #pragma NOGCSE can be used to turn off global subexpression elimination for a given function only.

--noinvariant

Will not do loop invariant optimizations, this may be turned off for reasons explained for the previous option. For more details of loop optimizations performed see section Loop Invariants.It recommended that this option NOT be used, #pragma NOINVARIANT can be used to turn off invariant optimizations for a given function only.

--noinduction

Will not do loop induction optimizations, see section strength reduction for more details.It is recommended that this option is NOT used, #pragma NOINDUCTION can be used to turn off induction optimizations for a given function only.

--nojtbound

Will not generate boundary condition check when switch statements are implemented using jump-tables. See section 7.1.743'switch' Statements<A NAME="sub:'switch'-Statements"></A><A NAME="@default11"></A>subsubsection.7.1.7 Switch Statements for more details. It is recommended that this option is NOT used, #pragma NOJTBOUND can be used to turn off boundary checking for jump tables for a given function only.

--noloopreverse

Will not do loop reversal optimization.

--nolabelopt

Will not optimize labels (makes the dumpfiles more readable).

--no-xinit-opt

Will not memcpy initialized data from code space into xdata space. This saves a few bytes in code space if you don't have initialized data.

3.2.8  Other Options

-c --compile-only

will compile and assemble the source, but will not call the linkage editor.

--c1mode

reads the preprocessed source from standard input and compiles it. The file name for the assembler output must be specified using the -o option.

-E

Run only the C preprocessor. Preprocess all the C source files specified and output the results to standard output.

-o path/file

The output path resp. file where everything will be placed. If the parameter is a path, it must have a trailing slash (or backslash for the Windows binaries) to be recognized as a path.

--stack-auto

All functions in the source file will be compiled as reentrant, i.e. the parameters and local variables will be allocated on the stack. see section Parameters and Local Variables for more details. If this option is used all source files in the project should be compiled with this option.

--callee-saves

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 the register saving convention for the function names specified. The compiler will not save registers when calling these functions, no extra code will be generated at the entry & exit (function prologue & epilogue) 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) will be able to determine the appropriate scheme to use for each function call. DO NOT use this option for built-in functions such as _mulint..., if this option is used for a library function the appropriate library function needs to be recompiled with the same option. If the project consists of multiple source files then all the source file should be compiled with the same --callee-saves option string. Also see #pragma CALLEE-SAVES.

--debug

When this option is used the compiler will generate debug information, that can be used with the SDCDB. The debug information is collected in a file with .cdb extension. For more information see documentation for SDCDB.

-S

Stop after the stage of compilation proper; do not assemble. The output is an assembler code file for the input file specified.

-Wa_asmOption[,asmOption]...

Pass the asmOption to the assembler.

-Wl_linkOption[,linkOption]...

Pass the linkOption to the linker.

--int-long-reent

Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant. Note by default these libraries are compiled as non-reentrant. See section Installation for more details.

--cyclomatic

This option will cause the compiler to generate an information message for each function in the source file. The message contains some important information about the function. The number of edges and nodes the compiler detected in the control flow graph of the function, and most importantly the cyclomatic complexity see section on Cyclomatic Complexity for more details.

--float-reent

Floating point library is compiled as reentrant. See section Installation for more details.

--nooverlay

The compiler will not overlay parameters and local variables of any function, see section Parameters and local variables for more details.

--main-return

This option can be used when the code generated is called by a monitor program. The compiler will generate a 'ret' upon return from the 'main' function. The default setting is to lock up i.e. generate a 'ljmp .'.

--peep-filefilename

This option can be used to use additional rules to be used by the peep hole optimizer. See section 7.1.1145Peephole Optimizer<A NAME="sub:Peephole-Optimizer"></A><A NAME="@default12"></A>subsubsection.7.1.11 Peep Hole optimizations for details on how to write these rules.

--no-peep

Disable peep-hole optimization.

--peep-asm

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 rules defined in the source file tree 'target/peeph.def' before using this option.

--nostdincl

This will prevent the compiler from passing on the default include path to the preprocessor.

--nostdlib

This will prevent the compiler from passing on the default library path to the linker.

--verbose

Shows the various actions the compiler is performing.

-V

Shows the actual commands the compiler is executing.

--no-c-code-in-asm

Hides your ugly and inefficient c-code from the asm file, so you can always blame the compiler :).

--i-code-in-asm

Include i-codes in the asm file. Sounds like noise but is most helpful for debugging the compiler itself.

--less-pedantic

Disable some of the more pedantic warnings (jwk burps: please be more specific here, please!). If you want rather more than less warnings you should consider using a separate tool dedicated to syntax checking like www.splint.org.

--print-search-dirs

Display the directories in the compiler's search path

--vc

Display errors and warnings using MSVC style, so you can use SDCC with visual studio.

--use-stdout

Send errors and warnings to stdout instead of stderr.

3.2.9  Intermediate Dump Options

--dumpraw

This option will cause the compiler to dump the intermediate code into a file of named source filename.dumpraw just after the intermediate code has been generated for a function, i.e. before any optimizations are done. The basic blocks at this stage ordered in the depth first number, so they may not be in sequence of execution.

--dumpgcse

Will create a dump of iCode's, after global subexpression elimination, into a file named source filename.dumpgcse.

--dumpdeadcode

Will create a dump of iCode's, after deadcode elimination, into a file named source filename.dumpdeadcode.

--dumploop

Will create a dump of iCode's, after loop optimizations, into a file named source filename.dumploop.

--dumprange

Will create a dump of iCode's, after live range analysis, into a file named source filename.dumprange.

--dumlrange

Will dump the life ranges for all symbols.

--dumpregassign

Will create a dump of iCode's, after register assignment, into a file named source filename.dumprassgn.

--dumplrange

Will create a dump of the live ranges of iTemp's

--dumpall

Will cause all the above mentioned dumps to be created.

3.2.10  Redirecting output on Windows Shells

3.3  Environment variables

SDCC_LEAVE_SIGNALS

SDCC installs a signal handler to be able to delete temporary files after an user break (C) or an exception. If this environment variable is set, SDCC won't install the signal handler in order to be able to debug SDCC.

TMP, TEMP, TMPDIR

Path, where temporary files will be created. The order of the variables is the search order. In a standard *nix environment these variables are not set, and there's no need to set them. On Windows it's recommended to set one of them.

SDCC_HOME

Path, see section 2.26Install paths<A NAME="sub:Install-paths"></A><A NAME="@default0"></A>subsection.2.2 '' Install Paths''.

SDCC_INCLUDE

Path, see section ?? ''Search Paths''.

SDCC_LIB

Path, see section ?? ''Search Paths''..

3.4  MCS51/DS390 Storage Class Language Extensions

3.4.1  data

3.4.2  xdata

3.4.3  idata

3.4.4  pdata

3.4.5  code

3.4.6  bit

3.4.7  sfr / sbit

3.4.8  Pointers to MCS51/DS390 specific memory spaces

3.5  Absolute Addressing

3.6  Parameters & Local Variables

3.7  Overlaying

3.8  Interrupt Service Routines

3.9  Critical Functions

3.10  Functions using private banks

3.11  Startup Code

3.11.1  MCS51/DS390 Startup Code

3.11.2  Z80 Startup Code

3.12  Inline Assembler Code

3.12.1  A Step by Step Introduction

3.12.2  Naked Functions

3.12.3  Use of Labels within Inline Assembler

3.13  Interfacing with Assembler Code

3.13.1  Global Registers used for Parameter Passing

3.13.2  Assembler Routine(non-reentrant)

3.13.3  Assembler Routine(reentrant)

3.14  int (16 bit) and long (32 bit) Support

3.15  Floating Point Support

3.16  MCS51 Memory Models

3.17  DS390 Memory Models

3.18  Pragmas

• SAVE - this will save all current options to the SAVE/RESTORE stack. See RESTORE.
• RESTORE - 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.
• NOGCSE - will stop global common subexpression elimination.
• NOINDUCTION - will stop loop induction optimizations.
• NOJTBOUND - will not generate code for boundary value checking, when switch statements are turned into jump-tables (dangerous). For more details see section 7.1.743'switch' Statements<A NAME="sub:'switch'-Statements"></A><A NAME="@default11"></A>subsubsection.7.1.7.
• NOOVERLAY - the compiler will not overlay the parameters and local variables of a function.
• LESS_PEDANTIC - the compiler will not warn you anymore for obvious mistakes, you'r on your own now ;-(
• NOLOOPREVERSE - Will not do loop reversal optimization
• EXCLUDE NONE {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of pair of push/pop instruction in ISR function (using interrupt 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 EXCLUDE none.
• NOIV - Do not generate interrupt vector table entries for all ISR functions defined after the pragma. This is useful in cases where the interrupt vector table must be defined manually, or when there is a secondary, manually defined interrupt vector table (e.g. for the autovector feature of the Cypress EZ-USB FX2). More elegantly this can be achieved by obmitting the optional interrupt number after the interrupt keyword, see section ?? about interrupts.
• CALLEE-SAVES 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 --callee-saves command line option is used, the function names specified in #pragma CALLEE-SAVES is appended to the list of functions specified in the command line.

3.19  Defines Created by the Compiler

4  Debugging with SDCDB

4.1  Compiling for Debugging

4.2  How the Debugger Works

4.3  Starting the Debugger

• foo.c - the source file.
• foo.cdb - the debugger symbol information file.
• foo.ihx - the Intel hex format object file.

4.4  Command Line Options.

• --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 --directory option should be --directory=/home/src1:/home/src2. Note there can be no spaces in the option.
• -cd directory - change to the directory.
• -fullname - used by GUI front ends.
• -cpu cpu-type - this argument is passed to the simulator please see the simulator docs for details.
• -X Clock frequency this options is passed to the simulator please see the simulator docs for details.
• -s serial port file passed to simulator see the simulator docs for details.
• -S serial in,out passed to simulator see the simulator docs for details.

4.5  Debugger Commands.

break [line file:line function file:function]

clear [line file:line function file:function ]

continue

finish

delete [n]

info [break stack frame registers ]

• info break - list all breakpoints
• info stack - show the function call stack.
• info frame - show information about the current execution frame.
• info registers - show content of all registers.

step

next

run

ptype variable

print variable

file filename

frame

set srcmode

! simulator command

quit.

4.6  Interfacing with XEmacs.

• sdcdbsrc-cpu-type '51
• sdcdbsrc-frequency '11059200
• sdcdbsrc-serial nil

5  TIPS

• 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'.
• 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.
• NEVER jump into a LOOP.
• Declare the variables to be local whenever possible, especially loop control variables (induction).
• Since the compiler does not always do implicit integral promotion, the programmer should do an explicit cast when integral promotion is required.
• Reducing the size of division, multiplication & modulus operations can reduce code size substantially. Take the following code for example.
  
  foobar(unsigned int p1, unsigned char ch) 
  { 
      unsigned char ch1 = p1 % ch ; 
      .... 
  } 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
  
  foobar(unsigned int p1, unsigned char ch) 
  { 
      unsigned char ch1 = (unsigned char)p1 % ch ; 
      .... 
  } It would substantially reduce the code generated (future versions of the compiler will be smart enough to detect such optimization opportunities).
  
  
• Have a look at the assembly listing to get a ''feeling'' for the code generation.

5.1  Notes on MCS51 memory layout

5.2  Tools included in the distribution

5.3  Related open source tools

5.4  Related documentation / recommended reading

6  Support

6.1  Reporting Bugs

1. Attach the code you are compiling with SDCC.
2. Specify the exact command you use to run SDCC, or attach your Makefile.
3. Specify the SDCC version (type "sdcc -v"), your platform, and operating system.
4. Provide an exact copy of any error message or incorrect output.
5. Put something meaningful in the subject of your message.

6.2  Requesting Features

6.3  Getting Help

6.4  ChangeLog

6.5  Release policy

6.6  Examples

6.7  Quality control

7  SDCC Technical Data

7.1  Optimizations

7.1.1  Sub-expression Elimination

7.1.2  Dead-Code Elimination

7.1.3  Copy-Propagation

7.1.4  Loop Optimizations

7.1.5  Loop Reversing

• The 'for' loop is of the form
  
  for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym> += 1]) 
      <for body>
• The for body does not contain ``continue'' or 'break''.
• All goto's are contained within the loop.
• No function calls within the loop.
• The loop control variable sym is not assigned any value within the loop
• The loop control variable does NOT participate in any arithmetic operation within the loop.
• There are NO switch statements in the loop.

7.1.6  Algebraic Simplifications

7.1.7  'switch' Statements

• The case labels are in numerical sequence, the labels need not be in order, and the starting number need not be one or zero.
  
  switch(i) {                          switch (i) {  
     case 4: ...                          case 0: ...  
     case 5: ...                          case 1: ...  
     case 3: ...                          case 2: ...  
     case 6: ...                          case 3: ...  
  }                                    } 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.
  
  
• 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 less than 84, since each label takes 3 bytes and a jump-table can be utmost 256 bytes long.

7.1.8  Bit-shifting Operations.

7.1.9  Bit-rotation

7.1.10  Highest Order Bit

7.1.11  Peephole Optimizer

7.2  Library Routines

1. Compiler support routines (_gptrget, _mulint etc)
2. Stdclib functions (puts, printf, strcat etc)
3. Math functions (sin, pow, sqrt etc)

7.3  External Stack

7.4  ANSI-Compliance

• functions are not always reentrant.
• 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.:
  
  struct s { ... };  
  struct s s1, s2;  
  foo()  
  {  
      ...  
      s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */  
      ...  
  } 
  struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI */ 
  {  
      struct s rets;  
      ...  
      return rets;/* is invalid in SDCC although allowed in ANSI */  
  }
• 'long long' (64 bit integers) not supported.
• 'double' precision floating point not supported.
• No support for setjmp and longjmp (for now).
• Old K&R style function declarations are NOT allowed.
  
  foo(i,j) /* this old style of function declarations */  
  int i,j; /* are valid in ANSI but not valid in SDCC */  
  {  
      ...  
  }
• functions declared as pointers must be dereferenced during the call.
  
  int (*foo)(); 
  ...  
  /* has to be called like this */  
  (*foo)(); /* ANSI standard allows calls to be made like 'foo()' */

7.5  Cyclomatic Complexity

7.6  Other Processors

7.6.1  MCS51 variants

pdata access by SFR

Other Features available by SFR

7.6.2  The Z80 and gbz80 port

7.7  Retargetting for other MCUs.

• 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.
• 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 --dumpraw option.
• This phase does the bulk of the standard optimizations and is also MCU independent. This phase can be broken down into several sub-phases:
  
  Break down intermediate code (iCode) into basic blocks.
  Do control flow & data flow analysis on the basic blocks.
  Do local common subexpression elimination, then global subexpression elimination
  Dead code elimination
  Loop optimizations
  If loop optimizations caused any changes then do 'global subexpression elimination' and 'dead code elimination' again.
• This phase determines the live-ranges; by live range I mean those iTemp variables defined by the compiler that still survive after all the optimizations. Live range analysis is essential for register allocation, since these computation determines which of these iTemps will be assigned to registers, and for how long.
• Phase five is register allocation. There are two parts to this process.
  
  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.
  
  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.
• 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.
• As mentioned in the optimization section the peep-hole optimizer is rule based system, which can reprogrammed for other MCUs.

8  Compiler internals

8.1  The anatomy of the compiler

Parsing

Generating iCode

Optimizations.

Live range analysis

Register Allocation

Code generation

ICode Example

8.2  A few words about basic block successors, predecessors and dominators

9  Acknowledgments

10  Alphabetical index

Index

1

Obviously this has pros and cons

2

possible exception: if a function is called ONLY from 'interrupt' functions using a particular bank, it can be declared with the same 'using' attribute as the calling 'interrupt' functions. For instance, if you have several ISRs using bank one, and all of them call memcpy(), it might make sense to create a specialized version of memcpy() 'using 1', since this would prevent the ISR from having to save bank zero to the stack on entry and switch to bank zero before calling the function

3

The assembler does not like some characters like ':' or ''' in comments.

4

Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting automated messages (mid 2003)

5

Usually 8-bit processors don't care much about endianness. This is not the case for the standard 8051 which only has an instruction to increment its dptr-datapointer so little-endian is the more efficient byte order.

This document was translated from L^AT_EX by H^EV^EA.