3L Parallel C user guide

February 1989
INMOS document number: 72-TDS-179-00
278 Pages

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

Back to the top