%
% x-kernel v3.3
%
% Copyright (c) 1996,1993,1991,1990  Arizona Board of Regents
%

\section{Overview}

{\xS} is a network simulator based on the {\xk}. It provides a
framework for developing, analyzing, and testing network protocols;
for evaluating congestion control mechanisms; and for studying network
dynamics. This document is intended to be used as a reference to {\xs}
by those already familiar with the {\xk}.

{\xS} includes all of the modules necessary to simulate a large and
arbitrarily complex internetwork.  An internet composed of Ethernets
and point-to-point links, FCFS and RED routers, and hosts with arbitrary
protocol graphs can be specified.  In addition, the user may write
code to implement other types of networks and routers for inclusion in
a simulation.

{\xS} is tightly integrated with the {\xk} architecture; it runs {\xk}
protocols and protocols can be moved between the simulator and the
{\xk} without any changes. {\xS} Version 1.0 adheres to Version 3.3 of
the {\xk} interface \cite{ProgMan_3.3}. Despite the close relationship
between {\xs} and the {\xk}, there are two important differences
between the standard {\xk} and the simulator of which the user should
be aware.  We discuss these differences here.

First, the {\xk} allows the hosts on which it runs to communicate with
each other, either through direct network access (i.e., directly
accessing the network device), or by emulating a low-level network
connection via sockets.  In contrast, the simulator does not use the
network at all.  Instead, it simulates communications between
potentially thousands of hosts over an internetwork specified by the
user.  A special protocol called SIM is included at the bottom of all
host protocol stacks; host driver protocols pass messages to SIM, and
SIM implements the networks and routers that make up this internet.

Figures~\ref{userlvl} and \ref{simgraph} show the protocol graphs of a
user-level {\xk} and an instance of {\xs}, respectively.
Figure~\ref{userlvl} shows two hosts, each running a user-level {\xk}
with its own protocol stack, connected by an Ethernet.  Protocol
SIMETH on each host uses the Unix socket interface to send messages
across the network.\footnote{We call this device protocol SIMETH for
historical reasons. SIMETH has nothing to do with SIM; the former
simulates an ethernet using sockets, and the latter simulates an
entire internet on a single machine.} In contrast,
Figure~\ref{simgraph} shows a protocol graph representing four
simulated hosts connected by an internetwork.  Protocol SIM contains
code that implements the entire internetwork to which the hosts are
attached.  Note that in {\xs}, each simulated host is implemented by
its own protocol stack; this leads to multiple instantiations of
protocol objects, and a large protocol graph.

Second, in a user-level {\xk}, the protocol graph is static and it is
specified at compile time in the {\var graph.comp} file. In contrast,
the simulator has been enhanced so that the protocol graph is created
at runtime, allowing different simulations to be run without
recompiling.  The {\var graph.comp} file is still used by {\xs}, but
only as a means of specifying which protocol modules to include in the
executable.  In other words, if any simulated host is going to be
running protocol $P$, then protocol $P$ must appear somewhere in {\var
graph.comp}.  The relationships between protocols specified in {\var
graph.comp} are ignored by the simulator.

At runtime, {\xs} reads a configuration file, called {\var xsim.data},
or any other file that can be specified by the {\var -simfile} option,
which specifies the network topology: the number and types of networks;
the number of hosts and routers; how the networks, hosts and routers
are connected; the protocol graph for each host; and various other
parameters such as the addresses of each host and network, the speed
and delay of each point-to-point link and network, whether Ethernet
networks should simulate collisions, and so on.

\begin{figure}[ht]
\centering
\leavevmode\hbox{\epsfig{file=userlvl.eps,height=2.0in}}
\caption{A user-level {\xk} protocol graph}\label{userlvl}
\end{figure}
 
\begin{figure}[ht]
\centering
\leavevmode\hbox{\epsfig{file=sim.eps,height=2.0in}}
\caption{An {\xs} protocol graph}\label{simgraph}
\end{figure}
 
In summary, building the protocol graph for a simulation involves two
stages: including the necessary protocol modules in the simulator
executable (via {\var graph.comp}), and specifying at runtime the
protocol graphs for the individual simulated hosts (via {\var
xsim.data}).  To illustrate this point, here is the {\var graph.comp}
file for the simulator instance shown in Figure~\ref{simgraph}:

\begin{verbatim}
    @;

    name=sim;
    name=ethd;
    name=eth;
    name=arp;
    name=vnet;
    name=ip;
    name=ttcp;
    name=rtcp;
    name=btcp;
    name=vtcp;
    name=megtest;
    name=traffic;

    @;

    prottbl=prottbl.default;
    prottbl=prottbl.xsim;
\end{verbatim}

\noindent
Notice that nowhere are multiple hosts mentioned in this {\var
graph.comp} file, and no explicit protocol relationships are given.
(You can give them if you want, but they have no effect.)  Also note
that we included multiple TCP protocols (i.e., TTCP, BTCP, VTCP), not
all of which are involved in the simulation illustrated in
Figure~\ref{simgraph}.  If later we want to replace RTCP in our simulation
with another TCP, or have different TCP protocols running on different
hosts, we can do so without recompiling because we've already included
these protocols in the simulator.

Following the standard {\xk} build procedures defined in the {\xk}
Programmer's Manual \cite{ProgMan_3.3}, the above {\var graph.comp}
file produces an {\xs} executable in the build directory.
Section~\ref{example} shows the {\var xsim.data} file that is read at
runtime by this executable, resulting in the protocol graph shown in
Figure~\ref{simgraph}.

Finally, we reiterate that only minimal modifications to the {\xk}
were necessary so it could be used as the {\xs} infrastructure.  No
modifications were made to the {\xk} interface, thereby making it
possible to move protocols between the simulator and the standard
{\xk} without modification.

The next section provides an example configuration file for a simple
internetwork and explains its components; Figure~\ref{simgraph} shows
the protocol graph produced by this file.  Section~\ref{spec} then
documents all aspects of the {\var xsim.data} file in detail.
Section~\ref{more_examples} includes a more complex example {\var
xsim.data} file.  Finally, running a complex simulation is only half
the battle. Often, analyzing the results takes much longer than
running the simulation itself. A set of graphical display tools are included
with {\xs} to aid in analyzing the behavior of different parts of the
simulator.  These tools display graphs based on traces saved by
protocols and routers, and have proven invaluable in helping to
understand complex protocols. The final section of this documents
briefly describes these display tools.