Occam 2 toolset user manual - Part 1

March 1991
INMOS document number: 72-TDS-275-02
538 Pages

Preface

This manual is a combined user and reference guide to the occam 2 toolset. Part 1 'User guide and tools' (this book) describes the toolset and shows how it is used to develop and run transputer programs. Part 2 'Occam libraries and appendices' (72-TDS-276-02) describes the libraries supplied with the toolset and provides reference data in the form of appendices. A guide to how to use this manual, follows immediately after this preface.

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 librarian tool for building code libraries, a network debugger which provides both interactive and post-mortem debugging facilities, 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 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 application software to be in a format suitable for blowing into ROM. Two tools are provided with the toolset to support EPROM programming, they are the EPROM program formatting tool and the EPROM memory configurer.

Host versions

The manual is designed to cover all host versions of the toolset:

• IMS D7205 - IBM and NEC PC running MS-DOS
• IMS D5205 - Sun 3 systems running SunOS
• IMS D4205 - Sun 4 systems running SunOS
• IMS D6205 - VAX systems running VMS

Contents

	Contents overview
	Contents 
	Preface 
	How to use the manual

User guide

1	Introduction
	1.1	Overview
	1.2	Transputers
	1.3	Transputers and occam
		1.3.1	The occam programming model
		1.3.2	Multitransputer programming
		1.3.3	Reliability
		1.3.4	Real time programming
	1.4	Program development using the toolset
		1.4.1	System design
		1.4.2	Programming and code generation
		1.4.3	Debugging

2	Overview of the toolset
	2.1	Introduction
		2.1.1	Standard file format
		2.1.2	New configuration language
	2.2	oc - the occam 2 compiler
	2.3	Code generation tools
		2.3.1	Linker
		2.3.2	Configurer
		2.3.3	Collector
	2.4	Code loading
		2.4.1	Host file server
		2.4.2	Skip loader
	2.5	Program development and support tools
		2.5.1	Network debugger
		2.5.2	Memory dumper
		2.5.3	Librarian
		2.5.4	Binary lister
		2.5.5	Makefile generator
		2.5.6	File format convertor
		2.5.7	T425 simulator
	2.6	EPROM support tools
		2.6.1	EPROM programmer
		2.6.2	Memory configurer
		2.6.3	Memory Interface file convertor
	2.7	The occam libraries
		2.7.1	Constants
		2.7.2	Compiler libraries
		2.7.3	Maths libraries
		2.7.4	I/O libraries
			Hostio library
			Streamio library
		2.7.5	Other libraries
			String handling library
			Type conversion library
			Extraordinary link handling library
			Block CRC library
			Debugging support library
			Mixed language support library
			DOS specific hostio library
	2.8	Program development
		2.8.1	Development support
	2.9	File extensions
			File extensions for use with imakef
	2.10	Host dependencies
			Command line syntax
		2.10.1	Libraries
		2.10.2	Filenames
		2.10.3	Search paths
		2.10.4	Host environment variables
		2.10.5	Default command line arguments
	2.11	Toolset conventions
	2.12	Command line syntax
			Standard options
		2.12.1	Error handling and message format
			Severities 
			Information messages

3	Getting started
	3.1	Example command line
	3.2	Interrupting programs
	3.3	Compiling and running a simple example program
		3.3.1	Setting environment variables
		3.3.2	Compiling the example program
		3.3.3	Linking the example program
		3.3.4	Creating a bootable file
		3.3.5	Running the example program
		3.3.6	Compiling and linking for other transputer types
	3.4	Using imakef

4	Programming single transputers
	4.1	Program examples
	4.2	Occam programs
		4.2.1	Compiling programs
			Compilation information
		4.2.2	Linking programs
		4.2.3	Viewing code
		4.2.4	Making bootable programs
		4.2.5	Loading and running programs
	4.3	Transputer types and classes
		4.3.1	Single transputer type
		4.3.2	Creating a program which can run on a range of transputers
		4.3.3	Mixing code compiled for different targets
		4.3.4	Classes/instruction sets - additional information
	4.4	Error modes
		4.4.1	Error detection
	4.5	Interactive debugging
	4.6	Alias and usage checking
	4.7	Using separate vector space
	4.8	Sharing source between files
	4.9	Separate compilation
		4.9.1	Sharing protocols and constants
		4.9.2	Compiling and linking large programs
	4.10	Using imakef
	4.11	Libraries
		4.11.1	Selective loading
		4.11.2	Building libraries
	4.12	Example program - the pipeline sorter
		4.12.1	Overview of the program
		4.12.2	The protocol
		4.12.3	The sorting element
		4.12.4	The input/output process
		4.12.5	The calling program
		4.12.6	Building the program
		4.12.7	Automated program building

5	Configuring transputer networks
	5.1	Introduction
	5.2	Configuration model
		5.2.1	Configuration language
		5.2.2	Overall structure of a configuration description
	5.3	Hardware description
		5.3.1	Declaring processors
		5.3.2	NODE attributes
		5.3.3	NETWORK description
		5.3.4	Declaring EDGEs
		5.3.5	Declaring ARCs
		5.3.6	Abbreviations
		5.3.7	Host connection
		5.3.8	Examples of network descriptions
	5.4	Software description
		5.4.1	Libraries of linked units
		5.4.2	Example
	5.5	Mapping descriptions
		5.5.1	Mapping processes
		5.5.2	Mapping channels
		5.5.3	Moving code and data areas
		5.5.4	Mapping without a MAPPING section
		5.5.5	Mapping examples
	5.6	Example: A pipeline sorter on four transputers
		5.6.1	Building the program
		5.6.2	Running the program
		5.6.3	Automated program building
	5.7	Use of conditionals in a configuration
		5.7.1	Example: Configuration using conditional IF
	5.8	Summary of configuration steps

6	Loading transputer programs
	6.1	Introduction
	6.2	Tools for loading
	6.3	The boot from link loading mechanism
		6.3.1	Breakpoint debugging
	6.4	Boards and subnetworks
		6.4.1	Subsystem wiring
		6.4.2	Connecting subnetworks
	6.5	Loading programs for debugging
		6.5.1	Board types
		6.5.2	Use of the root transputer
		6.5.3	Analyse and Reset
	6.6	Example skip load
		6.6.1	Target network
		6.6.2	Loading the program
		6.6.3	Clearing the network

7	Debugging occam programs
	7.1	Introduction
		7.1.1	Debugging with isim
	7.2	Programs that can be debugged
	7.3	Runtime errors
	7.4	Compiling programs for debugging
		7.4.1	Symbolic debug information
		7.4.2	Error modes
	7.5	Post-mortem debugging
		7.5.1	Program loading
	7.6	Breakpoint debugging
		7.6.1	Runtime kernel
		7.6.2	Hardware breakpoint support
		7.6.3	Compiling the program
		7.6.4	Configuring the program
		7.6.5	Loading the program
		7.6.6	Clearing error flags
		7.6.7	Breakpoint functions and commands
		7.6.8	Breakpoints
	7.7	Program termination
	7.8	Symbolic facilities
		7.8.1	Locating to source code
		7.8.2	Browsing source code
		7.8.3	Inspecting variables
			Jumping down channels
		7.8.4	Tracing procedure calls
		7.8.5	Modifying variables
		7.8.6	Breakpointing
	7.9	Monitor page
		7.9.1	Startup display
			Process pointers
			Registers 
			Error flags
			Clocks 
			Memory map
		7.9.2	Monitor page commands
			Examining memory
			Locating processes
			Specifying processes
			Selecting processes
			Other processors
			Breakpoint commands
			Changing to post-mortem debugging
	7.10	A method for debugging halted programs
		7.10.1	Inspecting other processes
		7.10.2	Locating processes
			Running on the processor
			Waiting on a run queue
			Waiting on a timer queue
			Waiting for communication on a link
			Waiting for communication on a channel
			Processes stopped, terminated or not started
		7.10.3	Locating to procedures and functions
	7.11	Library functions
		7.11.1	Action when the debugger is not available
	7.12	Debugging with isim
		7.12.1	Command interface
		7.12.2	Using the simulator
		7.12.3	Program execution monitoring
			Breakpoints 
			Single step execution
		7.12.4	Core dump file
	7.13	Debugging using embedded messages
		7.13.1	Reading the message buffers
	7.14	Debugging example
		7.14.1	The example program
		7.14.2	Compiling the facs program
			Using imakef
			Using the tools directly
	7.15	Breakpoint debugging
		7.15.1	Prerequisites for breakpoint debugging
		7.15.2	Loading the program
		7.15.3	Setting initial breakpoints
		7.15.4	Starting the program
		7.15.5	Entering the debugger
		7.15.6	Inspecting variables
		7.15.7	Backtracing
		7.15.8	Jumping down a channel
		7.15.9	Modifying a variable
		7.15.10	Entering #INCLUDE files
		7.15.11	Resuming the program
		7.15.12	Clearing a breakpoint
		7.15.13	Quitting the debugger
	7.16	Post-mortem debugging
		7.16.1	Prerequisites for post-mortem debugging
		7.16.2	Running the example program
		7.16.3	Creating a memory dump file
		7.16.4	Running the debugger
	7.17	Hints and further guidance
		7.17.1	Invalid pointers
		7.17.2	Examining and disassembling memory
		7.17.3	occam scope rules
		7.17.4	Debugging IF and CASE statements
		7.17.5	Analysing deadlock
		7.17.6	Inspecting soft configuration channels
	7.18	Points to note when using the debugger
		7.18.1	Abusing hard links
		7.18.3	Using [INSPECT] with channel communications
		7.18.4	Selecting events from specific processors
		7.18.5	Minimal confidence check
		7.18.6	INTERRUPT key
		7.18.7	Program crashes
		7.18.8	Undetected program crashes
		7.18.9	Debugger hangs when starting program
		7.18.10	Debugger hangs
		7.18.11	Catching concurrent processes with breakpoints
		7.18.12	Phantom breakpoints
		7.18.13	Breakpoint configuration considerations
		7.18.14	Determining connectivity and memory sizes
		7.18.15	Long source code lines
		7.18.16	Setting breakpoints on the transputer seterr instruction
		7.18.17	Backtracing to occam configuration code

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	Importing C functions
		9.2.1	Deciding whether a static area Is required
		9.2.2	Functions which do not require static or heap
		9.2.3	Declaring the C function
			Translating C names
			Linking 
		9.2.4	Functions which require static and/or heap
			The static area
			The heap area
			Calic library
		9.2.5	Example of using the callc library
		9.2.6	Linking the program
	9.3	Parameter passing
		9.3.1	Return values
		9.3.2	Examples of passing parameters

10	Low level programming
	10.1	Allocation
		10.1.1	The PLACE statement
		10.1.2	Allocating specific workspace locations
		10.1.3	Allocating channels to links
	10.2	RETYPING channels and creating channel array constructors
	10.3	Code insertion
		10.3.1	Using the code insertion mechanism
		10.3.2	Special names
		10.3.3	Labels and jumps
		10.3.4	Programming notes
	10.4	Dynamic code loading
		10.4.1	Calling code
		10.4.2	Loading parameters
		10.4.3	Examples
	10.5	Extraordinary use of links
		10.5.1	Clarification of requirements
		10.5.2	Programming concerns
		10.5.3	Input and output procedures
		10.5.4	Recovery from failure
		10.5.5	Example: a development system
	10.6	Scheduling
	10.7	Setting the error flag

11	EPROM programming
	11.1	Introduction
	11.2	Processing configurations
		11.2.1	Single program, single processor, run from ROM
		11.2.2	Configured program, single processor, run from ROM
		11.2.3	Single program, single processor, run from RAM
		11.2.4	Configured program, single processor, run from RAM
		11.2.5	Configured program, multiple processor, run from RAM
		11.2.6	Configured program, multiple processor, root run from ROM,
			 rest of network run from RAM
	11.3	The eprom tool: ieprom
	11.4	Using the configurer and collector to produce ROMbootable code
	11.5	Summary of EPROM tool steps for different processing configurations

Tools

12	icollect - code collector
	12.1	Introduction
	12.2	Running the code collector
		12.2.1	Examples of use
		12.2.2	Input files
		12.2.3	Output files
			Debug data file
		12.2.4	Small values of IBOARDSIZE
	12.3	Program interface
		12.3.1	Interface used for 'T' option
			Warning messages
		12.3.2	Interface used for 'T' and 'm' options
	12.4	Memory allocation for single processor
		12.4.1	Memory allocation for mixed language program;
	12.5	The memory map file
		12.5.1	Single processor, boot from link
		12.5.2	Configured program boot from link
		12.5.3	Boot from ROM programs
			Single processor, boot from ROM, run in RAM
			Single processor, boot from ROM, run in ROM
			Configured program, boot from ROM, run in RAM
			Configured program, boot from ROM, run in ROM
	12.6	Non-bootable files
	12.7	Boot-from-ROM options
	12.8	Alternative bootstrap loaders
	12.9	Use of the icollect 'Y' option
	12.10	Error messages
		12.10.1	Warnings
		12.10.2	Serious errors

13	icvlink - TCOFF convertor
	13.1	Introduction
	13.2	Running the format convertor
		13.2.1	Default command line
		13.2.2	Input files
			Compiled object files
			Library files
			Linked object files
		13.2.3	Output files
	13.3	Transputer classes and error modes
	13.4	Summary of rules for using icvlink
	13.5	Error messages
		13.5.1	Warning Messages
		13.5.2	Serious errors

14	idebug - debugger
	14.1	Introduction
		14.1.1	Post-mortem debugging
		14.1.2	Breakpoint debugging
		14.1.3	Mixed language debugging
	14.2	The root transputer
		14.2.1	Board wiring
		14.2.2	Post-mortem debugging R-mode programs
		14.2.3	Post-mortem debugging T-mode programs
		14.2.4	Post-mortem debugging from a network dump file
		14.2.5	Debugging a dummy network
		14.2.6	Methods for breakpoint debugging
	14.3	Running the debugger
		14.3.1	Toolset file types read by the debugger
		14.3.2	Environment variables
		14.3.3	Program termination
		14.3.4	Post-mortem mode Invocation
		14.3.5	Reinvoking the debugger on single transputer programs
		14.3.6	Breakpoint mode invocation
			Clearing error flags on transputer boards
			Program loading
		14.3.7	Function key mappings
	14.4	Debugging programs on INMOS boards
		14.4.1	Subsystem wiring
		14.4.2	Debugging commands
		14.4.3	Detecting the error flag in breakpoint mode
	14.5	Debugging programs on non-INMOS boards
	14.6	Monitor page commands
		14.6.1	Command format
		14.6.2	Specifying transputer addresses
		14.6.3	Scrolling the display
		14.6.4	Editing keys
		14.6.5	Commands mapped by ITERM
		14.6.6	Summary of main commands
		14.6.7	Symbolic-type commands and scroll keys
		14.6.8	Symbolic-type commands
	14.7	Symbolic functions
		14.7.1	Breakpoint functions
	14.8	Error messages
		14.8.1	Out of memory errors
		14.8.2	If the debugger hangs
		14.8.3	Error message list

15	idump - memory dumper
	15.1	Introduction
	15.2	Running the memory dumper
		15.2.1	Example of use
	15.3	Error messages

16	iemit - Memory configurer
	16.1	Introduction
	16.2	Running iemit
	16.3	Output files
	16.4	Interactive operation
		16.4.1	Page 0
		16.4.2	Page 1
		16.4.3	Page 2
		16.4.4	Page 3
		16.4.5	Page 4
		16.4.6	Page 5
		16.4.7	Page 6
	16.5	Example iemit display pages
	16.6	iemit error and warning messages
	16.7	Memory configuration file
	16.8	Memory interface conversion tool icvemit
	16.9	Running icvemit
	16.10	icvemit error messages

17	ieprom - EPROM program convertor
	17.1	Introduction
	17.2	Prerequisites to using the hex tool ieprom
	17.3	Running ieprom
		17.3.1	Examples of use
	17.4	ieprom control file
	17.5	What goes In the EPROM
		17.5.1	Memory configuration data
		17.5.2	Jump instructions
		17.5.3	Bootable file
		17.5.4	Traceback Information
	17.6	ieprom output files
		17.6.1	Binary output
		17.6.2	Hex dump
		17.6.3	Intel hex format
		17.6.4	Intel extended hex format
		17.6.5	Motorola S-record format
	17.7	Block mode
		17.7.1	Memory organisation
		17.7.2	When to use block mode
		17.7.3	How to use block mode
	17.8	Example control files
	17.9	Error and warning messages

18	ilibr - librarian
	18.1	Introduction
	18.2	Running the librarian
		18.2.1	Default command line
		18.2.2	Library indirect files
		18.2.3	Linked object input files
	18.3	Library modules
		18.3.1	Selective loading
		18.3.2	How the librarian sorts the library index
	18.4	Library usage files
	18.5	Building libraries
		18.5.1	Rules for constructing libraries
		18.5.2	General hints for building libraries
		18.5.3	Optimising libraries
			Library build targetted at specific transputer types
			Semi-optimised library build targetted at all transputer
			 types
			Optimised library targetted at all transputer types
	18.6	Error Messages
		18.6.1	Warning messages
		18.6.2	Serious errors

19	ilink - linker
	19.1	Introduction
	19.2	Running the linker
		19.2.1	Default command line
	19.3	Linker indirect files
		19.3.1	Linker directives
		19.3.2	Linker indirect files - supplied with the toolset
	19.4	Linker options
		19.4.1	Processor types
		19.4.2	Error modes - options H, S and X
		19.4.3	TCOFF and LFF output files - options T, LB, LC
		19.4.4	Extraction of library modules - option EX
		19.4.5	Display information - option I
		19.4.6	Virtual memory - option KB
		19.4.7	Main entry point - option ME
		19.4.8	Link map filename - option MO
		19.4.9	Linked unit output file - option o
		19.4.10	Permit unresolved references - option u
		19.4.11	Disable interactive debugging - option Y
	19.5	Selective linking of library modules
	19.6	The link map file
	19.7	Using imakef for version control
	19.8	Error messages
		19.8.1	Warning messages
		19.8.2	Errors
			Serious errors
		19.8.3	Embedded messages

20	ilist - binary lister
	20.1	Introduction
	20.2	Data displays
		20.2.1	Example displays used in this chapter
	20.3	Running the lister
		20.3.1	Default command line
	20.4	Specifying an output file - option 0
	20.5	Symbol data - option A
	20.6	Code listing - option C
	20.7	Exported names - option E
	20.8	Hexadecimal/ASCII dump - option H
	20.9	Module data - option M
	20.10	Library index data - option N
	20.11	Procedural interface data - option P
	20.12	Specify reference - option R
	20.13	Full listing - option T
	20.14	File identification - option W
	20.15	External reference data - option X
	20.16	Error messages
		20.16.1	Warning messages
		20.16.2	Serious errors

21	imakef - Makefile generator
	21.1	Introduction
	21.2	How imakef works
		21.2.1	Target files
		21.2.2	File extensions for use with imakef
	21.3	Running the Makefile generator
		21.3.1	Example of use
		21.3.2	Incorporating C modules
		21.3.3	Configuration description files
		21.3.4	Disabling debug data
		21.3.5	Removing intermediate files
		21.3.6	Files found on ISEARCH
	21.4	imakef examples
		21.4.1	Single transputer program
		21.4.2	Multitransputer program
		21.4.3	Mixed language program
	21.5	Format of Makefiles
		21.5.1	Macros
		21.5.2	Rules
			Action strings
		21.5.3	Delete rule
		21.5.4	Editing the Makefile
			Adding options
			Re-running imakef
	21.6	Library usage files
	21.7	Linker indirect files
	21.8	Error messages

22	iserver - host file server
	22.1	Introduction
		22.1.1	Loadable programs
	22.2	Running the server
		22.2.1	Examples of use
		22.2.2	Supplying parameters to the program
		22.2.3	Checking and clearing the network
		22.2.4	Terminating the server
		22.2.5	Options to use when loading the program
		22.2.6	Specifying a link address - option SL
		22.2.7	Terminating on error - option SE
	22.3	Server functions
			File system commands
			Host environment commands
			Server control commands
	22.4	Error messages

23	isim - IMS T425 simulator
	23.1	Introduction
	23.2	Running the simulator
		23.2.1	Passing in parameters to the program
		23.2.2	Example of use
		23.2.3	ITERM file
	23.3	Monitor page display
	23.4	Simulator commands
		23.4.1	Specifying numerical parameters
		23.4.2	Commands mapped by ITERM
	23.5	Batch mode operation
		23.5.1	Setting Up ISIMBATCH
		23.5.2	Input command files
		23.5.3	Output
		23.5.4	Batch mode commands
	23.6	Error messages

24	iskip - skip loader
	24.1	Introduction
		24.1.1	Uses of the skip tool
	24.2	Running the skip tool
		24.2.1	Skipping a single transputerSubsystem wired downSubsystem
			 wired subs
		24.2.2	Skipping multiple transputers
		24.2.3	Loading a program
		24.2.4	Monitoring the error status - option E
		24.2.5	Clearing the error flag
	24.3	Error messages

25	oc - occam 2 compiler
	25.1	Introduction
	25.2	Running the compiler
		25.2.1	Filenames
	25.3	Transputer targets
	25.4	Compilation error modes
	25.5	Enable/Disable Error Detection
	25.6	Enabling/disabling warning messages
	25.7	Support for interactive debugging
	25.8	Separately compiled units and libraries
	25.9	ASM and GUY code
	25.10	Compiler directives
		25.10.1	Syntax
		25.10.2	#INCLUDE directive
		25.10.3	#USE directive
		25.10.4	#IMPORT directive
			Changes from the IMS D705/D605/D505 product.
		25.10.5	#COMMENT directive
		25.10.6	#OPTION directive
		25.10.7	#PRAGMA directive
			#PRAGMA EXTERNAL "declaration" comment
			#PRAGMA TRANSLATE identifier "string" comment
			#PRAGMA LINKAGE ["section-name"] comment
	25.11	INLINE keyword
	25.12	Implementation of channels
	25.13	Implementation of usage checking
		25.13.1	Usage rules of occam 2
		25.13.2	Checking of non-array elements
		25.13.3	Checking of arrays of variables and channels
		25.13.4	Arrays as procedure parameters
		25.13.5	Abbreviating variables and channels
	25.14	Implementation of alias checking
		25.14.1	Alias checking
			Scalar variables
			Arrays 
	25.15	Error messages
		25.15.1	Warning messages
		25.15.2	Errors

26	occonf - configurer
	26.1	Introduction
	26.2	Running the configurer
		26.2.1	Search paths
	26.3	Boot-from-ROM options
	26.4	Configuration error modes
	26.5	Enable/Disable Error Detection
	26.6	Enabling memory lay-out re-ordering
	26.7	Enabling/disabling warning messages
	26.8	Support for interactive debugging
	26.9	ASM and GUY code
	26.10	Configurer diagnostics
		26.10.1	Warning messages

Back to the top