3.16 Pragmas
Keywords: sdccman

#
3.16 Pragmas

Pragmas are used to turn on and/or off certain compiler options. Some of them are closely related to corresponding command-line options (see section sec:Command-Line-Options).
Pragmas should be placed before and/or after a function, placing pragmas inside a function body could have unpredictable results.
SDCC supports the following #pragma directives:

- save - this will save most current options to the save/restore stack. See #pragma restore.
- restore - will restore saved options from the last save. saves & restores can be nested. SDCC uses a save/restore stack: save pushes current options to the stack, restore pulls current options from the stack. See #pragma save.
- 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 off the register saving convention for the function names specified. The compiler will not save registers when calling these functions, extra code need to be manually inserted at the entry and exit 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) may be able to determine the appropriate scheme to use for each function call. If —callee-saves command line option is used (see page lyx:–callee-saves-function1=00005B,function2=00005D=00005B,function3=00005D...), the function names specified in #pragma callee_saves is appended to the list of functions specified in the command line.
- exclude none | {acc[,b[,dpl[,dph[,bits]]]]} - The exclude pragma disables the generation of pairs of push/pop instructions in Interrupt Service Routines. The directive should be placed immediately before the ISR function definition and it affects ALL ISR functions following it. To enable the normal register saving for ISR functions use #pragma exclude none. See also the related keyword __naked.
- less_pedantic- the compiler will not warn you anymore for obvious mistakes, you're on your own now ;-(. See also the command line option —less-pedantic lyx:–less-pedantic.
  More specifically, the following warnings will be disabled: comparison is always [true/false] due to limited range of data type (94); overflow in implicit constant conversion (158); [the (in)famous] conditional flow changed by optimizer: so said EVELYN the modified DOG (110); function '[function name]' must return value (59).
  Furthermore, warnings of less importance (of PEDANTIC and INFO warning level) are disabled, too, namely: constant value '[]', out of range (81); [left/right] shifting more than size of object changed to zero (116); unreachable code (126); integer overflow in expression (165); unmatched #pragma save and #pragma restore (170); comparison of 'signed char' with 'unsigned char' requires promotion to int (185); ISO C90 does not support flexible array members (187); extended stack by [number] bytes for compiler temp(s) :in function '[function name]': [] (114); function '[function name]', # edges [number] , # nodes [number] , cyclomatic complexity [number] (121).
- disable_warning <nnnn> - the compiler will not warn you anymore about warning number <nnnn>.
- nogcse - will stop global common subexpression elimination.
- noinduction - will stop loop induction optimizations.
- noinvariant - will not do loop invariant optimizations. For more details see Loop Invariants in section8.1.4.
- noiv - Do not generate interrupt vector table entries for all ISR functions defined after the pragma. This is useful in cases where the interrupt vector table must be defined manually, or when there is a secondary, manually defined interrupt vector table (e.g. for the autovector feature of the Cypress EZ-USB FX2). More elegantly this can be achieved by omitting the optional interrupt number after the __interrupt keyword, see section 3.8 about interrupts.
- noloopreverse - Will not do loop reversal optimization
- nooverlay - the compiler will not overlay the parameters and local variables of a function.
- stackauto- See option —stack-auto and section 3.6 Parameters and Local Variables.
- 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.
- opt_code_balanced - The compiler will attempt to generate code that is both compact and fast, as long as meeting one goal is not a detriment to the other (this is the default).
- std_sdcc89 - Generally follow the C89 standard, but allow SDCC features that conflict with the standard.
- std_c89 - Follow the C89 standard and disable SDCC features that conflict with the standard.
- std_sdcc99 - Generally follow the C99 standard, but allow SDCC features that conflict with the standard.
- std_c99 - Follow the C99 standard and disable SDCC features that conflict with the standard.
- std_c11 - Follow the C11 standard and disable SDCC features that conflict with the standard.
- std_c2x- Follow the C2X standard and disable SDCC features that conflict with the standard.
- codeseg <name>- Use this name (max. 8 characters) for the code segment. See option —codeseg.
- constseg <name>- Use this name (max. 8 characters) for the const segment. See option —constseg.

The preprocessor SDCPP supports the following #pragma directives:

- preproc_asm (+ | -) - switch the __asm __endasm block preprocessing on / off. Default is on. Below is an example on how to use this pragma.

> #pragma preproc_asm -
> /* this is a c code nop */
> #define NOP ;
> void foo (void)
> {
> ...
> while (--i)
> NOP
> ...
> __asm
> ; this is an assembler nop instruction
> ; it is not preprocessed to ';' since the asm preprocessing is disabled
> NOP
> __endasm;
> ...
> }

> The pragma preproc_asm should not be used to define multilines of assembly code (even if it supports it), since this behavior is only a side effect of sdcpp __asm __endasm implementation in combination with pragma preproc_asm and is not in conformance with the C standard. This behavior might be changed in the future sdcpp versions. To define multilines of assembly code you have to include each assembly line into it's own __asm __endasm block. Below is an example for multiline assembly defines.

> #define Nop __asm \
> nop \
> __endasm
> #define ThreeNops Nop; \
> Nop; \
> Nop
> void foo (void)
> {
> ...
> ThreeNops;
> ...
> }

- sdcc_hash (+ | -) - Allow naked hash in macro definition, for example:
  #define DIR_LO(x) #(x & 0xff)
  Default is off. Below is an example on how to use this pragma.

> #pragma preproc_asm +
> #pragma sdcc_hash +
> #define ROMCALL(x) \
> mov R6_B3, #(x & 0xff) \
> mov R7_B3, #((x » 8) & 0xff) \
> lcall __romcall
> ...
> __asm
> ROMCALL(72)
> __endasm;
> ...

Some of the pragmas are intended to be used to turn-on or off certain optimizations which might cause the compiler to generate extra stack and/or data space to store compiler generated temporary variables. This usually happens in large functions. Pragma directives should be used as shown in the following example, they are used to control options and optimizations for a given function.

> #pragma save /* save the current settings */
> #pragma nogcse /* turnoff global subexpression elimination */
> #pragma noinduction /* turn off induction optimizations */
> int foo ()
> {
> ...
> /* large code */
> ...
> }
> #pragma restore /* turn the optimizations back on */

The compiler will generate a warning message when extra space is allocated. It is strongly recommended that the save and restore pragmas be used when changing options for a function.