Commit 2139f3b1 authored by Jonathan Jenkins's avatar Jonathan Jenkins
Browse files

formatting and naming consistency

parent 020731dc
...@@ -149,6 +149,11 @@ xleftmargin=6ex ...@@ -149,6 +149,11 @@ xleftmargin=6ex
% correct bad hyphenation here % correct bad hyphenation here
\hyphenation{op-tical net-works semi-conduc-tor} \hyphenation{op-tical net-works semi-conduc-tor}
\newcommand{\codesmapping}[1]{\texttt{codes\_mapping}}
\newcommand{\codesconfig}[1]{\texttt{codes\_config}}
\newcommand{\codesmodelnet}[1]{\texttt{model\_net}}
\begin{document} \begin{document}
\title{CODES Best Practices} \title{CODES Best Practices}
...@@ -527,21 +532,21 @@ struct svr_msg ...@@ -527,21 +532,21 @@ struct svr_msg
In this program, CODES is used in the following four ways: to provide In this program, CODES is used in the following four ways: to provide
configuration utilities for the program, to logically separate and provide configuration utilities for the program, to logically separate and provide
lookup functionality for multiple LP types, to automate LP placement on KPs/PEs, lookup functionality for multiple LP types, to automate LP placement on KPs/PEs,
and to simplify/modularize the underlying network structure. The CODES and to simplify/modularize the underlying network structure. The \codesconfig{}
Configurator is used for the first use-case, the CODES Mapping API is used for API is used for the first use-case, the \codesmapping{} API is used for
the second and third use-cases, and the CODES Model-Net API is used for the the second and third use-cases, and the \codesmodelnet{} API is used for the
fourth use-case. The following sections discuss these while covering necessary fourth use-case. The following sections discuss these while covering necessary
ROSS-specific information. ROSS-specific information.
\subsection{CODES Configurator} \subsection{\codesconfig{}}
Listing~\ref{snippet2} shows a stripped version of example.conf (see the file Listing~\ref{snippet2} shows a stripped version of example.conf (see the file
for comments). The configuration format allows categories, and optionally for comments). The configuration format allows categories, and optionally
subgroups within the category, of key-value pairs for configuration. The LPGROUPS subgroups within the category, of key-value pairs for configuration. The LPGROUPS
listing defines the LP configuration and (described in listing defines the LP configuration and (described in
Section~\ref{subsec:codes_mapping}). The PARAMS category is used by both Section~\ref{subsec:codes_mapping}). The PARAMS category is used by both
CODES Mapping and Model-Net for configuration, providing both ROSS-specific and \codesmapping{} and \codesmodelnet{} for configuration, providing both ROSS-specific and
network specific parameters. For instance, the message\_size field defines the network specific parameters. For instance, the \texttt{message\_size} field defines the
maximum event size used in ROSS for memory management. Of course, user-defined maximum event size used in ROSS for memory management. Of course, user-defined
categories can be used as well, which are used in this case to define the rounds categories can be used as well, which are used in this case to define the rounds
of communication and the size of each message. of communication and the size of each message.
...@@ -574,34 +579,35 @@ server_pings ...@@ -574,34 +579,35 @@ server_pings
\end{figure} \end{figure}
\subsection{CODES Mapping} \subsection{\codesmapping{}}
\label{subsec:codes_mapping} \label{subsec:codes_mapping}
The CODES mapping API transparently maps LP types to MPI ranks (Aka ROSS PE's). The \codesmapping{} API transparently maps LP types to MPI ranks (Aka ROSS PE's).
The LP type and count can be specified through the CODES Configurator. In this The LP type and count can be specified through \codesconfig{}. In this
section, we focus on the CODES Mapping API as well as configuration. Refer again section, we focus on the \codesmapping{} API as well as configuration. Refer again
to Listing~\ref{snippet2}. Multiple LP types are specified in a single LP group to Listing~\ref{snippet2}. Multiple LP types are specified in a single LP group
(there can also be multiple LP groups in a config file). (there can also be multiple LP groups in a config file).
In Listing~\ref{snippet2}, there is 1 server LP and 1 modelnet\_simplenet LP In Listing~\ref{snippet2}, there is 1 server LP and 1
type in a group and this combination is repeated 16 time (repetitions="16"). \texttt{modelnet\_simplenet} LP type in a group and this combination is repeated
ROSS will assign the LPs to the PEs (PEs is an abstraction for MPI rank in ROSS) 16 time (repetitions="16"). ROSS will assign the LPs to the PEs (PEs is an
by placing 1 server LP then 1 modelnet\_simplenet LP a total of 16 times. This abstraction for MPI rank in ROSS) by placing 1 server LP then 1
configuration is useful if there is heavy communication involved between the \texttt{modelnet\_simplenet} LP a total of 16 times. This configuration is
server and modelnet\_simplenet LP types, in which case ROSS will place them on useful if there is heavy communication involved between the server and
the same PE so that the communication between server and modelnet\_simplenet LPs \texttt{modelnet\_simplenet} LP types, in which case ROSS will place them on the
will not involve remote messages. same PE so that the communication between server and
\texttt{modelnet\_simplenet} LPs will not involve remote messages.
An important consideration when defining the configuration file is the way An important consideration when defining the configuration file is the way
Model-Net maps the network-layer LPs (the NICs in this example) and the upper \codesmodelnet{} maps the network-layer LPs (the NICs in this example) and the upper
level LPs (e.g., the servers). Specifically, each NIC is mapped in a one-to-one level LPs (e.g., the servers). Specifically, each NIC is mapped in a one-to-one
manner with the calling LP through the calling LP's group name, repetition manner with the calling LP through the calling LP's group name, repetition
number, and number within the repetition. number, and number within the repetition.
After the initialization function calls of ROSS (tw\_init), the configuration After the initialization function calls of ROSS (\texttt{tw\_init}), the configuration
file can be loaded in the example program using the calls in Figure file can be loaded in the example program using the calls in Figure
\ref{snippet3}. Each LP type must register itself using \'lp\_type\_register\' \ref{snippet3}. Each LP type must register itself using \texttt{lp\_type\_register}
before setting up the codes-mapping. Figure \ref{snippet4} shows an example of how before setting up the mapping. Figure \ref{snippet4} shows an example of how
the server LP registers itself. the server LP registers itself.
\begin{figure} \begin{figure}
...@@ -641,11 +647,11 @@ static void svr_add_lp_type() ...@@ -641,11 +647,11 @@ static void svr_add_lp_type()
\end{lstlisting} \end{lstlisting}
\end{figure} \end{figure}
The CODES Mapping API provides ways to query information like number of LPs of The \codesmapping{} API provides ways to query information like number of LPs of
a particular LP types, group to which a LP type belongs, repetitions in the a particular LP types, group to which a LP type belongs, repetitions in the
group (For details see codes-base/codes/codes-mapping.h file). Figure group (For details see codes-base/codes/codes-mapping.h file). Figure
\ref{snippet3} shows how to setup CODES mapping API with our CODES example and \ref{snippet3} shows how to setup the \codesmapping{} API with our CODES example
computes basic information by querying the number of servers in a particular and computes basic information by querying the number of servers in a particular
group. group.
\subsection{Event Handlers} \subsection{Event Handlers}
...@@ -688,26 +694,26 @@ static void svr_event(svr_state * ns, tw_bf * b, svr_msg * m, tw_lp * lp) ...@@ -688,26 +694,26 @@ static void svr_event(svr_state * ns, tw_bf * b, svr_msg * m, tw_lp * lp)
\end{lstlisting} \end{lstlisting}
\end{figure} \end{figure}
\subsection{Model-Net API} \subsection{\codesmodelnet{}}
Model-Net is an abstraction layer that allow models to send messages \codesmodelnet{} is an abstraction layer that allow models to send messages
across components using different network transports. This is a across components using different network transports. This is a
consistent API that can send messages across either torus, dragonfly, or consistent API that can send messages across either torus, dragonfly, or
simplenet network models without changing the higher level model code. simplenet network models without changing the higher level model code.
In the CODES example, we use simple-net as the underlying plug-in for In the CODES example, we use \emph{simple-net} as the underlying plug-in for
Model-Net. The simple-net parameters are specified by the user in the config \codesmodelnet{}. The simple-net parameters are specified by the user in the config
file (See Figure \ref{snippet2}). A call to `model\_net\_set\_params' sets up file (See Figure \ref{snippet2}). A call to \texttt{model\_net\_set\_params} sets up
the model\-net parameters as given in the config file. the model\-net parameters as given in the config file.
Model-Net assumes that the caller already knows what LP it wants to deliver the \codesmodelnet{} assumes that the caller already knows what LP it wants to
message to and how large the simulated message is. It carries two types of deliver the message to and how large the simulated message is. It carries two
events (1) a remote event to be delivered to a higher level model LP (In the types of events (1) a remote event to be delivered to a higher level model LP
example, the Model-Net LPs carry the remote event to the server LPs) and (2) a (In the example, the \codesmodelnet{} LPs carry the remote event to the server LPs) and
local event to be delivered to the caller once the message has been transmitted (2) a local event to be delivered to the caller once the message has been
from the node (In the example, a local completion message is delivered to the transmitted from the node (In the example, a local completion message is
server LP once the Model-Net LP sends the message). Figure \ref{snippet6} shows delivered to the server LP once the Model-Net LP sends the message). Figure
how the server LP sends messages to the neighboring server using the model\-net \ref{snippet6} shows how the server LP sends messages to the neighboring server
LP. using the model\-net LP.
\begin{figure} \begin{figure}
\begin{lstlisting}[caption=Example code snippet showing data transfer through model-net API, label=snippet6] \begin{lstlisting}[caption=Example code snippet showing data transfer through model-net API, label=snippet6]
...@@ -749,30 +755,30 @@ simulation is not computationally intense. ...@@ -749,30 +755,30 @@ simulation is not computationally intense.
For our example program, recall the ``forward'' event handlers. They perform the For our example program, recall the ``forward'' event handlers. They perform the
following: following:
\begin{description} \begin{enumerate}
\item [Kickoff] send a message to the peer server, and increment sender LP's \item Kickoff: send a message to the peer server, and increment sender LP's
count of sent messages. count of sent messages.
\item [Request (received from peer server)] increment receiver count of \item Request (received from peer server): increment receiver count of
received messages, and send an acknowledgement to the sender. received messages, and send an acknowledgement to the sender.
\item [Acknowledgement (received from message receiver)] send the next \item Acknowledgement (received from message receiver): send the next
message to the receiver and increment messages sent count. Set a flag message to the receiver and increment messages sent count. Set a flag
indicating whether a message has been sent. indicating whether a message has been sent.
\item [Local model-net callback] increment the local model-net \item Local \codesmodelnet{} callback: increment the local model-net
received messages count. received messages count.
\end{description} \end{enumerate}
In terms of LP state, the four operations are simply modifying counts. Hence, In terms of LP state, the four operations are simply modifying counts. Hence,
the ``reverse'' event handlers need to merely roll back those changes: the ``reverse'' event handlers need to merely roll back those changes:
\begin{description} \begin{enumerate}
\item [Kickoff] decrement sender LP's count of sent messages. \item Kickoff: decrement sender LP's count of sent messages.
\item [Request (received from peer server)] decrement receiver count of \item Request (received from peer server): decrement receiver count of
received messages. received messages.
\item [Acknowledgement (received from message receiver)] decrement messages \item Acknowledgement (received from message receiver): decrement messages
sent count if flag indicating a message has been sent has not been sent count if flag indicating a message has been sent has not been
set. set.
\item [Local model-net callback] decrement the local model-net \item Local \codesmodelnet{} callback: decrement the local model-net
received messages count. received messages count.
\end{description} \end{enumerate}
For more complex LP states (such as maintaining queues), reverse event For more complex LP states (such as maintaining queues), reverse event
processing becomes similarly more complex. Other sections of this document processing becomes similarly more complex. Other sections of this document
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment