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

\section{Configuring a Kernel}\label{config}

This section describes how to configure and build an {\xk}.  You will
need to substitute the pathname where your system's {\xk} tree resides
for {\var /usr/xkernel} in the following.

The {\xk} configure and build procedure is the same, regardless of
whether you are building a user\_level, standalone, or simulator
{\xk}.  For simplicity, we explain how to build a user\_level kernel.
Substitute {\var stand\_alone} or {\var simulator} for 
{\var user\_level} in the pathnames that follow to build standalone and
simulator kernels, respectively.

\subsection{Build Directory}\label{build_dir}

The {\xk} user must set up a ``build directory'' in which to construct
an instance of the {\xk}. Build directories are usually created within
a user's home directory.

Each build directory can support one {\xk} configuration at a time.
The contents of three types of files determine an {\xk} configuration.
They are:

\begin{itemize}

\item{}
A {\var graph.comp} file specifies the collection of protocols that
are to be included in the kernel and the relations between them.

\item{}
Protocol table files ({\var prottab}) define the number space for
protocols to identify each other.

\item{}
ROM files specify runtime options, such as the IP address of the host
machine on which an {\xk} will be run.

\end{itemize}

The {\var graph.comp} file must reside in the build directory.
Protocol table files and ROM files are not required to be in the build
directory; later, we show how to specify the locations of these files.
Note that the {\var graph.comp} file is read in during the build
phase, and so represents an {\xk}'s static configuration.  The
protocol table files and ROM files are scanned at runtime, and so allow
dynamic configuration of the {\xk}.

Directory {\var /usr/xkernel/user\_level/build/Template} contains
samples of common {\var graph.comp} and ROM files.  The {\var
graph.comp} file should be copied from this directory to your build
directory.  Also, the appropriate Makefile for your platform must be
copied from this directory to the build directory; it should be
renamed {\var Makefile}, and made writable.  The sample ROM file found
in this directory may be copied to a directory from which you intend
to run the {\xk}; more on this in Section~\ref{running}.

For the purpose of the remaining discussion, we assume you are
configuring a kernel so as to implement and evaluate protocol ASP (A
Simple Protocol), the example protocol used in the {\xk} Tutorial
\cite{Tutorial}.

\subsection{Specifying a Protocol Graph}\label{prot_graph}

The {\var graph.comp} file is divided into three sections: device
drivers, protocols, and miscellaneous configuration parameters.  The
sections are separated by lines beginning with {\var @;} each section
may be empty.

The first two sections---device drivers and protocols---describe the
protocol graph to be configured into the {\xk}.  The only difference
between the two sections is that drivers in the first section are
initialized directly from the {\xk} boot thread, whereas protocols in
the protocol section are initialized from a distinct protocol
initialization thread.  For the device drivers and platforms in this
distribution, this distinction is of no consequence and device drivers
may be configured in either the first or the second section.

Device drivers and protocols are described by the same types of
entries, as illustrated by the following example.

\begin{verbatim}
      name=asp files=asp dir=asp protocols=ip,eth trace=TR_MAJOR_EVENTS;
\end{verbatim}

\noindent
The first field gives the protocol's name.  The rest of the fields are
optional and may occur in any order.  The {\var dir} and {\var files}
fields describe the names and locations of the source files that
implement the protocol.  Files are specified without extensions.  The
{\var dir} and {\var files} fields are not used in the common case
where you want to link in protocol object code from the public system
object area ({\var /usr/xkernel/protocols}); they are used only when
you want to compile and link code from your private build area.  If a
{\var files} entry exists but no {\var dir} entry is specified, the
current directory (i.e., the build directory) is assumed.  If a 
{\var dir} entry exists without a {\var files} entry, the {\var files} 
field defaults to a single {\var .c} file with the protocol's name.

The {\var protocols} field indicates the protocols directly below the
current protocol in the graph, that is, the protocols upon which this
protocol depends.  When this field contains multiple protocols, order
is significant; the lower protocols will be loaded into the upper
protocol's down vector in the order in which they are listed.  A
protocol tha expects multiple protocols below it will describe the
expected semantics of the lower protocols in its manual page in
Appendix~\ref{prot_specs}.

The {\var trace} field defines the debugging level used in trace
statements depending on the protocol variable {\var traceaspp}.

Multiple instantiations of protocols are supported by using a ``/''
character after the protocol name, and then adding a unique suffix.
In the following example, two instantiations of ``asp'' are indicated,
one over ``ip'' and one over ``eth,'' and both are used by the ``prt''
protocol.  In this example, each instance suffix for the ``asp''
protocol is the name of the protocol below the instance, but this is
just a convention; any distinct string could be used as an instance
suffix.  Note that only the first of multiple instantiations should
have {\var dir}, {\var files}, or {\var trace} fields.

\begin{verbatim}
      name=asp/ip files=asp dir=asp protocols=ip trace=TR_MAJOR_EVENTS;
      name=asp/eth protocols=eth;
      name=prt files=prt dir=prt protocols=asp/ip,asp/eth trace=TR_ERRORS;
\end{verbatim}

The third section of {\var graph.comp} contains the names of protocol
table files that are to be loaded during initialization.  It also
contains the names of subsystems and their configuration parameters.
Currently, trace variables are the only configuration parameters that
can be set here.  The following illustrates a typical use of the third
section.

\begin{verbatim}
      @;
      #
      # You can specify protocol tables to be read in at boot time.
      #
      prottbl=/usr/xkernel/etc/prottbl.std;
      prottbl=./prottbl.local;
      #
      # You can specify subsystem tracing for messages and protocol operations
      # (see file include/xk_debug.h for a list of subsystem trace variables).
      #
      name=msg        trace=TR_GROSS_EVENTS;
      name=protocol   trace=TR_MAJOR_EVENTS;
      #
      # You can specify the name of the ROM file to be used; it will be read
      # during "make compose" and incorporated into the xkernel runtime image.
      #
      romfile=romfile.asp;
      #
      # You can specify romfile contents (see section "ROM options").
      #
      romopt shepherd threads 8;
\end{verbatim}

The {\var graph.comp} file is read by an {\xk} utility program called
{\var compose}. This utility generates startup code to build the
protocol graph and set up the described configuration.  The protocol
graph is built bottom-up; when a protocol's initialization function is
called, the lower level-protocols have already been initialized.

\input protnums

\input rom

\subsection{Build Procedure}\label{build_proc}

Once you have edited the {\var graph.comp} file to include all
protocols and device drivers to be configured into the {\xk}, an
instance of the {\xk} can be built.  Execute the following steps.
(The protocol table and ROM files can be specified and even changed at
a later time because they are read at runtime.)

\begin{enumerate}

\item{}
Put {\var /usr/xkernel/bin/BINTYPE} and {\var /usr/xkernel/bin} in
your search path, where {\var BINTYPE} is one of {\var sunos-sparc},
{\var solaris-sparc}, {\var osf1-alpha}, {\var linux-alpha}, 
{\var linux-x86} or {\var irix-mips}.

These must occur before {\var /bin} and {\var /usr/bin}.  This allows
use of the version of {\var make} distributed with the {\xk} (GNU make
v. 3.66), which is included in the {\var BINTYPE} directory, rather
than the standard Unix {\var make}.

\item{}
Modify the Makefile in the build directory.  The variable {\var XRT}
in this Makefile must be a path to the root of the {\xk} source tree;
e.g., {\var /usr/xkernel}.  The {\xk} uses a trace package to generate
debugging information; to enable the tracing facility, set the
Makefile variable {\var HOWTOCOMPILE} to {\var DEBUG}.  To obtain
accurate performance timings, variable {\var HOWTOCOMPILE} should be
assigned {\var OPTIMIZE}.  This causes all trace of tracing code to be
eliminated from the kernel.

\item{}
Type: {\var make compose}

If this is the first time {\var make compose} has been run, you may
see what appear to be error messages about missing files, such as
{\var Makefile.local} and {\var DEPS/Makedep.*}.  These warnings can
be ignored, since these files will be created by the running of 
{\var make compose}.

\item{}
Type: {\var make depend}

\item{}
Type: {\var make}

\end{enumerate}

Object files will be placed in a subdirectory of the {\var OBJS}
directory, whose name reflects the chosen configuration and platform
(e.g., {\var UL-DEBUG-sunos-sparc}). Object files are stored
similarly throughout the {\xk} hierarchy.  The final {\xk} executable
({\var xkernel}) will be placed in your build directory.

Steps 3 through 5 must be repeated whenever you change the 
{\var graph.comp} file.  If the Makefile is changed, only step 5 must be
repeated.  Changes to the protocol tables and ROM files do not require
rebuilding tke {\xk}.

\input config_examples