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

\subsection{Protocol Tables}\label{protocol_tables}

The {\xk} runtime environment always includes a protocol table that
defines the number space protocols use to identify each other.  The
{\xk} builds a table of protocol numbers by reading configuration
files at runtime, and provides an operation for protocols to query
this table to determine the protocol corresponding to a protocol
number.  This frees protocol developers from having to embed explicit
protocol numbers in the protocol code itself.

The reason that the protocol table is needed may not be obvious.
After an {\xk} protocol receives an incoming data message and finishes
processing it, the message must be passed up to the appropriate
higher-level protocol.  To do this, the protocol must determine the
high level protocol to which the message belongs; for example, the IP
protocol must decide if a received message should be passed up to UDP
or TCP.  Each {\xk} message carries in its message headers fields
containing the numbers of the protocols that sent it, and these
determine which protocols should process the message on the receiving
host.  Thus, the protocol holding the message extracts the protocol
number of the next high level protocol from the message header,
queries the protocol table, and passes the message on to the indicated
protocol.

If the {\var graph.comp} file does not include any non-standard
protocols, one of the default protocol tables in 
{\var /usr/xkernel/etc} may safely be used.

The following is an example protocol table file.

\begin{verbatim}
      #
      # prottbl
      #
      # This file describes absolute protocol id's and gives relative
      # protocol numbers for those protocols that use them.
      #

      eth      1
      {
          ip       x0800
          arp      x0806
          rarp     x8035
          #
          # ethernet types x3*** are not reserved
          #
          blast    x3001
      }
      ip       2
      {
          icmp     1
          tcp      6
          udp      17
          #
          # IP protocol numbers n, 91 < n < 255, are unassigned
          #
          blast    101
      }
      arp      3
      rarp     4
      udp      5
      tcp      6
      icmp     7
      blast    8
\end{verbatim}

\noindent
Each protocol has an entry of the form:

\medskip

\begin{quote}
{\var name  idNumber  [ \{  hlp1  relNum1  hlp2  relNum2  ... \} ] }
\end{quote}

\medskip

\noindent
where {\var idNumber} uniquely identifies each protocol.

There are two ways for a protocol to define its protocol number space.
The first technique uses an {\em explicit numbering} scheme; the
protocol explicitly indicates which protocols may be configured above
it and the relative number that should be used for each higher-level
protocol.  Use of this numbering scheme is indicated by the presence
of the optional {\em hlp} list after the protocol's {\em idNumber}.

The second technique uses an {\em implicit numbering} scheme; the
protocol does not explicitly name its allowed upper protocols, but
will implicitly use each protocol's unique {\em idNumber} as its
relative protocol number.  BLAST, for example, employs this technique
and would use SUNRPC's {\em idNumber} 9 as its protocol number
relative to BLAST.  Protocol ID numbers are 4-byte quantities in the
{\xk}, so protocols using implicit numbering have a 4-byte field in
their headers for the upper protocol number.

Implicit numbering clearly allows more flexibility in how protocols
may be composed.  As flexible composability is one of the goals of the
{\xk}, all new protocols written in the {\xk} should use this implicit
numbering scheme.

The {\xk} is distributed with two useful protocol table files: 
{\var prottbl.std} and {\var prottbl.nonstd}. These files are located in
{\var /usr/xkernel/etc}. The first of these two files, 
{\var prottbl.std}, contains the standard protocol numbers; e.g., TCP is
known as protocol ``6'' relative to IP, IP is known as protocol
``x0800'' relative to the ethernet, and so on.  This file should be
used when there is no danger of interfering with the standard protocol
suite on the platform you are using.  The second file, 
{\var prottbl.nonstd}, uses non-standard protocol numbers.  You will want 
to use this file when there is a danger of interfering with the
platform's native protocol stack; e.g., when both the {\xk} and the
native stack are running and getting packets diverted their way by a
packet filter.

All {\xk}s must load at least one protocol table, and all protocols
configured in a kernel must have an entry in the protocol table.  If
you are writing a new protocol, you will probably want to define an
auxiliary protocol table which assigns a temporary {\em idNumber} to
your new protocol and then configure your kernel to read in both the
system table and your auxiliary table.  If you need to configure your
new protocol above an existing protocol which uses explicit numbering,
you can augment the table for the existing protocol as in this
example.

\begin{verbatim}
      #
      # Auxiliary protocol table
      #

      asp  1000

      ip   2  {
          asp  200
      }
\end{verbatim}

Here, we define our new protocol ASP and indicate that it has protocol
number 200 relative to IP.  Note that when augmenting the tables of
other protocols, the {\em idNumber} of the other protocol must match
its number in the system file.

The {\xk} runs consistency checks on the protocol tables and will give
error messages and abort in the presence of inconsistencies.

\subsubsection{ROM options}\label{rom_opts}

The protocol table files used by a particular instance of the {\xk}
can be specified in either the {\var graph.comp} file
(Section~\ref{prot_graph}), or in a ROM file (see
Section~\ref{rom_files}).  The ROM file format is:

\begin{quote}
\begin{tt}
prottbl FILENAME1\\
prottbl FILENAME2\\
...
\end{tt}
\end{quote}

\noindent
In both cases, the named protocol tables are loaded at runtime.

By default, the protocol table allows multiple upper protocols to use
the same protocol number relative to a single lower protocol.  To
restrict this behavior, so that each upper protocol must have a unique
relative protocol number, the {\tt unique\_hlps} ROM option may be
used.

\begin{quote}
\begin{tt}
prottbl unique\_hlps on
\end{tt}
\end{quote}