Transputer Development System - Second Edition
First published 1990 by
Prentice Hall International (UK) Ltd
ISBN-10: 0-13-929068-0; INMOS document number: 72-TRN-011-01
© 1990 INMOS Limited. INMOS reserves the right to make changes in specifications at any time and without notice. The information furnished by INMOS in this publication is believed to be accurate; however, no responsibility is assumed for its use, nor for any infringement of patents or other rights of third parties resulting from its use. No license is granted under any patents, trademarks or other rights of INMOS.
This manual describes the Transputer Development System, an integrated programming environment developed by INMOS to support the programming of transputer networks in occam. The Transputer Development System comprises an integrated editor, file manager, compiler and debugging system.
The Transputer Development System runs on a transputer board; for example it runs on an INMOS IMS B008 board with an IMS B404 TRAM (transputer module) containing an IMS T800 32-bit processor and 2 MBytes of memory. This board is installed inside an IBM PC/AT or similar computer, which provides a means of interfacing keyboard, screen and disks to the transputer.
The Transputer Development System allows occam programs to be written, compiled and then run from within the development system. Programs may also be configured to run on a target network of transputers; these may range from a single transputer on an evaluation board to networks of several hundred transputers. The code for a transputer network may be loaded directly from the Transputer Development System, through a link connecting the Transputer Development System transputer to the target network. Programs may also be placed into a file separate from the Transputer Development System, or into a ROM (Read-Only Memory), and used to load a network.
A post-mortem debugger allows programs running in the Transputer Development System environment or on a transputer network to be examined after they have been interrupted or have stopped as a result of an error. The line of source corresponding to a program error on one of the processors can be displayed, and the values of variables may be examined. The state of other currently active processes on this processor, and on other processors in the network, can also be examined.
The Transputer Development System software includes the interactive programming environment, the compilation utilities and other programming tools, a number of libraries to support program development (such as mathematical functions and I/O libraries), and an extensive set of examples in source form.
This manual is divided into two major parts: the User Guide, which introduces the system and takes the reader through the steps needed to write, compile and run programs, and the Reference Manual, which contains detailed reference information on the editor, utilities, tools, libraries and system interfaces.
The instructions on installing the software and a detailed list of the components of the release are contained in a separate Delivery manual, supplied with the software.
This manual corresponds to the IMS D700E (IBM PC) release of the Transputer Development System, which supports new transputer targets and is supported by, and can generate programs supported by, the server program iserver, used by all other INMOS hosted software products.
Contents overview Preface 1 How to use the manual 1.1 Introduction 1.2 User guide 1.3 Reference manual 1.4 Appendices 1.5 Delivery manual 2 Introduction 2.1 Overview Transputers and occam 2.2 System design rationale 2.2.1 Programming 2.2.2 Hardware 2.2.3 Programmable components 2.3 occam model 2.4 A programmer's introduction to the transputer 2.4.1 Addresses and the memory 2.4.2 Registers and instructions 2.4.3 Processes and communications 2.4.4 Starting and stopping 2.4.5 Programs 2.4.6 Multi-processor programs 2.4.7 Conventions for the code on each processor 2.5 Program development 2.5.1 Logical behaviour 2.5.2 Performance measurement 2.5.3 The transputer development system
The user guide
3 Directories 4 The editing environment 4.1 Introduction 4.1.1 Folding 4.1.2 Files as folds 4.2 Starting and finishing the system for the first time 4.2.1 Starting the system 4.2.2 The TDS3 command 4.2.3 Problems starting the system 4.2.4 Keyboard layout 4.2.5 Repainting the screen 4.2.6 Ending the session 4.2.7 Interrupting and rebooting the TDS 4.2.8 Suspending the TDS 4.3 Tutorial file 4.4 The editor interface 4.4.1 Editor's view of a document 4.4.2 The screen display 4.4.3 Line types 4.5 Editor functions 4.5.1 Overview of editor functions 4.5.2 Editor modes 4.5.3 Moving the cursor 4.5.4 Scrolling and panning the screen 4.5.5 Fold browsing operations Opening and closing folds Fold information Browsing mode 4.5.6 Inserting and deleting characters Insertion Deletion 4.5.7 Fold creation and removal 4.5.8 Filed folds Storage of files in memory File extensions Writing back files 4.5.9 Deleting lines 4.5.10 Moving and copying lines 4.5.11 Defining keystroke macros 4.6 Utilities and programs 4.6.1 The toolkit fold 4.6.2 Loading utilities and programs 4.6.3 Loading code from the toolkit fold 4.6.4 Running a utility 4.6.5 Supplying parameters to utilities 4.6.6 When a utility finishes 4.6.7 Running executable programs 4.7 File handling utilities 4.8 Searching and replacing 4.9 Listing programs 4.9.1 The lister and unlister programs 4.10 Transferring TDS files between computers 5 Compiling and linking occam programs 5.1 Introduction 5.2 The compiler utility set 5.3 Preparing a program for compilation 5.3.1 Creating a compilation fold 5.3.2 Comment folds 5.4 Using the compiler utilities 5.4.1 Compilation for different transputers Transputer classes 5.4.2 Mixing code for different transputers 5.4.3 Error modes of compilation 5.4.4 Mixing code with different error modes 5.4.5 Checking occam programs 5.4.6 Compiling occam programs 5.4.7 Linking occam programs 5.5 Compiling a simple example program 5.5.1 Getting the compiler utilities 5.5.2 Making an EXE fold 5.5.3 Checking and compiling the example program 5.5.4 Running the example program 5.5.5 Compilation information 5.6 Separate compilation and libraries 5.6.1 Separate compilation 5.6.2 Libraries 5.6.3 Compiling and linking large programs 5.6.4 Changing and recompiling programs 5.6.5 The implementation of change control 5.7 Compiler parameters 5.7.1 The parameter fold 5.7.2 Error modes and range checking 5.7.3 Alias and usage checking 5.7.4 Using the separate vector space 5.8 Creating and using libraries 5.8.1 Creating libraries 5.8.2 Using libraries 5.8.3 Using protocols with separate compilation 5.8.4 How the library system works 5.8.5 The library logical names fold 5.8.6 Library compaction 5.9 Changing and recompiling libraries 5.9.1 Change control 5.9.2 Library dependencies 5.9.3 Recompiling mixed libraries 5.9.4 Compacting recompiled libraries 5.10 The pipeline sorter example 5.10.1 The 'header.tsr' library fold 5.10.2 The 'problem.tsr' library fold 5.10.3 The 'monitor.tsr' library fold The keyboard handler The screen handler 5.11 The implementation of occam 5.11.1 The transputer implementation of occam 5.11.2 Memory allocation by the compiler 5.11.3 Implementation of usage checking Usage rules Checking of non-array elements Checking of arrays of variables and channels Arrays as procedure parameters Abbreviating variables and channels Problems with replicators 6 Running programs within the TDS 6.1 Loading and running an executable program 6.2 The interface for user programs 6.3 The channel parameters and their protocols 6.3.1 The explicit iserver channels 6.3.2 The keyboard and screen 6.3.3 Communicating with the user filer 6.3.4 The fold manager 6.3.5 Communicating with the filer 6.3.6 The kernel channels 6.4 Memory usage within the TDS 6.5 The occam input/output procedures 6.5.1 The input/output models 6.5.2 The hostio model 6.5.3 The streamio model 6.5.4 The folded file store model 6.5.5 Interface procedures 6.6 The pipeline sorter example 6.7 Example programs using the I/O libraries 6.7.1 Keyboard and screen example 6.7.2 Example showing input from file 7 Configuring programs and loading transputer networks 7.1 Introduction 7.2 The transputer configuration and loading utilities 7.3 The configuration description 7.4 Configuring a program 7.5 Connecting a network to the TDS 7.6 Loading a network 7.7 Using the transputer network tester 7.8 Running the pipeline sorter on a target transputer 7.8.1 Creating a PROGRAM fold 7.8.2 Monitoring the target with an EXE 7.8.3 Configuring and running the example 7.9 Running the pipeline sorter on a four transputer network 7.9.1 A PROGRAM for four transputers 7.9.2 The root transputer 7.9.3 The three other transputers 7.9.4 Configuration for four transputers 8 Standalone transputer programs 8.1 Introduction 8.2 Using the iserver 8.3 Creating a parameterless standalone program 8.4 Creating a standard hosted PROC 8.5 The pipeline sorter 9 Debugging 9.1 Using the debugger 9.2 Debugger facilities 9.2.1 Symbolic facilities 9.2.2 Lower level facilities 9.3 Debugging a program running on a network of transputers 9.4 Debugging a program running within the TDS 9.5 Debugging a standalone program 9.6 A worked example 9.6.1 Running the example program 9.6.2 Creating a core dump 9.6.3 Using the debugger 9.6.4 Inspecting variables 9.6.5 Jumping down channels 9.6.6 Retrace and Backtrace 9.6.7 Process Queues 9.6.8 Display occam 9.6.9 Finish 9.6.10 Other functions 9.6.11 More information 9.7 How the debugger works 9.7.1 How the debugger accesses the network 9.7.2 Debugging information generated by the compiler 9.7.3 How the symbolic facilities work 9.7.4 Backtracing 9.7.5 Inspecting variables 9.7.6 Jumping down channels 9.7.7 Analysis of deadlock 9.7.8 occam scope rules 10 EPROM programming 10.1 Introduction 10.2 How to create the fold bundle 10.3 Creating the ROM file 10.4 Burning the ROM 10.5 Execution from ROM instead of RAM 10.6 ROMs which load from a host computer 10.7 Adding a memory configuration to the EPROM 11 Low level programming 11.1 Allocation 11.2 Code insertion 11.2.1 Using the code insertion mechanism 11.2.2 Labels and jumps 11.3 Dynamic code loading 11.3.1 The call 11.3.2 Loading parameters 11.3.3 Examples 11.4 Extraordinary use of links 11.4.1 Clarification of requirements 11.4.2 Programming concerns 11.4.3 Input and output procedures 11.4.4 Recovery from failure 11.4.5 Example: a development system 11.5 Setting the error flag
The reference manual
12 The development environment 12.1 Keys 12.2 Messages 12.2.1 Development environment messages 12.2.2 iserver termination messages 13 Utilities 13.2 File handling package 13.2.1 ATTACH 13.2.2 COMPACT LIBRARIES 13.2.3 COPY ATTACH 13.2.4 COPY IN 13.2.5 COPY OUT 13.2.6 DETACH 13.2.7 READ HOST 13.2.8 RENAME FILE 13.2.9 WRITE HOST 13.1 occam program development package 13.1.1 CHECK 13.1.2 COMPILATION INFO Compilation information Configuration information Library information 13.1.3 COMPILE 13.1.4 Compiler messages 13.1.5 Library logical name fold errors 13.1.6 Program errors 13.1.7 Implementation limits 13.1.8 Compiler errors 13.1.9 Configurer error messages 13.1.10 EXTRACT 13.1.11 LIST FOLD 13.1.12 LOAD NETWORK 13.1.13 MAKE FOLDSET 13.1.14 RECOMPILE 13.1.15 REPLACE 13.1.16 SEARCH 14 Libraries 14.1 Introduction to the libraries 14.2 Compiler and system libraries (complibs) 14.2.1 Multiple length integer arithmetic functions 14.2.2 Floating point functions 14.2.3 IEEE arithmetic functions 14.2.4 2D block move library 14.2.5 Bit manipulation and CRC library 14.2.6 Code execution 14.2.7 Arithmetic instruction library 14.2.8 Extraordinary link handling library reinit 14.2.9 Block CRC library blockcrc 14.3 Mathematical libraries (mathlibs) 14.3.1 Single length and double length elementary function library Introduction Inputs NaNs and Infs Outputs Accuracy Symmetry The Function Specifications ALOG ALOG10 EXP POWER SIN COS TAN ASIN ACOS ATAN ATAN2 SINH COSH TANH RAN 14.3.2 IMS T414 elementary function library ALOG ALOG10 EXP POWER SIN COS TAN ASIN ACOS ATAN ATAN2 SINH COSH TANH RAN 14.4 Introduction to input/output libraries (hostlibs, iolibs) 14.5 Tables of contents of the input/output libraries (hostlibs, iolibs) 14.5.1 Basic type i/o conversion library ioconv 14.5.2 Extra type i/o conversion library extrio 14.5.3 String handling library strings 14.5.4 Host i/o basic procedure library splib 14.5.5 Hostio general and screen output procedure library sollib 14.5.6 Keyboard input library sklib 14.5.7 Host and stream i/o interface library spinterf 14.5.8 Protocol conversion library afsp 14.5.9 Keystream and screenstream library streamio 14.5.10 Screenstream interface procedure library ssinterf 14.5.11 General purpose i/o procedure library userio 14.5.12 Low level user filer interface support library ufiler 14.5.13 Interface procedure library interf 14.5.14 Transputer board support libraries t4board, t2board 14.5.15 Other libraries 14.6 Protocols and formal parameter conventions 14.7 Environment enquiries 14.8 Representation conversions and string handling Time and date functions Character handling functions String comparison functions String editing procedures String searching functions String add/append functions Line parsing 14.9 Terminals and text streams 14.9.1 The simple input and output procedures (TDS stream models) 14.9.2 Procedures supporting screenstream output 14.9.3 Procedures supporting keystream input 14.9.4 Procedures supporting the standard input model of the keyboard 14.9.5 Procedures supporting the standard output model of the screen 14.10 Buffers, multiplexors and protocol converters 14.11 Access to host filing system 14.12 Access to the TDS's folded file store Write folded stream Read folded stream 14.13 Access to transputer board peripherals 15 Tools 15.1 Debugger 15.1.1 Debugging a PROGRAM on a network which may include the host What the debugger does 15.1.2 Debugging an EXE (or UTIL) Start up procedure for an EXE 15.1.3 Debugging an SC Start up procedure for an SC 15.1.4 Symbolic functions Debugging an SC Invalid Wdesc 15.1.6 Monitor page commands 15.1.7 Hints Invalid pointers Failure to communicate Default addresses IF, CASE and guarded ALT ALT CASE input Deadlocks 15.1.8 Creating a core dump file 15.1.9 occam run time errors 15.2 Transputer network tester - nettest 15.2.1 What the network tester does 15.2.2 Using the network test program A note on matching Limitations of use 15.2.3 Options available 15.2.4 Interpretation of loading data 15.2.5 Description of network 15.2.6 Error messages 15.2.7 Testing specifications 15.2.8 Stages of loading 15.3 Memory interface program - memint 15.3.1 Capabilities 15.3.2 Using the program 15.3.3 Input 15.3.4 Output Numeric output Waveform output 15.3.5 Storing and retrieving parameters and pages 15.3.6 Examples 15.3.7 Caveats 15.3.8 Error and warning messages 15.4 EPROM hex program - epromhex 15.4.1 Using the program 15.4.2 What the EPROM hex program does Error messages 15.5 Hex to programmer program - hextoprq 15.5.1 Using the program 15.6 Write EPROM file program - promfile 15.6.1 Using the program 15.7 Preparing a bootstrap and adding it to a program - addboot, wocctab 15.7.1 The code to occam table converter wocctab 15.7.2 The bootstrap adder addboot 15.7.3 The example two-stage loader 15.7.4 Memory allocation 16 System interfaces 16.1 Use of host environment variables 16.2 The TDS loader and TDS start up process 16.3 The ITERM terminal configuration file 16.3.1 The structure of an ITERM file 16.3.2 The host definitions ITERM version Screen size 16.3.3 The screen definitions Goto X Y processing 16.3.4 The keyboard definitions 16.3.5 Setting up the ITERM environment variable 16.3.6 An example ITERM 16.4 The INMOS file server - iserver - command line interface 16.4.1 iserver command line syntax Loading programs Terminating the server Server termination codes Specifying a link address - option SL Terminating on error - option SE 16.4.2 Server functions 16.4.3 iserver error messages 16.5 The INMOS file server - iserver - program interface 16.5.1 The server protocol Packet size Protocol operation 16.5.2 The server libraries 16.5.3 Porting the server 16.5.4 Defined protocol Reserved values File commands Fopen Fclose Fread Fwrite Fgets Fputs Fflush Fseek Ftell Feof Ferror Remove Rename 16.5.5 Host commands Getkey Pollkey Getenv Time System 16.5.6 Server commands Exit CommandLine Core Version 16.5.7 Extensions to iserver protocol supported within the TDS only 16.6 The TDS screen and keyboard channels 16.6.1 Input from the keyboard channel 16.6.2 Screen stream and SS protocols Outputting characters to the screen Cursor movement Clearing the screen Character operations Line operations Other operations Initialising Changing the way keyboard input is processed Other commands 16.7 The TDS user filer interface 16.7.1 User filer protocol 16.7.2 Selecting a fold for access 16.7.3 User filer channels 16.7.4 User filer modes 16.7.5 Commands in user filer command mode Definitions of uf. commands Example showing use of a uf. command Opening a fold for reading Opening a fold for writing 16.7.6 Communications in file stream modes Introduction to file stream modes Syntax of valid sequences of communications Data stream modes Folded stream modes Reading a fold stream from the system sender Writing a fold stream to the system receiver 16.8 Other TDS interfaces
A Keyboard layouts A.1 IBM PC function keys A.2 IBM PC keyboard layout A.3 NEC PC keyboard layout B Summary of standard utilities C Names defined by the software D System constant definitions D.1 LINKADDR D.2 MATHVALS D.3 SPHDR D.4 STRMHDR D.5 USERHDR D.6 FILERHDR E Error numbers E.1 File server errors E.2 DOS errors E.3 TDS internal errors E.4 Filer errors E.5 File streamer errors F Fold attributes F.1 Fold attributes in the TDS F.1.1 Fold type F.1.2 Fold contents F.1.3 Fold indent F.2 Attribute constant values F.3 Attributes of common fold types G File formats G.1 Structure of folded files G.2 DOS files produced by the TDS G.3 CODE PROGRAM files G.4 CODE SC, CODE EXE and CODE UTIL files G.5 Other compiler outputs H Transputer instruction support H.1 Direct functions H.2 Short indirect functions H.3 Long indirect functions H.4 Additional instructions for IMS T425 and IMS T800 H.5 Additional instructions for IMS T800 only I Bibliography I.1 INMOS publications I.2 INMOS technical notes I.3 References J Glossary Index