sdccman.txt

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

* asx8051 - The assembler for 8051 type processors.

* as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers.

* aslink -The linker for 8051 type processors.

* link-z80, link-gbz80 - The Z80 and GameBoy Z80 linkers.

* s51 - The ucSim 8051 simulator.

* sdcdb - The source debugger.

* packihx - A tool to pack (compress) Intel hex files.

In <installdir>/share/sdcc/include

* the include files

In <installdir>/share/sdcc/lib

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

In <installdir>/share/sdcc/doc

* the documentation

As development for other processors proceeds, this list 
will expand to include executables to support 
processors like AVR, PIC, etc.

2.9.1 sdcc - The Compiler

This is the actual compiler, it in turn uses the 
c-preprocessor and invokes the assembler and linkage editor.

2.9.2 sdcpp - The C-Preprocessor

The preprocessor is a modified version of the GNU cpp 
preprocessor [http://gcc.gnu.org/]. The C preprocessor is used to pull in 
#include sources, process #ifdef statements, #defines 
and so on.

2.9.3 asxxxx, aslink, link-xxx - The Assemblers and 
  Linkage Editors

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

2.9.4 s51 - The Simulator

S51 is a free open source simulator developed by Daniel 
Drotos. The simulator is built as part of the build 
process. For more information visit Daniel's web site 
at: [http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51]. It currently supports the core mcs51, the Dallas 
DS80C390 and the Phillips XA51 family.

2.9.5 sdcdb - Source Level Debugger

SDCDB is the companion source level debugger. More 
about SDCDB in section [cha:Debugging-with-SDCDB]. The current version of the 
debugger uses Daniel's Simulator S51, but can be easily 
changed to use other simulators.

Using SDCC

3.1 Compiling

3.1.1 Single Source File Projects

For single source file 8051 projects the process is 
very simple. Compile your programs with the following 
command "sdcc sourcefile.c". This will compile, 
assemble and link your source file. Output files are as follows:

* sourcefile.asm - Assembler source file created by the compiler

* sourcefile.lst - Assembler listing file created by 
  the Assembler

* sourcefile.rst - Assembler listing file updated with 
  linkedit information, created by linkage editor

* sourcefile.sym - symbol listing for the sourcefile, 
  created by the assembler

* sourcefile.rel or sourcefile.o - Object file created 
  by the assembler, input to Linkage editor

* sourcefile.map - The memory map for the load module, 
  created by the Linker

* sourcefile.mem - A file with a summary of the memory usage

* sourcefile.ihx - The load module in Intel hex format 
  (you can select the Motorola S19 format with --out-fmt-s19
  . If you need another format you might want to use objdump
   or srecord - see also section [sub:Postprocessing-the-Intel]). Both formats are 
  documented in the documentation of srecord

* sourcefile.adb - An intermediate file containing 
  debug information needed to create the .cdb file 
  (with --debug) 

* sourcefile.cdb - An optional file (with --debug) 
  containing debug information. The format is 
  documented in cdbfileformat.pdf

* sourcefile. - (no extension) An optional AOMF or AOMF51
   <OMF file>file containing debug information (generated with 
  option --debug). The (Intel) absolute object module 
  format is a subformat of the OMF51 format and is 
  commonly used by third party tools (debuggers, 
  simulators, emulators).

* sourcefile.dump* - Dump file to debug the compiler it 
  self (generated with option --dumpall) (see section [sub:Intermediate-Dump-Options]  
  and section [sub:The-anatomy-of] "Anatomy of the compiler").

3.1.2 Postprocessing the Intel Hex file<sub:Postprocessing-the-Intel>

In most cases this won't be needed but the Intel Hex file
 which is generated by SDCC might include lines of 
varying length and the addresses within the file are 
not guaranteed to be strictly ascending. If your 
toolchain or a bootloader does not like this you can 
use the tool packihx which is part of the SDCC 
distribution: 

 packihx sourcefile.ihx >sourcefile.hex


The separately available srecord package additionally 
allows to set undefined locations to a predefined 
value, to insert checksums of various flavours (crc, 
add, xor) and to perform other manipulations (convert, 
split, crop, offset, ...). 

srec_cat  sourcefile.ihx -intel  
-o sourcefile.hex -intel

An example for a more complex 
command line

the command backfills unused memory with 0x12 and the 
overall 16 bit sum of the complete 64 kByte block is 
zero. If the program counter on an mcs51 runs wild the 
backfill pattern 0x12 will be interpreted as an lcall 
to address 0x1212 (where an emergency routine could sit).
 could look like:

srec_cat sourcefile.ihx -intel  -fill 
0x12 0x0000 0xfffe -little-endian-checksum-negative 
0xfffe 0x02 0x02  -o sourcefile.hex -intel

The srecord 
package is available at [http://sf.net/projects/srecord] .

3.1.3 Projects with Multiple Source Files

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

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

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

sdcc -c 
foo1.c
sdcc -c foo2.c

Then compile the source file 
containing the main() function and link the files 
together with the following command: 

sdcc foomain.c foo1.rel 
foo2.rel

Alternatively, foomain.c can be separately 
compiled as well: 

sdcc -c foomain.c
sdcc foomain.rel 
foo1.rel foo2.rel

The file containing the main() 
function must be the first file specified in the 
command line, since the linkage editor processes file 
in the order they are presented to it. The linker is 
invoked from SDCC using a script file with extension .lnk
. You can view this file to troubleshoot linking 
problems such as those arising from missing libraries.

3.1.4 Projects with Additional Libraries

Some reusable routines may be compiled into a library, 
see the documentation for the assembler and linkage 
editor (which are in <installdir>/share/sdcc/doc) for 
how to create a .lib library file. Libraries created in 
this manner can be included in the command line. Make 
sure you include the -L <library-path> option to tell 
the linker where to look for these files if they are 
not in the current directory. Here is an example, 
assuming you have the source file foomain.c and a 
library foolib.lib in the directory mylib (if that is 
not the same as your current project):

sdcc foomain.c 
foolib.lib -L mylib

Note here that mylib must be an 
absolute path name.

The most efficient way to use 
libraries is to keep separate modules in separate 
source files. The lib file now should name all the modules.rel
 files. For an example see the standard library file 
libsdcc.lib in the directory <installdir>/share/lib/small.

3.1.5 Using sdcclib to Create and Manage Libraries

Alternatively, instead of having a .rel file for each 
entry on the library file as described in the preceding 
section, sdcclib can be used to embed all the modules 
belonging to such library in the library file itself. 
This results in a larger library file, but it greatly 
reduces the number of disk files accessed by the 
linker.  Additionally, the packed library file contains 
an index of all include modules and symbols that 
significantly speeds up the linking process. To display 
a list of options supported by sdcclib type:


sdcclib -?

To create a new library file, start by 
compiling all the required modules. For example:


sdcc -c _divsint.c

sdcc -c _divuint.c

sdcc -c _modsint.c

sdcc -c _moduint.c

sdcc -c _mulint.c


This will create files _divsint.rel, _divuint.rel, 
_modsint.rel, _moduint.rel, and _mulint.rel. The next 
step is to add the .rel files to the library file:


sdcclib libint.lib _divsint.rel

sdcclib libint.lib _divuint.rel

sdcclib libint.lib _modsint.rel

sdcclib libint.lib _moduint.rel

sdcclib libint.lib _mulint.rel


Or, if you preffer:


sdcclib libint.lib _divsint.rel _divuint.rel 
_modsint.rel _moduint.rel _mulint.rel


If the file already exists in the library, it will be 
replaced. If a list of .rel files is available, you can 
tell sdcclib to add those files to a library. For 
example, if the file 'myliblist.txt' contains


_divsint.rel

_divuint.rel

_modsint.rel

_moduint.rel

_mulint.rel


Use


sdcclib -l libint.lib myliblist.txt


Additionally, you can instruct sdcclib to compiles the 
files before adding them to the library. This is 
achieved using the environment variables SDCCLIB_CC 
and/or SDCCLIB_AS. For example:


set SDCCLIB_CC=sdcc -c

sdcclib -l libint.lib myliblist.txt


To see what modules and symbols are included in the 
library, options -s and -m are available. For example:


sdcclib -s libint.lib
_divsint.rel:

__divsint_a_1_1

__divsint_PARM_2

__divsint
_divuint.rel:

__divuint_a_1_1

__divuint_PARM_2

__divuint_reste_1_1

__divuint_count_1_1

__divuint
_modsint.rel:

__modsint_a_1_1

__modsint_PARM_2

__modsint
_moduint.rel:

__moduint_a_1_1

__moduint_PARM_2

__moduint_count_1_1

__moduint
_mulint.rel:

__mulint_PARM_2

__mulint


If the source files are compiled using --debug, the 
corresponding debug information file .adb will be 
include in the library file as well. The library files 
created with sdcclib are plain text files, so they can 
be viewed with a text editor. It is not recomended to 
modify a library file created with sdcclib using a text 
editor, as there are file indexes numbers located 
accross the file used by the linker to quickly locate 
the required module to link. Once a .rel file (as well 
as a .adb file) is added to a library using sdcclib, it 
can be safely deleted, since all the information 
required for linking is embedded in the library file 
itself. Library files created using sdcclib are used as 
described in the preceding sections.



3.2 Command Line Options<sec:Command-Line-Options>

3.2.1 Processor Selection Options

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

-mds390 Generate code for the Dallas DS80C390 processor.

-mds400 Generate code for the Dallas DS80C400 processor.

-mhc08 Generate code for the Freescale/Motorola HC08 
family of processors.

-mz80 Generate code for the Zilog Z80 family of processors.

-mgbz80 Generate code for the GameBoy Z80 processor 
(Not actively maintained).

-mavr Generate code for the Atmel AVR processor (Not 
maintained, not complete). AVR users should probably 
have a look at winavr [http://sourceforge.net/projects/winavr] or [http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index], which is based on AVR-port 
of the gcc compiler.



-mpic14 Generate code for the Microchip PIC 14-bit 
processors (p16f84 and variants. In development, not complete).



-mpic16 Generate code for the Microc