% ----------------------------------------------------------------------------
%
%                                  Hans Wolfgang Loidl, RISC-Linz,  4.3.1992 

% Changes:    <By whom>, <When>, <What changes> 
%
% H.W.  Loidl, 7.11.1991, Title in \bf style, contents of
%                         `Functions' in \tt style
%
%  SW-form for registering the software products that are installed
%  on a machine in the ACPC network. 
%  NOTE: This is no independent LaTex file. It has to be included in the 
%        file that describes the corresponding ACPC group
%        or in a `frame' LaTex file (see `sw-frame.tex') where
%        formating information etc is given.
%        All SW-forms should be included into the group description file
%        after the included HW-form.
%
% ----------------------------------------------------------------------------


\subsubsection*{\bf Occam 2 Toolset}

\begin{itemize}
 \item {\bf Name:} Occam 2 Toolset for IBM/NEC PC by Inmos (Version D705B).
                   % Full name and version of the software product (sw-p).

 \item {\bf Location:} /usr0/dos/itools/tools (of host PC)
                       % Full path of the sw-p (references to other
                       % important directories might be included here).

 \item {\bf Type:} A collection of independent programs for programming
                   in occam.
                   % What sort of sw-p is this?
                   % Possible entries are: (Parallelizing) Compiler, Debugger,
                   % Editor, Computer Algebra System etc.

 \item {\bf Characterization:} 
                   This toolset consists of various programs that
                   allow the user to work with a transputer (network).
                   The toolset contains the following programs:
                   \begin{itemize}
                    \item {\tt iboot} --- the bootstrap tool,
                    \item {\tt icheck} --- the occam 2 syntax checker,
                    \item {\tt iconf} --- the configurer,
                    \item {\tt idebug} --- the debugger,
                    \item {\tt idump} --- the memory dumper,
                    \item {\tt ilibr} --- the librarian,
                    \item {\tt ilink} --- the linker,
                    \item {\tt ilist} --- the binary lister,
                    \item {\tt imakef} --- the makefile generator,
                    \item {\tt iserver} --- the host file server,
                    \item {\tt isim} --- the T414 simulator,
                    \item {\tt iskip} --- the skip loader tool,
                    \item {\tt occam} --- the occam 2 compiler.
                   \end{itemize}

                           % A short description of what the sw-p
                           % does (no longer than 50 words).

 \item {\bf Functions:} 

       For the most important tools listed above, their usage is
       described in more detail here:
                        % Description of the main features of the 
                        % sw-p.
                        % This should include the following subtopics:
       \begin{itemize}
        \item {{\tt iboot} --- the bootstrap tool}.
              This tool produces executable code for single transputers. The
              object file it generates can be loaded onto a single transputer
              and run. The input must be a compiled ({\tt .t}{\it xx}) or a
              linked ({\tt .c}{\it xx}) object file.           
       \begin{itemize}
        \item {Invocation:}  {\tt iboot} {\it filename} \{ {\it options} \}
        \item {Termination:} {\tt $<$CTRL$>$ C} % How to leave the sw-p.
        \item {Help:}                % How to get help.
        \item {Example:}     {\tt iboot foo.c8h} 

                             This takes the compiled and linked file {\tt foo.c8h}
                             and creates the file {\tt foo.b8h} that can be started
                             with the {\tt iserver} on one transputer.
        \item {Other important functions:}  
       \end{itemize}


        \item {{\tt icheck} --- the occam 2 syntax checker}.
              This tool performs a syntax check of the full occam 2 product 
              language, as described in the ``Occam 2 Refernece Manual'',
              but produces no object code. It generates more data and displays
              more information about the errors than the compiler. 
       \begin{itemize}
        \item {Invocation:}  {\tt icheck} {\it filename} \{ {\it options} \}
        \item {Termination:} {\tt $<$CTRL$>$ C} % How to leave the sw-p.
        \item {Help:}                % How to get help.
        \item {Example:}     {\tt icheck foo.occ} 

                             This checks the syntax of the occam program in 
                              {\tt foo.occ}. The `{\tt .occ}' suffix may be omitted.
        \item {Other important functions:}  
       \end{itemize}

        \item {{\tt iconf} --- the configurer}.
              This tool allocates occam processes to processors and assigns
              channels to links on transputer networks. It takes a 
              configuration description and produces either an object code
              file ready for booting into a network of transputers, or a
              configuration map describing the allocation of code and 
              placement of channels.
       \begin{itemize}
        \item {Invocation:}  {\tt iconf} {\it filename} \{ {\it options} \}
        \item {Termination:} {\tt $<$CTRL$>$ C} % How to leave the sw-p.
        \item {Help:}                % How to get help.
        \item {Example:}     {\tt iconf foo.pgm} 

                             This configures a transputer network that is
                              described in the file
                              {\tt foo.pgm}. The `{\tt .pgm}' suffix may be omitted.

                                    % of some important features.
        \item {Other important functions:}  
       \end{itemize}

    \item {{\tt idebug} --- the debugger}.
          This tool allows to debug an occam program even when it is
          executed on a transputer network. With this debugger errors
          can be located in the source code, parameters can be examined
          channels and processes can be analysed and procedures can be 
          traced.
       \begin{itemize}
        \item {Invocation:}  {\tt idebug} {\it bootablefile} \{ {\it options} \}
        \item {Termination:} {\tt $<$CTRL$>$ C} % How to leave the sw-p.
        \item {Help:}                % How to get help.
        \item {Example:}     {\tt idebug foo.btl} 

                             This starts the debugger on the program {\tt foo.btl}
                              that runs on a transputer network. Possible 
                              suffices are `{\tt .b}{\it xx}', `{\tt .btl}' and 
                              `{\tt .btr}'.
        \item {Other important functions:}  
       \end{itemize}

    \item {{\tt idump} --- the memory dumper}.
          This tool dumps the contents of the root processor's memory
          to disk. It is used to enable the debugging of code running
          on the root transputer.
       \begin{itemize}
        \item {Invocation:}  {\tt idump} {\it filename} {\it memorysize} \{ {\it startoffset length} \}
        \item {Termination:} {\tt $<$CTRL$>$ C} % How to leave the sw-p.
        \item {Help:}                % How to get help.
        \item {Example:}     {\tt idump foo.btl \#200000 \#300000 \#100000}

                             This dumps the first half of the memory of the 
                              root transputer (bytes 0 -- \#200000). Additionally,
                              \#100000 bytes starting from address \#300000 are
                              dumped.
        \item {Other important functions:}  
       \end{itemize}

    \item {{\tt ilink} --- the linker}.
          This tool creates single object files from separately compiled code
          and libraries (all external references are resolved).
       \begin{itemize}
        \item {Invocation:}  {\tt ilink} \{ {\it filenames} \} \{ {\it options} \}
        \item {Termination:} {\tt $<$CTRL$>$ C} % How to leave the sw-p.
        \item {Help:}                % How to get help.
        \item {Example:}     {\tt ilink foo1.t8h foo2.t8h string.lib} 

                              This links the compiled occam files {\tt foo1.t8h} and
                              {\tt foo2.t8h} with the routines from the string library
                              in {\tt string.lib}. The resulting file has the name 
                              {\tt foo1.c8h}.
        \item {Other important functions:}  
       \end{itemize}

    \item {{\tt iserver} --- the host file server}.
          This tool loads programs onto transputers and transputer networks
          and provides the run-time environment through which programs 
          communicate with the host.
       \begin{itemize}
        \item {Invocation:}  {\tt iserver} \{ {\it options} \}
        \item {Termination:} {\tt $<$CTRL$>$ C} % How to leave the sw-p.
        \item {Help:}                % How to get help.
        \item {Example:}     {\tt iserver /sb foo.btl} 

                              This loads the program foo.btl on a tranputer
                              network and boots the program ({\tt /sb} option).
                              To get a file like {\tt foo.btl} the source files
                              have to be compiled and linked and made bootable
                              by using the bootstrap tool {\tt iboot} (for 
                              single transputer programs) or the configurer
                              {\tt iconf} (for multitransputer programs). 
                              Furthermore, before the {\tt iserver} can be 
                              started the topology of the network has to be fixed
                              with a call to the network configurer (see below).
        \item {Other important functions:}  
       \end{itemize}

    \item {{\tt occam} --- the occam 2 compiler}.
          This tool compiles occam source code programs into the assembler
          code of the transputer (optionally to T212, T222, M212, T414, T425,
          T800).
       \begin{itemize}
        \item {Invocation:}  {\tt occam} {\it filename} \{ {\it options} \}
        \item {Termination:} {\tt $<$CTRL$>$ C} % How to leave the sw-p.
        \item {Help:}                % How to get help.
        \item {Example:}     {\tt occam /t8 /h foo.occ} 

                             This compiles the occam program {\tt foo.occ} into
                              the assembler code of the T800 transputer in 
                              halt mode (i.e.\  the transputer halts when an
                              error occurs in the program). The resulting
                              file is {\tt foo.t8h}.
        \item {Other important functions:}  
       \end{itemize}
  \end{itemize}

 \item {\bf Installation:}  \verb+SET IBOARDSIZE=#400000+ (this sets the transputer
                            memory size for the bootstrap loader).

                            \verb+SET TRANSPUTER=#150+ (this sets the transputer 
                            base address).

                            \verb+SET ITERM=Z:\USR0\DOS\ITOOLS\ITERMS\IBMPC.ITM+
                            (the terminal description file for a PC).

                            \verb+SET ISEARCH=Z:\USR0\DOS\ITOOLS\LIBS+ (this sets the
                            library path).

 \item {\bf Manuals:} ``Occam 2 Toolset, User Manual, IBM/NEC PC'', by 
                      Inmos Limited, 1989.

                      ``Occam 2 Reference Manual'', by Inmos Limited,
                      Prentice Hall, 1988.
                            % Name, location and version of the manuals for this
                            % sw-p.
 
 
\end{itemize}


