C-DVM compiler
User's guide
* May, 2000 *

- last edited 17.10.00 -


Contents

1 Functions of the Compiler
2 Invoking the Compiler
3 Debugging mode of compilation
4 Compiler diagnostics

4.1 Fatal errors
4.2 Scanner and parser diagnostics
4.3 File level and statement errors
4.4 Declarations
4.5 Declaration and usage of DVM-objects
4.6 DISTRIBUTE, ALIGN, TEMPLATE
4.7 malloc & access to distributed data
4.8 PARALLEL loop
4.9 SHADOW
4.10 REDUCTION
4.11 Procedures
4.12 Data tracing
4.13 Miscellaneous


1 Functions of the Compiler

C-DVM is the ANSI-C language extended by special annotations for specifying parallel execution of a program. These annotations are called DVM-directives.

C-DVM compiler (C-DVM converter) is DVM-system tool to translate an annotated C-DVM program to a SPMD stile program in ANSY-C language containing Run-Time library (Lib-DVM) calls. Then the resulted program (with INCLUDE-file cdvm_c.h) be translated by any C-compiler and linked with Lib-DVM library.

Besides "pure" parallel code the compiler can produce an "extended" debugging code to use features of the performance analyzer (PPPA) and debugger (the data tracer), and "sequential" program (i.e. without Lib-DVM calls) with debugging extensions used to obtain performance characteristics of source program and so called "reference" trace for debugging in trace comparison mode.

2 Invoking the Compiler

The following command line starts the C-DVM compiler:

dvm cdv [<options>] <infile>

where:

<infile> - file name (without extension) containing source program in C-DVM language to be compiled. The file must has extension .cdv. The current directory only is searched for the source file. It is assumed that the file is correct with respect to C syntax and compiled by standard C compiler. C-DVM compiler does not perform standard C syntax and semantics checking.

<options> - one or more options from the following list:

-o <outfile> - output file name for converted program (optional; by default it is <infile>.c). Output file is placed to the current directory. If C-DVM compiler detected errors, the file is not created. Error messages are output to cdvm_msg file.

-s – generate sequential program (to obtain trace and performance characteristics), debugging extensions only); by default, parallel program is generated;

-p – generate parallel program;

Trace modes:

-d1 – tracing only DVM-array updates,
-d2 – tracing DVM-arrays reading and updates,
-d3 – tracing all data updates,
-d4 – tracing all data reading and updates;

Note1. Loop iteration execution is traced in any mode.

Performance analyzer modes:

-e1 – measuring parallel loops and enclosing sequential loops,
-e2 – measuring user defined INTERVALs,
-e3 = e1 + e2,
-e4 = e3 + all other sequential loops;

Note 2. Only sequential loops, specified by DO and FOR macros are taken into account. Standard C loops (for, while, do) are not measured.

Others:

-v – output informational messages to the screen,
-w – all warnings are enabled,
-w- – no warnings are enabled,
-xN – system table size (-x16 – by default),

3 Debugging mode of compilation

There are two ways to debug C-DVM programs:

Some debugging levels are defined for each of them.

Functional debugging levels. Functional debugging level (leveld) is an integer (from 0 to 4) specifying the events, the debugger is informed about:

0 - no events;
1 - arrays modifying,
2 - distributed arrays modifying and usage,
3 - all the variables modifying,
4 - all the variables modifying and usage.

Performance debugging levels. The performance debugging level (levele) is an integer (from 0 to 4) specifying the program segments examined as execution intervals. The performance characteristics may be estimated for each of the intervals.

0 - no intervals;
1 - parallel loops and surrounding sequential loops;
2 - statement intervals, specified in the program by INTERVAL directive;
3 - combination of the levels 1 and 2;
4 - all the loops and intervals specified by INTERVAL directive.

A sequence of statements is declared as interval by the following directives:

DVM( INTERVAL [<integer-expression>]) {
<statement-sequence>
}

Each interval must satisfy statement block conditions:

In other words transfer of control from outside the interval into it and from within the interval to a statement outside it is prohibited.

Program fragments. A program may be divided into separate statement fragments to be debugged. The fragment is specified by the folowing directive:

DVM(DEBUG <fragment-number> [ <parameter>] ) {
<statement-sequence>
}

<fragment-number> ::= <integer>
<parameter> ::= -d<leveld>
  | -e<levele>
  | -d<leveld> -e<levele>

where:

-d specifies maximal allowed level of functional debugging for the fragment,
-e specifies maximal allowed level of performance debugging for the fragment,
<leveld> – integer number (from 0 to 4),
<levele> – integer number (from 0 to 4).

Each fragment must satisfy statement block conditions.

The enclosed fragments are permitted. Let f1 denotes the set of statements that compose surrounding fragment, l1 denotes the debugging level specified in DEBUG directive for the fragment, and f2 , l2 denote the set of statements and debugging level of enclosed fragment. Then maximal allowed level is l1 for set f1  f2 and l2 for set f2.

By default, whole program is the fragment with number 0 and its maximal allowed debugging level is -d4 -e4.

Debugging levels specified by compiler options.

The debug level for whole program is defined by options:

-d<leveld> - for functional debugging,
-e<levele> - for performance debugging.

The default options are –d0 and –e0.

The debugging levels for program fragments are defined by options:

-d<leveld> [:<fr-list>]
-e<levele> [:<fr-list>]

where:

fr ::= Lfr [ - Hfr ]
Lfr ::= <fragment-number>
Hfr> ::= <fragment-number>

The condition Lfr Hfr must be satisfied.

fr-list is a list where each element is fragment number or a range of fragment numbers. Let m be the debugging level specified for some fragment in DEBUG directive. If the level l is specified for the fragment by compiler option, the fragment debugging level is min( m , l ).

For detailes see "DVM-program debugging. User's guide" and "Debugging DVM-program performance. User's guide".

4 Compiler diagnostics

4.1 Fatal errors

Fatal errors terminate execution. They include:

4.2 Scanner and parser diagnostics

The scanner is stopped and outputs a message in the case of:

The parser is stopped with the message:

Unexpected <token>
Possible terminal symbol is not found.

<construct> expected
Required construction is not found;

<construct> syntax
Error in construct.

4.3 File level and statement errors

The 'main' should get the command line parameters
The command line contains parameters to initialize Lib-DVM. Therefore it is necessary to specify
int main (int argn, char ** args)

The 'main' should 'return <rc>;' for the Lib-DVM
The main function should return a value. The value is passed to operating system by the Lib-DVM.

Implicitly created objects must precede 'main'
Declarations of implicitly created objects must precede main function. Such objects are distributed arrays, templates, processors arrangements (and so on) with constant dimensions. The are created automatically at the beginning of main function, so all of them should be known at this point.

'main' required for implicitly created objects
Distributed arrays, templates, processors arrangements (and so on) with constant dimensions are created at the beginning of the main function, so the main function must exist in the file.

DVM-operator outside function
DVM-statement is placed outside function.

Misplaced declarative DVM-directive
Declarative directive is found among statements or in a statement.

DVM-directive requires a non-empty statement
This directive is a specification of a statement. The directive should not be separated from the statement by ‘;’.

Should be followed by the ';'
This directive is a statement itself. So semicolon must follow the directive.

TASK_REGION must be a sequence of ON-blocks or ON-loop
TASK_REGION
can not contain statements without ON directive.

Not allowed in a PARALLEL loop
Collective operation can not be performed on a separate processor.

4.4 Declarations

DVM-object should be defined as 'void * '
DVM syntax convention.

DVM-arrays may be int, long, float, or double only
DVM-system limitation.

Scalar can not be distributed
Scalars are always implicitly replicated.

DVM-pointer should be a C-pointer
DVM(* …)
requires <type> * <id>.

'*' is valid only with DISTRIBUTE and ALIGN
'*' can be used in DISTRIBUTE and ALIGN directives only.

Only 1D-arrays of ptrs to DVM-arrays supported
Compiler limitation. Only one-dimensional arrays of pointers to distributed arrays are allowable.

Unsupported declarator for distributed data
Unsupported declarator for distributed data.

Can not initialize DVM-objects
An initializer can't be specified for DVM objects and arrays.

DVM declarator syntax error
Other syntax error in declarator.

4.5 Declaration and usage of DVM-objects

Undefined
Undefined identifier is used in DVM-directive. Sequential program may be compiled correctly if the identifier is used in DVM-directives only.

This is not a DVM-object
The object used in DVM-directive is not DVM-object.

Rank error
Rank in usage does not match with rank of definition.

This is not a REDUCTION_GROUP
DVM-directive requires parameters of definite class.

This is not a SHADOW_GROUP
DVM-directive requires parameters of definite class.

This is not a REMOTE_GROUP
DVM-directive requires parameters of definite class.

This is not a TASK
DVM-directive requires parameters of definite class.

An array of void* required
The array of (void *) pointers is required.

MAP-target must be a processors section
C-DVM syntax.

ON-target must be an element of task array
C-DVM syntax.

4.6 DISTRIBUTE, ALIGN, TEMPLATE

'[*]' is only allowed in DVM( * DISTRIBUTE...)
C-DVM syntax.

Array should be defined as DVM(DISTRIBUTE...)
DVM-array should be defined as DVM(DISTRIBUTE...)

GENBLOCK requires non-distributed 1D integer array
Semantic constrain.

ONTO target must be a TASK or a PROCESSORS

ONTO target must be an element of task array

Align-expression syntax: [-][A*]var[+B|-B]
Only linear expression are allowed.

Already used align|do variable
Two alignment expressions with the same variable are not allowed.

The base of a static should be a (known) static
All “static” DVM arrays are automatically malloc’ed at the beginning of the main function in order of declaration. The base of ALIGNed array must exist before creation of this array.

The parameter should be a (non-static) TEMPLATE
Wrong parameter of the CREATE_TEMPLATE directive.

4.7 malloc & access to distributed data

DVM-malloc requires (dim1*...*sizeof(...))
Distributed array creation requires of all dimensions of this array.

Is it 'sizeof(<element type>)' ?
The last multiplier of malloc is supposed to be the size of array element.

Only DVM-arrays may be malloc'ed
The DVM-pointer is used to create DVM array by malloc function.

Static DVM-array can not be malloc'ed
Static arrays can't be created by malloc function. They are created automatically at the beginning of main function.

Only DVM-pointers may be assigned
DVM arrays may be assigned only by malloc(). Only DVM-pointers may be assigned by values of other pointers and DVM-arrays.

REDISTRIBUTE|REALIGN must follow this malloc
To properly create (malloc) DVM array that has been declared without distribution/alignment stuff, this information must be provided here.

Can not assign to REMOTE
REMOTE_ACCESS
semantic constrain.

Can not get REMOTE address
REMOTE_ACCESS
semantic constrain. The & operator can't be applied to remote-access data.

Possible non-local assignment. Use DVM(OWN)
Left hand side of assignment in sequential branch is element of distributed array.

Only 1..4-D arrays may be distributed
Syntax limitation. Distributed arrays of 1-4 rank are supported only.

Too many distributed dimensions
Special case of “Rank error

Not all distributed dimensions
Special case of “Rank error”.

4.8 PARALLEL loop

Duplicated or incompatible sub-directive
PARALLEL
loop header constrain. Incompatible subdirectives are SHADOW_RENEW, SHADOW_START and SHADOW_WAIT subdirectives and all subdirectives with ON <task>.

Too many headers in the PARALLEL loop
Use {} to separate distributed header and internal sequential one.

Not enough headers in the PARALLEL loop
DVM allows tightly nested parallel loops only.

Not a PARALLEL loop variable
The variable in a distributed DO/FOR header must be listed in the PARALLEL loop header.

PARALLEL loop variables disordered
Loop variable must be listed it the PARALLEL header in the same order they are used in DO/FOR loop headers.

Variable already used
Two alignment expressions with the same variable are not allowed.

Loop variable required
Empty ‘[ ]’ in PARALLEL loop header are not allowed.

Only 'long' or 'int' scalar loop variables allowed
Lib-DVM limitation.

4.9 SHADOW

Declared (or default) maximum width exceeded
The width necessary for a shadow operation exceeds the width provided in array creation (declaration).

1D-array's shadow has no CORNERs
Warning. Keyword is useless in this context.

4.10 REDUCTION

Reduction operation syntax or semantics violation:

Undefined RVAR
Wrong type of RVAR
Undefined RLOC
Wrong type of RLOC
Unallowed RVAR-expression
Unallowed RLOC-expression

4.11 Procedures

Parameter should be defined as DVM(*...)
DVM arrays are passed by reference.

Only DISTRIBUTE and ALIGN are valid for parameter
TEMPLATE
s, SHADOW_GROUPs, PROCESSORS and so on can not be passed as parameters.

4.12 Data tracing

These are warnings:

This initialization will not be traced
Because of unsupported type, or main already generated.

Can not trace ++, --, +=, -=, ...
Compiler limitation.

Can not trace multiple assignment
Compiler limitation.

Can not trace this type
Unsupported type.

4.13 Miscellaneous

Can fread-fwrite DVM-arrays as a whole only
Subscripted distributed array in I/O operation is used. Lib-DVM limitation.

Do you mean multiple index?
Rewrite A[a,b] as either A[(a.b)] or A[a][b] depending on your intention.

Not yet implemented... or error