Occam 2.1 toolset user guide

August 1995
INMOS document number: 72-TDS-366-02
285 Pages

About this manual

This manual is the User Guide to the occam 2.1 toolset.

The manual describes the use of the toolset in developing programs for running on the transputer. The manual is divided into two parts; Basics which describes each of the main stages of the development process, how to configure occam programs for the transputer and how to build and load them. It also includes a Getting started tutorial. The Advanced Techniques part is aimed at more experienced users. The Appendices contain some reference material, a glossary of terms and a bibliography. Some chapters are in common with other toolsets e.g. Developing programs for the transputer and Mixed language programming.

Host versions

The documentation set which accompanies the occam 2.1 toolset is designed to cover all host versions of the toolset:

Contents

	Contents overview
	Preface
		Host versions
		About this manual
		About the toolset documentation set
		Other documents
		Transputer targets supported by this toolset
		Documentation conventions

Part 1: Basics

	1	Introduction to transputers
		1.1	Transputers
			1.1.1	Transputer links
			1.1.2	Process scheduling
			1.1.3	Real time programming
			1.1.4	Multi-transputer systems
		1.2	Programming models
			1.2.1	Parallel processing model
		1.3	Transputer products
			1.3.1	Toolset products

	2	Overview of the toolset
		2.1	Introduction
		2.2	Toolset features
		2.3	Standard object file format
		2.4	occam 2.1 compiler
			2.4.1	Programming model
			2.4.2	Language extensions
			2.4.3	occam libraries
			2.4.4	Low level programming
		2.5	Multi-language linker
		2.6	Configuration system
			2.6.1	Software routing and multiplexing
			2.6.2	Code and data placement
		2.7	Mixed language programming
		2.8	Toolset summary

	3	Getting started
		3.1	Introduction
		3.2	Running the examples
			3.2.1	Sources
		3.3	The example program
			3.3.1	Compiling the program
			3.3.2	Linking the program
			3.3.3	Configuring the program
			3.3.4	Collecting the program
			3.3.5	Running the program on a transputer board
			3.3.6	A short cut to creating a bootable file
		3.4	Compiling and linking for other transputer types
		3.5	Using the Makefile generator

	4	Developing programs for the transputer
		4.1	Program development using the toolsets
			4.1.1	Compatibility with previous toolset releases
		4.2	Compiling
		4.3	Tools for building executable code
			4.3.1	Linker - ilink
			4.3.2	Configurer - occonf
			4.3.3	Code collector - icollect
		4.4	Loading and running programs
			4.4.1	Host file server
			4.4.2	Skip bootables
		4.5	Program development and support
			4.5.1	Librarian - ilibr
			4.5.2	Binary lister - ilist
			4.5.3	Makefile generator - imakef
			4.5.4	Memory map tool - imap
		4.6	EPROM programming
		4.7	Mixed language programming
		4.8	File types and filename extensions
			4.8.1	Filename extensions required by imakef
		4.9	Error reporting
		4.10	Host dependencies
			4.10.1	Filenames
			4.10.2	Search path
			4.10.3	Environment variables
			4.10.4	Default command line arguments
		4.11	Unsupported options

	5	An example program
		5.1	Overview of the program
		5.2	The channel protocol
		5.3	The sorting element
		5.4	The input/output process
		5.5	The calling program
		5.6	Compiling the program
		5.7	Linking the program
		5.8	Configuring and collecting the program
		5.9	Running the program
		5.10	Automated program building

	6	Programming in occam
		6.1	Host channels
			6.1.1	Interrupting programs
		6.2	occam error handling
			6.2.1	Error modes
			6.2.2	Error detection compiler options
		6.3	Library i/o
		6.4	Alias and usage checking
		6.5	Using separate vector space
		6.6	Sharing source between files
		6.7	Separate compilation
			6.7.1	Sharing protocols and constants
			6.7.2	Compiling and linking large programs
		6.8	Using imakef
		6.9	Libraries
			6.9.1	Selective loading
			6.9.2	Building libraries

	7	Configuring transputer networks
		7.1	Introduction to configuration
			7.1.1	What is configuration?
			7.1.2	Mixing languages
		7.2	Configuration model
			7.2.1	Configuration tools
			7.2.2	Configuration language
			7.2.3	Importing code and source files
			7.2.4	Overall structure of a configuration description
		7.3	Hardware description
			7.3.1	Declaring processors
			7.3.2	NODE attributes
			7.3.3	NETWORK description
			7.3.4	Declaring EDGEs
			7.3.5	Declaring ARCs
			7.3.6	Abbreviations
			7.3.7	Host connection
			7.3.8	Example - a single processor connected to the host
			7.3.9	Example - a simple pipeline
			7.3.10	Example - a square array with host interface processor
		7.4	Software description
			7.4.1	Libraries of linked units
			7.4.2	Example
		7.5	Mapping description
			7.5.1	Mapping processors
			7.5.2	Mapping channels
			7.5.3	Mapping without a MAPPING section
			7.5.4	Mapping example - pipeline sorter on a single processor
			7.5.5	Mapping example - pipeline sorter on a ring of processors
		7.6	Example - a pipeline sorter on four transputers
			7.6.1	Building the program
			7.6.2	Running the program
			7.6.3	Automated program building
			7.6.4	Other configuration examples
		7.7	Summary of configuration steps

	8	Loading application programs
		8.1	Introduction
		8.2	Tools for loading
		8.3	The boot from link loading mechanism
			8.3.1	Initializing the ST20450 memory interface
		8.4	Boards and subnetworks
			8.4.1	System services wiring
			8.4.2	Connecting subnetworks
		8.5	AServer and the AServer database
			8.5.1	AServer
			8.5.2	AServer database
		8.6	Skip loading
			8.6.1	Invoking skip bootables
		8.7	Clearing error flags

	9	Access to host services
		9.1	Introduction
		9.2	Communicating with the host
			9.2.1	The host file server
			9.2.2	Library support
			9.2.3	File streams
		9.3	Accessing the host from a program
		9.4	Multiplexing processes to the host
			9.4.1	Buffering processes to the host
			9.4.2	Pipelining

Part 2: Advanced techniques

	10	Advanced use of the configurer
		10.1	Support for INQUEST
		10.2	Code and data placement
			10.2.1	Default memory map
			10.2.2	Other memory configurations
			10.2.3	Reserving memory
			10.2.4	Absolute address code placement
			10.2.5	Ordering code and data segments
		10.3	Channel communication - configuration techniques
			10.3.1	Routing and placement constants
			10.3.2	Optimizing important application channels
			10.3.3	Virtual communications - use of fast memory
		10.4	Control of routing
			10.4.1	Routing cost
			10.4.2	Tolerance
			10.4.3	Link quota
			10.4.4	The minimal spanning tree
			10.4.5	Summary of routing attributes
			10.4.6	Prevention of through-routing via critical processors
			10.4.7	Use of additional processors for through-routing
			10.4.8	Support for memory-critical systems
		10.5	Example - optimized filter test program

	11	Mixed language programming
		11.1	Mixed language programs
			11.1.1	Declaring external routines
			11.1.2	Translating identifiers
			11.1.3	Parameter passing
			11.1.4	Global static base parameter
			11.1.5	Function return values
			11.1.6	Passing array parameters
			11.1.7	Linking the program
			11.1.8	Allocating memory for C functions called from occam
			11.1.9	Restrictions and caveats
		11.2	occam interface procedures
			11.2.1	Interface code
			11.2.2	Parameters to the C program
			11.2.3	Stack and heap requirements
			11.2.4	Type 1 interface definition
			11.2.5	Type 2 interface definition
			11.2.6	Type 3 interface definition
			11.2.7	Building the occam equivalent process

	12	Low level programming
		12.1	Allocation
			12.1.1	The PLACE statement
			12.1.2	Allocating specific workspace locations
			12.1.3	Allocating channels to links
		12.2	Retyping channels and creating channel array constructors
		12.3	Code insertion
			12.3.1	Using the code insertion mechanism
			12.3.2	Special names
			12.3.3	Labels and jumps
			12.3.4	Workspace zero
			12.3.5	Below workspace slots
			12.3.6	Channels
			12.3.7	Programming notes
		12.4	Dynamic code loading
			12.4.1	Calling code
			12.4.2	Loading parameters
			12.4.3	Examples
		12.5	Extraordinary use of links
			12.5.1	Programming concerns
			12.5.2	Input and output procedures
			12.5.3	Recovery from failure
			12.5.4	Example - unreliable connections
		12.6	Scheduling
		12.7	Setting the error flag

	13	EPROM programming
		13.1	Introduction
		13.2	Processing options
			13.2.1	Single processor, run from ROM
			13.2.2	Single processor, run from RAM
			13.2.3	Multi-processor, run from RAM
			13.2.4	Multi-processor, root run from ROM, rest of network run from RAM
		13.3	The EPROM tool: ieprom
		13.4	Producing ROM-boatable code
		13.5	Summary of EPROM tool steps for different configurations
			13.5.1	Using icconf
			13.5.2	Using occonf

	14	ST20450 memory interface configuration
		14.1	The memory interface
		14.2	General parameters
			14.2.1	Waveform diagrams
		14.3	Timing
			14.3.1	Strobes
			14.3.2	Timing skews
		14.4	Configuring for no external memory
		14.5	Configuring for SRAM
			14.5.1	Timings
		14.6	Configuring for DRAM and Video RAM
			14.6.1	Timings
			14.6.2	Refresh
		14.7	Configuring for ROM
			14.7.1	EPROM
			14.7.2	Flash EPROM
		14.8	Configuring for non-memory devices
		14.9	Building and using memory configuration code
			14.9.1	Booting from link
			14.9.2	Booting from an application code ROM
			14.9.3	Booting from a memory configuration ROM

	15	Performance improvement
		15.1	Introduction
			15.1.1	Transputer architecture
		15.2	Trade-offs and issues
			15.2.1	Space versus time
			15.2.2	On-chip RAM
			15.2.3	Basic code generation techniques
			15.2.4	Processor classes and types
			15.2.5	Interactive debugging
			15.2.6	Virtual routing
			15.2.7	Error modes
			15.2.8	Vector space
			15.2.9	Alias checking
			15.2.10	Usage checking
			15.2.11	Memory layout
			15.2.12	When there is not enough on-Chip RAM
		15.3	Obtaining information
		15.4	Command line switches
			15.4.1	Compiler command line switches
			15.4.2	Linker command line switches
			15.4.3	Linker directives
			15.4.4	Configurer command line switches
			15.4.5	Configuration language attributes for optimizing memory
			15.4.6	Collector command line switches
		15.5	Compiler optimizations
		15.6	Source code optimizations
			15.6.1	Compiler workspace layout
			15.6.2	Compiler code layout
			15.6.3	Abbreviations
			15.6.4	Vector space
			15.6.5	Beware the PLACE statement
			15.6.6	Abbreviating PLACED objects
			15.6.7	Block move
			15.6.8	Use TIMES
			15.6.9	Retyping - accelerating byte manipulation
			15.6.10	Scoping of variables
			15.6.11	Use the whole language
			15.6.12	INLINE procedures and functions
			15.6.13	Access to non-local variables
			15.6.14	Access to formal parameters
			15.6.15	Pre-evaluate expressions
			15.6.16	Conditional expressions
			15.6.17	Array SUbscripts
			15.6.18	INT16s
			15.6.19	ALTs
			15.6.20	Use of ASSERT()
			15.6.21	Transputer scheduler
		15.7	Summary
			15.7.1	Optimizing for code size
			15.7.2	Removing run-time checks
			15.7.3	Placing arrays in on-chip RAM
			15.7.4	Placing code in on-chip RAM
			15.7.5	Building benchmarks
		15.8	Maximizing multiprocessor performance
			15.8.1	Maximizing link performance
			15.8.2	Large link transfers
		15.9	Dynamic load balancing and processor farms

	Appendices

	A	Equivalent data types
		A.1	occam as the calling language
			A.1.1	Example of passing parameters from occam to C
			A.1.2	Parameter passing
			A.1.3	Return values
			A.1.4	typedef types
		A.2	C as the calling language
			A.2.1	Example of passing parameters
			A.2.2	Parameter passing
			A.2.3	Return values
			A.2.4	Named types

	B	Transputer code insertion
		B.1	Inline transputer code insertion
			B.1.1	Sequential code insertion
			B.1.2	Full code insertion
		B.2	ASM construct
			B.2.1	Syntax
			B.2.2	ASM instructions
			B.2.3	Pseudo operations
		B.3	Instructions supported by sequential code insertion

	C	Glossary

	D	Bibliography
		D.1	Transputers
		D.2	C programming
		D.3	occam programming
		D.4	Technical notes
		D.5	Development systems
		D.6	References

	Index

Back to the top