ANSI C toolset user guide

October 1992
INMOS document number: 72-TDS-345-01
326 Pages

About this manual

This manual is the User Guide to the ANSI C 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 ANSI C 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.
• Developing code which may be dynamically loaded.

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

Contents

	Contents overview
	Contents
	Preface
		Host versions
		About this manual
		About the toolset documentation set
		Other documents
		occam and FORTRAN toolsets
		Documentation conventions
	Differences from previous issue

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	Overview of the toolset
	2.1	Introduction
		2.1.1	Toolset features
		2.1.2	Transputer targets
	2.2	ANSI C compiler - icc
		2.2.1	Concurrent programming
		2.2.2	Standard object file format
		2.2.3	Preprocessor directives
		2.2.4	Include files
		2.2.5	Pragmas
		2.2.6	Error modes
		2.2.7	Transputer Program Execution
	2.3	Runtime library
		2.3.1	Reduced library
		2.3.2	Header files
	2.4	Runtime system
	2.5	Dynamic code loading
	2.6	Low level programming
		2.6.1	Assembly code support
		2.6.2	Compiler predefines
		2.6.3	Assembly programming
	2.7	Configuration system
		2.7.1	Configuration language
		2.7.2	Software routing and multiplexing
		2.7.3	Code and data placement
	2.8	Mixed language programming
	2.9	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
			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	Outline procedure
	4.2	Running the examples
		4.2.1	Sources
		4.2.2	Example command lines
		4.2.3	Using the simulator
	4.3	A simple sequential program
		4.3.1	Compiling
		4.3.2	Linking
		4.3.3	Configuring
		4.3.4	Collecting
		4.3.5	Loading and Execution
		4.3.6	A short cut
		4.3.7	Separate compilation

5	Parallel processing
	5.1	Introduction
	5.2	Abstract model
		5.2.1	Processes
		5.2.2	Channels
		5.2.3	Semaphores
	5.3	Parallel processing and transputers
		5.3.1	Multitransputer networks
		5.3.2	Instruction set
			Process control
			Process selection
			Process timing
	5.4	INMOS Concurrent C library
		5.4.1	Library support
		5.4.2	New data types
		5.4.3	Concurrency functions
	5.5	Processes
		5.5.1	Unused process pointer
		5.5.2	Process initialization
		5.5.3	Freeing stack and workspace
		5.5.4	Process termination
		5.5.5	Process execution (process.h)
			Asynchronous processes
			Synchronous processes
			Synchronizing between processes
	5.6	Channel communications (channel.h)
		5.6.1	Channel initialization
		5.6.2	Channel output
		5.6.3	Channel input
		5.6.4	Reading from several channels
	5.7	Semaphores (semaphor.h)
	5.8	Timers and delays
		5.8.1	Control of processes by timers
	5.9	Other process facilities

6	Configuring transputer programs
	6.1	Configuration basics
		6.1.1	Introduction to configuration
		6.1.2	Hardware network description
			Processor links
			Defining new processor types
			Edges
			Host edge
			The reserved attribute
			The router attribute
		6.1.3	Software network description
			Process attributes
			Defining new process types
			Input and output channels
			Edge connections
		6.1.4	Mapping description
			Placement of processes
			Placement of channels
			Predefined connection names
			Assigning code to processes
			Mapping example
		6.1.5	Types of main program
		6.1.6	Access to interface parameters
		6.1.7	Example configuration
	6.2	Configuration language
		6.2.1	Introduction
		6.2.2	Statements
		6.2.3	Comments
		6.2.4	Identifiers
			Character set
		6.2.5	Types
		6.2.6	Constants
		6.2.7	Booleans
		6.2.8	Expressions and arithmetic
		6.2.9	Arrays
		6.2.10	Conditional statement
		6.2.11	Replication
		6.2.12	Built-in functions
		6.2.13	Network definition
			Nodes
			Node attributes
			Defining new node types
			Connections
			Prohibited connections
		6.2.14	Configuration language summary
			Network data types
			Numeric data types
			Language constructs
			Definitions
			Operators
			Predefinitions
			(Node types)
			(Constants)
			(Edges)
			Built-in functions
	6.3	Further considerations
		6.3.1	Runtime library
		6.3.2	Reliable Channel Communications
		6.3.3	Terminating configured processes
		6.3.4	Checking the configuration
		6.3.5	The effect of icconf on idebug
	6.4	Configuration examples
		6.4.1	Example 1 - single processor configuration
		6.4.2	Example 2 - Two processes configured on a two-processor network
		6.4.3	Example 3 - using virtual channels
		6.4.4	Example 4 - Virtual channel routing

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	Debugging transputer programs
	8.1	Introduction
		8.1.1	Post-mortem debugging
		8.1.2	Interactive debugging
		8.1.3	Mixed language debugging
		8.1.4	Debugging with isim
	8.2	Programs that can be debugged
	8.3	Compiling programs for debugging
			Minimal debugging information
			occam channel communication
			C channel communication
		8.3.1	Error modes
	8.4	Debugging configured programs
		8.4.1	Debugging with configuration level channels
		8.4.2	Debugging with the configurer reserved attribute
	8.5	Debugging boot from ROM programs
	8.6	Post-mortem debugging
		8.6.1	C and FORTRAN programs
		8.6.2	occam programs
		8.6.3	Interrupted programs
		8.6.4	Parity errors
		8.6.5	Debugging the root transputer
			Skip loading
	8.7	Interactive debugging
		8.7.1	Runtime kernel
		8.7.2	Processors without hardware breakpoint support
		8.7.3	Creating programs for debugging
		8.7.4	Loading the program
			Clearing error flags
			Parity-checked memory
		8.7.5	Running the debugger
		8.7.6	Interactive mode functions and commands
			Symbolic functions
			Monitor page commands
		8.7.7	Breakpoints
	8.8	Program termination
	8.9	Symbolic facilities
			Help screen
		8.9.1	Locating to source code
		8.9.2	Browsing source code
		8.9.3	Inspecting source code and variables
		8.9.4	Jumping down channels
		8.9.5	Tracing procedure calls
		8.9.6	Modifying variables
		8.9.7	Breakpointing
		8.9.8	Miscellaneous functions
	8.10	Monitor page
		8.10.1	Startup display
			Process Workspace or Stack
			Process Descriptors
			Process pointers
			Practical notes
			Registers
			Error flags
			Clocks
			Parity errors
			Memory map
		8.10.2	Monitor page commands
			Examining memory
			Locating processes
			Specifying processes
			Selecting processes
			Other processors
			Breakpoint commands
			Changing to post-mortem debugging
	8.11	Locating processes
		8.11.1	Running on the processor
		8.11.2	Waiting on a run queue
		8.11.3	Waiting on a timer queue
		8.11.4	Waiting for communication on a link
		8.11.5	Waiting for communication on a software virtual link
		8.11.6	Waiting for communication on a channel
		8.11.7	Interrupted by a high priority process
		8.11.8	Processes terminated or not started
		8.11.9	Locating to procedures and functions
	8.12	Debugging support library
			Example
		8.12.1	Action when the debugger is not available
	8.13	Debugging with isim
		8.13.1	Command interface
		8.13.2	Using the simulator
		8.13.3	Program execution monitoring
			Breakpoints
			Single step execution
		8.13.4	Core dump file
	8.14	Hints and further guidance
		8.14.1	Invalid pointers
		8.14.2	Examining and disassembling memory
		8.14.3	Scope rules
		8.14.4	Inspecting soft configuration channels
		8.14.5	Locating to IF, ALT and CASE in occam
		8.14.6	Analyzing deadlock
	8.15	Points to note when using the debugger
		8.15.1	Abusing hard links
		8.15.2	Examining an active network (the network is volatile)
		8.15.3	Using INSPECT with channel communications
		8.15.4	Debugging in the presence of software virtual links
		8.15.5	Selecting events from specific processors
		8.15.6	Minimal confidence check
		8.15.7	INTERRUPT key
		8.15.8	Program crashes
		8.15.9	Undetected program crashes
		8.15.10	Debugger hangs when starting program
		8.15.11	Debugger hangs
		8.15.12	Catching concurrent processes with breakpoints
		8.15.13	Phantom breakpoints
		8.15.14	Breakpoint configuration considerations
		8.15.15	Determining connectivity and memory sizes
		8.15.16	Long source code lines
		8.15.17	Resuming breakpoints on the transputer seterr instruction
		8.15.18	Arrays as arguments to C functions
		8.15.19	Backtracing with concurrent C processes
		8.15.20	Errors generated by the full C library
		8.15.21	Errors generated by the reduced C library
		8.15.22	Shifting by large or negative values
		8.15.23	C compiler optimizations
	8.16	C debugging example
		8.16.1	The example program
		8.16.2	Compiling and loading the example
		8.16.3	Setting initial breakpoints
		8.16.4	Starting the program
		8.16.5	Entering the debugger
		8.16.6	Inspecting variables
		8.16.7	Finding addresses of variables
		8.16.8	Backtracing
		8.16.9	Jumping down a channel
		8.16.10	Inspecting by expression
		8.16.11	Modifying a variable
		8.16.12	Backtracing to main()
		8.16.13	Entering #include files
		8.16.14	Quitting the debugger
	8.17	occam debugging example
		8.17.1	The example program
		8.17.2	Compiling the facs program
			Using imakef
			Using the tools directly
	8.18	Breakpoint debugging
		8.18.1	Loading the program
		8.18.2	Setting initial breakpoints
		8.18.3	Starting the program
		8.18.4	Entering the debugger
		8.18.5	Inspecting variables
		8.18.6	Backtracing
		8.18.7	Jumping down a channel
		8.18.8	Modifying a variable
		8.18.9	Entering #INCLUDE files
		8.18.10	Resuming the program
		8.18.11	Clearing a breakpoint
		8.18.12	Quitting the debugger
	8.19	Post-mortem debugging
		8.19.1	Running the example program
		8.19.2	Creating a memory dump file
		8.19.3	Running the debugger
			Inspecting variables
			Inspecting channels
			Retracing and Backtracing
			Displaying process queues
			Goto process

Advanced techniques

9	Advanced use of the configurer
	9.1	Code and data placement
		9.1.1	Default memory map
		9.1.2	other memory configurations
		9.1.3	reserved processor attribute
			Example
		9.1.4	location process attribute
			Example (on a 32-bit processor)
		9.1.5	order process attribute
		9.1.6	location versus order attribute
	9.2	Channel communication - configuration techniques
		9.2.1	Optimizing important application channels
		9.2.2	Virtual communications - use of fast memory
		9.2.3	Control of routing and placement
			Introduction to routing and placement attributes
			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
		9.2.4	Example - optimized filter test program

10	Mixed language programming
	10.1	Mixed language programs
		10.1.1	Declaring external routines
		10.1.2	Translating identifiers
		10.1.3	Parameter passing
			Parameter compatibility
			Range checking
			occam timers
		10.1.4	Global static base parameter
			Method 1 - dummy GSB parameter
			Method 2 - nolink pragma
			Method 3 - using call_without_gsb function
		10.1.5	Function return values
			Restrictions on functions that may be called
		10.1.6	Linking the program
			Calling occam from C
			Calling C from occam
		10.1.7	Allocating memory for C functions called from other languages
			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
		10.1.8	Restrictions and caveats
			General
			Rules for importing C code
			Rules for importing occam code
	10.2	occam interface procedures
		10.2.1	Interface code
			Type 1
			Type 2
			Type 3
			Channel arrays
			Reserved channels
		10.2.2	Parameters to the C program
		10.2.3	Stack and heap requirements
			Stack overflow detection
		10.2.4	Type 1 interface definition
			Procedural interface
			Parameters to C program
			Example
		10.2.5	Type 2 interface definition
			Procedural interface
			Parameters to C program
			Example
		10.2.6	Type 3 interface definition
			Procedural interface
			Parameters to C program
			Example
		10.2.7	Building the occam equivalent process

11	EPROM programming
	11.1	Introduction
	11.2	Processing configurations
		11.2.1	Single processor, run from ROM
		11.2.2	Single processor, run from RAM
		11.2.3	Multiple process, multiple processor, run from RAM
		11.2.4	Multiple process, 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 ROM-bootable code
	11.5	Summary of EPROM tool steps for different configurations
		11.5.1	Using icconf
		11.5.2	Single processor unconfigured occam program
		11.5.3	Using occonf

12	Dynamic code loading
	12.1	Introduction
	12.2	Overview
	12.3	Basic Parenthood
	12.4	Childhood in INMOS ANSI C
		12.4.1	The IMS_descriptor pragma
	12.5	Advanced Parenthood
		12.5.1	static
		12.5.2	stack
		12.5.3	heap
		12.5.4	input/output
	12.6	Childhood in INMOS occam 2

Appendices

A	Transputer instruction set
	A.1	Prefixing instructions
	A.2	Direct instructions
	A.3	Operations
	A.4	Additional instructions for T400, T414, T425 and TB
	A.5	Additional instructions for IMS T800, T801 and T805
		A.5.1	Floating-point instructions
	A.6	Additional instructions for IMS T225, T400, T425, T800, T801, T805
	A.7	Additional instructions for the IMS T225, T400, T425, T801 and T805

B	Configuration language syntax
	B.1	Notation
	B.2	Implementation details
	B.3	Reserved words
		B.3.1	Keywords
		B.3.2	Pre-defined attributes
			Node attributes
			Processor attributes
			Process attributes
	B.4	Predefinitions
		B.4.1	Constants
		B.4.2	Types
		B.4.3	Declarations
	B.5	Language syntax
		B.5.1	Configuration
		B.5.2	Language features
		B.5.3	Expressions
		B.5.4	Replication and conditionals
		B.5.5	Numeric value declarations
		B.5.6	Network declarations
		B.5.7	Mapping declarations

C	Glossary

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

	Index

Back to the top