SDCC Compiler User Guide
SDCC 3.3.2
$Date:: 2014-01-02 #$
$Revision: 8933 $
Contents
1
2
3
Introduction
1.1 About SDCC . . . . . . . . . . . .
1.2 SDCC Suite Licenses . . . . . . . .
1.3 Documentation . . . . . . . . . . .
1.4 Typographic conventions . . . . . .
1.5 Compatibility with previous versions
1.6 System Requirements . . . . . . . .
1.7 Other Resources . . . . . . . . . . .
1.8 Wishes for the future . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
6
6
7
8
8
8
10
10
10
Installing SDCC
2.1 Configure Options . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Install paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Search Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Building SDCC . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.1 Building SDCC on Linux . . . . . . . . . . . . . . . . . .
2.4.2 Building SDCC on Mac OS X . . . . . . . . . . . . . . . .
2.4.3 Cross compiling SDCC on Linux for Windows . . . . . . .
2.4.4 Building SDCC using Cygwin and Mingw32 . . . . . . . .
2.4.5 Building SDCC Using Microsoft Visual C++ 2010 (MSVC)
2.4.6 Windows Install Using a ZIP Package . . . . . . . . . . . .
2.4.7 Windows Install Using the Setup Program . . . . . . . . . .
2.4.8 VPATH feature . . . . . . . . . . . . . . . . . . . . . . . .
2.5 Building the Documentation . . . . . . . . . . . . . . . . . . . . .
2.6 Reading the Documentation . . . . . . . . . . . . . . . . . . . . .
2.7 Testing the SDCC Compiler . . . . . . . . . . . . . . . . . . . . .
2.8 Install Trouble-shooting . . . . . . . . . . . . . . . . . . . . . . . .
2.8.1 If SDCC does not build correctly . . . . . . . . . . . . . . .
2.8.2 What the ”./configure” does . . . . . . . . . . . . . . . . .
2.8.3 What the ”make” does . . . . . . . . . . . . . . . . . . . .
2.8.4 What the ”make install” command does. . . . . . . . . . . .
2.9 Components of SDCC . . . . . . . . . . . . . . . . . . . . . . . .
2.9.1 sdcc - The Compiler . . . . . . . . . . . . . . . . . . . . .
2.9.2 sdcpp - The C-Preprocessor . . . . . . . . . . . . . . . . .
2.9.3 sdas, sdld - The Assemblers and Linkage Editors . . . . . .
2.9.4 s51, sz80, shc08, sstm8 - The Simulators . . . . . . . . . .
2.9.5 sdcdb - Source Level Debugger . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
14
14
16
16
16
17
17
18
19
19
19
19
20
20
21
21
21
21
21
21
23
23
23
23
23
Using SDCC
3.1 Standard-Compliance . . . . . .
3.1.1 ISO C90 and ANSI C89
3.1.2 ISO C99 . . . . . . . .
3.1.3 ISO C11 . . . . . . . .
3.1.4 Embedded C . . . . . .
3.2 Compiling . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
24
24
24
25
25
25
26
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
CONTENTS
CONTENTS
3.2.1 Single Source File Projects . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 Postprocessing the Intel Hex file . . . . . . . . . . . . . . . . . . . .
3.2.3 Projects with Multiple Source Files . . . . . . . . . . . . . . . . . .
3.2.4 Projects with Additional Libraries . . . . . . . . . . . . . . . . . . .
3.2.5 Using sdar to Create and Manage Libraries . . . . . . . . . . . . . .
3.2.6 Using sdcclib to Create and Manage Libraries (deprecated) . . . . . .
3.3 Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Processor Selection Options . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Preprocessor Options . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.3 Optimization Options . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.4 Other Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.5 Linker Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.6 MCS51 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.7 DS390 / DS400 Options . . . . . . . . . . . . . . . . . . . . . . . .
3.3.8 Options common to all z80-related ports (z80, z180, r2k, r3ka, gbz80)
3.3.9 Z80 Options (apply to z80, z180, r2k and r3ka port) . . . . . . . . . .
3.3.10 GBZ80 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.11 Intermediate Dump Options . . . . . . . . . . . . . . . . . . . . . .
3.3.12 Redirecting output on Windows Shells . . . . . . . . . . . . . . . . .
3.4 Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5 Storage Class Language Extensions . . . . . . . . . . . . . . . . . . . . . .
3.5.1 MCS51/DS390 Storage Class Language Extensions . . . . . . . . . .
3.5.1.1 __data / __near . . . . . . . . . . . . . . . . . . . . . . .
3.5.1.2 __xdata / __far . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1.3 __idata . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1.4 __pdata . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1.5 __code . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1.6 __bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1.7 __sfr / __sfr16 / __sfr32 / __sbit . . . . . . . . . . . . . .
3.5.1.8 Pointers to MCS51/DS390 specific memory spaces . . . .
3.5.1.9 Notes on MCS51 memory layout . . . . . . . . . . . . . .
3.5.2 Z80/Z180 Storage Class Language Extensions . . . . . . . . . . . .
3.5.2.1 __sfr (in/out to 8-bit addresses) . . . . . . . . . . . . . . .
3.5.2.2 banked sfr (in/out to 16-bit addresses) . . . . . . . . . . .
3.5.2.3 __sfr (in0/out0 to 8 bit addresses on Z180/HD64180) . . .
3.5.3 HC08/S08 Storage Class Language Extensions . . . . . . . . . . . .
3.5.3.1 __data . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.3.2 __xdata . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6 Other SDCC language extensions . . . . . . . . . . . . . . . . . . . . . . .
3.6.1 Binary constants . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.2 Named address spaces . . . . . . . . . . . . . . . . . . . . . . . . .
3.7 Absolute Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8 Parameters & Local Variables . . . . . . . . . . . . . . . . . . . . . . . . .
3.9 Overlaying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.10 Interrupt Service Routines . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.10.1 General Information . . . . . . . . . . . . . . . . . . . . . . . . . .
3.10.1.1 Common interrupt pitfall: variable not declared volatile . .
3.10.1.2 Common interrupt pitfall: non-atomic access . . . . . . . .
3.10.1.3 Common interrupt pitfall: stack overflow . . . . . . . . . .
3.10.1.4 Common interrupt pitfall: use of non-reentrant functions .
3.10.2 MCS51/DS390 Interrupt Service Routines . . . . . . . . . . . . . . .
3.10.3 HC08 Interrupt Service Routines . . . . . . . . . . . . . . . . . . . .
3.10.4 Z80 Interrupt Service Routines . . . . . . . . . . . . . . . . . . . . .
3.11 Enabling and Disabling Interrupts . . . . . . . . . . . . . . . . . . . . . . .
3.11.1 Critical Functions and Critical Statements . . . . . . . . . . . . . . .
3.11.2 Enabling and Disabling Interrupts directly . . . . . . . . . . . . . . .
2
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
26
26
27
27
27
28
29
29
30
30
31
34
34
35
36
36
36
36
36
37
37
37
37
37
37
38
38
38
39
39
40
40
40
41
41
41
41
41
41
41
41
42
43
44
44
44
45
45
45
45
45
46
46
46
46
47
CONTENTS
4
CONTENTS
3.11.3 Semaphore locking (mcs51/ds390) . . . . . . . . . . . . . .
3.12 Functions using private register banks (mcs51/ds390) . . . . . . . .
3.13 Startup Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.13.1 MCS51/DS390 Startup Code . . . . . . . . . . . . . . . . .
3.13.2 HC08 Startup Code . . . . . . . . . . . . . . . . . . . . . .
3.13.3 Z80 Startup Code . . . . . . . . . . . . . . . . . . . . . . .
3.14 Inline Assembler Code . . . . . . . . . . . . . . . . . . . . . . . .
3.14.1 Inline Assemblere Code Formats . . . . . . . . . . . . . . .
3.14.1.1 Old __asm ... __endasm; Format . . . . . . . . .
3.14.1.2 New __asm__ (”inline_assembler_code”) Format
3.14.2 A Step by Step Introduction . . . . . . . . . . . . . . . . .
3.14.3 Naked Functions . . . . . . . . . . . . . . . . . . . . . . .
3.14.4 Use of Labels within Inline Assembler . . . . . . . . . . . .
3.15 Interfacing with Assembler Code . . . . . . . . . . . . . . . . . . .
3.15.1 Global Registers used for Parameter Passing . . . . . . . .
3.15.2 Registers usage . . . . . . . . . . . . . . . . . . . . . . . .
3.15.3 Assembler Routine (non-reentrant) . . . . . . . . . . . . . .
3.15.4 Assembler Routine (reentrant) . . . . . . . . . . . . . . . .
3.15.5 Small-C calling convention . . . . . . . . . . . . . . . . . .
3.16 int (16 bit) and long (32 bit) Support . . . . . . . . . . . . . . . . .
3.17 Floating Point Support . . . . . . . . . . . . . . . . . . . . . . . .
3.18 Library Routines . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.18.1 Compiler support routines (_gptrget, _mulint etc.) . . . . .
3.18.2 Stdclib functions (puts, printf, strcat etc.) . . . . . . . . . .
3.18.2.1 . . . . . . . . . . . . . . . . . . . . . .
3.18.2.2 . . . . . . . . . . . . . . . . . . . . .
3.18.3 Math functions (sinf, powf, sqrtf etc.) . . . . . . . . . . . .
3.18.3.1 . . . . . . . . . . . . . . . . . . . . . .
3.18.4 Other libraries . . . . . . . . . . . . . . . . . . . . . . . .
3.19 Memory Models . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.19.1 MCS51 Memory Models . . . . . . . . . . . . . . . . . . .
3.19.1.1 Small, Medium, Large and Huge . . . . . . . . .
3.19.1.2 External Stack . . . . . . . . . . . . . . . . . . .
3.19.2 DS390 Memory Model . . . . . . . . . . . . . . . . . . . .
3.20 Pragmas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.21 Defines Created by the Compiler . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
47
47
48
48
50
50
50
50
50
51
51
53
54
54
54
55
55
56
56
56
57
57
58
58
58
59
59
59
59
60
60
60
60
60
60
64
Notes on supported Processors
4.1 MCS51 variants . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.1 pdata access by SFR . . . . . . . . . . . . . . . . . . . . .
4.1.2 Other Features available by SFR . . . . . . . . . . . . . . .
4.1.3 Bankswitching . . . . . . . . . . . . . . . . . . . . . . . .
4.1.3.1 Hardware . . . . . . . . . . . . . . . . . . . . .
4.1.3.2 Software . . . . . . . . . . . . . . . . . . . . . .
4.2 DS400 port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 The Z80, Z180, Rabbit 2000/3000, Rabbit 3000A and GBZ80 ports
4.4 The HC08 and S08 ports . . . . . . . . . . . . . . . . . . . . . . .
4.5 The PIC14 port . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.1 PIC Code Pages and Memory Banks . . . . . . . . . . . . .
4.5.2 Adding New Devices to the Port . . . . . . . . . . . . . . .
4.5.3 Interrupt Code . . . . . . . . . . . . . . . . . . . . . . . .
4.5.4 Configuration Bits . . . . . . . . . . . . . . . . . . . . . .
4.5.5 Linking and Assembling . . . . . . . . . . . . . . . . . . .
4.5.6 Command-Line Options . . . . . . . . . . . . . . . . . . .
4.5.7 Environment Variables . . . . . . . . . . . . . . . . . . . .
4.5.8 The Library . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.8.1 Enhanced cores . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
65
65
65
65
65
66
66
66
66
67
67
67
68
68
68
69
69
70
70
70
3
CONTENTS
4.6
5
6
CONTENTS
4.5.8.2 Accessing bits of special function registers . . . .
4.5.8.3 Naming of special function registers . . . . . . .
4.5.8.4 error: missing definition for symbol “__gptrget1”
4.5.8.5 Processor mismatch in file “XXX”. . . . . . . . .
4.5.9 Known Bugs . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.9.1 Function arguments . . . . . . . . . . . . . . . .
4.5.9.2 Regression tests fail . . . . . . . . . . . . . . . .
The PIC16 port . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1 Global Options . . . . . . . . . . . . . . . . . . . . . . . .
4.6.2 Port Specific Options . . . . . . . . . . . . . . . . . . . . .
4.6.2.1 Code Generation Options . . . . . . . . . . . . .
4.6.2.2 Optimization Options . . . . . . . . . . . . . . .
4.6.2.3 Assembling Options . . . . . . . . . . . . . . . .
4.6.2.4 Linking Options . . . . . . . . . . . . . . . . . .
4.6.2.5 Debugging Options . . . . . . . . . . . . . . . .
4.6.3 Environment Variables . . . . . . . . . . . . . . . . . . . .
4.6.4 Preprocessor Macros . . . . . . . . . . . . . . . . . . . . .
4.6.5 Directories . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.6 Pragmas . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.7 Header Files and Libraries . . . . . . . . . . . . . . . . . .
4.6.8 Header Files . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.9 Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.10 Adding New Devices to the Port . . . . . . . . . . . . . . .
4.6.11 Memory Models . . . . . . . . . . . . . . . . . . . . . . .
4.6.12 Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.13 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.14 Function return values . . . . . . . . . . . . . . . . . . . .
4.6.15 Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.16 Generic Pointers . . . . . . . . . . . . . . . . . . . . . . .
4.6.17 Configuration Bits . . . . . . . . . . . . . . . . . . . . . .
4.6.18 PIC16 C Libraries . . . . . . . . . . . . . . . . . . . . . .
4.6.18.1 Standard I/O Streams . . . . . . . . . . . . . . .
4.6.18.2 Printing functions . . . . . . . . . . . . . . . . .
4.6.18.3 Signals . . . . . . . . . . . . . . . . . . . . . . .
4.6.19 PIC16 Port – Tips . . . . . . . . . . . . . . . . . . . . . . .
4.6.19.1 Stack size . . . . . . . . . . . . . . . . . . . . .
4.6.20 Known Bugs . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.20.1 Extended Instruction Set . . . . . . . . . . . . . .
4.6.20.2 Regression Tests . . . . . . . . . . . . . . . . . .
Debugging
5.1 Debugging with SDCDB . . . . . . . . .
5.1.1 Compiling for Debugging . . . .
5.1.2 How the Debugger Works . . . .
5.1.3 Starting the Debugger SDCDB . .
5.1.4 SDCDB Command Line Options
5.1.5 SDCDB Debugger Commands . .
5.1.6 Interfacing SDCDB with DDD . .
5.1.7 Interfacing SDCDB with XEmacs
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
70
70
70
70
71
71
71
71
72
72
72
72
72
73
73
73
73
74
74
75
76
76
76
77
77
78
78
79
79
80
80
80
81
81
82
82
83
83
83
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
84
85
85
85
85
86
86
88
88
TIPS
6.1 Porting code from or to other compilers . . . .
6.2 Tools included in the distribution . . . . . . . .
6.3 Documentation included in the distribution . .
6.4 Communication online at SourceForge . . . . .
6.5 Related open source tools . . . . . . . . . . . .
6.6 Related documentation / recommended reading
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
90
91
92
93
93
94
94
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4
CONTENTS
6.7
6.8
7
8
9
CONTENTS
Application notes specifically for SDCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Some Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Support
7.1 Reporting Bugs . . . . . . . . . . .
7.2 Requesting Features . . . . . . . . .
7.3 Submitting patches . . . . . . . . .
7.4 Getting Help . . . . . . . . . . . . .
7.5 ChangeLog . . . . . . . . . . . . .
7.6 Subversion Source Code Repository
7.7 Release policy . . . . . . . . . . . .
7.8 Quality control . . . . . . . . . . .
7.9 Examples . . . . . . . . . . . . . .
7.10 Use of SDCC in Education . . . . .
94
95
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
96
96
97
97
97
97
97
97
97
98
98
SDCC Technical Data
8.1 Optimizations . . . . . . . . . . . . . . . . . .
8.1.1 Sub-expression Elimination . . . . . .
8.1.2 Dead-Code Elimination . . . . . . . .
8.1.3 Copy-Propagation . . . . . . . . . . .
8.1.4 Loop Optimizations . . . . . . . . . .
8.1.5 Loop Reversing . . . . . . . . . . . . .
8.1.6 Algebraic Simplifications . . . . . . .
8.1.7 ’switch’ Statements . . . . . . . . . . .
8.1.8 Bit-shifting Operations. . . . . . . . .
8.1.9 Bit-rotation . . . . . . . . . . . . . . .
8.1.10 Nibble and Byte Swapping . . . . . . .
8.1.11 Highest Order Bit / Any Order Bit . . .
8.1.12 Higher Order Byte / Higher Order Word
8.1.13 Register Allocation . . . . . . . . . . .
8.1.14 Peephole Optimizer . . . . . . . . . . .
8.2 Cyclomatic Complexity . . . . . . . . . . . . .
8.3 Retargetting for other Processors . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
99
99
99
99
100
100
101
101
101
103
103
104
104
105
106
106
108
108
Compiler internals
9.1 The anatomy of the compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.2 A few words about basic block successors, predecessors and dominators . . . . . . . . . . . . . .
110
110
116
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
10 Acknowledgments
117
5
Chapter 1
Introduction
1.1
About SDCC
SDCC (Small Device C Compiler) is free open source, retargettable, optimizing ANSI-C compiler suite by
Sandeep Dutta designed for 8 bit Microprocessors. The current version targets Intel MCS51 based Microprocessors (8031, 8032, 8051, 8052, etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 based (hc08,
s08), Zilog Z80 based MCUs (z80, z180, gbz80, Rabbit 2000/3000, Rabbit 3000A) and STMicroelectronics STM8
. It can be retargeted for other microprocessors, support for Microchip PIC is under development. The entire
source code for the compiler is distributed under GPL. SDCC uses a modified version of ASXXXX & ASLINK,
free open source retargetable assembler & linker. SDCC has extensive language extensions suitable for utilizing
various microcontrollers and underlying hardware effectively.
Warning: Parts of this manual apply to the mc51 port only. Further information on the z80, z180, r2k, r3ka and
gbz80 ports and standard compliance can be found in the sdcc wiki http://sdcc.sourceforge.net/
wiki/.
In addition to the MCU specific optimizations SDCC also does a host of standard optimizations like:
• global sub expression elimination,
• loop optimizations (loop invariant, strength reduction of induction variables and loop reversing),
• constant folding & propagation,
• copy propagation,
• dead code elimination
• jump tables for switch statements.
For the back-end SDCC uses a global register allocation scheme which should be well suited for other 8 bit MCUs.
The peep hole optimizer uses a rule based substitution mechanism which is MCU independent.
Supported data-types are:
6
1.2. SDCC SUITE LICENSES
type
bool1
_Bool /
char
short
int
long
long long3
float
CHAPTER 1. INTRODUCTION
width
byte2
8 bits, 1
8 bits, 1 byte
16 bits, 2 bytes
16 bits, 2 bytes
32 bits, 4 bytes
64 bits, 8 bytes
4 bytes IEEE 754
default
signed range
unsigned
signed
signed
signed
signed
signed
signed
-128, +127
-32.768, +32.767
-32.768, +32.767
-2.147.483.648, +2.147.483.647
unsigned range
0, 1
0, +255
0, +65.535
0, +65.535
0, +4.294.967.295
1.175494351E-38,
3.402823466E+38
pointer
1, 2, 3 or 4 bytes
generic
The compiler also allows inline assembler code to be embedded anywhere in a function. In addition, routines
developed in assembly can also be called.
SDCC also provides an option (--cyclomatic) to report the relative complexity of a function.
tions can then be further optimized, or hand coded in assembly if needed.
These func-
SDCC also comes with a companion source level debugger SDCDB. The debugger currently uses ucSim, a
free open source simulator for 8051 and other micro-controllers.
The latest SDCC version can be downloaded from http://sdcc.sourceforge.net/snap.php.
Please note: the compiler will probably always be some steps ahead of this documentation4 .
1.2
SDCC Suite Licenses
SDCC suite is a collection of several components derived from different sources with different licenses:
• executables:
– sdcc compiler:
sdcc compiler is licensed under the GPLv2.
The code or object files generated by SDCC suite are not licensed, so they can be used in FLOSS or
proprietary (closed source) applications.
– sdcpp preprocessor:
derived from GCC cpp preprocessor http://gcc.gnu.org/; GPLv3 license
– sdas assemblers and sdld linker:
derived from ASXXXX http://shop-pdp.kent.edu/ashtml/asxxxx.htm;
license
GPLv3
– SDCC run-time libraries:
The great majority of SDCC run-time libraries are licensed under the GPLv2+LE which allows linking
of SDCC run-time libraries with proprietary (closed source) applications.
Exception are pic device libraries and header files which are derived from Microchip header (.inc) and
linker script (.lkr) files. Microchip requires that "The header files should state that they are only to
be used with authentic Microchip devices" which makes them incompatible with the GPL. Pic device
libraries and header files are located at non-free/lib and non-free/include directories respectively. Sdcc
should be run with the --use-non-free command line option in order to include non-free header files and
libraries.
– sdbinutils utilities (sdar, sdranlib, sdnm, sdobjcopy):
derived from GNU Binutils http://www.gnu.org/software/binutils/; GPLv3 license
– sdcclib librarian:
GPLv2 license
– ucsim simulators:
GPLv2 license
4 Obviously
this has pros and cons
7
1.3. DOCUMENTATION
CHAPTER 1. INTRODUCTION
– sdcdb debugger:
GPLv2 license
– gcc-test regression tests:
derived from gcc-testsuite; no license explicitely specified, but since it is a part of GCC is probably
GPLv3 licensed
– packihx:
public domain
– makebin:
zlib/libpng License
• libraries:
– dbuf library:
zlib/libpng License
– Boost C++ libraries:
http://www.boost.org/; Boost Software License 1.0 (BSL-1.0)
– STX B+ Tree C++ Template Classes:
http://idlebox.net/2007/stx-btree/; LGPLv2.1
Links to licenses:
• GPLv2 license: http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
• LGPLv2.1 license: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
• GPLv3 license: http://www.gnu.org/licenses/gpl.html
• zlib/libpng License: http://www.opensource.org/licenses/Zlib
• Boost Software License 1.0 (BSL-1.0): http://www.opensource.org/licenses/BSL-1.0
1.3
Documentation
This documentation is maintained using a free open source word processor (LYX) http://www.lyx.org/.
1.4
Typographic conventions
Throughout this manual, we will use the following convention. Commands you have to type in are printed in "sans
serif". Code samples are printed in typewriter font. Interesting items and new terms are printed in italic.
1.5
Compatibility with previous versions
Newer versions have usually numerous bug fixes compared with the previous version. But we also sometimes
introduce some incompatibilities with older versions. Not just for the fun of it, but to make the compiler more
stable, efficient and ANSI compliant (see section 3.1 for Standard-Compliance).
• short is now equivalent to int (16 bits), it used to be equivalent to char (8 bits) which is not ANSI compliant.
To maintain compatibility, old programs may be compiled using the --short-is-8bits commandline option
(see 3.3.4 on page 33).
• the default directory for gcc-builds where include, library and documentation files are stored is now in
/usr/local/share.
8
1.5. COMPATIBILITY WITH PREVIOUS VERSIONS
CHAPTER 1. INTRODUCTION
• char type parameters to vararg functions are casted to int unless explicitly casted and --std-c89 and --std-c99
command line option are not defined, e.g.:
char a=3;
printf ("%d %c\n", a, (char)a);
will push a as an int and as a char resp if --std-c89 and --std-c99 command line options are not defined,
will push a as two ints if --std-c89 or --std-c99 command line option is defined.
• pointer type parameters to vararg functions are casted to generic pointers on harvard architectures (e.g.
mcs51, ds390) unless explicitly casted and --std-c89 and --std-c99 command line option are not defined.
• option --regextend has been removed.
• option --noregparms has been removed.
• option --stack-after-data has been removed.
• bit and sbit types now consistently behave like the C99 _Bool type with respect to type conversion. The most
common incompatibility resulting from this change is related to bit toggling idioms, e.g.:
bit b;
b = ~b; /* equivalent to b=1 instead of toggling b */
b = !b; /* toggles b */
In previous versions, both forms would have toggled the bit.
• in older versions, the preprocessor was always called with --std-c99 regardless of the --std-xxx setting. This
is no longer true, and can cause compilation failures on code built with --std-c89 but using c99 preprocessor
features, such as one-line (//) comments
• in versions older than 2.8.4 the pic16 *printf() and printf_tiny() library functions supported undocumented
and not standard compliant ’b’ binary format specifier ("%b", "%hb" and "%lb"). The ’b’ specifier
is now disabled by default. It can be enabled by defining BINARY_SPECIFIER macro in files device/lib/pic16/libc/stdio/vfprintf.c and device/lib/pic16/libc/stdio/printf_tiny.c and recompiling the library.
• in versions older then 2.8.5 the unnamed bitfield structure members participated in initialization, which is
not conforming with ISO/IEC 9899:1999 standard (see section Section 6.7.8 Initialization, clause 9)
Old behavior, before version 2.8.5:
struct {
int a : 2;
char : 2;
int b : 2;
} s = {1, 2, 3};
/* s.a = 1, s.b = 3 */
New behavior:
struct {
int a : 2;
char : 2;
int b : 2;
} s = {1, 2};
/* s.a = 1, s.b = 2 */
• libraries, included in sdcc packages, are in ar format in sdcc version 2.9.0 and higher. See section 3.2.5.
• targets for xa51 and avr are disabled by default in version 3.0.0 and higher.
• in sdcc version 3.0.0 and higher sdldgb and sdldz80 don’t support generation of GameBoy binary image
format. The makebin utility can be used to convert Intel Hex format to GameBoy binary image format.
• in sdcc version 3.0.0 and higher sdldgb and sdldz80 don’t support generation of rrgb (GameBoy simulator)
map file and no$gmb symbol file formats. The as2gbmap utility can be used to convert sdld map format to
rrgb and no$gmb file formats.
9
1.6. SYSTEM REQUIREMENTS
CHAPTER 1. INTRODUCTION
• asranlib utility was renamed to sdranlib in sdcc version 3.1.0.
• in sdcc version 3.1.0 pic 14 traget, structured access to SFR via _bits. is deprecated and replaced by bits.. It will be obsoleted (removed) in one of next sdcc
releases. See section 4.5.8.3.
• sdar archive managing utility and sdnm utilityes were introduced in version 3.2.0. sdar, sdranlib and sdnm
are derived from GNU Binutils package.
• with sdcc version 3.2.0 the sdcclib utility is deprecated. Sdar utility should be used to create sdcc object file
archives. Sdcclib utility will become obsolete in one of next sdcc releases and will be removed from sdcc
packages.
• special sdcc keywords which are not preceded by a double underscore are obsoleted (removed) in version
3.2.0 and higher. See section 3.1 Standard-Compliance.
• in sdcc version 3.2.0 compiler macro definitions not starting with double underscore characters are deprecated
if –std-cXX command line option is defined. They will be oboleted (removed) in one of next sdcc releases.
• in sdcc version 3.2.0 new compiler macros for processor definition were introduced for pic14 and pic16
targets: -D__SDCC_PIC16XXXX and -D__SDCC_PIC18FXXX respectively. The pic16 macro definition
-D__18fXXX is deprecated. It will be obsoleted (removed) in one of next sdcc releases.
• pragma config for pic16 target was introduced in version 3.2.0. See section 4.6.6
• new inline assembler format __asm__ (inline_assembler_code”); as an addition to __asm
... __endasem; format introduced in version 3.2.0. See section 3.14
• sdobjcopy utility was introduced in version 3.3.0. It is derived from GNU Binutils package.
1.6
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.7
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.
The latest snapshot build version of this document in pdf format is available at http://sdcc.sourceforge.
net/doc/sdccman.pdf. 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 from Subversion on http://sourceforge.net/p/sdcc/
code/8805/tree/trunk/sdcc/.
1.8
Wishes for the future
There are (and always will be) some things that could be done. Here are some I can think of:
char KernelFunction3(char p) at 0x340;
better code banking support for mcs51
If you can think of some more, please see the section 7.2 about filing feature requests.
10
Chapter 2
Installing SDCC
For most users it is sufficient to skip to either section 2.4.1 (Unix) or section 2.4.7 (Windows). More detailed
instructions follow below.
2.1
Configure Options
The install paths, search paths and other options are defined when running ’configure’. The defaults can be overridden by:
--prefix
see table below
--exec_prefix see table below
--bindir
see table below
--datadir
see table below
--datarootdir see table below
docdir
environment variable, see table below
include_dir_suffix environment variable, see table below
non_free_include_dir_suffix environment variable, see table below
lib_dir_suffix environment variable, see table below
non_free_lib_dir_suffix environment variable, see table below
sdccconf_h_dir_separator environment variable, either / or \\ makes sense here. This character will only be used
in sdccconf.h; don’t forget it’s a C-header, therefore a double-backslash is needed there.
--disable-mcs51-port Excludes the Intel mcs51 port
--disable-z80-port Excludes the z80 port
--disable-z180-port Excludes the z180 port
--disable-r2k-port Excludes the r2k port
--disable-r3ka-port Excludes the r3ka port
--disable-gbz80-port Excludes the GameBoy gbz80 port
--disable-avr-port Excludes the AVR port (disabled by default)
--disable-ds390-port Excludes the DS390 port
11
2.1. CONFIGURE OPTIONS
CHAPTER 2. INSTALLING SDCC
--disable-hc08-port Excludes the HC08 port
--disable-s08-port Excludes the S08 port
--disable-stm8-port Excludes the STM8 port
--disable-pic-port Excludes the PIC14 port
--disable-pic16-port Excludes the PIC16 port
--disable-xa51-port Excludes the XA51 port (disabled by default)
--disable-ucsim Disables configuring and building of ucsim
--disable-device-lib Disables automatically building device libraries
--disable-packihx Disables building packihx
--enable-doc Build pdf, html and txt files from the lyx sources
--enable-libgc Use the Bohem memory allocator. Lower runtime footprint.
--without-ccache Do not use ccache even if available
Furthermore the environment variables CC, CFLAGS, ... the tools and their arguments can be influenced. Please
see ‘configure --help’ and the man/info pages of ‘configure’ for details.
The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB, STD_FP_LIB,
STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_NAME, SDCC_INCLUDE_NAME,
SDCC_LIB_NAME are defined by ‘configure’ too. At the moment it’s not possible to change the default settings
(it was simply never required).
These configure options are compiled into the binaries, and can only be changed by rerunning ’configure’
and recompiling SDCC. The configure options are written in italics to distinguish them from run time environment
variables (see section search paths).
The settings for ”Win32 builds” are used by the SDCC team to build the official Win32 binaries.
SDCC team uses Mingw32 to build the official Windows binaries, because it’s
The
1. open source,
2. a gcc compiler and last but not least
3. the binaries can be built by cross compiling on SDCC Distributed Compile Farm.
See the examples, how to pass the Win32 settings to ’configure’. The other Win32 builds using VC or whatever
don’t use ’configure’, but a header file sdcc_vc.h.in is the same as sdccconf.h built by ’configure’ for Win32.
These defaults are:
Variable
PREFIX
EXEC_PREFIX
BINDIR
DATADIR
DATAROOTDIR
DOCDIR
INCLUDE_DIR_SUFFIX
NON_FREE_INCLUDE_DIR_SUFFIX
LIB_DIR_SUFFIX
NON_FREE_LIB_DIR_SUFFIX
default
/usr/local
$PREFIX
$EXEC_PREFIX/bin
$DATAROOTDIR
$PREFIX/share
$DATAROOTDIR/sdcc/doc
sdcc/include
sdcc/non-free/include
sdcc/lib
sdcc/non-free/lib
12
Win32 builds
\sdcc
$PREFIX
$EXEC_PREFIX\bin
$DATAROOTDIR
$PREFIX
$DATAROOTDIR\doc
include
non-free/include
lib
non-free/lib
2.1. CONFIGURE OPTIONS
CHAPTER 2. INSTALLING SDCC
’configure’ also computes relative paths. This is needed for full relocatability of a binary package and to complete
search paths (see section search paths below):
Variable (computed)
BIN2DATA_DIR
PREFIX2BIN_DIR
PREFIX2DATA_DIR
default
../share
bin
share/sdcc
Win32 builds
..
bin
Examples:
./configure
./configure --prefix=”/usr/bin” --datarootdir=”/usr/share”
./configure --disable-avr-port --disable-xa51-port
To cross compile on linux for Mingw32 (see also ’sdcc/support/scripts/sdcc_mingw32’):
./configure \
CC=”i586-mingw32msvc-gcc” CXX=”i586-mingw32msvc-g++” \
RANLIB=”i586-mingw32msvc-ranlib” \
STRIP=”i586-mingw32msvc-strip” \
--prefix=”/sdcc” \
--datarootdir=”/sdcc” \
docdir=”\${datarootdir}/doc” \
include_dir_suffix=”include” \
non_free_include_dir_suffix=”non-free/include” \
lib_dir_suffix=”lib” \
non_free_lib_dir_suffix=”non-free/lib” \
sdccconf_h_dir_separator=”\\\\” \
--disable-device-lib\
--host=i586-mingw32msvc\
--build=unknown-unknown-linux-gnu
To ”cross”compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32):
./configure -C \
--prefix=”/sdcc” \
--datarootdir=”/sdcc” \
docdir=”\${datarootdir}/doc” \
include_dir_suffix=”include” \
non_free_include_dir_suffix=”non-free/include” \
lib_dir_suffix=”lib” \
non_free_lib_dir_suffix=”non-free/lib” \
sdccconf_h_dir_separator=”\\\\” \
CC=”gcc -mno-cygwin” \
CXX=”g++ -mno-cygwin”
’configure’ is quite slow on Cygwin (at least on windows before Win2000/XP). The option ’--C’ turns on caching,
which gives a little bit extra speed. However if options are changed, it can be necessary to delete the config.cache
file.
13
2.2. INSTALL PATHS
2.2
CHAPTER 2. INSTALLING SDCC
Install paths
Description
Binary files*
Include files
Non-free include files
Library file**
Library file**
Documentation
Path
$EXEC_PREFIX
$DATADIR/
$INCLUDE_DIR_SUFFIX
$DATADIR/non-free/
$INCLUDE_DIR_SUFFIX
$DATADIR/
$LIB_DIR_SUFFIX
$DATADIR/non-free/
$LIB_DIR_SUFFIX
$DOCDIR
Default
/usr/local/bin
/usr/local/share/
sdcc/include
/usr/local/share/
sdcc/non-free/include
/usr/local/share/
sdcc/lib
/usr/local/share/
sdcc/non-free/lib
/usr/local/share/
sdcc/doc
Win32 builds
\sdcc\bin
\sdcc\include
\sdcc\non-free\include
\sdcc\lib
\sdcc\non-free\lib
\sdcc\doc
*compiler, preprocessor, assembler, and linker
**the model is auto-appended by the compiler, e.g. small, large, z80, ds390 etc
The install paths can still be changed during ‘make install’ with e.g.:
make install prefix=$(HOME)/local/sdcc
Of course this doesn’t change the search paths compiled into the binaries.
Moreover the install path can be changed by defining DESTDIR:
make install DESTDIR=$(HOME)/sdcc.rpm/
Please note that DESTDIR must have a trailing slash!
2.3
Search Paths
Some search paths or parts of them are determined by configure variables (in italics, see section above). Further
search paths are determined by environment variables during runtime.
The paths searched when running the compiler are as follows (the first catch wins):
1. Binary files (preprocessor, assembler and linker)
Search path
$SDCC_HOME/$PPREFIX2BIN_DIR
Path of argv[0] (if available)
$PATH
default
$SDCC_HOME/bin
Path of argv[0]
$PATH
2. Include files
14
Win32 builds
$SDCC_HOME\bin
Path of argv[0]
$PATH
2.3. SEARCH PATHS
#
1
2
3
4
5
6
7
8
Search path
--I dir
$SDCC_INCLUDE
$SDCC_HOME/
$PREFIX2DATA_DIR/
$INCLUDE_DIR_SUFFIX
path(argv[0])/
$BIN2DATADIR/
$INCLUDE_DIR_SUFFIX
$DATADIR/
$INCLUDE_DIR_SUFFIX
$SDCC_HOME/
$PREFIX2DATA_DIR/
non-free/
$INCLUDE_DIR_SUFFIX
path(argv[0])/
$BIN2DATADIR/
non-free/
$INCLUDE_DIR_SUFFIX
$DATADIR/
non-free/
$INCLUDE_DIR_SUFFIX
CHAPTER 2. INSTALLING SDCC
default
--I dir
$SDCC_INCLUDE
$SDCC_HOME/
share/sdcc/include
Win32 builds
--I dir
$SDCC_INCLUDE
$SDCC_HOME\include
path(argv[0])/../
sdcc/include
path(argv[0])\..\include
/usr/local/share/
sdcc/include
$SDCC_HOME/share/
sdcc/non-free/include
(not on Win32)
$SDCC_HOME\non-free\include
path(argv[0])/../
sdcc/non-free/include
path(argv[0])\..\non-free\include
/usr/local/share/
sdcc/non-free/include
(not on Win32)
The option --nostdinc disables all search paths except #1 and #2.
3. Library files
With the exception of ”--L dir” the model is auto-appended by the compiler (e.g. small, large, z80, ds390 etc.).
15
2.4. BUILDING SDCC
#
1
2
3
4
Search path
--L dir
$SDCC_LIB/
$SDCC_LIB
$SDCC_HOME/
$PREFIX2DATA_DIR/
$LIB_DIR_SUFFIX/
path(argv[0])/
$BIN2DATADIR/
$LIB_DIR_SUFFIX/
$DATADIR/non-free/
$LIB_DIR_SUFFIX/
$SDCC_HOME/
$PREFIX2DATA_DIR/
non-free/
$LIB_DIR_SUFFIX/
path(argv[0])/
$BIN2DATADIR/
non-free/
$LIB_DIR_SUFFIX/
$DATADIR/non-free/
$LIB_DIR_SUFFIX/
5
6
7
8
9
CHAPTER 2. INSTALLING SDCC
default
--L dir
$SDCC_LIB/
$SDCC_LIB
$SDCC_HOME/
share/sdcc/lib/
Win32 builds
--L dir
$SDCC_LIB/
$SDCC_LIB
$SDCC_HOME\
lib\
path(argv[0])/../sdcc/
lib/
path(argv[0])\
..\lib\
/usr/local/share/sdcc/
lib/
(not on Win32)
$SDCC_HOME/share/sdcc/
non-free/lib/
$SDCC_HOME\
lib\non-free\
path(argv[0])/../sdcc/
non-free/lib/
path(argv[0])\..\
lib\non-free\
/usr/local/share/sdcc/
non-free/lib/
(not on Win32)
The option --nostdlib disables all search paths except #1 and #2.
2.4
2.4.1
Building SDCC
Building SDCC on Linux
1. Download the source package either from the SDCC Subversion repository or from snapshot builds, it will
be named something like sdcc-src-yyyymmdd-rrrr.tar.bz2 http://sdcc.sourceforge.net/snap.
php.
2. Bring up a command line terminal, such as xterm.
3. Unpack the file using a command like: "tar -xvjf sdcc-src-yyyymmdd-rrrr.tar.bz2”, 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, the include files, the libraries and the
documentation to the install directories. Proceed with section 2.7.
2.4.2
Building SDCC on Mac OS X
Follow the instruction for Linux.
16
2.4. BUILDING SDCC
CHAPTER 2. INSTALLING SDCC
On Mac OS X 10.2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease)) fails to compile SDCC. Fortunately there’s also gcc 2.9.x installed, which works fine. This compiler can be selected by running
’configure’ with:
./configure CC=gcc2 CXX=g++2
Universal (ppc and i386) binaries can be produced on Mac OS X 10.4.x with Xcode. Run ’configure’ with:
./configure \
LDFLAGS="-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc" \
CXXFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc" \
CFLAGS = "-O2 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc"
2.4.3
Cross compiling SDCC on Linux for Windows
With the Mingw32 gcc cross compiler it’s easy to compile SDCC for Win32. See section ’Configure Options’.
2.4.4
Building SDCC using Cygwin and Mingw32
For building and installing a Cygwin executable follow the instructions for Linux.
On Cygwin a ”native” Win32-binary can be built, which will not need the Cygwin-DLL. For the necessary
’configure’ options see section ’configure options’ or the script ’sdcc/support/scripts/sdcc_cygwin_mingw32’.
In order to install Cygwin on Windows download setup.exe from www.cygwin.com http://www.cygwin.
com/. Run it, set the ”default text file type” to ”unix” and download/install at least the following packages. Some
packages are selected by default, others will be automatically selected because of dependencies with the manually
selected packages. Never deselect these packages!
• flex
• bison
• gcc ; version 3.x is fine, no need to use the old 2.9x
• binutils ; selected with gcc
• make
• libboost-dev
• rxvt ; a nice console, which makes life much easier under windoze (see below)
• man ; not really needed for building SDCC, but you’ll miss it sooner or later
• less ; not really needed for building SDCC, but you’ll miss it sooner or later
• svn ; only if you use Subversion access
If you want to develop something you’ll need:
• python ; for the regression tests
• gdb ; the gnu debugger, together with the nice GUI ”insight”
• openssh ; to access the CF or commit changes
• autoconf and autoconf-devel ; if you want to fight with ’configure’, don’t use autoconf-stable!
rxvt is a nice console with history. Replace in your cygwin.bat the line
bash --login -i
with (one line):
17
2.4. BUILDING SDCC
CHAPTER 2. INSTALLING SDCC
rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
-bg black -fg white -geometry 100x65 -e bash --login
Text selected with the mouse is automatically copied to the clipboard, pasting works with shift-insert.
The other good tip is to make sure you have no //c/-style paths anywhere, use /cygdrive/c/ instead. Using //
invokes a network lookup which is very slow. If you think ”cygdrive” is too long, you can change it with e.g.
mount -s -u -c /mnt
SDCC sources use the unix line ending LF. Life is much easier, if you store the source tree on a drive which is
mounted in binary mode. And use an editor which can handle LF-only line endings. Make sure not to commit files
with windows line endings. The tabulator spacing used in the project is 8. Although a tabulator spacing of 8 is a
sensible choice for programmers (it’s a power of 2 and allows to display 8/16 bit signed variables without loosing
columns) the plan is to move towards using only spaces in the source.
2.4.5
Building SDCC Using Microsoft Visual C++ 2010 (MSVC)
Download the source package either from the SDCC Subversion repository or from the snapshot builds
http://sdcc.sourceforge.net/snap.php, it will be named something like sdcc-src-yyyymmddrrrr.tar.bz2. SDCC is distributed with all the project, solution and other files you need to build it using Visual C++
2010 (except for ucSim). The solution name is ’sdcc.sln’. Please note that as it is now, all the executables are
created in a folder called sdcc\bin_vc. Once built you need to copy the executables from sdcc\bin_vc to sdcc\bin
before running SDCC.
Apart from the SDCC sources you also need to have the BOOST libraries installed for MSVC. Get it here
http://www.boost.org/
In order to build SDCC with MSVC you need win32 executables of bison.exe, flex.exe, and gawk.exe. One
good place to get them is here http://unxutils.sourceforge.net
Download the file UnxUtils.zip. Now you have to install the utilities and setup MSVC so it can locate the
required programs. Here there are two alternatives (choose one!):
1. The easy way:
a) Extract UnxUtils.zip to your C:\ hard disk PRESERVING the original paths, otherwise bison won’t work.
(If you are using WinZip make certain that ’Use folder names’ is selected)
b) Add ’C:\user\local\wbin’ to VC++ Directories / Executable Directories.
(As a side effect, you get a bunch of Unix utilities that could be useful, such as diff and patch.)
2. A more compact way:
This one avoids extracting a bunch of files you may not use, but requires some extra work:
a) Create a directory were to put the tools needed, or use a directory already present. Say for example ’C:\util’.
b) Extract ’bison.exe’, ’bison.hairy’, ’bison.simple’, ’flex.exe’, and gawk.exe to such directory WITHOUT
preserving the original paths. (If you are using WinZip make certain that ’Use folder names’ is not selected)
c) Rename bison.exe to ’_bison.exe’.
d) Create a batch file ’bison.bat’ in ’C:\util\’ and add these lines:
set BISON_SIMPLE=C:\util\bison.simple
set BISON_HAIRY=C:\util\bison.hairy
18
2.5. BUILDING THE DOCUMENTATION
CHAPTER 2. INSTALLING SDCC
_bison %1 %2 %3 %4 %5 %6 %7 %8 %9
Steps ’c’ and ’d’ are needed because bison requires by default that the files ’bison.simple’ and ’bison.hairy’ reside in some weird Unix directory, ’/usr/local/share/’ I think. So it is necessary to tell bison
where those files are located if they are not in such directory. That is the function of the environment
variables BISON_SIMPLE and BISON_HAIRY.
e) Add ’C:\util’ to VC++ Directories / Executable Directories. Note that you can use any other path
instead of ’C:\util’, even the path where the Visual C++ tools are, probably: ’C:\Program Files\Microsoft
Visual Studio\Common\Tools’. So you don’t have to execute step ’e’ :)
That is it. Open ’sdcc.sln’ in Visual Studio, click ’build all’, when it finishes copy the executables from sdcc\bin_vc
to sdcc\bin, and you can compile using SDCC.
2.4.6
Windows Install Using a ZIP Package
1. Download the binary zip package from http://sdcc.sf.net/snap.php 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 the mingw32 package is: C:\sdcc\bin for the executables, C:\sdcc\include
and C:\sdcc\lib for the include and libraries.
2. Adjust your environment variable PATH to include the location of the bin directory or start sdcc using the
full path.
2.4.7
Windows Install Using the Setup Program
Download the setup program sdcc-x.y.z-setup.exe for an official release from
http://sourceforge.net/projects/sdcc/files/ or a setup program for one of the snapshots sdccyyyymmdd-xxxx-setup.exe from http://sdcc.sourceforge.net/snap.php and execute it. A windows
typical installer will guide you through the installation process.
2.4.8
VPATH feature
SDCC supports the VPATH feature provided by configure and make. It allows to separate the source and build
trees. Here’s an example:
cd ~
# cd $HOME
tar -xjf sdcc-src-yyyymmdd-rrrr.tar.bz2 # extract source to directory
sdcc
mkdir sdcc.build
# put output in sdcc.build
cd sdcc.build
../sdcc/configure
# configure is doing all the
magic!
make
That’s it! configure will create the directory tree will all the necessary Makefiles in ~/sdcc.build. It automagically
computes the variables srcdir, top_srcdir and top_buildir for each directory. After running make the generated files
will be in ~/sdcc.build, while the source files stay in ~/sdcc.
This is not only usefull for building different binaries, e.g. when cross compiling. It also gives you a much better
overview in the source tree when all the generated files are not scattered between the source files. And the best
thing is: if you want to change a file you can leave the original file untouched in the source directory. Simply copy
it to the build directory, edit it, enter ‘make clean’, ‘rm Makefile.dep’ and ‘make’. make will do the rest for you!
2.5
Building the Documentation
Add --enable-doc to the configure arguments to build the documentation together with all the other stuff. You will
need several tools (LYX, LATEX, LATEX2HTML, pdflatex, dvipdf, dvips and makeindex) to get the job done. Another
possibility is to change to the doc directory and to type ”make” there. You’re invited to make changes and additions
19
2.6. READING THE DOCUMENTATION
CHAPTER 2. INSTALLING SDCC
to this manual (sdcc/doc/sdccman.lyx). Using LYX http://www.lyx.org as editor is straightforward. Prebuilt
documentation is available from http://sdcc.sourceforge.net/snap.php.
2.6
Reading the Documentation
Currently reading the document in pdf format is recommended, as for unknown reason the hyperlinks are working
there whereas in the html version they are not1 .
You’ll find the pdf version at http://sdcc.sourceforge.net/doc/sdccman.pdf.
This documentation is in some aspects different from a commercial documentation:
• It tries to document SDCC for several processor architectures in one document (commercially these probably
would be separate documents/products). This document currently matches SDCC for mcs51 and DS390 best
and does give too few information about f.e. Z80, PIC14, PIC16 and HC08.
• There are many references pointing away from this documentation. Don’t let this distract you. If there
f.e. was a reference like http://www.opencores.org together with a statement ”some processors which are targetted by SDCC can be implemented in a f ield programmable gate array” or http:
//sourceforge.net/projects/fpgac/ ”have you ever heard of an open source compiler that compiles a subset of C for an FPGA?” we expect you to have a quick look there and come back. If you read this
you are on the right track.
• Some sections attribute more space to problems, restrictions and warnings than to the solution.
• The installation section and the section about the debugger is intimidating.
• There are still lots of typos and there are more different writing styles than pictures.
2.7
Testing 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 output its version like:
SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
(UNIX)
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 section 2.8 Install trouble-shooting for suggestions). Make sure that the sdcc program is in the bin
folder, if not perhaps something did not install correctly.
SDCC is commonly installed as described in section ”Install and search paths”.
Make sure the compiler works on a very simple example. Type in the following test.c program using your
favorite ASCII editor:
char test;
void main(void) {
test=0;
}
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 directory (see section 2.8 Install
1 If
you should know why please drop us a note
20
2.8. INSTALL TROUBLE-SHOOTING
CHAPTER 2. INSTALLING SDCC
trouble-shooting 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
char str1[10];
void main(void) {
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 section 2.8 Install trouble-shooting section for suggestions). Use
option --print-search-dirs to find exactly where SDCC is looking for the include and lib files.
2.8
2.8.1
Install Trouble-shooting
If SDCC does not build correctly
A thing to try is starting from scratch by unpacking the .tgz source package again in an empty directory. Configure
it like:
./configure 2>&1 | tee configure.log
and build it like:
make 2>&1 | tee make.log
If anything goes wrong, you can review the log files to locate the problem. Or a relevant part of this can
be attached to an email that could be helpful when requesting help from the mailing list.
2.8.2
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.8.3
What the ”make” does
This runs the GNU make tool, which automatically compiles all the source packages into the final installed binary
executables.
2.8.4
What the ”make install” command does.
This will install the compiler, other executables libraries and include files into the appropriate directories. See
sections 2.2, 2.3 about install and search paths.
On most systems you will need super-user privileges to do this.
2.9
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.
21
2.9. COMPONENTS OF SDCC
CHAPTER 2. INSTALLING SDCC
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 files which are installed in . At the time of this writing, we find
the following programs for gcc-builds:
In /bin:
• sdcc - The compiler.
• sdcpp - The C preprocessor.
• sdas8051 - The assembler for 8051 type processors.
• sdas390 - The assembler for DS80C390 processor.
• sdasz80, sdasgb - The Z80 and GameBoy Z80 assemblers.
• sdas6808 - The 6808 assembler.
• sdasstm8 - The STM8 assembler.
• sdld -The linker for 8051 and STM8 type processors.
• sdldz80, sdldgb - The Z80 and GameBoy Z80 linkers.
• sdld6808 - The 6808 linker.
• s51 - The ucSim 8051 simulator.
• sz80 - The ucSim Z80 simulator.
• shc08 - The ucSim 6808 simulator.
• sstm8 - The ucSim STM8 simulator.
• sdcdb - The source debugger.
• sdcclib - A tool for creating sdcc libraries (deprecated)
• sdar, sdranlib, sdnm, sdobjcopy - The sdcc archive managing and indexing utilites.
• packihx - A tool to pack (compress) Intel hex files.
• makebin - A tool to convert Intel Hex file to a binary and GameBoy binary image file format.
In /share/sdcc/include
• the include files
In /share/sdcc/non-free/include
• the non-free include files
In /share/sdcc/lib
• the src and target subdirectories with the precompiled relocatables.
In /share/sdcc/non-free/lib
• the src and target subdirectories with the non-free precompiled relocatables.
In /share/sdcc/doc
• the documentation
22
2.9. COMPONENTS OF SDCC
2.9.1
CHAPTER 2. INSTALLING SDCC
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
sdas, sdld - The Assemblers and Linkage Editors
This is a set of retargettable assemblers and linkage editors, which 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.
SDCC used an about 1998 branch of asxxxx version 2.0 which unfortunately is not compatible with the more
advanced (f.e. macros, more targets) ASxxxx Cross Assemblers nowadays available from Alan Baldwin http:
//shop-pdp.kent.edu/. In 2009 Alan made his ASxxxx Cross Assemblers version 5.0 available under the
GPL licence (GPLv3 or later), so a reunion is now a work in progress. Thanks Alan!
2.9.4
s51, sz80, shc08, sstm8 - The Simulators
s51, sz80 shc08 and sstm8 are free open source simulators developed by Daniel Drotos. The simulators are
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,
the Phillips XA51 family, the Z80, 6808 and the STM8.
2.9.5
sdcdb - Source Level Debugger
SDCDB is the companion source level debugger. More about SDCDB in section 5.1. The current version of the
debugger uses Daniel’s Simulator S51, but can be easily changed to use other simulators.
23
Chapter 3
Using SDCC
3.1
Standard-Compliance
sdcc aims to be a conforming freestanding implementation of the C programming language.
3.1.1
ISO C90 and ANSI C89
Use --std-c89 to compile in this mode.
The latest publicly available version of the standard ISO/IEC 9899 - Programming languages - C should be
available at: http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899.
Deviations from standard compliance:
• structures and unions 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, e.g.:
struct s { ... };
struct s s1, s2;
foo()
{
...
s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
...
}
struct s foo1 (struct s parms) /* invalid in SDCC although allowed
in ANSI */
{
struct s rets;
...
return rets; /* is invalid in SDCC although allowed in ANSI
/
*
}
• initialization of structure arrays must be fully braced.
struct s { char x } a[] = {1, 2};
/* invalid in SDCC */
struct s { char x } a[] = {{1}, {2}}; /* OK */
• ’double’ precision floating point not supported. Instead a warning is emitted, and float is used instead.
• Old K&R style function declarations are NOT allowed.
foo(i,j) /* this old style of function declarations */
int i,j; /* is valid in ANSI but not valid in SDCC */
24
3.1. STANDARD-COMPLIANCE
CHAPTER 3. USING SDCC
{
...
}
• Warning for qualifiers occuring multiple times in qualifier-specifier lists is not emitted (sdcc always behaves
according to the ISO C99 / ISO C11 standard in this respect).
Some features of this standard are not supported in some ports:
• Functions are not reentrant unless explicitly declared as such or –stack-auto is specified in the mcs51, hc08
and s08 ports.
3.1.2
ISO C99
Use --std-c99 to compile in this mode.
In addition to what is mentioned in the section above, the following features of this standard are not supported
by sdcc:
• Declarations in places other than those where ISO C90 allows them, e.g.:
for (int
i=0; i<10; i++) /* is invalid in SDCC although allowed
in C99 */
• Data type long double.
• Compound literals.
• Variable-length arrays.
• Integer constants and modulo for long long, unsigned long long, int_fast64_t, int_least64_t, int64_t,
uint_fast64_t, uint_least64_t, uint64_t.
• Float classification macros in math.h.
Some features of this standard are not supported in some ports:
• Support for _Bool / bool is incomplete (no pointers to bool, or bool inside a struct) in the mcs51, ds390 and
xa51 ports.
• There is no support for data types long long, unsigned long long, int_fast64_t, int_least64_t, int64_t,
uint_fast64_t, uint_least64_t, uint64_t in the mcs51, ds390, ds400, pic14, pic16 and xa51 ports.
3.1.3
ISO C11
Use --std-c11 to compile in this mode.
In addition to what is mentioned in the section above, the following features of this standard are not supported
by sdcc:
• Float classification macros in math.h (C11 requires more than C99).
• Type-generic expressions
• Improved Unicode support.
3.1.4
Embedded C
sdcc has some support for named address spaces. The support for fixed-point math in sdcc is inconsistent with this
standard. Other parts of the standard are not supported.
25
3.2. COMPILING
3.2
3.2.1
CHAPTER 3. USING SDCC
Compiling
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 - 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-fmts19. If you need another format you might want to use objdump or srecord - see also section 3.2.2). 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.omf - An optional AOMF or AOMF51 file containing debug information (generated with option
--debug). The (Intel) absolute object module f ormat 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
3.3.11 and section 9.1 ”Anatomy of the compiler”).
3.2.2
Postprocessing the Intel Hex file
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 line1 could look like:
srec_cat sourcefile.ihx -intel
file.hex -intel
-fill 0x12 0x0000 0xfffe -little-endian-checksum-negative 0xfffe 0x02 0x02
-o source-
The srecord package is available at hhttp://sourceforge.net/projects/srecord/.
1 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).
26
3.2. COMPILING
3.2.3
CHAPTER 3. USING SDCC
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.2.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 /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 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
/share/lib/small.
3.2.5
Using sdar to Create and Manage Libraries
Support for sdar format libraries was introduced in sdcc 2.9.0.
Both the GNU and BSD ar format variants are supported by sdld linkers.
To create a library containing sdas object files, you should use the following sequence:
sdar -rc .lib
27
3.2. COMPILING
3.2.6
CHAPTER 3. USING SDCC
Using sdcclib to Create and Manage Libraries (deprecated)2
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 compile 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
2 With sdcc version 3.2.0 the sdcclib utility is deprecated. Sdar utility should be used to create sdcc object file archives. Sdcclib utility will
become obsolete in one of next sdcc releases and will be removed from sdcc packages.
28
3.3. COMMAND LINE OPTIONS
CHAPTER 3. USING SDCC
__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 included
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 recommended to modify a library file created with sdcclib using a text editor, as there are file index
numbers located across 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.3
Command Line Options
3.3.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 (aka 68HC08) family of processors.
-ms08
Generate code for the Freescale/Motorola S08 (aka 68HCS08, HCS08, CS08) family of processors.
-mz80
Generate code for the Zilog Z80 family of processors.
-mz180
Generate code for the Zilog Z180 family of processors.
-mr2k
Generate code for the Rabbit 2000 / Rabbit 3000 family of processors.
-mr3ka
Generate code for the Rabbit 3000A family of processors.
-mgbz80
Generate code for the LR35902 GameBoy Z80 processor.
-mstm8
Generate code for the STMicroelectronics STM8 family of processors.
-mpic14
Generate code for the Microchip PIC 14-bit processors (p16f84 and variants. In development, not
complete).
-mpic16
Generate code for the Microchip PIC 16-bit processors (p18f452 and variants. In development, not
complete).
29
3.3. COMMAND LINE OPTIONS
CHAPTER 3. USING SDCC
SDCC inspects the program name it was called with so the processor family can also be selected by renaming the
sdcc binary (to f.e. z80-sdcc) or by calling SDCC from a suitable link. Option -m has higher priority than setting
from program name.
3.3.2
Preprocessor Options
SDCC uses sdcpp, an adapted version of the GNU Compiler Collection preprocessor cpp (gcc http://gcc.
gnu.org/). If you need more dedicated options than those listed below please refer to the GCC CPP Manual at
http://www.gnu.org/software/gcc/onlinedocs/.
-I
The additional location where the preprocessor will look for <..h> or “..h” files.
-D Command line definition of macros. Passed to the preprocessor.
-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.
-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.
-pedantic-parse-number Pedantic parse numbers so that situations like 0xfe-LO_B(3) are parsed properly and the
macro LO_B(3) gets expanded. See also #pragma pedantic_parse_number on page 62 in section3.20
Note: this functionality is not in conformance with C99 standard!
-Wp preprocessorOption[,preprocessorOption]... Pass the preprocessorOption to the preprocessor sdcpp.
3.3.3
--nogcse
Optimization Options
Will not do global common subexpression elimination, this option may be used when the compiler
creates undesirably large stack/data spaces to store compiler temporaries (spill locations, sloc). A
warning message will be generated when this happens and the compiler will indicate the number of
extra bytes it allocated. It is 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 Loop Invariants in section 8.1.4. It
is recommended that this option NOT be used, #pragma noinvariant can be used to turn off invariant
optimizations for a given function only.
30
3.3. COMMAND LINE OPTIONS
CHAPTER 3. USING SDCC
--noinduction Will not do loop induction optimizations, see section strength reduction for more details. It is
recommended that this option is NOT used, #pragma noinduction can be used to turn off induction
optimizations for a given function only.
--nojtbound Will not generate boundary condition check when switch statements are implemented using jumptables. See section 8.1.7 Switch Statements for more details. It is recommended that this option is
NOT 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.
--nolabelopt Will not optimize labels (makes the dumpfiles more readable).
--no-xinit-opt Will not memcpy initialized data from code space into xdata space. This saves a few bytes in code
space if you don’t have initialized data.
--nooverlay The compiler will not overlay parameters and local variables of any function, see section Parameters
and local variables for more details.
--no-peep Disable peep-hole optimization with built-in rules.
--peep-file This option can be used to use additional rules to be used by the peep hole optimizer. See
section 8.1.14 Peep Hole optimizations for details on how to write these rules.
--peep-asm Pass the inline assembler code through the peep hole optimizer. This can cause unexpected changes
to inline assembler code, please go through the peephole optimizer rules defined in the source file tree
’/peeph.def’ before using this option.
--peep-return Let the peep hole optimizer do return optimizations. This is the default without --debug.
--no-peep-return Do not let the peep hole optimizer do return optimizations. This is the default with --debug.
--opt-code-speed The compiler will optimize code generation towards fast code, possibly at the expense of code
size.
--opt-code-size The compiler will optimize code generation towards compact code, possibly at the expense of code
speed.
--fomit-frame-pointer Frame pointer will be omitted when the function uses no local variables. On the z80-related
ports this option will result in the frame pointer always being omitted.
--max-allocs-per-node Setting this to a high value will result in increased compilation time and more optimized
code being generated. Setting it to lower values speed up compilation, but does not optimize as much.
The default value is 3000. This option currently only affects the hc08, s08, z80, z180, r2k, r3ka and
gbz80 ports.
--nolospre Disable lospre. lospre is an advanced redundancy elimination technique, essentially an improved variant of global subexpression elimination.
--lospre-unsafe-read Allow unsafe reads in lospre. This will enable additional optimizations, but can result in
spurious reads from undefined memory addresses, which can be harmful if the target system uses
certain ways of doing memory-mapped I/O.
3.3.4
Other Options
-v --version displays the sdcc version.
-c --compile-only will compile and assemble the source, but will not call the linkage editor.
--c1mode
reads the preprocessed source from standard input and compiles it. The file name for the assembler
output must be specified using the -o option.
-E
Run only the C preprocessor. Preprocess all the C source files specified and output the results to
standard output.
31
3.3. COMMAND LINE OPTIONS
CHAPTER 3. USING SDCC
-o The output path where everything will be placed or the file name used for all generated output
files. If the parameter is a path, it must have a trailing slash (or backslash for the Windows binaries) to be recognized as a path. Note for Windows users: if the path contains spaces, it should be
surrounded by quotes. The trailing backslash should be doubled in order to prevent escaping the final quote, for example: -o ”F:\Projects\test3\output 1\\” or put after the final quote, for example: -o
”F:\Projects\test3\output 1”\. The path using slashes for directory delimiters can be used too, for
example: -o ”F:/Projects/test3/output 1/”.
--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 3.8 Parameters and Local Variables for more details. If
this option is used all source files in the project should be compiled with this option. It automatically
implies --int-long-reent and --float-reent.
--callee-saves function1[,function2][,function3].... The compiler by default uses a caller saves convention for
register saving across function calls, however this can cause unnecessary register pushing and 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, no extra code will be generated at the entry and exit (function prologue and epilogue)
for these functions to save and restore the registers used by these functions, this can SUBSTANTIALLY
reduce code and improve run time performance of the generated code. In the future the compiler (with
inter procedural 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 _mulint..., 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 callee_saves on page 61.
--all-callee-saves Function of --callee-saves will be applied to all functions by default.
--debug
When this option is used the compiler will generate debug information. The debug information collected in a file with .cdb extension can be used with the SDCDB. For more information see documentation for SDCDB. Another file with a .omf extension contains debug information in AOMF or AOMF51
format which is commonly used by third party tools.
-S
Stop after the stage of compilation proper; do not assemble. The output is an assembler code file for
the input file specified.
--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.
--funsigned-char The default signedness for every type is signed. In some embedded environments the default
signedness of char is unsigned. To set the signess for characters to unsigned, use the option -funsigned-char. If this option is set and no signedness keyword (unsigned/signed) is given, a char will
be signed. All other types are unaffected.
--nostdinc This will prevent the compiler from passing on the default include path to the preprocessor.
--nostdlib This will prevent the compiler from passing on the default library path to the linker.
--verbose
Shows the various actions the compiler is performing.
-V
Shows the actual commands the compiler is executing.
--no-c-code-in-asm Hides your ugly and inefficient c-code from the asm file, so you can always blame the compiler
:)
32
3.3. COMMAND LINE OPTIONS
CHAPTER 3. USING SDCC
--no-peep-comments Don’t include peep-hole comments in the generated asm files even if --fverbose-asm option
is specified.
--i-code-in-asm Include i-codes in the asm file. Sounds like noise but is helpful for debugging the compiler itself.
--less-pedantic Disable some of the more pedantic warnings. For more details, see the less_pedantic pragma on
page 61.
--disable-warning Disable specific warning with number .
--Werror
Treat all warnings as errors.
--print-search-dirs Display the directories in the compiler’s search path
--vc
Display errors and warnings using MSVC style, so you can use SDCC with the visual studio IDE.
With SDCC both offering a GCC-like (the default) and a MSVC-like output style, integration into
most programming editors should be straightforward.
--use-stdout Send errors and warnings to stdout instead of stderr.
-Wa asmOption[,asmOption]... Pass the asmOption to the assembler. See file sdcc/sdas/doc/asmlnk.txt for assembler options.cd
--std-sdcc89 Generally follow the ANSI C89 / ISO C90 standard, but allow some SDCC behaviour that conflicts
with the standard (default).
--std-c89
Follow the ANSI C89 / ISO C90 standard.
--std-sdcc99 Generally follow the ISO C99 standard, but allow some SDCC behaviour that conflicts with the
standard.
--std-c99
Follow the ISO C99 standard.
--std-c11
Follow the ISO C11 standard.
--codeseg The name to be used for the code segment, default CSEG. This is useful if you need to tell the
compiler to put the code in a special segment so you can later on tell the linker to put this segment in
a special place in memory. Can be used for instance when using bank switching to put the code in a
bank.
--constseg The name to be used for the const segment, default CONST. This is useful if you need to tell
the compiler to put the const data in a special segment so you can later on tell the linker to put this
segment in a special place in memory. Can be used for instance when using bank switching to put the
const data in a bank.
--fdollars-in-identifiers Permit ’$’ as an identifier character.
--more-pedantic Actually this is not a SDCC compiler option but if you want more warnings you can use a separate tool dedicated to syntax checking like splint http://www.splint.org. To make your source
files parseable by splint you will have to include lint.h in your source file and add brackets around extended keywords (like ”__at (0xab)” and ”__interrupt (2)”).
Splint has an excellent on line manual at http://www.splint.org/manual/ and it’s capabilities go beyond pure syntax checking. You’ll need to tell splint the location of SDCC’s include files so
a typical command line could look like this:
splint -I /usr/local/share/sdcc/include/mcs51/ myprogram.c
--short-is-8bits Treat short as 8-bit (for backward compatibility with older versions of compiler - see section 1.5).
This option is deprectaed.
--use-non-free Search / include non-free licensed libraries and header files, located under the non-free directory see section 2.3
33
3.3. COMMAND LINE OPTIONS
3.3.5
CHAPTER 3. USING SDCC
Linker Options
-L --lib-path This option is passed to the linkage editor’s 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.
--xram-loc The start location of the external ram, default value is 0. The value entered can be in Hexadecimal or Decimal format, e.g.: --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, e.g.: --code-loc 0x8000 or --code-loc 32768.
--stack-loc By default the stack is placed after the data segment. Using this option the stack can be
placed anywhere in the internal memory space of the 8051. The value entered can be in Hexadecimal
or Decimal format, e.g. --stack-loc 0x20 or --stack-loc 32. Since the sp register is incremented before
a push or call, the initial sp will be set to one byte prior the provided value. The provided value should
not overlap any other memory areas such as used register banks or the data segment and with enough
space for the current application. The --pack-iram option (which is now a default setting) will override
this setting, so you should also specify the --no-pack-iram option if you need to manually place the
stack.
--xstack-loc By default the external stack is placed after the pdata segment. Using this option the xstack
can be placed anywhere in the external memory space of the 8051. The value entered can be in
Hexadecimal or Decimal format, e.g. --xstack-loc 0x8000 or --stack-loc 32768. The provided value
should not overlap any other memory areas such as the pdata or xdata segment and with enough space
for the current application.
--data-loc The start location of the internal ram data segment. The value entered can be in Hexadecimal
or Decimal format, eg. --data-loc 0x20 or --data-loc 32. (By default, the start location of the internal
ram data segment is set as low as possible in memory, taking into account the used register banks and
the bit segment at address 0x20. For example if register banks 0 and 1 are used without bit variables,
the data segment will be set, if --data-loc is not used, to location 0x10.)
--idata-loc The start location of the indirectly addressable internal ram of the 8051, default value is 0x80.
The value entered can be in Hexadecimal or Decimal format, eg. --idata-loc 0x88 or --idata-loc 136.
--bit-loc The start location of the bit addressable internal ram of the 8051. This is not implemented yet.
Instead an option can be passed directly to the linker: -Wl -bBSEG=.
--out-fmt-ihx The linker output (final object code) is in Intel Hex format. This is the default option. The format
itself is documented in the documentation of srecord.
--out-fmt-s19 The linker output (final object code) is in Motorola S19 format. The format itself is documented in
the documentation of srecord.
--out-fmt-elf The linker output (final object code) is in ELF format. (Currently only supported for the HC08 and
S08 processors)
-Wl linkOption[,linkOption]... Pass the linkOption to the linker. If a bootloader is used an option like ”-Wl bCSEG=0x1000” would be typical to set the start of the code segment. Either use the double quotes
around this option or use no space (e.g. -Wl-bCSEG=0x1000). See also #pragma constseg and
#pragma codeseg in section3.20. File sdcc/sdas/doc/asmlnk.txt has more on linker options.
3.3.6
MCS51 Options
--model-small Generate code for Small model programs, see section Memory Models for more details. This is the
default model.
--model-medium Generate code for Medium model programs, see section Memory Models for more details. If
this option is used all source files in the project have to be compiled with this option. It must also be
used when invoking the linker.
34
3.3. COMMAND LINE OPTIONS
CHAPTER 3. USING SDCC
--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 have to be compiled with this option. It must also be used
when invoking the linker.
--model-huge Generate code for Huge model programs, see section Memory Models for more details. If this
option is used all source files in the project have to be compiled with this option. It must also be used
when invoking the linker.
--xstack
Uses a pseudo stack in the pdata area (usually the first 256 bytes in the external ram) for allocating
variables and passing parameters. See section 3.19.1.2 External Stack for more details.
--iram-size Causes the linker to check if the internal ram usage is within limits of the given value.
--xram-size Causes the linker to check if the external ram usage is within limits of the given value.
--code-size Causes the linker to check if the code memory usage is within limits of the given value.
--stack-size Causes the linker to check if there is at minimum bytes for stack.
--pack-iram Causes the linker to use unused register banks for data variables and pack data, idata and stack
together. This is the default and this option will probably be removed along with the removal of --nopack-iram.
--no-pack-iram (deprecated) Causes the linker to use old style for allocating memory areas. This option is now
deprecated and will be removed in future versions.
--acall-ajmp Replaces the three byte instructions lcall/ljmp with the two byte instructions acall/ajmp. Only use
this option if your code is in the same 2k block of memory. You may need to use this option for some
8051 derivatives which lack the lcall/ljmp instructions.
--no-ret-without-call Causes the code generator to insert an extra lcall or acall instruction whenever it needs to
use a ret instruction in a context other than a function returning. This option is needed when using the
Infineon XC800 series microcontrollers to keep its Memory Extension Stack balanced.
3.3.7
DS390 / DS400 Options
--model-flat24 Generate 24-bit flat mode code. This is the one and only that the ds390 code generator supports
right now and is default when using -mds390. See section Memory Models for more details.
--protect-sp-update disable interrupts during ESP:SP updates.
--stack-10bit Generate code for the 10 bit stack mode of the Dallas DS80C390 part. This is the one and only that
the ds390 code generator supports right now and is default when using -mds390. 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 will 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).
--stack-probe insert call to function __stack_probe at each function prologue.
--tini-libid LibraryID used in -mTININative.
--use-accelerator generate code for DS390 Arithmetic Accelerator.
35
3.3. COMMAND LINE OPTIONS
3.3.8
CHAPTER 3. USING SDCC
Options common to all z80-related ports (z80, z180, r2k, r3ka, gbz80)
--no-std-crt0 When linking, skip the standard crt0.rel object file. You must provide your own crt0.rel for your
system when linking.
--callee-saves-bc Force a called function to always save BC.
--codeseg Use for the code segment name.
--constseg Use for the const segment name.
3.3.9
Z80 Options (apply to z80, z180, r2k and r3ka port)
--portmode= Determinate PORT I/O mode ( is z80 or z180).
--asm= Define assembler name ( is rgbds, sdasz80, isas or z80asm).
--reserve-regs-iy This option tells the compiler that it is not allowed to use register pair iy. The option can be useful
for systems where iy is reserved for the OS. This option is incompatible with --fomit-frame-pointer.
--oldralloc Use old register allocator. The old register allocator typically is faster than the current one, but the
current one generates better code. This differences are the strongest, when a high value for --maxallocs-per-node is used.
--fno-omit-frame-pointer Never omit the frame pointer.
3.3.10
GBZ80 Options
-bo Use code bank .
-ba Use data bank .
3.3.11
Intermediate Dump Options
The following options are provided for the purpose of retargetting and debugging the compiler. They provide a
means to dump the intermediate code (iCode) generated by the compiler in human readable form at various stages
of the compilation process. More on iCodes see chapter 9.1 ”The anatomy of the compiler”.
--dum-ast This option will cause the compiler to dump the abstract syntax tree to the econsole.
--dump-i-code Will dump iCodes at various stages into files named
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.3
Linearized : Yes
Subject : installation, user manual
Create Date : 2014:02:01 06:03:46-06:00
Trapped : False
PTEX Fullbanner : This is pdfTeX using libpoppler, Version 3.141592-1.40.3-2.2 (Web2C 7.5.6) kpathsea version 3.5.6
Author : SDCC development team
Title : SDCC Compiler User Guide
Keywords : 68hc08, 8032, 8051, ansi, iso, c, compiler, assembler, CPU, DS390, embedded, development, free, Floating, Point, Arithmetic, Freescale, GPL, HC08, S08, inline, Intel, ISO/IEC, 9899:1990, Linux, MAC, OS, X, manual, Maxim, mcs51, Microchip, microcontroller, open, source, PIC, Unix, Windows, Z80, Z180, Zilog, Rabbit
Producer : pdfTeX-1.40.3
Modify Date : 2014:02:01 06:03:46-06:00
Creator : LaTeX with hyperref package
Page Mode : UseOutlines
Page Count : 124