Occam 2 toolset reference manual

March 1993
INMOS document number: 72-TDS-367-01
384 Pages

About this manual

This manual is the Toolset Reference Manual to the occam 2 toolset.

The manual provides reference material for each tool in the toolset describing:

Many of the tools in the toolset are generic to other INMOS toolset products i.e. the ANSI C and FORTRAN toolsets and the documentation reflects this. Examples are given in C.

The appendices provide details of:

• Toolset conventions.
• Transputer types.
• Server protocol.
• ITERM files.
• Bootstrap loaders.

Contents

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

Tools

1	oc - occam 2 compiler
	1.1	Introduction
	1.2	Running the compiler
	1.3	Filenames
	1.4	Transputer targets
	1.5	Error modes
	1.6	Enable/Disable Error Detection
	1.7	Enabling/disabling warning messages
	1.8	Support for debugging
	1.9	Separately compiled units and libraries
	1.10	Code insertion using ASM
	1.11	Memory map
	1.12	Compiler directives
		1.12.1	Syntax of compiler directives
		1.12.2	#INCLUDE
		1.12.3	#USE
		1.12.4	#IMPORT
		1.12.5	#COMMENT
		1.12.6	#OPTION
			UNDEFINED error mode
		1.12.7	#PRAGMA
			#PRAGMA COMMENT "string" [comment]
			#PRAGMA EXTERNAL "declaration" [comment]
			#PRAGMA LINKAGE ["section-name"] [comment]
			#PRAGMA PERMITALIASES variable.list [comment]
			#PRAGMA SHARED variable.list [comment]
			#PRAGMA TRANSLATE identifier "string" [ comment]
	1.13	Error messages
			Notes
		1.13.1	Warnings
		1.13.2	Errors

2	occonf - occam configurer
	2.1	Introduction
	2.2	Running the configurer
			Examples of use
		2.2.1	Search paths
	2.3	Boot-from-ROM options
	2.4	Configuration error modes
	2.5	Enable/Disable Error Detection
	2.6	Enabling memory re-ordering and placement
	2.7	Disabling virtual routing
	2.8	Enabling/disabling warning messages
	2.9	Support for interactive debugging
	2.10	ASM code
	2.11	Support for INQUEST
	2.12	Default memory map
		2.12.1	LoadStart
	2.13	Configurer diagnostics
		2.13.1	Warning messages
		2.13.2	Error messages

3	icollect - code collector
	3.1	Introduction
			Unconfigured program (using 'T' option)
			Configured processor program
	3.2	Running the code collector
		3.2.1	Examples of use
		3.2.2	Default command line
		3.2.3	Input files
		3.2.4	Output files
			Specifying an output filename
			Default case
			Boot-from-ROM/RAM
			Dynamically loadable output
			Memory map files
			Debug data file
	3.3	Program interface for occam unconfigured programs
		3.3.1	Interface used for 'T' option
		3.3.2	Interface used for 'T' and 'N' options
	3.4	Memory allocation for unconfigured programs
		3.4.1	C and FORTRAN programs
		3.4.2	occam programs
		3.4.3	Memory initialization errors
		3.4.4	Small values of IBOARDSIZE
	3.5	Parity-checked memory
	3.6	Non-bootable files created with the K option
		3.6.1	File format
	3.7	Boot-from-ROM output files
	3.8	Alternative bootstrap loaders for unconfigured programs
	3.9	Alternative bootstrap schemes
	3.10	The memory map file
		3.10.1	Unconfigured (single processor), boot from link
			Program targetted at transputer type
			Program targetted at transputer class
		3.10.2	Configured program boot from link
		3.10.3	Boot from ROM programs
			Unconfigured (single processor), boot from ROM, run in RAM
			Unconfigured (single processor), boot from ROM, run in ROM
			Configured program, boot from ROM, run in RAM
			Configured program, boot from ROM, run in ROM
	3.11	Disabling interactive debugging - 'Y' option
	3.12	Error messages
		3.12.1	Warnings
		3.12.2	Serious errors
		3.12.3	Fatal errors

4	idebug - network debugger
	4.1	Introduction
	4.2	Debugging the root transputer
		4.2.1	Board wiring
		4.2.2	Post-mortem debugging R-mode programs
		4.2.3	Post-mortem debugging T-mode programs
		4.2.4	Post-mortem debugging from a network dump file
		4.2.5	Debugging a dummy network
		4.2.6	Methods for interactive breakpoint debugging
	4.3	Running the debugger
		4.3.1	Toolset file types read by the debugger
		4.3.2	Environment variables
		4.3.3	Program termination
	4.4	Post-mortem mode invocation
		4.4.1	Debugging T-mode programs - option 'T'
		4.4.2	Debugging R-mode programs - option 'R'
		4.4.3	Debugging a network dump file - option'N'
		4.4.4	Debugging a previous breakpoint session - option 'N'
		4.4.5	Re-invoking the debugger on single transputer programs
		4.4.6	Debugging boot from ROM programs
	4.5	Interactive mode invocation
	4.6	Function key mappings
	4.7	Debugging programs on INMOS boards
		4.7.1	Subsystem wiring
		4.7.2	Debugging options to use with specific board types
		4.7.3	Detecting the error flag in interactive mode
	4.8	Debugging programs on non-INMOS boards
	4.9	Monitor page commands
		4.9.1	Command format
		4.9.2	Specifying transputer addresses
		4.9.3	Scrolling the display
		4.9.4	Editing functions
		4.9.5	Commands mapped by ITERM
		4.9.6	Summary of commands
		4.9.7	Symbolic-type commands
		4.9.8	Scroll keys
		4.9.9	Monitor page command descriptions
		4.9.10	Symbolic-type commands
	4.10	Symbolic functions
		4.10.1	Symbolic functions
		4.10.2	Interactive mode functions
		4.10.3	Locating functions
		4.10.4	Cursor and display control functions
		4.10.5	Miscellaneous functions
	4.11	INSPECT/MODIFY expression language for C
		4.11.1	Syntax not supported
		4.11.2	Extensions to C syntax
			Subarrays
			Scope resolution operator
			Hex constants
			Address constant indirect
		4.11.3	Automatic expression pickup
		4.11.4	Editing functions
		4.11.5	Warnings
		4.11.6	Types
			Type compatibility when using MODIFY
	4.12	Display formats for source code symbols
		4.12.1	Notation
		4.12.2	Basic Types
		4.12.3	Default type of "plain" char
		4.12.4	Enumerated types
		4.12.5	Pointers
		4.12.6	Function Pointers
		4.12.7	Structs
		4.12.8	Unions
		4.12.9	Addressof operator &
		4.12.10	Arrays
		4.12.11	Channels
	4.13	Example displays
	4.14	INSPECT/MODIFY expression language for occam
		4.14.1	Inspecting memory
		4.14.2	Inspecting arrays
		4.14.3	Type compatibility when using MODIFY
	4.15	Display formats for source code symbols
		4.15.1	Notation
		4.15.2	Basic Types
		4.15.3	Channels
		4.15.4	Arrays
		4.15.5	Procedures and functions
	4.16	Example displays
	4.17	Error messages
		4.17.1	Out of memory errors
		4.17.2	If the debugger hangs
		4.17.3	Error message list

5	idump - memory dumper
	5.1	Introduction
	5.2	Running the memory dumper
		5.2.1	Example of use
	5.3	Error messages

6	iemit - memory interface configurer
	6.1	Introduction
	6.2	Running iemit
	6.3	Output files
	6.4	Interactive operation
		6.4.1	Page 0
		6.4.2	Page 1
		6.4.3	Page 2
		6.4.4	Page 3
		6.4.5	Page 4
		6.4.6	Page 5
		6.4.7	Page 6
	6.5	iemit error and warning messages
	6.6	Memory configuration file

7	ieprom - ROM program convertor
	7.1	Introduction
	7.2	Prerequisites to using the ieprom tool
	7.3	Running ieprom
		7.3.1	Examples of use
	7.4	ieprom control file
	7.5	What goes into the EPROM
		7.5.1	Memory configuration data
		7.5.2	Parity registers
		7.5.3	Jump instructions
		7.5.4	Bootable file
		7.5.5	Traceback information
	7.6	ieprom output files
		7.6.1	Binary output
		7.6.2	Hex dump
		7.6.3	Intel hex format
		7.6.4	Intel extended hex format
		7.6.5	Motorola S-record format
	7.7	Block mode
		7.7.1	Memory organization
		7.7.2	When to use block mode
		7.7.3	How to use block mode
	7.8	Example control files
		7.8.1	Simple output
		7.8.2	Using block mode
	7.9	Error and warning messages

8	ilibr - librarian
	8.1	Introduction
	8.2	Running the librarian
		Example
		8.2.1	Default command line
		8.2.2	Library indirect files
		8.2.3	Linked object input files
		8.2.4	Library files as input
	8.3	Library modules
		8.3.1	Selective loading
		8.3.2	How the librarian sorts the library index
	8.4	Library usage files
	8.5	Building libraries
		8.5.1	Rules for constructing libraries
		8.5.2	General hints for building libraries
		8.5.3	Optimizing libraries
			All libraries
			Libraries containing occam modules
			Semi-optimized library build targeted at all transputer types
			Optimized library targeted at all transputer types
			Library build targeted at specific transputer types
	8.6	Error Messages
		8.6.1	Warning messages
		8.6.2	Serious errors

9	ilink - linker
	9.1	Introduction
	9.2	Running the linker
		9.2.1	Default command line
	9.3	Linker indirect files
		9.3.1	Linker indirect files supplied with the toolset
	9.4	Linker directives
		9.4.1	#alias basename {aliases}
		9.4.2	#define symbolname value
		9.4.3	#include filename
		9.4.4	#mainentry symbolname
		9.4.5	#reference symbolname
		9.4.6	#section name
	9.5	Linker options
		9.5.1	Processor types
		9.5.2	Error modes - options H, S and X
		9.5.3	TCOFF and LFF output files - options T, LB, LC
		9.5.4	Extraction of library modules - option EX
			Example: Extraction from a user library
			Example: Extraction from a user library, using the run-time library
			Example: Extraction from a user library, for multiple processor types
			Example: Generation of a completely linkable library
			Extraction using #define
		9.5.5	Display information - option I
		9.5.6	Virtual memory - option KB
		9.5.7	Main entry point - option ME
		9.5.8	Link map filename - option MO
		9.5.9	Linked unit output file - O
		9.5.10	Permit unresolved references - option U
		9.5.11	Disable interactive debugging - Y
	9.6	Selective linking of library modules
	9.7	The link map file
		9.7.1	MODULE record
		9.7.2	SECT record
		9.7.3	MAP record
		9.7.4	Value record
	9.8	Using imakef for version control
	9.9	Error messages
		9.9.1	Warnings
		9.9.2	Errors
		9.9.3	Serious errors
		9.9.4	Embedded messages

10	ilist - binary lister
	10.1	Introduction
	10.2	Data displays
		10.2.1	Modular displays
		10.2.2	Example displays used in this chapter
	10.3	Running the binary lister
		10.3.1	Options to use for specific file types
		10.3.2	Output device
		10.3.3	Default command line
	10.4	Specifying an output file - option O
	10.5	Symbol data - option A
		10.5.1	Specific section attributes
		10.5.2	General symbol attributes
		10.5.3	Example symbol data display
	10.6	Code listing - option C
		10.6.1	Example code listing display
	10.7	Exported names - option E
		10.7.1	Example exported names display
	10.8	Hexadecimal/ASCII dump - option H
		10.8.1	Example hex dump display
	10.9	Module data - option M
		10.9.1	Example module data display
	10.10	Library index data - option N
		10.10.1	Example library index display
	10.11	Procedural interface data - option P
		10.11.1Example procedural data display
	10.12	Specify reference - option R
	10.13	Full listing - option T
		10.13.1	Example full data display
		10.13.2	Configuration data files
	10.14	File identification - option W
		10.14.1	Example file identification display
	10.15	External reference data - option X
		10.15.1	Example external reference data display
	10.16	Error messages
		10.16.1	Warning messages
		10.16.2	Serious errors

11	imakef - makefile generator
	11.1	Introduction
	11.2	How imakef works
	11.3	File extensions for use with imakef
		11.3.1	Target files
	11.4	Linker indirect files
	11.5	Library indirect and library usage files
	11.6	Running the makefile generator
		11.6.1	Example of use
		11.6.2	Specifying language mode
		11.6.3	Configuration description files
		11.6.4	Disabling debug data
		11.6.5	Removing intermediate files
		11.6.6	Files found on ISEARCH
		11.6.7	Map file output for imap
	11.7	imakef examples
		11.7.1	C examples
			Single transputer program
			Multitransputer program
		11.7.2	occam examples
			Single transputer program
			Multitransputer program
		11.7.3	Mixed language program
	11.8	Format of makefiles
		11.8.1	Macros
		11.8.2	Rules
			Example
			Action strings
		11.8.3	Delete rule
		11.8.4	Editing the makefile
			Adding options
			Re-running imakef
	11.9	Error messages

12	imap - memory mapper
	12.1	Introduction
	12.2	Running the map tool
		12.2.1	Source files required by imap
		12.2.2	Re-directing imap's output
	12.3	Output format
		12.3.1	imap memory map structure
		12.3.2	Process types
		12.3.3	User processes
		12.3.4	Module memory usage
		12.3.5	Other processes
		12.3.6	Symbol table
	12.4	Example
	12.5	Error messages
		12.5.1	Serious errors
		12.5.2	Fatal errors

13	iserver - host file server
	13.1	Introduction
	13.2	Loading programs
	13.3	Host interface
	13.4	Access to transputer networks
		User links
		The session manager
	13.5	Running the iserver
		13.5.1	Examples of use
		13.5.2	Server environment variables
		13.5.3	Loading programs
			Running a program using the iserver - option SB
			Sending data down a user link - option SC
			Running programs which do not use the server
			Analyzing a transputer network - option SA
			Terminating the server
		13.5.4	Supplying parameters to a program
		13.5.5	Specifying the transputer resource - option SL
		13.5.6	Terminating on error - option SE
		13.5.7	Terminating the server
		13.5.8	Specifying the session manager configuration file
	13.6	Using the session manager interface
		13.6.1	Session manager commands
		13.6.2	The options command
		13.6.3	The iserver command
		13.6.4	User-defined commands
			Running the debugger from the session manager
		13.6.5	Host OS commands
	13.7	Connecting transputers to computer networks
		13.7.1	Capabilities
		13.7.2	The connection database
		13.7.3	Using a specific node
	13.8	The connection database
		13.8.1	Connection databases
			Capability names
		13.8.2	Connection database format
		13.8.3	Example connection databases
			PC development system
			Sun workstation
			IMS B300
	13.9	New server features
		13.9.1	Session manager
		13.9.2	Connection manager
		13.9.3	New command line options
		13.9.4	User interrupt
		13.9.5	Exit codes
		13.9.6	Error codes
		13.9.7	Stream identifier validation
		13.9.8	Record structured file support
	13.10	Error messages
		13.10.1	Additional error messages

14	isim - T425 simulator
	14.1	Introduction
	14.2	Running the simulator
		14.2.1	Passing in parameters to the program
		14.2.2	Example of use
		14.2.3	ITERM file
	14.3	Monitor page display
	14.4	Simulator commands
		14.4.1	Specifying numerical parameters
		14.4.2	Keys mapped by ITERM
		14.4.3	Command summary
		14.4.4	Command descriptions
	14.5	Batch mode operation
		14.5.1	Setting up ISIMBATCH
		14.5.2	Input command files
		14.5.3	Output
		14.5.4	Batch mode commands
	14.6	Error messages

15	iskip - skip loader
	15.1	Introduction
		15.1.1	Uses of the skip tool
	15.2	Running the skip loader
		15.2.1	Skipping a single transputer
			Subsystem wired down
			Subsystem wired subs
		15.2.2	Skipping multiple transputers
		15.2.3	Loading a program
		15.2.4	Monitoring the error status - option E
		15.2.5	Clearing the error flag
	15.3	Error messages

Appendices

A	Toolset conventions and defaults
	A.1	Command line syntax
		A.1.1	General conventions
		A.1.2	Standard options
	A.2	Unsupported options
	A.3	Filenames
	A.4	Search paths
	A.5	Standard file extensions
		A.5.1	Main source and object files
		A.5.2	Indirect input files (script files)
		A.5.3	Files read by the memory map tool imap
		A.5.4	Other output files
		A.5.5	Miscellaneous files
	A.6	Extensions required for imakef
	A.7	Message handling
		A.7.1	Message format
		A.7.2	Severities
		A.7.3	Runtime errors

B	Transputer types and classes
	B.1	Transputer types supported by this toolset
	B.2	Transputer types and classes
		B.2.1	Single transputer type
		B.2.2	Creating a program which can run on a range of transputers
		B.2.3	Linked file containing code compiled for different targets
			occam object files targetted at different targets
		B.2.4	Classes/instruction sets - additional information
	B.3	Transputer type command line options

C	iserver protocol
	C.1	iserver packets
	C.2	Server commands
	C.3	File commands
		C.3.1	Fopen - Open a file
		C.3.2	Fclose - Close a file
		C.3.3	Fread - Read a block of data
		C.3.4	Fwrite - Write a block of data
		C.3.5	FGetBlock - Read a block of data and return success
		C.3.6	FPutBlock - Write a block of data and return success
		C.3.7	Fgets - Read a line
		C.3.8	Fputs - Write a line
		C.3.9	Fflush - Flush a stream
	C.4	Record Structured file commands
		C.4.1	FopenRec - Open a record structured file
		C.4.2	FGetRec - Read a record
		C.4.3	FPutRec - Write a record
		C.4.4	FputEOF - Write an end of file record
		C.4.5	Fseek - Set position in a file
		C.4.6	Ftell - Find out position in a file
		C.4.7	Feof - Test for end of file
		C.4.8	Ferror - Get file error status
		C.4.9	Remove - Delete a file
		C.4.10	Rename - Rename a file
		C.4.11	Isatty - Discover if a stream is connected to a terminal
		C.4.12	FileExists - Check to see if a file exists
		C.4.13	FerrStat - Get file error status
	C.5	Host commands
		C.5.1	Getkey - Get a keystroke
		C.5.2	Pollkey - Test for a key
		C.5.3	RequestKey - Request a single keyboard 'event'
		C.5.4	Getenv - Get environment variable
		C.5.5	Time - Get the time of day
		C.5.6	System - Run a command
		C.5.7	Translate - Translate an environment variable
	C.6	Server commands
		C.6.1	Exit - Terminate the server
		C.6.2	CommandLine - Retrieve the server command line
		C.6.3	Core - Read peeked memory
		C.6.4	Version - Find out about the server
		C.6.5	GetInfo - Obtain information about the host and server
		C.6.6	CommandArgs - Retrieve the server command line arguments
	C.7	Reserved Tags and Third Party Tags
		C.7.1	MSDOS - Perform MS-DOS specific function
		C.7.2	SocketA - make a socket library call
		C.7.3	SocketM - make a socket library call
		C.7.4	ALSYS - Perform Alsys specific function
		C.7.5	KPAR - Perform Kpar specific function
	C.8	Record Structured file format
		C.8.1	SunOS and MS-DOS
			Formatted Sequential
			Unformatted Sequential
			Formatted Direct
			Unformatted Direct
	C.9	Termination codes

D	ITERM files
	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	Iterms supplied with a toolset
	D.8	An example ITERM

E	Bootstrap loaders
	E.1	Introduction
		E.1.1	The example bootstrap
			Transfer of control
		E.1.2	Writing bootstrap loaders

	Index

Back to the top