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

\section{Running a Kernel}\label{running}

This section describes the procedure for running a user\_level
simulator {\xk}.  A user\_level {\xk} runs in Unix user space, and
usually uses a Unix socket interface (or other OS-specific interfaces,
such as ETHPKT) to send and receive messages on the network.  A simulator
{\xk} also runs in user space, but doesn't use the network hardware at
all; instead, it simulates traffic between hosts on a configurable
network in virtual time.

\input userlevel
\input simulator

\subsection{Running Test Suites}\label{test_suites}

Most protocols distributed with the {\xk} come with a test protocol in
the {\var protocols/test} directory.  These protocols typically send
a number of round trips for messages of various sizes and report the
total time for the test.  The most common test protocols are
configured into the protocol library, but some may have to be copied
and compiled directly in a user's build area.  Test protocols compiled
into the protocol graph start up automatically with the rest of the
protocols.

The behavior of test protocols can be modified by various command-line
and ROM file options.  See the man page for the TEST protocol in
Appendix~\ref{prot_specs}.

\subsection{Troubleshooting}\label{troubleshooting}

Many of the problems encountered when running an {\xk} turn out to be
configuration problems.  Setting the debugging variable 
{\var traceprotocol} to {\var TR\_EVENTS} or higher can be very helpful in
identifying problems.  A few common symptoms and some things you might
want to check if these symptoms occur are:

\begin{itemize}

\item{}
The {\xk} aborts before the first protocol's init routine is called.

Your {\xk} may have been configured without a protocol table.  Make
sure your {\var graph.comp} or ROM files mention at least one protocol
table and that the specified protocol table exists and is readable.

\item{}
The {\xk} hangs in arp\_init.

ARP's initialization routine will not return until it has discovered
the binding for its local IP address.  If the {\xk} hangs in 
{\var arp\_init}, ARP is probably sending out RARP requests which are not
being answered.  Multiple warning messages of the form:

\begin{quote}
\begin{var}
ARP: Could not get my IP address for interface eth (still trying)
\end{var}
\end{quote}

\noindent
are an indicator of this problem.

If you are running the {\var sunos} simulator, you must have an ARP
binding in your ROM file for your local host (see
Section~\ref{user_level}).  On other platforms, an ARP binding for the
local host is not necessary if another host on your network will
respond to RARP broadcasts.  If you do not have such a host (or if it
is not responding for whatever reason), adding a local binding to your
ROM file should fix the problem.

\item{}
Messages sent out on one host are never received on the destination host.

Check your ROM file.  If it contains an initial binding for the
destination host which is incorrect, the destination host will not see
packets from the sending host.

\item{}
An {\var xOpen} hangs for a while and then fails.

An open may fail if ARP cannot resolve the IP address of the
destination (turning ARP tracing on can help identify this problem).
ARP requests should never be sent on the {\var sunos} simulator
platform.  If you are running on the {\var sunos} platform and you see
ARP requests being sent, check the ROM file on the sending host and
make sure there is an ARP binding for the destination host.

\item{}
The {\xk} aborts before a specific protocol's init routine is called.

If the {\xk} cannot find a protocol number for your protocol in any of
its tables, it will abort before calling that protocol's
initialization routine.  You will need to add an entry for your
protocol in one of the tables (see Section~\ref{protocol_tables}).

\item{}
Messages get to the destination host but never make it up to the
appropriate protocol.

Make sure that the source and destination hosts are running with
identical protocol table entries for the protocol in question.  If the
numbers are different, messages won't get to the appropriate protocol
on the destination host.

\end{itemize}