readme

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

$Header: /home/harrison/c/tcgmsg/ipcv4.0/RCS/README,v 1.1 91/12/06 17:25:35 harrison Exp Locker: harrison $

TCGMSG Send/receive subroutines ... version 4.03 (January 1993)
---------------------------------------------------------------

Robert J. Harrison

Mail Stop K1-90                             tel: [phone]
Battelle Pacific Northwest Laboratory       fax: [phone]
P.O. Box 999, Richland WA 99352          E-mail: [e-mail]

The programming model and interface is directly modelled after the
PARMACS of the ANL ACRF (see "Portable Programs for Parallel
Processors", J. Boyle, R. Butler, T. Disz, B. Glickfeld, E. Lusk, R.
Overbeek, J. Patterson, R. Stevens. Holt, Rinehart and Winston, Inc.,
1987, ISBN 0-03-014404-3).  Attention is drawn to the P4 parallel
programming system (contact Ewing Lusk, [e-mail]) which
is the successor to PARMACS.

In the UNIX environment communication is over TCP sockets, unless
indentical processes are running on a machine with support for shared
memory, which is then used. Thus applications can be built to run over
an entire network of machines with local communication running at
memory bandwidth (plus synchronization overhead) and remote
communication running at Ethernet speed (close to the maximum of 10
Mbits/s can be seen on quiet networks).  On true message-passing
machines TCGMSG is just a thin layer over the system interface.

A configuration file specifies the placement of processes over the
network. The message passing program is then invoked with the command
'parallel' which reads the configuration file and invokes the required
processes using fork() or rsh. This has the benefits of the placement
of processes being identical no matter from where on the network the
command is given, and the 'spare' process running the command parallel
is used to provide load balancing service in a straightfoward fashion.

Hooks are in the lower level routines for conversion of data between
machines with different byte ordering/numerical representation. This
is currently only implemented for FORTRAN integer and double precision
(C long and double) data types and C character data.

Examples
--------

Associated with this source is a directory ('examples'!) of sample
programs, including dynamic load balancing.  See the README file in
that directory for more details.  It is interesting that in only one
of the examples was it necessary to resort to explict message passing,
and only then for efficiency.  The functionality of DGOP and BRDCST
sufficed for the other examples, which display respectable speedup.

The Model
---------

Strong typing is enforced.  The type associated with a message when
sent must match the type specified on the corresponding receive.
No wildcard types are permitted.

Processes are connected with ordered, synchronous channels.  On
machines that explicitly support it (currently the iPSC and DELTA)
explicitly asynchronous communication is supported.  Otherwise it
should be thought that:

  a) sends block until the message is explicitly received

  b) messages from a particular process can only be received
     in the order sent.

As far as buffering provided by the transport layer permits, messages
are actually sent without any synchronization between the sender and
receiver.  However, since the amount of buffering varies greatly from
one mechanism to another you cannot explicitly use this fact.  On the
iPSC and also on the Alliant MPP over HIPPI (and perhaps on the KSR
over shared memory ... I have yet to check this) you can also receive
messages from a given process in any order (provided that they do not
exhaust the system buffering).  But if you want portability don't
exploit this feature.

This fuzzy specification permits significant reduction of latency
without requiring essentially unbounded buffers.

Programming
-----------

Both the C and FORTRAN interfaces are now consistent and fully
portable.  Just compile and link following the library usage in the 
example makefiles. 

The following restrictions are important.

NB: Use of FORTRAN character variables in argument lists except where
    indicated below is NOT supported as some implementations pass them
    using two arguments, or as a pointer to a structure.

NB: All user detected errors requiring termination MUST result
    in a call to PARERR (see testf.f for an example). From 'C'
    call Error(char *message, long info).

NB: The value of message types must be in the range 1-32767.
    Set bits higher than this are used (amoungst other things) to
    indicate that data translation is requested (see point 3 below).

NB: On the KSR see the README.KSR file.

1) On entry the first things all processes must do is 

   FORTRAN:    CALL PBEGINF or CALL PBGINF

   C:          #include "sndrcv.h"

	       int main() 
               {
                 PBEGIN_(argc, argv);

   This connects all the processes together and initializes the
   environment.

2) Immediately before exit all processes must call pend as follows.

   FORTRAN:    CALL PEND

   C:          PEND_();

   This tidies up any shared resources and notifies the load balancing
   server that it has completed. PEND does return but only to allow you
   to exit normally.  It is important that the FORTRAN runtime
   environment be allowed to tidy up after itself.  Calling PBEGIN or
   PEND more than once per process is bound to produce some bizarre sort
   of screw up.

3) Data translation when communicating between machines with different
   data representations or byte ordering is enabled by OR-ing your
   message type with the appropriate choice of:

   MSGDBL - for double precision floating point data
   MSGINT - for FORTRAN integer (C long) data
   MSGCHR - for byte packed character data (C char) ... note above
            comments on use of character variables in FORTRAN

   These are defined in the include files:

   msgtypesf.h - for FORTRAN
   msgtypesc.h - for C

   Obviously all the data in the message must be of the same type.
   It should be simple to add extra types if required.

   e.g. to send a double precision array X with translation if necessary
   simply code the matching calls

   CALL SND(TYPE+MSGDBL, X, LENX, NODE, SYNC)
   --------
   CALL RCV(TYPE+MSGDBL, X, LENX, LEN, NODESEL, NODEFROM, SYNC)

   where the positive integer TYPE must be <= 32767.

4) Between the calls to PBEGINF and PEND any of the following may be
   used.

   a)  INTEGER FUNCTION NNODES()

       long NNODES_()

       Returns no. of processes

   b)  INTEGER FUNCTION NODEID()

       long NODEID_()

       Returns logical node no. of the current process 
       (0,1,...,NNODES()-1)

   c)  SUBROUTINE LLOG()

       void LLOG_()

       Opens separate logfiles in the current directory for each
       process. The files are named log.<NODEID()>.

   d)  SUBROUTINE STATS()

       void STATS_()

       Print out summary of communication statistics for calling
       process.

   e)  INTEGER FUNCTION MTIME()

       long MTIME_()

       Return wall time from an arbitrary origin in centi-seconds

   f)  DOUBLE PRECISION FUNCITON TCGTIME()

       double TCGTIME_()

       Return wall time from an arbitrary origin in seconds as accurately
       as possible

   g)  SUBROUTINE SND(TYPE, BUF, LENBUF, NODE, SYNC)
       INTEGER TYPE       [input]
       BYTE BUF(LENBUF)   [input]
       INTEGER LENBUF     [input]
       INTEGER NODE       [input]
       INTEGER SYNC       [input]

       void SND_(long *type, char *buf, long *lenbuf, long *node, 
                 long *sync)

       Send a message of type TYPE to node NODE. LENBUF is the length
       of the message in bytes. BUF may be any type other than a
       FORTRAN CHARACTER variable or constant.  SYNC indicates
       synchronous (1) or asynchronous (0) communication.  If
       aynchronous communication is requested the buffer may not be
       modified until WAITCOM is called. This avoids having to waste
       valuable local memory taking a copy of the message.  If a bit
       is set in the TYPE matching MSGDBL, MSGINT or MSGCHR then XDR
       is used if communication is over sockets.
       !
       ! Requests for asynchronous communication on UNIX machines
       ! where it is not supported are quietly ignored.
       !

   h)  SUBROUTINE RCV(TYPE, BUF, LENBUF, LENMES, NODESEL, NODEFROM, SYNC)
       INTEGER TYPE       [input]
       BYTE BUF(LENBUF)   [output]
       INTEGER LENBUF     [input]
       INTEGER LENMES     [output]
       INTEGER NODESEL    [input]
       INTEGER NODEFROM   [output]
       INTEGER SYNC       [input]

       void RCV_(long *type, char *buf, long *lenbuf, long *lenmes,
                 long *nodesel, long *nodefrom, long *sync)

       Receive a message of type TYPE from node NODESEL. LENBUF is the
       length of the receiving buffer in bytes. LENMES returns the length
       of the message received. An error results if the buffer is not
       large enough. NODEFROM returns the node from which the message was
       received. If the NODESEL is specified as -1 then the next node to
       send to this process is chosen. The selection of the 'next' process
       is guaranteed to be fair.  The length of the buffer is checked
       and the type of the message must agree with that being received
       (there is only one channel between processes so messages are
       received in the order sent). BUF may be of any type other than
       CHARACTER. SYNC indicates synchronous (1) or asynchronous (0) 
       communication.
       If a bit is set in the TYPE matching MSGDBL, MSGINT or MSGCHR then
       XDR is used if communication is over sockets.
       !
       ! Requests for asynchronous communication on UNIX machines
       ! where it is not supported are quietly ignored.
       !

   i)  SUBROUTINE BRDCST(TYPE, BUF, LENBUF, IFROM)
       INTEGER TYPE       [input]
       BYTE BUF(LENBUF)   [input/output]
       INTEGER LENBUF     [input]
       INTEGER IFROM      [input]

       void BRDCST_(long *type, char *buf, long *lenbuf, long *ifrom)

       Broadcast from process IFROM to all other processes a message
       of type TYPE and length LENBUF. All processes call this routine
       which uses an optimized algorithm to distribute the data in