ANSI C toolset user manual
August 1990
INMOS document number: 72-TDS-224-00
577 Pages
© INMOS Limited 1990.
Preface
About this Manual
This manual is a User Guide to the ANSI C toolset. The manual is divided into two main parts, plus appendices:
1) User Guide. Describes the toolset and shows how it is used to develop and run transputer programs.
2) Tools. Detailed descriptions of the individual tools, with their syntax and options.
3) Appendices. For technical reference.
Differences from previous toolsets
Differences from the 3L Parallel C toolset are listed immediately after this preface.
Host versions
The manual is designed to cover all host versions of the toolset:
- IMS D7214 - IBM and NEC PC running MS-DOS
- IMS D5214 - Sun 3 systems running SunOS
- IMS D4214 - Sun 4 systems running SunOS
- IMS D6214 - VAX systems running VMS
Contents
Contents overview Contents Preface Differences from 3L Parallel C
User Guide
1 Introduction to transputers 1.1 Overview 1.2 Transputers 1.2.1 Multitransputer systems 1.2.2 Links 1.2.3 Hardware parallel support 1.2.4 Transputer products 1.3 Transputers and C 1.3.1 Programming model 1.3.2 Multitransputer programming 1.3.3 Real time programming 1.4 Program development 1.4.1 Software design 1.4.2 Programming 1.4.3 Debugging 1.4.4 Embedded systems 2 Overview of the toolset 2.1 Introduction 2.2 Features of the toolset 2.2.1 Standard object file forma 2.2.2 New configuration language 2.2.3 Runtime library 2.2.4 Concurrent programming 2.2.5 Transputer targets 2.2.6 Support for earlier toolsets 2.3 Toolset summary 2.4 ANSI C compiler - icc 2.5 Generating executable code 2.5.1 Linker - ilink 2.5.2 Configurer - icconf 2.5.3 Code collector - icollect 2.6 Loading and running programs 2.6.1 Host file server - iserver 2.6.2 Skip loader - iskip 2.7 Program development and support 2.7.1 Network debugger - idebug 2.7.2 Memory dumper - idump 2.7.3 Librarian - ilibr 2.7.4 Binary lister - ilist 2.7.5 Transputer simulator - isim 2.7.6 Makefile generator - imakef 2.7.7 File format convertor - icvlink 2.8 EPROM programming 2.8.1 EPROM programmer - ieprom 2.8.2 Memory configurer - iemit 2.9 Program development using the toolset 2.10 Runtime library 2.10.1 Header files 2.11 Toolset file extensions File extension scheme required for imakef 2.12 Error reporting 2.13 Host dependencies Command line syntax 2.13.1 Host-specific library 2.13.2 Filenames 2.13.3 Search paths 2.13.4 Environment variables 2.13.5 Default command line arguments 3 Getting started 3.1 Outline procedure 3.2 Running the examples 3.2.1 Sources 3.2.2 Example command lines 3.2.3 Using the simulator 3.3 A simple sequential program 3.3.1 Compiling 3.3.2 Linking 3.3.3 Configuring 3.3.4 Loading 3.4 A parallel version 3.5 Separate compilation 3.6 A simple configuration example 4 Parallel processing 4.1 Introduction 4.2 Abstract model 4.2.1 Processes 4.2.2 Channels 4.3 Semaphores 4.4 Parallel processing and transputers 4.4.1 Multitransputer networks 4.4.2 Multitransputer programming 4.4.3 Instruction set Process control Process selection Process timing 4.5 ANSI C 4.5.1 Library support 4.5.2 New data types 4.6 Concurrency functions 4.7 Processes 4.7.1 Unused process pointer 4.7.2 Process initialisation 4.7.3 Freeing stack and workspace 4.7.4 Process execution Unsynchronised processes Synchronised processes 4.7.5 Process timing and scheduling Process timing Process scheduling 4.7.6 Clock time 4.7.7 Input alternation 4.7.8 Simple alternation 4.7.9 Polling several Inputs 4.7.10 Timed input 4.7.11 Example of use 4.8 Channel communication 4.8.1 Transputer link addresses 4.8.2 Channel allocation, initialisation, and reset 4.8.3 Channel input and output 4.8.4 Reliable channel protocols 4.8.5 Semaphores Use of semaphores by the library 4.8.6 Semaphore allocation Examples 4.8.7 Semaphore handling 4.9 Parallel programming examples 5 Introduction to the ANSI C compiler 5.1 Introduction 5.2 Source and object code 5.2.1 Object code format 5.3 Transputer types and classes 5.3.1 Single transputer type 5.3.2 Creating a program which can run on a range of transputers 5.3.3 Object file containing code compiled for different targets 5.3.4 Classes/instruction sets - additional information 5.4 Error modes 5.5 Preprocessor directives 5.5.1 Include files 5.5.2 Pragmas 5.5.3 Compiler messages 5.6 Runtime library 5.6.1 Reduced library 5.7 Low level programming 5.7.1 Assembly code support 5.7.2 Compiler predefines 5.8 Mixed language programming 6 Configuring transputer programs 6.1 Introduction 6.2 Configuration model 6.3 Configuration language 6.3.1 Identifiers 6.3.2 Types 6.3.3 Constants 6.3.4 Booleans 6.3.5 Expressions and arithmetic 6.3.6 Arrays 6.3.7 Conditional statement 6.3.8 Replication 6.3.9 Predefined functions 6.4 Network definition 6.4.1 Nodes 6.4.2 New node types 6.4.3 Connections Prohibited connections 6.5 Software network description 6.5.1 Process attributes 6.5.2 Stack and heap size 6.5.3 Interface Array parameters get_param function Host server channels 6.5.4 Execution priority 6.5.5 Segment ordering 6.5.6 Defining new process types 6.5.7 Input and output channels 6.5.8 Edge connections 6.5.9 Assigning code to processes 6.6 Hardware network description 6.6.1 Processor links 6.6.2 Defining new processor types 6.6.3 Links 6.6.4 Edges 6.7 Mapping description 6.7.1 Placement of channels 6.8 Software network example 6.9 Terminating configured processes 6.10 Checking the configuration 6.11 Configuration examples 6.12 Configuration language summary 7 Loading transputer programs 7.1 Introduction 7.2 Tools for loading 7.3 The loading mechanism 7.3.1 Breakpoint debugging 7.4 Boards and subnetworks 7.4.1 Subsystem wiring 7.4.2 Connecting subnetworks 7.5 Loading programs for debugging 7.5.1 Board types 7.5.2 Use of the root transputer 7.5.3 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 Debugging with isim 8.2 Programs that can be debugged 8.3 Compiling programs for debugging 8.3.1 Symbolic debug information 8.3.2 Error modes 8.4 Debugging configured programs 8.5 Post mortem debugging Using abort to halt a program 8.5.1 Program loading 8.6 Breakpoint debugging 8.6.1 Runtime kernel 8.6.2 Hardware breakpoint support 8.6.3 Compiling the program 8.6.4 Loading the program 8.6.5 Clearing error flags 8.6.6 Breakpoint functions and commands 8.6.7 Breakpoints 8.7 Program termination 8.8 Symbolic facilities 8.8.1 Locating to source code 8.8.2 Browsing source code 8.8.3 Inspecting variables Jumping down channels 8.8.4 Tracing procedure calls 8.8.5 Modifying variables 8.8.6 Breakpointing 8.9 Monitor page 8.9.1 Startup display Process pointers Registers Error flags Clocks Memory map 8.9.2 Monitor page commands Examining memory Locating processes Specifying processes Selecting processes Other processors Breakpoint commands 8.10 A method for debugging halted programs 8.10.1 Locating all processes Running on the processor Waiting on a run queue Waiting on a timer queue Waiting for communication on a link Waiting for communication on a channel Processes stopped, terminated or not started 8.10.2 Locating functions 8.11 Library functions 8.11.1 Action when the debugger is not available 8.12 Debugging with isim 8.12.1 Command interface 8.12.2 Using the simulator 8.12.3 Program execution monitoring Breakpoints Single step execution 8.12.4 Core dump file 8.13 Debugging example 8.13.1 The example program 8.13.2 Compiling and loading the facs program 8.13.3 Setting Initial breakpoints 8.13.4 Starting the program 8.13.5 Entering the debugger 8.13.6 Inspecting variables 8.13.7 Backtracing 8.13.8 Jumping down a channel 8.13.9 Inspecting by expression 8.13.10 Modifying a variable 8.13.11 Backtracing to main 8.13.12 Entering #include files 8.13.13 Quitting the debugger 8.14 Points to note when using the debugger 8.14.1 Abusing hard links 8.14.2 Examining the active network (the network is volatile) 8.14.3 Selecting events from specific processors 8.14.4 Invalid pointers 8.14.5 INTERRUPT key 8.14.6 Program crashes 8.14.7 Undetected program crashes 8.14.8 Debugger hangs when starting program 8.14.9 Debugger hangs 8.14.10 Catching concurrent processes with breakpoints 8.14.11 Arrays as arguments 8.14.12 Backtracing with concurrent C processes 8.14.13 Phantom breakpoints 8.14.14 Errors generated by the full library 8.14.15 Errors generated by the reduced library 8.14.16 Shifting by large positive or negative values 8.14.17 Compiler optimisations 8.14.18 Determining connectivity and memory sizes 9 Mixed language programming 9.1 Introduction 9.2 Mixing code at configuration level 9.2.1 C and occam 9.3 Calling occam processes 9.3.1 Pragma IMS_nolink 9.3.2 Translating occam names 9.3.3 Rules for importing occam code 9.4 Parameter passing 9.4.1 Return values 9.4.2 Example of passing parameters 9.5 Mixing code using the occam 2 toolset 9.5.1 Calling C from occam 10 Using the EPROM tools 10.1 Introduction 10.2 Processing configurations 10.2.1 Single process, single processor, run from ROM 10.2.2 Multiple process, single processor, run from ROM 10.2.3 Single process, single processor, run from RAM 10.2.4 Multiple process, single processor, run from RAM 10.2.5 Multiple process, multiple processor, run from RAM 10.2.6 Multiple process, multiple processor, root run from ROM, rest of network run from RAM 10.3 The eprom tool: ieprom 10.4 Using the configurer and collector to produce ROM bootable code 10.5 Summary of EPROM steps for different processing configurations
Tools
11 icc - ANSI C compiler 11.1 Introduction 11.2 Running the compiler 11.2.1 Transputer targets 11.2.2 Error modes 11.2.3 Default command line options 11.2.4 File extension defaults 11.2.5 Search paths 11.3 Compiler directives 11.3.1 #include Relative directory names Backslash character in filenames 11.3.2 #define 11.3.3 #undef 11.3.4 #if 11.3.5 #ifdef 11.3.6 #ifndef 11.3.7 #else 11.3.8 #elif 11.3.9 #endif 11.3.10 #line 11.3.11 #pragma Pragma IMS_nolink 11.3.12 #error 11.4 Optimised functions 11.5 Compiler predefinitions 11.5.1 Constants 11.5.2 Functions 11.5.3 Other predefines 11.6 Fatal runtime errors 11.6.1 Runtime error messages 11.7 Transputer in-line code 11.8 Compiler diagnostics 11.8.1 Message format 11.8.2 Severities 11.8.3 Standard terms 11.8.4 ANSI trigraphs 11.8.5 Warning diagnostics 11.8.6 Recoverable errors 11.8.7 Serious errors 11.8.8 Fatal errors 11.9 icc error messages 11.9.1 Warnings 11.9.2 Serious errors 11.9.3 Fatal errors 12 icconf - configurer 12.1 Introduction 12.2 Configuration language implementation 12.3 Running the configurer 12.3.1 Default command line parameters 12.3.2 Boot-from-ROM options 12.3.3 Standard include files 12.3.4 Configuration description examples 12.3.5 Configurer library files 12.3.6 Search paths 12.3.7 Default memory map 12.4 Configurer diagnostics 12.4.1 Warning messages 12.4.2 Error messages 12.4.3 Serious messages 12.5 icconf error messages 12.5.1 Serious errors 12.5.2 Fatal errors 13 icollect - code collector 13.1 Introduction 13.2 Running the code collector 13.2.1 Examples of use 13.2.2 Input files 13.2.3 Output files 13.2.4 Non-bootable files 13.2.5 Boot-from-ROM options 13.2.6 Debug data file 13.2.7 Alternative bootstrap loaders 13.2.8 Small Values of IBOARDSIZE 13.3 Error messages 13.3.1 Warnings 13.3.2 Serious errors 14 icvlink - file format convertor 14.1 Introduction 14.2 Running the format convertor 14.2.1 Default command line 14.2.2 Input files Compiled object files Library files Linked object files 14.2.3 Output files 14.3 Transputer classes and error modes 14.4 Summary of rules for using icvlink 14.5 Error messages 14.5.1 Serious errors 15 idebug - debugger 15.1 Introduction 15.1.1 Post-mortem debugging 15.1.2 Breakpoint debugging 15.2 The root transputer 15.2.1 Board wiring 15.2.2 Post-mortem debugging R-mode programs 15.2.3 Post-mortem debugging T-mode programs 15.2.4 Post-mortem debugging from a network dump file 15.2.5 Debugging a dummy network 15.2.6 Methods for breakpoint debugging 15.3 Running the debugger 15.3.1 Environment variables 15.3.2 Program termination 15.3.3 Post-mortem mode invocation Reinvoking the debugger on single transputer programs 15.3.4 Breakpoint mode invocation Clearing error flags on transputer boards Program loading 15.3.5 Function key mappings 15.4 Debugging programs on different board types 15.4.1 Subsystem wiring 15.4.2 Debugging commands 15.4.3 Detecting the error flag in breakpoint mode 15.5 Debugging programs on other boards 15.6 Monitor page commands Command format Specifying transputer addresses 15.6.1 Scrolling the display 15.6.2 Commands mapped by ITERM 15.6.3 Summary of main commands 15.6.4 Symbolic-type commands and scroll keys 15.6.5 Symbolic-type commands 15.7 Symbolic functions 15.7.1 Breakpoint functions 15.8 Expression language for [INSPECT] and [MODIFY] 15.8.1 C syntax not supported 15.8.2 Extensions to C syntax 15.8.3 Editing keys 15.8.4 Types Type compatibility when using [MODIFY] 15.9 Display formats for source code symbols 15.9.1 Warnings 15.9.2 [TOGGLE HEX] key 15.9.3 Notation 15.9.4 Basic Types 15.9.5 Enumerated types 15.9.6 Pointers 15.9.7 Function Pointers 15.9.8 Structs 15.9.9 Unions 15.9.10 Addressof (&) operator 15.9.11 Arrays 15.9.12 Channels 15.10 Example displays 15.11 Error messages 15.11.1 Out of memory errors 15.11.2 If the debugger hangs 15.11.3 Error message list 16 idump - memory dumper 16.1 Introduction 16.2 Running the memory dumper 16.2.1 Example of use 16.3 Error messages 17 iemit - memory configurer 17.1 Introduction 17.2 Running iemit 17.3 Output files 17.4 Interactive operation 17.4.1 Page 0 17.4.2 Page 1 17.4.3 Page 2 17.4.4 Page 3 17.4.5 Page 4 17.4.6 Page 5 17.4.7 Page 6 17.5 Example iemit display pages 17.6 iemit error and warning messages 17.7 Memory configuration file 17.8 Memory interface conversion tool icvemit 17.9 Running icvemit 17.10 icvemit error messages 18 ieprom - EPROM program convertor 18.1 Introduction 18.2 Prerequisites to using the hex tool ieprom 18.3 Running ieprom 18.3.1 Examples of use 18.4 ieprom control file 18.5 What goes in the EPROM 18.5.1 Memory configuration data 18.5.2 Jump instructions 18.5.3 Bootable file 18.5.4 Traceback information 18.6 ieprom output files 18.6.1 Binary output 18.6.2 Hex dump 18.6.3 Intel hex format 18.6.4 Intel extended hex format 18.6.5 Motorola S-record format 18.7 Block mode 18.7.1 Memory organisation 18.7.2 When to use block mode 18.7.3 How to use block mode 18.8 Example control files 18.9 Error and warning messages 19 ilibr - librarian 19.1 Introduction 19.2 Running the librarian 19.2.1 Default command line 19.2.2 Library indirect files 19.3 Library modules 19.3.1 Selective loading 19.4 Library usage files 19.5 Building libraries 19.5.1 Rules for constructing libraries 19.5.2 Hints for building libraries 19.5.3 Optimising libraries Library build targeted at specific transputer types Semi-optimised library build targeted at all transputer types Optimised library 19.6 Error messages 19.6.1 Warning messages 19.6.2 Serious errors 20 ilink - linker 20.1 Introduction 20.2 Running the linker 20.2.1 Default command line parameters 20.3 Linker indirect files 20.3.1 Linker directives 20.3.2 Linker startup files 20.4 Linker options 20.4.1 Processor types 20.4.2 Error modes - options H, S and X 20.4.3 TCOFF and LFF output files - options T, LB, LC 20.4.4 Display information - option I 20.4.5 Virtual memory - option KB 20.4.6 Main entry point - option ME 20.4.7 Link map filename - option MO 20.4.8 Linked unit output file - option O 20.4.9 Permit unresolved references - option U 20.4.10 Disable interactive debugging - option Y 20.5 Selective linking of library modules 20.6 The link map file 20.7 Using imakef for version control 20.8 Error messages 20.8.1 Warning messages 20.8.2 Errors Serious errors 20.8.3 Embedded messages 21 ilist - binary lister 21.1 Introduction 21.2 Data displays 21.3 Running the lister 21.3.1 Default command line parameters 21.4 Specifying an output file - option O 21.5 Symbol data - option A 21.6 Code listing - option C 21.7 Exported names - option E 21.8 Hexadecimal/ASCII dump - option H 21.9 Module data - option M 21.10 Library index data - option N 21.11 Procedural interface data - option P 21.12 Specify reference - option R 21.13 Full listing - option T 21.14 File identification - option W 21.15 External reference data - option X 21.16 Error messages 21.16.1 Warning messages 21.16.2 Serious errors 22 imakef - Makefile generator 22.1 Introduction 22.2 How imakef works 22.3 Target files 22.4 File extensions for use with imakef 22.4.1 Transputer types and error modes Error modes in mixed language programs 22.5 Linker indirect files 22.6 Running the Makefile generator 22.6.1 Example of use 22.6.2 Disabling debug data 22.6.3 Removing intermediate files 22.7 imakef examples 22.7.1 Single transputer program 22.7.2 Multitransputer program 22.8 Format of Makefiles 22.8.1 Macros 22.8.2 Rules Action strings 22.8.3 Delete rule 22.8.4 Editing the Makefile Adding options 22.9 Error messages 23 iserver - host file server 23.1 Introduction 23.1.1 Loadable programs 23.2 Running the server 23.2.1 Examples of use 23.2.2 Supplying parameters to the program 23.2.3 Checking and clearing the network 23.2.4 Terminating the server 23.2.5 Options to use when loading the program 23.2.6 Specifying a link address - option SL 23.2.7 Terminating on error - option SE 23.3 Server functions File system commands Host environment commands Server control commands 23.4 Error messages 24 isim - T425 simulator 24.1 Introduction 24.2 Running the simulator 24.2.1 Example of use 24.2.2 ITERM file 24.3 Monitor page display 24.4 Simulator commands 24.4.1 Specifying numerical parameters 24.4.2 Commands mapped by ITERM 24.5 Batch mode operation 24.5.1 Setting up ISIMBATCH 24.5.2 Input command files 24.5.3 Output 24.5.4 Batch mode commands 24.6 Error messages 25 iskip - skip loader tool 25.1 Introduction 25.1.1 Uses of the skip tool 25.2 Running the skip tool 25.2.1 Examples of use 25.2.2 Monitoring the error status - option E 25.2.3 Loading a program 25.2.4 Clearing the error flag 25.3 Error messages
Appendices
A Toolset standards and conventions A.1 Command line syntax A.1.1 General conventions A.1.2 Standard options A.2 Filenames A.3 Search paths A.4 Standard file extensions A.4.1 'Main path' source and object files A.4.2 Other outputs A.4.3 Indirect input files A.4.4 Miscellaneous files A.5 Extensions required for imakef A.6 Error handling A.6.1 Error displays A.6.2 Severities A.6.3 Runtime errors B Transputer instruction set B.1 Pseudo-instructions B.2 size option on __asm statement B.3 Prefixing instructions B.4 Direct instructions B.5 Operations B.6 Additional instructions for T400, T414, T425 and TB B.7 Additional instructions for IMS T800, T801 and T805 B.7.1 Floating-point instructions B.8 Additional instructions for IMS T225, T400, T425, T800, T801, T805 B.9 Additional instructions for the IMS T225, T400, T425, T801 and T805 C Configuration language definition C.1 Notation C.2 Implementation details C.3 Reserved words C.3.1 Keywords C.3.2 Pre-defined attributes Node attributes Processor attributes Process attributes C.4 Predefinitions C.4.1 Constants C.4.2 Types C.5 Language syntax C.5.1 Configuration C.5.2 Language features C.5.3 Expressions C.5.4 Replication and conditionals C.5.5 Numeric value declarations C.5.6 Network declarations C.5.7 Mapping declarations D Bootstrap loaders D.1 Introduction D.1.1 The example bootstrap Transfer of control D.1.2 Writing bootstrap loaders D.2 Example user bootstrap D.3 The INMOS Network Loader E ISERVER protocol E.1 The host file server iserver E.2 The server protocol E.2.1 Packet size E.2.2 Protocol operation E.3 The server libraries E.4 Porting the server E.5 Server commands E.5.1 Notation E.5.2 Reserved values E.5.3 File commands E.5.4 Host commands E.5.5 Server commands F Occam interface code F.1 Interface code F.2 Reserved channels F.3 Stack and heap requirements F.3.1 Stack overflow F.4 Parameters to C main F.5 Type 1 interface F.5.1 Type 1 procedural interface F.5.2 Building a type 1 process F.6 Type 2 interface definition F.6.1 Type 2 procedural interface F.6.2 Example type 2 wrapping F.7 Type 3 interface definition F.7.1 Type 3 procedural interfaces F.7.2 Example type 3 wrapping G 3L functions supported G.1 Code compatibility G.1.1 Source code G.1.2 Object code G.2 Parallel functions supported G.2.1 Header file G.2.2 Restrictions H ITERM H.1 Introduction H.2 The structure of an ITERM file H.3 The host definitions H.3.1 ITERM version H.3.2 Screen size H.4 The screen definitions H.4.1 Goto X Y processing H.5 The keyboard definitions H.6 Setting up the ITERM environment variable H.7 An example ITERM I Glossary J Bibliography J.1 Reference books J.2 INMOS publications J.3 INMOS technical notes Index