xorpdev_101.tex

xorp源码hg

%
% $XORP: xorp/docs/xorpdev_101/xorpdev_101.tex,v 1.24 2007/03/15 00:43:16 pavlin Exp $
%

\documentclass[11pt]{article}

%\usepackage[dvips]{changebar}

\usepackage{subfigure}
\usepackage{fullpage}
\usepackage{setspace}
\usepackage{times}
\usepackage{latexsym}
\usepackage{epsfig}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage{color}
\usepackage{amsmath}
\usepackage{rotating}
\usepackage{moreverb}
\usepackage{listings}
\usepackage{alltt}
\usepackage{stmaryrd}
%\usepackage[dvipdf]{graphics}
%\usepackage[dvips]{graphicx}
%\usepackage{xorp}

\definecolor{gray}{rgb}{0.5,0.5,0.5}
\newcommand{\etc}{\emph{etc.}\xspace}
\newcommand{\ie}{\emph{i.e.,}\xspace}
\newcommand{\eg}{\emph{e.g.,}\xspace}
%\newcommand{\comment}[1]{{\color{gray}[\textsf{#1}]}}
%\newcommand{\comment}[1]{}

% Changebar stuff
% \newenvironment{colorcode}{\color{blue}}{}
% \renewcommand{\cbstart}{\begin{colorcode}}
% \renewcommand{\cbend}{\end{colorcode}}

% \pagestyle{empty}

\begin{document}

\title{An Introduction to Writing a XORP Process \\
\vspace{1ex}
Version 1.4}
\author{ XORP Project					\\
%	 International Computer Science Institute	\\
%	 Berkeley, CA 94704, USA			\\
         {\it http://www.xorp.org/}			\\
	 {\it [e-mail]}
}
\date{March 20, 2007}

\maketitle


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Local definitions
%
\newcommand{\stt}{\tt\small}
\newcommand{\SR}{{\tt\small static\_routes}\xspace}
\newcommand{\SRI}{{\it static\_routes}\xspace}

% Configure listings
\lstloadlanguages{C++,C}
\lstset{
    tabsize=8
  , basicstyle=\ttfamily\small
  , commentstyle=\color{gray}
  , flexiblecolumns=false
  , frame=TBLR
  , language=C++
  , stringstyle=\ttfamily
  , showstringspaces=false
}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\tableofcontents

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}

This document is intented for a developer who wishes to write a XORP
process, but doesn't know where to start.  We'll walk through a simple
XORP process, discussing how to define and use XRL interfaces, and how
the bits fit together.  

This is a first pass at such a document.  We're bound to have missed
things that are not obvious when you're starting out.  Please provide
us feedback as to how much help this document is; what really helped,
what's missing, and what isn't explained properly.

We'll assume that you have copies of four other XORP design documents:

\begin{itemize}
  \item XORP Design Overview\cite{xorp:design_arch}
  \item XORP Libxorp Library Overview\cite{xorp:libxorp}
  \item XORP Inter-Process Communication Library Overview\cite{xorp:xrl}
  \item XRL Interfaces: Specifications and Tools\cite{xorp:xrl_interfaces}
\end{itemize}

These are available from the XORP web server.  You should probably
have read these through quickly so you're aware what additional
information is available before reading this document further.  It's
recommended to read them in the order above.  

We will assume you are familiar with what an XRL request is, the
overall structure of the processes on a XORP router, and with C++.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Overview}

In this document we'll work through by example the structure of a
simple XORP process.  We've chosen the {\it static\_routes} process as
an example.  At the time of writing, this document is in sync with the
source code for static\_routes, but this is not guaranteed to always be
the case.

{\it static\_routes} is a very simple XORP process.  To a first
approximation, it receives XRL configuration requests from the
{\it xorp\_rtrmgr} to set up static routing entries, stores the entries, and
communicates them to the RIB using XRLs.  

This makes it a good example, because it exports an XRL interface to
other processes (typically the xorp\_rtrmgr) and calls XRLs on the XRL
interface of another XORP process (the RIB).  But it doesn't do all
that much else, so there are few files and the code is quite readable.

The source code for the \SRI process is found in the {\stt
xorp/static\_routes} subdirectory of the XORP source tree.

We'll walk through the main pieces of static\_routes in the following
order:

\begin{itemize}
  \item The XRL interface of static\_routes.
  \item Implementing the XRL interface of static\_routes.
  \item The main loop of static routes.
  \item Calling XRLs on the RIB.
\end{itemize}


\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The XRL Interface of {\it static\_routes}}

XRL interfaces are defined by a {\stt.xif} file (pronounced {\it dot-ziff}).
{\stt xif} stands for XRL InterFace.  All {\stt.xif} files reside in
{\stt xorp/xrl/interfaces}.

The relevant file for us is {\stt
xorp/xrl/interfaces/static\_routes.xif}. The first part of this file is
shown in Listing \ref{lst:xif}.

\begin{lstlisting}[caption={ The start of {\stt xorp/xrl/interfaces/static\_routes.xif} %
                                     \label{lst:xif} } ]{}
/*
 * Static Routes XRL interface.
 */

interface static_routes/0.1 {

	/**
	 * Enable/disable/start/stop StaticRoutes.
	 *
	 * @param enable if true, then enable StaticRoutes, otherwise
	 * disable it.
	 */
	enable_static_routes	? enable:bool
	start_static_routes
	stop_static_routes

	/**
	 * Add/replace/delete a static route.
	 *
	 * @param unicast if true, then the route would be used for unicast
	 * routing.
	 * @param multicast if true, then the route would be used in the
	 * MRIB (Multicast Routing Information Base) for multicast purpose
	 * (e.g., computing the Reverse-Path Forwarding information).
	 * @param network the network address prefix this route applies to.
	 * @param nexthop the address of the next-hop router for this route.
	 * @param metric the metric distance for this route.
	 */
	add_route4	? unicast:bool & multicast:bool & network:ipv4net \
			& nexthop:ipv4 & metric:u32

	add_route6	? unicast:bool & multicast:bool & network:ipv6net \
			& nexthop:ipv6 & metric:u32

...
}
\end{lstlisting}

The file {\stt static\_routes.xif} defines all the XRLs that are part of the
{\stt static\_routes} XRL interface.  These are XRLs that other processes can
call on the {\it static\_routes} process.

The format of the file is basically the keyword {\stt interface}
followed by the name and version of this particular interface,
followed by a list of XRLs.  
In this case the name of the interface is {\stt static\_routes}, but
this does not have to be the same as the name of the process.  The
version number is {\stt 0.1}.  Version numbers are generally increased
when a change is made that is not backwards compatible, but the
precise value has no important meaning.

The list of XRLs is demarked by braces {\stt \{ ... \}}, and one XRL is
given per line.  Blank lines and comments are allowed, and a backslash
before the newline can be used to split a long XRL over multiple lines
to aid readability.

\vspace{0.1in}
\noindent
Thus the first XRL in this file is:\\
 {\tt\small static\_routes/0.1/enable\_static\_routes?enable:bool}

\vspace{0.1in}
\noindent
When this XRL is actually called, it would look like:\\
{\tt\small
  finder://static\_routes/static\_routes/0.1/enable\_static\_routes?enable:bool=true}

\vspace{0.1in} The {\stt finder} part indicates that the XRL is an
abstract one - we don't yet know what the transport parameters are.
The first \SR indicates the name of the target process, and the second
\SR is the name of the interface, taken from the XIF
file.  A process can support more than one interface, and an interface
definition can be used by more than one process, hence the duplication
in a process as simple as \SRI.

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Using the {\tt static\_routes} XRL Interface}

Now we have seen how the XRLs comprising the static\_routes interface
are defined, we shall examine how processes actually use them.  For
any particular interface, there are two types of user:

\begin{itemize}

  \item The process that calls the XRLs and gets back responses.  This
  is called the XRL {\it caller}.

  \item The process on which the XRL is called, and which generates
  responses.  This is called the XRL {\it target}.

\end{itemize}

XORP provides scripts which can generate C++ code to make life much
easier for both these parties.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Generating stub code for the caller}

If we examine the file {\stt Makefile.am} (the automake Makefile) in
{\stt xorp/xrl/interfaces}, we find the fragment in Listing
\ref{lst:iftemp}.
\begin{lstlisting}[caption={ Fragment from {\stt xorp/xrl/interfaces/Makefile.am} %
                                     \label{lst:iftemp} } ]{}
###############################################################################
# Client Interface related
###############################################################################

# BGP MIB traps
noinst_LTLIBRARIES = libbgpmibtrapsxif.la
libbgpmibtrapsxif_la_SOURCES = bgp_mib_traps_xif.hh bgp_mib_traps_xif.cc

...

# StaticRoutes Interface
noinst_LTLIBRARIES += libstaticroutesxif.la
libstaticroutesxif_la_SOURCES = static_routes_xif.hh static_routes_xif.cc

...

###############################################################################
# Static Pattern Rules
###############################################################################

SCRIPT_DIR=$(top_srcdir)/xrl/scripts
CLNTGEN_PY=$(SCRIPT_DIR)/clnt-gen

@PYTHON_BUILD@%_xif.cc %_xif.hh $(srcdir)/%_xif.hh $(srcdir)/%_xif.cc: \
         $(srcdir)/%.xif $(CLNTGEN_PY)
@PYTHON_BUILD@	$(PYTHON) $(CLNTGEN_PY) $<

\end{lstlisting}%$

This adds {\stt libstaticroutesxif.la} to the list of libraries that
should be built, and indicates that the source files for this library
are {\stt static\_routes\_xif.hh} and {\stt static\_routes\_xif.cc}

The last part is pretty cryptic, but basically is a generic rule that
says that files ending with {\stt \_xif.cc} and {\stt \_xif.hh} will be
generated from files ending with {\stt .xif} using the python script
called {\stt clnt-gen}.

So what actually happens here is that the file {\stt static\_routes.xif}
is processed by {\stt clnt-gen} to produce {\stt static\_routes\_xif.hh}
and {\stt static\_routes\_xif.cc}, which are then compiled and linked
into the library {\stt libstaticroutesxif.la}.  Any process that wants
to call the \SRI interface can link with this library.

So what functionality does this library provide?  Listing
\ref{lst:sr.xif.hh} shows a fragment from the machine-generated file
{\stt static\_routes\_xif.hh}.  Between them, {\stt static\_routes\_xif.hh} and {\stt
static\_routes\_xif.cc} define the machine-generated class {\stt
XrlStaticRoutesV0p1Client} and its complete implementation.



\begin{lstlisting}[caption={ Fragment from {\stt xorp/xrl/interfaces/static\_routes\_xif.hh} %
                                     \label{lst:sr.xif.hh} } ]{}
class XrlStaticRoutesV0p1Client {
public:
    XrlStaticRoutesV0p1Client(XrlSender* s) : _sender(s) {}
    virtual ~XrlStaticRoutesV0p1Client() {}

...

    typedef XorpCallback1<void, const XrlError&>::RefPtr AddRoute4CB;
    /**
     *  Send Xrl intended to:
     *
     *  Add/replace/delete a static route.
     *
     *  @param dst_xrl_target_name the Xrl target name of the destination.
     *
     *  @param unicast if true, then the route would be used for unicast
     *  routing.
     *
     *  @param multicast if true, then the route would be used in the MRIB
     *  (Multicast Routing Information Base) for multicast purpose (e.g.,
     *  computing the Reverse-Path Forwarding information).
     *
     *  @param network the network address prefix this route applies to.
     *
     *  @param nexthop the address of the next-hop router for this route.
     *
     *  @param metric the metric distance for this route.
     */
    bool send_add_route4(
	const char*	dst_xrl_target_name,
	const bool&	unicast,
	const bool&	multicast,
	const IPv4Net&	network,
	const IPv4&	nexthop,
	const uint32_t&	metric,
	const AddRoute4CB&	cb
    );

...

}
\end{lstlisting}

\newpage

The constructor for {\stt XrlStaticRoutesV0p1Client} takes a pointer to
an {\stt XrlSender} as its parameter.  Typically this is actually an
{\stt XrlRouter} - we'll come to this in more detail later.

Then for every XRL defined in {\stt static\_routes.xif} there is a
method to be called on an instance of {\stt XrlStaticRoutesV0p1Client}.
The example we'll look at here is {\stt send\_add\_route4()}, although
there are many more methods defined in {\stt static\_routes.xif}.

If you compare the method {\stt send\_add\_route4()} in Listing
\ref{lst:sr.xif.hh} with the XRL {\stt add\_route4} in Listing
\ref{lst:xif}, it should be pretty clear where this comes from.
Basically, when you call \\
{\stt XrlStaticRoutesV0p1Client::send\_add\_route4} with all the
parameters ({\stt unicast}, {\stt nexthop}, etc).  set appropriately,
the XRL {\stt add\_route4} will be called.  You don't need to concern
yourself with how the parameters are marshalled into the right syntax
for the XRL, or how the XRL is actually transmitted, or even how the
target process is discovered.  But you do need to set the {\stt
target\_name} parameter to the same thing that the \SR process sets it
to, otherwise the XRL {\it finder} won't be able to route your XRL to
its destination.  Often the target name will be the same as the name
of the process - in this case \SRI - but if there are multiple
instances of the interface then you'll need to figure out which target
name to use.

You'll also notice that some of the parameters for XRL functions are
not native C++ types.  In this case, {\stt network} is of type {\stt
IPv4Net} and {\stt nexthop} is of type {\stt IPv4}.  Classes
instantiating the these additional types are found in {\stt libxorp}
and are used throughout XORP.  

The final parameter is {\stt const AddRoute4CB\& cb}.\\
Earlier in the