sdccman.txt

This a FREE tool chain which compiles C codes into 8051 binary code, converts the binary to RTL ROM,

SDCC Compiler User Guide

SDCC 2.8.3
$Date:: 2008-08-07#$ 
$Revision: 5206 $



Table of Contents

    Chapter 1 Introduction
        1.1 About SDCC
        1.2 Open Source
        1.3 Typographic conventions
        1.4 Compatibility with previous versions
        1.5 System Requirements
        1.6 Other Resources
        1.7 Wishes for the future
    Chapter 2 Installing SDCC
        2.1 Configure Options
        2.2 Install paths
        2.3 Search Paths
        2.4 Building SDCC
            2.4.1 Building SDCC on Linux
            2.4.2 Building SDCC on Mac OS X
            2.4.3 Cross compiling SDCC on Linux for Windows
            2.4.4 Building SDCC using Cygwin and Mingw32
            2.4.5 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
            2.4.6 Building SDCC Using Borland
            2.4.7 Windows Install Using a ZIP Package
            2.4.8 Windows Install Using the Setup Program
            2.4.9 VPATH feature
        2.5 Building the Documentation
        2.6 Reading the Documentation
        2.7 Testing the SDCC Compiler
        2.8 Install Trouble-shooting
            2.8.1 If SDCC does not build correctly
            2.8.2 What the "./configure" does
            2.8.3 What the "make" does
            2.8.4 What the "make install" command does.
        2.9 Components of SDCC
            2.9.1 sdcc - The Compiler
            2.9.2 sdcpp - The C-Preprocessor
            2.9.3 asxxxx, aslink, link-xxx - The Assemblers and Linkage Editors
            2.9.4 s51 - The Simulator
            2.9.5 sdcdb - Source Level Debugger
    Chapter 3 Using SDCC
        3.1 Compiling
            3.1.1 Single Source File Projects
            3.1.2 Postprocessing the Intel Hex file
            3.1.3 Projects with Multiple Source Files
            3.1.4 Projects with Additional Libraries
            3.1.5 Using sdcclib to Create and Manage Libraries
        3.2 Command Line Options
            3.2.1 Processor Selection Options
            3.2.2 Preprocessor Options
            3.2.3 Linker Options
            3.2.4 MCS51 Options
            3.2.5 DS390 / DS400 Options
            3.2.6 Z80 Options
            3.2.7 GBZ80 Options
            3.2.8 Optimization Options
            3.2.9 Other Options
            3.2.10 Intermediate Dump Options
            3.2.11 Redirecting output on Windows Shells
        3.3 Environment variables
        3.4 Storage Class Language Extensions
            3.4.1 MCS51/DS390 Storage Class Language Extensions
                3.4.1.1 data / near
                3.4.1.2 xdata / far
                3.4.1.3 idata
                3.4.1.4 pdata
                3.4.1.5 code
                3.4.1.6 bit
                3.4.1.7 sfr / sfr16 / sfr32 / sbit
                3.4.1.8 Pointers to MCS51/DS390 specific memory spaces
                3.4.1.9 Notes on MCS51 memory layout
            3.4.2 Z80/Z180 Storage Class Language Extensions
                3.4.2.1 sfr (in/out to 8-bit addresses)
                3.4.2.2 banked sfr (in/out to 16-bit addresses)
                3.4.2.3 sfr (in0/out0 to 8 bit addresses on Z180/HD64180)
            3.4.3 HC08 Storage Class Language Extensions
                3.4.3.1 data 
                3.4.3.2 xdata 
        3.5 Other SDCC language extensions
            3.5.1 Binary constants
        3.6 Absolute Addressing
        3.7 Parameters & Local Variables
        3.8 Overlaying
        3.9 Interrupt Service Routines
            3.9.1 General Information
                3.9.1.1 Common interrupt pitfall: variable not declared volatile
                3.9.1.2 Common interrupt pitfall: non-atomic access
                3.9.1.3 Common interrupt pitfall: stack overflow
                3.9.1.4 Common interrupt pitfall: use of non-reentrant functions
            3.9.2 MCS51/DS390 Interrupt Service Routines
            3.9.3 HC08 Interrupt Service Routines
            3.9.4 Z80 Interrupt Service Routines
        3.10 Enabling and Disabling Interrupts
            3.10.1 Critical Functions and Critical Statements
            3.10.2 Enabling and Disabling Interrupts directly
            3.10.3 Semaphore locking (mcs51/ds390)
        3.11 Functions using private register banks (mcs51/ds390)
        3.12 Startup Code
            3.12.1 MCS51/DS390 Startup Code
            3.12.2 HC08 Startup Code
            3.12.3 Z80 Startup Code
        3.13 Inline Assembler Code
            3.13.1 A Step by Step Introduction
            3.13.2 Naked Functions
            3.13.3 Use of Labels within Inline Assembler
        3.14 Interfacing with Assembler Code
            3.14.1 Global Registers used for Parameter Passing
            3.14.2 Registers usage
            3.14.3 Assembler Routine (non-reentrant)
            3.14.4 Assembler Routine (reentrant)
        3.15 int (16 bit) and long (32 bit) Support
        3.16 Floating Point Support
        3.17 Library Routines
            3.17.1 Compiler support routines (_gptrget, _mulint etc.)
            3.17.2 Stdclib functions (puts, printf, strcat etc.)
                3.17.2.1 <stdio.h>
                3.17.2.2 <malloc.h>
            3.17.3 Math functions (sinf, powf, sqrtf etc.)
                3.17.3.1 <math.h>
            3.17.4 Other libraries
        3.18 Memory Models
            3.18.1 MCS51 Memory Models
                3.18.1.1 Small, Medium and Large
                3.18.1.2 External Stack
            3.18.2 DS390 Memory Model
        3.19 Pragmas
        3.20 Defines Created by the Compiler
    Chapter 4 Notes on supported Processors
        4.1 MCS51 variants
            4.1.1 pdata access by SFR 
            4.1.2 Other Features available by SFR
            4.1.3 Bankswitching
                4.1.3.1 Hardware
                4.1.3.2 Software
        4.2 DS400 port
        4.3 The Z80 and gbz80 port
        4.4 The HC08 port
        4.5 The PIC14 port
            4.5.1 PIC Code Pages and Memory Banks
            4.5.2 Adding New Devices to the Port 
            4.5.3 Interrupt Code
            4.5.4 Linking and Assembling
            4.5.5 Command-Line Options
            4.5.6 Environment Variables
            4.5.7 The Library
                4.5.7.1 error: missing definition for symbol ``__gptrget1''
                4.5.7.2 Processor mismatch in file ``XXX''.
            4.5.8 Known Bugs
                4.5.8.1 Function arguments
                4.5.8.2 Regression tests fail
        4.6 The PIC16 port
            4.6.1 Global Options
            4.6.2 Port Specific Options
                4.6.2.1 Code Generation Options
                4.6.2.2 Optimization Options
                4.6.2.3 Assembling Options
                4.6.2.4 Linking Options
                4.6.2.5 Debugging Options
            4.6.3 Enviroment Variables
            4.6.4 Preprocessor Macros
            4.6.5 Directories
            4.6.6 Pragmas
            4.6.7 Header Files
            4.6.8 Libraries
                Building the libraries
            4.6.9 Adding New Devices to the Port
            4.6.10 Memory Models
            4.6.11 Stack
            4.6.12 Functions
            4.6.13 Function return values
            4.6.14 Interrupts
            4.6.15 Generic Pointers
            4.6.16 PIC16 C Libraries
                4.6.16.1 Standard I/O Streams
                4.6.16.2 Printing functions
                4.6.16.3 Signals
            4.6.17 PIC16 Port -- Tips
                4.6.17.1 Stack size
            4.6.18 Known Bugs
    Chapter 5 Debugging
        5.1 Debugging with SDCDB 
            5.1.1 Compiling for Debugging
            5.1.2 How the Debugger Works
            5.1.3 Starting the Debugger SDCDB
            5.1.4 SDCDB Command Line Options
            5.1.5 SDCDB 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
            5.1.6 Interfacing SDCDB with DDD
            5.1.7 Interfacing SDCDB with XEmacs
    Chapter 6 TIPS
        6.1 Porting code from or to other compilers
        6.2 Tools included in the distribution
        6.3 Documentation included in the distribution
        6.4 Related open source tools
        6.5 Related documentation / recommended reading
        6.6 Application notes specifically for SDCC
        6.7 Some Questions
    Chapter 7 Support
        7.1 Reporting Bugs
        7.2 Requesting Features
        7.3 Submitting patches
        7.4 Getting Help
        7.5 ChangeLog
        7.6 Subversion Source Code Repository
        7.7 Release policy
        7.8 Examples
        7.9 Quality control
        7.10 Use of SDCC in Education
    Chapter 8 SDCC Technical Data
        8.1 Optimizations
            8.1.1 Sub-expression Elimination
            8.1.2 Dead-Code Elimination
            8.1.3 Copy-Propagation
            8.1.4 Loop Optimizations
            8.1.5 Loop Reversing
            8.1.6 Algebraic Simplifications
            8.1.7 'switch' Statements
            8.1.8 Bit-shifting Operations.
            8.1.9 Bit-rotation
            8.1.10 Nibble and Byte Swapping
            8.1.11 Highest Order Bit / Any Order Bit
            8.1.12 Higher Order Byte / Higher Order Word
            8.1.13 Peephole Optimizer
        8.2 ANSI-Compliance
        8.3 Cyclomatic Complexity
        8.4 Retargetting for other Processors
    Chapter 9 Compiler internals
        9.1 The anatomy of the compiler
        9.2 A few words about basic block successors, predecessors and dominators
    Chapter 10 Acknowledgments
        Alphabetical index



Introduction

1.1 About SDCC

SDCC (Small Device C Compiler) is free open source, 
retargettable, optimizing ANSI-C compiler by Sandeep 
Dutta designed for 8 bit Microprocessors. The current 
version targets Intel MCS51 based Microprocessors 
(8031, 8032, 8051, 8052, etc.), Dallas DS80C390 
variants, Freescale (formerly Motorola) HC08 and Zilog 
Z80 based MCUs. It can be retargeted for other 
microprocessors, support for Microchip PIC, Atmel AVR 
is under development. The entire source code for the 
compiler is distributed under GPL. SDCC uses ASXXXX & ASLINK
, an open source retargetable 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 

* jump tables 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:

+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
|  

type    |       

width         | 

default   |          

signed range           | 

unsigned range                   |
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
|  

bool    |       

1 bit         | 

unsigned  |               

-                 | 

0, 1                             |
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
|  

char    |   

8 bits, 1 byte    |  

signed   |           

-128, +127            | 

0, +255                          |
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
|  

short   |  

16 bits, 2 bytes   |  

signed   |        

-32.768, +32.767         | 

0, +65.535                       |
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
|   

int    |  

16 bits, 2 bytes   |  

signed   |        

-32.768, +32.767         | 

0, +65.535                       |
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
|  

long    |  

32 bits, 4 bytes   |  

signed   | 

-2.147.483.648, +2.147.483.647  | 

0, +4.294.967.295                |
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
|  

float   |  

4 bytes IEEE 754   |  

signed   |                

                 | 

1.175494351E-38, 3.402823466E+38 |
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+
| 

pointer  | 

1, 2, 3 or 4 bytes  | 

generic   |                

                 | 

                                 |
+------------+-----------------------+-------------+-----------------------------------+------------------------------------+


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