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.
- 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:
- 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. Default is off. See also the —pedantic-parse-number
command line option lyx:-pedantic-parse-number.
Below is an example on how to use this pragma. Note: this functionality
is not in conformance with standard!
#pragma pedantic_parse_number +
#define LO_B(x) ((x) & 0xff)
unsigned char foo(void)
{
unsigned char c=0xfe-LO_B(3);
return c;
}
- 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.