Transputer Development System
First published 1988 by
Prentice Hall International (UK) Ltd
ISBN-10: 0-13-928995-X; INMOS document number: 72-TRN-011-00
© 1988 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 B004 board containing an IMS T414 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 MS D700D (IBM PC) and IMS D800D (NEC PC) releases of the Transputer Development System.
Contents overview Preface 1 How to use the manual 1.1 Introduction 1.2 User guide 1.3 Reference manual 1.4 Appendices 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 Program development 2.4.1 Logical behaviour 2.4.2 Performance measurement 2.4.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 TDS2 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 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 a keystroke macro 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 Checking occam programs 5.4.2 Compiling occam programs 5.4.3 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 of compilation 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 keyboard and screen 6.3.2 Communicating with the user filer 6.3.3 The fold manager 6.3.4 Communicating with the filer 6.3.5 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 TDS terminal and file I/O 6.5.3 Reading and writing a DOS file 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 host file server 8.3 Creating a standalone program 8.4 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 Read/Write and Finish 9.6.10 Other options 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.3.4 Code format Extracted code format 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
The reference manual
12 The development environment 12.1 Keys 12.2 Messages 12.2.1 Development environment messages 12.2.2 TDS server termination messages 13 Utilities 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 LOAD NETWORK 13.1.12 MAKE COMMENT 13.1.13 MAKE FOLDSET 13.1.14 RECOMPILE 13.1.15 REPLACE 13.1.16 SEARCH 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 ENABLE 13.2.10 WRITE HOST 13.2.11 WRITE PROTECT 14 Libraries 14.1 Multiple length integer arithmetic functions 14.2 Floating point functions 14.3 IEEE arithmetic functions 14.4 2D block move library MOVE2D DRAW2D CLIP2D 14.5 Bit manipulation and CRC library BITCOUNT CRCWORD CRCBYTE BITREVNBITS BITREVWORD 14.6 Code execution 14.7 Arithmetic instruction library 14.8 Single length and double length elementary function library 14.8.1 Introduction 14.8.2 Inputs and Outputs 14.8.3 Accuracy Range Reduction Generated Error Propagated Error Test Procedures 14.8.4 Symmetry 14.8.5 The Function Specifications Terms used in the Specifications Specification of Ranges Abbreviations 14.8.6 ALOG 14.8.7 ALOG10 14.8.8 EXP 14.8.9 POWER 14.8.10 SIN 14.8.11 COS 14.8.12 TAN 14.8.13 ASIN 14.8.14 ACOS 14.8.15 ATAN 14.8.16 ATAN2 14.8.17 SINH 14.8.18 COSH 14.8.19 TANH 14.8.20 RAN 14.9 IMS T414 elementary function library 14.9.1 ALOG 14.9.2 ALOG10 14.9.3 EXP 14.9.4 POWER 14.9.5 SIN 14.9.6 COS 14.9.7 TAN 14.9.8 ASIN 14.9.9 ACOS 14.9.10 ATAN 14.9.11 ATAN2 14.9.12 SINH 14.9.13 COSH 14.9.14 TANH 14.9.15 RAN 14.10 Basic type i/o conversion library ioconv 14.11 Extra type i/o conversion library extrio 14.12 String handling library strings 14.12.1 Character handling functions 14.12.2 String comparison functions 14.12.3 String editing procedures 14.12.4 String searching functions 14.12.5 String append functions 14.13 General purpose i/o procedure library userio 14.13.1 The simple input and output procedures Simple output procedures Simple input procedures Output to and input from the folded file store 14.13.2 Simple output 14.13.3 Control codes to the terminal screen 14.13.4 Simple input 14.13.5 Long integers and reals 14.13.6 Write folded stream 14.13.7 Read folded stream 14.14 Interface procedure library interf 14.15 Block transfer procedure library slice 14.16 Low level user filer interface support library ufiler 14.17 TDS server channel support library msdos 14.18 Byte stream i/o library derivio 14.19 Afserver low level protocol library afio 14.20 Afserver command library afiler 14.21 Afserver protocol interface and multiplexor afinterf 14.22 Transputer board support library t4board 14.23 IMS B006 support library t2board 14.24 Extraordinary link handling library reinit 14.25 Block CRC library blockcrc 15 Tools 15.1 Debugger 15.1.1 Debugging a PROGRAM What the debugger does 15.1.2 Debugging an EXE Start up procedure for an EXE 15.1.3 Debugging an SC Start up procedure for an SC 15.1.4 Symbolic facilities Debugging an SC Invalid Wdesc 15.1.5 Monitor page 15.1.6 Monitor page options 15.1.7 Hints Invalid pointers Failure to communicate Default addresses IF and CASE ALT CASE Input Deadlocks 15.1.8 Creating a core dump file 15.1.9 occam run time errors 15.2 Transputer network tester 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 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 15.4.1 Using the program 15.4.2 What the EPROM hex program does Error messages 15.5 Hex to programmer program 15.5.1 Using the program 15.5.2 Adapting the Hex to programmer program 16 System interfaces 16.1 Terminal interfaces 16.1.1 Input from the keyboard channel 16.1.2 Screen stream protocol Outputting characters to the screen Cursor movement Clearing the screen Character operations Line operations Other operations Initialising Changing the way keyboard input is processed Termination claim and release 16.2 User filer interfaces 16.2.1 User filer protocol 16.2.2 Selecting a fold for access 16.2.3 User filer channels 16.2.4 User filer modes 16.2.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.2.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.3 Host file server 16.3.1 Afserver command syntax 16.3.2 Afserver command line options 16.3.3 Afserver protocol Introduction to the afserver protocol Overview of afserver operations Server termination operations Stream opening operations Server information operations Operating system support operations Stream information operations Stream reading and writing operations Low level DOS operations 16.3.4 Afserver error messages 16.3.5 Summary of afserver protocol Basic protocol Parameter and result types Operations protocol 16.4 TDS file server 16.4.1 Server description 16.4.2 The SERVER command 16.4.3 Server overview 16.4.4 Communicating with the server Channel multiplexing Sequence of communications 16.4.5 The terminal channels Protocol to the terminal Protocol from the terminal Differences in the server and TDS terminals 16.4.6 The filer channels 16.4.7 The kernel channels 16.4.8 The serial channels 16.4.9 Summary of TDS server protocol
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 MATHVALS D.2 USERHDR D.3 FILERHDR D.4 KRNLHDR D.5 USERVALS D.6 AFHDR E Error numbers E.1 File server errors E.2 DOS errors E.3 Filer errors E.4 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 H Transputer Instruction support H.1 Direct functions H.2 Short indirect functions H.3 Long indirect functions H.4 Additional Instructions for IMS T800 I Bibliography I.1 INMOS publications I.2 INMOS technical notes I.3 References J Glossary