nest/proto.sgml

   1 <!--
   2         BIRD Programmer's Guide: Protocols
   3
   4         (c) 2000 Martin Mares <mj@ucw.cz>
   5 -->
   6
   7 <sect>Routing protocols
   8
   9 <sect1>Introduction
  10
  11 <p>The routing protocols are the bird's heart and a fine amount of code
  12 is dedicated to their management and for providing support functions to them.
  13 (-: Actually, this is the reason why the directory with sources of the core
  14 code is called <tt/nest/ :-).
  15
  16 <p>When talking about protocols, one need to distinguish between <em/protocols/
  17 and protocol <em/instances/. A protocol exists exactly once, not depending on whether
  18 it's configured or not and it can have an arbitrary number of instances corresponding
  19 to its "incarnations" requested by the configuration file. Each instance is completely
  20 autonomous, has its own configuration, its own status, its own set of routes and its
  21 own set of interfaces it works on.
  22
  23 <p>A protocol is represented by a <struct/protocol/ structure containing all the basic
  24 information (protocol name, default settings and pointers to most of the protocol
  25 hooks). All these structures are linked in the <param/protocol_list/ list.
  26
  27 <p>Each instance has its own <struct/proto/ structure describing all its properties: protocol
  28 type, configuration, a resource pool where all resources belonging to the instance
  29 live, various protocol attributes (take a look at the declaration of <struct/proto/ in
  30 <tt/protocol.h/), protocol states (see below for what do they mean), connections
  31 to routing tables, filters attached to the protocol
  32 and finally a set of pointers to the rest of protocol hooks (they
  33 are the same for all instances of the protocol, but in order to avoid extra
  34 indirections when calling the hooks from the fast path, they are stored directly
  35 in <struct/proto/). The instance is always linked in both the global instance list
  36 (<param/proto_list/) and a per-status list (either <param/active_proto_list/ for
  37 running protocols, <param/initial_proto_list/ for protocols being initialized or
  38 <param/flush_proto_list/ when the protocol is being shut down).
  39
  40 <p>The protocol hooks are described in the next chapter, for more information about
  41 configuration of protocols, please refer to the configuration chapter and also
  42 to the description of the <func/proto_commit/ function.
  43
  44 <sect1>Protocol states
  45
  46 <p>As startup and shutdown of each protocol are complex processes which can be affected
  47 by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.),
  48 we have decided to supervise them by a pair of simple state machines -- the protocol
  49 state machine and a core state machine.
  50
  51 <p>The <em/protocol state machine/ corresponds to internal state of the protocol
  52 and the protocol can alter its state whenever it wants to. There are
  53 the following states:
  54
  55 <descrip>
  56         <tag/PS_DOWN/ The protocol is down and waits for being woken up by calling its
  57         start() hook.
  58         <tag/PS_START/ The protocol is waiting for connection with the rest of the
  59         network. It's active, it has resources allocated, but it still doesn't want
  60         any routes since it doesn't know what to do with them.
  61         <tag/PS_UP/ The protocol is up and running. It communicates with the core,
  62         delivers routes to tables and wants to hear announcement about route changes.
  63         <tag/PS_STOP/ The protocol has been shut down (either by being asked by the
  64         core code to do so or due to having encountered a protocol error).
  65 </descrip>
  66
  67 <p>Unless the protocol is in the <tt/PS_DOWN/ state, it can decide to change
  68 its state by calling the <func/proto_notify_state/ function.
  69
  70 <p>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.
  71
  72 <sect1>Functions of the protocol module
  73
  74 <p>The protocol module provides the following functions: