]>
Commit | Line | Data |
---|---|---|
3c6269b8 MM |
1 | <!-- |
2 | BIRD Programmer's Guide: Protocols | |
3 | ||
4 | (c) 2000 Martin Mares <mj@ucw.cz> | |
5 | --> | |
6 | ||
371adba6 | 7 | <sect>Routing protocols |
3c6269b8 | 8 | |
371adba6 | 9 | <sect1>Introduction |
3c6269b8 | 10 | |
725270cb | 11 | <p>The routing protocols are the bird's heart and a fine amount of code |
3c6269b8 MM |
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 | |
725270cb | 18 | it's configured or not and it can have an arbitrary number of instances corresponding |
3c6269b8 MM |
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 | ||
371adba6 | 44 | <sect1>Protocol states |
3c6269b8 MM |
45 | |
46 | <p>As startup and shutdown of each protocol are complex processes which can be affected | |
9238b06a | 47 | by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.), |
3c6269b8 MM |
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 | |
725270cb | 52 | and the protocol can alter its state whenever it wants to. There are |
3c6269b8 MM |
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 | ||
58f7d004 | 70 | <p>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook. |
3c6269b8 MM |
71 | |
72 | <p>The <em/core state machine/ takes care of the core view of protocol state. | |
73 | The states are traversed according to changes of the protocol state machine, but | |
74 | sometimes the transitions are delayed if the core needs to finish some actions | |
75 | (for example sending of new routes to the protocol) before proceeding to the | |
725270cb | 76 | new state. There are the following core states: |
3c6269b8 MM |
77 | |
78 | <descrip> | |
79 | <tag/FS_HUNGRY/ The protocol is down, it doesn't have any routes and | |
80 | doesn't want them. | |
81 | <tag/FS_FEEDING/ The protocol has reached the <tt/PS_UP/ state, but | |
82 | we are still busy sending the initial set of routes to it. | |
83 | <tag/FS_HAPPY/ The protocol is up and has complete routing information. | |
84 | <tag/FS_FLUSHING/ The protocol is shutting down (it's in either <tt/PS_STOP/ | |
85 | or <tt/PS_DOWN/ state) and we're flushing all of its routes from the | |
86 | routing tables. | |
87 | </descrip> | |
88 | ||
371adba6 | 89 | <sect1>Functions of the protocol module |
3c6269b8 MM |
90 | |
91 | <p>The protocol module provides the following functions: |