This file gives a few notes about each example program in the subdirectories
of the examples directory.

SUBDIRECTORY idebug


debug.occ    Example of use of debug support procedures

facs.occ     Simple parallel program using channels, for demonstrating
	     breakpointing and postmortem debugging.

scope.occ    example demonstrating occam scope rules

modify.occ   example of modifying memory with debugger

master.occ   master process for opair.pgm

mult.occ     multiplier process for opair.pgm

opair.pgm    configuration source file for network debugging example

deadlock.occ  Simple example of a deadlock.

deadfix.occ   Simple example of a deadlock modified for easy debugging


SUBDIRECTORY sorter

The examples in this subdirectory are based on the pipeline sorter program
originally introduced in "A tutorial example to occam programming" by
Pountain and May, and also discussed in the occam toolset user manual.

inout.occ     The user interface, etc (compile for TA H)

element.occ   The pipeline sorting element (compile for TA H)

sorter.occ    A single processor main program calling the 2 modules above

sorthdr.inc   A shared file of constant and protocol definitions

sortsoft.inc  The software description of the sorter for configured versions

sortb4.pgm    Configuration for a single processor on a T4 or similar

sortb3.pgm    Configuration for four T4 processors on a B003 (manual build)

sortb3c.pgm   Configuration for four T4 processors on a B003 (imakef version)

sortb4b3.pgm  Configuration for 5 processors on a B004 and a B003 (for imakef)

sortnb3.pgm   Configuration for two or more B003s (for imakef)

The principal point made by these examples is the relatively simple changes
that are needed to run suitably structured programs on a wide variety of
different hardware networks on to which a linear pipeline of processes may
be mapped. The use of imakef (and the corresponding need for different file
naming conventions) is also demonstrated. Users with alternative
multi-processor configurations (e.g B008 or other motherboard plus TRAMs)
may easily adapt the configurations to suit their hardware.

SUBDIRECTORY oc

ex0.occ       The archetypal "Hello world" program

nullprog.occ  The absolutely smallest program that can be compiled, etc.

simple.occ    The introductory program from the toolset user manual

exh1.occ      An example of simple numerical outputs for all occam types

exh2.occ      Inputs and outputs of REAL32 numbers

exh4.occ      Derived from exh2 to show how composition of parallel processes
	      may be used to divert input/output streams, etc

exh19.occ     Exercise showing the use of most of the string handling library

exh20.occ     Simple use of some of the mathematical library functions

exh21.occ     Demonstration of all the ways a program can communicate with
	      its supporting host using the ISERVER interface.
	      Also includes code to determine the type of transputer being
	      used

ask.occ       Simple example of interactive use of the host terminal

echokeys.occ  Program which uses the keyboard translation table of an ITERM
	      file to translate key sequences as is done by the 'idebug'
	      tool

wfs.occ       Program for writing a value into the whole of memory.
	      Maybe useful to clear parity on B004 and similar boards.

loadrxh.occ   Program demonstrating how to read a loadable program code file
	      and to execute the code therein by means of KERNEL.RUN

codesc.occ    A procedure which may be compiled into a loadable code file

assert.occ    Coding example - asserting reset/analyse, setting error on
	      a B004 or similar.

b6pr0.occ     A simple T2 program using RS232 UART output (for a B006)
	      Contains UART driver code also suitable for B001,2,11 and 16,
	      by changing base address of memory mapped UART registers.

process0.inc  Conversion from screen stream to bytes for ANSI terminal

process1.inc  Conversion from screen stream to bytes for TVI920 terminal

process2.inc  RS232 UART driver for B001, B002

process3.inc  RS232 UART driver for B006

b6math.occ    A bigger B006 program showing use of T2 maths library

double.occ    Coding example - double buffering

ringbuff.occ  Coding example - ring buffer

farmprot.inc  Protocol definitions for following farming example

applic.occ    Stub for application code in a processor farm example

farming.occ   Single processor analogue showing processor farm style of
	      use of pipelined processes. This may be trivially extended to
	      an arbitrary hardware network for examples such as the
	      Mandelbrot Set


SUBDIRECTORY occonf

These examples include configuration code (in .pgm files) for a variety of
simple networks. Common sub-files are stored in .inc files.

b004td.occ    A user interface for the simple 5 processor hello program

hello0.occ    Hello procedure for root processor of a B003

hello1.occ    Hello procedure for other processors of B003

b3b4.pgm      Configuration calling three previous examples on a 5 processor
	      network consisting of a B004 and a B003.
	      (see also ..\sorter\sortb4b3.pgm)

rootsrv.pgm   The first configuration example in the user manual (not complete)

hostpass.occ  A stub procedure for a variety of following configurations.
	      This goes on the processor supported directly by the host.

multpass.occ  A stub procedure for a variety of following configurations.
	      This is replicated on all other processors of the networks.

The following configuration files are in a form suitable for generating
make files with imakef. They all use the same code code modules:
hostpass.cah and multpass.cah

otree.pgm     A simple tree-shaped configuration

oring.pgm     A simple ring with more processes than processors

opipe.pgm     A simple pipeline of processes

squanet.inc   Hardware network description for a general p*p square network
	      suitable for osquare and ozigzag

squab003.inc  Special case for 2*2 square on a B003, supported by T800

squamap.inc   Mapping of osquare onto square network plus host transputer

osquare.pgm   A complex multi-connected square array of processes, with
	      mappings onto one processor or may be modified for
	      (p*p)+1 processors.

ozigzag.pgm   A different configuration based on the same network as osquare
	      but with a less complex connectivity in the software


SUBDIRECTORY mixed

These examples show various techniques for mixing C and occam

The first group use procedures from the library "centry.lib" which is in
the INMOS C toolset products.  The first 3 pairs are C subroutines called
from occam using different types of interface. These interfaces are unchanged
from earlier versions of the occam and C toolsets. Users will need to compile
both sources appropriately and then link them with suitable library code,
and collect them into bootable programs.
A linker indirect file corresponding to each main program is also provided.

Always use the tools corresponding to the most recently revised toolset -
some of the original tools did not cater for mixed language programs properly.

hello.c        Calling C from occam. For type 1 interface

occam.occ      Type 1 call using MAIN.ENTRY to call hello.c

occam.lah      Linker indirect file

hello2.c       Calling C from occam. For type 2 interface, using occam
	       channels for communication

harness.occ    Type 2 call using PROC.ENTRY to call hello2.c

harness.lah    Linker indirect file

slave.c        Calling C from occam. Type 3. No C use of host io interface.
	       so use libcred.lib when linking.

master.occ     Type 3 call using PROC.ENTRY.RC to call slave.c

master.lah     Linker indirect file

The second group use procedures from the library "callc.lib". This method
is introduced in the new occam toolset and provides closer control of the
setting up of work space when a C routine is called from occam. It should
be used to put an occam wrapping round any C program that is to be
called from an occam main program.

Occam calling C:

f.c            A simple C function which may be called from occam

c.occ          An occam program which calls f

c.lah          Linker indirect file

csubfunc.c     A C function as used in the occam toolset user manual to
	       show calling from an occam program

callc.occ      An occam program which calls the C function csubfunc

callc.lax      Linker indirect file

C calling occam:

ocfunc.occ     A simple occam FUNCTION that may be called from C

caloccam.c     A C program which calls ocfunc

caloccam.lax   Linker indirect file

occparam.occ   An occam module containing a function and a procedure with
	       parameters of all the supported types. This may be compiled
	       for any transputer type or class and then called from a C
	       program similarly compiled

calocc2.c      A C program which calls the occam function and procedure
	       defined above. Contains conditional compilation directives
	       to cope with the differences between 32bit and 16bit
	       transputers

calocc2.lax    Linker indirect file

SUBDIRECTORY mixconf

This directory contains three examples showing how C code may be called
directly from the occam configurer in both single and multi-processor
configurations. These examples use procedures from the library "centry.lib".
Each program is accompanied by a make file and a linker indirect file as it
is not straightforward to produce these for multiprocessor mixed language
programs with imakef. When using the make files the make macro FLAG should
be defined as / or - according to host.

mixed1.pgm     Single processor program written in C and linked with
mixed1c.c      MAIN.ENTRY to make it callable from occam configuration code
mixed1c.lnk
mixed1.mak

mixed2.pgm     2 processor program showing communication between C and
mixed2o.occ    occam processes on two channels in parallel using PROC.ENTRY
mixed2c.c      Both processes can talk to the server.
mixed2c.lnk
mixed2.mak

mixed3.pgm     A root process in occam, talking to the server and to another
mixed3c.c      process on a separate processor which is coded in C and
mixed3o.occ    called using PROC.ENTRY.RC, which does not treat server
mixed3c.lnk    channels specially.
mixed3.mak

SUBDIRECTORY bootstrap

Example bootstraps and related matter - see User Manual Appendix F

userboot.asm   Example bootstrap

loader.occ     Network loader

userboot.lnk   Link file for userboot

makefile.tp    Make file for userboot
