Return to proto.sgml CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird2 / nest

Annotation of embedaddon/bird2/nest/proto.sgml, revision 1.1

1.1     ! misho       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: