SDCC(1)

📦 version 4.5.0, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 sdcc — Small Device C Compiler 💖

General Commands Manual · section 1 · the vibe? iconic. the facts? untouched. 🦋

✨ NAME ✨

sdcc — Small Device C Compiler 💅

✨ SYNOPSIS ✨

sdcc [options] filename

⚠️ WARNING ⚠️

okay bestie, read this one, it's important 🫶
The information in this man page is an extract from the full documentation of SDCC, and is limited to the meaning of the options.
For complete and current documentation, refer to the SDCC Compiler User Guide.

🌸 DESCRIPTION 🌸

So. SDCC is a free open source, retargettable, optimizing ANSI-C compiler, and it was literally designed for 8 bit Microprocessors. Main character energy from day one. 👑

The current version targets Intel MCS51 based Microprocessors (8031, 8032, 8051, 8052, etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and Zilog Z80 based MCUs (z80, z180, gbz80, Rabbit 2000/3000). It can be retargeted for other microprocessors, and support for Microchip PIC is under development. 👀

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. ✨

SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker. SDCC has extensive language extensions suitable for utilizing various microcontrollers and underlying hardware effectively. (yes we said it twice, the docs said it twice, we don't gatekeep 💀)

The compiler also allows inline assembler code to be embedded anywhere in a function. In addition, routines developed in assembly can also be called. 🧚

🎀 PROCESSOR SELECTION OPTIONS 🎀

Pick your fave. Choose your fighter. It's giving build-your-own-target. 💫

  • -mmcs51 — Generate code for the MCS51 (8051) family of processors. This is the default processor target. ✨
  • -mds390 — Generate code for the DS80C390 processor.
  • -mds400 — Generate code for the DS80C400 processor.
  • -mz80 — Generate code for the Z80 family of processors.
  • -mhc08 — Generate code for the GameBoy Z80 processor. (yep, that's literally what it says here, we're keeping it word for word, no editing 💀)
  • -mz80 — Generate code for the Zilog Z80 family of processors. (yep, again 😭 it's listed twice and we respect the list)
  • -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 2000 / Rabbit 3000 family of processors. Check XXXXX"
  • -mgbz80 — Generate code for the GameBoy Z80 processor (Not actively maintained).
  • -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).
  • -mtlcs900h — Generate code for the Toshiba TLCS-900H processor (Not maintained, not complete).
  • -mxa51 — Generate code for the Phillips XA51 processor (Not maintained, not complete).
  • -mstm8 — Generate code for the STM8 processor.

🌈 PREPROCESSOR OPTIONS 🌈

The preprocessor said "let me handle it" and honestly? she did. 💅

  • -I<path> — The additional location where the pre processor will look for <..h> or ..h files.
  • -D <macro[=value]> — Command line definition of macros. Passed to the pre processor.
  • -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 #included in it. This rule may be a single line or may be continued with \-newline if it is long. The list of rules is printed on standard output instead of the preprocessed C program. -M implies -E. 🔥
  • -C — Tell the preprocessor not to discard comments. Used with the -E option.
  • -MM — Like -M but the output mentions only the user header files included with #include "file". System header files included with #include <file> are omitted.
  • -A question(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.
  • -A question — (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.

🔗 LINKER OPTIONS 🔗

Where the code actually gets stitched together. The linker is the friend who makes the group plan happen. 🫶

  • -L, -lib-path<absolute path to additional libraries> — 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 <Value> — 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 <Value> — The start location of the code segment, default value 0. Note when this option is used the interrupt vector table is also relocated to the given address. The value entered can be in Hexadecimal or Decimal format, e.g.: --code-loc 0x8000 or --code-loc 32768.
  • --stack-loc <Value> — The initial value of the stack pointer. The default value of the stack pointer is 0x07 if only register bank 0 is used, if other register banks are used then the stack pointer is initialized to the location above the highest register bank used. eg. if register banks 1 & 2 are used the stack pointer will default to location 0x18. The value entered can be in Hexadecimal or Decimal format, eg. --stack-loc 0x20 or --stack-loc 32. If all four register banks are used the stack will be placed after the data segment (equivalent to --stack-after-data). 🌸
  • --stack-after-data — This option will cause the stack to be located in the internal ram after the data segment.
  • --data-loc <Value> — The start location of the internal ram data segment, the default value is 0x30. The value entered can be in Hexadecimal or Decimal format, eg. --data-loc 0x20 or --data-loc 32.
  • --idata-loc <Value> — The start location of the indirectly addressable internal ram, default value is 0x80. The value entered can be in Hexadecimal or Decimal format, eg. --idata-loc 0x88 or --idata-loc 136.
  • --out-fmt-ihx — The linker output (final object code) is in Intel Hex format. (This is the default option). ✨
  • --out-fmt-s19 — The linker output (final object code) is in Motorola S19 format.

👑 MCS51 OPTIONS 👑

  • --model-large — Generate code for Large model programs see section Memory Models for more details. If this option is used all source files in the project should be compiled with this option. In addition the standard library routines are compiled with small model, they will need to be recompiled. 😭
  • --model-small — Generate code for Small Model programs see section Memory Models for more details. This is the default model.

🦋 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.
  • --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).
heads up bestie, that option name starts with an underscore in here: _--stack-10bit — we're keeping it exactly as it appears, no cap. 💀

💜 Z80 Options 💜

  • --callee-saves-bc — Force a called function to always save BC.
  • --no-std-crt0 — When linking, skip the standard crt0.o object file. You must provide your own crt0.o for your system when linking. 🫡

🔥 OPTIMIZATIONS OPTIONS 🔥

Okay bestie, these are the "actually, don't optimize that part" knobs. Use with caution, they're giving last-resort energy.

  • --nogcse — says no to global subexpression elimination. Use it if the compiler is being dramatic and making your stack/data spaces undesirably large to stash its temporaries. When that happens you'll get a warning message, and the compiler will tell you exactly how many extra bytes it allocated. It's recommended that you do NOT use this, and #pragma NOGCSE can turn off global subexpression elimination for one single function instead. So targeted, so slay.
  • --noinvariant — says no to loop invariant optimizations. You might turn it off for the same reasons as the previous one. Wanna know the deets on loop optimizations? See section Loop Invariants. It's recommended that you do NOT use this, and #pragma NOINVARIANT can turn off invariant optimizations for just one function. 💅
  • --noinduction — says no to loop induction optimizations; see section strength reduction for the whole lore. It is recommended that this option is NOT used, and #pragma NOINDUCTION can turn off induction optimizations for one function only.
  • --nojtbound — will not generate the boundary condition check when switch statements get implemented using jump-tables. It is recommended that this option is NOT used, and #pragma NOJTBOUND can turn off boundary checking for jump tables for one function only.
  • --noloopreverse — will not do loop reversal optimization. That's it, that's the whole vibe.

✨ OTHER OPTIONS ✨

  • -c, --compile-only — will compile and assemble the source, but will not call the linkage editor. So close, yet so far.
  • -E — run only the C preprocessor. Preprocess all the C source files you specified and output the results to standard output.
  • --stack-auto — every function in the source file gets compiled as reentrant, meaning the parameters and local variables get allocated on the stack. 🫶 If you use this option, all source files in the project should be compiled with it. No halfsies.
  • --xstack — uses a pseudo stack in the first 256 bytes in the external ram for allocating variables and passing parameters.
  • --callee-saves function1[,function2][,function3].... — okay so by default the compiler uses a caller saves convention for register saving across function calls, but that can cause unnecessary register pushing & popping when you call small functions from larger functions. This option switches the register saving convention for the function names you specify. The compiler won't save registers when calling these functions, and no extra code gets generated at the entry & exit for these functions to save & restore the registers they use — this can SUBSTANTIALLY reduce code & improve run time performance of the generated code. In the future the compiler (with interprocedural analysis) will be able to determine the appropriate scheme to use for each function call. > DO NOT use this option for built-in functions such as _muluint..., and if you use it for a library function, the appropriate library function needs to be recompiled with the same option. If the project is multiple source files, then all the source files should be compiled with the same --callee-saves option string. Periodt.
  • --debug — when this option is used the compiler generates debug information, which can be used with the SDCDB. That debug info gets collected in a file with a .cdb extension.
  • --regextend — this option is obsolete and isn't supported anymore. 👻
  • --noregparms — this option is obsolete and isn't supported anymore. Also a ghost.
  • --peep-file<filename> — lets you use additional rules for the peep hole optimizer.
  • -S — stop after the stage of compilation proper; do not assemble. The output is an assembler code file for the input file you specified.
  • -Wa_asmOption[,asmOption]...] — pass the asmOption to the assembler.
  • -Wl_linkOption[,linkOption]...] — pass the linkOption to the linker.
  • --int-long-reent — the Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant. Note: by default these libraries are compiled as non-reentrant.
  • --cyclomatic — makes the compiler generate an information message for each function in the source file. That message has some important info 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. Nerd stats, but make it ✨iconic✨.
  • --float-reent — the floating point library is compiled as reentrant.
  • --nooverlay — the compiler will not overlay parameters and local variables of any function; see section Parameters and local variables for more details.
  • --main-return — use this when the code generated is called by a monitor program. The compiler will generate a 'ret' upon return from the 'main' function. The default option is to lock up, i.e. generate a 'ljmp '. (yes, with the space, we don't question it 💀)
  • --no-peep — disable peep-hole optimization.
  • --peep-asm — pass the inline assembler code through the peep hole optimizer. This can cause unexpected changes to inline assembler code, so please go through the peephole optimizer rules defined in the source file tree '<target>/peeph.def' before using this option. Read before you leap, bestie.
  • --iram-size <Value> — causes the linker to check if the internal ram usage is within limits of the given value.
  • --nostdincl — prevents the compiler from passing on the default include path to the preprocessor.
  • --nostdlib — prevents 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.

🦋 INTERMEDIATE DUMP OPTIONS 🦋

The following options are provided for the purpose of retargetting and debugging the compiler. They give you a way to dump the intermediate code (iCode) generated by the compiler in human readable form at various stages of the compilation process. So much lore, honestly.

  • --dumpraw — makes the compiler dump the intermediate code into a file named <source filename>. dumpraw just after the intermediate code has been generated for a function, i.e. before any optimizations are done. The basic blocks at this stage are ordered in the depth first number, so they may not be in sequence of execution. (yes, that double space in the filename is real, we respect the original 💅)
  • --dumpgcse — creates a dump of iCode's, after global subexpression elimination, into a file named <source filename>.dumpgcse.
  • --dumpdeadcode — creates a dump of iCode's, after deadcode elimination, into a file named <source filename>.dumpdeadcode.
  • --dumploop — creates a dump of iCode's, after loop optimizations, into a file named <source filename>.dumploop.
  • --dumprange — creates a dump of iCode's, after live range analysis, into a file named <source filename>.dumprange.
  • --dumlrange — will dump the life ranges for all symbols. (yep, that's the spelling, don't come for me 🙈)
  • --dumpregassign — creates a dump of iCode's, after register assignment, into a file named <source filename>.dumprassgn.
  • --dumplrange — creates a dump of the live ranges of iTemp's.
  • --dumpall — makes all the above mentioned dumps get created. Go big or go home. 🔥

🌈 COPYING 🌈

The entire source code for the compiler is distributed under GNU General Public License. Free as in freedom, bestie. 👑

💖 SEE ALSO 💖

sdcpp(1), asxxxx(1), aslink(1).

🎀 AUTHOR 🎀

This manual page was written by Aurelien Jarno <aurel32@debian.org>, for the Debian GNU/Linux system (but may be used by others). Give them their flowers. 🌸

And that's the whole page, bestie — SDCC(1) is the name on the tin, no cap, and you've officially read the entire thing. Go compile something cute. 💅✨🦋

📦 where this page comes from