4 COMPILER USE

This chapter contains the following sections:

Control Program
Compilers
Detailed Description of the Compiler Options
Include Files
Pragmas
Alias Checking
Compiler Limits

4.1 Control Program

The control program cc563 facilitates the invocation of the various components of the DSP563xx/DSP566xx family toolchain, from a single command line. cc56 is the control program for the DSP5600x. The control program accepts source files and options on the command line in random order.

The invocation syntax of the control program is:

Options are preceded by a '-' (minus sign). The input file can have one of the extensions explained below.

When you use a UNIX shell (Bourne shell, C-shell), arguments containing special characters (such as '( )' and '?') must be enclosed with "" or escaped. The -? option (in the C-shell) becomes: "-?" or -\?.

The control program recognizes the following argument types:

Normally, a control program tries to compile and assemble all source files to object files, followed by a link and locate phase which produces an absolute output file. There are however, options to suppress the assembler, linker or locator stage. The control program produces unique filenames for intermediate steps in the compilation process, which are removed afterwards. If the compiler and assembler are called subsequently, the control program prevents preprocessing of the compiler generated assembly file. Normally, assembly input files are preprocessed first.

The following options are interpreted by the control programs:

Option Description
-? or none Display invocation syntax
-Mm Mixed memory model (only allowed for cc56)
-Mr Reentrant memory model (only allowed for cc56)
-Ms Static memory model (only allowed for cc56)
-M24 24-bit memory model (only allowed for cc563)
-M1624 16/24-bit memory model (only allowed for cc563)
-M16 16-bit memory model (only allowed for cc563)
-M6 DSP566xx memory model (only allowed for cc563)
-S Generate Motorola compatible assembly file with COFF debug, stops at .asm
-Tname target hardware
-V Display version header only
-Waarg Pass argument directly to the assembler
-Wcarg Pass argument directly to the C compiler
-Wcparg Pass argument directly to the C++ compiler
-Wlcarg Pass argument directly to the locator
-Wlkarg Pass argument directly to the linker
-Wplarg Pass argument directly to the C++ pre-linker
-c++ Force .c files to C++ mode
-c Do not link: stop at .obj
-cc Compile C++ files to .c and stop
-cl Do not locate: stop at .out
-clas Set locator output file format to CLAS compatible
-cs Do not assemble: compile C and C++ files to .src and stop
-f file Read arguments from file ("-" denotes standard input)
-ieee Set locator output file format to IEEE-695 (default)
-ihex Set locator output file format to Intel Hex
-nolib Do not link with the standard libraries
-o file Specify the output file
-srec Set locator output file format to Motorola S-records
-tiof Set locator output file format to TIOF-695
-tmp Keep intermediate files
-v Show command invocations
-v0 Show command invocations, but do not start them
-wc++ Enable C and assembler warnings for C++ files

Table 4-1: Control program options

4.2 Compilers

The invocation syntax of the C compilers is:

When you use a UNIX shell (Bourne shell, C-shell), arguments containing special characters (such as '( )' and '?') must be enclosed with "" or escaped. The -? option (in the C-shell) becomes: "-?" or -\?.

The C compilers accept C source file names and command line options in random order. Source files are processed in the same order as they appear on the command line (left-to-right). Options are indicated by a leading '-' character. Each C source file is compiled separately and the compilers generate an output file with suffix .src per C source module, containing assembly source code.

The priority of the options is left-to-right: when two options conflict, the first (most left) one takes effect. The -D and -U options are not considered conflicting options, so they are processed left-to-right for each source file. You can overrule the default output file name with the -o option. The compiler uses each -o option only once, so it is possible to specify multiple -o options for multiple source files.

When you invoke c563 without any argument, the invocation syntax is displayed (same as -? option).

A summary of the options is given below. The next section describes the options in more detail.

Option Description
-? Display invocation syntax
-A[flag...] Control language extensions
-Cflag... Control compatibility options
-Dmacro[=def] Define preprocessor macro
-E[m|l|c|i |p|x] Preprocess options or emit dependencies
-Hfile Include file before starting compilation
-Idirectory Look in directory for include files
-Lnumber Specify depth of hardware stack use
-M[m|s|r][x |y|l|p][L] Select memory model: mixed, static or reentrant. Select default memory space: X, Y, L or P. Specify stack not in L memory (only for c56)
-M[24|1624|16|6]
[n][x|y|l|p][L]
Select memory model: 24-bit, 16/24-bit, 16-bit or DSP566xx. Do not use hardware stack extension. Select default memory space: X, Y, L or P. Specify stack not in L memory (only for c563).
-Oflag... Control optimization
-R[dname[=sname]] Change default section name
-Umacro Remove preprocessor macro
-V Display version header only
-csize Specify size of cache sectors for the DSP563xx
-e Remove output file if compiler errors occur
-err Send diagnostics to error list file (.err)
-f file Read options from file
-g[f|l|n|c ]... Enable symbolic debug information (unless -gn is used)
-mmask Compile for silicon mask (c563 only)
-n Send output to standard output
-o file Specify name of output file
-ppage Specify number of Patriot memory pages
-rregister Reserve a register for external use
-s Merge C source code with assembly output
-si Merge C source code and included files with assembly output
-t Display lines/min
-u Treat all 'char' variables as signed
-w[num] Suppress one or all warning messages
-wstrict Suppress warning messages 196, 303
-zpragma Identical to '#pragma pragma' in the C source

Table 4-2: Compiler options (alphabetical)

Description Option
Include options
Read options from file -f file
Include file before starting compilation -Hfile
Look in directory for include files -Idirectory
Preprocess options
Preprocess options or emit dependencies -E[m|l|c|i |p|x]
Define preprocessor macro -Dmacro[=def]
Remove preprocessor macro -Umacro
Allocation control options
Specify depth of hardware stack use -Lnumber
Change default section name -R[dname[=sname]]
Specify size of cache sectors for the DSP563xx -csize
Reserve a register for external use -rregister
Code generation options
Select memory model: mixed, static or reentrant. Select default memory space: X, Y or P. Specify stack not in L memory (only for c56) -M[m|s|r][x |y|l|p][L]
Select memory model: 24-bit, 16/24-bit, 16-bit or DSP566xx. Do not use hardware stack extension. Select default memory space: X, Y, L or P. Specify stack not in L memory (only for c563). -M[24|1624|16|6]
[n][x|y|l|p][L]
Control optimization -Oflag...
Compile for silicon mask -mmask
Specify number of Patriot memory pages -ppage
Identical to '#pragma pragma' in the C source -zpragma
Language control options
Control language extensions -A[flag...]
Control compatibility options -Cflag...
Treat all 'char' variables as signed -u
Output file options
Remove output file if compiler errors occur -e
Send output to standard output -n
Specify name of output file -o file
Merge C source code with assembly output -s
Merge C source code and included files with assembly output -si
Diagnostic options
Display invocation syntax -?
Display version header only -V
Send diagnostics to error list file (.err) -err
Enable symbolic debug information (unless -gn is used) -g[f|l|n|c ]...
Display lines/min -t
Suppress one or all warning messages -w[num]
Suppress warning messages 196, 303 -wstrict

Table 4-3: Compiler options (functional)

4.2.1 Detailed Description of the Compiler Options

Option letters are listed below. Each option (except -o; see description of the -o option ) is applied to every source file. If the same option is used more than once, the first (most left) occurrence is used. The placement of command line options is of no importance except for the -I and -o options. For the -o option, the filename may not start immediately after the option. There must be a tab or space in between. All other option arguments must start immediately after the option. Source files are processed in the same order as they appear on the command line (left-to-right).

Some options have an equivalent pragma.

With options that can be set from within EDE, you will find a mouse icon that describes the corresponding action.

-?

Option:

-?

Description:

Display an explanation of options at stdout.

Example:

c563  -?

-A

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Language Extensions. Select the Advanced language extensions radio button and enable one or more language exentensions.

-A[flags]

Arguments:

Optionally one or more language extension flags.

Default:

-A1

Description:

Control language extensions. -A without any flags, specifies strict ANSI mode; all language extensions are disabled. This is equivalent to -ACDEFKLOPRSTV and -A0.

Flags which are controlled by a letter, can be switched on with the lower case letter and switched off with the uppercase letter. Note that the usage of these options might have effect on code density and code execution performance. The following flags are allowed:

c Default. Do not check for assignments of a constant string to a non constant string pointer. With this option the following example produces no warning:

C Conform to ANSI-C by checking for assignments of a constant string to a non constant string pointer. The example above produces warning W130: "operands of '=' are pointers to different types".

d Default. Define storage for uninitialized constant rom data, instead of implicit zero initialization. The compiler generates a 'DS 1' for 'const char i[1];'.

D Uninitialized constant rom data is implicitly zero. The compiler generates a 'BSC 1' for 'const char i[1];'.

e Default. Relaxed char/short arithmetic overflow masking. Do not force conversions on small types to prevent overflows.

E Select forced conversions on small types. Normally, the excess bits are not cleared or extended on a cast from a char or a short to an int or a long. For signed values, the ANSI specification does not prescribe such behavior, for unsigned values it requires overflow masking. By default the compiler avoids the overhead involved by code to prevent overflows, but this flag forces it to insert this code. Example:

f Default. A constant in the range [-1.0,1.0> has type _fract.

F A constant in the range [-1.0,1.0> has type float.

k Default. Allow keyword language extensions such as _fract, _X and _near.

K Keyword extensions are not allowed.

l Default. 500 significant characters are allowed in an identifier instead of the minimum ANSI-C translation limit of 31 significant characters. Note: more significant characters are truncated without any notice.

L Conform to the minimum ANSI-C translation limit of 31 significant characters. This makes it possible to translate your code with any ANSI-C conforming C compiler. Note: more significant characters are truncated without any notice.

o Default. Allow language extension keyword _circ.

O Disable language extension keyword _circ. This removes the handling of m-registers from the scope of the compiler. When the _circ keyword is not allowed, the compiler does not need to save the modifier registers in an interrupt routine, and set them to the linear mode. In applications that do not need circular pointers this will decrease the interrupt latency. Of course, the application may not use the modifier registers on the assembly level either, or the interrupt handling will fail. Example:

p Default. Allow C++ style comments in C source code. For example:

P Do not allow C++ style comments in C source code, to conform to strict ANSI-C.

r Default. Enable the restrict keyword.

R Disable the restrict keyword.

s Default. __STDC__ is defined as '0'. The decimal constant '0', intended to indicate a non-conforming implementation. When one of the language extensions are enabled __STDC__ should be defined as '0'.

S __STDC__ is defined as '1'. In strict ANSI-C mode (-A) __STDC__ is defined as '1'.

t Default. Do not promote old-style function parameters when prototype checking.

T Perform default argument promotions on old-style function parameters for a strict ANSI-C implementation. char type arguments are promoted to int type and float type arguments are then promoted to double type.

v Default. Allow type cast of an lvalue object with incomplete type void and lvalue cast which does not change the type and memory of an lvalue object.

Example:

V A cast may not yield an lvalue, to conform strict ANSI-C mode.

0 - same as -ACDEFKLOPRSTV (disable all, strict ANSI-C)

1 - same as -Acdefkloprstv (default, enable all)

Example:

To disable C++ comments enter:

-C

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Output. Enable or disable the Generate Motorola compatible assembly check box.

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Code Generation. Enable or disable the following check boxes:

-C[flags]

Arguments:

One or more compatibility option flags.

Default:

-CACGRS

Description:

You can use the -C command line option to switch global compatibility options. -C without any flags specified enables all compatibility options. This is the same as specifying -Cacgrs or -C1.

Flags which are controlled by a letter, can be switched on with the lower case letter and switched off with the uppercase letter. The following flags are allowed:

a Motorola assembler compatible output. The compiler will use conditional assembly to generate assembly sources that are compatible with the Motorola assembler while retaining all features of the TASKING toolchain. The output will be a little longer and somewhat harder to read. Use this option and the -S option of the TASKING assembler together with assembler optimization options to produce an optimized Motorola compatible assembler file.

A Default. TASKING assembler output.

c All functions are generated and called with Motorola compatible calling convention, including external functions. This also means that any libraries linked in (including the C library) must have been translated with this option, otherwise conflicts in the passing of parameters will result. In most cases using the _compatible qualifier for only those functions requiring it will be more convenient and gives more efficient compilation results.

C Default. TASKING calling convention.

g Create COFF style debug information.

G Default. IEEE-695 style debug information.

r User stack pointer register is R6 instead of R7. This option is required to link objects created by the Motorola C compiler.

R Default. Register R7 is used as the user stack pointer.

s Stack pointer points to the next item above the top-of-stack item (first unused location), as used by Motorola and by TASKING compilers prior to version 2.2r1.

S Default. Stack pointer points to the top-of-stack item (last used location).

0 - same as -CACGRS (disable all, default)

1 - same as -Cacgrs (all compatibility options)

Example:

To enable all compatibility options, enter:

-c (c563 only)

Option:

-csize

Pragma:

cache_sector_size

Arguments:

The cache sector size of the used DSP563xx derivative. Only the values 128 and 256 are allowed.

Default:

-c128

Description:

Specify the size of the cache sectors for the used DSP563xx derivative. This size is used for the alignments generated for the pragma cache_align_now and for the _cache_region qualifier. The default cache size is 128.

Example:

To set the cache size to 256 enter:

Section 3.16 DSP563xx Cache Support.

-D

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Preprocessing. Define a macro (syntax: macro[=def]) in the Define user macros field. You can define more macros by separating them with commas.

-Dmacro[=def]

Arguments:

The macro you want to define and optionally its definition.

Description:

Define macro to the preprocessor, as in #define. If def is not given ('=' is absent), '1' is assumed. Any number of symbols can be defined. The definition can be tested by the preprocessor with #if, #ifdef and #ifndef, for conditional compilations. If the command line is getting longer than the limit of the operating system used, the -f option is needed.

Example:

The following command defines the symbol NORAM as 1 and defines the symbol PI as 3.1416.

-U

-E

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Preprocessing.
Enable the Preprocess only and capture output check box.

-E[m|l|c|i|p|x]

Description:

Run the preprocessor of the compiler only and send the output to stdout. When you use the -E option, use the -o option to separate the output from the header produced by the compiler.

With the -Em option, the compiler generates dependency rules which can be used by a 'make' utility.

With the -El option, you can use multi-line macros. A backslash used to continue a macro on the next source line will be expanded as a new line instead of a concatenation of the lines.

With the -Ec option, comments in the c file are preserved.

With the -Ei option, include libraries are not included in the c file while the #include statement remains present.

With the -Ep option, no #line numbers are added to the c file.

With the -Ex option, macros are not expanded while the macro definition and calls to macros remain present in the c file.

Examples:

The following command preprocesses the file test.c and sends the output to the file preout.

The following command preprocesses the file test.c which may contain multi-line macros, and sends the output to the file multi.

The following command generates dependency rules for the file test.c which can be used by mk563 (the 'make' utility).

-e

Option:

EDE always removes the output file on errors.

-e

Description:

Remove the output file when an error has occurred. With this option the 'make' utility always does the proper productions.

Example:

c563 -e test.c

-err

Option:

In EDE this option is not useful.

-err

Description:

Write errors to the file source.err instead of stderr.

Example:

To write errors to the test.err instead of stderr, enter:

-f

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Miscellaneous.
Add the option to the Additional options field.

-f file

Arguments:

A filename for command line processing. The filename "-" may be used to denote standard input.

Description:

Use file for command line processing. To get around the limits on the size of the command line, it is possible to use command files. These command files contain the options that could not be part of the real command line. Command files can also be generated on the fly, for example by the make utility.

More than one -f option is allowed.

Some simple rules apply to the format of the command file:

1. It is possible to have multiple arguments on the same line in the command file.

2. To include whitespace in the argument, surround the argument with either single or double quotes.

3. If single or double quotes are to be used inside a quoted argument, we have to go by the following rules:

a. If the embedded quotes are only single or double quotes, use the opposite quote around the argument. Thus, if a argument should contain a double quote, surround the argument with single quotes.

b. If both types of quotes are used, we have to split the argument in such a way that each embedded quote is surrounded by the opposite type of quote.

Example:

     "This has a single quote ' embedded"

or

     'This has a double quote " embedded'

or

     'This has a double quote " and \
     a single quote '"' embedded"

4. Some operating systems impose limits on the length of lines within a text file. To circumvent this limitation it is possible to use continuation lines. These lines end with a backslash and newline. In a quoted argument, continuation lines will be appended without stripping any whitespace on the next line. For non-quoted arguments, all whitespace on the next line will be stripped.

Example:

     "This is a continuation \
     line"
          -> "This is a continuation line"

     control(file1(mode,type),\
          file2(type))
          -> 
     control(file1(mode,type),file2(type))

5. It is possible to nest command line files up to 25 levels.

Example:

Suppose the file mycmds containts the following line:

The command line can now be:

-g

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Debug. Enable Generate symbolic debug information. Optionally enable the Include debug information for non referenced types check box and/or disable the Include lifetime info for all types check box.

-g[f|l|n|c]...

Default:

Generate type checking information only.

Description:

Add directives to the output files for incorporating symbolic information. This facilitates high level debugging.

With -gn you disable all debug, including type checking.

With -gl you disable the lifetime information for all types.

If you use -gf, high level language type information is also emitted for types which are not referenced by variables. Therefore, this sub-option is not recommended.

If you use -gc, code to the application is added that performs a run-time check on stack overflows. When calling a function, the stack usage of this function and the maximum number of parameters that will be passed on stack is checked. If too little reserved memory for the stack is left, a stack overflow occurs. The application halts and stays on the label _stack_error.

When the compiler is set to a high optimization level the debug comfort may decrease. Therefore, the following rules are applied:

Examples:

To add symbolic debug information to the output files, enter:

To add symbolic debug information to the output files and disable lifetime information for all types, enter:

To disable all symbolic debug information including type checking, enter:

-O

-H

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Preprocessing. Enter a filename in the Include this file before source field.

-Hfile

Arguments:

The name of an include file.

Description:

Include file before compiling the C source. This is the same as specifying #include "file" at the first line of your C source.

Example:

c563 -Hstdio.h test.c

-I

-I

Option:

Select the Project | Directories... menu item. Add one or more directory paths to the Include Files Path field.

-Idirectory

Arguments:

The name of the directory to search for include file(s).

Description:

Change the algorithm for searching #include files whose names do not have an absolute pathname to look in directory. Thus, #include files whose names are enclosed in "" are searched for first in the directory of the file containing the #include line, then in directories named in -I options in left-to-right order. If the include file is still not found, the compiler searches in a directory specified with the environment variable C56INC (for DSP5600x), C563INC (for DSP563xx). C56INC and C563INC may contain more than one directory. Finally, the directory ../include relative to the directory where the compiler binary is located is searched. This is the standard include directory supplied with the compiler package.

For #include files whose names are in <>, the directory of the file containing the #include line is not searched. However, the directories named in -I options (and the one in C56INC (C563INC for DSP563xx), and the relative path) are still searched.

Example:

c563 -I/proj/include test.c

Section Include Files.

-L

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Code Generation. For c563 only, first disable the Use hardware stack extension check box. Enter a stack level in the Max. hardware stack use outside interrupt functions field.

-Lnumber

Arguments:

The amount of hardware stack space available in a function (1..15)

Default:

-L7

Description:

Control the amount of hardware stack space available in a function. The compiler generates hardware DO loops for the innermost loops only. If a (nested) loop contains a function call, no hardware loop is generated.

Example:

c563 -L4 example.c

The code in example.c is:

Section Hardware DO and REP Loops in chapter Overview.

-M

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Code Generation. Select a Memory Model and a Default Data Memory.

-M[model][ n][mem][L] (at least one argument must be specified)

Arguments:

The memory model to be used, where model is one of:

and mem is one of:

other arguments:

Default:

-Mmx for c56
-M24x for c563

Description:

Select memory model and default memory space to be used. With -Mn (c563 only) the compiler selects pushing and popping the return address on the user stack (DSP563xx only). To circumvent hardware stack extension silicon problems on the DSP563xx , the compiler can avoid using the hardware stack for function calls by saving the return address on the user stack.

The use of default P data memory (-Mp) is not recommended because it leads to much more object code. It is meant for applications with special hardware layouts only.

Example:

c56 -Mr test.c
c563 -M16 test.c

Section Memory Models.

-m (c563 only)

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Miscellaneous. Select a chip mask.

-mmask

Arguments:

A number indicating the silicon mask for a DSP563xx/DSP566xx processor:

Description:

Specify the silicon mask to compile for.

Example:

c563 -m1 example.c

-n

Option:

-n

Description:

Do not create output files; instead, the output is sent to stdout.

Example:

c563 -n test.c

-O

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization. Select an optimization level in the Optimization box.

If you select Custom optimization in the Optimization box, you can enable or disable individual optimizations in the Custom optimization list.

-Oflags

Pragma:

optimize flags

Arguments:

One or more optimization flags.

Default:

-O1

Description:

Control optimization. If you do not use this option, the default optimization of c563 is -O1, which is an optimization level to let c563 generate the smallest code.

Flags which are controlled by a letter, can be switched on with the lower case letter and switched off with the uppercase letter. These options are described together.

All optimization flags can also be given in the source file after a #pragma optimize. However, depending on the optimization some optimize pragmas can be used on a function scope only (function level), whereas other optimize pragmas can be used on each source line (flow level). 'On function level' means that if a pragma optimize is found within a function, it is interpreted as if it was found just before the function. A #pragma optimize number must be specified outside a function body. The optimization level of each optimize pragma is described for each -O option.

An overview of the flags is given below.

a - relax alias checking (needs -Oc) (function)
c - common subexpression elimination (function)
e - expression propagation (needs -Oc) (function)
f - code flow, order rearranging (function)
g - register allocation graph optimization (function)
h - hardware loops (function)
i - move invariant code outside loop (needs -Oc) (function)
j - cache global variables in functions (function)
l - fast loops (increases code size) (function)
n - nop insertion (flow)
o - move parallelization, nop reduction (flow)
(assembler)
p - data flow, constant/copy propagation (function)
r - single instruction DO to REP (flow)
s - small code size (flow)
t - force jump table for switch statement (flow)
u - loop unrolling (function)
v - subscript strength reduction (function)
w - smart switch statement, table or chain (flow)
x - register contents tracking (flow)
y - peephole optimization (flow)
z - non sequential register allocation (flow)

0 - same as -OACEFGHIJLNOPRSTUVWXYZ (no optim)
1 - same as -OacefghijLnoprsTUvwxyz (default, size)
2 - same as -OacefghijLnOprsTUvwxyz (debug, size)
all optimizations which can be debugged,
optimized for code size
3 - same as -OacefghijLnoprSTuvwxyz (speed)
4 - same as -OacefghijLnOprSTuvwxyz (debug, speed)
all optimizations which can be debugged,
optimized for speed

Example:

c563 -OacefghijLnOprsTUvwxyz test.c

Pragma optimize in section Pragmas.

-Onumber

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization. Select an optimization level in the Optimization box. Optionally enable the Reduce optimization for debugging check box.

-Onumber

Arguments:

A number in the range 0 - 4.

Default:

-O1

Description:

Control optimization. You can specify a single number in the range 0 - 4, to enable or disable optimization. The options are a combination of the other optimization flags:

-O0 - same as -OACEFGHIJLNOPRSTUVWXYZ
Switchable optimizations switched off

-O1 - same as -OacefghijLnoprsTUvwxyz
Default. Set optimization to let c563 generate the smallest code.

-O2 - same as -OacefghijLnOprsTUvwxyz
Set optimization flags to let c563 generate the smallest code, but switch off optimizations that affect the ability to debug.

-O3 - same as -OacefghijLnoprSTuvwxyz
Set optimization flags to let c563 generate the fastest code.

-O4 - same as -OacefghijLnOprSTuvwxyz
Set optimization flags to let c563 generate the fastest code, but switch off optimizations that affect the ability to debug.

The flags 0 to 4 cannot be concatenated with other flags. For example, -Oa3c is not allowd, -OacE is allowed.

Example:

To optimize for code size and debug information, enter:

-g

-Oa / -OA

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Relaxed alias checking (requires CSE).

-Oa / -OA

Pragma:

optimize a / optimize A (on function level)

Default:

-Oa

Description:

With -Oa you relax alias checking. If you specify this option, c563 will not erase remembered register contents of user variables if a write operation is done via an indirect (calculated) address. You must be sure this is not done in your C code (check pointers!) before turning on this option.

The option -Oc must be on to use this option.

With -OA you specify strict alias checking. If you specify this option, the compiler erases all register contents of user variables when a write operation is done via an indirect (calculated) address.

Example:

An example is given in section Alias Checking in this chapter.

-Oc
Pragma optimize in section Pragmas.

-Oc / -OC

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Common subexpression elimination (CSE).

-Oc / -OC

Pragma:

optimize c / optimize C (on function level)

Default:

-Oc

Description:

With -Oc you enable CSE (common subexpression elimination). With this option specified, the compiler tries to detect common subexpressions within the C code. The common expressions are evaluated only once, and their result is temporarily held in registers.

The -Oc option must be on to enable the relax alias checking (-Oa), expression propagation (-Oe) and moving invariant code outside a loop (-Oi).

With -OC you disable CSE (common subexpression elimination). With this option specified, the compiler will not try to search for common expressions. Also relax alias checking, expression propagation and moving invariant code outside a loop will be disabled.

Example:

/*
 * Compile with -OC -O0,
 * Compile with -Oc -O0, common subexpressions are found
 *    and temporarily saved.
 */

char x, y, a, b, c, d;

void
main( void )
{
   x = (a * b) - (c * d);

   y = (a * b) + (c * d);
}

Pragma optimize in section Pragmas.

-Oe / -OE

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Expression propagation (requires CSE).

-Oe / -OE

Pragma:

optimize e / optimize E (on function level)

Default:

-Oe

Description:

With -Oe you enable expression propagation. With this option, the compiler tries to find assignments of expressions to a variable, a subsequent assignment of the variable to another variable can be replaced by the expression itself. Note that the option -Oc must be on to use this option.

With -OE you disable expression propagation.

Example:

/*
 * Compile with -OE -Oc -O0, normal cse is done
 * Compile with -Oe -Oc -O0, 'i+j' is propagated.
 */
unsigned i, j;

int
main( void )
{
      static int a;
      a = i + j;
      return (a);
}

-Oc
Pragma optimize in section Pragmas.

-Of / -OF

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Code flow optimization and order rearranging.

-Of / -OF

Pragma:

optimize f / optimize F (on function level)

Default:

-Of

Description:

With -Of you enable control flow optimizations and code order rearranging on the intermediate code representation, such as jump chaining and conditional jump reversal.

With -OF you disable control flow optimizations.

Examples:

The following example shows a control optimization:

The following example shows a conditional jump reversal:

Pragma optimize in section Pragmas.

-Og / -OG

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Register allocation graph optimization.

-Og / -OG

Pragma:

optimize g / optimize G (on function level)

Default:

-Og

Description:

With -Og you switch on optimizations in the register allocation graph. This will for one thing create instructions with the indexed addressing mode.

With -OG no optimizations on the register allocation graph are performed.

Example:

/*
 * Compile with -OG -O0
 * Compile with -Og -O0, register allocation 
 * graph optimization
 */
typedef struct
{
     long l;
     int  i;
} STRUCT;

int f(STRUCT *s_p)
{
     return s_p->i;
} 

-Oh / -OH

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Hardware loop generation.

-Oh / -OH

Pragma:

optimize h / optimize H (on function level)

Default:

-Oh

Description:

With -Oh you enable the use of hardware loops. Note that this option must be on to use the -Or option.

With -OH c563 will not use hardware DO/REP loops.

Example:

/*
 * Compile with -OH -O0, software loop is used
 * Compile with -Oh -O0, hardware DO loop is used
 */
int cumu;

void
main( void )
{
      int i;
      for ( i = 0; i<1000; i++ )
      {
            cumu = cumu + i;
      }
}

Section Hardware DO and REP Loops.
Pragma optimize in section Pragmas.

-Oi / -OI

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Move invariant code outside loop (requires CSE).

-Oi / -OI

Pragma:

optimize i / optimize I (on function level)

Default:

-Oi

Description:

With -Oi you move invariant code outside a loop. With -OI you disable moving invariant code outside a loop.

The option -Oc must be on to use the -Oi option.

Example:

/*
 * Compile with -OI -Oc -O0, normal cse is done
 * Compile with -Oi -Oc -O0, invariant code is found in
 *    the loop, code is moved outside the loop.
 */
void
main( void )
{
      char x, y, a, b;
      int i;

      for( i=0; i<20; i++ )
      {
            x = a + b;
            y = a + b;
      }
}

-Oc
Pragma optimize in section Pragmas.

-Oj / -OJ

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Cache global variables in functions.

-Oj / -OJ

Pragma:

optimize j / optimize J (on function level)

Default:

-Oj

Description:

With -Oj the compiler will cache a global variable in a register in some situations. The compiler detects when a global variable is accessed multiple times without being changed by other routines, and creates a local variable to temporarily contain the global. Afterwards, the local variable is written back to the global. This speeds up access to global variables.

With -OJ all updates of a global variable are directly written to memory.

Examples:

/*
 * Compile with -OJ -O0, 'sum' is updated twice
 * Compile with -Oj -O0, 'sum' is updated only once
 */
int sum;

void
add( int a, int b )
{
      sum += a;
      sum += b;
}

Pragma optimize in section Pragmas.

-Ol / -OL

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Generate fast loops (increases code size).

The fast loop optimization is disabled when Hardware loop generation is enabled.

-Ol / -OL

Pragma:

optimize l / optimize L (on function level)

Default:

-OL

Description:

With -Ol you enable fast loops. Duplicate the loop condition. Evaluate the loop condition one time outside the loop, just before entering the loop, and at the bottom of the loop. This saves one unconditional jump and gives less code inside a loop.

With -OL you disable fast loops.

The fast loop optimization is switched off when hardware loop generation is enabled (-Oh).

Example:

/*
 * Compile with -OL -O0
 * Compile with -Ol -O0, compiler duplicates the loop
 * condition, the unconditional jump is removed.
 */
int i;

void
main( void )
{
     for( ; i<10; i++ )
     {
          do_something();
     }
}

Pragma optimize in section Pragmas.

-On / -ON

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable NOP insertion.

-On / -ON

Pragma:

optimize n / optimize N (on flow level)

Default:

-On

Description:

With -On you enable NOP insertion. This ensures the generation of correct code. For some instructions, for example moves to and from address-type registers, a nop instruction must be inserted before the pending instruction to take care of the delay slot.

With -ON you disable NOP insertion. The assembler is instructed to insert nops instead.

Example:

/*
 * Compile with -ON, NOP is not inserted.
 * Compile with -On, NOP is inserted.
 */
int i;

void
main( void )
{
     int a;

     f();     /* call a function */
     
     for ( i = 0; i < 1; i++)
          a = i;
}

Section Replacing NOPs.
Pragma optimize in section Pragmas.

-Oo / -OO

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Generate parallel moves.

-Oo / -OO

Pragma:

optimize o / optimize O (on flow level)

Default:

-Oo

Description:

With -Oo the compiler generates the opt op option for the assembler to enable move parallelization and nop reduction.

With -OO you disable the assembler optimization.

Example:

To disable the assembler optimization, enter:

Section Replacing NOPs and section Instruction Parallelization (parallel moves) in chapter Overview.
Pragma optimize in section Pragmas.

-Op / -OP

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Constant and copy propagation (data flow).

-Op / -OP

Pragma:

optimize p / optimize P (on function level)

Default:

-Op

Description:

With -Op you enable constant and copy propagation. With this option, the compiler tries to find assignments of constant values to a variable, a subsequent assignment of the variable to another variable can be replaced by the constant value.

With -OP you disable constant and copy propagation.

Example:

/*
 * Compile with -OP -O0, 'i' is actually assigned to 'j'
 * Compile with -Op -O0, 15 is assigned to 'j', 'i' was
 * propagated
 */

int i;
int j;

void
main( void )
{
      i = 10;
      j = i + 5;
}

Pragma optimize in section Pragmas.

-Or / -OR

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Optimize single instruction hardware DO to REP loops.

-Or / -OR

Pragma:

optimize r / optimize R (on flow level)

Default:

-Or

Description:

With -Or you specify to optimize single instruction DO loops to REP loops. Note that the option -Oh (enable hardware loops) must be on to use this option.

With -OR c563 will not optimize to REP loops. This is advantageous for the interrupt latency as REP loops are not interruptible.

Example:

/*
 * Compile with -OR -Oh, a DO loop is used
 * Compile with -Or -Oh, optimize to REP loops
 */
void
f( void )
{
      int i, a;
      for ( i = 0; i<1000; i++ )
      {
            a = i;
      }
      return( a+i );
}

Section Hardware DO and REP Loops.
Pragma optimize in section Pragmas.

-Os / -OS

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Favor code size above execution speed.

-Os / -OS

Pragma:

optimize s / optimize S (on flow level)

Default:

-Os

Description:

With -Os you tell the compiler to generate smaller code. Whenever possible fewer instructions are used. Note that this may result in more instruction cycles.

With -OS you disable the smaller code optimization.

Example:

     int a, b;
     
     void
     main( void )
     {
          a = ( b != 0 );
     }

Compiling once with -Os and once -OS results in the following difference in code (-Os generates smaller code):

     bset #0,b          ; -Os:  1 word,  4 cycles
     move #>1,b         ; -OS:  2 words, 3 cycles

The number of cycles is calculated for zero wait state memory. the cycle count for the -OS option increases rapidly for non-zero wait states, so that small code will execute faster here.

Pragma optimize in section Pragmas.

-Ot / -OT

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Select an entry from the Code generation for switch statement box.

-Ot / -OT

Pragma:

optimize t / optimize T (on flow level)

Default:

-OT

Description:

With -Ot you force the compiler to generate jump tables for switch statements.

With -OT it depends on the -Ow/-OW option which switch method is used. With -OT and -OW the compiler generates a jump chain for switch statements. With -OT and -Ow the compiler chooses the best switch method possible, jump chain or jump table. So, with -OT a jump table can still be generated.

Overview:

Example:

/*
 * Compile with -OT -OW -O0, generate jump chain.
 * Compile with -Ot -OW -O0, generate jump table.
 */
int i;

void
main( void )
{
      switch (i)
      {
            case 1: i = 0;
            case 2: i = 1;
            case 3: i = 2;
            default: i = 3;
      }
}

Section Switch Statement.
Pragma optimize in section Pragmas.

-Ou / -OU

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Loop unrolling.

-Ou / -OU

Pragma:

optimize u / optimize U (on function level)

Default:

-OU

Description:

With -Ou you enable loop unrolling. With this option specified, the compiler tries to eliminate short loops by duplicating a loop body 2, 4 or 8 times. This reduces the number of branches and creates a longer linear code part.

With -OU you disable loop unrolling.

Example:

/*
 * Compile with -OU, normal loop handling
 * Compile with -Ou, loop is eliminated, body is duplicated
 */
int i, j;

void
main( void )
{
      for( i=0; i<2; i++ )      /* short loop */
      {
            j = 2 * i;
      }
}

Pragma optimize in section Pragmas.

-Ov / -OV

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Subscript strength reduction.

-Ov / -OV

Pragma:

optimize v / optimize V (on function level)

Default:

-Ov

Description:

With -Ov you enable subscript strength reduction. With this option specified, the compiler tries to reduce expressions involving an index variable in strength.

With -OV you disable subscript strength reduction.

Example:

 * Compile with -OV -O0, disable subscript strength reduction
 * Compile with -Ov -O0, begin and end address of 'a'
 * are determined before the loop and temporarily put in
 * registers instead of determining the address each
 * time inside the loop
 */
int i;
int a[4];

void
main( void )
{
      for( i=0; i<4; i++ )
      {
            a[i] = i;
      }
}

Pragma optimize in section Pragmas.

-Ow / -OW

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Select an entry from the Code generation for switch statement box.

-Ow / -OW

Pragma:

optimize w / optimize W (on flow level)

Default:

-Ow

Description:

With -Ow the compiler chooses the best switch method possible, jump chain or jump table, unless -Ot is used. -Ot forces the generation of a jump table.

With -OW the compiler generates a jump chain for switch statements, unless -Ot is used. -Ot forces the generation of a jump table.

Overview:

Example:

/*
 * Compile with -OW -OT -O0, always generate jump chain.
 * Compile with -Ow -OT -O0, choose best switch method, in this
 * case this is also a jump chain.
 */
int i;

void
main( void )
{
      switch (i)
      {
            case 1: i = 0;
            case 2: i = 1;
            case 3: i = 2;
            default: i = 3;
      }
}

Section Switch Statement.
Pragma optimize in section Pragmas.
-Ot / -OT

-Ox / -OX

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Register contents tracking.

-Ox / -OX

Pragma:

optimize x / optimize X (on function level)

Default:

-Ox

Description:

With -Ox you switch on register contents tracking.

With -OX you disable register contents tracking.

Example:

/*
 * Compile with -OX -O0
 * Compile with -Ox -O0, register contents tracking,
 * the overlay scratch section is removed
 */
int a, b, c;

void main(void)
{
      a = 2;
      switch(b)
      {
      case 1:
            c = 3;
            break;
      case 2:
      case 3:
            c = 0;
            break;
      }
}

-Oy / -OY

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Peephole optimization.

-Oy / -OY

Pragma:

optimize y / optimize Y (on flow level)

Default:

-Oy

Description:

With -Oy you enable peephole optimization. Remove redundant code. The peephole optimizer searches for redundent instructions or for instruction sequences which can be combined to minimize the number of instructions.

With -OY you disable peephole optimization.

Example:

/*
 * Compile with -OY -O0, unnecessary instructions found
 * Compile with -Oy -O0, peephole optimizer searches
 * for patterns in the generated code which can be
 * removed/combined. E.g.
 *  asl  b
 *  add  a,b
 * can be combined to: addl a,b
 */
long a;
long f(void);

void
main( void )
{
      long b;
      b = f();
      a = (a << 1) + b;
}

Pragma optimize in section Pragmas.

-Oz / -OZ

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Optimization.
Select Custom optimization in the Optimization box.
Enable or disable Non-sequential register allocation.

-Oz / -OZ

Pragma:

optimize z / optimize Z (on flow level)

Default:

-Oz

Description:

With -Oz the compiler tries to use a non sequential register allocation scheme. The compiler chooses one of the available registers in an arbitrary order. With this compiler optimization the assembler can perform a better optimization.

With -OZ the compiler uses a sequential register allocation scheme. The next available register is used. This can also be a previously allocated register that is no longer used.

Example:

/*
 * Compile with -OZ -O0, sequential register allocation, the
 *   same register is used for each allocation.
 * Compile with -Oz -O0, non sequential register allocation.
 *   Three different registers are used for the allocations.
 */
int a[3];

void
main( void )
{
      a[0] = 0;
      a[1] = 1;
      a[2] = 2;
}

Pragma optimize in section Pragmas.

-o

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Miscellaneous.
Add the option to the Additional options field.

-o file

Arguments:

An output filename. The filename may not start immediately after the option. There must be a tab or space in between.

Default:

Module name with .src suffix.

Description:

Use file as output filename, instead of the module name with .src suffix. Special care must be taken when using this option, the first -o option found acts on the first file to compile, the second -o option acts on the second file to compile, etc.

Example:

When specified:

two files will be created, file3.src for the compiled file file1.c and file2.src for the compiled file file2.c.

-p

Option:

-ppage

Arguments:

The number of Patriot memory pages (1..8).

Default:

-p2

Description:

Use this option to specify the number of Patriot memory pages. Page switch instructions depend on the specified number of memory pages.

Section 3.17 , Patriot Bank Switching Support, in chapter Language Implementation.

Example:

To set the number of Patriot memory pages to five:

-R

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Output. Add a section name replacement to the Replace default section names field.

-R[dname[ =sname]]

Arguments:

Optionally the default section name and the new section name.

Description:

You can use the -R option to replace the default section names generated by the compiler. If you use the -R option alone, the compiler replaces all section names by a name that is related to the filename of the source module. If you want to replace some of the default section names, you can specify these default names with -R. The new names are related to the module name unless the new name is specified in an optional second part. The -R option may appear more than once.

dname is the default name of the section, normally used by the compiler. sname is the new section name the compiler must generate instead.

Example:

To generate the section name mystring instead of the default section name .xstring, enter:

By specifying:

the section name .xstring has been renamed to .xstringtest.

-r

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Code Generation. Add one or more registers to the Reserve address or offset register field.

-rregister

Arguments:

A register name. The register argument must be one of the following:

For the DSP5600x and DSP563xx/DSP566xx:

In the static model (DSP5600x only) R7, M7 and N7 can also be used; in the other models these registers are used for the user stack pointer.

Description:

Reserve a register. The compiler avoids the use of the register while allocating registers. When you want to reserve a register that is to be used in, for example, an interrupt routine, it is recommended to do this application wide. This implies that you will have to specify the -r option for each module translated. If the register is not reserved in all modules, the compiler may allocate it and overwrite its contents.

Because an R and an M register are very close related, the compiler also reserves the M register when an R register is reserved. E.g., reserving R1 implies also reserving M1. You can reserve a list of registers by supplying a -r option to the compiler for each register to be reserved. Besides the user stack pointer registers, at least one combination of R and N registers must be kept free for compiler use.

Example:

The following example reserves r5, m5 and n5 while translating example.c.

-s

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Output. Enable the Merge C source file with assembly output check box.

-s[i]

Pragma:

source

Description:

Merge C source code with generated assembly code in output file.

With the optional 'i' sub-option you can specify to merge the lines of included files as well. This is useful when included files generate program code. In general it will only create longer source files due to expansion of all header files.

Example:

c563 -s test.c
;            test.c:
; 1    |int i;
; 2    |
; 3    |int
; 4    |main( void )
; 5    |{

        extern  F_START
        global  Fmain

Pragmas source and nosource in section Pragmas.

-t

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Output.
Enable the Display lines/min check box.

-t

Description:

Display the number of lines processed and the compilation speed in lines per minute.

Example:

c563 -t test.c
processed 180 lines at 8102 lines/min

-U

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Preprocessing. Undefine one or more predefined macros by disabling the corresponding check box.

-Uname

Arguments:

The name macro you want to undefine.

Description:

Remove any initial definition of identifier name as in #undef, unless it is a predefined ANSI standard macro. ANSI specifies the following predefined symbols to exist, which cannot be removed:

__FILE__ "current source filename"

__LINE__ current source line number (int type)

__TIME__ "hh:mm:ss"

__DATE__ "Mmm dd yyyy"

__STDC__ level of ANSI standard. This macro is set to 1 when the option to disable language extensions (-A) is effective. Whenever language extensions are excepted, __STDC__ is set to 0 (zero).

When c563 is invoked, also the following predefined symbols exist:

_C56 predefined symbol to identify the compiler. This symbol can be used to flag parts of the source which must be recognized by the TASKING c56 or c563 compiler only. It expands to the version number of the compiler.

_MODEL identifies for which memory model the module is compiled. It expands to a single character ('r' for reentrant, 'm' for mixed, 's' for static, 16 for 16-bit 1624 for 16/24-bit or 24 for 24-bit) that can be tested by the preprocessor. See section Memory Models for details.

_DEFMEM identifies the default data memory. See section Memory Models for details.

_DSP identifies for which DSP processor type the module is compiled. It expands to a number. For example, '0' for the DSP5600x processor type, '3' for the DSP563xx and '6' for the DSP566xx processor types.

_STKMEM identifies the data memory used for the stack; this is either default data memory, or L memory. See section Memory Models for details.

_USP identifies the user stack pointer register from the -Cr/-CR option (r6 or r7). For r6 its value is '6', for r7 it is '7'.

_CACHE_SECTOR_SIZE
Expands to the value set with the option -csize or with the pragma cache_sector_size (c563 only).

These symbols can be turned off with the -U option.

Example:

c563 -U_MODEL test.c

-D

-u

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Code Generation.
Enable the Treat 'char' variables as unsigned check box.

-u

Description:

Treat 'character' type variables as 'signed character' variables. By default char is the same as specifying unsigned char. With -u char is the same as signed char.

Example:

With the following command char is treated as signed char:

-V

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Miscellaneous.
Add the option to the Additional options field.

-V

Description:

Display version information.

Example:

c56 -V
TASKING DSP5600x C compiler     vx.yrz Build nnn
Copyright 1995-year Altium BV   Serial# 00000000
c563 -V
TASKING DSP563xx/6xx compiler   vx.yrz Build nnn
Copyright 1996-year Altium BV   Serial# 00000000

-w

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Diagnostics. Select Display all warnings, Suppress all warnings or Suppress only certain warnings.
If you select Suppress only certain warnings, type the numbers of the warnings you want to suppress in the corresponding field.

-w[num]
-wstrict

Arguments:

Optionally the warning number to suppress.

Description:

-w suppresses all warning messages. -wnum only suppresses the given warning. -wstrict suppresses all "strict" warning messages (196, 303).

Example:

To suppress warning 135, enter:

-z

Option:

Select the Project | Project Options... menu item. Expand the C Compiler entry and select Miscellaneous.
Add the option to the Additional options field.

-zpragma

Arguments:

A pragma as listed in section Pragmas.

Description:

With this option you can give a pragma on the command line. This is the same as specifying '#pragma pragma' in the C source. Dashes ('-') on the command line in the pragma are converted to spaces. A dash prefixed by another dash or space is never translated, so it is still possible to specify a dash for negative numbers as pragma argument.

Example:

The following options

are equivalent with:

Section Pragmas.

4.3 Include Files

You may specify include files in two ways: enclosed in <> or enclosed in "". When an #include directive is seen, c563 used the following algorithm trying to open the include file:

1. If the filename is enclosed in "", and it is not an absolute pathname (does not begin with a '\' for PC, or a '/' for UNIX), the include file is searched for in the directory of the file containing the #include line. For example, in:

PC:

UNIX:

c563 first searches in the directory ..\..\source ( ../../source for UNIX) for include files.

If you compile a source file in the directory where the file is located (c563 test.c), the compiler searches for include files in the current directory.

This first step is not done for include files enclosed in <>.

2. Use the directories specified with the -I options, in a left-to-right order. For example:

Select the Project | Directories... menu item. Add one or more directory paths to the Include Files Path field.

PC:

UNIX:

3. Check if the environment variable C563INC exists (for the DSP563xx; use C56INC for the DSP5600x). If it does exist, use the contents as a directory specifier for include files. You can specify more than one directory in the environment variable C563INC by using a separator character. Instead of using -I as in the example above, you can specify the same directory using C563INC:

PC (Command Prompt window):

UNIX:

     C563INC=../../include
     export C563INC
     c563 demo.c
     setenv C563INC ../../include
     c563 demo.c

4. When an include file is not found with the rules mentioned above, the compiler tries the subdirectory include in the directory that contains the subdirectory with the c563 binary. For example:

PC:

UNIX:

The compiler determines run-time which directory the binary is executed from to find this include directory.

The DSP5600x installation directory is c56.

A directory name specified with the -I option or in C563INC (C563INC for the DSP5600x) may or may not be terminated with a directory separator, because c563 (or c56 respectively) inserts this separator, if omitted.

When you specify more than one directory to the environment variable C563INC , you have to use one of the following separator characters:

PC:

UNIX:

4.4 Pragmas

According to ANSI (3.8.6) a preprocessing directive of the form:

causes the compiler to behave in an implementation-defined manner. The compiler ignores pragmas which are not mentioned in the list below. Pragmas give directions to the code generator of the compiler. Besides the pragmas there are two other possibilities to steer the code generator: command line options and keywords. The compiler acknowledges these three groups using the following rule:

Command line options can be overruled by keywords and pragmas. Keywords can be overruled by pragmas. So the pragma has the highest priority.

This approach makes it possible to set a default optimization level for a source module, which can be overridden temporarily within the source by a pragma.

c563 supports the following pragmas:

asm

Insert the following (non preprocessor lines) as assembly language source code into the output file. The inserted lines are not checked for their syntax. The code buffer of the peephole optimizer is flushed. Thus the compiler will stop optimizations such as NOPs removal, parallel moves and peephole pattern replacement and resumes these optimizations after the endasm pragma as if it starts at the beginning of a function.

For advanced assembly in-lining, intrinsic functions can be used. The defined set of intrinsic functions cover most of the specific DSP56xxx features which could otherwise not be accessed by the C language.

For more information on intrinsic functions see section 3.13 Intrinsic Functions.

asm_noflush

Same as asm, except that the peephole optimizer does not flush the code buffer and assumes register contents remain valid.

endasm

Switch back to the C language.

The section Inline Assembly in the chapter Language Implementation contains more information.

cache_align_now

Aligns current address at a cache boundary. This can be done only once per function. The alignment may introduce an unusable memory alignment gap at the beginning of the section.

cache_sector_size

Specify the size of the cache sectors for the used DSP563xx derivative. This size is used for the alignments generated for the pragma cache_align_now and for the _cache_region qualifier. The size is either 128 or 256 words. The default cache size is 128. This pragma is equivalent to the command line option -c and it is given in the form:

cache_region_start

Mark start position of a cache region. The argument of the pragma must be a function pointer defined with the _cache_region qualifier.

cache_region_end

Mark end position of a cache region. The argument of the pragma must be a function pointer defined with the _cache_region qualifier.

The section 3.16 DSP563xx Cache Support contains more infomation about these pragmas.

iterate_at_least_once
no_iterate_at_least_once (default)

For the compiler it is not always possible to determine whether a loop condition is valid for the first iteration. In these cases the compiler will generate code to check the loop end condition for this first iteration. If it is certain that the loop will be executed at least once, this code is superfluous. The iterate_at_least_once pragma tells the compiler that the following loop(s) are iterated at least once and that it does not have to generate the code for checking the end condition for the first iteration. This pragma remains valid until the no_iterate_at_least_once pragma is specified.

If the iterate_at_least_once pragma is specified for a loop which is not iterated at least once, the results of the loop will not be as expected.

Example:

The compiler does not know the start value of i, and therefore cannot predict whether the end condition is true for the first loop. The iterate_at_least_once pragma tells the compiler that the condition is valid for the first iteration and the compiler will not generate code to test the condition for the first iteration.

For do-while loops (which are always iterated at least once) the iterate_at_least_once pragma indicates that the do-while loop end condition is false for the first iteration.

Example:

jumptable_memory

Specifies in which memory the switch jump table is generated. The default is P memory. Please note that changing the default into X or Y memory will result in a (possibly large) entry in the copy table! This pragma is given in the form:

where, mem can be either P, X or Y.

optimize

Controls the amount of optimization. The remainder of the source line is scanned for option characters, which are processed like the flags of the -O command line option. Please refer to the -O option for the list of available flags. This pragma is given in the form:

Depending on the optimization some optimize pragmas can be used on a function scope only (function level), whereas other optimize pragmas can be used on each source line (flow level). 'On function level' means that if a pragma optimize is found within a function, it is interpreted as if it was found just before the function. A #pragma optimize number must be specified outside a function body. The optimization level of each optimize pragma is described for each flag of the -O option.

endoptimize

End a region that was optimized with a #pragma optimize. The pragma endoptimize restores the situation as it was before the corresponding pragma optimize. #pragma optimize/endoptimize pairs can be nested.

pack_strings

After this pragma all string constants will be packed string constants. Using such a string as a not packed string (e.g., passing to a function with a not packed string argument type) will yield a type conflict error.

nopack_strings

After this pragma string constants will no longer be packed string constants.

The section 3.18 Packed Strings contains more information about packed strings.

source

Same as -s option. Enable mixing C source with assembly code.

nosource

Default. Disable generation of C source within assembly code.

4.5 Alias Checking

When alias checking is turned on (-OA option) the compiler assumes that each pointer may point to any object created in the program, so when any pointer is dereferenced, all register contents are assumed to be invalid afterwards.

When it is known that aliasing problems do not occur in the written C source, alias checking may be relaxed (-Oa option or #pragma optimize a). This is the default. Note that the option -Oc (or #pragma optimize c) must be on to use this option. Relaxing alias checking may reduce code size.

Example 1:

int i;

void
func( )
{
   char  * p;
   char  c;
   char  d;

   if( i )
      p = &c;
   else
      p = &d;

   c = 2;
   d = 3;

   *p = 4;   /* may write to 'c' or 'd'                          */
             /* --> aliasing object 'c' or 'd'                   */

   i = c;    /* '*p' might have changed the value of 'c',        */
             /* so 'c' may not be used from register             */
             /* contents, but MUST be read from memory           */
             /* --> alias checking MUST be ON in this case       */
}

Example 2:

int i;

void
func( char *p )
{
   char  c;
   char  d;

   c = 2;
   d = 3;

   *p = 4;     /* cannot write to 'c' or 'd', but to some other 
                  object */

   i = c;      /* '*p' cannot have changed the value of 'c',     */
               /* so 'c' may be used from register contents      */
               /* --> alias checking may be OFF in this case     */
}

Example 3:

typedef union
{
   struct
   {
      unsigned int exponent;
      _fract fraction;
   } binary;
   double value;
} _FDEF;

#define _FBIAS 127

double
frexp_excerpt( double value, int *exp )
{
   double loc_value = value;  /* prevent taking address of 
                                 argument 'value' */
                
   *exp = ((_FDEF *)&loc_value)->binary.exponent - _FBIAS;
   ((_FDEF *)&loc_value)->binary.exponent = _FBIAS;

   if ( loc_value == -1.0 )
   {
      *exp += 1;      
      return( -0.5 );
   }
   return( loc_value );
}

The compiler will make a CSE on loc_value, ignoring the write through the type casted pointer because it is of a different type.

4.6 Compiler Limits

The ANSI C standard [1-2.2.4] defines a number of translation limits, which a C compiler must support to conform to the standard. The standard states that a compiler implementation should be able to translate and execute a program that contains at least one instance of every one of the limits listed below. c563's actual limits are given within parentheses.

Most of the actual compiler limits are determined by the amount of free memory in the host system. In this case a 'D' (Dynamic) is given between parentheses. Some limits are determined by the size of the internal compiler parser stack. These limits are marked with a 'P'. Although the size of this stack is 200, the actual limit can be lower and depends on the structure of the translated program.


Copyright © 2002 Altium BV