readme

spice中支持多层次元件模型仿真的可单独运行的插件源码

a) The command 'parallel' is used to execute a program. It needs to
   read a configuration file (the procgroup file in the parlance of the
   PARMACS) to determine which process to run where. Currently it tries
   the following in order to determine the file name:

  1) the first argument on the command line with .p appended
  2) as 1) but also prepending $HOME/pdir/
  3) the translation of the environmental variable PROCGRP
  4) the file PROCGRP in the current directory

b) The command line arguments of parallel are currently propagated to
   all processes and rsh usually exports the environment variables also.
   Note that extra arguments are appended and that the PROCGRP file if
   specified is still there, so any arguments that you use must be flagged
   rather than just positional.  Avoid the flag -master as this is used
   by TCGMSG when starting remote processes.

c) If you want a process to interactively read input then it must be
   process number 0 and must be on the same machine as parallel. This 
   is because remote processes are invoked with 'rsh -n' to avoid
   bugs due to race conditions in the shell.

d) The PROCGRP file is read to EOF. The character '#' (hash or pound
   sign) is used to indicate a comment which continues to the next new
   line character. For each 'cluster' of processes the following
   whitespace separated fields should be present in order.

      <userid>  <hostname>  <nslave>  <executable>  <workdir>

  userid     The username on the machine that will be executing the
             process. 

  hostname   The hostname of the machine to execute this process.
             If it is the same machine on which parallel was invoked
             the name must match the value returned by the command 
             hostname. If a remote machine it must allow remote execution
             from this machine (see man pages for rlogin, rsh).

  nslave     The total number of copies of this process to be executing
             on the specified machine. Only 'clusters' of identical processes
             specified in this fashion can use shared memory to communicate.
             If no shared memory is supported on machine <hostname> then
             only the value one (1) is valid (e.g. on the Cray).

  executable Full path name on the host <hostname> of the image to execute.
             If <hostname> is the local machine then a local path will
             suffice.

  workdir    Full path name on the host <hostname> of the directory to
             work in. Processes execute a chdir() to this directory before
             returning from pbegin(). If specified as a '.' then remote
             processes will use the login directory on that machine and local
             processes (relative to where parallel was invoked) will use
             the current directory of parallel.

  e.g.

  harrison boys      3  /home/harrison/c/ipc/testf.x  /tmp      # my sun 4
  harrison dirac     3  /home/harrison/c/ipc/testf.x  /tmp      # ron's sun4
  harrison eyring    8  /usr5/harrison/c/ipc/testf.x  /scratch  # alliant fx/8

 The above PROCGRP file would put processes 0-2 on boys (executing
testf.x in /tmp), 3-5 on dirac (executing testf.x in /tmp) and 6-13 on
eyring (executing testf.x in /scratch). Processes on each machine use
shared memory to communicate with each other, sockets otherwise.

e) Note that the number of processes and where they are executed is the
   same no matter where the command parallel is invoked, as long as the
   PROCGRP file is the same.

f) If programs are correctly set up they will function as expected when
   invoked with parallel no matter how processes are specified in the
   PROCGRP.
   N.B. Point c) above is an exception to this.

g) The makep command can be used to build a procgroup file on a simple
   network ... try 'tcgmsg/makep -help' for usage and have a look at the
   top of tcgmsg/makep for more detail.


Executing processes on the IPSC
-------------------------------

I have not encountered a single program that once running in the UNIX
environment has failed to run correctly first time on the iPSC-i860
(other than the usual C/FORTRAN porting issues).  The converse is not
likely to be true due to availability of asynchronous comms on the
iPSC (not in the UNIX stuff yet).  if you have problems I would be
interested to hear of them.

The command parallel is somewhat more functional than under
UNIX.  The format of the PROCGRP file is different (of
necessity). The format of each line of the PROCGRP is (again white
space separated fields with '#' indicating comment to EOL).

     <lo>  <hi>  <image>  <workdir>

     lo-hi = range of nodes to be loaded with this image
             two special cases are recognized ...
             $ = highest numbered node
             $-1 (no spaces!) = highest but one node

     image = path to executable
             one special case is recognized ... 
             if image is the string nextvalueservice (no spaces!) then
             the nxtval server is loaded from the appropriate place.
             This must always be on the highest node.

     workdir = directory that the process cd's into before commencing

     e.g.

        0 0    master.x     /cfs/rjh
        1 $-1  slave.x      /cfs/rjh
        $ $    last_slave.x /cfs/rjh

The parallel command takes the following format

     parallel [-w] [-t cubetype] [-C cubename] [procgrp]

By default parallel assumes that U have already gotten a cube and
will not release it when it finishes (so you can hog resources).

     -t cubetype = get a cube of the specified type and release it 
                   when finished. If such a cube is not available parallel
                   aborts with an error

     -w = if getting a cube wait for the cube to become available if
          it is not now (prints a message every minute)

     -C cubename = attach to or get the named cube

     procgrp = append .p to get the path name for the procgrp file
               in this directory or in $HOME/pdir. If this is not
               specified it looks for either the translation of the
               environment variable PROCGRP or the file PROCGRP in the
               current directory

    e.g. 
 
        parallel bigjob

           run the processes described in bigjob.p on the cube
           defaultname which is already allocated with getcube.

        parallel -t 32 -C N2CI selci

           get a 32 node cube with name N2CI and process description
           file selci.p

The following should be noted (for both the IPSC and DELTA):

  1) Various trivial functions (e.g. STATS_) are not implemented
     and just return benignly.  LLOG_() has the nasty habit of core
     dumping when 32 or more cpus call it (IPSC only) ... I think this
     is not my bug but the fileserver on the cubemanager running out
     of file descriptors.  [Have not checked this bug out for a while
     so it may be OK now?]

  2) The WAITCOM(NODE) call always acts as if NODE=-1 which has the
     effect of waiting for all outstanding I/O requests to complete.
     If this is a major problem for someone I might fix it.

  3) NXTVAL is implemnted using an hrecv() interrupt handler running
     on the highest numbered node.  Thus use of the IPSC routine
     masktrap() can interfere with the functioning of NXTVAL().

  4) The synchronous communication (SYNCH=1) is asynchronous for
     short messages (100 bytes on the IPSC, system load dependent for
     the DELTA).


Running on the Touchstone Delta
-------------------------------

  The command parallel does not exist as it is not possible to write
code for the service node.  Programs should be compiled and linked
as usual and subsequently executed with the mexec command. Also,
the immediately preceeding list of points apply to both the
IPSC and the Delta.


Miscellaneous and Bugs
----------------------

If a program crashes on machines with the system V shared memory and
semaphores some of these resources may not be deallocated.  If these
are not tidied up the system can run out. The shell script ipcreset
(by Jim Patterson?) removes ALL such resources currently allocated by
a user. Removing the resources for a running process will cause it to
crash the next time it tries to access it. Try man on ipcs, ipcrm for
more details. On a Sequent ipcs, ipcrm are found in '/usr/att/bin', and
on the Encore in '/etc'.

Many machines have the number of sockets etc. either statically
configured in the kernel, or capped by some number. While debugging a
program that keeps crashing sockets may be left open. Most systems
tidy these unused sockets up every few minutes (?). However when the
system runs out of these resources it will wreak havoc with all
networking and windowing operations and possibly crash the system
(e.g. Ardent Titan, 2.2).

The script zapit (bsd and sysv versions, courtesy of JP again)  kills
all processes whose command contains a given string.  This is useful
if a crash or deadlock occurs which leaves junk processes lying around
(rsh is prone to run away on some machines).

To run large number of processes you may have to patch the kernel to
increase the limits on numbers of semaphores and open file
descriptors, or the amount of shared memory.  For shells that support
it STOP/CONT signals (as generated by ^Z and bg/fg in the csh) should
work OK.  Interrupts (SIGINT) are trapped and should cause everything
to tidy up and die (with a few error messages). To kill a program the
best way is just to use ^C on the parallel program or to send it an
interrupt with kill -2 (usually).

Porting to new UNIX machines
----------------------------
    
     1) Make the makefiles etc. for the known machine closest to 
        yours, or failing that the SUN (probably the most reliable).

        make machdep MACHINE=SUN

     2) Now go into the ipcv4.0 directory and run lint on everything
        to see what it complains about (probably a lot)

        cd ipcv4.0
        make lint

     3) If it looks as if shared memory and semaphores are not
        available, disable the compilation flags -DSHMEM -DSYSV.
        If XDR seems to be missing remove -DGOTXDR.  The stuff in
        the eventlogging is sometimes especially problematic so you
        can also remove that (-DEVENTLOG). Run lint again and now
        fix everything (other than a few pointer alignment problems)
        that it complains about.  Put any changes in appropriate ifdef
        blocks.

     4) If your machine has proprietary shared memory/semaphores
        and sockets aren't fast enough for you, then you must 
        provide the interfaces described in sema.c and shmem.c.
        Then recompile with -DSHMEM and the new machine flag.

     5) To get FORTRAN working you must

        1) Determine global symbol that FORTRAN uses to store
           the command line arguments.  Take an existing FORTRAN
           executable (a.out) and

           nm -g a.out | grep -i arg

           Some of the listed symbols will probably be the desired
           argc and argv ... modify farg.h accordingly.

        2) Determine how FORTRAN passes character variables, either
           by reading manuals or by experiment.

           If it passes the pointer to the string as the argument
           and appends the argument list with the VALUE of the length
           then don't do anything.  Otherwise modify the source in
           evon.c, globalop.c and pfilecopy.c to reflect the correct
           mechanism.