ClearSpeed Programming Language C n

1. ClearSpeed Programming Language Cn

2. Reference Primary Reference: • ClearSpeed Introductory Programming, Version 3.1 for Cn language, September 2010 Earlier Primary Reference: • ClearSpeed Introductory Programming Manual, Version 3.0, January 2008 Comments: • Version 3.1 is the official document for the current Cn language for our SDK and advanced e710 accelerator • These slides were initially prepared using the earlier Version 3.0. Not many changes have occurred in basic material covered in these slides. • If you notice any updates I need to make in these slides, please let me know.

3. Additional References • ClearSpeed Technical Training Slides for ClearSpeed Accelerator 620, software version 3.0, Slide Sets 1-2, December 2007 • Acknowledgement: Some slides from ClearSpeed Slide Sets 1 & 3 have been used in these slides in part or completely. • ClearSpeed Manuals Document Pack, Version 3.1 • SDK 3.1 Reference Manual • Cn Standard Library Reference Manual • CSX600/CSX700 Instruction Set Reference Manual

4. 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).

5. Example

6. Cn Language Data Types • Basic Types • char, unsigned char, signed 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 : Above are exactly the same as for ANSI C.

7. 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: If not indicated, the default multiplicity is “mono”.

8. Comments about Complex Data Types • There are many data type possibilities, and some are fairly complex. • We will only provide an brief overview of these. • If one of the more complex types is needed, you should study its details carefully at that point. • It is probably best to minimize use of more complex constructs initially. • In Potter’s ASC language, the use of pointers is avoided altogether by use of the associative functions. • An important use here is to specify which data is to be moved between mono memory and poly memory.

9. 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 */

10. Mono pointer to mono data : Poly pointer to mono data : Pointers to mono data

11. 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).

12. 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; // Initialize count = 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 } Mono Pointer to Poly Data(Most common type pointer in Cn)

13. 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 PE ptr = strchrp(str, ’z’);// search for first occurrence of ‘z’ different on each PE Poly Pointer to Poly Data

14. 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

15. Arrays in Cn The multiplicity specifier for an array type defines the domain for the base type. • Example :poly int 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 int. • The declaration will also create 20 rows of elements of type int 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 . • This is effectively the same as poly int * mono • See diagram of this type two slides back. • Warning : It is not possible to create a poly int * poly pointer using array notation as an array only specifies the base type of the array • The implicit pointer multiplicity class of base array elements is always mono. • Multi dimension array are supported in Cn language as we have done in ANSI C. • Reference: For Example above, see SDK Reference Manual 11.5.3

16. Structure and Union(Skip) • 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;

17. Structure and Union Cont …….(Skip) 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. • Due to fact that 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.

18. Structure and Union (cont)(Skip) 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

19. Typedefs • Cnsupports 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

20. Mixing Mono & Poly Variables Generally 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. 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.

21. Flow Control Statements • Cn has the same flow control statements as C. • Ifstatements • forloops • whileloops • 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. • It is important to understand how these work and how they differ from the statements for C.

22. 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.

23. 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

24. 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

25. For, while, and do...while loops(cont) • Consider following code poly 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.

26. 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

27. 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 }}}

28. 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 */ }

29. Switch Statement • Equivalent code for poly expressions using nested if statements. 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. */ }

30. 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.

31. Function (2 out of 3) 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 */ • Consider the following example

32. 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.

33. Summary on Function Returns

34. Data Transfers Between Mono and Poly • The following coverage will provide an short overview of what transfers are possible • Additionally, some information about the speed of transfers is included. • However, this is primarily just a light overview. • Additional investigations will be needed before using these transfer functions.

38. 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.

40. 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.

44. 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.

45. Further Information • See the ClearSpeed Standard Library Reference Manual for further details

49. Running & Debugging Cn Programs

50. 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.