[fw/sdcc] / doc / SDCCUdoc.txt

SDCC Compiler User Guide

Sandeep Dutta (sandeep.dutta@usa.net)

1 Introduction

SDCC is a Free ware , retargettable, optimizing ANSI-C compiler. The
current version targets Intel 8051 based MCUs, it can be retargetted
for other 8 bit MCUs or PICs. The entire source code for the compiler
is distributed under GPL. SDCC used ASXXXX & ASLINK a Free ware, retargettable
assembler & linker. SDCC has extensive MCU (8051) specific language
extensions, which lets it utilize the underlying hardware effectively.
The front-end (parser) will be enhanced to handle language extensions
for other MCUs as and when they are targetted. In addition to the
MCU Specific optimizations SDCC also does a host of standard optimizations
like global sub expression elimination, loop optimizations (loop invariant,
strength reduction of induction variables and loop reversing), constant
folding & propagation, copy propagation, dead code elimination and
jumptables for 'switch' statements. For the back-end SDCC uses a global
register allocation scheme which should be well suited for other 8
bit MCUs , the peep hole optimizer uses a rule based substitution
mechanism which is MCU independent. Supported data-types are short
(8 bits, 1 byte), char (8 bits, 1 byte), int (16 bits, 2 bytes ),
long (32 bit, 4 bytes) & float (4 byte IEEE). The compiler also allows
inline assembler code to be embedded anywhere in a function. In addition
routines developed in assembly can also be called. SDCC also provides
an option to report the relative complexity of a function, these functions
can then be further optimized , or hand coded in assembly if need
be. SDCC also comes with a companion source level debugger SDCDB,
the debugger currently uses S51 a freeware simulator for 8051, it
can be easily modified to use other simulators. The latest version
can be downloaded from http://www.geocities.com/ResearchTriangle/Forum/1353

All packages used in this compiler system are opensource (freeware);
source code for all the sub-packages ( asxxxx assembler/linker , pre-processor
and gc a conservative garbage collector) are distributed with the
package. Documentation was created using a freeware word processor
(LyX). 

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 2, or (at your option)
any later version. This program is distributed in the hope that it
will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
the GNU General Public License for more details. You should have received
a copy of the GNU General Public License along with this program;
if not, write to the Free Software Foundation, 59 Temple Place - Suite
330, Boston, MA 02111-1307, USA. In other words, you are welcome to
use, share and improve this program. You are forbidden to forbid anyone
else to use, share and improve what you give them. Help stamp out
software-hoarding! 

2 Installation \label{Installation}

What you need before you start installation of SDCC ? A C Compiler,
not just any C Compiler, gcc to be exact, you can get adventurous
and try another compiler , I HAVEN'T tried it. GCC is free , and is
available for almost all major platforms, if you are using linux you
probably already have it, if you are using Windows 95/NT go to www.cygnus.com
and download CYGWIN32 you will need the full development version of
their tool (full.exe), follow their instructions for installation
(this is also free and is very easy to install), Windows 95/NT users
be aware that the compiler runs substantially slower on the Windows
platform, I am not sure why.

After you have installed gcc you are ready to build the compiler (sorry
no binary distributions yet). SDCC is native to Linux but can be ported
to any platform on which GCC is available . Extract the source file
package (.zip or .tar.gz) into some directory , which we shall refer
to as SDCCDIR from now on.

2.1 Components of SDCC\label{Components}

2.1.1 gc ( a conservative garbage collector)

SDCC relies on this component to do all the memory management, this
excellent package is copyrighted by Jans J Boehm(boehm@sgi.com) and
Alan J Demers but can be used with minimum restrictions. The GC source
will be extracted into the directory SDCCDIR/gc. 

2.1.2 cpp ( C-Preprocessor)

The preprocessor is extracted into the directory SDCCDIR/cpp, it is
a modified version of the GNU preprocessor.

2.1.3 asxxxx & aslink ( The assembler and Linkage Editor)

This is retargettable assembler & linkage editor, it was developed
by Alan Baldwin, John Hartman created the version for 8051, and I
(Sandeep) have some enhancements and bug fixes for it to work properly
with the SDCC. This component is extracted into the directory SDCCDIR/asxxxx.

2.1.4 SDCC - The compiler.

This is the actual compiler, it uses gc and invokes the assembler and
linkage editor. All files with the prefix SDCC are part of the compiler
and is extracted into the the directory SDCCDIR.

2.1.5 S51 - Simulator

Version 2.1.8 onwards contains s51 a freeware , opensource simulator
developed by Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu>. The
executable is built as part of build process, for more information
visit Daniel's website at <http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51/>.

2.1.6 SDCDB - Source level Debugger.

SDCDB is the companion source level debugger . The current version
of the debugger uses Daniel's Simulator S51, but can be easily changed
to use other simulators.

2.2 Installation for Version <= 2.1.7

After the package is extracted (Windows 95/NT users start CYGWIN shell),
change to the directory where you extracted the package and give the
command.

./sdccbuild.sh

This is a bash shell script, it will compile all the above mentioned
components and install the executables into the directory SDCCDIR/bin
make sure you add this directory to your PATH environment variable.
This script will also compile all the support routines ( library routines
) using SDCC. The support routines are all developed in C and need
to be compiled.

2.3 Installation for Version >= 2.1.8a

The distribution method from Version 2.1.8a has been changed to be
conforment with the ``autoconf'' utility. The source is now distributed
as sdcc-<version number>.tar.gz format , instead of the older .zip
format. The steps for installation are as follows.

2.3.1 Unpack the sources.

This is usually done by the following command ``gunzip -c sdcc-<version
number>.tar.gz | tar -xv -``

2.3.2 Change to the main source directory (usually sdcc or sdcc-<version
  number>)

2.3.3 Issue command to configure your system

The configure command has several options the most commonly used option
is --prefix=<directory name>, where <directory name> is the final
location for the sdcc executables and libraries, (default location
is /usr/local). The installation process will create the following
directory structure under the <directory name> specified.

bin/ - binary exectables (add to PATH environment variable) 
share/ 
      sdcc51inc/ - include header files 
      sdcc51lib/ - 
             small/ - Object & Library files for small model library 
             large/ - Object & library files for large model library

The command 

'./configure --prefix=/usr/local'' 

will create configure the compiler to be installed in directory /usr/local/bin.

2.3.4 make

After configuration step issue the command 

``make''

This will compile the compiler

2.3.5 ``make install''

Will install the compiler and libraries in the appropriate directories.

2.3.6 Special Notes for Windows Users. Provided by Michael Jamet[ mjamet@computer.org] 

 

  How to install SDCC from source on a Windows 95 or Windows NT 4 system 

 

  This document describes how to install SDCC on a Win 95 or Win NT
4 system. 

  These instructions probably work for Win 98 as well, but have not
been 

  tested on that platform. 

 

  There are lots of little differences between UNIX and the Win32 Cygnus 

  environment which make porting more difficult than it should be.  If 

  you want the details, please contact me.  Otherwise just follow these 

  instructions. 

 

  1. Install the Cygnus Software 

  Go to http://sourceware.cygnus.com/cygwin.  Cygnus provides a UNIX
like 

  environment for Win 32 systems.  Download "full.exe" and install.  You 

  MUST install it on your C drive.  "full.exe" contains a shell AND many 

  common UNIX utilities. 

 

  2. Download and Extract the Latest SDCC 

  The latest version can be found at 

   www.geocities.com/ResearchTriange/Forum/1353. 

  It can be uncompressed with winzip. 

 

  3.  Start a Cygnus Shell 

  There should be an entry in the Start Menu for Cygnus.  Invoke the
shell. 

  This gives you a UNIX like environment.  FROM THIS POINT ON, DIRECTORIES 

  MUST BE SPECIFIED WITH FORWARD SLASHES (/) NOT THE DOS STYLE BACK 

  SLASHES (\) BECAUSE THIS IS WHAT UNIX EXPECTS.  - 

   ex. "\winnt" would be "/winnt" under the shell. 

 

  4. Change Directory to Where SDCC was extracted (referred to as INSTALLDIR) 

 

  ex. cd /sdcc218Da.  If you extracted to a drive OTHER THAN C, the drive 

  must be specified as part of the path. For example, if you extracted
to 

  your "g drive", type the following: "cd //g/mydir".  You must use "//" 

  to specify the drive. 

 

  5. Make Dirs Which are Automatically Made During the UNIX Installation 

  From the INSTALLDIR, 

 

   mkdir -p bin   (not a typo, just "bin") 

   mkdir -p /bin 

   mkdir -p /usr/local/bin 

   mkdir -p /usr/local/share 

   mkdir -p /usr/local/share/sdcc51lib 

   mkdir -p /usr/local/share/sdcc51inc 

   mkdir -p /tmp 

 

  (When a path from the root directory is specified WITHOUT a drive,
the 

  drive defaults to c.  For example /michael/newuser => c:\michael\newuser) 

 

  6.  Add Programs to /bin Expected by the Installation Process 

   - Look at your path: echo $PATH 

     One of the fields is the diretory with the CYGNUS programs. 

    ex. /CYGNUS/CYGWIN~1/H-I586/BIN 

 

   - cd to the directory found above.  You may have to fiddle with the 

     case (upper or lower) here because the PATH is SHOWN as all upper 

     case, but is actually mixed.  To help you along, you may type 

     a letter or 2 followed by the escape key.  The shell will fill 

     out the remaining letters IF THEY describe a unique directory. 

     If you have problems here, cd one directory and type "ls".  "ls" 

     is the equivalent of "dir/w". 

 

   - Copy the following: 

    cp sh.exe /bin 

    cp pwd.exe /bin 

    cp echo.exe /bin 

 

  7. Go back to the INSTALLDIR 

   cd INSTALLDIR 

  ex. cd //d/sdcc218Da 

 

  8. Run the configure Program 

   ./configure 

  The "./" is important because your current directory is NOT in your
path. 

  Under DOS, your current directory was implicitly always the first
entry 

  in your path. 

 

  9. Run make 

   make 

 

  This process takes quite some time under Win 32. 

 

  10. Install the Newly Built Software 

   make install 

 

  This will partially install the software into the /usr/local directories 

  created in step 5.  What it actually doing is copying the .c, .h and 

  library files to directories under /usr/local/share. 

 

  It will NOT be able to install the actual programs (binaries) because 

  it does not know programs on Win32 systems have ".exe" extensions. 

  For example, it tries to install sdcc instead of sdcc.exe. 

 

  After the automated part is finished, you must manually copy the binaries: 

   cd bin  (This is the bin directory in your INSTALLDIR) 

   cp * /usr/local/bin 

 

  11. Make sure /usr/local/bin is in Your PATH 

  You may add c:\usr\local\bin to your path however your Win32 system allows. 
For 

  example you may add it to the PATH statement in autoexec.bat. 

 

  Good luck.  If you have any questions send them to me or post them 

  to the list. 

3 Compiling.\label{Compiling}

3.1 Single Source file projects.\label{One Source File}

For single source file projects the process is very simple. Compile
your programs with the following command

sdcc sourcefile.c

The above command will compile ,assemble and link your source file.
Output files are as follows.

* 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.<ihx | s19> - The load module : ihx - Intel hex format
  (default ), s19 - Motorola S19 format when compiler option --out-fmt-s19
  is used.

3.2 Projects with multiple source files.

SDCC can compile only ONE file at a time. Let us for example assume
that you have a project containing the following files.

foo1.c ( contains some functions )

foo2.c (contains some more functions)

foomain.c (contains more functions and the function main)

The first two files will need to be compiled separately with the commands

sdcc -c foo1.c

sdcc -c foo2.c

Then compile the source file containing main and link the other files
together with the following command.

sdcc foomain.c foo1.rel foo2.rel

Alternatively foomain.c can be separately compiled as well

sdcc -c foomain.c 

sdcc foomain.rel foo1.rel foo2.rel

The file containing the main function MUST be the FIRST file specified
in the command line , since the linkage editor processes file in the
order they are presented to it.

3.3 Projects with additional libraries.

Some reusable routines may be compiled into a library, see the documentation
for the assembler and linkage editor in the directory SDCCDIR/asxxxx/asxhtm.htm
this describes how to create a .lib library file, the libraries created
in this manner may be included using the command line, make sure you
include the -L <library-path> option to tell the linker where to look
for these files. Here is an example, assuming you have the source
file 'foomain.c' and a library 'foolib.lib' in the directory 'mylib'.

sdcc foomain.c foolib.lib -L mylib

Note here that 'mylib' must be an absolute path name.

The view of the way the linkage editor processes the library files,
it is recommended that you put each source routine in a separate file
and combine them using the .lib file. For an example see the standard
library file 'libsdcc.lib' in the directory SDCCDIR/sdcc51lib.

4 Command Line options\label{Command Line Options}

* --model-large\label{--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 should be compiled with
  this option. In addition the standard library routines are compiled
  with small model , they will need to be recompiled.

* --model-small \label{--model-small}Generate code for Small Model
  programs see section Memory Models for more details. This is the
  default model.

* --stack-auto \label{--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. 

* --xstack\label{--xstack} Uses a pseudo stack in the first 256 bytes
  in the external ram for allocating variables and passing parameters.
  See section on external stack for more details.

* --nogcse\label{--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\label{--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\label{--noinduction} Will not do loop induction optimizations,
  see section Strength reduction for more details.It recommended that
  this option NOT be used , #pragma NOINDUCTION can be used to turn
  off induction optimizations for given function only.

* --nojtbound \label{--nojtbound} Will not generate boundary condition
  check when switch statements are implemented using jump-tables.
  See section Switch Statements for more details.It recommended that
  this option NOT be used , #pragma NOJTBOUND can be used to turn
  off boundary checking for jump tables for a given function only.

* --noloopreverse \label{--noloopreverse}Will not do loop reversal
  optimization

* --noregparms\label{--noregparms} By default the first parameter is
  passed using global registers (DPL,DPH,B,ACC). This option will
  disable parameter passing using registers. NOTE: if your program
  uses the 16/32 bit support routines (for multiplication/division)
  these library routines will need to be recompiled with the --noregparms
  option as well.

* --callee-saves function1[,function2][,function3].... \label{--callee-saves}The
  compiler by default uses a caller saves convention for register
  saving across function calls, however this can cause unneccessary
  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, extra code will be
  generated 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 future
  the compiler (with interprocedural 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 _muluint..., 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 Directive\ref{Pragmaa}
  CALLEE-SAVES.\ref{pragma callee-saves} .

* --debug \label{--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.

* --regextend \label{--regextend} This option will cause the compiler
  to define pseudo registers , if this option is used, all source
  files in the project should be compiled with this option. See section
  Register Extension for more details.

* --compile-only(-c) \label{--compile-only} will compile and assemble
  the source only, will not call the linkage editor.

* --xram-loc \label{--xram-loc}<Value> The start location of the external
  ram, default value is 0. The value entered can be in Hexadecimal
  or Decimal format .eg. --xram-loc 0x8000 or --xram-loc 32768.

* --code-loc \label{--code-loc}<Value> 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 .eg. --code-loc 0x8000 or
  --code-loc 32768.

* --stack-loc\label{--stack-loc}<Value> The initial value of the stack
  pointer. The default value of the stack pointer is 0x07 if only
  register bank 0 is used, if other register banks are used then the
  stack pointer is initialized to the location above the highest register
  bank used. eg. if register banks 1 & 2 are used the stack pointer
  will default to location 0x18. The value entered can be in Hexadecimal
  or Decimal format .eg. --stack-loc 0x20 or --stack-loc 32. If all
  four register banks are used the stack will be placed after the
  data segment (equivalent to --stack-after-data)

* --stack-after-data\label{--stack-after-data}This option will cause
  the stack to be located in the internal ram after the data segment.

* --data-loc \label{--data-loc}<Value> The start location of the internal
  ram data segment, the default value is 0x30.The value entered can
  be in Hexadecimal or Decimal format .eg. --data-loc 0x20 or --data-loc
  32.

* --idata-loc\label{--idata-loc}<Value> 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.

* --peep-file\label{--peep-file} <filename> This option can be used
  to use additional rules to be used by the peep hole optimizer. See
  section Peep Hole optimizations for details on how to write these
  rules.

* --lib-path (-L) \label{--lib-path}<absolute path to additional libraries>
  This option is passed to the linkage editor, 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.

* -I <path>\label{-I} The additional location where the pre processor
  will look for <..h> or ``..h'' files.

* -D<macro[=value]> \label{-D}Command line definition of macros. Passed
  to the pre processor.

* -E\label{-E} Run only the C preprocessor. Preprocess all the C source
  files specified and output the results to standard output.

* -M\label{-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 \label{-C}Tell the preprocessor not to discard comments. Used
  with the `-E' option.

* -MM \label{-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)\label{-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 asser-
  tions that normally describe the target machine.

* -Aquestion\label{-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\label{-Umacro} Undefine macro macro. `-U' options are evaluated
  after all `-D' options, but before any `-include' and `-imac- ros'
  options.

* -dM\label{-dM} Tell the preprocessor to output only a list of the
  mac- ro definitions that are in effect at the end of prepro- cessing.
  Used with the `-E' option.

* -dD \label{-dD}Tell the preprocessor to pass all macro definitions
  into the output, in their proper sequence in the rest of the output.

* -dN \label{-dN}Like `-dD' except that the macro arguments and contents
  are omitted. Only `#define name' is included in the output.

* -S \label{-S}Stop after the stage of compilation proper; do not as-
  semble. 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 \label{--int-long-rent} 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 \label{--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 \label{--float-reent} Floating point library is compiled
  as reentrant.See section Installation for more details.

* --out-fmt-ihx\label{--out-fmt-ihx} The linker output (final object
  code) is in Intel Hex format. (This is the default option).

* --out-fmt-s19 \label{--out-fmt-s19}The linker output (final object
  code) is in Motorola S19 format.

* --nooverlay \label{--nooverlay} The compiler will not overlay parameters
  and local variables of any function, see section Parameters and
  local variables for more details.

* --main-return\label{--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
  option is to lock up i.e. generate a 'ljmp .' .

* --no-peep \label{--no-peep} Disable peep-hole optimization.

* --peep-asm \label{--peep-asm} Pass the inline assembler code through
  the peep hole optimizer. Can cause unexpected changes to inline
  assembler code , please go through the peephole optimizer rules
  defnied in file 'SDCCpeeph.def' before using this option.

* --iram-size\label{--iram-size} <Value> Causes the linker to check
  if the interal ram usage is within limits of the given value.

The following options are provided for the purpose of retargetting
and debugging the compiler . These provided a means to dump the intermediate
code (iCode) generated by the compiler in human readable form at various
stages of the compilation process. 

* --dumpraw \label{--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.\label{--dumpgcse} Will create a dump if iCode, after
  global subexpression elimination, into a file named <source filename>.dumpgcse.

* --dumpdeadcode \label{--dumpdeadcode}.Will create a dump if iCode,
  after deadcode elimination, into a file named <source filename>.dumpdeadcode.

* --dumploop. \label{--dumploop}Will create a dump if iCode, after
  loop optimizations, into a file named <source filename>.dumploop.

* --dumprange. \label{--dump-range}Will create a dump if iCode, after
  live range analysis, into a file named <source filename>.dumprange.

* --dumpregassign. \label{--dumpregassign}Will create a dump if iCode,
  after register assignment , into a file named <source filename>.dumprassgn.

* --dumpall. \label{--dumpall}Will cause all the above mentioned dumps
  to be created.

Note that the files created for the dump are appended to each time.
So the files should be deleted manually , before each dump is created. 

When reporting bugs, it will be very helpful if you could include these
dumps along with the portion of the code that is causing the problem.

5 Language Extensions\label{Language Extension}

5.1 Storage Classes.\label{Storage Classes}

In addition to the ANSI storage classes SDCC allows the following 8051
specific storage classes.

5.1.1 xdata.\label{xdata}

Variables declared with this storage class will be placed in the extern
RAM. This is the default storage class for Large Memory model .

eg. xdata unsigned char xduc;

5.1.2 data\label{data}

This is the default storage class for Small Memory model. Variables
declared with this storage class will be allocated in the internal
RAM.

eg. data int iramdata;

5.1.3 idata\label{idata}

Variables declared with this storage class will be allocated into the
indirectly addressable portion of the internal ram of a 8051 .

eg.idata int idi;

5.1.4 bit\label{bit}

This is a data-type and a storage class specifier. When a variable
is declared as a bit , it is allocated into the bit addressable memory
of 8051.

eg.bit iFlag;

5.1.5 sfr / sbit\label{sfr / sbit}

Like the bit keyword, sfr / sbit signifies both a data-type and storage
class, they are used to describe the special function registers and
special bit variables of a 8051. 

eg. 

sfr at 0x80 P0; /* special function register P0 at location 0x80 */

sbit at 0xd7 CY; /* CY (Carry Flag) */

6 Optimizations\label{Optimizations}

SDCC performs a a host of standard optimizations in addition to some
MCU specific optimizations. 

6.1 Sub-expression elimination\label{Sub-expression Elimination}

The compiler does local and global common subexpression elimination.

eg. 

i = x + y + 1; 
j = x + y;

will be translated to

iTemp = x + y 
i = iTemp + 1 
j = iTemp

Some subexpressions are not as obvious as the above example.

eg.

a->b[i].c = 10; 
a->b[i].d = 11;

In this case the address arithmetic a->b[i] will be computed only once;
the equivalent code in C would be.

iTemp = a->b[i]; 
iTemp.c = 10; 
iTemp.d = 11;

The compiler will try to keep these temporary variables in registers.

6.2 Dead-Code elimination.\label{Dead-code elimination}

eg.

int global; 
void f () { 
  int i; 
  i = 1;    /* dead store */ 
  global = 1; /* dead store */ 
  global = 2; 
  return; 
  global = 3; /* unreachable */ 
}

will be changed to

int global; void f () 
{     
 global = 2;     
 return; 
}

6.3 Copy-Propagation:\label{Copy-Propagation}

eg.

int f() { 
   int i, j; 
   i = 10; 
   j = i; 
   return j; 
}

will be changed to 

int f() { 
    int i,j; 
    i = 10; 
    j = 10; 
    return 10; 
}

Note: the dead stores created by this copy propagation will be eliminated
by dead-code elimination .

6.4 Loop optimizations\label{Loop Optimizations}

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 , loop induction optimization causes an
increase in register pressure, which may cause unwanted spilling of
other temporary variables into the stack / 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 --noinduction option) or for a given
function only (#pragma NOINDUCTION).

6.4.1 Loop Invariant:\label{Loop Invariant}

eg

for (i = 0 ; i < 100 ; i ++) 
     f += k + l;

changed to

itemp = k + l; 
for ( i = 0; i < 100; i++ ) f += itemp;

As mentioned previously some loop invariants are not as apparent, all
static address computations are also moved out of the loop.

6.4.2 Strength reduction :\label{Strength Reduction}

This optimization substitutes an expression by a cheaper expression.

eg.

for (i=0;i < 100; i++) ar[i*5] = i*3;

changed to

itemp1 = 0; 
itemp2 = 0; 
for (i=0;i< 100;i++) { 
     ar[itemp1] = itemp2; 
     itemp1 += 5; 
     itemp2 += 3; 
}

The more expensive multiplication is changed to a less expensive addition.

6.4.3 Loop reversing:\label{Loop reversing}

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 ``decrement and jump if not zero'' instruction. SDCC checks
for the following criterion to determine if a loop is reversible (note:
more sophisticated compiers use data-dependency analysis to make this
determination, SDCC uses a more simple minded analysis).

* 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.

Note djnz instruction can be used for 8-bit values ONLY, therefore
it is advantageous to declare loop control symbols as either 'char'
or 'short', ofcourse this may not be possible on all situations.

6.5 Algebraic simplifications:\label{Algebraic Simplifications}

SDCC does numerous algebraic simplifications, the following is a small
sub-set of these optimizations.

eg 
i = j + 0 ; /* changed to */ i = j; 
i /= 2; /* changed to */ i >>= 1; 
i = j - j ; /* changed to */ i = 0; 
i = j / 1 ; /* changed to */ i = j;

Note the subexpressions given above are generally introduced by macro
expansions or as a result of copy/constant propagation.

6.6 'switch' statements.\label{Switch Statement}

SDCC changes switch statements to jump tables when the following conditions
are true. 

* The case labels are in numerical sequence , the labels need not be
  in order, and the starting number need not be one or zero.

eg 

switch(i) {                         switch (i) { 
case 4:...                          case 1: ... 
case 5:...                          case 2: ... 
case 3:...                          case 3: ... 
case 6:...                          case 4: ... 
}                                   }

Both the above switch statements will be implemented using a jump-table.

* 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. 

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.

eg

switch (i) { 
case 1: ... 
case 2: ... 
case 3: ... 
case 4: ... 
case 9: ... 
case 10: ... 
case 11: ... 
case 12: ... 
}

If the above switch statement is broken down into two switch statements

switch (i) { 
case 1: ... 
case 2: ... 
case 3: ... 
case 4: ... 
}

switch (i) { 
case 9: ... 
case 10: ... 
case 11: ... 
case 12:... 
}

then both the switch statements will be implemented using jump-tables
whereas the unmodified switch statement will not be .

6.7 bit-shifting operations.\label{bit shifting}

Bit shifting is one of the most frequently used operation in embedded
programming . SDCC tries to implement bit-shift operations in the
most efficient way possible.

eg.

unsigned short i;

... 
i>>= 4; 
..

generates the following code.

mov a,_i 
swap a 
anl a,#0x0f 
mov _i,a

In general SDCC will never setup a loop if the shift count is known.
Another example

unsigned int i; 
... 
i >>= 9; 
...

will generate

mov a,(_i + 1) 
mov (_i + 1),#0x00 
clr c 
rrc a 
mov _i,a

Note that SDCC stores numbers in little-endian format (i.e. lowest
order first)

6.7.1 Bit-rotation:\label{bit rotation}

A special case of the bit-shift operation is bit rotation, SDCC recognizes
the following expression to be a left bit-rotation.

unsigned char i; 
... 
i = ( ( i << 1) | ( i >> 7)); 
...

will generate the following code.

mov a,_i 
rl a 
mov _i,a

SDCC uses pattern matching on the parse tree to determine this operation
.Variations of this case will also be recognized as bit-rotation i.e
i = ((i >> 7) | (i << 1)); /* left-bit rotation */

6.8 Highest Order Bit.\label{Highest Order Bit}

It is frequently required to obtain the highest order bit of an integral
type (int,long,short or char types). SDCC recognizes the following
expression to yield the highest order bit and generates optimized
code for it.

eg 
unsigned int gint; 
foo () { 
unsigned char hob; 
   ... 
   hob = (gint >> 15) & 1; 
   .. 
}

Will generate the following code.

                             61 ;  hob.c 7 
   000A E5*01                62         mov  a,(_gint + 1) 
   000C 33                   63         rlc  a 
   000D E4                   64         clr  a 
   000E 13                   65         rrc  a 
   000F F5*02                66         mov  _foo_hob_1_1,a

Variations of this case however will NOT 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.

eg.

xyz = gint + ((gint >> 15) & 1);

will still be recognized.

6.9 Peep-hole optimizer.\label{Peep-Hole}

The compiler uses a rule based , pattern matching and re-writing mechanism
for peep-hole optimization . It is inspired by 'copt' 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 --peep-file <filename> option. The rule language
is best illustrated with examples.

replace { 
mov %1,a 
mov a,%1 } by { mov %1,a }

The above rule will the following assembly sequence

mov r1,a 
mov a,r1

to

mov r1,a

Note: All occurrences of a '%n' ( pattern variable ) must denote the
same string. With the above rule, the assembly sequence

mov r1,a 
mov a,r2

will remain unmodified. Other special case optimizations may be added
by the user (via --peep-file option), eg. some variants of the 8051
MCU allow only 'AJMP' and 'ACALL' , the following two rules will change
all 'LJMP' & 'LCALL' to 'AJMP' & 'ACALL'.

replace { lcall %1 } by { acall %1 } 
replace { ljmp %1 } by { ajmp %1 }

The inline-assembler' code 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-structure is MCU independent. Peephole optimization
rules for other MCU can be easily programmed using the rule language.

The syntax for a rule is as follows ,

rule := replace [ restart ] '{' <assembly sequence> '\n' 
                            '}' by '{' '\n' 
                                <assembly sequence> '\n' 
                            '}' [if <functionName> ] '\n' 
<assembly sequence> := assembly instruction (each instruction including
labels must be on a separate line).   

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. A good example
of this the following rule.

replace restart { 
pop %1 
push %1 } by { 
; nop 
}

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.

pop ar1 
pop ar2 
push ar2 
push ar1

would result in

pop ar1 
; nop 
push ar1

with the 'restart' option the rule will be applied again to the resulting
code and the all the 'pop' 'push' pairs will be eliminated to yield

; nop 
; nop

A conditional function can be attached to a rule. Attaching rules are
somewhat more involved, let me illustrate this with an example.

replace { 
     ljmp %5 
%2:} by { 
     sjmp %5 
%2:} if labelInRange

The optimizer does a look-up of a function name table defined in function
'callFuncByName' in the source file SDCCpeeph.c , with the name 'labelInRange',
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 '%5' is crucial, since the function labelInRange expects to
find the label in that particular variable (the hash table containing
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. I know this
whole thing is a little kludgey , may be some day we will have some
better means. If you are looking at this file, you will also see the
default rules that are compiled into the compiler, you can your own
rules in the default set there if you get tired of specifying the
--peep-file option.

7 Pointers\label{Pointers}

SDCC allows (via language extensions) pointers to explicitly point
to any of the memory spaces of the 8051. In addition to the explicit
pointers, the compiler also allows a _generic class of pointers which
can be used to point to any of the memory spaces. 

Pointer declaration examples.

/* pointer physically in xternal ram pointing to object in internal
ram */ 
data unsigned char * xdata p;


/* pointer physically in code rom pointing to data in xdata space */

xdata unsigned char * code p;


/* pointer physically in code space pointing to data in code space
*/ 
code unsigned char * code p;

/* the folowing is a generic pointer physically located in xdata space
*/
char * xdata p;

Well you get the idea. For compatibility with the previous version
of the compiler, the following syntax for pointer declaration is also
supported. Note the above examples will be portable to other commercially
available compilers.

unsigned char _xdata *ucxdp; /* pointer to data in external ram */

unsigned char _data  *ucdp ; /* pointer to data in internal ram */ 
unsigned char _code  *uccp ; /* pointer to data in R/O code space */
unsigned char _idata *uccp;  /* pointer to upper 128 bytes of ram */

All unqualified pointers are treated as 3 - byte '_generic' pointers.
These type of pointers can also to be explicitly declared.

unsigned char _generic *ucgp;

The highest order byte of the generic pointers contains the data space
information. Assembler support routines are called whenever data is
stored or retrieved using _generic pointers. These are useful for
developing reusable library routines. Explicitly specifying the pointer
type will generate the most efficient code. Pointers declared using
a mixture of OLD/NEW style could have unpredictable results.

8 Parameters & Local Variables\label{Auto Variables}

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). They can be placed on the
stack either by using the --stack-auto compiler option or by using
the 'reentrant' keyword in the function declaration.

eg

unsigned short foo( short i) reentrant { 
... 
}

Note that when the parameters & local variables are declared in the
internal/external ram the functions are non-reentrant. Since stack
space on 8051 is limited the 'reentrant' keyword or the --stack-auto
option should be used sparingly. Note the reentrant keyword just means
that the parameters & local variables will be allocated to the stack,
it DOES NOT mean that the function is register bank independent.

When compiled with the default option (i.e. non-reentrant ), local
variables can be assigned storage classes and absolute addresses. 

eg

unsigned short foo() { 
   xdata unsigned short i; 
   bit bvar; 
   data at 0x31 unsiged short j; 
... 
}

In the above example the variable i will be allocated in the external
ram, bvar in bit addressable space and j in internal ram. When compiled
with the --stack-auto or when a function is declared as 'reentrant'
local variables cannot be assigned storage classes or absolute addresses.

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.

8.1 Overlaying\label{Overlaying}

For non-reentrant 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 overlayable segment if the function has no other function calls
and the function is non-reentrant and the memory model is small. If
an explicit storage class is specified for a local variable , it will
NOT be overplayed.

Note that the compiler (not the linkage editor) makes the decision
for overlaying the data items. Functions that are called from an interrupt
service routine should be preceded by a #pragma NOOVERLAY if they
are not reentrant Along the same lines the compiler does not do any
processing with the inline assembler code so the compiler might incorrectly
assign local variables and parameters of a function into the overlay
segment if the only function call from a function is from inline assembler
code, it is safe to use the #pragma NOOVERLAY for functions which
call other functions using inline assembler code.

Parameters and Local variables of functions that contain 16 or 32 bit
multiplication or division will NOT be overlayed since these are implemented
using external functions.

eg.

#pragma SAVE 
#pragma NOOVERLAY 
void set_error( unsigned short errcd) 
{ 
    P3 = errcd; 
} 
#pragma RESTORE 
void some_isr () interrupt 2 using 1 
{ 
    ... 
    set_error(10); 
    ... 
}

In the above example the parameter errcd for the function set_error
would be assigned to the overlayable segment (if the #pragma NOOVERLAY
was not present) , this could cause unpredictable runtime behavior.
The pragma NOOVERLAY ensures that the parameters and local variables
for the function are NOT overlayed.

9 critical Functions.\label{Critical}

A special keyword may be associated with a function declaring it as
'critical'. SDCC will generate code to disable all interrupts upon
entry to a critical function and enable them back before returning
. Note that nesting critical functions may cause unpredictable results.

eg

int foo () critical 
{ 
... 
... 
}

The critical attribute maybe used with other attributes like reentrant.

10 Absolute addressing.\label{Absolute Addressing}

Data items can be assigned an absolute address with the at <address>
keyword, in addition to a storage class.

eg. 

xdata at 0x8000 unsigned char PORTA_8255 ;

In the above example the PORTA_8255 will be allocated to the location
0x8000 of the external ram. 

Note that is this feature is provided to give the programmer access
to memory mapped devices attached to the controller. 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) and the linker output files (<filename>.rst)
and (<filename>.map) are a good places to look for such overlaps.

Absolute address can be specified for variables in all storage classes.

eg.

bit at 0x02 bvar;

The above example will allocate the variable at offset 0x02 in the
bit-addressable 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.

11 Interrupt Service Routines\label{Interrupt Service Rouines}

SDCC allows interrupt service routines to be coded in C, with some
extended keywords.

void timer_isr (void) interrupt 2 using 1 
{ 
.. 
}

The number following the 'interrupt' keyword is the interrupt number
this routine will service. The compiler will insert a call to this
routine in the interrupt vector table for the interrupt number specified.
The 'using' keyword is 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 NOOVERLAY (if it is not reentrant)
. A special note here, int (16 bit) and long (32 bit) integer division,
multiplication & modulus operations are implemented using external
support routines developed in ANSI-C, if an interrupt service routine
needs to do any of these operations then the support routines (as
mentioned in a following section) will have to recompiled using the
--stack-auto option and the source file will need to be compiled using
the --int-long-rent compiler option.

If you have multiple source files in your project, interrupt service
routines can be present in any of them, but a prototype of the isr
MUST be present in the file that contains the function 'main'.

Interrupt Numbers and the corresponding address & descriptions for
the Standard 8051 are listed below. SDCC will automatically adjust
the interrupt vector table to the maximum interrupt number specified.

Interrupt #         Description           Vector Address 
   0                External 0            0x0003 
   1                Timer 0               0x000B 
   2                External 1            0x0013 
   3                Timer 1               0x001B 
   4                Serial                0x0023

If the interrupt service routine is defined without a register bank
or with register bank 0 (using 0), the compiler will save the registers
used by itself on the stack (upon entry and restore them at exit),
however if such an interrupt service routine calls another function
then the entire register bank will be saved on the stack. This scheme
may be advantageous for small interrupt service routines which have
low register usage.

If the interrupt service routine is defined to be using a specific
register bank then only ``a'',''b'' & ``dptr'' are save and restored,
if such an interrupt service routine calls another function (using
another register bank) then the entire register bank of the called
function will be saved on the stack. This scheme is recommended for
larger interrupt service routines.

Calling other functions from an interrupt service routine is not recommended
avoid it if possible.

12 Startup Code\label{Startup}

The compiler inserts a jump to the C routine _sdcc__external__startup()
at the start of the CODE area. This routine can be found in the file
SDCCDIR/sdcc51lib/_startup.c , 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,
other wise static & global variables will be initialized before the
function main is invoked.

13 Inline assembler code.\label{Inline}

SDCC allows the use of in-line assembler with a few restriction as
regards labels. All labels defined within inline assembler code HAS
TO BE of the form nnnnn$ where nnnn is a number less than 100 (which
implies a limit of utmost 100 inline assembler labels per function).
It is strongly recommended that each assembly instruction (including
labels) be placed in a separate line ( as the example shows). When
the --peep-asm command line option is used, the inline assembler code
will be passed through the peephole optimizer, this might cause some
unexpected changes in the inline assembler code, please go throught
the peephole optimizer rules defined in file 'SDCCpeeph.def' carefully
before using this option.

eg

_asm 
         mov b,#10 
00001$: 
         djnz b,00001$ 
_endasm ;

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 _asm ... _endasm; keyword pair. 

Inline assembler code cannot reference any C-Labels however it can
reference labels defined by the inline assembler.

eg

foo() { 
... /* some c code */ 
_asm 
     ; some assembler code 
    ljmp $0003 
_endasm ; 
... /* some more c code */ 
clabel:   /* inline assembler cannot reference this label */ 
_asm 
   $0003: ;label (can be reference by inline assembler only) 
_endasm ; 
... 
}

In other words inline assembly code can access labels defined in inline
assembly. The same goes the other way, ie. labels defines in inline
assembly CANNOT be accessed by C statements.

14 int (16 bit) and long (32 bit ) support.\label{int and long}

For signed & unsigned int (16 bit) and long (32 bit) variables, division,
multiplication and modulus operations are implemented by support routines.
These support routines are all developed in ANSI-C to facilitate porting
to other MCUs. The following files contain the described routine,
all of them can be found in the directory SDCCDIR/sdcc51lib

* _mulsint.c - signed 16 bit multiplication (calls _muluint)

* _muluint.c - unsigned 16 bit multiplication

* _divsint.c - signed 16 bit division (calls _divuint)

* _divuint.c - unsigned 16 bit division.

* _modsint.c - signed 16 bit modulus (call _moduint)

* _moduint.c - unsigned 16 bit modulus.

* _mulslong.c - signed 32 bit multiplication (calls _mululong)

* _mululong.c - unsigned32 bit multiplication.

* _divslong.c - signed 32 division (calls _divulong)

* _divulong.c - unsigned 32 division.

* _modslong.c - signed 32 bit modulus (calls _modulong).

* _modulong.c - unsigned 32 bit modulus.

All these routines are compiled as non-reentrant and small model. Since
they are compiled as non-reentrant, interrupt service routines should
not do any of the above operations, if this unavoidable then the above
routines will need to ne compiled with the --stack-auto option, after
which the source program will have to be compiled with --int-long-rent
option.

15 Floating point support\label{Float}

SDCC supports IEEE (single precision 4bytes) floating point numbers.The
floating point support routines are derived from gcc's floatlib.c
and consists of the following routines. 

* _fsadd.c - add floating point numbers.

* _fssub.c - subtract floating point numbers

* _fsdiv.c - divide floating point numbers

* _fsmul.c - multiply floating point numbers

* _fs2uchar.c - convert floating point to unsigned char

* _fs2char.c - convert floating point to signed char.

* _fs2uint.c - convert floating point to unsigned int.

* _fs2int.c - convert floating point to signed int.

* _fs2ulong.c - convert floating point to unsigned long.

* _fs2long.c - convert floating point to signed long.

* _uchar2fs.c - convert unsigned char to floating point

* _char2fs.c - convert char to floating point number

* _uint2fs.c - convert unsigned int to floating point

* _int2fs.c - convert int to floating point numbers

* _ulong2fs.c - convert unsigned long to floating point number

* _long2fs.c - convert long to floating point number.

Note if all these routines are used simultaneously the data space might
overflow. For serious floating point usage it is strongly recommended
that the Large model be used (in which case the floating point routines
mentioned above will need to recompiled with the --model-Large option).

16 Memory Models\label{Memory Models}

SDCC allows two memory models, modules compiled with different memory
models should be combined together, the results would be unpredictable.
The support routines supplied with the compiler are compiled in small-model
by default, and will need to be recompiled using the large model if
the large model is used. In general the use of the large model is
discouraged.

When the large model is used all variables declared without a storage
class will be allocated into the external ram, this includes all parameters
and local variables (for non-reentrant functions). When the small
model is used variables without storage class are allocated in the
internal ram.

Judicious usage of the processor specific storage classes and the 'reentrant'
function type will yield much more efficient code, than using the
large-model.

17 Defines created by the compiler.\label{Defines.}

The compiler creates the following #defines .

* SDCC - this Symbol is always defined.

* SDCC_STACK_AUTO - this symbol is defined when --stack-auto option
  is used.

* SDCC_MODEL_SMALL - when small model is used.

* SDCC_MODEL_LARGE - when --model-large is used.

* SDCC_USE_XSTACK - when --xstack option is used.

18 Pragmas\label{Pragmaa}

SDCC supports the following #pragma directives. This directives are
applicable only at a function level.

* SAVE\label{pragma save} - this will save all the current options .

* RESTORE \label{pragma restore}- will restore the saved options from
  the last save. Note that SAVES & RESTOREs cannot be nested. SDCC
  uses the same buffer to save the options each time a SAVE is called.

* NOGCSE\label{pragma nogcse} - will stop global subexpression elimination.

* NOINDUCTION \label{pragma noinduction}- will stop loop induction
  optimizations .

* NOJTBOUND \label{pragma nojtbound}- will not generate code for boundary
  value checking , when switch statements are turned into jump-tables.

* NOOVERLAY \label{pragma nooverlay}- the compiler will not overlay
  the parameters and local variables of a function.

* NOLOOPREVERSE \label{pragma noloopreverse}- Will not do loop reversal
  optimization

* EXCLUDE NONE | {acc[,b[,dpl[,dph]]]\label{pragma exclude} - 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''

* CALLEE-SAVES function1[,function2[,function3...]]\label{pragma callee-saves}
  - The compiler by default uses a caller saves convention for register
  saving across function calls, however this can cause unneccessary
  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, extra code will be
  generated 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 future
  the compiler (with interprocedural analysis) will be able to determine
  the appropriate scheme to use for each function call. If --callee-saves\ref{--callee-saves}
  command line option is used, the function names specified in #pragma
  CALLEE-SAVES is appended to the list of functions specified inthe
  command line.

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.

eg

#pragma SAVE   /* save the current settings */ 
#pragma NOGCSE /* turnoff global subexpression elimination */ 
#pragma NOINDUCTION /* turn off induction optimizations */ 
int foo () 
{ 
    ... 
    /* large code */ 
    ... 
} 
#pragma RESTORE /* turn the optimizations back on */

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.

19 Library routines.\label{Library}

The following library routines are provided for your convenience.

stdio.h - Contains the following functions printf & sprintf these routines
are developed by Martijn van Balen <balen@natlab.research.philips.com>. 

%[flags][width][b|B|l|L]type

           flags: -        left justify output in specified field width 
                 +        prefix output with +/- sign if output is signed type 
                 space    prefix output with a blank if it's a signed positive value 
          width:          specifies minimum number of characters outputted for numbers

                          or strings. 
                          - For numbers, spaces are added on the left when needed. 
                            If width starts with a zero character, zeroes and used 
                            instead of spaces. 
                          - For strings, spaces are are added on the left or right (when 
                            flag '-' is used) when needed. 
                          
          b/B:            byte argument (used by d, u, o, x, X) 
          l/L:            long argument (used by d, u, o, x, X)
          type:  d        decimal number 
                 u        unsigned decimal number 
                 o        unsigned octal number 
                 x        unsigned hexadecimal number (0-9, a-f) 
                 X        unsigned hexadecimal number (0-9, A-F) 
                 c        character 
                 s        string (generic pointer) 
                 p        generic pointer (I:data/idata, C:code, X:xdata, P:paged) 
                 f        float (still to be implemented)

Also contains a very simple version of printf (printf_small). This
simplified version of printf supports only the following formats.

format     output type     argument-type 
%d         decimal       int 
%ld        decimal       long 
%hd        decimal       short/char 
%x        hexadecimal    int 
%lx       hexadecimal    long 
%hx       hexadecimal    short/char 
%o         octal         int 
%lo        octal         long 
%ho        octal         short/char 
%c        character      char/short 
%s        character     _generic pointer

  The routine is very stack intesive , --stack-after-data parameter
  should be used when using this routine, the routine also takes about
  1K of code space .It also expects an external function named putchar(char
  ) to be present (this can be changed). When using the %s format
  the string / pointer should be cast to a generic pointer. eg.

  printf_small(``my str %s, my int %d\n'',(char _generic *)mystr,myint);

* stdarg.h - contains definition for the following macros to be used
  for variable parameter list, note that a function can have a variable
  parameter list if and only if it is 'reentrant'

  va_list, va_start, va_arg, va_end.

* setjmp.h - contains defintion for ANSI setjmp & longjmp routines.
  Note in this case setjmp & longjmp can be used between functions
  executing within the same register bank, if long jmp is executed
  from a function that is using a different register bank from the
  function issuing the setjmp function, the results may be unpredictable.
  The jump buffer requires 3 bytes of data (the stack pointer & a
  16 byte return address), and can be placed in any address space.

* stdlib.h - contains the following functions.

  atoi, atol.

* string.h - contains the following functions.

  strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr,
  strspn, strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp,
  memset.

* ctype.h - contains the following routines.

  iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
  isxdigit, isalnum, isalpha.

* malloc.h - The malloc routines are developed by Dmitry S. Obukhov
  (dso@usa.net). These routines will allocate memory from the external
  ram. Here is a description on how to use them (as described by the
  author).

  //Example: 
       //     #define DYNAMIC_MEMORY_SIZE 0x2000 
       //     ..... 
       //     unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
  
       //     unsigned char xdata * current_buffer; 
       //     ..... 
       //     void main(void) 
       //     { 
       //         ... 
       //         init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
  
       //         //Now it's possible to use malloc. 
       //         ... 
       //         current_buffer = malloc(0x100); 
       //

* serial.h - Serial IO routines are also developed by Dmitry S. Obukhov
  (dso@usa.net). These routines are interrupt driven with a 256 byte
  circular buffer, they also expect external ram to be present. Please
  see documentation in file SDCCDIR/sdcc51lib/serial.c . Note the
  header file ``serial.h'' MUST be included in the file containing
  the 'main' function.

* ser.h - Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.com>
  these routines are more compact and faster. Please see documentation
  in file SDCCDIR/sdcc51lib/ser.c

* ser_ir.h - Another alternate set of serial routines provided by Josef
  Wolf <jw@raven.inka.de> , these routines do not use the external
  ram.

* reg51.h - contains register definitions for a standard 8051

* reg552.h - contains register definitions for 80C552.

* float.h - contains min, max and other floating point related stuff.

All library routines are compiled as --model-small , they are all non-reentrant,
if you plan to use the large model or want to make these routines
reentrant, then they will have to be recompiled with the appropriate
compiler option.

Have not had time to do the more involved routines like printf, will
get to them shortly.

20 Interfacing with assembly routines.\label{Interface_asm}

20.1 Global registers used for parameter passing.

By default the compiler uses the global registers ``DPL,DPH,B,ACC''
to pass the first parameter to a routine, the second parameter onwards
is either allocated on the stack (for reentrant routines or --stack-auto
is used) or in the internal / external ram (depending on the memory
model). 

20.1.1 Assembler routine non-reentrant

In the following example the function cfunc calls an assembler routine
asm_func, which takes two parameters.

extern int asm_func( unsigned short, unsigned short);

 
int c_func (unsigned short i, unsigned short j) 
{ 
        return asm_func(i,j); 
} 
int main() 
{ 
   return c_func(10,9); 
}

The corresponding assembler function is:-

        .globl _asm_func_PARM_2 
        .globl _asm_func 
        .area OSEG 
_asm_func_PARM_2:       .ds      1 
        .area CSEG 
_asm_func: 
        mov     a,dpl 
        add     a,_asm_func_PARM_2 
        mov     dpl,a 
        mov     dpl,#0x00 
        ret

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.

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 ``dpl'' for One bye parameter, ``dptr''
if two bytes, ``b,dptr'' for three bytes and ``acc,b,dptr'' for four
bytes, the varaible name for the second parameter will be _<function_name>_PARM_2.

Assemble the assembler routine with the following command.

asx8051 -losg asmfunc.asm

Then compile and link the assembler routine to the C source file with
the following command,

sdcc cfunc.c asmfunc.rel

20.1.2 Assembler routine is reentrant

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.

extern int asm_func( unsigned short, unsigned short);

 

int c_func (unsigned short i, unsigned short j) reentrant 
{ 
        return asm_func(i,j); 
} 
int main() 
{ 
   return c_func(10,9); 
}

The corresponding assembler routine is.

        .globl _asm_func 
_asm_func: 
        push  _bp 
        mov  _bp,sp 
        mov  r2,dpl
        mov  a,_bp 
        clr  c 
        add  a,#0xfd 
        mov  r0,a 
        add  a,#0xfc
        mov  r1,a 
        mov  a,@r0 
        add  a,r2
        mov  dpl,a 
        mov  dph,#0x00 
        mov  sp,_bp 
        pop  _bp 
        ret

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.

20.2 With --noregparms option.

When the source is compiled with --noregparms option , space is allocated
for each of the parameters passed to a routine.

20.2.1 Assembler routine non-reentrant.

In the following example the function cfunc calls an assembler routine
asm_func, which takes two parameters.

extern int asm_func( unsigned short, unsigned short);

 
int c_func (unsigned short i, unsigned short j) 
{ 
        return asm_func(i,j); 
} 
int main() 
{ 
   return c_func(10,9); 
}

The corresponding assembler function is:-

        .globl _asm_func_PARM_1 
        .globl _asm_func_PARM_2 
        .globl _asm_func 
        .area OSEG 
_asm_func_PARM_1:       .ds     1 
_asm_func_PARM_2:       .ds      1 
        .area CSEG 
_asm_func: 
        mov     a,_asm_func_PARM_1 
        add     a,_asm_func_PARM_2 
        mov     dpl,a 
        mov     dpl,#0x00 
        ret

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.

The parameter naming convention is _<function_name>_PARM_<n>, where
n is the parameter number starting from 1, and counting from the left.
i.e. the left-most parameter name will be _<function_name>_PARM_1.

Assemble the assembler routine with the following command.

asx8051 -losg asmfunc.asm

Then compile and link the assembler routine to the C source file with
the following command,

sdcc cfunc.c asmfunc.rel

20.2.2 Assembler routine is reentrant.

In this case the parameters 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.

extern int asm_func( unsigned short, unsigned short);

 

int c_func (unsigned short i, unsigned short j) reentrant 
{ 
        return asm_func(i,j); 
} 
int main() 
{ 
   return c_func(10,9); 
}

The corresponding assembler routine is.

        .globl _asm_func 
_asm_func: 
        push  _bp 
        mov  _bp,sp 
        mov  a,_bp 
        clr  c 
        add  a,#0xfd 
        mov  r0,a 
        mov  a,_bp 
        clr  c 
        add  a,#0xfc 
        mov  r1,a 
        mov  a,@r0 
        add  a,@r1 
        mov  dpl,a 
        mov  dph,#0x00 
        mov  sp,_bp 
        pop  _bp 
        ret

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.

21 External Stack.\label{xstack}

The external stack is located at the start of the external ram segment
, and is 256 bytes in size. When --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 --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).

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.

22 ANSI-Compliance.\label{ANSI_Compliance}

Deviations from the compliancy.

1. functions are not always reentrant.

2. 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.

  eg

struct s { ... }; 
struct s s1, s2; 
foo() 
{ 
... 
s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ 
... 
}

struct s foo1 (struct s parms) /* is invalid in SDCC although allowed
in ANSI */ 
{ 
struct s rets; 
... 
return rets;/* is invalid in SDCC although allowed in ANSI */ 
}

1. 'long long' (64 bit integers) not supported.

2. 'double' precision floating point not supported.

3. integral promotions are suppressed. What does this mean ? The compiler
  will not implicitly promote an integer expression to a higher order
  integer, exception is an assignment or parameter passing. 

4. No support for setjmp and longjmp (for now).

5. 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 .. not valid in SDCC */ 
{ 
... 
}

1. 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()' */

23 Cyclomatic Complexity\label{Cyclomatic}

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. SDCC uses the following
formula to compute the complexity.

complexity = (number of edges in control flow graph) - 
             (number of nodes in control flow graph) + 2;

Having said that the industry standard is 10, you should be aware that
in some cases it 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.

24 TIPS\label{Tips}

Here are a few guide-lines that will help the compiler generate more
efficient code, some of the tips are specific to this compiler others
are generally good programming practice.

* Use the smallest data type to represent your data-value. If it is
  known in advance that the value is going to be less than 256 then
  use a 'short' or 'char' instead of an '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 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 a support routine). 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
  oppurtunities).

Notes from an USER ( Trefor@magera.freeserve.co.uk )

The 8051 family of micro controller have a minimum of 128 bytes of
internal memory which is structured as follows

- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7
to R7 

- Bytes 20-2F - 16 bytes to hold 128 bit variables and 

- Bytes 30-7F - 60 bytes for general purpose use.

Normally the SDCC compiler will only utilise the first bank of registers,
but it is possible to specify that other banks of registers should
be used in interrupt routines. By default, the compiler will place
the stack after the last bank of used registers, i.e. if the first
2 banks of registers are used, it will position the base of the internal
stack at address 16 (0X10). This implies that as the stack grows,
it will use up the remaining register banks, and the 16 bytes used
by the 128 bit variables, and 60 bytes for general purpose use.

By default, the compiler uses the 60 general purpose bytes to hold
"near data". The compiler/optimiser may also declare some Local Variables
in this area to hold local data. 

If any of the 128 bit variables are used, or near data is being used
then care needs to be taken to ensure that the stack does not grow
so much that it starts to over write either your bit variables or
"near data". There is no runtime checking to prevent this from happening.

The amount of stack being used is affected by the use of the "internal
stack" to save registers before a subroutine call is made, - --stack-auto
will declare parameters and local variables on the stack - the number
of nested subroutines.

If you detect that the stack is over writing you data, then the following
can be done. --xstack will cause an external stack to be used for
saving registers and (if --stack-auto is being used) storing parameters
and local variables. However this will produce more and code which
will be slower to execute. 

--stack-loc will allow you specify the start of the stack, i.e. you
could start it after any data in the general purpose area. However
this may waste the memory not used by the register banks and if the
size of the "near data" increases, it may creep into the bottom of
the stack.

--stack-after-data, similar to the --stack-loc, but it automatically
places the stack after the end of the "near data". Again this could
waste any spare register space.

--data-loc allows you to specify the start address of the near data.
This could be used to move the "near data" further away from the stack
giving it more room to grow. This will only work if no bit variables
are being used and the stack can grow to use the bit variable space.

Conclusion.

If you find that the stack is over writing your bit variables or "near
data" then the approach which best utilised the internal memory is
to position the "near data" after the last bank of used registers
or, if you use bit variables, after the last bit variable by using
the --data-loc, e.g. if two register banks are being used and no data
variables, --data-loc 16, and - use the --stack-after-data option.

If bit variables are being used, another method would be to try and
squeeze the data area in the unused register banks if it will fit,
and start the stack after the last bit variable.

25 Retargetting for other MCUs.\label{Retargetting}

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.

1. 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.

2. 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.

3. 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.

4. 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.

5. Phase five is register allocation. There are two parts to this process .

  (a) 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.

  (b) 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.

6. 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.

7. As mentioned in the optimization section the peep-hole optimizer
  is rule based system, which can reprogrammed for other MCUs.

26 Reporting Bugs\label{Bugs}

Shoot of an email to 'sandeep.dutta@usa.net', as a matter of principle
I always reply to all email's sent to me. Bugs will be fixed ASAP.
When reporting a bug , it is useful to include a small snippet of
code that is causing the problem, if possible compile your program
with the --dumpall option and send the dump files along with the bug
report.

27 SDCDB - Source level debugger.

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 ( the GNU debugger) as possible. The configuration
and build process of the compiler see Installation \ref{Installation}
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.

27.1 Compiling for debugging.

The --debug option must be specified for all files for which debug
information is to be generated. The complier generates a .cdb file
for each of these files. The linker updates the .cdb file with the
address information. This .cdb is used by the debugger .

27.2 How the debugger works.

When the --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 .cdb file, the linker updates the .cdb file
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 .

27.3 Starting the debugger.

The debugger can be started using the following command line. (Assume
the file you are debugging has

the file name foo).

>sdcdb foo

The debugger will look for the following files.

1. foo.c - the source file.

2. foo.cdb - the debugger symbol information file.

3. foo.ihx - the intel hex format object file.

27.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 simulator docs for details.

* -s <serial port file> passed to simulator see simulator docs for
  details.

* -S <serial in,out> passed to simulator see simulator docs for details.

27.5 Debugger Commands.

As mention earlier the command interface for the debugger has been
deliberately kept as close the GNU debugger gdb , as possible, this
will help int integration with existing graphical user interfaces
(like ddd, xxgdb or xemacs) existing for the GNU debugger.

27.5.1 break [line | file:line | function | file:function]

Set breakpoint at specified line or function.

sdcdb>break 100 
sdcdb>break foo.c:100
sdcdb>break funcfoo
sdcdb>break foo.c:funcfoo

27.5.2 clear [line | file:line | function | file:function ]

Clear breakpoint at specified line or function.

sdcdb>clear 100
sdcdb>clear foo.c:100
sdcdb>clear funcfoo
sdcdb>clear foo.c:funcfoo

27.5.3 continue

Continue program being debugged, after breakpoint.

27.5.4 finish

Execute till the end of the current function.

27.5.5 delete [n]

Delete breakpoint number 'n'. If used without any option clear ALL
user defined break points.

27.5.6 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.

27.5.7 step

Step program until it reaches a different source line.

27.5.8 next

Step program, proceeding through subroutine calls.

27.5.9 run

Start debugged program.

27.5.10 ptype variable 

Print type information of the variable.

27.5.11 print variable

print value of variable.

27.5.12 file filename

load the given file name. Note this is an alternate method of loading
file for debugging.

27.5.13 frame

print information about current frame.

27.5.14 set srcmode

Toggle between C source & assembly source.

27.5.15 ! simulator command

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.

27.5.16 quit.

"Watch me now. Iam going Down. My name is Bobby Brown"

27.6 Interfacing with XEmacs.

Two files are (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 installation 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) (load-file
sdcdbsrc.el) [ .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 [$(prefix)/bin], then enter the following command ESC-x
load-file sdcdbsrc . To start the interface enter the following command
ESC-x sdcdbsrc , you will prompted to enter the file name to be debugged. 

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.

* sdcdbsrc-cpu-type '51

* sdcdbsrc-frequency '11059200

* sdcdbsrc-serial nil

The following is a list of key mapping for the debugger interface.

 
;; Current Listing :: 
;;key               binding                      Comment 
;;---               -------                      ------- 
;; 
;; n               sdcdb-next-from-src          SDCDB next command 
;; b               sdcdb-back-from-src          SDCDB back command 
;; c               sdcdb-cont-from-src          SDCDB continue command
;; s               sdcdb-step-from-src          SDCDB step command 
;; ?               sdcdb-whatis-c-sexp          SDCDB ptypecommand for data at 
;;                                           buffer point 
;; x               sdcdbsrc-delete              SDCDB Delete all breakpoints if no arg 
;;                                              given or delete arg (C-u arg x) 
;; m               sdcdbsrc-frame               SDCDB Display current frame if no arg, 
;;                                              given or display frame arg 
;;                                             buffer point 
;; !               sdcdbsrc-goto-sdcdb          Goto the SDCDB output buffer 
;; p               sdcdb-print-c-sexp           SDCDB print command for data at 
;;                                           buffer point 
;; g               sdcdbsrc-goto-sdcdb          Goto the SDCDB output buffer 
;; t               sdcdbsrc-mode                Toggles Sdcdbsrc mode (turns it off) 
;; 
;; C-c C-f         sdcdb-finish-from-src        SDCDB finish command 
;; 
;; C-x SPC         sdcdb-break                  Set break for line with point 
;; ESC t           sdcdbsrc-mode                Toggle Sdcdbsrc mode 
;; ESC m           sdcdbsrc-srcmode             Toggle list mode 
;; 


28 Conclusion\label{Conclusion}

SDCC is a large project , the compiler alone (without the Assembler
Package , Preprocessor & garbage collector) is about 40,000 lines
of code (blank stripped). As with any project of this size there are
bound to be bugs, I am more than willing to work to fix these bugs
, of course all the source code is included with the package. 

Where does it go from here ? I am planning to target the Atmel AVR
8-bit MCUs which seems to have a lot of users. I am also planning
to include an alias analysis system with this compiler (it does not
currently have one).

29 Acknowledgments\label{Acknowledgements}

Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX
& ASLINK. 

John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for
8051

Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines. 

Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware
simulator

Jans J Boehm(boehm@sgi.com) and Alan J Demers - Conservative garbage
collector for C & C++.

Malini Dutta(malini@mediaone.net) - my wife for her patience and support.

Unknown - for the GNU C - preprocessor.

\index