From da87e26e52bd353c30a8fda30cbb80b92031dbb6 Mon Sep 17 00:00:00 2001 From: kbongers Date: Mon, 2 Jul 2001 05:48:50 +0000 Subject: [PATCH] Update user doc git-svn-id: https://sdcc.svn.sourceforge.net/svnroot/sdcc/trunk/sdcc@990 4a8a32a2-be11-0410-ad9d-d568d2c75423 --- doc/SDCCUdoc.html | 4439 ++++++++++- doc/SDCCUdoc.lyx | 17679 ++++++++++++++++++-------------------------- doc/SDCCUdoc.txt | 4051 +++++----- 3 files changed, 13839 insertions(+), 12330 deletions(-) diff --git a/doc/SDCCUdoc.html b/doc/SDCCUdoc.html index 5b76eac9..17638654 100644 --- a/doc/SDCCUdoc.html +++ b/doc/SDCCUdoc.html @@ -1,225 +1,4380 @@ + + - - SDCC Compiler User Guide - +SDCC Compiler User Guide + + + + + + + + + - -Next -Previous -Contents -

SDCC Compiler User Guide

Sandeep Dutta (sandeep.dutta@usa.net)

+ + +

+
+
+
+ +

1. Introduction

2. Installation

SDCC Compiler User Guide

+
+ +

+Contents +

2.1 Components of SDCC -
2.2 Installation for Version <= 2.1.7 -
2.3 Installation for Version >= 2.1.8a +
1 Introduction +
- 1.1 About SDCC +
- 1.2 Open Source +
- 1.3 System Requirements +
- 1.4 Other Resources +
+
+
2 Installation +
+
+
3 Using SDCC +
+
+
4 SDCC Technical Data +
+
+
5 TIPS +
6 Retargetting for other MCUs. +
7 SDCDB - Source Level Debugger +
+
+
8 Other Processors +
- 8.1 The Z80 and gbz80 port +
+
+
9 Support +
- 9.1 Reporting Bugs +
- 9.2 Acknowledgments +
+
+
About this document ... +

+ +

3. Compiling.

3.1 Single Source file projects. -
3.2 Projects with multiple source files. -
3.3 Projects with additional libraries. +
+1 Introduction +
+
-
4. Command Line options
+ +
+1.1 About SDCC +

-
5. Language Extensions
+SDCC is a Free ware, 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 80C390 MCS51 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 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 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 ucSim a freeware simulator for 8051 and other micro-controllers. +The latest version can be downloaded from http://sdcc.sourceforge.net/. -
- 5.1 Storage Classes.
  -
  6. Optimizations
  -
  - 6.1 Sub-expression elimination -
  - 6.2 Dead-Code elimination. -
  - 6.3 Copy-Propagation: -
  - 6.4 Loop optimizations -
  - 6.5 Algebraic simplifications: -
  - 6.6 'switch' statements. -
  - 6.7 bit-shifting operations. -
  - 6.8 Highest Order Bit. -
  - 6.9 Peep-hole optimizer. +
    +1.2 Open Source +
    + +
    +All packages used in this compiler system are opensource(freeware); +source code for all the sub-packages (asxxxx assembler/linker, pre-processor) +are 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! + +
    + +
    +1.3 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. + +
    + +
    +1.4 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 www.sourceforge.net. + +
    + +
    +2 Installation +
    + +
    + +
    +2.1 Linux/Unix Installation +
    + +
    + +
    1. Download the source package, it will be named something like sdcc-2.x.x.tgz. +
    2. Bring up a command line terminal, such as xterm. +
    3. 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. +
    4. Change directory into the main SDCC directory, for example type: ``cd +sdcc''. +
    5. Type ``./configure''. This configures the package for compilation +on your system. +
    6. Type ``make''. All of the source packages will compile, this can +take a while. +
    7. Type ``make install'' as root. This copies the binary executables +to the install directories. +
    + +
    + +
    +2.2 Windows Installation +
    + +
    +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. + +
    + +
    +2.2.1 Windows Install Using a Binary Package +
    + +
    + +
    1. 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. +
    2. 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% +
    3. 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 +
    + +
    + +
    +2.2.2 Windows Install Using Cygwin +
    + +
    + +
    1. Download and install the cygwin package from the redhat sitehttp://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). +
    2. Bring up a Unix/Bash command line terminal from the Cygwin menu. +
    3. Follow the instructions in the preceding Linux/Unix installation section. +
    + +
    + +
    +2.3 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
    + +
    +Make sure the compiler works on a very simple example. Type in the +following test.c program using your favorite editor: + +
    +main() +
    { int i; +
    i = 0; +
    i += 10; +
    } +
    +
    +Compile this using the following command: ``sdcc -c test.c''. +If all goes well, the compiler will generate a test.asm and test.rel +file. Congratulations, you've just compiled your first program with +SDCC. We used the -c option to tell SDCC not to link the generated +code, just to keep things simple for this step. + +
    +The next step is to try it with the linker. Type in ``sdcc test.c''. +If all goes well the compiler will link with the libraries and produce +a test.ihx output file. If this step fails(no test.ihx, and the linker +generates warnings), then the problem is most likely that sdcc cannot +find the usr/local/share/sdcc/lib/small directory(see the Install +trouble-shooting section for suggestions). + +
    +The final test is to ensure sdcc can use the standard header files +and libraries. Edit test.c and change it to the following: + +
    +#include <string.h> +
    main() +
    { char str1[10]; +
    strcpy(str1, ``testing''); +
    } + +
    +Compile this by typing: ``sdcc test.c''. This should generate +a test.ihx output file, and it should give no warnings such as not +finding the string.h file. If it cannot find the string.h file, then +the problem is that sdcc cannot find the /usr/local/share/sdcc/include +directory(see the Install trouble-shooting section for suggestions). + +
    + +
    +2.4 Install Trouble-shooting +
    + +
    + +
    +2.4.1 SDCC cannot find libraries or header files. +
    + +
    +The default installation assumes the libraries and header files are +located at ``/usr/local/share/sdcc/lib'' and ``/usr/local/share/sdcc/include''. +An alternative is to specify these locations as compiler options like +this: sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include +test.c + +
    + +
    +2.4.2 SDCC does not compile correctly. +
    + +
    +A few things to try include starting from scratch by unpacking the +.tgz source package again in an empty directory. If this doesn't work, +you could try downloading a different version. If this doesn't work, +you can re-direct the install messages by doing the following: + +
    +$./make > dump.txt 2>&1 + +
    +After this you can examine the dump.txt files to locate the problem. +Or these messages can be attached to an email that could be helpful +when requesting help from the mailing list. + +
    + +
    +2.4.3 What the ``./configure'' does +
    + +
    +The ``./configure'' command is a script that analyzes your system +and performs some configuration to ensure the source package compiles +on your system. It will take a few minutes to run, and will compile +a few tests to determine what compiler features are installed. + +
    + +
    +2.4.4 What the ``make'' does. +
    + +
    +This runs the GNU make tool, which automatically compiles all the +source packages into the final installed binary executables. +
    -
    7. Pointers
    + +
    +2.4.5 What the ``make install'' command does. +
    + +
    +This will install the compiler, other executables and libraries in +to the appropriate system directories. The default is to copy the +executables to /usr/local/bin and the libraries and header files to +/usr/local/share/sdcc/lib and /usr/local/share/sdcc/include. + +
    + +
    +2.5 Additional Information for Windows Users +
    + +
    +The standard method of installing on a Unix system involves compiling +the source package. This is easily done under Unix, but under Windows +it can be a more difficult process. The Cygwin is a large package +to download, and the compilation runs considerably slower under Windows +due to the overhead of the Cygwin tool set. An alternative is to install +a pre-compiled Windows binary package. There are various trade-offs +between each of these methods. + +
    +The Cygwin package allows a Windows user to run a Unix command line +interface(bash shell) and also implements a Unix like file system +on top of Windows. Included are many of the famous GNU software development +tools which can augment the SDCC compiler.This is great if you have +some experience with Unix command line tools and file system conventions, +if not you may find it easier to start by installing a binary Windows +package. The binary packages work with the Windows file system conventions. + +
    + +
    +2.5.1 Getting started with Cygwin +
    + +
    +SDCC is typically distributed as a tarred/gzipped file(.tgz). This +is a packed file similar to a .zip file. Cygwin includes the tools +you will need to unpack the SDCC distribution(tar and gzip). To unpack +it, simply follow the instructions under the Linux/Unix install section. +Before you do this you need to learn how to start a cygwin shell and +some of the basic commands used to move files, change directory, run +commands and so on. The change directory command is ``cd'', the +move command is ``mv''. To print the current working directory, +type ``pwd''. To make a directory, use ``mkdir''. + +
    +There are some basic differences between Unix and Windows file systems +you should understand. When you type in directory paths, Unix and +the Cygwin bash prompt uses forward slashes '/' between directories +while Windows traditionally uses '\' backward slashes. +So when you work at the Cygwin bash prompt, you will need to use the +forward '/' slashes. Unix does not have a concept of drive letters, +such as ``c:``, instead all files systems attach and appear +as directories. + +
    + +
    +2.5.2 Running SDCC as Native Compiled Executables +
    + +
    +If you use the pre-compiled binaries, the install directories for +the libraries and header files may need to be specified on the sdcc +command line like this: sdcc -L c:\usr\local\sdcc\lib\small +-I c:\usr\local\sdcc\include +test.c if you are running outside of a Unix bash shell. + +
    +If you have successfully installed and compiled SDCC with the Cygwin +package, it is possible to compile into native .exe files by using +the additional makefiles included for this purpose. For example, with +the Borland 32-bit compiler you would run make -f Makefile.bcc. A +command line version of the Borland 32-bit compiler can be downloaded +from the Inprise web site. + +
    + +
    +2.6 SDCC on Other Platforms +
    
    -
    8. Parameters & Local Variables
    - 8.1 Overlaying +
    - FreeBSD and other non-GNU Unixes - Make sure the GNU make +is installed as the default make tool. +
    - SDCC has been ported to run under a variety of operating systems and +processors. If you can run GNU GCC/make then chances are good SDCC +can be compiled and run on your system. +
    + +
    + +
    +2.7 Advanced Install Options +
    + +
    +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/ +
            sdcc/include/ - include header files +
            sdcc/lib/ - +
                 small/ - Object & library files for small +model library +
                 large/ - Object & library files for large +model library +
                 ds390/ - Object & library files forDS80C390 +library + +
    +The command + +
    +'./configure -prefix=/usr/local'' +
    + + +
    +will configure the compiler to be installed in directory /usr/local/bin. + +
    + +
    +2.8 Components of SDCC +
    + +
    +SDCC is not just a compiler, but a collection of tools by various +developers. These include linkers, assemblers, simulators and other +components. Here is a summary of some of the components. Note that +the included simulator and assembler have separate documentation which +you can find in the source package in their respective directories. +As SDCC grows to include support for other processors, other packages +from various developers are included and may have their own sets of +documentation. + +
    +You might want to look at the various executables which are installed +in the bin directory. At the time of this writing, we find the following +programs: + +
    +sdcc - The compiler. + +
    +aslink -The linker for 8051 type processors. + +
    +asx8051 - The assembler for 8051 type processors. + +
    +sdcpp - The C preprocessor. + +
    +sdcpd - The source debugger. + +
    +s51 - The ucSim 8051 simulator. + +
    +linkz80, linkgbz80 - The Z80 and GameBoy Z80 linkers. + +
    +as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers. + +
    +packihx - A tool to pack Intel hex files. + +
    +As development for other processors proceeds, this list will expand +to include executables to support processors like AVR, PIC, etc. + +
    + +
    +2.8.1 cpp ( C-Preprocessor) +
    + +
    +The preprocessor is extracted into the directory SDCCDIR/cpp, +it is a modified version of the GNU preprocessor. The C preprocessor +is used to pull in #include sources, process #ifdef statements, +#defines and so on. + +
    + +
    +2.8.2 asxxxx & aslink ( The assembler and Linkage Editor) +
    +
    -
    9. critical Functions.
    +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.
    -
    10. Absolute addressing.
    + +
    +2.8.3 SDCC - The compiler +
    
    -
    11. Interrupt Service Routines
    +This is the actual compiler, it in turn uses the c-preprocessor and +invokes the assembler and linkage editors. All files with the prefix +SDCC are part of the compiler and are extracted into the the +directory SDCCDIR.
    -
    12. Startup Code
    + +
    +2.8.4 S51 - Simulator +
    
    -
    13. Inline assembler code.
    +s51 is a freeware, opensource simulator developed by Daniel Drotos +<drdani@mazsola.iit.uni-miskolc.hu>. The executable is built as part +of the build process, for more information visit Daniel's website +at <http://mazsola.iit.uni-miskolc.hu/drdani/embedded/s51/>.
    -
    14. int (16 bit) and long (32 bit ) support.
    + +
    +2.8.5 SDCDB - Source Level Debugger +
    
    -
    15. Floating point support
    +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.
    -
    16. Memory Models
    + +
    +3 Using SDCC +
    
    -
    17. Flat 24 bit addressing model.
    + +
    +3.1 Compiling +
    
    -
    18. Defines created by the compiler.
    + +
    +3.1.1 Single Source File Projects +
    
    -
    19. Pragmas
    +For single source file 8051 projects the process is very simple. Compile +your programs with the following command
    -
    20. Library routines.
    +sdcc sourcefile.c +
    +
    -
```
-printf_small("my str %s, my int %d\n",(char _generic *)mystr,myint);
-  
-
```
    +The above command will compile ,assemble and link your source file. +Output files are as follows.
    +
    - 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. +
    - 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 +
      +
    - 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. +
    - sourcefile.sym - symbol listing for the sourcefile, +created by the assembler. +
      +
    - string.h - contains the following functions. -
      strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn, -strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset. +
    - sourcefile.rel - Object file created by the assembler, +input to Linkage editor. +
      +
    - ctype.h - contains the following routines. -
      iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace, -isxdigit, isalnum, isalpha. +
    - sourcefile.map - The memory map for the load module, +created by the Linker. +
      +
    - 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); 
-     //
-  
-
```
      +
    - sourcefile.<ihx | s19> - The load module : ihx - Intel +hex format (default ), s19 - Motorola S19 format when compiler option +-out-fmt-s19 is used. +
      +
    - 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. +
    -
    21. Interfacing with assembly routines.
    -
    - 21.1 Global registers used for parameter passing. -
    - 21.2 With --noregparms option. +
      +3.1.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 )
      -
      22. External Stack.
      + +
      +foo2.c (contains some more functions)
      -
      23. ANSI-Compliance.
      + +
      +foomain.c (contains more functions and the function +main)
      -
      24. Cyclomatic Complexity
      +
      -
      25. TIPS
      +The first two files will need to be compiled separately with the commands
      -
      26. Retargetting for other MCUs.
      +sdcc -c foo1.c +
      + +
      +sdcc -c foo2.c
      -
      27. Reporting Bugs
      +
      -
      28. SDCDB - Source level debugger.
      +Then compile the source file containing main and link the other files +together with the following command. -
      - 28.1 Compiling for debugging. -
      - 28.2 How the debugger works. -
      - 28.3 Starting the debugger. -
      - 28.4 Command line options. -
      - 28.5 Debugger Commands. -
      - 28.6 Interfacing with XEmacs.
        -
        29. Conclusion
        +sdcc foomain.c foo1.rel foo2.rel +
        +
        -
        30. Acknowledgments
        +Alternatively foomain.c can be separately compiled as well
        -
        31. Appendix A: The Z80 and gbz80 port
        +sdcc -c foomain.c +
        + -
        -Next -Previous -Contents +
        +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.1.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. + +
        + +
        +3.2 Command Line Options +
        + +
        + +
        +3.2.1 Processor Selection Options +
        + +
        + +
        +
        [-mmcs51]Generate code for the MCS51 (8051) family of processors. +This is the default processor target. +
        +
        [-mds390]Generate code for the DS80C390 processor. +
        +
        [-mz80]Generate code for the Z80 family of processors. +
        +
        [-mgbz80]Generate code for the GameBoy Z80 processor. +
        +
        [-mavr]Generate code for the Atmel AVR processor(In development, +not complete). +
        +
        [-mpic14]Generate code for the PIC 14-bit processors(In development, +not complete). +
        +
        [-mtlcs900h]Generate code for the Toshiba TLCS-900H processor(In +development, not complete). +
        +
        +
        + +
        +3.2.2 Path, Lib and Define Options +
        + +
        + +
        +
        [-I<path>] The additional location where the pre +processor will look for <..h> or ``..h'' files. +
        +
        [-D<macro[=value]>]Command line definition +of macros. Passed to the pre processor. +
        +
        [-lib-path(-L)]<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. +
        +
        +
        + +
        +3.2.3 MCS51 Options +
        + +
        + +
        +
        [-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]Generate code for Small +Model programs see section Memory Models for more details. This is +the default model. +
        +
        [-model-flat24]Generate code forDS80C390 +24-bit flat mode. See section Memory Models for more details. +
        +
        [-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]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. +
        +
        +
        + +
        +3.2.4 Optimization Options +
        + +
        + +
        +
        [-nogcse]Will not do global subexpression +elimination, this option may be used when the compiler creates undesirably +large stack/data spaces to store compiler temporaries. A warning message +will be generated when this happens and the compiler will indicate +the number of extra bytes it allocated. It recommended that this option +NOT be used , #pragma NOGCSE can be used to turn off global subexpression +elimination for a given function only. +
        +
        [-noinvariant]Will not do loop invariant +optimizations, this may be turned off for reasons explained for the +previous option . For more details of loop optimizations performed +see section Loop Invariants.It recommended that this option NOT be +used , #pragma NOINVARIANT can be used to turn off invariant optimizations +for a given function only. +
        +
        [-noinduction]Will not do loop induction +optimizations, see section Strength reduction for more details.It +recommended that this option NOT be used , #pragma NOINDUCTION can +be used to turn off induction optimizations for given function only. +
        +
        [-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]Will not do loop reversal +optimization +
        +
        [-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. +
        +
        +
        + +
        +3.2.5 DS390 Options +
        + +
        + +
        +
        [-stack-auto]See MCS51 section for description. +
        +
        [-stack-10bit]This option generates code for the 10 bit +stack mode of the Dallas DS80C390 part. In this mode, the stack is +located in the lower 1K of the internal RAM, which is mapped to 0x400000. +Note that the support is incomplete, since it still uses a single +byte as the stack pointer. This means that only the lower 256 bytes +of the potential 1K stack space can actually be used. However, this +does allow you to reclaim the precious 256 bytes of low RAM for use +for the DATA and IDATA segments. The compiler will not generate any +code to put the processor into 10 bit stack mode. It is important +to ensure that the processor is in this mode before calling any re-entrant +functions compiled with this option. In principle, this should work +with the -stack-auto option, but that has not been tested. It is +incompatible with the -xstack option. It also only makes sense if +the processor is in 24 bit contiguous addressing mode (see the -model-flat24 +option). +
        +
        +
        + +
        +3.2.6 Other Options +
        + +
        + +
        +
        [-callee-saves]function1[,function2][,function3].... +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 CALLEE-SAVES. . +
        +
        [-debug]When this option is used the compiler +will generate debug information , that can be used with the SDCDB. +The debug information is collected in a file with .cdb extension. +For more information see documentation for SDCDB. +
        +
        [-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)] will compile +and assemble the source only, will not call the linkage editor. +
        +
        [-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<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<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]This option will cause +the stack to be located in the internal ram after the data segment. +
        +
        [-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<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<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. +
        +
        [-E]Run only the C preprocessor. Preprocess +all the C source files specified and output the results to standard +output. +
        +
        [-M]Tell the preprocessor to output a rule +suitable for make describing the dependencies of each object file. +For each source file, the preprocessor outputs one make-rule whose +target is the object file name for that source file and whose dependencies +are all the files `#include'd in it. This rule may be a single line +or may be continued with `\'-newline if it is long. +The list of rules is printed on standard output instead of the preprocessed +C program. `-M' implies `-E'. +
        +
        [-C]Tell the preprocessor not to discard +comments. Used with the `-E' option. +
        +
        [-MM]Like `-M' but the output mentions +only the user header files included with `#include file"'. +System header files included with `#include <file>' are omitted. +
        +
        [-Aquestion(answer)]Assert the answer answer +for question, in case it is tested with a preprocessor conditional +such as `#if #question(answer)'. `-A-' disables the standard assertions +that normally describe the target machine. +
        +
        [-Aquestion](answer) Assert the answer +answer for question, in case it is tested with a preprocessor conditional +such as `#if #question(answer)'. `-A-' disables the standard assertions +that normally describe the target machine. +
        +
        [-Umacro]Undefine macro macro. `-U' options +are evaluated after all `-D' options, but before any `-include' and +`-imacros' options. +
        +
        [-dM]Tell the preprocessor to output only +a list of the macro definitions that are in effect at the end of preprocessing. +Used with the `-E' option. +
        +
        [-dD]Tell the preprocessor to pass all +macro definitions into the output, in their proper sequence in the +rest of the output. +
        +
        [-dN]Like `-dD' except that the macro arguments +and contents are omitted. Only `#define name' is included in the +output. +
        +
        [-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] Integer (16 bit) and +long (32 bit) libraries have been compiled as reentrant. Note by default +these libraries are compiled as non-reentrant. See section Installation +for more details. +
        +
        [-cyclomatic]This option will cause the +compiler to generate an information message for each function in the +source file. The message contains some important information +about the function. The number of edges and nodes the compiler detected +in the control flow graph of the function, and most importantly the +cyclomatic complexity see section on Cyclomatic Complexity +for more details. +
        +
        [-float-reent] Floating point library +is compiled as reentrant.See section Installation for more details. +
        +
        [-out-fmt-ihx]The linker output (final +object code) is in Intel Hex format. (This is the default option). +
        +
        [-out-fmt-s19]The linker output (final +object code) is in Motorola S19 format. +
        +
        [-nooverlay] The compiler will not overlay +parameters and local variables of any function, see section Parameters +and local variables for more details. +
        +
        [-main-return]This option can be used +when the code generated is called by a monitor program. The compiler +will generate a 'ret' upon return from the 'main' function. The default +option is to lock up i.e. generate a 'ljmp .' . +
        +
        [-no-peep] Disable peep-hole optimization. +
        +
        [-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<Value>]Causes the linker to +check if the interal ram usage is within limits of the given value. +
        +
        +
        + +
        +3.2.7 Intermediate Dump Options +
        + +
        +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]. This option will cause the +compiler to dump the intermediate code into a file of named <source +filename>.dumpraw just after the intermediate code has been generated +for a function , i.e. before any optimizations are done. The basic +blocks at this stage ordered in the depth first number, so they may +not be in sequence of execution. +
        +
        [-dumpgcse.]Will create a dump +if iCode, after global subexpression elimination, into a file named +<source filename>.dumpgcse. +
        +
        [-dumpdeadcode].Will create a dump if +iCode, after deadcode elimination, into a file named <source +filename>.dumpdeadcode. +
        +
        [-dumploop.]Will create a dump if iCode, +after loop optimizations, into a file named <source filename>.dumploop. +
        +
        [-dumprange.]Will create a dump if iCode, +after live range analysis, into a file named <source filename>.dumprange. +
        +
        [-dumpregassign.]Will create a dump if +iCode, after register assignment , into a file named <source +filename>.dumprassgn. +
        +
        [-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 can be helpful to include these dumps along +with the portion of the code that is causing the problem. + +
        + +
        +3.3 MCS51 Storage Class Language Extensions +
        + +
        +In addition to the ANSI storage classes SDCC allows the following +MCS51 specific storage classes. + +
        + +
        +3.3.1 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; +
        + + +
        + +
        +3.3.2 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; +
        + + +
        + +
        +3.3.3 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; +
        + + +
        + +
        +3.3.4 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; + +
        + +
        +3.3.5 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) */ + +
        + +
        +3.4 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. + +
        + +
        +3.5 Parameters & Local 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. + +
        + +
        +3.6 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. + +
        + +
        +3.7 Critical Functions +
        + +
        +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. + +
        + +
        +3.8 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. + +
        + +
        +3.9 Interrupt Service Routines +
        + +
        +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. + +
        + +
        +3.10 Startup Code +
        + +
        +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. You could add a _sdcc__external__startup() +routine to your program to override the default if you needed to setup +hardware or perform some other critical operation prior to static +& global variable initialization. + +
        + +
        +3.11 Inline Assembler Code +
        + +
        +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. + +
        + +
        +3.12 int(16 bit) and long (32 bit ) Support +
        + +
        +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. + +
        + +
        +3.13 Floating Point Support +
        + +
        +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) + +
        + +
        +3.14 MCS51 Memory Models +
        + +
        +SDCC allows two memory models for MCS51 code, small and large. Modules +compiled with different memory models should never be combined together +or the results would be unpredictable. The library routines supplied +with the compiler are compiled as both small and large. The compiled +library modules are contained in seperate directories as small and +large so that you can link to either set. 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. Several optimizations are disabled when the +program is compiled using the large model, it is therefore strongly +recommdended that the small model be used unless absolutely required. + +
        + +
        +3.15 Flat 24 bit Addressing Model +
        + +
        +This option generates code for the 24 bit contiguous addressing mode +of the Dallas DS80C390 part. In this mode, up to four meg of external +RAM or code space can be directly addressed. See the data sheets at +www.dalsemi.com for further information on this part. + +
        +In older versions of the compiler, this option was used with the MCS51 +code generator (-mmcs51). Now, however, the '390 has it's own code +generator, selected by the -mds390 switch. This code generator currently +supports only the flat24 model, but the -model-flat24 switch is still +required, in case later versions of the code generator support other +models (such as the paged mode of the '390). The combination of -mmcs51 +and -model-flat24 is now depracated. + +
        +Note that the compiler does not generate any code to place the processor +into24 bitmode (it defaults to 8051 compatible mode). Boot loader +or similar code must ensure that the processor is in 24 bit contiguous +addressing mode before calling the SDCC startup code. + +
        +Like the -model-large option, variables will by default be placed +into the XDATA segment. + +
        +Segments may be placed anywhere in the 4 meg address space using the +usual -*-loc options. Note that if any segments are located above +64K, the -r flag must be passed to the linker to generate the proper +segment relocations, and the Intel HEX output format must be used. +The -r flag can be passed to the linker by using the option -Wl-r +on the sdcc command line. + +
        + +
        +3.16 Defines Created by the Compiler +
        + +
        +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. +
        +
        + +
        + +
        +4 SDCC Technical Data +
        + +
        + +
        +4.1 Optimizations +
        + +
        +SDCC performs a a host of standard optimizations in addition to some +MCU specific optimizations. + +
        + +
        +4.1.1 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. + +
        + +
        +4.1.2 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; +
        } +
        + + +
        + +
        +4.1.3 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 . + +
        + +
        +4.1.4 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). + +
        + +
        +
        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. + +
        + +
        +
        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. + +
        + +
        +4.1.5 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. + +
        + +
        +4.1.6 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. + +
        + +
        +4.1.7 'switch' Statements +
        + +
        +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 . + +
        + +
        +4.1.8 Bit-shifting Operations. +
        + +
        +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) + +
        + +
        +4.1.9 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 */ + +
        + +
        +4.1.10 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. + +
        + +
        +4.1.11 Peep-hole Optimizer +
        + +
        +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. + +
        + +
        +4.2 Pragmas +
        + +
        +SDCC supports the following #pragma directives. This directives +are applicable only at a function level. + +
        + +
        +
        SAVE - this will save all the current options . +
        +
        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 - will stop global subexpression elimination. +
        +
        NOINDUCTION - will stop loop induction optimizations . +
        +
        NOJTBOUND - will not generate code for boundary value checking +, when switch statements are turned into jump-tables. +
        +
        NOOVERLAY - the compiler will not overlay the parameters +and local variables of a function. +
        +
        NOLOOPREVERSE - Will not do loop reversal optimization +
        +
        EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude +pragma disables generation of pair of push/pop instruction in ISR +function (using interrupt keyword). The directive should be placed +immediately before the ISR function definition and it affects ALL +ISR functions following it. To enable the normal register saving for +ISR functions use ``#pragma EXCLUDE none'' +
        +
        CALLEE-SAVES function1[,function2[,function3...]] +- 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 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. + +
        + +
        +4.3 Library Routines +
        + +
        +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. + +
        + +
        +4.4 Interfacing with Assembly Routines +
        + +
        + +
        +4.5 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). + +
        + +
        +4.5.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 + +
        + +
        +4.5.2 Assembler Routine(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. + +
        + +
        +4.6 With -noregparms Option +
        + +
        +When the source is compiled with -noregparms option , space is allocated +for each of the parameters passed to a routine. + +
        + +
        +4.6.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 + +
        + +
        +4.6.2 Assembler Routine(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. + +
        + +
        +4.7 External Stack +
        + +
        +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. + +
        + +
        +4.8 ANSI-Compliance +
        + +
        +Deviations from the compliancy. + +
        + +
        +
        functions are not always reentrant. +
        +
        structures cannot be assigned values directly, cannot be passed as +function parameters or assigned to each other and cannot be a return +value from a function. + +
        +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 +*/ +
        } +
        + + +
        + +
        +
        'long long' (64 bit integers) not supported. +
        +
        'double' precision floating point not supported. +
        +
        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. +
        +
        No support for setjmp and longjmp (for now). +
        +
        Old K&R style function declarations are NOT allowed. +
        +
        +foo( i,j) /* this old style of function declarations +*/ +
        int i,j; /* are valid in ANSI .. not valid in SDCC +*/ +
        { +
        ... +
        } +
        + + +
        + +
        +
        functions declared as pointers must be dereferenced during the call. + +
        +int (*foo)(); +
        + + +
        +
        +
        + ... +
        /* has to be called like this */ +
        (*foo)();/* ansi standard allows calls to be made +like 'foo()' */ +
        + + +
        + +
        +4.9 Cyclomatic Complexity +
        + +
        +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. + +
        + +
        +5 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 on MCS51 memory layout(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. + +
        + +
        +6 Retargetting for other MCUs. +
        + +
        +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. + +
        + +
        +
        Parsing the source and building the annotated parse tree. This phase +is largely MCU independent (except for the language extensions). Syntax +& semantic checks are also done in this phase , along with some initial +optimizations like back patching labels and the pattern matching optimizations +like bit-rotation etc. +
        +
        The second phase involves generating an intermediate code which can +be easy manipulated during the later phases. This phase is entirely +MCU independent. The intermediate code generation assumes the target +machine has unlimited number of registers, and designates them with +the name iTemp. The compiler can be made to dump a human readable +form of the code generated by using the -dumpraw option. +
        +
        This phase does the bulk of the standard optimizations and is also +MCU independent. This phase can be broken down into several sub-phases. + +
        + +
        +
        Break down intermediate code (iCode) into basic blocks. +
        +
        Do control flow & data flow analysis on the basic blocks. +
        +
        Do local common subexpression elimination, then global subexpression +elimination +
        +
        dead code elimination +
        +
        loop optimizations +
        +
        if loop optimizations caused any changes then do 'global subexpression +elimination' and 'dead code elimination' again. +
        +
        +
        +
        This phase determines the live-ranges; by live range I mean those +iTemp variables defined by the compiler that still survive after all +the optimizations. Live range analysis is essential for register allocation, +since these computation determines which of these iTemps will be assigned +to registers, and for how long. +
        +
        Phase five is register allocation. There are two parts to this process +. + +
        + +
        +
        The first part I call 'register packing' (for lack of a better term) +. In this case several MCU specific expression folding is done to +reduce register pressure. +
        +
        The second part is more MCU independent and deals with allocating +registers to the remaining live ranges. A lot of MCU specific code +does creep into this phase because of the limited number of index +registers available in the 8051. +
        +
        +
        +
        The Code generation phase is (unhappily), entirely MCU dependent and +very little (if any at all) of this code can be reused for other MCU. +However the scheme for allocating a homogenized assembler operand +for each iCode operand may be reused. +
        +
        As mentioned in the optimization section the peep-hole optimizer is +rule based system, which can reprogrammed for other MCUs. +
        +
        + +
        + +
        +7 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 is part of the standard compiler installation, which +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. + +
        + +
        +7.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 . + +
        + +
        +7.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 . + +
        + +
        +7.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. + +
        + +
        +
        foo.c - the source file. +
        +
        foo.cdb - the debugger symbol information file. +
        +
        foo.ihx - the intel hex format object file. +
        +
        + +
        + +
        +7.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. +
        +
        + +
        + +
        +7.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. + +
        + +
        +7.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 + +
        + +
        +7.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 + +
        + +
        +7.5.3 continue +
        + +
        +Continue program being debugged, after breakpoint. + +
        + +
        +7.5.4 finish +
        + +
        +Execute till the end of the current function. + +
        + +
        +7.5.5 delete [n] +
        + +
        +Delete breakpoint number 'n'. If used without any option clear ALL +user defined break points. + +
        + +
        +7.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. +
        +
        + +
        + +
        +7.5.7 step +
        + +
        +Step program until it reaches a different source line. + +
        + +
        +7.5.8 next +
        + +
        +Step program, proceeding through subroutine calls. + +
        + +
        +7.5.9 run +
        + +
        +Start debugged program. + +
        + +
        +7.5.10 ptype variable +
        + +
        +Print type information of the variable. + +
        + +
        +7.5.11 print variable +
        + +
        +print value of variable. + +
        + +
        +7.5.12 file filename +
        + +
        +load the given file name. Note this is an alternate method of loading +file for debugging. + +
        + +
        +7.5.13 frame +
        + +
        +print information about current frame. + +
        + +
        +7.5.14 set srcmode +
        + +
        +Toggle between C source & assembly source. + +
        + +
        +7.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. + +
        + +
        +7.5.16 quit. +
        + +
        +"Watch me now. Iam going Down. My name is Bobby Brown" + +
        + +
        +7.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 +
        ;; +
        +
        + + +
        + +
        +8 Other Processors +
        + +
        + +
        +8.1 The Z80 and gbz80 port +
        + +
        +SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like +gbz80. The port is incomplete - long support is incomplete (mul, div +and mod are unimplimented), and both float and bitfield support is +missing, but apart from that the code generated is correct. + +
        +As always, the code is the authoritave reference - see z80/ralloc.c +and z80/gen.c. The stack frame is similar to that generated by the +IAR Z80 compiler. IX is used as the base pointer, HL is used as a +temporary register, and BC and DE are available for holding varibles. +IY is currently unusued. Return values are stored in HL. One bad side +effect of using IX as the base pointer is that a functions stack frame +is limited to 127 bytes - this will be fixed in a later version. + +
        + +
        +9 Support +
        + +
        +SDCC has grown to be large project, the compiler alone (without the +Assembler Package, Preprocessor) is about 40,000 lines of code (blank +stripped). The open source nature of this project is a key to its +continued growth and support. You gain the benefit and support of +many active software developers and end users. Is SDCC perfect? No, +that's why we need your help. The developers take pride in fixing +reported bugs. You can help by reporting the bugs and helping other +SDCC users. There are lots of ways to contribute, and we encourage +you to take part in making SDCC a great software package. + +
        + +
        +9.1 Reporting Bugs +
        + +
        +Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' +or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed ASAP. When +reporting a bug, it is very useful to include a small test program +which reproduces the problem. If you can isolate the problem by looking +at the generated assembly code, this can be very helpful. Compiling +your program with the -dumpall option can sometimes be useful in +locating optimization problems. + +
        + +
        +9.2 Acknowledgments +
        + +
        +Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code +generator, Debugger, AVR port +
        +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 +
        +Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience +and support. +
        +Unknown - for the GNU C - preprocessor. +
        +Michael Hope - The Z80 and Z80GB port, 186 development +
        +Kevin Vigor - The DS390 port. +
        +Johan Knol - DS390/TINI libs, lots of fixes and enhancements. +
        +Scott Datallo - PIC port. +
        (Thanks to all the other volunteer developers who have helped with +coding, testing, web-page creation, distribution sets, etc. You know +who you are :-) +
        +
        +This document initially written by Sandeep Dutta + +
        +All product names mentioned herein may be trademarks of their respective +companies. + +
        + + +
        +About this document ... +
        + SDCC Compiler User Guide
        +This document was generated using the +LaTeX2HTML translator Version 2K.1beta (1.47) +
        +Copyright © 1993, 1994, 1995, 1996, +Nikos Drakos, +Computer Based Learning Unit, University of Leeds. +
        +Copyright © 1997, 1998, 1999, +Ross Moore, +Mathematics Department, Macquarie University, Sydney. +
        +The command line arguments were:
        + latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir72816uWRHo/lyx_tmpbuf7281E6F6dg/SDCCUdoc.tex +
        +The translation was initiated by Karl Bongers on 2001-07-02
        + + + + +
        + +
        +Karl Bongers +2001-07-02 +
        diff --git a/doc/SDCCUdoc.lyx b/doc/SDCCUdoc.lyx index cc06d741..b88a2869 100644 --- a/doc/SDCCUdoc.lyx +++ b/doc/SDCCUdoc.lyx @@ -1,6 +1,5 @@ -#This file was created by Wed Oct 4 16:57:26 2000 -#LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team -\lyxformat 2.15 +#LyX 1.1 created this file. For more info see http://www.lyx.org/ +\lyxformat 218 \textclass article \language english \inputencoding default @@ -26,25 +25,40 @@ \layout Title SDCC Compiler User Guide -\layout Author +\layout Standard + + +\begin_inset LatexCommand \tableofcontents{} + +\end_inset + -Sandeep Dutta (sandeep.dutta@usa.net) \layout Section Introduction +\layout Subsection + +About SDCC \layout Standard -SDCC is a Free ware , retargettable, optimizing ANSI-C compiler. - The current version targets Intel 8051 based MCUs, including the Dallas - 80C390 variant, as well as the Zilog Z80 family. - It can be retargetted for other 8 bit MCUs or PICs. + +\series bold +SDCC +\series default + is a Free ware, retargettable, optimizing ANSI-C compiler by +\series bold +Sandeep Dutta +\series default + designed for 8 bit Microprocessors. + The current version targets Intel MCS51 based Microprocessors(8051,8052, + etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51 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 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 + SDCC has extensive language extensions suitable for utilizing various microcont +rollers underlying hardware effectively. + In addition to the MCU specific optimizations SDCC also does a host of standard optimizations like \emph on global sub expression elimination, loop optimizations (loop invariant, @@ -54,8 +68,9 @@ SDCC is a Free ware , retargettable, optimizing ANSI-C compiler. \emph default 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. + 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 \emph on short (8 bits, 1 byte), char (8 bits, 1 byte), int (16 bits, 2 bytes ), @@ -69,27 +84,30 @@ 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 + 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. + currently uses ucSim a freeware simulator for 8051 and other micro-controllers. The latest version can be downloaded from \series bold -http://sdcc.sourceforge.net + +\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/} + +\end_inset + +. +\layout Subsection + +Open Source \layout Standard All packages used in this compiler system are \emph on opensource \emph default - (freeware); source code for all the sub-packages ( asxxxx assembler/linker - , pre-processor and -\emph on - gc -\emph default - a conservative garbage collector) are distributed with the package. - Documentation was created using a freeware word processor (LyX). +(freeware); source code for all the sub-packages (asxxxx assembler/linker, + pre-processor) are distributed with the package. + This documentation is maintained using a freeware word processor (LyX). \layout Standard @@ -107,11650 +125,8385 @@ This program is free software; you can redistribute it and/or modify it You are forbidden to forbid anyone else to use, share and improve what you give them. Help stamp out software-hoarding! -\layout Section - -Installation -\begin_inset LatexCommand \label{Installation} - -\end_inset - - -\layout Standard - -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 -\emph on -linux -\emph default - you probably already have it, if you are using -\emph on -Windows 9x/NT -\emph default - go to -\emph on -http://sources.redhat.com/ -\emph default - and download -\emph on -Cygwin. +\layout Subsection -\emph default - +System Requirements \layout Standard -After you have installed -\emph on -gcc -\emph default - 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 ( -\emph on -.zip -\emph default - or -\emph on -.tar.gz -\emph default -) into some directory , which we shall refer to as -\emph on -SDCCDIR -\emph default - from now on. +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. \layout Subsection -Components of SDCC -\begin_inset LatexCommand \label{Components} - -\end_inset - - -\layout Subsubsection - -gc ( a conservative garbage collector) +Other Resources \layout Standard -SDCC relies on this component to do all the memory management, this excellent - package is copyrighted by -\emph on -Jans J Boehm(boehm@sgi.com) and Alan J Demers -\emph default - but can be used with minimum restrictions. - The GC source will be extracted into the directory -\emph on -SDCCDIR/gc. - -\emph default - -\layout Subsubsection - -cpp ( C-Preprocessor) -\layout Standard +The SDCC home page at +\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/} -The preprocessor is extracted into the directory -\emph on -SDCCDIR/cpp -\emph default -, it is a modified version of the GNU preprocessor. -\layout Subsubsection +\end_inset -asxxxx & aslink ( The assembler and Linkage Editor) -\layout Standard + 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 www.sourceforge.net. +\layout Section -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 -\emph on -SDCCDIR/asxxxx. -\layout Subsubsection +Installation +\layout Subsection -SDCC - The compiler. -\layout Standard +Linux/Unix Installation +\layout Enumerate -This is the actual compiler, it uses -\emph on -gc -\emph default - and invokes the assembler and linkage editor. - All files with the prefix -\emph on -SDCC -\emph default -are part of the compiler and is extracted into the the directory -\emph on -SDCCDIR. -\layout Subsubsection -S51 - Simulator -\layout Standard +\series medium +Download the source package, it will be named something like sdcc-2.x.x.tgz. +\layout Enumerate -Version 2.1.8 onwards contains s51 a freeware , opensource simulator developed - by Daniel Drotos . - The executable is built as part of build process, for more information - visit Daniel's website at . -\layout Subsubsection -SDCDB - Source level Debugger. -\layout Standard +\series medium +Bring up a command line terminal, such as xterm. +\layout Enumerate -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. -\layout Subsection -Installation for Version <= 2.1.7 -\layout Standard +\series medium +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. +\layout Enumerate -After the package is extracted ( -\emph on -Windows 95/NT -\emph default - users start -\emph on -CYGWIN shell) -\emph default -, change to the directory where you extracted the package and give the command. -\layout Standard +Change directory into the main SDCC directory, for example type: +\begin_inset Quotes eld +\end_inset -./sdccbuild.sh -\layout Standard +cd sdcc +\begin_inset Quotes erd +\end_inset -This is a -\emph on -bash -\emph default - shell script, it will compile all the above mentioned components and install - the executables into the directory -\emph on -SDCCDIR/bin -\emph default - make sure you add this directory to your -\emph on -PATH -\emph default - 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. -\layout Subsection +. +\layout Enumerate -Installation for Version >= 2.1.8a -\layout Standard -The distribution method from Version 2.1.8a has been changed to be conforment - with the +\series medium +Type \begin_inset Quotes eld \end_inset -autoconf +./configure \begin_inset Quotes erd \end_inset - utility. - The source is now distributed as -\series bold -\size large -\emph on -sdcc-.tar.gz format + \series default -\size default -\emph default - , instead of the older .zip format. - The steps for installation are as follows. -\layout Subsubsection +. + This configures the package for compilation on your system. +\layout Enumerate -Unpack the sources. -\layout Standard -This is usually done by the following command +\series medium +Type \begin_inset Quotes eld \end_inset +make +\begin_inset Quotes erd +\end_inset + +. -\series bold -\size large -\emph on -gunzip -c sdcc-.tar.gz | tar -xv - \series default -\size default -\emph default + All of the source packages will compile, this can take a while. +\layout Enumerate + +\series medium +Type \begin_inset Quotes eld \end_inset +make install +\begin_inset Quotes erd +\end_inset -\layout Subsubsection -Change to the main source directory (usually sdcc or sdcc-) -\layout Subsubsection +\series default + as root +\series medium +. -Issue command to configure your system -\layout Standard +\series default + This copies the binary executables to the install directories. +\layout Subsection -The configure command has several options the most commonly used option - is --prefix=, where 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 specified. - +Windows Installation \layout Standard -bin/ - binary exectables (add to PATH environment variable) -\newline -share/ -\newline +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. +\layout Subsubsection -\protected_separator +Windows Install Using a Binary Package +\layout Enumerate -\protected_separator +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: +\backslash +usr +\backslash +local +\backslash +bin for the executables, c: +\backslash +usr +\backslash +local +\backslash +share +\backslash +sdcc +\backslash +include and c: +\backslash +usr +\backslash +local +\backslash +share +\backslash +sdcc +\backslash +lib for the include and libraries. +\layout Enumerate -\protected_separator +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: +\backslash +usr +\backslash +local +\backslash +bin;%PATH% +\layout Enumerate -\protected_separator +When you compile with sdcc, you may need to specify the location of the + lib and include folders. + For example, sdcc -I c: +\backslash +usr +\backslash +local +\backslash +share +\backslash +sdcc +\backslash +include -L c: +\backslash +usr +\backslash +local +\backslash +share +\backslash +sdcc +\backslash +lib +\backslash +small test.c +\layout Subsubsection -\protected_separator +Windows Install Using Cygwin +\layout Enumerate -\protected_separator -sdcc51inc/ - include header files -\newline -\protected_separator +\series medium +Download and install the cygwin package from the redhat site +\series default +\emph on -\protected_separator +\begin_inset LatexCommand \htmlurl{http://sources.redhat.com/cygwin/} -\protected_separator +\end_inset -\protected_separator -\protected_separator +\series medium +\emph default +. + Currently, this involved downloading a small install program which then + automates downloading and installing +\series default +selected parts of +\series medium + the package +\series default +(a large 80M byte sized dowload for the whole thing) +\series medium +. -\protected_separator -sdcc51lib/ - -\newline +\series default + +\layout Enumerate -\protected_separator -\protected_separator +\series medium +Bring up a +\series default +Unix/Bash +\series medium +command line terminal from the Cygwin menu. +\layout Enumerate -\protected_separator -\protected_separator +\series medium +Follow the instructions in the preceding Linux/Unix installation section. +\layout Subsection -\protected_separator +Testing out the SDCC Compiler +\layout Standard -\protected_separator +The first thing you should do after installing your SDCC compiler is to + see if it runs. + Type +\begin_inset Quotes eld +\end_inset -\protected_separator +sdcc --version +\begin_inset Quotes erd +\end_inset -\protected_separator + 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. +\layout Standard -\protected_separator -\protected_separator +\series medium +SDCC binaries are commonly installed in a directory arrangement like this: +\layout Standard -\protected_separator -\protected_separator +\begin_inset Tabular + + + + + + +\begin_inset Text -\protected_separator -small/ - Object & Library files for small model library -\newline +\layout Standard -\protected_separator +/ +\series medium +usr/local/bin +\end_inset + + +\begin_inset Text -\protected_separator +\layout Standard -\protected_separator -\protected_separator +\series medium +Holds executables(sdcc, s51, aslink, +\series default +... +\series medium +) +\end_inset + + + + +\begin_inset Text -\protected_separator +\layout Standard -\protected_separator +/ +\series medium +usr/local/share/sdcc/lib +\end_inset + + +\begin_inset Text -\protected_separator +\layout Standard -\protected_separator -\protected_separator +\series medium +Holds common C +\series default +libraries +\end_inset + + + + +\begin_inset Text -\protected_separator +\layout Standard -\protected_separator +/ +\series medium +usr/local/share/sdcc/include +\end_inset + + +\begin_inset Text -\protected_separator +\layout Standard -\protected_separator -large/ - Object & library files for large model library -\newline -\protected_separator +\series medium +Holds common C header files +\end_inset + + + -\protected_separator +\end_inset -\protected_separator -\protected_separator +\layout Standard -\protected_separator -\protected_separator +\series medium +Make sure the compiler works on a very simple example. + Type in the following test.c program using your favorite editor: +\layout Standard -\protected_separator -\protected_separator +\emph on +main() +\newline +{ int i; +\newline +i = 0; +\newline +i += 10; +\newline +} +\series medium +\emph default -\protected_separator +\newline -\protected_separator +\layout Standard -\protected_separator -\protected_separator +\series medium +Compile this using the following command: +\begin_inset Quotes eld +\end_inset -\protected_separator -ds390/ - Object & library files forDS80C390 library -\newline +sdcc -c test.c +\begin_inset Quotes erd +\end_inset +. + If all goes well, the compiler will generate a test.asm and test.rel file. + Congratulations, you've just compiled your first program with SDCC. + We used the -c option to tell SDCC not to link the generated code, just + to keep things simple for this step. \layout Standard -The command -\layout Standard +\series medium +The next step is to try it with the linker. + Type in +\begin_inset Quotes eld +\end_inset -\series bold -\size large -\bar under -'./configure --prefix=/usr/local +sdcc test.c \begin_inset Quotes erd \end_inset - +. + If all goes well the compiler will link with the libraries and produce + a test.ihx output file. + If this step fails(no test.ihx, and the linker generates warnings), then + the problem is most likely that sdcc cannot find the usr/local/share/sdcc/lib +\series default +/small +\series medium + directory(see the Install trouble-shooting section for suggestions). \layout Standard -will create configure the compiler to be installed in directory /usr/local/bin. -\layout Subsubsection - -make -\layout Standard -After configuration step issue the command +\series medium +The final test is to ensure sdcc can use the standard header files and libraries. + Edit test.c and change it to the following: \layout Standard -\series bold -\size large -\bar under - +\emph on +#include +\newline +main() +\newline +{ char str1[10]; +\newline +strcpy(str1, \begin_inset Quotes eld \end_inset -make +testing \begin_inset Quotes erd \end_inset - +); +\newline +} \layout Standard -This will compile the compiler -\layout Subsubsection - +\series medium +Compile this by typing: \begin_inset Quotes eld \end_inset -make install +sdcc test.c \begin_inset Quotes erd \end_inset +. + This should generate a test.ihx output file, and it should give no warnings + such as not finding the string.h file. + If it cannot find the string.h file, then the problem is that sdcc cannot + find the /usr/local/share/sdcc/include directory(see the Install trouble-shooti +ng section for suggestions). +\layout Subsection -\layout Standard - -Will install the compiler and libraries in the appropriate directories. +Install Trouble-shooting \layout Subsubsection -Special Notes for Windows Users. - Provided by Michael Jamet[ mjamet@computer.org] +SDCC cannot find libraries or header files. \layout Standard -Please note: these instructions are valid for Cygwin versions prior to 1.0. - If you have Cygwin 1.0 or later, the generic +The default installation assumes the libraries and header files are located + at \begin_inset Quotes eld \end_inset -configure/make/make install +/usr/local/share/sdcc/lib \begin_inset Quotes erd \end_inset - procedure described above should work as expected from the Cygwin shell. - If you have an earlier version of Cygwin, I strongly recommend upgrading. - If, however, you insist on using an earlier version, the following instructions - should prove helpful. -\layout Standard + and +\begin_inset Quotes eld +\end_inset +/usr/local/share/sdcc/include +\begin_inset Quotes erd +\end_inset -\protected_separator +. + An alternative is to specify these locations as compiler options like this: + sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include test.c +\layout Subsubsection +SDCC does not compile correctly. \layout Standard +A few things to try include starting from scratch by unpacking the .tgz source + package again in an empty directory. + If this doesn't work, you could try downloading a different version. + If this doesn't work, you can re-direct the install messages by doing the + following: +\layout Standard -\protected_separator - How to install SDCC from source on a Windows 95 or Windows NT 4 system - +$./make > dump.txt 2>&1 \layout Standard +After this you can examine the dump.txt files to locate the problem. + Or these messages can be attached to an email that could be helpful when + requesting help from the mailing list. +\layout Subsubsection + +What the +\begin_inset Quotes eld +\end_inset -\protected_separator +./configure +\begin_inset Quotes erd +\end_inset + does \layout Standard +The +\begin_inset Quotes eld +\end_inset -\protected_separator - This document describes how to install SDCC on a Win 95 or Win NT 4 system. - -\layout Standard +./configure +\begin_inset Quotes erd +\end_inset + command is a script that analyzes your system and performs some configuration + to ensure the source package compiles on your system. + It will take a few minutes to run, and will compile a few tests to determine + what compiler features are installed. +\layout Subsubsection -\protected_separator - These instructions probably work for Win 98 as well, but have not been - -\layout Standard +What the +\begin_inset Quotes eld +\end_inset +make +\begin_inset Quotes erd +\end_inset -\protected_separator - tested on that platform. - + does. \layout Standard +This runs the GNU make tool, which automatically compiles all the source + packages into the final installed binary executables. +\layout Subsubsection -\protected_separator - -\layout Standard +What the +\begin_inset Quotes eld +\end_inset +make install +\begin_inset Quotes erd +\end_inset -\protected_separator - There are lots of little differences between UNIX and the Win32 Cygnus - + command does. \layout Standard +This will install the compiler, other executables and libraries in to the + appropriate system directories. + The default is to copy the executables to /usr/local/bin and the libraries + and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include. +\layout Subsection -\protected_separator - environment which make porting more difficult than it should be. -\protected_separator - If +Additional Information for Windows Users \layout Standard - -\protected_separator - you want the details, please contact me. -\protected_separator - Otherwise just follow these +The standard method of installing on a Unix system involves compiling the + source package. + This is easily done under Unix, but under Windows it can be a more difficult + process. + The Cygwin is a large package to download, and the compilation runs considerabl +y slower under Windows due to the overhead of the Cygwin tool set. + An alternative is to install a pre-compiled Windows binary package. + There are various trade-offs between each of these methods. + \layout Standard +The Cygwin package allows a Windows user to run a Unix command line interface(ba +sh shell) and also implements a Unix like file system on top of Windows. + Included are many of the famous GNU software development tools which can + augment the SDCC compiler.This is great if you have some experience with + Unix command line tools and file system conventions, if not you may find + it easier to start by installing a binary Windows package. + The binary packages work with the Windows file system conventions. +\layout Subsubsection -\protected_separator - instructions. - +Getting started with Cygwin \layout Standard +SDCC is typically distributed as a tarred/gzipped file(.tgz). + This is a packed file similar to a .zip file. + Cygwin includes the tools you will need to unpack the SDCC distribution(tar + and gzip). + To unpack it, simply follow the instructions under the Linux/Unix install + section. + Before you do this you need to learn how to start a cygwin shell and some + of the basic commands used to move files, change directory, run commands + and so on. + The change directory command is +\begin_inset Quotes eld +\end_inset -\protected_separator +cd +\begin_inset Quotes erd +\end_inset -\layout Standard +, the move command is +\begin_inset Quotes eld +\end_inset +mv +\begin_inset Quotes erd +\end_inset -\protected_separator - 1. - Install the Cygnus Software -\layout Standard +. + To print the current working directory, type +\begin_inset Quotes eld +\end_inset +pwd +\begin_inset Quotes erd +\end_inset -\protected_separator - Go to http://sourceware.cygnus.com/cygwin. -\protected_separator - Cygnus provides a UNIX like -\layout Standard +. + To make a directory, use +\begin_inset Quotes eld +\end_inset +mkdir +\begin_inset Quotes erd +\end_inset -\protected_separator - environment for Win 32 systems. -\protected_separator - Download "full.exe" and install. -\protected_separator - You +. \layout Standard +There are some basic differences between Unix and Windows file systems you + should understand. + When you type in directory paths, Unix and the Cygwin bash prompt uses + forward slashes '/' between directories while Windows traditionally uses + ' +\backslash +' backward slashes. + So when you work at the Cygwin bash prompt, you will need to use the forward + '/' slashes. + Unix does not have a concept of drive letters, such as +\begin_inset Quotes eld +\end_inset -\protected_separator - MUST install it on your C drive. -\protected_separator - "full.exe" contains a shell AND many -\layout Standard +c: +\begin_inset Quotes eld +\end_inset +, instead all files systems attach and appear as directories. +\layout Subsubsection -\protected_separator - common UNIX utilities. - +Running SDCC as Native Compiled Executables \layout Standard +If you use the pre-compiled binaries, the install directories for the libraries + and header files may need to be specified on the sdcc command line like + this: sdcc -L c: +\backslash +usr +\backslash +local +\backslash +sdcc +\backslash +lib +\backslash +small -I c: +\backslash +usr +\backslash +local +\backslash +sdcc +\backslash +include test.c if you are running outside of a Unix bash shell. +\layout Standard -\protected_separator +If you have successfully installed and compiled SDCC with the Cygwin package, + it is possible to compile into native .exe files by using the additional + makefiles included for this purpose. + For example, with the Borland 32-bit compiler you would run make -f Makefile.bcc. + A command line version of the Borland 32-bit compiler can be downloaded + from the Inprise web site. +\layout Subsection -\layout Standard +SDCC on Other Platforms +\layout Itemize -\protected_separator - 2. - Download and Extract the Latest SDCC -\layout Standard +\series bold +FreeBSD and other non-GNU Unixes +\series default +- Make sure the GNU make is installed as the default make tool. +\layout Itemize +SDCC has been ported to run under a variety of operating systems and processors. + If you can run GNU GCC/make then chances are good SDCC can be compiled + and run on your system. +\layout Subsection -\protected_separator - The latest version can be found at +Advanced Install Options \layout Standard +The +\begin_inset Quotes eld +\end_inset -\protected_separator +configure +\begin_inset Quotes erd +\end_inset -\protected_separator - www.geocities.com/ResearchTriange/Forum/1353. + command has several options. + The most commonly used option is --prefix=, where 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 specified. \layout Standard +bin/ - binary exectables (add to PATH environment variable) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +share/ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcc/include/ - include header files +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +sdcc/lib/ - +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +small/ - Object & library files for small model library +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +large/ - Object & library files for large model library +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +ds390/ - Object & library files forDS80C390 library +\layout Standard -\protected_separator - It can be uncompressed with winzip. - +The command \layout Standard -\protected_separator +\series bold +\size large +\bar under +'./configure --prefix=/usr/local +\begin_inset Quotes erd +\end_inset + \layout Standard +will configure the compiler to be installed in directory /usr/local/bin. +\layout Subsection -\protected_separator - 3. -\protected_separator - Start a Cygnus Shell +Components of SDCC \layout Standard - -\protected_separator - There should be an entry in the Start Menu for Cygnus. -\protected_separator - Invoke the shell. - +SDCC is not just a compiler, but a collection of tools by various developers. + These include linkers, assemblers, simulators and other components. + Here is a summary of some of the components. + Note that the included simulator and assembler have separate documentation + which you can find in the source package in their respective directories. + As SDCC grows to include support for other processors, other packages from + various developers are included and may have their own sets of documentation. \layout Standard - -\protected_separator - This gives you a UNIX like environment. -\protected_separator - FROM THIS POINT ON, DIRECTORIES +You might want to look at the various executables which are installed in + the bin directory. + At the time of this writing, we find the following programs: \layout Standard -\protected_separator - MUST BE SPECIFIED WITH FORWARD SLASHES (/) NOT THE DOS STYLE BACK +\series bold +sdcc +\series default + - The compiler. \layout Standard -\protected_separator - SLASHES ( -\backslash -) BECAUSE THIS IS WHAT UNIX EXPECTS. -\protected_separator - - +\series bold +aslink +\series default + -The linker for 8051 type processors. \layout Standard -\protected_separator - -\protected_separator - ex. - " -\backslash -winnt" would be "/winnt" under the shell. - +\series bold +asx8051 +\series default + - The assembler for 8051 type processors. \layout Standard -\protected_separator - +\series bold +sdcpp +\series default + - The C preprocessor. \layout Standard -\protected_separator - 4. - Change Directory to Where SDCC was extracted (referred to as INSTALLDIR) - +\series bold +sdcpd +\series default + - The source debugger. \layout Standard -\protected_separator - +\series bold +s51 +\series default + - The ucSim 8051 simulator. \layout Standard -\protected_separator - ex. - cd /sdcc218Da. -\protected_separator - If you extracted to a drive OTHER THAN C, the drive +\series bold +linkz80, linkgbz80 +\series default + - The Z80 and GameBoy Z80 linkers. \layout Standard -\protected_separator - must be specified as part of the path. - For example, if you extracted to +\series bold +as-z80, as-gbz80 +\series default + - The Z80 and GameBoy Z80 assemblers. \layout Standard -\protected_separator - your "g drive", type the following: "cd //g/mydir". -\protected_separator - You must use "//" +\series bold +packihx +\series default + - A tool to pack Intel hex files. \layout Standard +As development for other processors proceeds, this list will expand to include + executables to support processors like AVR, PIC, etc. +\layout Subsubsection -\protected_separator - to specify the drive. - +cpp ( C-Preprocessor) \layout Standard +The preprocessor is extracted into the directory +\emph on +SDCCDIR/cpp +\emph default +, it is a modified version of the GNU preprocessor. + The C preprocessor is used to pull in #include sources, process #ifdef + statements, #defines and so on. +\layout Subsubsection -\protected_separator - +asxxxx & aslink ( The assembler and Linkage Editor) \layout Standard +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 +\emph on +SDCCDIR/asxxxx. +\layout Subsubsection -\protected_separator - 5. - Make Dirs Which are Automatically Made During the UNIX Installation +SDCC - The compiler \layout Standard +This is the actual compiler, it in turn uses the c-preprocessor and invokes + the assembler and linkage editors. + All files with the prefix +\emph on +SDCC +\emph default +are part of the compiler and are extracted into the the directory +\emph on +SDCCDIR. +\layout Subsubsection -\protected_separator - From the INSTALLDIR, +S51 - Simulator \layout Standard +s51 is a freeware, opensource simulator developed by Daniel Drotos . + The executable is built as part of the build process, for more information + visit Daniel's website at . +\layout Subsubsection -\protected_separator - +SDCDB - Source Level Debugger \layout Standard +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. +\layout Section -\protected_separator +Using SDCC +\layout Subsection -\protected_separator - mkdir -p bin -\protected_separator +Compiling +\layout Subsubsection -\protected_separator - (not a typo, just "bin") +Single Source File Projects \layout Standard - -\protected_separator - -\protected_separator - mkdir -p /bin +For single source file 8051 projects the process is very simple. + Compile your programs with the following command \layout Standard -\protected_separator - -\protected_separator - mkdir -p /usr/local/bin +\size footnotesize +sdcc sourcefile.c \layout Standard +The above command will compile ,assemble and link your source file. + Output files are as follows. +\layout Itemize -\protected_separator -\protected_separator - mkdir -p /usr/local/share -\layout Standard +\size footnotesize +sourcefile.asm - Assembler source file created by the compiler +\layout Itemize -\protected_separator - -\protected_separator - mkdir -p /usr/local/share/sdcc51lib -\layout Standard +\size footnotesize +sourcefile.lst - Assembler listing file created by the Assembler +\layout Itemize -\protected_separator +\size footnotesize +sourcefile.rst - Assembler listing file updated with linkedit information + , created by linkage editor +\layout Itemize -\protected_separator - mkdir -p /usr/local/share/sdcc51inc -\layout Standard +\size footnotesize +sourcefile.sym - symbol listing for the sourcefile, created by the assembler. +\layout Itemize -\protected_separator -\protected_separator - mkdir -p /tmp -\layout Standard +\size footnotesize +sourcefile.rel - Object file created by the assembler, input to Linkage editor. +\layout Itemize -\protected_separator +\size footnotesize +sourcefile.map - The memory map for the load module, created by the Linker. +\layout Itemize -\layout Standard +\size footnotesize +sourcefile. - The load module : ihx - Intel hex format (default + ), s19 - Motorola S19 format when compiler option --out-fmt-s19 is used. +\layout Subsubsection -\protected_separator - (When a path from the root directory is specified WITHOUT a drive, the - +Projects with Multiple Source Files \layout Standard - -\protected_separator - drive defaults to c. -\protected_separator - For example /michael/newuser => c: -\backslash -michael -\backslash -newuser) +SDCC can compile only ONE file at a time. + Let us for example assume that you have a project containing the following + files. \layout Standard -\protected_separator - +\size footnotesize +foo1.c ( contains some functions ) \layout Standard -\protected_separator - 6. -\protected_separator - Add Programs to /bin Expected by the Installation Process +\size footnotesize +foo2.c (contains some more functions) \layout Standard -\protected_separator - -\protected_separator - - Look at your path: echo $PATH +\size footnotesize +foomain.c (contains more functions and the function main) \layout Standard - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - One of the fields is the diretory with the CYGNUS programs. - +The first two files will need to be compiled separately with the commands \layout Standard -\protected_separator - -\protected_separator - -\protected_separator - ex. - /CYGNUS/CYGWIN~1/H-I586/BIN +\size footnotesize +sdcc -c foo1.c \layout Standard -\protected_separator - +\size footnotesize +sdcc -c foo2.c \layout Standard - -\protected_separator - -\protected_separator - - cd to the directory found above. -\protected_separator - You may have to fiddle with the +Then compile the source file containing main and link the other files together + with the following command. \layout Standard -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - case (upper or lower) here because the PATH is SHOWN as all upper +\size footnotesize +sdcc foomain.c foo1.rel foo2.rel \layout Standard - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - case, but is actually mixed. -\protected_separator - To help you along, you may type +Alternatively +\emph on +foomain.c +\emph default + can be separately compiled as well \layout Standard -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - a letter or 2 followed by the escape key. -\protected_separator - The shell will fill +\size footnotesize +sdcc -c foomain.c \layout Standard -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - out the remaining letters IF THEY describe a unique directory. - +\size footnotesize +sdcc foomain.rel foo1.rel foo2.rel \layout Standard +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. +\layout Subsubsection -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - If you have problems here, cd one directory and type "ls". -\protected_separator - "ls" +Projects with Additional Libraries \layout Standard - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - is the equivalent of "dir/w". - +Some reusable routines may be compiled into a library, see the documentation + for the assembler and linkage editor in the directory +\emph on +SDCCDIR/asxxxx/asxhtm.htm +\emph default +this describes how to create a +\emph on +.lib +\emph default + library file, the libraries created in this manner may be included using + the command line, make sure you include the -L option to + tell the linker where to look for these files. + Here is an example, assuming you have the source file +\emph on +'foomain.c +\emph default +' and a library +\emph on + 'foolib.lib' +\emph default + in the directory +\emph on +'mylib' +\emph default +. \layout Standard -\protected_separator - +\size footnotesize +sdcc foomain.c foolib.lib -L mylib \layout Standard - -\protected_separator - -\protected_separator - - Copy the following: +Note here that +\emph on +'mylib +\emph default +' must be an absolute path name. \layout Standard +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. +\layout Subsection -\protected_separator - -\protected_separator +Command Line Options +\layout Subsubsection -\protected_separator - cp sh.exe /bin -\layout Standard +Processor Selection Options +\layout List +\labelwidthstring 00.00.0000 -\protected_separator +\series bold +-mmcs51 +\series default + Generate code for the MCS51 (8051) family of processors. + This is the default processor target. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\protected_separator - cp pwd.exe /bin -\layout Standard +\series bold +-mds390 +\series default + Generate code for the DS80C390 processor. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator +\series bold +-mz80 +\series default + Generate code for the Z80 family of processors. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\protected_separator - cp echo.exe /bin -\layout Standard +\series bold +-mgbz80 +\series default + Generate code for the GameBoy Z80 processor. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator +\series bold +-mavr +\series default + Generate code for the Atmel AVR processor(In development, not complete). +\layout List +\labelwidthstring 00.00.0000 -\layout Standard +\series bold +-mpic14 +\series default + Generate code for the PIC 14-bit processors(In development, not complete). +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - 7. - Go back to the INSTALLDIR -\layout Standard +\series bold +-mtlcs900h +\series default + Generate code for the Toshiba TLCS-900H processor(In development, not complete). +\layout Subsubsection -\protected_separator +Path, Lib and Define Options +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - cd INSTALLDIR -\layout Standard +\series bold +\bar under +-I +\series default +\bar default + The additional location where the pre processor will look for <..h> or +\begin_inset Quotes eld +\end_inset -\protected_separator - ex. - cd //d/sdcc218Da -\layout Standard +..h +\begin_inset Quotes erd +\end_inset + files. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\layout Standard +\series bold +\size large +\bar under +-D +\series default +\size default +\bar default + Command line definition of macros. + Passed to the pre processor. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - 8. - Run the configure Program -\layout Standard +\series bold +\size large +\bar under +--lib-path(-L) +\size default + +\series default +\bar default + 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. +\layout Subsubsection +MCS51 Options +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\protected_separator - ./configure -\layout Standard +\series bold +\size large +--model-large +\series default +\size default + 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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - The "./" is important because your current directory is NOT in your path. +\series bold +\size large +\bar under +--model-small +\series default +\emph on +\bar default -\layout Standard +\size default +\emph default +Generate code for Small Model programs see section Memory Models for more + details. + This is the default model. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - Under DOS, your current directory was implicitly always the first entry +\series bold +\size large +\bar under +--model-flat24 +\series default +\emph on +\bar default -\layout Standard +\size default +\emph default +Generate code forDS80C390 24-bit flat mode. + See section Memory Models for more details. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - in your path. +\series bold +\size large +\bar under +--stack- +\emph on +auto +\series default +\bar default -\layout Standard - - -\protected_separator - -\layout Standard +\size default +\emph default +All functions in the source file will be compiled as +\emph on +reentrant +\emph default +, 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. + +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - 9. - Run make -\layout Standard +\series bold +\size large +\bar under +--xstack +\series default +\size default +\bar default + 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. +\layout Subsubsection +Optimization Options +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\protected_separator - make -\layout Standard +\series bold +\size large +\bar under +--nogcse +\series default +\size default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 + +\series bold +\size large +\bar under +--noinvariant +\series default +\size default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\layout Standard +\series bold +\size large +\bar under +--noinduction +\series default +\size default +\bar default + Will not do loop induction optimizations, see section Strength reduction + for more details.It recommended that this option NOT be used , #pragma NOINDUCTI +ON can be used to turn off induction optimizations for given function only. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - This process takes quite some time under Win 32. - -\layout Standard +\series bold +\size large +\bar under +--nojtbound +\series default +\size default +\bar default + Will not generate boundary condition check when switch statements are implement +ed 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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator +\series bold +\size large +\bar under +--noloopreverse +\series default +\bar default + +\size default +Will not do loop reversal optimization +\layout List +\labelwidthstring 00.00.0000 -\layout Standard +\series bold +\size large +\bar under +--noregparms +\series default +\size default +\bar default + 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/d +ivision) these library routines will need to be recompiled with the --noregparms + option as well. +\layout Subsubsection -\protected_separator - 10. - Install the Newly Built Software -\layout Standard +DS390 Options +\layout List +\labelwidthstring 00.00.0000 -\protected_separator +\series bold +--stack-auto +\series default + See MCS51 section for description. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - make install -\layout Standard +\series bold +--stack-10bit +\series default + This option generates code for the 10 bit stack mode of the Dallas DS80C390 + part. + In this mode, the stack is located in the lower 1K of the internal RAM, + which is mapped to 0x400000. + Note that the support is incomplete, since it still uses a single byte + as the stack pointer. + This means that only the lower 256 bytes of the potential 1K stack space + can actually be used. + However, this does allow you to reclaim the precious 256 bytes of low RAM + for use for the DATA and IDATA segments. + The compiler will not generate any code to put the processor into 10 bit + stack mode. + It is important to ensure that the processor is in this mode before calling + any re-entrant functions compiled with this option. + In principle, this should work with the --stack-auto option, but that has + not been tested. + It is incompatible with the --xstack option. + It also only makes sense if the processor is in 24 bit contiguous addressing + mode (see the --model-flat24 option). +\layout Subsubsection -\protected_separator +Other Options +\layout List +\labelwidthstring 00.00.0000 -\layout Standard +\series bold +\size large +\bar under +--callee-saves function1[,function2][,function3].... -\protected_separator - This will partially install the software into the /usr/local directories - -\layout Standard +\series default +\size default +\bar default + 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 CALLEE-SAVES. + . +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - created in step 5. -\protected_separator - What it actually doing is copying the .c, .h and -\layout Standard +\series bold +\bar under +--debug +\series default +\bar default +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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - library files to directories under /usr/local/share. +\series bold +\size large +\bar under +--regextend +\size default -\layout Standard +\series default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator +\series bold +\size large +\bar under +--compile-only +\series default +\bar default +(-c) +\size default + will compile and assemble the source only, will not call the linkage editor. +\layout List +\labelwidthstring 00.00.0000 -\layout Standard +\series bold +\size large +\bar under +--xram-loc +\series default +\size default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - It will NOT be able to install the actual programs (binaries) because -\layout Standard +\series bold +\size large +\bar under +--code-loc +\series default +\size default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - it does not know programs on Win32 systems have ".exe" extensions. - -\layout Standard +\series bold +\size large +\bar under +--stack-loc +\series default +\size default +\bar default + 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) +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - For example, it tries to install sdcc instead of sdcc.exe. - -\layout Standard +\series bold +\size large +\bar under +--stack-after-data +\series default +\size default +\bar default + This option will cause the stack to be located in the internal ram after + the data segment. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\layout Standard +\series bold +\size large +\bar under +--data-loc +\series default +\size default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - After the automated part is finished, you must manually copy the binaries: - -\layout Standard +\series bold +\size large +\bar under +--idata-loc +\series default +\size default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator +\series bold +\size large +\bar under +--peep-file +\series default +\size default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - cd bin -\protected_separator - (This is the bin directory in your INSTALLDIR) -\layout Standard - -\protected_separator - -\protected_separator - cp * /usr/local/bin -\layout Standard - - -\protected_separator - -\layout Standard - - -\protected_separator - 11. - Make sure /usr/local/bin is in Your PATH -\layout Standard - - -\protected_separator - You may add c: -\backslash -usr -\backslash -local -\backslash -bin to your path however your Win32 system allows. -\protected_separator - For -\layout Standard - - -\protected_separator - example you may add it to the PATH statement in autoexec.bat. - -\layout Standard - - -\protected_separator - -\layout Standard - - -\protected_separator - Good luck. -\protected_separator - If you have any questions send them to me or post them -\layout Standard - - -\protected_separator - to the list. -\layout Subsubsection - -FreeBSD and other non-GNU unixes -\layout Standard - -Note that the SDCC build environment uses Gnu make. - If this is not the default 'make' on your system, you may need to install - it. - On many systems, Gnu make is installed as 'gmake'. -\layout Section - -Compiling. -\begin_inset LatexCommand \label{Compiling} - -\end_inset - - -\layout Subsection - -Single Source file projects. -\begin_inset LatexCommand \label{One Source File} - -\end_inset - - -\layout Standard - -For single source file projects the process is very simple. - Compile your programs with the following command -\layout Standard - - -\size footnotesize -sdcc sourcefile.c -\layout Standard - -The above command will compile ,assemble and link your source file. - Output files are as follows. -\layout Itemize - - -\size footnotesize -sourcefile.asm - Assembler source file created by the compiler -\layout Itemize - - -\size footnotesize -sourcefile.lst - Assembler listing file created by the Assembler -\layout Itemize - - -\size footnotesize -sourcefile.rst - Assembler listing file updated with linkedit information - , created by linkage editor -\layout Itemize - - -\size footnotesize -sourcefile.sym - symbol listing for the sourcefile, created by the assembler. -\layout Itemize - - -\size footnotesize -sourcefile.rel - Object file created by the assembler, input to Linkage editor. -\layout Itemize - - -\size footnotesize -sourcefile.map - The memory map for the load module, created by the Linker. -\layout Itemize - - -\size footnotesize -sourcefile. - The load module : ihx - Intel hex format (default - ), s19 - Motorola S19 format when compiler option --out-fmt-s19 is used. -\layout Subsection - -Projects with multiple source files. -\layout Standard - -SDCC can compile only ONE file at a time. - Let us for example assume that you have a project containing the following - files. -\layout Standard - - -\size footnotesize -foo1.c ( contains some functions ) -\layout Standard - - -\size footnotesize -foo2.c (contains some more functions) -\layout Standard - - -\size footnotesize -foomain.c (contains more functions and the function main) -\layout Standard - -The first two files will need to be compiled separately with the commands -\layout Standard - - -\size footnotesize -sdcc -c foo1.c -\layout Standard - - -\size footnotesize -sdcc -c foo2.c -\layout Standard - -Then compile the source file containing main and link the other files together - with the following command. -\layout Standard - - -\size footnotesize -sdcc foomain.c foo1.rel foo2.rel -\layout Standard - -Alternatively -\emph on -foomain.c -\emph default - can be separately compiled as well -\layout Standard - - -\size footnotesize -sdcc -c foomain.c -\layout Standard - - -\size footnotesize -sdcc foomain.rel foo1.rel foo2.rel -\layout Standard - -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. -\layout Subsection - -Projects with additional libraries. -\layout Standard - -Some reusable routines may be compiled into a library, see the documentation - for the assembler and linkage editor in the directory -\emph on -SDCCDIR/asxxxx/asxhtm.htm -\emph default -this describes how to create a -\emph on -.lib -\emph default - library file, the libraries created in this manner may be included using - the command line, make sure you include the -L option to - tell the linker where to look for these files. - Here is an example, assuming you have the source file -\emph on -'foomain.c -\emph default -' and a library -\emph on - 'foolib.lib' -\emph default - in the directory -\emph on -'mylib' -\emph default -. -\layout Standard - - -\size footnotesize -sdcc foomain.c foolib.lib -L mylib -\layout Standard - -Note here that -\emph on -'mylib -\emph default -' must be an absolute path name. -\layout Standard - -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. -\layout Section - -Command Line options -\begin_inset LatexCommand \label{Command Line Options} - -\end_inset - - -\layout Itemize - --mmcs51 -\begin_inset LatexCommand \label{-mmcs51} - -\end_inset - -Generate code for the MCS51 (8051) family of processors. - This is the default processor target. -\layout Itemize - --mz80 -\begin_inset LatexCommand \label{-mz80} - -\end_inset - -Generate code for the Z80 family of processors. - Various other options may not be applicable in this mode. - -\layout Itemize - - -\series bold --mds390 -\series default - -\begin_inset LatexCommand \label{-mds390} - -\end_inset - -Generate code for the DS80C390 processor. - Various other options may not be applicable in this mode. -\layout Itemize - - -\series bold -\size large ---model-large -\emph on - -\begin_inset LatexCommand \label{--model-large} - -\end_inset - - -\series default -\size default -\emph default - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---model-small -\series default -\emph on -\bar default - -\size default -\emph default - -\begin_inset LatexCommand \label{--model-small} - -\end_inset - -Generate code for Small Model programs see section Memory Models for more - details. - This is the default model. -\layout Itemize - - -\series bold -\size large -\bar under ---model-flat24 -\series default -\emph on -\bar default - -\size default -\emph default - -\begin_inset LatexCommand \ref[--model-flat24]{--model-flat24} - -\end_inset - -Generate code forDS80C390 24-bit flat mode. - See section Memory Models for more details. -\layout Itemize - - -\series bold -\size large -\bar under ---stack- -\emph on -auto -\series default -\bar default - -\size default -\emph default - -\begin_inset LatexCommand \label{--stack-auto} - -\end_inset - -All functions in the source file will be compiled as -\emph on -reentrant -\emph default -, 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. - -\layout Itemize - - -\series bold -\size large -\bar under ---xstack -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--xstack} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---nogcse -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--nogcse} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---noinvariant -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--noinvariant} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---noinduction -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--noinduction} - -\end_inset - - Will not do loop induction optimizations, see section Strength reduction - for more details.It recommended that this option NOT be used , #pragma NOINDUCTI -ON can be used to turn off induction optimizations for given function only. -\layout Itemize - - -\series bold -\size large -\bar under ---nojtbound -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--nojtbound} - -\end_inset - - Will not generate boundary condition check when switch statements are implement -ed 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. -\layout Itemize - - -\series bold -\size large -\bar under ---noloopreverse -\series default -\bar default - -\size default - -\begin_inset LatexCommand \label{--noloopreverse} - -\end_inset - -Will not do loop reversal optimization -\layout Itemize - - -\series bold -\size large -\bar under ---noregparms -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--noregparms} - -\end_inset - - 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/d -ivision) these library routines will need to be recompiled with the --noregparms - option as well. -\layout Itemize - - -\series bold -\size large -\bar under ---callee-saves function1[,function2][,function3].... - -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--callee-saves} - -\end_inset - -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 -\begin_inset LatexCommand \ref{Pragmaa} - -\end_inset - - CALLEE-SAVES. -\begin_inset LatexCommand \ref{pragma callee-saves} - -\end_inset - - . -\layout Itemize - - -\series bold -\bar under ---debug -\series default -\bar default - -\begin_inset LatexCommand \label{--debug} - -\end_inset - -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. -\layout Itemize - - -\series bold -\size large -\bar under ---regextend -\size default - -\series default -\bar default - -\begin_inset LatexCommand \label{--regextend} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---compile-only -\series default -\bar default -(-c) -\size default - -\begin_inset LatexCommand \label{--compile-only} - -\end_inset - - will compile and assemble the source only, will not call the linkage editor. -\layout Itemize - - -\series bold -\size large -\bar under ---xram-loc -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--xram-loc} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---code-loc -\size default - -\series default -\bar default - -\begin_inset LatexCommand \label{--code-loc} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---stack-loc -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--stack-loc} - -\end_inset - - 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) -\layout Itemize - - -\series bold -\size large -\bar under ---stack-after-data -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--stack-after-data} - -\end_inset - -This option will cause the stack to be located in the internal ram after - the data segment. -\layout Itemize - - -\series bold -\size large -\bar under ---data-loc -\series default -\bar default - -\size default - -\begin_inset LatexCommand \label{--data-loc} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---idata-loc -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--idata-loc} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---peep-file -\size default - -\begin_inset LatexCommand \label{--peep-file} - -\end_inset - - -\series default -\bar default - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---lib-path (-L) -\size default - -\series default -\bar default - -\begin_inset LatexCommand \label{--lib-path} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\bar under --I -\begin_inset LatexCommand \label{-I} - -\end_inset - - -\series default -\bar default - The additional location where the pre processor will look for <..h> or -\begin_inset Quotes eld -\end_inset - -..h -\begin_inset Quotes erd -\end_inset - - files. -\layout Itemize - - -\series bold -\size large -\bar under --D -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-D} - -\end_inset - -Command line definition of macros. - Passed to the pre processor. -\layout Itemize - - -\series bold -\size large -\bar under --E -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-E} - -\end_inset - - Run only the C preprocessor. - Preprocess all the C source files specified and output the results to standard - output. -\layout Itemize - - -\series bold -\size large -\bar under --M -\bar default - -\begin_inset LatexCommand \label{-M} - -\end_inset - - -\series default -\size default - 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 ` -\backslash -'-newline if it is long. - The list of rules is printed on standard output instead of the preprocessed - C program. - `-M' implies `-E'. -\layout Itemize - - -\series bold -\size large -\bar under --C -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-C} - -\end_inset - -Tell the preprocessor not to discard comments. - Used with the `-E' option. -\layout Itemize - - -\series bold -\size large -\bar under --MM -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-MM} - -\end_inset - -Like `-M' but the output mentions only the user header files included with - `#include file"'. - System header files included with `#include ' are omitted. -\layout Itemize - - -\series bold -\size large -\bar under --Aquestion(answer) -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-Aquestion(answer)} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under --Aquestion -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-Aquestion} - -\end_inset - - (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. -\layout Itemize - - -\series bold -\size large -\bar under --Umacro -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-Umacro} - -\end_inset - - Undefine macro macro. - `-U' options are evaluated after all `-D' options, but before any `-include' - and `-imac- ros' options. -\layout Itemize - - -\series bold -\size large -\bar under --dM -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-dM} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under --dD -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-dD} - -\end_inset - -Tell the preprocessor to pass all macro definitions into the output, in - their proper sequence in the rest of the output. -\layout Itemize - - -\series bold -\size large -\bar under --dN -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-dN} - -\end_inset - -Like `-dD' except that the macro arguments and contents are omitted. - Only `#define name' is included in the output. -\layout Itemize - - -\series bold -\size large -\bar under --S -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{-S} - -\end_inset - -Stop after the stage of compilation proper; do not as- semble. - The output is an assembler code file for the input file specified. -\layout Itemize - - -\series bold -\bar under --Wa asmOption[,asmOption] -\series default -\bar default -... - Pass the asmOption to the assembler -\layout Itemize - - -\series bold -\bar under --Wl linkOption[,linkOption] -\series default -\bar default - .. - Pass the linkOption to the linker. -\layout Itemize - - -\series bold -\size large -\bar under ---int-long-reent -\series default -\bar default - -\size default - -\begin_inset LatexCommand \label{--int-long-rent} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---cyclomatic -\size default - -\series default -\bar default - -\begin_inset LatexCommand \label{--cyclomatic} - -\end_inset - -This option will cause the compiler to generate an information message for - each function in the source file. - The message contains some -\emph on -important -\emph default - 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 -\emph on -cyclomatic complexity -\emph default - see section on Cyclomatic Complexity for more details. -\layout Itemize - - -\series bold -\size large -\bar under ---float-reent -\size default - -\series default -\bar default - -\begin_inset LatexCommand \label{--float-reent} - -\end_inset - - Floating point library is compiled as reentrant.See section Installation - for more details. -\layout Itemize - - -\series bold -\size large -\bar under ---out-fmt-ihx -\size default - -\begin_inset LatexCommand \label{--out-fmt-ihx} - -\end_inset - - -\series default -\bar default -The linker output (final object code) is in Intel Hex format. - (This is the default option). -\layout Itemize - - -\series bold -\size large -\bar under ---out-fmt-s19 -\size default - -\series default -\bar default - -\begin_inset LatexCommand \label{--out-fmt-s19} - -\end_inset - -The linker output (final object code) is in Motorola S19 format. -\layout Itemize - - -\series bold -\size large -\bar under ---nooverlay -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--nooverlay} - -\end_inset - - The compiler will not overlay parameters and local variables of any function, - see section Parameters and local variables for more details. -\layout Itemize - - -\series bold -\size large -\bar under ---main-return -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--main-return} - -\end_inset - - 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 .' . -\layout Itemize - - -\series bold -\size large -\bar under ---no-peep -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--no-peep} - -\end_inset - - Disable peep-hole optimization. -\layout Itemize - - -\series bold -\size large -\bar under ---peep-asm -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--peep-asm} - -\end_inset - - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---iram-size -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--iram-size} - -\end_inset - - Causes the linker to check if the interal ram usage is within limits - of the given value. -\layout Standard - -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. - -\layout Itemize - - -\series bold -\size large -\bar under ---dumpraw -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--dumpraw} - -\end_inset - -. - This option will cause the compiler to dump the intermediate code into - a file of named -\emph on -.dumpraw -\emph default - 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. -\layout Itemize - - -\series bold -\size large -\bar under ---dumpgcse -\series default -\bar default -. -\size default - -\begin_inset LatexCommand \label{--dumpgcse} - -\end_inset - - Will create a dump if iCode, after global subexpression elimination, into - a file named -\emph on -.dumpgcse. -\layout Itemize - - -\series bold -\size large -\bar under ---dumpdeadcode -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--dumpdeadcode} - -\end_inset - -.Will create a dump if iCode, after deadcode elimination, into a file named - -\emph on -.dumpdeadcode. -\layout Itemize - - -\series bold -\size large -\bar under ---dumploop. - -\series default -\bar default - -\size default - -\begin_inset LatexCommand \label{--dumploop} - -\end_inset - -Will create a dump if iCode, after loop optimizations, into a file named - -\emph on -.dumploop. -\layout Itemize - - -\series bold -\size large -\bar under ---dumprange. - -\series default -\bar default - -\size default - -\begin_inset LatexCommand \label{--dump-range} - -\end_inset - -Will create a dump if iCode, after live range analysis, into a file named - -\emph on -.dumprange. -\layout Itemize - - -\series bold -\size large -\bar under ---dumpregassign. - -\size default - -\series default -\bar default - -\begin_inset LatexCommand \label{--dumpregassign} - -\end_inset - -Will create a dump if iCode, after register assignment , into a file named - -\emph on -.dumprassgn. -\layout Itemize - - -\series bold -\size large -\bar under ---dumpall. - -\series default -\size default -\bar default - -\begin_inset LatexCommand \label{--dumpall} - -\end_inset - -Will cause all the above mentioned dumps to be created. -\layout Standard - -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. - -\layout Standard - -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. -\layout Section - -Language Extensions -\begin_inset LatexCommand \label{Language Extension} - -\end_inset - - -\layout Subsection - -Storage Classes. -\begin_inset LatexCommand \label{Storage Classes} - -\end_inset - - -\layout Standard - -In addition to the ANSI storage classes SDCC allows the following 8051 specific - storage classes. -\layout Subsubsection - -xdata. -\begin_inset LatexCommand \label{xdata} - -\end_inset - - -\layout Standard - -Variables declared with this storage class will be placed in the extern - RAM. - This is the -\series bold -default -\series default - storage class for Large Memory model . -\layout Standard - - -\size footnotesize -eg. - -\emph on -xdata unsigned char xduc; -\layout Subsubsection - -data -\begin_inset LatexCommand \label{data} - -\end_inset - - -\layout Standard - -This is the -\series bold -default -\series default - storage class for Small Memory model. - Variables declared with this storage class will be allocated in the internal - RAM. -\layout Standard - - -\size footnotesize -eg. - -\emph on - data int iramdata; -\layout Subsubsection - -idata -\begin_inset LatexCommand \label{idata} - -\end_inset - - -\layout Standard - -Variables declared with this storage class will be allocated into the indirectly - addressable portion of the internal ram of a 8051 . -\layout Standard - - -\size footnotesize -eg. -\emph on -idata int idi; -\layout Subsubsection - -bit -\begin_inset LatexCommand \label{bit} - -\end_inset - - -\layout Standard - -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. -\layout Standard - -eg. -\emph on -bit iFlag; -\layout Subsubsection - -sfr / sbit -\begin_inset LatexCommand \label{sfr / sbit} - -\end_inset - - -\layout Standard - -Like the bit keyword, -\emph on -sfr / sbit -\emph default -signifies both a data-type and storage class, they are used to describe - the special function registers and special bit variables of a 8051. - -\layout Standard - -eg. - -\emph on - -\layout Standard - - -\emph on -sfr at 0x80 P0; -\emph default -\noun on -/* special function register P0 at location 0x80 */ -\layout Standard - - -\emph on -sbit at 0xd7 CY; /* -\noun on -CY (Carry Flag) */ -\layout Section - -Optimizations -\begin_inset LatexCommand \label{Optimizations} - -\end_inset - - -\layout Standard - -SDCC performs a a host of standard optimizations in addition to some MCU - specific optimizations. - -\layout Subsection - -Sub-expression elimination -\begin_inset LatexCommand \label{Sub-expression Elimination} - -\end_inset - - -\layout Standard - -The compiler does -\emph on -local and global -\emph default -common subexpression elimination. -\layout Standard - - -\family typewriter -\size scriptsize -eg. - -\layout Standard - - -\size small -i = x + y + 1; -\size default - -\newline -j -\size small -= x + y; -\layout Standard - -will be translated to -\layout Standard - - -\size small -iTemp = x + y -\newline -i = iTemp + 1 -\newline -j = iTemp -\layout Standard - -Some subexpressions are not as obvious as the above example. -\layout Standard - -eg. -\layout Standard - - -\size small -a->b[i].c = 10; -\newline -a->b[i].d = 11; -\layout Standard - -In this case the address arithmetic -\emph on -a->b[i] -\emph default -will be computed only once; the equivalent code in C would be. -\layout Standard - - -\size small -iTemp = a->b[i]; -\newline -iTemp.c = 10; -\newline -iTemp.d = 11; -\layout Standard - -The compiler will try to keep these temporary variables in registers. -\layout Subsection - -Dead-Code elimination. -\begin_inset LatexCommand \label{Dead-code elimination} - -\end_inset - - -\layout Standard - -eg. -\layout Standard - - -\size small -int global; -\newline -void f () { -\newline - -\protected_separator - -\protected_separator -int i; -\newline - -\protected_separator - -\protected_separator -i = 1; -\protected_separator - -\protected_separator - -\protected_separator -/* dead store */ -\newline - -\protected_separator - -\protected_separator -global = 1; /* dead store */ -\newline - -\protected_separator - -\protected_separator -global = 2; -\newline - -\protected_separator - -\protected_separator -return; -\newline - -\protected_separator - -\protected_separator -global = 3; /* unreachable */ -\newline -} -\layout Standard - -will be changed to -\layout Standard - - -\size footnotesize -int global; void f () -\newline -{ -\protected_separator - -\protected_separator - -\newline - -\protected_separator -global = 2; -\protected_separator - -\protected_separator - -\newline - -\protected_separator -return; -\newline -} -\layout Subsection - -Copy-Propagation: -\begin_inset LatexCommand \label{Copy-Propagation} - -\end_inset - - -\layout Standard - -eg. -\layout Standard - - -\size footnotesize -int f() { -\newline - -\protected_separator - -\protected_separator - -\protected_separator -int i, j; -\newline - -\protected_separator - -\protected_separator - -\protected_separator -i = 10; -\newline - -\protected_separator - -\protected_separator - -\protected_separator -j = i; -\newline - -\protected_separator - -\protected_separator - -\protected_separator -return j; -\newline -} -\layout Standard - -will be changed to -\layout Standard - - -\size small -int f() { -\newline - -\protected_separator - -\protected_separator - int i,j; -\newline - -\protected_separator - -\protected_separator - i = 10; -\newline - -\protected_separator - -\protected_separator - j = 10; -\newline - -\protected_separator - -\protected_separator - return 10; -\newline -} -\layout Standard - -Note: the dead stores created by this copy propagation will be eliminated - by dead-code elimination . -\layout Subsection - -Loop optimizations -\begin_inset LatexCommand \label{Loop Optimizations} - -\end_inset - - -\layout Standard - -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 optimizat -ion 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). -\layout Subsubsection - -Loop Invariant: -\begin_inset LatexCommand \label{Loop Invariant} - -\end_inset - - -\layout Standard - -eg -\layout Standard - - -\size small -for (i = 0 ; i < 100 ; i ++) -\newline - -\protected_separator - -\protected_separator - -\protected_separator -f += k + l; -\layout Standard - -changed to -\layout Standard - - -\size small -itemp = k + l; -\newline -for ( i = 0; i < 100; i++ ) f += itemp; -\layout Standard - -As mentioned previously some loop invariants are not as apparent, all static - address computations are also moved out of the loop. -\layout Subsubsection - -Strength reduction : -\begin_inset LatexCommand \label{Strength Reduction} - -\end_inset - - -\layout Standard - -This optimization substitutes an expression by a cheaper expression. -\layout Standard - -eg. -\layout Standard - - -\size small -for (i=0;i < 100; i++) ar[i*5] = i*3; -\layout Standard - -changed to -\layout Standard - - -\size small -itemp1 = 0; -\newline -itemp2 = 0; -\newline -for (i=0;i< 100;i++) { -\newline - -\protected_separator - -\protected_separator - -\protected_separator -ar[itemp1] = itemp2; -\newline - -\protected_separator - -\protected_separator - -\protected_separator -itemp1 += 5; -\newline - -\protected_separator - -\protected_separator - -\protected_separator -itemp2 += 3; -\newline -} -\layout Standard - -The more expensive multiplication is changed to a less expensive addition. -\layout Subsubsection - -Loop reversing: -\begin_inset LatexCommand \label{Loop reversing} - -\end_inset - - -\layout Standard - -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 -\begin_inset Quotes eld -\end_inset - -decrement and jump if not zero -\begin_inset Quotes erd -\end_inset - - 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). -\layout Itemize - -The 'for' loop is of the form -\newline - -\begin_inset Quotes eld -\end_inset - -for ( = ; [< | <=] ; [++ | - += 1]) -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\begin_inset Quotes erd -\end_inset - - -\layout Itemize - -The does not contain -\begin_inset Quotes eld -\end_inset - -continue -\begin_inset Quotes erd -\end_inset - - or 'break -\begin_inset Quotes erd -\end_inset - -. -\layout Itemize - -All goto's are contained within the loop. -\layout Itemize - -No function calls within the loop. -\layout Itemize - -The loop control variable is not assigned any value within the loop -\layout Itemize - -The loop control variable does NOT participate in any arithmetic operation - within the loop. -\layout Itemize - -There are NO switch statements in the loop. -\layout Standard - -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. -\layout Subsection - -Algebraic simplifications: -\begin_inset LatexCommand \label{Algebraic Simplifications} - -\end_inset - - -\layout Standard - -SDCC does numerous algebraic simplifications, the following is a small sub-set - of these optimizations. -\layout Standard - - -\size small -eg -\emph on - -\emph default - -\newline -i = j + 0 ; /* changed to */ i = j; -\newline -i /= 2; /* changed to */ i >>= 1; -\newline -i = j - j ; /* changed to */ i = 0; -\newline -i = j / 1 ; /* changed to */ i = j; -\layout Standard - -Note the subexpressions given above are generally introduced by macro expansions - or as a result of copy/constant propagation. -\layout Subsection - -'switch' statements. -\begin_inset LatexCommand \label{Switch Statement} - -\end_inset - - -\layout Standard - -SDCC changes switch statements to jump tables when the following conditions - are true. - -\layout Itemize - -The case labels are in numerical sequence , the labels need not be in order, - and the starting number need not be one or zero. -\layout Standard - -eg -\layout Standard - - -\size small -switch(i) { -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -switch (i) { -\newline -case 4:... - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -case 1: ... - -\newline -case 5:... - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -case 2: ... - -\newline -case 3:... - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -case 3: ... - -\newline -case 6:... - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -case 4: ... - -\newline -} -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -} -\layout Standard - -Both the above switch statements will be implemented using a jump-table. -\layout Itemize - -The number of case labels is at least three, since it takes two conditional - statements to handle the boundary conditions. -\layout Itemize - -The number of case labels is less than 84, since each label takes 3 bytes - and a jump-table can be utmost 256 bytes long. - -\layout Standard - -Switch statements which have gaps in the numeric sequence or those that - have more that 84 case labels can be split into more than one switch statement - for efficient code generation. -\layout Standard - -eg -\layout Standard - - -\size small -switch (i) { -\newline -case 1: ... - -\newline -case 2: ... - -\newline -case 3: ... - -\newline -case 4: ... - -\newline -case 9: ... - -\newline -case 10: ... - -\newline -case 11: ... - -\newline -case 12: ... - -\newline -} -\layout Standard - -If the above switch statement is broken down into two switch statements -\layout Standard - - -\size small -switch (i) { -\newline -case 1: ... - -\newline -case 2: ... - -\newline -case 3: ... - -\newline -case 4: ... - -\newline -} -\layout Standard - - -\size small -switch (i) { -\newline -case 9: ... - -\newline -case 10: ... - -\newline -case 11: ... - -\newline -case 12:... - -\newline -} -\layout Standard - -then both the switch statements will be implemented using jump-tables whereas - the unmodified switch statement will not be . -\layout Subsection - -bit-shifting operations. -\begin_inset LatexCommand \label{bit shifting} - -\end_inset - - -\layout Standard - -Bit shifting is one of the most frequently used operation in embedded programmin -g . - SDCC tries to implement bit-shift operations in the most efficient way - possible. -\layout Standard - -eg. -\layout Standard - - -\size small -unsigned short i; -\layout Standard - - -\size small -... - -\newline -i>>= 4; -\newline -.. -\layout Standard - -generates the following code. -\layout Standard - - -\size small -mov a,_i -\newline -swap a -\newline -anl a,#0x0f -\newline -mov _i,a -\layout Standard - -In general SDCC will never setup a loop if the shift count is known. - Another example -\layout Standard - - -\size small -unsigned int i; -\newline -... - -\newline -i >>= 9; -\newline -... -\layout Standard - -will generate -\layout Standard - - -\size small -mov a,(_i + 1) -\newline -mov (_i + 1),#0x00 -\newline -clr c -\newline -rrc a -\newline -mov _i,a -\layout Standard - -Note that SDCC stores numbers in -\noun on -little-endian -\noun default -format (i.e. - lowest order first) -\layout Subsubsection - -Bit-rotation: -\begin_inset LatexCommand \label{bit rotation} - -\end_inset - - -\layout Standard - -A special case of the bit-shift operation is bit rotation, SDCC recognizes - the following expression to be a left bit-rotation. -\layout Standard - - -\size small -unsigned char i; -\newline -... - -\newline -i = ( ( i << 1) | ( i >> 7)); -\newline -... -\layout Standard - -will generate the following code. -\layout Standard - - -\size small -mov a,_i -\newline -rl a -\newline -mov _i,a -\layout Standard - -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 -\emph on - i = ((i >> 7) | (i << 1)); -\emph default -/* left-bit rotation */ -\layout Subsection - -Highest Order Bit. -\begin_inset LatexCommand \label{Highest Order Bit} - -\end_inset - - -\layout Standard - -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. -\layout Standard - - -\size small -eg -\newline -unsigned int gint; -\newline -foo () { -\newline -unsigned char hob; -\newline - -\protected_separator - -\protected_separator - -\protected_separator -... - -\newline - -\protected_separator - -\protected_separator - -\protected_separator -hob = (gint >> 15) & 1; -\newline - -\protected_separator - -\protected_separator - -\protected_separator -.. - -\newline -} -\layout Standard - -Will generate the following code. -\layout Standard - - -\size small - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - 61 ; -\protected_separator - hob.c 7 -\newline - -\protected_separator - -\protected_separator - 000A E5*01 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - 62 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - a,(_gint + 1) -\newline - -\protected_separator - -\protected_separator - 000C 33 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - 63 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - rlc -\protected_separator - a -\newline - -\protected_separator - -\protected_separator - 000D E4 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - 64 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - clr -\protected_separator - a -\newline - -\protected_separator - -\protected_separator - 000E 13 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - 65 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - rrc -\protected_separator - a -\newline - -\protected_separator - -\protected_separator - 000F F5*02 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - 66 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - _foo_hob_1_1,a -\layout Standard - -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. -\layout Standard - - -\size small -eg. -\layout Standard - - -\size small -xyz = gint + ((gint >> 15) & 1); -\layout Standard - -will still be recognized. -\layout Subsection - -Peep-hole optimizer. -\begin_inset LatexCommand \label{Peep-Hole} - -\end_inset - - -\layout Standard - -The compiler uses a rule based , pattern matching and re-writing mechanism - for peep-hole optimization . - It is inspired by ' -\emph on -copt' -\emph default - 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 option. - The rule language is best illustrated with examples. -\layout Standard - - -\size small -replace { -\newline -mov %1,a -\newline -mov a,%1 } by { mov %1,a } -\layout Standard - -The above rule will the following assembly sequence -\layout Standard - - -\size small -mov r1,a -\newline -mov a,r1 -\layout Standard - -to -\layout Standard - - -\size small -mov r1,a -\layout Standard - -Note: All occurrences of a '%n' ( pattern variable ) must denote the same - string. - With the above rule, the assembly sequence -\layout Standard - - -\size small -mov r1,a -\newline -mov a,r2 -\layout Standard - -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'. -\layout Standard - - -\size small -replace { lcall %1 } by { acall %1 } -\newline -replace { ljmp %1 } by { ajmp %1 } -\layout Standard - -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-structur -e is MCU independent. - Peephole optimization rules for other MCU can be easily programmed using - the rule language. -\layout Standard - -The syntax for a rule is as follows , -\layout Standard - - -\size small -rule := replace [ restart ] '{' ' -\backslash -n' -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - '}' by '{' ' -\backslash -n' -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - ' -\backslash -n' -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - '}' [if ] ' -\backslash -n' -\newline - := assembly instruction (each instruction including - labels must be on a separate line). -\protected_separator - -\protected_separator - -\layout Standard - -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 ' -\emph on -restart -\emph default -' 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. -\layout Standard - - -\size small -replace restart { -\newline -pop %1 -\newline -push %1 } by { -\newline -; nop -\newline -} -\layout Standard - -Note that the replace pattern cannot be a blank, but can be a comment line. - Without the ' -\emph on -restart -\emph default -' option only the inner most 'pop' 'push' pair would be eliminated. - i.e. -\layout Standard - - -\size small -pop ar1 -\newline -pop ar2 -\newline -push ar2 -\newline -push ar1 -\layout Standard - -would result in -\layout Standard - - -\size small -pop ar1 -\newline -; nop -\newline -push ar1 -\layout Standard - -with the ' -\emph on -restart -\emph default -' option the rule will be applied again to the resulting code and the all - the ' -\emph on -pop' 'push' -\emph default - pairs will be eliminated to yield -\layout Standard - - -\size small -; nop -\newline -; nop -\layout Standard - -A conditional function can be attached to a rule. - Attaching rules are somewhat more involved, let me illustrate this with - an example. -\layout Standard - - -\size small -replace { -\newline - -\protected_separator - -\protected_separator - -\protected_separator -ljmp %5 -\newline -%2:} by { -\newline - -\protected_separator - -\protected_separator - -\protected_separator -sjmp %5 -\newline -%2:} if labelInRange -\layout Standard - -The optimizer does a look-up of a function name table defined in function - ' -\emph on -callFuncByName' -\emph default - in the source file -\emph on -SDCCpeeph.c -\emph default - , with the name -\emph on -'labelInRange -\emph default -', 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 -\emph on -'%5 -\emph default -' is crucial, since the function -\emph on -labelInRange -\emph default - expects to find the label in that particular variable (the hash table containin -g the variable bindings is passed as a parameter). - If you want to code more such functions , take a close look at the function - -\emph on -labelInRange -\emph default - and the calling mechanism in source file -\emph on -SDCCpeeph.c -\emph default -. - 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 -\emph on ---peep-file -\emph default - option. -\layout Section - -Pointers -\begin_inset LatexCommand \label{Pointers} - -\end_inset - - -\layout Standard - -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 -\emph on -_generic -\emph default - class of pointers which can be used to point to any of the memory spaces. - -\layout Standard - -Pointer declaration examples. -\layout Standard - - -\size small -/* pointer physically in xternal ram pointing to object in internal ram - */ -\newline -data unsigned char * xdata p; -\newline - -\layout Standard - - -\size small -/* pointer physically in code rom pointing to data in xdata space */ -\newline -xdata unsigned char * code p; -\newline - -\layout Standard - - -\size small -/* pointer physically in code space pointing to data in code space */ -\newline -code unsigned char * code p; -\newline - -\newline -/* the folowing is a generic pointer physically located in xdata space */ -\newline -char * xdata p; -\layout Standard - -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. -\layout Standard - - -\size small -unsigned char _xdata *ucxdp; /* pointer to data in external ram */ -\newline -unsigned char _data -\protected_separator -*ucdp ; /* pointer to data in internal ram */ -\newline -unsigned char _code -\protected_separator -*uccp ; /* pointer to data in R/O code space */ -\newline -unsigned char _idata *uccp; -\protected_separator -/* pointer to upper 128 bytes of ram */ -\layout Standard - -All unqualified pointers are treated as 3 - byte '_generic' pointers. - These type of pointers can also to be explicitly declared. -\layout Standard - - -\size small -unsigned char _generic *ucgp; -\layout Standard - -The highest order byte of the generic pointers contains the data space informati -on. - 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. -\layout Section - -Parameters & Local Variables -\begin_inset LatexCommand \label{Auto Variables} - -\end_inset - - -\layout Standard - -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 -\emph on - --stack-auto -\emph default - compiler option or by using the 'reentrant' keyword in the function declaration. -\layout Standard - - -\family typewriter -\size scriptsize -eg -\layout Standard - - -\size small -unsigned short foo( short i) reentrant { -\newline -... - -\newline -} -\layout Standard - -Note that when the parameters & local variables are declared in the internal/ext -ernal ram the functions are non-reentrant. - Since stack space on 8051 is limited the -\emph on -'reentrant' -\emph default -keyword or the -\emph on - --stack-auto -\emph default - 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. -\layout Standard - -When compiled with the default option (i.e. - non-reentrant ), local variables can be assigned storage classes and absolute - addresses. - -\layout Standard - - -\family typewriter -\size scriptsize -eg -\layout Standard - - -\size small -unsigned short foo() { -\newline - -\protected_separator - -\protected_separator -xdata unsigned short i; -\newline - -\protected_separator - -\protected_separator -bit bvar; -\newline - -\protected_separator - -\protected_separator -data at 0x31 unsiged short j; -\newline -... - -\newline -} -\layout Standard - -In the above example the variable -\emph on -i -\emph default - will be allocated in the external ram, -\emph on -bvar -\emph default - in bit addressable space and -\emph on - j -\emph default - in internal ram. - When compiled with the -\emph on ---stack-auto -\emph default - or when a function is declared as -\emph on -'reentrant' -\emph default - local variables cannot be assigned storage classes or absolute addresses. -\layout Standard - -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. -\layout Subsection - -Overlaying -\begin_inset LatexCommand \label{Overlaying} - -\end_inset - - -\layout Standard - -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 overlayabl -e segment if the function has -\emph on -no other function calls and the function is non-reentrant and the memory - model is small. - -\emph default - If an explicit storage class is specified for a local variable , it will - NOT be overplayed. -\layout Standard - -Note that the compiler (not the linkage editor) makes the decision for overlayin -g 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. -\layout Standard - -Parameters and Local variables of functions that contain 16 or 32 bit multiplica -tion or division will NOT be overlayed since these are implemented using - external functions. -\layout Standard - -eg. -\layout Standard - - -\size small -#pragma SAVE -\newline -#pragma NOOVERLAY -\newline -void set_error( unsigned short errcd) -\newline -{ -\newline - -\protected_separator - -\protected_separator - P3 = errcd; -\newline -} -\newline -#pragma RESTORE -\newline -void some_isr () interrupt 2 using 1 -\newline -{ -\newline - -\protected_separator - -\protected_separator - ... - -\newline - -\protected_separator - -\protected_separator - set_error(10); -\newline - -\protected_separator - -\protected_separator - ... - -\newline -} -\layout Standard - -In the above example the parameter -\emph on -errcd -\emph default - for the function -\emph on -set_error -\emph default - 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. -\layout Section - -critical Functions. -\begin_inset LatexCommand \label{Critical} - -\end_inset - - -\layout Standard - -A special keyword may be associated with a function declaring it as ' -\emph on -critical -\emph default -'. - 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. -\layout Standard - -eg -\layout Standard - - -\size small -int foo () critical -\newline -{ -\newline -... - -\newline -... - -\newline -} -\layout Standard - -The critical attribute maybe used with other attributes like -\emph on -reentrant. -\layout Section - -Absolute addressing. -\begin_inset LatexCommand \label{Absolute Addressing} - -\end_inset - - -\layout Standard - -Data items can be assigned an absolute address with the -\emph on -at
        -\emph default - keyword, in addition to a storage class. -\layout Standard - -eg. - -\layout Standard - - -\size small -xdata at 0x8000 unsigned char PORTA_8255 ; -\layout Standard - -In the above example the -\emph on -PORTA_8255 -\emph default - will be allocated to the location 0x8000 of the external ram. - -\layout Standard - -Note that is this feature is provided to give the programmer access to -\emph on -memory mapped -\emph default - 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 (.rst) and (.m -ap) are a good places to look for such overlaps. -\layout Standard - -Absolute address can be specified for variables in all storage classes. -\layout Standard - - -\size small -eg. -\layout Standard - - -\size small -bit at 0x02 bvar; -\layout Standard - -The above example will allocate the variable at offset 0x02 in the bit-addressab -le 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. -\layout Section - -Interrupt Service Routines -\begin_inset LatexCommand \label{Interrupt Service Rouines} - -\end_inset - - -\layout Standard - -SDCC allows interrupt service routines to be coded in C, with some extended - keywords. -\layout Standard - - -\size small -void timer_isr (void) interrupt 2 using 1 -\newline -{ -\newline -.. - -\newline -} -\layout Standard - -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, multiplic -ation & 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. -\layout Standard - -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 -\emph on -'main' -\emph default -. -\layout Standard - -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. -\layout Standard - -Interrupt # -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -Description -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -Vector Address -\newline - -\protected_separator - -\protected_separator - -\protected_separator -0 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -External 0 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -0x0003 -\newline - -\protected_separator - -\protected_separator - -\protected_separator -1 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -Timer 0 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -0x000B -\newline - -\protected_separator - -\protected_separator - -\protected_separator -2 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -External 1 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -0x0013 -\newline - -\protected_separator - -\protected_separator - -\protected_separator -3 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -Timer 1 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -0x001B -\newline - -\protected_separator - -\protected_separator - -\protected_separator -4 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -Serial -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -0x0023 -\layout Standard - -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. -\layout Standard - -If the interrupt service routine is defined to be using a specific register - bank then only -\begin_inset Quotes eld -\end_inset - -a -\begin_inset Quotes erd -\end_inset - -, -\begin_inset Quotes erd -\end_inset - -b -\begin_inset Quotes erd -\end_inset - - & -\begin_inset Quotes eld -\end_inset - -dptr -\begin_inset Quotes erd -\end_inset - - 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. -\layout Standard - -Calling other functions from an interrupt service routine is not recommended - avoid it if possible. -\layout Section - -Startup Code -\begin_inset LatexCommand \label{Startup} - -\end_inset - - -\layout Standard - -The compiler inserts a jump to the C routine -\series bold -_sdcc__external__startup() -\series default -at the start of the CODE area. - This routine can be found in the file -\series bold -SDCCDIR/sdcc51lib/_startup.c -\series default - , 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. -\layout Section - -Inline assembler code. -\begin_inset LatexCommand \label{Inline} - -\end_inset - - -\layout Standard - -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 -\emph on -form nnnnn$ -\emph default - where nnnn is a number less than 100 (which implies a limit of utmost 100 - inline assembler labels -\noun on -per function) -\noun default -. - It is strongly recommended that each assembly instruction (including labels) - be placed in a separate line ( as the example shows). - When the -\series bold -\bar under ---peep-asm -\series default -\bar default - 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. -\layout Standard - - -\size small -eg -\layout Standard - - -\size small -_asm -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -mov b,#10 -\newline -00001$: -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -djnz b,00001$ -\newline -_endasm ; -\layout Standard - -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 -\emph on -_asm ... - _endasm; -\emph default - keyword pair. - -\layout Standard - -Inline assembler code cannot reference any C-Labels however it can reference - labels defined by the inline assembler. -\layout Standard - - -\size small -eg -\layout Standard - - -\size small -foo() { -\newline -... - /* some c code */ -\newline -_asm -\newline - -\protected_separator - -\protected_separator - -\protected_separator -; some assembler code -\newline - -\protected_separator - -\protected_separator - ljmp $0003 -\newline -_endasm ; -\newline -... - /* some more c code */ -\newline -clabel: -\protected_separator - /* inline assembler cannot reference this label */ -\newline -_asm -\newline - -\protected_separator - -\protected_separator -$0003: ;label (can be reference by inline assembler only) -\newline -_endasm ; -\newline -... - -\newline -} -\layout Standard - -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. -\layout Section - -int (16 bit) and long (32 bit ) support. -\begin_inset LatexCommand \label{int and long} - -\end_inset - - -\layout Standard - -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 -\layout Itemize - - -\size footnotesize -_mulsint.c - signed 16 bit multiplication (calls _muluint) -\layout Itemize - - -\size footnotesize -_muluint.c - unsigned 16 bit multiplication -\layout Itemize - - -\size footnotesize -_divsint.c - signed 16 bit division (calls _divuint) -\layout Itemize - - -\size footnotesize -_divuint.c - unsigned 16 bit division. -\layout Itemize - - -\size footnotesize -_modsint.c - signed 16 bit modulus (call _moduint) -\layout Itemize - - -\size footnotesize -_moduint.c - unsigned 16 bit modulus. -\layout Itemize - - -\size footnotesize -_mulslong.c - signed 32 bit multiplication (calls _mululong) -\layout Itemize - - -\size footnotesize -_mululong.c - unsigned32 bit multiplication. -\layout Itemize - - -\size footnotesize -_divslong.c - signed 32 division (calls _divulong) -\layout Itemize - - -\size footnotesize -_divulong.c - unsigned 32 division. -\layout Itemize - - -\size footnotesize -_modslong.c - signed 32 bit modulus (calls _modulong). -\layout Itemize - - -\size footnotesize -_modulong.c - unsigned 32 bit modulus. -\layout Standard - -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. -\layout Section - -Floating point support -\begin_inset LatexCommand \label{Float} - -\end_inset - - -\layout Standard - -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. - -\layout Itemize - - -\size footnotesize -_fsadd.c - add floating point numbers. -\layout Itemize - - -\size footnotesize -_fssub.c - subtract floating point numbers -\layout Itemize - - -\size footnotesize -_fsdiv.c - divide floating point numbers -\layout Itemize - - -\size footnotesize -_fsmul.c - multiply floating point numbers -\layout Itemize - - -\size footnotesize -_fs2uchar.c - convert floating point to unsigned char -\layout Itemize - - -\size footnotesize -_fs2char.c - convert floating point to signed char. -\layout Itemize - - -\size footnotesize -_fs2uint.c - convert floating point to unsigned int. -\layout Itemize - - -\size footnotesize -_fs2int.c - convert floating point to signed int. -\layout Itemize - - -\size footnotesize -_fs2ulong.c - convert floating point to unsigned long. -\layout Itemize - - -\size footnotesize -_fs2long.c - convert floating point to signed long. -\layout Itemize - - -\size footnotesize -_uchar2fs.c - convert unsigned char to floating point -\layout Itemize - - -\size footnotesize -_char2fs.c - convert char to floating point number -\layout Itemize - - -\size footnotesize -_uint2fs.c - convert unsigned int to floating point -\layout Itemize - - -\size footnotesize -_int2fs.c - convert int to floating point numbers -\layout Itemize - - -\size footnotesize -_ulong2fs.c - convert unsigned long to floating point number -\layout Itemize - - -\size footnotesize -_long2fs.c - convert long to floating point number. -\layout Standard - -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) -\layout Section - -Memory Models -\begin_inset LatexCommand \label{Memory Models} - -\end_inset - - -\layout Standard - -SDCC allows two memory models for MCS51 code. - 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. -\layout Standard - -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. -\layout Standard - -Judicious usage of the processor specific storage classes and the 'reentrant' - function type will yield much more efficient code, than using the large-model. - Several optimizations are disabled when the program is compiled using the - large model, it is therefore strongly recommdended that the small model - be used unless absolutely required. -\layout Section - -Flat 24 bit addressing model. -\begin_inset LatexCommand \label{--model-flat24} - -\end_inset - - -\layout Standard - -This option generates code for the 24 bit contiguous addressing mode of - the Dallas DS80C390 part. - In this mode, up to four meg of external RAM or code space can be directly - addressed. - See the data sheets at www.dalsemi.com for further information on this part. -\layout Standard - -In older versions of the compiler, this option was used with the MCS51 code - generator (-mmcs51). - Now, however, the '390 has it's own code generator, selected by the -mds390 - switch. - This code generator currently supports only the flat24 model, but the --model-f -lat24 switch is still required, in case later versions of the code generator - support other models (such as the paged mode of the '390). - The combination of -mmcs51 and --model-flat24 is now depracated. -\layout Standard - -Note that the compiler does not generate any code to place the processor - into24 bitmode (it defaults to 8051 compatible mode). - Boot loader or similar code must ensure that the processor is in 24 bit - contiguous addressing mode before calling the SDCC startup code. -\layout Standard - -Like the --model-large option, variables will by default be placed into - the XDATA segment. - -\layout Standard - -Segments may be placed anywhere in the 4 meg address space using the usual - --*-loc options. - Note that if any segments are located above 64K, the -r flag must be passed - to the linker to generate the proper segment relocations, and the Intel - HEX output format must be used. - The -r flag can be passed to the linker by using the option -Wl-r on the - sdcc command line. -\layout Standard - ---stack-10bit: -\layout Standard - -This option generates code for the 10 bit stack mode of the Dallas DS80C390 - part. - In this mode, the stack is located in the lower 1K of the internal RAM, - which is mapped to 0x400000. -\layout Standard - -With this option, sdcc will generate the proper addressing for stack variables. -\layout Standard - -Note that the support is incomplete, since it still uses a single byte as - the stack pointer. - This means that only the lower 256 bytes of the potential 1K stack space - can actually be used. - However, this does allow you to reclaim the precious 256 bytes of low RAM - for use for the DATA and IDATA segments. -\layout Standard - -The compiler will not generate any code to put the processor into 10 bit - stack mode. - It is important to ensure that the processor is in this mode before calling - any re-entrant functions compiled with this option. -\layout Standard - -In principle, this should work with the --stack-auto option, but that has - not been tested. - It is incompatible with the --xstack option. - It also only makes sense if the processor is in 24 bit contiguous addressing - mode (see the --model-flat24 option). -\layout Section - -Defines created by the compiler. -\begin_inset LatexCommand \label{Defines.} - -\end_inset - - -\layout Standard - -The compiler creates the following #defines . -\layout Itemize - -SDCC - this Symbol is always defined. -\layout Itemize - -SDCC_STACK_AUTO - this symbol is defined when --stack-auto option is used. -\layout Itemize - -SDCC_MODEL_SMALL - when small model is used. -\layout Itemize - -SDCC_MODEL_LARGE - when --model-large is used. -\layout Itemize - -SDCC_USE_XSTACK - when --xstack option is used. -\layout Section - -Pragmas -\begin_inset LatexCommand \label{Pragmaa} - -\end_inset - - -\layout Standard - -SDCC supports the following -\emph on -#pragma -\emph default -directives. - This directives are applicable only at a function level. -\layout Itemize - - -\series bold -SAVE -\series default - -\begin_inset LatexCommand \label{pragma save} - -\end_inset - - - this will save all the current options . -\layout Itemize - - -\series bold -RESTORE -\series default - -\begin_inset LatexCommand \label{pragma restore} - -\end_inset - -- 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. -\layout Itemize - - -\series bold -NOGCSE -\series default - -\begin_inset LatexCommand \label{pragma nogcse} - -\end_inset - - - will stop global subexpression elimination. -\layout Itemize - - -\series bold -NOINDUCTION -\series default - -\begin_inset LatexCommand \label{pragma noinduction} - -\end_inset - -- will stop loop induction optimizations . -\layout Itemize - - -\series bold -NOJTBOUND -\series default - -\begin_inset LatexCommand \label{pragma nojtbound} - -\end_inset - -- will not generate code for boundary value checking , when switch statements - are turned into jump-tables. -\layout Itemize - - -\series bold -NOOVERLAY -\series default - -\begin_inset LatexCommand \label{pragma nooverlay} - -\end_inset - -- the compiler will not overlay the parameters and local variables of a - function. -\layout Itemize - - -\series bold -NOLOOPREVERSE -\series default - -\begin_inset LatexCommand \label{pragma noloopreverse} - -\end_inset - -- Will not do loop reversal optimization -\layout Itemize - - -\series bold -EXCLUDE NONE | {acc[,b[,dpl[,dph]]] -\series default - -\begin_inset LatexCommand \label{pragma exclude} - -\end_inset - - - 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 -\begin_inset Quotes eld -\end_inset - -#pragma EXCLUDE none -\begin_inset Quotes erd -\end_inset - - -\layout Itemize - - -\series bold -CALLEE-SAVES function1[,function2[,function3...]] -\series default - -\begin_inset LatexCommand \label{pragma callee-saves} - -\end_inset - - - 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 -\begin_inset LatexCommand \ref{--callee-saves} - -\end_inset - - command line option is used, the function names specified in #pragma CALLEE-SAV -ES is appended to the list of functions specified inthe command line. -\layout Standard - -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 -\noun on -before -\noun default - and/or -\noun on -after -\noun default - a function, placing pragma's inside a function body could have unpredictable - results. -\layout Standard - - -\size scriptsize -eg -\layout Standard - - -\size scriptsize -#pragma SAVE -\protected_separator - /* save the current settings */ -\newline -#pragma NOGCSE /* turnoff global subexpression elimination */ -\newline -#pragma NOINDUCTION /* turn off induction optimizations */ -\newline -int foo () -\newline -{ -\newline - -\protected_separator - -\protected_separator - ... - -\newline - -\protected_separator - -\protected_separator - /* large code */ -\newline - -\protected_separator - -\protected_separator - ... - -\newline -} -\newline -#pragma RESTORE /* turn the optimizations back on */ -\layout Standard - -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. -\layout Section - -Library routines. -\begin_inset LatexCommand \label{Library} - -\end_inset - - -\layout Standard - -The following library routines are provided for your convenience. -\layout Standard - - -\series bold -\size large -stdio.h -\series default -\size default -- Contains the following functions printf & sprintf these routines are developed - by -\emph on -Martijn van Balen . - -\layout Standard - - -\size scriptsize -%[flags][width][b|B|l|L]type -\layout Standard - - -\size scriptsize - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - flags: - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - left justify output in specified field width -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - + -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - prefix output with +/- sign if output is signed type -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - space -\protected_separator - -\protected_separator - -\protected_separator - prefix output with a blank if it's a signed positive value -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - width: -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - specifies minimum number of characters outputted for numbers -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - or strings. - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - - For numbers, spaces are added on the left when needed. - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - If width starts with a zero character, zeroes and used -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - instead of spaces. - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - - For strings, spaces are are added on the left or right (when -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - flag '-' is used) when needed. - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - b/B: -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - byte argument (used by d, u, o, x, X) -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - l/L: -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - long argument (used by d, u, o, x, X) -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - type: -\protected_separator - d -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - decimal number -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - u -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - unsigned decimal number -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - o -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - unsigned octal number -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - x -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - unsigned hexadecimal number (0-9, a-f) -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - X -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - unsigned hexadecimal number (0-9, A-F) -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - c -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - character -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - s -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - string (generic pointer) -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - p -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - generic pointer (I:data/idata, C:code, X:xdata, P:paged) -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - f -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - float (still to be implemented) -\layout Standard - -Also contains a very simple version of printf ( -\series bold -printf_small -\series default -). - This simplified version of printf supports only the following formats. -\layout Standard - - -\size scriptsize -\bar under -format -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -output -\protected_separator -type -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -argument-type -\bar default - -\series bold -\size default - -\newline - -\series default -\size scriptsize -%d -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -decimal -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - int -\newline -%ld -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -decimal -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -long -\newline -%hd -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -decimal -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -short/char -\newline -%x -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -hexadecimal -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -int -\newline -%lx -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -hexadecimal -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -long -\newline -%hx -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -hexadecimal -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -short/char -\newline -%o -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -octal -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -int -\newline -%lo -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -octal -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -long -\newline -%ho -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -octal -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -short/char -\newline -%c -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -character -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -char/short -\newline -%s -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -character -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -_generic pointer -\layout Standard - -The routine is -\series bold -very stack intesive -\series default -, --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 -\emph on -putchar(char ) -\emph default - to be present (this can be changed). - When using the %s format the string / pointer should be cast to a generic - pointer. - eg. -\layout Standard - - -\size scriptsize -printf_small( -\begin_inset Quotes eld -\end_inset - -my str %s, my int %d -\backslash -n -\begin_inset Quotes erd -\end_inset - -,(char _generic *)mystr,myint); -\layout Itemize - - -\series bold -\size large -stdarg.h -\series default -\size default -- 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' -\begin_deeper -\layout Standard - - -\size small -va_list, va_start, va_arg, va_end. -\end_deeper -\layout Itemize - - -\series bold -\size large -setjmp.h -\series default -\size default -- contains defintion for ANSI -\series bold - setjmp -\series default -& -\series bold -longjmp -\series default - 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. -\layout Itemize - - -\series bold -\size large -stdlib.h -\series default -\size default - - contains the following functions. -\begin_deeper -\layout Standard - - -\size footnotesize -atoi, atol. -\end_deeper -\layout Itemize - - -\series bold -\size large -string.h -\series default -\size default -- contains the following functions. -\begin_deeper -\layout Standard - - -\size footnotesize -strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn, - strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset. -\end_deeper -\layout Itemize - - -\series bold -\size large -ctype.h -\series default -\size default - - contains the following routines. -\begin_deeper -\layout Standard - - -\size footnotesize -iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace, - isxdigit, isalnum, isalpha. -\end_deeper -\layout Itemize - - -\series bold -\size large -malloc.h -\series default -\size default - - 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). -\begin_deeper -\layout Standard - - -\size scriptsize -//Example: -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - #define DYNAMIC_MEMORY_SIZE 0x2000 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - ..... - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE]; -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - unsigned char xdata * current_buffer; -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - ..... - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - void main(void) -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - { -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - ... - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -// -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE); -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - //Now it's possible to use malloc. - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - ... - -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - current_buffer = malloc(0x100); -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - // -\end_deeper -\layout Itemize - - -\series bold -\size large -serial.h -\series default -\size default - - 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 -\begin_inset Quotes eld -\end_inset - -serial.h -\begin_inset Quotes erd -\end_inset - - MUST be included in the file containing the 'main' function. -\layout Itemize - - -\series bold -\size large -ser.h -\series default -\size default -- Alternate serial routine provided by Wolfgang Esslinger these routines are more compact and faster. - Please see documentation in file SDCCDIR/sdcc51lib/ser.c -\layout Itemize - - -\series bold -\size large -ser_ir.h -\series default -\size default -- Another alternate set of serial routines provided by Josef Wolf , these routines do not use the external ram. -\layout Itemize - - -\series bold -\size large -reg51.h -\series default -\size default - - contains register definitions for a standard 8051 -\layout Itemize - - -\series bold -\size large -reg552.h -\series default -\size default -- contains register definitions for 80C552. -\layout Itemize - - -\series bold -\size large -float.h -\series default -\size default - - contains min, max and other floating point related stuff. -\layout Standard - -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. -\layout Standard - -Have not had time to do the more involved routines like printf, will get - to them shortly. -\layout Section - -Interfacing with assembly routines. -\begin_inset LatexCommand \label{Interface_asm} - -\end_inset - - -\layout Subsection - -Global registers used for parameter passing. -\layout Standard - -By default the compiler uses the global registers -\begin_inset Quotes eld -\end_inset - -DPL,DPH,B,ACC -\begin_inset Quotes erd -\end_inset - - 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). - -\layout Subsubsection - -Assembler routine non-reentrant -\layout Standard - -In the following example the function -\series bold - cfunc -\series default - calls an assembler routine -\series bold -asm_func -\series default -, which takes two parameters. -\layout Standard - - -\size footnotesize -extern int asm_func( unsigned short, unsigned short); -\layout Standard - - -\size footnotesize - -\protected_separator - -\newline -int c_func (unsigned short i, unsigned short j) -\newline -{ -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - return asm_func(i,j); -\newline -} -\size default - -\size scriptsize - -\newline -int main() -\newline -{ -\newline - -\protected_separator - -\protected_separator - -\protected_separator -return c_func(10,9); -\newline -} -\layout Standard - -The corresponding assembler function is:- -\layout Standard - - -\size scriptsize - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .globl _asm_func_PARM_2 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .globl _asm_func -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .area OSEG -\newline -_asm_func_PARM_2: -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .ds -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - 1 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .area CSEG -\newline -_asm_func: -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - a,dpl -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - add -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - a,_asm_func_PARM_2 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - dpl,a -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - dpl,#0x00 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - ret -\layout Standard - -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. -\layout Standard - -The parameter naming convention is -\series bold -__PARM_, -\series default - where n is the parameter number starting from 1, and counting from the - left. - The first parameter is passed in -\begin_inset Quotes eld -\end_inset - -dpl -\begin_inset Quotes erd -\end_inset - - for One bye parameter, -\begin_inset Quotes eld -\end_inset - -dptr -\begin_inset Quotes erd -\end_inset - - if two bytes, -\begin_inset Quotes eld -\end_inset - -b,dptr -\begin_inset Quotes erd -\end_inset - - for three bytes and -\begin_inset Quotes eld -\end_inset - -acc,b,dptr -\begin_inset Quotes erd -\end_inset - - for four bytes, the -\family typewriter -\series bold -\size footnotesize -varaible name for the second parameter will be __PARM_2. -\layout Standard - -Assemble the assembler routine with the following command. -\layout Standard - -asx8051 -losg asmfunc.asm -\layout Standard - -Then compile and link the assembler routine to the C source file with the - following command, -\layout Standard - -sdcc cfunc.c asmfunc.rel -\layout Subsubsection - -Assembler routine is reentrant -\layout Standard - -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. -\layout Standard - - -\size footnotesize -extern int asm_func( unsigned short, unsigned short); -\layout Standard - - -\size footnotesize - -\protected_separator - -\layout Standard - - -\size footnotesize -int c_func (unsigned short i, unsigned short j) reentrant -\newline -{ -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - return asm_func(i,j); -\newline -} -\size default - -\size scriptsize - -\newline -int main() -\newline -{ -\newline - -\protected_separator - -\protected_separator - -\protected_separator -return c_func(10,9); -\newline -} -\layout Standard - -The corresponding assembler routine is. -\layout Standard - - -\size scriptsize - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .globl _asm_func -\newline -_asm_func: -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - push -\protected_separator - _bp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - _bp,sp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -mov -\protected_separator - r2,dpl -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - a,_bp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - clr -\protected_separator - c -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - add -\protected_separator - a,#0xfd -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - r0,a -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - add -\protected_separator - a,#0xfc -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - r1,a -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - a,@r0 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - add -\protected_separator - a,r2 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - dpl,a -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - dph,#0x00 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - sp,_bp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - pop -\protected_separator - _bp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - ret -\layout Standard - -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. -\layout Subsection - -With --noregparms option. -\layout Standard - -When the source is compiled with --noregparms option , space is allocated - for each of the parameters passed to a routine. -\layout Subsubsection - -Assembler routine non-reentrant. -\layout Standard - -In the following example the function -\series bold - cfunc -\series default - calls an assembler routine -\series bold -asm_func -\series default -, which takes two parameters. -\layout Standard - - -\size footnotesize -extern int asm_func( unsigned short, unsigned short); -\layout Standard - - -\size footnotesize - -\protected_separator - -\newline -int c_func (unsigned short i, unsigned short j) -\newline -{ -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - return asm_func(i,j); -\newline -} -\size default - -\size scriptsize - -\newline -int main() -\newline -{ -\newline - -\protected_separator - -\protected_separator - -\protected_separator -return c_func(10,9); -\newline -} -\layout Standard - -The corresponding assembler function is:- -\layout Standard - - -\size scriptsize - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .globl _asm_func_PARM_1 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .globl _asm_func_PARM_2 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .globl _asm_func -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .area OSEG -\newline -_asm_func_PARM_1: -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .ds -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - 1 -\newline -_asm_func_PARM_2: -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .ds -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - 1 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .area CSEG -\newline -_asm_func: -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - a,_asm_func_PARM_1 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - add -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - a,_asm_func_PARM_2 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - dpl,a -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - dpl,#0x00 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - ret -\layout Standard - -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. -\layout Standard - -The parameter naming convention is -\series bold -__PARM_, -\series default - where n is the parameter number starting from 1, and counting from the - left. - i.e. - the -\family typewriter -\series bold -\size footnotesize -left-most parameter name will be __PARM_1. -\layout Standard - -Assemble the assembler routine with the following command. -\layout Standard - -asx8051 -losg asmfunc.asm -\layout Standard - -Then compile and link the assembler routine to the C source file with the - following command, -\layout Standard - -sdcc cfunc.c asmfunc.rel -\layout Subsubsection - -Assembler routine is reentrant. -\layout Standard - -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. -\layout Standard - - -\size footnotesize -extern int asm_func( unsigned short, unsigned short); -\layout Standard - - -\size footnotesize - -\protected_separator - -\layout Standard - - -\size footnotesize -int c_func (unsigned short i, unsigned short j) reentrant -\newline -{ -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - return asm_func(i,j); -\newline -} +\series bold +\size large +\bar under +-E +\series default \size default - -\size scriptsize - -\newline -int main() -\newline -{ -\newline - -\protected_separator - -\protected_separator - -\protected_separator -return c_func(10,9); -\newline -} -\layout Standard - -The corresponding assembler routine is. -\layout Standard - - -\size scriptsize - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - .globl _asm_func -\newline -_asm_func: -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - push -\protected_separator - _bp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - _bp,sp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - a,_bp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - clr -\protected_separator - c -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - add -\protected_separator - a,#0xfd -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - r0,a -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - a,_bp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - clr -\protected_separator - c -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - add -\protected_separator - a,#0xfc -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - r1,a -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - a,@r0 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - add -\protected_separator - a,@r1 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - dpl,a -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - dph,#0x00 -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - mov -\protected_separator - sp,_bp -\newline - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - pop -\protected_separator - _bp -\newline - -\protected_separator +\bar default + Run only the C preprocessor. + Preprocess all the C source files specified and output the results to standard + output. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\protected_separator +\series bold +\size large +\bar under +-M +\series default +\size default +\bar default + 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 ` +\backslash +'-newline if it is long. + The list of rules is printed on standard output instead of the preprocessed + C program. + `-M' implies `-E'. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\protected_separator +\series bold +\size large +\bar under +-C +\series default +\size default +\bar default + Tell the preprocessor not to discard comments. + Used with the `-E' option. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\protected_separator - ret -\layout Standard +\series bold +\size large +\bar under +-MM +\series default +\size default +\bar default +Like `-M' but the output mentions only the user header files included with + `#include file"'. + System header files included with `#include ' are omitted. +\layout List +\labelwidthstring 00.00.0000 -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. -\layout Section -External Stack. -\begin_inset LatexCommand \label{xstack} +\series bold +\size large +\bar under +-Aquestion(answer) +\series default +\size default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 -\end_inset +\series bold +\size large +\bar under +-Aquestion +\series default +\size default +\bar default + (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. +\layout List +\labelwidthstring 00.00.0000 -\layout Standard -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). -\layout Standard +\series bold +\size large +\bar under +-Umacro +\series default +\size default +\bar default + Undefine macro macro. + `-U' options are evaluated after all `-D' options, but before any `-include' + and `-imacros' options. +\layout List +\labelwidthstring 00.00.0000 -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. -\layout Section -ANSI-Compliance. -\begin_inset LatexCommand \label{ANSI_Compliance} +\series bold +\size large +\bar under +-dM +\series default +\size default +\bar default + Tell the preprocessor to output only a list of the macro definitions that + are in effect at the end of preprocessing. + Used with the `-E' option. +\layout List +\labelwidthstring 00.00.0000 -\end_inset +\series bold +\size large +\bar under +-dD +\series default +\size default +\bar default + Tell the preprocessor to pass all macro definitions into the output, in + their proper sequence in the rest of the output. +\layout List +\labelwidthstring 00.00.0000 -\layout Standard -Deviations from the compliancy. -\layout Enumerate +\series bold +\size large +\bar under +-dN +\series default +\size default +\bar default +Like `-dD' except that the macro arguments and contents are omitted. + Only `#define name' is included in the output. +\layout List +\labelwidthstring 00.00.0000 -functions are not always reentrant. -\layout Enumerate -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. -\begin_deeper -\layout Standard +\series bold +\size large +\bar under +-S +\series default +\size default +\bar default +Stop after the stage of compilation proper; do not as- semble. + The output is an assembler code file for the input file specified. +\layout List +\labelwidthstring 00.00.0000 -\size small -eg -\end_deeper -\layout Standard +\series bold +\bar under +-Wa_asmOption[,asmOption] +\series default +\bar default +... + Pass the asmOption to the assembler. +\layout List +\labelwidthstring 00.00.0000 -\size small -struct s { ... - }; -\newline -struct s s1, s2; -\newline -foo() -\newline -{ -\newline -... - -\newline -s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ -\newline -... - -\newline -} -\layout Standard +\series bold +\bar under +-Wl_linkOption[,linkOption] +\series default +\bar default + .. + Pass the linkOption to the linker. +\layout List +\labelwidthstring 00.00.0000 -\size small -struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in - ANSI */ -\newline -{ -\newline -struct s rets; -\newline -... +\series bold +\size large +\bar under +--int-long-reent +\series default +\bar default -\newline -return rets;/* is invalid in SDCC although allowed in ANSI */ -\newline -} -\layout Enumerate - -'long long' (64 bit integers) not supported. -\layout Enumerate +\size default + 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. +\layout List +\labelwidthstring 00.00.0000 -'double' precision floating point not supported. -\layout Enumerate -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. +\series bold +\size large +\bar under +--cyclomatic +\size default -\layout Enumerate - -No support for +\series default +\bar default +This option will cause the compiler to generate an information message for + each function in the source file. + The message contains some \emph on -setjmp +important \emph default - and + 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 \emph on -longjmp +cyclomatic complexity \emph default - (for now). -\layout Enumerate - -Old K&R style function declarations are NOT allowed. -\layout Standard + see section on Cyclomatic Complexity for more details. +\layout List +\labelwidthstring 00.00.0000 -\size footnotesize -foo( i,j) /* this old style of function declarations */ -\newline -int i,j; /* are valid in ANSI .. - not valid in SDCC */ -\newline -{ -\newline -... +\series bold +\size large +\bar under +--float-reent +\size default -\newline -} -\layout Enumerate - -functions declared as pointers must be dereferenced during the call. -\begin_deeper -\layout Standard - - -\size small -int (*foo)(); -\end_deeper -\layout Standard - +\series default +\bar default + Floating point library is compiled as reentrant.See section Installation + for more details. +\layout List +\labelwidthstring 00.00.0000 -\size small -\protected_separator - -\protected_separator -... +\series bold +\size large +\bar under +--out-fmt-ihx +\size default -\newline +\series default +\bar default +The linker output (final object code) is in Intel Hex format. + (This is the default option). +\layout List +\labelwidthstring 00.00.0000 -\protected_separator - -\protected_separator -/* has to be called like this */ -\newline -\protected_separator +\series bold +\size large +\bar under +--out-fmt-s19 +\size default -\protected_separator -(*foo)();/* ansi standard allows calls to be made like 'foo()' */ -\layout Section - -Cyclomatic Complexity -\begin_inset LatexCommand \label{Cyclomatic} - -\end_inset - - -\layout Standard - -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. -\layout Standard +\series default +\bar default +The linker output (final object code) is in Motorola S19 format. +\layout List +\labelwidthstring 00.00.0000 -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. -\layout Standard +\series bold +\size large +\bar under +--nooverlay +\series default +\size default +\bar default + The compiler will not overlay parameters and local variables of any function, + see section Parameters and local variables for more details. +\layout List +\labelwidthstring 00.00.0000 -\size small -complexity = (number of edges in control flow graph) - -\newline -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -(number of nodes in control flow graph) + 2; -\layout Standard +\series bold +\size large +\bar under +--main-return +\series default +\size default +\bar default + 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 .' . +\layout List +\labelwidthstring 00.00.0000 -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. -\layout Section -TIPS -\begin_inset LatexCommand \label{Tips} +\series bold +\size large +\bar under +--no-peep +\series default +\size default +\bar default + Disable peep-hole optimization. +\layout List +\labelwidthstring 00.00.0000 -\end_inset +\series bold +\size large +\bar under +--peep-asm +\series default +\size default +\bar default + 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. +\layout List +\labelwidthstring 00.00.0000 -\layout Standard -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. -\layout Itemize +\series bold +\size large +\bar under +--iram-size +\series default +\size default +\bar default + Causes the linker to check if the interal ram usage is within limits + of the given value. +\layout Subsubsection -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'. -\layout Itemize +Intermediate Dump Options +\layout Standard -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. -\layout Itemize +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. + +\layout List +\labelwidthstring 00.00.0000 -NEVER jump into a LOOP. -\layout Itemize -Declare the variables to be local whenever possible, especially loop control - variables (induction). -\layout Itemize +\series bold +\size large +\bar under +--dumpraw +\series default +\size default +\bar default +. + This option will cause the compiler to dump the intermediate code into + a file of named +\emph on +.dumpraw +\emph default + 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. +\layout List +\labelwidthstring 00.00.0000 -Since the compiler does not do implicit integral promotion, the programmer - should do an explicit cast when integral promotion is required. -\layout Itemize -Reducing the size of division , multiplication & modulus operations can - reduce code size substantially. - Take the following code for example. -\begin_deeper -\layout Standard +\series bold +\size large +\bar under +--dumpgcse +\series default +\bar default +. +\size default + Will create a dump if iCode, after global subexpression elimination, into + a file named +\emph on +.dumpgcse. +\layout List +\labelwidthstring 00.00.0000 -\size footnotesize -foobar( unsigned int p1, unsigned char ch) -\newline -{ -\newline -\protected_separator +\series bold +\size large +\bar under +--dumpdeadcode +\series default +\size default +\bar default +.Will create a dump if iCode, after deadcode elimination, into a file named + +\emph on +.dumpdeadcode. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\protected_separator +\series bold +\size large +\bar under +--dumploop. -\protected_separator -unsigned char ch1 = p1 % ch ; -\newline +\series default +\bar default + +\size default +Will create a dump if iCode, after loop optimizations, into a file named + +\emph on +.dumploop. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\protected_separator +\series bold +\size large +\bar under +--dumprange. -\protected_separator +\series default +\bar default + +\size default +Will create a dump if iCode, after live range analysis, into a file named + +\emph on +.dumprange. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -.... -\protected_separator -\protected_separator +\series bold +\size large +\bar under +--dumpregassign. -\protected_separator +\size default + +\series default +\bar default +Will create a dump if iCode, after register assignment , into a file named + +\emph on +.dumprassgn. +\layout List +\labelwidthstring 00.00.0000 -\protected_separator -\newline -} +\series bold +\size large +\bar under +--dumpall. + +\series default +\size default +\bar default +Will cause all the above mentioned dumps to be created. \layout Standard -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 +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. + \layout Standard +When reporting bugs, it can be helpful to include these dumps along with + the portion of the code that is causing the problem. +\layout Subsection -\size footnotesize -foobar( unsigned int p1, unsigned char ch) -\newline -{ -\newline - -\protected_separator +MCS51 Storage Class Language Extensions +\layout Standard -\protected_separator +In addition to the ANSI storage classes SDCC allows the following MCS51 + specific storage classes. +\layout Subsubsection -\protected_separator +xdata +\layout Standard -\protected_separator -unsigned char ch1 = (unsigned char)p1 % ch ; -\newline +Variables declared with this storage class will be placed in the extern + RAM. + This is the +\series bold +default +\series default + storage class for Large Memory model . +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +eg. + +\emph on +xdata unsigned char xduc; +\layout Subsubsection -\protected_separator +data +\layout Standard -\protected_separator -.... -\protected_separator +This is the +\series bold +default +\series default + storage class for Small Memory model. + Variables declared with this storage class will be allocated in the internal + RAM. +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +eg. -\protected_separator +\emph on + data int iramdata; +\layout Subsubsection -\newline -} +idata \layout Standard -It would substantially reduce the code generated (future versions of the - compiler will be smart enough to detect such optimization oppurtunities). -\end_deeper +Variables declared with this storage class will be allocated into the indirectly + addressable portion of the internal ram of a 8051 . \layout Standard -\series bold -Notes from an USER ( Trefor@magera.freeserve.co.uk ) +\size footnotesize +eg. +\emph on +idata int idi; +\layout Subsubsection + +bit \layout Standard -The 8051 family of micro controller have a minimum of 128 bytes of internal - memory which is structured as follows +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. \layout Standard -- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7 - -\layout Standard +eg. +\emph on +bit iFlag; +\layout Subsubsection -- Bytes 20-2F - 16 bytes to hold 128 bit variables and +sfr / sbit \layout Standard -- Bytes 30-7F - 60 bytes for general purpose use. +Like the bit keyword, +\emph on +sfr / sbit +\emph default +signifies both a data-type and storage class, they are used to describe + the special function registers and special bit variables of a 8051. + \layout Standard -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. -\layout Standard +eg. -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. +\emph on \layout Standard -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. -\layout Standard - -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. -\layout Standard -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. - +\emph on +sfr at 0x80 P0; +\emph default +\noun on +/* special function register P0 at location 0x80 */ \layout Standard ---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. -\layout Standard ---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. -\layout Standard +\emph on +sbit at 0xd7 CY; /* +\noun on +CY (Carry Flag) */ +\layout Subsection ---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. +Pointers \layout Standard -Conclusion. +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 +\emph on +_generic +\emph default + class of pointers which can be used to point to any of the memory spaces. + \layout Standard -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. +Pointer declaration examples. \layout Standard -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. -\layout Section - -Retargetting for other MCUs. -\begin_inset LatexCommand \label{Retargetting} - -\end_inset +\size small +/* pointer physically in xternal ram pointing to object in internal ram + */ +\newline +data unsigned char * xdata p; +\newline \layout Standard -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. -\layout Enumerate -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. -\layout Enumerate +\size small +/* pointer physically in code rom pointing to data in xdata space */ +\newline +xdata unsigned char * code p; +\newline -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. -\layout Enumerate +\layout Standard -This phase does the bulk of the standard optimizations and is also MCU independe -nt. - This phase can be broken down into several sub-phases. -\begin_deeper -\layout Itemize -Break down intermediate code (iCode) into basic blocks. -\layout Itemize +\size small +/* pointer physically in code space pointing to data in code space */ +\newline +code unsigned char * code p; +\newline -Do control flow & data flow analysis on the basic blocks. -\layout Itemize +\newline +/* the folowing is a generic pointer physically located in xdata space */ +\newline +char * xdata p; +\layout Standard -Do local common subexpression elimination, then global subexpression elimination -\layout Itemize +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. +\layout Standard -dead code elimination -\layout Itemize -loop optimizations -\layout Itemize +\size small +unsigned char _xdata *ucxdp; /* pointer to data in external ram */ +\newline +unsigned char _data \SpecialChar ~ +*ucdp ; /* pointer to data in internal ram */ +\newline +unsigned char _code \SpecialChar ~ +*uccp ; /* pointer to data in R/O code space */ +\newline +unsigned char _idata *uccp; \SpecialChar ~ +/* pointer to upper 128 bytes of ram */ +\layout Standard -if loop optimizations caused any changes then do 'global subexpression eliminati -on' and 'dead code elimination' again. -\end_deeper -\layout Enumerate +All unqualified pointers are treated as 3 - byte '_generic' pointers. + These type of pointers can also to be explicitly declared. +\layout Standard -This phase determines the live-ranges; by live range I mean those iTemp - variables defined by the compiler that still survive after all the optimization -s. - Live range analysis is essential for register allocation, since these computati -on determines which of these iTemps will be assigned to registers, and for - how long. -\layout Enumerate -Phase five is register allocation. - There are two parts to this process . -\begin_deeper -\layout Enumerate +\size small +unsigned char _generic *ucgp; +\layout Standard -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. -\layout Enumerate +The highest order byte of the generic pointers contains the data space informati +on. + 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. +\layout Subsection -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. -\end_deeper -\layout Enumerate +Parameters & Local Variables +\layout Standard -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. -\layout Enumerate +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 +\emph on + --stack-auto +\emph default + compiler option or by using the 'reentrant' keyword in the function declaration. +\layout Standard -As mentioned in the optimization section the peep-hole optimizer is rule - based system, which can reprogrammed for other MCUs. -\layout Section -Reporting Bugs -\begin_inset LatexCommand \label{Bugs} +\family typewriter +\size scriptsize +eg +\layout Standard -\end_inset +\size small +unsigned short foo( short i) reentrant { +\newline +... + +\newline +} +\layout Standard +Note that when the parameters & local variables are declared in the internal/ext +ernal ram the functions are non-reentrant. + Since stack space on 8051 is limited the +\emph on +'reentrant' +\emph default +keyword or the +\emph on + --stack-auto +\emph default + 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. \layout Standard -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. -\layout Section - -SDCDB - Source level debugger. +When compiled with the default option (i.e. + non-reentrant ), local variables can be assigned storage classes and absolute + addresses. + \layout Standard -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 -\begin_inset LatexCommand \ref{Installation} -\end_inset +\family typewriter +\size scriptsize +eg +\layout Standard - 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. -\layout Subsection -Compiling for debugging. +\size small +unsigned short foo() { +\newline +\SpecialChar ~ + \SpecialChar ~ +xdata unsigned short i; +\newline +\SpecialChar ~ + \SpecialChar ~ +bit bvar; +\newline +\SpecialChar ~ + \SpecialChar ~ +data at 0x31 unsiged short j; +\newline +... + +\newline +} \layout Standard -The +In the above example the variable \emph on ---debug +i \emph default - option must be specified for all files for which debug information is to - be generated. - The complier generates a + will be allocated in the external ram, \emph on -.cdb +bvar \emph default - file for each of these files. - The linker updates the + in bit addressable space and \emph on -.cdb + j \emph default - file with the address information. - This .cdb is used by the debugger . + in internal ram. + When compiled with the +\emph on +--stack-auto +\emph default + or when a function is declared as +\emph on +'reentrant' +\emph default + local variables cannot be assigned storage classes or absolute addresses. +\layout Standard + +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. \layout Subsection -How the debugger works. +Overlaying \layout Standard -When the +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 overlayabl +e segment if the function has \emph on ---debug +no other function calls and the function is non-reentrant and the memory + model is small. + \emph default - 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 . -\layout Subsection + If an explicit storage class is specified for a local variable , it will + NOT be overplayed. +\layout Standard -Starting the debugger. +Note that the compiler (not the linkage editor) makes the decision for overlayin +g 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. \layout Standard -The debugger can be started using the following command line. - (Assume the file you are debugging has +Parameters and Local variables of functions that contain 16 or 32 bit multiplica +tion or division will NOT be overlayed since these are implemented using + external functions. \layout Standard -the file name foo). +eg. \layout Standard ->sdcdb foo + +\size small +#pragma SAVE +\newline +#pragma NOOVERLAY +\newline +void set_error( unsigned short errcd) +\newline +{ +\newline +\SpecialChar ~ + \SpecialChar ~ + P3 = errcd; +\newline +} +\newline +#pragma RESTORE +\newline +void some_isr () interrupt 2 using 1 +\newline +{ +\newline +\SpecialChar ~ + \SpecialChar ~ + ... + +\newline +\SpecialChar ~ + \SpecialChar ~ + set_error(10); +\newline +\SpecialChar ~ + \SpecialChar ~ + ... + +\newline +} \layout Standard -The debugger will look for the following files. -\layout Enumerate +In the above example the parameter +\emph on +errcd +\emph default + for the function +\emph on +set_error +\emph default + 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. +\layout Subsection -foo.c - the source file. -\layout Enumerate +Critical Functions +\layout Standard -foo.cdb - the debugger symbol information file. -\layout Enumerate +A special keyword may be associated with a function declaring it as ' +\emph on +critical +\emph default +'. + 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. +\layout Standard -foo.ihx - the intel hex format object file. -\layout Subsection +eg +\layout Standard -Command line options. -\layout Itemize ---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. +\size small +int foo () critical +\newline +{ +\newline +... -\layout Itemize - --cd - change to the . -\layout Itemize +\newline +... + +\newline +} +\layout Standard --fullname - used by GUI front ends. -\layout Itemize +The critical attribute maybe used with other attributes like +\emph on +reentrant. +\layout Subsection --cpu - this argument is passed to the simulator please see the - simulator docs for details. -\layout Itemize +Absolute Addressing +\layout Standard --X this options is passed to the simulator please see - simulator docs for details. -\layout Itemize +Data items can be assigned an absolute address with the +\emph on +at
        +\emph default + keyword, in addition to a storage class. +\layout Standard --s passed to simulator see simulator docs for details. -\layout Itemize +eg. + +\layout Standard --S passed to simulator see simulator docs for details. -\layout Subsection -Debugger Commands. +\size small +xdata at 0x8000 unsigned char PORTA_8255 ; \layout Standard -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 integratio -n with existing graphical user interfaces (like ddd, xxgdb or xemacs) existing - for the GNU debugger. -\layout Subsubsection +In the above example the +\emph on +PORTA_8255 +\emph default + will be allocated to the location 0x8000 of the external ram. + +\layout Standard -break [line | file:line | function | file:function] +Note that is this feature is provided to give the programmer access to +\emph on +memory mapped +\emph default + 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 (.rst) and (.m +ap) are a good places to look for such overlaps. \layout Standard -Set breakpoint at specified line or function. +Absolute address can be specified for variables in all storage classes. \layout Standard -sdcdb>break 100 -\newline -sdcdb>break foo.c:100 -\newline -sdcdb>break funcfoo -\newline -sdcdb>break foo.c:funcfoo -\layout Subsubsection -clear [line | file:line | function | file:function ] +\size small +eg. \layout Standard -Clear breakpoint at specified line or function. + +\size small +bit at 0x02 bvar; \layout Standard -sdcdb>clear 100 -\newline -sdcdb>clear foo.c:100 -\newline -sdcdb>clear funcfoo -\newline -sdcdb>clear foo.c:funcfoo -\layout Subsubsection +The above example will allocate the variable at offset 0x02 in the bit-addressab +le 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. +\layout Subsection -continue +Interrupt Service Routines \layout Standard -Continue program being debugged, after breakpoint. -\layout Subsubsection - -finish +SDCC allows interrupt service routines to be coded in C, with some extended + keywords. \layout Standard -Execute till the end of the current function. -\layout Subsubsection -delete [n] +\size small +void timer_isr (void) interrupt 2 using 1 +\newline +{ +\newline +.. + +\newline +} \layout Standard -Delete breakpoint number 'n'. - If used without any option clear ALL user defined break points. -\layout Subsubsection - -info [break | stack | frame | registers ] -\layout Itemize +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, multiplic +ation & 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. +\layout Standard -info break - list all breakpoints -\layout Itemize +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 +\emph on +'main' +\emph default +. +\layout Standard -info stack - show the function call stack. -\layout Itemize +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. +\layout Standard -info frame - show information about the current execution frame. -\layout Itemize -info registers - show content of all registers. -\layout Subsubsection +\begin_inset Tabular + + + + + + + +\begin_inset Text -step \layout Standard -Step program until it reaches a different source line. -\layout Subsubsection +Interrupt # +\end_inset + + +\begin_inset Text -next \layout Standard -Step program, proceeding through subroutine calls. -\layout Subsubsection +Description +\end_inset + + +\begin_inset Text -run \layout Standard -Start debugged program. -\layout Subsubsection +Vector Address +\end_inset + + + + +\begin_inset Text -ptype variable \layout Standard -Print type information of the variable. -\layout Subsubsection +0 +\end_inset + + +\begin_inset Text -print variable \layout Standard -print value of variable. -\layout Subsubsection +External 0 +\end_inset + + +\begin_inset Text -file filename \layout Standard -load the given file name. - Note this is an alternate method of loading file for debugging. -\layout Subsubsection +0x0003 +\end_inset + + + + +\begin_inset Text -frame \layout Standard -print information about current frame. -\layout Subsubsection +1 +\end_inset + + +\begin_inset Text -set srcmode \layout Standard -Toggle between C source & assembly source. -\layout Subsubsection +Timer 0 +\end_inset + + +\begin_inset Text -! simulator command \layout Standard -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. -\layout Subsubsection +0x000B +\end_inset + + + + +\begin_inset Text -quit. \layout Standard -"Watch me now. - Iam going Down. - My name is Bobby Brown" -\layout Subsection - -Interfacing with XEmacs. -\layout Standard +2 +\end_inset + + +\begin_inset Text -Two files are (in emacs lisp) are provided for the interfacing with XEmacs, -\emph on - sdcdb.el -\emph default - and -\emph on -sdcdbsrc.el -\emph default -. - These two files can be found in the $(prefix)/bin directory after the installat -ion 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 - -\emph on -'.xemacs' -\emph default - file (which can be found in your HOME directory) -\emph on -(load-file sdcdbsrc.el) -\emph default -[ .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 -\emph on -'EMACSLOADPATH' -\emph default -to the installation bin directory [$(prefix)/bin], then enter the following - command -\emph on -ESC-x load-file sdcdbsrc . - -\emph default -To start the interface enter the following command -\emph on -ESC-x sdcdbsrc -\emph default - , you will prompted to enter the file name to be debugged. - \layout Standard -The command line options that are passed to the simulator directly are bound - to default values in the file -\emph on -sdcdbsrc.el -\emph default -the variables are listed below these values maybe changed as required. -\layout Itemize +External 1 +\end_inset + + +\begin_inset Text -sdcdbsrc-cpu-type '51 -\layout Itemize +\layout Standard -sdcdbsrc-frequency '11059200 -\layout Itemize +0x0013 +\end_inset + + + + +\begin_inset Text -sdcdbsrc-serial nil \layout Standard -The following is a list of key mapping for the debugger interface. +3 +\end_inset + + +\begin_inset Text + \layout Standard +Timer 1 +\end_inset + + +\begin_inset Text -\protected_separator +\layout Standard -\size scriptsize +0x001B +\end_inset + + + + +\begin_inset Text -\newline -;; Current Listing :: -\newline -;;key -\protected_separator +\layout Standard -\protected_separator +4 +\end_inset + + +\begin_inset Text -\protected_separator +\layout Standard -\protected_separator +Serial +\end_inset + + +\begin_inset Text -\protected_separator +\layout Standard -\protected_separator +0x0023 +\end_inset + + + -\protected_separator +\end_inset -\protected_separator -\protected_separator +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +If the interrupt service routine is defined to be using a specific register + bank then only +\begin_inset Quotes eld +\end_inset -\protected_separator +a +\begin_inset Quotes erd +\end_inset -\protected_separator +, +\begin_inset Quotes erd +\end_inset -\protected_separator +b +\begin_inset Quotes erd +\end_inset -\protected_separator -binding -\protected_separator + & +\begin_inset Quotes eld +\end_inset -\protected_separator +dptr +\begin_inset Quotes erd +\end_inset -\protected_separator + 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. +\layout Standard -\protected_separator +Calling other functions from an interrupt service routine is not recommended + avoid it if possible. +\layout Subsection -\protected_separator +Startup Code +\layout Standard -\protected_separator +The compiler inserts a jump to the C routine +\series bold +_sdcc__external__startup() +\series default +at the start of the CODE area. + This routine can be found in the file +\series bold +SDCCDIR/sdcc51lib/_startup.c +\series default +, 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. + You could add a +\series bold +_sdcc__external__startup() +\series default + routine to your program to override the default if you needed to setup + hardware or perform some other critical operation prior to static & global + variable initialization. +\layout Subsection -\protected_separator +Inline Assembler Code +\layout Standard -\protected_separator +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 +\emph on +form nnnnn$ +\emph default + where nnnn is a number less than 100 (which implies a limit of utmost 100 + inline assembler labels +\noun on +per function) +\noun default +. + It is strongly recommended that each assembly instruction (including labels) + be placed in a separate line ( as the example shows). + When the +\series bold +\bar under +--peep-asm +\series default +\bar default + 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. +\layout Standard -\protected_separator -\protected_separator +\size small +eg +\layout Standard -\protected_separator -\protected_separator +\size small +_asm +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +mov b,#10 +\newline +00001$: +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +djnz b,00001$ +\newline +_endasm ; +\layout Standard -\protected_separator +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 +\emph on +_asm ... + _endasm; +\emph default + keyword pair. + +\layout Standard -\protected_separator +Inline assembler code cannot reference any C-Labels however it can reference + labels defined by the inline assembler. +\layout Standard -\protected_separator -\protected_separator +\size small +eg +\layout Standard -\protected_separator -\protected_separator +\size small +foo() { +\newline +... + /* some c code */ +\newline +_asm +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +; some assembler code +\newline +\SpecialChar ~ + \SpecialChar ~ + ljmp $0003 +\newline +_endasm ; +\newline +... + /* some more c code */ +\newline +clabel: \SpecialChar ~ + /* inline assembler cannot reference this label */ +\newline +_asm +\newline +\SpecialChar ~ + \SpecialChar ~ +$0003: ;label (can be reference by inline assembler only) +\newline +_endasm ; +\newline +... + +\newline +} +\layout Standard -\protected_separator +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. +\layout Subsection -\protected_separator +int(16 bit) and long (32 bit ) Support +\layout Standard -\protected_separator +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 +\layout Itemize -\protected_separator -Comment -\newline -;;--- -\protected_separator -\protected_separator +\size footnotesize +_mulsint.c - signed 16 bit multiplication (calls _muluint) +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_muluint.c - unsigned 16 bit multiplication +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_divsint.c - signed 16 bit division (calls _divuint) +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_divuint.c - unsigned 16 bit division. +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_modsint.c - signed 16 bit modulus (call _moduint) +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_moduint.c - unsigned 16 bit modulus. +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_mulslong.c - signed 32 bit multiplication (calls _mululong) +\layout Itemize -\protected_separator -------- -\protected_separator -\protected_separator +\size footnotesize +_mululong.c - unsigned32 bit multiplication. +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_divslong.c - signed 32 division (calls _divulong) +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_divulong.c - unsigned 32 division. +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_modslong.c - signed 32 bit modulus (calls _modulong). +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_modulong.c - unsigned 32 bit modulus. +\layout Standard -\protected_separator +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. +\layout Subsection -\protected_separator +Floating Point Support +\layout Standard -\protected_separator +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. + +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_fsadd.c - add floating point numbers. +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_fssub.c - subtract floating point numbers +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_fsdiv.c - divide floating point numbers +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_fsmul.c - multiply floating point numbers +\layout Itemize -\protected_separator -------- -\newline -;; -\newline -;; n -\protected_separator -\protected_separator +\size footnotesize +_fs2uchar.c - convert floating point to unsigned char +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_fs2char.c - convert floating point to signed char. +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_fs2uint.c - convert floating point to unsigned int. +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_fs2int.c - convert floating point to signed int. +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_fs2ulong.c - convert floating point to unsigned long. +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_fs2long.c - convert floating point to signed long. +\layout Itemize -\protected_separator -\protected_separator - sdcdb-next-from-src -\protected_separator +\size footnotesize +_uchar2fs.c - convert unsigned char to floating point +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_char2fs.c - convert char to floating point number +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_uint2fs.c - convert unsigned int to floating point +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_int2fs.c - convert int to floating point numbers +\layout Itemize -\protected_separator -\protected_separator +\size footnotesize +_ulong2fs.c - convert unsigned long to floating point number +\layout Itemize -\protected_separator -SDCDB next command -\newline -;; b -\protected_separator -\protected_separator +\size footnotesize +_long2fs.c - convert long to floating point number. +\layout Standard -\protected_separator +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) +\layout Subsection -\protected_separator +MCS51 Memory Models +\layout Standard -\protected_separator +SDCC allows two memory models for MCS51 code, small and large. + Modules compiled with different memory models should never be combined + together or the results would be unpredictable. + The library routines supplied with the compiler are compiled as both small + and large. + The compiled library modules are contained in seperate directories as small + and large so that you can link to either set. + In general the use of the large model is discouraged. +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +Judicious usage of the processor specific storage classes and the 'reentrant' + function type will yield much more efficient code, than using the large-model. + Several optimizations are disabled when the program is compiled using the + large model, it is therefore strongly recommdended that the small model + be used unless absolutely required. +\layout Subsection -\protected_separator +Flat 24 bit Addressing Model +\layout Standard -\protected_separator +This option generates code for the 24 bit contiguous addressing mode of + the Dallas DS80C390 part. + In this mode, up to four meg of external RAM or code space can be directly + addressed. + See the data sheets at www.dalsemi.com for further information on this part. +\layout Standard -\protected_separator +In older versions of the compiler, this option was used with the MCS51 code + generator (-mmcs51). + Now, however, the '390 has it's own code generator, selected by the -mds390 + switch. + This code generator currently supports only the flat24 model, but the --model-f +lat24 switch is still required, in case later versions of the code generator + support other models (such as the paged mode of the '390). + The combination of -mmcs51 and --model-flat24 is now depracated. +\layout Standard -\protected_separator +Note that the compiler does not generate any code to place the processor + into24 bitmode (it defaults to 8051 compatible mode). + Boot loader or similar code must ensure that the processor is in 24 bit + contiguous addressing mode before calling the SDCC startup code. +\layout Standard -\protected_separator +Like the --model-large option, variables will by default be placed into + the XDATA segment. + +\layout Standard -\protected_separator +Segments may be placed anywhere in the 4 meg address space using the usual + --*-loc options. + Note that if any segments are located above 64K, the -r flag must be passed + to the linker to generate the proper segment relocations, and the Intel + HEX output format must be used. + The -r flag can be passed to the linker by using the option -Wl-r on the + sdcc command line. +\layout Subsection -\protected_separator - sdcdb-back-from-src -\protected_separator +Defines Created by the Compiler +\layout Standard -\protected_separator +The compiler creates the following #defines . +\layout Itemize -\protected_separator +SDCC - this Symbol is always defined. +\layout Itemize -\protected_separator +SDCC_STACK_AUTO - this symbol is defined when --stack-auto option is used. +\layout Itemize -\protected_separator +SDCC_MODEL_SMALL - when small model is used. +\layout Itemize -\protected_separator +SDCC_MODEL_LARGE - when --model-large is used. +\layout Itemize -\protected_separator +SDCC_USE_XSTACK - when --xstack option is used. +\layout Section -\protected_separator +SDCC Technical Data +\layout Subsection -\protected_separator +Optimizations +\layout Standard -\protected_separator -SDCDB back command -\newline -;; c -\protected_separator +SDCC performs a a host of standard optimizations in addition to some MCU + specific optimizations. + +\layout Subsubsection -\protected_separator +Sub-expression Elimination +\layout Standard -\protected_separator +The compiler does +\emph on +local and global +\emph default +common subexpression elimination. +\layout Standard -\protected_separator -\protected_separator +\family typewriter +\size scriptsize +eg. + +\layout Standard -\protected_separator -\protected_separator +\size small +i = x + y + 1; +\size default -\protected_separator +\newline +j +\size small += x + y; +\layout Standard -\protected_separator +will be translated to +\layout Standard -\protected_separator -\protected_separator +\size small +iTemp = x + y +\newline +i = iTemp + 1 +\newline +j = iTemp +\layout Standard -\protected_separator +Some subexpressions are not as obvious as the above example. +\layout Standard -\protected_separator +eg. +\layout Standard -\protected_separator - sdcdb-cont-from-src -\protected_separator -\protected_separator +\size small +a->b[i].c = 10; +\newline +a->b[i].d = 11; +\layout Standard -\protected_separator +In this case the address arithmetic +\emph on +a->b[i] +\emph default +will be computed only once; the equivalent code in C would be. +\layout Standard -\protected_separator -\protected_separator +\size small +iTemp = a->b[i]; +\newline +iTemp.c = 10; +\newline +iTemp.d = 11; +\layout Standard -\protected_separator +The compiler will try to keep these temporary variables in registers. +\layout Subsubsection -\protected_separator +Dead-Code Elimination +\layout Standard -\protected_separator +eg. +\layout Standard -\protected_separator -\protected_separator -SDCDB continue command +\size small +int global; \newline -;; s -\protected_separator - -\protected_separator +void f () { +\newline +\SpecialChar ~ +\SpecialChar ~ +int i; +\newline +\SpecialChar ~ +\SpecialChar ~ +i = 1; \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +/* dead store */ +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 1; /* dead store */ +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 2; +\newline +\SpecialChar ~ +\SpecialChar ~ +return; +\newline +\SpecialChar ~ +\SpecialChar ~ +global = 3; /* unreachable */ +\newline +} +\layout Standard -\protected_separator +will be changed to +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +int global; void f () +\newline +{ \SpecialChar ~ + \SpecialChar ~ + +\newline +\SpecialChar ~ +global = 2; \SpecialChar ~ + \SpecialChar ~ + +\newline +\SpecialChar ~ +return; +\newline +} +\layout Subsubsection -\protected_separator +Copy-Propagation +\layout Standard -\protected_separator +eg. +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +int f() { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +int i, j; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +i = 10; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +j = i; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return j; +\newline +} +\layout Standard -\protected_separator +will be changed to +\layout Standard -\protected_separator -\protected_separator +\size small +int f() { +\newline +\SpecialChar ~ + \SpecialChar ~ + int i,j; +\newline +\SpecialChar ~ + \SpecialChar ~ + i = 10; +\newline +\SpecialChar ~ + \SpecialChar ~ + j = 10; +\newline +\SpecialChar ~ + \SpecialChar ~ + return 10; +\newline +} +\layout Standard -\protected_separator +Note: the dead stores created by this copy propagation will be eliminated + by dead-code elimination . +\layout Subsubsection -\protected_separator - sdcdb-step-from-src -\protected_separator +Loop Optimizations +\layout Standard -\protected_separator +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 optimizat +ion 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). +\layout Itemize -\protected_separator -\protected_separator +\series bold +Loop Invariant: +\layout Standard -\protected_separator +eg +\layout Standard -\protected_separator -\protected_separator +\size small +for (i = 0 ; i < 100 ; i ++) +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +f += k + l; +\layout Standard -\protected_separator +changed to +\layout Standard -\protected_separator -\protected_separator -SDCDB step command +\size small +itemp = k + l; \newline -;; ? -\protected_separator - -\protected_separator +for ( i = 0; i < 100; i++ ) f += itemp; +\layout Standard -\protected_separator +As mentioned previously some loop invariants are not as apparent, all static + address computations are also moved out of the loop. +\layout Itemize -\protected_separator -\protected_separator +\series bold +Strength Reduction : +\layout Standard -\protected_separator +This optimization substitutes an expression by a cheaper expression. +\layout Standard -\protected_separator +eg. +\layout Standard -\protected_separator -\protected_separator +\size small +for (i=0;i < 100; i++) ar[i*5] = i*3; +\layout Standard -\protected_separator +changed to +\layout Standard -\protected_separator -\protected_separator +\size small +itemp1 = 0; +\newline +itemp2 = 0; +\newline +for (i=0;i< 100;i++) { +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +ar[itemp1] = itemp2; +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +itemp1 += 5; +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +itemp2 += 3; +\newline +} +\layout Standard -\protected_separator +The more expensive multiplication is changed to a less expensive addition. +\layout Subsubsection -\protected_separator - sdcdb-whatis-c-sexp -\protected_separator +Loop Reversing: +\layout Standard -\protected_separator +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 +\begin_inset Quotes eld +\end_inset -\protected_separator +decrement and jump if not zero +\begin_inset Quotes erd +\end_inset -\protected_separator + 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). +\layout Itemize -\protected_separator +The 'for' loop is of the form +\newline -\protected_separator +\begin_inset Quotes eld +\end_inset -\protected_separator +for ( = ; [< | <=] ; [++ | + += 1]) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\begin_inset Quotes erd +\end_inset -\protected_separator -\protected_separator +\layout Itemize -\protected_separator -SDCDB ptypecommand for data at -\newline -;; -\protected_separator +The does not contain +\begin_inset Quotes eld +\end_inset -\protected_separator +continue +\begin_inset Quotes erd +\end_inset -\protected_separator + or 'break +\begin_inset Quotes erd +\end_inset -\protected_separator +. +\layout Itemize -\protected_separator +All goto's are contained within the loop. +\layout Itemize -\protected_separator +No function calls within the loop. +\layout Itemize -\protected_separator +The loop control variable is not assigned any value within the loop +\layout Itemize -\protected_separator +The loop control variable does NOT participate in any arithmetic operation + within the loop. +\layout Itemize -\protected_separator +There are NO switch statements in the loop. +\layout Standard -\protected_separator +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. +\layout Subsubsection -\protected_separator +Algebraic Simplifications +\layout Standard -\protected_separator +SDCC does numerous algebraic simplifications, the following is a small sub-set + of these optimizations. +\layout Standard -\protected_separator -\protected_separator +\size small +eg +\emph on + +\emph default -\protected_separator +\newline +i = j + 0 ; /* changed to */ i = j; +\newline +i /= 2; /* changed to */ i >>= 1; +\newline +i = j - j ; /* changed to */ i = 0; +\newline +i = j / 1 ; /* changed to */ i = j; +\layout Standard -\protected_separator +Note the subexpressions given above are generally introduced by macro expansions + or as a result of copy/constant propagation. +\layout Subsubsection -\protected_separator +'switch' Statements +\layout Standard -\protected_separator +SDCC changes switch statements to jump tables when the following conditions + are true. + +\layout Itemize -\protected_separator +The case labels are in numerical sequence , the labels need not be in order, + and the starting number need not be one or zero. +\layout Standard -\protected_separator +eg +\layout Standard -\protected_separator -\protected_separator +\size small +switch(i) {\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +switch (i) { +\newline +case 4:... + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +case 1: ... + +\newline +case 5:... + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +case 2: ... + +\newline +case 3:... + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +case 3: ... + +\newline +case 6:... + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +case 4: ... + +\newline +}\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +} +\layout Standard -\protected_separator +Both the above switch statements will be implemented using a jump-table. +\layout Itemize -\protected_separator +The number of case labels is at least three, since it takes two conditional + statements to handle the boundary conditions. +\layout Itemize -\protected_separator +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. + +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +eg +\layout Standard -\protected_separator -\protected_separator +\size small +switch (i) { +\newline +case 1: ... + +\newline +case 2: ... + +\newline +case 3: ... + +\newline +case 4: ... + +\newline +case 9: ... + +\newline +case 10: ... + +\newline +case 11: ... + +\newline +case 12: ... + +\newline +} +\layout Standard -\protected_separator +If the above switch statement is broken down into two switch statements +\layout Standard -\protected_separator -\protected_separator +\size small +switch (i) { +\newline +case 1: ... + +\newline +case 2: ... + +\newline +case 3: ... + +\newline +case 4: ... + +\newline +} +\layout Standard -\protected_separator -\protected_separator +\size small +switch (i) { +\newline +case 9: ... + +\newline +case 10: ... + +\newline +case 11: ... + +\newline +case 12:... + +\newline +} +\layout Standard -\protected_separator +then both the switch statements will be implemented using jump-tables whereas + the unmodified switch statement will not be . +\layout Subsubsection -\protected_separator +Bit-shifting Operations. +\layout Standard -\protected_separator +Bit shifting is one of the most frequently used operation in embedded programmin +g . + SDCC tries to implement bit-shift operations in the most efficient way + possible. +\layout Standard -\protected_separator +eg. +\layout Standard -\protected_separator -\protected_separator +\size small +unsigned short i; +\layout Standard -\protected_separator -\protected_separator - buffer point +\size small +... + \newline -;; x -\protected_separator - -\protected_separator +i>>= 4; +\newline +.. +\layout Standard -\protected_separator +generates the following code. +\layout Standard -\protected_separator -\protected_separator +\size small +mov a,_i +\newline +swap a +\newline +anl a,#0x0f +\newline +mov _i,a +\layout Standard -\protected_separator +In general SDCC will never setup a loop if the shift count is known. + Another example +\layout Standard -\protected_separator -\protected_separator +\size small +unsigned int i; +\newline +... + +\newline +i >>= 9; +\newline +... +\layout Standard -\protected_separator +will generate +\layout Standard -\protected_separator -\protected_separator +\size small +mov a,(_i + 1) +\newline +mov (_i + 1),#0x00 +\newline +clr c +\newline +rrc a +\newline +mov _i,a +\layout Standard -\protected_separator +Note that SDCC stores numbers in +\noun on +little-endian +\noun default +format (i.e. + lowest order first) +\layout Subsubsection -\protected_separator +Bit-rotation +\layout Standard -\protected_separator - sdcdbsrc-delete -\protected_separator +A special case of the bit-shift operation is bit rotation, SDCC recognizes + the following expression to be a left bit-rotation. +\layout Standard -\protected_separator -\protected_separator +\size small +unsigned char i; +\newline +... + +\newline +i = ( ( i << 1) | ( i >> 7)); +\newline +... +\layout Standard -\protected_separator +will generate the following code. +\layout Standard -\protected_separator -\protected_separator +\size small +mov a,_i +\newline +rl a +\newline +mov _i,a +\layout Standard -\protected_separator +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 +\emph on + i = ((i >> 7) | (i << 1)); +\emph default +/* left-bit rotation */ +\layout Subsubsection -\protected_separator +Highest Order Bit +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator -\protected_separator +\size small +eg +\newline +unsigned int gint; +\newline +foo () { +\newline +unsigned char hob; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +hob = (gint >> 15) & 1; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +.. + +\newline +} +\layout Standard -\protected_separator +Will generate the following code. +\layout Standard -\protected_separator -\protected_separator -SDCDB Delete all breakpoints if no arg +\size small +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 61 ;\SpecialChar ~ + hob.c 7 \newline -;; -\protected_separator - -\protected_separator +\SpecialChar ~ +\SpecialChar ~ + 000A E5*01\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 62\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + a,(_gint + 1) +\newline +\SpecialChar ~ +\SpecialChar ~ + 000C 33\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 63\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + rlc\SpecialChar ~ + a +\newline +\SpecialChar ~ +\SpecialChar ~ + 000D E4\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 64\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + clr\SpecialChar ~ + a +\newline +\SpecialChar ~ +\SpecialChar ~ + 000E 13\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 65\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + rrc\SpecialChar ~ + a +\newline +\SpecialChar ~ +\SpecialChar ~ + 000F F5*02\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 66\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + _foo_hob_1_1,a +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator -\protected_separator +\size small +eg. +\layout Standard -\protected_separator -\protected_separator +\size small +xyz = gint + ((gint >> 15) & 1); +\layout Standard -\protected_separator +will still be recognized. +\layout Subsubsection -\protected_separator +Peep-hole Optimizer +\layout Standard -\protected_separator +The compiler uses a rule based , pattern matching and re-writing mechanism + for peep-hole optimization . + It is inspired by ' +\emph on +copt' +\emph default + 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 option. + The rule language is best illustrated with examples. +\layout Standard -\protected_separator -\protected_separator +\size small +replace { +\newline +mov %1,a +\newline +mov a,%1 } by { mov %1,a } +\layout Standard -\protected_separator +The above rule will the following assembly sequence +\layout Standard -\protected_separator -\protected_separator +\size small +mov r1,a +\newline +mov a,r1 +\layout Standard -\protected_separator +to +\layout Standard -\protected_separator -\protected_separator +\size small +mov r1,a +\layout Standard -\protected_separator +Note: All occurrences of a '%n' ( pattern variable ) must denote the same + string. + With the above rule, the assembly sequence +\layout Standard -\protected_separator -\protected_separator +\size small +mov r1,a +\newline +mov a,r2 +\layout Standard -\protected_separator +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'. +\layout Standard -\protected_separator -\protected_separator +\size small +replace { lcall %1 } by { acall %1 } +\newline +replace { ljmp %1 } by { ajmp %1 } +\layout Standard -\protected_separator +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-structur +e is MCU independent. + Peephole optimization rules for other MCU can be easily programmed using + the rule language. +\layout Standard -\protected_separator +The syntax for a rule is as follows , +\layout Standard -\protected_separator -\protected_separator +\size small +rule := replace [ restart ] '{' ' +\backslash +n' +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + '}' by '{' ' +\backslash +n' +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + ' +\backslash +n' +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + '}' [if ] ' +\backslash +n' +\newline + := assembly instruction (each instruction including + labels must be on a separate line).\SpecialChar ~ + \SpecialChar ~ -\protected_separator +\layout Standard -\protected_separator +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 ' +\emph on +restart +\emph default +' 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. +\layout Standard -\protected_separator -\protected_separator +\size small +replace restart { +\newline +pop %1 +\newline +push %1 } by { +\newline +; nop +\newline +} +\layout Standard -\protected_separator +Note that the replace pattern cannot be a blank, but can be a comment line. + Without the ' +\emph on +restart +\emph default +' option only the inner most 'pop' 'push' pair would be eliminated. + i.e. +\layout Standard -\protected_separator -\protected_separator +\size small +pop ar1 +\newline +pop ar2 +\newline +push ar2 +\newline +push ar1 +\layout Standard -\protected_separator +would result in +\layout Standard -\protected_separator -\protected_separator +\size small +pop ar1 +\newline +; nop +\newline +push ar1 +\layout Standard -\protected_separator +with the ' +\emph on +restart +\emph default +' option the rule will be applied again to the resulting code and the all + the ' +\emph on +pop' 'push' +\emph default + pairs will be eliminated to yield +\layout Standard -\protected_separator -\protected_separator +\size small +; nop +\newline +; nop +\layout Standard -\protected_separator +A conditional function can be attached to a rule. + Attaching rules are somewhat more involved, let me illustrate this with + an example. +\layout Standard -\protected_separator -\protected_separator +\size small +replace { +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +ljmp %5 +\newline +%2:} by { +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +sjmp %5 +\newline +%2:} if labelInRange +\layout Standard -\protected_separator +The optimizer does a look-up of a function name table defined in function + ' +\emph on +callFuncByName' +\emph default + in the source file +\emph on +SDCCpeeph.c +\emph default + , with the name +\emph on +'labelInRange +\emph default +', 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 +\emph on +'%5 +\emph default +' is crucial, since the function +\emph on +labelInRange +\emph default + expects to find the label in that particular variable (the hash table containin +g the variable bindings is passed as a parameter). + If you want to code more such functions , take a close look at the function + +\emph on +labelInRange +\emph default + and the calling mechanism in source file +\emph on +SDCCpeeph.c +\emph default +. + 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 +\emph on +--peep-file +\emph default + option. +\layout Subsection -\protected_separator -given or delete arg (C-u arg x) -\newline -;; m -\protected_separator +Pragmas +\layout Standard -\protected_separator +SDCC supports the following +\emph on +#pragma +\emph default +directives. + This directives are applicable only at a function level. +\layout Itemize -\protected_separator -\protected_separator +\series bold +SAVE +\series default + - this will save all the current options . +\layout Itemize -\protected_separator -\protected_separator +\series bold +RESTORE +\series default +- 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. +\layout Itemize -\protected_separator -\protected_separator +\series bold +NOGCSE +\series default + - will stop global subexpression elimination. +\layout Itemize -\protected_separator -\protected_separator +\series bold +NOINDUCTION +\series default + - will stop loop induction optimizations . +\layout Itemize -\protected_separator -\protected_separator +\series bold +NOJTBOUND +\series default + - will not generate code for boundary value checking , when switch statements + are turned into jump-tables. +\layout Itemize -\protected_separator -\protected_separator - sdcdbsrc-frame -\protected_separator +\series bold +NOOVERLAY +\series default +- the compiler will not overlay the parameters and local variables of a + function. +\layout Itemize -\protected_separator -\protected_separator +\series bold +NOLOOPREVERSE +\series default + - Will not do loop reversal optimization +\layout Itemize -\protected_separator -\protected_separator +\series bold +EXCLUDE NONE | {acc[,b[,dpl[,dph]]] +\series default + - 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 +\begin_inset Quotes eld +\end_inset -\protected_separator +#pragma EXCLUDE none +\begin_inset Quotes erd +\end_inset -\protected_separator -\protected_separator +\layout Itemize -\protected_separator -\protected_separator +\series bold +CALLEE-SAVES function1[,function2[,function3...]] +\series default + - 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 command line option is used, the function names specified + in #pragma CALLEE-SAVES is appended to the list of functions specified + inthe command line. +\layout Standard -\protected_separator +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 +\noun on +before +\noun default + and/or +\noun on +after +\noun default + a function, placing pragma's inside a function body could have unpredictable + results. +\layout Standard -\protected_separator -\protected_separator +\size scriptsize +eg +\layout Standard -\protected_separator -\protected_separator -SDCDB Display current frame if no arg, +\size scriptsize +#pragma SAVE \SpecialChar ~ + /* save the current settings */ \newline -;; -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator +#pragma NOGCSE /* turnoff global subexpression elimination */ +\newline +#pragma NOINDUCTION /* turn off induction optimizations */ +\newline +int foo () +\newline +{ +\newline +\SpecialChar ~ + \SpecialChar ~ + ... + +\newline +\SpecialChar ~ + \SpecialChar ~ + /* large code */ +\newline +\SpecialChar ~ + \SpecialChar ~ + ... + +\newline +} +\newline +#pragma RESTORE /* turn the optimizations back on */ +\layout Standard -\protected_separator +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. +\layout Subsection -\protected_separator +Library Routines +\layout Standard -\protected_separator +The following library routines are provided for your convenience. +\layout Standard -\protected_separator -\protected_separator +\series bold +\size large +stdio.h +\series default +\size default +- Contains the following functions printf & sprintf these routines are developed + by +\emph on +Martijn van Balen . + +\layout Standard -\protected_separator -\protected_separator +\size scriptsize +%[flags][width][b|B|l|L]type +\layout Standard -\protected_separator -\protected_separator +\size scriptsize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + flags: -\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + left justify output in specified field width +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + prefix output with +/- sign if output is signed type +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + space\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + prefix output with a blank if it's a signed positive value +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + width:\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + specifies minimum number of characters outputted for numbers +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + or strings. + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + - For numbers, spaces are added on the left when needed. + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + If width starts with a zero character, zeroes and used +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + instead of spaces. + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + - For strings, spaces are are added on the left or right (when +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + flag '-' is used) when needed. + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + b/B:\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + byte argument (used by d, u, o, x, X) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + l/L:\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + long argument (used by d, u, o, x, X) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + type:\SpecialChar ~ + d\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + decimal number +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + u\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + unsigned decimal number +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + o\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + unsigned octal number +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + x\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + unsigned hexadecimal number (0-9, a-f) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + X\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + unsigned hexadecimal number (0-9, A-F) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + c\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + character +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + s\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + string (generic pointer) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + p\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + generic pointer (I:data/idata, C:code, X:xdata, P:paged) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + f\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + float (still to be implemented) +\layout Standard -\protected_separator +Also contains a very simple version of printf ( +\series bold +printf_small +\series default +). + This simplified version of printf supports only the following formats. +\layout Standard -\protected_separator -\protected_separator +\size scriptsize +\bar under +format\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +output\SpecialChar ~ +type\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +argument-type +\bar default + +\series bold +\size default -\protected_separator +\newline -\protected_separator +\series default +\size scriptsize +%d \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +decimal \SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + int +\newline +%ld\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +decimal\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +long +\newline +%hd\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +decimal\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +short/char +\newline +%x\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +hexadecimal\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +int +\newline +%lx\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +hexadecimal\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +long +\newline +%hx\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +hexadecimal\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +short/char +\newline +%o\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +octal\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +int +\newline +%lo\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +octal\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +long +\newline +%ho\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +octal\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +short/char +\newline +%c\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +character\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +char/short +\newline +%s\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +character\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +_generic pointer +\layout Standard -\protected_separator +The routine is +\series bold +very stack intesive +\series default +, --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 +\emph on +putchar(char ) +\emph default + to be present (this can be changed). + When using the %s format the string / pointer should be cast to a generic + pointer. + eg. +\layout Standard -\protected_separator -\protected_separator +\size scriptsize +printf_small( +\begin_inset Quotes eld +\end_inset -\protected_separator +my str %s, my int %d +\backslash +n +\begin_inset Quotes erd +\end_inset -\protected_separator +,(char _generic *)mystr,myint); +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +stdarg.h +\series default +\size default +- 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' +\begin_deeper +\layout Standard -\protected_separator -\protected_separator +\size small +va_list, va_start, va_arg, va_end. +\end_deeper +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +setjmp.h +\series default +\size default +- contains defintion for ANSI +\series bold + setjmp +\series default +& +\series bold +longjmp +\series default + 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. +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +stdlib.h +\series default +\size default + - contains the following functions. +\begin_deeper +\layout Standard -\protected_separator -\protected_separator -given or display frame arg -\newline -;; -\protected_separator +\size footnotesize +atoi, atol. +\end_deeper +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +string.h +\series default +\size default +- contains the following functions. +\begin_deeper +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn, + strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset. +\end_deeper +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +ctype.h +\series default +\size default + - contains the following routines. +\begin_deeper +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace, + isxdigit, isalnum, isalpha. +\end_deeper +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +malloc.h +\series default +\size default + - 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). +\begin_deeper +\layout Standard -\protected_separator -\protected_separator +\size scriptsize +//Example: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + #define DYNAMIC_MEMORY_SIZE 0x2000 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ..... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE]; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + unsigned char xdata * current_buffer; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ..... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + void main(void) +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + { +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +//\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE); +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //Now it's possible to use malloc. + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ... + +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + //\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + current_buffer = malloc(0x100); +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + // +\end_deeper +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +serial.h +\series default +\size default + - 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 +\begin_inset Quotes eld +\end_inset -\protected_separator +serial.h +\begin_inset Quotes erd +\end_inset -\protected_separator + MUST be included in the file containing the 'main' function. +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +ser.h +\series default +\size default +- Alternate serial routine provided by Wolfgang Esslinger these routines are more compact and faster. + Please see documentation in file SDCCDIR/sdcc51lib/ser.c +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +ser_ir.h +\series default +\size default +- Another alternate set of serial routines provided by Josef Wolf , these routines do not use the external ram. +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +reg51.h +\series default +\size default + - contains register definitions for a standard 8051 +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +reg552.h +\series default +\size default +- contains register definitions for 80C552. +\layout Itemize -\protected_separator -\protected_separator +\series bold +\size large +float.h +\series default +\size default + - contains min, max and other floating point related stuff. +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +Have not had time to do the more involved routines like printf, will get + to them shortly. +\layout Subsection -\protected_separator +Interfacing with Assembly Routines +\layout Subsection -\protected_separator +Global Registers used for Parameter Passing +\layout Standard -\protected_separator +By default the compiler uses the global registers +\begin_inset Quotes eld +\end_inset -\protected_separator +DPL,DPH,B,ACC +\begin_inset Quotes erd +\end_inset -\protected_separator + 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). + +\layout Subsubsection -\protected_separator +Assembler Routine(non-reentrant) +\layout Standard -\protected_separator +In the following example the function +\series bold + cfunc +\series default + calls an assembler routine +\series bold +asm_func +\series default +, which takes two parameters. +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +extern int asm_func( unsigned short, unsigned short); +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +\SpecialChar ~ -\protected_separator +\newline +int c_func (unsigned short i, unsigned short j) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + return asm_func(i,j); +\newline +} +\size default + +\size scriptsize -\protected_separator +\newline +int main() +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return c_func(10,9); +\newline +} +\layout Standard -\protected_separator +The corresponding assembler function is:- +\layout Standard -\protected_separator -\protected_separator -buffer point +\size scriptsize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .globl _asm_func_PARM_2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .globl _asm_func +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .area OSEG +\newline +_asm_func_PARM_2:\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .ds\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 1 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .area CSEG \newline -;; ! -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator +_asm_func: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + a,dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + add\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + a,_asm_func_PARM_2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + dpl,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + dpl,#0x00 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ret +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +The parameter naming convention is +\series bold +__PARM_, +\series default + where n is the parameter number starting from 1, and counting from the + left. + The first parameter is passed in +\begin_inset Quotes eld +\end_inset -\protected_separator +dpl +\begin_inset Quotes erd +\end_inset -\protected_separator + for One bye parameter, +\begin_inset Quotes eld +\end_inset -\protected_separator +dptr +\begin_inset Quotes erd +\end_inset -\protected_separator + if two bytes, +\begin_inset Quotes eld +\end_inset -\protected_separator +b,dptr +\begin_inset Quotes erd +\end_inset -\protected_separator + for three bytes and +\begin_inset Quotes eld +\end_inset -\protected_separator - sdcdbsrc-goto-sdcdb -\protected_separator +acc,b,dptr +\begin_inset Quotes erd +\end_inset -\protected_separator + for four bytes, the +\family typewriter +\series bold +\size footnotesize +varaible name for the second parameter will be __PARM_2. +\layout Standard -\protected_separator +Assemble the assembler routine with the following command. +\layout Standard -\protected_separator +asx8051 -losg asmfunc.asm +\layout Standard -\protected_separator +Then compile and link the assembler routine to the C source file with the + following command, +\layout Standard -\protected_separator +sdcc cfunc.c asmfunc.rel +\layout Subsubsection -\protected_separator +Assembler Routine(reentrant) +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator -\protected_separator -Goto the SDCDB output buffer -\newline -;; p -\protected_separator +\size footnotesize +extern int asm_func( unsigned short, unsigned short); +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +\SpecialChar ~ -\protected_separator +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +int c_func (unsigned short i, unsigned short j) reentrant +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + return asm_func(i,j); +\newline +} +\size default + +\size scriptsize -\protected_separator +\newline +int main() +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return c_func(10,9); +\newline +} +\layout Standard -\protected_separator +The corresponding assembler routine is. +\layout Standard -\protected_separator -\protected_separator +\size scriptsize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .globl _asm_func +\newline +_asm_func: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + push\SpecialChar ~ + _bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + _bp,sp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +mov\SpecialChar ~ + r2,dpl +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + a,_bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + clr\SpecialChar ~ + c +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + add\SpecialChar ~ + a,#0xfd +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + r0,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + add\SpecialChar ~ + a,#0xfc +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + r1,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + a,@r0 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + add\SpecialChar ~ + a,r2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + dpl,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + dph,#0x00 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + sp,_bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + pop\SpecialChar ~ + _bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ret +\layout Standard -\protected_separator +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. +\layout Subsection -\protected_separator +With --noregparms Option +\layout Standard -\protected_separator +When the source is compiled with --noregparms option , space is allocated + for each of the parameters passed to a routine. +\layout Subsubsection -\protected_separator - sdcdb-print-c-sexp -\protected_separator +Assembler Routine Non-reentrant +\layout Standard -\protected_separator +In the following example the function +\series bold + cfunc +\series default + calls an assembler routine +\series bold +asm_func +\series default +, which takes two parameters. +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +extern int asm_func( unsigned short, unsigned short); +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +\SpecialChar ~ -\protected_separator +\newline +int c_func (unsigned short i, unsigned short j) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + return asm_func(i,j); +\newline +} +\size default + +\size scriptsize -\protected_separator +\newline +int main() +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return c_func(10,9); +\newline +} +\layout Standard -\protected_separator +The corresponding assembler function is:- +\layout Standard -\protected_separator -\protected_separator -SDCDB print command for data at +\size scriptsize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .globl _asm_func_PARM_1 \newline -;; -\protected_separator - -\protected_separator +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .globl _asm_func_PARM_2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .globl _asm_func +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .area OSEG +\newline +_asm_func_PARM_1:\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .ds\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 1 +\newline +_asm_func_PARM_2:\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .ds\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + 1 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .area CSEG +\newline +_asm_func: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + a,_asm_func_PARM_1 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + add\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + a,_asm_func_PARM_2 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + dpl,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + dpl,#0x00 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ret +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +The parameter naming convention is +\series bold +__PARM_, +\series default + where n is the parameter number starting from 1, and counting from the + left. + i.e. + the +\family typewriter +\series bold +\size footnotesize +left-most parameter name will be __PARM_1. +\layout Standard -\protected_separator +Assemble the assembler routine with the following command. +\layout Standard -\protected_separator +asx8051 -losg asmfunc.asm +\layout Standard -\protected_separator +Then compile and link the assembler routine to the C source file with the + following command, +\layout Standard -\protected_separator +sdcc cfunc.c asmfunc.rel +\layout Subsubsection -\protected_separator +Assembler Routine(reentrant) +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +extern int asm_func( unsigned short, unsigned short); +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +\SpecialChar ~ -\protected_separator +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +int c_func (unsigned short i, unsigned short j) reentrant +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + return asm_func(i,j); +\newline +} +\size default + +\size scriptsize -\protected_separator +\newline +int main() +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +return c_func(10,9); +\newline +} +\layout Standard -\protected_separator +The corresponding assembler routine is. +\layout Standard -\protected_separator -\protected_separator +\size scriptsize +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + .globl _asm_func +\newline +_asm_func: +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + push\SpecialChar ~ + _bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + _bp,sp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + a,_bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + clr\SpecialChar ~ + c +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + add\SpecialChar ~ + a,#0xfd +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + r0,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + a,_bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + clr\SpecialChar ~ + c +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + add\SpecialChar ~ + a,#0xfc +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + r1,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + a,@r0 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + add\SpecialChar ~ + a,@r1 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + dpl,a +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + dph,#0x00 +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + mov\SpecialChar ~ + sp,_bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + pop\SpecialChar ~ + _bp +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + ret +\layout Standard -\protected_separator +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. +\layout Subsection -\protected_separator +External Stack +\layout Standard -\protected_separator +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). +\layout Standard -\protected_separator +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. +\layout Subsection -\protected_separator +ANSI-Compliance +\layout Standard -\protected_separator +Deviations from the compliancy. +\layout Enumerate -\protected_separator +functions are not always reentrant. +\layout Enumerate -\protected_separator +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. +\begin_deeper +\layout Standard -\protected_separator -\protected_separator +\size small +eg +\end_deeper +\layout Standard -\protected_separator -\protected_separator +\size small +struct s { ... + }; +\newline +struct s s1, s2; +\newline +foo() +\newline +{ +\newline +... + +\newline +s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ +\newline +... + +\newline +} +\layout Standard -\protected_separator -\protected_separator +\size small +struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in + ANSI */ +\newline +{ +\newline +struct s rets; +\newline +... + +\newline +return rets;/* is invalid in SDCC although allowed in ANSI */ +\newline +} +\layout Enumerate -\protected_separator +'long long' (64 bit integers) not supported. +\layout Enumerate -\protected_separator +'double' precision floating point not supported. +\layout Enumerate -\protected_separator +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. + +\layout Enumerate -\protected_separator +No support for +\emph on +setjmp +\emph default + and +\emph on +longjmp +\emph default + (for now). +\layout Enumerate -\protected_separator +Old K&R style function declarations are NOT allowed. +\layout Standard -\protected_separator -\protected_separator - buffer point +\size footnotesize +foo( i,j) /* this old style of function declarations */ +\newline +int i,j; /* are valid in ANSI .. + not valid in SDCC */ +\newline +{ +\newline +... + \newline -;; g -\protected_separator +} +\layout Enumerate -\protected_separator +functions declared as pointers must be dereferenced during the call. +\begin_deeper +\layout Standard -\protected_separator -\protected_separator +\size small +int (*foo)(); +\end_deeper +\layout Standard -\protected_separator -\protected_separator +\size small +\SpecialChar ~ + \SpecialChar ~ +... + +\newline +\SpecialChar ~ + \SpecialChar ~ +/* has to be called like this */ +\newline +\SpecialChar ~ + \SpecialChar ~ +(*foo)();/* ansi standard allows calls to be made like 'foo()' */ +\layout Subsection -\protected_separator +Cyclomatic Complexity +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator -\protected_separator +\size small +complexity = (number of edges in control flow graph) - +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ +(number of nodes in control flow graph) + 2; +\layout Standard -\protected_separator +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. +\layout Section -\protected_separator +TIPS +\layout Standard -\protected_separator - sdcdbsrc-goto-sdcdb -\protected_separator +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. +\layout Itemize -\protected_separator +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'. +\layout Itemize -\protected_separator +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. +\layout Itemize -\protected_separator +NEVER jump into a LOOP. +\layout Itemize -\protected_separator +Declare the variables to be local whenever possible, especially loop control + variables (induction). +\layout Itemize -\protected_separator +Since the compiler does not do implicit integral promotion, the programmer + should do an explicit cast when integral promotion is required. +\layout Itemize -\protected_separator +Reducing the size of division , multiplication & modulus operations can + reduce code size substantially. + Take the following code for example. +\begin_deeper +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +foobar( unsigned int p1, unsigned char ch) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +unsigned char ch1 = p1 % ch ; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +....\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ -\protected_separator -Goto the SDCDB output buffer \newline -;; t -\protected_separator +} +\layout Standard -\protected_separator +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 +\layout Standard -\protected_separator -\protected_separator +\size footnotesize +foobar( unsigned int p1, unsigned char ch) +\newline +{ +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +unsigned char ch1 = (unsigned char)p1 % ch ; +\newline +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +....\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ -\protected_separator +\newline +} +\layout Standard -\protected_separator +It would substantially reduce the code generated (future versions of the + compiler will be smart enough to detect such optimization oppurtunities). +\end_deeper +\layout Standard -\protected_separator -\protected_separator +\series bold +Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk) +\layout Standard -\protected_separator +The 8051 family of micro controller have a minimum of 128 bytes of internal + memory which is structured as follows +\layout Standard -\protected_separator +- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7 + +\layout Standard -\protected_separator +- Bytes 20-2F - 16 bytes to hold 128 bit variables and +\layout Standard -\protected_separator +- Bytes 30-7F - 60 bytes for general purpose use. +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator - sdcdbsrc-mode -\protected_separator +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. + +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +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. + +\layout Standard -\protected_separator +--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. +\layout Standard -\protected_separator +--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. +\layout Standard -\protected_separator +--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. +\layout Standard -\protected_separator +Conclusion. +\layout Standard -\protected_separator +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. +\layout Standard -\protected_separator +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. +\layout Section -\protected_separator +Retargetting for other MCUs. +\layout Standard -\protected_separator +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. +\layout Enumerate -\protected_separator +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. +\layout Enumerate -\protected_separator +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. +\layout Enumerate -\protected_separator +This phase does the bulk of the standard optimizations and is also MCU independe +nt. + This phase can be broken down into several sub-phases. +\begin_deeper +\layout Itemize -\protected_separator -Toggles Sdcdbsrc mode (turns it off) -\newline -;; -\newline -;; C-c C-f -\protected_separator +Break down intermediate code (iCode) into basic blocks. +\layout Itemize -\protected_separator +Do control flow & data flow analysis on the basic blocks. +\layout Itemize -\protected_separator +Do local common subexpression elimination, then global subexpression elimination +\layout Itemize -\protected_separator +dead code elimination +\layout Itemize -\protected_separator +loop optimizations +\layout Itemize -\protected_separator +if loop optimizations caused any changes then do 'global subexpression eliminati +on' and 'dead code elimination' again. +\end_deeper +\layout Enumerate -\protected_separator +This phase determines the live-ranges; by live range I mean those iTemp + variables defined by the compiler that still survive after all the optimization +s. + Live range analysis is essential for register allocation, since these computati +on determines which of these iTemps will be assigned to registers, and for + how long. +\layout Enumerate -\protected_separator - sdcdb-finish-from-src -\protected_separator +Phase five is register allocation. + There are two parts to this process . +\begin_deeper +\layout Enumerate -\protected_separator +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. +\layout Enumerate -\protected_separator +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. +\end_deeper +\layout Enumerate -\protected_separator +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. +\layout Enumerate -\protected_separator +As mentioned in the optimization section the peep-hole optimizer is rule + based system, which can reprogrammed for other MCUs. +\layout Section -\protected_separator +SDCDB - Source Level Debugger +\layout Standard -\protected_separator +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 is part of the standard compiler installati +on, which 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. +\layout Subsection -\protected_separator -SDCDB finish command -\newline -;; -\newline -;; C-x SPC -\protected_separator +Compiling for Debugging +\layout Standard -\protected_separator +The +\emph on +--debug +\emph default + option must be specified for all files for which debug information is to + be generated. + The complier generates a +\emph on +.cdb +\emph default + file for each of these files. + The linker updates the +\emph on +.cdb +\emph default + file with the address information. + This .cdb is used by the debugger . +\layout Subsection -\protected_separator +How the Debugger Works +\layout Standard -\protected_separator +When the +\emph on +--debug +\emph default + 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 . +\layout Subsection -\protected_separator +Starting the Debugger +\layout Standard -\protected_separator +The debugger can be started using the following command line. + (Assume the file you are debugging has +\layout Standard -\protected_separator +the file name foo). +\layout Standard -\protected_separator - sdcdb-break -\protected_separator +>sdcdb foo +\layout Standard -\protected_separator +The debugger will look for the following files. +\layout Enumerate -\protected_separator +foo.c - the source file. +\layout Enumerate -\protected_separator +foo.cdb - the debugger symbol information file. +\layout Enumerate -\protected_separator +foo.ihx - the intel hex format object file. +\layout Subsection -\protected_separator +Command Line Options. +\layout Itemize -\protected_separator +--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. + +\layout Itemize -\protected_separator +-cd - change to the . +\layout Itemize -\protected_separator +-fullname - used by GUI front ends. +\layout Itemize -\protected_separator +-cpu - this argument is passed to the simulator please see the + simulator docs for details. +\layout Itemize -\protected_separator +-X this options is passed to the simulator please see + simulator docs for details. +\layout Itemize -\protected_separator +-s passed to simulator see simulator docs for details. +\layout Itemize -\protected_separator +-S passed to simulator see simulator docs for details. +\layout Subsection -\protected_separator +Debugger Commands. +\layout Standard -\protected_separator +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 integratio +n with existing graphical user interfaces (like ddd, xxgdb or xemacs) existing + for the GNU debugger. +\layout Subsubsection -\protected_separator +break [line | file:line | function | file:function] +\layout Standard -\protected_separator +Set breakpoint at specified line or function. +\layout Standard -\protected_separator -Set break for line with point +sdcdb>break 100 +\newline +sdcdb>break foo.c:100 \newline -;; ESC t -\protected_separator +sdcdb>break funcfoo +\newline +sdcdb>break foo.c:funcfoo +\layout Subsubsection -\protected_separator +clear [line | file:line | function | file:function ] +\layout Standard -\protected_separator +Clear breakpoint at specified line or function. +\layout Standard -\protected_separator +sdcdb>clear 100 +\newline +sdcdb>clear foo.c:100 +\newline +sdcdb>clear funcfoo +\newline +sdcdb>clear foo.c:funcfoo +\layout Subsubsection -\protected_separator +continue +\layout Standard -\protected_separator +Continue program being debugged, after breakpoint. +\layout Subsubsection -\protected_separator +finish +\layout Standard -\protected_separator +Execute till the end of the current function. +\layout Subsubsection -\protected_separator +delete [n] +\layout Standard -\protected_separator - sdcdbsrc-mode -\protected_separator +Delete breakpoint number 'n'. + If used without any option clear ALL user defined break points. +\layout Subsubsection -\protected_separator +info [break | stack | frame | registers ] +\layout Itemize -\protected_separator +info break - list all breakpoints +\layout Itemize -\protected_separator +info stack - show the function call stack. +\layout Itemize -\protected_separator +info frame - show information about the current execution frame. +\layout Itemize -\protected_separator +info registers - show content of all registers. +\layout Subsubsection -\protected_separator +step +\layout Standard -\protected_separator +Step program until it reaches a different source line. +\layout Subsubsection -\protected_separator +next +\layout Standard -\protected_separator +Step program, proceeding through subroutine calls. +\layout Subsubsection -\protected_separator +run +\layout Standard -\protected_separator +Start debugged program. +\layout Subsubsection -\protected_separator +ptype variable +\layout Standard -\protected_separator +Print type information of the variable. +\layout Subsubsection -\protected_separator +print variable +\layout Standard -\protected_separator -Toggle Sdcdbsrc mode -\newline -;; ESC m -\protected_separator +print value of variable. +\layout Subsubsection -\protected_separator +file filename +\layout Standard -\protected_separator +load the given file name. + Note this is an alternate method of loading file for debugging. +\layout Subsubsection -\protected_separator +frame +\layout Standard -\protected_separator +print information about current frame. +\layout Subsubsection -\protected_separator +set srcmode +\layout Standard -\protected_separator +Toggle between C source & assembly source. +\layout Subsubsection -\protected_separator +! simulator command +\layout Standard -\protected_separator +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. +\layout Subsubsection -\protected_separator - sdcdbsrc-srcmode -\protected_separator +quit. +\layout Standard -\protected_separator +"Watch me now. + Iam going Down. + My name is Bobby Brown" +\layout Subsection -\protected_separator +Interfacing with XEmacs. +\layout Standard -\protected_separator +Two files are (in emacs lisp) are provided for the interfacing with XEmacs, +\emph on + sdcdb.el +\emph default + and +\emph on +sdcdbsrc.el +\emph default +. + These two files can be found in the $(prefix)/bin directory after the installat +ion 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 + +\emph on +'.xemacs' +\emph default + file (which can be found in your HOME directory) +\emph on +(load-file sdcdbsrc.el) +\emph default +[ .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 +\emph on +'EMACSLOADPATH' +\emph default +to the installation bin directory [$(prefix)/bin], then enter the following + command +\emph on +ESC-x load-file sdcdbsrc . + +\emph default +To start the interface enter the following command +\emph on +ESC-x sdcdbsrc +\emph default + , you will prompted to enter the file name to be debugged. + +\layout Standard -\protected_separator +The command line options that are passed to the simulator directly are bound + to default values in the file +\emph on +sdcdbsrc.el +\emph default +the variables are listed below these values maybe changed as required. +\layout Itemize -\protected_separator +sdcdbsrc-cpu-type '51 +\layout Itemize -\protected_separator +sdcdbsrc-frequency '11059200 +\layout Itemize -\protected_separator +sdcdbsrc-serial nil +\layout Standard -\protected_separator +The following is a list of key mapping for the debugger interface. +\layout Standard -\protected_separator +\SpecialChar ~ -\protected_separator +\size scriptsize -\protected_separator +\newline +;; Current Listing :: +\newline +;;key\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +binding\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Comment +\newline +;;---\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +-------\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +------- +\newline +;; +\newline +;; n\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdb-next-from-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB next command +\newline +;; b\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdb-back-from-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB back command +\newline +;; c\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdb-cont-from-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB continue command +\newline +;; s\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdb-step-from-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB step command +\newline +;; ?\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdb-whatis-c-sexp\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB ptypecommand for data at +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + buffer point +\newline +;; x\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdbsrc-delete\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB Delete all breakpoints if no arg +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +given or delete arg (C-u arg x) +\newline +;; m\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdbsrc-frame\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB Display current frame if no arg, +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +given or display frame arg +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +buffer point +\newline +;; !\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdbsrc-goto-sdcdb\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Goto the SDCDB output buffer +\newline +;; p\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdb-print-c-sexp\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB print command for data at +\newline +;;\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + buffer point +\newline +;; g\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdbsrc-goto-sdcdb\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Goto the SDCDB output buffer +\newline +;; t\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdbsrc-mode\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Toggles Sdcdbsrc mode (turns it off) +\newline +;; +\newline +;; C-c C-f\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdb-finish-from-src\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +SDCDB finish command +\newline +;; +\newline +;; C-x SPC\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdb-break\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Set break for line with point +\newline +;; ESC t\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdbsrc-mode\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +Toggle Sdcdbsrc mode +\newline +;; ESC m\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ + sdcdbsrc-srcmode\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ +\SpecialChar ~ Toggle list mode \newline ;; @@ -11758,82 +8511,100 @@ Toggle Sdcdbsrc mode \layout Section -Conclusion -\begin_inset LatexCommand \label{Conclusion} - -\end_inset - +Other Processors +\layout Subsection +The Z80 and gbz80 port \layout Standard -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. - +SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80. + The port is incomplete - long support is incomplete (mul, div and mod are + unimplimented), and both float and bitfield support is missing, but apart + from that the code generated is correct. \layout Standard -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). +As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c. + The stack frame is similar to that generated by the IAR Z80 compiler. + IX is used as the base pointer, HL is used as a temporary register, and + BC and DE are available for holding varibles. + IY is currently unusued. + Return values are stored in HL. + One bad side effect of using IX as the base pointer is that a functions + stack frame is limited to 127 bytes - this will be fixed in a later version. \layout Section -Acknowledgments -\begin_inset LatexCommand \label{Acknowledgements} +Support +\layout Standard -\end_inset +SDCC has grown to be large project, the compiler alone (without the Assembler + Package, Preprocessor) is about 40,000 lines of code (blank stripped). + The open source nature of this project is a key to its continued growth + and support. + You gain the benefit and support of many active software developers and + end users. + Is SDCC perfect? No, that's why we need your help. + The developers take pride in fixing reported bugs. + You can help by reporting the bugs and helping other SDCC users. + There are lots of ways to contribute, and we encourage you to take part + in making SDCC a great software package. +\layout Subsection +Reporting Bugs +\layout Standard + +Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd +cc@sdcc.sourceforge.net'. + Bugs will be fixed ASAP. + When reporting a bug, it is very useful to include a small test program + which reproduces the problem. + If you can isolate the problem by looking at the generated assembly code, + this can be very helpful. + Compiling your program with the --dumpall option can sometimes be useful + in locating optimization problems. +\layout Subsection +Acknowledgments \layout Standard +Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code generator, + Debugger, AVR port +\newline Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX & ASLINK. -\layout Standard - +\newline John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for 8051 -\layout Standard - +\newline Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines. -\layout Standard - +\newline Daniel Drotos - for his Freeware simulator -\layout Standard - -Jans J Boehm(boehm@sgi.com) and Alan J Demers - Conservative garbage collector - for C & C++. -\layout Standard - +\newline Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience and support. -\layout Standard - +\newline Unknown - for the GNU C - preprocessor. -\layout Section - -Appendix A: The Z80 and gbz80 port -\layout Standard +\newline +Michael Hope - The Z80 and Z80GB port, 186 development +\newline +Kevin Vigor - The DS390 port. +\newline +Johan Knol - DS390/TINI libs, lots of fixes and enhancements. +\newline +Scott Datallo - PIC port. +\newline +(Thanks to all the other volunteer developers who have helped with coding, + testing, web-page creation, distribution sets, etc. + You know who you are :-) +\newline -2.2.0 can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80. - The port is incomplete - long support is incomplete (mul, div and mod are - unimplimented), and both float and bitfield support is missing, but apart - from that the code generated is correct. \layout Standard -As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c. - The stack frame is similar to that generated by the IAR Z80 compiler. - IX is used as the base pointer, HL is used as a temporary register, and - BC and DE are available for holding varibles. - IY is currently unusued. - Return values are stored in HL. - One bad side effect of using IX as the base pointer is that a functions - stack frame is limited to 127 bytes - this will be fixed in a later version.bc +This document initially written by Sandeep Dutta \layout Standard -9 +All product names mentioned herein may be trademarks of their respective + companies. + \layout Standard diff --git a/doc/SDCCUdoc.txt b/doc/SDCCUdoc.txt index 838102c0..e06e9c2c 100644 --- a/doc/SDCCUdoc.txt +++ b/doc/SDCCUdoc.txt @@ -2,806 +2,1555 @@ SDCC Compiler User Guide -Sandeep Dutta (sandeep.dutta@usa.net) +Table of Contents 1 Introduction + 1.1 About SDCC + 1.2 Open Source + 1.3 System Requirements + 1.4 Other Resources +2 Installation + 2.1 Linux/Unix Installation + 2.2 Windows Installation + 2.2.1 Windows Install Using a Binary Package + 2.2.2 Windows Install Using Cygwin + 2.3 Testing out the SDCC Compiler + 2.4 Install Trouble-shooting + 2.4.1 SDCC cannot find libraries or header files. + 2.4.2 SDCC does not compile correctly. + 2.4.3 What the ./configure does + 2.4.4 What the make does. + 2.4.5 What the make install command does. + 2.5 Additional Information for Windows Users + 2.5.1 Getting started with Cygwin + 2.5.2 Running SDCC as Native Compiled Executables + 2.6 SDCC on Other Platforms + 2.7 Advanced Install Options + 2.8 Components of SDCC + 2.8.1 cpp ( C-Preprocessor) + 2.8.2 asxxxx & aslink ( The assembler and Linkage Editor) + 2.8.3 SDCC - The compiler + 2.8.4 S51 - Simulator + 2.8.5 SDCDB - Source Level Debugger +3 Using SDCC + 3.1 Compiling + 3.1.1 Single Source File Projects + 3.1.2 Projects with Multiple Source Files + 3.1.3 Projects with Additional Libraries + 3.2 Command Line Options + 3.2.1 Processor Selection Options + 3.2.2 Path, Lib and Define Options + 3.2.3 MCS51 Options + 3.2.4 Optimization Options + 3.2.5 DS390 Options + 3.2.6 Other Options + 3.2.7 Intermediate Dump Options + 3.3 MCS51 Storage Class Language Extensions + 3.3.1 xdata + 3.3.2 data + 3.3.3 idata + 3.3.4 bit + 3.3.5 sfr / sbit + 3.4 Pointers + 3.5 Parameters & Local Variables + 3.6 Overlaying + 3.7 Critical Functions + 3.8 Absolute Addressing + 3.9 Interrupt Service Routines + 3.10 Startup Code + 3.11 Inline Assembler Code + 3.12 int(16 bit) and long (32 bit ) Support + 3.13 Floating Point Support + 3.14 MCS51 Memory Models + 3.15 Flat 24 bit Addressing Model + 3.16 Defines Created by the Compiler +4 SDCC Technical Data + 4.1 Optimizations + 4.1.1 Sub-expression Elimination + 4.1.2 Dead-Code Elimination + 4.1.3 Copy-Propagation + 4.1.4 Loop Optimizations + 4.1.5 Loop Reversing: + 4.1.6 Algebraic Simplifications + 4.1.7 'switch' Statements + 4.1.8 Bit-shifting Operations. + 4.1.9 Bit-rotation + 4.1.10 Highest Order Bit + 4.1.11 Peep-hole Optimizer + 4.2 Pragmas + 4.3 Library Routines + 4.4 Interfacing with Assembly Routines + 4.5 Global Registers used for Parameter Passing + 4.5.1 Assembler Routine(non-reentrant) + 4.5.2 Assembler Routine(reentrant) + 4.6 With --noregparms Option + 4.6.1 Assembler Routine Non-reentrant + 4.6.2 Assembler Routine(reentrant) + 4.7 External Stack + 4.8 ANSI-Compliance + 4.9 Cyclomatic Complexity +5 TIPS +6 Retargetting for other MCUs. +7 SDCDB - Source Level Debugger + 7.1 Compiling for Debugging + 7.2 How the Debugger Works + 7.3 Starting the Debugger + 7.4 Command Line Options. + 7.5 Debugger Commands. + 7.5.1 break [line | file:line | function | file:function] + 7.5.2 clear [line | file:line | function | file:function ] + 7.5.3 continue + 7.5.4 finish + 7.5.5 delete [n] + 7.5.6 info [break | stack | frame | registers ] + 7.5.7 step + 7.5.8 next + 7.5.9 run + 7.5.10 ptype variable + 7.5.11 print variable + 7.5.12 file filename + 7.5.13 frame + 7.5.14 set srcmode + 7.5.15 ! simulator command + 7.5.16 quit. + 7.6 Interfacing with XEmacs. +8 Other Processors + 8.1 The Z80 and gbz80 port +9 Support + 9.1 Reporting Bugs + 9.2 Acknowledgments -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) +1 Introduction -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. +1.1 About SDCC + +SDCC is a Free ware, 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 80C390 MCS51 +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 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 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 ucSim a freeware +simulator for 8051 and other micro-controllers. The latest +version can be downloaded from [http://sdcc.sourceforge.net/]. + +1.2 Open Source + +All packages used in this compiler system are opensource(freeware); +source code for all the sub-packages (asxxxx assembler/linker, +pre-processor) are 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! -2.1.2 cpp ( C-Preprocessor) +1.3 System Requirements -The preprocessor is extracted into the directory SDCCDIR/cpp, it is -a modified version of the GNU preprocessor. +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. + +1.4 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 www.sourceforge.net. + +2 Installation + +2.1 Linux/Unix Installation + +1. Download the source package, it will be named something + like sdcc-2.x.x.tgz. + +2. Bring up a command line terminal, such as xterm. + +3. 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. + +4. Change directory into the main SDCC directory, for example + type: "cd sdcc". + +5. Type "./configure". This configures + the package for compilation on your system. + +6. Type "make". All of the source packages + will compile, this can take a while. + +7. Type "make install" as root. + This copies the binary executables to the install directories. + +2.2 Windows Installation + +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. + +2.2.1 Windows Install Using a Binary Package + +1. 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. + +2. 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% + +3. 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 + +2.2.2 Windows Install Using Cygwin + +1. 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). + +2. Bring up a Unix/Bash command line terminal from the Cygwin + menu. + +3. Follow the instructions in the preceding Linux/Unix installation + section. + +2.3 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 | ++--------------------------------+-------------------------------------------+ + + +Make sure the compiler works on a very simple example. Type +in the following test.c program using your favorite editor: -2.1.3 asxxxx & aslink ( The assembler and Linkage Editor) +main() +{ int i; +i = 0; +i += 10; +} -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. +Compile this using the following command: "sdcc +-c test.c". If all goes well, the compiler will +generate a test.asm and test.rel file. Congratulations, +you've just compiled your first program with SDCC. We used +the -c option to tell SDCC not to link the generated code, +just to keep things simple for this step. + +The next step is to try it with the linker. Type in "sdcc +test.c". If all goes well the compiler will link with +the libraries and produce a test.ihx output file. If this +step fails(no test.ihx, and the linker generates warnings), +then the problem is most likely that sdcc cannot find the +usr/local/share/sdcc/lib/small directory(see the Install +trouble-shooting section for suggestions). + +The final test is to ensure sdcc can use the standard header +files and libraries. Edit test.c and change it to the following: + +#include +main() +{ char str1[10]; +strcpy(str1, "testing"); +} -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. +Compile this by typing: "sdcc test.c". +This should generate a test.ihx output file, and it should +give no warnings such as not finding the string.h file. +If it cannot find the string.h file, then the problem is +that sdcc cannot find the /usr/local/share/sdcc/include +directory(see the Install trouble-shooting section for suggestions). + +2.4 Install Trouble-shooting + +2.4.1 SDCC cannot find libraries or header files. + +The default installation assumes the libraries and header +files are located at "/usr/local/share/sdcc/lib" +and "/usr/local/share/sdcc/include". +An alternative is to specify these locations as compiler +options like this: sdcc -L /usr/local/sdcc/lib/small -I +/usr/local/sdcc/include test.c + +2.4.2 SDCC does not compile correctly. + +A few things to try include starting from scratch by unpacking +the .tgz source package again in an empty directory. If +this doesn't work, you could try downloading a different +version. If this doesn't work, you can re-direct the install +messages by doing the following: + +$./make > dump.txt 2>&1 + +After this you can examine the dump.txt files to locate the +problem. Or these messages can be attached to an email that +could be helpful when requesting help from the mailing list. + +2.4.3 What the "./configure" + does + +The "./configure" command is a script +that analyzes your system and performs some configuration +to ensure the source package compiles on your system. It +will take a few minutes to run, and will compile a few tests +to determine what compiler features are installed. + +2.4.4 What the "make" does. + +This runs the GNU make tool, which automatically compiles +all the source packages into the final installed binary +executables. + +2.4.5 What the "make install" + command does. + +This will install the compiler, other executables and libraries +in to the appropriate system directories. The default is +to copy the executables to /usr/local/bin and the libraries +and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include. + +2.5 Additional Information for Windows Users + +The standard method of installing on a Unix system involves +compiling the source package. This is easily done under +Unix, but under Windows it can be a more difficult process. +The Cygwin is a large package to download, and the compilation +runs considerably slower under Windows due to the overhead +of the Cygwin tool set. An alternative is to install a pre-compiled +Windows binary package. There are various trade-offs between +each of these methods. + +The Cygwin package allows a Windows user to run a Unix command +line interface(bash shell) and also implements a Unix like +file system on top of Windows. Included are many of the +famous GNU software development tools which can augment +the SDCC compiler.This is great if you have some experience +with Unix command line tools and file system conventions, +if not you may find it easier to start by installing a binary +Windows package. The binary packages work with the Windows +file system conventions. + +2.5.1 Getting started with Cygwin + +SDCC is typically distributed as a tarred/gzipped file(.tgz). +This is a packed file similar to a .zip file. Cygwin includes +the tools you will need to unpack the SDCC distribution(tar +and gzip). To unpack it, simply follow the instructions +under the Linux/Unix install section. Before you do this +you need to learn how to start a cygwin shell and some of +the basic commands used to move files, change directory, +run commands and so on. The change directory command is +"cd", the move command is "mv". +To print the current working directory, type "pwd". +To make a directory, use "mkdir". + +There are some basic differences between Unix and Windows +file systems you should understand. When you type in directory +paths, Unix and the Cygwin bash prompt uses forward slashes +'/' between directories while Windows traditionally uses +'\' backward slashes. So when you work at the Cygwin bash +prompt, you will need to use the forward '/' slashes. Unix +does not have a concept of drive letters, such as "c:", +instead all files systems attach and appear as directories. + +2.5.2 Running SDCC as Native Compiled Executables + +If you use the pre-compiled binaries, the install directories +for the libraries and header files may need to be specified +on the sdcc command line like this: sdcc -L c:\usr\local\sdcc\lib\small +-I c:\usr\local\sdcc\include test.c if you are running outside +of a Unix bash shell. + +If you have successfully installed and compiled SDCC with +the Cygwin package, it is possible to compile into native +.exe files by using the additional makefiles included for +this purpose. For example, with the Borland 32-bit compiler +you would run make -f Makefile.bcc. A command line version +of the Borland 32-bit compiler can be downloaded from the +Inprise web site. + +2.6 SDCC on Other Platforms + +* FreeBSD and other non-GNU Unixes - Make sure the GNU make + is installed as the default make tool. + +* SDCC has been ported to run under a variety of operating + systems and processors. If you can run GNU GCC/make then + chances are good SDCC can be compiled and run on your + system. + +2.7 Advanced Install Options + +The "configure" command has several options. +The most commonly used option is --prefix=, +where 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 specified. + +bin/ - binary exectables (add to PATH environment variable) + + share/ + sdcc/include/ - include +header files + sdcc/lib/ - + small/ +- Object & library files for small model library + large/ +- Object & library files for large model library + ds390/ +- Object & library files forDS80C390 library -2.1.5 S51 - Simulator +The command -Version 2.1.8 onwards contains s51 a freeware , opensource simulator -developed by Daniel Drotos . The -executable is built as part of build process, for more information -visit Daniel's website at . +'./configure --prefix=/usr/local" -2.1.6 SDCDB - Source level Debugger. +will configure the compiler to be installed in directory +/usr/local/bin. -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.8 Components of SDCC -2.2 Installation for Version <= 2.1.7 +SDCC is not just a compiler, but a collection of tools by +various developers. These include linkers, assemblers, simulators +and other components. Here is a summary of some of the components. +Note that the included simulator and assembler have separate +documentation which you can find in the source package in +their respective directories. As SDCC grows to include support +for other processors, other packages from various developers +are included and may have their own sets of documentation. -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. +You might want to look at the various executables which are +installed in the bin directory. At the time of this writing, +we find the following programs: -./sdccbuild.sh +sdcc - The compiler. -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. +aslink -The linker for 8051 type processors. -2.3 Installation for Version >= 2.1.8a +asx8051 - The assembler for 8051 type processors. -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-.tar.gz format , instead of the older .zip -format. The steps for installation are as follows. +sdcpp - The C preprocessor. -2.3.1 Unpack the sources. +sdcpd - The source debugger. -This is usually done by the following command ``gunzip -c sdcc-.tar.gz | tar -xv -`` +s51 - The ucSim 8051 simulator. -2.3.2 Change to the main source directory (usually sdcc or sdcc-) +linkz80, linkgbz80 - The Z80 and GameBoy Z80 linkers. -2.3.3 Issue command to configure your system +as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers. -The configure command has several options the most commonly used option -is --prefix=, where 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 specified. +packihx - A tool to pack Intel hex files. -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 +As development for other processors proceeds, this list will +expand to include executables to support processors like +AVR, PIC, etc. -The command +2.8.1 cpp ( C-Preprocessor) -'./configure --prefix=/usr/local'' +The preprocessor is extracted into the directory SDCCDIR/cpp, +it is a modified version of the GNU preprocessor. The C +preprocessor is used to pull in #include sources, process +#ifdef statements, #defines and so on. -will create configure the compiler to be installed in directory /usr/local/bin. +2.8.2 asxxxx & aslink ( The assembler and Linkage Editor) -2.3.4 make +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. -After configuration step issue the command +2.8.3 SDCC - The compiler -``make'' +This is the actual compiler, it in turn uses the c-preprocessor +and invokes the assembler and linkage editors. All files +with the prefix SDCC are part of the compiler and are extracted +into the the directory SDCCDIR. -This will compile the compiler +2.8.4 S51 - Simulator -2.3.5 ``make install'' +s51 is a freeware, opensource simulator developed by Daniel +Drotos . The executable +is built as part of the build process, for more information +visit Daniel's website at . -Will install the compiler and libraries in the appropriate directories. +2.8.5 SDCDB - Source Level Debugger -2.3.6 Special Notes for Windows Users. Provided by Michael Jamet[ mjamet@computer.org] +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. - +3 Using SDCC - How to install SDCC from source on a Windows 95 or Windows NT 4 system +3.1 Compiling - +3.1.1 Single Source File Projects - This document describes how to install SDCC on a Win 95 or Win NT -4 system. +For single source file 8051 projects the process is very +simple. Compile your programs with the following command - These instructions probably work for Win 98 as well, but have not -been - - tested on that platform. - - +sdcc sourcefile.c - There are lots of little differences between UNIX and the Win32 Cygnus +The above command will compile ,assemble and link your source +file. Output files are as follows. - environment which make porting more difficult than it should be. If +* sourcefile.asm - Assembler source file created by the compiler - you want the details, please contact me. Otherwise just follow these +* sourcefile.lst - Assembler listing file created by the + Assembler - instructions. +* sourcefile.rst - Assembler listing file updated with linkedit + information , created by linkage editor - +* sourcefile.sym - symbol listing for the sourcefile, created + by the assembler. - 1. Install the Cygnus Software +* sourcefile.rel - Object file created by the assembler, + input to Linkage editor. - Go to http://sourceware.cygnus.com/cygwin. Cygnus provides a UNIX -like +* sourcefile.map - The memory map for the load module, created + by the Linker. - environment for Win 32 systems. Download "full.exe" and install. You +* sourcefile. - The load module : ihx - Intel + hex format (default ), s19 - Motorola S19 format when + compiler option --out-fmt-s19 is used. - MUST install it on your C drive. "full.exe" contains a shell AND many +3.1.2 Projects with Multiple Source Files - common UNIX utilities. +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 ) - 2. Download and Extract the Latest SDCC +foo2.c (contains some more functions) - The latest version can be found at +foomain.c (contains more functions and the function main) - www.geocities.com/ResearchTriange/Forum/1353. +The first two files will need to be compiled separately with +the commands - It can be uncompressed with winzip. +sdcc -c foo1.c - +sdcc -c foo2.c - 3. Start a Cygnus Shell +Then compile the source file containing main and link the +other files together with the following command. - There should be an entry in the Start Menu for Cygnus. Invoke the -shell. +sdcc foomain.c foo1.rel foo2.rel - This gives you a UNIX like environment. FROM THIS POINT ON, DIRECTORIES +Alternatively foomain.c can be separately compiled as well - MUST BE SPECIFIED WITH FORWARD SLASHES (/) NOT THE DOS STYLE BACK +sdcc -c foomain.c - SLASHES (\) BECAUSE THIS IS WHAT UNIX EXPECTS. - +sdcc foomain.rel foo1.rel foo2.rel - ex. "\winnt" would be "/winnt" under the shell. +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.1.3 Projects with Additional Libraries - 4. Change Directory to Where SDCC was extracted (referred to as INSTALLDIR) +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 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 - ex. cd /sdcc218Da. If you extracted to a drive OTHER THAN C, the drive +Note here that 'mylib' must be an absolute path name. - must be specified as part of the path. For example, if you extracted -to +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. - your "g drive", type the following: "cd //g/mydir". You must use "//" +3.2 Command Line Options - to specify the drive. +3.2.1 Processor Selection Options - +-mmcs51 Generate code for the MCS51 (8051) family of processors. +This is the default processor target. - 5. Make Dirs Which are Automatically Made During the UNIX Installation +-mds390 Generate code for the DS80C390 processor. - From the INSTALLDIR, +-mz80 Generate code for the Z80 family of processors. - +-mgbz80 Generate code for the GameBoy Z80 processor. - mkdir -p bin (not a typo, just "bin") +-mavr Generate code for the Atmel AVR processor(In development, +not complete). - mkdir -p /bin +-mpic14 Generate code for the PIC 14-bit processors(In development, +not complete). + +-mtlcs900h Generate code for the Toshiba TLCS-900H processor(In +development, not complete). + +3.2.2 Path, Lib and Define Options + +-I The additional location where the pre processor +will look for <..h> or "..h" +files. + +-D Command line definition of macros. Passed +to the pre processor. + +--lib-path(-L) 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. + +3.2.3 MCS51 Options + +--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 Generate code for Small Model programs see +section Memory Models for more details. This is the default +model. + +--model-flat24 Generate code forDS80C390 24-bit flat mode. +See section Memory Models for more details. + +--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 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. + +3.2.4 Optimization Options + +--nogcse Will not do global subexpression elimination, this +option may be used when the compiler creates undesirably +large stack/data spaces to store compiler temporaries. A +warning message will be generated when this happens and +the compiler will indicate the number of extra bytes it +allocated. It recommended that this option NOT be used , +#pragma NOGCSE can be used to turn off global subexpression +elimination for a given function only. + +--noinvariant Will not do loop invariant optimizations, this +may be turned off for reasons explained for the previous +option . For more details of loop optimizations performed +see section Loop Invariants.It recommended that this option +NOT be used , #pragma NOINVARIANT can be used to turn off +invariant optimizations for a given function only. + +--noinduction Will not do loop induction optimizations, see +section Strength reduction for more details.It recommended +that this option NOT be used , #pragma NOINDUCTION can be +used to turn off induction optimizations for given function +only. + +--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 Will not do loop reversal optimization + +--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. + +3.2.5 DS390 Options + +--stack-auto See MCS51 section for description. + +--stack-10bit This option generates code for the 10 bit stack +mode of the Dallas DS80C390 part. In this mode, the stack +is located in the lower 1K of the internal RAM, which is +mapped to 0x400000. Note that the support is incomplete, +since it still uses a single byte as the stack pointer. +This means that only the lower 256 bytes of the potential +1K stack space can actually be used. However, this does +allow you to reclaim the precious 256 bytes of low RAM for +use for the DATA and IDATA segments. The compiler will not +generate any code to put the processor into 10 bit stack +mode. It is important to ensure that the processor is in +this mode before calling any re-entrant functions compiled +with this option. In principle, this should work with the +--stack-auto option, but that has not been tested. It is +incompatible with the --xstack option. It also only makes +sense if the processor is in 24 bit contiguous addressing +mode (see the --model-flat24 option). + +3.2.6 Other Options + +--callee-saves function1[,function2][,function3].... 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 CALLEE-SAVES. . + +--debug When this option is used the compiler will generate +debug information , that can be used with the SDCDB. The +debug information is collected in a file with .cdb extension. +For more information see documentation for SDCDB. + +--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) will compile and assemble the source +only, will not call the linkage editor. + +--xram-loc 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 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 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 This option will cause the stack to be +located in the internal ram after the data segment. + +--data-loc 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 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 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. + +-E Run only the C preprocessor. Preprocess all the C source +files specified and output the results to standard output. + +-M Tell the preprocessor to output a rule suitable for make +describing the dependencies of each object file. For each +source file, the preprocessor outputs one make-rule whose +target is the object file name for that source file and +whose dependencies are all the files `#include'd in it. +This rule may be a single line or may be continued with +`\'-newline if it is long. The list of rules is printed on +standard output instead of the preprocessed C program. `-M' +implies `-E'. + +-C Tell the preprocessor not to discard comments. Used with +the `-E' option. + +-MM Like `-M' but the output mentions only the user header +files included with `#include file"'. System header files +included with `#include ' are omitted. + +-Aquestion(answer) Assert the answer answer for question, +in case it is tested with a preprocessor conditional such +as `#if #question(answer)'. `-A-' disables the standard +assertions that normally describe the target machine. + +-Aquestion (answer) Assert the answer answer for question, +in case it is tested with a preprocessor conditional such +as `#if #question(answer)'. `-A-' disables the standard +assertions that normally describe the target machine. + +-Umacro Undefine macro macro. `-U' options are evaluated +after all `-D' options, but before any `-include' and `-imacros' +options. + +-dM Tell the preprocessor to output only a list of the macro +definitions that are in effect at the end of preprocessing. +Used with the `-E' option. + +-dD Tell the preprocessor to pass all macro definitions into +the output, in their proper sequence in the rest of the +output. + +-dN Like `-dD' except that the macro arguments and contents +are omitted. Only `#define name' is included in the output. + +-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 Integer (16 bit) and long (32 bit) libraries +have been compiled as reentrant. Note by default these libraries +are compiled as non-reentrant. See section Installation +for more details. + +--cyclomatic This option will cause the compiler to generate +an information message for each function in the source file. +The message contains some important information about the +function. The number of edges and nodes the compiler detected +in the control flow graph of the function, and most importantly +the cyclomatic complexity see section on Cyclomatic Complexity +for more details. + +--float-reent Floating point library is compiled as reentrant.See +section Installation for more details. + +--out-fmt-ihx The linker output (final object code) is in +Intel Hex format. (This is the default option). + +--out-fmt-s19 The linker output (final object code) is in +Motorola S19 format. + +--nooverlay The compiler will not overlay parameters and +local variables of any function, see section Parameters +and local variables for more details. - mkdir -p /usr/local/bin +--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 .' . - mkdir -p /usr/local/share +--no-peep Disable peep-hole optimization. - mkdir -p /usr/local/share/sdcc51lib +--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. - mkdir -p /usr/local/share/sdcc51inc +--iram-size Causes the linker to check if the interal +ram usage is within limits of the given value. - mkdir -p /tmp +3.2.7 Intermediate Dump Options - +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. - (When a path from the root directory is specified WITHOUT a drive, -the +--dumpraw . This option will cause the compiler to dump the +intermediate code into a file of named .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. - drive defaults to c. For example /michael/newuser => c:\michael\newuser) +--dumpgcse. Will create a dump if iCode, after global subexpression +elimination, into a file named .dumpgcse. - +--dumpdeadcode .Will create a dump if iCode, after deadcode +elimination, into a file named .dumpdeadcode. - 6. Add Programs to /bin Expected by the Installation Process +--dumploop. Will create a dump if iCode, after loop optimizations, +into a file named .dumploop. - - Look at your path: echo $PATH +--dumprange. Will create a dump if iCode, after live range +analysis, into a file named .dumprange. - One of the fields is the diretory with the CYGNUS programs. +--dumpregassign. Will create a dump if iCode, after register +assignment , into a file named .dumprassgn. - ex. /CYGNUS/CYGWIN~1/H-I586/BIN +--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. - - cd to the directory found above. You may have to fiddle with the +When reporting bugs, it can be helpful to include these dumps +along with the portion of the code that is causing the problem. - case (upper or lower) here because the PATH is SHOWN as all upper +3.3 MCS51 Storage Class Language Extensions - case, but is actually mixed. To help you along, you may type +In addition to the ANSI storage classes SDCC allows the following +MCS51 specific storage classes. - a letter or 2 followed by the escape key. The shell will fill +3.3.1 xdata - out the remaining letters IF THEY describe a unique directory. +Variables declared with this storage class will be placed +in the extern RAM. This is the default storage class for +Large Memory model . - If you have problems here, cd one directory and type "ls". "ls" +eg. xdata unsigned char xduc; - is the equivalent of "dir/w". +3.3.2 data - +This is the default storage class for Small Memory model. +Variables declared with this storage class will be allocated +in the internal RAM. - - Copy the following: +eg. data int iramdata; - cp sh.exe /bin +3.3.3 idata - cp pwd.exe /bin +Variables declared with this storage class will be allocated +into the indirectly addressable portion of the internal +ram of a 8051 . - cp echo.exe /bin +eg.idata int idi; - +3.3.4 bit - 7. Go back to the INSTALLDIR +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. - cd INSTALLDIR +eg.bit iFlag; - ex. cd //d/sdcc218Da +3.3.5 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. - 8. Run the configure Program +eg. - ./configure +sfr at 0x80 P0; /* special function register P0 at location +0x80 */ - The "./" is important because your current directory is NOT in your -path. +sbit at 0xd7 CY; /* CY (Carry Flag) */ - Under DOS, your current directory was implicitly always the first -entry +3.4 Pointers - in your path. +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. - 9. Run make +/* pointer physically in xternal ram pointing to object in +internal ram */ +data unsigned char * xdata p; - make - +/* pointer physically in code rom pointing to data in xdata +space */ +xdata unsigned char * code p; - This process takes quite some time under Win 32. - +/* pointer physically in code space pointing to data in code +space */ +code unsigned char * code p; - 10. Install the Newly Built Software +/* the folowing is a generic pointer physically located in +xdata space */ +char * xdata p; - make install +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 */ - This will partially install the software into the /usr/local directories +All unqualified pointers are treated as 3 - byte '_generic' +pointers. These type of pointers can also to be explicitly +declared. - created in step 5. What it actually doing is copying the .c, .h and +unsigned char _generic *ucgp; - library files to directories under /usr/local/share. +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. - +3.5 Parameters & Local Variables - It will NOT be able to install the actual programs (binaries) because +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. - it does not know programs on Win32 systems have ".exe" extensions. +eg - For example, it tries to install sdcc instead of sdcc.exe. +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. - After the automated part is finished, you must manually copy the binaries: +When compiled with the default option (i.e. non-reentrant +), local variables can be assigned storage classes and absolute +addresses. - cd bin (This is the bin directory in your INSTALLDIR) +eg - cp * /usr/local/bin +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. + +3.6 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. - 11. Make sure /usr/local/bin is in Your PATH +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. - You may add c:\usr\local\bin to your path however your Win32 system allows. -For +eg. - example you may add it to the PATH statement in autoexec.bat. +#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. - Good luck. If you have any questions send them to me or post them +3.7 Critical Functions - to the list. +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. -3 Compiling.\label{Compiling} +eg -3.1 Single Source file projects.\label{One Source File} +int foo () critical +{ +... +... +} -For single source file projects the process is very simple. Compile -your programs with the following command +The critical attribute maybe used with other attributes like +reentrant. -sdcc sourcefile.c +3.8 Absolute Addressing -The above command will compile ,assemble and link your source file. -Output files are as follows. +Data items can be assigned an absolute address with the at +
        keyword, in addition to a storage class. -* sourcefile.asm - Assembler source file created by the compiler +eg. -* sourcefile.lst - Assembler listing file created by the Assembler +xdata at 0x8000 unsigned char PORTA_8255 ; -* sourcefile.rst - Assembler listing file updated with linkedit information - , created by linkage editor +In the above example the PORTA_8255 will be allocated to +the location 0x8000 of the external ram. -* sourcefile.sym - symbol listing for the sourcefile, created by the - assembler. +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 (.rst) +and (.map) are a good places to look for such +overlaps. -* sourcefile.rel - Object file created by the assembler, input to Linkage - editor. +Absolute address can be specified for variables in all storage +classes. -* sourcefile.map - The memory map for the load module, created by the - Linker. +eg. -* sourcefile. - The load module : ihx - Intel hex format - (default ), s19 - Motorola S19 format when compiler option --out-fmt-s19 - is used. +bit at 0x02 bvar; -3.2 Projects with multiple source files. +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. -SDCC can compile only ONE file at a time. Let us for example assume -that you have a project containing the following files. +3.9 Interrupt Service Routines -foo1.c ( contains some functions ) +SDCC allows interrupt service routines to be coded in C, +with some extended keywords. -foo2.c (contains some more functions) +void timer_isr (void) interrupt 2 using 1 +{ +.. +} -foomain.c (contains more functions and the function main) +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. -The first two files will need to be compiled separately with the commands +Calling other functions from an interrupt service routine +is not recommended avoid it if possible. -sdcc -c foo1.c +3.10 Startup Code -sdcc -c foo2.c +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. You could add a _sdcc__external__startup() +routine to your program to override the default if you needed +to setup hardware or perform some other critical operation +prior to static & global variable initialization. + +3.11 Inline Assembler Code + +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. -Then compile the source file containing main and link the other files -together with the following command. +eg -sdcc foomain.c foo1.rel foo2.rel +_asm + mov b,#10 +00001$: + djnz b,00001$ +_endasm ; -Alternatively foomain.c can be separately compiled as well +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. -sdcc -c foomain.c +Inline assembler code cannot reference any C-Labels however +it can reference labels defined by the inline assembler. -sdcc foomain.rel foo1.rel foo2.rel +eg -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. +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 ; +... +} -3.3 Projects with additional libraries. +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. -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 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'. +3.12 int(16 bit) and long (32 bit ) Support -sdcc foomain.c foolib.lib -L mylib +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 -Note here that 'mylib' must be an absolute path name. +* _mulsint.c - signed 16 bit multiplication (calls _muluint) -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} 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} 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} 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} 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} 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} 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} - 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 \label{-I} The additional location where the pre processor - will look for <..h> or ``..h'' files. - -* -D \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 ' 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. +* _muluint.c - unsigned 16 bit multiplication -* --out-fmt-ihx\label{--out-fmt-ihx} The linker output (final object - code) is in Intel Hex format. (This is the default option). +* _divsint.c - signed 16 bit division (calls _divuint) -* --out-fmt-s19 \label{--out-fmt-s19}The linker output (final object - code) is in Motorola S19 format. +* _divuint.c - unsigned 16 bit division. -* --nooverlay \label{--nooverlay} The compiler will not overlay parameters - and local variables of any function, see section Parameters and - local variables for more details. +* _modsint.c - signed 16 bit modulus (call _moduint) -* --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 .' . +* _moduint.c - unsigned 16 bit modulus. -* --no-peep \label{--no-peep} Disable peep-hole optimization. +* _mulslong.c - signed 32 bit multiplication (calls _mululong) -* --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. +* _mululong.c - unsigned32 bit multiplication. -* --iram-size\label{--iram-size} Causes the linker to check - if the interal ram usage is within limits of the given value. +* _divslong.c - signed 32 division (calls _divulong) -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. +* _divulong.c - unsigned 32 division. -* --dumpraw \label{--dumpraw}. This option will cause the compiler - to dump the intermediate code into a file of named .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. +* _modslong.c - signed 32 bit modulus (calls _modulong). -* --dumpgcse.\label{--dumpgcse} Will create a dump if iCode, after - global subexpression elimination, into a file named .dumpgcse. +* _modulong.c - unsigned 32 bit modulus. -* --dumpdeadcode \label{--dumpdeadcode}.Will create a dump if iCode, - after deadcode elimination, into a file named .dumpdeadcode. +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. -* --dumploop. \label{--dumploop}Will create a dump if iCode, after - loop optimizations, into a file named .dumploop. +3.13 Floating Point Support -* --dumprange. \label{--dump-range}Will create a dump if iCode, after - live range analysis, into a file named .dumprange. +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. -* --dumpregassign. \label{--dumpregassign}Will create a dump if iCode, - after register assignment , into a file named .dumprassgn. +* _fsadd.c - add floating point numbers. -* --dumpall. \label{--dumpall}Will cause all the above mentioned dumps - to be created. +* _fssub.c - subtract floating point numbers -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. +* _fsdiv.c - divide floating point numbers -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. +* _fsmul.c - multiply floating point numbers -5 Language Extensions\label{Language Extension} +* _fs2uchar.c - convert floating point to unsigned char -5.1 Storage Classes.\label{Storage Classes} +* _fs2char.c - convert floating point to signed char. -In addition to the ANSI storage classes SDCC allows the following 8051 -specific storage classes. +* _fs2uint.c - convert floating point to unsigned int. -5.1.1 xdata.\label{xdata} +* _fs2int.c - convert floating point to signed int. -Variables declared with this storage class will be placed in the extern -RAM. This is the default storage class for Large Memory model . +* _fs2ulong.c - convert floating point to unsigned long. -eg. xdata unsigned char xduc; +* _fs2long.c - convert floating point to signed long. -5.1.2 data\label{data} +* _uchar2fs.c - convert unsigned char to floating point -This is the default storage class for Small Memory model. Variables -declared with this storage class will be allocated in the internal -RAM. +* _char2fs.c - convert char to floating point number -eg. data int iramdata; +* _uint2fs.c - convert unsigned int to floating point -5.1.3 idata\label{idata} +* _int2fs.c - convert int to floating point numbers -Variables declared with this storage class will be allocated into the -indirectly addressable portion of the internal ram of a 8051 . +* _ulong2fs.c - convert unsigned long to floating point number -eg.idata int idi; +* _long2fs.c - convert long to floating point number. -5.1.4 bit\label{bit} +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) + +3.14 MCS51 Memory Models + +SDCC allows two memory models for MCS51 code, small and large. +Modules compiled with different memory models should never +be combined together or the results would be unpredictable. +The library routines supplied with the compiler are compiled +as both small and large. The compiled library modules are +contained in seperate directories as small and large so +that you can link to either set. 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. Several optimizations +are disabled when the program is compiled using the large +model, it is therefore strongly recommdended that the small +model be used unless absolutely required. + +3.15 Flat 24 bit Addressing Model + +This option generates code for the 24 bit contiguous addressing +mode of the Dallas DS80C390 part. In this mode, up to four +meg of external RAM or code space can be directly addressed. +See the data sheets at www.dalsemi.com for further information +on this part. + +In older versions of the compiler, this option was used with +the MCS51 code generator (-mmcs51). Now, however, the '390 +has it's own code generator, selected by the -mds390 switch. +This code generator currently supports only the flat24 model, +but the --model-flat24 switch is still required, in case +later versions of the code generator support other models +(such as the paged mode of the '390). The combination of +-mmcs51 and --model-flat24 is now depracated. + +Note that the compiler does not generate any code to place +the processor into24 bitmode (it defaults to 8051 compatible +mode). Boot loader or similar code must ensure that the +processor is in 24 bit contiguous addressing mode before +calling the SDCC startup code. + +Like the --model-large option, variables will by default +be placed into the XDATA segment. + +Segments may be placed anywhere in the 4 meg address space +using the usual --*-loc options. Note that if any segments +are located above 64K, the -r flag must be passed to the +linker to generate the proper segment relocations, and the +Intel HEX output format must be used. The -r flag can be +passed to the linker by using the option -Wl-r on the sdcc +command line. + +3.16 Defines Created by the Compiler -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. +The compiler creates the following #defines . -eg.bit iFlag; +* SDCC - this Symbol is always defined. -5.1.5 sfr / sbit\label{sfr / sbit} +* SDCC_STACK_AUTO - this symbol is defined when --stack-auto + option is used. -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. +* SDCC_MODEL_SMALL - when small model is used. -eg. +* SDCC_MODEL_LARGE - when --model-large is used. -sfr at 0x80 P0; /* special function register P0 at location 0x80 */ +* SDCC_USE_XSTACK - when --xstack option is used. -sbit at 0xd7 CY; /* CY (Carry Flag) */ +4 SDCC Technical Data -6 Optimizations\label{Optimizations} +4.1 Optimizations -SDCC performs a a host of standard optimizations in addition to some -MCU specific 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} +4.1.1 Sub-expression Elimination The compiler does local and global common subexpression elimination. @@ -823,23 +1572,25 @@ 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. +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. +The compiler will try to keep these temporary variables in +registers. -6.2 Dead-Code elimination.\label{Dead-code elimination} +4.1.2 Dead-Code Elimination eg. int global; void f () { int i; - i = 1; /* dead store */ + i = 1; /* dead store +*/ global = 1; /* dead store */ global = 2; return; @@ -854,7 +1605,7 @@ int global; void f () return; } -6.3 Copy-Propagation:\label{Copy-Propagation} +4.1.3 Copy-Propagation eg. @@ -874,26 +1625,28 @@ int f() { 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} +Note: the dead stores created by this copy propagation will +be eliminated by dead-code elimination . + +4.1.4 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). + +* Loop Invariant: eg @@ -905,12 +1658,14 @@ 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. +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} +* Strength Reduction : -This optimization substitutes an expression by a cheaper expression. +This optimization substitutes an expression by a cheaper +expression. eg. @@ -926,44 +1681,49 @@ for (i=0;i< 100;i++) { itemp2 += 3; } -The more expensive multiplication is changed to a less expensive addition. +The more expensive multiplication is changed to a less expensive +addition. -6.4.3 Loop reversing:\label{Loop reversing} +4.1.5 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). +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 ( = ; [< | <=] ; [++ - | += 1]) - '' + "for ( = ; [< | <=] + ; [++ | += 1]) + " -* The does not contain ``continue'' or 'break''. +* The does not contain "continue" + or 'break". * All goto's are contained within the loop. * No function calls within the loop. -* The loop control variable is not assigned any value within - the loop +* The loop control variable 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. +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} +4.1.6 Algebraic Simplifications -SDCC does numerous algebraic simplifications, the following is a small -sub-set of these optimizations. +SDCC does numerous algebraic simplifications, the following +is a small sub-set of these optimizations. eg i = j + 0 ; /* changed to */ i = j; @@ -971,37 +1731,52 @@ 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. +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} +4.1.7 'switch' Statements -SDCC changes switch statements to jump tables when the following conditions -are true. +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. +* 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. +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 @@ -1016,7 +1791,8 @@ case 11: ... case 12: ... } -If the above switch statement is broken down into two switch statements +If the above switch statement is broken down into two switch +statements switch (i) { case 1: ... @@ -1032,14 +1808,15 @@ case 11: ... case 12:... } -then both the switch statements will be implemented using jump-tables -whereas the unmodified switch statement will not be . +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} +4.1.8 Bit-shifting Operations. -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. +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. @@ -1056,8 +1833,8 @@ swap a anl a,#0x0f mov _i,a -In general SDCC will never setup a loop if the shift count is known. -Another example +In general SDCC will never setup a loop if the shift count +is known. Another example unsigned int i; ... @@ -1072,13 +1849,13 @@ clr c rrc a mov _i,a -Note that SDCC stores numbers in little-endian format (i.e. lowest -order first) +Note that SDCC stores numbers in little-endian format (i.e. +lowest order first) -6.7.1 Bit-rotation:\label{bit rotation} +4.1.9 Bit-rotation -A special case of the bit-shift operation is bit rotation, SDCC recognizes -the following expression to be a left 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; ... @@ -1091,16 +1868,17 @@ 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 */ +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} +4.1.10 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. +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; @@ -1113,17 +1891,29 @@ unsigned char hob; 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. + +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. @@ -1131,14 +1921,14 @@ xyz = gint + ((gint >> 15) & 1); will still be recognized. -6.9 Peep-hole optimizer.\label{Peep-Hole} +4.1.11 Peep-hole Optimizer -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 option. The rule language -is best illustrated with examples. +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 option. +The rule language is best illustrated with examples. replace { mov %1,a @@ -1153,42 +1943,52 @@ to mov r1,a -Note: All occurrences of a '%n' ( pattern variable ) must denote the -same string. With the above rule, the assembly sequence +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'. +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 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 ] '{' '\n' - '}' by '{' '\n' - '\n' - '}' [if ] '\n' - := 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. + + '}' by '{' '\n' + + + + '\n' + + '}' [if +] '\n' + := 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 @@ -1196,9 +1996,9 @@ 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. +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 @@ -1211,14 +2011,16 @@ 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 +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. +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 @@ -1226,505 +2028,91 @@ replace { 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
        -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 (.rst) -and (.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. +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. + +4.2 Pragmas + +SDCC supports the following #pragma directives. This directives +are applicable only at a function level. + +* SAVE - this will save all the current options . + +* 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 - will stop global subexpression elimination. + +* NOINDUCTION - will stop loop induction optimizations . + +* NOJTBOUND - will not generate code for boundary value checking + , when switch statements are turned into jump-tables. + +* NOOVERLAY - the compiler will not overlay the parameters + and local variables of a function. + +* NOLOOPREVERSE - Will not do loop reversal optimization + +* EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma + disables generation of pair of push/pop instruction in + ISR function (using interrupt keyword). The directive + should be placed immediately before the ISR function definition + and it affects ALL ISR functions following it. To enable + the normal register saving for ISR functions use "#pragma + EXCLUDE none" + +* CALLEE-SAVES function1[,function2[,function3...]] - 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 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 -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 */ -#pragma SAVE /* save the current settings */ -#pragma NOGCSE /* turnoff global subexpression elimination */ -#pragma NOINDUCTION /* turn off induction optimizations */ int foo () { ... @@ -1733,80 +2121,132 @@ int foo () } #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. +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} +4.3 Library Routines 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 . +stdio.h - Contains the following functions printf & sprintf +these routines are developed by Martijn van Balen . %[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' + 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. +* 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. @@ -1814,80 +2254,95 @@ format output type argument-type * string.h - contains the following functions. - strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, - strspn, strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, - memset. + 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. + 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). +* 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]; + // + #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); + // + 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); + // + //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 +* 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 - these routines are more compact and faster. Please see documentation - in file SDCCDIR/sdcc51lib/ser.c +* ser.h - Alternate serial routine provided by Wolfgang Esslinger + 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 , these routines do not use the external - ram. +* ser_ir.h - Another alternate set of serial routines provided + by Josef Wolf , these routines do not + use the external ram. -* reg51.h - contains register definitions for a standard 8051 +* 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. +* 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. +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. +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} +4.4 Interfacing with Assembly Routines -20.1 Global registers used for parameter passing. +4.5 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). +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 +4.5.1 Assembler Routine(non-reentrant) -In the following example the function cfunc calls an assembler routine -asm_func, which takes two parameters. +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); @@ -1906,47 +2361,56 @@ The corresponding assembler function is:- .globl _asm_func_PARM_2 .globl _asm_func .area OSEG -_asm_func_PARM_2: .ds 1 +_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 + 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. +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 __PARM_, 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 __PARM_2. +The parameter naming convention is __PARM_, +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 __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, +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 +4.5.2 Assembler Routine(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. +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 +int c_func (unsigned short i, unsigned short j) reentrant + { return asm_func(i,j); } @@ -1976,20 +2440,20 @@ _asm_func: 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. +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. +4.6 With --noregparms Option -When the source is compiled with --noregparms option , space is allocated -for each of the parameters passed to a routine. +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. +4.6.1 Assembler Routine Non-reentrant -In the following example the function cfunc calls an assembler routine -asm_func, which takes two parameters. +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); @@ -2009,45 +2473,54 @@ The corresponding assembler function is:- .globl _asm_func_PARM_2 .globl _asm_func .area OSEG -_asm_func_PARM_1: .ds 1 -_asm_func_PARM_2: .ds 1 +_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 + 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. +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 __PARM_, where -n is the parameter number starting from 1, and counting from the left. -i.e. the left-most parameter name will be __PARM_1. +The parameter naming convention is __PARM_, +where n is the parameter number starting from 1, and counting +from the left. i.e. the left-most parameter name will be +__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, +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. +4.6.2 Assembler Routine(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. +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 +int c_func (unsigned short i, unsigned short j) reentrant + { return asm_func(i,j); } @@ -2078,35 +2551,37 @@ _asm_func: 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. +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} +4.7 External Stack -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 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. +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} +4.8 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. +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 @@ -2115,25 +2590,28 @@ struct s s1, s2; foo() { ... -s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ +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 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 */ +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. +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). @@ -2145,65 +2623,73 @@ int i,j; /* are valid in ANSI .. not valid in SDCC */ ... } -1. functions declared as pointers must be dereferenced during the call. +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()' */ + (*foo)();/* ansi standard allows calls to be made like +'foo()' */ -23 Cyclomatic Complexity\label{Cyclomatic} +4.9 Cyclomatic Complexity -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. +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. +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. + (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. + +5 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). +* 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. +* 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. +* 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) { @@ -2211,192 +2697,205 @@ are generally good programming practice. .... } - 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 + 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 ; + 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). + 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 ) +Notes on MCS51 memory layout(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 +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 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. +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. +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. +--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 +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. + +6 Retargetting for other MCUs. + +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. +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 + * 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 + * 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. + +7 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 is part +of the standard compiler installation, which 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. + +7.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 . + +7.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 . + +7.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). @@ -2410,39 +2909,42 @@ The debugger will look for the following files. 3. foo.ihx - the intel hex format object file. -27.4 Command line options. +7.4 Command Line Options. -* --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. +* --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 - change to the . * -fullname - used by GUI front ends. -* -cpu - this argument is passed to the simulator please - see the simulator docs for details. +* -cpu - this argument is passed to the simulator + please see the simulator docs for details. -* -X this options is passed to the simulator please - see simulator docs for details. +* -X this options is passed to the simulator + please see simulator docs for details. -* -s passed to simulator see simulator docs for - details. +* -s passed to simulator see simulator + docs for details. -* -S passed to simulator see simulator docs for details. +* -S passed to simulator see simulator docs + for details. -27.5 Debugger Commands. +7.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. +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] +7.5.1 break [line | file:line | function | file:function] Set breakpoint at specified line or function. @@ -2451,7 +2953,7 @@ sdcdb>break foo.c:100 sdcdb>break funcfoo sdcdb>break foo.c:funcfoo -27.5.2 clear [line | file:line | function | file:function ] +7.5.2 clear [line | file:line | function | file:function ] Clear breakpoint at specified line or function. @@ -2460,91 +2962,96 @@ sdcdb>clear foo.c:100 sdcdb>clear funcfoo sdcdb>clear foo.c:funcfoo -27.5.3 continue +7.5.3 continue Continue program being debugged, after breakpoint. -27.5.4 finish +7.5.4 finish Execute till the end of the current function. -27.5.5 delete [n] +7.5.5 delete [n] -Delete breakpoint number 'n'. If used without any option clear ALL -user defined break points. +Delete breakpoint number 'n'. If used without any option +clear ALL user defined break points. -27.5.6 info [break | stack | frame | registers ] +7.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 frame - show information about the current execution + frame. * info registers - show content of all registers. -27.5.7 step +7.5.7 step Step program until it reaches a different source line. -27.5.8 next +7.5.8 next Step program, proceeding through subroutine calls. -27.5.9 run +7.5.9 run Start debugged program. -27.5.10 ptype variable +7.5.10 ptype variable Print type information of the variable. -27.5.11 print variable +7.5.11 print variable print value of variable. -27.5.12 file filename +7.5.12 file filename -load the given file name. Note this is an alternate method of loading -file for debugging. +load the given file name. Note this is an alternate method +of loading file for debugging. -27.5.13 frame +7.5.13 frame print information about current frame. -27.5.14 set srcmode +7.5.14 set srcmode Toggle between C source & assembly source. -27.5.15 ! simulator command +7.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. +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. +7.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. +7.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 @@ -2556,65 +3063,141 @@ The following is a list of key mapping for the debugger interface. ;; Current Listing :: -;;key binding Comment -;;--- ------- ------- +;;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) +;; 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-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 +;; 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. +8 Other Processors + +8.1 The Z80 and gbz80 port + +SDCC can target both the Zilog Z80 and the Nintendo Gameboy's +Z80-like gbz80. The port is incomplete - long support is +incomplete (mul, div and mod are unimplimented), and both +float and bitfield support is missing, but apart from that +the code generated is correct. + +As always, the code is the authoritave reference - see z80/ralloc.c +and z80/gen.c. The stack frame is similar to that generated +by the IAR Z80 compiler. IX is used as the base pointer, +HL is used as a temporary register, and BC and DE are available +for holding varibles. IY is currently unusued. Return values +are stored in HL. One bad side effect of using IX as the +base pointer is that a functions stack frame is limited +to 127 bytes - this will be fixed in a later version. + +9 Support + +SDCC has grown to be large project, the compiler alone (without +the Assembler Package, Preprocessor) is about 40,000 lines +of code (blank stripped). The open source nature of this +project is a key to its continued growth and support. You +gain the benefit and support of many active software developers +and end users. Is SDCC perfect? No, that's why we need your +help. The developers take pride in fixing reported bugs. +You can help by reporting the bugs and helping other SDCC +users. There are lots of ways to contribute, and we encourage +you to take part in making SDCC a great software package. + +9.1 Reporting Bugs + +Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' +or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed +ASAP. When reporting a bug, it is very useful to include +a small test program which reproduces the problem. If you +can isolate the problem by looking at the generated assembly +code, this can be very helpful. Compiling your program with +the --dumpall option can sometimes be useful in locating +optimization problems. + +9.2 Acknowledgments + +Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, +MCS51 code generator, Debugger, AVR port +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 - for his +Freeware simulator +Malini Dutta(malini_dutta@hotmail.com) - my wife for her +patience and support. +Unknown - for the GNU C - preprocessor. +Michael Hope - The Z80 and Z80GB port, 186 development +Kevin Vigor - The DS390 port. +Johan Knol - DS390/TINI libs, lots of fixes and enhancements. +Scott Datallo - PIC port. +(Thanks to all the other volunteer developers who have helped +with coding, testing, web-page creation, distribution sets, +etc. You know who you are :-) -Daniel Drotos - for his Freeware -simulator -Jans J Boehm(boehm@sgi.com) and Alan J Demers - Conservative garbage -collector for C & C++. +This document initially written by Sandeep Dutta -Malini Dutta(malini@mediaone.net) - my wife for her patience and support. +All product names mentioned herein may be trademarks of their +respective companies. -Unknown - for the GNU C - preprocessor. -\index -- 2.30.2

/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

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

SDCC Compiler User Guide

Sandeep Dutta (sandeep.dutta@usa.net)

SDCC Compiler User Guide

+Contents +

+1 Introduction +

+1.1 About SDCC +

+1.2 Open Source +

+1.3 System Requirements +

+1.4 Other Resources +

+2 Installation +

+2.1 Linux/Unix Installation +

+2.2 Windows Installation +

+2.2.1 Windows Install Using a Binary Package +

+2.2.2 Windows Install Using Cygwin +

+2.3 Testing out the SDCC Compiler +

+2.4 Install Trouble-shooting +

+2.4.1 SDCC cannot find libraries or header files. +

+2.4.2 SDCC does not compile correctly. +

+2.4.3 What the ``./configure'' does +

+2.4.4 What the ``make'' does. +

+2.4.5 What the ``make install'' command does. +

+2.5 Additional Information for Windows Users +

+2.5.1 Getting started with Cygwin +

+2.5.2 Running SDCC as Native Compiled Executables +

+2.6 SDCC on Other Platforms +

+2.7 Advanced Install Options +

+2.8 Components of SDCC +

+2.8.1 cpp ( C-Preprocessor) +

+2.8.2 asxxxx & aslink ( The assembler and Linkage Editor) +

+2.8.3 SDCC - The compiler +

+2.8.4 S51 - Simulator +

+2.8.5 SDCDB - Source Level Debugger +

+3 Using SDCC +

+3.1 Compiling +

+3.1.1 Single Source File Projects +

+3.1.2 Projects with Multiple Source Files +

+3.1.3 Projects with Additional Libraries +

+3.2 Command Line Options +

+3.2.1 Processor Selection Options +

+3.2.2 Path, Lib and Define Options +

+3.2.3 MCS51 Options +

+3.2.4 Optimization Options +

+3.2.5 DS390 Options +

+3.2.6 Other Options +

+3.2.7 Intermediate Dump Options +

+3.3 MCS51 Storage Class Language Extensions +

+3.3.1 xdata +

+3.3.2 data +

+3.3.3 idata +

+3.3.4 bit +

+3.3.5 sfr / sbit +

+3.4 Pointers +

+3.5 Parameters & Local Variables +

+3.6 Overlaying +

+3.7 Critical Functions +

+3.8 Absolute Addressing +

+3.9 Interrupt Service Routines +

+3.10 Startup Code +

+3.11 Inline Assembler Code +

+3.12 int(16 bit) and long (32 bit ) Support +

+3.13 Floating Point Support +

+3.14 MCS51 Memory Models +

+3.15 Flat 24 bit Addressing Model +

+3.16 Defines Created by the Compiler +

+4 SDCC Technical Data +

+4.1 Optimizations +

+4.1.1 Sub-expression Elimination +

+4.1.2 Dead-Code Elimination +

+4.1.3 Copy-Propagation +

+4.1.4 Loop Optimizations +

+4.1.5 Loop Reversing: +

+4.1.6 Algebraic Simplifications +

+4.1.7 'switch' Statements +

+4.1.8 Bit-shifting Operations. +

+4.1.9 Bit-rotation +

+4.1.10 Highest Order Bit +

+4.1.11 Peep-hole Optimizer +

+4.2 Pragmas +

+4.3 Library Routines +

+4.4 Interfacing with Assembly Routines +