3L Parallel C user guide
February 1989
INMOS document number: 72-TDS-179-00
278 Pages
© INMOS Limited 1989.
1 How to use the manual
Intended audience
This User Guide accompanies 3L's Parallel C product, and is intended for anyone who wants to use Parallel C to program a transputer system, whether writing a conventional sequential program or using the full support for concurrency which the transputer processor has to offer.
1.1 How to use the manual
There are three main divisions within this document, as follows:
- User guide
- Reference manual
- Appendices
Each of the sections is described briefly below.
1.2 User guide
The user guide introduces you to the operation of the compiler and the other tools supplied with Parallel C. In particular, there are tutorial sections explaining parallelism on the transputer and the way in which this can be accessed from Parallel C programs.
1.3 Reference manual
The reference manual contains the detailed technical information which you will require to write sophisticated applications for the transputer using Parallel C.
1.4 Appendices
The appendices at the end of this manual contain supplementary information in a condensed form, such as tables of transputer assembly language mnemonics.
Further reading
This User Guide does not attempt to teach the C language itself; rather, reference should be made to one of the many introductory texts available. The first - and still one of the best - books about C is the original book describing the language. This is The C Programming Language [1], by Kernighan and Ritchie.
In a similar way, the reader is assumed to be reasonably familiar with the operating system of the host computer being used. For personal computers made by IBM, this will usually be PC-DOS, which is supplied with a manual called Disk Operating System Reference [2]. For compatible machines made by other manufacturers, the operating system will usually be MS-DOS, described in Microsoft MS-DOS Users Reference [3]. These two operating systems are largely compatible, and their documentation is very similar.
References to these and other documents mentioned in this manual are collected in a bibliography, which can be found on page 259.
1.5 Host operating system dependencies
Operating system dependencies are as far as possible made invisible to the user. The few differences are summarized below.
Command line syntax
The major difference between different host implementations is the option prefix character. For UNIX based toolsets the prefix character is the hyphen '-'; for all other toolsets it is the forward slash character '/'.
This manual uses the '-' character in all examples where the tools are invoked from the host operating system.
Directories and files
Directories and pathnames are treated in a host dependent manner, whereas filenames are independent of the host, with certain restrictions. As long as the directory names are legal for the host operating system, they can also be treated as host independent.
A directory path searching mechanism is implemented within the compiler, and full pathnames need not be given.
Contents
Contents Contents overview 1 How to use the manual 1.1 How to use the manual 1.2 User guide 1.3 Reference manual 1.4 Appendices 1.5 Host operating system dependencies
The user guide
2 Programming single transputers 2.1 Outline procedure 2.2 A simple example 2.3 A more complex example 2.4 Indirect linker files 2.5 Libraries 3 Introduction to Parallel C 3.1 Abstract model 3.2 Hardware realisation 3.3 Software model 3.4 Parallel execution threads 3.5 Configuring an application 3.6 Processor farms 4 Programming transputer networks 4.1 Configuring one user task 4.1.1 Hardware configuration 4.1.2 Software configuration Declaring tasks Making connections between tasks Assigning tasks to processors 4.1.3 Building the application Building a task image Configuring the task images 4.2 More than one user task 4.2.1 Inter-task communication functions 4.2.2 Building the application 4.3 Access to host services 4.4 Multi-transputer systems 4.5 Multi-threaded tasks 4.5.1 Creating threads 4.5.2 Threads versus tasks 4.6 Debugging 4.7 Estimating memory requirements 5 Processor farms 5.1 The worker task 5.2 The master task 5.3 The net functions 5.4 Building the application 5.4.1 Building master and worker task images 5.4.2 Configuration file 5.4.3 Configuration 5.4.4 Running the example 5.5 Mixed networks
The reference manual
6 config general purpose configurer 6.1 Running the configurer 6.2 The distributing loader 6.2.1 Bootstrapping a transputer 6.2.2 Bootstrapping a network 6.2.3 Loader command stream 6.2.4 Memory allocation 7 decode utility 7.1 Usage 7.2 Features of the decode program 7.3 Other languages 8 fconfig flood-fill configurer 8.1 Running the flood-fill configurer 8.2 User task protocol 8.2.1 Master task's ports 8.2.2 Worker task's ports 8.3 Packet format 9 iboot bootstrap 9.1 Running the iboot tool 9.2 What can be made executable 9.3 Producing task Images 9.4 Bootstrap loader interface 9.5 Error messages 10 ilibr librarian 10.1 Introduction 10.2 Running the librarian 10.3 Exploding libraries 10.4 Removing debug data 10.5 Rules for constructing libraries 10.6 Library Modules 10.6.1 Selective loading 10.7 Building libraries 10.8 Indirect files 10.9 Error messages 11 ilink linker 11.1 Introduction 11.2 Notes on using the linker 11.2.1 Output files 11.2.2 Processor type checks 11.2.3 Selective loading of library files 11.3 Running the linker 11.4 Redirected command input 11.4.1 Linker indirect files 11.5 Linker options 11.5.1 Option M - disable file Map 11.5.2 Option E - extend link capacity 11.5.3 Option S - disable Symbol table 11.5.4 Option B - change Buffer size Calculating memory requirements for a linked program 11.5.5 Option Q - optimise symbols 11.5.6 Order of linking of object files 11.6 Error messages 12 iserver host file server 12.1 Running the server 12.1.1 Loading programs 12.1.2 Specifying link address - option SL 13 tc C compiler 13.1 Running the compiler 13.2 Compiler switches 13.2.1 Controlling output files Switches FB and FO Switch FL 13.2.2 Controlling object code Switches T4, T8 and T8A Switch S Switch PCn Switch C 13.2.3 Controlling #include processing Switch Idirectory Switch X 13.2.4 Macro definitions Switch Dmacro and Dmacro=string Switch Umac 13.2.5 Information from the compiler Switch I Switch M Switch V 13.2.6 Obsolescent switches 13.3 Compiler error messages 13.3.1 Compiler error message format 13.3.2 Fixing errors detected by the compiler 13.3.3 Compiler control lines 13.3.4 List of error messages Program errors System errors Code generator errors 13.3.5 Errors in assembler code 14 C language implementation 14.1 The C language 14.1.1 Restrictions Loose type checking of '.' and -> operators White space within compound operators Use of sizeof in array declarations #line ignored Anachronisms not allowed 14.1.2 Extensions Dollar sign in identifiers More significant characters in identifiers Assignment to whole struct/union variables Restrictions on struct member names relaxed type-name syntax relaxed 14.1.3 Keywords 14.2 System-dependent features 14.2.1 Data type enum not allowed 14.2.2 All bit fields unsigned 14.2.3 >> operator 14.2.4 Register variables 14.3 Predefined macros 14.4 Handling of #include files 14.5 Assembly language 14.5.1 When to use assembly language 14.5.2 Assembly language syntax 14.5.3 Literal operands 14.5.4 Variables as operands Storage class Type 14.5.5 Accessing complex structures 14.5.6 Labels and jumps Labels within asm statements Jump optimisations 14.5.7 Literal machine code 14.5.8 Errors 14.6 Data-type representations 15 The C run-time library 15.1 Purpose of the run-time library 15.2 Conventions 15.3 Header files 15.4 Library modules 15.4.1 Input/output Standard I/O Low-level I/O 15.4.2 Mathematical functions 15.4.3 String handling 15.4.4 Character classification 15.4.5 Conversions 15.4.6 Dynamic memory allocation 15.4.7 Date and time 15.4.8 thread package 15.4.9 sema package 15.4.10 timer package 15.4.11 chan package 15.4.12 net package 15.4.13 par package 15.4.14 Compatibility channel I/O 15.4.15 Miscellaneous 15.5 The C main program 15.6 Reduced run-time library 16 Alphabetic list of run-time library functions 17 Configuration language 17.1 Standard Syntactic Metalanguage 17.2 Configuration Language Syntax 17.2.1 Low Level Syntax 17.2.2 Numeric Constants 17.2.3 String Constants 17.2.4 Identifiers 17.2.5 Statements 17.2.6 PROCESSOR Statement 17.2.7 WIRE Statement 17.2.8 TASK Statement INS Attribute OUTS Attribute FILE Attribute Memory Size Attributes OPT Attribute URGENT Attribute Port Specifiers 17.2.9 CONNECT Statement 17.2.10 PLACE Statement 17.2.11 BIND Statement
Appendices
A Task data sheets B Harnesses and run-time libraries B.1 Harnesses B.2 Run-time libraries B.2.1 Core maths run-time library C Transputer instructions C.1 Pseudo-instructions C.2 Prefixing instructions C.3 Direct instructions C.4 Operations C.5 T414-only instructions C.6 T800-only instructions C.6.1 Floating-point instructions C.6.2 Other T800-only instructions D Conventions and defaults D.1 Command line conventions D.2 Filename conventions D.3 File location conventions D.4 Search paths on the IBM PC and SUN3 D.5 Search paths on VMS systems E ASCII code chart Bibliography Index