ClearSpeed Programming Language Cn

References

Primary Reference:• ClearSpeed Introductory Programming Manual, Version

3.0, January 2008

Additional References:• ClearSpeed Software Development Kit Reference

Manual, Version 3.0, January 2003. • ClearSpeed Technical Training Slides for ClearSpeed

Accelerator 620, software version 3.0, Slide Sets 1-2, December 2007– Acknowledgement: Some slides from Sets 1 & 3 have

been used in part or completely.

Basics of the Cn Language

• The Cn language is strongly based on ANSI C. • Cn accepts C block style comments (/* ... */) and

the C++ syntax (// ...) for line comments.• The goto statement is not supported.

– Both break and continue statements can be used with a label to control what loop they apply to.

• Cn uses two new keywords called multiplicity specifiers:– mono indicates a variable which has one instance,

which is stored in the mono memory. – poly indicates a variable has many instances – with

one stored in each processing element (PE).

Example

Cn Language Data Types

• Basic Types– char, unsigned char, signed char, unsigned char– short, unsigned short, signed short– int, unsigned int, signed int– long, unsigned long, signed long– float, double, long double

• Derived Types– struct– union – pointers– arrays

Note : These are exactly the same as for ANSI C.

Basic Types with Mono or Poly

• Basic types used with a multiplicity specifier.– poly int counter; // A different instance of ’counter’ exists on each

PE – mono unsigned char initial; // A single instance of ’initial’ exists in

mono memory

• Note: The default multiplicity is mono.

Pointers Type• Pointer declarations consist of the base type on the left

of “*” and the pointer object to the right.• In traditional C, it is possible to make either of these

entities constant.const int * const foo; /* const pointer to const int */ int * const bar; /* const pointer to non-const int */ const int * bing; /* non-const pointer to const int */

• Multiplicity specifiers work in similar way poly int * poly foo; /* poly pointer to poly int */ int * poly bar; /* poly pointer to mono int

(equiv to mono int * poly bar) */ poly int * bing; /* mono pointer to poly int

(equiv to poly int * mono bing) */ mono int * mono p; /* mono pointer to mono int */

Pointers to mono data

Mono pointer to mono data : Poly pointer to mono data :

Pointers to Poly Data

• For poly data, the same two types of pointers exist:– mono pointer points to the same address

in every PE’s memory. • This is the most frequently used pointer in Cn

– poly pointer can hold a different address on each PE (pointing to data on the same PE).

Mono Pointer to Poly Data(Most common type pointer in Cn)

Example : Count nr bytes with 0 value in a buffer on each PE

poly char buffer[BUFFER_SIZE]

poly char * mono ptr;

poly int count;

int i;

ptr = buffer; // Initializecount = 0; // Interate over the buffer

for (i = 0; i < BUFFER_SIZE; i++) { if (*ptr == 0) //check value pointed to

each PE

{ count++; // increment the counter

} ptr++; // move the pointer to next byte

}

Poly Pointer to Poly Data

Mono pointer to poly data :The type is (poly * poly)

Example:// prototype for poly version of

strchr() poly char * poly strchrp(const poly

char * mono s1, poly char c); poly char str[256]; // variable str is

actually a poly * mono pointer poly char * poly ptr; // a pointer

into string......... // initialize string on each

PEptr = strchrp(str, ’z’); // search for

first occurrence of ‘z’ different on each PE

Illegal Cast Problem

• Since mono and poly data are in completely separate memory space, it is not legal to cast (i.e., assign) a mono pointer to a poly pointer or vice-versa.

• First reason for this problem is that mono and poly pointer sizes are not guaranteed to be the same.

– poly memory is typically quite small and may use 16-bit pointers, while mono pointers may be 32 or 64 bits

• Second reason for this problem is that a pointer to data in poly memory will not necessarily point to anything meaningful if cast to a pointer to mono memory.

– it could point to arbitrary data or even code

Arrays

• The multiplicity specifier for an array type defines the domain for the base type.

• Example : poly char buffer[20] ;– This declaration will create an array of 20 elements in mono

memory and an array of 20 corresponding poly memory variables

– The poly specifier indicates the base type (i.e., type of elements) in mono array. In this case, the array elements are poly char.

– The declaration will also create 20 rows of elements of type char in poly memory.

• Think of 20 copies of slide picture of “mono pointer to poly data”.– The address of each of these arrays in poly space will be same .

• Warning : It is not possible to create a poly char * poly pointer using array notation since an array only specifies the base type of the array ( the implicit pointer multiplicity class of base array elements will always be mono).

• Multi dimension array are supported in Cn language as we have done in ANSI C.

Structure and Union

• They are same as ANSI C .• But multiplicity specifiers have strict rules for use inside the

structure /union.• Objects inside a structure /union definition have no multiplicity class.

Example : struct _A { int a; char b; // Multiplicity class not defined in struct definition float c; };poly struct _A my_struct; // All objects within the struct are poly mono struct _A my_struct_2; // All objects within the struct are mono • But poly struct _B { int a; // Not allowed to declare multiplicity inside defn

int b; // (but statement also declares a poly object) } my_struct_3;

Structure and Union Cont …….

Even the following syntax is also wrong :union _B { poly int a; // Illegal use of multiplicity specifier mono char b; // Illegal use of multiplicity specifier float c; };

mono union _B my_union; // Multiplicity of declaration would conflict with definition

• Only at the time of pointer declaration in structure/union the poly and mono can be used.

• Because the member itself (the pointer) cannot have a multiplicity specifier, but the object pointed to can

• Without this capability it would not be possible to have a pointer to a poly object as a member of a structure or union.

Structure and Union (cont)Example : A pointer inside a struct/union can point to an object with

multiplicity specifier,

struct _C {

mono int *a; // pointer to a mono int

poly char *b; // pointer to a poly char

};

struct _C my_struct2; // Note: this is an implicit mono object

// a is mono pointer to mono int

// b is mono pointer to poly char

struct _C poly my_struct3; // Poly object of the same type

// a is poly pointer to mono int

// b is poly pointer to poly char • The first object my_struct2 contains two members which are mono

int * mono a and poly char * mono b. • The second object my_struct3 contains two members which are

mono int * poly a and poly char * poly b

Typedefs

• Cn supports typedefs as in ANSI C• Typedef causes compiler to add type to list of types it recognizes.

Type names can be used in same way as the built-in type names, as in variable declaration, cast expressions, etc.

• The typedef statement cannot use multiplicity specifiers to define the multiplicity of the type.

• But as with structs and unions, it can define pointers to mono or poly types.

• Example: typedef short Bool // Bool variables are of type short typedef poly int p_int; // illegal use of multiplicity specifier typedef poly int * p_ptr; // ’p_ptr’ is a pointer to poly int typedef mono int * m_ptr; // ’m_ptr’ is a pointer to mono int p_ptr a; // poly int * mono a poly p_ptr a; // poly int * poly a m_ptr a; // mono int * mono a poly m_ptr a; // mono int * poly a

Mixing Mono & Poly VariablesGenerally legal to mix mono and poly variables in

expressions.• A mono value can be assigned to a poly variable. Below

expression results in 1 being copied to all instances of x.– poly int x = 1;

• An expression can mix mono and poly variables. Below statements result in y being added to

poly int x;

Int y;

x = x + y;

– Above results in y being promoted to a poly variable and added to x.

• It is not legal or meaningful to assign a poly to a mono variable.

Flow Control Statements

Cn has the same flow control statements as C.

• If statements• for loops• while loops• do .... while loops• Switch statements (not supported for poly

expressions)

The difference in the Cn flow control statements is that the conditional expression evaluated can be either a mono or poly expression.

If Statement• When the expression evaluated in the control statement

is a mono expression, the if statement branching is the same as in standard C.

• Consider the case below where the expression evaluated in control statement is a poly conditional

poly short penum( );mono int i = 0; /* Each PE now contains a different value in the penum

variable */if (penum < 32) {

. . . /* do some work */}else { . . . /* do some different work */}

– Note all PEs less than 32 execute the first branch while all other PEs execute the second branch.

– The use of “else” in this construct is optional.

If Statement (cont)

• The execution of mono operations inside an if statement with a poly conditional requires additional consideration

poly short penum( );mono int i = 0;/* Each PE now contains a different value in the penum variable */if (penum < 32) {

. . . /* do some work */i ++; /* increment mono variable i */

}else { . . . /* do some different work */

i ++;}

– Mono actions are executed first for if branch then else branch, even if there are no PEs responding to one of the branches.

– The value of i is changed to 1 in if branch and to 2 in else branch, so final value of i is 2.

– This action in Cn is different that for ASC language.• Mono statements in vacuous PE branches in ASC are not executed

For, while, and do...while loops

• These loops can be covered together, due to similarity• A loop with a poly control expression (i.e., poly loop) will

be executed until all PEs evaluate conditional as false.• Before a loop terminates, any PE that evaluates the

conditional as false is disabled for all remaining iterations– Mono expressions are executed every pass through

loop• A loop may execute zero times. In this case, mono

statements inside loop are not executed.– This feature differs from IF statement.

• Break and continue can be used inside loops to control the flow of the program

For, while, and do...while loops (cont)

• Consider following codepoly int i;mono int max_loop_count = 0;poly int this_loop_count = 0;. . . /* In this code, i is set so that it has a different value in each PE */while (i > 0){i--; /* decrement poly loop control

*/max_loop_count++; /* increment mono loop_count each loop */this_loop_count++; /* increment poly loop_count while i >0 */}

– At the end of this code, each PE will have a different value in this_loop_count (i.e., the initial value of i for this PE).

– The value of max_loop_count will be the value of the largest i across PEs.

• This value might be useful for debugging purposes.

Goto Statements

• Are selectively supported in Cn

• Must meet restriction that goto statement does not cross a poly boundary– Prohibits anything that changes the “enable

state” of PEs such as a poly if or poly while.

• As a result, not too useful.

• Use labeled break statements instead

Labeled Breaks• To provide the functionality of the goto, the break and continue

statement are provided in Cn.

• Labels are permitted in Cn but only on loop constructs.– E.g., for, while, do...while.

• The break and continue statements can specify a label, allowing the program to break out of heavily nested loops.

• Example:for_i:

for (i = 0; i < 10000; i++) { // Label for_i is associated with this for loop

while(j > 100) {do { // . . . Code for do ... while if (foo = = bar) {

break for_i } // . . . More code for do ... while

}}}

Switch Statements• Switch statements are supported in Cn and provide the

same functionality as in ANSI C• Switch statements must be mono expressions.• Example:

int val;. . . . /* Some code which sets up the value in val */switch (val) { /* only mono expressions are valid for switch */case 0:case 1: . . . . /* Do some work */ break;case 2: . . . . /* do other work */ break:default: . . . . /* etc */}

Switch Statement

• Equivalent code for poly expressions using if statement.

poly int val;

.... /* some code to set up values in val */

if ((val == 0) || (val == 1)) {

/* Select operations to be done on each PE */

}

else if (val = = 2) {

. . . . /* do other work */

}

else {

. . . . /* etc. */

}

Functions• Functions are fundamentally the same in Cn as

in ANSI C.• Cn supports function pointers.

– Multiplicity specifiers can be used to specify the return type of a function, as well as the types of any arguments.

• Functions with a mono return type are called mono functions.– Mono functions terminate (like C) when a return is

executed• Functions with a poly return type are poly

functions– Poly functions only end when all PE’s have executed

a return statement.– Additionally, execution continues to the end of the

code, so that any mono code is executed.

Function (2 out of 3)• Consider the following example

poly int bar(poly int p1, p2) { if (p1) { if (p2) { return -1; // disable appropriate PEs and save the return value of -1 } else { return 0; // disable appropriate PEs and save the return value of 0 } } . . . . (1) return 0; // PEs which are still enabled save 0 as a return value and are disabled . . . . (2)} /* return saved poly values here */

Functions (3 out of 3)

• Comments on Code– All PEs for which condition p1 is true will return a

value (either 0 or -1, depending on p2.– These PEs will be disabled until the end of the

function. – All other PEs will continue to execute the rest of the

poly code in the function. – Note that poly code at (1) will be executed by those

PEs which have not already specified a return value of 0 or -1

– This is followed by an unconditional return, so any poly code at (2) will not be executed.

– All mono code in the function will always be executed.Reference: SDK Reference manual, pg 120-121.

Summary on Function Returns

Data Transfers Between Mono and Poly

Strided Data Transfer

• memcpym2p_strided – This function transfers data from mono to poly

using strided mode: – the starting address in mono memory is

specified; this is then incremented by the specified stride value for each PE’s data.

– Every enabled PE transfers the same amount of data to the same location in poly memory; disabled PEs do not take part in the transfer.

• memcpyp2m_strided – As above, but transferring data from poly to

mono memory.

Caution on Caching and I/O• It is important to be aware of the way that the cache is used

for mono data when using the I/O functions.

• Normally, accesses by a program to mono memory are cached to provide faster access to frequently used data.

• However, I/O transfers to and from the PEs do not go via the cache— this could lead to unexpected behavior unless efforts are made to keep the contents of the cache and external memory consistent.

• The memcpy functions described above do this automatically; however, the asynchronous versions do not.

• The function dcache_flush can be used to ensure that the contents of the data cache are consistent with mono memory. This should be used if your program mixes normal accesses to mono memory with the I/O functions.

Semaphores• A semaphore is a non-negative number and

two associated operations: Signal and Wait. A signal is a atomic operation that increases

the semaphores value. Wait is a atomic operation that decrements

the semaphores value. Valid user semaphore numbers are 0-92 93-127 are reserved for system use An atomic operation is one that can not be

interrupted.

Further Information

• See the ClearSpeed Standard Library Reference Manual for further details

Running & Debugging Cn Programs

Executing Cn Programs

• The Quick Start Guide will be covered at this point– It is posted separately on the course website.– Slides in this section provide a brief summary of

Quick Start Guide.

• Another important reference is Chapters 3 & 4 of the ClearSpeed “Introductory Programming Manual”– This reference is also posted on the course website.

Executing a Cn Program• Log into the simd server while in your Kent CS

account using SSH using command

ssh username@simd.cs.kent.edu• $CSHOME should be set as in Quick Start

Guide.

• The Cn program to be executed should be moved to a subdirectory of your home directory.– You can use a program example located in

$CSHOME/examples

– We will use the Cn version of Hello World in the file

$CSHOME/examples/sdk/hello_world

Executing a Cn Program (cont)• Resetting, Compiling, and Running

– The command csreset must be used to reset the clearspeed board before running programs

• csreset

– The command cscn is used to compile.• cscn hello_world.cn

– Preceding command will produce the executable program a.csx

• As with C, the output can be renamed using the “-o” option.

– The command csrun is used to run executable code• csrun a.csx

– Only one program can be compiled and run at a time.• If the resource is being used, an error message will indicate

this.

Executing a Cn Program on the Simulator

• When developing code, it is better to use the simulator instead of the hardware.

• The command “isim” is used to start the simulator• The program is run in another SSH window in which you

are logged into clearspeed.• Before starting, the simulator must first be reset:

– csrun -s –A

• To run your program on the simulator, use following command:– Csrun –s hello_world.cn

• Until you perform a CTRL C in first ssh window, no one else can use the simulator.– Please exit the simulator as soon as you are done with it.

Overview of Activating Debugger• To use the debugger, the code has to be

compiled with the –g option.– cscn -g –o hello_world.csx hello_world.cn

• Start the debugger with command– csgbd hello_world.csx

• Connect debugger to simulator or hardware– (gdb) connect

• Next, the program source can be listed and break points set at locations where you want to examine values of mono and poly variables.

• Finally, start the program running– (gbd) run

• A slightly more complex program will better illustrate how to use the debugger.

Example Cn Parallel program• #include <stdiop.h> • #include <mathp.h> • #include <lib_ext.h>• #define SAMPLES 96 • int main() • { • poly float sine, angle;• poly int i;• // get PE number: 0...n-1 • i = get_penum(); • // convert to an angle in // the range 0 to Pi• angle = i * M_PI / SAMPLES; • // calculate sine on each PE • sine = sinp(angle);• // print out values • printfp("%d: %0.3f\n", i, sine);• return 0; • }

Using the Debugger• Compile program with debug support:

cscn -o -g sine_poly.csx sine_poly.cn • Next, start the debugger

csgdb sine_poly.csx• A message is displayed along with the debugger

prompt ‘(gdb)’.• Use ‘connect’ command to connect to hardware or

simulator. When, connected, the current location of the

program counter is displayed• To view the program source, enter “list”:

(gbd) list• Type a return at the prompt to display more of the

program ---- See next slide to see effect

Using the Debugger (cont)

• Setting break point before print statement– (gbd) break 19

• Response to above command– Breakpoint 1 at 0xx80015180: file sine_poly.cn, line

19

(gbd)• Start the program running

– (gdb) run• You can now use debugger to examine the state of

some of the variables (mono or poly). If you print a parallel variable, you will have a lot of values printed.

– (gbd) print sine

Using the Debugger (cont)

• Can limit the number of parallel variables printed by entering following command earlier– set print elements 4– Use of the “continue” command here will print the

entire list of parallel values – one PE value per line.– (gbd) continue

• Exiting the debugger– (gbd) quit

Some Basic csgdb Commands

• next– Steps to next program line (stepping over function calls

• step– Differs from next by stepping into a function call rather than

stepping over.

• help– Shows command help within csgdb

• set listsize 8– Sets number of lines displayed by “list” command. Default is 10.

• break <fcn-name>– Sets a break around a function

• break info– Lists all breaks that have been set

• tbreak– Sets temporary break. Will be deleted after it is hit the first time.

Some csgdb Commands (cont)• where

– Finds the current location of the program counter while debugging

• whatis <variablename>– Gives the data type of the variable name.

• delete <breakpointnumber>– Deletes the specified break point.

• next– Move debugger to the next line of execution.

• continue– Run till the end of the program is reached.

• set print elements 4– Limits the number of PE values displayed to 4

• up – Move up the call stack and back towards main

• down – Move down the call stack towards the end of code

Some csgdb Commands (cont)• Finish

– debugger can return from a function by using the finish command

• ignore 6 20 – Will ignore next 20 crossings of breakpoint 6.

• Print &x– print the address of variable x<mono or poly>

• print/f $8p4 – If address is $8p4 then above will print the value stored at this

address

• Continue – Continue program being debugged, after signal or breakpoint.

Note: Additional information about many of these command is given in Ch. 7 of the Introductory Programming Manual. Also, additional commands to step through functions and print values which are not covered in these slides is given in Chapter 7

Slides from ClearSpeed Training Set 3 follow

Included for possible reference purposes