[Xorp-hackers] An Introduction to Writing a XORP Process

[Pavlin Radoslavov]

> 
> I have three students this summer here at UCL working on XORP-related
> projects.  One of them has had no problems whatsoever figuring out how
> the pieces of XORP fit together, but the other two have had some
> difficulty.
> 
> To try and make it easier to get started, I've written a document
> called "An Introduction to Writing a XORP Process".  It attempts to
> lead the reader through by example how XRL interfaces are defined, the
> stub compilation process, what the XORP main loop looks like, and how
> you call XRLs on other processes.
> 
> My first draft is currently available here:
> 
>   http://nrg.cs.ucl.ac.uk/mjh/tmp/xorpdev101.pdf
> 
> If it seems like it's useful, it will probably find a more permanent
> home somewhere else.  It's also checked in to CVS in the xorp/docs
> directory.
> 
> If you've found yourself in a similar situation to my students, I'd
> appreciate feedback as to how useful this is, what critical things are
> missing, and what could be explained better.

Mark,

Below are a number of random comments:

 * At the beginning, it may be useful to have a diagram what a XORP
   process looks like. E.g., the core of the process that is doing
   the task, the XRL interface around it, the single eventloop
   instance, etc. There it may be worth mentioning/repeating that
   a XORP process is single-threaded.

 * Somewhere (probably at the end) there should be a section with
   design guidelines/hints. For example, because the code is no
   preemptive, no part of the code is allowed to run for a very long
   time without returning control to the eventloop.
   Another example would be the guideline that no global state is
   allowed.

 * The document is missing several important pieces:
   - Handling the PROC_* process status that is required for
    controlling the process via the rtrmgr
   - An introduction to the ServiceStatus codes (in
    libxorp/service.hh) which can be used to set the service status
    on each sub-component. Strictly speaking, using the ServiceStatus
    codes is not mandatory, but it can simplify significantly a
    process with several components whose status or behavior depends
    on each other.
   - An introduction to the rtrmgr/xorpsh (with regard to adding a
    new process). For example, what are the requirements for the
    XORP process so it can be controlled via the rtrmgr (e.g., every
    process must implement the "common/0.1" XRL interface).
    Also, information about writing rtrmgr template files and xorpsh
    operational commands templates.
  - Information about printing various info: the XLOG_ facility.
  - Information about supporting default command-line options. E.g.,
    we have defined [-F <finder_hostname>[:<finder_port>]]
    as the default command-line options to set the finder name and
    port number.
  - Information about the autoconf/automake mechanism. E.g., what a
    simple Makefile.am should look like, how to modify configure.in
    and the top-level Makefile.am to add the new module, and when
    ./bootstrap should be run

 * If a protocol would be dealing with network interfaces (as most
   protocols are), then a brief introduction to libfeaclient can be
   useful (the library to register with the FEA and receive the
   information updates).

 * Add a brief intro/mentioning to kdoc and how to generate the kdoc
   documentation.

In general, I like the style of the document which has plenty of
examples, code listings and describes things into tiny details.
BTW, do you know how easy is to use line numbers in the source code
listings similar to the text of Stevens' books (RIP).
Myself I am a big fan of his style, and I think the document can be
improved even further by using that style as a model.

Regards,
Pavlin