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