ANSI C toolset reference manual
October 1992
INMOS document number: 72-TDS-346-01
458 Pages
© INMOS Limited 1992.
About this manual
This manual is the Toolset Reference Manual to the ANSI C toolset.
The manual provides reference material for each tool in the toolset describing:
- Command line syntax, including an example command line.
- Command line options.
- How to run the tool.
- A list of error messages which may be obtained.
Many of the tools in the toolset are generic to other INMOS toolset products i.e. the occam and FORTRAN toolsets and the documentation reflects this. Examples are given in C.
The appendices provide details of:
- Toolset conventions.
- Transputer types.
- The C assembler.
- Server protocol.
- ITERM files.
- Bootstrap loaders.
Contents
Contents overview Contents Preface
Tools
1 icc - ANSI C compiler 1.1 Introduction 1.2 Running the compiler Examples of use 1.2.1 Optimizing compiler options 1.2.2 Transputer targets 1.2.3 Error modes 1.2.4 Default command line options 1.2.5 File extension defaults 1.2.6 Search paths 1.2.7 Using the assembler 1.2.8 Compatibility with other C implementations Arithmetic right shifts Signedness of char 1.2.9 Software quality check 1.3 Memory map 1.4 Compiler directives 1.4.1 #define 1.4.2 #elif constant_expression 1.4.3 #else 1.4.4 #endif 1.4.5 #error 1.4.6 #if 1.4.7 #ifdef 1.4.8 #ifndef 1.4.9 #include Relative directory names Backslash character in filenames 1.4.10 #line 1.4.11 #pragma Pragma IMS_nolink Pragma IMS_descriptor 1.4.12 #undef 1.5 Compiler predefinitions 1.5.1 Macro names 1.5.2 Other predefines 1.6 Transputer inline code 1.6.1 Inlined functions 1.7 Compiler diagnostics 1.7.1 Message format 1.7.2 Severities 1.7.3 Standard terms abstract declarator 1.7.4 ANSI trigraphs 1.7.5 Warning diagnostics 1.7.6 Recoverable errors 1.7.7 Serious errors 2 icconf - configurer 2.1 Introduction 2.2 Configuration language implementation 2.3 Running the configurer 2.3.1 Default command line 2.3.2 Virtual routing processes 2.3.3 Support for the Advanced Toolset 2.3.4 Boot from ROM options 2.3.5 Mixed language programming 2.3.6 Configurer library file 2.3.7 Standard include files Defaults file setconf.inc Other include files 2.3.8 Configuration description examples 2.3.9 Search paths 2.3.10 Default memory map 2.3.11 LoadStart 2.3.12 System processes 2.4 Configurer messages 2.4.1 Information 2.4.2 Warnings 2.4.3 Errors 2.4.4 Serious messages 2.4.5 Fatal errors 3 icollect - code collector 3.1 Introduction Unconfigured program (using 'T' option) Configured processor program 3.2 Running the code collector 3.2.1 Examples of use 3.2.2 Default command line 3.2.3 Input files 3.2.4 Output files Single processor non-configured case (T option) Configured programs Memory map files Debug data file 3.3 Memory allocation for unconfigured programs 3.3.1 C and FORTRAN programs 3.3.2 occam programs 3.3.3 Memory initialization errors 3.3.4 Small values of IBOARDSIZE 3.4 Parity-checked memory 3.5 Non-bootable files created with the K option 3.5.1 File format 3.6 Boot-from-ROM output files 3.7 Alternative bootstrap loaders for unconfigured programs 3.8 Alternative bootstrap schemes 3.9 The memory map file 3.9.1 Unconfigured (single processor), boot from link Program targetted at transputer type Program targetted at transputer class 3.9.2 Configured program boot from link 3.9.3 Boot from ROM programs Unconfigured (single processor), boot from ROM, run in RAM Unconfigured (single processor), boot from ROM, run in ROM Configured program, boot from ROM, run in RAM Configured program, boot from ROM, run in ROM 3.10 Disabling interactive debugging - 'Y' option 3.11 Error messages 3.11.1 Warnings 3.11.2 Serious errors 3.11.3 Fatal errors 4 idebug - network debugger 4.1 Introduction 4.2 Debugging the root transputer 4.2.1 Board wiring 4.2.2 Post-mortem debugging R-mode programs 4.2.3 Post-mortem debugging T-mode programs 4.2.4 Post-mortem debugging from a network dump file 4.2.5 Debugging a dummy network 4.2.6 Methods for interactive breakpoint debugging 4.3 Running the debugger 4.3.1 Toolset file types read by the debugger 4.3.2 Environment variables 4.3.3 Program termination 4.4 Post-mortem mode invocation 4.4.1 Debugging T-mode programs - option 'T' 4.4.2 Debugging R-mode programs - option 'R' 4.4.3 Debugging a network dump file - option 'N' 4.4.4 Debugging a previous breakpoint session - option 'M' 4.4.5 Reinvoking the debugger on single transputer programs 4.4.6 Debugging boot from ROM programs 4.5 Interactive mode invocation 4.6 Function key mappings 4.7 Debugging programs on INMOS boards 4.7.1 Subsystem wiring 4.7.2 Debugging options to use with specific board types 4.7.3 Detecting the error flag in interactive mode 4.8 Debugging programs on non-INMOS boards 4.9 Monitor page commands 4.9.1 Command format 4.9.2 Specifying transputer addresses 4.9.3 Scrolling the display 4.9.4 Editing functions 4.9.5 Commands mapped by ITERM 4.9.6 Summary of commands 4.9.7 Symbolic-type commands 4.9.8 Scroll keys 4.9.9 Monitor page command descriptions 4.9.10 Symbolic-type commands 4.10 Symbolic functions 4.10.1 Symbolic functions 4.10.2 Interactive mode functions 4.10.3 Locating functions 4.10.4 Cursor and display control functions 4.10.5 Miscellaneous functions 4.11 INSPECT/MODIFY expression language for C 4.11.1 Syntax not supported 4.11.2 Extensions to C syntax Subarrays Scope resolution operator Hex constants Address constant indirect 4.11.3 Automatic expression pickup 4.11.4 Editing functions 4.11.5 Warnings 4.11.6 Types Type compatibility when using MODIFY 4.12 Display formats for source code symbols 4.12.1 Notation 4.12.2 Basic Types 4.12.3 Default type of "plain" char 4.12.4 Enumerated types 4.12.5 Pointers 4.12.6 Function Pointers 4.12.7 Structs 4.12.8 Unions 4.12.9 Addressof operator & 4.12.10 Arrays 4.12.11 Channels 4.13 Example displays 4.14 INSPECT/MODIFY expression language for occam 4.14.1 Inspecting memory 4.14.2 Inspecting arrays 4.14.3 Type compatibility when using MODIFY 4.15 Display formats for source code symbols 4.15.1 Notation 4.15.2 Basic Types 4.15.3 Channels 4.15.4 Arrays 4.15.5 Procedures and functions 4.16 Example displays 4.17 Error messages 4.17.1 Out of memory errors 4.17.2 If the debugger hangs 4.17.3 Error message list 5 idump - memory dumper 5.1 Introduction 5.2 Running the memory dumper 5.2.1 Example of use 5.3 Error messages 6 iemit - memory interface configurer 6.1 Introduction 6.2 Running iemit 6.3 Output files 6.4 Interactive operation 6.4.1 Page 0 6.4.2 Page 1 6.4.3 Page 2 6.4.4 Page 3 6.4.5 Page 4 6.4.6 Page 5 6.4.7 Page 6 6.5 iemit error and warning messages 6.6 Memory configuration file 7 ieprom - ROM program convertor 7.1 Introduction 7.2 Prerequisites to using the ieprom tool 7.3 Running ieprom 7.3.1 Examples of use 7.4 ieprom control file 7.5 What goes into the EPROM 7.5.1 Memory configuration data 7.5.2 Parity registers 7.5.3 Jump instructions 7.5.4 Bootable file 7.5.5 Traceback information 7.6 ieprom output files 7.6.1 Binary output 7.6.2 Hex dump 7.6.3 Intel hex format 7.6.4 Intel extended hex format 7.6.5 Motorola S-record format 7.7 Block mode 7.7.1 Memory organization 7.7.2 When to use block mode 7.7.3 How to use block mode 7.8 Example control files 7.8.1 Simple output 7.8.2 Using block mode 7.9 Error and warning messages 8 ilibr - librarian 8.1 Introduction 8.2 Running the librarian Example 8.2.1 Default command line 8.2.2 Library indirect files 8.2.3 Linked object input files 8.2.4 Library files as input 8.3 Library modules 8.3.1 Selective loading 8.3.2 How the librarian sorts the library index 8.4 Library usage files 8.5 Building libraries 8.5.1 Rules for constructing libraries 8.5.2 General hints for building libraries 8.5.3 Optimizing libraries All libraries Libraries containing occam modules Semi-optimized library build targeted at all transputer types Optimized library targeted at all transputer types Library build targeted at specific transputer types 8.6 Error Messages 8.6.1 Warning messages 8.6.2 Serious errors 9 ilink - linker 9.1 Introduction 9.2 Running the linker 9.2.1 Default command line 9.3 Linker indirect files 9.3.1 Linker indirect files supplied with the toolset 9.4 Linker directives 9.4.1 #alias basename {aliases} 9.4.2 #define symbolname value 9.4.3 #include filename 9.4.4 #mainentry symbolname 9.4.5 #reference symbolname 9.4.6 #section name 9.5 Linker options 9.5.1 Processor types 9.5.2 Error modes - options H, S and X 9.5.3 TCOFF and LFF output files - options T, LB, LC 9.5.4 Extraction of library modules - option EX Example: Extraction from a user library Example: Extraction from a user library, using the run-time library Example: Extraction from a user library, for multiple processor types Example: Generation of a completely linkable library Extraction using #define 9.5.5 Display information - option I 9.5.6 Virtual memory - option KB 9.5.7 Main entry point - option ME 9.5.8 Link map filename - option MO 9.5.9 Linked unit output file - O 9.5.10 Permit unresolved references - option U 9.5.11 Disable interactive debugging - Y 9.6 Selective linking of library modules 9.7 The link map file 9.7.1 MODULE record 9.7.2 SECT record 9.7.3 MAP record 9.7.4 Value record 9.8 Using imakef for version control 9.9 Error messages 9.9.1 Warnings 9.9.2 Errors 9.9.3 Serious errors 9.9.4 Embedded messages 10 ilist - binary lister 10.1 Introduction 10.2 Data displays 10.2.1 Modular displays 10.2.2 Example displays used in this chapter 10.3 Running the binary lister 10.3.1 Options to use for specific file types 10.3.2 Output device 10.3.3 Default command line 10.4 Specifying an output file - option O 10.5 Symbol data - option A 10.5.1 Specific section attributes 10.5.2 General symbol attributes 10.5.3 Example symbol data display 10.6 Code listing - option C 10.6.1 Example code listing display 10.7 Exported names - option E 10.7.1 Example exported names display 10.8 Hexadecimal/ASCII dump - option H 10.8.1 Example hex dump display 10.9 Module data - option M 10.9.1 Example module data display 10.10 Library index data - option N 10.10.1 Example library index display 10.11 Procedural interface data - option P 10.11.1 Example procedural data display 10.12 Specify reference - option R 10.13 Full listing - option T 10.13.1 Example full data display 10.13.2 Configuration data files 10.14 File identification - option W 10.14.1 Example file identification display 10.15 External reference data - option X 10.15.1 Example external reference data display 10.16 Error messages 10.16.1 Warning messages 10.16.2 Serious errors 11 imakef - makefile generator 11.1 Introduction 11.2 How imakef works 11.3 File extensions for use with imakef 11.3.1 Target files 11.4 Linker indirect files 11.5 Library indirect and library usage files 11.6 Running the makefile generator 11.6.1 Example of use 11.6.2 Specifying language mode 11.6.3 Configuration description files 11.6.4 Disabling debug data 11.6.5 Removing intermediate files 11.6.6 Files found on ISEARCH 11.6.7 Map file output for imap 11.7 imakef examples 11.7.1 C examples Single transputer program Multitransputer program 11.7.2 occam examples Single transputer program Multitransputer program 11.7.3 Mixed language program 11.8 Format of makefiles 11.8.1 Macros 11.8.2 Rules Example Action strings 11.8.3 Delete rule 11.8.4 Editing the makefile Adding options Re-running imakef 11.9 Error messages 12 imap - memory mapper 12.1 Introduction 12.2 Running the map tool 12.2.1 Source files required by imap 12.2.2 Re-directing imap's output 12.3 Output format 12.3.1 imap memory map structure 12.3.2 Process types 12.3.3 User processes 12.3.4 Module memory usage 12.3.5 Other processes 12.3.6 Symbol table 12.4 Example 12.5 Error messages 12.5.1 Serious errors 12.5.2 Fatal errors 13 iserver - host file server 13.1 Introduction 13.2 Loading programs 13.3 Host interface 13.4 Access to transputer networks User links The session manager 13.5 Running the iserver 13.5.1 Examples of use 13.5.2 Server environment variables 13.5.3 Loading programs Running a program using the iserver - option SB Sending data down a user link - option SC Running programs which do not use the server Analyzing a transputer network - option SA Terminating the server 13.5.4 Supplying parameters to a program 13.5.5 Specifying the transputer resource - option SL 13.5.6 Terminating on error - option SE 13.5.7 Terminating the server 13.5.8 Specifying the session manager configuration file 13.6 Using the session manager interface 13.6.1 Session manager commands 13.6.2 The options command 13.6.3 The iserver command 13.6.4 User-defined commands Running the debugger from the session manager 13.6.5 Host OS commands 13.7 Connecting transputers to computer networks 13.7.1 Capabilities 13.7.2 The connection database 13.7.3 Using a specific node 13.8 The connection database 13.8.1 Connection databases Capability names 13.8.2 Connection database format 13.8.3 Example connection databases PC development system Sun workstation IMS B300 13.9 New server features 13.9.1 Session manager 13.9.2 Connection manager 13.9.3 New command line options 13.9.4 User interrupt 13.9.5 Exit codes 13.9.6 Error codes 13.9.7 Stream identifier validation 13.9.8 Record structured file support 13.10 Error messages 13.10.1 Additional error messages 14 isim - T425 simulator 14.1 Introduction 14.2 Running the simulator 14.2.1 Passing in parameters to the program 14.2.2 Example of use 14.2.3 ITERM file 14.3 Monitor page display 14.4 Simulator commands 14.4.1 Specifying numerical parameters 14.4.2 Keys mapped by ITERM 14.4.3 Command summary 14.4.4 Command descriptions 14.5 Batch mode operation 14.5.1 Setting up ISIMBATCH 14.5.2 Input command files 14.5.3 Output 14.5.4 Batch mode commands 14.6 Error messages 15 iskip - skip loader 15.1 Introduction 15.1.1 Uses of the skip tool 15.2 Running the skip loader 15.2.1 Skipping a single transputer Subsystem wired down Subsystem wired subs 15.2.2 Skipping multiple transputers 15.2.3 Loading a program 15.2.4 Monitoring the error status - option E 15.2.5 Clearing the error flag 15.3 Error messages
Appendices
A Toolset conventions and defaults A.1 Command line syntax A.1.1 General conventions A.1.2 Standard options A.2 Unsupported options A.3 Filenames A.4 Search paths A.5 Standard file extensions A.5.1 Main source and object files A.5.2 Indirect input files (script files) A.5.3 Files read by the memory map tool imap A.5.4 Other output files A.5.5 Miscellaneous files A.6 Extensions required for imakef A.7 Message handling A.7.1 Message format A.7.2 Severities A.7.3 Runtime errors B Transputer types and classes B.1 Transputer types supported by this toolset B.2 Transputer types and classes B.2.1 Single transputer type B.2.2 Creating a program which can run on a range of transputers B.2.3 Linked file containing code compiled for different targets occam object files targetted at different targets B.2.4 Classes/instruction sets - additional information B.3 Transputer type command line options C Using the assembler C.1 Introduction C.2 Running the assembler C.2.1 Specifying the source filename C.2.2 Use of icc command options with the assembler C.2.3 Using the pre-processor with the assembler C.3 Language C.3.1 Label definitions C.3.2 Symbols C.3.3 Expressions C.3.4 Transputer instruction mnemonics C.3.5 Comments C.4 Assembler directives align blkb blkw byte comment common data debug defsym descriptor extern global init language maininit map1 map2 patch patch - codefix patch - datafix patch - extoffset patch - limit patch - modnumber patch - staticfix size sourcefile textname toolname word C.5 BNF grammar for assembler language C.6 Errors C.6.1 Fatal Errors C.6.2 Serious Errors C.6.3 Errors D iserver protocol D.1 iserver packets D.2 Server commands D.3 File commands D.3.1 Fopen - Open a file D.3.2 Fclose - Close a file D.3.3 Fread - Read a block of data D.3.4 Fwrite - Write a block of data D.3.5 FGetBlock - Read a block of data and return success D.3.6 FPutBlock - Write a block of data and return success D.3.7 Fgets - Read a line D.3.8 Fputs - Write a line D.3.9 Fflush - Flush a stream D.4 Record structured file commands D.4.1 FopenRec - Open a record structured file D.4.2 FGetRec - Read a record D.4.3 FPutRec - Write a record D.4.4 FputEOF - Write an end of file record D.4.5 Fseek - Set position in a file D.4.6 Ftell - Find out position in a file D.4.7 Feof - Test for end of file D.4.8 Ferror - Get file error status D.4.9 Remove - Delete a file D.4.10 Rename - Rename a file D.4.11 Isatty - Discover if a stream is connected to a terminal D.4.12 FileExists - Check to see if a file exists D.4.13 FerrStat - Get file error status D.5 Host commands D.5.1 Getkey - Get a keystroke D.5.2 Pollkey - Test for a key D.5.3 RequestKey - Request a single keyboard 'event' D.5.4 Getenv - Get environment variable D.5.5 Time - Get the time of day D.5.6 System - Run a command D.5.7 Translate - Translate an environment variable D.6 Server commands D.6.1 Exit - Terminate the server D.6.2 CommandLine - Retrieve the server command line D.6.3 Core - Read peeked memory D.6.4 Version - Find out about the server D.6.5 Getlnfo - Obtain information about the host and server D.6.6 CommandArgs - Retrieve the server command line arguments D.7 Reserved Tags and Third Party Tags D.7.1 MSDOS - Perform MS-DOS specific function D.7.2 SocketA - make a socket library call D.7.3 SocketM - make a socket library call D.7.4 ALSYS - Perform Alsys specific function D.7.5 KPAR - Perform Kpar specific function D.8 Record structured file format D.8.1 SunOS and MS-DOS Formatted Sequential Unformatted Sequential Formatted Direct Unformatted Direct D.9 Termination codes E ITERM files E.1 Introduction E.2 The structure of an ITERM file E.3 The host definitions E.3.1 ITERM version E.3.2 Screen size E.4 The screen definitions E.4.1 Goto X Y processing E.5 The keyboard definitions E.6 Setting up the ITERM environment variable E.7 Iterms supplied with a toolset E.8 An example ITERM F Bootstrap loaders F.1 Introduction F.1.1 The example bootstrap Transfer of control F.1.2 Writing bootstrap loaders Index