Update manual to include swapglobals.
authorChao Huang <chuang10@uiuc.edu>
Fri, 23 Jan 2004 03:23:36 +0000 (03:23 +0000)
committerChao Huang <chuang10@uiuc.edu>
Fri, 23 Jan 2004 03:23:36 +0000 (03:23 +0000)
doc/ampi/manual.tex

index 3e296b14840526a805cb52f39f386da0d2632ec7..07f299c6a57c33f4c3f6e01ffec168846f6b9031 100644 (file)
@@ -151,6 +151,37 @@ track of computation loads of each thread as well as communication graph
 between \ampi{} threads, and can migrate these threads in order to balance the
 overall load while simultaneously minimizing communication overhead. 
 
+\subsection{AMPI Status}
+
+Currently all the MPI-1.1 Standard functions are supported in \ampi{}, with a
+collection of our extentions explained in detail in this manual.
+
+\begin{alltt}
+MPI_Migrate    MPI_Checkpoint  MPI_Restart     MPI_Register    MPI_Get_userda  '
+MPI_Ialltoall  MPI_Iallgather  MPI_Iallreduce  MPI_Ireduce
+\end{alltt}
+
+Following MPI-1.1 basic datatypes are supported in \ampi{}. (Some are not available in
+Fortran binding. Refer to MPI-1.1 Standard for details.)
+\begin{alltt}
+MPI_DATATYPE_NULL  MPI_BYTE            MPI_UNSIGNED_LONG MPI_LONG_DOUBLE_INT
+MPI_DOUBLE         MPI_PACKED          MPI_LONG_DOUBLE   MPI_2FLOAT
+MPI_INT            MPI_SHORT           MPI_FLOAT_INT     MPI_2DOUBLE
+MPI_FLOAT          MPI_LONG            MPI_DOUBLE_INT    MPI_LB
+MPI_COMPLEX        MPI_UNSIGNED_CHAR   MPI_LONG_INT      MPI_UB
+MPI_LOGICAL        MPI_UNSIGNED_SHORT  MPI_2INT
+MPI_CHAR           MPI_UNSIGNED        MPI_SHORT_INT
+\end{alltt}
+
+Following MPI-1.1 reduction operations are supported in \ampi{}.
+
+\begin{alltt}
+MPI_MAX   MPI_MIN   MPI_SUM   MPI_PROD  MPI_MAXLOC  MPI_MINLOC
+MPI_LAND  MPI_LOR   MPI_LXOR  MPI_BAND  MPI_BOR     MPI_BXOR
+\end{alltt}
+
+\subsection{From MPI to AMPI}
+
 For dynamic load balancing to be effective, one needs to map multiple
 user-level threads onto a processor. Traditional MPI programs assume that the
 entire processor is allocated to themselves, and that only one thread of
@@ -189,8 +220,19 @@ category. If such a program is executed without privatization on \ampi{}, all
 the \ampi{} threads that reside on one processor will access the same copy of
 such variables, which is clearly not the desired semantics.  To ensure correct
 execution of the original source program, it is necessary to make such
-variables ``private'' to individual threads.  
-
+variables ``private'' to individual threads. We are two choices: automatic 
+global swapping and manual code modification.
+
+\subsubsection{Automatic Globals Swapping}
+Thanks to the ELF Object Format, we have successfully automated the procedure 
+of switching the set of user global variables when switching thread contexts. 
+The only thing that the user needs to do is to set flag {\tt -swapglobals} 
+at compile and link time. Of course this feature is available on platforms where Position
+Independent Code(PIC) is supported. When this feature does not work for you,
+you are advised to make the modification manually, which is detailed in the
+following section.
+
+\subsubsection{Manual Change}
 We have employed a strategy of argument passing to do this privatization
 transformation. That is, the global variables are bunched together in a
 single user-defined type, which is allocated by each thread dynamically. Then a
@@ -257,8 +299,9 @@ void subA()\{
 
 \ampi{} executes the main program inside a user-level thread as a subroutine.
 For this purpose, the main program needs to be changed to be a subroutine with
-the name \verb+MPI_Main+.
-
+the name \verb+MPI_Main+. In C version we have quitely done this by a {\tt \#define}
+macro, but in Fortran code you will have to do it manually.
 Now we transform this program using the argument passing strategy. We first group the
 shared data into a user-defined type.
 
@@ -341,86 +384,6 @@ For large shared data, it would be better to do heap allocation because in
 command line) and stacks do not grow dynamically.
 
 
-\subsection{AMPI Status}
-
-Currently the following subset of MPI-1.1 standard is supported in \ampi{}.
-
-\begin{alltt}
-=============================================================================================
-Point-to-point     Collective         Groups, Contexts          Processor
-                                      and Communicators         Topology
-=============================================================================================
-MPI_Send           MPI_Barrier        MPI_Group_size            MPI_Cart_create
-MPI_Recv           MPI_Bcast          MPI_Group_rank            MPI_Dims_create
-MPI_Get_count      MPI_Gather         MPI_Group_translate_ranks MPI_Graph_create
-MPI_Bsend          MPI_Gatherv        MPI_Group_compare         MPI_Topo_test
-MPI_Rsend          MPI_Scatter        MPI_Comm_group            MPI_Cartdim_get
-MPI_Ssend          MPI_Scatterv       MPI_Group_union           MPI_Cart_get
-MPI_Buffer_attach  MPI_Allgather      MPI_Group_intersection    MPI_Cart_rank
-MPI_Buffer_detach  MPI_Allgatherv     MPI_Group_difference      MPI_Cart_coords
-MPI_Isend          MPI_Alltoall       MPI_Group_incl            MPI_Cart_shift
-MPI_Ibsend         MPI_Alltoallv      MPI_Group_excl            MPI_Cart_sub
-MPI_Issend         MPI_Reduce         MPI_Group_range_incl      MPI_Cart_map
-MPI_Irecv          MPI_Allreduce      MPI_Group_range_excl      MPI_Graphdims_get
-MPI_Wait           MPI_Reduce_scatter MPI_Group_free            MPI_Graph_get
-MPI_Waitany                           MPI_Comm_create           MPI_Graph_neighbors_count
-MPI_Waitall                           MPI_Comm_size             MPI_Graph_neighbors
-MPI_Waitsome                          MPI_Comm_rank             MPI_Graph_map
-MPI_Test                              MPI_Comm_dup
-MPI_Testall                           MPI_Comm_split
-MPI_Testsome                          MPI_Comm_free
-MPI_Request_free
-MPI_Cancel
-MPI_Iprobe
-MPI_Probe
-MPI_Send_init
-MPI_Bsend_init
-MPI_Ssend_init
-MPI_Rsend_init
-MPI_Recv_init                        ========================================================
-MPI_Start                             Environment               AMPI Extensions*
-MPI_Startall                          Management
-MPI_Sendrecv                         ========================================================
-MPI_Sendrecv_replace                  MPI_Error_string          MPI_Migrate
-MPI_Type_contiguous                   MPI_Wtime                 MPI_Checkpoint
-MPI_Type_vector                       MPI_Wtick                 MPI_Restart
-MPI_Type_hvector                      MPI_Init                  MPI_Register
-MPI_Type_indexed                      MPI_Initialized           MPI_Get_userda
-MPI_Type_hindexed                     MPI_Finalize              MPI_Ialltoall
-MPI_Type_struct                       MPI_Abort                 MPI_Iallgather
-MPI_Type_commit                                                 MPI_Iallreduce
-MPI_Type_free                                                   MPI_Ireduce
-MPI_Type_extent
-MPI_Type_size
-MPI_Type_lb
-MPI_Type_ub
-MPI_Address
-MPI_Get_elements
-MPI_Pack
-MPI_Unpack
-MPI_Pack_size
-=============================================================================================
-* AMPI extensions are explained later in this manual.
-\end{alltt}
-
-Following MPI-1.1 basic datatypes are supported in \ampi{}. (Some are not available in
-Fortran binding. Refer to MPI-1.1 Standard for details.)
-\begin{alltt}
-MPI_DATATYPE_NULL  MPI_BYTE            MPI_UNSIGNED_LONG MPI_LONG_DOUBLE_INT
-MPI_DOUBLE         MPI_PACKED          MPI_LONG_DOUBLE   MPI_2FLOAT
-MPI_INT            MPI_SHORT           MPI_FLOAT_INT     MPI_2DOUBLE
-MPI_FLOAT          MPI_LONG            MPI_DOUBLE_INT    MPI_LB
-MPI_COMPLEX        MPI_UNSIGNED_CHAR   MPI_LONG_INT      MPI_UB
-MPI_LOGICAL        MPI_UNSIGNED_SHORT  MPI_2INT
-MPI_CHAR           MPI_UNSIGNED        MPI_SHORT_INT
-\end{alltt}
-
-Following MPI-1.1 reduction operations are supported in \ampi{}.
-
-\begin{alltt}
-MPI_MAX   MPI_MIN   MPI_SUM   MPI_PROD  MPI_MAXLOC  MPI_MINLOC
-MPI_LAND  MPI_LOR   MPI_LXOR  MPI_BAND  MPI_BOR     MPI_BXOR
-\end{alltt}
 
 \subsection{Extensions for Migrations}
 
@@ -738,7 +701,7 @@ codes.  For this purpose, we have extended the \ampi{} functionality to allow
 multiple ``\texttt{COMM\_WORLD}s''; one for each application. These \emph{world
 communicators} form a ``communicator universe'': an array of communicators
 aptly called \emph{MPI\_COMM\_UNIVERSE}. This array of communicators in
-indexed $1\cdots\texttt{MPI\_MAX\_COMM}$. In the current implementation,
+indexed [1 . . . \texttt{MPI\_MAX\_COMM}]. In the current implementation,
 \texttt{MPI\_MAX\_COMM} is 8, that is, maximum of 8 applications can co-exist
 within the same executable.
 
@@ -856,8 +819,7 @@ mapped to processors will be in proportion to their processing power.
 
 \end{description}
 
-If you want to define your own mapping scheme, please contact us and we will be
-happy to help you with it.
+If you want to define your own mapping scheme, please contact us for help.
 
 \subsection{Compiling AMPI Programs}