Occam 2 toolset user manual

April 1989
INMOS document number: 72-TDS-184-00
494 Pages

Preface

This manual is a combined user and reference guide to the occam 2 toolset.

The occam 2 toolset is a set of software tools for developing transputer programs on host systems. Used with the occam libraries, it provides a complete environment for developing programs on transputers and transputer networks.

The toolset allows occam programs to be written using any convenient text editor. Programs are then compiled and linked using programs resident on the host or running on the transputer board. Self-booting code for single transputers and multitransputer networks is produced using separate tools, and loaded from the host system down the transputer link.

Tools that assist program development include a syntax checker, a librarian tool for building code libraries, a network debugger for analysing halted programs, and a transputer simulator that allows programs to be tested without transputer hardware. A Makefile generator is provided to assist with program version control, and a binary lister tool allows object files to be decoded and displayed in a readable form.

Transputer programs are normally written in occam to make full use of transputer parallel processing. Programs can also be written in C, FORTRAN, and Pascal and included in occam programs as separately compiled procedures.

The occam 2 toolset is intended for developing programs on transputers and transputer boards that are loaded from the host via a transputer link. Boards that boot from on-board ROM require special software. For details of the products available to support EPROM programming, contact INMOS.

Contents

	Contents overview
	Contents
	Preface

1	How to use the manual
	1.1	About the manual
		1.1.1	Readership
	1.2	User guide
		1.2.1	Getting started
	1.3	Reference manual
	1.4	Conventions used in the manual

2	Introduction
	2.1	Overview
	2.2	Transputers
	2.3	Transputers and occam
		2.3.1	The occam programming model
		2.3.2	Multitransputer programming
		2.3.3	Reliability
		2.3.4	Real time programming
	2.4	Program development using the toolset
		2.4.1	System design
		2.4.2	Programming and code generation
		2.4.3	Debugging

User guide

3	Overview of the toolset
	3.1	Introduction
	3.2	Program development
	3.3	The toolset
		3.3.13	occam - the occam 2 compiler
		3.3.12	iskip - the skip loader tool
		3.3.11	isim - the T414 simulator
		3.3.10	iserver - the host file server
		3.3.9	imakef - the Makefile generator
		3.3.8	ilist - the binary lister
		3.3.7	ilink - the linker
		3.3.6	ilibr - the librarian
		3.3.5	idump - the memory dumper
		3.3.4	idebug - the debugger
		3.3.3	iconf - the configurer
		3.3.2	icheck - the occam 2 syntax checker
		3.3.1	iboot - the bootstrap tool
	3.4	The occam libraries
		3.4.1	Constants
		3.4.2	Compiler libraries
		3.4.3	Maths libraries
		3.4.4	I/o libraries
			Hostio library
			Streamio library
		3.4.5	Other libraries
			String handling library
			Type conversion library
			Extraordinary link handling library
			Block CRC library
			Process library
	3.5	Implementation differences
		3.5.1	Host dependencies
			Command line syntax
			Libraries
			Directories and files
	3.6	Host environment variables
	3.7	Toolset conventions
		3.7.1	Command line conventions
			Syntax
			Common options
		3.7.2	Filename conventions
			Filenames
			File extensions
		3.7.3	Locating files
		3.7.4	Search paths
		3.7.5	Error handling and message format
			Message formats

4	Programming single transputers
	4.1	Program examples
	4.2	occam programs
		4.2.1	Checking programs
		4.2.2	Compiling programs
			Compilation information
		4.2.3	Linking programs
		4.2.4	Viewing code
		4.2.5	Making bootable programs
		4.2.6	Loading and running programs
		4.2.7	Interrupting programs
	4.3	Compiling a simple example program
		4.3.1	Checking the example program
		4.3.2	Compiling the example program
		4.3.3	Linking the example program
		4.3.4	Running the example program
	4.4	Compiler parameters
		4.4.1	Compilation for different transputers
			Transputer classes
		4.4.2	Mixing code for different transputers
		4.4.3	Error modes of compilation
		4.4.4	Mixing code with different error modes
		4.4.5	Alias and usage checking
		4.4.6	Using separate vector space
	4.5	Sharing source between files
	4.6	Separate compilation
		4.6.1	Sharing protocols and constants
		4.6.2	Compiling and linking large programs
	4.7	Change control
	4.8	Libraries
		4.8.1	Selective loading
		4.8.2	Building libraries
	4.9	The pipeline sorter program
		4.9.1	Overview of the program
		4.9.2	The protocol
		4.9.3	The sorting element
		4.9.4	The input/output process
		4.9.5	The calling program
		4.9.6	Building the program
		4.9.7	Automated program building

5	Programming transputer networks
	5.1	Introduction
	5.2	Configuration
	5.3	Preparing for configuration
	5.4	Configuring a program
	5.5	Loading a network
	5.6	Example: A pipeline sorter on four transputers
		5.6.1	The configuration description
			Planning the configuration description
		5.6.2	Building the program
		5.6.3	Running the program
		5.6.4	Automated program building
	5.7	Summary of configuration steps

6	Loading transputer programs
	6.1	Introduction
	6.2	Tools for loading programs
		6.2.1	The loading mechanism
	6.3	Boards and sub-networks
		6.3.1	Boot from ROM boards
		6.3.2	Subsystem wiring
		6.3.3	Controlling sub-networks
	6.4	Debugging programs on transputer boards
		6.4.1	Program mode
		6.4.2	Board types
		6.4.3	Programs which use the root transputer
		6.4.4	Programs which do not use the root transputer
		6.4.5	Analyse and Reset
	6.5	Example of using iskip

7	Debugging occam programs
	7.1	Introduction
		7.1.1	Compiling programs for debugging
		7.1.2	Programs that can be debugged
	7.2	Debugger facilities
		7.2.1	Symbolic debugging
		7.2.2	Debugging non-occam programs
		7.2.3	Assembly level debugging
	7.3	A debugging example
		7.3.1	The example program
		7.3.2	Building a loadable program
		7.3.3	Host environment variables
		7.3.4	Running the example program
		7.3.5	Creating a memory dump file
		7.3.6	Running the debugger
	7.4	Hints for debugging occam programs
		Examining and disassembling memory
		Debugging IF and CASE statements
		Analysing deadlock
	7.5	Debugging using embedded messages
		7.5.1	Reading the message buffers
	7.6	Notes on using the debugger
		Invalid pointers
		Locating within the ALT construct
		occam scope rules
	7.7	Debugging with the T414 simulator
		7.7.1	Using the simulator
		7.7.2	Standard debugging
			Symbolic facilities
			Low level facilities
		7.7.3	Program execution monitoring
			Break points
			Single step execution
			Changing registers
	7.8	Simulator example
		7.8.1	Running the simulation
			Setting break points
		7.8.2	Starting the program
		7.8.3	Single step execution
		7.8.4	Setting break points in source

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	Mixed language programming
	9.1	Introduction
	9.2	The equivalent occam process
		9.2.1	occam interface code
		9.2.2	Reserved channels
		9.2.3	Error modes
		9.2.4	Stack and heap requirements
			Stack overflow
	9.3	Type 1 interface
		9.3.1	Type 1 procedural interface
		9.3.2	Building a type 1 process
	9.4	Type 2 interface definition
		9.4.1	Type 2 procedural interface
		9.4.2	Building a type 2 process
		9.4.3	Example type 2 wrappings
	9.5	Type 3 interface definition
		9.5.1	Type 3 procedural interfaces
		9.5.2	Building a type 3 process
		9.5.3	Example type 3 wrapping
	9.6	Channel communication
		9.6.1	Communication libraries
		9.6.2	C channel communication
		9.6.3	FORTRAN channel communication
		9.6.4	Pascal channel communication
		9.6.5	Implementing other occam protocols
		9.6.6	Guidelines and rules
			Simple protocols
			Sequential protocols
			Variant protocols
	9.7	Calling occam from other languages
		9.7.1	Examples

10	Low level programming
	10.1	Allocation
	10.2	Code insertion
		10.2.1	Using the code insertion mechanism
		10.2.2	Labels and jumps
	10.3	Dynamic code loading
		10.3.1	Calling code
		10.3.2	Loading parameters
		10.3.3	Examples
	10.4	Extraordinary use of links
		10.4.1	Clarification of requirements
		10.4.2	Programming concerns
		10.4.3	Input and output procedures
		10.4.4	Recovery from failure
		10.4.5	Example: a development system
	10.5	Setting the error flag

Reference manual

11	iboot - bootstrap tool
	11.1	Introduction
		11.1.1	Programs that can be made bootable
		11.1.2	Transputer targets
	11.2	Running the bootstrap tool
		11.2.1	Bootstrap code
		11.2.2	Producing code for dynamic loading
		11.2.3	External loaders
	11.3	Bootstrap loaders
		11.3.1	Secondary loader interface
		11.3.2	Program interface
		11.3.3	Memory allocation
	11.4	External bootstrap loaders
		11.4.1	Creating external loaders
	11.5	Error messages

12	icheck - occam 2 checker
	12.1	Introduction
	12.2	Running the checker
		12.2.1	Checker messages
	12.3	Alias and usage checking
		12.3.1	Usage checking
		12.3.2	Alias checking
			Scalar variables
			Arrays
	12.4	Error messages

13	iconf - configurer
	13.1	Introduction
	13.2	Running the configurer
		13.2.1	Source compilation mode - options H S U
		13.2.2	Generating a configuration map - option M
	13.3	Configuration description
		13.3.1	Separately compiled code
		13.3.2	Source code
		13.3.3	Configuration language
			Allocating code to processors
			Placing channels on links
	13.4	Summary of configuration description
	13.5	Error messages

14	idebug - debugger
	14.1	Introduction
		14.1.1	Debugged code
	14.2	The root transputer
		14.2.1	T-mode programs
		14.2.2	Debugging R-mode programs
		14.2.3	Debugging from a network dump file
		14.2.4	Debugging a dummy network
	14.3	Running the debugger
		14.3.1	Debugging programs on B004-type boards and TRAMs
	14.4	Debugger symbolic facilities
		14.4.1	Scrolling the display
		14.4.2	Compiling modules for symbolic debugging
		14.4.3	Non-occam programs
		14.4.4	Symbolic functions
	14.5	Monitor page
		14.5.1	Monitor page commands
		14.5.2	occam run time errors
	14.6	Implementation notes
		14.6.1	Debugging information generated by the compiler
		14.6.2	Accessing the network
		14.6.3	Backtracing
		14.6.4	Accessing variables and channels
	14.7	Error messages

15	idump - memory dumper
	15.1	Introduction
	15.2	Running the memory dumper
	15.3	Error messages

16	ilibr - librarian
	16.1	Introduction
	16.2	Running the librarian
		16.2.1	Library indirect files
		16.2.2	Exploding libraries into constituent files
		16.2.3	Removing debug data
	16.3	Library modules
		16.3.1	Selective loading
	16.4	Library usage files
	16.5	Building libraries
		16.5.1	Rules for constructing libraries
		16.5.2	Hints for building libraries
	16.6	Error messages

17	ilink - linker
	17.1	Introduction
	17.2	Running the linker
		17.2.1	Ordering of Input flies
		17.2.2	Renaming entry points
		17.2.3	Using imakef to simplify linking
		17.2.4	Input files referenced by #SC
		17.2.5	Linker output
		17.2.6	Linker indirect files
	17.3	Features of the linker
		17.3.1	Selective linking of libraries
		17.3.2	Prelinking of program components
		17.3.3	Command line prelinking
	17.4	Linker options
		17.4.1	Extending linker capacity - option E
		17.4.2	Permit unresolved references - option U
		17.4.3	Disabling the link map - option M
		17.4.4	Symbol table - option S
		17.4.5	Changing buffer sizes - option B
			Buffer sizes
			Calculating memory requirements
		17.4.6	Optimise symbols - option Q
	17.5	Error messages

18	ilist - binary lister
	18.1	Introduction
	18.2	Data displays
	18.3	Running the binary lister
	18.4	Procedural interface data - option P
	18.5	Entry point data - option E
	18.6	External reference data - option X
	18.7	Module data - option M
	18.8	Tag data
	18.9	Debugging data - option D
	18.10	Code dump data - option C
	18.11	Global data - option V
	18.12	Error messages

19	imakef - Makefile generator
	19.1	Introduction
	19.2	What is Make?
		19.2.1	Makefiles
	19.3	Running the Makefile generator
		19.3.1	Code targets for imakef
	19.4	Format of Makefiles
		19.4.1	Macro definitions
		19.4.2	Rules
			Action Strings
		19.4.3	Editing the Makefile
			Adding options
			Adding rules for C, FORTRAN and Pascal
	19.5	Library usage files
	19.6	Error Messages

20	iserver - host file server
	20.1	Introduction
	20.2	Running the server
		20.2.1	Supplying parameters to the program
		20.2.2	Loading programs
		20.2.3	Terminating the server
		20.2.4	Specifying a link address - option SL
		20.2.5	Terminating on error - option SE
	20.3	Server functions
		File system commands
		Host environment commands
		Server control commands
	20.4	Error messages

21	isim - T414 simulator
	21.1	Introduction
	21.2	Running the simulator
		21.2.1	The ITERM file
		21.2.2	Loading and running a program
	21.3	Simulator interfaces
		21.3.1	Numerical parameters
	21.4	The Monitor page
		21.4.1	Monitor page commands
	21.5	Symbolic facilities
		21.5.1	Symbolic debugging commands
			Locating and backtracing
		21.5.2	Execution monitoring commands
	21.6	Error messages

22	iskip - skip loader
	22.1	Introduction
		22.1.1	Uses of the skip tool
	22.2	Running the skip tool
		22.2.1	Monitoring the error flag
		22.2.2	Loading a program
	22.3	Error messages

23	occam - occam 2 compiler
	23.1	Introduction
	23.2	Running the compiler
		23.2.1	Filenames
	23.3	Transputer targets
		23.3.1	Transputer classes
	23.4	Compilation error modes
		23.4.1	UNIVERSAL mode
	23.5	Separately compiled units and libraries
	23.6	Compiler directives
		23.6.1	Syntax
		23.6.2	#INCLUDE directive
		23.6.3	#USE directive
		23.6.4	#IMPORT directive
		23.6.5	#COMMENT directive
		23.6.6	#OPTION directive
		23.6.7	#SC directive
	23.7	Implementation of usage checking
		23.7.1	Usage rules of occam 2
		23.7.2	Checking of non-array elements
		23.7.3	Checking of arrays of variables and channels
		23.7.4	Arrays as procedure parameters
		23.7.5	Abbreviating variables and channels
			Problems with replicators
	23.8	Memory allocation by the compiler
		23.8.1	Procedure code
		23.8.2	Code referenced by #SC
		23.8.3	Workspace
	23.9	The transputer implementation of occam
		23.9.3	Language and configuration
		23.9.2	Hardware dependencies
		23.9.1	Data representation
	23.10	Error messages

24	occam libraries
	24.1	Introduction
		24.1.1	Using the occam libraries
			Linking libraries
		24.1.2	Listing library contents
		24.1.3	Toolset constants
	24.2	Compiler libraries
		24.2.1	User functions
			Maths functions
			2D block moves
			Bit manipulation functions
			CRC functions
	24.3	Maths libraries
		24.3.1	Function definitions
	24.4	Host file server library
		24.4.1	Errors and the C run time library
		24.4.2	Inputting real numbers
		24.4.3	Procedure descriptions
		24.4.4	File access routines
			Procedure definitions
		24.4.5	General host access
			Procedure definitions
		24.4.6	Keyboard input
			Procedure definitions
		24.4.7	Screen output
			Procedure definitions
		24.4.8	File output
			Procedure definitions
		24.4.9	Miscellaneous commands
			Time processing
			Buffers and multiplexors
			Protocol converter
	24.5	Streamio library
		24.5.1	Naming conventions
		24.5.2	Stream processes
			Procedure definitions
		24.5.3	Stream input
			Procedure definitions
		24.5.4	Stream output
			Procedure definitions
	24.6	String handling library
		24.6.1	Character identification
		24.6.2	String comparison
		24.6.3	String searching
		24.6.4	String editing
		24.6.5	Line parsing
	24.7	Type conversion library
		24.7.1	Procedure definitions
	24.8	Block CRC library
		24.8.1	Function definitions
	24.9	Extraordinary link handling library
		24.9.1	Procedure definitions
	24.10	Process library
		24.10.1	Procedure definitions

Appendices

A	Names defined by the software

B	Transputer instruction support
	B.1 Direct functions
	B.2 Short indirect functions
	B.3 Long indirect functions
	B.4 Additional instructions for IMS T425, T800 and TC
	B.5 Additional instructions for IMS T800

C	Constants
	C.1 Hostio constants
	C.2 Streamio constants
	C.3 Maths constants
	C.4 Transputer link addresses

D	ITERM
	D.1 Introduction
	D.2 The structure of an ITERM file
	D.3 The host definitions
		D.3.1 ITERM version
		D.3.2 Screen size
	D.4 The screen definitions
		D.4.1 Goto X Y processing
	D.5 The keyboard definitions
	D.6 Setting up the ITERM environment variable
	D.7 An example ITERM

E	Executable file format
	E.1 Bootable files
	E.2 Non-bootable files

F	Host file server protocol
	F.1 The host file server iserver
	F.2 The server protocol
		F.2.1 Packet size
		F.2.2 Protocol operation
	F.3 The server libraries
	F.4 Porting the server
	F.5 Defined protocol
		F.5.1 Reserved values
		F.5.2 File commands
		F.5.3 Host commands
		F.5.4 Server commands

G	Glossary

H	Bibliography
	H.1 INMOS publications
	H.2 INMOS technical notes

	Index

Back to the top