Reorganized directory structure
authorRobert Brunner <rbrunner@uiuc.edu>
Tue, 30 May 1995 18:53:53 +0000 (18:53 +0000)
committerRobert Brunner <rbrunner@uiuc.edu>
Tue, 30 May 1995 18:53:53 +0000 (18:53 +0000)
NOTES/NOTE.CHANGELOG [new file with mode: 0755]
NOTES/NOTE.KNOWNBUGS [new file with mode: 0755]
NOTES/NOTE.PORTING [new file with mode: 0755]
SUPER_INSTALL [new file with mode: 0755]

diff --git a/NOTES/NOTE.CHANGELOG b/NOTES/NOTE.CHANGELOG
new file mode 100755 (executable)
index 0000000..75368bb
--- /dev/null
@@ -0,0 +1,115 @@
+Note: charm libraries (eg, reduction library) not currently dealt with
+in makefiles.  Need to be included.
+
+Note: Created new directory structure for converse.  Very similar to
+old structure for charm, but greatly simplified.  See new
+SUPER_INSTALL script for description.
+
+Note: Disentangled the CMI and the CSD.  Now the LocalQueue is
+a part of the Cmi, not part of the scheduler.  Also, the machine layer
+isn't shoving stuff into the main sheduler queue anymore.
+
+Note: each version must include the following files: machine.c, machine.h,
+spantree.c, and converse.mk.  Converse.mk must define the symbols CMK_CC,
+CMK_CXX, etc (see net-sol version for complete list), and must include
+make-rules for cmk_extras and cmk_clean.
+
+Note: changed name of charmhost to "conv-host", for lack of a better name.
+
+Note: tested linkage of NET-SOL version of converse, no unresolved
+externals.  Similarly with charm.
+
+Note: all "unported" source moved into a separate directory.  This includes
+most of the queueing strategies and most of the versions.  I am currenly
+trying to get just one version and just one queueing strategy working,
+and I'll do the others later.
+
+Note: all references to Mc or Ck removed from net-* version of
+converse.  Charm also updated, although Ck not removed from charm.
+
+Note: Memory allocator moved into machine.c, as CmiAlloc, CmiSize,
+and CmiFree.  Currently, this has only been done for network version.
+It is currently a trivial implementation based on malloc and free.
+CmiAlloc now never returns zero.  (We can add a variant function that
+returns zero, if desired).  Not sure how this interacts with Charm yet,
+and in particular, TotalMsgSize.  (I dumbly replaced TotalMsgSize with
+CmiSize, but who knows what that will do).
+
+Note: Argument parsing has been simplified.  CmiInit, CmiInitMc,
+CsdInit, and ConverseInit each takes a single argument (argv), and
+each removes a subset of the arguments from that vector.  pparam is
+gone entirely.  Charm will need to be updated.
+
+Note: machine.c no longer exports CmiGetMsg.  Instead, it
+exports CmiGetNonLocal (a function) and CmiLocalQueue (a FIFO queue).
+
+Note: machine.c no longer exports CmiInit.  Instead, it
+exports CmiInitMc.
+
+Warning: ConverseInit must not do anything critical, since user may
+not call ConverseInit.  (In fact, must be moved to separate file to
+avoid having the linker drag everything in).  Distribute functionality
+of ConverseInit among CsdInit, CmiInit, etc.
+
+Note: FIFO queues are currently part of converse (eg, FIFO_enqueue, etc).
+
+Error: converse.h file should contain declarations for all functions
+defined in converse.c, it does not.
+
+Error: comm-handle semantics definitely not implemented correctly.
+
+Error: CmiGrabBuffer definitely not correct.
+
+Error: qs.newfifo.c, qs.ififo.c, etc, refer to "ENVELOPE"
+
+Note: Changed the typedef "CommHandle" to CmiCommHandle.
+
+Note: Modifying the queueing strategy modules in the following manner:
+    1. Renamed all QS modules so each has a different name.
+    2. For some strategies, collapsed the .c and the .h file together.
+       Not done with all strategies.
+
+Question: Didn't we decide to change the interface of the QS module
+to CqsEnqueueFifo(msg, prioptr, priolen) or something like that?  If
+we postpone this alteration, changes will be harder later.
+
+-------------------------------------------------------------------------------
+The following stuff cut from network version "machine.h", don't know
+what it does or is supposed to do:
+
+#define _CK_VARSIZE_UNIT 8
+
+typedef char            BYTE;
+typedef unsigned char   BOOLEAN;
+
+#define ALL_NODES           (-1)
+#define ALL_NODES_EXCEPT_ME (-2)
+
+#define PROCESS_PID 1
+
+#define MAXUSERARGS  20  /* these are used to pass comm line args not used */
+
+# define SCANFBUFFER   8192
+# define PRINTFBUFFER  8192
+# define SCANFMSGLENGTH        1024
+# define SCANFNVAR     16
+# define MAX_PRINTFORMATS 128
+# define STATIC
+# define WORDSIZE      sizeof(int)
+
+/* Types of lowest-level messages. */
+# define CMI_TYPE              1       /* Chare Kernel message. */
+#define McSyncReceive(msgsize,msg) (netRecv(msgsize,msg,CMI_TYPE))
+
+#define McAllAsyncMsgsSent() TRUE
+
+#define McReleaseSentMessages()
+
+extern int _MC_InsideMachine ;
+
+#define CkAsyncSend(destPE, size, env)   {\
+       CmiAsyncSend(destPE, size, env); \
+       CkFree(env); }
+
+-------------------------------------------------------------------------------
diff --git a/NOTES/NOTE.KNOWNBUGS b/NOTES/NOTE.KNOWNBUGS
new file mode 100755 (executable)
index 0000000..fb979ae
--- /dev/null
@@ -0,0 +1,27 @@
+Question: shouldn't CmiGetMsg block?  It doesn't.
+
+Warning: ConverseInit must not do anything critical, since user may
+not call ConverseInit.  (In fact, must be moved to separate file to
+avoid having the linker drag everything in).  Distribute functionality
+of ConverseInit among CsdInit, CmiInit, etc.
+
+Error: converse.h file should contain declarations for all functions
+defined in converse.c, it does not.
+
+Error: comm-handle semantics definitely not implemented correctly.
+
+Error: CmiGrabBuffer definitely not correct.
+
+Error: qs.newfifo.c, qs.ififo.c, etc, refer to "ENVELOPE"
+
+Question: Didn't we decide to change the interface of the QS module
+to CqsEnqueueFifo(msg, prioptr, priolen) or something like that?  If
+we postpone this alteration, changes will be harder later.
+
+Memory stuff currently not being dealt with.
+
+CHARM is NOT using CsdScheduler.  It's using its own version of the loop,
+with periodic and timer checks added.  Charm will therefore fail if
+somebody tries to use something other than the default-main.
+
+
diff --git a/NOTES/NOTE.PORTING b/NOTES/NOTE.PORTING
new file mode 100755 (executable)
index 0000000..70f693e
--- /dev/null
@@ -0,0 +1,104 @@
+-------------------------------------------------------------------------------
+How to convert an old version of converse into a new version of converse:
+
+   1. Convert machine.mk into conv-mach.mk.
+   2. Create a conv-mach.h for the version.
+   3. Reduce the machine layer to machine.c, spantree.c, and the header-files.
+   4. Deal with the contents of machine.h
+   5. Edit machine.c to fix the identifier names (change Mc to Cmi, etc).
+   6. Change CmiInit --> CmiInitMc in the machine layer.
+   7. Change CmiGetMsg --> CmiGetNonLocal in the machine layer.
+   8. Add CmiLocalQueue to the machine layer.
+   9. Add CmiAlloc, CmiSize, CmiFree to machine layer.
+  10. Make sure machine.c only exports functions that start with "Cmi".
+
+Details on this process described below.
+-------------------------------------------------------------------------------
+1. Converting machine.mk into conv-mach.mk.  This is easy.  Basically, I
+just changed the names of the variables so that they all start with CMK_.
+See the net-linux version for an example.
+-------------------------------------------------------------------------------
+2. Converting an old machine.h to a new conv-mach.h.  Copy the conv-mach.h
+from the net-linux version, then change the flag-settings.  Each conv-mach.h
+is basically a long list of flags.  For example, the net-linux version
+contains this snippet:
+
+        /* #define CMK_CMIMYPE_IS_A_BUILTIN */
+           #define CMK_CMIMYPE_IS_A_VARIABLE
+        
+           #define CMK_CMIPRINTF_IS_A_BUILTIN
+        /* #define CMK_CMIPRINTF_IS_JUST_PRINTF */
+
+Indicating that in the net-linux version, CmiMyPe was implementeda as
+a variable (Cmi_mype), and that CmiPrintf was implemented as a
+function.  These flags enable converse.h to produce the correct macro
+definitions and prototypes for CmiMyPe and CmiPrintf.  You must create
+a similar flags-list for your machine version.  The easiest way to do
+this is to edit the net-linux version.
+-------------------------------------------------------------------------------
+3. Reduce the machine layer to machine.c, spantree.c, and the
+header-files.  Just do this by concatenating all the C files into
+machine.c.  This simplifies the makefiles dramatically.
+-------------------------------------------------------------------------------
+4. Deal with the old machine.h.  My first observation is this: the
+vast majority of the stuff in machine.h is not used at all, anywhere.
+If it's not used, just ignore it.  The second observation is that the
+majority of the rest of it is only used inside the machine layer
+itself.  Such code can be cut an pasted into the machine layer
+(machine.c, or a header file of your own invention included by
+machine.c).  There is one other kind of thing in machine.h, namely,
+Definitions of exported Cmi functions like "#define CmiMyPe() _MC_mypenum".
+Usually, these are already accounted for in converse.h.  For example,
+converse.h already contains:
+
+             #ifdef CMK_CMIMYPE_IS_A_VARIABLE
+                extern int Cmi_mype;
+                extern int Cmi_numpe;
+                #define CmiMyPe() Cmi_mype
+                #define CmiNumPe() Cmi_numpe
+             #endif
+
+Therefore, the easiest way to handle the macro definition
+"#define CmiMyPe() _MC_mypenum" is to convert _MC_mypenum to
+Cmi_mype throughout the machine layer, and to set the flag
+CMK_CMIMYPE_IS_A_VARIABLE.
+
+Eventually, you may run into a macro which is not easily made to
+conform to the possibilities laid out by the flags-list.  In this
+case, you must add a new flag to the flags-list, and add a section
+to converse.h.
+-------------------------------------------------------------------------------
+5. Edit machine.c to fix the identifier names (change Mc to Cmi, etc).
+This is straightforward.
+-------------------------------------------------------------------------------
+6. Change CmiInit --> CmiInitMc in the machine layer.  machine.c no
+longer contains CmiInit, instead, it contains CmiInitMc.  The prototype
+for CmiInitMc is "void CmiInitMc(void **argv)".  It should initialize the
+machine-specific part of the Cmi layer.  If it uses any arguments from
+argv, it should remove them from argv.
+-------------------------------------------------------------------------------
+7. Change CmiGetMsg --> CmiGetNonLocal in the machine layer.  machine.c
+no longer contains CmiGetMsg.  Instead, it contains CmiGetNonLocal, which
+retrieves a message from the network.  (NOT from the CMI fifo queue).
+Most machine layers already worked this way anyway, so it's just a question
+of changing the function name.
+-------------------------------------------------------------------------------
+8. Add CmiLocalQueue to the machine layer.  This is the machine layer's
+FIFO queue.  This must be declared as void* CmiLocalQueue, and must
+be created inside CmiInitMc using CmiLocalQueue=FIFO_Create().  It can
+then be used by machine-functions to enqueue messages-to-self.  In fact,
+look for places in the machine layer where messages-to-self get enqueued
+on the scheduler queue, and make sure they get enqueued on the CmiLocalQueue
+instead.
+-------------------------------------------------------------------------------
+9. Add CmiAlloc, CmiSize, CmiFree to machine layer.  This is a bit hazy
+in my mind.  Basically, CmiAlloc allocates memory, CmiSize returns the
+size of a block you previously allocated, and CmiFree frees a block you
+allocated with CmiAlloc.  It should work to cut the definitions
+from the Common.net source code.  However, we need to think about how
+to do this for real.
+-------------------------------------------------------------------------------
+10. Make sure machine.c only exports functions that start with "Cmi".
+Take your "static" in hand, and distribute liberally.  In places where
+you can't add a "static", change the function name to CmiSomething.
+-------------------------------------------------------------------------------
diff --git a/SUPER_INSTALL b/SUPER_INSTALL
new file mode 100755 (executable)
index 0000000..4f5d601
--- /dev/null
@@ -0,0 +1,143 @@
+#!/bin/csh -f
+#
+# The syntax of this script is:
+#
+#    SUPER-INSTALL program version <operation>
+#
+# Where program is: converse, charm, charm++
+# Where version is: net-sun, net-sol, cm5, paragon, etc...
+# Where operation can be: gather make install all (defaults to all)
+#
+# Some versions of charm are interrelated.  For example, net-sun, net-sol,
+# and net-hp all belong to a group of versions called the "net" group.
+# Likewise, uni-sun, uni-sol, and uni-hp belong to a group of versions
+# called the "uni" group.  The group name can always be found by truncating
+# the version name before the dash.
+#
+# Converse contains the following directories:
+#
+#    src/Common         - contains source common to all versions
+#    src/Common.$GROUP  - contains source common to a group of versions
+#    src/$VERSION       - contains source for a specific version
+#
+#    $VERSION/tmp       - used to build the specified version
+#    $VERSION/lib       - used to hold object files once compiled.
+#    $VERSION/bin       - used to hold binary files once compiled.
+#    $VERSION/make      - used to hold make-include files
+#    $VERSION/include   - used to hold include files
+#
+# To compile a version of Converse, SUPER_INSTALL performs the following
+# actions:
+#
+#    * Create directory $VERSION and its subdirectories.
+#
+#    * Copy all source files from src/Common          to $VERSION/tmp
+#    * Copy all source files from src/Common.$GROUP   to $VERSION/tmp
+#    * Copy all source files from src/$VERSION        to $VERSION/tmp
+#
+#    * Perform "make $PROGRAM" in $VERSION/tmp
+#
+#    * Copy the results to $VERSION/bin, $VERSION/lib, $VERSION/include.
+#
+#    * Rebuild central "bin" directory.
+#
+# That's all SUPER_INSTALL does.  The rest is handled by the Makefile.
+# 
+# Note: As SUPER_INSTALL copies files from the src directories to the
+# tmp directory, two of the files that happen to get copied are Makefile
+# and converse.mk.  Makefile comes from src/Common, and converse.mk comes
+# from src/$VERSION.  Together, these form the makefile that gets used in
+# the "make all".  The contents of converse.mk is fully specified: it
+# must define exactly the following symbols:
+#
+#   <put symbols here>
+#
+# It must also contain rules for making cmk_extras, cmk_clean, and
+# cmk_install.  Those three rules can be used to compile and install
+# any machine-specific utilities (eg, a host program or something like
+# that).  converse.mk must not define anything else (the intention is
+# that the converse-user, eg charm, can include converse.mk in his own
+# makefiles as well).
+#
+
+set PROGRAM=$1
+set VERSION=$2
+set OPERATION=$3
+
+if ( x$OPERATION == x ) set OPERATION=all
+
+if ( x$VERSION == x ) goto syntax
+if { ( echo $2 | egrep -s '^Common' ) } goto syntax
+if ( ! -d src/$VERSION ) goto syntax
+goto install
+
+syntax:
+
+    echo ''
+    echo 'Usage: SUPER-INSTALL program version'
+    echo ''
+    echo 'Where program can be: converse charm charm++'
+    echo 'Where the available versions are: '
+    echo ''
+    (cd src ; ls -1 | egrep -v '^Common')
+    echo ''
+    exit
+
+install:
+
+    #Compute what GROUP of versions we are using:
+    set GROUP=Common.`echo $VERSION | sed -e 's@-.*@@'`
+
+    if (( $OPERATION == gather ) || ( $OPERATION == all )) then
+       echo "Creating directories for $VERSION..."
+       if (! -d $VERSION        ) mkdir $VERSION
+       if (! -d $VERSION/bin    ) mkdir $VERSION/bin
+       if (! -d $VERSION/lib    ) mkdir $VERSION/lib
+       if (! -d $VERSION/include) mkdir $VERSION/include
+       if (! -d $VERSION/tmp    ) mkdir $VERSION/tmp
+       cd $VERSION/tmp
+       echo "Copying all files in src/Common to $VERSION/tmp..."
+       find ../../src/Common -type f \! -name "*,v" -exec ln -s {} . \;
+       if (-d ../../src/$GROUP) then
+          echo "Copying all files in src/$GROUP to $VERSION/tmp..."
+          find ../../src/$GROUP -type f \! -name "*,v" -exec ln -s {} . \;
+       endif
+       echo "Copying all files in src/$VERSION to $VERSION/tmp..."
+       find ../../src/$VERSION -type f \! -name "*,v" -exec ln -s {} . \;
+       cd ../..
+    endif
+
+    if (( $OPERATION == make ) || ( $OPERATION == all )) then
+       cd $VERSION/tmp
+       echo "Performing 'make $PROGRAM' in $VERSION/tmp"
+       make $PROGRAM
+       cd ../..
+    endif
+
+    if (( $OPERATION == install ) || ( $OPERATION == all )) then
+      echo "Copying libconv-*.a from $VERSION/tmp to $VERSION/lib"
+      find $VERSION/tmp -type f -name "libconv-*.a" -exec cp {} $VERSION/lib \;
+      echo "Copying libck?-*.a  from $VERSION/tmp to $VERSION/lib"
+      find $VERSION/tmp -type f -name "libck?-*.a"  -exec cp {} $VERSION/lib \;
+      echo "Copying *.h         from $VERSION/tmp to $VERSION/include"
+      find $VERSION/tmp -name "*.h"       -exec cp {} $VERSION/include \;
+      echo "Copying conv-*.mk   from $VERSION/tmp to $VERSION/include"
+      find $VERSION/tmp -name "conv-*.mk" -exec cp {} $VERSION/include \;
+      echo "Copying conv-*.sh   from $VERSION/tmp to $VERSION/include"
+      find $VERSION/tmp -name "conv-*.sh" -exec cp {} $VERSION/include \;
+      echo "Copying conv-*.csh  from $VERSION/tmp to $VERSION/include"
+      find $VERSION/tmp -name "conv-*.csh" -exec cp {} $VERSION/include \;
+      echo "Copying conv*       from $VERSION/tmp to $VERSION/bin"
+      find $VERSION/tmp -type f -name "conv*" -perm -500 -exec cp {} $VERSION/bin \;
+      echo "Copying charm*      from $VERSION/tmp to $VERSION/bin"
+      find $VERSION/tmp -type f -name "charm*" -perm -500 -exec cp {} $VERSION/bin \;
+      echo "Copying charmc      from $VERSION/tmp to $VERSION/bin"
+      cp $VERSION/tmp/charmc $VERSION/bin/charmc
+
+      echo "Relinking central bin directory."
+      rm -f bin 
+      ln -s $VERSION/bin bin
+    endif
+
+    exit
+