Home

C* User`s Guide

1. 49 5 9 4 The Second hee 253 5 9 5 The Third Debugging Session 57 5 9 6 The Final Debugging Session 60 Appendix Man 65 About This Manual Objectives of This Manual This rnanual describes how to develop compile execute and debug C programs on a Connection Ma chine system Intended Audience Readers are assumed to have a working knowledge of the C language and of the UNIX operating systern Organization of This Manual Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Appendix A Introduction Chapter 1 is a brief overview Developing a C Program This chapter describes C libraries and associated header files and explains how to call Paris functions CM library functions and CM Fortran subroutines from a C program Compiling a C Program Chapter 3 describes the C compiler and its command line options Executing a C Program on a CM 2 Chapter 4 describes how to run a C program Debugging a C Program This chapter describes functions useful in debugging a C program and contains a sample debugging session Man Pages This appendix contains man pages for the cs compiler command and C libraries vii C User 5 Guide Associated Documents The following document about C appears in the s
2. 19 3 1 1 Basic Options 22 40 8840 ese series Sed ves be awa he 19 Getting Help The help 21 Changing the Optimization Level The O Option 21 Choosing a Specific Version of the Compiler release Opio codo eI iE ve 21 Choosing a Specific Version of Paris The ucode Option 22 Printing the Version Number The version Option 22 3 1 2 Options in Common with cc c g 1 L pg and U Options 22 3 2 A Closer Look at the Compilation 23 3 2 1 Advanced Options 23 Using Another C Compiler The Option 23 Specifying a Different C Pre processor The Option 24 Displaying Compilation Steps dryrun Option 24 Putting c Files through the C Compilation Phase The force Option hex 24 Keeping the Intermediate File The keep Option 24 Suppressing Line Directives The noline Option 25 Displaying Names of Overloaded Functions The overload PimctOn 25 Turning On Verbose Compilation The verbose Option 25 Creating Assembly Source Files The S Option 25 Changing the location of Temporary Files The temp Option 25 Turning Off Warnings The warn Option 26 Specifying Options for Other Components
3. 10 Parameters DE uS 12 A pointer is prime p to a one dimensional parallel 13 char that will have non zero elements in all positions 14 where the index is a prime number Ib 16 Side effects 17 18 find primes alters the one dimensional parallel char 19 that is pointed to by is prime p 20 Chapter 5 Debugging a C Program 47 21 Calling constraints 752222 of 23 The shape of the parallel char pointed to by 24 is prime p must be the current shape and all 25 positions must be active 26 27 Algorithm 28 29 This function will use the Sieve of Eratosthenes to 30 find the prime numbers That is it will iterate gd G through all numbers that are indices to the one 32 dimensional paraliel char pointed to by is prime p 33 34 void find primes char current is prime p 35 char current is candidate 36 int minimum prime 37 38 39 40 15 candidate pcoord 0 gt FIRST PRIME TRUE FALSE 41 42 do 43 where is candidate 44 minimum prime pcoord 0 45 where pcoord 0 minimum 46 is candidate FALSE 47 minimum prime is prime p TRUE 48 49 while is candidate 50 51 52 main 53 shape MAXIMUM PRIME s 54 55 char s is prime 56 inti 57 58 59 find primes amp is prime 60 for i 0 i MAXIMUM PRIME
4. Connection Machine System C User s Guide Version 6 0 2 June 1991 Thinking Machines Corporation 1 Cambridge Massachusetts First printing November 1990 Second printing with corrections June 1991 The information in this document is subjectto change without notice and should not be construed as a commitmentby Thinking Machines Corporation Thinking Machines Corporation reserves the right to make changes to any products described herein to improve functioning or design Although the information in this document has been reviewed and is believed to be reliable Thinking Machines Corporation does not assume responsibility or liability for any errors that may appear in this document Thinking Machines Corporation does not assume any liability arising from the application or use of any information or product described herein c isa registered trademark of Thinking Machines Corporation Connection Machine is a registered trademark of Thinking Machines Corporation CM 2 CM Paris CM Fortran and DataVault are trademarks of Thinking Machines Corporation and CMSSL are trademarks of Thinking Machines Corporation VAX and ULTRIX are trademarks of Digital Equipment Corporation Sun Sun 4 and SunOS are registered trademarks of Sun Microsystems Inc UNIX is a registered trademark of AT amp T Bell Laboratories Copyright 1991 by Thinking Machines Corporation All rights reserved Thinking Machines Corporation
5. Passing Parallel Variables two step process is required to pass a C parallel variable to a CM Fortran subroutine First declare a scalar variable of type CMC descriptor t For example CMC descriptor t desc a Next make this variable a descriptor for the parallel variable by calling the function CMC wrap pvar With a pointer to the parallel variable as its argument and assigning the result to the scalar variable For example if p1 is the parallel variable you want to pass call the CMC wrap pvar function as follows desc wrap pvar amp pl You can wrap a parallel variable of any shape You can then pass the descriptor to the CM Fortran subroutine For example CMC CALL FORTRAN subroutine desc a The descriptor stores the address field ID of the parallel variable and the parallel variable is passed by reference in this way The CM Fortran subroutine can then operate on the parallel variable referenced by the descriptor C code can operate on the parallel variable even after it has been wrapped You can reuse a descriptor in a program but first you must free it see below Passing Scalar Variables Pass scalar variables to a CM Fortran subroutine by reference For example int 51 CMC CALL FORTRAN subroutine amp s1 Chapter 2 Developing C Program 17 Freeing the Descriptors When you are through using a descriptor free it by calling zee desc with the des criptor as
6. 245 First Street Cambridge Massachusetts 02142 1264 617 234 1000 876 1111 Contents About This Manual 2 2252 ee Re ete eee Ga p REA vii Customer Support idu adii bre RR PERRA ETE oe ix Chapter 1 Introduction ecco re ee Rin caves 1 11 Developing C Program 1 12 Compiling C Program 1 13 Executing Program 2 14 Debugging 2 Chapter 2 Developing a C Program 3 21 169268 FeS 1 ta ers TCR 3 2 LI CA Keywords EAR bmw is 3 2 1 2 Reserved Identifiers 4 2 13 Default Shape 2 029 e085 erobern 4 22 Header Flles ses me cite AG Sead ae ENS 5 22 1 lt gt 5 222 The lt stdlib h gt File 6 22 3 The lt string h gt File 6 2 24 Header Files and Keywords 7 2 3 Calling Paris from C 2 rl LR Deua eR c eee TE 7 2 3 1 The Relationship between Paris and 7 2 3 2 Calling Paris Functions 8 C Parallel Variables and Paris Field IDs lads 9
7. Shape views vp set 0 0 stopped in find primes at line 43 in file primes cs 43 where is candidate Why are there two Shape regions defined The first one vp set 2 clearly refers to shape s since we defined the region 0 9 for shape s the second one is much larger and that is apparently the region that was being printed for is candidate Why isn t is candidate of shape s This gives us enough evidence to figure out the bug there is no with statement making s the current shape Without the with statement is candidate becomes a parallel vari able of the default shape which for this implementation of C is the shape physical see Chapter 2 We now quit dbx dox quit and add the required with statement 5 9 4 The Second Session Here is the revised program with the revision shown in bold 1 define MAXIMUM PRIME 16384 3 define FALSE 0 4 define TRUE 1 5 define FIRST PRIME 2 34 void find primes char current is prime p 35 char current is candidate 36 int minimum prime 37 38 39 54 C User 5 Guide 40 is candidate pcoord 0 gt FIRST PRIME TRUE FALSE 41 42 do 43 where is candidate 44 minimum prime pcoord 0 45 where pcoord 0 minimum prime 46 is candidate FALSE 47 minimum prime is prime p TRUE 48 49 while is candidate 50 51 52 main 53 shape MAXIMUM PRIME s 54 55 is prime 56 int
8. 2 21 25 alias command 38 call command 38 using 35 38 deallocate_shape 6 debugging 2 4 compiler option required for 22 obtaining help in 46 printing values of pointers to parallel variables 41 42 table of C functions for 37 default type changing 39 developing C programs 1 E elements 8 executing C programs 2 F field IDs 45 and parallel variables 9 function prototyping 23 Index 81 G gprof 1 and pg compiler option 22 using with C 18 graphics and visualization 12 H header files 5 7 and C keywords 7 VO library calling from 12 identifiers reserved 4 intermediate files See e files K keywords and header files 7 list of C 3 make utility 1 18 lt math h gt 5 memcmp 6 memcpy 6 memmove 6 memory layout and Paris functions 11 memset 6 O optimization level 21 overloaded functions invoking from within dbx 36 overloading 25 36 P 11 6 11 parallel arrays and C debugging functions 40 and Paris fields 10 parallel structures and C debugging functions 40 parallel variables and field IDs 9 and Paris fields 8 assigning values to in debugging 44 45 changing the display of 42 43 printing values of 40 43 Paris calling from C 7 11 choosing a specific version of 22 relationship to C 7 Paris functions allocating fields using 8 manipulating the context using 8 pfree 6 physical 4 pointers
9. i 61 if ilis prime 62 printf The next prime number is d n i 63 ud idi 48 User 5 Guide We want to use the following algorithm 1 Take as candidates all non negative integers up to a specified value 2 Eliminate 0 and 1 as candidates 3 The smallest remaining candidate is a prime call it p 4 Remove p and all multiples of p from the set of candidates 5 Goto step 3 To implement this algorithm primes cs uses a function called primes find primes declares a parallel variable called is candidate whose coordinates rep resent possible prime numbers The function makes positions 0 and 1 inactive to eliminate 0 and 1 as candidates then finds the minimum active position initially this is 2 this is a prime number It then turns off all positions whose coordinates are multiples of the coor dinate of this minimum active position these coordinates no longer represent possible primes The element at the minimum active position is set to 1 in a parallel variable pointed toby is prime p find primes goes through a do loop repeating these steps until there are no candidates left The coordinates of the elements set to 1 in the parallel variable pointed to by is prime p represent the prime numbers 5 9 2 Compiling the Program We begin by trying to compile the program cs primes primes cs g But primes cs does not make the compiler happy The
10. the cmps command to list the processes that are running under timesharing on a sequencer a Use the cmsetsafety command to turn Paris level safety checking on and off Use the emcoldboot command to reset the state of the CM hardware to which you are attached Use the qdel command to delete a batch request from a queue Use the gstat command to obtain information about batch requests in a queue See the CM User 5 Guide and the on line man pages for complete information on these commands Chapter 5 Debugging C Program C programs can be debugged using a standard debugger like dbx C provides a variety of functions that you can call within a debugger Among other things these functions let you Define a region within a shape to use for debugging Print values of a parallel variable Make positions active or inactive Assign values to a parallel variable These functions stay in effect during the execution of a program in dbx They output their results to the standard error device Table 2 summarizes the debugging functions discussed in this chapter As described in Chapter 3 note that debugging is difficult when your program is compiled with the option 5 1 Using dbx To use dbx or another debugger invoke it from within an interactive subshell spawned by cmattach For example cmattach Attaching the Connection Machine system name coldbooting done Attached to 8192 physical processo
11. 00 to turn off all optimization Compile using the compiler version number Link with CM software version number Print the compiler version number Options in common with cc C pname def g Idir Ldir Alib output Pg Advanced options compiler pre processor dryrun force noline overload 5 temp directory verbose y warn Zcomp switch Compile only Define a symbol name to the preprocessor Produce additional symbol table information for debugging required for C debugging functions Search the specified directory for include files Add dir to the list of directories in the object library search path Link with the specified library Change the name of the final output file to output Link with profiling libraries for use with gprof Undefine the C preprocessor symbol name Use the specified C compiler Specify a different C pre processor Show but do not execute compilation steps Force c files through the C compilation phase Keep the intermediate e file Suppress line directives in the output C file Display names used by the compiler for overloaded functions Create an assembly source file for each input source file Change the location of temporary files to directory Display informational messages during compilation Suppress warnings from the C compilation phase Pass option switch to component comp where com
12. FIRST PRIME TRUE FALSE dbx n 52 User 5 Guide stopped in find primes at line 43 in file primes cs 43 where is candidate We now call the appropriate C debugging functions We use CMC define region to define a region from 0 through 9 of shape s We call CMC define type to define is candidate as a char We define width to specify that is candidate is to be printed as an int with field width 2 dox dr s O 9 Region set to 0 9 Stopped in find primes at line 43 in file primes cs 43 where is candidate dbx dt is candidate CMC char stopped in find primes at line 43 in file primes cs 43 where is candidate dbx dw CMC char 2 stopped in find primes at line 43 in file primes cs 43 where is candidate Finally we call CMC print region to print the values of is candidate dbx ppr is candidate But something has gone very wrong Instead of printing out 10 values the debugger prints out screen after screen of numbers Puzzled we call CMC print status to see what s going on dbx pstat CMC debugging status Default type CMC double Default formats CMC bool ld 2 short int 10 long int 101d CMC float 10 49 double 104 long doubie 109 Parallel variable types field id 458760 type CMC char Chapter 5 Debugging C Program 53 Shape regions vp set 2 0 9 vp set 0 0 8191 Context stacks
13. FIRST PRIME 2 58 C User 5 Guide 34 void find primes char current is prime p 35 char current is candidate 36 int minimum prime ST 38 39 40 is candidate 0 gt FIRST PRIME TRUE FALSE 41 42 do 43 where is candidate 44 minimum prime lt pcoord 0 45 where pcoord 0 minimum prime 46 is candidate FALSE 47 minimum prime is prime p TRUE 48 49 while is candidate 50 51 52 main 53 shape MAXIMUM PRIME s 54 55 is prime 56 inti 57 58 with s 59 find primes amp is prime 60 for i 0 i MAXIMUM PRIME i 61 if i is prime 62 printf The next prime number is d n i 63 This time we pick up the story where we started to go wrong last time in the inner where statement of nd primes where we want to set the context to the positions whose coor dinates are multiples of minimum prime Once again we have already defined the region the width and the type of is candidate dbx n stopped in find primes at line 45 in file primes cs 45 where pcoord 0 minimum prime dbx n stopped in find primes at line 46 in file primes cs 46 is candidate FALSE dbx ppr is candidate Row 0 0 1 1 1 1 1 1 1 1 stopped in find primes at line 46 in file primes cs 46 is candidate FALSE This looks right The even numbered positions are active We leave the i
14. The Z Option 26 MET Contents 3 3 3 4 Chapter 4 4 1 4 2 43 4 Chapter 5 541 52 53 54 5 5 gua eats E 26 Compiling a C Program that Calls CM Fortran 27 Executing a C Program on CM 29 DVEIVIGW aches rt ad E tata dee 29 Obtaining Direct 30 4 2 1 Executing the Program Immediately 30 4 2 2 Obtaining an Interactive 31 4 2 3 Options for cmattach 31 Waiting for Resources 31 Specifying a Sequencer an Interface and a CM 31 Obtaining Exclusive Access 32 Obtaining Batch Access 32 4 3 11 Submitting a Batch Request 32 4 3 2 Options for qsub 33 Specifying a 33 Recerving Malls Coke xatd rap epi PR 33 Setting the Priority 33 Specifying Output Files 34 Other CM Commands 34 Debugging 35 Using dbx ilv hes ARES EN DR 35 5 1 1 Invoking Over
15. i 57 58 with s 59 find primes amp is prime 60 for i 0 i MAXIMUM PRIME i 61 if i is prime 62 printf The next prime number is d n i 63 We now debug this new version We issue the same debugging calls to define the region the width and the type of is candidate Let s pick up the story where we left off in the previous session as we attempted to print out a region of candidate at line 43 ppr is candidate Row stopped in find primes at line 43 in file primes cs 43 where is candidate 1 This is the behavior we want We then enter the where statement and see what happens to the context Chapter 5 Debugging C Program dox n stopped in find primes at line 44 in file primes cs 44 minimum prime lt pcoord 0 dbx ppr is candidate Row Stopped in find primes at line 44 in file primes cs 44 minimum prime pcoord 0 This too is the behavior we want positions 0 and 1 are now inactive Note that inactive positions are shown in parentheses We go to the next line of code and print out the value of minimum prime dbx n stopped in find primes at line 45 in file primes cs 45 where 0 minimum prime dbx p minimum prime minimum prime 2 This is correct 2 is the lowest coordinate of all the active positions We step again and print out the region for is candidate dbx n stopped in find primes at line 46 in fi
16. is candidate 50 51 52 main 53 shape MAXIMUM PRIME s 50 C User 5 Guide 54 55 char s is prime 56 inti 57 58 59 find primes amp is prime 60 for i 0 i MAXIMUM PRIME i 61 if il is prime 62 printf The next prime number is dWMn i 63 We confidently compile the revised program As expected there are no errors so we attach to a CM In the cmattach subshell we first set Paris safety on this is recommended when you are going to be debugging emsetsafety on And then we run the program primes Unfortunately something seems to be wrong The program isn t printing out a list of prime numbers it isn t doing anything It seems to be stuck in an infinite loop We use Ctrl C to kill the program and we go into dbx dbx primes Reading symbolic information Read 1693 symbols We have created aliases for the C debugging functions and some frequently used dbx commands We print them out to refresh our memory dbx alias call define format dr call CMC define region dt call CMC define type dv call CMC define view dw call CMC define widtn off call CMC off offr call CMC off region on call CMC on call on region 1 call help popc call CMC pop context PP call CMC print ppr Call CMC print region pstat call CMC status pushc call CMC push context set call CMC set setr call CMC set
17. memcpy and related functions is in terms of chars while the size argument for the boolean versions is in terms of bools For example in the following code fragment both memcpy and boolcpy copy source to dest include lt string h gt E va int current source 2 dest 2 memcpy source dest 2 sizeof int current boolcpy bool current source bool current dest 2 boolsizeof int current In this case both functions accomplish the same thing you would use boolepy however if the number of bits to be copied was not a multiple of chars Chapter 2 Developing C Program 7 2 2 4 Header Files and C Keywords A difficulty can occur when you want to include a standard header file that also makes use of a C keyword For example the X Window System header file lt x11 Xlib h gt uses the C keyword current as a variable name Including this file would result in a syntax error In such a situation you can do the following define current Current include X11 Xlib h undef current This redefines current to be Current while X11 Xlib h is being included then un defines it Of course if you subsequently want to use the X11 X1lib nh variable in your program you must refer to it as Current 2 3 Calling Paris from C The header file cm paris h declares the functions in the C interface to Paris You might want to use these C functions to obtain Paris features not available with C syntax In add
18. region type call CMC default type n next P print S step We will use these abbreviations in our debugging sessions Note that you must create your own aliases for the C debugging functions put the appropriate alias commands in dbxinit if you want them to be in effect when you start your dbx session We then start debugging primes cs We decide to take alook at is candidate before the program enters the first where statement of the ind primes function We don t need to see very much of the parallel variable we know that elements 0 and 1 should be set to 0 and elements 2 and above should be set to 1 All elements should be active We begin by stepping through main Note that we use a next command at the beginning of main When you enter the first function in a compilation unit use the next command to avoid stepping into functions required by C runtime support Note also the use of the step command to enter the ind primes function we use step in this case so that we do go into the function dbx stop in main 1 stop in main dbx run Running primes Stopped in main at line 52 in file primes cs 52 main dbx n stopped in main at line 59 in file primes cs 59 find primes amp is prime dbx s stopped in find primes at line 34 in file primes cs 34 void find primes char current is prime p n stopped in find primes at line 40 in file primes cs 40 is candidate pcoord 0 gt
19. type read from position CMC sendaddr t send address type void sourcep type write to position CMC sendaddr t send address type void destp bool source CMC multicoord t make multi coord shape s unsigned int axis mask sendaddr t send address multicoord t make multi coord sbape s unsigned int axis mask int axes multicoord t make multi coord shape s unsigned int axis mask int axis sendaddr t current make send address shape s int current axis CMC sendaddr t current make send address shape s int current axes CMC sendaddr t make send address shape s int axis sendaddr t make send address shape s int axes type current from grid type current sourcep type current value int distance type current from grid dim type current sourcep type current value int axis int distance Thinking Machines Last change 10 31 90 1 cscomm h 1 MISC REFERENCE MANUAL PAGES cscomm h 1 Q type to grid type current destp type current source type current valuep int distance void to grid dim type current destp type current source type current valuep int axis int distance type current from torus type current sourcep int distance type current from torus dim fype current sourcep int axis int distance void to torus ftype current destp type current source int distance void to torus dim type current destp type current source i
20. 14 1 tries usr lib libx a If that does not exist 14 1 tries fusr local lib libx a A library is searched when its name is encountered so the placement of a is significant o output Name the final output file output If this option is used the file a out will be left undis turbed pg Link with profiling libraries for use with gprof 7 Uname Undefine the preprocessor symbol name OPTIMIZATION The C compiler has three levels of optimization zero one and two Level zero turns the optimizer off This is not normally useful for users Specify 0 to turn the optim izer off Level one performs local copy propagation dead code elimination variable minimization and some peephole optimizations This is the default behavior of the compiler You don t need to specify anything on the command line to get this behavior Level 2 performs the same optimizations as level one except that user variables are optimized in addi tion to compiler generated temporaries A program compiled at optimization level two will generally be too highly optimized for use with the debugger Specify O or O2 to tum on optimization level 2 DEFAULT SYMBOLS FILES The C compiler provides the following default symbols each defined as 1 These symbols are useful in ifdef statements to isolate code for one of the particular cases Thus these symbols can be useful for ensuring portable code The estar symbol can be used to share source bet
21. 3 Options for cmattach This section describes several of the most commonly used options for cmattach See its on line man page for a discussion of all its options Waiting for Resources Use the w option to tell cmattach to wait if initially it cannot obtain an interface and a sequencer If you don t require interactive use of the CM it is generally preferable to sub mit your program to a batch queue Specifying a Sequencer an Interface and a CM You can control the CM the interface and sequencer s to which cmattach will attach you You might want to specify a particular sequencer if for example you want to use a framebuffer that is connected to that sequencer Use the C option followed by the name of a CM to specify the CM to which you want to attach Use the S option to specify number of the sequencer s to which you want to attach Valid values are 0 1 2 3 0 1 2 3 and 0 3 Use the i option to specify the number of the interface to which you want to attach Obtaining Exclusive Access Use the option to cmattach to specify that you require exclusive access to one or more sequencers If you use this option the system will not attach you to a sequencer that is running under timesharing 4 3 Obtaining Batch Access In the CM batch system you submit your program as a request to a queue The queue may be associated with a CM and a sequencer in which case the request is generally executed when it reac
22. AME cs C compiler SYNOPSIS es option file DESCRIPTION cs is the C compiler It translates C programs into C Paris and then invokes the C compiler cc 1 to make an executable load module File names ending in are treated as C source files file names ending in c are treated as C source files and are passed directly to cc file names ending in 0 are treated as object files and are passed directly to 1 file names ending in a are treated as object libraries and are passed directly to 14 In addition VAX file names ending in obj are treated as object files and are passed directly to cs accepts a number of the options and filename endings that cc accepts plus a few specific to cs OPTIONS Options specific to cs cmdname Use rather than cc as the compiler to perform C compilations dryrun Show but do not execute compilation steps force Force input files with the c suffix to be passed through the C compilation phase rather than just the cc phase This option is useful for processing ANSI C programs help Print a summary of available command line switches without compiling h Synonym for help keyword Retain intermediate files generated by the compilation process Currently the only legal value for keyword is c noline Suppress line directives in the output C file overload For each call to an overloaded function print the actual name of the functio
23. C Shapes and Paris VP Sets 10 C Parallel Arrays and Paris 105 10 C Memory Layout and Paris 11 24 Calling CM Libraries 1 2 4 1 General Information 11 2 4 2 Graphics and Visualization Library 12 2 4 3 The CM VO Libtatys zs Ores uer nOn rie Cbr d bu 12 2 4 4 The CM Scientific Software Library 13 2 5 Calling CM Fortran 2 22 2222 eee terr mer err eels 13 ii iv C User 5 Guide 2 5 T OVETVIEW E PEE ERI 13 2 52 An Detail 5o eve ERES REM 14 Include File Mere E Ds 14 Calling the Subroutine 14 What Kinds of Variables Can You Pass 15 Passing Parallel 16 Passing Scalar Variables 16 Freeing the Descriptors 17 Example 52 cade Oe RO ect vi 17 2 6 Using UNIX Utilities 0 0 ccc ccc eee eee eect nee nnn 18 2 6 1 The Program Maintenance Utility make 18 2 6 2 The Profiling Tools prof and gprof 18 Chapter 3 Compiling Program 19 3 1 The Basic Compilation Process
24. C compiler s pre processor for oo cs the pathname of this pre processor may be different at different sites This gives you access to ANSI C features available in the Gnu C pre processor Note however that the use of a pre processor other than the one available with the standard C compiler on your VAX or Sun front end is not supported Displaying Compilation Steps The dryrun Option Specify dryrun to cause cs to show but not carry out the steps in the compilation Putting c Files through the C Compilation Phase The force Option Specify force to put c files through the C compilation phase Otherwise such files are passed unread to the C compilation phase You might want to specify to take ad vantage of the C compilation phase s type checking of prototyped function declarations Keeping the Intermediate File The keep Option Specify the keep option followed by the argument c to have cs keep the c file produced by the C compilation phase NOTE The c file is not portable between front ends You cannot create a c file ona Sun for example and execute it on a VAX Chapter 3 Compiling a C Program 25 Suppressing Line Directives The noline Option Specify noline to suppress line directives the output C file This seriously limits your ability to debug C source files with dbx or other debuggers It does however let you debug at the C Paris level in other words you can
25. FIRST PRIME 2 34 void find primes char current is prime p 35 char current is candidate 36 int minimum prime 37 38 is_ prime p FALSE 39 40 is candidate pcoord 0 gt FIRST PRIME TRUE FALSE 41 42 do 43 where is candidate 44 minimum prime lt pcoord 0 45 where pcoord 0 minimum prime 46 is candidate FALSE 47 minimum prime is prime p TRUE 48 49 while is candidate 50 51 52 main 53 shape MAXIMUM PRIME s 54 55 char s is prime 56 int i 57 58 with s 59 find primes amp is prime 60 for i 0 i MAXIMUM PRIME 1 61 if i is prime 62 printf The next prime number is d n i 63 We rerun dbx and look at is prime p before line 38 is executed dbx primes Reading symbolic information Read 1711 symbols dbx stop in find primes 1 stop in find primes dox run Running primes stopped in find primes at line 34 in file primes cs 34 void find primes char current is prime p dbx n stopped in find primes at line 38 in file primes cs 38 is prime p FALSE dox dt is prime p CMC char stopped in find primes at line 38 in file primes cs 38 is prime p FALSE dox dr s 0 9 Region set to 0 9 stopped in find primes at line 38 in file primes cs 38 is prime p FALSE dbx dw CMC char 2 stopped in find primes at line 38 in file primes cs 38 is prime p FALSE d
26. a region Save the current context on a stack Assign a value to an active element of a parallel variable Assign a constant value to active elements of a parallel variable in a region Display debugging status information 38 C User 5 Guide 5 1 2 Calling C Debugging Functions from within dbx To use one of the C debugging functions described in this chapter issue it with the dbx command 11 To lessen the amount of typing this requires you can use the dbx com mand alias to create an abbreviation for the call For example issuing the following command dbx alias ppr call print region makes ppr an alias for the string CMC print region You can then use ppr along with the appropriate argument in place of a call to CMC print region For example ppr p1 To execute these alias commands automatically when you start a dbx session put them in the file dbxinit in your current or home directory We provide a sample dbxinit file called cs dbxinit which is located in the directory that contains sample programs Ask your system administrator for the path for this directo ry at your site 5 2 Defining a Region The define region Function C debugging functions let you perform operations either on a single element or position or on a selected set of positions within a shape this set of positions 15 referred to as a re gion Since shapes usually have thousands of positions it is easier
27. access to some of its processors this is known as attaching to the CM Your front end has one or more interfaces each of which can attach to one or more sequencers within the CM each sequencer controls a group of CM processors There are two basic methods of attaching to a CM direct access and batch access For direct access issue the cmattach command to attach an interface to one or more sequencers on the CM Depending on how you issue the command your pro grams is executed immediately and you are then detached from the CM or you enter an interactive subshell from which you can execute the program and other commands For batch access issue the qsub command to submit your program to a queue that has been set up in the CM batch system Your program attaches to the CM and is executed when it reaches the head of the queue Check with your system adminis trator to find out if the batch system has been installed at your site In both cases access to the CM can be either exclusive or timeshared depending on how your system is configured With exclusive access only one user can be attached to an inter i face and a sequencer at a time With timeshared access multiple users can be attached at 29 a time and multiple jobs can be running on the same processors Neither affects the way you compile or execute your Performance may be somewhat slower under time sharing however Direct exclusive access is ideal when yo
28. ame volume as this user s guide C Programming Guide In addition a technical report is available that provides a reference description of the C language Information about related aspects ofthe Connection Machine system is contained in the following vol umes of the Connection Machine documentation set Connection Machine User 5 Guide Connection Machine I O Programming Connection Machine Graphics Programming Connection Machine Parallel Instruction Set Connection Machine Programming in C Paris Also consult the documentation for your front end a Sun 4 running SunOS ora VAX running ULTRIX for further information about program development facilities Notation Conventions The table below displays the notation conventions used in this manual Convention Meaning bold typewriter C and C language elements such as keywords operators and function names when they appear embedded in text Also UNIX and CM System Software commands command options and file names italics Parameter names and placeholders in function and command formats typewriter Code examples and code fragments boldface In interactive examples user input is shown in boldface regular typewriter and system output is shown in regular typewriter font Customer Support Thinking Machines Customer Support encourages customers to report errors in Connection Machine operation and to suggest improvements in our products When reporting an er
29. and Paris Field IDs Pass the addresses of parallel variables rather than field IDs to Paris functions that take field IDs as arguments You can simply pass the parallel variable itself but this requires an unnecessary creation of a temporary variable For example the following C Paris code fragment adds the values in two fields include cm paris h C Paris code omitted CM set vp 5 CM field id t pl 2 Stack fields are explicitly allocated 1 CM allocate stack field 32 p2 CM allocate stack field 32 C Paris code omitted CM s add 2 114 1 p2 32 Here is the corresponding C Paris program fragment including a call to CM s add 2 1L finclude lt cm paris h gt C code omitted with S int S pl pz Addresses of parallel variables are passed CM s add 2 1L amp pl amp p2 boolsizeof int S Note the use of boolsizeof to determine the size of a parallel int in the C fragment this makes the code more portable than explicitly specifying the value 32 C Shapes and Paris VP Sets A C shape represents the VP set ID of the corresponding VP set For example CM vp set geometry 5 returns the geometry associated with shape S You could use this geometry in a call to CM geometry axis vp ratio for example to obtain the VP ratio of axis 0 of shape S CM geometry axis vp ratio CM vp set 5 C Parallel Arrays a
30. arallel structures or parallel arrays 5 4 Printing Values of a Parallel Variable The CMC print and CMC print region Functions C provides functions that let you print out either the value of a single element of a parallel variable or the values of a parallel variable s elements in the region specified by de fine region If the parallel variable does not have the default type you must have previously called the function CMC define type to specify a type for it To print the value of a single element call the print function As arguments specify the parallel variable followed by the coordinate s of the element whose value you want to print Start with axis 0 For example dbx call print p1 5 7 prints the value of 5 7 p1 If the specified element is in an inactive position its value is displayed in parentheses Chapter 5 Debugging C Program 41 To print the values of a parallel variable s elements in a region call CMC print region The parallel variable is the only argument The function prints the values of the elements the region specified by define region if you have not called CMC define region for the shape of this variable the function prints the values of all elements of the parallel variable If parallel variable p1 is of shape ShapeA and you issue the following commands dbx call define region ShapeA 0 4 0 9 dbx call print region pl CMC p
31. assed to a function C passes the field ID of a copy of the parallel variable this allows the parallel variable to be passed by value A position in C is a virtual processor ctive positions are processors in the current VP set that have their context flags set An element in C is the value of a field stored in an individual virtual processor Send and get operations in C are performed by the corresponding Paris calls Grid com munication functions in C are performed by the corresponding NEWS calls in Paris 2 3 2 Calling Paris Functions In calling Paris functions within a C program there is one essential difference from C Paris programming C does all space allocation You pass C Paris functions addresses of C parallel variables rather than direct machine offsets Little of the usual C Paris book keeping is required in particular no initialization or CM stack control is necessary Please note the following in calling Paris from C If you explicitly allocate fields using Paris functions in a C program it is impor tant to understand that C automatically deallocates all stack fields when leaving a block Therefore stack fields can exist only within a block If you want a field to continue to exist after your program leaves a block allocate a heap field instead Don t manipulate the context using Paris functions the C behavior is undefined A 6 Chapter 2 Developing C Program 9 Parallel Variables
32. at define width and define view Functions To change the way in which CMC print region displays the values of a parallel variable use the de ine format define width and define view functions Use define format to specify a different display format for a data type The func tion takes as arguments a type selector and a printf format For example dbx call CMC define format CMC float 5 2f causes loats to be printed out with a field width of 5 and a precision of 2 See Section 5 3 for the list of type selectors Due to a restriction in some Sun versions of dbx you cannot pass a string to dbx as an argument to a function This means that you cannot call CMC define format from a Sun front end Instead use CMC define width CMC define width takes as arguments a type selector and an integer that specifies the field width of that type For example dbx call CMC define width CMC int 4 causes integers to be printed with a width of 4 Note the following in using de ine width f the type selector is CMC float CMC double or CMC long double you must specify two integers the first specifies the width and the second specifies the precision All other type selectors take only one integer Ifthe type selector is char and you specify a negative width the char is printed as an int with the width you specify If the width is greater than or equal to 0 the char is prin
33. bx ppr is prime p Row stopped in find primes at line 38 in file primes cs 38 is prime p FALSE 62 C User 5 Guide The values have not changed from the previous execution of the program We then look atis prime p after line 38 is executed As required all values are now zero dbx n Stopped in find primes at line 40 in file primes cs 40 is candidate pcoord 0 gt FIRST PRIME TRUE FALSE dox ppr is prime p Row Stopped in find primes at line 40 in file primes cs 40 is candidate pcoord 0 gt FIRST PRIME TRUE FALSE We continue go step through the program looking at the behavior of is prime p dbx n Stopped in find primes at line 43 in file primes cs 43 where is candidate dox n stopped in find primes at line 44 in file primes cs 44 minimum prime pcoord 0 dbx n Stopped in find primes at line 45 in file primes cs 45 where pcoord 0 minimum prime dbx n stopped in find primes at line 46 in file primes cs 46 is candidate FALSE dox n stopped in find primes at line 47 in file primes cs 47 minimum prime is prime p TRUE dbx n stopped in find primes at line 48 in file primes cs 48 dbx ppr is prime p Row Chapter 5 Debugging C Program 63 stopped in find primes at line 48 in file primes cs 48 The first prime number is set correctly We go through the loop again dbx n stopped in f
34. code C code see Section 2 1 Header files see Section 2 2 Calls to Paris the CM parallel instruction set see Section 2 3 Calls to CM library functions see Section 2 4 Calls to CM Fortran subroutines see Section 2 5 2 4 C cs Files C code must appear in files with the suffix cs C code consists of any of the exten sions that C adds to standard C Standard C code can appear in either c or cs files putting it in c files speeds up compilation as discussed in Section 3 2 in the next chapter 2 1 1 C Keywords C adds the following new keywords to standard C allocate detailed shape allocate shape bool boolsizeof 4 C User 5 Guide current dimof everywhere overload pcoord physical positionsof rankof shape shapeof where with C code must not use these words except as prescribed in the definition of the language 2 1 2 Reserved Identifiers Identifiers beginning with CM are reserved for use by this implementation of the language Do not create identifiers beginning with CM in your programs 2 1 3 Default Shape Although the language does not define a default shape this implementation provides one If you specify a default geometry via the g option to the cmattach or emcoldboot com mand a VP with this geometry becomes the default shape of the program If you do not use this option the default shape is physical that is a 1 dimensional shape whose size is the number of phys
35. compiler responds primes cs line 47 illegal indirection primes cs line 59 type clash on argument 1 primes cs line 45 undefined identifier minimum We look at the offending lines Chapter 5 Debugging Program 49 47 minimum prime p TRUE 59 find primes amp is prime 45 where pcoord 0 minimum The problems are fairly easy to spot The difficulties with lines 47 and 59 are caused by the same error We defined find primes on line 34 as taking a parallel variable rather than as taking a pointer to a parallel variable Thus the compiler complained when it reached the lines where we treat the parameter as a pointer The problem with the identifier minimum on line 45 is also obvious We declared the vari able as minimum prime on line 36 but refer to it as minimum here 5 9 3 The Initial Debugging Session We make the corrections which are shown below in bold we omit the initial comments 1 define MAXIMUM PRIME 16384 2 3 define FALSE 0 4 define TRUE 1 5 define FIRST PRIME 2 34 void find primes char current is prime p 35 char current is candidate 36 int minimum prime 3T 38 39 40 candidate pcoord 0 gt FIRST PRIME TRUE FALSE 41 42 do 43 where is candidate 44 minimum prime pcoord 0 45 where pcoord 0 minimum prime 46 is candidate FALSE 47 minimum prime is prime p TRUE 48 49 while
36. d produces an executable load module Typically only cs files are read during the C compilation phase c o and a files are not read until the C compilation phase This means that putting serial code in c files speeds up compilation since these files don t have to go through both compilation phases You may however want a c file to go through the C compilation phase if the code includes ANSI features like function prototyping since the C compilation phase imple ments many ANSI features To accomplish this specify the option to as described below 3 2 1 Advanced Options This section describes cs options that would typically be used by an advanced program mer All options are listed in Table 1 Using Another C Compiler The cc Option The C compiler works in conjunction with the standard C compiler available on your VAX or Sun front end The use of with other C compilers is not supported and can lead to incorrect results However you can use another compiler if you want to by including the 24 C User 5 Guide cc switch followed by the name of the compiler For example to use Gnu C compiler specify the ec option as in the following example cs myfile cs Specifying a Different Pre processor The Option Use the option to specify a different pre processor during C compilation For example cs cpp usr local lib gcc cpp foo cs uses the Gnu
37. de fault call the CMC default type function Its sole argument is a data type selector which must be one of the following bool CMC char CMC double CMC float CMC int CMC long double loag int CMC short If you want the default to be an unsigned data type use the corresponding signed type For example use CMC int to make either integers or unsigned integers the default data type If a parallel variable does not have the default data type specify its type using the CMC define type function Include the parallel variable and the type selector as argu ments For example dbx call define int defines p1 as an int You can t define a type for a parallel variable until you have passed the point in your pro gram where space is allocated for the parallel variable on the CM For a parallel variable at file scope this occurs when you enter the first function in the compilation unit where the parallel variable is declared For an auto parallel variable this occurs when the parallel variable is declared Note It is important to use CMC define type to define the type for any parallel variable that is not of the default type If you don t and the parallel variable is smaller than the default type the de bugger may try to access memory beyond the parallel variable s boundary this may cause the debugger to abort Note that you can t use structure or array syntax to print out p
38. debug the c file rather than the cs file Displaying Names of Overloaded Functions The overload Function Use the overload option to cause the compiler to display informational messages listing the names it uses internally for overloaded functions This is necessary if you want to in voke such a function directly using dbx Turning On Verbose Compilation The verbose Option Specify verbose or v to display informational messages as the compilation proceeds This can be useful if you want to see which part of the compilation process produced an error message Creating Assembly Source Files The S Option Use the S compiler option to create an assembly source file for each input source file For example cs S foo cs bar cs produces the files foo s and bar s You cannot combine the S option with either the option or the option Changing the location of Temporary Files The temp Option Use the temp option to change the location in which C temporary files are created By default these files are created in tmp To create them in the directory var bar for ex ample issue a cs command like this cs temp var bar foo cs Note that spaces are allowed Sun users who want to redirect temporary files created by the C compiler should still use this option Zcc temp directory Turning Off Warnings The warn Option Specify warn to suppress warnings produced during the C compilation
39. e overload rank read from position write to position make multi coord make send address overload from grid from grid dim to grid to grid dim overload from torus torus dim to torus to torus dim overload read from pvar write to pvar type current get CMC sendaddr t current send address type void sourcep CMC collision mode t collision_mode type current send type void destp CMC_sendaddr t current send address type current source CMC combiner t combiner bool void notifyp type current scan type current source int axis combiner t combiner CMC communication direction t direction CMC segment mode t smode bool current sbitp scan inclusion t inclusion type global type current source CMC combiner t combiner type current spread type current source int axis CMC combiner t combiner type current copy spread type current sourcep int axis int coordinate type current multispread type current source int axis map CMC combiner t combiner type current copy multispread type current sourcep int axis map multicoord t multi coord void reduce type current destp type current source int axis CMC combiner t combiner int to coord void copy reduce type current destp type current source int axis int to coord int from coord unsigned int current rank type current source int axis communication direction t direction CMC segment mode t smode bool current sbitp
40. eB 47 59 makes it inactive For a region region to make all positions within the region active and call CMC off region to make them all inactive The only argument for both functions is a shape For example dbx call on region ShapeA makes all positions active in the currently defined region for shape ShapeA dbx call off region ShapeA makes them inactive NOTE To indicate the current shape specify CM current vp set instead of the key word current 5 5 1 Saving and Restoring Contexts The CMC push context and CMC pop context Functions In debugging you might want to change a shape s context see what happens and then change back to an earlier context To do this use the functions CMC push context and CMC pop context Both take a shape as an argument Use CMC push context to save the current context for a shape You might then call a function like region to change the context Once you are through using the changed context call CMC pop context to return the context to what it was before the change Do this before leaving a block that changes the context you will get unexpected results if you issue CMC pop context when the context is not the same as it was when you issued CMC push context NOTE To indicate the current shape specify CM current vp setinstead ofthe C key word current 5 6 Assigning Values to a Parallel Variable The CMC set and CMC set region Fu
41. earrange the data 2 4 4 Scientific Software Library program can contain calls to routines in the Connection Machine Scientific Software Library CMSSL Currently C users must use the C Paris interface to the CMSSL For complete information on this interface see the manual CMSSL for Paris Please note the following in addition to the information discussed in Section 2 4 1 CMSSL routines typically run more efficiently when fields are allocated contigu ously Normal stack allocation in C does not work in this way To get this behavior you must call the 11 function to allocate memory individually for each argument to a CMSSL routine 2 5 Calling CM Fortran You can call CM Fortran subroutines from within a C program This section describes how See Chapter 3 for a discussion of how to link in the CM Fortran program and other required files 2 5 1 Overview To call a CM Fortran subroutine do the following Include the file lt esfort h gt Use the function CALL FORTRAN to call one or more CM Fortran subrou tines You must convert the subroutine name to lowercase and add an underscore to the end of it a parallel variable to a subroutine create a scalar variable of type CMC descriptor t Call the function CMC wrap pvar with a pointer to the parallel variable as an argument and assign the result to the scalar variable you created Pass this scalar variable to the CM Fo
42. ent d float current scalb float current f int current i double current scalb double current d int current i DESCRIPTION The mathematical library under C contains the entire serial C mathematical library along with parallel overloadings of many of the functions In addition only parallel versions of the following functions which have scalar overloadings are provided acosh asinh and atanh SEE ALSO cs C User s Guide C Programming Guide RESTRICTIONS Because the scalar and parallel versions of some routines are implemented using different algorithms Thinking Machines Last change 10 29 90 2 math h 1 MISC REFERENCE MANUAL PAGES math h 1 e results of routines given the same numerical input may be slightly different in a serial context than in a parallel context This is particularly the case on the VAX because the VAX and the Connection Machine processors use different floating point formats the VAX uses VAX format while the Connec tion Machine processors use IEEE format Thinking Machines Last change 10 29 90 3 stdarg h 1 MISC REFERENCE MANUAL PAGES stdarg h 1 NAME stdarg h C variable arguments SYNTAX include lt stdarg h gt SYNOPSIS void va_start va_list ap parmN type va_arg va_alist ap type void va end va list DESCRIPTION The macros start va arg and va end be used to write functions that can operate a variable number of arguments The va s
43. er set starts unsigned timer unsigned value void CMC timer start unsigned timer void CMC timer stop unsigned timer DESCRIPTION The timer functions under C are wrappers for the Paris timer functions See the CM User s Guide for more information about the Paris timer functions SEE ALSO CM User s Guide Thinking Machines Last change 10 29 90 1 math h 1 MISC REFERENCE MANUAL PAGES NAME math h C mathematical library SYNTAX include lt math h gt SYNOPSIS overload acos asin atan overload atan2 overload cos sin tan overload cosh sinh tanh overload asinh acosh atanh overload exp log log10 logb overload pow ceil sqrt fabs floor overload copysign drem finite scalb truncate float current acos float current double current acos double current float current asin float current double current asin double current float current atan float current double current atan double current float current atan2 float current f float current 2 double current atan2 double current 4 double current 42 float current cos float current double current cos double current float current sin float current double current sin double current float current tan float current double current tan double current float current cosh float current double current cosh double current float current sinh float current double current sinh double current float current tanh float cur
44. g with parallel overloadings of the functions SEE ALSO ANSI C Programming Language Standard Thinking Machines Last change 10 29 90 1 Symbols C files 23 debugging 25 keeping 24 a files 19 23 C files 3 19 23 putting through C compilation 24 CS files 1 3 5 23 dbxinit 38 files 19 23 obj files 19 define 26 ifdef 27 1 directives suppressing 25 A abs 6 allocate_detailed_shape 12 aref32 11 arrays parallel See parallel arrays aset32 11 attaching See cmattach attaching to the CM 29 B batch request submitting 32 batch system executing a C program under 32 boolcmp 6 boolcpy 6 boolmove 6 boolset 6 boolsizeof 9 compiler using other than the default 23 79 1 C debugging functions aliasing 38 table of 37 C Paris 8 23 cc 19 26 CM Fortran calling from C 13 CM libraries calling from C 11 lt em paris h gt 5 7 CM add offset to field 10 CM current vp set 39 43 44 cmattach 2 29 35 g option 4 executing a program immediately with 30 options for 31 using to obtain an interactive subshell 31 bool 39 char 39 define width 42 default type 39 40 define format 42 44 define region 38 39 40 define type 39 40 define view 42 44 define width 42 44 double 39 float 39 and define wid
45. ght all the positions are active again and element 2 is set to 1 We step through the outer where statement again as the do loop continues and then print out is candidate and minimum prime Chapter 5 Debugging C Program 57 dbx n stopped in find primes at line 43 file primes cs 43 where is candidate dbx n Stopped in find primes at line 44 in file primes cs 44 minimum prime lt pcoord 0 dbx n stopped in find primes at line 45 in file primes cs 45 where pcoord 0 minimum prime dbx ppr is candidate Row 0 1 2 3 4 5 6 7 8 9 0 0 1 0 1 0 1 0 1 0 stopped in find primes at line 45 in file primes cs 45 where pcoord 0 minimum prime D dbx p minimum prime minimum prime 2 We see now why the program went into an infinite loop We wanted to select the coordi nates that were multiples of minimum prime so that we could set is candidate to 0 in those positions instead we did the opposite in line 45 The even numbered positions remain set to 1 for is candidate and therefore remain active as a result minimum prime always comes out 2 and the program never stops The solution is to use to negate the condition for the where statement in line 45 We quit dbx fix the bug and try again 5 9 5 The Third Debugging Session The revised program is shown below the revised line is in bold 1 define MAXIMUM PRIME 16384 2 3 define FALSE 0 4 define TRUE 1 5 define
46. he current region s If you have not defined a region for a shape but you have called functions like CMC print region that access a region for the shape CMC status prints the default which is all positions in the shape Note In the display parallel variables are shown as Paris field IDs and Shapes are shown as Paris VP set IDs To determine the field ID for a parallel variable use the dbx command print with the par allel variable name as the argument Similarly to obtain the VP set ID for a shape issue print with the name of the shape See Chap ter 2 for a discussion of the relationship between Paris concepts and C concepts 46 C User 5 Guide 5 8 Obtaining Help The CMC help Function Call the function CMC help to obtain a list of the C debugging functions and their argu ments 5 9 Sample Debugging Sessions This section presents a series of dbx sessions in which we debug a C program The ses sions are on a Sun VAX sessions would look somewhat different 5 9 1 The Program The program primes cs is supposed to find and display prime numbers and is shown below line numbers have been added to help you follow the explanations There are sever al errors in the program The rest of the section will show the process by which these errors are uncovered 1 define MAXIMUM PRIME 16384 2 3 define FALSE 0 4 define TRUE 1 5 define FIRST PRIME 2 6 ay 8 Function to find prime numbers kf 9
47. hes the head of the queue Or tbe queue could send the request to another queue for execution The batch system is configured differently at different sites To find out what queues exist at your site and when they are active ask your system administrator or issue the following command qstat 4 3 1 Submitting a Batch Request Use the qsub command to submit a batch request for execution via a queue in the CM batch system You can submit multiple programs as one batch request There are two ways of specifying the programs to be executed Put their names in a script file and specify the name of the script file on the qsub command line For example the file myprogram script could contain the fol lowing names of executable C programs myprograml myprogram2 myprogram3 You can then submit these programs for execution by issuing the following command Chapter 4 Executing C Program 33 qsub myprogram script Enter the names of the files from standard input Put the names of the programs on separate lines and type Ctrl D at the end to signal that there is no more input For example qsub myprograml myprogram2 myprogram3 Cirl D You can also issue other commands as part of the request for example cmsetsafety to turn Paris run time safety on or off 4 3 2 Options for qsub This section describes several of the most commonly used options for qsub See its on line man page for a discussion of all its op
48. hine Graphic Display System in the Connection Machine documentation set 2 4 3 The CM I O Library operations on the CM are carried out by making calls to functions in the CMFS library CMFS stands for CM file system For information on CMFS library calls consult the CM I O System Programming Guide This guide describes how to use these calls to do such things as create files in the CM file system read and write data between a CM and an I O device in the Connection Machine system and if necessary transpose serial data so that it is in the proper format for parallel operations Please note the following in addition to the information discussed in Section 2 4 1 above Shapes by default are in news order You can specify a different order by using the allocate detailed shape function When using the CMFS trans pose always function to transpose data between serial and parallel format you must include as the final argument one of the provided functions CMFS write to row major CMFS write to column major CMFS read from row major or CMFS read from column major to make sure that the data is correctly transposed Do this even if the data is one di mensional The choice between row major and column major order depends on the way in which the serial data is laid out note that data in C is laid out in row ma jor order If the data is laid out in an order other than column major or row major you must write your own function to correctly r
49. ic display system or on an X Window System Call routines from the CM VO library to perform standard functions for ex ample reading data into the CM from a DataVault or other I O device Call routines from the Connection Machine Scientific Software Library CMSSL to perform data parallel versions of standard mathematical operations such as ma trix multiply and Fast Fourier Transform 2 4 1 General Information CM libraries currently provide a C Paris interface you can call functions in these libraries as you would any Paris functions See Section 2 3 for a discussion of the relationship be tween C and Paris Therefore note the following when consulting the documentation for the libraries When a call requires a field ID as an argument pass it the address of the corre sponding parallel variable described in Section 2 3 a shape in C is the VP set ID of a VP set with its associated geometry positions are virtual processors Interpret discussions of ge ometry and VP sets with these correspondences in mind 12 C User 5 Guide Since initializes the CM automatically ignore the requirement that the Paris routine CM init must be called before making any calls to library routines 2 4 2 The Graphics and Visualization Library Use the CMSR library to perform graphics operations and to display images of your data For complete information on the calls in this library consult the volume Connection Ma c
50. ical processors to which you are attached For more information on cmattach and emcoldboot see the CM User 5 Guide To gain access to a default shape specified via the g option you must first declare a shape that is not fully specified and assign the current shape to it while the default shape is cur rent In the following example the default shape is assigned to shape S shape 5 main CX Chapter 2 Developing a C Program 5 S current float S x y 2 with S 2 NOTE We do not recommend writing code that relies the default shape since this fea ture is implementation dependent and may change 2 2 HeaderFiles C substitutes its own header files for lt math h gt lt stdlib h gt and lt string h gt as described below These files are typically in usr include cs C accepts any other standard C libraries and associated header files Appendix A contains the man pages for these files In addition C includes the following header files cscomm h which is the header file for the communication functions described in Part III of the C Programming Guide Xcstimer h which provides wrappers for the Paris timing functions described in the CM User 5 Guide Note that the timer functions in cstimer h begin with rather than If you use these versions of the timing functions and in clude estimer h you need not include the much larger header f
51. ile cm paris h as described in the CM User 5 Guide Man pages for these header files are also contained in Appendix A 2 2 1 The lt math h gt File The C version of math h gt declares all the functions in the UNIX serial math library and extends all ANSI serial functions with parallel overloadings No special library is required to use these functions 6 C 5 Guide 2 2 2 The lt stdlib h gt File The file lt stdlib h gt contains scalar and parallel declarations of the function abs rand and srand the parallel versions of rand and srand are named prand and psrand The file also contains the declarations of palloc pfree anddeallocate shape which are described in the C Programming Guide No special library is required to use these functions Note that prand returns a different random number for every element of a parallel variable 2 2 3 The lt string h gt File The file lt string h gt contains parallel declarations of the functions memcpy memmove memcmp and memset In addition it contains declarations of boolean versions of these functions called boolepy boolmove boolcmp and boolset The boolean versions are useful for performing memory operations at the bit level These functions take pointers to bools for arguments and return pointers to bools except for boolcmp If you are dealing with arguments that are not bools you must cast them to be pointers to bools Also note that the size argument for
52. ind primes at line 43 in file primes cs 43 where is candidate dbx n stopped in find primes at line 44 in file primes cs 44 minimum prime pcoord 0 dbx n stopped in find primes at line 45 in file primes cs 45 where pcoord 0 minimum prime dbx print minimum prime minimum prime 3 dbx n stopped in find primes at line 46 in file primes cs 46 is candidate FALSE dbx n stopped in find primes at line 47 in file primes cs 47 minimum prime is prime p TRUE dbx n stopped in find primes at line 48 in file primes cs 48 dbx ppr is prime Row stopped in find primes at line 48 in file primes cs 48 The second prime number is correctly set We feel confident enough now to see if the pro gram can run to completion dbx cont The next prime number is 2 The next prime number is 3 The next prime number is 5 64 C User 5 Guide The next prime number is 7 The next prime number is 11 The next prime number is 13 execution completed exit code is 0 program exited with 0 The program runs correctly we spare you from having to read the rest of the prime num bers There is nothing left to do then except to quit dbx dox quit Appendix Man Pages This appendix contains the text of man pages for cs and for C header files These man pages are also available on line 65 66 1 MISC REFERENCE MANUAL PAGES cs 1 e N
53. ion option to cause cs to print its version number before compiling If you do not specify a source file cs simply prints the version number and exits 3 1 2 Options in Common with cc The c D g 1 L o 9 and U Options The C compiler allows you to specify the cc options D g 1 L o and pg on the cs command line See Table 1 for a brief description of these options for more information consult your documentation for cc You must include the option if you want to use the C debugging functions on the com piled program Use the pg option if you want to profile your program using the UNIX gprof utility This option causes the compiler to link your program with special Paris and I O libraries These libraries provide more accurate timings of individual operations at the expense of de creased efficiency in the program as a whole 3 2 Look at the Compilation Process The es command actually has three phases which normally are transparent to the user A preprocessing phase C compilation phase compilation phase which includes linking The C compilation phase takes a preprocessed C source file and generates an equivalent output file which has the extension c Any parallel code in the cs file is translated into C Paris this c file serial code in the cs file may be somewhat changed C com pilation phase takes this C Paris file an
54. ition you need to know the relationship between C and Paris if you are going to call routines in the CM graphics I O or scientific software libraries These libraries provide a C Paris interface they do not currently provide a direct C interface For general information about Paris functions see the manual Introduction to Programming in C Paris For complete reference information on Paris see the Paris Reference Manual Section 2 4 below discusses the CM libraries 2 3 1 The Relationship between Paris and C This section explains how concepts in C map onto underlying Paris concepts A shape in C is the VP set ID set id t ofa Paris VP set with its associated geometry When a shape is passed to a function C passes this VP set ID It is also this VP set ID that is returned when you issue a dbx print call with the name of the shape as an argument see Chapter 5 The current shape is the current VP set 8 C User 5 Guide A parallel variable in C is a Paris field with the length specified by the parallel variable s type A pointer to a parallel variable is also a Paris field Thus pvar CM field id t amp pvar CM field id t When you issue the dbx command print with the name of the parallel variable as an argu ment it returns the field ID of a Paris field see Chapter 5 When a pointer to a parallel variable is passed to a function C passes the field ID of the parallel variable When a parallel variable is p
55. ix cs if the file contains parallel code or any other features that C adds to standard C for example the new lt and operators You can use standard UNIX tools like gprof and make Chapter 2 describes facilities for developing a C program It also describes how to call Paris func tions functions in the CM graphics I O and scientific software libraries and CM Fortran subroutines 1 2 Compiling C Program Compile the files by issuing the command cs from your UNIX front end The command can take various options some of which are identical to options for the C compiler Chapter 3 describes the compiler options and the compiling process in detail 1 3 Executing C Program To execute a program issue the command cmattach along with the name of the executa ble load module plus any arguments that the program requires Or use the qsub command to submit the executable load module as a batch request to the CM batch system The cmattach and qsub commands are discussed in Chapter 4 1 4 Debugging a C Program You can debug a C program using a standard UNIX debugger like dbx C provides func tions you can call to do such things as print out values of a parallel variable set the context of a shape and define a region within a shape on which operations are to take place Chap ter 5 describes the C debugging functions Chapter 2 Developing a C Program A C program can consist of Standard serial C
56. le primes cs 46 is candidate FALSE dox ppr is candidate Row 0 0 1 1 1 1 1 1 1 1 stopped in find primes at line 46 in file primes cs 46 is candidate FALSE This doesn t look right We wanted to select the positions whose coordinates were multi ples of minimum prime instead those positions have been turned off and the 56 C User 5 Guide odd numbered positions are active We forge ahead however and see what happens after line 46 dox n stopped in find primes at line 47 in file primes cs 47 minimum prime is prime p TRUE dox ppr is candidate Row 00 0 1 0 1 0 1 0 1 0 stopped in find primes at line 47 in file primes cs 47 minimum prime is prime p TRUE dox n stopped in find primes at line 48 in file primes cs 48 No this doesn t look good We have come out of the inner where statement and only the even coordinates are set to 1 This is the opposite of what we wanted We decide to take alookatis prime p Note that even though it s a pointer to a parallel variable we can treat it as a parallel variable in dbx First we make sure to define its type the debugger might abort if we try to print it as a double which is the default Then we print it dox dt is prime p CMC char stopped in find primes at line 47 in file primes cs 48 dbx ppr is prime p Row stopped in find primes at line 48 in file primes cs 48 This looks all ri
57. loaded Functions from within dbx 36 5 1 2 Calling C Debugging Functions from within dbx 38 Defining a Region The CMC define region Function 38 Defining Data Types for Parallel Variables The CMC default type and define type Functions 39 Printing Values of a Parallel Variable The print and print region Functions 40 5 4 1 Printing Values of a Pointer to a Parallel Variable 4 5 42 Changing the Format The define format define width and define view FUNCHONS 2l luu eei e Ie ebbe dae 42 Setting the Context The CMC on CMC region off and off region Functions 43 Version 6 0 Month 1991 vi C User 5 Guide 5 5 1 Saving and Restoring Contexts The push context and pop context Functions 44 5 6 Assigning Values to a Parallel Variable The set set region Functions 44 5 7 Obtaining Status Information The status Function 45 5 8 Obtaining Help The CMC help Func hOn ee aaa eer ee Ree 46 5 9 Sample Debugging 46 5 9 1 The Program 46 5 9 2 Compiling 48 5 9 3 The Initial Debugging Session
58. n For example cs release 6 0 1 myfile cs compiles with C Version 6 0 1 Typically the default C version will work with the standard installed version of the Paris library If that is the case you will have to specify the ucode option along with the release option in order to compile a program under a CM system software version that is not the default the ucode option is described below 22 C User 5 Guide Choosing a Specific Version of Paris The ucode Option By default cs uses the standard installed version of the Paris library You might want to use a different version for your program if for example you want to compare execution time for the standard version against that obtained using an older version Use the ucode option followed by a four digit number to specify another version of Paris Obtain this four digit number from your system administrator Then issue the cs command as in the following example cs ucode 5211 myfile cs The Paris library 5211 is the version used in Version 5 2 of CM system software If Version 6 0 1 is the default version of C you would also have to specify the release option to compile your program using this library For example cs ucode 5211 release 6 0 myfile cs Note that the version numbers of C and CM System Software do not coincide See above for more information about the release option Printing the Version Number The version Option Specify the vers
59. n called This is useful for debugging Olevel Invoke the optimizer with level level Legal values for level are 0 1 and 2 Optimiza tion levels are described in more detail below ucode number Link with CM software version number verbose Display informational messages as the compilation proceeds v Synonym for verbose version Print the C compiler version number before compiling warn Suppress warnings from the C compilation phase Zcomp switch Pass option switch to component comp comp is either cpp or cc For example Zcc O turns on the C compiler s optimizer Options in common with cc lt Suppress the linking phase of the compilation and force an object to be produced even if only one program is compiled Define the symbol name to the preprocessor If def is not supplied then name is defined e with a value of 1 2 Have the compiler produce additional symbol table information for dbx 1 Thinking Machines Last change 11 01 90 1 1 MISC REFERENCE MANUAL PAGES cs 1 Idir Seek include files whose names do not begin with first in the directory of the file argument then in directories named in options then in directories on a standard list Ldir Add directory dir to the list of directories on the object library search path x This option is an abbreviation for the library name lib libx a where x is a string If that does not exist
60. nctions C provides two debugging functions that let you change the values in elements of a paral lel variable For both these functions if the parallel variable s type is not the default you must first specify its type using CMC define type Chapter 5 Debugging Program 45 To assign a value to a single element of a parallel variable call the CMC set function As arguments specify the parallel variable the value to be assigned and the coordinates of the element starting with axis 0 For example dbx call CMC set p2 4 0 6 7 assigns the value 4 0 to 6 71p2 provided that the position is active If the position is inactive you receive a warning message and the value is not assigned To assign a single value to all active parallel variable elements in a region call CMC set region s arguments specify the parallel variable and the value For example dox call set region p2 4 0 assigns the value 4 0 to all elements of p2 that are in active positions in the currently de fined region If some positions are inactive the value is assigned to the elements in active positions and you receive a warning message about the inactive positions 5 7 Obtaining Status Information The status Function To find out the current status of your debugging session call the status function CMC status prints out information such as the default type the default formats the de fault views and t
61. nd Paris Fields A parallel array in C is allocated as one large Paris field and elements within the array are calculated as offsets within this field using CM add offset to field If you write a C Paris function that takes a C parallel array as an argument you must treat it similarly For example here is a C parallel array int S parray 10 A user written C Paris function that takes this array as an argument should be prototyped as in the following example f CM field id t x rather than as f CM field id t x 10 This is wrong To access element 3 of the array the function should do the following CM add offset to field id x 3 sizeof parray 0 rather than simply specifying x 3 Chapter 2 Developing C Program 11 C Memory Layout and Paris Functions Some advanced Paris functions for example are 32 and aset32 require that memory for fields be allocated contiguously on the CM The current implementation of C does not guarantee that memory for parallel variables will be laid out contiguously To ensure that you have the correct memory layout use 11 to allocate the memory yourself for par allel variables that are to be used with these Paris functions 2 4 Calling CM Libraries You can call routines from the standard CM libraries from within a C program Specifically Call routines from the CM graphics libraries to perform basic graphics operations and to display images on the CM graph
62. nner where state ment and look at is candidate once again dox n stopped in find primes at line 47 in file primes cs 47 minimum prime is prime p TRUE dbx ppr is candidate Row 0 0 0 1 0 1 0 1 0 1 stopped find primes at line 47 in file primes cs 47 minimum prime is prime p TRUE The positions with odd numbered coordinates are now set to 1 and therefore are still candi dates This is the correct behavior We then look at is prime p dbx dt is prime p char stopped in find primes at line 47 in file primes cs 47 minimum prime is prime p TRUE dbx ppr is prime p Row 0 0 1 0 0 0 0 0 0 0 stopped in find primes at line 47 in file primes cs 47 minimum prime is prime p TRUE 60 C User s Guide But that can t be right line 47 hasn t been executed yet to set element 2 to 1 for is prime p So why is it set At this point we notice another error in our program we forgot to initialize is prime p to 0 in the find primes function This means that the parallel variables retain their values from the previous execution of the program since we haven t coldbooted the CM and element 2 of is_prime_p remains set to 1 We make the required change and try again 5 9 6 The Final Debugging Session Here is what the code looks like now the latest revision is in bold 1 define MAXIMUM PRIME 16384 2 3 define FALSE 0 4 define TRUE 1 5 define
63. nt axis int distance void read from pvar type destp type current source type current write to pvar type sourcep unsigned int current enumerate int axis communication direction t direction CMC scan inclusion t inclusion CMC segment mode t smode bool current sbitp DESCRIPTION The C communication functions which duplicate and supplement communication features of the language support grid communication communication with computation and general communication Communication functions are overloaded to support arithmetic aggregate and void types In the function prototypes listed above there exists a function definition for the following values of type bool signed char signed short int unsigned short int signed int unsigned int signed long int unsigned long int float double long double and void SEE ALSO cs C Users Guide C Programming Guide Thinking Machines Last change 10 31 90 2 cstimer h 1 MISC REFERENCE MANUAL PAGES cstimer h 1 NAME cstimer h C timer functions SYNTAX Zinclude lt cstimer h gt SYNOPSIS extern unsigned CMC number of timers void CMC timer clear unsigned timer void CMC timer print unsigned timer double CMC timer read cm busy unsigned timer double CMC timer read cm idle unsigned timer double CMC timer read elapsed unsigned timer int CMC timer read run state unsigned timer int CMC timer read starts unsigned timer void CMC tim
64. ompiler converts all subroutine names to uppercase with no leading or trailing under scores The first line of the file creates the mapping The second line is mask of registers to be saved you need not change the sample line shown below For example if the name of the CM Fortran subroutine is TEST create the following file it must have the suffix jbl test TEST pass r2 r3 r4 r5 r6 r7 r8 r9 r10 rll Note that you would use the same file if the CM Fortran routine were called test in lowercase because the CM Fortran compiler converts the name to uppercase You can create multiple mappings in a single JBL file See Chapter 3 of this manual for information on compiling this file See the VAX Fortran for ULTRIX System User Manual for more information about JBL What Kinds of Variables Can You Pass You can pass both parallel and scalar variables as arguments to a CM Fortran subroutine The parallel variables you pass can be of any shape The variables can be of the following standard types bool signed int Signed long int float double long double In addition lt esfort h gt provides typedefs for two new types complex and CMC double complex The typedefs are defined as follows typedef struct float real imag complex typedef struct double real imag double complex Use these types to pass variables that can be treated as complex numbers by CM Fortran C User 5 Guide
65. p is cpp or cc Getting Help help Option Specify help or h to print a summary of available command line options for cs without compiling 6 Changing the Optimization Level The O Option Use the option to choose extra optimization for your program or to turn off optimiza tion If you do not specify default optimization includes local copy propagation dead code elimination variable minimization and some peephole optimizations You can debug a program compiled at this level by using dbx or another debugger For more optimization specify At this level the compiler optimizes user variables as well as compiler generated temporaries A program compiled using 0 is too highly opti mized for use with a debugger To turn off all optimization specify 00 This is normally not useful Choosing a Specific Version of the Compiler The release Option Use the release option to choose a specific version of the compiler The initial release of the compiler has two versions 6 0 which operates with version 5 2 of the CM system software and 6 0 1 which operates with version 6 0 of the CM System Software Note that the compiler version and the CM system software version do not coincide Either one of these versions may be installed as the default To determine which version is the default use the version option as described below To compile using a version that is not the default use the release optio
66. phase Specifying Options for Other Components The Z Option Use the 2 option to specify cpp or cc options that cs does not recognize These options are passed directly to the specified component without any interpretation by cs Type 2 followed by the component name followed by the option There is no space between 2 and the component name leave at least one space between the component name and the option For example specify cs Zcc w myfile cs to suppress cc warning messages 3 3 Symbols The cs command provides defines for the symbols listed below cstar The C language as opposed to the C language unix Any UNIX system ultrix ULTRIX only vax VAX only sun Sun only sparc Sun 4 only If the symbol is applicable es automatically defines it as 1 For example if you are execut ing cs on a VAX running ULTRIX the vax and ultrix symbols are each defined as 1 This 9 EN Chapter 3 Compiling a C Program lets you place the symbols ifdef statements to isolate code for execution only when the program is running under VAX ULTRIX Thus you can use these symbols to ensure that your code is portable The estar symbol lets you isolate parallel code within a program allowing you to share source code between a C and a C program 3 4 Compiling a C Program that Calls CM Fortran If your program includes a call to a CM Fortran subroutine as described in Chapter 2 fol low the instructions in this sec
67. rent double current tanh double current float current acosh float current double current acosh double current float current asinh float current double current asinh double current Thinking Machines Last change 10 29 90 math h 1 1 MISC REFERENCE MANUAL PAGES math h 1 float current atanh float current double current atanh double current float current exp float current double current exp double current float current log float current double current log double current float current logl0 float current double current log10 double current float current logb float current f double current logb double current d float current pow float current float current double current pow double current double current float current ceil float current double current ceil double current float current sqrt float current f double current sqrt double current d float current fabs fioat current double current fabs double current float current floor fioat current double current floor double current float current truncate float current double current truncate double current float current copysign float current f float current f2 double current copysign double current d double current d2 float current drem float current f float current 2 double current drem double current d double current d2 int current finite float current f int current finite double curr
68. rint region prints out the specified values of p1 as a 5 by 10 table with axis 0 as the rows and axis 1 as the columns Values of elements in inactive positions are dis played in parentheses If the shape is 3 dimensional the function prints out a series of tables of values each repre senting a plane of positions through axis 2 The function starts with the table of values for elements whose axis 2 coordinate is the lower boundary for axis 2 specified in the call to CMC define region You can change the format in which the values are displayed see Section 5 4 2 If the region contains too much data to be displayed on the screen reissue CMC define region to reduce the size of the region 5 4 1 Printing Values of a Pointer to a Parallel Variable To look at values pointed to by a scalar pointer to a parallel variable treat the pointer as if it were a regular parallel variable For example if you declare par ptr as follows int current par ptr you can define its type as follows dbx call CMC define type par ptr CMC int If the current shape is 1 dimensional you can print out the value at element 0 as follows dbx eall CMC print par ptr 0 You cannot treat a pointer to a parallel variable as you would a standard C pointer because the debugger doesn t understand C syntax See Chapter 2 for information on the underly ing implementation of scalar to parallel pointers in C 5 4 2 Changing the Format The CMC define form
69. ror please provide as much information as possible to help us identify and correct the problem A code example that failed to execute a session transcript the record of a back trace or other such information can greatly reduce the time it takes Thinking Machines to respond to the report To contact Thinking Machines Customer Support U S Mail Thinking Machines Corporation Customer Support 245 First Street Cambridge Massachusetts 02142 1264 Internet Electronic Mail customer support think com Usenet Electronic Mail ames think customer support Telephone 617 234 4000 617 876 1111 For Symbolics Users Only The Symbolics Lisp machine when connected to the Internet network provides a special mail facil ity for automatic reporting of Connection Machine system errors When such an error occurs simply press Ctrl M to create a report In the mail window that appears the field should be addressed as follows To customer support think com Please supplement the automatic report with any further pertinent information Chapter 1 Introduction C is an extension of the C programming language designed for the Connection Machine data parallel computing system This chapter presents an overview of the process of devel oping and executing a C program The rest of this manual goes into the process in more detail 1 1 Developing a C Program Develop C source code in one or more files You must use the suff
70. rs on sequencer 0 microcode version 6002 35 36 C User Guide Paris safety is off Entering CMATTACH subshell Type exit or control D to detach the CM 5 dbx a out dbx dbx commands such as run step and next dbx quit exit Detaching done dbx commands behave with programs as they do with C programs with the exception noted below Note on the VAX version of dbx C programs are translated into C Paris programs as part of the compilation process Although dbx displays the C statements it actually operates on this C Paris program In the VAX version of dbx the result is that you may have to issue a step or next command more than once before a C statement is completely executed what is happening is that dbx is stepping through the underlying C Paris statements 5 1 1 Invoking Overloaded Functions from within dbx To keep track of different versions of an overloaded function within a program the compil er assigns separate names to each version If you want to invoke a particular version of such a function from within dbx you must use this internal name To obtain these names use the overload option when compiling the program this causes the compiler to display the names it uses For example if your program contains two versions of the function sin one called with a parallel float the other with a parallel double the compiler might respond as in the following example Chap
71. rtran subroutine when you call it via CMC CALL FORTRAN a Pass scalar variables to a CM Fortran subroutine by reference After you are finished with a descriptor free it by calling ree desc with the scalar variable as an argument 2 5 2 Detail Inciude File As mentioned in the overview you must include the lt csfort h gt if your program includes a call to a CM Fortran subroutine Calling the Subroutine To call a CM Fortran subroutine use the following syntax CALL FORTRAN subroutine args where subroutine is the name of the subroutine It must be in lowercase even if the original subroutine name is in uppercase and you must add an underscore to the end of the subroutine name args are the subroutine s arguments if any To call multiple subroutines separate them with commas within the argument list For ex ample CALL FORTRAN subroutinel subroutine2 The subroutine is not constrained by the current shape or the context as established by the C program When the call to CALL FORTRAN returns however both the shape and the context are what they were before the function was called VAX users only In addition if you compile on a VAX you must create and compile a JBL Jacket Building Language file to map the subroutine name used in your C program plus a preceding underscore to the subroutine name used by the CM Fortran compiler The CM Fortran c
72. s the argument The function psrand reseeds the random number generator in all processors even those that are not selected when the call occurs Even though a scalar integer is passed to psrand every processor will be seeded for a different sequence of random numbers Actually it may be possible for two processors to have the same sequence given a Connection Machine configuration with many virtual processors The function prand is the parallel version of the rand function SEE ALSO cs abs 3 rand 3 C Programming Guide LIMITATIONS Seed values of 0 and 1 are not accepted by psrand Thinking Machines Last change 10 29 90 1 string h 1 MISC REFERENCE MANUAL PAGES string 1 NAME string h C string handling functions SYNTAX Zinclude lt string h gt SYNOPSIS bool current boolcpy bool current 51 bool current s2 size t ny bool current boolmove bool current s1 bool current s2 size t int current boolcmp const bool current 51 bool current s size t n bool current boolset bool current s bool current c size t n void current memcpy void current 51 void current s2 size t n void current memmove void current 51 void current s2 size t n int current memcmp const void current 51 void current s size t void current memset void current s int current c size t DESCRIPTION The string handling functions under C contain the serial C string handling functions alon
73. scalar to parallel in debugging 41 42 positions and virtual processors 8 turning on and off in debugging 43 44 prand 6 preprocessing 23 printf 42 prof using with C 18 psrand 6 Q qde1 34 qstat 34 qsub 29 32 options for 33 R rand 6 See also prand randomizing a parallel variable 6 region assigning values to 44 45 changing the display of 42 43 defining 38 39 making positions active within 44 82 User 5 Guide making positions inactive in 44 printing values in 40 43 S shapes and Paris VP sets 10 default 4 sparc symbol 26 srand 6 See also psrand status information in debugging 45 lt stdlib h gt 6 7 lt string h gt 6 structures parallel See parallel structures sun symbol 26 T timesharing executing a program under 29 timing functions 5 type default for debugging functions 39 types defining 39 40 U ULTRIX 26 ultrix symbol 26 unix symbol 26 V vax symbol 26 virtual processors 8 VP set IDs 7 45 VP sets 7 and shapes 10 warnings turning off 26
74. tart macro must be called to initialize ap before use by va arg and va end The va arg macro expands to an expression that has the type and value of the next argument in the call The value of ap is modified so that successive calls to va arg will continue to read arguments in the call The va end macro facilitates a normal return from a function that the macros va start and va arg to read a variable argument list EXAMPLE include stdarg h define MAXARGS 32 void f int n params int i array 32 va_list ap va_start ap n_params for i 0 i lt MAXARGS array i va_arg ap int va end ap SEE ALSO ANSI C Programming Language Standard Programming Guide Thinking Machines Last change 10 29 90 1 stdlib h 1 MISC REFERENCE MANUAL PAGES stdlib h 1 NAME stdlib h C generic utilities SYNTAX include lt stdlib h gt SYNOPSIS int abs int i int rand void void srand unsigned seed overload abs int current abs int current i void psrand unsigned seed int current prand void void deallocate shape shape s void void palloc shape s int bsize void pfree void void pvar DESCRIPTION The C generic utilities contain the parallel and scalar overloading of abs The serial function is docu mented on the abs man page the parallel function behaves exactly like the scalar function Which abs function is called depends on whether a scalar or parallel integer is passed a
75. ted as a character If you specify a width of 0 minimum width columns are printed Chapter 5 Debugging Program 43 Use CMC define view to specify the order in which axes are represented for a shape By default axis 0 is represented as rows and axis 1 is represented as columns CMC define view takes the following arguments CMC define view shape row axis column axis Therefore to display axis 0 as the columns and axis 1 as the rows for shape ShapeB call the function as follows dbx call define view ShapeB 1 0 If Shapec is 3 dimensional you can reverse the default method of presenting the axes by calling the function as follows dbx call define view ShapeC 2 1 0 The results of the call remain in effect for a shape even if you call CMC define region to change the region that is to be displayed NOTE To indicate the current shape specify CM current vp set instead of the C key word current 5 5 Setting the Context The CMC on CMC on region CMC off and CMC off region Functions C provides functions that let you make positions active or inactive For a single position call the function CMC on to make a position active call the function off to make it inactive Both take as arguments a shape and the coordinates of the position starting with axis 0 For example dbx call CMC on ShapeB 47 59 makes position 47 59 of ShapeB active call off Shap
76. ter 5 Debugging C Program 37 cs overload myprogram cs myprogram cs line 13 info overloading is sin F_ myprogram cs line 14 info overloading is sin D Table 2 C debugging functions Function and Arguments default type sel define format fype sel format Use Change the default data type to type sel Specify a format for printing define region shape lower bound upper bound define type pvar type spec define view shape row col define width type_sel width CMC help off shape coord CMC off region shape CMC on shape coord CMC on region shape CMC pop context shape CMC print pvar coord CMC print region pvar CMC push context shape set pvar value coord set region pvar value status Specify a region of a shape Specify a data type for a parallel variable Specify the order in which axes are to be represented by CMC print region Specify a width for printing a parallel variable Get information about the debugging functions Make a position inactive Make all positions in the shape s region inactive Make a position active Make all positions in the shape s region active Change the context to the most recently saved context Print the value of one element of a parallel variable Print values of a parallel variable in
77. th 42 help 46 CMC int 39 long double 39 long int 39 off 43 44 off region 43 44 CMC on 43 44 CMC on region 43 44 CMC pop context 44 print 40 43 80 CMC print 40 43 push context 44 set 44 45 set region 44 45 short 39 status 45 cmcoldboot 34 g option 4 cmdetach 34 emfinger 34 CMFS library 12 cmps 34 emsetsafety 34 CMSR library 12 CMSSL calling from C 13 compiler choosing a specific version of 21 compiling changing location of temporary files 25 26 creating assembly source files 25 displaying steps in 24 getting help 21 keeping intermediate files 24 specifying a different pre processor 24 turning off warnings 26 compiling a C program 1 in detail 23 26 the basic process 19 23 context saving and restoring 44 cpp 26 cs 1 19 option 23 option 24 dryrun option 24 force option 24 g option 22 help option 21 keep option 24 line option 25 O option 21 debugging with 35 overload option 25 36 pg option 22 C User 5 Guide f 4 release option 21 S option 25 temp option 25 26 ucode option 22 v option 25 verbose option 25 version option 22 warn option 26 2 option 26 options in common with 22 23 symbols defined for 26 lt escomm h gt 5 cstar symbol 26 lt estimer h gt 5 current shape 7 D dbx
78. that called them In contrast gpro shows the total time spent in each C routine See the CM User 5 Guide for more information about profiling Chapter 3 Compiling Program To compile C program use the command Section 3 1 describes the basics of using cs including the most common options This section contains all the information most programmers need Section 3 2 provides a more detailed look at the compilation process and discusses options more likely to be used by advanced programmers Section 3 3 discusses symbols for which provides defines Section 3 4 explains how to compile a C program that calls a CM Fortran subroutine 3 1 The Basic Compilation Process The es command takes C source file which must have a cs suffix and produces an executable load module The command also accepts c source files output files obj JBL files VAX only and a library files but all parallel code must be in a cs file 3 1 1 Basic Options The options accepted by cs include some that are specific to C and the Connection Ma chine system as well as versions of cc options This section describes commonly used options All options are listed in Table 1 19 20 Option Basic options help h o 0 release number ucode number Version C User 5 Guide Table 1 C compiler options Meaning Give information about cs without compiling Invoke extra C optimization Specify
79. the only argument For example free desc desc You can free a descriptor to a parallel variable of any shape An Example The following is a C program that calls a CM Fortran subroutine finclude stdio h include csfort h shape 16384 S CMC descriptor t desc a int s1 int S 1 main with S 51 1 pl 1 desc wrap pvar amp p1 CALL FORTRAN fortran desc amp 51 free desc desc a printf Result for last position is dMn 16383 1 And here is the simple CM Fortran subroutine it calls subroutine fortran 5 integer a 16384 integer s 18 C Users Guide return end 2 6 Using UNIX Utilities You can use standard UNIX utilities like make prof gprof and dbx with C programs dbx is discussed in Chapter 5 2 6 1 Program Maintenance Utility make The make utility makes object o files from C cs files just as it does with c files The only requirement is that the following code must appear somewhere in the makefile CS cs CSFLAGS CFLAGS SUFFIXES cs CS 0 CS c S CSFLAGS lt 2 6 2 The Profiling Tools prof and gprof The two profiling tools prof and gprof work with C programs just as they do with C programs We recommend using rather than prof since prof shows only the ex ecution times of individual Paris operations without adding them into the times shown for the C routines
80. tion 1 Compile the C program using the option For example cs testcs cs Compile the CM Fortran program also using the option For example emf c testfcm fcm For Vax users only Compile the JBL file you created to map the subroutine name s you used in the C program to those created by the ULTRIX Fortran com piler For example jbl cstofortran jbl This creates a file with a obj suffix that you must link in with your other files Use the emf compiler to link the o files the obj file if you are compiling on VAX and the required libraries You must also link the following library libesrt a the runtime library In addition include any libraries that you need to explicitly link with your program For example a Sun you might issue the emf command as follows emf nocmfmain testcs o testfcm o Zld lcsrt On a VAX you might issue the cm command as follows cmf nocmfmain testcs o testfcm o cstofortran obj Zlk lcsrt The result is an executable load module that you can execute as you normally would Chapter 4 Executing a C Program on a CM Once a C program has been compiled and linked you can execute the output file on a Connection Machine system This chapter gives an overview of how to execute a program on CM system For complete information consult the CM User 5 Guide 1 4 1 Overview To execute a program on a CM you must gain
81. tions Specifying a Queue Use the q option to specify the name of the queue to which the request is to be submitted If you omit this the request is sent to the default queue if one has been set up Receiving Mail Use the mb option to specify that mail is to be sent to you when the request begins execu tion Use to have mail sent to you when the request ends execution Setting the Priority Use the p option followed by an integer from 0 through 63 to set a priority for this re quest in its queue 63 is the highest priority and 0 is the lowest priority The priority 34 User 5 Guide determines the request s position in the queue If you don t set a priority the request is assigned a default priority Specifying Output Files Use the o option followed by a pathname to specify the file to which output of the batch request is to be sent Use the option to specify the pathname for the standard error out put If you omit these options the output is sent to default files based on an ID number assigned to the request by the batch system 4 4 Other CM Commands Other commands are useful in executing programs on the CM For example Use the cm inger command to obtain information about the CM system who is using the interfaces and sequencers and whether any sequencers are free Use the cmdetach command to detach an interface from a sequencer making it available for use by another user
82. to focus on a small subset of them for debugging purposes Initially a shape s region consists of all positions in the shape To change the region use the CMC define region function Its first argument is the name of the shape Then for each dimension specify the beginning and ending coordinates that define the region Start with axis 0 and include beginning and ending coordinates for each axis in the shape For example dbx call CMC define region ShapeA 0 4 defines the region of Shapea as positions 0 through 4 ShapeA must be a 1 dimensional shape dbx call define region ShapeB 0 4 O0 9 Chapter 5 Debugging a C Program 39 defines the region of ShapeB as those positions with coordinates 0 through 4 along axis 0 and 0 through 9 along axis 1 a total of 50 positions ShapeB must be a 2 dimensional shape Note that a region can contain both active and inactive positions Once a region is defined for a shape it stays in effect until you issue another call to CMC define region to change it or until the program finishes execution within dbx NOTE To indicate the current shape specify CM current vp set rather than the C keyword current 5 3 Defining Data Types for Parallel Variables The CMC default type and CMC define type Functions C debugging functions must know the type of a parallel variable before they can operate on it The default type for use with the debugging functions is double To change the
83. u are developing your program since it lets you debug interactively on the CM This kind of access may be relatively difficult to obtain however 4 2 Obtaining Direct Access Use the cmattach command to obtain direct access to CM processors 4 2 1 Executing the Program Immediately To execute a program immediately issue cmattach with the name of the executable pro gram as an argument For example cmattach myprogram attaches to any free interface and sequencer initializes cold boots the sequencer and its processors and executes the program The system displays a message that gives you the following information The name of the CM the number of the sequencer and the number of processors to which you are attaching version of the CM microcode that this sequencer is running Whether Paris level safety checking is on If no sequencers or interfaces are available you receive an error message N 4 2 2 Obtaining an Interactive Subshell Issue cmattach without the name of an executable program to obtain an interactive sub shell If an interface and a sequencer are available you are attached to them and the processors controlled by the sequencer are cold booted You are placed in a UNIX subshell from which you can execute your program enter the debugger or issue any standard UNIX commands To leave the subshell and detach from the CM type exit or the Ctrl D key combination at the UNIX prompt 4 2
84. ween C and C pro gram cstar The C language as opposed to the C language unix Any UNIX system ultrix ULTRIX only vax VAX only sun Sun only sparc Sun 4 only file cs input C code file cpp intermediate preprocessed code file c intermediate C Paris code file o relocatable object file file obj VAX JBL object file file a object library a out linked executable output lib cpp C preprocessor usr include cs directory of C include files usr local lib cstar C compiler executable bin cc C compiler usr local lib libesrt a library linked by default usr local lib libesrt pg a default profiling library usr local lib libparis a Paris library linked by default Thinking Machines Last change 11 01 90 2 5 1 MISC REFERENCE MANUAL PAGES cs 1 SEE ALSO cc 1 dbx 1 Thinking Machines Corporation C documentation set C Programming Guide C Release Notes and C User s Guide DIAGNOSTICS Occasional messages may be produced by the C compiler assembler or linker in addition to those nor mally produced by the C compilation phase RESTRICTIONS Bugs and restrictions are listed in the C Release Notes Thinking Machines Last change 11 01 90 3 cscomm h 1 MISC REFERENCE MANUAL PAGES cscomm h 1 NAME cscomm h C communication functions SYNTAX Zinclude lt cscomm h gt SYNOPSIS overload get send scan global overload spread copy spread multispread copy multispread reduce copy reduc

C* User`s Guide

Contents

Download Pdf Manuals

Related Search

Related Contents