sdccman.txt

很少见的源码公开的msc51和z80的c编译器。

SDCC Compiler User Guide

Table of Contents

Introduction
    About SDCC
    Open Source
    Typographic conventions
    Compatibility with previous versions
    System Requirements
    Other Resources
    Wishes for the future
Installation
    Linux/Unix Installation
    Windows Installation
        Windows Install Using a Binary Package
        Windows Install Using Cygwin
    Testing out the SDCC Compiler
    Install Trouble-shooting
        SDCC cannot find libraries or header files.
        SDCC does not compile correctly.
        What the ./configure does
        What the make does.
        What the make install command does.
    Additional Information for Windows Users
        Getting started with Cygwin
        Running SDCC as Native Compiled Executables
    SDCC on Other Platforms
    Advanced Install Options
    Components of SDCC
        sdcc - The Compiler
        sdcpp (C-Preprocessor)
        asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 (The Assemblers and Linkage Editors)
        s51 - Simulator
        sdcdb - Source Level Debugger
Using SDCC
    Compiling
        Single Source File Projects
        Projects with Multiple Source Files
        Projects with Additional Libraries
    Command Line Options
        Processor Selection Options
        Preprocessor Options
        Linker Options
        MCS51 Options
        DS390 Options
        Optimization Options
        Other Options
        Intermediate Dump Options
    MCS51/DS390 Storage Class Language Extensions
        xdata
        data
        idata
        bit
        sfr / sbit
    Pointers
    Parameters & Local Variables
    Overlaying
    Interrupt Service Routines
    Critical Functions
    Naked Functions
    Functions using private banks
    Absolute Addressing
    Startup Code
    Inline Assembler Code
    int(16 bit) and long (32 bit) Support
    Floating Point Support
    MCS51 Memory Models
    DS390 Memory Models
    Defines Created by the Compiler
SDCC Technical Data
    Optimizations
        Sub-expression Elimination
        Dead-Code Elimination
        Copy-Propagation
        Loop Optimizations
        Loop Reversing
        Algebraic Simplifications
        'switch' Statements
        Bit-shifting Operations.
        Bit-rotation
        Highest Order Bit
        Peep-hole Optimizer
    Pragmas
    <pending: this is messy and incomplete> Library Routines
    Interfacing with Assembly Routines
        Global Registers used for Parameter Passing
        Assembler Routine(non-reentrant)
        Assembler Routine(reentrant)
    External Stack
    ANSI-Compliance
    Cyclomatic Complexity
TIPS
    Notes on MCS51 memory layout
Retargetting for other MCUs.
SDCDB - Source Level Debugger
    Compiling for Debugging
    How the Debugger Works
    Starting the Debugger
    Command Line Options.
    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 ]
        step
        next
        run
        ptype variable 
        print variable
        file filename
        frame
        set srcmode
        ! simulator command
        quit.
    Interfacing with XEmacs.
Other Processors
    The Z80 and gbz80 port
Support
    Reporting Bugs
Acknowledgments



 Introduction

 About SDCC

SDCC is a Freeware, retargettable, optimizing ANSI-C compiler
by Sandeep Dutta designed for 8 bit Microprocessors. The
current version targets Intel MCS51 based Microprocessors(8051,8052,
etc), Zilog Z80 based MCUs, and the Dallas DS80C390 variant.
It can be retargetted for other microprocessors, support
for PIC, AVR and 186 is under development. The entire source
code for the compiler is distributed under GPL. SDCC uses
ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
SDCC has extensive language extensions suitable for utilizing
various microcontrollers and underlying hardware effectively.


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 

 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:

 char (8 bits, 1 byte), 

 short and 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 (--cyclomatic) to report the
relative complexity of a function. These functions can then
be further optimized, or hand coded in assembly if needed.


SDCC also comes with a companion source level debugger SDCDB,
the debugger currently uses ucSim a freeware simulator for
8051 and other micro-controllers. 

The latest version can be downloaded from [http://sdcc.sourceforge.net/].

 Open Source

All packages used in this compiler system are opensource
and freeware; source code for all the sub-packages (asxxxx
assembler/linker, pre-processor) is distributed with the
package. This documentation is maintained 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! 

 Typographic conventions

Throughout this manual, we will use the following convention.
Commands you have to type in are printed in "sans serif".
Code samples are printed in typewriter font. Interesting
items and new terms are printed in italicised type.

 Compatibility with previous versions

This version has numerous bug fixes compared with the previous
version. But we also introduced some incompatibilities with
older versions. Not just for the fun of it, but to make
the compiler more stable, efficient and ANSI compliant. 


 short is now equivalent to int (16 bits), it used to be
  equivalent to char (8 bits)

 the default directory where include, library and documention
  files are stored is no in /usr/local/share

 char type parameters to vararg functions are casted to
  int unless explicitly casted, e.g.: 
    char a=3;
    printf ("%d %c\n", a, (char)a);
   will push a as an int and as a char resp.

 option --regextend has been removed

 option --noreparms has been removed

<pending: more incompatibilities?>

 System Requirements

What do you need before you start installation of SDCC? A
computer, and a desire to compute. The preferred method
of installation is to compile SDCC from source using GNU
gcc and make. For Windows some pre-compiled binary distributions
are available for your convenience. You should have some
experience with command line tools and compiler use.

 Other Resources

The SDCC home page at [http://sdcc.sourceforge.net/]
is a great place to find distribution sets. You can also
find links to the user mailing lists that offer help or
discuss SDCC with other SDCC users. Web links to other SDCC
related sites can also be found here. This document can
be found in the DOC directory of the source package as a
text or HTML file. Some of the other tools (simulator and
assembler) included with SDCC contain their own documentation
and can be found in the source distribution. If you want
the latest unreleased software, the complete source package
is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.

 Wishes for the future

There are (and always will be) some things that could be
done. Here are some I can think of:


sdcc -c --model-large -o large _atoi.c (where large could
be a different basename or a directory)


char KernelFunction3(char p) at 0x340;

If you can think of some more, please send them to the list.

<pending: And then of course a proper index-table>

 Installation

 Linux/Unix Installation

 Download the source package, it will be named something
  like sdcc-2.x.x.tgz.

 Bring up a command line terminal, such as xterm.

 Unpack the file using a command like: "tar -xzf sdcc-2.x.x.tgz",
  this will create a sub-directory called sdcc with all
  of the sources.

 Change directory into the main SDCC directory, for example
  type: "cd sdcc".

 Type "./configure". This configures the package for compilation
  on your system.

 Type "make". All of the source packages will compile, this
  can take a while.

 Type "make install" as root. This copies the binary executables,
  the include files, the libraries and the documentation
  to the install directories.

 Windows Installation

<pending: is this complete? where is borland, mingw>

For installation under Windows you first need to pick between
a pre-compiled binary package, or installing the source
package along with the Cygwin package. The binary package
is the quickest to install, while the Cygwin package includes
all of the open source power tools used to compile the complete
SDCC source package in the Windows environment. If you are
not familiar with the Unix command line environment, you
may want to read the section on additional information for
Windows users prior to your initial installation.

 Windows Install Using a Binary Package

 Download the binary package and unpack it using your favorite
  unpacking tool (gunzip, WinZip, etc). This should unpack
  to a group of sub-directories. An example directory structure
  after unpacking is: c:\usr\local\bin for the executables,
  c:\usr\local\share\sdcc\include and c:\usr\local\share\sdcc\lib
  for the include and libraries.

 Adjust your environment PATH to include the location of
  the bin directory. For example, make a setsdcc.bat file
  with the following: set PATH=c:\usr\local\bin;%PATH%

 When you compile with sdcc, you may need to specify the
  location of the lib and include folders. For example,
  sdcc -I c:\usr\local\share\sdcc\include -L c:\usr\local\share\sdcc\lib\small
  test.c

 Windows Install Using Cygwin

 Download and install the cygwin package from the redhat
  site[http://sources.redhat.com/cygwin/]. Currently,
  this involved downloading a small install program which
  then automates downloading and installing selected parts
  of the package (a large 80M byte sized dowload for the
  whole thing). 

 Bring up a Unix/Bash command line terminal from the Cygwin
  menu.

 Follow the instructions in the preceding Linux/Unix installation
  section.

 Testing out the SDCC Compiler

The first thing you should do after installing your SDCC
compiler is to see if it runs. Type "sdcc --version" at
the prompt, and the program should run and tell you the
version. If it doesn't run, or gives a message about not
finding sdcc program, then you need to check over your installation.
Make sure that the sdcc bin directory is in your executable
search path defined by the PATH environment setting (see
the Trouble-shooting section for suggestions). Make sure
that the sdcc program is in the bin folder, if not perhaps
something did not install correctly.

SDCC binaries are commonly installed in a directory arrangement
like this:

+--------------------------------+-------------------------------------------+
| /usr/local/bin                 | Holds executables(sdcc, s51, aslink, ...) |
+--------------------------------+-------------------------------------------+
+--------------------------------+-------------------------------------------+
| /usr/local/share/sdcc/lib      | Holds common C libraries                  |
+--------------------------------+-------------------------------------------+
| /usr/local/share/sdcc/include  | Holds common C header files               |