Occam 2 toolset user guide
INMOS document number: 72-TDS-366-01
© INMOS Limited 1993.
About this manual
This manual is the User Guide to the occam 2 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 occam 2 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.
- Access to host services.
- 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.
- Low level programming facilities provided by the toolset e.g. dynamic code loading.
The appendices provided in the User Guide include a glossary of terms and a bibliography.
Contents overview Preface Host versions About this manual Examples used in this manual About the toolset documentation set Other documents FORTRAN toolset INQUEST Documentation conventions
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 Introduction to the toolset 2.1 Introduction 2.2 Toolset features 2.3 Standard object file format 2.4 occam 2 compiler 2.4.1 Programming model 2.4.2 Language extensions 2.4.3 occam libraries 2.4.4 Low level programming 2.5 Multilanguage linker 2.6 Configuration system 2.6.1 Software routing and multiplexing 2.6.2 Code and data placement 2.7 Mixed language programming 2.8 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 3.8.1 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 Introduction 4.2 Running the examples 4.2.1 Sources 4.2.2 Example command lines 4.2.3 Using the simulator 4.3 The example program 4.3.1 Compiling the program 4.3.2 Linking the program 4.3.3 Configuring the program 4.3.4 Collecting the program 4.3.5 Running the program on a transputer board 4.3.6 Running the program using isim 4.3.6 Running the program using isim 4.3.7 A short cut to creating a bootable file 4.4 Compiling and linking for other transputer types 4.5 Using imakef 5 Programming single transputers 5.1 Program examples 5.2 occam programs 5.2.1 Compiling programs Compilation information 5.2.2 Linking programs 5.2.3 Displaying the contents of code files 5.2.4 Making bootable programs 5.2.5 Loading and running programs 5.2.6 Interrupting programs 5.3 occam error handling 5.3.1 Error modes Error mode UNDEFINED 5.3.2 Error detection 5.4 Interactive debugging and virtual routing 5.5 Alias and usage checking 5.6 Using separate vector space 5.7 Sharing source between files 5.8 Separate compilation 5.8.1 Sharing protocols and constants 5.8.2 Compiling and linking large programs 5.9 Using imakef 5.10 Libraries 5.10.1 Selective loading 5.10.2 Building libraries 5.11 Example program - the pipeline sorter 5.11.1 Overview of the program 5.11.2 The channel protocol 5.11.3 The sorting element 5.11.4 The input/output process 5.11.5 The calling program 5.11.6 Compiling the program 5.11.7 Linking the program 5.11.8 Configuring and collecting the program 5.11.9 Running the program 5.11.10 Alternative method of creating a bootable file 5.11.11 Automated program building 6 Configuring transputer networks 6.1 Introduction 6.1.1 Mixing languages 6.2 Configuration model 6.2.1 Configuration language Importing code and source files 6.2.2 Overall structure of a configuration description 6.3 Hardware description 6.3.1 Declaring processors 6.3.2 NODE attributes 6.3.3 NETWORK description 6.3.4 Declaring EDGEs 6.3.5 Declaring ARCs 6.3.6 Abbreviations 6.3.7 Host connection 6.3.8 Examples of network descriptions 6.4 Software description 6.4.1 Libraries of linked units 6.4.2 Example 6.5 Mapping descriptions 6.5.1 Mapping processes 6.5.2 Channels 6.5.3 Mapping channels 6.5.4 Mapping without a MAPPING section 6.5.5 Moving code and data areas 6.5.6 Reserving memory 6.5.7 Absolute address code placement 6.5.8 Control of routing and virtual channel placement routecost tolerance linkquota occonf.inc 6.5.9 Control of debugging by the INQUEST tools 6.5.10 Mapping examples 6.6 Example: A pipeline sorter on four transputers 6.6.1 Building the program 6.6.2 Running the program 6.6.3 Automated program building 6.6.4 Other configuration examples 6.7 Conditional configurations 6.7.1 Example: Configuration using conditional IF 6.8 Summary of configuration steps 6.9 Further considerations 6.9.1 The effect of occonf on idebug 6.9.2 Reliable Channel Communications 6.9.3 Checking the configuration 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 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 Debugging transputer programs 9.1 Introduction 9.1.1 Post-mortem debugging 9.1.2 Interactive debugging 9.1.3 Mixed language debugging 9.1.4 Debugging with isim 9.2 Programs that can be debugged 9.3 Compiling programs for debugging Minimal debugging information occam channel communication C channel communication 9.3.1 Error modes 9.4 Debugging configured programs 9.4.1 Debugging with configuration level channels 9.4.2 Debugging with the configurer reserved attribute 9.5 Debugging boot from ROM programs 9.6 Post-mortem debugging 9.6.1 C and FORTRAN programs 9.6.2 occam programs 9.6.3 Interrupted programs 9.6.4 Parity errors 9.6.5 Debugging the root transputer Skip loading 9.7 Interactive debugging 9.7.1 Runtime kernel 9.7.2 Processors without hardware breakpoint support 9.7.3 Creating programs for debugging 9.7.4 Loading the program Clearing error flags Parity-checked memory 9.7.5 Running the debugger 9.7.6 Interactive mode functions and commands Symbolic functions Monitor page commands 9.7.7 Breakpoints 9.8 Program termination 9.9 Symbolic facilities Help screen 9.9.1 Locating to source code 9.9.2 Browsing source code 9.9.3 Inspecting source code and variables 9.9.4 Jumping down channels 9.9.5 Tracing procedure calls 9.9.6 Modifying variables 9.9.7 Breakpointing 9.9.8 Miscellaneous functions 9.10 Monitor page 9.10.1 Startup display Process Workspace or Stack Process Descriptors Process pointers Practical notes Registers Error flags Clocks Parity errors Memory map 9.10.2 Monitor page commands Examining memory Locating processes Specifying processes Selecting processes Other processors Breakpoint commands Changing to post-mortem debugging 9.11 Locating processes 9.11.1 Running on the processor 9.11.2 Waiting on a run queue 9.11.3 Waiting on a timer queue 9.11.4 Waiting for communication on a link 9.11.5 Waiting for communication on a software virtual link 9.11.6 Waiting for communication on a channel 9.11.7 Interrupted by a high priority process 9.11.8 Processes terminated or not started 9.11.9 Locating to procedures and functions 9.12 Debugging support library 9.12.1 Examples C example occam example 9.12.2 Actions when the debugger is not available 9.13 Debugging with isim 9.13.1 Command interface 9.13.2 Using the simulator 9.13.3 Program execution monitoring Breakpoints Single step execution 9.13.4 Core dump file 9.14 Hints and further guidance 9.14.1 Invalid pointers 9.14.2 Examining and disassembling memory 9.14.3 Scope rules 9.14.4 Inspecting soft configuration channels 9.14.5 Locating to IF, ALT and CASE in occam 9.14.6 Analyzing deadlock 9.15 Points to note when using the debugger 9.15.1 Abusing hard links 9.15.2 Examining an active network (the network is volatile) 9.15.3 Using INSPECT with channel communications 9.15.4 Debugging in the presence of software virtual links 9.15.5 Selecting events from specific processors 9.15.6 Minimal confidence check 9.15.7 INTERRUPT key 9.15.8 Program crashes 9.15.9 Undetected program crashes 9.15.10 Debugger hangs when starting program 9.15.11 Debugger hangs 9.15.12 Catching concurrent processes with breakpoints 9.15.13 Phantom breakpoints 9.15.14 Breakpoint configuration considerations 9.15.15 Determining connectivity and memory sizes 9.15.16 Long source code lines 9.15.17 Resuming breakpoints on the transputer seterr instruction 9.15.18 Shifting by large or negative values 9.15.19 Aspects of C debugging Arrays as arguments to C functions Backtracing with concurrent C processes Errors generated by the full C library Errors generated by the reduced C library C compiler optimizations 9.16 C debugging example 9.16.1 The example program 9.16.2 Compiling and loading the example 9.16.3 Setting initial breakpoints 9.16.4 Starting the program 9.16.5 Entering the debugger 9.16.6 Inspecting variables 9.16.7 Finding addresses of variables 9.16.8 Backtracing 9.16.9 Jumping down a channel 9.16.10 Inspecting by expression 9.16.11 Modifying a variable 9.16.12 Backtracing to main() 9.16.13 Entering #include files 9.16.14 Quitting the debugger 9.17 occam debugging example 9.17.1 The example program 9.17.2 Compiling the facs program Using imakef Using the tools directly 9.18 Breakpoint debugging 9.18.1 Loading the program 9.18.2 Setting initial breakpoints 9.18.3 Starting the program 9.18.4 Entering the debugger 9.18.5 Inspecting variables 9.18.6 Backtracing 9.18.7 Jumping down a channel 9.18.8 Modifying a variable 9.18.9 Entering #INCLUDE files 9.18.10 Resuming the program 9.18.11 Clearing a breakpoint 9.18.12 Quitting the debugger 9.19 Post-mortem debugging 9.19.1 Running the example program 9.19.2 Creating a memory dump file 9.19.3 Running the debugger Inspecting variables Inspecting channels Retracing and Backtracing Displaying process queues Goto process
10 Advanced use of the configurer 10.1 Code and data placement 10.1.1 Default memory map 10.1.2 Other memory configurations 10.1.3 reserved attribute Example 10.1.4 location attributes Example (on a 32úbit processor) 10.1.5 order attributes 10.1.6 location versus order attributes 10.2 Channel communication - configuration techniques 10.2.1 Routing and placement constants 10.2.2 Optimizing important application channels 10.2.3 Virtual communications - use of fast memory 10.2.4 Control of routing and placement Introduction to routing and placement attributes Routing cost Tolerance Link quota The minimal spanning tree 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 10.3 Example - optimized filter test program 11 Mixed language programming 11.1 Mixed language programs 11.1.1 Declaring external routines 11.1.2 Translating identifiers 11.1.3 Parameter passing Parameter compatibility Range checking in occam occam timers 11.1.4 Passing array parameters C calling occam Multi-dimensional arrays (C calling occam) occam calling C Multi-dimensional arrays (occam calling C) 11.1.5 Function return values C function type void Restrictions on functions that may be called 11.1.6 Global static base parameter Method 1 - dummy GSB parameter Method 2 - nolink pragma Method 3 - using call_without_gsb function 11.1.7 Linking the program Calling occam from C Calling C from occam 11.1.8 Allocating memory for C functions called from occam 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 11.1.9 Restrictions and caveats General Rules for importing C code Rules for importing occam code 11.2 occam interface procedures 11.2.1 Interface code Type 1 Type 2 Type 3 Channel arrays Reserved channels 11.2.2 Parameters to the C program 11.2.3 Stack and heap requirements Stack overflow detection 11.2.4 Type 1 interface definition Procedural interface Parameters to C program Example 11.2.5 Type 2 interface definition Procedural interface Parameters to C program Example 11.2.6 Type 3 interface definition Procedural interface Parameters to C program Example 11.2.7 Building the occam equivalent process 12 EPROM programming 12.1 Introduction 12.2 Processing configurations 12.2.1 Single processor, run from ROM 12.2.2 Single processor, run from RAM 12.2.3 Multiple process, multiple processor, run from RAM 12.2.4 Multiple process, multiple processor, root run from ROM, rest of network run from RAM 12.3 The EPROM tool: ieprom 12.4 Using the configurer and collector to produce ROM-bootable code 12.5 Summary of EPROM tool steps for different configurations 12.5.1 Using icconf 12.5.2 Single processor unconfigured occam program 12.5.3 Using occonf 13 Low level programming 13.1 Allocation 13.1.1 The PLACE statement 13.1.2 Allocating specific workspace locations 13.1.3 Allocating channels to links 13.2 RETYPING channels and creating channel array constructors 13.3 Code insertion 13.3.1 Using the code insertion mechanism 13.3.2 Special names 13.3.3 Labels and jumps 13.3.4 Workspace zero 13.3.5 Below workspace slots 13.3.6 Channels 13.3.7 Programming notes 13.4 Dynamic code loading 13.4.1 Calling code 13.4.2 Loading parameters 13.4.3 Examples Example 1: load from link and run Example 2: system loader 13.5 Extraordinary use of links 13.5.1 Introduction 13.5.2 Clarification of requirements 13.5.3 Programming concerns 13.5.4 Input and output procedures 13.5.5 Recovery from failure 13.5.6 Example: a development system 13.6 Scheduling 13.7 Setting the error flag
A Configuration language definition A.1 Notation A.2 Introduction A.3 New types and specifications A.3.1 Syntax of configuration description A.4 Hardware description A.4.1 Processor attributes A.4.2 Syntax definition A.5 Software description A.5.1 Syntax definition A.6 Mapping structure A.6.1 Syntax definition A.7 Constraints B Equivalent data types B.1 occam as the calling language B.1.1 Parameter passing B.1.2 Return values B.1.3 Example of passing parameters from occam to C B.2 C as the calling language B.2.1 Parameter passing B.2.2 Return values B.2.3 Example of passing parameters C Transputer instruction set C.1 Prefixing instructions C.2 Direct instructions C.3 Operations C.4 Additional instructions for T400, T414, T425 and TB C.5 Additional instructions for IMS T800, T801 and T805 C.5.1 Floating-point instructions C.6 Additional instructions for IMS T225, T400, T425, T800, T801, T805 C.7 Additional instructions for the IMS T225, T400, T425, T801and T805 C.8 Instructions supported by 'sequential code insertion' D Transputer code insertion D.1 Inline transputer code insertion D.1.1 Sequential code insertion D.1.2 Full code insertion D.2 ASM construct D.2.1 Syntax E Glossary F Bibliography F.1 Transputers F.2 C programming F.3 occam programming F.4 INMOS technical notes F.5 Development systems F.6 References Index