Occam 2 toolset user guide

March 1993
INMOS document number: 72-TDS-366-01
344 Pages

About this manual

This manual is the User Guide to the occam 2 toolset and is divided into two parts: 'Basics' and 'Advanced Techniques' plus appendices. In addition some chapters are generic to other INMOS toolsets.

Differences from the previous release of the occam 2 toolset are listed immediately after this preface.

The basic section introduces the transputer and the toolset; provides an overview of the development cycle and then provides a chapter on each of the following:

The advanced section is aimed at the more experienced user and covers the following topics:

• Advanced use of the configurer including placing code and data at specific memory locations and the software virtual through-routing mechanism.
• Mixed language programming.
• Developing programs for EPROM.
• Low level programming facilities provided by the toolset e.g. dynamic code loading.

The appendices provided in the User Guide include a glossary of terms and a bibliography.

Contents

	Contents overview
	Preface
		Host versions
		About this manual
		Examples used in this manual
		About the toolset documentation set
		Other documents
		FORTRAN toolset
		INQUEST
		Documentation conventions

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	Multitransputer systems
	1.2	Programming models
		1.2.1	Parallel processing model
	1.3	Transputer products
		1.3.1	Toolset products

2	Introduction to the toolset
	2.1	Introduction
	2.2	Toolset features
	2.3	Standard object file format
	2.4	occam 2 compiler
		2.4.1	Programming model
		2.4.2	Language extensions
		2.4.3	occam libraries
		2.4.4	Low level programming
	2.5	Multilanguage 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	Developing programs for the transputer
	3.1	Introduction
	3.2	Program development using the toolsets
		3.2.1	Compatibility with previous toolset releases
	3.3	Compiling
	3.4	Tools for building executable code
		3.4.1	Linker - ilink
		3.4.2	Configurer
		3.4.3	Code collector - icollect
	3.5	Loading and running programs
		3.5.1	Host file server - iserver
		3.5.2	Skip loader - iskip
	3.6	Program development and support
		3.6.1	Network debugger - idebug
		3.6.2	Memory dumper - idump
		3.6.3	Librarian - ilibr
		3.6.4	Binary lister - ilist
		3.6.5	Makefile generator - imakef
		3.6.6	Memory map tool - imap
		3.6.7	T425 simulator - isim
	3.7	EPROM programming
		3.7.1	EPROM programmer - ieprom
		3.7.2	Memory configurer - iemit
	3.8	File types and extensions
		3.8.1	File extensions required by imakef
	3.9	Error reporting
	3.10	Host dependencies
		Command line syntax
		3.10.1	Filenames
		3.10.2	Search path
		3.10.3	Environment variables
		3.10.4	Default command line arguments
	3.11	Linker startup and indirect files
		3.11.1	ANSI C Toolset
			cstartup.lnk
			cstartrd.lnk
			cnonconf.lnk
		3.11.2	occam 2 Toolset
		3.11.3	Mixed language programs
		3.11.4	Other startup files supplied with the ANSI C Toolset
	3.12	Unsupported options

4	Getting started
	4.1	Introduction
	4.2	Running the examples
		4.2.1	Sources
		4.2.2	Example command lines
		4.2.3	Using the simulator
	4.3	The example program
		4.3.1	Compiling the program
		4.3.2	Linking the program
		4.3.3	Configuring the program
		4.3.4	Collecting the program
		4.3.5	Running the program on a transputer board
		4.3.6	Running the program using isim
		4.3.6	Running the program using isim
		4.3.7	A short cut to creating a bootable file
	4.4	Compiling and linking for other transputer types
	4.5	Using imakef

5	Programming single transputers
	5.1	Program examples
	5.2	occam programs
		5.2.1	Compiling programs
			Compilation information
		5.2.2	Linking programs
		5.2.3	Displaying the contents of code files
		5.2.4	Making bootable programs
		5.2.5	Loading and running programs
		5.2.6	Interrupting programs
	5.3	occam error handling
		5.3.1	Error modes
			Error mode UNDEFINED
		5.3.2	Error detection
	5.4	Interactive debugging and virtual routing
	5.5	Alias and usage checking
	5.6	Using separate vector space
	5.7	Sharing source between files
	5.8	Separate compilation
		5.8.1	Sharing protocols and constants
		5.8.2	Compiling and linking large programs
	5.9	Using imakef
	5.10	Libraries
		5.10.1	Selective loading
		5.10.2	Building libraries
	5.11	Example program - the pipeline sorter
		5.11.1	Overview of the program
		5.11.2	The channel protocol
		5.11.3	The sorting element
		5.11.4	The input/output process
		5.11.5	The calling program
		5.11.6	Compiling the program
		5.11.7	Linking the program
		5.11.8	Configuring and collecting the program
		5.11.9	Running the program
		5.11.10	Alternative method of creating a bootable file
		5.11.11	Automated program building

6	Configuring transputer networks
	6.1	Introduction
		6.1.1	Mixing languages
	6.2	Configuration model
		6.2.1	Configuration language
			Importing code and source files
		6.2.2	Overall structure of a configuration description
	6.3	Hardware description
		6.3.1	Declaring processors
		6.3.2	NODE attributes
		6.3.3	NETWORK description
		6.3.4	Declaring EDGEs
		6.3.5	Declaring ARCs
		6.3.6	Abbreviations
		6.3.7	Host connection
		6.3.8	Examples of network descriptions
	6.4	Software description
		6.4.1	Libraries of linked units
		6.4.2	Example
	6.5	Mapping descriptions
		6.5.1	Mapping processes
		6.5.2	Channels
		6.5.3	Mapping channels
		6.5.4	Mapping without a MAPPING section
		6.5.5	Moving code and data areas
		6.5.6	Reserving memory
		6.5.7	Absolute address code placement
		6.5.8	Control of routing and virtual channel placement
			routecost
			tolerance
			linkquota
			occonf.inc
		6.5.9	Control of debugging by the INQUEST tools
		6.5.10	Mapping examples
	6.6	Example: A pipeline sorter on four transputers
		6.6.1	Building the program
		6.6.2	Running the program
		6.6.3	Automated program building
		6.6.4	Other configuration examples
	6.7	Conditional configurations
		6.7.1	Example: Configuration using conditional IF
	6.8	Summary of configuration steps
	6.9	Further considerations
		6.9.1	The effect of occonf on idebug
		6.9.2	Reliable Channel Communications
		6.9.3	Checking the configuration

7	Loading transputer programs
	7.1	Introduction
	7.2	Tools for loading
	7.3	The boot from link loading mechanism
	7.4	Boards and subnetworks
		7.4.1	Subsystem wiring
		7.4.2	Connecting subnetworks
	7.5	Loading programs for debugging
		7.5.1	Breakpoint debugging
		7.5.2	Board types
		7.5.3	Use of the root transputer
		7.5.4	Analyse and Reset
	7.6	Example skip load
		7.6.1	Target network
		7.6.2	Loading the program
		7.6.3	Clearing the network

8	Access to host services
	8.1	Introduction
	8.2	Communicating with the host
		8.2.1	The host file server
		8.2.2	Library support
		8.2.3	File streams
			Protocols
	8.3	Host implementation differences
	8.4	Accessing the host from a program
		8.4.1	Using the simulator
	8.5	Multiplexing processes to the host
		8.5.1	Buffering processes to the host
		8.5.2	Pipelining

9	Debugging transputer programs
	9.1	Introduction
		9.1.1	Post-mortem debugging
		9.1.2	Interactive debugging
		9.1.3	Mixed language debugging
		9.1.4	Debugging with isim
	9.2	Programs that can be debugged
	9.3	Compiling programs for debugging
			Minimal debugging information
			occam channel communication
			C channel communication
		9.3.1	Error modes
	9.4	Debugging configured programs
		9.4.1	Debugging with configuration level channels
		9.4.2	Debugging with the configurer reserved attribute
	9.5	Debugging boot from ROM programs
	9.6	Post-mortem debugging
		9.6.1	C and FORTRAN programs
		9.6.2	occam programs
		9.6.3	Interrupted programs
		9.6.4	Parity errors
		9.6.5	Debugging the root transputer
			Skip loading
	9.7	Interactive debugging
		9.7.1	Runtime kernel
		9.7.2	Processors without hardware breakpoint support
		9.7.3	Creating programs for debugging
		9.7.4	Loading the program
			Clearing error flags
			Parity-checked memory
		9.7.5	Running the debugger
		9.7.6	Interactive mode functions and commands
			Symbolic functions
			Monitor page commands
		9.7.7	Breakpoints
	9.8	Program termination
	9.9	Symbolic facilities
			Help screen
		9.9.1	Locating to source code
		9.9.2	Browsing source code
		9.9.3	Inspecting source code and variables
		9.9.4	Jumping down channels
		9.9.5	Tracing procedure calls
		9.9.6	Modifying variables
		9.9.7	Breakpointing
		9.9.8	Miscellaneous functions
	9.10	Monitor page
		9.10.1	Startup display
			Process Workspace or Stack
			Process Descriptors
			Process pointers
			Practical notes
			Registers
			Error flags
			Clocks
			Parity errors
			Memory map
		9.10.2	Monitor page commands
			Examining memory
			Locating processes
			Specifying processes
			Selecting processes
			Other processors
			Breakpoint commands
			Changing to post-mortem debugging
	9.11	Locating processes
		9.11.1	Running on the processor
		9.11.2	Waiting on a run queue
		9.11.3	Waiting on a timer queue
		9.11.4	Waiting for communication on a link
		9.11.5	Waiting for communication on a software virtual link
		9.11.6	Waiting for communication on a channel
		9.11.7	Interrupted by a high priority process
		9.11.8	Processes terminated or not started
		9.11.9	Locating to procedures and functions
	9.12	Debugging support library
		9.12.1	Examples
			C example
			occam example
		9.12.2	Actions when the debugger is not available
	9.13	Debugging with isim
		9.13.1	Command interface
		9.13.2	Using the simulator
		9.13.3	Program execution monitoring
			Breakpoints
			Single step execution
		9.13.4	Core dump file
	9.14	Hints and further guidance
		9.14.1	Invalid pointers
		9.14.2	Examining and disassembling memory
		9.14.3	Scope rules
		9.14.4	Inspecting soft configuration channels
		9.14.5	Locating to IF, ALT and CASE in occam
		9.14.6	Analyzing deadlock
	9.15	Points to note when using the debugger
		9.15.1	Abusing hard links
		9.15.2	Examining an active network (the network is volatile)
		9.15.3	Using INSPECT with channel communications
		9.15.4	Debugging in the presence of software virtual links
		9.15.5	Selecting events from specific processors
		9.15.6	Minimal confidence check
		9.15.7	INTERRUPT key
		9.15.8	Program crashes
		9.15.9	Undetected program crashes
		9.15.10	Debugger hangs when starting program
		9.15.11	Debugger hangs
		9.15.12	Catching concurrent processes with breakpoints
		9.15.13	Phantom breakpoints
		9.15.14	Breakpoint configuration considerations
		9.15.15	Determining connectivity and memory sizes
		9.15.16	Long source code lines
		9.15.17	Resuming breakpoints on the transputer seterr instruction
		9.15.18	Shifting by large or negative values
		9.15.19	Aspects of C debugging
			Arrays as arguments to C functions
			Backtracing with concurrent C processes
			Errors generated by the full C library
			Errors generated by the reduced C library
			C compiler optimizations
	9.16	C debugging example
		9.16.1	The example program
		9.16.2	Compiling and loading the example
		9.16.3	Setting initial breakpoints
		9.16.4	Starting the program
		9.16.5	Entering the debugger
		9.16.6	Inspecting variables
		9.16.7	Finding addresses of variables
		9.16.8	Backtracing
		9.16.9	Jumping down a channel
		9.16.10	Inspecting by expression
		9.16.11	Modifying a variable
		9.16.12	Backtracing to main()
		9.16.13	Entering #include files
		9.16.14	Quitting the debugger
	9.17	occam debugging example
		9.17.1	The example program
		9.17.2	Compiling the facs program
			Using imakef
			Using the tools directly
	9.18	Breakpoint debugging
		9.18.1	Loading the program
		9.18.2	Setting initial breakpoints
		9.18.3	Starting the program
		9.18.4	Entering the debugger
		9.18.5	Inspecting variables
		9.18.6	Backtracing
		9.18.7	Jumping down a channel
		9.18.8	Modifying a variable
		9.18.9	Entering #INCLUDE files
		9.18.10	Resuming the program
		9.18.11	Clearing a breakpoint
		9.18.12	Quitting the debugger
	9.19	Post-mortem debugging
		9.19.1	Running the example program
		9.19.2	Creating a memory dump file
		9.19.3	Running the debugger
			Inspecting variables
			Inspecting channels
			Retracing and Backtracing
			Displaying process queues
			Goto process

Advanced techniques

10	Advanced use of the configurer
	10.1	Code and data placement
		10.1.1	Default memory map
		10.1.2	Other memory configurations
		10.1.3	reserved attribute
			Example
		10.1.4	location attributes
			Example (on a 32úbit processor)
		10.1.5	order attributes
		10.1.6	location versus order attributes
	10.2	Channel communication - configuration techniques
		10.2.1	Routing and placement constants
		10.2.2	Optimizing important application channels
		10.2.3	Virtual communications - use of fast memory
		10.2.4	Control of routing and placement
			Introduction to routing and placement attributes
			Routing cost
			Tolerance
			Link quota
			The minimal spanning tree
			Summary of routing and placement attributes
			Prevention of through-routing via critical processors
			Use of additional processors for through-routing
			Support for memory-critical systems
	10.3	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
			Parameter compatibility
			Range checking in occam
			occam timers
		11.1.4	Passing array parameters
			C calling occam
			Multi-dimensional arrays (C calling occam)
			occam calling C
			Multi-dimensional arrays (occam calling C)
		11.1.5	Function return values
			C function type void
			Restrictions on functions that may be called
		11.1.6	Global static base parameter
			Method 1 - dummy GSB parameter
			Method 2 - nolink pragma
			Method 3 - using call_without_gsb function
		11.1.7	Linking the program
			Calling occam from C
			Calling C from occam
		11.1.8	Allocating memory for C functions called from occam
			The static area
			The heap area
			Providing static and heap
			Deciding whether a static area is required
			Calling functions which do not require static or heap
			Calling functions which do require static or heap
			Example
		11.1.9	Restrictions and caveats
			General
			Rules for importing C code
			Rules for importing occam code
	11.2	occam interface procedures
		11.2.1	Interface code
			Type 1
			Type 2
			Type 3
			Channel arrays
			Reserved channels
		11.2.2	Parameters to the C program
		11.2.3	Stack and heap requirements
			Stack overflow detection
		11.2.4	Type 1 interface definition
			Procedural interface
			Parameters to C program
			Example
		11.2.5	Type 2 interface definition
			Procedural interface
			Parameters to C program
			Example
		11.2.6	Type 3 interface definition
			Procedural interface
			Parameters to C program
			Example
		11.2.7	Building the occam equivalent process

12	EPROM programming
	12.1	Introduction
	12.2	Processing configurations
		12.2.1	Single processor, run from ROM
		12.2.2	Single processor, run from RAM
		12.2.3	Multiple process, multiple processor, run from RAM
		12.2.4	Multiple process, multiple processor, root run from ROM, rest of network run from RAM
	12.3	The EPROM tool: ieprom
	12.4	Using the configurer and collector to produce ROM-bootable code
	12.5	Summary of EPROM tool steps for different configurations
		12.5.1	Using icconf
		12.5.2	Single processor unconfigured occam program
		12.5.3	Using occonf

13	Low level programming
	13.1	Allocation
		13.1.1	The PLACE statement
		13.1.2	Allocating specific workspace locations
		13.1.3	Allocating channels to links
	13.2	RETYPING channels and creating channel array constructors
	13.3	Code insertion
		13.3.1	Using the code insertion mechanism
		13.3.2	Special names
		13.3.3	Labels and jumps
		13.3.4	Workspace zero
		13.3.5	Below workspace slots
		13.3.6	Channels
		13.3.7	Programming notes
	13.4	Dynamic code loading
		13.4.1	Calling code
		13.4.2	Loading parameters
		13.4.3	Examples
			Example 1: load from link and run
			Example 2: system loader
	13.5	Extraordinary use of links
		13.5.1	Introduction
		13.5.2	Clarification of requirements
		13.5.3	Programming concerns
		13.5.4	Input and output procedures
		13.5.5	Recovery from failure
		13.5.6	Example: a development system
	13.6	Scheduling
	13.7	Setting the error flag

Appendices

A	Configuration language definition
	A.1	Notation
	A.2	Introduction
	A.3	New types and specifications
		A.3.1	Syntax of configuration description
	A.4	Hardware description
		A.4.1	Processor attributes
		A.4.2	Syntax definition
	A.5	Software description
		A.5.1	Syntax definition
	A.6	Mapping structure
		A.6.1	Syntax definition
	A.7	Constraints

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

C	Transputer instruction set
	C.1	Prefixing instructions
	C.2	Direct instructions
	C.3	Operations
	C.4	Additional instructions for T400, T414, T425 and TB
	C.5	Additional instructions for IMS T800, T801 and T805
		C.5.1	Floating-point instructions
	C.6	Additional instructions for IMS T225, T400, T425, T800, T801, T805
	C.7	Additional instructions for the IMS T225, T400, T425, T801and T805
	C.8	Instructions supported by 'sequential code insertion'

D	Transputer code insertion
	D.1	Inline transputer code insertion
		D.1.1	Sequential code insertion
		D.1.2	Full code insertion
	D.2	ASM construct
		D.2.1	Syntax

E Glossary

F	Bibliography
	F.1	Transputers
	F.2	C programming
	F.3	occam programming
	F.4	INMOS technical notes
	F.5	Development systems
	F.6	References

	Index

Back to the top