Annotation of embedaddon/bird/doc/prog-2.html, revision 1.1.1.2
1.1 misho 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2: <HTML>
3: <HEAD>
4: <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9">
5: <TITLE>BIRD Programmer's Documentation: Core</TITLE>
6: <LINK HREF="prog-3.html" REL=next>
7: <LINK HREF="prog-1.html" REL=previous>
8: <LINK HREF="prog.html#toc2" REL=contents>
9: </HEAD>
10: <BODY>
11: <A HREF="prog-3.html">Next</A>
12: <A HREF="prog-1.html">Previous</A>
13: <A HREF="prog.html#toc2">Contents</A>
14: <HR>
15: <H2><A NAME="s2">2.</A> <A HREF="prog.html#toc2">Core</A></H2>
16:
17: <H2><A NAME="ss2.1">2.1</A> <A HREF="prog.html#toc2.1">Forwarding Information Base</A>
18: </H2>
19:
20: <P>
21: <P>FIB is a data structure designed for storage of routes indexed by their
22: network prefixes. It supports insertion, deletion, searching by prefix,
23: `routing' (in CIDR sense, that is searching for a longest prefix matching
24: a given IP address) and (which makes the structure very tricky to implement)
25: asynchronous reading, that is enumerating the contents of a FIB while other
26: modules add, modify or remove entries.
27: <P>Internally, each FIB is represented as a collection of nodes of type <I>fib_node</I>
28: indexed using a sophisticated hashing mechanism.
29: We use two-stage hashing where we calculate a 16-bit primary hash key independent
30: on hash table size and then we just divide the primary keys modulo table size
31: to get a real hash key used for determining the bucket containing the node.
32: The lists of nodes in each bucket are sorted according to the primary hash
33: key, hence if we keep the total number of buckets to be a power of two,
34: re-hashing of the structure keeps the relative order of the nodes.
35: <P>To get the asynchronous reading consistent over node deletions, we need to
36: keep a list of readers for each node. When a node gets deleted, its readers
37: are automatically moved to the next node in the table.
38: <P>Basic FIB operations are performed by functions defined by this module,
39: enumerating of FIB contents is accomplished by using the <B>FIB_WALK()</B> macro
40: or <B>FIB_ITERATE_START()</B> if you want to do it asynchronously.
1.1.1.2 ! misho 41: <P>For simple iteration just place the body of the loop between <B>FIB_WALK()</B> and
! 42: <B>FIB_WALK_END()</B>. You can't modify the FIB during the iteration (you can modify
! 43: data in the node, but not add or remove nodes).
! 44: <P>If you need more freedom, you can use the FIB_ITERATE_*() group of macros.
! 45: First, you initialize an iterator with <B>FIB_ITERATE_INIT()</B>. Then you can put
! 46: the loop body in between <B>FIB_ITERATE_START()</B> and <B>FIB_ITERATE_END()</B>. In
! 47: addition, the iteration can be suspended by calling <B>FIB_ITERATE_PUT()</B>.
! 48: This'll link the iterator inside the FIB. While suspended, you may modify the
! 49: FIB, exit the current function, etc. To resume the iteration, enter the loop
! 50: again. You can use <B>FIB_ITERATE_UNLINK()</B> to unlink the iterator (while
! 51: iteration is suspended) in cases like premature end of FIB iteration.
! 52: <P>Note that the iterator must not be destroyed when the iteration is suspended,
! 53: the FIB would then contain a pointer to invalid memory. Therefore, after each
! 54: <B>FIB_ITERATE_INIT()</B> or <B>FIB_ITERATE_PUT()</B> there must be either
! 55: <B>FIB_ITERATE_START()</B> or <B>FIB_ITERATE_UNLINK()</B> before the iterator is destroyed.
1.1 misho 56: <P>
57: <P><HR><H3>Function</H3>
58: <P><I>void</I>
59: <B>fib_init</B>
60: (<I>struct fib *</I> <B>f</B>, <I>pool *</I> <B>p</B>, <I>unsigned</I> <B>node_size</B>, <I>unsigned</I> <B>hash_order</B>, <I>fib_init_func</I> <B>init</B>) -- initialize a new FIB
61: <P>
62: <H3>Arguments</H3>
63: <P>
64: <DL>
65: <DT><I>struct fib *</I> <B>f</B><DD><P>the FIB to be initialized (the structure itself being allocated by the caller)
66: <DT><I>pool *</I> <B>p</B><DD><P>pool to allocate the nodes in
67: <DT><I>unsigned</I> <B>node_size</B><DD><P>node size to be used (each node consists of a standard header <I>fib_node</I>
68: followed by user data)
69: <DT><I>unsigned</I> <B>hash_order</B><DD><P>initial hash order (a binary logarithm of hash table size), 0 to use default order
70: (recommended)
71: <DT><I>fib_init_func</I> <B>init</B><DD><P>pointer a function to be called to initialize a newly created node
72: </DL>
73: <H3>Description</H3>
74: <P>This function initializes a newly allocated FIB and prepares it for use.
75:
76:
77: <HR><H3>Function</H3>
78: <P><I>void *</I>
79: <B>fib_find</B>
80: (<I>struct fib *</I> <B>f</B>, <I>ip_addr *</I> <B>a</B>, <I>int</I> <B>len</B>) -- search for FIB node by prefix
81: <P>
82: <H3>Arguments</H3>
83: <P>
84: <DL>
85: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to search in
86: <DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the prefix
87: <DT><I>int</I> <B>len</B><DD><P>prefix length
88: </DL>
89: <H3>Description</H3>
90: <P>Search for a FIB node corresponding to the given prefix, return
91: a pointer to it or <I>NULL</I> if no such node exists.
92:
93:
94: <HR><H3>Function</H3>
95: <P><I>void *</I>
96: <B>fib_get</B>
97: (<I>struct fib *</I> <B>f</B>, <I>ip_addr *</I> <B>a</B>, <I>int</I> <B>len</B>) -- find or create a FIB node
98: <P>
99: <H3>Arguments</H3>
100: <P>
101: <DL>
102: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to work with
103: <DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the prefix
104: <DT><I>int</I> <B>len</B><DD><P>prefix length
105: </DL>
106: <H3>Description</H3>
107: <P>Search for a FIB node corresponding to the given prefix and
108: return a pointer to it. If no such node exists, create it.
109:
110:
111: <HR><H3>Function</H3>
112: <P><I>void *</I>
113: <B>fib_route</B>
114: (<I>struct fib *</I> <B>f</B>, <I>ip_addr</I> <B>a</B>, <I>int</I> <B>len</B>) -- CIDR routing lookup
115: <P>
116: <H3>Arguments</H3>
117: <P>
118: <DL>
119: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to search in
120: <DT><I>ip_addr</I> <B>a</B><DD><P>pointer to IP address of the prefix
121: <DT><I>int</I> <B>len</B><DD><P>prefix length
122: </DL>
123: <H3>Description</H3>
124: <P>Search for a FIB node with longest prefix matching the given
125: network, that is a node which a CIDR router would use for routing
126: that network.
127:
128:
129: <HR><H3>Function</H3>
130: <P><I>void</I>
131: <B>fib_delete</B>
132: (<I>struct fib *</I> <B>f</B>, <I>void *</I> <B>E</B>) -- delete a FIB node
133: <P>
134: <H3>Arguments</H3>
135: <P>
136: <DL>
137: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to delete from
138: <DT><I>void *</I> <B>E</B><DD><P>entry to delete
139: </DL>
140: <H3>Description</H3>
141: <P>This function removes the given entry from the FIB,
142: taking care of all the asynchronous readers by shifting
143: them to the next node in the canonical reading order.
144:
145:
146: <HR><H3>Function</H3>
147: <P><I>void</I>
148: <B>fib_free</B>
149: (<I>struct fib *</I> <B>f</B>) -- delete a FIB
150: <P>
151: <H3>Arguments</H3>
152: <P>
153: <DL>
154: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to be deleted
155: </DL>
156: <H3>Description</H3>
157: <P>This function deletes a FIB -- it frees all memory associated
158: with it and all its entries.
159:
160:
161: <HR><H3>Function</H3>
162: <P><I>void</I>
163: <B>fib_check</B>
164: (<I>struct fib *</I> <B>f</B>) -- audit a FIB
165: <P>
166: <H3>Arguments</H3>
167: <P>
168: <DL>
169: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to be checked
170: </DL>
171: <H3>Description</H3>
172: <P>This debugging function audits a FIB by checking its internal consistency.
173: Use when you suspect somebody of corrupting innocent data structures.
174:
175: <H2><A NAME="ss2.2">2.2</A> <A HREF="prog.html#toc2.2">Routing tables</A>
176: </H2>
177:
178: <P>
179: <P>Routing tables are probably the most important structures BIRD uses. They
180: hold all the information about known networks, the associated routes and
181: their attributes.
182: <P>There are multiple routing tables (a primary one together with any
183: number of secondary ones if requested by the configuration). Each table
184: is basically a FIB containing entries describing the individual
185: destination networks. For each network (represented by structure <I>net</I>),
186: there is a one-way linked list of route entries (<I>rte</I>), the first entry
187: on the list being the best one (i.e., the one we currently use
188: for routing), the order of the other ones is undetermined.
189: <P>The <I>rte</I> contains information specific to the route (preference, protocol
190: metrics, time of last modification etc.) and a pointer to a <I>rta</I> structure
191: (see the route attribute module for a precise explanation) holding the
192: remaining route attributes which are expected to be shared by multiple
193: routes in order to conserve memory.
194: <P>
195: <P><HR><H3>Function</H3>
196: <P><I>rte *</I>
197: <B>rte_find</B>
198: (<I>net *</I> <B>net</B>, <I>struct rte_src *</I> <B>src</B>) -- find a route
199: <P>
200: <H3>Arguments</H3>
201: <P>
202: <DL>
203: <DT><I>net *</I> <B>net</B><DD><P>network node
204: <DT><I>struct rte_src *</I> <B>src</B><DD><P>route source
205: </DL>
206: <H3>Description</H3>
207: <P>The <B>rte_find()</B> function returns a route for destination <B>net</B>
208: which is from route source <B>src</B>.
209:
210:
211: <HR><H3>Function</H3>
212: <P><I>rte *</I>
213: <B>rte_get_temp</B>
214: (<I>rta *</I> <B>a</B>) -- get a temporary <I>rte</I>
215: <P>
216: <H3>Arguments</H3>
217: <P>
218: <DL>
219: <DT><I>rta *</I> <B>a</B><DD><P>attributes to assign to the new route (a <I>rta</I>; in case it's
220: un-cached, <B>rte_update()</B> will create a cached copy automatically)
221: </DL>
222: <H3>Description</H3>
223: <P>Create a temporary <I>rte</I> and bind it with the attributes <B>a</B>.
224: Also set route preference to the default preference set for
225: the protocol.
226:
227:
228: <HR><H3>Function</H3>
229: <P><I>rte *</I>
230: <B>rte_cow_rta</B>
231: (<I>rte *</I> <B>r</B>, <I>linpool *</I> <B>lp</B>) -- get a private writable copy of <I>rte</I> with writable <I>rta</I>
232: <P>
233: <H3>Arguments</H3>
234: <P>
235: <DL>
236: <DT><I>rte *</I> <B>r</B><DD><P>a route entry to be copied
237: <DT><I>linpool *</I> <B>lp</B><DD><P>a linpool from which to allocate <I>rta</I>
238: </DL>
239: <H3>Description</H3>
240: <P><B>rte_cow_rta()</B> takes a <I>rte</I> and prepares it and associated <I>rta</I> for
241: modification. There are three possibilities: First, both <I>rte</I> and <I>rta</I> are
242: private copies, in that case they are returned unchanged. Second, <I>rte</I> is
243: private copy, but <I>rta</I> is cached, in that case <I>rta</I> is duplicated using
244: <B>rta_do_cow()</B>. Third, both <I>rte</I> is shared and <I>rta</I> is cached, in that case
245: both structures are duplicated by <B>rte_do_cow()</B> and <B>rta_do_cow()</B>.
246: <P>Note that in the second case, cached <I>rta</I> loses one reference, while private
247: copy created by <B>rta_do_cow()</B> is a shallow copy sharing indirect data (eattrs,
248: nexthops, ...) with it. To work properly, original shared <I>rta</I> should have
249: another reference during the life of created private copy.
250: <H3>Result</H3>
251: <P>a pointer to the new writable <I>rte</I> with writable <I>rta</I>.
252:
253:
254: <HR><H3>Function</H3>
255: <P><I>void</I>
256: <B>rte_announce</B>
257: (<I>rtable *</I> <B>tab</B>, <I>unsigned</I> <B>type</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>, <I>rte *</I> <B>new_best</B>, <I>rte *</I> <B>old_best</B>, <I>rte *</I> <B>before_old</B>) -- announce a routing table change
258: <P>
259: <H3>Arguments</H3>
260: <P>
261: <DL>
262: <DT><I>rtable *</I> <B>tab</B><DD><P>table the route has been added to
263: <DT><I>unsigned</I> <B>type</B><DD><P>type of route announcement (RA_OPTIMAL or RA_ANY)
264: <DT><I>net *</I> <B>net</B><DD><P>network in question
265: <DT><I>rte *</I> <B>new</B><DD><P>the new route to be announced
266: <DT><I>rte *</I> <B>old</B><DD><P>the previous route for the same network
267: <DT><I>rte *</I> <B>new_best</B><DD><P>the new best route for the same network
268: <DT><I>rte *</I> <B>old_best</B><DD><P>the previous best route for the same network
269: <DT><I>rte *</I> <B>before_old</B><DD><P>The previous route before <B>old</B> for the same network.
270: If <B>before_old</B> is NULL <B>old</B> was the first.
271: </DL>
272: <H3>Description</H3>
273: <P>This function gets a routing table update and announces it
274: to all protocols that acccepts given type of route announcement
275: and are connected to the same table by their announcement hooks.
276: <P>Route announcement of type <I>RA_OPTIMAL</I> si generated when optimal
277: route (in routing table <B>tab</B>) changes. In that case <B>old</B> stores the
278: old optimal route.
279: <P>Route announcement of type <I>RA_ANY</I> si generated when any route (in
280: routing table <B>tab</B>) changes In that case <B>old</B> stores the old route
281: from the same protocol.
282: <P>For each appropriate protocol, we first call its <B>import_control()</B>
283: hook which performs basic checks on the route (each protocol has a
284: right to veto or force accept of the route before any filter is
285: asked) and adds default values of attributes specific to the new
286: protocol (metrics, tags etc.). Then it consults the protocol's
287: export filter and if it accepts the route, the <B>rt_notify()</B> hook of
288: the protocol gets called.
289:
290:
291: <HR><H3>Function</H3>
292: <P><I>void</I>
293: <B>rte_free</B>
294: (<I>rte *</I> <B>e</B>) -- delete a <I>rte</I>
295: <P>
296: <H3>Arguments</H3>
297: <P>
298: <DL>
299: <DT><I>rte *</I> <B>e</B><DD><P><I>rte</I> to be deleted
300: </DL>
301: <H3>Description</H3>
302: <P><B>rte_free()</B> deletes the given <I>rte</I> from the routing table it's linked to.
303:
304:
305: <HR><H3>Function</H3>
306: <P><I>void</I>
307: <B>rte_update2</B>
308: (<I>struct announce_hook *</I> <B>ah</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>struct rte_src *</I> <B>src</B>) -- enter a new update to a routing table
309: <P>
310: <H3>Arguments</H3>
311: <P>
312: <DL>
313: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>pointer to table announce hook
314: <DT><I>net *</I> <B>net</B><DD><P>network node
315: <DT><I>rte *</I> <B>new</B><DD><P>a <I>rte</I> representing the new route or <I>NULL</I> for route removal.
316: <DT><I>struct rte_src *</I> <B>src</B><DD><P>protocol originating the update
317: </DL>
318: <H3>Description</H3>
319: <P>This function is called by the routing protocols whenever they discover
320: a new route or wish to update/remove an existing route. The right announcement
321: sequence is to build route attributes first (either un-cached with <B>aflags</B> set
322: to zero or a cached one using <B>rta_lookup()</B>; in this case please note that
323: you need to increase the use count of the attributes yourself by calling
324: <B>rta_clone()</B>), call <B>rte_get_temp()</B> to obtain a temporary <I>rte</I>, fill in all
325: the appropriate data and finally submit the new <I>rte</I> by calling <B>rte_update()</B>.
326: <P><B>src</B> specifies the protocol that originally created the route and the meaning
327: of protocol-dependent data of <B>new</B>. If <B>new</B> is not <I>NULL</I>, <B>src</B> have to be the
328: same value as <B>new</B>->attrs->proto. <B>p</B> specifies the protocol that called
329: <B>rte_update()</B>. In most cases it is the same protocol as <B>src</B>. <B>rte_update()</B>
330: stores <B>p</B> in <B>new</B>->sender;
331: <P>When <B>rte_update()</B> gets any route, it automatically validates it (checks,
332: whether the network and next hop address are valid IP addresses and also
333: whether a normal routing protocol doesn't try to smuggle a host or link
334: scope route to the table), converts all protocol dependent attributes stored
335: in the <I>rte</I> to temporary extended attributes, consults import filters of the
336: protocol to see if the route should be accepted and/or its attributes modified,
337: stores the temporary attributes back to the <I>rte</I>.
338: <P>Now, having a "public" version of the route, we
339: automatically find any old route defined by the protocol <B>src</B>
340: for network <B>n</B>, replace it by the new one (or removing it if <B>new</B> is <I>NULL</I>),
341: recalculate the optimal route for this destination and finally broadcast
342: the change (if any) to all routing protocols by calling <B>rte_announce()</B>.
343: <P>All memory used for attribute lists and other temporary allocations is taken
344: from a special linear pool <B>rte_update_pool</B> and freed when <B>rte_update()</B>
345: finishes.
346:
347:
348: <HR><H3>Function</H3>
349: <P><I>void</I>
350: <B>rt_refresh_begin</B>
351: (<I>rtable *</I> <B>t</B>, <I>struct announce_hook *</I> <B>ah</B>) -- start a refresh cycle
352: <P>
353: <H3>Arguments</H3>
354: <P>
355: <DL>
356: <DT><I>rtable *</I> <B>t</B><DD><P>related routing table
357: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>related announce hook
358: </DL>
359: <H3>Description</H3>
360: <P>This function starts a refresh cycle for given routing table and announce
361: hook. The refresh cycle is a sequence where the protocol sends all its valid
362: routes to the routing table (by <B>rte_update()</B>). After that, all protocol
363: routes (more precisely routes with <B>ah</B> as <B>sender</B>) not sent during the
364: refresh cycle but still in the table from the past are pruned. This is
365: implemented by marking all related routes as stale by REF_STALE flag in
366: <B>rt_refresh_begin()</B>, then marking all related stale routes with REF_DISCARD
367: flag in <B>rt_refresh_end()</B> and then removing such routes in the prune loop.
368:
369:
370: <HR><H3>Function</H3>
371: <P><I>void</I>
372: <B>rt_refresh_end</B>
373: (<I>rtable *</I> <B>t</B>, <I>struct announce_hook *</I> <B>ah</B>) -- end a refresh cycle
374: <P>
375: <H3>Arguments</H3>
376: <P>
377: <DL>
378: <DT><I>rtable *</I> <B>t</B><DD><P>related routing table
379: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>related announce hook
380: </DL>
381: <H3>Description</H3>
382: <P>This function starts a refresh cycle for given routing table and announce
383: hook. See <B>rt_refresh_begin()</B> for description of refresh cycles.
384:
385:
386: <HR><H3>Function</H3>
387: <P><I>void</I>
388: <B>rte_dump</B>
389: (<I>rte *</I> <B>e</B>) -- dump a route
390: <P>
391: <H3>Arguments</H3>
392: <P>
393: <DL>
394: <DT><I>rte *</I> <B>e</B><DD><P><I>rte</I> to be dumped
395: </DL>
396: <H3>Description</H3>
397: <P>This functions dumps contents of a <I>rte</I> to debug output.
398:
399:
400: <HR><H3>Function</H3>
401: <P><I>void</I>
402: <B>rt_dump</B>
403: (<I>rtable *</I> <B>t</B>) -- dump a routing table
404: <P>
405: <H3>Arguments</H3>
406: <P>
407: <DL>
408: <DT><I>rtable *</I> <B>t</B><DD><P>routing table to be dumped
409: </DL>
410: <H3>Description</H3>
411: <P>This function dumps contents of a given routing table to debug output.
412:
413:
414: <HR><H3>Function</H3>
415: <P><I>void</I>
416: <B>rt_dump_all</B>
417: (<B>void</B>) -- dump all routing tables
418: <P>
419: <H3>Description</H3>
420: <P>
421: <P>This function dumps contents of all routing tables to debug output.
422:
423:
424: <HR><H3>Function</H3>
425: <P><I>void</I>
426: <B>rt_init</B>
427: (<B>void</B>) -- initialize routing tables
428: <P>
429: <H3>Description</H3>
430: <P>
431: <P>This function is called during BIRD startup. It initializes the
432: routing table module.
433:
434:
435: <HR><H3>Function</H3>
436: <P><I>int</I>
437: <B>rt_prune_table</B>
438: (<I>rtable *</I> <B>tab</B>) -- prune a routing table
439: <P>
440: <H3>Arguments</H3>
441: <P>
442: <DL>
443: <DT><I>rtable *</I> <B>tab</B><DD><P>a routing table for pruning
444: </DL>
445: <H3>Description</H3>
446: <P>This function scans the routing table <B>tab</B> and removes routes belonging to
447: flushing protocols, discarded routes and also stale network entries, in a
448: similar fashion like <B>rt_prune_loop()</B>. Returns 1 when all such routes are
449: pruned. Contrary to <B>rt_prune_loop()</B>, this function is not a part of the
450: protocol flushing loop, but it is called from <B>rt_event()</B> for just one routing
451: table.
452: <P>Note that <B>rt_prune_table()</B> and <B>rt_prune_loop()</B> share (for each table) the
453: prune state (<B>prune_state</B>) and also the pruning iterator (<B>prune_fit</B>).
454:
455:
456: <HR><H3>Function</H3>
457: <P><I>int</I>
458: <B>rt_prune_loop</B>
459: (<B>void</B>) -- prune routing tables
460: <P>
461: <H3>Description</H3>
462: <P>
463: <P>The prune loop scans routing tables and removes routes belonging to flushing
464: protocols, discarded routes and also stale network entries. Returns 1 when
465: all such routes are pruned. It is a part of the protocol flushing loop.
466:
467:
468: <HR><H3>Function</H3>
469: <P><I>void</I>
470: <B>rt_lock_table</B>
471: (<I>rtable *</I> <B>r</B>) -- lock a routing table
472: <P>
473: <H3>Arguments</H3>
474: <P>
475: <DL>
476: <DT><I>rtable *</I> <B>r</B><DD><P>routing table to be locked
477: </DL>
478: <H3>Description</H3>
479: <P>Lock a routing table, because it's in use by a protocol,
480: preventing it from being freed when it gets undefined in a new
481: configuration.
482:
483:
484: <HR><H3>Function</H3>
485: <P><I>void</I>
486: <B>rt_unlock_table</B>
487: (<I>rtable *</I> <B>r</B>) -- unlock a routing table
488: <P>
489: <H3>Arguments</H3>
490: <P>
491: <DL>
492: <DT><I>rtable *</I> <B>r</B><DD><P>routing table to be unlocked
493: </DL>
494: <H3>Description</H3>
495: <P>Unlock a routing table formerly locked by <B>rt_lock_table()</B>,
496: that is decrease its use count and delete it if it's scheduled
497: for deletion by configuration changes.
498:
499:
500: <HR><H3>Function</H3>
501: <P><I>void</I>
502: <B>rt_commit</B>
503: (<I>struct config *</I> <B>new</B>, <I>struct config *</I> <B>old</B>) -- commit new routing table configuration
504: <P>
505: <H3>Arguments</H3>
506: <P>
507: <DL>
508: <DT><I>struct config *</I> <B>new</B><DD><P>new configuration
509: <DT><I>struct config *</I> <B>old</B><DD><P>original configuration or <I>NULL</I> if it's boot time config
510: </DL>
511: <H3>Description</H3>
512: <P>Scan differences between <B>old</B> and <B>new</B> configuration and modify
513: the routing tables according to these changes. If <B>new</B> defines a
514: previously unknown table, create it, if it omits a table existing
515: in <B>old</B>, schedule it for deletion (it gets deleted when all protocols
516: disconnect from it by calling <B>rt_unlock_table()</B>), if it exists
517: in both configurations, leave it unchanged.
518:
519:
520: <HR><H3>Function</H3>
521: <P><I>int</I>
522: <B>rt_feed_baby</B>
523: (<I>struct proto *</I> <B>p</B>) -- advertise routes to a new protocol
524: <P>
525: <H3>Arguments</H3>
526: <P>
527: <DL>
528: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol to be fed
529: </DL>
530: <H3>Description</H3>
531: <P>This function performs one pass of advertisement of routes to a newly
532: initialized protocol. It's called by the protocol code as long as it
533: has something to do. (We avoid transferring all the routes in single
534: pass in order not to monopolize CPU time.)
535:
536:
537: <HR><H3>Function</H3>
538: <P><I>void</I>
539: <B>rt_feed_baby_abort</B>
540: (<I>struct proto *</I> <B>p</B>) -- abort protocol feeding
541: <P>
542: <H3>Arguments</H3>
543: <P>
544: <DL>
545: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol
546: </DL>
547: <H3>Description</H3>
548: <P>This function is called by the protocol code when the protocol
549: stops or ceases to exist before the last iteration of <B>rt_feed_baby()</B>
550: has finished.
551:
552:
553: <HR><H3>Function</H3>
554: <P><I>net *</I>
555: <B>net_find</B>
556: (<I>rtable *</I> <B>tab</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>len</B>) -- find a network entry
557: <P>
558: <H3>Arguments</H3>
559: <P>
560: <DL>
561: <DT><I>rtable *</I> <B>tab</B><DD><P>a routing table
562: <DT><I>ip_addr</I> <B>addr</B><DD><P>address of the network
563: <DT><I>unsigned</I> <B>len</B><DD><P>length of the network prefix
564: </DL>
565: <H3>Description</H3>
566: <P><B>net_find()</B> looks up the given network in routing table <B>tab</B> and
567: returns a pointer to its <I>net</I> entry or <I>NULL</I> if no such network
568: exists.
569:
570:
571: <HR><H3>Function</H3>
572: <P><I>net *</I>
573: <B>net_get</B>
574: (<I>rtable *</I> <B>tab</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>len</B>) -- obtain a network entry
575: <P>
576: <H3>Arguments</H3>
577: <P>
578: <DL>
579: <DT><I>rtable *</I> <B>tab</B><DD><P>a routing table
580: <DT><I>ip_addr</I> <B>addr</B><DD><P>address of the network
581: <DT><I>unsigned</I> <B>len</B><DD><P>length of the network prefix
582: </DL>
583: <H3>Description</H3>
584: <P><B>net_get()</B> looks up the given network in routing table <B>tab</B> and
585: returns a pointer to its <I>net</I> entry. If no such entry exists, it's
586: created.
587:
588:
589: <HR><H3>Function</H3>
590: <P><I>rte *</I>
591: <B>rte_cow</B>
592: (<I>rte *</I> <B>r</B>) -- copy a route for writing
593: <P>
594: <H3>Arguments</H3>
595: <P>
596: <DL>
597: <DT><I>rte *</I> <B>r</B><DD><P>a route entry to be copied
598: </DL>
599: <H3>Description</H3>
600: <P><B>rte_cow()</B> takes a <I>rte</I> and prepares it for modification. The exact action
601: taken depends on the flags of the <I>rte</I> -- if it's a temporary entry, it's
602: just returned unchanged, else a new temporary entry with the same contents
603: is created.
604: <P>The primary use of this function is inside the filter machinery -- when
605: a filter wants to modify <I>rte</I> contents (to change the preference or to
606: attach another set of attributes), it must ensure that the <I>rte</I> is not
607: shared with anyone else (and especially that it isn't stored in any routing
608: table).
609: <H3>Result</H3>
610: <P>a pointer to the new writable <I>rte</I>.
611:
612: <H2><A NAME="ss2.3">2.3</A> <A HREF="prog.html#toc2.3">Route attribute cache</A>
613: </H2>
614:
615: <P>
616: <P>Each route entry carries a set of route attributes. Several of them
617: vary from route to route, but most attributes are usually common
618: for a large number of routes. To conserve memory, we've decided to
619: store only the varying ones directly in the <I>rte</I> and hold the rest
620: in a special structure called <I>rta</I> which is shared among all the
621: <I>rte</I>'s with these attributes.
622: <P>Each <I>rta</I> contains all the static attributes of the route (i.e.,
623: those which are always present) as structure members and a list of
624: dynamic attributes represented by a linked list of <I>ea_list</I>
625: structures, each of them consisting of an array of <I>eattr</I>'s containing
626: the individual attributes. An attribute can be specified more than once
627: in the <I>ea_list</I> chain and in such case the first occurrence overrides
628: the others. This semantics is used especially when someone (for example
629: a filter) wishes to alter values of several dynamic attributes, but
630: it wants to preserve the original attribute lists maintained by
631: another module.
632: <P>Each <I>eattr</I> contains an attribute identifier (split to protocol ID and
633: per-protocol attribute ID), protocol dependent flags, a type code (consisting
634: of several bit fields describing attribute characteristics) and either an
635: embedded 32-bit value or a pointer to a <I>adata</I> structure holding attribute
636: contents.
637: <P>There exist two variants of <I>rta</I>'s -- cached and un-cached ones. Un-cached
638: <I>rta</I>'s can have arbitrarily complex structure of <I>ea_list</I>'s and they
639: can be modified by any module in the route processing chain. Cached
640: <I>rta</I>'s have their attribute lists normalized (that means at most one
641: <I>ea_list</I> is present and its values are sorted in order to speed up
642: searching), they are stored in a hash table to make fast lookup possible
643: and they are provided with a use count to allow sharing.
644: <P>Routing tables always contain only cached <I>rta</I>'s.
645: <P>
646: <P><HR><H3>Function</H3>
647: <P><I>struct mpnh *</I>
648: <B>mpnh_merge</B>
649: (<I>struct mpnh *</I> <B>x</B>, <I>struct mpnh *</I> <B>y</B>, <I>int</I> <B>rx</B>, <I>int</I> <B>ry</B>, <I>int</I> <B>max</B>, <I>linpool *</I> <B>lp</B>) -- merge nexthop lists
650: <P>
651: <H3>Arguments</H3>
652: <P>
653: <DL>
654: <DT><I>struct mpnh *</I> <B>x</B><DD><P>list 1
655: <DT><I>struct mpnh *</I> <B>y</B><DD><P>list 2
656: <DT><I>int</I> <B>rx</B><DD><P>reusability of list <B>x</B>
657: <DT><I>int</I> <B>ry</B><DD><P>reusability of list <B>y</B>
658: <DT><I>int</I> <B>max</B><DD><P>max number of nexthops
659: <DT><I>linpool *</I> <B>lp</B><DD><P>linpool for allocating nexthops
660: </DL>
661: <H3>Description</H3>
662: <P>The <B>mpnh_merge()</B> function takes two nexthop lists <B>x</B> and <B>y</B> and merges them,
663: eliminating possible duplicates. The input lists must be sorted and the
664: result is sorted too. The number of nexthops in result is limited by <B>max</B>.
665: New nodes are allocated from linpool <B>lp</B>.
666: <P>The arguments <B>rx</B> and <B>ry</B> specify whether corresponding input lists may be
667: consumed by the function (i.e. their nodes reused in the resulting list), in
668: that case the caller should not access these lists after that. To eliminate
669: issues with deallocation of these lists, the caller should use some form of
670: bulk deallocation (e.g. stack or linpool) to free these nodes when the
671: resulting list is no longer needed. When reusability is not set, the
672: corresponding lists are not modified nor linked from the resulting list.
673:
674:
675: <HR><H3>Function</H3>
676: <P><I>eattr *</I>
677: <B>ea_find</B>
678: (<I>ea_list *</I> <B>e</B>, <I>unsigned</I> <B>id</B>) -- find an extended attribute
679: <P>
680: <H3>Arguments</H3>
681: <P>
682: <DL>
683: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list to search in
684: <DT><I>unsigned</I> <B>id</B><DD><P>attribute ID to search for
685: </DL>
686: <H3>Description</H3>
687: <P>Given an extended attribute list, <B>ea_find()</B> searches for a first
688: occurrence of an attribute with specified ID, returning either a pointer
689: to its <I>eattr</I> structure or <I>NULL</I> if no such attribute exists.
690:
691:
692: <HR><H3>Function</H3>
693: <P><I>eattr *</I>
694: <B>ea_walk</B>
695: (<I>struct ea_walk_state *</I> <B>s</B>, <I>uint</I> <B>id</B>, <I>uint</I> <B>max</B>) -- walk through extended attributes
696: <P>
697: <H3>Arguments</H3>
698: <P>
699: <DL>
700: <DT><I>struct ea_walk_state *</I> <B>s</B><DD><P>walk state structure
701: <DT><I>uint</I> <B>id</B><DD><P>start of attribute ID interval
702: <DT><I>uint</I> <B>max</B><DD><P>length of attribute ID interval
703: </DL>
704: <H3>Description</H3>
705: <P>Given an extended attribute list, <B>ea_walk()</B> walks through the list looking
706: for first occurrences of attributes with ID in specified interval from <B>id</B> to
707: (<B>id</B> + <B>max</B> - 1), returning pointers to found <I>eattr</I> structures, storing its
708: walk state in <B>s</B> for subsequent calls.
709: <P>The function <B>ea_walk()</B> is supposed to be called in a loop, with initially
710: zeroed walk state structure <B>s</B> with filled the initial extended attribute
711: list, returning one found attribute in each call or <I>NULL</I> when no other
712: attribute exists. The extended attribute list or the arguments should not be
713: modified between calls. The maximum value of <B>max</B> is 128.
714:
715:
716: <HR><H3>Function</H3>
717: <P><I>int</I>
718: <B>ea_get_int</B>
719: (<I>ea_list *</I> <B>e</B>, <I>unsigned</I> <B>id</B>, <I>int</I> <B>def</B>) -- fetch an integer attribute
720: <P>
721: <H3>Arguments</H3>
722: <P>
723: <DL>
724: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
725: <DT><I>unsigned</I> <B>id</B><DD><P>attribute ID
726: <DT><I>int</I> <B>def</B><DD><P>default value
727: </DL>
728: <H3>Description</H3>
729: <P>This function is a shortcut for retrieving a value of an integer attribute
730: by calling <B>ea_find()</B> to find the attribute, extracting its value or returning
731: a provided default if no such attribute is present.
732:
733:
734: <HR><H3>Function</H3>
735: <P><I>void</I>
736: <B>ea_sort</B>
737: (<I>ea_list *</I> <B>e</B>) -- sort an attribute list
738: <P>
739: <H3>Arguments</H3>
740: <P>
741: <DL>
742: <DT><I>ea_list *</I> <B>e</B><DD><P>list to be sorted
743: </DL>
744: <H3>Description</H3>
745: <P>This function takes a <I>ea_list</I> chain and sorts the attributes
746: within each of its entries.
747: <P>If an attribute occurs multiple times in a single <I>ea_list</I>,
748: <B>ea_sort()</B> leaves only the first (the only significant) occurrence.
749:
750:
751: <HR><H3>Function</H3>
752: <P><I>unsigned</I>
753: <B>ea_scan</B>
754: (<I>ea_list *</I> <B>e</B>) -- estimate attribute list size
755: <P>
756: <H3>Arguments</H3>
757: <P>
758: <DL>
759: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
760: </DL>
761: <H3>Description</H3>
762: <P>This function calculates an upper bound of the size of
763: a given <I>ea_list</I> after merging with <B>ea_merge()</B>.
764:
765:
766: <HR><H3>Function</H3>
767: <P><I>void</I>
768: <B>ea_merge</B>
769: (<I>ea_list *</I> <B>e</B>, <I>ea_list *</I> <B>t</B>) -- merge segments of an attribute list
770: <P>
771: <H3>Arguments</H3>
772: <P>
773: <DL>
774: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
775: <DT><I>ea_list *</I> <B>t</B><DD><P>buffer to store the result to
776: </DL>
777: <H3>Description</H3>
778: <P>This function takes a possibly multi-segment attribute list
779: and merges all of its segments to one.
780: <P>The primary use of this function is for <I>ea_list</I> normalization:
781: first call <B>ea_scan()</B> to determine how much memory will the result
782: take, then allocate a buffer (usually using <B>alloca()</B>), merge the
783: segments with <B>ea_merge()</B> and finally sort and prune the result
784: by calling <B>ea_sort()</B>.
785:
786:
787: <HR><H3>Function</H3>
788: <P><I>int</I>
789: <B>ea_same</B>
790: (<I>ea_list *</I> <B>x</B>, <I>ea_list *</I> <B>y</B>) -- compare two <I>ea_list</I>'s
791: <P>
792: <H3>Arguments</H3>
793: <P>
794: <DL>
795: <DT><I>ea_list *</I> <B>x</B><DD><P>attribute list
796: <DT><I>ea_list *</I> <B>y</B><DD><P>attribute list
797: </DL>
798: <H3>Description</H3>
799: <P><B>ea_same()</B> compares two normalized attribute lists <B>x</B> and <B>y</B> and returns
800: 1 if they contain the same attributes, 0 otherwise.
801:
802:
803: <HR><H3>Function</H3>
804: <P><I>void</I>
805: <B>ea_show</B>
806: (<I>struct cli *</I> <B>c</B>, <I>eattr *</I> <B>e</B>) -- print an <I>eattr</I> to CLI
807: <P>
808: <H3>Arguments</H3>
809: <P>
810: <DL>
811: <DT><I>struct cli *</I> <B>c</B><DD><P>destination CLI
812: <DT><I>eattr *</I> <B>e</B><DD><P>attribute to be printed
813: </DL>
814: <H3>Description</H3>
815: <P>This function takes an extended attribute represented by its <I>eattr</I>
816: structure and prints it to the CLI according to the type information.
817: <P>If the protocol defining the attribute provides its own
818: <B>get_attr()</B> hook, it's consulted first.
819:
820:
821: <HR><H3>Function</H3>
822: <P><I>void</I>
823: <B>ea_dump</B>
824: (<I>ea_list *</I> <B>e</B>) -- dump an extended attribute
825: <P>
826: <H3>Arguments</H3>
827: <P>
828: <DL>
829: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute to be dumped
830: </DL>
831: <H3>Description</H3>
832: <P><B>ea_dump()</B> dumps contents of the extended attribute given to
833: the debug output.
834:
835:
836: <HR><H3>Function</H3>
837: <P><I>uint</I>
838: <B>ea_hash</B>
839: (<I>ea_list *</I> <B>e</B>) -- calculate an <I>ea_list</I> hash key
840: <P>
841: <H3>Arguments</H3>
842: <P>
843: <DL>
844: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
845: </DL>
846: <H3>Description</H3>
847: <P><B>ea_hash()</B> takes an extended attribute list and calculated a hopefully
848: uniformly distributed hash value from its contents.
849:
850:
851: <HR><H3>Function</H3>
852: <P><I>ea_list *</I>
853: <B>ea_append</B>
854: (<I>ea_list *</I> <B>to</B>, <I>ea_list *</I> <B>what</B>) -- concatenate <I>ea_list</I>'s
855: <P>
856: <H3>Arguments</H3>
857: <P>
858: <DL>
859: <DT><I>ea_list *</I> <B>to</B><DD><P>destination list (can be <I>NULL</I>)
860: <DT><I>ea_list *</I> <B>what</B><DD><P>list to be appended (can be <I>NULL</I>)
861: </DL>
862: <H3>Description</H3>
863: <P>This function appends the <I>ea_list</I> <B>what</B> at the end of
864: <I>ea_list</I> <B>to</B> and returns a pointer to the resulting list.
865:
866:
867: <HR><H3>Function</H3>
868: <P><I>rta *</I>
869: <B>rta_lookup</B>
870: (<I>rta *</I> <B>o</B>) -- look up a <I>rta</I> in attribute cache
871: <P>
872: <H3>Arguments</H3>
873: <P>
874: <DL>
875: <DT><I>rta *</I> <B>o</B><DD><P>a un-cached <I>rta</I>
876: </DL>
877: <H3>Description</H3>
878: <P><B>rta_lookup()</B> gets an un-cached <I>rta</I> structure and returns its cached
879: counterpart. It starts with examining the attribute cache to see whether
880: there exists a matching entry. If such an entry exists, it's returned and
881: its use count is incremented, else a new entry is created with use count
882: set to 1.
883: <P>The extended attribute lists attached to the <I>rta</I> are automatically
884: converted to the normalized form.
885:
886:
887: <HR><H3>Function</H3>
888: <P><I>void</I>
889: <B>rta_dump</B>
890: (<I>rta *</I> <B>a</B>) -- dump route attributes
891: <P>
892: <H3>Arguments</H3>
893: <P>
894: <DL>
895: <DT><I>rta *</I> <B>a</B><DD><P>attribute structure to dump
896: </DL>
897: <H3>Description</H3>
898: <P>This function takes a <I>rta</I> and dumps its contents to the debug output.
899:
900:
901: <HR><H3>Function</H3>
902: <P><I>void</I>
903: <B>rta_dump_all</B>
904: (<B>void</B>) -- dump attribute cache
905: <P>
906: <H3>Description</H3>
907: <P>
908: <P>This function dumps the whole contents of route attribute cache
909: to the debug output.
910:
911:
912: <HR><H3>Function</H3>
913: <P><I>void</I>
914: <B>rta_init</B>
915: (<B>void</B>) -- initialize route attribute cache
916: <P>
917: <H3>Description</H3>
918: <P>
919: <P>This function is called during initialization of the routing
920: table module to set up the internals of the attribute cache.
921:
922:
923: <HR><H3>Function</H3>
924: <P><I>rta *</I>
925: <B>rta_clone</B>
926: (<I>rta *</I> <B>r</B>) -- clone route attributes
927: <P>
928: <H3>Arguments</H3>
929: <P>
930: <DL>
931: <DT><I>rta *</I> <B>r</B><DD><P>a <I>rta</I> to be cloned
932: </DL>
933: <H3>Description</H3>
934: <P><B>rta_clone()</B> takes a cached <I>rta</I> and returns its identical cached
935: copy. Currently it works by just returning the original <I>rta</I> with
936: its use count incremented.
937:
938:
939: <HR><H3>Function</H3>
940: <P><I>void</I>
941: <B>rta_free</B>
942: (<I>rta *</I> <B>r</B>) -- free route attributes
943: <P>
944: <H3>Arguments</H3>
945: <P>
946: <DL>
947: <DT><I>rta *</I> <B>r</B><DD><P>a <I>rta</I> to be freed
948: </DL>
949: <H3>Description</H3>
950: <P>If you stop using a <I>rta</I> (for example when deleting a route which uses
951: it), you need to call <B>rta_free()</B> to notify the attribute cache the
952: attribute is no longer in use and can be freed if you were the last
953: user (which <B>rta_free()</B> tests by inspecting the use count).
954:
955: <P>
956: <H2><A NAME="ss2.4">2.4</A> <A HREF="prog.html#toc2.4">Routing protocols</A>
957: </H2>
958:
959: <H3>Introduction</H3>
960:
961: <P>The routing protocols are the bird's heart and a fine amount of code
962: is dedicated to their management and for providing support functions to them.
963: (-: Actually, this is the reason why the directory with sources of the core
964: code is called <CODE>nest</CODE> :-).
965: <P>
966: <P>When talking about protocols, one need to distinguish between <EM>protocols</EM>
967: and protocol <EM>instances</EM>. A protocol exists exactly once, not depending on whether
968: it's configured or not and it can have an arbitrary number of instances corresponding
969: to its "incarnations" requested by the configuration file. Each instance is completely
970: autonomous, has its own configuration, its own status, its own set of routes and its
971: own set of interfaces it works on.
972: <P>
973: <P>A protocol is represented by a <I>protocol</I> structure containing all the basic
974: information (protocol name, default settings and pointers to most of the protocol
975: hooks). All these structures are linked in the <B>protocol_list</B> list.
976: <P>
977: <P>Each instance has its own <I>proto</I> structure describing all its properties: protocol
978: type, configuration, a resource pool where all resources belonging to the instance
979: live, various protocol attributes (take a look at the declaration of <I>proto</I> in
980: <CODE>protocol.h</CODE>), protocol states (see below for what do they mean), connections
981: to routing tables, filters attached to the protocol
982: and finally a set of pointers to the rest of protocol hooks (they
983: are the same for all instances of the protocol, but in order to avoid extra
984: indirections when calling the hooks from the fast path, they are stored directly
985: in <I>proto</I>). The instance is always linked in both the global instance list
986: (<B>proto_list</B>) and a per-status list (either <B>active_proto_list</B> for
987: running protocols, <B>initial_proto_list</B> for protocols being initialized or
988: <B>flush_proto_list</B> when the protocol is being shut down).
989: <P>
990: <P>The protocol hooks are described in the next chapter, for more information about
991: configuration of protocols, please refer to the configuration chapter and also
992: to the description of the <B>proto_commit</B> function.
993: <P>
994: <H3>Protocol states</H3>
995:
996: <P>As startup and shutdown of each protocol are complex processes which can be affected
997: by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.),
998: we have decided to supervise them by a pair of simple state machines -- the protocol
999: state machine and a core state machine.
1000: <P>
1001: <P>The <EM>protocol state machine</EM> corresponds to internal state of the protocol
1002: and the protocol can alter its state whenever it wants to. There are
1003: the following states:
1004: <P>
1005: <DL>
1006: <DT><CODE>PS_DOWN</CODE><DD><P>The protocol is down and waits for being woken up by calling its
1007: start() hook.
1008: <DT><CODE>PS_START</CODE><DD><P>The protocol is waiting for connection with the rest of the
1009: network. It's active, it has resources allocated, but it still doesn't want
1010: any routes since it doesn't know what to do with them.
1011: <DT><CODE>PS_UP</CODE><DD><P>The protocol is up and running. It communicates with the core,
1012: delivers routes to tables and wants to hear announcement about route changes.
1013: <DT><CODE>PS_STOP</CODE><DD><P>The protocol has been shut down (either by being asked by the
1014: core code to do so or due to having encountered a protocol error).
1015: </DL>
1016: <P>
1017: <P>Unless the protocol is in the <CODE>PS_DOWN</CODE> state, it can decide to change
1018: its state by calling the <B>proto_notify_state</B> function.
1019: <P>
1020: <P>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.
1021: <P>
1022: <P>The <EM>core state machine</EM> takes care of the core view of protocol state.
1023: The states are traversed according to changes of the protocol state machine, but
1024: sometimes the transitions are delayed if the core needs to finish some actions
1025: (for example sending of new routes to the protocol) before proceeding to the
1026: new state. There are the following core states:
1027: <P>
1028: <DL>
1029: <DT><CODE>FS_HUNGRY</CODE><DD><P>The protocol is down, it doesn't have any routes and
1030: doesn't want them.
1031: <DT><CODE>FS_FEEDING</CODE><DD><P>The protocol has reached the <CODE>PS_UP</CODE> state, but
1032: we are still busy sending the initial set of routes to it.
1033: <DT><CODE>FS_HAPPY</CODE><DD><P>The protocol is up and has complete routing information.
1034: <DT><CODE>FS_FLUSHING</CODE><DD><P>The protocol is shutting down (it's in either <CODE>PS_STOP</CODE>
1035: or <CODE>PS_DOWN</CODE> state) and we're flushing all of its routes from the
1036: routing tables.
1037: </DL>
1038: <P>
1039: <H3>Functions of the protocol module</H3>
1040:
1041: <P>The protocol module provides the following functions:
1042: <HR><H3>Function</H3>
1043: <P><I>void *</I>
1044: <B>proto_new</B>
1045: (<I>struct proto_config *</I> <B>c</B>, <I>unsigned</I> <B>size</B>) -- create a new protocol instance
1046: <P>
1047: <H3>Arguments</H3>
1048: <P>
1049: <DL>
1050: <DT><I>struct proto_config *</I> <B>c</B><DD><P>protocol configuration
1051: <DT><I>unsigned</I> <B>size</B><DD><P>size of protocol data structure (each protocol instance is represented by
1052: a structure starting with generic part [struct <I>proto</I>] and continued
1053: with data specific to the protocol)
1054: </DL>
1055: <H3>Description</H3>
1056: <P>When a new configuration has been read in, the core code starts
1057: initializing all the protocol instances configured by calling their
1058: <B>init()</B> hooks with the corresponding instance configuration. The initialization
1059: code of the protocol is expected to create a new instance according to the
1060: configuration by calling this function and then modifying the default settings
1061: to values wanted by the protocol.
1062:
1063:
1064: <HR><H3>Function</H3>
1065: <P><I>struct announce_hook *</I>
1066: <B>proto_add_announce_hook</B>
1067: (<I>struct proto *</I> <B>p</B>, <I>struct rtable *</I> <B>t</B>, <I>struct proto_stats *</I> <B>stats</B>) -- connect protocol to a routing table
1068: <P>
1069: <H3>Arguments</H3>
1070: <P>
1071: <DL>
1072: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1073: <DT><I>struct rtable *</I> <B>t</B><DD><P>routing table to connect to
1074: <DT><I>struct proto_stats *</I> <B>stats</B><DD><P>per-table protocol statistics
1075: </DL>
1076: <H3>Description</H3>
1077: <P>This function creates a connection between the protocol instance <B>p</B> and the
1078: routing table <B>t</B>, making the protocol hear all changes in the table.
1079: <P>The announce hook is linked in the protocol ahook list. Announce hooks are
1080: allocated from the routing table resource pool and when protocol accepts
1081: routes also in the table ahook list. The are linked to the table ahook list
1082: and unlinked from it depending on export_state (in <B>proto_want_export_up()</B> and
1083: <B>proto_want_export_down()</B>) and they are automatically freed after the protocol
1084: is flushed (in <B>proto_fell_down()</B>).
1085: <P>Unless you want to listen to multiple routing tables (as the Pipe protocol
1086: does), you needn't to worry about this function since the connection to the
1087: protocol's primary routing table is initialized automatically by the core
1088: code.
1089:
1090:
1091: <HR><H3>Function</H3>
1092: <P><I>struct announce_hook *</I>
1093: <B>proto_find_announce_hook</B>
1094: (<I>struct proto *</I> <B>p</B>, <I>struct rtable *</I> <B>t</B>) -- find announce hooks
1095: <P>
1096: <H3>Arguments</H3>
1097: <P>
1098: <DL>
1099: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1100: <DT><I>struct rtable *</I> <B>t</B><DD><P>routing table
1101: </DL>
1102: <H3>Description</H3>
1103: <P>Returns pointer to announce hook or NULL
1104:
1105:
1106: <HR><H3>Function</H3>
1107: <P><I>void *</I>
1108: <B>proto_config_new</B>
1109: (<I>struct protocol *</I> <B>pr</B>, <I>int</I> <B>class</B>) -- create a new protocol configuration
1110: <P>
1111: <H3>Arguments</H3>
1112: <P>
1113: <DL>
1114: <DT><I>struct protocol *</I> <B>pr</B><DD><P>protocol the configuration will belong to
1115: <DT><I>int</I> <B>class</B><DD><P>SYM_PROTO or SYM_TEMPLATE
1116: </DL>
1117: <H3>Description</H3>
1118: <P>Whenever the configuration file says that a new instance
1119: of a routing protocol should be created, the parser calls
1120: <B>proto_config_new()</B> to create a configuration entry for this
1121: instance (a structure staring with the <I>proto_config</I> header
1122: containing all the generic items followed by protocol-specific
1123: ones). Also, the configuration entry gets added to the list
1124: of protocol instances kept in the configuration.
1125: <P>The function is also used to create protocol templates (when class
1126: SYM_TEMPLATE is specified), the only difference is that templates
1127: are not added to the list of protocol instances and therefore not
1128: initialized during <B>protos_commit()</B>).
1129:
1130:
1131: <HR><H3>Function</H3>
1132: <P><I>void</I>
1133: <B>proto_copy_config</B>
1134: (<I>struct proto_config *</I> <B>dest</B>, <I>struct proto_config *</I> <B>src</B>) -- copy a protocol configuration
1135: <P>
1136: <H3>Arguments</H3>
1137: <P>
1138: <DL>
1139: <DT><I>struct proto_config *</I> <B>dest</B><DD><P>destination protocol configuration
1140: <DT><I>struct proto_config *</I> <B>src</B><DD><P>source protocol configuration
1141: </DL>
1142: <H3>Description</H3>
1143: <P>Whenever a new instance of a routing protocol is created from the
1144: template, <B>proto_copy_config()</B> is called to copy a content of
1145: the source protocol configuration to the new protocol configuration.
1146: Name, class and a node in protos list of <B>dest</B> are kept intact.
1147: <B>copy_config()</B> protocol hook is used to copy protocol-specific data.
1148:
1149:
1150: <HR><H3>Function</H3>
1151: <P><I>void</I>
1152: <B>protos_preconfig</B>
1153: (<I>struct config *</I> <B>c</B>) -- pre-configuration processing
1154: <P>
1155: <H3>Arguments</H3>
1156: <P>
1157: <DL>
1158: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
1159: </DL>
1160: <H3>Description</H3>
1161: <P>This function calls the <B>preconfig()</B> hooks of all routing
1162: protocols available to prepare them for reading of the new
1163: configuration.
1164:
1165:
1166: <HR><H3>Function</H3>
1167: <P><I>void</I>
1168: <B>protos_postconfig</B>
1169: (<I>struct config *</I> <B>c</B>) -- post-configuration processing
1170: <P>
1171: <H3>Arguments</H3>
1172: <P>
1173: <DL>
1174: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
1175: </DL>
1176: <H3>Description</H3>
1177: <P>This function calls the <B>postconfig()</B> hooks of all protocol
1178: instances specified in configuration <B>c</B>. The hooks are not
1179: called for protocol templates.
1180:
1181:
1182: <HR><H3>Function</H3>
1183: <P><I>void</I>
1184: <B>protos_commit</B>
1185: (<I>struct config *</I> <B>new</B>, <I>struct config *</I> <B>old</B>, <I>int</I> <B>force_reconfig</B>, <I>int</I> <B>type</B>) -- commit new protocol configuration
1186: <P>
1187: <H3>Arguments</H3>
1188: <P>
1189: <DL>
1190: <DT><I>struct config *</I> <B>new</B><DD><P>new configuration
1191: <DT><I>struct config *</I> <B>old</B><DD><P>old configuration or <I>NULL</I> if it's boot time config
1192: <DT><I>int</I> <B>force_reconfig</B><DD><P>force restart of all protocols (used for example
1193: when the router ID changes)
1194: <DT><I>int</I> <B>type</B><DD><P>type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)
1195: </DL>
1196: <H3>Description</H3>
1197: <P>Scan differences between <B>old</B> and <B>new</B> configuration and adjust all
1198: protocol instances to conform to the new configuration.
1199: <P>When a protocol exists in the new configuration, but it doesn't in the
1200: original one, it's immediately started. When a collision with the other
1201: running protocol would arise, the new protocol will be temporarily stopped
1202: by the locking mechanism.
1203: <P>When a protocol exists in the old configuration, but it doesn't in the
1204: new one, it's shut down and deleted after the shutdown completes.
1205: <P>When a protocol exists in both configurations, the core decides
1206: whether it's possible to reconfigure it dynamically - it checks all
1207: the core properties of the protocol (changes in filters are ignored
1208: if type is RECONFIG_SOFT) and if they match, it asks the
1209: <B>reconfigure()</B> hook of the protocol to see if the protocol is able
1210: to switch to the new configuration. If it isn't possible, the
1211: protocol is shut down and a new instance is started with the new
1212: configuration after the shutdown is completed.
1213:
1214: <H2><A NAME="ss2.5">2.5</A> <A HREF="prog.html#toc2.5">Graceful restart recovery</A>
1215: </H2>
1216:
1217: <P>
1218: <P>Graceful restart of a router is a process when the routing plane (e.g. BIRD)
1219: restarts but both the forwarding plane (e.g kernel routing table) and routing
1220: neighbors keep proper routes, and therefore uninterrupted packet forwarding
1221: is maintained.
1222: <P>BIRD implements graceful restart recovery by deferring export of routes to
1223: protocols until routing tables are refilled with the expected content. After
1224: start, protocols generate routes as usual, but routes are not propagated to
1225: them, until protocols report that they generated all routes. After that,
1226: graceful restart recovery is finished and the export (and the initial feed)
1227: to protocols is enabled.
1228: <P>When graceful restart recovery need is detected during initialization, then
1229: enabled protocols are marked with <B>gr_recovery</B> flag before start. Such
1230: protocols then decide how to proceed with graceful restart, participation is
1231: voluntary. Protocols could lock the recovery by <B>proto_graceful_restart_lock()</B>
1232: (stored in <B>gr_lock</B> flag), which means that they want to postpone the end of
1233: the recovery until they converge and then unlock it. They also could set
1234: <B>gr_wait</B> before advancing to <I>PS_UP</I>, which means that the core should defer
1235: route export to that protocol until the end of the recovery. This should be
1236: done by protocols that expect their neigbors to keep the proper routes
1237: (kernel table, BGP sessions with BGP graceful restart capability).
1238: <P>The graceful restart recovery is finished when either all graceful restart
1239: locks are unlocked or when graceful restart wait timer fires.
1240: <P>
1241: <P><HR><H3>Function</H3>
1242: <P><I>void</I>
1243: <B>graceful_restart_recovery</B>
1244: (<B>void</B>) -- request initial graceful restart recovery
1245: <P>
1246: <H3>Graceful restart recovery</H3>
1247: <P>
1248: <P>Called by the platform initialization code if the need for recovery
1249: after graceful restart is detected during boot. Have to be called
1250: before <B>protos_commit()</B>.
1251:
1252:
1253: <HR><H3>Function</H3>
1254: <P><I>void</I>
1255: <B>graceful_restart_init</B>
1256: (<B>void</B>) -- initialize graceful restart
1257: <P>
1258: <H3>Description</H3>
1259: <P>
1260: <P>When graceful restart recovery was requested, the function starts an active
1261: phase of the recovery and initializes graceful restart wait timer. The
1262: function have to be called after <B>protos_commit()</B>.
1263:
1264:
1265: <HR><H3>Function</H3>
1266: <P><I>void</I>
1267: <B>graceful_restart_done</B>
1268: (<I>struct timer *t</I> <B>UNUSED</B>) -- finalize graceful restart
1269: <P>
1270: <H3>Arguments</H3>
1271: <P>
1272: <DL>
1273: <DT><I>struct timer *t</I> <B>UNUSED</B><DD><P>-- undescribed --
1274: </DL>
1275: <H3>Description</H3>
1276: <P>When there are no locks on graceful restart, the functions finalizes the
1277: graceful restart recovery. Protocols postponing route export until the end of
1278: the recovery are awakened and the export to them is enabled. All other
1279: related state is cleared. The function is also called when the graceful
1280: restart wait timer fires (but there are still some locks).
1281:
1282:
1283: <HR><H3>Function</H3>
1284: <P><I>void</I>
1285: <B>proto_graceful_restart_lock</B>
1286: (<I>struct proto *</I> <B>p</B>) -- lock graceful restart by protocol
1287: <P>
1288: <H3>Arguments</H3>
1289: <P>
1290: <DL>
1291: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1292: </DL>
1293: <H3>Description</H3>
1294: <P>This function allows a protocol to postpone the end of graceful restart
1295: recovery until it converges. The lock is removed when the protocol calls
1296: <B>proto_graceful_restart_unlock()</B> or when the protocol is stopped.
1297: <P>The function have to be called during the initial phase of graceful restart
1298: recovery and only for protocols that are part of graceful restart (i.e. their
1299: <B>gr_recovery</B> is set), which means it should be called from protocol start
1300: hooks.
1301:
1302:
1303: <HR><H3>Function</H3>
1304: <P><I>void</I>
1305: <B>proto_graceful_restart_unlock</B>
1306: (<I>struct proto *</I> <B>p</B>) -- unlock graceful restart by protocol
1307: <P>
1308: <H3>Arguments</H3>
1309: <P>
1310: <DL>
1311: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1312: </DL>
1313: <H3>Description</H3>
1314: <P>This function unlocks a lock from <B>proto_graceful_restart_lock()</B>. It is also
1315: automatically called when the lock holding protocol went down.
1316:
1317:
1318: <HR><H3>Function</H3>
1319: <P><I>void</I>
1320: <B>protos_dump_all</B>
1321: (<B>void</B>) -- dump status of all protocols
1322: <P>
1323: <H3>Description</H3>
1324: <P>
1325: <P>This function dumps status of all existing protocol instances to the
1326: debug output. It involves printing of general status information
1327: such as protocol states, its position on the protocol lists
1328: and also calling of a <B>dump()</B> hook of the protocol to print
1329: the internals.
1330:
1331:
1332: <HR><H3>Function</H3>
1333: <P><I>void</I>
1334: <B>proto_build</B>
1335: (<I>struct protocol *</I> <B>p</B>) -- make a single protocol available
1336: <P>
1337: <H3>Arguments</H3>
1338: <P>
1339: <DL>
1340: <DT><I>struct protocol *</I> <B>p</B><DD><P>the protocol
1341: </DL>
1342: <H3>Description</H3>
1343: <P>After the platform specific initialization code uses <B>protos_build()</B>
1344: to add all the standard protocols, it should call <B>proto_build()</B> for
1345: all platform specific protocols to inform the core that they exist.
1346:
1347:
1348: <HR><H3>Function</H3>
1349: <P><I>void</I>
1350: <B>protos_build</B>
1351: (<B>void</B>) -- build a protocol list
1352: <P>
1353: <H3>Description</H3>
1354: <P>
1355: <P>This function is called during BIRD startup to insert
1356: all standard protocols to the global protocol list. Insertion
1357: of platform specific protocols (such as the kernel syncer)
1358: is in the domain of competence of the platform dependent
1359: startup code.
1360:
1361:
1362: <HR><H3>Function</H3>
1363: <P><I>void</I>
1.1.1.2 ! misho 1364: <B>proto_set_message</B>
! 1365: (<I>struct proto *</I> <B>p</B>, <I>char *</I> <B>msg</B>, <I>int</I> <B>len</B>) -- set administrative message to protocol
! 1366: <P>
! 1367: <H3>Arguments</H3>
! 1368: <P>
! 1369: <DL>
! 1370: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol
! 1371: <DT><I>char *</I> <B>msg</B><DD><P>message
! 1372: <DT><I>int</I> <B>len</B><DD><P>message length (-1 for NULL-terminated string)
! 1373: </DL>
! 1374: <H3>Description</H3>
! 1375: <P>The function sets administrative message (string) related to protocol state
! 1376: change. It is called by the nest code for manual enable/disable/restart
! 1377: commands all routes to the protocol, and by protocol-specific code when the
! 1378: protocol state change is initiated by the protocol. Using NULL message clears
! 1379: the last message. The message string may be either NULL-terminated or with an
! 1380: explicit length.
! 1381:
! 1382:
! 1383: <HR><H3>Function</H3>
! 1384: <P><I>void</I>
1.1 misho 1385: <B>proto_request_feeding</B>
1386: (<I>struct proto *</I> <B>p</B>) -- request feeding routes to the protocol
1387: <P>
1388: <H3>Arguments</H3>
1389: <P>
1390: <DL>
1391: <DT><I>struct proto *</I> <B>p</B><DD><P>given protocol
1392: </DL>
1393: <H3>Description</H3>
1394: <P>Sometimes it is needed to send again all routes to the
1395: protocol. This is called feeding and can be requested by this
1396: function. This would cause protocol export state transition
1397: to ES_FEEDING (during feeding) and when completed, it will
1398: switch back to ES_READY. This function can be called even
1399: when feeding is already running, in that case it is restarted.
1400:
1401:
1402: <HR><H3>Function</H3>
1403: <P><I>void</I>
1404: <B>proto_notify_limit</B>
1405: (<I>struct announce_hook *</I> <B>ah</B>, <I>struct proto_limit *</I> <B>l</B>, <I>int</I> <B>dir</B>, <I>u32</I> <B>rt_count</B>)
1406: <H3>Arguments</H3>
1407: <P>
1408: <DL>
1409: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>announce hook
1410: <DT><I>struct proto_limit *</I> <B>l</B><DD><P>limit being hit
1411: <DT><I>int</I> <B>dir</B><DD><P>limit direction (PLD_*)
1412: <DT><I>u32</I> <B>rt_count</B><DD><P>the number of routes
1413: </DL>
1414: <H3>Description</H3>
1415: <P>The function is called by the route processing core when limit <B>l</B>
1416: is breached. It activates the limit and tooks appropriate action
1417: according to <B>l</B>->action.
1418:
1419:
1420: <HR><H3>Function</H3>
1421: <P><I>void</I>
1422: <B>proto_notify_state</B>
1423: (<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>ps</B>) -- notify core about protocol state change
1424: <P>
1425: <H3>Arguments</H3>
1426: <P>
1427: <DL>
1428: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol the state of which has changed
1429: <DT><I>unsigned</I> <B>ps</B><DD><P>the new status
1430: </DL>
1431: <H3>Description</H3>
1432: <P>Whenever a state of a protocol changes due to some event internal
1433: to the protocol (i.e., not inside a <B>start()</B> or <B>shutdown()</B> hook),
1434: it should immediately notify the core about the change by calling
1435: <B>proto_notify_state()</B> which will write the new state to the <I>proto</I>
1436: structure and take all the actions necessary to adapt to the new
1437: state. State change to PS_DOWN immediately frees resources of protocol
1438: and might execute start callback of protocol; therefore,
1439: it should be used at tail positions of protocol callbacks.
1440:
1441: <H2><A NAME="ss2.6">2.6</A> <A HREF="prog.html#toc2.6">Protocol hooks</A>
1442: </H2>
1443:
1444: <P>
1445: <P>Each protocol can provide a rich set of hook functions referred to by pointers
1446: in either the <I>proto</I> or <I>protocol</I> structure. They are called by the core whenever
1447: it wants the protocol to perform some action or to notify the protocol about
1448: any change of its environment. All of the hooks can be set to <I>NULL</I> which means
1449: to ignore the change or to take a default action.
1450: <P>
1451: <P><HR><H3>Function</H3>
1452: <P><I>void</I>
1453: <B>preconfig</B>
1454: (<I>struct protocol *</I> <B>p</B>, <I>struct config *</I> <B>c</B>) -- protocol preconfiguration
1455: <P>
1456: <H3>Arguments</H3>
1457: <P>
1458: <DL>
1459: <DT><I>struct protocol *</I> <B>p</B><DD><P>a routing protocol
1460: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
1461: </DL>
1462: <H3>Description</H3>
1463: <P>The <B>preconfig()</B> hook is called before parsing of a new configuration.
1464:
1465:
1466: <HR><H3>Function</H3>
1467: <P><I>void</I>
1468: <B>postconfig</B>
1469: (<I>struct proto_config *</I> <B>c</B>) -- instance post-configuration
1470: <P>
1471: <H3>Arguments</H3>
1472: <P>
1473: <DL>
1474: <DT><I>struct proto_config *</I> <B>c</B><DD><P>instance configuration
1475: </DL>
1476: <H3>Description</H3>
1477: <P>The <B>postconfig()</B> hook is called for each configured instance after
1478: parsing of the new configuration is finished.
1479:
1480:
1481: <HR><H3>Function</H3>
1482: <P><I>struct proto *</I>
1483: <B>init</B>
1484: (<I>struct proto_config *</I> <B>c</B>) -- initialize an instance
1485: <P>
1486: <H3>Arguments</H3>
1487: <P>
1488: <DL>
1489: <DT><I>struct proto_config *</I> <B>c</B><DD><P>instance configuration
1490: </DL>
1491: <H3>Description</H3>
1492: <P>The <B>init()</B> hook is called by the core to create a protocol instance
1493: according to supplied protocol configuration.
1494: <H3>Result</H3>
1495: <P>a pointer to the instance created
1496:
1497:
1498: <HR><H3>Function</H3>
1499: <P><I>int</I>
1500: <B>reconfigure</B>
1501: (<I>struct proto *</I> <B>p</B>, <I>struct proto_config *</I> <B>c</B>) -- request instance reconfiguration
1502: <P>
1503: <H3>Arguments</H3>
1504: <P>
1505: <DL>
1506: <DT><I>struct proto *</I> <B>p</B><DD><P>an instance
1507: <DT><I>struct proto_config *</I> <B>c</B><DD><P>new configuration
1508: </DL>
1509: <H3>Description</H3>
1510: <P>The core calls the <B>reconfigure()</B> hook whenever it wants to ask the
1511: protocol for switching to a new configuration. If the reconfiguration
1512: is possible, the hook returns 1. Otherwise, it returns 0 and the core
1513: will shut down the instance and start a new one with the new configuration.
1514: <P>After the protocol confirms reconfiguration, it must no longer keep any
1515: references to the old configuration since the memory it's stored in can
1516: be re-used at any time.
1517:
1518:
1519: <HR><H3>Function</H3>
1520: <P><I>void</I>
1521: <B>dump</B>
1522: (<I>struct proto *</I> <B>p</B>) -- dump protocol state
1523: <P>
1524: <H3>Arguments</H3>
1525: <P>
1526: <DL>
1527: <DT><I>struct proto *</I> <B>p</B><DD><P>an instance
1528: </DL>
1529: <H3>Description</H3>
1530: <P>This hook dumps the complete state of the instance to the
1531: debug output.
1532:
1533:
1534: <HR><H3>Function</H3>
1535: <P><I>void</I>
1536: <B>dump_attrs</B>
1537: (<I>rte *</I> <B>e</B>) -- dump protocol-dependent attributes
1538: <P>
1539: <H3>Arguments</H3>
1540: <P>
1541: <DL>
1542: <DT><I>rte *</I> <B>e</B><DD><P>a route entry
1543: </DL>
1544: <H3>Description</H3>
1545: <P>This hook dumps all attributes in the <I>rte</I> which belong to this
1546: protocol to the debug output.
1547:
1548:
1549: <HR><H3>Function</H3>
1550: <P><I>int</I>
1551: <B>start</B>
1552: (<I>struct proto *</I> <B>p</B>) -- request instance startup
1553: <P>
1554: <H3>Arguments</H3>
1555: <P>
1556: <DL>
1557: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1558: </DL>
1559: <H3>Description</H3>
1560: <P>The <B>start()</B> hook is called by the core when it wishes to start
1561: the instance. Multitable protocols should lock their tables here.
1562: <H3>Result</H3>
1563: <P>new protocol state
1564:
1565:
1566: <HR><H3>Function</H3>
1567: <P><I>int</I>
1568: <B>shutdown</B>
1569: (<I>struct proto *</I> <B>p</B>) -- request instance shutdown
1570: <P>
1571: <H3>Arguments</H3>
1572: <P>
1573: <DL>
1574: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1575: </DL>
1576: <H3>Description</H3>
1577: <P>The <B>stop()</B> hook is called by the core when it wishes to shut
1578: the instance down for some reason.
1579: <H3>Returns</H3>
1580: <P>new protocol state
1581:
1582:
1583: <HR><H3>Function</H3>
1584: <P><I>void</I>
1585: <B>cleanup</B>
1586: (<I>struct proto *</I> <B>p</B>) -- request instance cleanup
1587: <P>
1588: <H3>Arguments</H3>
1589: <P>
1590: <DL>
1591: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1592: </DL>
1593: <H3>Description</H3>
1594: <P>The <B>cleanup()</B> hook is called by the core when the protocol became
1595: hungry/down, i.e. all protocol ahooks and routes are flushed.
1596: Multitable protocols should unlock their tables here.
1597:
1598:
1599: <HR><H3>Function</H3>
1600: <P><I>void</I>
1601: <B>get_status</B>
1602: (<I>struct proto *</I> <B>p</B>, <I>byte *</I> <B>buf</B>) -- get instance status
1603: <P>
1604: <H3>Arguments</H3>
1605: <P>
1606: <DL>
1607: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1608: <DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with the status string
1609: </DL>
1610: <H3>Description</H3>
1611: <P>This hook is called by the core if it wishes to obtain an brief one-line user friendly
1612: representation of the status of the instance to be printed by the <cf/show protocols/
1613: command.
1614:
1615:
1616: <HR><H3>Function</H3>
1617: <P><I>void</I>
1618: <B>get_route_info</B>
1619: (<I>rte *</I> <B>e</B>, <I>byte *</I> <B>buf</B>, <I>ea_list *</I> <B>attrs</B>) -- get route information
1620: <P>
1621: <H3>Arguments</H3>
1622: <P>
1623: <DL>
1624: <DT><I>rte *</I> <B>e</B><DD><P>a route entry
1625: <DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with the resulting string
1626: <DT><I>ea_list *</I> <B>attrs</B><DD><P>extended attributes of the route
1627: </DL>
1628: <H3>Description</H3>
1629: <P>This hook is called to fill the buffer <B>buf</B> with a brief user friendly
1630: representation of metrics of a route belonging to this protocol.
1631:
1632:
1633: <HR><H3>Function</H3>
1634: <P><I>int</I>
1635: <B>get_attr</B>
1636: (<I>eattr *</I> <B>a</B>, <I>byte *</I> <B>buf</B>, <I>int</I> <B>buflen</B>) -- get attribute information
1637: <P>
1638: <H3>Arguments</H3>
1639: <P>
1640: <DL>
1641: <DT><I>eattr *</I> <B>a</B><DD><P>an extended attribute
1642: <DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with attribute information
1643: <DT><I>int</I> <B>buflen</B><DD><P>a length of the <B>buf</B> parameter
1644: </DL>
1645: <H3>Description</H3>
1646: <P>The <B>get_attr()</B> hook is called by the core to obtain a user friendly
1647: representation of an extended route attribute. It can either leave
1648: the whole conversion to the core (by returning <I>GA_UNKNOWN</I>), fill
1649: in only attribute name (and let the core format the attribute value
1650: automatically according to the type field; by returning <I>GA_NAME</I>)
1651: or doing the whole conversion (used in case the value requires extra
1652: care; return <I>GA_FULL</I>).
1653:
1654:
1655: <HR><H3>Function</H3>
1656: <P><I>void</I>
1657: <B>if_notify</B>
1658: (<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>flags</B>, <I>struct iface *</I> <B>i</B>) -- notify instance about interface changes
1659: <P>
1660: <H3>Arguments</H3>
1661: <P>
1662: <DL>
1663: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1664: <DT><I>unsigned</I> <B>flags</B><DD><P>interface change flags
1665: <DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question
1666: </DL>
1667: <H3>Description</H3>
1668: <P>This hook is called whenever any network interface changes its status.
1669: The change is described by a combination of status bits (<I>IF_CHANGE_xxx</I>)
1670: in the <B>flags</B> parameter.
1671:
1672:
1673: <HR><H3>Function</H3>
1674: <P><I>void</I>
1675: <B>ifa_notify</B>
1676: (<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>flags</B>, <I>struct ifa *</I> <B>a</B>) -- notify instance about interface address changes
1677: <P>
1678: <H3>Arguments</H3>
1679: <P>
1680: <DL>
1681: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1682: <DT><I>unsigned</I> <B>flags</B><DD><P>address change flags
1683: <DT><I>struct ifa *</I> <B>a</B><DD><P>the interface address
1684: </DL>
1685: <H3>Description</H3>
1686: <P>This hook is called to notify the protocol instance about an interface
1687: acquiring or losing one of its addresses. The change is described by
1688: a combination of status bits (<I>IF_CHANGE_xxx</I>) in the <B>flags</B> parameter.
1689:
1690:
1691: <HR><H3>Function</H3>
1692: <P><I>void</I>
1693: <B>rt_notify</B>
1694: (<I>struct proto *</I> <B>p</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>, <I>ea_list *</I> <B>attrs</B>) -- notify instance about routing table change
1695: <P>
1696: <H3>Arguments</H3>
1697: <P>
1698: <DL>
1699: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
1700: <DT><I>net *</I> <B>net</B><DD><P>a network entry
1701: <DT><I>rte *</I> <B>new</B><DD><P>new route for the network
1702: <DT><I>rte *</I> <B>old</B><DD><P>old route for the network
1703: <DT><I>ea_list *</I> <B>attrs</B><DD><P>extended attributes associated with the <B>new</B> entry
1704: </DL>
1705: <H3>Description</H3>
1706: <P>The <B>rt_notify()</B> hook is called to inform the protocol instance about
1707: changes in the connected routing table <B>table</B>, that is a route <B>old</B>
1708: belonging to network <B>net</B> being replaced by a new route <B>new</B> with
1709: extended attributes <B>attrs</B>. Either <B>new</B> or <B>old</B> or both can be <I>NULL</I>
1710: if the corresponding route doesn't exist.
1711: <P>If the type of route announcement is RA_OPTIMAL, it is an
1712: announcement of optimal route change, <B>new</B> stores the new optimal
1713: route and <B>old</B> stores the old optimal route.
1714: <P>If the type of route announcement is RA_ANY, it is an announcement
1715: of any route change, <B>new</B> stores the new route and <B>old</B> stores the
1716: old route from the same protocol.
1717: <P><B>p</B>->accept_ra_types specifies which kind of route announcements
1718: protocol wants to receive.
1719:
1720:
1721: <HR><H3>Function</H3>
1722: <P><I>void</I>
1723: <B>neigh_notify</B>
1724: (<I>neighbor *</I> <B>neigh</B>) -- notify instance about neighbor status change
1725: <P>
1726: <H3>Arguments</H3>
1727: <P>
1728: <DL>
1729: <DT><I>neighbor *</I> <B>neigh</B><DD><P>a neighbor cache entry
1730: </DL>
1731: <H3>Description</H3>
1732: <P>The <B>neigh_notify()</B> hook is called by the neighbor cache whenever
1733: a neighbor changes its state, that is it gets disconnected or a
1734: sticky neighbor gets connected.
1735:
1736:
1737: <HR><H3>Function</H3>
1738: <P><I>ea_list *</I>
1739: <B>make_tmp_attrs</B>
1740: (<I>rte *</I> <B>e</B>, <I>struct linpool *</I> <B>pool</B>) -- convert embedded attributes to temporary ones
1741: <P>
1742: <H3>Arguments</H3>
1743: <P>
1744: <DL>
1745: <DT><I>rte *</I> <B>e</B><DD><P>route entry
1746: <DT><I>struct linpool *</I> <B>pool</B><DD><P>linear pool to allocate attribute memory in
1747: </DL>
1748: <H3>Description</H3>
1749: <P>This hook is called by the routing table functions if they need
1750: to convert the protocol attributes embedded directly in the <I>rte</I>
1751: to temporary extended attributes in order to distribute them
1752: to other protocols or to filters. <B>make_tmp_attrs()</B> creates
1753: an <I>ea_list</I> in the linear pool <B>pool</B>, fills it with values of the
1754: temporary attributes and returns a pointer to it.
1755:
1756:
1757: <HR><H3>Function</H3>
1758: <P><I>void</I>
1759: <B>store_tmp_attrs</B>
1760: (<I>rte *</I> <B>e</B>, <I>ea_list *</I> <B>attrs</B>) -- convert temporary attributes to embedded ones
1761: <P>
1762: <H3>Arguments</H3>
1763: <P>
1764: <DL>
1765: <DT><I>rte *</I> <B>e</B><DD><P>route entry
1766: <DT><I>ea_list *</I> <B>attrs</B><DD><P>temporary attributes to be converted
1767: </DL>
1768: <H3>Description</H3>
1769: <P>This hook is an exact opposite of <B>make_tmp_attrs()</B> -- it takes
1770: a list of extended attributes and converts them to attributes
1771: embedded in the <I>rte</I> corresponding to this protocol.
1772: <P>You must be prepared for any of the attributes being missing
1773: from the list and use default values instead.
1774:
1775:
1776: <HR><H3>Function</H3>
1777: <P><I>int</I>
1778: <B>import_control</B>
1779: (<I>struct proto *</I> <B>p</B>, <I>rte **</I> <B>e</B>, <I>ea_list **</I> <B>attrs</B>, <I>struct linpool *</I> <B>pool</B>) -- pre-filtering decisions on route import
1780: <P>
1781: <H3>Arguments</H3>
1782: <P>
1783: <DL>
1784: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance the route is going to be imported to
1785: <DT><I>rte **</I> <B>e</B><DD><P>the route in question
1786: <DT><I>ea_list **</I> <B>attrs</B><DD><P>extended attributes of the route
1787: <DT><I>struct linpool *</I> <B>pool</B><DD><P>linear pool for allocation of all temporary data
1788: </DL>
1789: <H3>Description</H3>
1790: <P>The <B>import_control()</B> hook is called as the first step of a exporting
1791: a route from a routing table to the protocol instance. It can modify
1792: route attributes and force acceptance or rejection of the route regardless
1793: of user-specified filters. See <B>rte_announce()</B> for a complete description
1794: of the route distribution process.
1795: <P>The standard use of this hook is to reject routes having originated
1796: from the same instance and to set default values of the protocol's metrics.
1797: <H3>Result</H3>
1798: <P>1 if the route has to be accepted, -1 if rejected and 0 if it
1799: should be passed to the filters.
1800:
1801:
1802: <HR><H3>Function</H3>
1803: <P><I>int</I>
1804: <B>rte_recalculate</B>
1805: (<I>struct rtable *</I> <B>table</B>, <I>struct network *</I> <B>net</B>, <I>struct rte *</I> <B>new</B>, <I>struct rte *</I> <B>old</B>, <I>struct rte *</I> <B>old_best</B>) -- prepare routes for comparison
1806: <P>
1807: <H3>Arguments</H3>
1808: <P>
1809: <DL>
1810: <DT><I>struct rtable *</I> <B>table</B><DD><P>a routing table
1811: <DT><I>struct network *</I> <B>net</B><DD><P>a network entry
1812: <DT><I>struct rte *</I> <B>new</B><DD><P>new route for the network
1813: <DT><I>struct rte *</I> <B>old</B><DD><P>old route for the network
1814: <DT><I>struct rte *</I> <B>old_best</B><DD><P>old best route for the network (may be NULL)
1815: </DL>
1816: <H3>Description</H3>
1817: <P>This hook is called when a route change (from <B>old</B> to <B>new</B> for a
1818: <B>net</B> entry) is propagated to a <B>table</B>. It may be used to prepare
1819: routes for comparison by <B>rte_better()</B> in the best route
1820: selection. <B>new</B> may or may not be in <B>net</B>->routes list,
1821: <B>old</B> is not there.
1822: <H3>Result</H3>
1823: <P>1 if the ordering implied by <B>rte_better()</B> changes enough
1824: that full best route calculation have to be done, 0 otherwise.
1825:
1826:
1827: <HR><H3>Function</H3>
1828: <P><I>int</I>
1829: <B>rte_better</B>
1830: (<I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>) -- compare metrics of two routes
1831: <P>
1832: <H3>Arguments</H3>
1833: <P>
1834: <DL>
1835: <DT><I>rte *</I> <B>new</B><DD><P>the new route
1836: <DT><I>rte *</I> <B>old</B><DD><P>the original route
1837: </DL>
1838: <H3>Description</H3>
1839: <P>This hook gets called when the routing table contains two routes
1840: for the same network which have originated from different instances
1841: of a single protocol and it wants to select which one is preferred
1842: over the other one. Protocols usually decide according to route metrics.
1843: <H3>Result</H3>
1844: <P>1 if <B>new</B> is better (more preferred) than <B>old</B>, 0 otherwise.
1845:
1846:
1847: <HR><H3>Function</H3>
1848: <P><I>int</I>
1849: <B>rte_same</B>
1850: (<I>rte *</I> <B>e1</B>, <I>rte *</I> <B>e2</B>) -- compare two routes
1851: <P>
1852: <H3>Arguments</H3>
1853: <P>
1854: <DL>
1855: <DT><I>rte *</I> <B>e1</B><DD><P>route
1856: <DT><I>rte *</I> <B>e2</B><DD><P>route
1857: </DL>
1858: <H3>Description</H3>
1859: <P>The <B>rte_same()</B> hook tests whether the routes <B>e1</B> and <B>e2</B> belonging
1860: to the same protocol instance have identical contents. Contents of
1861: <I>rta</I>, all the extended attributes and <I>rte</I> preference are checked
1862: by the core code, no need to take care of them here.
1863: <H3>Result</H3>
1864: <P>1 if <B>e1</B> is identical to <B>e2</B>, 0 otherwise.
1865:
1866:
1867: <HR><H3>Function</H3>
1868: <P><I>void</I>
1869: <B>rte_insert</B>
1870: (<I>net *</I> <B>n</B>, <I>rte *</I> <B>e</B>) -- notify instance about route insertion
1871: <P>
1872: <H3>Arguments</H3>
1873: <P>
1874: <DL>
1875: <DT><I>net *</I> <B>n</B><DD><P>network
1876: <DT><I>rte *</I> <B>e</B><DD><P>route
1877: </DL>
1878: <H3>Description</H3>
1879: <P>This hook is called whenever a <I>rte</I> belonging to the instance
1880: is accepted for insertion to a routing table.
1881: <P>Please avoid using this function in new protocols.
1882:
1883:
1884: <HR><H3>Function</H3>
1885: <P><I>void</I>
1886: <B>rte_remove</B>
1887: (<I>net *</I> <B>n</B>, <I>rte *</I> <B>e</B>) -- notify instance about route removal
1888: <P>
1889: <H3>Arguments</H3>
1890: <P>
1891: <DL>
1892: <DT><I>net *</I> <B>n</B><DD><P>network
1893: <DT><I>rte *</I> <B>e</B><DD><P>route
1894: </DL>
1895: <H3>Description</H3>
1896: <P>This hook is called whenever a <I>rte</I> belonging to the instance
1897: is removed from a routing table.
1898: <P>Please avoid using this function in new protocols.
1899:
1900: <H2><A NAME="ss2.7">2.7</A> <A HREF="prog.html#toc2.7">Interfaces</A>
1901: </H2>
1902:
1903: <P>
1904: <P>The interface module keeps track of all network interfaces in the
1905: system and their addresses.
1906: <P>Each interface is represented by an <I>iface</I> structure which carries
1907: interface capability flags (<I>IF_MULTIACCESS</I>, <I>IF_BROADCAST</I> etc.),
1908: MTU, interface name and index and finally a linked list of network
1909: prefixes assigned to the interface, each one represented by
1910: struct <I>ifa</I>.
1911: <P>The interface module keeps a `soft-up' state for each <I>iface</I> which
1912: is a conjunction of link being up, the interface being of a `sane'
1913: type and at least one IP address assigned to it.
1914: <P>
1915: <P><HR><H3>Function</H3>
1916: <P><I>void</I>
1917: <B>ifa_dump</B>
1918: (<I>struct ifa *</I> <B>a</B>) -- dump interface address
1919: <P>
1920: <H3>Arguments</H3>
1921: <P>
1922: <DL>
1923: <DT><I>struct ifa *</I> <B>a</B><DD><P>interface address descriptor
1924: </DL>
1925: <H3>Description</H3>
1926: <P>This function dumps contents of an <I>ifa</I> to the debug output.
1927:
1928:
1929: <HR><H3>Function</H3>
1930: <P><I>void</I>
1931: <B>if_dump</B>
1932: (<I>struct iface *</I> <B>i</B>) -- dump interface
1933: <P>
1934: <H3>Arguments</H3>
1935: <P>
1936: <DL>
1937: <DT><I>struct iface *</I> <B>i</B><DD><P>interface to dump
1938: </DL>
1939: <H3>Description</H3>
1940: <P>This function dumps all information associated with a given
1941: network interface to the debug output.
1942:
1943:
1944: <HR><H3>Function</H3>
1945: <P><I>void</I>
1946: <B>if_dump_all</B>
1947: (<B>void</B>) -- dump all interfaces
1948: <P>
1949: <H3>Description</H3>
1950: <P>
1951: <P>This function dumps information about all known network
1952: interfaces to the debug output.
1953:
1954:
1955: <HR><H3>Function</H3>
1956: <P><I>void</I>
1957: <B>if_delete</B>
1958: (<I>struct iface *</I> <B>old</B>) -- remove interface
1959: <P>
1960: <H3>Arguments</H3>
1961: <P>
1962: <DL>
1963: <DT><I>struct iface *</I> <B>old</B><DD><P>interface
1964: </DL>
1965: <H3>Description</H3>
1966: <P>This function is called by the low-level platform dependent code
1967: whenever it notices an interface disappears. It is just a shorthand
1968: for <B>if_update()</B>.
1969:
1970:
1971: <HR><H3>Function</H3>
1972: <P><I>struct iface *</I>
1973: <B>if_update</B>
1974: (<I>struct iface *</I> <B>new</B>) -- update interface status
1975: <P>
1976: <H3>Arguments</H3>
1977: <P>
1978: <DL>
1979: <DT><I>struct iface *</I> <B>new</B><DD><P>new interface status
1980: </DL>
1981: <H3>Description</H3>
1982: <P><B>if_update()</B> is called by the low-level platform dependent code
1983: whenever it notices an interface change.
1984: <P>There exist two types of interface updates -- synchronous and asynchronous
1985: ones. In the synchronous case, the low-level code calls <B>if_start_update()</B>,
1986: scans all interfaces reported by the OS, uses <B>if_update()</B> and <B>ifa_update()</B>
1987: to pass them to the core and then it finishes the update sequence by
1988: calling <B>if_end_update()</B>. When working asynchronously, the sysdep code
1989: calls <B>if_update()</B> and <B>ifa_update()</B> whenever it notices a change.
1990: <P><B>if_update()</B> will automatically notify all other modules about the change.
1991:
1992:
1993: <HR><H3>Function</H3>
1994: <P><I>void</I>
1995: <B>if_feed_baby</B>
1996: (<I>struct proto *</I> <B>p</B>) -- advertise interfaces to a new protocol
1997: <P>
1998: <H3>Arguments</H3>
1999: <P>
2000: <DL>
2001: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol to feed
2002: </DL>
2003: <H3>Description</H3>
2004: <P>When a new protocol starts, this function sends it a series
2005: of notifications about all existing interfaces.
2006:
2007:
2008: <HR><H3>Function</H3>
2009: <P><I>struct iface *</I>
2010: <B>if_find_by_index</B>
2011: (<I>unsigned</I> <B>idx</B>) -- find interface by ifindex
2012: <P>
2013: <H3>Arguments</H3>
2014: <P>
2015: <DL>
2016: <DT><I>unsigned</I> <B>idx</B><DD><P>ifindex
2017: </DL>
2018: <H3>Description</H3>
2019: <P>This function finds an <I>iface</I> structure corresponding to an interface
2020: of the given index <B>idx</B>. Returns a pointer to the structure or <I>NULL</I>
2021: if no such structure exists.
2022:
2023:
2024: <HR><H3>Function</H3>
2025: <P><I>struct iface *</I>
2026: <B>if_find_by_name</B>
2027: (<I>char *</I> <B>name</B>) -- find interface by name
2028: <P>
2029: <H3>Arguments</H3>
2030: <P>
2031: <DL>
2032: <DT><I>char *</I> <B>name</B><DD><P>interface name
2033: </DL>
2034: <H3>Description</H3>
2035: <P>This function finds an <I>iface</I> structure corresponding to an interface
2036: of the given name <B>name</B>. Returns a pointer to the structure or <I>NULL</I>
2037: if no such structure exists.
2038:
2039:
2040: <HR><H3>Function</H3>
2041: <P><I>struct ifa *</I>
2042: <B>ifa_update</B>
2043: (<I>struct ifa *</I> <B>a</B>) -- update interface address
2044: <P>
2045: <H3>Arguments</H3>
2046: <P>
2047: <DL>
2048: <DT><I>struct ifa *</I> <B>a</B><DD><P>new interface address
2049: </DL>
2050: <H3>Description</H3>
2051: <P>This function adds address information to a network
2052: interface. It's called by the platform dependent code during
2053: the interface update process described under <B>if_update()</B>.
2054:
2055:
2056: <HR><H3>Function</H3>
2057: <P><I>void</I>
2058: <B>ifa_delete</B>
2059: (<I>struct ifa *</I> <B>a</B>) -- remove interface address
2060: <P>
2061: <H3>Arguments</H3>
2062: <P>
2063: <DL>
2064: <DT><I>struct ifa *</I> <B>a</B><DD><P>interface address
2065: </DL>
2066: <H3>Description</H3>
2067: <P>This function removes address information from a network
2068: interface. It's called by the platform dependent code during
2069: the interface update process described under <B>if_update()</B>.
2070:
2071:
2072: <HR><H3>Function</H3>
2073: <P><I>void</I>
2074: <B>if_init</B>
2075: (<B>void</B>) -- initialize interface module
2076: <P>
2077: <H3>Description</H3>
2078: <P>
2079: <P>This function is called during BIRD startup to initialize
2080: all data structures of the interface module.
2081:
2082: <H2><A NAME="ss2.8">2.8</A> <A HREF="prog.html#toc2.8">Neighbor cache</A>
2083: </H2>
2084:
2085: <P>
2086: <P>Most routing protocols need to associate their internal state data with
2087: neighboring routers, check whether an address given as the next hop
2088: attribute of a route is really an address of a directly connected host
2089: and which interface is it connected through. Also, they often need to
2090: be notified when a neighbor ceases to exist or when their long awaited
2091: neighbor becomes connected. The neighbor cache is there to solve all
2092: these problems.
2093: <P>The neighbor cache maintains a collection of neighbor entries. Each
2094: entry represents one IP address corresponding to either our directly
2095: connected neighbor or our own end of the link (when the scope of the
2096: address is set to <I>SCOPE_HOST</I>) together with per-neighbor data belonging to a
2097: single protocol.
2098: <P>Active entries represent known neighbors and are stored in a hash
2099: table (to allow fast retrieval based on the IP address of the node) and
2100: two linked lists: one global and one per-interface (allowing quick
2101: processing of interface change events). Inactive entries exist only
2102: when the protocol has explicitly requested it via the <I>NEF_STICKY</I>
2103: flag because it wishes to be notified when the node will again become
2104: a neighbor. Such entries are enqueued in a special list which is walked
1.1.1.2 ! misho 2105: whenever an interface changes its state to up. Neighbor entry VRF
! 2106: association is implied by respective protocol.
1.1 misho 2107: <P>When a neighbor event occurs (a neighbor gets disconnected or a sticky
2108: inactive neighbor becomes connected), the protocol hook <B>neigh_notify()</B>
2109: is called to advertise the change.
2110: <P>
2111: <P><HR><H3>Function</H3>
2112: <P><I>neighbor *</I>
2113: <B>neigh_find</B>
2114: (<I>struct proto *</I> <B>p</B>, <I>ip_addr *</I> <B>a</B>, <I>unsigned</I> <B>flags</B>) -- find or create a neighbor entry.
2115: <P>
2116: <H3>Arguments</H3>
2117: <P>
2118: <DL>
2119: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol which asks for the entry.
2120: <DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the node to be searched for.
2121: <DT><I>unsigned</I> <B>flags</B><DD><P>0 or <I>NEF_STICKY</I> if you want to create a sticky entry.
2122: </DL>
2123: <H3>Description</H3>
2124: <P>Search the neighbor cache for a node with given IP address. If
2125: it's found, a pointer to the neighbor entry is returned. If no
2126: such entry exists and the node is directly connected on
2127: one of our active interfaces, a new entry is created and returned
2128: to the caller with protocol-dependent fields initialized to zero.
2129: If the node is not connected directly or *<B>a</B> is not a valid unicast
2130: IP address, <B>neigh_find()</B> returns <I>NULL</I>.
2131:
2132:
2133: <HR><H3>Function</H3>
2134: <P><I>void</I>
2135: <B>neigh_dump</B>
2136: (<I>neighbor *</I> <B>n</B>) -- dump specified neighbor entry.
2137: <P>
2138: <H3>Arguments</H3>
2139: <P>
2140: <DL>
2141: <DT><I>neighbor *</I> <B>n</B><DD><P>the entry to dump
2142: </DL>
2143: <H3>Description</H3>
2144: <P>This functions dumps the contents of a given neighbor entry
2145: to debug output.
2146:
2147:
2148: <HR><H3>Function</H3>
2149: <P><I>void</I>
2150: <B>neigh_dump_all</B>
2151: (<B>void</B>) -- dump all neighbor entries.
2152: <P>
2153: <H3>Description</H3>
2154: <P>
2155: <P>This function dumps the contents of the neighbor cache to
2156: debug output.
2157:
2158:
2159: <HR><H3>Function</H3>
2160: <P><I>void</I>
2161: <B>neigh_if_up</B>
2162: (<I>struct iface *</I> <B>i</B>)
2163: <H3>Arguments</H3>
2164: <P>
2165: <DL>
2166: <DT><I>struct iface *</I> <B>i</B><DD><P>interface in question
2167: </DL>
2168: <H3>Description</H3>
2169: <P>Tell the neighbor cache that a new interface became up.
2170: <P>The neighbor cache wakes up all inactive sticky neighbors with
2171: addresses belonging to prefixes of the interface <B>i</B>.
2172:
2173:
2174: <HR><H3>Function</H3>
2175: <P><I>void</I>
2176: <B>neigh_if_down</B>
2177: (<I>struct iface *</I> <B>i</B>) -- notify neighbor cache about interface down event
2178: <P>
2179: <H3>Arguments</H3>
2180: <P>
2181: <DL>
2182: <DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question
2183: </DL>
2184: <H3>Description</H3>
2185: <P>Notify the neighbor cache that an interface has ceased to exist.
2186: <P>It causes all entries belonging to neighbors connected to this interface
2187: to be flushed.
2188:
2189:
2190: <HR><H3>Function</H3>
2191: <P><I>void</I>
2192: <B>neigh_if_link</B>
2193: (<I>struct iface *</I> <B>i</B>) -- notify neighbor cache about interface link change
2194: <P>
2195: <H3>Arguments</H3>
2196: <P>
2197: <DL>
2198: <DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question
2199: </DL>
2200: <H3>Description</H3>
2201: <P>Notify the neighbor cache that an interface changed link state.
2202: All owners of neighbor entries connected to this interface are
2203: notified.
2204:
2205:
2206: <HR><H3>Function</H3>
2207: <P><I>void</I>
2208: <B>neigh_ifa_update</B>
2209: (<I>struct ifa *</I> <B>a</B>)
2210: <H3>Arguments</H3>
2211: <P>
2212: <DL>
2213: <DT><I>struct ifa *</I> <B>a</B><DD><P>interface address in question
2214: </DL>
2215: <H3>Description</H3>
2216: <P>Tell the neighbor cache that an address was added or removed.
2217: <P>The neighbor cache wakes up all inactive sticky neighbors with
2218: addresses belonging to prefixes of the interface belonging to <B>ifa</B>
2219: and causes all unreachable neighbors to be flushed.
2220:
2221:
2222: <HR><H3>Function</H3>
2223: <P><I>void</I>
2224: <B>neigh_prune</B>
2225: (<B>void</B>) -- prune neighbor cache
2226: <P>
2227: <H3>Description</H3>
2228: <P>
2229: <P><B>neigh_prune()</B> examines all neighbor entries cached and removes those
2230: corresponding to inactive protocols. It's called whenever a protocol
2231: is shut down to get rid of all its heritage.
2232:
2233:
2234: <HR><H3>Function</H3>
2235: <P><I>void</I>
2236: <B>neigh_init</B>
2237: (<I>pool *</I> <B>if_pool</B>) -- initialize the neighbor cache.
2238: <P>
2239: <H3>Arguments</H3>
2240: <P>
2241: <DL>
2242: <DT><I>pool *</I> <B>if_pool</B><DD><P>resource pool to be used for neighbor entries.
2243: </DL>
2244: <H3>Description</H3>
2245: <P>This function is called during BIRD startup to initialize
2246: the neighbor cache module.
2247:
2248: <H2><A NAME="ss2.9">2.9</A> <A HREF="prog.html#toc2.9">Command line interface</A>
2249: </H2>
2250:
2251: <P>
2252: <P>This module takes care of the BIRD's command-line interface (CLI).
2253: The CLI exists to provide a way to control BIRD remotely and to inspect
2254: its status. It uses a very simple textual protocol over a stream
2255: connection provided by the platform dependent code (on UNIX systems,
2256: it's a UNIX domain socket).
2257: <P>Each session of the CLI consists of a sequence of request and replies,
2258: slightly resembling the FTP and SMTP protocols.
2259: Requests are commands encoded as a single line of text, replies are
2260: sequences of lines starting with a four-digit code followed by either
2261: a space (if it's the last line of the reply) or a minus sign (when the
2262: reply is going to continue with the next line), the rest of the line
2263: contains a textual message semantics of which depends on the numeric
2264: code. If a reply line has the same code as the previous one and it's
2265: a continuation line, the whole prefix can be replaced by a single
2266: white space character.
2267: <P>Reply codes starting with 0 stand for `action successfully completed' messages,
2268: 1 means `table entry', 8 `runtime error' and 9 `syntax error'.
2269: <P>Each CLI session is internally represented by a <I>cli</I> structure and a
2270: resource pool containing all resources associated with the connection,
2271: so that it can be easily freed whenever the connection gets closed, not depending
2272: on the current state of command processing.
2273: <P>The CLI commands are declared as a part of the configuration grammar
2274: by using the <CODE>CF_CLI</CODE> macro. When a command is received, it is processed
2275: by the same lexical analyzer and parser as used for the configuration, but
2276: it's switched to a special mode by prepending a fake token to the text,
2277: so that it uses only the CLI command rules. Then the parser invokes
2278: an execution routine corresponding to the command, which either constructs
2279: the whole reply and returns it back or (in case it expects the reply will be long)
2280: it prints a partial reply and asks the CLI module (using the <B>cont</B> hook)
2281: to call it again when the output is transferred to the user.
2282: <P>The <B>this_cli</B> variable points to a <I>cli</I> structure of the session being
2283: currently parsed, but it's of course available only in command handlers
2284: not entered using the <B>cont</B> hook.
2285: <P>TX buffer management works as follows: At cli.tx_buf there is a
2286: list of TX buffers (struct cli_out), cli.tx_write is the buffer
2287: currently used by the producer (<B>cli_printf()</B>, <B>cli_alloc_out()</B>) and
2288: cli.tx_pos is the buffer currently used by the consumer
2289: (<B>cli_write()</B>, in system dependent code). The producer uses
2290: cli_out.wpos ptr as the current write position and the consumer
2291: uses cli_out.outpos ptr as the current read position. When the
2292: producer produces something, it calls <B>cli_write_trigger()</B>. If there
2293: is not enough space in the current buffer, the producer allocates
2294: the new one. When the consumer processes everything in the buffer
2295: queue, it calls <B>cli_written()</B>, tha frees all buffers (except the
2296: first one) and schedules cli.event .
2297: <P>
2298: <P><HR><H3>Function</H3>
2299: <P><I>void</I>
2300: <B>cli_printf</B>
2301: (<I>cli *</I> <B>c</B>, <I>int</I> <B>code</B>, <I>char *</I> <B>msg</B>, <I>...</I> <B>...</B>) -- send reply to a CLI connection
2302: <P>
2303: <H3>Arguments</H3>
2304: <P>
2305: <DL>
2306: <DT><I>cli *</I> <B>c</B><DD><P>CLI connection
2307: <DT><I>int</I> <B>code</B><DD><P>numeric code of the reply, negative for continuation lines
2308: <DT><I>char *</I> <B>msg</B><DD><P>a <B>printf()</B>-like formatting string.
2309: <DT><I>...</I> <B>...</B><DD><P>variable arguments
2310: </DL>
2311: <H3>Description</H3>
2312: <P>This function send a single line of reply to a given CLI connection.
2313: In works in all aspects like <B>bsprintf()</B> except that it automatically
2314: prepends the reply line prefix.
2315: <P>Please note that if the connection can be already busy sending some
2316: data in which case <B>cli_printf()</B> stores the output to a temporary buffer,
2317: so please avoid sending a large batch of replies without waiting
2318: for the buffers to be flushed.
2319: <P>If you want to write to the current CLI output, you can use the <B>cli_msg()</B>
2320: macro instead.
2321:
2322:
2323: <HR><H3>Function</H3>
2324: <P><I>void</I>
2325: <B>cli_init</B>
2326: (<B>void</B>) -- initialize the CLI module
2327: <P>
2328: <H3>Description</H3>
2329: <P>
2330: <P>This function is called during BIRD startup to initialize
2331: the internal data structures of the CLI module.
2332:
2333: <H2><A NAME="ss2.10">2.10</A> <A HREF="prog.html#toc2.10">Object locks</A>
2334: </H2>
2335:
2336: <P>
2337: <P>The lock module provides a simple mechanism for avoiding conflicts between
2338: various protocols which would like to use a single physical resource (for
2339: example a network port). It would be easy to say that such collisions can
2340: occur only when the user specifies an invalid configuration and therefore
2341: he deserves to get what he has asked for, but unfortunately they can also
2342: arise legitimately when the daemon is reconfigured and there exists (although
2343: for a short time period only) an old protocol instance being shut down and a new one
2344: willing to start up on the same interface.
2345: <P>The solution is very simple: when any protocol wishes to use a network port
2346: or some other non-shareable resource, it asks the core to lock it and it doesn't
2347: use the resource until it's notified that it has acquired the lock.
2348: <P>Object locks are represented by <I>object_lock</I> structures which are in turn a
2349: kind of resource. Lockable resources are uniquely determined by resource type
2350: (<I>OBJLOCK_UDP</I> for a UDP port etc.), IP address (usually a broadcast or
2351: multicast address the port is bound to), port number, interface and optional
2352: instance ID.
2353: <P>
2354: <P><HR><H3>Function</H3>
2355: <P><I>struct object_lock *</I>
2356: <B>olock_new</B>
2357: (<I>pool *</I> <B>p</B>) -- create an object lock
2358: <P>
2359: <H3>Arguments</H3>
2360: <P>
2361: <DL>
2362: <DT><I>pool *</I> <B>p</B><DD><P>resource pool to create the lock in.
2363: </DL>
2364: <H3>Description</H3>
2365: <P>The <B>olock_new()</B> function creates a new resource of type <I>object_lock</I>
2366: and returns a pointer to it. After filling in the structure, the caller
2367: should call <B>olock_acquire()</B> to do the real locking.
2368:
2369:
2370: <HR><H3>Function</H3>
2371: <P><I>void</I>
2372: <B>olock_acquire</B>
2373: (<I>struct object_lock *</I> <B>l</B>) -- acquire a lock
2374: <P>
2375: <H3>Arguments</H3>
2376: <P>
2377: <DL>
2378: <DT><I>struct object_lock *</I> <B>l</B><DD><P>the lock to acquire
2379: </DL>
2380: <H3>Description</H3>
2381: <P>This function attempts to acquire exclusive access to the non-shareable
2382: resource described by the lock <B>l</B>. It returns immediately, but as soon
2383: as the resource becomes available, it calls the <B>hook()</B> function set up
2384: by the caller.
2385: <P>When you want to release the resource, just <B>rfree()</B> the lock.
2386:
2387:
2388: <HR><H3>Function</H3>
2389: <P><I>void</I>
2390: <B>olock_init</B>
2391: (<B>void</B>) -- initialize the object lock mechanism
2392: <P>
2393: <H3>Description</H3>
2394: <P>
2395: <P>This function is called during BIRD startup. It initializes
2396: all the internal data structures of the lock module.
2397:
2398: <HR>
2399: <A HREF="prog-3.html">Next</A>
2400: <A HREF="prog-1.html">Previous</A>
2401: <A HREF="prog.html#toc2">Contents</A>
2402: </BODY>
2403: </HTML>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog-2.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc