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

\documentstyle[times,fcanon,html]{article}

\begin{document}

\bibliographystyle{abbrv}
\newcommand{\xk}{{\it x}-kernel}
\newcommand{\var}{\sf}
\begin{htmlonly}
   %these overwrite the above definitions when running latex2html
   \newcommand{\var}{\tt}
\end{htmlonly}

\title{Getting Started with the {\xk}}
\author{Larry L. Peterson}
\date{June 1997}
\maketitle{}

\renewcommand{\baselinestretch}{1}
\setlength{\tolerance}{1000}
\small\normalsize

\noindent
This note describes the procedures that should be followed to install,
configure, build, and run the {\xk} as a user-level Unix process.  It
purposely focuses on a vanilla system. To understand all the options
available to you, consult the {\xk} Programmer's Manual
\cite{ProgMan_3.3}.  We assume the following throughout the rest of
this note.

\begin{itemize}
\item You will be installing the {\xk} in directory {\var /usr/xkernel}, 
and  this directory is reachable (via NSF, for example) from all machines
on which you want to run the {\xk}. You may choose some root directory
other than {\var /usr/xkernel}. If you do select another root directory,
change the steps given below accordingly.

\item You will be running the {\xk} on a pair of Solaris (Sparc) 
workstations connected by an Ethernet. We will refer to these two
machines as machine $A$ and machine $B$ in the following discussion.
If you are building the {\xk} on SunOS (on Sparc), IRIX (on SGI), or
OSF/1 (on Alpha)---then substitute {\var sunos}, {\var irix}, or {\var
osf1} for {\var solaris}, respectively, in the steps that follow. If
you are running the {\xk} on Linux (on Alpha or x86), then substitute
{\var linux-alpha} or {\var linux-x86}, respectively, for {\var
solaris}.\footnote{The SunOS and Irix versions of the {\xk} are
included in the distribution, but they are no longer supported.}

\end{itemize}

\section*{Ten Step Process}

\begin{enumerate}

\item Create directory {\var /usr/xkernel} and copy the compressed tar
file from {\var ftp://ftp.cs.arizona.edu/xkernel/xkernel.tar.Z} into
this directory. Then type:

\begin{quote}
{\var cd /usr/xkernel}\\
{\var uncompress xkernel.tar.Z}\\
{\var tar xf xkernel.tar}
\end{quote}
This will create several subdirectories in {\var /usr/xkernel}.  A
description of the {\xk} directory hierarchy can be found in 
{\var /usr/xkernel/README}. Note that you can skip this step if the 
{\xk}has already been installed at your site.

\item Create a directory in which you will build an instance of the
{\xk}. This is called your build directory, and in general, each
different configuration of the {\xk} has its own build directory.
\begin{quote}
{\var cd /usr/xkernel/user\_level/build}\\ 
{\var mkdir solaris}
\end{quote}
If directory {\var /usr/xkernel/user\_level/build/solaris} already
exists---because someone else has already followed this
procedure---then you have two choices.

\begin{enumerate}
\item Select another name for your build directory (e.g.,
{\var mydir}) and create a directory with this name in directory 
{\var /usr/xkernel/user\_level/build}. The catch to this option is that 
you have to either have write permission in directory 
{\var /usr/xkernel/user\_level/build}, or you have to have someone that 
has write permission create your build directory for you.

\item Create a build directory in your own home directory; e.g., 
{\var /usr/llp/xk\_build/solaris}. This is the preferred approach if a 
lot of different people are going to be building the {\xk}.
\end{enumerate}

\noindent
Substitute the name of your build directory, as appropriate, in the
rest of the steps.

\item Copy configuration files into your build directory.
\begin{quote}
{\var cd /usr/xkernel/user\_level/build/solaris}\\
{\var cp ../Template/Makefile.solaris Makefile}\\
{\var cp ../Template/graph.comp .}\\
{\var mkdir client server}\\
{\var cp ../Template/rom.client client/rom}\\
{\var cp ../Template/rom.server server/rom}\\
{\var chmod 664 Makefile graph.comp client/rom server/rom}
\end{quote}
Note that if your build directory is not in {\var
/usr/xkernel/user\_level/build}, then you will have to use the full
path names for these various files (e.g., 
{\var /usr/xkernel/user\_level/build/Template/graph.comp}) rather than the
relative path names (e.g., {\var ../Template/graph.comp}) given above.

\item Edit the {\var ``XRT =''} line of the {\var Makefile} you just 
copied into your build directory to reflect the root of your {\xk}
source tree.  Assuming your tree is at {\var /usr/xkernel}, this means
changing
\begin{quote}
{\var XRT = ../../..}
\end{quote}
to
\begin{quote}
{\var XRT = /usr/xkernel}
\end{quote}
Note that this step is necessary only if your build directory is
underneath your home directory. It is not necessary if your build
directory is in {\var /usr/xkernel/user\_level/build} since from there,
{\var ../../..} already points to the root of the {\xk} source tree.

\item Edit the last line of the {\var graph.comp} file you just copied
into your build directory to reflect the root of your {\xk} tree. Assuming
your tree is at {\var /usr/kernel}, this means changing
\begin{quote}
{\var prottbl=/cs/x33/etc/prottbl.std;}
\end{quote}
to
\begin{quote}
{\var prottbl=/usr/xkernel/etc/prottbl.std;}
\end{quote}

\item Edit the two {\var rom} files you just copied to reflect
the addresses of the two machines on which you will be running the
{\xk}. This will involve editing the {\var Real IP address} field of
the two lines that begin with {\var arp}. Specifically, edit 
{\var client/rom} by changing 192.12.69.186 in the first {\var arp} 
line to the IP address of machine $A$, and by changing 192.12.69.35 in 
the second {\var arp} line to the IP address of machine $B$. Edit 
{\var server/rom} in exactly the same way.

\medskip
Note that $A$ and $B$ can be the same machine, in this case, the same
IP address is used in the {\var rom} file for both machines.

\item Put {\var /usr/xkernel/bin/solaris-sparc} and 
{\var /usr/xkernel/bin} in your search path. They should appear before
{\var /bin} and {\var /usr/bin} in order to pick up GNU {\var make}
before the standard Unix {\var make}. If you are building the {\xk} on
a platform other than Solaris, then substitute {\var sunos-sparc},
{\var osf1-alpha}, {\var irix-mips}, {\var linux-alpha}, or {\var linux-x86} 
for  {\var solaris-sparc}, as appropriate. Also, make sure the GNU C compiler
{\var (gcc)} is in your search path. (At Arizona, {\var gcc} can be
found in directory {\var /usr/local/bin}.)

\item Build libraries necessary for your {\xk}. This could take quite
a while.
\begin{quote}
{\var cd /usr/xkernel/user\_level/build/solaris}\\
{\var make system}
\end{quote}
Note that you can skip this step if you are not the first person to
build an {\xk} for this platform.

\item You are now ready to build the {\xk}.
\begin{quote}
{\var cd /usr/xkernel/user\_level/build/solaris}\\
{\var make compose}\\
{\var make depend}\\
{\var make}
\end{quote}
This sequence should result in the creation of the binary file 
{\var xkernel} in your build directory. Note that you may see what appear 
to be error messages about missing files (e.g., {\var Makefile.local} and
{\var DEPS/Makedep.*}) when you run {\var make compose}.  These
warnings can be ignored.

\item You are now ready to run the {\xk}. This will involve
being logged onto both machines $A$ and $B$. This is easiest to do by
using a window-based interface and opening a separate terminal (shell)
window on both $A$ and $B$. First, on machine $A$ type:
\begin{quote}
{\var cd /usr/xkernel/user\_level/build/solaris/server}\\
{\var ../xkernel -s}
\end{quote}
This starts a version of the {\xk} on machine $A$ that will act as
a server for this run. Second, on machine $B$ type:
\begin{quote}
{\var cd /usr/xkernel/user\_level/build/solaris/client}\\
{\var ../xkernel -c128.1.2.3}
\end{quote}
This starts a version of the {\xk} on machine $B$ that will act as a
client for this run. Note that you have to start the server before
the client. When the run is over, you can kill the {\xk} by typing 
{\var Control-C} on both $A$ and $B$.

\medskip
The run involves the client establishing a TCP connection to the
server, with a sequence of different-sized messages then sent back and
forth between the client and the server. The time it takes to exchange
100 messages of each size between the client and the server will be
printed out. For example, the output on the client will consist of a
sequence of lines that look something like this:
\begin{verbatim}
Protocol: TCP
Time: Fri Jun  6 16:16:11 1997
Host: cicada.CS.Arizona.EDU
Participant: client
Round Trips: 100 

Message Length (bytes): 1
Times (sec):
select: Interrupted system call
     0.061818
     0.060986
     0.063218
\end{verbatim}
This means it took 0.061818 seconds (or 61ms) to send 100, 1-byte
messages between the client and server machines, for an average of
.61ms per round-trip.

\end{enumerate}

\section*{Troubleshooting}

Many of the problems encountered when running an {\xk} turn out to be
configuration problems. The following are three of the most common
symptoms, and some things you might try if these symptoms occur.

\begin{itemize}

\item{}
The {\xk} aborts with the message
\begin{quote}
{\var could not open protocol table file prottbl}\\
{\var ...}
\end{quote}
Make sure you edited the last line of {\var graph.comp} correctly in
step 5, and that {\var /usr/xkernel/etc/prottbl.std} exists and is
readable.

\item{}
The {\xk} hangs (doesn't abort) and repeatedly prints out the message
\begin{quote}
{\var ARP: Could not get my ip address for interface eth (still trying)}
\end{quote}
Make sure you edited the two {\var rom} files correctly in step 6, and
that you started the server on machine $A$ and the client on machine
$B$ in step 10.

\item{}
Both the client and server initialize, but then seem to hang. You
will know that the server has successfully initialized when it prints
the message
\begin{quote}
{\var tcp timing test}\\
{\var I am the server}
\end{quote}
and that the client has successfully initialized when it prints
the message
\begin{quote}
{\var tcp timing test}\\
{\var I am the client}\\
{\var Sending (1) ...}\\
{\var msg lengh: 1}
\end{quote}
Make sure you edited the two {\var rom} files correctly in step 6.

\end{itemize}

\section*{Other Things to Try}

Now that you are able to build a vanilla system, you can start
experimenting with different optional configurations. The following
gives a list of things you might try. Consult the Programmer's Manual
for more information on each item.

\begin{itemize}

\item Edit {\var graph.comp} in your build directory by adding the
string
\begin{quote}
{\var trace=TR\_MAJOR\_EVENTS}
\end{quote}
to the end of each of the following four lines
\begin{quote}
{\var name=eth protocols=simeth;}\\
{\var name=arp protocols=eth;}\\
{\var name=ip protocols=vnet;}\\
{\var name=tcp protocols=ip;}
\end{quote}
For example, the first line would become
\begin{quote}
{\var name=eth protocols=simeth trace=TR\_MAJOR\_EVENTS;}
\end{quote}
Similarly with the other lines. Once this edit is done, repeat steps 9
and 10 from above. This change will increase the amount of tracing
information that is output when the {\xk} runs. This output will now
include events from TCP, IP, ARP, and the Ethernet driver (ETH). To
see an even greater level of trace detail, change {\var
TR\_MAJOR\_EVENTS} to {\var TR\_FUNCTIONAL\_TRACE} in each of the
above lines, and repeat steps 8 and 9 again.

\item Edit the {\var Makefile} in your build directory by commenting
out the line
\begin{quote}
{\var HOWTOCOMPILE = DEBUG}
\end{quote}
and un-commenting the line
\begin{quote}
{\var \#HOWTOCOMPILE = OPTIMIZE}
\end{quote}
Then repeat steps 9 and 10 from above. (You will also need to repeat
step 8 if this is the first time the {\xk} has been built in
{\var OPTIMIZE} mode on this platform.) This will build an optimized version
of the {\xk} that does not include the trace statements that generated
much of the output you saw before. Typically, you want to run the
{\xk} in OPTIMIZED mode when you care about the performance
measurements it generates.

\item Edit {\var graph.comp} to include a different set of protocols.
For example, instead of configuring TCP into your kernel, you could
configure in UDP. This is done by replacing the lines
\begin{quote}
{\var name=tcp protocols=ip;}\\
{\var name=tcptest protocols=tcp;}
\end{quote}
with the lines
\begin{quote}
{\var name=udp protocols=ip;}\\
{\var name=udptest protocols=udp;}
\end{quote}
Then repeat steps 9 and 10 from above. You can also play with OPTIMIZE
versus DEBUG mode, as well as the trace level while in DEBUG mode.

\medskip Note that {\var /usr/xkernel/user\_level/build/Template}
contains various {\var example\_*} subdirectories, each of which
contains configuration files for various protocol stacks you can
try. For example, try running an RPC protocol stack, or the MSP or SWP
protocols.

\item Repeat the entire process---steps 2 through 10---for some other
Unix platform, for example, Linux on x86s rather than Solaris on
Sparc.

\item Implement a new protocol, and then configure an instance of
the {\xk} that tests this new protocol. The best way to get started on
this process is to copy an existing protocol into your build
directory, and then edit this protocol to implement the desired
functionality.  We recommend protocol ASP as a template for doing this
because it is so simple.  ASP is implemented by the three files in
{\var /usr/xkernel/protocols/asp/asp.c}, 
{\var /usr/xkernel/protocols/asp/asp\_internal.h}, and 
{\var /usr/xkernel/include/prot/asp.h}. (Copy all three of these files to
your build directory, and change their names to reflect the name of
your protocol.) You will also need a test protocol that sits on top of
your new protocol; we recommend {\var
/usr/xkernel/protocols/test/asptest.c} for this purpose. Finally, you
will need to edit {\var graph.comp} to configure your new protocol
into the {\xk}.

\medskip
Of course, the hard work is to write the {\xk} code that implements
the desired functionality. You will need to study the {\xk}
Programmer's Manual \cite{ProgMan_3.3} and Tutorial \cite{Tutorial} to
help you with this task.  It will be especially helpful to study
protocol ASP, which is described in detail in the Tutorial.  We
recommend you start with something simple, like changing the header
format.
\end{itemize}

\bibliography{../manual/manual}
\end{document}