]>
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 | 71 | |
371adba6 | 72 | <sect1>Functions of the protocol module |
3c6269b8 MM |
73 | |
74 | <p>The protocol module provides the following functions: |