ANSI C toolset user guide
October 1992
INMOS document number: 72-TDS-345-01
326 Pages
© INMOS Limited 1992.
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:
- Getting started - a tutorial.
- Parallel programming using a single transputer.
- The configuration process.
- Loading programs onto a transputer network.
- Debugging programs with the toolset debugger idebug.
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