Annotation of embedaddon/bird2/doc/prog.sgml, revision 1.1.1.1
1.1 misho 1: <!doctype birddoc system>
2:
3: <!--
4: BIRD: Programmer's Documentation
5:
6: Copyright (c) 2000 Martin Mares <mj@ucw.cz>
7: -->
8:
9: <book>
10: <progdoc>
11:
12: <title>BIRD Programmer's Documentation
13: <author>
14: Ondrej Filip <it/<feela@network.cz>/,
15: Pavel Machek <it/<pavel@ucw.cz>/,
16: Martin Mares <it/<mj@ucw.cz>/,
17: Ondrej Zajicek <it/<santiago@crfreenet.org>/
18: </author>
19:
20: <abstract>
21: This document contains programmer's documentation for the BIRD Internet Routing Daemon project.
22: </abstract>
23:
24: <!-- Table of contents -->
25: <toc>
26:
27: <!-- Begin the document -->
28: <chapt>BIRD Design
29:
30: <sect>Introduction
31:
32: <p>This document describes the internal workings of BIRD, its architecture,
33: design decisions and rationale behind them. It also contains documentation on
34: all the essential components of the system and their interfaces.
35:
36: <p>Routing daemons are complicated things which need to act in real time
37: to complex sequences of external events, respond correctly even to the most erroneous behavior
38: of their environment and still handle enormous amount of data with reasonable
39: speed. Due to all of this, their design is very tricky as one needs to carefully
40: balance between efficiency, stability and (last, but not least) simplicity of
41: the program and it would be possible to write literally hundreds of pages about
42: all of these issues. In accordance to the famous quote of Anton Chekhov "Shortness
43: is a sister of talent", we've tried to write a much shorter document highlighting
44: the most important stuff and leaving the boring technical details better explained
45: by the program source itself together with comments contained therein.
46:
47: <sect>Design goals
48:
49: <p>When planning the architecture of BIRD, we've taken a close look at the other existing routing
50: daemons and also at some of the operating systems used on dedicated routers, gathered all important
51: features and added lots of new ones to overcome their shortcomings and to better match the requirements
52: of routing in today's Internet: IPv6, policy routing, route filtering and so on. From this
53: planning, the following set of design goals has arisen:
54:
55: <itemize>
56:
57: <item><it>Support all the standard routing protocols and make it easy to add new ones.</it>
58: This leads to modularity and clean separation between the core and the protocols.
59:
60: <item><it>Support both IPv4 and IPv6 in the same source tree, re-using most of the code.</it>
61: This leads to abstraction of IP addresses and operations on them.
62:
63: <item><it>Minimize OS dependent code to make porting as easy as possible.</it>
64: Unfortunately, such code cannot be avoided at all as the details of communication with
65: the IP stack differ from OS to OS and they often vary even between different
66: versions of the same OS. But we can isolate such code in special modules and
67: do the porting by changing or replacing just these modules.
68: Also, don't rely on specific features of various operating systems, but be able
69: to make use of them if they are available.
70:
71: <item><it>Allow multiple routing tables.</it>
72: Easily solvable by abstracting out routing tables and the corresponding operations.
73:
74: <item><it>Offer powerful route filtering.</it>
75: There already were several attempts to incorporate route filters to a dynamic router,
76: but most of them have used simple sequences of filtering rules which were very inflexible
77: and hard to use for non-trivial filters. We've decided to employ a simple loop-free
78: programming language having access to all the route attributes and being able to
79: modify the most of them.
80:
81: <item><it>Support easy configuration and re-configuration.</it>
82: Most routers use a simple configuration language designed ad hoc with no structure at all
83: and allow online changes of configuration by using their command-line interface, thus
84: any complex re-configurations are hard to achieve without replacing the configuration
85: file and restarting the whole router. We've decided to use a more general approach: to
86: have a configuration defined in a context-free language with blocks and nesting, to
87: perform all configuration changes by editing the configuration file, but to be able
88: to read the new configuration and smoothly adapt to it without disturbing parts of
89: the routing process which are not affected by the change.
90:
91: <item><it>Be able to be controlled online.</it>
92: In addition to the online reconfiguration, a routing daemon should be able to communicate
93: with the user and with many other programs (primarily scripts used for network maintenance)
94: in order to make it possible to inspect contents of routing tables, status of all
95: routing protocols and also to control their behavior (disable, enable or reset a protocol without restarting all the others). To achieve
96: this, we implement a simple command-line protocol based on those used by FTP and SMTP
97: (that is textual commands and textual replies accompanied by a numeric code which makes
98: them both readable to a human and easy to recognize in software).
99:
100: <item><it>Respond to all events in real time.</it>
101: A typical solution to this problem is to use lots of threads to separate the workings
102: of all the routing protocols and also of the user interface parts and to hope that
103: the scheduler will assign time to them in a fair enough manner. This is surely a good
104: solution, but we have resisted the temptation and preferred to avoid the overhead of threading
105: and the large number of locks involved and preferred a event driven architecture with
106: our own scheduling of events. An unpleasant consequence of such an approach
107: is that long lasting tasks must be split to more parts linked by special
108: events or timers to make the CPU available for other tasks as well.
109:
110: </itemize>
111:
112: <sect>Architecture
113:
114: <p>The requirements set above have lead to a simple modular architecture containing
115: the following types of modules:
116:
117: <descrip>
118:
119: <tagp>Core modules</tagp> implement the core functions of BIRD: taking care
120: of routing tables, keeping protocol status, interacting with the user using
121: the Command-Line Interface (to be called CLI in the rest of this document)
122: etc.
123:
124: <tagp>Library modules</tagp> form a large set of various library functions
125: implementing several data abstractions, utility functions and also functions
126: which are a part of the standard libraries on some systems, but missing on other
127: ones.
128:
129: <tagp>Resource management modules</tagp> take care of resources, their allocation
130: and automatic freeing when the module having requested shuts itself down.
131:
132: <tagp>Configuration modules</tagp> are fragments of lexical analyzer,
133: grammar rules and the corresponding snippets of C code. For each group
134: of code modules (core, each protocol, filters) there exist a configuration
135: module taking care of all the related configuration stuff.
136:
137: <tagp>The filter</tagp> implements the route filtering language.
138:
139: <tagp>Protocol modules</tagp> implement the individual routing protocols.
140:
141: <tagp>System-dependent modules</tagp> implement the interface between BIRD
142: and specific operating systems.
143:
144: <tagp>The client</tagp> is a simple program providing an easy, though friendly
145: interface to the CLI.
146:
147: </descrip>
148:
149: <sect>Implementation
150:
151: <p>BIRD has been written in GNU C. We've considered using C++, but we've
152: preferred the simplicity and straightforward nature of C which gives us fine
153: control over all implementation details and on the other hand enough
154: instruments to build the abstractions we need.
155:
156: <p>The modules are statically linked to produce a single executable file
157: (except for the client which stands on its own).
158:
159: <p>The building process is controlled by a set of Makefiles for GNU Make,
160: intermixed with several Perl and shell scripts.
161:
162: <p>The initial configuration of the daemon, detection of system features
163: and selection of the right modules to include for the particular OS
164: and the set of protocols the user has chosen is performed by a configure
165: script generated by GNU Autoconf.
166:
167: <p>The parser of the configuration is generated by the GNU Bison.
168:
169: <p>The documentation is generated using <file/SGMLtools/ with our own DTD
170: and mapping rules which produce both an online version in HTML and
171: a neatly formatted one for printing (first converted
172: from SGML to &latex; and then processed by &tex; and <file/dvips/ to
173: get a PostScript file).
174:
175: <p>The comments from C sources which form a part of the programmer's
176: documentation are extracted using a modified version of the <file/kernel-doc/
177: tool.
178:
179: <p>If you want to work on BIRD, it's highly recommended to configure it
180: with a <tt/--enable-debug/ switch which enables some internal consistency
181: checks and it also links BIRD with a memory allocation checking library
182: if you have one (either <tt/efence/ or <tt/dmalloc/).
183:
184: <!--
185: LocalWords: IPv IP CLI snippets Perl Autoconf SGMLtools DTD SGML dvips
186: LocalWords: PostScript
187: -->
188: <chapt>Core
189: <sect>Forwarding Information Base
190: <p>
191: <p>
192: FIB is a data structure designed for storage of routes indexed by their
193: network prefixes. It supports insertion, deletion, searching by prefix,
194: `routing' (in CIDR sense, that is searching for a longest prefix matching
195: a given IP address) and (which makes the structure very tricky to implement)
196: asynchronous reading, that is enumerating the contents of a FIB while other
197: modules add, modify or remove entries.
198: <p>
199: Internally, each FIB is represented as a collection of nodes of type <struct/fib_node/
200: indexed using a sophisticated hashing mechanism.
201: We use two-stage hashing where we calculate a 16-bit primary hash key independent
202: on hash table size and then we just divide the primary keys modulo table size
203: to get a real hash key used for determining the bucket containing the node.
204: The lists of nodes in each bucket are sorted according to the primary hash
205: key, hence if we keep the total number of buckets to be a power of two,
206: re-hashing of the structure keeps the relative order of the nodes.
207: <p>
208: To get the asynchronous reading consistent over node deletions, we need to
209: keep a list of readers for each node. When a node gets deleted, its readers
210: are automatically moved to the next node in the table.
211: <p>
212: Basic FIB operations are performed by functions defined by this module,
213: enumerating of FIB contents is accomplished by using the <func/FIB_WALK()/ macro
214: or <func/FIB_ITERATE_START()/ if you want to do it asynchronously.
215: <p>
216: For simple iteration just place the body of the loop between <func/FIB_WALK()/ and
217: <func/FIB_WALK_END()/. You can't modify the FIB during the iteration (you can modify
218: data in the node, but not add or remove nodes).
219: <p>
220: If you need more freedom, you can use the FIB_ITERATE_*() group of macros.
221: First, you initialize an iterator with <func/FIB_ITERATE_INIT()/. Then you can put
222: the loop body in between <func/FIB_ITERATE_START()/ and <func/FIB_ITERATE_END()/. In
223: addition, the iteration can be suspended by calling <func/FIB_ITERATE_PUT()/.
224: This'll link the iterator inside the FIB. While suspended, you may modify the
225: FIB, exit the current function, etc. To resume the iteration, enter the loop
226: again. You can use <func/FIB_ITERATE_UNLINK()/ to unlink the iterator (while
227: iteration is suspended) in cases like premature end of FIB iteration.
228: <p>
229: Note that the iterator must not be destroyed when the iteration is suspended,
230: the FIB would then contain a pointer to invalid memory. Therefore, after each
231: <func/FIB_ITERATE_INIT()/ or <func/FIB_ITERATE_PUT()/ there must be either
232: <func/FIB_ITERATE_START()/ or <func/FIB_ITERATE_UNLINK()/ before the iterator is destroyed.
233:
234:
235: <function><p><type>void</type>
236: <funcdef>fib_init</funcdef>
237: (<type>struct fib *</type> <param>f</param>, <type>pool *</type> <param>p</param>, <type>unsigned</type> <param>node_size</param>, <type>unsigned</type> <param>hash_order</param>, <type>fib_init_func</type> <param>init</param>) -- initialize a new FIB
238:
239: <funcsect>Arguments
240: <p><descrip>
241: <tagp><type>struct fib *</type> <param>f</param></tagp>
242: the FIB to be initialized (the structure itself being allocated by the caller)
243: <tagp><type>pool *</type> <param>p</param></tagp>
244: pool to allocate the nodes in
245: <tagp><type>unsigned</type> <param>node_size</param></tagp>
246: node size to be used (each node consists of a standard header <struct/fib_node/
247: followed by user data)
248: <tagp><type>unsigned</type> <param>hash_order</param></tagp>
249: initial hash order (a binary logarithm of hash table size), 0 to use default order
250: (recommended)
251: <tagp><type>fib_init_func</type> <param>init</param></tagp>
252: pointer a function to be called to initialize a newly created node
253: </descrip>
254: <funcsect>Description
255: <p>
256: This function initializes a newly allocated FIB and prepares it for use.
257: </function>
258: <function><p><type>void *</type>
259: <funcdef>fib_find</funcdef>
260: (<type>struct fib *</type> <param>f</param>, <type>ip_addr *</type> <param>a</param>, <type>int</type> <param>len</param>) -- search for FIB node by prefix
261:
262: <funcsect>Arguments
263: <p><descrip>
264: <tagp><type>struct fib *</type> <param>f</param></tagp>
265: FIB to search in
266: <tagp><type>ip_addr *</type> <param>a</param></tagp>
267: pointer to IP address of the prefix
268: <tagp><type>int</type> <param>len</param></tagp>
269: prefix length
270: </descrip>
271: <funcsect>Description
272: <p>
273: Search for a FIB node corresponding to the given prefix, return
274: a pointer to it or <const/NULL/ if no such node exists.
275: </function>
276: <function><p><type>void *</type>
277: <funcdef>fib_get</funcdef>
278: (<type>struct fib *</type> <param>f</param>, <type>ip_addr *</type> <param>a</param>, <type>int</type> <param>len</param>) -- find or create a FIB node
279:
280: <funcsect>Arguments
281: <p><descrip>
282: <tagp><type>struct fib *</type> <param>f</param></tagp>
283: FIB to work with
284: <tagp><type>ip_addr *</type> <param>a</param></tagp>
285: pointer to IP address of the prefix
286: <tagp><type>int</type> <param>len</param></tagp>
287: prefix length
288: </descrip>
289: <funcsect>Description
290: <p>
291: Search for a FIB node corresponding to the given prefix and
292: return a pointer to it. If no such node exists, create it.
293: </function>
294: <function><p><type>void *</type>
295: <funcdef>fib_route</funcdef>
296: (<type>struct fib *</type> <param>f</param>, <type>ip_addr</type> <param>a</param>, <type>int</type> <param>len</param>) -- CIDR routing lookup
297:
298: <funcsect>Arguments
299: <p><descrip>
300: <tagp><type>struct fib *</type> <param>f</param></tagp>
301: FIB to search in
302: <tagp><type>ip_addr</type> <param>a</param></tagp>
303: pointer to IP address of the prefix
304: <tagp><type>int</type> <param>len</param></tagp>
305: prefix length
306: </descrip>
307: <funcsect>Description
308: <p>
309: Search for a FIB node with longest prefix matching the given
310: network, that is a node which a CIDR router would use for routing
311: that network.
312: </function>
313: <function><p><type>void</type>
314: <funcdef>fib_delete</funcdef>
315: (<type>struct fib *</type> <param>f</param>, <type>void *</type> <param>E</param>) -- delete a FIB node
316:
317: <funcsect>Arguments
318: <p><descrip>
319: <tagp><type>struct fib *</type> <param>f</param></tagp>
320: FIB to delete from
321: <tagp><type>void *</type> <param>E</param></tagp>
322: entry to delete
323: </descrip>
324: <funcsect>Description
325: <p>
326: This function removes the given entry from the FIB,
327: taking care of all the asynchronous readers by shifting
328: them to the next node in the canonical reading order.
329: </function>
330: <function><p><type>void</type>
331: <funcdef>fib_free</funcdef>
332: (<type>struct fib *</type> <param>f</param>) -- delete a FIB
333:
334: <funcsect>Arguments
335: <p><descrip>
336: <tagp><type>struct fib *</type> <param>f</param></tagp>
337: FIB to be deleted
338: </descrip>
339: <funcsect>Description
340: <p>
341: This function deletes a FIB -- it frees all memory associated
342: with it and all its entries.
343: </function>
344: <function><p><type>void</type>
345: <funcdef>fib_check</funcdef>
346: (<type>struct fib *</type> <param>f</param>) -- audit a FIB
347:
348: <funcsect>Arguments
349: <p><descrip>
350: <tagp><type>struct fib *</type> <param>f</param></tagp>
351: FIB to be checked
352: </descrip>
353: <funcsect>Description
354: <p>
355: This debugging function audits a FIB by checking its internal consistency.
356: Use when you suspect somebody of corrupting innocent data structures.
357: </function>
358: <sect>Routing tables
359: <p>
360: <p>
361: Routing tables are probably the most important structures BIRD uses. They
362: hold all the information about known networks, the associated routes and
363: their attributes.
364: <p>
365: There are multiple routing tables (a primary one together with any
366: number of secondary ones if requested by the configuration). Each table
367: is basically a FIB containing entries describing the individual
368: destination networks. For each network (represented by structure <struct/net/),
369: there is a one-way linked list of route entries (<struct/rte/), the first entry
370: on the list being the best one (i.e., the one we currently use
371: for routing), the order of the other ones is undetermined.
372: <p>
373: The <struct/rte/ contains information specific to the route (preference, protocol
374: metrics, time of last modification etc.) and a pointer to a <struct/rta/ structure
375: (see the route attribute module for a precise explanation) holding the
376: remaining route attributes which are expected to be shared by multiple
377: routes in order to conserve memory.
378:
379:
380: <function><p><type>rte *</type>
381: <funcdef>rte_find</funcdef>
382: (<type>net *</type> <param>net</param>, <type>struct rte_src *</type> <param>src</param>) -- find a route
383:
384: <funcsect>Arguments
385: <p><descrip>
386: <tagp><type>net *</type> <param>net</param></tagp>
387: network node
388: <tagp><type>struct rte_src *</type> <param>src</param></tagp>
389: route source
390: </descrip>
391: <funcsect>Description
392: <p>
393: The <func/rte_find()/ function returns a route for destination <param/net/
394: which is from route source <param/src/.
395: </function>
396: <function><p><type>rte *</type>
397: <funcdef>rte_get_temp</funcdef>
398: (<type>rta *</type> <param>a</param>) -- get a temporary <struct/rte/
399:
400: <funcsect>Arguments
401: <p><descrip>
402: <tagp><type>rta *</type> <param>a</param></tagp>
403: attributes to assign to the new route (a <struct/rta/; in case it's
404: un-cached, <func/rte_update()/ will create a cached copy automatically)
405: </descrip>
406: <funcsect>Description
407: <p>
408: Create a temporary <struct/rte/ and bind it with the attributes <param/a/.
409: Also set route preference to the default preference set for
410: the protocol.
411: </function>
412: <function><p><type>rte *</type>
413: <funcdef>rte_cow_rta</funcdef>
414: (<type>rte *</type> <param>r</param>, <type>linpool *</type> <param>lp</param>) -- get a private writable copy of <struct/rte/ with writable <struct/rta/
415:
416: <funcsect>Arguments
417: <p><descrip>
418: <tagp><type>rte *</type> <param>r</param></tagp>
419: a route entry to be copied
420: <tagp><type>linpool *</type> <param>lp</param></tagp>
421: a linpool from which to allocate <struct/rta/
422: </descrip>
423: <funcsect>Description
424: <p>
425: <func/rte_cow_rta()/ takes a <struct/rte/ and prepares it and associated <struct/rta/ for
426: modification. There are three possibilities: First, both <struct/rte/ and <struct/rta/ are
427: private copies, in that case they are returned unchanged. Second, <struct/rte/ is
428: private copy, but <struct/rta/ is cached, in that case <struct/rta/ is duplicated using
429: <func/rta_do_cow()/. Third, both <struct/rte/ is shared and <struct/rta/ is cached, in that case
430: both structures are duplicated by <func/rte_do_cow()/ and <func/rta_do_cow()/.
431: <p>
432: Note that in the second case, cached <struct/rta/ loses one reference, while private
433: copy created by <func/rta_do_cow()/ is a shallow copy sharing indirect data (eattrs,
434: nexthops, ...) with it. To work properly, original shared <struct/rta/ should have
435: another reference during the life of created private copy.
436: <funcsect>Result
437: <p>
438: a pointer to the new writable <struct/rte/ with writable <struct/rta/.
439: </function>
440: <function><p><type>void</type>
441: <funcdef>rte_announce</funcdef>
442: (<type>rtable *</type> <param>tab</param>, <type>unsigned</type> <param>type</param>, <type>net *</type> <param>net</param>, <type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>, <type>rte *</type> <param>new_best</param>, <type>rte *</type> <param>old_best</param>, <type>rte *</type> <param>before_old</param>) -- announce a routing table change
443:
444: <funcsect>Arguments
445: <p><descrip>
446: <tagp><type>rtable *</type> <param>tab</param></tagp>
447: table the route has been added to
448: <tagp><type>unsigned</type> <param>type</param></tagp>
449: type of route announcement (RA_OPTIMAL or RA_ANY)
450: <tagp><type>net *</type> <param>net</param></tagp>
451: network in question
452: <tagp><type>rte *</type> <param>new</param></tagp>
453: the new route to be announced
454: <tagp><type>rte *</type> <param>old</param></tagp>
455: the previous route for the same network
456: <tagp><type>rte *</type> <param>new_best</param></tagp>
457: the new best route for the same network
458: <tagp><type>rte *</type> <param>old_best</param></tagp>
459: the previous best route for the same network
460: <tagp><type>rte *</type> <param>before_old</param></tagp>
461: The previous route before <param/old/ for the same network.
462: If <param/before_old/ is NULL <param/old/ was the first.
463: </descrip>
464: <funcsect>Description
465: <p>
466: This function gets a routing table update and announces it
467: to all protocols that acccepts given type of route announcement
468: and are connected to the same table by their announcement hooks.
469: <p>
470: Route announcement of type <const/RA_OPTIMAL/ si generated when optimal
471: route (in routing table <param/tab/) changes. In that case <param/old/ stores the
472: old optimal route.
473: <p>
474: Route announcement of type <const/RA_ANY/ si generated when any route (in
475: routing table <param/tab/) changes In that case <param/old/ stores the old route
476: from the same protocol.
477: <p>
478: For each appropriate protocol, we first call its <func/import_control()/
479: hook which performs basic checks on the route (each protocol has a
480: right to veto or force accept of the route before any filter is
481: asked) and adds default values of attributes specific to the new
482: protocol (metrics, tags etc.). Then it consults the protocol's
483: export filter and if it accepts the route, the <func/rt_notify()/ hook of
484: the protocol gets called.
485: </function>
486: <function><p><type>void</type>
487: <funcdef>rte_free</funcdef>
488: (<type>rte *</type> <param>e</param>) -- delete a <struct/rte/
489:
490: <funcsect>Arguments
491: <p><descrip>
492: <tagp><type>rte *</type> <param>e</param></tagp>
493: <struct/rte/ to be deleted
494: </descrip>
495: <funcsect>Description
496: <p>
497: <func/rte_free()/ deletes the given <struct/rte/ from the routing table it's linked to.
498: </function>
499: <function><p><type>void</type>
500: <funcdef>rte_update2</funcdef>
501: (<type>struct announce_hook *</type> <param>ah</param>, <type>net *</type> <param>net</param>, <type>rte *</type> <param>new</param>, <type>struct rte_src *</type> <param>src</param>) -- enter a new update to a routing table
502:
503: <funcsect>Arguments
504: <p><descrip>
505: <tagp><type>struct announce_hook *</type> <param>ah</param></tagp>
506: pointer to table announce hook
507: <tagp><type>net *</type> <param>net</param></tagp>
508: network node
509: <tagp><type>rte *</type> <param>new</param></tagp>
510: a <struct/rte/ representing the new route or <const/NULL/ for route removal.
511: <tagp><type>struct rte_src *</type> <param>src</param></tagp>
512: protocol originating the update
513: </descrip>
514: <funcsect>Description
515: <p>
516: This function is called by the routing protocols whenever they discover
517: a new route or wish to update/remove an existing route. The right announcement
518: sequence is to build route attributes first (either un-cached with <param/aflags/ set
519: to zero or a cached one using <func/rta_lookup()/; in this case please note that
520: you need to increase the use count of the attributes yourself by calling
521: <func/rta_clone()/), call <func/rte_get_temp()/ to obtain a temporary <struct/rte/, fill in all
522: the appropriate data and finally submit the new <struct/rte/ by calling <func/rte_update()/.
523: <p>
524: <param/src/ specifies the protocol that originally created the route and the meaning
525: of protocol-dependent data of <param/new/. If <param/new/ is not <const/NULL/, <param/src/ have to be the
526: same value as <param/new/->attrs->proto. <param/p/ specifies the protocol that called
527: <func/rte_update()/. In most cases it is the same protocol as <param/src/. <func/rte_update()/
528: stores <param/p/ in <param/new/->sender;
529: <p>
530: When <func/rte_update()/ gets any route, it automatically validates it (checks,
531: whether the network and next hop address are valid IP addresses and also
532: whether a normal routing protocol doesn't try to smuggle a host or link
533: scope route to the table), converts all protocol dependent attributes stored
534: in the <struct/rte/ to temporary extended attributes, consults import filters of the
535: protocol to see if the route should be accepted and/or its attributes modified,
536: stores the temporary attributes back to the <struct/rte/.
537: <p>
538: Now, having a "public" version of the route, we
539: automatically find any old route defined by the protocol <param/src/
540: for network <param/n/, replace it by the new one (or removing it if <param/new/ is <const/NULL/),
541: recalculate the optimal route for this destination and finally broadcast
542: the change (if any) to all routing protocols by calling <func/rte_announce()/.
543: <p>
544: All memory used for attribute lists and other temporary allocations is taken
545: from a special linear pool <param/rte_update_pool/ and freed when <func/rte_update()/
546: finishes.
547: </function>
548: <function><p><type>void</type>
549: <funcdef>rt_refresh_begin</funcdef>
550: (<type>rtable *</type> <param>t</param>, <type>struct announce_hook *</type> <param>ah</param>) -- start a refresh cycle
551:
552: <funcsect>Arguments
553: <p><descrip>
554: <tagp><type>rtable *</type> <param>t</param></tagp>
555: related routing table
556: <tagp><type>struct announce_hook *</type> <param>ah</param></tagp>
557: related announce hook
558: </descrip>
559: <funcsect>Description
560: <p>
561: This function starts a refresh cycle for given routing table and announce
562: hook. The refresh cycle is a sequence where the protocol sends all its valid
563: routes to the routing table (by <func/rte_update()/). After that, all protocol
564: routes (more precisely routes with <param/ah/ as <param/sender/) not sent during the
565: refresh cycle but still in the table from the past are pruned. This is
566: implemented by marking all related routes as stale by REF_STALE flag in
567: <func/rt_refresh_begin()/, then marking all related stale routes with REF_DISCARD
568: flag in <func/rt_refresh_end()/ and then removing such routes in the prune loop.
569: </function>
570: <function><p><type>void</type>
571: <funcdef>rt_refresh_end</funcdef>
572: (<type>rtable *</type> <param>t</param>, <type>struct announce_hook *</type> <param>ah</param>) -- end a refresh cycle
573:
574: <funcsect>Arguments
575: <p><descrip>
576: <tagp><type>rtable *</type> <param>t</param></tagp>
577: related routing table
578: <tagp><type>struct announce_hook *</type> <param>ah</param></tagp>
579: related announce hook
580: </descrip>
581: <funcsect>Description
582: <p>
583: This function starts a refresh cycle for given routing table and announce
584: hook. See <func/rt_refresh_begin()/ for description of refresh cycles.
585: </function>
586: <function><p><type>void</type>
587: <funcdef>rte_dump</funcdef>
588: (<type>rte *</type> <param>e</param>) -- dump a route
589:
590: <funcsect>Arguments
591: <p><descrip>
592: <tagp><type>rte *</type> <param>e</param></tagp>
593: <struct/rte/ to be dumped
594: </descrip>
595: <funcsect>Description
596: <p>
597: This functions dumps contents of a <struct/rte/ to debug output.
598: </function>
599: <function><p><type>void</type>
600: <funcdef>rt_dump</funcdef>
601: (<type>rtable *</type> <param>t</param>) -- dump a routing table
602:
603: <funcsect>Arguments
604: <p><descrip>
605: <tagp><type>rtable *</type> <param>t</param></tagp>
606: routing table to be dumped
607: </descrip>
608: <funcsect>Description
609: <p>
610: This function dumps contents of a given routing table to debug output.
611: </function>
612: <function><p><type>void</type>
613: <funcdef>rt_dump_all</funcdef>
614: (<param>void</param>) -- dump all routing tables
615:
616: <funcsect>Description
617: <p>
618: <p>
619: This function dumps contents of all routing tables to debug output.
620: </function>
621: <function><p><type>void</type>
622: <funcdef>rt_init</funcdef>
623: (<param>void</param>) -- initialize routing tables
624:
625: <funcsect>Description
626: <p>
627: <p>
628: This function is called during BIRD startup. It initializes the
629: routing table module.
630: </function>
631: <function><p><type>int</type>
632: <funcdef>rt_prune_table</funcdef>
633: (<type>rtable *</type> <param>tab</param>) -- prune a routing table
634:
635: <funcsect>Arguments
636: <p><descrip>
637: <tagp><type>rtable *</type> <param>tab</param></tagp>
638: a routing table for pruning
639: </descrip>
640: <funcsect>Description
641: <p>
642: This function scans the routing table <param/tab/ and removes routes belonging to
643: flushing protocols, discarded routes and also stale network entries, in a
644: similar fashion like <func/rt_prune_loop()/. Returns 1 when all such routes are
645: pruned. Contrary to <func/rt_prune_loop()/, this function is not a part of the
646: protocol flushing loop, but it is called from <func/rt_event()/ for just one routing
647: table.
648: <p>
649: Note that <func/rt_prune_table()/ and <func/rt_prune_loop()/ share (for each table) the
650: prune state (<param/prune_state/) and also the pruning iterator (<param/prune_fit/).
651: </function>
652: <function><p><type>int</type>
653: <funcdef>rt_prune_loop</funcdef>
654: (<param>void</param>) -- prune routing tables
655:
656: <funcsect>Description
657: <p>
658: <p>
659: The prune loop scans routing tables and removes routes belonging to flushing
660: protocols, discarded routes and also stale network entries. Returns 1 when
661: all such routes are pruned. It is a part of the protocol flushing loop.
662: </function>
663: <function><p><type>void</type>
664: <funcdef>rt_lock_table</funcdef>
665: (<type>rtable *</type> <param>r</param>) -- lock a routing table
666:
667: <funcsect>Arguments
668: <p><descrip>
669: <tagp><type>rtable *</type> <param>r</param></tagp>
670: routing table to be locked
671: </descrip>
672: <funcsect>Description
673: <p>
674: Lock a routing table, because it's in use by a protocol,
675: preventing it from being freed when it gets undefined in a new
676: configuration.
677: </function>
678: <function><p><type>void</type>
679: <funcdef>rt_unlock_table</funcdef>
680: (<type>rtable *</type> <param>r</param>) -- unlock a routing table
681:
682: <funcsect>Arguments
683: <p><descrip>
684: <tagp><type>rtable *</type> <param>r</param></tagp>
685: routing table to be unlocked
686: </descrip>
687: <funcsect>Description
688: <p>
689: Unlock a routing table formerly locked by <func/rt_lock_table()/,
690: that is decrease its use count and delete it if it's scheduled
691: for deletion by configuration changes.
692: </function>
693: <function><p><type>void</type>
694: <funcdef>rt_commit</funcdef>
695: (<type>struct config *</type> <param>new</param>, <type>struct config *</type> <param>old</param>) -- commit new routing table configuration
696:
697: <funcsect>Arguments
698: <p><descrip>
699: <tagp><type>struct config *</type> <param>new</param></tagp>
700: new configuration
701: <tagp><type>struct config *</type> <param>old</param></tagp>
702: original configuration or <const/NULL/ if it's boot time config
703: </descrip>
704: <funcsect>Description
705: <p>
706: Scan differences between <param/old/ and <param/new/ configuration and modify
707: the routing tables according to these changes. If <param/new/ defines a
708: previously unknown table, create it, if it omits a table existing
709: in <param/old/, schedule it for deletion (it gets deleted when all protocols
710: disconnect from it by calling <func/rt_unlock_table()/), if it exists
711: in both configurations, leave it unchanged.
712: </function>
713: <function><p><type>int</type>
714: <funcdef>rt_feed_baby</funcdef>
715: (<type>struct proto *</type> <param>p</param>) -- advertise routes to a new protocol
716:
717: <funcsect>Arguments
718: <p><descrip>
719: <tagp><type>struct proto *</type> <param>p</param></tagp>
720: protocol to be fed
721: </descrip>
722: <funcsect>Description
723: <p>
724: This function performs one pass of advertisement of routes to a newly
725: initialized protocol. It's called by the protocol code as long as it
726: has something to do. (We avoid transferring all the routes in single
727: pass in order not to monopolize CPU time.)
728: </function>
729: <function><p><type>void</type>
730: <funcdef>rt_feed_baby_abort</funcdef>
731: (<type>struct proto *</type> <param>p</param>) -- abort protocol feeding
732:
733: <funcsect>Arguments
734: <p><descrip>
735: <tagp><type>struct proto *</type> <param>p</param></tagp>
736: protocol
737: </descrip>
738: <funcsect>Description
739: <p>
740: This function is called by the protocol code when the protocol
741: stops or ceases to exist before the last iteration of <func/rt_feed_baby()/
742: has finished.
743: </function>
744: <function><p><type>net *</type>
745: <funcdef>net_find</funcdef>
746: (<type>rtable *</type> <param>tab</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>len</param>) -- find a network entry
747:
748: <funcsect>Arguments
749: <p><descrip>
750: <tagp><type>rtable *</type> <param>tab</param></tagp>
751: a routing table
752: <tagp><type>ip_addr</type> <param>addr</param></tagp>
753: address of the network
754: <tagp><type>unsigned</type> <param>len</param></tagp>
755: length of the network prefix
756: </descrip>
757: <funcsect>Description
758: <p>
759: <func/net_find()/ looks up the given network in routing table <param/tab/ and
760: returns a pointer to its <struct/net/ entry or <const/NULL/ if no such network
761: exists.
762: </function>
763: <function><p><type>net *</type>
764: <funcdef>net_get</funcdef>
765: (<type>rtable *</type> <param>tab</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>len</param>) -- obtain a network entry
766:
767: <funcsect>Arguments
768: <p><descrip>
769: <tagp><type>rtable *</type> <param>tab</param></tagp>
770: a routing table
771: <tagp><type>ip_addr</type> <param>addr</param></tagp>
772: address of the network
773: <tagp><type>unsigned</type> <param>len</param></tagp>
774: length of the network prefix
775: </descrip>
776: <funcsect>Description
777: <p>
778: <func/net_get()/ looks up the given network in routing table <param/tab/ and
779: returns a pointer to its <struct/net/ entry. If no such entry exists, it's
780: created.
781: </function>
782: <function><p><type>rte *</type>
783: <funcdef>rte_cow</funcdef>
784: (<type>rte *</type> <param>r</param>) -- copy a route for writing
785:
786: <funcsect>Arguments
787: <p><descrip>
788: <tagp><type>rte *</type> <param>r</param></tagp>
789: a route entry to be copied
790: </descrip>
791: <funcsect>Description
792: <p>
793: <func/rte_cow()/ takes a <struct/rte/ and prepares it for modification. The exact action
794: taken depends on the flags of the <struct/rte/ -- if it's a temporary entry, it's
795: just returned unchanged, else a new temporary entry with the same contents
796: is created.
797: <p>
798: The primary use of this function is inside the filter machinery -- when
799: a filter wants to modify <struct/rte/ contents (to change the preference or to
800: attach another set of attributes), it must ensure that the <struct/rte/ is not
801: shared with anyone else (and especially that it isn't stored in any routing
802: table).
803: <funcsect>Result
804: <p>
805: a pointer to the new writable <struct/rte/.
806: </function>
807: <sect>Route attribute cache
808: <p>
809: <p>
810: Each route entry carries a set of route attributes. Several of them
811: vary from route to route, but most attributes are usually common
812: for a large number of routes. To conserve memory, we've decided to
813: store only the varying ones directly in the <struct/rte/ and hold the rest
814: in a special structure called <struct/rta/ which is shared among all the
815: <struct/rte/'s with these attributes.
816: <p>
817: Each <struct/rta/ contains all the static attributes of the route (i.e.,
818: those which are always present) as structure members and a list of
819: dynamic attributes represented by a linked list of <struct/ea_list/
820: structures, each of them consisting of an array of <struct/eattr/'s containing
821: the individual attributes. An attribute can be specified more than once
822: in the <struct/ea_list/ chain and in such case the first occurrence overrides
823: the others. This semantics is used especially when someone (for example
824: a filter) wishes to alter values of several dynamic attributes, but
825: it wants to preserve the original attribute lists maintained by
826: another module.
827: <p>
828: Each <struct/eattr/ contains an attribute identifier (split to protocol ID and
829: per-protocol attribute ID), protocol dependent flags, a type code (consisting
830: of several bit fields describing attribute characteristics) and either an
831: embedded 32-bit value or a pointer to a <struct/adata/ structure holding attribute
832: contents.
833: <p>
834: There exist two variants of <struct/rta/'s -- cached and un-cached ones. Un-cached
835: <struct/rta/'s can have arbitrarily complex structure of <struct/ea_list/'s and they
836: can be modified by any module in the route processing chain. Cached
837: <struct/rta/'s have their attribute lists normalized (that means at most one
838: <struct/ea_list/ is present and its values are sorted in order to speed up
839: searching), they are stored in a hash table to make fast lookup possible
840: and they are provided with a use count to allow sharing.
841: <p>
842: Routing tables always contain only cached <struct/rta/'s.
843:
844:
845: <function><p><type>struct mpnh *</type>
846: <funcdef>mpnh_merge</funcdef>
847: (<type>struct mpnh *</type> <param>x</param>, <type>struct mpnh *</type> <param>y</param>, <type>int</type> <param>rx</param>, <type>int</type> <param>ry</param>, <type>int</type> <param>max</param>, <type>linpool *</type> <param>lp</param>) -- merge nexthop lists
848:
849: <funcsect>Arguments
850: <p><descrip>
851: <tagp><type>struct mpnh *</type> <param>x</param></tagp>
852: list 1
853: <tagp><type>struct mpnh *</type> <param>y</param></tagp>
854: list 2
855: <tagp><type>int</type> <param>rx</param></tagp>
856: reusability of list <param/x/
857: <tagp><type>int</type> <param>ry</param></tagp>
858: reusability of list <param/y/
859: <tagp><type>int</type> <param>max</param></tagp>
860: max number of nexthops
861: <tagp><type>linpool *</type> <param>lp</param></tagp>
862: linpool for allocating nexthops
863: </descrip>
864: <funcsect>Description
865: <p>
866: The <func/mpnh_merge()/ function takes two nexthop lists <param/x/ and <param/y/ and merges them,
867: eliminating possible duplicates. The input lists must be sorted and the
868: result is sorted too. The number of nexthops in result is limited by <param/max/.
869: New nodes are allocated from linpool <param/lp/.
870: <p>
871: The arguments <param/rx/ and <param/ry/ specify whether corresponding input lists may be
872: consumed by the function (i.e. their nodes reused in the resulting list), in
873: that case the caller should not access these lists after that. To eliminate
874: issues with deallocation of these lists, the caller should use some form of
875: bulk deallocation (e.g. stack or linpool) to free these nodes when the
876: resulting list is no longer needed. When reusability is not set, the
877: corresponding lists are not modified nor linked from the resulting list.
878: </function>
879: <function><p><type>eattr *</type>
880: <funcdef>ea_find</funcdef>
881: (<type>ea_list *</type> <param>e</param>, <type>unsigned</type> <param>id</param>) -- find an extended attribute
882:
883: <funcsect>Arguments
884: <p><descrip>
885: <tagp><type>ea_list *</type> <param>e</param></tagp>
886: attribute list to search in
887: <tagp><type>unsigned</type> <param>id</param></tagp>
888: attribute ID to search for
889: </descrip>
890: <funcsect>Description
891: <p>
892: Given an extended attribute list, <func/ea_find()/ searches for a first
893: occurrence of an attribute with specified ID, returning either a pointer
894: to its <struct/eattr/ structure or <const/NULL/ if no such attribute exists.
895: </function>
896: <function><p><type>eattr *</type>
897: <funcdef>ea_walk</funcdef>
898: (<type>struct ea_walk_state *</type> <param>s</param>, <type>uint</type> <param>id</param>, <type>uint</type> <param>max</param>) -- walk through extended attributes
899:
900: <funcsect>Arguments
901: <p><descrip>
902: <tagp><type>struct ea_walk_state *</type> <param>s</param></tagp>
903: walk state structure
904: <tagp><type>uint</type> <param>id</param></tagp>
905: start of attribute ID interval
906: <tagp><type>uint</type> <param>max</param></tagp>
907: length of attribute ID interval
908: </descrip>
909: <funcsect>Description
910: <p>
911: Given an extended attribute list, <func/ea_walk()/ walks through the list looking
912: for first occurrences of attributes with ID in specified interval from <param/id/ to
913: (<param/id/ + <param/max/ - 1), returning pointers to found <struct/eattr/ structures, storing its
914: walk state in <param/s/ for subsequent calls.
915: <p>
916: The function <func/ea_walk()/ is supposed to be called in a loop, with initially
917: zeroed walk state structure <param/s/ with filled the initial extended attribute
918: list, returning one found attribute in each call or <const/NULL/ when no other
919: attribute exists. The extended attribute list or the arguments should not be
920: modified between calls. The maximum value of <param/max/ is 128.
921: </function>
922: <function><p><type>int</type>
923: <funcdef>ea_get_int</funcdef>
924: (<type>ea_list *</type> <param>e</param>, <type>unsigned</type> <param>id</param>, <type>int</type> <param>def</param>) -- fetch an integer attribute
925:
926: <funcsect>Arguments
927: <p><descrip>
928: <tagp><type>ea_list *</type> <param>e</param></tagp>
929: attribute list
930: <tagp><type>unsigned</type> <param>id</param></tagp>
931: attribute ID
932: <tagp><type>int</type> <param>def</param></tagp>
933: default value
934: </descrip>
935: <funcsect>Description
936: <p>
937: This function is a shortcut for retrieving a value of an integer attribute
938: by calling <func/ea_find()/ to find the attribute, extracting its value or returning
939: a provided default if no such attribute is present.
940: </function>
941: <function><p><type>void</type>
942: <funcdef>ea_sort</funcdef>
943: (<type>ea_list *</type> <param>e</param>) -- sort an attribute list
944:
945: <funcsect>Arguments
946: <p><descrip>
947: <tagp><type>ea_list *</type> <param>e</param></tagp>
948: list to be sorted
949: </descrip>
950: <funcsect>Description
951: <p>
952: This function takes a <struct/ea_list/ chain and sorts the attributes
953: within each of its entries.
954: <p>
955: If an attribute occurs multiple times in a single <struct/ea_list/,
956: <func/ea_sort()/ leaves only the first (the only significant) occurrence.
957: </function>
958: <function><p><type>unsigned</type>
959: <funcdef>ea_scan</funcdef>
960: (<type>ea_list *</type> <param>e</param>) -- estimate attribute list size
961:
962: <funcsect>Arguments
963: <p><descrip>
964: <tagp><type>ea_list *</type> <param>e</param></tagp>
965: attribute list
966: </descrip>
967: <funcsect>Description
968: <p>
969: This function calculates an upper bound of the size of
970: a given <struct/ea_list/ after merging with <func/ea_merge()/.
971: </function>
972: <function><p><type>void</type>
973: <funcdef>ea_merge</funcdef>
974: (<type>ea_list *</type> <param>e</param>, <type>ea_list *</type> <param>t</param>) -- merge segments of an attribute list
975:
976: <funcsect>Arguments
977: <p><descrip>
978: <tagp><type>ea_list *</type> <param>e</param></tagp>
979: attribute list
980: <tagp><type>ea_list *</type> <param>t</param></tagp>
981: buffer to store the result to
982: </descrip>
983: <funcsect>Description
984: <p>
985: This function takes a possibly multi-segment attribute list
986: and merges all of its segments to one.
987: <p>
988: The primary use of this function is for <struct/ea_list/ normalization:
989: first call <func/ea_scan()/ to determine how much memory will the result
990: take, then allocate a buffer (usually using <func/alloca()/), merge the
991: segments with <func/ea_merge()/ and finally sort and prune the result
992: by calling <func/ea_sort()/.
993: </function>
994: <function><p><type>int</type>
995: <funcdef>ea_same</funcdef>
996: (<type>ea_list *</type> <param>x</param>, <type>ea_list *</type> <param>y</param>) -- compare two <struct/ea_list/'s
997:
998: <funcsect>Arguments
999: <p><descrip>
1000: <tagp><type>ea_list *</type> <param>x</param></tagp>
1001: attribute list
1002: <tagp><type>ea_list *</type> <param>y</param></tagp>
1003: attribute list
1004: </descrip>
1005: <funcsect>Description
1006: <p>
1007: <func/ea_same()/ compares two normalized attribute lists <param/x/ and <param/y/ and returns
1008: 1 if they contain the same attributes, 0 otherwise.
1009: </function>
1010: <function><p><type>void</type>
1011: <funcdef>ea_show</funcdef>
1012: (<type>struct cli *</type> <param>c</param>, <type>eattr *</type> <param>e</param>) -- print an <struct/eattr/ to CLI
1013:
1014: <funcsect>Arguments
1015: <p><descrip>
1016: <tagp><type>struct cli *</type> <param>c</param></tagp>
1017: destination CLI
1018: <tagp><type>eattr *</type> <param>e</param></tagp>
1019: attribute to be printed
1020: </descrip>
1021: <funcsect>Description
1022: <p>
1023: This function takes an extended attribute represented by its <struct/eattr/
1024: structure and prints it to the CLI according to the type information.
1025: <p>
1026: If the protocol defining the attribute provides its own
1027: <func/get_attr()/ hook, it's consulted first.
1028: </function>
1029: <function><p><type>void</type>
1030: <funcdef>ea_dump</funcdef>
1031: (<type>ea_list *</type> <param>e</param>) -- dump an extended attribute
1032:
1033: <funcsect>Arguments
1034: <p><descrip>
1035: <tagp><type>ea_list *</type> <param>e</param></tagp>
1036: attribute to be dumped
1037: </descrip>
1038: <funcsect>Description
1039: <p>
1040: <func/ea_dump()/ dumps contents of the extended attribute given to
1041: the debug output.
1042: </function>
1043: <function><p><type>uint</type>
1044: <funcdef>ea_hash</funcdef>
1045: (<type>ea_list *</type> <param>e</param>) -- calculate an <struct/ea_list/ hash key
1046:
1047: <funcsect>Arguments
1048: <p><descrip>
1049: <tagp><type>ea_list *</type> <param>e</param></tagp>
1050: attribute list
1051: </descrip>
1052: <funcsect>Description
1053: <p>
1054: <func/ea_hash()/ takes an extended attribute list and calculated a hopefully
1055: uniformly distributed hash value from its contents.
1056: </function>
1057: <function><p><type>ea_list *</type>
1058: <funcdef>ea_append</funcdef>
1059: (<type>ea_list *</type> <param>to</param>, <type>ea_list *</type> <param>what</param>) -- concatenate <struct/ea_list/'s
1060:
1061: <funcsect>Arguments
1062: <p><descrip>
1063: <tagp><type>ea_list *</type> <param>to</param></tagp>
1064: destination list (can be <const/NULL/)
1065: <tagp><type>ea_list *</type> <param>what</param></tagp>
1066: list to be appended (can be <const/NULL/)
1067: </descrip>
1068: <funcsect>Description
1069: <p>
1070: This function appends the <struct/ea_list/ <param/what/ at the end of
1071: <struct/ea_list/ <param/to/ and returns a pointer to the resulting list.
1072: </function>
1073: <function><p><type>rta *</type>
1074: <funcdef>rta_lookup</funcdef>
1075: (<type>rta *</type> <param>o</param>) -- look up a <struct/rta/ in attribute cache
1076:
1077: <funcsect>Arguments
1078: <p><descrip>
1079: <tagp><type>rta *</type> <param>o</param></tagp>
1080: a un-cached <struct/rta/
1081: </descrip>
1082: <funcsect>Description
1083: <p>
1084: <func/rta_lookup()/ gets an un-cached <struct/rta/ structure and returns its cached
1085: counterpart. It starts with examining the attribute cache to see whether
1086: there exists a matching entry. If such an entry exists, it's returned and
1087: its use count is incremented, else a new entry is created with use count
1088: set to 1.
1089: <p>
1090: The extended attribute lists attached to the <struct/rta/ are automatically
1091: converted to the normalized form.
1092: </function>
1093: <function><p><type>void</type>
1094: <funcdef>rta_dump</funcdef>
1095: (<type>rta *</type> <param>a</param>) -- dump route attributes
1096:
1097: <funcsect>Arguments
1098: <p><descrip>
1099: <tagp><type>rta *</type> <param>a</param></tagp>
1100: attribute structure to dump
1101: </descrip>
1102: <funcsect>Description
1103: <p>
1104: This function takes a <struct/rta/ and dumps its contents to the debug output.
1105: </function>
1106: <function><p><type>void</type>
1107: <funcdef>rta_dump_all</funcdef>
1108: (<param>void</param>) -- dump attribute cache
1109:
1110: <funcsect>Description
1111: <p>
1112: <p>
1113: This function dumps the whole contents of route attribute cache
1114: to the debug output.
1115: </function>
1116: <function><p><type>void</type>
1117: <funcdef>rta_init</funcdef>
1118: (<param>void</param>) -- initialize route attribute cache
1119:
1120: <funcsect>Description
1121: <p>
1122: <p>
1123: This function is called during initialization of the routing
1124: table module to set up the internals of the attribute cache.
1125: </function>
1126: <function><p><type>rta *</type>
1127: <funcdef>rta_clone</funcdef>
1128: (<type>rta *</type> <param>r</param>) -- clone route attributes
1129:
1130: <funcsect>Arguments
1131: <p><descrip>
1132: <tagp><type>rta *</type> <param>r</param></tagp>
1133: a <struct/rta/ to be cloned
1134: </descrip>
1135: <funcsect>Description
1136: <p>
1137: <func/rta_clone()/ takes a cached <struct/rta/ and returns its identical cached
1138: copy. Currently it works by just returning the original <struct/rta/ with
1139: its use count incremented.
1140: </function>
1141: <function><p><type>void</type>
1142: <funcdef>rta_free</funcdef>
1143: (<type>rta *</type> <param>r</param>) -- free route attributes
1144:
1145: <funcsect>Arguments
1146: <p><descrip>
1147: <tagp><type>rta *</type> <param>r</param></tagp>
1148: a <struct/rta/ to be freed
1149: </descrip>
1150: <funcsect>Description
1151: <p>
1152: If you stop using a <struct/rta/ (for example when deleting a route which uses
1153: it), you need to call <func/rta_free()/ to notify the attribute cache the
1154: attribute is no longer in use and can be freed if you were the last
1155: user (which <func/rta_free()/ tests by inspecting the use count).
1156: </function>
1157: <!--
1158: BIRD Programmer's Guide: Protocols
1159:
1160: (c) 2000 Martin Mares <mj@ucw.cz>
1161: -->
1162:
1163: <sect>Routing protocols
1164:
1165: <sect1>Introduction
1166:
1167: <p>The routing protocols are the bird's heart and a fine amount of code
1168: is dedicated to their management and for providing support functions to them.
1169: (-: Actually, this is the reason why the directory with sources of the core
1170: code is called <tt/nest/ :-).
1171:
1172: <p>When talking about protocols, one need to distinguish between <em/protocols/
1173: and protocol <em/instances/. A protocol exists exactly once, not depending on whether
1174: it's configured or not and it can have an arbitrary number of instances corresponding
1175: to its "incarnations" requested by the configuration file. Each instance is completely
1176: autonomous, has its own configuration, its own status, its own set of routes and its
1177: own set of interfaces it works on.
1178:
1179: <p>A protocol is represented by a <struct/protocol/ structure containing all the basic
1180: information (protocol name, default settings and pointers to most of the protocol
1181: hooks). All these structures are linked in the <param/protocol_list/ list.
1182:
1183: <p>Each instance has its own <struct/proto/ structure describing all its properties: protocol
1184: type, configuration, a resource pool where all resources belonging to the instance
1185: live, various protocol attributes (take a look at the declaration of <struct/proto/ in
1186: <tt/protocol.h/), protocol states (see below for what do they mean), connections
1187: to routing tables, filters attached to the protocol
1188: and finally a set of pointers to the rest of protocol hooks (they
1189: are the same for all instances of the protocol, but in order to avoid extra
1190: indirections when calling the hooks from the fast path, they are stored directly
1191: in <struct/proto/). The instance is always linked in both the global instance list
1192: (<param/proto_list/) and a per-status list (either <param/active_proto_list/ for
1193: running protocols, <param/initial_proto_list/ for protocols being initialized or
1194: <param/flush_proto_list/ when the protocol is being shut down).
1195:
1196: <p>The protocol hooks are described in the next chapter, for more information about
1197: configuration of protocols, please refer to the configuration chapter and also
1198: to the description of the <func/proto_commit/ function.
1199:
1200: <sect1>Protocol states
1201:
1202: <p>As startup and shutdown of each protocol are complex processes which can be affected
1203: by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.),
1204: we have decided to supervise them by a pair of simple state machines -- the protocol
1205: state machine and a core state machine.
1206:
1207: <p>The <em/protocol state machine/ corresponds to internal state of the protocol
1208: and the protocol can alter its state whenever it wants to. There are
1209: the following states:
1210:
1211: <descrip>
1212: <tag/PS_DOWN/ The protocol is down and waits for being woken up by calling its
1213: start() hook.
1214: <tag/PS_START/ The protocol is waiting for connection with the rest of the
1215: network. It's active, it has resources allocated, but it still doesn't want
1216: any routes since it doesn't know what to do with them.
1217: <tag/PS_UP/ The protocol is up and running. It communicates with the core,
1218: delivers routes to tables and wants to hear announcement about route changes.
1219: <tag/PS_STOP/ The protocol has been shut down (either by being asked by the
1220: core code to do so or due to having encountered a protocol error).
1221: </descrip>
1222:
1223: <p>Unless the protocol is in the <tt/PS_DOWN/ state, it can decide to change
1224: its state by calling the <func/proto_notify_state/ function.
1225:
1226: <p>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.
1227:
1228: <p>The <em/core state machine/ takes care of the core view of protocol state.
1229: The states are traversed according to changes of the protocol state machine, but
1230: sometimes the transitions are delayed if the core needs to finish some actions
1231: (for example sending of new routes to the protocol) before proceeding to the
1232: new state. There are the following core states:
1233:
1234: <descrip>
1235: <tag/FS_HUNGRY/ The protocol is down, it doesn't have any routes and
1236: doesn't want them.
1237: <tag/FS_FEEDING/ The protocol has reached the <tt/PS_UP/ state, but
1238: we are still busy sending the initial set of routes to it.
1239: <tag/FS_HAPPY/ The protocol is up and has complete routing information.
1240: <tag/FS_FLUSHING/ The protocol is shutting down (it's in either <tt/PS_STOP/
1241: or <tt/PS_DOWN/ state) and we're flushing all of its routes from the
1242: routing tables.
1243: </descrip>
1244:
1245: <sect1>Functions of the protocol module
1246:
1247: <p>The protocol module provides the following functions:
1248: <function><p><type>void *</type>
1249: <funcdef>proto_new</funcdef>
1250: (<type>struct proto_config *</type> <param>c</param>, <type>unsigned</type> <param>size</param>) -- create a new protocol instance
1251:
1252: <funcsect>Arguments
1253: <p><descrip>
1254: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
1255: protocol configuration
1256: <tagp><type>unsigned</type> <param>size</param></tagp>
1257: size of protocol data structure (each protocol instance is represented by
1258: a structure starting with generic part [struct <struct/proto/] and continued
1259: with data specific to the protocol)
1260: </descrip>
1261: <funcsect>Description
1262: <p>
1263: When a new configuration has been read in, the core code starts
1264: initializing all the protocol instances configured by calling their
1265: <func/init()/ hooks with the corresponding instance configuration. The initialization
1266: code of the protocol is expected to create a new instance according to the
1267: configuration by calling this function and then modifying the default settings
1268: to values wanted by the protocol.
1269: </function>
1270: <function><p><type>struct announce_hook *</type>
1271: <funcdef>proto_add_announce_hook</funcdef>
1272: (<type>struct proto *</type> <param>p</param>, <type>struct rtable *</type> <param>t</param>, <type>struct proto_stats *</type> <param>stats</param>) -- connect protocol to a routing table
1273:
1274: <funcsect>Arguments
1275: <p><descrip>
1276: <tagp><type>struct proto *</type> <param>p</param></tagp>
1277: protocol instance
1278: <tagp><type>struct rtable *</type> <param>t</param></tagp>
1279: routing table to connect to
1280: <tagp><type>struct proto_stats *</type> <param>stats</param></tagp>
1281: per-table protocol statistics
1282: </descrip>
1283: <funcsect>Description
1284: <p>
1285: This function creates a connection between the protocol instance <param/p/ and the
1286: routing table <param/t/, making the protocol hear all changes in the table.
1287: <p>
1288: The announce hook is linked in the protocol ahook list. Announce hooks are
1289: allocated from the routing table resource pool and when protocol accepts
1290: routes also in the table ahook list. The are linked to the table ahook list
1291: and unlinked from it depending on export_state (in <func/proto_want_export_up()/ and
1292: <func/proto_want_export_down()/) and they are automatically freed after the protocol
1293: is flushed (in <func/proto_fell_down()/).
1294: <p>
1295: Unless you want to listen to multiple routing tables (as the Pipe protocol
1296: does), you needn't to worry about this function since the connection to the
1297: protocol's primary routing table is initialized automatically by the core
1298: code.
1299: </function>
1300: <function><p><type>struct announce_hook *</type>
1301: <funcdef>proto_find_announce_hook</funcdef>
1302: (<type>struct proto *</type> <param>p</param>, <type>struct rtable *</type> <param>t</param>) -- find announce hooks
1303:
1304: <funcsect>Arguments
1305: <p><descrip>
1306: <tagp><type>struct proto *</type> <param>p</param></tagp>
1307: protocol instance
1308: <tagp><type>struct rtable *</type> <param>t</param></tagp>
1309: routing table
1310: </descrip>
1311: <funcsect>Description
1312: <p>
1313: Returns pointer to announce hook or NULL
1314: </function>
1315: <function><p><type>void *</type>
1316: <funcdef>proto_config_new</funcdef>
1317: (<type>struct protocol *</type> <param>pr</param>, <type>int</type> <param>class</param>) -- create a new protocol configuration
1318:
1319: <funcsect>Arguments
1320: <p><descrip>
1321: <tagp><type>struct protocol *</type> <param>pr</param></tagp>
1322: protocol the configuration will belong to
1323: <tagp><type>int</type> <param>class</param></tagp>
1324: SYM_PROTO or SYM_TEMPLATE
1325: </descrip>
1326: <funcsect>Description
1327: <p>
1328: Whenever the configuration file says that a new instance
1329: of a routing protocol should be created, the parser calls
1330: <func/proto_config_new()/ to create a configuration entry for this
1331: instance (a structure staring with the <struct/proto_config/ header
1332: containing all the generic items followed by protocol-specific
1333: ones). Also, the configuration entry gets added to the list
1334: of protocol instances kept in the configuration.
1335: <p>
1336: The function is also used to create protocol templates (when class
1337: SYM_TEMPLATE is specified), the only difference is that templates
1338: are not added to the list of protocol instances and therefore not
1339: initialized during <func/protos_commit()/).
1340: </function>
1341: <function><p><type>void</type>
1342: <funcdef>proto_copy_config</funcdef>
1343: (<type>struct proto_config *</type> <param>dest</param>, <type>struct proto_config *</type> <param>src</param>) -- copy a protocol configuration
1344:
1345: <funcsect>Arguments
1346: <p><descrip>
1347: <tagp><type>struct proto_config *</type> <param>dest</param></tagp>
1348: destination protocol configuration
1349: <tagp><type>struct proto_config *</type> <param>src</param></tagp>
1350: source protocol configuration
1351: </descrip>
1352: <funcsect>Description
1353: <p>
1354: Whenever a new instance of a routing protocol is created from the
1355: template, <func/proto_copy_config()/ is called to copy a content of
1356: the source protocol configuration to the new protocol configuration.
1357: Name, class and a node in protos list of <param/dest/ are kept intact.
1358: <func/copy_config()/ protocol hook is used to copy protocol-specific data.
1359: </function>
1360: <function><p><type>void</type>
1361: <funcdef>protos_preconfig</funcdef>
1362: (<type>struct config *</type> <param>c</param>) -- pre-configuration processing
1363:
1364: <funcsect>Arguments
1365: <p><descrip>
1366: <tagp><type>struct config *</type> <param>c</param></tagp>
1367: new configuration
1368: </descrip>
1369: <funcsect>Description
1370: <p>
1371: This function calls the <func/preconfig()/ hooks of all routing
1372: protocols available to prepare them for reading of the new
1373: configuration.
1374: </function>
1375: <function><p><type>void</type>
1376: <funcdef>protos_postconfig</funcdef>
1377: (<type>struct config *</type> <param>c</param>) -- post-configuration processing
1378:
1379: <funcsect>Arguments
1380: <p><descrip>
1381: <tagp><type>struct config *</type> <param>c</param></tagp>
1382: new configuration
1383: </descrip>
1384: <funcsect>Description
1385: <p>
1386: This function calls the <func/postconfig()/ hooks of all protocol
1387: instances specified in configuration <param/c/. The hooks are not
1388: called for protocol templates.
1389: </function>
1390: <function><p><type>void</type>
1391: <funcdef>protos_commit</funcdef>
1392: (<type>struct config *</type> <param>new</param>, <type>struct config *</type> <param>old</param>, <type>int</type> <param>force_reconfig</param>, <type>int</type> <param>type</param>) -- commit new protocol configuration
1393:
1394: <funcsect>Arguments
1395: <p><descrip>
1396: <tagp><type>struct config *</type> <param>new</param></tagp>
1397: new configuration
1398: <tagp><type>struct config *</type> <param>old</param></tagp>
1399: old configuration or <const/NULL/ if it's boot time config
1400: <tagp><type>int</type> <param>force_reconfig</param></tagp>
1401: force restart of all protocols (used for example
1402: when the router ID changes)
1403: <tagp><type>int</type> <param>type</param></tagp>
1404: type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)
1405: </descrip>
1406: <funcsect>Description
1407: <p>
1408: Scan differences between <param/old/ and <param/new/ configuration and adjust all
1409: protocol instances to conform to the new configuration.
1410: <p>
1411: When a protocol exists in the new configuration, but it doesn't in the
1412: original one, it's immediately started. When a collision with the other
1413: running protocol would arise, the new protocol will be temporarily stopped
1414: by the locking mechanism.
1415: <p>
1416: When a protocol exists in the old configuration, but it doesn't in the
1417: new one, it's shut down and deleted after the shutdown completes.
1418: <p>
1419: When a protocol exists in both configurations, the core decides
1420: whether it's possible to reconfigure it dynamically - it checks all
1421: the core properties of the protocol (changes in filters are ignored
1422: if type is RECONFIG_SOFT) and if they match, it asks the
1423: <func/reconfigure()/ hook of the protocol to see if the protocol is able
1424: to switch to the new configuration. If it isn't possible, the
1425: protocol is shut down and a new instance is started with the new
1426: configuration after the shutdown is completed.
1427: </function>
1428: <sect>Graceful restart recovery
1429: <p>
1430: <p>
1431: Graceful restart of a router is a process when the routing plane (e.g. BIRD)
1432: restarts but both the forwarding plane (e.g kernel routing table) and routing
1433: neighbors keep proper routes, and therefore uninterrupted packet forwarding
1434: is maintained.
1435: <p>
1436: BIRD implements graceful restart recovery by deferring export of routes to
1437: protocols until routing tables are refilled with the expected content. After
1438: start, protocols generate routes as usual, but routes are not propagated to
1439: them, until protocols report that they generated all routes. After that,
1440: graceful restart recovery is finished and the export (and the initial feed)
1441: to protocols is enabled.
1442: <p>
1443: When graceful restart recovery need is detected during initialization, then
1444: enabled protocols are marked with <param/gr_recovery/ flag before start. Such
1445: protocols then decide how to proceed with graceful restart, participation is
1446: voluntary. Protocols could lock the recovery by <func/proto_graceful_restart_lock()/
1447: (stored in <param/gr_lock/ flag), which means that they want to postpone the end of
1448: the recovery until they converge and then unlock it. They also could set
1449: <param/gr_wait/ before advancing to <const/PS_UP/, which means that the core should defer
1450: route export to that protocol until the end of the recovery. This should be
1451: done by protocols that expect their neigbors to keep the proper routes
1452: (kernel table, BGP sessions with BGP graceful restart capability).
1453: <p>
1454: The graceful restart recovery is finished when either all graceful restart
1455: locks are unlocked or when graceful restart wait timer fires.
1456:
1457:
1458: <function><p><type>void</type>
1459: <funcdef>graceful_restart_recovery</funcdef>
1460: (<param>void</param>) -- request initial graceful restart recovery
1461:
1462: <funcsect>Graceful restart recovery
1463: <p>
1464: <p>
1465: Called by the platform initialization code if the need for recovery
1466: after graceful restart is detected during boot. Have to be called
1467: before <func/protos_commit()/.
1468: </function>
1469: <function><p><type>void</type>
1470: <funcdef>graceful_restart_init</funcdef>
1471: (<param>void</param>) -- initialize graceful restart
1472:
1473: <funcsect>Description
1474: <p>
1475: <p>
1476: When graceful restart recovery was requested, the function starts an active
1477: phase of the recovery and initializes graceful restart wait timer. The
1478: function have to be called after <func/protos_commit()/.
1479: </function>
1480: <function><p><type>void</type>
1481: <funcdef>graceful_restart_done</funcdef>
1482: (<type>struct timer *t</type> <param>UNUSED</param>) -- finalize graceful restart
1483:
1484: <funcsect>Arguments
1485: <p><descrip>
1486: <tagp><type>struct timer *t</type> <param>UNUSED</param></tagp>
1487: -- undescribed --
1488: </descrip>
1489: <funcsect>Description
1490: <p>
1491: When there are no locks on graceful restart, the functions finalizes the
1492: graceful restart recovery. Protocols postponing route export until the end of
1493: the recovery are awakened and the export to them is enabled. All other
1494: related state is cleared. The function is also called when the graceful
1495: restart wait timer fires (but there are still some locks).
1496: </function>
1497: <function><p><type>void</type>
1498: <funcdef>proto_graceful_restart_lock</funcdef>
1499: (<type>struct proto *</type> <param>p</param>) -- lock graceful restart by protocol
1500:
1501: <funcsect>Arguments
1502: <p><descrip>
1503: <tagp><type>struct proto *</type> <param>p</param></tagp>
1504: protocol instance
1505: </descrip>
1506: <funcsect>Description
1507: <p>
1508: This function allows a protocol to postpone the end of graceful restart
1509: recovery until it converges. The lock is removed when the protocol calls
1510: <func/proto_graceful_restart_unlock()/ or when the protocol is stopped.
1511: <p>
1512: The function have to be called during the initial phase of graceful restart
1513: recovery and only for protocols that are part of graceful restart (i.e. their
1514: <param/gr_recovery/ is set), which means it should be called from protocol start
1515: hooks.
1516: </function>
1517: <function><p><type>void</type>
1518: <funcdef>proto_graceful_restart_unlock</funcdef>
1519: (<type>struct proto *</type> <param>p</param>) -- unlock graceful restart by protocol
1520:
1521: <funcsect>Arguments
1522: <p><descrip>
1523: <tagp><type>struct proto *</type> <param>p</param></tagp>
1524: protocol instance
1525: </descrip>
1526: <funcsect>Description
1527: <p>
1528: This function unlocks a lock from <func/proto_graceful_restart_lock()/. It is also
1529: automatically called when the lock holding protocol went down.
1530: </function>
1531: <function><p><type>void</type>
1532: <funcdef>protos_dump_all</funcdef>
1533: (<param>void</param>) -- dump status of all protocols
1534:
1535: <funcsect>Description
1536: <p>
1537: <p>
1538: This function dumps status of all existing protocol instances to the
1539: debug output. It involves printing of general status information
1540: such as protocol states, its position on the protocol lists
1541: and also calling of a <func/dump()/ hook of the protocol to print
1542: the internals.
1543: </function>
1544: <function><p><type>void</type>
1545: <funcdef>proto_build</funcdef>
1546: (<type>struct protocol *</type> <param>p</param>) -- make a single protocol available
1547:
1548: <funcsect>Arguments
1549: <p><descrip>
1550: <tagp><type>struct protocol *</type> <param>p</param></tagp>
1551: the protocol
1552: </descrip>
1553: <funcsect>Description
1554: <p>
1555: After the platform specific initialization code uses <func/protos_build()/
1556: to add all the standard protocols, it should call <func/proto_build()/ for
1557: all platform specific protocols to inform the core that they exist.
1558: </function>
1559: <function><p><type>void</type>
1560: <funcdef>protos_build</funcdef>
1561: (<param>void</param>) -- build a protocol list
1562:
1563: <funcsect>Description
1564: <p>
1565: <p>
1566: This function is called during BIRD startup to insert
1567: all standard protocols to the global protocol list. Insertion
1568: of platform specific protocols (such as the kernel syncer)
1569: is in the domain of competence of the platform dependent
1570: startup code.
1571: </function>
1572: <function><p><type>void</type>
1573: <funcdef>proto_set_message</funcdef>
1574: (<type>struct proto *</type> <param>p</param>, <type>char *</type> <param>msg</param>, <type>int</type> <param>len</param>) -- set administrative message to protocol
1575:
1576: <funcsect>Arguments
1577: <p><descrip>
1578: <tagp><type>struct proto *</type> <param>p</param></tagp>
1579: protocol
1580: <tagp><type>char *</type> <param>msg</param></tagp>
1581: message
1582: <tagp><type>int</type> <param>len</param></tagp>
1583: message length (-1 for NULL-terminated string)
1584: </descrip>
1585: <funcsect>Description
1586: <p>
1587: The function sets administrative message (string) related to protocol state
1588: change. It is called by the nest code for manual enable/disable/restart
1589: commands all routes to the protocol, and by protocol-specific code when the
1590: protocol state change is initiated by the protocol. Using NULL message clears
1591: the last message. The message string may be either NULL-terminated or with an
1592: explicit length.
1593: </function>
1594: <function><p><type>void</type>
1595: <funcdef>proto_request_feeding</funcdef>
1596: (<type>struct proto *</type> <param>p</param>) -- request feeding routes to the protocol
1597:
1598: <funcsect>Arguments
1599: <p><descrip>
1600: <tagp><type>struct proto *</type> <param>p</param></tagp>
1601: given protocol
1602: </descrip>
1603: <funcsect>Description
1604: <p>
1605: Sometimes it is needed to send again all routes to the
1606: protocol. This is called feeding and can be requested by this
1607: function. This would cause protocol export state transition
1608: to ES_FEEDING (during feeding) and when completed, it will
1609: switch back to ES_READY. This function can be called even
1610: when feeding is already running, in that case it is restarted.
1611: </function>
1612: <function><p><type>void</type>
1613: <funcdef>proto_notify_limit</funcdef>
1614: (<type>struct announce_hook *</type> <param>ah</param>, <type>struct proto_limit *</type> <param>l</param>, <type>int</type> <param>dir</param>, <type>u32</type> <param>rt_count</param>)
1615: <funcsect>Arguments
1616: <p><descrip>
1617: <tagp><type>struct announce_hook *</type> <param>ah</param></tagp>
1618: announce hook
1619: <tagp><type>struct proto_limit *</type> <param>l</param></tagp>
1620: limit being hit
1621: <tagp><type>int</type> <param>dir</param></tagp>
1622: limit direction (PLD_*)
1623: <tagp><type>u32</type> <param>rt_count</param></tagp>
1624: the number of routes
1625: </descrip>
1626: <funcsect>Description
1627: <p>
1628: The function is called by the route processing core when limit <param/l/
1629: is breached. It activates the limit and tooks appropriate action
1630: according to <param/l/->action.
1631: </function>
1632: <function><p><type>void</type>
1633: <funcdef>proto_notify_state</funcdef>
1634: (<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>ps</param>) -- notify core about protocol state change
1635:
1636: <funcsect>Arguments
1637: <p><descrip>
1638: <tagp><type>struct proto *</type> <param>p</param></tagp>
1639: protocol the state of which has changed
1640: <tagp><type>unsigned</type> <param>ps</param></tagp>
1641: the new status
1642: </descrip>
1643: <funcsect>Description
1644: <p>
1645: Whenever a state of a protocol changes due to some event internal
1646: to the protocol (i.e., not inside a <func/start()/ or <func/shutdown()/ hook),
1647: it should immediately notify the core about the change by calling
1648: <func/proto_notify_state()/ which will write the new state to the <struct/proto/
1649: structure and take all the actions necessary to adapt to the new
1650: state. State change to PS_DOWN immediately frees resources of protocol
1651: and might execute start callback of protocol; therefore,
1652: it should be used at tail positions of protocol callbacks.
1653: </function>
1654: <sect>Protocol hooks
1655: <p>
1656: <p>
1657: Each protocol can provide a rich set of hook functions referred to by pointers
1658: in either the <struct/proto/ or <struct/protocol/ structure. They are called by the core whenever
1659: it wants the protocol to perform some action or to notify the protocol about
1660: any change of its environment. All of the hooks can be set to <const/NULL/ which means
1661: to ignore the change or to take a default action.
1662:
1663:
1664: <function><p><type>void</type>
1665: <funcdef>preconfig</funcdef>
1666: (<type>struct protocol *</type> <param>p</param>, <type>struct config *</type> <param>c</param>) -- protocol preconfiguration
1667:
1668: <funcsect>Arguments
1669: <p><descrip>
1670: <tagp><type>struct protocol *</type> <param>p</param></tagp>
1671: a routing protocol
1672: <tagp><type>struct config *</type> <param>c</param></tagp>
1673: new configuration
1674: </descrip>
1675: <funcsect>Description
1676: <p>
1677: The <func/preconfig()/ hook is called before parsing of a new configuration.
1678: </function>
1679: <function><p><type>void</type>
1680: <funcdef>postconfig</funcdef>
1681: (<type>struct proto_config *</type> <param>c</param>) -- instance post-configuration
1682:
1683: <funcsect>Arguments
1684: <p><descrip>
1685: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
1686: instance configuration
1687: </descrip>
1688: <funcsect>Description
1689: <p>
1690: The <func/postconfig()/ hook is called for each configured instance after
1691: parsing of the new configuration is finished.
1692: </function>
1693: <function><p><type>struct proto *</type>
1694: <funcdef>init</funcdef>
1695: (<type>struct proto_config *</type> <param>c</param>) -- initialize an instance
1696:
1697: <funcsect>Arguments
1698: <p><descrip>
1699: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
1700: instance configuration
1701: </descrip>
1702: <funcsect>Description
1703: <p>
1704: The <func/init()/ hook is called by the core to create a protocol instance
1705: according to supplied protocol configuration.
1706: <funcsect>Result
1707: <p>
1708: a pointer to the instance created
1709: </function>
1710: <function><p><type>int</type>
1711: <funcdef>reconfigure</funcdef>
1712: (<type>struct proto *</type> <param>p</param>, <type>struct proto_config *</type> <param>c</param>) -- request instance reconfiguration
1713:
1714: <funcsect>Arguments
1715: <p><descrip>
1716: <tagp><type>struct proto *</type> <param>p</param></tagp>
1717: an instance
1718: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
1719: new configuration
1720: </descrip>
1721: <funcsect>Description
1722: <p>
1723: The core calls the <func/reconfigure()/ hook whenever it wants to ask the
1724: protocol for switching to a new configuration. If the reconfiguration
1725: is possible, the hook returns 1. Otherwise, it returns 0 and the core
1726: will shut down the instance and start a new one with the new configuration.
1727: <p>
1728: After the protocol confirms reconfiguration, it must no longer keep any
1729: references to the old configuration since the memory it's stored in can
1730: be re-used at any time.
1731: </function>
1732: <function><p><type>void</type>
1733: <funcdef>dump</funcdef>
1734: (<type>struct proto *</type> <param>p</param>) -- dump protocol state
1735:
1736: <funcsect>Arguments
1737: <p><descrip>
1738: <tagp><type>struct proto *</type> <param>p</param></tagp>
1739: an instance
1740: </descrip>
1741: <funcsect>Description
1742: <p>
1743: This hook dumps the complete state of the instance to the
1744: debug output.
1745: </function>
1746: <function><p><type>void</type>
1747: <funcdef>dump_attrs</funcdef>
1748: (<type>rte *</type> <param>e</param>) -- dump protocol-dependent attributes
1749:
1750: <funcsect>Arguments
1751: <p><descrip>
1752: <tagp><type>rte *</type> <param>e</param></tagp>
1753: a route entry
1754: </descrip>
1755: <funcsect>Description
1756: <p>
1757: This hook dumps all attributes in the <struct/rte/ which belong to this
1758: protocol to the debug output.
1759: </function>
1760: <function><p><type>int</type>
1761: <funcdef>start</funcdef>
1762: (<type>struct proto *</type> <param>p</param>) -- request instance startup
1763:
1764: <funcsect>Arguments
1765: <p><descrip>
1766: <tagp><type>struct proto *</type> <param>p</param></tagp>
1767: protocol instance
1768: </descrip>
1769: <funcsect>Description
1770: <p>
1771: The <func/start()/ hook is called by the core when it wishes to start
1772: the instance. Multitable protocols should lock their tables here.
1773: <funcsect>Result
1774: <p>
1775: new protocol state
1776: </function>
1777: <function><p><type>int</type>
1778: <funcdef>shutdown</funcdef>
1779: (<type>struct proto *</type> <param>p</param>) -- request instance shutdown
1780:
1781: <funcsect>Arguments
1782: <p><descrip>
1783: <tagp><type>struct proto *</type> <param>p</param></tagp>
1784: protocol instance
1785: </descrip>
1786: <funcsect>Description
1787: <p>
1788: The <func/stop()/ hook is called by the core when it wishes to shut
1789: the instance down for some reason.
1790: <funcsect>Returns
1791: <p>
1792: new protocol state
1793: </function>
1794: <function><p><type>void</type>
1795: <funcdef>cleanup</funcdef>
1796: (<type>struct proto *</type> <param>p</param>) -- request instance cleanup
1797:
1798: <funcsect>Arguments
1799: <p><descrip>
1800: <tagp><type>struct proto *</type> <param>p</param></tagp>
1801: protocol instance
1802: </descrip>
1803: <funcsect>Description
1804: <p>
1805: The <func/cleanup()/ hook is called by the core when the protocol became
1806: hungry/down, i.e. all protocol ahooks and routes are flushed.
1807: Multitable protocols should unlock their tables here.
1808: </function>
1809: <function><p><type>void</type>
1810: <funcdef>get_status</funcdef>
1811: (<type>struct proto *</type> <param>p</param>, <type>byte *</type> <param>buf</param>) -- get instance status
1812:
1813: <funcsect>Arguments
1814: <p><descrip>
1815: <tagp><type>struct proto *</type> <param>p</param></tagp>
1816: protocol instance
1817: <tagp><type>byte *</type> <param>buf</param></tagp>
1818: buffer to be filled with the status string
1819: </descrip>
1820: <funcsect>Description
1821: <p>
1822: This hook is called by the core if it wishes to obtain an brief one-line user friendly
1823: representation of the status of the instance to be printed by the <cf/show protocols/
1824: command.
1825: </function>
1826: <function><p><type>void</type>
1827: <funcdef>get_route_info</funcdef>
1828: (<type>rte *</type> <param>e</param>, <type>byte *</type> <param>buf</param>, <type>ea_list *</type> <param>attrs</param>) -- get route information
1829:
1830: <funcsect>Arguments
1831: <p><descrip>
1832: <tagp><type>rte *</type> <param>e</param></tagp>
1833: a route entry
1834: <tagp><type>byte *</type> <param>buf</param></tagp>
1835: buffer to be filled with the resulting string
1836: <tagp><type>ea_list *</type> <param>attrs</param></tagp>
1837: extended attributes of the route
1838: </descrip>
1839: <funcsect>Description
1840: <p>
1841: This hook is called to fill the buffer <param/buf/ with a brief user friendly
1842: representation of metrics of a route belonging to this protocol.
1843: </function>
1844: <function><p><type>int</type>
1845: <funcdef>get_attr</funcdef>
1846: (<type>eattr *</type> <param>a</param>, <type>byte *</type> <param>buf</param>, <type>int</type> <param>buflen</param>) -- get attribute information
1847:
1848: <funcsect>Arguments
1849: <p><descrip>
1850: <tagp><type>eattr *</type> <param>a</param></tagp>
1851: an extended attribute
1852: <tagp><type>byte *</type> <param>buf</param></tagp>
1853: buffer to be filled with attribute information
1854: <tagp><type>int</type> <param>buflen</param></tagp>
1855: a length of the <param/buf/ parameter
1856: </descrip>
1857: <funcsect>Description
1858: <p>
1859: The <func/get_attr()/ hook is called by the core to obtain a user friendly
1860: representation of an extended route attribute. It can either leave
1861: the whole conversion to the core (by returning <const/GA_UNKNOWN/), fill
1862: in only attribute name (and let the core format the attribute value
1863: automatically according to the type field; by returning <const/GA_NAME/)
1864: or doing the whole conversion (used in case the value requires extra
1865: care; return <const/GA_FULL/).
1866: </function>
1867: <function><p><type>void</type>
1868: <funcdef>if_notify</funcdef>
1869: (<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>flags</param>, <type>struct iface *</type> <param>i</param>) -- notify instance about interface changes
1870:
1871: <funcsect>Arguments
1872: <p><descrip>
1873: <tagp><type>struct proto *</type> <param>p</param></tagp>
1874: protocol instance
1875: <tagp><type>unsigned</type> <param>flags</param></tagp>
1876: interface change flags
1877: <tagp><type>struct iface *</type> <param>i</param></tagp>
1878: the interface in question
1879: </descrip>
1880: <funcsect>Description
1881: <p>
1882: This hook is called whenever any network interface changes its status.
1883: The change is described by a combination of status bits (<const/IF_CHANGE_xxx/)
1884: in the <param/flags/ parameter.
1885: </function>
1886: <function><p><type>void</type>
1887: <funcdef>ifa_notify</funcdef>
1888: (<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>flags</param>, <type>struct ifa *</type> <param>a</param>) -- notify instance about interface address changes
1889:
1890: <funcsect>Arguments
1891: <p><descrip>
1892: <tagp><type>struct proto *</type> <param>p</param></tagp>
1893: protocol instance
1894: <tagp><type>unsigned</type> <param>flags</param></tagp>
1895: address change flags
1896: <tagp><type>struct ifa *</type> <param>a</param></tagp>
1897: the interface address
1898: </descrip>
1899: <funcsect>Description
1900: <p>
1901: This hook is called to notify the protocol instance about an interface
1902: acquiring or losing one of its addresses. The change is described by
1903: a combination of status bits (<const/IF_CHANGE_xxx/) in the <param/flags/ parameter.
1904: </function>
1905: <function><p><type>void</type>
1906: <funcdef>rt_notify</funcdef>
1907: (<type>struct proto *</type> <param>p</param>, <type>net *</type> <param>net</param>, <type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>, <type>ea_list *</type> <param>attrs</param>) -- notify instance about routing table change
1908:
1909: <funcsect>Arguments
1910: <p><descrip>
1911: <tagp><type>struct proto *</type> <param>p</param></tagp>
1912: protocol instance
1913: <tagp><type>net *</type> <param>net</param></tagp>
1914: a network entry
1915: <tagp><type>rte *</type> <param>new</param></tagp>
1916: new route for the network
1917: <tagp><type>rte *</type> <param>old</param></tagp>
1918: old route for the network
1919: <tagp><type>ea_list *</type> <param>attrs</param></tagp>
1920: extended attributes associated with the <param/new/ entry
1921: </descrip>
1922: <funcsect>Description
1923: <p>
1924: The <func/rt_notify()/ hook is called to inform the protocol instance about
1925: changes in the connected routing table <param/table/, that is a route <param/old/
1926: belonging to network <param/net/ being replaced by a new route <param/new/ with
1927: extended attributes <param/attrs/. Either <param/new/ or <param/old/ or both can be <const/NULL/
1928: if the corresponding route doesn't exist.
1929: <p>
1930: If the type of route announcement is RA_OPTIMAL, it is an
1931: announcement of optimal route change, <param/new/ stores the new optimal
1932: route and <param/old/ stores the old optimal route.
1933: <p>
1934: If the type of route announcement is RA_ANY, it is an announcement
1935: of any route change, <param/new/ stores the new route and <param/old/ stores the
1936: old route from the same protocol.
1937: <p>
1938: <param/p/->accept_ra_types specifies which kind of route announcements
1939: protocol wants to receive.
1940: </function>
1941: <function><p><type>void</type>
1942: <funcdef>neigh_notify</funcdef>
1943: (<type>neighbor *</type> <param>neigh</param>) -- notify instance about neighbor status change
1944:
1945: <funcsect>Arguments
1946: <p><descrip>
1947: <tagp><type>neighbor *</type> <param>neigh</param></tagp>
1948: a neighbor cache entry
1949: </descrip>
1950: <funcsect>Description
1951: <p>
1952: The <func/neigh_notify()/ hook is called by the neighbor cache whenever
1953: a neighbor changes its state, that is it gets disconnected or a
1954: sticky neighbor gets connected.
1955: </function>
1956: <function><p><type>ea_list *</type>
1957: <funcdef>make_tmp_attrs</funcdef>
1958: (<type>rte *</type> <param>e</param>, <type>struct linpool *</type> <param>pool</param>) -- convert embedded attributes to temporary ones
1959:
1960: <funcsect>Arguments
1961: <p><descrip>
1962: <tagp><type>rte *</type> <param>e</param></tagp>
1963: route entry
1964: <tagp><type>struct linpool *</type> <param>pool</param></tagp>
1965: linear pool to allocate attribute memory in
1966: </descrip>
1967: <funcsect>Description
1968: <p>
1969: This hook is called by the routing table functions if they need
1970: to convert the protocol attributes embedded directly in the <struct/rte/
1971: to temporary extended attributes in order to distribute them
1972: to other protocols or to filters. <func/make_tmp_attrs()/ creates
1973: an <struct/ea_list/ in the linear pool <param/pool/, fills it with values of the
1974: temporary attributes and returns a pointer to it.
1975: </function>
1976: <function><p><type>void</type>
1977: <funcdef>store_tmp_attrs</funcdef>
1978: (<type>rte *</type> <param>e</param>, <type>ea_list *</type> <param>attrs</param>) -- convert temporary attributes to embedded ones
1979:
1980: <funcsect>Arguments
1981: <p><descrip>
1982: <tagp><type>rte *</type> <param>e</param></tagp>
1983: route entry
1984: <tagp><type>ea_list *</type> <param>attrs</param></tagp>
1985: temporary attributes to be converted
1986: </descrip>
1987: <funcsect>Description
1988: <p>
1989: This hook is an exact opposite of <func/make_tmp_attrs()/ -- it takes
1990: a list of extended attributes and converts them to attributes
1991: embedded in the <struct/rte/ corresponding to this protocol.
1992: <p>
1993: You must be prepared for any of the attributes being missing
1994: from the list and use default values instead.
1995: </function>
1996: <function><p><type>int</type>
1997: <funcdef>import_control</funcdef>
1998: (<type>struct proto *</type> <param>p</param>, <type>rte **</type> <param>e</param>, <type>ea_list **</type> <param>attrs</param>, <type>struct linpool *</type> <param>pool</param>) -- pre-filtering decisions on route import
1999:
2000: <funcsect>Arguments
2001: <p><descrip>
2002: <tagp><type>struct proto *</type> <param>p</param></tagp>
2003: protocol instance the route is going to be imported to
2004: <tagp><type>rte **</type> <param>e</param></tagp>
2005: the route in question
2006: <tagp><type>ea_list **</type> <param>attrs</param></tagp>
2007: extended attributes of the route
2008: <tagp><type>struct linpool *</type> <param>pool</param></tagp>
2009: linear pool for allocation of all temporary data
2010: </descrip>
2011: <funcsect>Description
2012: <p>
2013: The <func/import_control()/ hook is called as the first step of a exporting
2014: a route from a routing table to the protocol instance. It can modify
2015: route attributes and force acceptance or rejection of the route regardless
2016: of user-specified filters. See <func/rte_announce()/ for a complete description
2017: of the route distribution process.
2018: <p>
2019: The standard use of this hook is to reject routes having originated
2020: from the same instance and to set default values of the protocol's metrics.
2021: <funcsect>Result
2022: <p>
2023: 1 if the route has to be accepted, -1 if rejected and 0 if it
2024: should be passed to the filters.
2025: </function>
2026: <function><p><type>int</type>
2027: <funcdef>rte_recalculate</funcdef>
2028: (<type>struct rtable *</type> <param>table</param>, <type>struct network *</type> <param>net</param>, <type>struct rte *</type> <param>new</param>, <type>struct rte *</type> <param>old</param>, <type>struct rte *</type> <param>old_best</param>) -- prepare routes for comparison
2029:
2030: <funcsect>Arguments
2031: <p><descrip>
2032: <tagp><type>struct rtable *</type> <param>table</param></tagp>
2033: a routing table
2034: <tagp><type>struct network *</type> <param>net</param></tagp>
2035: a network entry
2036: <tagp><type>struct rte *</type> <param>new</param></tagp>
2037: new route for the network
2038: <tagp><type>struct rte *</type> <param>old</param></tagp>
2039: old route for the network
2040: <tagp><type>struct rte *</type> <param>old_best</param></tagp>
2041: old best route for the network (may be NULL)
2042: </descrip>
2043: <funcsect>Description
2044: <p>
2045: This hook is called when a route change (from <param/old/ to <param/new/ for a
2046: <param/net/ entry) is propagated to a <param/table/. It may be used to prepare
2047: routes for comparison by <func/rte_better()/ in the best route
2048: selection. <param/new/ may or may not be in <param/net/->routes list,
2049: <param/old/ is not there.
2050: <funcsect>Result
2051: <p>
2052: 1 if the ordering implied by <func/rte_better()/ changes enough
2053: that full best route calculation have to be done, 0 otherwise.
2054: </function>
2055: <function><p><type>int</type>
2056: <funcdef>rte_better</funcdef>
2057: (<type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>) -- compare metrics of two routes
2058:
2059: <funcsect>Arguments
2060: <p><descrip>
2061: <tagp><type>rte *</type> <param>new</param></tagp>
2062: the new route
2063: <tagp><type>rte *</type> <param>old</param></tagp>
2064: the original route
2065: </descrip>
2066: <funcsect>Description
2067: <p>
2068: This hook gets called when the routing table contains two routes
2069: for the same network which have originated from different instances
2070: of a single protocol and it wants to select which one is preferred
2071: over the other one. Protocols usually decide according to route metrics.
2072: <funcsect>Result
2073: <p>
2074: 1 if <param/new/ is better (more preferred) than <param/old/, 0 otherwise.
2075: </function>
2076: <function><p><type>int</type>
2077: <funcdef>rte_same</funcdef>
2078: (<type>rte *</type> <param>e1</param>, <type>rte *</type> <param>e2</param>) -- compare two routes
2079:
2080: <funcsect>Arguments
2081: <p><descrip>
2082: <tagp><type>rte *</type> <param>e1</param></tagp>
2083: route
2084: <tagp><type>rte *</type> <param>e2</param></tagp>
2085: route
2086: </descrip>
2087: <funcsect>Description
2088: <p>
2089: The <func/rte_same()/ hook tests whether the routes <param/e1/ and <param/e2/ belonging
2090: to the same protocol instance have identical contents. Contents of
2091: <struct/rta/, all the extended attributes and <struct/rte/ preference are checked
2092: by the core code, no need to take care of them here.
2093: <funcsect>Result
2094: <p>
2095: 1 if <param/e1/ is identical to <param/e2/, 0 otherwise.
2096: </function>
2097: <function><p><type>void</type>
2098: <funcdef>rte_insert</funcdef>
2099: (<type>net *</type> <param>n</param>, <type>rte *</type> <param>e</param>) -- notify instance about route insertion
2100:
2101: <funcsect>Arguments
2102: <p><descrip>
2103: <tagp><type>net *</type> <param>n</param></tagp>
2104: network
2105: <tagp><type>rte *</type> <param>e</param></tagp>
2106: route
2107: </descrip>
2108: <funcsect>Description
2109: <p>
2110: This hook is called whenever a <struct/rte/ belonging to the instance
2111: is accepted for insertion to a routing table.
2112: <p>
2113: Please avoid using this function in new protocols.
2114: </function>
2115: <function><p><type>void</type>
2116: <funcdef>rte_remove</funcdef>
2117: (<type>net *</type> <param>n</param>, <type>rte *</type> <param>e</param>) -- notify instance about route removal
2118:
2119: <funcsect>Arguments
2120: <p><descrip>
2121: <tagp><type>net *</type> <param>n</param></tagp>
2122: network
2123: <tagp><type>rte *</type> <param>e</param></tagp>
2124: route
2125: </descrip>
2126: <funcsect>Description
2127: <p>
2128: This hook is called whenever a <struct/rte/ belonging to the instance
2129: is removed from a routing table.
2130: <p>
2131: Please avoid using this function in new protocols.
2132: </function>
2133: <sect>Interfaces
2134: <p>
2135: <p>
2136: The interface module keeps track of all network interfaces in the
2137: system and their addresses.
2138: <p>
2139: Each interface is represented by an <struct/iface/ structure which carries
2140: interface capability flags (<const/IF_MULTIACCESS/, <const/IF_BROADCAST/ etc.),
2141: MTU, interface name and index and finally a linked list of network
2142: prefixes assigned to the interface, each one represented by
2143: struct <struct/ifa/.
2144: <p>
2145: The interface module keeps a `soft-up' state for each <struct/iface/ which
2146: is a conjunction of link being up, the interface being of a `sane'
2147: type and at least one IP address assigned to it.
2148:
2149:
2150: <function><p><type>void</type>
2151: <funcdef>ifa_dump</funcdef>
2152: (<type>struct ifa *</type> <param>a</param>) -- dump interface address
2153:
2154: <funcsect>Arguments
2155: <p><descrip>
2156: <tagp><type>struct ifa *</type> <param>a</param></tagp>
2157: interface address descriptor
2158: </descrip>
2159: <funcsect>Description
2160: <p>
2161: This function dumps contents of an <struct/ifa/ to the debug output.
2162: </function>
2163: <function><p><type>void</type>
2164: <funcdef>if_dump</funcdef>
2165: (<type>struct iface *</type> <param>i</param>) -- dump interface
2166:
2167: <funcsect>Arguments
2168: <p><descrip>
2169: <tagp><type>struct iface *</type> <param>i</param></tagp>
2170: interface to dump
2171: </descrip>
2172: <funcsect>Description
2173: <p>
2174: This function dumps all information associated with a given
2175: network interface to the debug output.
2176: </function>
2177: <function><p><type>void</type>
2178: <funcdef>if_dump_all</funcdef>
2179: (<param>void</param>) -- dump all interfaces
2180:
2181: <funcsect>Description
2182: <p>
2183: <p>
2184: This function dumps information about all known network
2185: interfaces to the debug output.
2186: </function>
2187: <function><p><type>void</type>
2188: <funcdef>if_delete</funcdef>
2189: (<type>struct iface *</type> <param>old</param>) -- remove interface
2190:
2191: <funcsect>Arguments
2192: <p><descrip>
2193: <tagp><type>struct iface *</type> <param>old</param></tagp>
2194: interface
2195: </descrip>
2196: <funcsect>Description
2197: <p>
2198: This function is called by the low-level platform dependent code
2199: whenever it notices an interface disappears. It is just a shorthand
2200: for <func/if_update()/.
2201: </function>
2202: <function><p><type>struct iface *</type>
2203: <funcdef>if_update</funcdef>
2204: (<type>struct iface *</type> <param>new</param>) -- update interface status
2205:
2206: <funcsect>Arguments
2207: <p><descrip>
2208: <tagp><type>struct iface *</type> <param>new</param></tagp>
2209: new interface status
2210: </descrip>
2211: <funcsect>Description
2212: <p>
2213: <func/if_update()/ is called by the low-level platform dependent code
2214: whenever it notices an interface change.
2215: <p>
2216: There exist two types of interface updates -- synchronous and asynchronous
2217: ones. In the synchronous case, the low-level code calls <func/if_start_update()/,
2218: scans all interfaces reported by the OS, uses <func/if_update()/ and <func/ifa_update()/
2219: to pass them to the core and then it finishes the update sequence by
2220: calling <func/if_end_update()/. When working asynchronously, the sysdep code
2221: calls <func/if_update()/ and <func/ifa_update()/ whenever it notices a change.
2222: <p>
2223: <func/if_update()/ will automatically notify all other modules about the change.
2224: </function>
2225: <function><p><type>void</type>
2226: <funcdef>if_feed_baby</funcdef>
2227: (<type>struct proto *</type> <param>p</param>) -- advertise interfaces to a new protocol
2228:
2229: <funcsect>Arguments
2230: <p><descrip>
2231: <tagp><type>struct proto *</type> <param>p</param></tagp>
2232: protocol to feed
2233: </descrip>
2234: <funcsect>Description
2235: <p>
2236: When a new protocol starts, this function sends it a series
2237: of notifications about all existing interfaces.
2238: </function>
2239: <function><p><type>struct iface *</type>
2240: <funcdef>if_find_by_index</funcdef>
2241: (<type>unsigned</type> <param>idx</param>) -- find interface by ifindex
2242:
2243: <funcsect>Arguments
2244: <p><descrip>
2245: <tagp><type>unsigned</type> <param>idx</param></tagp>
2246: ifindex
2247: </descrip>
2248: <funcsect>Description
2249: <p>
2250: This function finds an <struct/iface/ structure corresponding to an interface
2251: of the given index <param/idx/. Returns a pointer to the structure or <const/NULL/
2252: if no such structure exists.
2253: </function>
2254: <function><p><type>struct iface *</type>
2255: <funcdef>if_find_by_name</funcdef>
2256: (<type>char *</type> <param>name</param>) -- find interface by name
2257:
2258: <funcsect>Arguments
2259: <p><descrip>
2260: <tagp><type>char *</type> <param>name</param></tagp>
2261: interface name
2262: </descrip>
2263: <funcsect>Description
2264: <p>
2265: This function finds an <struct/iface/ structure corresponding to an interface
2266: of the given name <param/name/. Returns a pointer to the structure or <const/NULL/
2267: if no such structure exists.
2268: </function>
2269: <function><p><type>struct ifa *</type>
2270: <funcdef>ifa_update</funcdef>
2271: (<type>struct ifa *</type> <param>a</param>) -- update interface address
2272:
2273: <funcsect>Arguments
2274: <p><descrip>
2275: <tagp><type>struct ifa *</type> <param>a</param></tagp>
2276: new interface address
2277: </descrip>
2278: <funcsect>Description
2279: <p>
2280: This function adds address information to a network
2281: interface. It's called by the platform dependent code during
2282: the interface update process described under <func/if_update()/.
2283: </function>
2284: <function><p><type>void</type>
2285: <funcdef>ifa_delete</funcdef>
2286: (<type>struct ifa *</type> <param>a</param>) -- remove interface address
2287:
2288: <funcsect>Arguments
2289: <p><descrip>
2290: <tagp><type>struct ifa *</type> <param>a</param></tagp>
2291: interface address
2292: </descrip>
2293: <funcsect>Description
2294: <p>
2295: This function removes address information from a network
2296: interface. It's called by the platform dependent code during
2297: the interface update process described under <func/if_update()/.
2298: </function>
2299: <function><p><type>void</type>
2300: <funcdef>if_init</funcdef>
2301: (<param>void</param>) -- initialize interface module
2302:
2303: <funcsect>Description
2304: <p>
2305: <p>
2306: This function is called during BIRD startup to initialize
2307: all data structures of the interface module.
2308: </function>
2309: <sect>Neighbor cache
2310: <p>
2311: <p>
2312: Most routing protocols need to associate their internal state data with
2313: neighboring routers, check whether an address given as the next hop
2314: attribute of a route is really an address of a directly connected host
2315: and which interface is it connected through. Also, they often need to
2316: be notified when a neighbor ceases to exist or when their long awaited
2317: neighbor becomes connected. The neighbor cache is there to solve all
2318: these problems.
2319: <p>
2320: The neighbor cache maintains a collection of neighbor entries. Each
2321: entry represents one IP address corresponding to either our directly
2322: connected neighbor or our own end of the link (when the scope of the
2323: address is set to <const/SCOPE_HOST/) together with per-neighbor data belonging to a
2324: single protocol.
2325: <p>
2326: Active entries represent known neighbors and are stored in a hash
2327: table (to allow fast retrieval based on the IP address of the node) and
2328: two linked lists: one global and one per-interface (allowing quick
2329: processing of interface change events). Inactive entries exist only
2330: when the protocol has explicitly requested it via the <const/NEF_STICKY/
2331: flag because it wishes to be notified when the node will again become
2332: a neighbor. Such entries are enqueued in a special list which is walked
2333: whenever an interface changes its state to up. Neighbor entry VRF
2334: association is implied by respective protocol.
2335: <p>
2336: When a neighbor event occurs (a neighbor gets disconnected or a sticky
2337: inactive neighbor becomes connected), the protocol hook <func/neigh_notify()/
2338: is called to advertise the change.
2339:
2340:
2341: <function><p><type>neighbor *</type>
2342: <funcdef>neigh_find</funcdef>
2343: (<type>struct proto *</type> <param>p</param>, <type>ip_addr *</type> <param>a</param>, <type>unsigned</type> <param>flags</param>) -- find or create a neighbor entry.
2344:
2345: <funcsect>Arguments
2346: <p><descrip>
2347: <tagp><type>struct proto *</type> <param>p</param></tagp>
2348: protocol which asks for the entry.
2349: <tagp><type>ip_addr *</type> <param>a</param></tagp>
2350: pointer to IP address of the node to be searched for.
2351: <tagp><type>unsigned</type> <param>flags</param></tagp>
2352: 0 or <const/NEF_STICKY/ if you want to create a sticky entry.
2353: </descrip>
2354: <funcsect>Description
2355: <p>
2356: Search the neighbor cache for a node with given IP address. If
2357: it's found, a pointer to the neighbor entry is returned. If no
2358: such entry exists and the node is directly connected on
2359: one of our active interfaces, a new entry is created and returned
2360: to the caller with protocol-dependent fields initialized to zero.
2361: If the node is not connected directly or *<param/a/ is not a valid unicast
2362: IP address, <func/neigh_find()/ returns <const/NULL/.
2363: </function>
2364: <function><p><type>void</type>
2365: <funcdef>neigh_dump</funcdef>
2366: (<type>neighbor *</type> <param>n</param>) -- dump specified neighbor entry.
2367:
2368: <funcsect>Arguments
2369: <p><descrip>
2370: <tagp><type>neighbor *</type> <param>n</param></tagp>
2371: the entry to dump
2372: </descrip>
2373: <funcsect>Description
2374: <p>
2375: This functions dumps the contents of a given neighbor entry
2376: to debug output.
2377: </function>
2378: <function><p><type>void</type>
2379: <funcdef>neigh_dump_all</funcdef>
2380: (<param>void</param>) -- dump all neighbor entries.
2381:
2382: <funcsect>Description
2383: <p>
2384: <p>
2385: This function dumps the contents of the neighbor cache to
2386: debug output.
2387: </function>
2388: <function><p><type>void</type>
2389: <funcdef>neigh_if_up</funcdef>
2390: (<type>struct iface *</type> <param>i</param>)
2391: <funcsect>Arguments
2392: <p><descrip>
2393: <tagp><type>struct iface *</type> <param>i</param></tagp>
2394: interface in question
2395: </descrip>
2396: <funcsect>Description
2397: <p>
2398: Tell the neighbor cache that a new interface became up.
2399: <p>
2400: The neighbor cache wakes up all inactive sticky neighbors with
2401: addresses belonging to prefixes of the interface <param/i/.
2402: </function>
2403: <function><p><type>void</type>
2404: <funcdef>neigh_if_down</funcdef>
2405: (<type>struct iface *</type> <param>i</param>) -- notify neighbor cache about interface down event
2406:
2407: <funcsect>Arguments
2408: <p><descrip>
2409: <tagp><type>struct iface *</type> <param>i</param></tagp>
2410: the interface in question
2411: </descrip>
2412: <funcsect>Description
2413: <p>
2414: Notify the neighbor cache that an interface has ceased to exist.
2415: <p>
2416: It causes all entries belonging to neighbors connected to this interface
2417: to be flushed.
2418: </function>
2419: <function><p><type>void</type>
2420: <funcdef>neigh_if_link</funcdef>
2421: (<type>struct iface *</type> <param>i</param>) -- notify neighbor cache about interface link change
2422:
2423: <funcsect>Arguments
2424: <p><descrip>
2425: <tagp><type>struct iface *</type> <param>i</param></tagp>
2426: the interface in question
2427: </descrip>
2428: <funcsect>Description
2429: <p>
2430: Notify the neighbor cache that an interface changed link state.
2431: All owners of neighbor entries connected to this interface are
2432: notified.
2433: </function>
2434: <function><p><type>void</type>
2435: <funcdef>neigh_ifa_update</funcdef>
2436: (<type>struct ifa *</type> <param>a</param>)
2437: <funcsect>Arguments
2438: <p><descrip>
2439: <tagp><type>struct ifa *</type> <param>a</param></tagp>
2440: interface address in question
2441: </descrip>
2442: <funcsect>Description
2443: <p>
2444: Tell the neighbor cache that an address was added or removed.
2445: <p>
2446: The neighbor cache wakes up all inactive sticky neighbors with
2447: addresses belonging to prefixes of the interface belonging to <param/ifa/
2448: and causes all unreachable neighbors to be flushed.
2449: </function>
2450: <function><p><type>void</type>
2451: <funcdef>neigh_prune</funcdef>
2452: (<param>void</param>) -- prune neighbor cache
2453:
2454: <funcsect>Description
2455: <p>
2456: <p>
2457: <func/neigh_prune()/ examines all neighbor entries cached and removes those
2458: corresponding to inactive protocols. It's called whenever a protocol
2459: is shut down to get rid of all its heritage.
2460: </function>
2461: <function><p><type>void</type>
2462: <funcdef>neigh_init</funcdef>
2463: (<type>pool *</type> <param>if_pool</param>) -- initialize the neighbor cache.
2464:
2465: <funcsect>Arguments
2466: <p><descrip>
2467: <tagp><type>pool *</type> <param>if_pool</param></tagp>
2468: resource pool to be used for neighbor entries.
2469: </descrip>
2470: <funcsect>Description
2471: <p>
2472: This function is called during BIRD startup to initialize
2473: the neighbor cache module.
2474: </function>
2475: <sect>Command line interface
2476: <p>
2477: <p>
2478: This module takes care of the BIRD's command-line interface (CLI).
2479: The CLI exists to provide a way to control BIRD remotely and to inspect
2480: its status. It uses a very simple textual protocol over a stream
2481: connection provided by the platform dependent code (on UNIX systems,
2482: it's a UNIX domain socket).
2483: <p>
2484: Each session of the CLI consists of a sequence of request and replies,
2485: slightly resembling the FTP and SMTP protocols.
2486: Requests are commands encoded as a single line of text, replies are
2487: sequences of lines starting with a four-digit code followed by either
2488: a space (if it's the last line of the reply) or a minus sign (when the
2489: reply is going to continue with the next line), the rest of the line
2490: contains a textual message semantics of which depends on the numeric
2491: code. If a reply line has the same code as the previous one and it's
2492: a continuation line, the whole prefix can be replaced by a single
2493: white space character.
2494: <p>
2495: Reply codes starting with 0 stand for `action successfully completed' messages,
2496: 1 means `table entry', 8 `runtime error' and 9 `syntax error'.
2497: <p>
2498: Each CLI session is internally represented by a <struct/cli/ structure and a
2499: resource pool containing all resources associated with the connection,
2500: so that it can be easily freed whenever the connection gets closed, not depending
2501: on the current state of command processing.
2502: <p>
2503: The CLI commands are declared as a part of the configuration grammar
2504: by using the <tt>CF_CLI</tt> macro. When a command is received, it is processed
2505: by the same lexical analyzer and parser as used for the configuration, but
2506: it's switched to a special mode by prepending a fake token to the text,
2507: so that it uses only the CLI command rules. Then the parser invokes
2508: an execution routine corresponding to the command, which either constructs
2509: the whole reply and returns it back or (in case it expects the reply will be long)
2510: it prints a partial reply and asks the CLI module (using the <param/cont/ hook)
2511: to call it again when the output is transferred to the user.
2512: <p>
2513: The <param/this_cli/ variable points to a <struct/cli/ structure of the session being
2514: currently parsed, but it's of course available only in command handlers
2515: not entered using the <param/cont/ hook.
2516: <p>
2517: TX buffer management works as follows: At cli.tx_buf there is a
2518: list of TX buffers (struct cli_out), cli.tx_write is the buffer
2519: currently used by the producer (<func/cli_printf()/, <func/cli_alloc_out()/) and
2520: cli.tx_pos is the buffer currently used by the consumer
2521: (<func/cli_write()/, in system dependent code). The producer uses
2522: cli_out.wpos ptr as the current write position and the consumer
2523: uses cli_out.outpos ptr as the current read position. When the
2524: producer produces something, it calls <func/cli_write_trigger()/. If there
2525: is not enough space in the current buffer, the producer allocates
2526: the new one. When the consumer processes everything in the buffer
2527: queue, it calls <func/cli_written()/, tha frees all buffers (except the
2528: first one) and schedules cli.event .
2529:
2530:
2531: <function><p><type>void</type>
2532: <funcdef>cli_printf</funcdef>
2533: (<type>cli *</type> <param>c</param>, <type>int</type> <param>code</param>, <type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- send reply to a CLI connection
2534:
2535: <funcsect>Arguments
2536: <p><descrip>
2537: <tagp><type>cli *</type> <param>c</param></tagp>
2538: CLI connection
2539: <tagp><type>int</type> <param>code</param></tagp>
2540: numeric code of the reply, negative for continuation lines
2541: <tagp><type>char *</type> <param>msg</param></tagp>
2542: a <func/printf()/-like formatting string.
2543: <tagp><type>...</type> <param>...</param></tagp>
2544: variable arguments
2545: </descrip>
2546: <funcsect>Description
2547: <p>
2548: This function send a single line of reply to a given CLI connection.
2549: In works in all aspects like <func/bsprintf()/ except that it automatically
2550: prepends the reply line prefix.
2551: <p>
2552: Please note that if the connection can be already busy sending some
2553: data in which case <func/cli_printf()/ stores the output to a temporary buffer,
2554: so please avoid sending a large batch of replies without waiting
2555: for the buffers to be flushed.
2556: <p>
2557: If you want to write to the current CLI output, you can use the <func/cli_msg()/
2558: macro instead.
2559: </function>
2560: <function><p><type>void</type>
2561: <funcdef>cli_init</funcdef>
2562: (<param>void</param>) -- initialize the CLI module
2563:
2564: <funcsect>Description
2565: <p>
2566: <p>
2567: This function is called during BIRD startup to initialize
2568: the internal data structures of the CLI module.
2569: </function>
2570: <sect>Object locks
2571: <p>
2572: <p>
2573: The lock module provides a simple mechanism for avoiding conflicts between
2574: various protocols which would like to use a single physical resource (for
2575: example a network port). It would be easy to say that such collisions can
2576: occur only when the user specifies an invalid configuration and therefore
2577: he deserves to get what he has asked for, but unfortunately they can also
2578: arise legitimately when the daemon is reconfigured and there exists (although
2579: for a short time period only) an old protocol instance being shut down and a new one
2580: willing to start up on the same interface.
2581: <p>
2582: The solution is very simple: when any protocol wishes to use a network port
2583: or some other non-shareable resource, it asks the core to lock it and it doesn't
2584: use the resource until it's notified that it has acquired the lock.
2585: <p>
2586: Object locks are represented by <struct/object_lock/ structures which are in turn a
2587: kind of resource. Lockable resources are uniquely determined by resource type
2588: (<const/OBJLOCK_UDP/ for a UDP port etc.), IP address (usually a broadcast or
2589: multicast address the port is bound to), port number, interface and optional
2590: instance ID.
2591:
2592:
2593: <function><p><type>struct object_lock *</type>
2594: <funcdef>olock_new</funcdef>
2595: (<type>pool *</type> <param>p</param>) -- create an object lock
2596:
2597: <funcsect>Arguments
2598: <p><descrip>
2599: <tagp><type>pool *</type> <param>p</param></tagp>
2600: resource pool to create the lock in.
2601: </descrip>
2602: <funcsect>Description
2603: <p>
2604: The <func/olock_new()/ function creates a new resource of type <struct/object_lock/
2605: and returns a pointer to it. After filling in the structure, the caller
2606: should call <func/olock_acquire()/ to do the real locking.
2607: </function>
2608: <function><p><type>void</type>
2609: <funcdef>olock_acquire</funcdef>
2610: (<type>struct object_lock *</type> <param>l</param>) -- acquire a lock
2611:
2612: <funcsect>Arguments
2613: <p><descrip>
2614: <tagp><type>struct object_lock *</type> <param>l</param></tagp>
2615: the lock to acquire
2616: </descrip>
2617: <funcsect>Description
2618: <p>
2619: This function attempts to acquire exclusive access to the non-shareable
2620: resource described by the lock <param/l/. It returns immediately, but as soon
2621: as the resource becomes available, it calls the <func/hook()/ function set up
2622: by the caller.
2623: <p>
2624: When you want to release the resource, just <func/rfree()/ the lock.
2625: </function>
2626: <function><p><type>void</type>
2627: <funcdef>olock_init</funcdef>
2628: (<param>void</param>) -- initialize the object lock mechanism
2629:
2630: <funcsect>Description
2631: <p>
2632: <p>
2633: This function is called during BIRD startup. It initializes
2634: all the internal data structures of the lock module.
2635: </function>
2636: <chapt>Configuration
2637: <sect>Configuration manager
2638: <p>
2639: <p>
2640: Configuration of BIRD is complex, yet straightforward. There are three
2641: modules taking care of the configuration: config manager (which takes care
2642: of storage of the config information and controls switching between configs),
2643: lexical analyzer and parser.
2644: <p>
2645: The configuration manager stores each config as a <struct/config/ structure
2646: accompanied by a linear pool from which all information associated
2647: with the config and pointed to by the <struct/config/ structure is allocated.
2648: <p>
2649: There can exist up to four different configurations at one time: an active
2650: one (pointed to by <param/config/), configuration we are just switching from
2651: (<param/old_config/), one queued for the next reconfiguration (<param/future_config/; if
2652: there is one and the user wants to reconfigure once again, we just free the
2653: previous queued config and replace it with the new one) and finally a config
2654: being parsed (<param/new_config/). The stored <param/old_config/ is also used for undo
2655: reconfiguration, which works in a similar way. Reconfiguration could also
2656: have timeout (using <param/config_timer/) and undo is automatically called if the
2657: new configuration is not confirmed later. The new config (<param/new_config/) and
2658: associated linear pool (<param/cfg_mem/) is non-NULL only during parsing.
2659: <p>
2660: Loading of new configuration is very simple: just call <func/config_alloc()/ to get
2661: a new <struct/config/ structure, then use <func/config_parse()/ to parse a configuration
2662: file and fill all fields of the structure and finally ask the config manager
2663: to switch to the new config by calling <func/config_commit()/.
2664: <p>
2665: CLI commands are parsed in a very similar way -- there is also a stripped-down
2666: <struct/config/ structure associated with them and they are lex-ed and parsed by the
2667: same functions, only a special fake token is prepended before the command
2668: text to make the parser recognize only the rules corresponding to CLI commands.
2669:
2670:
2671: <function><p><type>struct config *</type>
2672: <funcdef>config_alloc</funcdef>
2673: (<type>const byte *</type> <param>name</param>) -- allocate a new configuration
2674:
2675: <funcsect>Arguments
2676: <p><descrip>
2677: <tagp><type>const byte *</type> <param>name</param></tagp>
2678: name of the config
2679: </descrip>
2680: <funcsect>Description
2681: <p>
2682: This function creates new <struct/config/ structure, attaches a resource
2683: pool and a linear memory pool to it and makes it available for
2684: further use. Returns a pointer to the structure.
2685: </function>
2686: <function><p><type>int</type>
2687: <funcdef>config_parse</funcdef>
2688: (<type>struct config *</type> <param>c</param>) -- parse a configuration
2689:
2690: <funcsect>Arguments
2691: <p><descrip>
2692: <tagp><type>struct config *</type> <param>c</param></tagp>
2693: configuration
2694: </descrip>
2695: <funcsect>Description
2696: <p>
2697: <func/config_parse()/ reads input by calling a hook function pointed to
2698: by <param/cf_read_hook/ and parses it according to the configuration
2699: grammar. It also calls all the preconfig and postconfig hooks
2700: before, resp. after parsing.
2701: <funcsect>Result
2702: <p>
2703: 1 if the config has been parsed successfully, 0 if any
2704: error has occurred (such as anybody calling <func/cf_error()/) and
2705: the <param/err_msg/ field has been set to the error message.
2706: </function>
2707: <function><p><type>int</type>
2708: <funcdef>cli_parse</funcdef>
2709: (<type>struct config *</type> <param>c</param>) -- parse a CLI command
2710:
2711: <funcsect>Arguments
2712: <p><descrip>
2713: <tagp><type>struct config *</type> <param>c</param></tagp>
2714: temporary config structure
2715: </descrip>
2716: <funcsect>Description
2717: <p>
2718: <func/cli_parse()/ is similar to <func/config_parse()/, but instead of a configuration,
2719: it parses a CLI command. See the CLI module for more information.
2720: </function>
2721: <function><p><type>void</type>
2722: <funcdef>config_free</funcdef>
2723: (<type>struct config *</type> <param>c</param>) -- free a configuration
2724:
2725: <funcsect>Arguments
2726: <p><descrip>
2727: <tagp><type>struct config *</type> <param>c</param></tagp>
2728: configuration to be freed
2729: </descrip>
2730: <funcsect>Description
2731: <p>
2732: This function takes a <struct/config/ structure and frees all resources
2733: associated with it.
2734: </function>
2735: <function><p><type>int</type>
2736: <funcdef>config_commit</funcdef>
2737: (<type>struct config *</type> <param>c</param>, <type>int</type> <param>type</param>, <type>int</type> <param>timeout</param>) -- commit a configuration
2738:
2739: <funcsect>Arguments
2740: <p><descrip>
2741: <tagp><type>struct config *</type> <param>c</param></tagp>
2742: new configuration
2743: <tagp><type>int</type> <param>type</param></tagp>
2744: type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)
2745: <tagp><type>int</type> <param>timeout</param></tagp>
2746: timeout for undo (or 0 for no timeout)
2747: </descrip>
2748: <funcsect>Description
2749: <p>
2750: When a configuration is parsed and prepared for use, the
2751: <func/config_commit()/ function starts the process of reconfiguration.
2752: It checks whether there is already a reconfiguration in progress
2753: in which case it just queues the new config for later processing.
2754: Else it notifies all modules about the new configuration by calling
2755: their <func/commit()/ functions which can either accept it immediately
2756: or call <func/config_add_obstacle()/ to report that they need some time
2757: to complete the reconfiguration. After all such obstacles are removed
2758: using <func/config_del_obstacle()/, the old configuration is freed and
2759: everything runs according to the new one.
2760: <p>
2761: When <param/timeout/ is nonzero, the undo timer is activated with given
2762: timeout. The timer is deactivated when <func/config_commit()/,
2763: <func/config_confirm()/ or <func/config_undo()/ is called.
2764: <funcsect>Result
2765: <p>
2766: <const/CONF_DONE/ if the configuration has been accepted immediately,
2767: <const/CONF_PROGRESS/ if it will take some time to switch to it, <const/CONF_QUEUED/
2768: if it's been queued due to another reconfiguration being in progress now
2769: or <const/CONF_SHUTDOWN/ if BIRD is in shutdown mode and no new configurations
2770: are accepted.
2771: </function>
2772: <function><p><type>int</type>
2773: <funcdef>config_confirm</funcdef>
2774: (<param>void</param>) -- confirm a commited configuration
2775:
2776: <funcsect>Description
2777: <p>
2778: <p>
2779: When the undo timer is activated by <func/config_commit()/ with nonzero timeout,
2780: this function can be used to deactivate it and therefore confirm
2781: the current configuration.
2782: <funcsect>Result
2783: <p>
2784: <const/CONF_CONFIRM/ when the current configuration is confirmed,
2785: <const/CONF_NONE/ when there is nothing to confirm (i.e. undo timer is not active).
2786: </function>
2787: <function><p><type>int</type>
2788: <funcdef>config_undo</funcdef>
2789: (<param>void</param>) -- undo a configuration
2790:
2791: <funcsect>Description
2792: <p>
2793: <p>
2794: Function <func/config_undo()/ can be used to change the current
2795: configuration back to stored <const/old_config/. If no reconfiguration is
2796: running, this stored configuration is commited in the same way as a
2797: new configuration in <func/config_commit()/. If there is already a
2798: reconfiguration in progress and no next reconfiguration is
2799: scheduled, then the undo is scheduled for later processing as
2800: usual, but if another reconfiguration is already scheduled, then
2801: such reconfiguration is removed instead (i.e. undo is applied on
2802: the last commit that scheduled it).
2803: <funcsect>Result
2804: <p>
2805: <const/CONF_DONE/ if the configuration has been accepted immediately,
2806: <const/CONF_PROGRESS/ if it will take some time to switch to it, <const/CONF_QUEUED/
2807: if it's been queued due to another reconfiguration being in progress now,
2808: <const/CONF_UNQUEUED/ if a scheduled reconfiguration is removed, <const/CONF_NOTHING/
2809: if there is no relevant configuration to undo (the previous config request
2810: was <func/config_undo()/ too) or <const/CONF_SHUTDOWN/ if BIRD is in shutdown mode and
2811: no new configuration changes are accepted.
2812: </function>
2813: <function><p><type>void</type>
2814: <funcdef>order_shutdown</funcdef>
2815: (<param>void</param>) -- order BIRD shutdown
2816:
2817: <funcsect>Description
2818: <p>
2819: <p>
2820: This function initiates shutdown of BIRD. It's accomplished by asking
2821: for switching to an empty configuration.
2822: </function>
2823: <function><p><type>void</type>
2824: <funcdef>cf_error</funcdef>
2825: (<type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report a configuration error
2826:
2827: <funcsect>Arguments
2828: <p><descrip>
2829: <tagp><type>char *</type> <param>msg</param></tagp>
2830: printf-like format string
2831: <tagp><type>...</type> <param>...</param></tagp>
2832: variable arguments
2833: </descrip>
2834: <funcsect>Description
2835: <p>
2836: <func/cf_error()/ can be called during execution of <func/config_parse()/, that is
2837: from the parser, a preconfig hook or a postconfig hook, to report an
2838: error in the configuration.
2839: </function>
2840: <function><p><type>char *</type>
2841: <funcdef>cfg_strdup</funcdef>
2842: (<type>const char *</type> <param>c</param>) -- copy a string to config memory
2843:
2844: <funcsect>Arguments
2845: <p><descrip>
2846: <tagp><type>const char *</type> <param>c</param></tagp>
2847: string to copy
2848: </descrip>
2849: <funcsect>Description
2850: <p>
2851: <func/cfg_strdup()/ creates a new copy of the string in the memory
2852: pool associated with the configuration being currently parsed.
2853: It's often used when a string literal occurs in the configuration
2854: and we want to preserve it for further use.
2855: </function>
2856: <sect>Lexical analyzer
2857: <p>
2858: <p>
2859: The lexical analyzer used for configuration files and CLI commands
2860: is generated using the <tt>flex</tt> tool accompanied by a couple of
2861: functions maintaining the hash tables containing information about
2862: symbols and keywords.
2863: <p>
2864: Each symbol is represented by a <struct/symbol/ structure containing name
2865: of the symbol, its lexical scope, symbol class (<const/SYM_PROTO/ for a
2866: name of a protocol, <const/SYM_CONSTANT/ for a constant etc.) and class
2867: dependent data. When an unknown symbol is encountered, it's
2868: automatically added to the symbol table with class <const/SYM_VOID/.
2869: <p>
2870: The keyword tables are generated from the grammar templates
2871: using the <tt>gen_keywords.m4</tt> script.
2872:
2873:
2874: <function><p><type>void</type>
2875: <funcdef>cf_lex_unwind</funcdef>
2876: (<param>void</param>) -- unwind lexer state during error
2877:
2878: <funcsect>Lexical analyzer
2879: <p>
2880: <p>
2881: <func/cf_lex_unwind()/ frees the internal state on IFS stack when the lexical
2882: analyzer is terminated by <func/cf_error()/.
2883: </function>
2884: <function><p><type>struct symbol *</type>
2885: <funcdef>cf_find_symbol</funcdef>
2886: (<type>struct config *</type> <param>cfg</param>, <type>byte *</type> <param>c</param>) -- find a symbol by name
2887:
2888: <funcsect>Arguments
2889: <p><descrip>
2890: <tagp><type>struct config *</type> <param>cfg</param></tagp>
2891: specificed config
2892: <tagp><type>byte *</type> <param>c</param></tagp>
2893: symbol name
2894: </descrip>
2895: <funcsect>Description
2896: <p>
2897: This functions searches the symbol table in the config <param/cfg/ for a symbol of
2898: given name. First it examines the current scope, then the second recent one
2899: and so on until it either finds the symbol and returns a pointer to its
2900: <struct/symbol/ structure or reaches the end of the scope chain and returns <const/NULL/ to
2901: signify no match.
2902: </function>
2903: <function><p><type>struct symbol *</type>
2904: <funcdef>cf_get_symbol</funcdef>
2905: (<type>byte *</type> <param>c</param>) -- get a symbol by name
2906:
2907: <funcsect>Arguments
2908: <p><descrip>
2909: <tagp><type>byte *</type> <param>c</param></tagp>
2910: symbol name
2911: </descrip>
2912: <funcsect>Description
2913: <p>
2914: This functions searches the symbol table of the currently parsed config
2915: (<param/new_config/) for a symbol of given name. It returns either the already
2916: existing symbol or a newly allocated undefined (<const/SYM_VOID/) symbol if no
2917: existing symbol is found.
2918: </function>
2919: <function><p><type>struct symbol *</type>
2920: <funcdef>cf_define_symbol</funcdef>
2921: (<type>struct symbol *</type> <param>sym</param>, <type>int</type> <param>type</param>, <type>void *</type> <param>def</param>) -- define meaning of a symbol
2922:
2923: <funcsect>Arguments
2924: <p><descrip>
2925: <tagp><type>struct symbol *</type> <param>sym</param></tagp>
2926: symbol to be defined
2927: <tagp><type>int</type> <param>type</param></tagp>
2928: symbol class to assign
2929: <tagp><type>void *</type> <param>def</param></tagp>
2930: class dependent data
2931: </descrip>
2932: <funcsect>Description
2933: <p>
2934: Defines new meaning of a symbol. If the symbol is an undefined
2935: one (<const/SYM_VOID/), it's just re-defined to the new type. If it's defined
2936: in different scope, a new symbol in current scope is created and the
2937: meaning is assigned to it. If it's already defined in the current scope,
2938: an error is reported via <func/cf_error()/.
2939: <funcsect>Result
2940: <p>
2941: Pointer to the newly defined symbol. If we are in the top-level
2942: scope, it's the same <param/sym/ as passed to the function.
2943: </function>
2944: <function><p><type>void</type>
2945: <funcdef>cf_lex_init</funcdef>
2946: (<type>int</type> <param>is_cli</param>, <type>struct config *</type> <param>c</param>) -- initialize the lexer
2947:
2948: <funcsect>Arguments
2949: <p><descrip>
2950: <tagp><type>int</type> <param>is_cli</param></tagp>
2951: true if we're going to parse CLI command, false for configuration
2952: <tagp><type>struct config *</type> <param>c</param></tagp>
2953: configuration structure
2954: </descrip>
2955: <funcsect>Description
2956: <p>
2957: <func/cf_lex_init()/ initializes the lexical analyzer and prepares it for
2958: parsing of a new input.
2959: </function>
2960: <function><p><type>void</type>
2961: <funcdef>cf_push_scope</funcdef>
2962: (<type>struct symbol *</type> <param>sym</param>) -- enter new scope
2963:
2964: <funcsect>Arguments
2965: <p><descrip>
2966: <tagp><type>struct symbol *</type> <param>sym</param></tagp>
2967: symbol representing scope name
2968: </descrip>
2969: <funcsect>Description
2970: <p>
2971: If we want to enter a new scope to process declarations inside
2972: a nested block, we can just call <func/cf_push_scope()/ to push a new
2973: scope onto the scope stack which will cause all new symbols to be
2974: defined in this scope and all existing symbols to be sought for
2975: in all scopes stored on the stack.
2976: </function>
2977: <function><p><type>void</type>
2978: <funcdef>cf_pop_scope</funcdef>
2979: (<param>void</param>) -- leave a scope
2980:
2981: <funcsect>Description
2982: <p>
2983: <p>
2984: <func/cf_pop_scope()/ pops the topmost scope from the scope stack,
2985: leaving all its symbols in the symbol table, but making them
2986: invisible to the rest of the config.
2987: </function>
2988: <function><p><type>char *</type>
2989: <funcdef>cf_symbol_class_name</funcdef>
2990: (<type>struct symbol *</type> <param>sym</param>) -- get name of a symbol class
2991:
2992: <funcsect>Arguments
2993: <p><descrip>
2994: <tagp><type>struct symbol *</type> <param>sym</param></tagp>
2995: symbol
2996: </descrip>
2997: <funcsect>Description
2998: <p>
2999: This function returns a string representing the class
3000: of the given symbol.
3001: </function>
3002: <sect>Parser
3003: <p>
3004: <p>
3005: Both the configuration and CLI commands are analyzed using a syntax
3006: driven parser generated by the <tt>bison</tt> tool from a grammar which
3007: is constructed from information gathered from grammar snippets by
3008: the <tt>gen_parser.m4</tt> script.
3009: <p>
3010: Grammar snippets are files (usually with extension <tt>.Y</tt>) contributed
3011: by various BIRD modules in order to provide information about syntax of their
3012: configuration and their CLI commands. Each snipped consists of several
3013: sections, each of them starting with a special keyword: <tt>CF_HDR</tt> for
3014: a list of <tt>#include</tt> directives needed by the C code, <tt>CF_DEFINES</tt>
3015: for a list of C declarations, <tt>CF_DECLS</tt> for <tt>bison</tt> declarations
3016: including keyword definitions specified as <tt>CF_KEYWORDS</tt>, <tt>CF_GRAMMAR</tt>
3017: for the grammar rules, <tt>CF_CODE</tt> for auxiliary C code and finally
3018: <tt>CF_END</tt> at the end of the snippet.
3019: <p>
3020: To create references between the snippets, it's possible to define
3021: multi-part rules by utilizing the <tt>CF_ADDTO</tt> macro which adds a new
3022: alternative to a multi-part rule.
3023: <p>
3024: CLI commands are defined using a <tt>CF_CLI</tt> macro. Its parameters are:
3025: the list of keywords determining the command, the list of parameters,
3026: help text for the parameters and help text for the command.
3027: <p>
3028: Values of <tt>enum</tt> filter types can be defined using <tt>CF_ENUM</tt> with
3029: the following parameters: name of filter type, prefix common for all
3030: literals of this type and names of all the possible values.
3031:
3032:
3033: <chapt>Filters
3034: <sect>Filters
3035: <p>
3036: <p>
3037: You can find sources of the filter language in <tt>filter/</tt>
3038: directory. File <tt>filter/config.Y</tt> contains filter grammar and basically translates
3039: the source from user into a tree of <struct/f_inst/ structures. These trees are
3040: later interpreted using code in <tt>filter/filter.c</tt>.
3041: <p>
3042: A filter is represented by a tree of <struct/f_inst/ structures, one structure per
3043: "instruction". Each <struct/f_inst/ contains <param/code/, <param/aux/ value which is
3044: usually the data type this instruction operates on and two generic
3045: arguments (<param/a1/, <param/a2/). Some instructions contain pointer(s) to other
3046: instructions in their (<param/a1/, <param/a2/) fields.
3047: <p>
3048: Filters use a <struct/f_val/ structure for their data. Each <struct/f_val/
3049: contains type and value (types are constants prefixed with <const/T_/). Few
3050: of the types are special; <const/T_RETURN/ can be or-ed with a type to indicate
3051: that return from a function or from the whole filter should be
3052: forced. Important thing about <struct/f_val/'s is that they may be copied
3053: with a simple <tt>=</tt>. That's fine for all currently defined types: strings
3054: are read-only (and therefore okay), paths are copied for each
3055: operation (okay too).
3056:
3057:
3058: <function><p><type>int</type>
3059: <funcdef>val_compare</funcdef>
3060: (<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) -- compare two values
3061:
3062: <funcsect>Arguments
3063: <p><descrip>
3064: <tagp><type>struct f_val</type> <param>v1</param></tagp>
3065: first value
3066: <tagp><type>struct f_val</type> <param>v2</param></tagp>
3067: second value
3068: </descrip>
3069: <funcsect>Description
3070: <p>
3071: Compares two values and returns -1, 0, 1 on <, =, > or CMP_ERROR on
3072: error. Tree module relies on this giving consistent results so
3073: that it can be used for building balanced trees.
3074: </function>
3075: <function><p><type>int</type>
3076: <funcdef>val_same</funcdef>
3077: (<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) -- compare two values
3078:
3079: <funcsect>Arguments
3080: <p><descrip>
3081: <tagp><type>struct f_val</type> <param>v1</param></tagp>
3082: first value
3083: <tagp><type>struct f_val</type> <param>v2</param></tagp>
3084: second value
3085: </descrip>
3086: <funcsect>Description
3087: <p>
3088: Compares two values and returns 1 if they are same and 0 if not.
3089: Comparison of values of different types is valid and returns 0.
3090: </function>
3091: <function><p><type>int</type>
3092: <funcdef>val_in_range</funcdef>
3093: (<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) -- implement <tt>~</tt> operator
3094:
3095: <funcsect>Arguments
3096: <p><descrip>
3097: <tagp><type>struct f_val</type> <param>v1</param></tagp>
3098: element
3099: <tagp><type>struct f_val</type> <param>v2</param></tagp>
3100: set
3101: </descrip>
3102: <funcsect>Description
3103: <p>
3104: Checks if <param/v1/ is element (<tt>~</tt> operator) of <param/v2/.
3105: </function>
3106: <function><p><type>struct f_val</type>
3107: <funcdef>interpret</funcdef>
3108: (<type>struct f_inst *</type> <param>what</param>)
3109: <funcsect>Arguments
3110: <p><descrip>
3111: <tagp><type>struct f_inst *</type> <param>what</param></tagp>
3112: filter to interpret
3113: </descrip>
3114: <funcsect>Description
3115: <p>
3116: Interpret given tree of filter instructions. This is core function
3117: of filter system and does all the hard work.
3118: <funcsect>Each instruction has 4 fields
3119: <p>
3120: code (which is instruction code),
3121: aux (which is extension to instruction code, typically type),
3122: arg1 and arg2 - arguments. Depending on instruction, arguments
3123: are either integers, or pointers to instruction trees. Common
3124: instructions like +, that have two expressions as arguments use
3125: TWOARGS macro to get both of them evaluated.
3126: <p>
3127: <struct/f_val/ structures are copied around, so there are no problems with
3128: memory managment.
3129: </function>
3130: <function><p><type>int</type>
3131: <funcdef>f_run</funcdef>
3132: (<type>struct filter *</type> <param>filter</param>, <type>struct rte **</type> <param>rte</param>, <type>struct ea_list **</type> <param>tmp_attrs</param>, <type>struct linpool *</type> <param>tmp_pool</param>, <type>int</type> <param>flags</param>) -- run a filter for a route
3133:
3134: <funcsect>Arguments
3135: <p><descrip>
3136: <tagp><type>struct filter *</type> <param>filter</param></tagp>
3137: filter to run
3138: <tagp><type>struct rte **</type> <param>rte</param></tagp>
3139: route being filtered, may be modified
3140: <tagp><type>struct ea_list **</type> <param>tmp_attrs</param></tagp>
3141: temporary attributes, prepared by caller or generated by <func/f_run()/
3142: <tagp><type>struct linpool *</type> <param>tmp_pool</param></tagp>
3143: all filter allocations go from this pool
3144: <tagp><type>int</type> <param>flags</param></tagp>
3145: flags
3146: </descrip>
3147: <funcsect>Description
3148: <p>
3149: If filter needs to modify the route, there are several
3150: posibilities. <param/rte/ might be read-only (with REF_COW flag), in that
3151: case rw copy is obtained by <func/rte_cow()/ and <param/rte/ is replaced. If
3152: <param/rte/ is originally rw, it may be directly modified (and it is never
3153: copied).
3154: <p>
3155: The returned rte may reuse the (possibly cached, cloned) rta, or
3156: (if rta was modificied) contains a modified uncached rta, which
3157: uses parts allocated from <param/tmp_pool/ and parts shared from original
3158: rta. There is one exception - if <param/rte/ is rw but contains a cached
3159: rta and that is modified, rta in returned rte is also cached.
3160: <p>
3161: Ownership of cached rtas is consistent with rte, i.e.
3162: if a new rte is returned, it has its own clone of cached rta
3163: (and cached rta of read-only source rte is intact), if rte is
3164: modified in place, old cached rta is possibly freed.
3165: </function>
3166: <function><p><type>int</type>
3167: <funcdef>filter_same</funcdef>
3168: (<type>struct filter *</type> <param>new</param>, <type>struct filter *</type> <param>old</param>) -- compare two filters
3169:
3170: <funcsect>Arguments
3171: <p><descrip>
3172: <tagp><type>struct filter *</type> <param>new</param></tagp>
3173: first filter to be compared
3174: <tagp><type>struct filter *</type> <param>old</param></tagp>
3175: second filter to be compared, notice that this filter is
3176: damaged while comparing.
3177: </descrip>
3178: <funcsect>Description
3179: <p>
3180: Returns 1 in case filters are same, otherwise 0. If there are
3181: underlying bugs, it will rather say 0 on same filters than say
3182: 1 on different.
3183: </function>
3184: <function><p><type>struct f_tree *</type>
3185: <funcdef>find_tree</funcdef>
3186: (<type>struct f_tree *</type> <param>t</param>, <type>struct f_val</type> <param>val</param>)
3187: <funcsect>Arguments
3188: <p><descrip>
3189: <tagp><type>struct f_tree *</type> <param>t</param></tagp>
3190: tree to search in
3191: <tagp><type>struct f_val</type> <param>val</param></tagp>
3192: value to find
3193: </descrip>
3194: <funcsect>Description
3195: <p>
3196: Search for given value in the tree. I relies on fact that sorted tree is populated
3197: by <struct/f_val/ structures (that can be compared by <func/val_compare()/). In each node of tree,
3198: either single value (then t->from==t->to) or range is present.
3199: <p>
3200: Both set matching and <tt><func/switch()/ { }</tt> construction is implemented using this function,
3201: thus both are as fast as they can be.
3202: </function>
3203: <function><p><type>struct f_tree *</type>
3204: <funcdef>build_tree</funcdef>
3205: (<type>struct f_tree *</type> <param>from</param>)
3206: <funcsect>Arguments
3207: <p><descrip>
3208: <tagp><type>struct f_tree *</type> <param>from</param></tagp>
3209: degenerated tree (linked by <param/tree/->left) to be transformed into form suitable for <func/find_tree()/
3210: </descrip>
3211: <funcsect>Description
3212: <p>
3213: Transforms degenerated tree into balanced tree.
3214: </function>
3215: <function><p><type>int</type>
3216: <funcdef>same_tree</funcdef>
3217: (<type>struct f_tree *</type> <param>t1</param>, <type>struct f_tree *</type> <param>t2</param>)
3218: <funcsect>Arguments
3219: <p><descrip>
3220: <tagp><type>struct f_tree *</type> <param>t1</param></tagp>
3221: first tree to be compared
3222: <tagp><type>struct f_tree *</type> <param>t2</param></tagp>
3223: second one
3224: </descrip>
3225: <funcsect>Description
3226: <p>
3227: Compares two trees and returns 1 if they are same
3228: </function>
3229: <sect>Trie for prefix sets
3230: <p>
3231: <p>
3232: We use a (compressed) trie to represent prefix sets. Every node
3233: in the trie represents one prefix (<struct/addr//<struct/plen/) and <struct/plen/ also
3234: indicates the index of the bit in the address that is used to
3235: branch at the node. If we need to represent just a set of
3236: prefixes, it would be simple, but we have to represent a
3237: set of prefix patterns. Each prefix pattern consists of
3238: <struct/ppaddr//<struct/pplen/ and two integers: <struct/low/ and <struct/high/, and a prefix
3239: <struct/paddr//<struct/plen/ matches that pattern if the first MIN(<struct/plen/, <struct/pplen/)
3240: bits of <struct/paddr/ and <struct/ppaddr/ are the same and <struct/low/ <= <struct/plen/ <= <struct/high/.
3241: <p>
3242: We use a bitmask (<struct/accept/) to represent accepted prefix lengths
3243: at a node. As there are 33 prefix lengths (0..32 for IPv4), but
3244: there is just one prefix of zero length in the whole trie so we
3245: have <struct/zero/ flag in <struct/f_trie/ (indicating whether the trie accepts
3246: prefix 0.0.0.0/0) as a special case, and <struct/accept/ bitmask
3247: represents accepted prefix lengths from 1 to 32.
3248: <p>
3249: There are two cases in prefix matching - a match when the length
3250: of the prefix is smaller that the length of the prefix pattern,
3251: (<struct/plen/ < <struct/pplen/) and otherwise. The second case is simple - we
3252: just walk through the trie and look at every visited node
3253: whether that prefix accepts our prefix length (<struct/plen/). The
3254: first case is tricky - we don't want to examine every descendant
3255: of a final node, so (when we create the trie) we have to propagate
3256: that information from nodes to their ascendants.
3257: <p>
3258: Suppose that we have two masks (M1 and M2) for a node. Mask M1
3259: represents accepted prefix lengths by just the node and mask M2
3260: represents accepted prefix lengths by the node or any of its
3261: descendants. Therefore M2 is a bitwise or of M1 and children's
3262: M2 and this is a maintained invariant during trie building.
3263: Basically, when we want to match a prefix, we walk through the trie,
3264: check mask M1 for our prefix length and when we came to
3265: final node, we check mask M2.
3266: <p>
3267: There are two differences in the real implementation. First,
3268: we use a compressed trie so there is a case that we skip our
3269: final node (if it is not in the trie) and we came to node that
3270: is either extension of our prefix, or completely out of path
3271: In the first case, we also have to check M2.
3272: <p>
3273: Second, we really need not to maintain two separate bitmasks.
3274: Checks for mask M1 are always larger than <struct/applen/ and we need
3275: just the first <struct/pplen/ bits of mask M2 (if trie compression
3276: hadn't been used it would suffice to know just $applen-th bit),
3277: so we have to store them together in <struct/accept/ mask - the first
3278: <struct/pplen/ bits of mask M2 and then mask M1.
3279: <p>
3280: There are four cases when we walk through a trie:
3281: <p>
3282: - we are in NULL
3283: - we are out of path (prefixes are inconsistent)
3284: - we are in the wanted (final) node (node length == <struct/plen/)
3285: - we are beyond the end of path (node length > <struct/plen/)
3286: - we are still on path and keep walking (node length < <struct/plen/)
3287: <p>
3288: The walking code in <func/trie_match_prefix()/ is structured according to
3289: these cases.
3290:
3291:
3292: <function><p><type>struct f_trie *</type>
3293: <funcdef>f_new_trie</funcdef>
3294: (<type>linpool *</type> <param>lp</param>, <type>uint</type> <param>node_size</param>) -- allocates and returns a new empty trie
3295:
3296: <funcsect>Arguments
3297: <p><descrip>
3298: <tagp><type>linpool *</type> <param>lp</param></tagp>
3299: linear pool to allocate items from
3300: <tagp><type>uint</type> <param>node_size</param></tagp>
3301: node size to be used (<struct/f_trie_node/ and user data)
3302: </descrip>
3303: </function>
3304: <function><p><type>void *</type>
3305: <funcdef>trie_add_prefix</funcdef>
3306: (<type>struct f_trie *</type> <param>t</param>, <type>ip_addr</type> <param>px</param>, <type>int</type> <param>plen</param>, <type>int</type> <param>l</param>, <type>int</type> <param>h</param>)
3307: <funcsect>Arguments
3308: <p><descrip>
3309: <tagp><type>struct f_trie *</type> <param>t</param></tagp>
3310: trie to add to
3311: <tagp><type>ip_addr</type> <param>px</param></tagp>
3312: prefix address
3313: <tagp><type>int</type> <param>plen</param></tagp>
3314: prefix length
3315: <tagp><type>int</type> <param>l</param></tagp>
3316: prefix lower bound
3317: <tagp><type>int</type> <param>h</param></tagp>
3318: prefix upper bound
3319: </descrip>
3320: <funcsect>Description
3321: <p>
3322: Adds prefix (prefix pattern) <param/px//<param/plen/ to trie <param/t/. <param/l/ and <param/h/ are lower
3323: and upper bounds on accepted prefix lengths, both inclusive.
3324: 0 <= l, h <= 32 (128 for IPv6).
3325: <p>
3326: Returns a pointer to the allocated node. The function can return a pointer to
3327: an existing node if <param/px/ and <param/plen/ are the same. If px/plen == 0/0 (or ::/0),
3328: a pointer to the root node is returned.
3329: </function>
3330: <function><p><type>int</type>
3331: <funcdef>trie_match_prefix</funcdef>
3332: (<type>struct f_trie *</type> <param>t</param>, <type>ip_addr</type> <param>px</param>, <type>int</type> <param>plen</param>)
3333: <funcsect>Arguments
3334: <p><descrip>
3335: <tagp><type>struct f_trie *</type> <param>t</param></tagp>
3336: trie
3337: <tagp><type>ip_addr</type> <param>px</param></tagp>
3338: prefix address
3339: <tagp><type>int</type> <param>plen</param></tagp>
3340: prefix length
3341: </descrip>
3342: <funcsect>Description
3343: <p>
3344: Tries to find a matching prefix pattern in the trie such that
3345: prefix <param/px//<param/plen/ matches that prefix pattern. Returns 1 if there
3346: is such prefix pattern in the trie.
3347: </function>
3348: <function><p><type>int</type>
3349: <funcdef>trie_same</funcdef>
3350: (<type>struct f_trie *</type> <param>t1</param>, <type>struct f_trie *</type> <param>t2</param>)
3351: <funcsect>Arguments
3352: <p><descrip>
3353: <tagp><type>struct f_trie *</type> <param>t1</param></tagp>
3354: first trie to be compared
3355: <tagp><type>struct f_trie *</type> <param>t2</param></tagp>
3356: second one
3357: </descrip>
3358: <funcsect>Description
3359: <p>
3360: Compares two tries and returns 1 if they are same
3361: </function>
3362: <function><p><type>void</type>
3363: <funcdef>trie_format</funcdef>
3364: (<type>struct f_trie *</type> <param>t</param>, <type>buffer *</type> <param>buf</param>)
3365: <funcsect>Arguments
3366: <p><descrip>
3367: <tagp><type>struct f_trie *</type> <param>t</param></tagp>
3368: trie to be formatted
3369: <tagp><type>buffer *</type> <param>buf</param></tagp>
3370: destination buffer
3371: </descrip>
3372: <funcsect>Description
3373: <p>
3374: Prints the trie to the supplied buffer.
3375: </function>
3376: <chapt>Protocols
3377: <sect>The Babel protocol
3378: <p>
3379: <p>
3380: Babel (RFC6126) is a loop-avoiding distance-vector routing protocol that is
3381: robust and efficient both in ordinary wired networks and in wireless mesh
3382: networks.
3383: <p>
3384: The Babel protocol keeps state for each neighbour in a <struct/babel_neighbor/
3385: struct, tracking received Hello and I Heard You (IHU) messages. A
3386: <struct/babel_interface/ struct keeps hello and update times for each interface, and
3387: a separate hello seqno is maintained for each interface.
3388: <p>
3389: For each prefix, Babel keeps track of both the possible routes (with next hop
3390: and router IDs), as well as the feasibility distance for each prefix and
3391: router id. The prefix itself is tracked in a <struct/babel_entry/ struct, while the
3392: possible routes for the prefix are tracked as <struct/babel_route/ entries and the
3393: feasibility distance is maintained through <struct/babel_source/ structures.
3394: <p>
3395: The main route selection is done in <func/babel_select_route()/. This is called when
3396: an entry is updated by receiving updates from the network or when modified by
3397: internal timers. It performs feasibility checks on the available routes for
3398: the prefix and selects the one with the lowest metric to be announced to the
3399: core.
3400:
3401:
3402: <function><p><type>void</type>
3403: <funcdef>babel_announce_rte</funcdef>
3404: (<type>struct babel_proto *</type> <param>p</param>, <type>struct babel_entry *</type> <param>e</param>) -- announce selected route to the core
3405:
3406: <funcsect>Arguments
3407: <p><descrip>
3408: <tagp><type>struct babel_proto *</type> <param>p</param></tagp>
3409: Babel protocol instance
3410: <tagp><type>struct babel_entry *</type> <param>e</param></tagp>
3411: Babel route entry to announce
3412: </descrip>
3413: <funcsect>Description
3414: <p>
3415: This function announces a Babel entry to the core if it has a selected
3416: incoming path, and retracts it otherwise. If the selected entry has infinite
3417: metric, the route is announced as unreachable.
3418: </function>
3419: <function><p><type>void</type>
3420: <funcdef>babel_select_route</funcdef>
3421: (<type>struct babel_entry *</type> <param>e</param>) -- select best route for given route entry
3422:
3423: <funcsect>Arguments
3424: <p><descrip>
3425: <tagp><type>struct babel_entry *</type> <param>e</param></tagp>
3426: Babel entry to select the best route for
3427: </descrip>
3428: <funcsect>Description
3429: <p>
3430: Select the best feasible route for a given prefix among the routes received
3431: from peers, and propagate it to the nest. This just selects the feasible
3432: route with the lowest metric.
3433: <p>
3434: If no feasible route is available for a prefix that previously had a route
3435: selected, a seqno request is sent to try to get a valid route. In the
3436: meantime, the route is marked as infeasible in the nest (to blackhole packets
3437: going to it, as per the RFC).
3438: <p>
3439: If no feasible route is available, and no previous route is selected, the
3440: route is removed from the nest entirely.
3441: </function>
3442: <function><p><type>void</type>
3443: <funcdef>babel_send_update</funcdef>
3444: (<type>struct babel_iface *</type> <param>ifa</param>, <type>bird_clock_t</type> <param>changed</param>) -- send route table updates
3445:
3446: <funcsect>Arguments
3447: <p><descrip>
3448: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
3449: Interface to transmit on
3450: <tagp><type>bird_clock_t</type> <param>changed</param></tagp>
3451: Only send entries changed since this time
3452: </descrip>
3453: <funcsect>Description
3454: <p>
3455: This function produces update TLVs for all entries changed since the time
3456: indicated by the <struct/changed/ parameter and queues them for transmission on the
3457: selected interface. During the process, the feasibility distance for each
3458: transmitted entry is updated.
3459: </function>
3460: <function><p><type>void</type>
3461: <funcdef>babel_handle_update</funcdef>
3462: (<type>union babel_msg *</type> <param>m</param>, <type>struct babel_iface *</type> <param>ifa</param>) -- handle incoming route updates
3463:
3464: <funcsect>Arguments
3465: <p><descrip>
3466: <tagp><type>union babel_msg *</type> <param>m</param></tagp>
3467: Incoming update TLV
3468: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
3469: Interface the update was received on
3470: </descrip>
3471: <funcsect>Description
3472: <p>
3473: This function is called as a handler for update TLVs and handles the updating
3474: and maintenance of route entries in Babel's internal routing cache. The
3475: handling follows the actions described in the Babel RFC, and at the end of
3476: each update handling, <func/babel_select_route()/ is called on the affected entry to
3477: optionally update the selected routes and propagate them to the core.
3478: </function>
3479: <function><p><type>void</type>
3480: <funcdef>babel_iface_timer</funcdef>
3481: (<type>timer *</type> <param>t</param>) -- Babel interface timer handler
3482:
3483: <funcsect>Arguments
3484: <p><descrip>
3485: <tagp><type>timer *</type> <param>t</param></tagp>
3486: Timer
3487: </descrip>
3488: <funcsect>Description
3489: <p>
3490: This function is called by the per-interface timer and triggers sending of
3491: periodic Hello's and both triggered and periodic updates. Periodic Hello's
3492: and updates are simply handled by setting the next_{hello,regular} variables
3493: on the interface, and triggering an update (and resetting the variable)
3494: whenever 'now' exceeds that value.
3495: <p>
3496: For triggered updates, <func/babel_trigger_iface_update()/ will set the
3497: want_triggered field on the interface to a timestamp value. If this is set
3498: (and the next_triggered time has passed; this is a rate limiting mechanism),
3499: <func/babel_send_update()/ will be called with this timestamp as the second
3500: parameter. This causes updates to be send consisting of only the routes that
3501: have changed since the time saved in want_triggered.
3502: <p>
3503: Mostly when an update is triggered, the route being modified will be set to
3504: the value of 'now' at the time of the trigger; the >= comparison for
3505: selecting which routes to send in the update will make sure this is included.
3506: </function>
3507: <function><p><type>void</type>
3508: <funcdef>babel_timer</funcdef>
3509: (<type>timer *</type> <param>t</param>) -- global timer hook
3510:
3511: <funcsect>Arguments
3512: <p><descrip>
3513: <tagp><type>timer *</type> <param>t</param></tagp>
3514: Timer
3515: </descrip>
3516: <funcsect>Description
3517: <p>
3518: This function is called by the global protocol instance timer and handles
3519: expiration of routes and neighbours as well as pruning of the seqno request
3520: cache.
3521: </function>
3522: <function><p><type>uint</type>
3523: <funcdef>babel_write_queue</funcdef>
3524: (<type>struct babel_iface *</type> <param>ifa</param>, <type>list *</type> <param>queue</param>) -- Write a TLV queue to a transmission buffer
3525:
3526: <funcsect>Arguments
3527: <p><descrip>
3528: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
3529: Interface holding the transmission buffer
3530: <tagp><type>list *</type> <param>queue</param></tagp>
3531: TLV queue to write (containing internal-format TLVs)
3532: </descrip>
3533: <funcsect>Description
3534: <p>
3535: This function writes a packet to the interface transmission buffer with as
3536: many TLVs from the <struct/queue/ as will fit in the buffer. It returns the number of
3537: bytes written (NOT counting the packet header). The function is called by
3538: <func/babel_send_queue()/ and <func/babel_send_unicast()/ to construct packets for
3539: transmission, and uses per-TLV helper functions to convert the
3540: internal-format TLVs to their wire representations.
3541: <p>
3542: The TLVs in the queue are freed after they are written to the buffer.
3543: </function>
3544: <function><p><type>void</type>
3545: <funcdef>babel_send_unicast</funcdef>
3546: (<type>union babel_msg *</type> <param>msg</param>, <type>struct babel_iface *</type> <param>ifa</param>, <type>ip_addr</type> <param>dest</param>) -- send a single TLV via unicast to a destination
3547:
3548: <funcsect>Arguments
3549: <p><descrip>
3550: <tagp><type>union babel_msg *</type> <param>msg</param></tagp>
3551: TLV to send
3552: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
3553: Interface to send via
3554: <tagp><type>ip_addr</type> <param>dest</param></tagp>
3555: Destination of the TLV
3556: </descrip>
3557: <funcsect>Description
3558: <p>
3559: This function is used to send a single TLV via unicast to a designated
3560: receiver. This is used for replying to certain incoming requests, and for
3561: sending unicast requests to refresh routes before they expire.
3562: </function>
3563: <function><p><type>void</type>
3564: <funcdef>babel_enqueue</funcdef>
3565: (<type>union babel_msg *</type> <param>msg</param>, <type>struct babel_iface *</type> <param>ifa</param>) -- enqueue a TLV for transmission on an interface
3566:
3567: <funcsect>Arguments
3568: <p><descrip>
3569: <tagp><type>union babel_msg *</type> <param>msg</param></tagp>
3570: TLV to enqueue (in internal TLV format)
3571: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
3572: Interface to enqueue to
3573: </descrip>
3574: <funcsect>Description
3575: <p>
3576: This function is called to enqueue a TLV for subsequent transmission on an
3577: interface. The transmission event is triggered whenever a TLV is enqueued;
3578: this ensures that TLVs will be transmitted in a timely manner, but that TLVs
3579: which are enqueued in rapid succession can be transmitted together in one
3580: packet.
3581: </function>
3582: <function><p><type>void</type>
3583: <funcdef>babel_process_packet</funcdef>
3584: (<type>struct babel_pkt_header *</type> <param>pkt</param>, <type>int</type> <param>len</param>, <type>ip_addr</type> <param>saddr</param>, <type>struct babel_iface *</type> <param>ifa</param>) -- process incoming data packet
3585:
3586: <funcsect>Arguments
3587: <p><descrip>
3588: <tagp><type>struct babel_pkt_header *</type> <param>pkt</param></tagp>
3589: Pointer to the packet data
3590: <tagp><type>int</type> <param>len</param></tagp>
3591: Length of received packet
3592: <tagp><type>ip_addr</type> <param>saddr</param></tagp>
3593: Address of packet sender
3594: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
3595: Interface packet was received on.
3596: </descrip>
3597: <funcsect>Description
3598: <p>
3599: This function is the main processing hook of incoming Babel packets. It
3600: checks that the packet header is well-formed, then processes the TLVs
3601: contained in the packet. This is done in two passes: First all TLVs are
3602: parsed into the internal TLV format. If a TLV parser fails, processing of the
3603: rest of the packet is aborted.
3604: <p>
3605: After the parsing step, the TLV handlers are called for each parsed TLV in
3606: order.
3607: </function>
3608: <sect>Bidirectional Forwarding Detection
3609: <p>
3610: <p>
3611: The BFD protocol is implemented in three files: <tt>bfd.c</tt> containing the
3612: protocol logic and the protocol glue with BIRD core, <tt>packets.c</tt> handling BFD
3613: packet processing, RX, TX and protocol sockets. <tt>io.c</tt> then contains generic
3614: code for the event loop, threads and event sources (sockets, microsecond
3615: timers). This generic code will be merged to the main BIRD I/O code in the
3616: future.
3617: <p>
3618: The BFD implementation uses a separate thread with an internal event loop for
3619: handling the protocol logic, which requires high-res and low-latency timing,
3620: so it is not affected by the rest of BIRD, which has several low-granularity
3621: hooks in the main loop, uses second-based timers and cannot offer good
3622: latency. The core of BFD protocol (the code related to BFD sessions,
3623: interfaces and packets) runs in the BFD thread, while the rest (the code
3624: related to BFD requests, BFD neighbors and the protocol glue) runs in the
3625: main thread.
3626: <p>
3627: BFD sessions are represented by structure <struct/bfd_session/ that contains a state
3628: related to the session and two timers (TX timer for periodic packets and hold
3629: timer for session timeout). These sessions are allocated from <param/session_slab/
3630: and are accessible by two hash tables, <param/session_hash_id/ (by session ID) and
3631: <param/session_hash_ip/ (by IP addresses of neighbors). Slab and both hashes are in
3632: the main protocol structure <struct/bfd_proto/. The protocol logic related to BFD
3633: sessions is implemented in internal functions bfd_session_*(), which are
3634: expected to be called from the context of BFD thread, and external functions
3635: <func/bfd_add_session()/, <func/bfd_remove_session()/ and <func/bfd_reconfigure_session()/, which
3636: form an interface to the BFD core for the rest and are expected to be called
3637: from the context of main thread.
3638: <p>
3639: Each BFD session has an associated BFD interface, represented by structure
3640: <struct/bfd_iface/. A BFD interface contains a socket used for TX (the one for RX is
3641: shared in <struct/bfd_proto/), an interface configuration and reference counter.
3642: Compared to interface structures of other protocols, these structures are not
3643: created and removed based on interface notification events, but according to
3644: the needs of BFD sessions. When a new session is created, it requests a
3645: proper BFD interface by function <func/bfd_get_iface()/, which either finds an
3646: existing one in <struct/iface_list/ (from <struct/bfd_proto/) or allocates a new one. When a
3647: session is removed, an associated iface is discharged by <func/bfd_free_iface()/.
3648: <p>
3649: BFD requests are the external API for the other protocols. When a protocol
3650: wants a BFD session, it calls <func/bfd_request_session()/, which creates a
3651: structure <struct/bfd_request/ containing approprite information and an notify hook.
3652: This structure is a resource associated with the caller's resource pool. When
3653: a BFD protocol is available, a BFD request is submitted to the protocol, an
3654: appropriate BFD session is found or created and the request is attached to
3655: the session. When a session changes state, all attached requests (and related
3656: protocols) are notified. Note that BFD requests do not depend on BFD protocol
3657: running. When the BFD protocol is stopped or removed (or not available from
3658: beginning), related BFD requests are stored in <param/bfd_wait_list/, where waits
3659: for a new protocol.
3660: <p>
3661: BFD neighbors are just a way to statically configure BFD sessions without
3662: requests from other protocol. Structures <struct/bfd_neighbor/ are part of BFD
3663: configuration (like static routes in the static protocol). BFD neighbors are
3664: handled by BFD protocol like it is a BFD client -- when a BFD neighbor is
3665: ready, the protocol just creates a BFD request like any other protocol.
3666: <p>
3667: The protocol uses a new generic event loop (structure <struct/birdloop/) from <tt>io.c</tt>,
3668: which supports sockets, timers and events like the main loop. Timers
3669: (structure <struct/timer2/) are new microsecond based timers, while sockets and
3670: events are the same. A birdloop is associated with a thread (field <param/thread/)
3671: in which event hooks are executed. Most functions for setting event sources
3672: (like <func/sk_start()/ or <func/tm2_start()/) must be called from the context of that
3673: thread. Birdloop allows to temporarily acquire the context of that thread for
3674: the main thread by calling <func/birdloop_enter()/ and then <func/birdloop_leave()/, which
3675: also ensures mutual exclusion with all event hooks. Note that resources
3676: associated with a birdloop (like timers) should be attached to the
3677: independent resource pool, detached from the main resource tree.
3678: <p>
3679: There are two kinds of interaction between the BFD core (running in the BFD
3680: thread) and the rest of BFD (running in the main thread). The first kind are
3681: configuration calls from main thread to the BFD thread (like <func/bfd_add_session()/).
3682: These calls are synchronous and use <func/birdloop_enter()/ mechanism for mutual
3683: exclusion. The second kind is a notification about session changes from the
3684: BFD thread to the main thread. This is done in an asynchronous way, sesions
3685: with pending notifications are linked (in the BFD thread) to <param/notify_list/ in
3686: <struct/bfd_proto/, and then <func/bfd_notify_hook()/ in the main thread is activated using
3687: <func/bfd_notify_kick()/ and a pipe. The hook then processes scheduled sessions and
3688: calls hooks from associated BFD requests. This <param/notify_list/ (and state fields
3689: in structure <struct/bfd_session/) is protected by a spinlock in <struct/bfd_proto/ and
3690: functions <func/bfd_lock_sessions()/ / <func/bfd_unlock_sessions()/.
3691: <p>
3692: There are few data races (accessing <param/p/->p.debug from <func/TRACE()/ from the BFD
3693: thread and accessing some some private fields of <const/bfd_session/ from
3694: <func/bfd_show_sessions()/ from the main thread, but these are harmless (i hope).
3695: <p>
3696: TODO: document functions and access restrictions for fields in BFD structures.
3697: <p>
3698: Supported standards:
3699: - RFC 5880 - main BFD standard
3700: - RFC 5881 - BFD for IP links
3701: - RFC 5882 - generic application of BFD
3702: - RFC 5883 - BFD for multihop paths
3703:
3704:
3705: <sect>Border Gateway Protocol
3706: <p>
3707: <p>
3708: The BGP protocol is implemented in three parts: <tt>bgp.c</tt> which takes care of the
3709: connection and most of the interface with BIRD core, <tt>packets.c</tt> handling
3710: both incoming and outgoing BGP packets and <tt>attrs.c</tt> containing functions for
3711: manipulation with BGP attribute lists.
3712: <p>
3713: As opposed to the other existing routing daemons, BIRD has a sophisticated core
3714: architecture which is able to keep all the information needed by BGP in the
3715: primary routing table, therefore no complex data structures like a central
3716: BGP table are needed. This increases memory footprint of a BGP router with
3717: many connections, but not too much and, which is more important, it makes
3718: BGP much easier to implement.
3719: <p>
3720: Each instance of BGP (corresponding to a single BGP peer) is described by a <struct/bgp_proto/
3721: structure to which are attached individual connections represented by <struct/bgp_connection/
3722: (usually, there exists only one connection, but during BGP session setup, there
3723: can be more of them). The connections are handled according to the BGP state machine
3724: defined in the RFC with all the timers and all the parameters configurable.
3725: <p>
3726: In incoming direction, we listen on the connection's socket and each time we receive
3727: some input, we pass it to <func/bgp_rx()/. It decodes packet headers and the markers and
3728: passes complete packets to <func/bgp_rx_packet()/ which distributes the packet according
3729: to its type.
3730: <p>
3731: In outgoing direction, we gather all the routing updates and sort them to buckets
3732: (<struct/bgp_bucket/) according to their attributes (we keep a hash table for fast comparison
3733: of <struct/rta/'s and a <struct/fib/ which helps us to find if we already have another route for
3734: the same destination queued for sending, so that we can replace it with the new one
3735: immediately instead of sending both updates). There also exists a special bucket holding
3736: all the route withdrawals which cannot be queued anywhere else as they don't have any
3737: attributes. If we have any packet to send (due to either new routes or the connection
3738: tracking code wanting to send a Open, Keepalive or Notification message), we call
3739: <func/bgp_schedule_packet()/ which sets the corresponding bit in a <param/packet_to_send/
3740: bit field in <struct/bgp_conn/ and as soon as the transmit socket buffer becomes empty,
3741: we call <func/bgp_fire_tx()/. It inspects state of all the packet type bits and calls
3742: the corresponding <func/bgp_create_xx()/ functions, eventually rescheduling the same packet
3743: type if we have more data of the same type to send.
3744: <p>
3745: The processing of attributes consists of two functions: <func/bgp_decode_attrs()/ for checking
3746: of the attribute blocks and translating them to the language of BIRD's extended attributes
3747: and <func/bgp_encode_attrs()/ which does the converse. Both functions are built around a
3748: <param/bgp_attr_table/ array describing all important characteristics of all known attributes.
3749: Unknown transitive attributes are attached to the route as <const/EAF_TYPE_OPAQUE/ byte streams.
3750: <p>
3751: BGP protocol implements graceful restart in both restarting (local restart)
3752: and receiving (neighbor restart) roles. The first is handled mostly by the
3753: graceful restart code in the nest, BGP protocol just handles capabilities,
3754: sets <param/gr_wait/ and locks graceful restart until end-of-RIB mark is received.
3755: The second is implemented by internal restart of the BGP state to <const/BS_IDLE/
3756: and protocol state to <const/PS_START/, but keeping the protocol up from the core
3757: point of view and therefore maintaining received routes. Routing table
3758: refresh cycle (<func/rt_refresh_begin()/, <func/rt_refresh_end()/) is used for removing
3759: stale routes after reestablishment of BGP session during graceful restart.
3760:
3761:
3762: <function><p><type>int</type>
3763: <funcdef>bgp_open</funcdef>
3764: (<type>struct bgp_proto *</type> <param>p</param>) -- open a BGP instance
3765:
3766: <funcsect>Arguments
3767: <p><descrip>
3768: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
3769: BGP instance
3770: </descrip>
3771: <funcsect>Description
3772: <p>
3773: This function allocates and configures shared BGP resources.
3774: Should be called as the last step during initialization
3775: (when lock is acquired and neighbor is ready).
3776: When error, state changed to PS_DOWN, -1 is returned and caller
3777: should return immediately.
3778: </function>
3779: <function><p><type>void</type>
3780: <funcdef>bgp_close</funcdef>
3781: (<type>struct bgp_proto *</type> <param>p</param>, <type>int</type> <param>apply_md5</param>) -- close a BGP instance
3782:
3783: <funcsect>Arguments
3784: <p><descrip>
3785: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
3786: BGP instance
3787: <tagp><type>int</type> <param>apply_md5</param></tagp>
3788: 0 to disable unsetting MD5 auth
3789: </descrip>
3790: <funcsect>Description
3791: <p>
3792: This function frees and deconfigures shared BGP resources.
3793: <param/apply_md5/ is set to 0 when bgp_close is called as a cleanup
3794: from failed <func/bgp_open()/.
3795: </function>
3796: <function><p><type>void</type>
3797: <funcdef>bgp_start_timer</funcdef>
3798: (<type>timer *</type> <param>t</param>, <type>int</type> <param>value</param>) -- start a BGP timer
3799:
3800: <funcsect>Arguments
3801: <p><descrip>
3802: <tagp><type>timer *</type> <param>t</param></tagp>
3803: timer
3804: <tagp><type>int</type> <param>value</param></tagp>
3805: time to fire (0 to disable the timer)
3806: </descrip>
3807: <funcsect>Description
3808: <p>
3809: This functions calls <func/tm_start()/ on <param/t/ with time <param/value/ and the
3810: amount of randomization suggested by the BGP standard. Please use
3811: it for all BGP timers.
3812: </function>
3813: <function><p><type>void</type>
3814: <funcdef>bgp_close_conn</funcdef>
3815: (<type>struct bgp_conn *</type> <param>conn</param>) -- close a BGP connection
3816:
3817: <funcsect>Arguments
3818: <p><descrip>
3819: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
3820: connection to close
3821: </descrip>
3822: <funcsect>Description
3823: <p>
3824: This function takes a connection described by the <struct/bgp_conn/ structure,
3825: closes its socket and frees all resources associated with it.
3826: </function>
3827: <function><p><type>void</type>
3828: <funcdef>bgp_update_startup_delay</funcdef>
3829: (<type>struct bgp_proto *</type> <param>p</param>) -- update a startup delay
3830:
3831: <funcsect>Arguments
3832: <p><descrip>
3833: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
3834: BGP instance
3835: </descrip>
3836: <funcsect>Description
3837: <p>
3838: This function updates a startup delay that is used to postpone next BGP connect.
3839: It also handles disable_after_error and might stop BGP instance when error
3840: happened and disable_after_error is on.
3841: <p>
3842: It should be called when BGP protocol error happened.
3843: </function>
3844: <function><p><type>void</type>
3845: <funcdef>bgp_handle_graceful_restart</funcdef>
3846: (<type>struct bgp_proto *</type> <param>p</param>) -- handle detected BGP graceful restart
3847:
3848: <funcsect>Arguments
3849: <p><descrip>
3850: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
3851: BGP instance
3852: </descrip>
3853: <funcsect>Description
3854: <p>
3855: This function is called when a BGP graceful restart of the neighbor is
3856: detected (when the TCP connection fails or when a new TCP connection
3857: appears). The function activates processing of the restart - starts routing
3858: table refresh cycle and activates BGP restart timer. The protocol state goes
3859: back to <const/PS_START/, but changing BGP state back to <const/BS_IDLE/ is left for the
3860: caller.
3861: </function>
3862: <function><p><type>void</type>
3863: <funcdef>bgp_graceful_restart_done</funcdef>
3864: (<type>struct bgp_proto *</type> <param>p</param>) -- finish active BGP graceful restart
3865:
3866: <funcsect>Arguments
3867: <p><descrip>
3868: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
3869: BGP instance
3870: </descrip>
3871: <funcsect>Description
3872: <p>
3873: This function is called when the active BGP graceful restart of the neighbor
3874: should be finished - either successfully (the neighbor sends all paths and
3875: reports end-of-RIB on the new session) or unsuccessfully (the neighbor does
3876: not support BGP graceful restart on the new session). The function ends
3877: routing table refresh cycle and stops BGP restart timer.
3878: </function>
3879: <function><p><type>void</type>
3880: <funcdef>bgp_graceful_restart_timeout</funcdef>
3881: (<type>timer *</type> <param>t</param>) -- timeout of graceful restart 'restart timer'
3882:
3883: <funcsect>Arguments
3884: <p><descrip>
3885: <tagp><type>timer *</type> <param>t</param></tagp>
3886: timer
3887: </descrip>
3888: <funcsect>Description
3889: <p>
3890: This function is a timeout hook for <param/gr_timer/, implementing BGP restart time
3891: limit for reestablisment of the BGP session after the graceful restart. When
3892: fired, we just proceed with the usual protocol restart.
3893: </function>
3894: <function><p><type>void</type>
3895: <funcdef>bgp_refresh_begin</funcdef>
3896: (<type>struct bgp_proto *</type> <param>p</param>) -- start incoming enhanced route refresh sequence
3897:
3898: <funcsect>Arguments
3899: <p><descrip>
3900: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
3901: BGP instance
3902: </descrip>
3903: <funcsect>Description
3904: <p>
3905: This function is called when an incoming enhanced route refresh sequence is
3906: started by the neighbor, demarcated by the BoRR packet. The function updates
3907: the load state and starts the routing table refresh cycle. Note that graceful
3908: restart also uses routing table refresh cycle, but RFC 7313 and load states
3909: ensure that these two sequences do not overlap.
3910: </function>
3911: <function><p><type>void</type>
3912: <funcdef>bgp_refresh_end</funcdef>
3913: (<type>struct bgp_proto *</type> <param>p</param>) -- finish incoming enhanced route refresh sequence
3914:
3915: <funcsect>Arguments
3916: <p><descrip>
3917: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
3918: BGP instance
3919: </descrip>
3920: <funcsect>Description
3921: <p>
3922: This function is called when an incoming enhanced route refresh sequence is
3923: finished by the neighbor, demarcated by the EoRR packet. The function updates
3924: the load state and ends the routing table refresh cycle. Routes not received
3925: during the sequence are removed by the nest.
3926: </function>
3927: <function><p><type>void</type>
3928: <funcdef>bgp_connect</funcdef>
3929: (<type>struct bgp_proto *</type> <param>p</param>) -- initiate an outgoing connection
3930:
3931: <funcsect>Arguments
3932: <p><descrip>
3933: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
3934: BGP instance
3935: </descrip>
3936: <funcsect>Description
3937: <p>
3938: The <func/bgp_connect()/ function creates a new <struct/bgp_conn/ and initiates
3939: a TCP connection to the peer. The rest of connection setup is governed
3940: by the BGP state machine as described in the standard.
3941: </function>
3942: <function><p><type>struct bgp_proto *</type>
3943: <funcdef>bgp_find_proto</funcdef>
3944: (<type>sock *</type> <param>sk</param>) -- find existing proto for incoming connection
3945:
3946: <funcsect>Arguments
3947: <p><descrip>
3948: <tagp><type>sock *</type> <param>sk</param></tagp>
3949: TCP socket
3950: </descrip>
3951: </function>
3952: <function><p><type>int</type>
3953: <funcdef>bgp_incoming_connection</funcdef>
3954: (<type>sock *</type> <param>sk</param>, <type>uint dummy</type> <param>UNUSED</param>) -- handle an incoming connection
3955:
3956: <funcsect>Arguments
3957: <p><descrip>
3958: <tagp><type>sock *</type> <param>sk</param></tagp>
3959: TCP socket
3960: <tagp><type>uint dummy</type> <param>UNUSED</param></tagp>
3961: -- undescribed --
3962: </descrip>
3963: <funcsect>Description
3964: <p>
3965: This function serves as a socket hook for accepting of new BGP
3966: connections. It searches a BGP instance corresponding to the peer
3967: which has connected and if such an instance exists, it creates a
3968: <struct/bgp_conn/ structure, attaches it to the instance and either sends
3969: an Open message or (if there already is an active connection) it
3970: closes the new connection by sending a Notification message.
3971: </function>
3972: <function><p><type>void</type>
3973: <funcdef>bgp_error</funcdef>
3974: (<type>struct bgp_conn *</type> <param>c</param>, <type>unsigned</type> <param>code</param>, <type>unsigned</type> <param>subcode</param>, <type>byte *</type> <param>data</param>, <type>int</type> <param>len</param>) -- report a protocol error
3975:
3976: <funcsect>Arguments
3977: <p><descrip>
3978: <tagp><type>struct bgp_conn *</type> <param>c</param></tagp>
3979: connection
3980: <tagp><type>unsigned</type> <param>code</param></tagp>
3981: error code (according to the RFC)
3982: <tagp><type>unsigned</type> <param>subcode</param></tagp>
3983: error sub-code
3984: <tagp><type>byte *</type> <param>data</param></tagp>
3985: data to be passed in the Notification message
3986: <tagp><type>int</type> <param>len</param></tagp>
3987: length of the data
3988: </descrip>
3989: <funcsect>Description
3990: <p>
3991: <func/bgp_error()/ sends a notification packet to tell the other side that a protocol
3992: error has occurred (including the data considered erroneous if possible) and
3993: closes the connection.
3994: </function>
3995: <function><p><type>void</type>
3996: <funcdef>bgp_store_error</funcdef>
3997: (<type>struct bgp_proto *</type> <param>p</param>, <type>struct bgp_conn *</type> <param>c</param>, <type>u8</type> <param>class</param>, <type>u32</type> <param>code</param>) -- store last error for status report
3998:
3999: <funcsect>Arguments
4000: <p><descrip>
4001: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
4002: BGP instance
4003: <tagp><type>struct bgp_conn *</type> <param>c</param></tagp>
4004: connection
4005: <tagp><type>u8</type> <param>class</param></tagp>
4006: error class (BE_xxx constants)
4007: <tagp><type>u32</type> <param>code</param></tagp>
4008: error code (class specific)
4009: </descrip>
4010: <funcsect>Description
4011: <p>
4012: <func/bgp_store_error()/ decides whether given error is interesting enough
4013: and store that error to last_error variables of <param/p/
4014: </function>
4015: <function><p><type>int</type>
4016: <funcdef>bgp_fire_tx</funcdef>
4017: (<type>struct bgp_conn *</type> <param>conn</param>) -- transmit packets
4018:
4019: <funcsect>Arguments
4020: <p><descrip>
4021: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
4022: connection
4023: </descrip>
4024: <funcsect>Description
4025: <p>
4026: Whenever the transmit buffers of the underlying TCP connection
4027: are free and we have any packets queued for sending, the socket functions
4028: call <func/bgp_fire_tx()/ which takes care of selecting the highest priority packet
4029: queued (Notification > Keepalive > Open > Update), assembling its header
4030: and body and sending it to the connection.
4031: </function>
4032: <function><p><type>void</type>
4033: <funcdef>bgp_schedule_packet</funcdef>
4034: (<type>struct bgp_conn *</type> <param>conn</param>, <type>int</type> <param>type</param>) -- schedule a packet for transmission
4035:
4036: <funcsect>Arguments
4037: <p><descrip>
4038: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
4039: connection
4040: <tagp><type>int</type> <param>type</param></tagp>
4041: packet type
4042: </descrip>
4043: <funcsect>Description
4044: <p>
4045: Schedule a packet of type <param/type/ to be sent as soon as possible.
4046: </function>
4047: <function><p><type>const char *</type>
4048: <funcdef>bgp_error_dsc</funcdef>
4049: (<type>unsigned</type> <param>code</param>, <type>unsigned</type> <param>subcode</param>) -- return BGP error description
4050:
4051: <funcsect>Arguments
4052: <p><descrip>
4053: <tagp><type>unsigned</type> <param>code</param></tagp>
4054: BGP error code
4055: <tagp><type>unsigned</type> <param>subcode</param></tagp>
4056: BGP error subcode
4057: </descrip>
4058: <funcsect>Description
4059: <p>
4060: <func/bgp_error_dsc()/ returns error description for BGP errors
4061: which might be static string or given temporary buffer.
4062: </function>
4063: <function><p><type>void</type>
4064: <funcdef>bgp_rx_packet</funcdef>
4065: (<type>struct bgp_conn *</type> <param>conn</param>, <type>byte *</type> <param>pkt</param>, <type>unsigned</type> <param>len</param>) -- handle a received packet
4066:
4067: <funcsect>Arguments
4068: <p><descrip>
4069: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
4070: BGP connection
4071: <tagp><type>byte *</type> <param>pkt</param></tagp>
4072: start of the packet
4073: <tagp><type>unsigned</type> <param>len</param></tagp>
4074: packet size
4075: </descrip>
4076: <funcsect>Description
4077: <p>
4078: <func/bgp_rx_packet()/ takes a newly received packet and calls the corresponding
4079: packet handler according to the packet type.
4080: </function>
4081: <function><p><type>int</type>
4082: <funcdef>bgp_rx</funcdef>
4083: (<type>sock *</type> <param>sk</param>, <type>uint</type> <param>size</param>) -- handle received data
4084:
4085: <funcsect>Arguments
4086: <p><descrip>
4087: <tagp><type>sock *</type> <param>sk</param></tagp>
4088: socket
4089: <tagp><type>uint</type> <param>size</param></tagp>
4090: amount of data received
4091: </descrip>
4092: <funcsect>Description
4093: <p>
4094: <func/bgp_rx()/ is called by the socket layer whenever new data arrive from
4095: the underlying TCP connection. It assembles the data fragments to packets,
4096: checks their headers and framing and passes complete packets to
4097: <func/bgp_rx_packet()/.
4098: </function>
4099: <function><p><type>uint</type>
4100: <funcdef>bgp_encode_attrs</funcdef>
4101: (<type>struct bgp_proto *</type> <param>p</param>, <type>byte *</type> <param>w</param>, <type>ea_list *</type> <param>attrs</param>, <type>int</type> <param>remains</param>) -- encode BGP attributes
4102:
4103: <funcsect>Arguments
4104: <p><descrip>
4105: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
4106: BGP instance (or NULL)
4107: <tagp><type>byte *</type> <param>w</param></tagp>
4108: buffer
4109: <tagp><type>ea_list *</type> <param>attrs</param></tagp>
4110: a list of extended attributes
4111: <tagp><type>int</type> <param>remains</param></tagp>
4112: remaining space in the buffer
4113: </descrip>
4114: <funcsect>Description
4115: <p>
4116: The <func/bgp_encode_attrs()/ function takes a list of extended attributes
4117: and converts it to its BGP representation (a part of an Update message).
4118: <funcsect>Result
4119: <p>
4120: Length of the attribute block generated or -1 if not enough space.
4121: </function>
4122: <function><p><type>struct rta *</type>
4123: <funcdef>bgp_decode_attrs</funcdef>
4124: (<type>struct bgp_conn *</type> <param>conn</param>, <type>byte *</type> <param>attr</param>, <type>uint</type> <param>len</param>, <type>struct linpool *</type> <param>pool</param>, <type>int</type> <param>mandatory</param>) -- check and decode BGP attributes
4125:
4126: <funcsect>Arguments
4127: <p><descrip>
4128: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
4129: connection
4130: <tagp><type>byte *</type> <param>attr</param></tagp>
4131: start of attribute block
4132: <tagp><type>uint</type> <param>len</param></tagp>
4133: length of attribute block
4134: <tagp><type>struct linpool *</type> <param>pool</param></tagp>
4135: linear pool to make all the allocations in
4136: <tagp><type>int</type> <param>mandatory</param></tagp>
4137: 1 iff presence of mandatory attributes has to be checked
4138: </descrip>
4139: <funcsect>Description
4140: <p>
4141: This function takes a BGP attribute block (a part of an Update message), checks
4142: its consistency and converts it to a list of BIRD route attributes represented
4143: by a <struct/rta/.
4144: </function>
4145: <sect>Multi-Threaded Routing Toolkit (MRT) protocol
4146: <p>
4147: <p>
4148: The MRT protocol is implemented in just one file: <tt>mrt.c</tt>. It contains of
4149: several parts: Generic functions for preparing MRT messages in a buffer,
4150: functions for MRT table dump (called from timer or CLI), functions for MRT
4151: BGP4MP dump (called from BGP), and the usual protocol glue. For the MRT table
4152: dump, the key structure is struct mrt_table_dump_state, which contains all
4153: necessary data and created when the MRT dump cycle is started for the
4154: duration of the MRT dump. The MBGP4MP dump is currently not bound to MRT
4155: protocol instance and uses the config->mrtdump_file fd.
4156: <p>
4157: The protocol is simple, just periodically scans routing table and export it
4158: to a file. It does not use the regular update mechanism, but a direct access
4159: in order to handle iteration through multiple routing tables. The table dump
4160: needs to dump all peers first and then use indexes to address the peers, we
4161: use a hash table (<param/peer_hash/) to find peer index based on BGP protocol key
4162: attributes.
4163: <p>
4164: One thing worth documenting is the locking. During processing, the currently
4165: processed table (<param/table/ field in the state structure) is locked and also the
4166: explicitly named table is locked (<param/table_ptr/ field in the state structure) if
4167: specified. Between dumps no table is locked. Also the current config is
4168: locked (by <func/config_add_obstacle()/) during table dumps as some data (strings,
4169: filters) are shared from the config and the running table dump may be
4170: interrupted by reconfiguration.
4171: <p>
4172: Supported standards:
4173: - RFC 6396 - MRT format standard
4174: - RFC 8050 - ADD_PATH extension
4175:
4176:
4177: <sect>Open Shortest Path First (OSPF)
4178: <p>
4179: <p>
4180: The OSPF protocol is quite complicated and its complex implemenation is split
4181: to many files. In <tt>ospf.c</tt>, you will find mainly the interface for
4182: communication with the core (e.g., reconfiguration hooks, shutdown and
4183: initialisation and so on). File <tt>iface.c</tt> contains the interface state
4184: machine and functions for allocation and deallocation of OSPF's interface
4185: data structures. Source <tt>neighbor.c</tt> includes the neighbor state machine and
4186: functions for election of Designated Router and Backup Designated router. In
4187: <tt>packet.c</tt>, you will find various functions for sending and receiving generic
4188: OSPF packets. There are also routines for authentication and checksumming.
4189: In <tt>hello.c</tt>, there are routines for sending and receiving of hello packets
4190: as well as functions for maintaining wait times and the inactivity timer.
4191: Files <tt>lsreq.c</tt>, <tt>lsack.c</tt>, <tt>dbdes.c</tt> contain functions for sending and
4192: receiving of link-state requests, link-state acknowledgements and database
4193: descriptions respectively. In <tt>lsupd.c</tt>, there are functions for sending and
4194: receiving of link-state updates and also the flooding algorithm. Source
4195: <tt>topology.c</tt> is a place where routines for searching LSAs in the link-state
4196: database, adding and deleting them reside, there also are functions for
4197: originating of various types of LSAs (router LSA, net LSA, external LSA).
4198: File <tt>rt.c</tt> contains routines for calculating the routing table. <tt>lsalib.c</tt>
4199: is a set of various functions for working with the LSAs (endianity
4200: conversions, calculation of checksum etc.).
4201: <p>
4202: One instance of the protocol is able to hold LSA databases for multiple OSPF
4203: areas, to exchange routing information between multiple neighbors and to
4204: calculate the routing tables. The core structure is <struct/ospf_proto/ to which
4205: multiple <struct/ospf_area/ and <struct/ospf_iface/ structures are connected. <struct/ospf_proto/ is
4206: also connected to <struct/top_hash_graph/ which is a dynamic hashing structure that
4207: describes the link-state database. It allows fast search, addition and
4208: deletion. Each LSA is kept in two pieces: header and body. Both of them are
4209: kept in the endianity of the CPU.
4210: <p>
4211: In OSPFv2 specification, it is implied that there is one IP prefix for each
4212: physical network/interface (unless it is an ptp link). But in modern systems,
4213: there might be more independent IP prefixes associated with an interface. To
4214: handle this situation, we have one <struct/ospf_iface/ for each active IP prefix
4215: (instead for each active iface); This behaves like virtual interface for the
4216: purpose of OSPF. If we receive packet, we associate it with a proper virtual
4217: interface mainly according to its source address.
4218: <p>
4219: OSPF keeps one socket per <struct/ospf_iface/. This allows us (compared to one socket
4220: approach) to evade problems with a limit of multicast groups per socket and
4221: with sending multicast packets to appropriate interface in a portable way.
4222: The socket is associated with underlying physical iface and should not
4223: receive packets received on other ifaces (unfortunately, this is not true on
4224: BSD). Generally, one packet can be received by more sockets (for example, if
4225: there are more <struct/ospf_iface/ on one physical iface), therefore we explicitly
4226: filter received packets according to src/dst IP address and received iface.
4227: <p>
4228: Vlinks are implemented using particularly degenerate form of <struct/ospf_iface/,
4229: which has several exceptions: it does not have its iface or socket (it copies
4230: these from 'parent' <struct/ospf_iface/) and it is present in iface list even when
4231: down (it is not freed in <func/ospf_iface_down()/).
4232: <p>
4233: The heart beat of ospf is <func/ospf_disp()/. It is called at regular intervals
4234: (<struct/ospf_proto/->tick). It is responsible for aging and flushing of LSAs in the
4235: database, updating topology information in LSAs and for routing table
4236: calculation.
4237: <p>
4238: To every <struct/ospf_iface/, we connect one or more <struct/ospf_neighbor/'s -- a structure
4239: containing many timers and queues for building adjacency and for exchange of
4240: routing messages.
4241: <p>
4242: BIRD's OSPF implementation respects RFC2328 in every detail, but some of
4243: internal algorithms do differ. The RFC recommends making a snapshot of the
4244: link-state database when a new adjacency is forming and sending the database
4245: description packets based on the information in this snapshot. The database
4246: can be quite large in some networks, so rather we walk through a <struct/slist/
4247: structure which allows us to continue even if the actual LSA we were working
4248: with is deleted. New LSAs are added at the tail of this <struct/slist/.
4249: <p>
4250: We also do not keep a separate OSPF routing table, because the core helps us
4251: by being able to recognize when a route is updated to an identical one and it
4252: suppresses the update automatically. Due to this, we can flush all the routes
4253: we have recalculated and also those we have deleted to the core's routing
4254: table and the core will take care of the rest. This simplifies the process
4255: and conserves memory.
4256: <p>
4257: Supported standards:
4258: - RFC 2328 - main OSPFv2 standard
4259: - RFC 5340 - main OSPFv3 standard
4260: - RFC 3101 - OSPFv2 NSSA areas
4261: - RFC 6549 - OSPFv2 multi-instance extensions
4262: - RFC 6987 - OSPF stub router advertisement
4263:
4264:
4265: <function><p><type>void</type>
4266: <funcdef>ospf_disp</funcdef>
4267: (<type>timer *</type> <param>timer</param>) -- invokes routing table calculation, aging and also <func/area_disp()/
4268:
4269: <funcsect>Arguments
4270: <p><descrip>
4271: <tagp><type>timer *</type> <param>timer</param></tagp>
4272: timer usually called every <param/ospf_proto/->tick second, <param/timer/->data
4273: point to <param/ospf_proto/
4274: </descrip>
4275: </function>
4276: <function><p><type>int</type>
4277: <funcdef>ospf_import_control</funcdef>
4278: (<type>struct proto *</type> <param>P</param>, <type>rte **</type> <param>new</param>, <type>ea_list **</type> <param>attrs</param>, <type>struct linpool *</type> <param>pool</param>) -- accept or reject new route from nest's routing table
4279:
4280: <funcsect>Arguments
4281: <p><descrip>
4282: <tagp><type>struct proto *</type> <param>P</param></tagp>
4283: OSPF protocol instance
4284: <tagp><type>rte **</type> <param>new</param></tagp>
4285: the new route
4286: <tagp><type>ea_list **</type> <param>attrs</param></tagp>
4287: list of attributes
4288: <tagp><type>struct linpool *</type> <param>pool</param></tagp>
4289: pool for allocation of attributes
4290: </descrip>
4291: <funcsect>Description
4292: <p>
4293: Its quite simple. It does not accept our own routes and leaves the decision on
4294: import to the filters.
4295: </function>
4296: <function><p><type>int</type>
4297: <funcdef>ospf_shutdown</funcdef>
4298: (<type>struct proto *</type> <param>P</param>) -- Finish of OSPF instance
4299:
4300: <funcsect>Arguments
4301: <p><descrip>
4302: <tagp><type>struct proto *</type> <param>P</param></tagp>
4303: OSPF protocol instance
4304: </descrip>
4305: <funcsect>Description
4306: <p>
4307: RFC does not define any action that should be taken before router
4308: shutdown. To make my neighbors react as fast as possible, I send
4309: them hello packet with empty neighbor list. They should start
4310: their neighbor state machine with event <const/NEIGHBOR_1WAY/.
4311: </function>
4312: <function><p><type>int</type>
4313: <funcdef>ospf_reconfigure</funcdef>
4314: (<type>struct proto *</type> <param>P</param>, <type>struct proto_config *</type> <param>c</param>) -- reconfiguration hook
4315:
4316: <funcsect>Arguments
4317: <p><descrip>
4318: <tagp><type>struct proto *</type> <param>P</param></tagp>
4319: current instance of protocol (with old configuration)
4320: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
4321: new configuration requested by user
4322: </descrip>
4323: <funcsect>Description
4324: <p>
4325: This hook tries to be a little bit intelligent. Instance of OSPF
4326: will survive change of many constants like hello interval,
4327: password change, addition or deletion of some neighbor on
4328: nonbroadcast network, cost of interface, etc.
4329: </function>
4330: <function><p><type>struct top_hash_entry *</type>
4331: <funcdef>ospf_install_lsa</funcdef>
4332: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_lsa_header *</type> <param>lsa</param>, <type>u32</type> <param>type</param>, <type>u32</type> <param>domain</param>, <type>void *</type> <param>body</param>) -- install new LSA into database
4333:
4334: <funcsect>Arguments
4335: <p><descrip>
4336: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
4337: OSPF protocol instance
4338: <tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp>
4339: LSA header
4340: <tagp><type>u32</type> <param>type</param></tagp>
4341: type of LSA
4342: <tagp><type>u32</type> <param>domain</param></tagp>
4343: domain of LSA
4344: <tagp><type>void *</type> <param>body</param></tagp>
4345: pointer to LSA body
4346: </descrip>
4347: <funcsect>Description
4348: <p>
4349: This function ensures installing new LSA received in LS update into LSA
4350: database. Old instance is replaced. Several actions are taken to detect if
4351: new routing table calculation is necessary. This is described in 13.2 of RFC
4352: 2328. This function is for received LSA only, locally originated LSAs are
4353: installed by <func/ospf_originate_lsa()/.
4354: <p>
4355: The LSA body in <param/body/ is expected to be mb_allocated by the caller and its
4356: ownership is transferred to the LSA entry structure.
4357: </function>
4358: <function><p><type>void</type>
4359: <funcdef>ospf_advance_lsa</funcdef>
4360: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct top_hash_entry *</type> <param>en</param>, <type>struct ospf_lsa_header *</type> <param>lsa</param>, <type>u32</type> <param>type</param>, <type>u32</type> <param>domain</param>, <type>void *</type> <param>body</param>) -- handle received unexpected self-originated LSA
4361:
4362: <funcsect>Arguments
4363: <p><descrip>
4364: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
4365: OSPF protocol instance
4366: <tagp><type>struct top_hash_entry *</type> <param>en</param></tagp>
4367: current LSA entry or NULL
4368: <tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp>
4369: new LSA header
4370: <tagp><type>u32</type> <param>type</param></tagp>
4371: type of LSA
4372: <tagp><type>u32</type> <param>domain</param></tagp>
4373: domain of LSA
4374: <tagp><type>void *</type> <param>body</param></tagp>
4375: pointer to LSA body
4376: </descrip>
4377: <funcsect>Description
4378: <p>
4379: This function handles received unexpected self-originated LSA (<param/lsa/, <param/body/)
4380: by either advancing sequence number of the local LSA instance (<param/en/) and
4381: propagating it, or installing the received LSA and immediately flushing it
4382: (if there is no local LSA; i.e., <param/en/ is NULL or MaxAge).
4383: <p>
4384: The LSA body in <param/body/ is expected to be mb_allocated by the caller and its
4385: ownership is transferred to the LSA entry structure or it is freed.
4386: </function>
4387: <function><p><type>struct top_hash_entry *</type>
4388: <funcdef>ospf_originate_lsa</funcdef>
4389: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_new_lsa *</type> <param>lsa</param>) -- originate new LSA
4390:
4391: <funcsect>Arguments
4392: <p><descrip>
4393: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
4394: OSPF protocol instance
4395: <tagp><type>struct ospf_new_lsa *</type> <param>lsa</param></tagp>
4396: New LSA specification
4397: </descrip>
4398: <funcsect>Description
4399: <p>
4400: This function prepares a new LSA, installs it into the LSA database and
4401: floods it. If the new LSA cannot be originated now (because the old instance
4402: was originated within MinLSInterval, or because the LSA seqnum is currently
4403: wrapping), the origination is instead scheduled for later. If the new LSA is
4404: equivalent to the current LSA, the origination is skipped. In all cases, the
4405: corresponding LSA entry is returned. The new LSA is based on the LSA
4406: specification (<param/lsa/) and the LSA body from lsab buffer of <param/p/, which is
4407: emptied after the call. The opposite of this function is <func/ospf_flush_lsa()/.
4408: </function>
4409: <function><p><type>void</type>
4410: <funcdef>ospf_flush_lsa</funcdef>
4411: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct top_hash_entry *</type> <param>en</param>) -- flush LSA from OSPF domain
4412:
4413: <funcsect>Arguments
4414: <p><descrip>
4415: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
4416: OSPF protocol instance
4417: <tagp><type>struct top_hash_entry *</type> <param>en</param></tagp>
4418: LSA entry to flush
4419: </descrip>
4420: <funcsect>Description
4421: <p>
4422: This function flushes <param/en/ from the OSPF domain by setting its age to
4423: <const/LSA_MAXAGE/ and flooding it. That also triggers subsequent events in LSA
4424: lifecycle leading to removal of the LSA from the LSA database (e.g. the LSA
4425: content is freed when flushing is acknowledged by neighbors). The function
4426: does nothing if the LSA is already being flushed. LSA entries are not
4427: immediately removed when being flushed, the caller may assume that <param/en/ still
4428: exists after the call. The function is the opposite of <func/ospf_originate_lsa()/
4429: and is supposed to do the right thing even in cases of postponed
4430: origination.
4431: </function>
4432: <function><p><type>void</type>
4433: <funcdef>ospf_update_lsadb</funcdef>
4434: (<type>struct ospf_proto *</type> <param>p</param>) -- update LSA database
4435:
4436: <funcsect>Arguments
4437: <p><descrip>
4438: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
4439: OSPF protocol instance
4440: </descrip>
4441: <funcsect>Description
4442: <p>
4443: This function is periodicaly invoked from <func/ospf_disp()/. It does some periodic
4444: or postponed processing related to LSA entries. It originates postponed LSAs
4445: scheduled by <func/ospf_originate_lsa()/, It continues in flushing processes started
4446: by <func/ospf_flush_lsa()/. It also periodically refreshs locally originated LSAs --
4447: when the current instance is older <const/LSREFRESHTIME/, a new instance is originated.
4448: Finally, it also ages stored LSAs and flushes ones that reached <const/LSA_MAXAGE/.
4449: <p>
4450: The RFC 2328 says that a router should periodically check checksums of all
4451: stored LSAs to detect hardware problems. This is not implemented.
4452: </function>
4453: <function><p><type>void</type>
4454: <funcdef>ospf_originate_ext_lsa</funcdef>
4455: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_area *</type> <param>oa</param>, <type>ort *</type> <param>nf</param>, <type>u8</type> <param>mode</param>, <type>u32</type> <param>metric</param>, <type>u32</type> <param>ebit</param>, <type>ip_addr</type> <param>fwaddr</param>, <type>u32</type> <param>tag</param>, <type>int</type> <param>pbit</param>) -- new route received from nest and filters
4456:
4457: <funcsect>Arguments
4458: <p><descrip>
4459: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
4460: OSPF protocol instance
4461: <tagp><type>struct ospf_area *</type> <param>oa</param></tagp>
4462: ospf_area for which LSA is originated
4463: <tagp><type>ort *</type> <param>nf</param></tagp>
4464: network prefix and mask
4465: <tagp><type>u8</type> <param>mode</param></tagp>
4466: the mode of the LSA (LSA_M_EXPORT or LSA_M_RTCALC)
4467: <tagp><type>u32</type> <param>metric</param></tagp>
4468: the metric of a route
4469: <tagp><type>u32</type> <param>ebit</param></tagp>
4470: E-bit for route metric (bool)
4471: <tagp><type>ip_addr</type> <param>fwaddr</param></tagp>
4472: the forwarding address
4473: <tagp><type>u32</type> <param>tag</param></tagp>
4474: the route tag
4475: <tagp><type>int</type> <param>pbit</param></tagp>
4476: P-bit for NSSA LSAs (bool), ignored for external LSAs
4477: </descrip>
4478: <funcsect>Description
4479: <p>
4480: If I receive a message that new route is installed, I try to originate an
4481: external LSA. If <param/oa/ is an NSSA area, NSSA-LSA is originated instead.
4482: <param/oa/ should not be a stub area. <param/src/ does not specify whether the LSA
4483: is external or NSSA, but it specifies the source of origination -
4484: the export from <func/ospf_rt_notify()/, or the NSSA-EXT translation.
4485: </function>
4486: <function><p><type>struct top_graph *</type>
4487: <funcdef>ospf_top_new</funcdef>
4488: (<type>struct ospf_proto *p UNUSED4</type> <param>UNUSED6</param>, <type>pool *</type> <param>pool</param>) -- allocated new topology database
4489:
4490: <funcsect>Arguments
4491: <p><descrip>
4492: <tagp><type>struct ospf_proto *p UNUSED4</type> <param>UNUSED6</param></tagp>
4493: -- undescribed --
4494: <tagp><type>pool *</type> <param>pool</param></tagp>
4495: pool for allocation
4496: </descrip>
4497: <funcsect>Description
4498: <p>
4499: This dynamically hashed structure is used for keeping LSAs. Mainly it is used
4500: for the LSA database of the OSPF protocol, but also for LSA retransmission
4501: and request lists of OSPF neighbors.
4502: </function>
4503: <function><p><type>void</type>
4504: <funcdef>ospf_neigh_chstate</funcdef>
4505: (<type>struct ospf_neighbor *</type> <param>n</param>, <type>u8</type> <param>state</param>) -- handles changes related to new or lod state of neighbor
4506:
4507: <funcsect>Arguments
4508: <p><descrip>
4509: <tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp>
4510: OSPF neighbor
4511: <tagp><type>u8</type> <param>state</param></tagp>
4512: new state
4513: </descrip>
4514: <funcsect>Description
4515: <p>
4516: Many actions have to be taken acording to a change of state of a neighbor. It
4517: starts rxmt timers, call interface state machine etc.
4518: </function>
4519: <function><p><type>void</type>
4520: <funcdef>ospf_neigh_sm</funcdef>
4521: (<type>struct ospf_neighbor *</type> <param>n</param>, <type>int</type> <param>event</param>) -- ospf neighbor state machine
4522:
4523: <funcsect>Arguments
4524: <p><descrip>
4525: <tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp>
4526: neighor
4527: <tagp><type>int</type> <param>event</param></tagp>
4528: actual event
4529: </descrip>
4530: <funcsect>Description
4531: <p>
4532: This part implements the neighbor state machine as described in 10.3 of
4533: RFC 2328. The only difference is that state <const/NEIGHBOR_ATTEMPT/ is not
4534: used. We discover neighbors on nonbroadcast networks in the
4535: same way as on broadcast networks. The only difference is in
4536: sending hello packets. These are sent to IPs listed in
4537: <param/ospf_iface/->nbma_list .
4538: </function>
4539: <function><p><type>void</type>
4540: <funcdef>ospf_dr_election</funcdef>
4541: (<type>struct ospf_iface *</type> <param>ifa</param>) -- (Backup) Designed Router election
4542:
4543: <funcsect>Arguments
4544: <p><descrip>
4545: <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
4546: actual interface
4547: </descrip>
4548: <funcsect>Description
4549: <p>
4550: When the wait timer fires, it is time to elect (Backup) Designated Router.
4551: Structure describing me is added to this list so every electing router has
4552: the same list. Backup Designated Router is elected before Designated
4553: Router. This process is described in 9.4 of RFC 2328. The function is
4554: supposed to be called only from <func/ospf_iface_sm()/ as a part of the interface
4555: state machine.
4556: </function>
4557: <function><p><type>void</type>
4558: <funcdef>ospf_iface_chstate</funcdef>
4559: (<type>struct ospf_iface *</type> <param>ifa</param>, <type>u8</type> <param>state</param>) -- handle changes of interface state
4560:
4561: <funcsect>Arguments
4562: <p><descrip>
4563: <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
4564: OSPF interface
4565: <tagp><type>u8</type> <param>state</param></tagp>
4566: new state
4567: </descrip>
4568: <funcsect>Description
4569: <p>
4570: Many actions must be taken according to interface state changes. New network
4571: LSAs must be originated, flushed, new multicast sockets to listen for messages for
4572: <const/ALLDROUTERS/ have to be opened, etc.
4573: </function>
4574: <function><p><type>void</type>
4575: <funcdef>ospf_iface_sm</funcdef>
4576: (<type>struct ospf_iface *</type> <param>ifa</param>, <type>int</type> <param>event</param>) -- OSPF interface state machine
4577:
4578: <funcsect>Arguments
4579: <p><descrip>
4580: <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
4581: OSPF interface
4582: <tagp><type>int</type> <param>event</param></tagp>
4583: event comming to state machine
4584: </descrip>
4585: <funcsect>Description
4586: <p>
4587: This fully respects 9.3 of RFC 2328 except we have slightly
4588: different handling of <const/DOWN/ and <const/LOOP/ state. We remove intefaces
4589: that are <const/DOWN/. <const/DOWN/ state is used when an interface is waiting
4590: for a lock. <const/LOOP/ state is used when an interface does not have a
4591: link.
4592: </function>
4593: <function><p><type>int</type>
4594: <funcdef>ospf_rx_hook</funcdef>
4595: (<type>sock *</type> <param>sk</param>, <type>uint</type> <param>len</param>)
4596: <funcsect>Arguments
4597: <p><descrip>
4598: <tagp><type>sock *</type> <param>sk</param></tagp>
4599: socket we received the packet.
4600: <tagp><type>uint</type> <param>len</param></tagp>
4601: size of the packet
4602: </descrip>
4603: <funcsect>Description
4604: <p>
4605: This is the entry point for messages from neighbors. Many checks (like
4606: authentication, checksums, size) are done before the packet is passed to
4607: non generic functions.
4608: </function>
4609: <function><p><type>int</type>
4610: <funcdef>lsa_validate</funcdef>
4611: (<type>struct ospf_lsa_header *</type> <param>lsa</param>, <type>u32</type> <param>lsa_type</param>, <type>int</type> <param>ospf2</param>, <type>void *</type> <param>body</param>) -- check whether given LSA is valid
4612:
4613: <funcsect>Arguments
4614: <p><descrip>
4615: <tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp>
4616: LSA header
4617: <tagp><type>u32</type> <param>lsa_type</param></tagp>
4618: one of <const/LSA_T_xxx/
4619: <tagp><type>int</type> <param>ospf2</param></tagp>
4620: <const/true/ means OSPF version 2, <const/false/ means OSPF version 3
4621: <tagp><type>void *</type> <param>body</param></tagp>
4622: pointer to LSA body
4623: </descrip>
4624: <funcsect>Description
4625: <p>
4626: Checks internal structure of given LSA body (minimal length,
4627: consistency). Returns true if valid.
4628: </function>
4629: <function><p><type>void</type>
4630: <funcdef>ospf_send_dbdes</funcdef>
4631: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_neighbor *</type> <param>n</param>) -- transmit database description packet
4632:
4633: <funcsect>Arguments
4634: <p><descrip>
4635: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
4636: OSPF protocol instance
4637: <tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp>
4638: neighbor
4639: </descrip>
4640: <funcsect>Description
4641: <p>
4642: Sending of a database description packet is described in 10.8 of RFC 2328.
4643: Reception of each packet is acknowledged in the sequence number of another.
4644: When I send a packet to a neighbor I keep a copy in a buffer. If the neighbor
4645: does not reply, I don't create a new packet but just send the content
4646: of the buffer.
4647: </function>
4648: <function><p><type>void</type>
4649: <funcdef>ospf_rt_spf</funcdef>
4650: (<type>struct ospf_proto *</type> <param>p</param>) -- calculate internal routes
4651:
4652: <funcsect>Arguments
4653: <p><descrip>
4654: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
4655: OSPF protocol instance
4656: </descrip>
4657: <funcsect>Description
4658: <p>
4659: Calculation of internal paths in an area is described in 16.1 of RFC 2328.
4660: It's based on Dijkstra's shortest path tree algorithms.
4661: This function is invoked from <func/ospf_disp()/.
4662: </function>
4663: <sect>Pipe
4664: <p>
4665: <p>
4666: The Pipe protocol is very simple. It just connects to two routing tables
4667: using <func/proto_add_announce_hook()/ and whenever it receives a <func/rt_notify()/
4668: about a change in one of the tables, it converts it to a <func/rte_update()/
4669: in the other one.
4670: <p>
4671: To avoid pipe loops, Pipe keeps a `being updated' flag in each routing
4672: table.
4673: <p>
4674: A pipe has two announce hooks, the first connected to the main
4675: table, the second connected to the peer table. When a new route is
4676: announced on the main table, it gets checked by an export filter in
4677: ahook 1, and, after that, it is announced to the peer table via
4678: <func/rte_update()/, an import filter in ahook 2 is called. When a new
4679: route is announced in the peer table, an export filter in ahook2
4680: and an import filter in ahook 1 are used. Oviously, there is no
4681: need in filtering the same route twice, so both import filters are
4682: set to accept, while user configured 'import' and 'export' filters
4683: are used as export filters in ahooks 2 and 1. Route limits are
4684: handled similarly, but on the import side of ahooks.
4685:
4686:
4687: <sect>Routing Information Protocol (RIP)
4688: <p>
4689: <p>
4690: The RIP protocol is implemented in two files: <tt>rip.c</tt> containing the protocol
4691: logic, route management and the protocol glue with BIRD core, and <tt>packets.c</tt>
4692: handling RIP packet processing, RX, TX and protocol sockets.
4693: <p>
4694: Each instance of RIP is described by a structure <struct/rip_proto/, which contains
4695: an internal RIP routing table, a list of protocol interfaces and the main
4696: timer responsible for RIP routing table cleanup.
4697: <p>
4698: RIP internal routing table contains incoming and outgoing routes. For each
4699: network (represented by structure <struct/rip_entry/) there is one outgoing route
4700: stored directly in <struct/rip_entry/ and an one-way linked list of incoming routes
4701: (structures <struct/rip_rte/). The list contains incoming routes from different RIP
4702: neighbors, but only routes with the lowest metric are stored (i.e., all
4703: stored incoming routes have the same metric).
4704: <p>
4705: Note that RIP itself does not select outgoing route, that is done by the core
4706: routing table. When a new incoming route is received, it is propagated to the
4707: RIP table by <func/rip_update_rte()/ and possibly stored in the list of incoming
4708: routes. Then the change may be propagated to the core by <func/rip_announce_rte()/.
4709: The core selects the best route and propagate it to RIP by <func/rip_rt_notify()/,
4710: which updates outgoing route part of <struct/rip_entry/ and possibly triggers route
4711: propagation by <func/rip_trigger_update()/.
4712: <p>
4713: RIP interfaces are represented by structures <struct/rip_iface/. A RIP interface
4714: contains a per-interface socket, a list of associated neighbors, interface
4715: configuration, and state information related to scheduled interface events
4716: and running update sessions. RIP interfaces are added and removed based on
4717: core interface notifications.
4718: <p>
4719: There are two RIP interface events - regular updates and triggered updates.
4720: Both are managed from the RIP interface timer (<func/rip_iface_timer()/). Regular
4721: updates are called at fixed interval and propagate the whole routing table,
4722: while triggered updates are scheduled by <func/rip_trigger_update()/ due to some
4723: routing table change and propagate only the routes modified since the time
4724: they were scheduled. There are also unicast-destined requested updates, but
4725: these are sent directly as a reaction to received RIP request message. The
4726: update session is started by <func/rip_send_table()/. There may be at most one
4727: active update session per interface, as the associated state (including the
4728: fib iterator) is stored directly in <struct/rip_iface/ structure.
4729: <p>
4730: RIP neighbors are represented by structures <struct/rip_neighbor/. Compared to
4731: neighbor handling in other routing protocols, RIP does not have explicit
4732: neighbor discovery and adjacency maintenance, which makes the <struct/rip_neighbor/
4733: related code a bit peculiar. RIP neighbors are interlinked with core neighbor
4734: structures (<struct/neighbor/) and use core neighbor notifications to ensure that RIP
4735: neighbors are timely removed. RIP neighbors are added based on received route
4736: notifications and removed based on core neighbor and RIP interface events.
4737: <p>
4738: RIP neighbors are linked by RIP routes and use counter to track the number of
4739: associated routes, but when these RIP routes timeout, associated RIP neighbor
4740: is still alive (with zero counter). When RIP neighbor is removed but still
4741: has some associated routes, it is not freed, just changed to detached state
4742: (core neighbors and RIP ifaces are unlinked), then during the main timer
4743: cleanup phase the associated routes are removed and the <struct/rip_neighbor/
4744: structure is finally freed.
4745: <p>
4746: Supported standards:
4747: - RFC 1058 - RIPv1
4748: - RFC 2453 - RIPv2
4749: - RFC 2080 - RIPng
4750: - RFC 4822 - RIP cryptographic authentication
4751:
4752:
4753: <function><p><type>void</type>
4754: <funcdef>rip_announce_rte</funcdef>
4755: (<type>struct rip_proto *</type> <param>p</param>, <type>struct rip_entry *</type> <param>en</param>) -- announce route from RIP routing table to the core
4756:
4757: <funcsect>Arguments
4758: <p><descrip>
4759: <tagp><type>struct rip_proto *</type> <param>p</param></tagp>
4760: RIP instance
4761: <tagp><type>struct rip_entry *</type> <param>en</param></tagp>
4762: related network
4763: </descrip>
4764: <funcsect>Description
4765: <p>
4766: The function takes a list of incoming routes from <param/en/, prepare appropriate
4767: <struct/rte/ for the core and propagate it by <func/rte_update()/.
4768: </function>
4769: <function><p><type>void</type>
4770: <funcdef>rip_update_rte</funcdef>
4771: (<type>struct rip_proto *</type> <param>p</param>, <type>ip_addr *</type> <param>prefix</param>, <type>int</type> <param>pxlen</param>, <type>struct rip_rte *</type> <param>new</param>) -- enter a route update to RIP routing table
4772:
4773: <funcsect>Arguments
4774: <p><descrip>
4775: <tagp><type>struct rip_proto *</type> <param>p</param></tagp>
4776: RIP instance
4777: <tagp><type>ip_addr *</type> <param>prefix</param></tagp>
4778: network prefix
4779: <tagp><type>int</type> <param>pxlen</param></tagp>
4780: network prefix length
4781: <tagp><type>struct rip_rte *</type> <param>new</param></tagp>
4782: a <struct/rip_rte/ representing the new route
4783: </descrip>
4784: <funcsect>Description
4785: <p>
4786: The function is called by the RIP packet processing code whenever it receives
4787: a reachable route. The appropriate routing table entry is found and the list
4788: of incoming routes is updated. Eventually, the change is also propagated to
4789: the core by <func/rip_announce_rte()/. Note that for unreachable routes,
4790: <func/rip_withdraw_rte()/ should be called instead of <func/rip_update_rte()/.
4791: </function>
4792: <function><p><type>void</type>
4793: <funcdef>rip_withdraw_rte</funcdef>
4794: (<type>struct rip_proto *</type> <param>p</param>, <type>ip_addr *</type> <param>prefix</param>, <type>int</type> <param>pxlen</param>, <type>struct rip_neighbor *</type> <param>from</param>) -- enter a route withdraw to RIP routing table
4795:
4796: <funcsect>Arguments
4797: <p><descrip>
4798: <tagp><type>struct rip_proto *</type> <param>p</param></tagp>
4799: RIP instance
4800: <tagp><type>ip_addr *</type> <param>prefix</param></tagp>
4801: network prefix
4802: <tagp><type>int</type> <param>pxlen</param></tagp>
4803: network prefix length
4804: <tagp><type>struct rip_neighbor *</type> <param>from</param></tagp>
4805: a <struct/rip_neighbor/ propagating the withdraw
4806: </descrip>
4807: <funcsect>Description
4808: <p>
4809: The function is called by the RIP packet processing code whenever it receives
4810: an unreachable route. The incoming route for given network from nbr <param/from/ is
4811: removed. Eventually, the change is also propagated by <func/rip_announce_rte()/.
4812: </function>
4813: <function><p><type>void</type>
4814: <funcdef>rip_timer</funcdef>
4815: (<type>timer *</type> <param>t</param>) -- RIP main timer hook
4816:
4817: <funcsect>Arguments
4818: <p><descrip>
4819: <tagp><type>timer *</type> <param>t</param></tagp>
4820: timer
4821: </descrip>
4822: <funcsect>Description
4823: <p>
4824: The RIP main timer is responsible for routing table maintenance. Invalid or
4825: expired routes (<struct/rip_rte/) are removed and garbage collection of stale routing
4826: table entries (<struct/rip_entry/) is done. Changes are propagated to core tables,
4827: route reload is also done here. Note that garbage collection uses a maximal
4828: GC time, while interfaces maintain an illusion of per-interface GC times in
4829: <func/rip_send_response()/.
4830: <p>
4831: Keeping incoming routes and the selected outgoing route are two independent
4832: functions, therefore after garbage collection some entries now considered
4833: invalid (RIP_ENTRY_DUMMY) still may have non-empty list of incoming routes,
4834: while some valid entries (representing an outgoing route) may have that list
4835: empty.
4836: <p>
4837: The main timer is not scheduled periodically but it uses the time of the
4838: current next event and the minimal interval of any possible event to compute
4839: the time of the next run.
4840: </function>
4841: <function><p><type>void</type>
4842: <funcdef>rip_iface_timer</funcdef>
4843: (<type>timer *</type> <param>t</param>) -- RIP interface timer hook
4844:
4845: <funcsect>Arguments
4846: <p><descrip>
4847: <tagp><type>timer *</type> <param>t</param></tagp>
4848: timer
4849: </descrip>
4850: <funcsect>Description
4851: <p>
4852: RIP interface timers are responsible for scheduling both regular and
4853: triggered updates. Fixed, delay-independent period is used for regular
4854: updates, while minimal separating interval is enforced for triggered updates.
4855: The function also ensures that a new update is not started when the old one
4856: is still running.
4857: </function>
4858: <function><p><type>void</type>
4859: <funcdef>rip_send_table</funcdef>
4860: (<type>struct rip_proto *</type> <param>p</param>, <type>struct rip_iface *</type> <param>ifa</param>, <type>ip_addr</type> <param>addr</param>, <type>bird_clock_t</type> <param>changed</param>) -- RIP interface timer hook
4861:
4862: <funcsect>Arguments
4863: <p><descrip>
4864: <tagp><type>struct rip_proto *</type> <param>p</param></tagp>
4865: RIP instance
4866: <tagp><type>struct rip_iface *</type> <param>ifa</param></tagp>
4867: RIP interface
4868: <tagp><type>ip_addr</type> <param>addr</param></tagp>
4869: destination IP address
4870: <tagp><type>bird_clock_t</type> <param>changed</param></tagp>
4871: time limit for triggered updates
4872: </descrip>
4873: <funcsect>Description
4874: <p>
4875: The function activates an update session and starts sending routing update
4876: packets (using <func/rip_send_response()/). The session may be finished during the
4877: call or may continue in <func/rip_tx_hook()/ until all appropriate routes are
4878: transmitted. Note that there may be at most one active update session per
4879: interface, the function will terminate the old active session before
4880: activating the new one.
4881: </function>
4882: <sect>Router Advertisements
4883: <p>
4884: <p>
4885: The RAdv protocol is implemented in two files: <tt>radv.c</tt> containing the
4886: interface with BIRD core and the protocol logic and <tt>packets.c</tt> handling low
4887: level protocol stuff (RX, TX and packet formats). The protocol does not
4888: export any routes.
4889: <p>
4890: The RAdv is structured in the usual way - for each handled interface there is
4891: a structure <struct/radv_iface/ that contains a state related to that interface
4892: together with its resources (a socket, a timer). There is also a prepared RA
4893: stored in a TX buffer of the socket associated with an iface. These iface
4894: structures are created and removed according to iface events from BIRD core
4895: handled by <func/radv_if_notify()/ callback.
4896: <p>
4897: The main logic of RAdv consists of two functions: <func/radv_iface_notify()/, which
4898: processes asynchronous events (specified by RA_EV_* codes), and <func/radv_timer()/,
4899: which triggers sending RAs and computes the next timeout.
4900: <p>
4901: The RAdv protocol could receive routes (through <func/radv_import_control()/ and
4902: <func/radv_rt_notify()/), but only the configured trigger route is tracked (in
4903: <struct/active/ var). When a radv protocol is reconfigured, the connected routing
4904: table is examined (in <func/radv_check_active()/) to have proper <struct/active/ value in
4905: case of the specified trigger prefix was changed.
4906: <p>
4907: Supported standards:
4908: - RFC 4861 - main RA standard
4909: - RFC 4191 - Default Router Preferences and More-Specific Routes
4910: - RFC 6106 - DNS extensions (RDDNS, DNSSL)
4911:
4912:
4913: <sect>Static
4914: <p>
4915: <p>
4916: The Static protocol is implemented in a straightforward way. It keeps
4917: two lists of static routes: one containing interface routes and one
4918: holding the remaining ones. Interface routes are inserted and removed according
4919: to interface events received from the core via the <func/if_notify()/ hook. Routes
4920: pointing to a neighboring router use a sticky node in the neighbor cache
4921: to be notified about gaining or losing the neighbor. Special
4922: routes like black holes or rejects are inserted all the time.
4923: <p>
4924: Multipath routes are tricky. Because these routes depends on
4925: several neighbors we need to integrate that to the neighbor
4926: notification handling, we use dummy static_route nodes, one for
4927: each nexthop. Therefore, a multipath route consists of a master
4928: static_route node (of dest RTD_MULTIPATH), which specifies prefix
4929: and is used in most circumstances, and a list of dummy static_route
4930: nodes (of dest RTD_NONE), which stores info about nexthops and are
4931: connected to neighbor entries and neighbor notifications. Dummy
4932: nodes are chained using mp_next, they aren't in other_routes list,
4933: and abuse some fields (masklen, if_name) for other purposes.
4934: <p>
4935: The only other thing worth mentioning is that when asked for reconfiguration,
4936: Static not only compares the two configurations, but it also calculates
4937: difference between the lists of static routes and it just inserts the
4938: newly added routes and removes the obsolete ones.
4939:
4940:
4941: <sect>Direct
4942: <p>
4943: <p>
4944: The Direct protocol works by converting all <func/ifa_notify()/ events it receives
4945: to <func/rte_update()/ calls for the corresponding network.
4946:
4947:
4948: <!--
4949: BIRD Programmer's Guide: Sysdeps
4950:
4951: (c) 2000 Martin Mares <mj@ucw.cz>
4952: -->
4953:
4954: <chapt>System dependent parts
4955:
4956: <sect>Introduction
4957:
4958: <p>We've tried to make BIRD as portable as possible, but unfortunately
4959: communication with the network stack differs from one OS to another,
4960: so we need at least some OS specific code. The good news is that this
4961: code is isolated in a small set of modules:
4962:
4963: <descrip>
4964: <tagp><tt/config.h/</tagp> is a header file with configuration information,
4965: definition of the standard set of types and so on.
4966: <tagp/Startup module/ controls BIRD startup. Common for a family of OS's (e.g.,
4967: for all Unices).
4968: <tagp/Logging module/ manages the system logs. [per OS family]
4969: <tagp/IO module/ gives an implementation of sockets, timers and the
4970: global event queue. [per OS family]
4971: <tagp/KRT module/ implements the Kernel and Device protocols. This
4972: is the most arcane part of the system dependent stuff and some
4973: functions differ even between various releases of a single OS.
4974: </descrip>
4975: <sect>Logging
4976: <p>
4977: <p>
4978: The Logging module offers a simple set of functions for writing
4979: messages to system logs and to the debug output. Message classes
4980: used by this module are described in <tt>birdlib.h</tt> and also in the
4981: user's manual.
4982:
4983:
4984: <function><p><type>void</type>
4985: <funcdef>log_commit</funcdef>
4986: (<type>int</type> <param>class</param>, <type>buffer *</type> <param>buf</param>) -- commit a log message
4987:
4988: <funcsect>Arguments
4989: <p><descrip>
4990: <tagp><type>int</type> <param>class</param></tagp>
4991: message class information (<const/L_DEBUG/ to <const/L_BUG/, see <tt>lib/birdlib.h</tt>)
4992: <tagp><type>buffer *</type> <param>buf</param></tagp>
4993: message to write
4994: </descrip>
4995: <funcsect>Description
4996: <p>
4997: This function writes a message prepared in the log buffer to the
4998: log file (as specified in the configuration). The log buffer is
4999: reset after that. The log message is a full line, <func/log_commit()/
5000: terminates it.
5001: <p>
5002: The message class is an integer, not a first char of a string like
5003: in <func/log()/, so it should be written like *L_INFO.
5004: </function>
5005: <function><p><type>void</type>
5006: <funcdef>log_msg</funcdef>
5007: (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- log a message
5008:
5009: <funcsect>Arguments
5010: <p><descrip>
5011: <tagp><type>const char *</type> <param>msg</param></tagp>
5012: printf-like formatting string with message class information
5013: prepended (<const/L_DEBUG/ to <const/L_BUG/, see <tt>lib/birdlib.h</tt>)
5014: <tagp><type>...</type> <param>...</param></tagp>
5015: variable arguments
5016: </descrip>
5017: <funcsect>Description
5018: <p>
5019: This function formats a message according to the format string <param/msg/
5020: and writes it to the corresponding log file (as specified in the
5021: configuration). Please note that the message is automatically
5022: formatted as a full line, no need to include <tt>\n</tt> inside.
5023: It is essentially a sequence of <func/log_reset()/, <func/logn()/ and <func/log_commit()/.
5024: </function>
5025: <function><p><type>void</type>
5026: <funcdef>bug</funcdef>
5027: (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report an internal error
5028:
5029: <funcsect>Arguments
5030: <p><descrip>
5031: <tagp><type>const char *</type> <param>msg</param></tagp>
5032: a printf-like error message
5033: <tagp><type>...</type> <param>...</param></tagp>
5034: variable arguments
5035: </descrip>
5036: <funcsect>Description
5037: <p>
5038: This function logs an internal error and aborts execution
5039: of the program.
5040: </function>
5041: <function><p><type>void</type>
5042: <funcdef>die</funcdef>
5043: (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report a fatal error
5044:
5045: <funcsect>Arguments
5046: <p><descrip>
5047: <tagp><type>const char *</type> <param>msg</param></tagp>
5048: a printf-like error message
5049: <tagp><type>...</type> <param>...</param></tagp>
5050: variable arguments
5051: </descrip>
5052: <funcsect>Description
5053: <p>
5054: This function logs a fatal error and aborts execution
5055: of the program.
5056: </function>
5057: <function><p><type>void</type>
5058: <funcdef>debug</funcdef>
5059: (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- write to debug output
5060:
5061: <funcsect>Arguments
5062: <p><descrip>
5063: <tagp><type>const char *</type> <param>msg</param></tagp>
5064: a printf-like message
5065: <tagp><type>...</type> <param>...</param></tagp>
5066: variable arguments
5067: </descrip>
5068: <funcsect>Description
5069: <p>
5070: This function formats the message <param/msg/ and prints it out
5071: to the debugging output. No newline character is appended.
5072: </function>
5073: <sect>Kernel synchronization
5074: <p>
5075: <p>
5076: This system dependent module implements the Kernel and Device protocol,
5077: that is synchronization of interface lists and routing tables with the
5078: OS kernel.
5079: <p>
5080: The whole kernel synchronization is a bit messy and touches some internals
5081: of the routing table engine, because routing table maintenance is a typical
5082: example of the proverbial compatibility between different Unices and we want
5083: to keep the overhead of our KRT business as low as possible and avoid maintaining
5084: a local routing table copy.
5085: <p>
5086: The kernel syncer can work in three different modes (according to system config header):
5087: Either with a single routing table and single KRT protocol [traditional UNIX]
5088: or with many routing tables and separate KRT protocols for all of them
5089: or with many routing tables, but every scan including all tables, so we start
5090: separate KRT protocols which cooperate with each other [Linux].
5091: In this case, we keep only a single scan timer.
5092: <p>
5093: We use FIB node flags in the routing table to keep track of route
5094: synchronization status. We also attach temporary <struct/rte/'s to the routing table,
5095: but it cannot do any harm to the rest of BIRD since table synchronization is
5096: an atomic process.
5097: <p>
5098: When starting up, we cheat by looking if there is another
5099: KRT instance to be initialized later and performing table scan
5100: only once for all the instances.
5101: <p>
5102: The code uses OS-dependent parts for kernel updates and scans. These parts are
5103: in more specific sysdep directories (e.g. sysdep/linux) in functions krt_sys_*
5104: and kif_sys_* (and some others like <func/krt_replace_rte()/) and krt-sys.h header file.
5105: This is also used for platform specific protocol options and route attributes.
5106: <p>
5107: There was also an old code that used traditional UNIX ioctls for these tasks.
5108: It was unmaintained and later removed. For reference, see sysdep/krt-* files
5109: in commit 396dfa9042305f62da1f56589c4b98fac57fc2f6
5110:
5111:
5112: <chapt>Library functions
5113: <sect>IP addresses
5114: <p>
5115: <p>
5116: BIRD uses its own abstraction of IP address in order to share the same
5117: code for both IPv4 and IPv6. IP addresses are represented as entities
5118: of type <struct/ip_addr/ which are never to be treated as numbers and instead
5119: they must be manipulated using the following functions and macros.
5120:
5121:
5122: <function><p><type>char *</type>
5123: <funcdef>ip_scope_text</funcdef>
5124: (<type>uint</type> <param>scope</param>) -- get textual representation of address scope
5125:
5126: <funcsect>Arguments
5127: <p><descrip>
5128: <tagp><type>uint</type> <param>scope</param></tagp>
5129: scope (<const/SCOPE_xxx/)
5130: </descrip>
5131: <funcsect>Description
5132: <p>
5133: Returns a pointer to a textual name of the scope given.
5134: </function>
5135: <function><p><type>int</type>
5136: <funcdef>ipa_equal</funcdef>
5137: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compare two IP addresses for equality
5138:
5139: <funcsect>Arguments
5140: <p><descrip>
5141: <tagp><type>ip_addr</type> <param>x</param></tagp>
5142: IP address
5143: <tagp><type>ip_addr</type> <param>y</param></tagp>
5144: IP address
5145: </descrip>
5146: <funcsect>Description
5147: <p>
5148: <func/ipa_equal()/ returns 1 if <param/x/ and <param/y/ represent the same IP address, else 0.
5149: </function>
5150: <function><p><type>int</type>
5151: <funcdef>ipa_nonzero</funcdef>
5152: (<type>ip_addr</type> <param>x</param>) -- test if an IP address is defined
5153:
5154: <funcsect>Arguments
5155: <p><descrip>
5156: <tagp><type>ip_addr</type> <param>x</param></tagp>
5157: IP address
5158: </descrip>
5159: <funcsect>Description
5160: <p>
5161: ipa_nonzero returns 1 if <param/x/ is a defined IP address (not all bits are zero),
5162: else 0.
5163: <p>
5164: The undefined all-zero address is reachable as a <tt>IPA_NONE</tt> macro.
5165: </function>
5166: <function><p><type>ip_addr</type>
5167: <funcdef>ipa_and</funcdef>
5168: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compute bitwise and of two IP addresses
5169:
5170: <funcsect>Arguments
5171: <p><descrip>
5172: <tagp><type>ip_addr</type> <param>x</param></tagp>
5173: IP address
5174: <tagp><type>ip_addr</type> <param>y</param></tagp>
5175: IP address
5176: </descrip>
5177: <funcsect>Description
5178: <p>
5179: This function returns a bitwise and of <param/x/ and <param/y/. It's primarily
5180: used for network masking.
5181: </function>
5182: <function><p><type>ip_addr</type>
5183: <funcdef>ipa_or</funcdef>
5184: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compute bitwise or of two IP addresses
5185:
5186: <funcsect>Arguments
5187: <p><descrip>
5188: <tagp><type>ip_addr</type> <param>x</param></tagp>
5189: IP address
5190: <tagp><type>ip_addr</type> <param>y</param></tagp>
5191: IP address
5192: </descrip>
5193: <funcsect>Description
5194: <p>
5195: This function returns a bitwise or of <param/x/ and <param/y/.
5196: </function>
5197: <function><p><type>ip_addr</type>
5198: <funcdef>ipa_xor</funcdef>
5199: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compute bitwise xor of two IP addresses
5200:
5201: <funcsect>Arguments
5202: <p><descrip>
5203: <tagp><type>ip_addr</type> <param>x</param></tagp>
5204: IP address
5205: <tagp><type>ip_addr</type> <param>y</param></tagp>
5206: IP address
5207: </descrip>
5208: <funcsect>Description
5209: <p>
5210: This function returns a bitwise xor of <param/x/ and <param/y/.
5211: </function>
5212: <function><p><type>ip_addr</type>
5213: <funcdef>ipa_not</funcdef>
5214: (<type>ip_addr</type> <param>x</param>) -- compute bitwise negation of two IP addresses
5215:
5216: <funcsect>Arguments
5217: <p><descrip>
5218: <tagp><type>ip_addr</type> <param>x</param></tagp>
5219: IP address
5220: </descrip>
5221: <funcsect>Description
5222: <p>
5223: This function returns a bitwise negation of <param/x/.
5224: </function>
5225: <function><p><type>ip_addr</type>
5226: <funcdef>ipa_mkmask</funcdef>
5227: (<type>int</type> <param>x</param>) -- create a netmask
5228:
5229: <funcsect>Arguments
5230: <p><descrip>
5231: <tagp><type>int</type> <param>x</param></tagp>
5232: prefix length
5233: </descrip>
5234: <funcsect>Description
5235: <p>
5236: This function returns an <struct/ip_addr/ corresponding of a netmask
5237: of an address prefix of size <param/x/.
5238: </function>
5239: <function><p><type>int</type>
5240: <funcdef>ipa_masklen</funcdef>
5241: (<type>ip_addr</type> <param>x</param>) -- calculate netmask length
5242:
5243: <funcsect>Arguments
5244: <p><descrip>
5245: <tagp><type>ip_addr</type> <param>x</param></tagp>
5246: IP address
5247: </descrip>
5248: <funcsect>Description
5249: <p>
5250: This function checks whether <param/x/ represents a valid netmask and
5251: returns the size of the associate network prefix or -1 for invalid
5252: mask.
5253: </function>
5254: <function><p><type>int</type>
5255: <funcdef>ipa_hash</funcdef>
5256: (<type>ip_addr</type> <param>x</param>) -- hash IP addresses
5257:
5258: <funcsect>Arguments
5259: <p><descrip>
5260: <tagp><type>ip_addr</type> <param>x</param></tagp>
5261: IP address
5262: </descrip>
5263: <funcsect>Description
5264: <p>
5265: <func/ipa_hash()/ returns a 16-bit hash value of the IP address <param/x/.
5266: </function>
5267: <function><p><type>void</type>
5268: <funcdef>ipa_hton</funcdef>
5269: (<type>ip_addr</type> <param>x</param>) -- convert IP address to network order
5270:
5271: <funcsect>Arguments
5272: <p><descrip>
5273: <tagp><type>ip_addr</type> <param>x</param></tagp>
5274: IP address
5275: </descrip>
5276: <funcsect>Description
5277: <p>
5278: Converts the IP address <param/x/ to the network byte order.
5279: <p>
5280: Beware, this is a macro and it alters the argument!
5281: </function>
5282: <function><p><type>void</type>
5283: <funcdef>ipa_ntoh</funcdef>
5284: (<type>ip_addr</type> <param>x</param>) -- convert IP address to host order
5285:
5286: <funcsect>Arguments
5287: <p><descrip>
5288: <tagp><type>ip_addr</type> <param>x</param></tagp>
5289: IP address
5290: </descrip>
5291: <funcsect>Description
5292: <p>
5293: Converts the IP address <param/x/ from the network byte order.
5294: <p>
5295: Beware, this is a macro and it alters the argument!
5296: </function>
5297: <function><p><type>int</type>
5298: <funcdef>ipa_classify</funcdef>
5299: (<type>ip_addr</type> <param>x</param>) -- classify an IP address
5300:
5301: <funcsect>Arguments
5302: <p><descrip>
5303: <tagp><type>ip_addr</type> <param>x</param></tagp>
5304: IP address
5305: </descrip>
5306: <funcsect>Description
5307: <p>
5308: <func/ipa_classify()/ returns an address class of <param/x/, that is a bitwise or
5309: of address type (<const/IADDR_INVALID/, <const/IADDR_HOST/, <const/IADDR_BROADCAST/, <const/IADDR_MULTICAST/)
5310: with address scope (<const/SCOPE_HOST/ to <const/SCOPE_UNIVERSE/) or -1 (<const/IADDR_INVALID/)
5311: for an invalid address.
5312: </function>
5313: <function><p><type>ip4_addr</type>
5314: <funcdef>ip4_class_mask</funcdef>
5315: (<type>ip4_addr</type> <param>x</param>) -- guess netmask according to address class
5316:
5317: <funcsect>Arguments
5318: <p><descrip>
5319: <tagp><type>ip4_addr</type> <param>x</param></tagp>
5320: IPv4 address
5321: </descrip>
5322: <funcsect>Description
5323: <p>
5324: This function (available in IPv4 version only) returns a
5325: network mask according to the address class of <param/x/. Although
5326: classful addressing is nowadays obsolete, there still live
5327: routing protocols transferring no prefix lengths nor netmasks
5328: and this function could be useful to them.
5329: </function>
5330: <function><p><type>u32</type>
5331: <funcdef>ipa_from_u32</funcdef>
5332: (<type>ip_addr</type> <param>x</param>) -- convert IPv4 address to an integer
5333:
5334: <funcsect>Arguments
5335: <p><descrip>
5336: <tagp><type>ip_addr</type> <param>x</param></tagp>
5337: IP address
5338: </descrip>
5339: <funcsect>Description
5340: <p>
5341: This function takes an IPv4 address and returns its numeric
5342: representation.
5343: </function>
5344: <function><p><type>ip_addr</type>
5345: <funcdef>ipa_to_u32</funcdef>
5346: (<type>u32</type> <param>x</param>) -- convert integer to IPv4 address
5347:
5348: <funcsect>Arguments
5349: <p><descrip>
5350: <tagp><type>u32</type> <param>x</param></tagp>
5351: a 32-bit integer
5352: </descrip>
5353: <funcsect>Description
5354: <p>
5355: <func/ipa_to_u32()/ takes a numeric representation of an IPv4 address
5356: and converts it to the corresponding <struct/ip_addr/.
5357: </function>
5358: <function><p><type>int</type>
5359: <funcdef>ipa_compare</funcdef>
5360: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compare two IP addresses for order
5361:
5362: <funcsect>Arguments
5363: <p><descrip>
5364: <tagp><type>ip_addr</type> <param>x</param></tagp>
5365: IP address
5366: <tagp><type>ip_addr</type> <param>y</param></tagp>
5367: IP address
5368: </descrip>
5369: <funcsect>Description
5370: <p>
5371: The <func/ipa_compare()/ function takes two IP addresses and returns
5372: -1 if <param/x/ is less than <param/y/ in canonical ordering (lexicographical
5373: order of the bit strings), 1 if <param/x/ is greater than <param/y/ and 0
5374: if they are the same.
5375: </function>
5376: <function><p><type>ip_addr</type>
5377: <funcdef>ipa_build6</funcdef>
5378: (<type>u32</type> <param>a1</param>, <type>u32</type> <param>a2</param>, <type>u32</type> <param>a3</param>, <type>u32</type> <param>a4</param>) -- build an IPv6 address from parts
5379:
5380: <funcsect>Arguments
5381: <p><descrip>
5382: <tagp><type>u32</type> <param>a1</param></tagp>
5383: part #1
5384: <tagp><type>u32</type> <param>a2</param></tagp>
5385: part #2
5386: <tagp><type>u32</type> <param>a3</param></tagp>
5387: part #3
5388: <tagp><type>u32</type> <param>a4</param></tagp>
5389: part #4
5390: </descrip>
5391: <funcsect>Description
5392: <p>
5393: <func/ipa_build()/ takes <param/a1/ to <param/a4/ and assembles them to a single IPv6
5394: address. It's used for example when a protocol wants to bind its
5395: socket to a hard-wired multicast address.
5396: </function>
5397: <function><p><type>char *</type>
5398: <funcdef>ip_ntop</funcdef>
5399: (<type>ip_addr</type> <param>a</param>, <type>char *</type> <param>buf</param>) -- convert IP address to textual representation
5400:
5401: <funcsect>Arguments
5402: <p><descrip>
5403: <tagp><type>ip_addr</type> <param>a</param></tagp>
5404: IP address
5405: <tagp><type>char *</type> <param>buf</param></tagp>
5406: buffer of size at least <const/STD_ADDRESS_P_LENGTH/
5407: </descrip>
5408: <funcsect>Description
5409: <p>
5410: This function takes an IP address and creates its textual
5411: representation for presenting to the user.
5412: </function>
5413: <function><p><type>char *</type>
5414: <funcdef>ip_ntox</funcdef>
5415: (<type>ip_addr</type> <param>a</param>, <type>char *</type> <param>buf</param>) -- convert IP address to hexadecimal representation
5416:
5417: <funcsect>Arguments
5418: <p><descrip>
5419: <tagp><type>ip_addr</type> <param>a</param></tagp>
5420: IP address
5421: <tagp><type>char *</type> <param>buf</param></tagp>
5422: buffer of size at least <const/STD_ADDRESS_P_LENGTH/
5423: </descrip>
5424: <funcsect>Description
5425: <p>
5426: This function takes an IP address and creates its hexadecimal
5427: textual representation. Primary use: debugging dumps.
5428: </function>
5429: <function><p><type>int</type>
5430: <funcdef>ip_pton</funcdef>
5431: (<type>char *</type> <param>a</param>, <type>ip_addr *</type> <param>o</param>) -- parse textual representation of IP address
5432:
5433: <funcsect>Arguments
5434: <p><descrip>
5435: <tagp><type>char *</type> <param>a</param></tagp>
5436: textual representation
5437: <tagp><type>ip_addr *</type> <param>o</param></tagp>
5438: where to put the resulting address
5439: </descrip>
5440: <funcsect>Description
5441: <p>
5442: This function parses a textual IP address representation and
5443: stores the decoded address to a variable pointed to by <param/o/.
5444: Returns 0 if a parse error has occurred, else 0.
5445: </function>
5446: <sect>Linked lists
5447: <p>
5448: <p>
5449: The BIRD library provides a set of functions for operating on linked
5450: lists. The lists are internally represented as standard doubly linked
5451: lists with synthetic head and tail which makes all the basic operations
5452: run in constant time and contain no extra end-of-list checks. Each list
5453: is described by a <struct/list/ structure, nodes can have any format as long
5454: as they start with a <struct/node/ structure. If you want your nodes to belong
5455: to multiple lists at once, you can embed multiple <struct/node/ structures in them
5456: and use the <func/SKIP_BACK()/ macro to calculate a pointer to the start of the
5457: structure from a <struct/node/ pointer, but beware of obscurity.
5458: <p>
5459: There also exist safe linked lists (<struct/slist/, <struct/snode/ and all functions
5460: being prefixed with <tt>s_</tt>) which support asynchronous walking very
5461: similar to that used in the <struct/fib/ structure.
5462:
5463:
5464: <function><p><type>LIST_INLINE void</type>
5465: <funcdef>add_tail</funcdef>
5466: (<type>list *</type> <param>l</param>, <type>node *</type> <param>n</param>) -- append a node to a list
5467:
5468: <funcsect>Arguments
5469: <p><descrip>
5470: <tagp><type>list *</type> <param>l</param></tagp>
5471: linked list
5472: <tagp><type>node *</type> <param>n</param></tagp>
5473: list node
5474: </descrip>
5475: <funcsect>Description
5476: <p>
5477: <func/add_tail()/ takes a node <param/n/ and appends it at the end of the list <param/l/.
5478: </function>
5479: <function><p><type>LIST_INLINE void</type>
5480: <funcdef>add_head</funcdef>
5481: (<type>list *</type> <param>l</param>, <type>node *</type> <param>n</param>) -- prepend a node to a list
5482:
5483: <funcsect>Arguments
5484: <p><descrip>
5485: <tagp><type>list *</type> <param>l</param></tagp>
5486: linked list
5487: <tagp><type>node *</type> <param>n</param></tagp>
5488: list node
5489: </descrip>
5490: <funcsect>Description
5491: <p>
5492: <func/add_head()/ takes a node <param/n/ and prepends it at the start of the list <param/l/.
5493: </function>
5494: <function><p><type>LIST_INLINE void</type>
5495: <funcdef>insert_node</funcdef>
5496: (<type>node *</type> <param>n</param>, <type>node *</type> <param>after</param>) -- insert a node to a list
5497:
5498: <funcsect>Arguments
5499: <p><descrip>
5500: <tagp><type>node *</type> <param>n</param></tagp>
5501: a new list node
5502: <tagp><type>node *</type> <param>after</param></tagp>
5503: a node of a list
5504: </descrip>
5505: <funcsect>Description
5506: <p>
5507: Inserts a node <param/n/ to a linked list after an already inserted
5508: node <param/after/.
5509: </function>
5510: <function><p><type>LIST_INLINE void</type>
5511: <funcdef>rem_node</funcdef>
5512: (<type>node *</type> <param>n</param>) -- remove a node from a list
5513:
5514: <funcsect>Arguments
5515: <p><descrip>
5516: <tagp><type>node *</type> <param>n</param></tagp>
5517: node to be removed
5518: </descrip>
5519: <funcsect>Description
5520: <p>
5521: Removes a node <param/n/ from the list it's linked in. Afterwards, node <param/n/ is cleared.
5522: </function>
5523: <function><p><type>LIST_INLINE void</type>
5524: <funcdef>replace_node</funcdef>
5525: (<type>node *</type> <param>old</param>, <type>node *</type> <param>new</param>) -- replace a node in a list with another one
5526:
5527: <funcsect>Arguments
5528: <p><descrip>
5529: <tagp><type>node *</type> <param>old</param></tagp>
5530: node to be removed
5531: <tagp><type>node *</type> <param>new</param></tagp>
5532: node to be inserted
5533: </descrip>
5534: <funcsect>Description
5535: <p>
5536: Replaces node <param/old/ in the list it's linked in with node <param/new/. Node
5537: <param/old/ may be a copy of the original node, which is not accessed
5538: through the list. The function could be called with <param/old/ == <param/new/,
5539: which just fixes neighbors' pointers in the case that the node
5540: was reallocated.
5541: </function>
5542: <function><p><type>LIST_INLINE void</type>
5543: <funcdef>init_list</funcdef>
5544: (<type>list *</type> <param>l</param>) -- create an empty list
5545:
5546: <funcsect>Arguments
5547: <p><descrip>
5548: <tagp><type>list *</type> <param>l</param></tagp>
5549: list
5550: </descrip>
5551: <funcsect>Description
5552: <p>
5553: <func/init_list()/ takes a <struct/list/ structure and initializes its
5554: fields, so that it represents an empty list.
5555: </function>
5556: <function><p><type>LIST_INLINE void</type>
5557: <funcdef>add_tail_list</funcdef>
5558: (<type>list *</type> <param>to</param>, <type>list *</type> <param>l</param>) -- concatenate two lists
5559:
5560: <funcsect>Arguments
5561: <p><descrip>
5562: <tagp><type>list *</type> <param>to</param></tagp>
5563: destination list
5564: <tagp><type>list *</type> <param>l</param></tagp>
5565: source list
5566: </descrip>
5567: <funcsect>Description
5568: <p>
5569: This function appends all elements of the list <param/l/ to
5570: the list <param/to/ in constant time.
5571: </function>
5572: <sect>Miscellaneous functions.
5573: <p>
5574:
5575:
5576: <function><p><type>int</type>
5577: <funcdef>ipsum_verify</funcdef>
5578: (<type>void *</type> <param>frag</param>, <type>uint</type> <param>len</param>, <type>...</type> <param>...</param>) -- verify an IP checksum
5579:
5580: <funcsect>Arguments
5581: <p><descrip>
5582: <tagp><type>void *</type> <param>frag</param></tagp>
5583: first packet fragment
5584: <tagp><type>uint</type> <param>len</param></tagp>
5585: length in bytes
5586: <tagp><type>...</type> <param>...</param></tagp>
5587: variable arguments
5588: </descrip>
5589: <funcsect>Description
5590: <p>
5591: This function verifies whether a given fragmented packet
5592: has correct one's complement checksum as used by the IP
5593: protocol.
5594: <p>
5595: It uses all the clever tricks described in RFC 1071 to speed
5596: up checksum calculation as much as possible.
5597: <funcsect>Result
5598: <p>
5599: 1 if the checksum is correct, 0 else.
5600: </function>
5601: <function><p><type>u16</type>
5602: <funcdef>ipsum_calculate</funcdef>
5603: (<type>void *</type> <param>frag</param>, <type>uint</type> <param>len</param>, <type>...</type> <param>...</param>) -- compute an IP checksum
5604:
5605: <funcsect>Arguments
5606: <p><descrip>
5607: <tagp><type>void *</type> <param>frag</param></tagp>
5608: first packet fragment
5609: <tagp><type>uint</type> <param>len</param></tagp>
5610: length in bytes
5611: <tagp><type>...</type> <param>...</param></tagp>
5612: variable arguments
5613: </descrip>
5614: <funcsect>Description
5615: <p>
5616: This function calculates a one's complement checksum of a given fragmented
5617: packet.
5618: <p>
5619: It uses all the clever tricks described in RFC 1071 to speed
5620: up checksum calculation as much as possible.
5621: </function>
5622: <function><p><type>u32</type>
5623: <funcdef>u32_mkmask</funcdef>
5624: (<type>uint</type> <param>n</param>) -- create a bit mask
5625:
5626: <funcsect>Arguments
5627: <p><descrip>
5628: <tagp><type>uint</type> <param>n</param></tagp>
5629: number of bits
5630: </descrip>
5631: <funcsect>Description
5632: <p>
5633: <func/u32_mkmask()/ returns an unsigned 32-bit integer which binary
5634: representation consists of <param/n/ ones followed by zeroes.
5635: </function>
5636: <function><p><type>int</type>
5637: <funcdef>u32_masklen</funcdef>
5638: (<type>u32</type> <param>x</param>) -- calculate length of a bit mask
5639:
5640: <funcsect>Arguments
5641: <p><descrip>
5642: <tagp><type>u32</type> <param>x</param></tagp>
5643: bit mask
5644: </descrip>
5645: <funcsect>Description
5646: <p>
5647: This function checks whether the given integer <param/x/ represents
5648: a valid bit mask (binary representation contains first ones, then
5649: zeroes) and returns the number of ones or -1 if the mask is invalid.
5650: </function>
5651: <function><p><type>u32</type>
5652: <funcdef>u32_log2</funcdef>
5653: (<type>u32</type> <param>v</param>) -- compute a binary logarithm.
5654:
5655: <funcsect>Arguments
5656: <p><descrip>
5657: <tagp><type>u32</type> <param>v</param></tagp>
5658: number
5659: </descrip>
5660: <funcsect>Description
5661: <p>
5662: This function computes a integral part of binary logarithm of given
5663: integer <param/v/ and returns it. The computed value is also an index of the
5664: most significant non-zero bit position.
5665: </function>
5666: <function><p><type>int</type>
5667: <funcdef>patmatch</funcdef>
5668: (<type>byte *</type> <param>p</param>, <type>byte *</type> <param>s</param>) -- match shell-like patterns
5669:
5670: <funcsect>Arguments
5671: <p><descrip>
5672: <tagp><type>byte *</type> <param>p</param></tagp>
5673: pattern
5674: <tagp><type>byte *</type> <param>s</param></tagp>
5675: string
5676: </descrip>
5677: <funcsect>Description
5678: <p>
5679: <func/patmatch()/ returns whether given string <param/s/ matches the given shell-like
5680: pattern <param/p/. The patterns consist of characters (which are matched literally),
5681: question marks which match any single character, asterisks which match any
5682: (possibly empty) string of characters and backslashes which are used to
5683: escape any special characters and force them to be treated literally.
5684: <p>
5685: The matching process is not optimized with respect to time, so please
5686: avoid using this function for complex patterns.
5687: </function>
5688: <function><p><type>int</type>
5689: <funcdef>bvsnprintf</funcdef>
5690: (<type>char *</type> <param>buf</param>, <type>int</type> <param>size</param>, <type>const char *</type> <param>fmt</param>, <type>va_list</type> <param>args</param>) -- BIRD's <func/vsnprintf()/
5691:
5692: <funcsect>Arguments
5693: <p><descrip>
5694: <tagp><type>char *</type> <param>buf</param></tagp>
5695: destination buffer
5696: <tagp><type>int</type> <param>size</param></tagp>
5697: size of the buffer
5698: <tagp><type>const char *</type> <param>fmt</param></tagp>
5699: format string
5700: <tagp><type>va_list</type> <param>args</param></tagp>
5701: a list of arguments to be formatted
5702: </descrip>
5703: <funcsect>Description
5704: <p>
5705: This functions acts like ordinary <func/sprintf()/ except that it checks
5706: available space to avoid buffer overflows and it allows some more
5707: <funcsect>format specifiers
5708: <p>
5709: <tt><const/I/</tt> for formatting of IP addresses (any non-zero
5710: width is automatically replaced by standard IP address width which
5711: depends on whether we use IPv4 or IPv6; <tt>%#I</tt> gives hexadecimal format),
5712: <tt><const/R/</tt> for Router / Network ID (u32 value printed as IPv4 address)
5713: <tt><const/lR/</tt> for 64bit Router / Network ID (u64 value printed as eight :-separated octets)
5714: and <tt><const/m/</tt> resp. <tt><const/M/</tt> for error messages (uses <func/strerror()/ to translate <param/errno/ code to
5715: message text). On the other hand, it doesn't support floating
5716: point numbers.
5717: <funcsect>Result
5718: <p>
5719: number of characters of the output string or -1 if
5720: the buffer space was insufficient.
5721: </function>
5722: <function><p><type>int</type>
5723: <funcdef>bvsprintf</funcdef>
5724: (<type>char *</type> <param>buf</param>, <type>const char *</type> <param>fmt</param>, <type>va_list</type> <param>args</param>) -- BIRD's <func/vsprintf()/
5725:
5726: <funcsect>Arguments
5727: <p><descrip>
5728: <tagp><type>char *</type> <param>buf</param></tagp>
5729: buffer
5730: <tagp><type>const char *</type> <param>fmt</param></tagp>
5731: format string
5732: <tagp><type>va_list</type> <param>args</param></tagp>
5733: a list of arguments to be formatted
5734: </descrip>
5735: <funcsect>Description
5736: <p>
5737: This function is equivalent to <func/bvsnprintf()/ with an infinite
5738: buffer size. Please use carefully only when you are absolutely
5739: sure the buffer won't overflow.
5740: </function>
5741: <function><p><type>int</type>
5742: <funcdef>bsprintf</funcdef>
5743: (<type>char *</type> <param>buf</param>, <type>const char *</type> <param>fmt</param>, <type>...</type> <param>...</param>) -- BIRD's <func/sprintf()/
5744:
5745: <funcsect>Arguments
5746: <p><descrip>
5747: <tagp><type>char *</type> <param>buf</param></tagp>
5748: buffer
5749: <tagp><type>const char *</type> <param>fmt</param></tagp>
5750: format string
5751: <tagp><type>...</type> <param>...</param></tagp>
5752: variable arguments
5753: </descrip>
5754: <funcsect>Description
5755: <p>
5756: This function is equivalent to <func/bvsnprintf()/ with an infinite
5757: buffer size and variable arguments instead of a <struct/va_list/.
5758: Please use carefully only when you are absolutely
5759: sure the buffer won't overflow.
5760: </function>
5761: <function><p><type>int</type>
5762: <funcdef>bsnprintf</funcdef>
5763: (<type>char *</type> <param>buf</param>, <type>int</type> <param>size</param>, <type>const char *</type> <param>fmt</param>, <type>...</type> <param>...</param>) -- BIRD's <func/snprintf()/
5764:
5765: <funcsect>Arguments
5766: <p><descrip>
5767: <tagp><type>char *</type> <param>buf</param></tagp>
5768: buffer
5769: <tagp><type>int</type> <param>size</param></tagp>
5770: buffer size
5771: <tagp><type>const char *</type> <param>fmt</param></tagp>
5772: format string
5773: <tagp><type>...</type> <param>...</param></tagp>
5774: variable arguments
5775: </descrip>
5776: <funcsect>Description
5777: <p>
5778: This function is equivalent to <func/bsnprintf()/ with variable arguments instead of a <struct/va_list/.
5779: </function>
5780: <function><p><type>void *</type>
5781: <funcdef>xmalloc</funcdef>
5782: (<type>uint</type> <param>size</param>) -- malloc with checking
5783:
5784: <funcsect>Arguments
5785: <p><descrip>
5786: <tagp><type>uint</type> <param>size</param></tagp>
5787: block size
5788: </descrip>
5789: <funcsect>Description
5790: <p>
5791: This function is equivalent to <func/malloc()/ except that in case of
5792: failure it calls <func/die()/ to quit the program instead of returning
5793: a <const/NULL/ pointer.
5794: <p>
5795: Wherever possible, please use the memory resources instead.
5796: </function>
5797: <function><p><type>void *</type>
5798: <funcdef>xrealloc</funcdef>
5799: (<type>void *</type> <param>ptr</param>, <type>uint</type> <param>size</param>) -- realloc with checking
5800:
5801: <funcsect>Arguments
5802: <p><descrip>
5803: <tagp><type>void *</type> <param>ptr</param></tagp>
5804: original memory block
5805: <tagp><type>uint</type> <param>size</param></tagp>
5806: block size
5807: </descrip>
5808: <funcsect>Description
5809: <p>
5810: This function is equivalent to <func/realloc()/ except that in case of
5811: failure it calls <func/die()/ to quit the program instead of returning
5812: a <const/NULL/ pointer.
5813: <p>
5814: Wherever possible, please use the memory resources instead.
5815: </function>
5816: <sect>Message authentication codes
5817: <p>
5818: <p>
5819: MAC algorithms are simple cryptographic tools for message authentication.
5820: They use shared a secret key a and message text to generate authentication
5821: code, which is then passed with the message to the other side, where the code
5822: is verified. There are multiple families of MAC algorithms based on different
5823: cryptographic primitives, BIRD implements two MAC families which use hash
5824: functions.
5825: <p>
5826: The first family is simply a cryptographic hash camouflaged as MAC algorithm.
5827: Originally supposed to be (m|k)-hash (message is concatenated with key, and
5828: that is hashed), but later it turned out that a raw hash is more practical.
5829: This is used for cryptographic authentication in OSPFv2, RIP and BFD.
5830: <p>
5831: The second family is the standard HMAC (RFC 2104), using inner and outer hash
5832: to process key and message. HMAC (with SHA) is used in advanced OSPF and RIP
5833: authentication (RFC 5709, RFC 4822).
5834:
5835:
5836: <function><p><type>void</type>
5837: <funcdef>mac_init</funcdef>
5838: (<type>struct mac_context *</type> <param>ctx</param>, <type>uint</type> <param>id</param>, <type>const byte *</type> <param>key</param>, <type>uint</type> <param>keylen</param>) -- initialize MAC algorithm
5839:
5840: <funcsect>Arguments
5841: <p><descrip>
5842: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
5843: context to initialize
5844: <tagp><type>uint</type> <param>id</param></tagp>
5845: MAC algorithm ID
5846: <tagp><type>const byte *</type> <param>key</param></tagp>
5847: MAC key
5848: <tagp><type>uint</type> <param>keylen</param></tagp>
5849: MAC key length
5850: </descrip>
5851: <funcsect>Description
5852: <p>
5853: Initialize MAC context <param/ctx/ for algorithm <param/id/ (e.g., <const/ALG_HMAC_SHA1/), with
5854: key <param/key/ of length <param/keylen/. After that, message data could be added using
5855: <func/mac_update()/ function.
5856: </function>
5857: <function><p><type>void</type>
5858: <funcdef>mac_update</funcdef>
5859: (<type>struct mac_context *</type> <param>ctx</param>, <type>const byte *</type> <param>data</param>, <type>uint</type> <param>datalen</param>) -- add more data to MAC algorithm
5860:
5861: <funcsect>Arguments
5862: <p><descrip>
5863: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
5864: MAC context
5865: <tagp><type>const byte *</type> <param>data</param></tagp>
5866: data to add
5867: <tagp><type>uint</type> <param>datalen</param></tagp>
5868: length of data
5869: </descrip>
5870: <funcsect>Description
5871: <p>
5872: Push another <param/datalen/ bytes of data pointed to by <param/data/ into the MAC
5873: algorithm currently in <param/ctx/. Can be called multiple times for the same MAC
5874: context. It has the same effect as concatenating all the data together and
5875: passing them at once.
5876: </function>
5877: <function><p><type>byte *</type>
5878: <funcdef>mac_final</funcdef>
5879: (<type>struct mac_context *</type> <param>ctx</param>) -- finalize MAC algorithm
5880:
5881: <funcsect>Arguments
5882: <p><descrip>
5883: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
5884: MAC context
5885: </descrip>
5886: <funcsect>Description
5887: <p>
5888: Finish MAC computation and return a pointer to the result. No more
5889: <param/mac_update/() calls could be done, but the context may be reinitialized
5890: later.
5891: <p>
5892: Note that the returned pointer points into data in the <param/ctx/ context. If it
5893: ceases to exist, the pointer becomes invalid.
5894: </function>
5895: <function><p><type>void</type>
5896: <funcdef>mac_cleanup</funcdef>
5897: (<type>struct mac_context *</type> <param>ctx</param>) -- cleanup MAC context
5898:
5899: <funcsect>Arguments
5900: <p><descrip>
5901: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
5902: MAC context
5903: </descrip>
5904: <funcsect>Description
5905: <p>
5906: Cleanup MAC context after computation (by filling with zeros). Not strictly
5907: necessary, just to erase sensitive data from stack. This also invalidates the
5908: pointer returned by <param/mac_final/().
5909: </function>
5910: <function><p><type>void</type>
5911: <funcdef>mac_fill</funcdef>
5912: (<type>uint</type> <param>id</param>, <type>const byte *</type> <param>key</param>, <type>uint</type> <param>keylen</param>, <type>const byte *</type> <param>data</param>, <type>uint</type> <param>datalen</param>, <type>byte *</type> <param>mac</param>) -- compute and fill MAC
5913:
5914: <funcsect>Arguments
5915: <p><descrip>
5916: <tagp><type>uint</type> <param>id</param></tagp>
5917: MAC algorithm ID
5918: <tagp><type>const byte *</type> <param>key</param></tagp>
5919: secret key
5920: <tagp><type>uint</type> <param>keylen</param></tagp>
5921: key length
5922: <tagp><type>const byte *</type> <param>data</param></tagp>
5923: message data
5924: <tagp><type>uint</type> <param>datalen</param></tagp>
5925: message length
5926: <tagp><type>byte *</type> <param>mac</param></tagp>
5927: place to fill MAC
5928: </descrip>
5929: <funcsect>Description
5930: <p>
5931: Compute MAC for specified key <param/key/ and message <param/data/ using algorithm <param/id/ and
5932: copy it to buffer <param/mac/. <func/mac_fill()/ is a shortcut function doing all usual
5933: steps for transmitted messages.
5934: </function>
5935: <function><p><type>int</type>
5936: <funcdef>mac_verify</funcdef>
5937: (<type>uint</type> <param>id</param>, <type>const byte *</type> <param>key</param>, <type>uint</type> <param>keylen</param>, <type>const byte *</type> <param>data</param>, <type>uint</type> <param>datalen</param>, <type>const byte *</type> <param>mac</param>) -- compute and verify MAC
5938:
5939: <funcsect>Arguments
5940: <p><descrip>
5941: <tagp><type>uint</type> <param>id</param></tagp>
5942: MAC algorithm ID
5943: <tagp><type>const byte *</type> <param>key</param></tagp>
5944: secret key
5945: <tagp><type>uint</type> <param>keylen</param></tagp>
5946: key length
5947: <tagp><type>const byte *</type> <param>data</param></tagp>
5948: message data
5949: <tagp><type>uint</type> <param>datalen</param></tagp>
5950: message length
5951: <tagp><type>const byte *</type> <param>mac</param></tagp>
5952: received MAC
5953: </descrip>
5954: <funcsect>Description
5955: <p>
5956: Compute MAC for specified key <param/key/ and message <param/data/ using algorithm <param/id/ and
5957: compare it with received <param/mac/, return whether they are the same. <func/mac_verify()/
5958: is a shortcut function doing all usual steps for received messages.
5959: </function>
5960: <!--
5961: BIRD Programmer's Guide: Resources
5962:
5963: (c) 2000 Martin Mares <mj@ucw.cz>
5964: -->
5965:
5966: <chapt>Resources
5967:
5968: <sect>Introduction
5969:
5970: <p>Most large software projects implemented in classical procedural
5971: programming languages usually end up with lots of code taking care
5972: of resource allocation and deallocation. Bugs in such code are often
5973: very difficult to find, because they cause only `resource leakage',
5974: that is keeping a lot of memory and other resources which nobody
5975: references to.
5976:
5977: <p>We've tried to solve this problem by employing a resource tracking
5978: system which keeps track of all the resources allocated by all the
5979: modules of BIRD, deallocates everything automatically when a module
5980: shuts down and it is able to print out the list of resources and
5981: the corresponding modules they are allocated by.
5982:
5983: <p>Each allocated resource (from now we'll speak about allocated
5984: resources only) is represented by a structure starting with a standard
5985: header (struct <struct/resource/) consisting of a list node (resources are
5986: often linked to various lists) and a pointer to <struct/resclass/ -- a resource
5987: class structure pointing to functions implementing generic resource
5988: operations (such as freeing of the resource) for the particular resource
5989: type.
5990:
5991: <p>There exist the following types of resources:
5992:
5993: <itemize>
5994: <item><it/Resource pools/ (<struct/pool/)
5995: <item><it/Memory blocks/
5996: <item><it/Linear memory pools/ (<struct/linpool/)
5997: <item><it/Slabs/ (<struct/slab/)
5998: <item><it/Events/ (<struct/event/)
5999: <item><it/Timers/ (<struct/timer/)
6000: <item><it/Sockets/ (<struct/socket/)
6001: </itemize>
6002: <sect>Resource pools
6003: <p>
6004: <p>
6005: Resource pools (<struct/pool/) are just containers holding a list of
6006: other resources. Freeing a pool causes all the listed resources
6007: to be freed as well. Each existing <struct/resource/ is linked to some pool
6008: except for a root pool which isn't linked anywhere, so all the
6009: resources form a tree structure with internal nodes corresponding
6010: to pools and leaves being the other resources.
6011: <p>
6012: Example: Almost all modules of BIRD have their private pool which
6013: is freed upon shutdown of the module.
6014:
6015:
6016: <function><p><type>pool *</type>
6017: <funcdef>rp_new</funcdef>
6018: (<type>pool *</type> <param>p</param>, <type>char *</type> <param>name</param>) -- create a resource pool
6019:
6020: <funcsect>Arguments
6021: <p><descrip>
6022: <tagp><type>pool *</type> <param>p</param></tagp>
6023: parent pool
6024: <tagp><type>char *</type> <param>name</param></tagp>
6025: pool name (to be included in debugging dumps)
6026: </descrip>
6027: <funcsect>Description
6028: <p>
6029: <func/rp_new()/ creates a new resource pool inside the specified
6030: parent pool.
6031: </function>
6032: <function><p><type>void</type>
6033: <funcdef>rmove</funcdef>
6034: (<type>void *</type> <param>res</param>, <type>pool *</type> <param>p</param>) -- move a resource
6035:
6036: <funcsect>Arguments
6037: <p><descrip>
6038: <tagp><type>void *</type> <param>res</param></tagp>
6039: resource
6040: <tagp><type>pool *</type> <param>p</param></tagp>
6041: pool to move the resource to
6042: </descrip>
6043: <funcsect>Description
6044: <p>
6045: <func/rmove()/ moves a resource from one pool to another.
6046: </function>
6047: <function><p><type>void</type>
6048: <funcdef>rfree</funcdef>
6049: (<type>void *</type> <param>res</param>) -- free a resource
6050:
6051: <funcsect>Arguments
6052: <p><descrip>
6053: <tagp><type>void *</type> <param>res</param></tagp>
6054: resource
6055: </descrip>
6056: <funcsect>Description
6057: <p>
6058: <func/rfree()/ frees the given resource and all information associated
6059: with it. In case it's a resource pool, it also frees all the objects
6060: living inside the pool.
6061: <p>
6062: It works by calling a class-specific freeing function.
6063: </function>
6064: <function><p><type>void</type>
6065: <funcdef>rdump</funcdef>
6066: (<type>void *</type> <param>res</param>) -- dump a resource
6067:
6068: <funcsect>Arguments
6069: <p><descrip>
6070: <tagp><type>void *</type> <param>res</param></tagp>
6071: resource
6072: </descrip>
6073: <funcsect>Description
6074: <p>
6075: This function prints out all available information about the given
6076: resource to the debugging output.
6077: <p>
6078: It works by calling a class-specific dump function.
6079: </function>
6080: <function><p><type>void *</type>
6081: <funcdef>ralloc</funcdef>
6082: (<type>pool *</type> <param>p</param>, <type>struct resclass *</type> <param>c</param>) -- create a resource
6083:
6084: <funcsect>Arguments
6085: <p><descrip>
6086: <tagp><type>pool *</type> <param>p</param></tagp>
6087: pool to create the resource in
6088: <tagp><type>struct resclass *</type> <param>c</param></tagp>
6089: class of the new resource
6090: </descrip>
6091: <funcsect>Description
6092: <p>
6093: This function is called by the resource classes to create a new
6094: resource of the specified class and link it to the given pool.
6095: Allocated memory is zeroed. Size of the resource structure is taken
6096: from the <param/size/ field of the <struct/resclass/.
6097: </function>
6098: <function><p><type>void</type>
6099: <funcdef>rlookup</funcdef>
6100: (<type>unsigned long</type> <param>a</param>) -- look up a memory location
6101:
6102: <funcsect>Arguments
6103: <p><descrip>
6104: <tagp><type>unsigned long</type> <param>a</param></tagp>
6105: memory address
6106: </descrip>
6107: <funcsect>Description
6108: <p>
6109: This function examines all existing resources to see whether
6110: the address <param/a/ is inside any resource. It's used for debugging
6111: purposes only.
6112: <p>
6113: It works by calling a class-specific lookup function for each
6114: resource.
6115: </function>
6116: <function><p><type>void</type>
6117: <funcdef>resource_init</funcdef>
6118: (<param>void</param>) -- initialize the resource manager
6119:
6120: <funcsect>Description
6121: <p>
6122: <p>
6123: This function is called during BIRD startup. It initializes
6124: all data structures of the resource manager and creates the
6125: root pool.
6126: </function>
6127: <sect>Memory blocks
6128: <p>
6129: <p>
6130: Memory blocks are pieces of contiguous allocated memory.
6131: They are a bit non-standard since they are represented not by a pointer
6132: to <struct/resource/, but by a void pointer to the start of data of the
6133: memory block. All memory block functions know how to locate the header
6134: given the data pointer.
6135: <p>
6136: Example: All "unique" data structures such as hash tables are allocated
6137: as memory blocks.
6138:
6139:
6140: <function><p><type>void *</type>
6141: <funcdef>mb_alloc</funcdef>
6142: (<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>size</param>) -- allocate a memory block
6143:
6144: <funcsect>Arguments
6145: <p><descrip>
6146: <tagp><type>pool *</type> <param>p</param></tagp>
6147: pool
6148: <tagp><type>unsigned</type> <param>size</param></tagp>
6149: size of the block
6150: </descrip>
6151: <funcsect>Description
6152: <p>
6153: <func/mb_alloc()/ allocates memory of a given size and creates
6154: a memory block resource representing this memory chunk
6155: in the pool <param/p/.
6156: <p>
6157: Please note that <func/mb_alloc()/ returns a pointer to the memory
6158: chunk, not to the resource, hence you have to free it using
6159: <func/mb_free()/, not <func/rfree()/.
6160: </function>
6161: <function><p><type>void *</type>
6162: <funcdef>mb_allocz</funcdef>
6163: (<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>size</param>) -- allocate and clear a memory block
6164:
6165: <funcsect>Arguments
6166: <p><descrip>
6167: <tagp><type>pool *</type> <param>p</param></tagp>
6168: pool
6169: <tagp><type>unsigned</type> <param>size</param></tagp>
6170: size of the block
6171: </descrip>
6172: <funcsect>Description
6173: <p>
6174: <func/mb_allocz()/ allocates memory of a given size, initializes it to
6175: zeroes and creates a memory block resource representing this memory
6176: chunk in the pool <param/p/.
6177: <p>
6178: Please note that <func/mb_allocz()/ returns a pointer to the memory
6179: chunk, not to the resource, hence you have to free it using
6180: <func/mb_free()/, not <func/rfree()/.
6181: </function>
6182: <function><p><type>void *</type>
6183: <funcdef>mb_realloc</funcdef>
6184: (<type>void *</type> <param>m</param>, <type>unsigned</type> <param>size</param>) -- reallocate a memory block
6185:
6186: <funcsect>Arguments
6187: <p><descrip>
6188: <tagp><type>void *</type> <param>m</param></tagp>
6189: memory block
6190: <tagp><type>unsigned</type> <param>size</param></tagp>
6191: new size of the block
6192: </descrip>
6193: <funcsect>Description
6194: <p>
6195: <func/mb_realloc()/ changes the size of the memory block <param/m/ to a given size.
6196: The contents will be unchanged to the minimum of the old and new sizes;
6197: newly allocated memory will be uninitialized. Contrary to <func/realloc()/
6198: behavior, <param/m/ must be non-NULL, because the resource pool is inherited
6199: from it.
6200: <p>
6201: Like <func/mb_alloc()/, <func/mb_realloc()/ also returns a pointer to the memory
6202: chunk, not to the resource, hence you have to free it using
6203: <func/mb_free()/, not <func/rfree()/.
6204: </function>
6205: <function><p><type>void</type>
6206: <funcdef>mb_free</funcdef>
6207: (<type>void *</type> <param>m</param>) -- free a memory block
6208:
6209: <funcsect>Arguments
6210: <p><descrip>
6211: <tagp><type>void *</type> <param>m</param></tagp>
6212: memory block
6213: </descrip>
6214: <funcsect>Description
6215: <p>
6216: <func/mb_free()/ frees all memory associated with the block <param/m/.
6217: </function>
6218: <sect>Linear memory pools
6219: <p>
6220: <p>
6221: Linear memory pools are collections of memory blocks which
6222: support very fast allocation of new blocks, but are able to free only
6223: the whole collection at once.
6224: <p>
6225: Example: Each configuration is described by a complex system of structures,
6226: linked lists and function trees which are all allocated from a single linear
6227: pool, thus they can be freed at once when the configuration is no longer used.
6228:
6229:
6230: <function><p><type>linpool *</type>
6231: <funcdef>lp_new</funcdef>
6232: (<type>pool *</type> <param>p</param>, <type>uint</type> <param>blk</param>) -- create a new linear memory pool
6233:
6234: <funcsect>Arguments
6235: <p><descrip>
6236: <tagp><type>pool *</type> <param>p</param></tagp>
6237: pool
6238: <tagp><type>uint</type> <param>blk</param></tagp>
6239: block size
6240: </descrip>
6241: <funcsect>Description
6242: <p>
6243: <func/lp_new()/ creates a new linear memory pool resource inside the pool <param/p/.
6244: The linear pool consists of a list of memory chunks of size at least
6245: <param/blk/.
6246: </function>
6247: <function><p><type>void *</type>
6248: <funcdef>lp_alloc</funcdef>
6249: (<type>linpool *</type> <param>m</param>, <type>uint</type> <param>size</param>) -- allocate memory from a <struct/linpool/
6250:
6251: <funcsect>Arguments
6252: <p><descrip>
6253: <tagp><type>linpool *</type> <param>m</param></tagp>
6254: linear memory pool
6255: <tagp><type>uint</type> <param>size</param></tagp>
6256: amount of memory
6257: </descrip>
6258: <funcsect>Description
6259: <p>
6260: <func/lp_alloc()/ allocates <param/size/ bytes of memory from a <struct/linpool/ <param/m/
6261: and it returns a pointer to the allocated memory.
6262: <p>
6263: It works by trying to find free space in the last memory chunk
6264: associated with the <struct/linpool/ and creating a new chunk of the standard
6265: size (as specified during <func/lp_new()/) if the free space is too small
6266: to satisfy the allocation. If <param/size/ is too large to fit in a standard
6267: size chunk, an "overflow" chunk is created for it instead.
6268: </function>
6269: <function><p><type>void *</type>
6270: <funcdef>lp_allocu</funcdef>
6271: (<type>linpool *</type> <param>m</param>, <type>uint</type> <param>size</param>) -- allocate unaligned memory from a <struct/linpool/
6272:
6273: <funcsect>Arguments
6274: <p><descrip>
6275: <tagp><type>linpool *</type> <param>m</param></tagp>
6276: linear memory pool
6277: <tagp><type>uint</type> <param>size</param></tagp>
6278: amount of memory
6279: </descrip>
6280: <funcsect>Description
6281: <p>
6282: <func/lp_allocu()/ allocates <param/size/ bytes of memory from a <struct/linpool/ <param/m/
6283: and it returns a pointer to the allocated memory. It doesn't
6284: attempt to align the memory block, giving a very efficient way
6285: how to allocate strings without any space overhead.
6286: </function>
6287: <function><p><type>void *</type>
6288: <funcdef>lp_allocz</funcdef>
6289: (<type>linpool *</type> <param>m</param>, <type>uint</type> <param>size</param>) -- allocate cleared memory from a <struct/linpool/
6290:
6291: <funcsect>Arguments
6292: <p><descrip>
6293: <tagp><type>linpool *</type> <param>m</param></tagp>
6294: linear memory pool
6295: <tagp><type>uint</type> <param>size</param></tagp>
6296: amount of memory
6297: </descrip>
6298: <funcsect>Description
6299: <p>
6300: This function is identical to <func/lp_alloc()/ except that it
6301: clears the allocated memory block.
6302: </function>
6303: <function><p><type>void</type>
6304: <funcdef>lp_flush</funcdef>
6305: (<type>linpool *</type> <param>m</param>) -- flush a linear memory pool
6306:
6307: <funcsect>Arguments
6308: <p><descrip>
6309: <tagp><type>linpool *</type> <param>m</param></tagp>
6310: linear memory pool
6311: </descrip>
6312: <funcsect>Description
6313: <p>
6314: This function frees the whole contents of the given <struct/linpool/ <param/m/,
6315: but leaves the pool itself.
6316: </function>
6317: <sect>Slabs
6318: <p>
6319: <p>
6320: Slabs are collections of memory blocks of a fixed size.
6321: They support very fast allocation and freeing of such blocks, prevent memory
6322: fragmentation and optimize L2 cache usage. Slabs have been invented by Jeff Bonwick
6323: and published in USENIX proceedings as `The Slab Allocator: An Object-Caching Kernel
6324: Memory Allocator'. Our implementation follows this article except that we don't use
6325: constructors and destructors.
6326: <p>
6327: When the <tt>DEBUGGING</tt> switch is turned on, we automatically fill all
6328: newly allocated and freed blocks with a special pattern to make detection
6329: of use of uninitialized or already freed memory easier.
6330: <p>
6331: Example: Nodes of a FIB are allocated from a per-FIB Slab.
6332:
6333:
6334: <function><p><type>slab *</type>
6335: <funcdef>sl_new</funcdef>
6336: (<type>pool *</type> <param>p</param>, <type>uint</type> <param>size</param>) -- create a new Slab
6337:
6338: <funcsect>Arguments
6339: <p><descrip>
6340: <tagp><type>pool *</type> <param>p</param></tagp>
6341: resource pool
6342: <tagp><type>uint</type> <param>size</param></tagp>
6343: block size
6344: </descrip>
6345: <funcsect>Description
6346: <p>
6347: This function creates a new Slab resource from which
6348: objects of size <param/size/ can be allocated.
6349: </function>
6350: <function><p><type>void *</type>
6351: <funcdef>sl_alloc</funcdef>
6352: (<type>slab *</type> <param>s</param>) -- allocate an object from Slab
6353:
6354: <funcsect>Arguments
6355: <p><descrip>
6356: <tagp><type>slab *</type> <param>s</param></tagp>
6357: slab
6358: </descrip>
6359: <funcsect>Description
6360: <p>
6361: <func/sl_alloc()/ allocates space for a single object from the
6362: Slab and returns a pointer to the object.
6363: </function>
6364: <function><p><type>void</type>
6365: <funcdef>sl_free</funcdef>
6366: (<type>slab *</type> <param>s</param>, <type>void *</type> <param>oo</param>) -- return a free object back to a Slab
6367:
6368: <funcsect>Arguments
6369: <p><descrip>
6370: <tagp><type>slab *</type> <param>s</param></tagp>
6371: slab
6372: <tagp><type>void *</type> <param>oo</param></tagp>
6373: object returned by <func/sl_alloc()/
6374: </descrip>
6375: <funcsect>Description
6376: <p>
6377: This function frees memory associated with the object <param/oo/
6378: and returns it back to the Slab <param/s/.
6379: </function>
6380: <sect>Events
6381: <p>
6382: <p>
6383: Events are there to keep track of deferred execution.
6384: Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller
6385: parts, so that no module can monopolize the CPU. To split such a task, just create
6386: an <struct/event/ resource, point it to the function you want to have called and call <func/ev_schedule()/
6387: to ask the core to run the event when nothing more important requires attention.
6388: <p>
6389: You can also define your own event lists (the <struct/event_list/ structure), enqueue your
6390: events in them and explicitly ask to run them.
6391:
6392:
6393: <function><p><type>event *</type>
6394: <funcdef>ev_new</funcdef>
6395: (<type>pool *</type> <param>p</param>) -- create a new event
6396:
6397: <funcsect>Arguments
6398: <p><descrip>
6399: <tagp><type>pool *</type> <param>p</param></tagp>
6400: resource pool
6401: </descrip>
6402: <funcsect>Description
6403: <p>
6404: This function creates a new event resource. To use it,
6405: you need to fill the structure fields and call <func/ev_schedule()/.
6406: </function>
6407: <function><p><type>void</type>
6408: <funcdef>ev_run</funcdef>
6409: (<type>event *</type> <param>e</param>) -- run an event
6410:
6411: <funcsect>Arguments
6412: <p><descrip>
6413: <tagp><type>event *</type> <param>e</param></tagp>
6414: an event
6415: </descrip>
6416: <funcsect>Description
6417: <p>
6418: This function explicitly runs the event <param/e/ (calls its hook
6419: function) and removes it from an event list if it's linked to any.
6420: <p>
6421: From the hook function, you can call <func/ev_enqueue()/ or <func/ev_schedule()/
6422: to re-add the event.
6423: </function>
6424: <function><p><type>void</type>
6425: <funcdef>ev_enqueue</funcdef>
6426: (<type>event_list *</type> <param>l</param>, <type>event *</type> <param>e</param>) -- enqueue an event
6427:
6428: <funcsect>Arguments
6429: <p><descrip>
6430: <tagp><type>event_list *</type> <param>l</param></tagp>
6431: an event list
6432: <tagp><type>event *</type> <param>e</param></tagp>
6433: an event
6434: </descrip>
6435: <funcsect>Description
6436: <p>
6437: <func/ev_enqueue()/ stores the event <param/e/ to the specified event
6438: list <param/l/ which can be run by calling <func/ev_run_list()/.
6439: </function>
6440: <function><p><type>void</type>
6441: <funcdef>ev_schedule</funcdef>
6442: (<type>event *</type> <param>e</param>) -- schedule an event
6443:
6444: <funcsect>Arguments
6445: <p><descrip>
6446: <tagp><type>event *</type> <param>e</param></tagp>
6447: an event
6448: </descrip>
6449: <funcsect>Description
6450: <p>
6451: This function schedules an event by enqueueing it to a system-wide
6452: event list which is run by the platform dependent code whenever
6453: appropriate.
6454: </function>
6455: <function><p><type>int</type>
6456: <funcdef>ev_run_list</funcdef>
6457: (<type>event_list *</type> <param>l</param>) -- run an event list
6458:
6459: <funcsect>Arguments
6460: <p><descrip>
6461: <tagp><type>event_list *</type> <param>l</param></tagp>
6462: an event list
6463: </descrip>
6464: <funcsect>Description
6465: <p>
6466: This function calls <func/ev_run()/ for all events enqueued in the list <param/l/.
6467: </function>
6468: <sect>Timers
6469: <p>
6470: <p>
6471: Timers are resources which represent a wish of a module to call
6472: a function at the specified time. The platform dependent code
6473: doesn't guarantee exact timing, only that a timer function
6474: won't be called before the requested time.
6475: <p>
6476: In BIRD, time is represented by values of the <struct/bird_clock_t/ type
6477: which are integral numbers interpreted as a relative number of seconds since
6478: some fixed time point in past. The current time can be read
6479: from variable <param/now/ with reasonable accuracy and is monotonic. There is also
6480: a current 'absolute' time in variable <param/now_real/ reported by OS.
6481: <p>
6482: Each timer is described by a <struct/timer/ structure containing a pointer
6483: to the handler function (<param/hook/), data private to this function (<param/data/),
6484: time the function should be called at (<param/expires/, 0 for inactive timers),
6485: for the other fields see <tt>timer.h</tt>.
6486:
6487:
6488: <function><p><type>timer *</type>
6489: <funcdef>tm_new</funcdef>
6490: (<type>pool *</type> <param>p</param>) -- create a timer
6491:
6492: <funcsect>Arguments
6493: <p><descrip>
6494: <tagp><type>pool *</type> <param>p</param></tagp>
6495: pool
6496: </descrip>
6497: <funcsect>Description
6498: <p>
6499: This function creates a new timer resource and returns
6500: a pointer to it. To use the timer, you need to fill in
6501: the structure fields and call <func/tm_start()/ to start timing.
6502: </function>
6503: <function><p><type>void</type>
6504: <funcdef>tm_start</funcdef>
6505: (<type>timer *</type> <param>t</param>, <type>unsigned</type> <param>after</param>) -- start a timer
6506:
6507: <funcsect>Arguments
6508: <p><descrip>
6509: <tagp><type>timer *</type> <param>t</param></tagp>
6510: timer
6511: <tagp><type>unsigned</type> <param>after</param></tagp>
6512: number of seconds the timer should be run after
6513: </descrip>
6514: <funcsect>Description
6515: <p>
6516: This function schedules the hook function of the timer to
6517: be called after <param/after/ seconds. If the timer has been already
6518: started, it's <param/expire/ time is replaced by the new value.
6519: <p>
6520: You can have set the <param/randomize/ field of <param/t/, the timeout
6521: will be increased by a random number of seconds chosen
6522: uniformly from range 0 .. <param/randomize/.
6523: <p>
6524: You can call <func/tm_start()/ from the handler function of the timer
6525: to request another run of the timer. Also, you can set the <param/recurrent/
6526: field to have the timer re-added automatically with the same timeout.
6527: </function>
6528: <function><p><type>void</type>
6529: <funcdef>tm_stop</funcdef>
6530: (<type>timer *</type> <param>t</param>) -- stop a timer
6531:
6532: <funcsect>Arguments
6533: <p><descrip>
6534: <tagp><type>timer *</type> <param>t</param></tagp>
6535: timer
6536: </descrip>
6537: <funcsect>Description
6538: <p>
6539: This function stops a timer. If the timer is already stopped,
6540: nothing happens.
6541: </function>
6542: <function><p><type>bird_clock_t</type>
6543: <funcdef>tm_parse_datetime</funcdef>
6544: (<type>char *</type> <param>x</param>) -- parse a date and time
6545:
6546: <funcsect>Arguments
6547: <p><descrip>
6548: <tagp><type>char *</type> <param>x</param></tagp>
6549: datetime string
6550: </descrip>
6551: <funcsect>Description
6552: <p>
6553: <func/tm_parse_datetime()/ takes a textual representation of
6554: a date and time (dd-mm-yyyy hh:mm:ss)
6555: and converts it to the corresponding value of type <struct/bird_clock_t/.
6556: </function>
6557: <function><p><type>bird_clock_t</type>
6558: <funcdef>tm_parse_date</funcdef>
6559: (<type>char *</type> <param>x</param>) -- parse a date
6560:
6561: <funcsect>Arguments
6562: <p><descrip>
6563: <tagp><type>char *</type> <param>x</param></tagp>
6564: date string
6565: </descrip>
6566: <funcsect>Description
6567: <p>
6568: <func/tm_parse_date()/ takes a textual representation of a date (dd-mm-yyyy)
6569: and converts it to the corresponding value of type <struct/bird_clock_t/.
6570: </function>
6571: <function><p><type>void</type>
6572: <funcdef>tm_format_datetime</funcdef>
6573: (<type>char *</type> <param>x</param>, <type>struct timeformat *</type> <param>fmt_spec</param>, <type>bird_clock_t</type> <param>t</param>) -- convert date and time to textual representation
6574:
6575: <funcsect>Arguments
6576: <p><descrip>
6577: <tagp><type>char *</type> <param>x</param></tagp>
6578: destination buffer of size <const/TM_DATETIME_BUFFER_SIZE/
6579: <tagp><type>struct timeformat *</type> <param>fmt_spec</param></tagp>
6580: specification of resulting textual representation of the time
6581: <tagp><type>bird_clock_t</type> <param>t</param></tagp>
6582: time
6583: </descrip>
6584: <funcsect>Description
6585: <p>
6586: This function formats the given relative time value <param/t/ to a textual
6587: date/time representation (dd-mm-yyyy hh:mm:ss) in real time.
6588: </function>
6589: <sect>Sockets
6590: <p>
6591: <p>
6592: Socket resources represent network connections. Their data structure (<struct/socket/)
6593: contains a lot of fields defining the exact type of the socket, the local and
6594: remote addresses and ports, pointers to socket buffers and finally pointers to
6595: hook functions to be called when new data have arrived to the receive buffer
6596: (<param/rx_hook/), when the contents of the transmit buffer have been transmitted
6597: (<param/tx_hook/) and when an error or connection close occurs (<param/err_hook/).
6598: <p>
6599: Freeing of sockets from inside socket hooks is perfectly safe.
6600:
6601:
6602: <function><p><type>int</type>
6603: <funcdef>sk_setup_multicast</funcdef>
6604: (<type>sock *</type> <param>s</param>) -- enable multicast for given socket
6605:
6606: <funcsect>Arguments
6607: <p><descrip>
6608: <tagp><type>sock *</type> <param>s</param></tagp>
6609: socket
6610: </descrip>
6611: <funcsect>Description
6612: <p>
6613: Prepare transmission of multicast packets for given datagram socket.
6614: The socket must have defined <param/iface/.
6615: <funcsect>Result
6616: <p>
6617: 0 for success, -1 for an error.
6618: </function>
6619: <function><p><type>int</type>
6620: <funcdef>sk_join_group</funcdef>
6621: (<type>sock *</type> <param>s</param>, <type>ip_addr</type> <param>maddr</param>) -- join multicast group for given socket
6622:
6623: <funcsect>Arguments
6624: <p><descrip>
6625: <tagp><type>sock *</type> <param>s</param></tagp>
6626: socket
6627: <tagp><type>ip_addr</type> <param>maddr</param></tagp>
6628: multicast address
6629: </descrip>
6630: <funcsect>Description
6631: <p>
6632: Join multicast group for given datagram socket and associated interface.
6633: The socket must have defined <param/iface/.
6634: <funcsect>Result
6635: <p>
6636: 0 for success, -1 for an error.
6637: </function>
6638: <function><p><type>int</type>
6639: <funcdef>sk_leave_group</funcdef>
6640: (<type>sock *</type> <param>s</param>, <type>ip_addr</type> <param>maddr</param>) -- leave multicast group for given socket
6641:
6642: <funcsect>Arguments
6643: <p><descrip>
6644: <tagp><type>sock *</type> <param>s</param></tagp>
6645: socket
6646: <tagp><type>ip_addr</type> <param>maddr</param></tagp>
6647: multicast address
6648: </descrip>
6649: <funcsect>Description
6650: <p>
6651: Leave multicast group for given datagram socket and associated interface.
6652: The socket must have defined <param/iface/.
6653: <funcsect>Result
6654: <p>
6655: 0 for success, -1 for an error.
6656: </function>
6657: <function><p><type>int</type>
6658: <funcdef>sk_setup_broadcast</funcdef>
6659: (<type>sock *</type> <param>s</param>) -- enable broadcast for given socket
6660:
6661: <funcsect>Arguments
6662: <p><descrip>
6663: <tagp><type>sock *</type> <param>s</param></tagp>
6664: socket
6665: </descrip>
6666: <funcsect>Description
6667: <p>
6668: Allow reception and transmission of broadcast packets for given datagram
6669: socket. The socket must have defined <param/iface/. For transmission, packets should
6670: be send to <param/brd/ address of <param/iface/.
6671: <funcsect>Result
6672: <p>
6673: 0 for success, -1 for an error.
6674: </function>
6675: <function><p><type>int</type>
6676: <funcdef>sk_set_ttl</funcdef>
6677: (<type>sock *</type> <param>s</param>, <type>int</type> <param>ttl</param>) -- set transmit TTL for given socket
6678:
6679: <funcsect>Arguments
6680: <p><descrip>
6681: <tagp><type>sock *</type> <param>s</param></tagp>
6682: socket
6683: <tagp><type>int</type> <param>ttl</param></tagp>
6684: TTL value
6685: </descrip>
6686: <funcsect>Description
6687: <p>
6688: Set TTL for already opened connections when TTL was not set before. Useful
6689: for accepted connections when different ones should have different TTL.
6690: <funcsect>Result
6691: <p>
6692: 0 for success, -1 for an error.
6693: </function>
6694: <function><p><type>int</type>
6695: <funcdef>sk_set_min_ttl</funcdef>
6696: (<type>sock *</type> <param>s</param>, <type>int</type> <param>ttl</param>) -- set minimal accepted TTL for given socket
6697:
6698: <funcsect>Arguments
6699: <p><descrip>
6700: <tagp><type>sock *</type> <param>s</param></tagp>
6701: socket
6702: <tagp><type>int</type> <param>ttl</param></tagp>
6703: TTL value
6704: </descrip>
6705: <funcsect>Description
6706: <p>
6707: Set minimal accepted TTL for given socket. Can be used for TTL security.
6708: implementations.
6709: <funcsect>Result
6710: <p>
6711: 0 for success, -1 for an error.
6712: </function>
6713: <function><p><type>int</type>
6714: <funcdef>sk_set_md5_auth</funcdef>
6715: (<type>sock *</type> <param>s</param>, <type>ip_addr</type> <param>local</param>, <type>ip_addr</type> <param>remote</param>, <type>struct iface *</type> <param>ifa</param>, <type>char *</type> <param>passwd</param>, <type>int</type> <param>setkey</param>) -- add / remove MD5 security association for given socket
6716:
6717: <funcsect>Arguments
6718: <p><descrip>
6719: <tagp><type>sock *</type> <param>s</param></tagp>
6720: socket
6721: <tagp><type>ip_addr</type> <param>local</param></tagp>
6722: IP address of local side
6723: <tagp><type>ip_addr</type> <param>remote</param></tagp>
6724: IP address of remote side
6725: <tagp><type>struct iface *</type> <param>ifa</param></tagp>
6726: Interface for link-local IP address
6727: <tagp><type>char *</type> <param>passwd</param></tagp>
6728: Password used for MD5 authentication
6729: <tagp><type>int</type> <param>setkey</param></tagp>
6730: Update also system SA/SP database
6731: </descrip>
6732: <funcsect>Description
6733: <p>
6734: In TCP MD5 handling code in kernel, there is a set of security associations
6735: used for choosing password and other authentication parameters according to
6736: the local and remote address. This function is useful for listening socket,
6737: for active sockets it may be enough to set s->password field.
6738: <p>
6739: When called with passwd != NULL, the new pair is added,
6740: When called with passwd == NULL, the existing pair is removed.
6741: <p>
6742: Note that while in Linux, the MD5 SAs are specific to socket, in BSD they are
6743: stored in global SA/SP database (but the behavior also must be enabled on
6744: per-socket basis). In case of multiple sockets to the same neighbor, the
6745: socket-specific state must be configured for each socket while global state
6746: just once per src-dst pair. The <param/setkey/ argument controls whether the global
6747: state (SA/SP database) is also updated.
6748: <funcsect>Result
6749: <p>
6750: 0 for success, -1 for an error.
6751: </function>
6752: <function><p><type>int</type>
6753: <funcdef>sk_set_ipv6_checksum</funcdef>
6754: (<type>sock *</type> <param>s</param>, <type>int</type> <param>offset</param>) -- specify IPv6 checksum offset for given socket
6755:
6756: <funcsect>Arguments
6757: <p><descrip>
6758: <tagp><type>sock *</type> <param>s</param></tagp>
6759: socket
6760: <tagp><type>int</type> <param>offset</param></tagp>
6761: offset
6762: </descrip>
6763: <funcsect>Description
6764: <p>
6765: Specify IPv6 checksum field offset for given raw IPv6 socket. After that, the
6766: kernel will automatically fill it for outgoing packets and check it for
6767: incoming packets. Should not be used on ICMPv6 sockets, where the position is
6768: known to the kernel.
6769: <funcsect>Result
6770: <p>
6771: 0 for success, -1 for an error.
6772: </function>
6773: <function><p><type>sock *</type>
6774: <funcdef>sock_new</funcdef>
6775: (<type>pool *</type> <param>p</param>) -- create a socket
6776:
6777: <funcsect>Arguments
6778: <p><descrip>
6779: <tagp><type>pool *</type> <param>p</param></tagp>
6780: pool
6781: </descrip>
6782: <funcsect>Description
6783: <p>
6784: This function creates a new socket resource. If you want to use it,
6785: you need to fill in all the required fields of the structure and
6786: call <func/sk_open()/ to do the actual opening of the socket.
6787: <p>
6788: The real function name is <func/sock_new()/, <func/sk_new()/ is a macro wrapper
6789: to avoid collision with OpenSSL.
6790: </function>
6791: <function><p><type>int</type>
6792: <funcdef>sk_open</funcdef>
6793: (<type>sock *</type> <param>s</param>) -- open a socket
6794:
6795: <funcsect>Arguments
6796: <p><descrip>
6797: <tagp><type>sock *</type> <param>s</param></tagp>
6798: socket
6799: </descrip>
6800: <funcsect>Description
6801: <p>
6802: This function takes a socket resource created by <func/sk_new()/ and
6803: initialized by the user and binds a corresponding network connection
6804: to it.
6805: <funcsect>Result
6806: <p>
6807: 0 for success, -1 for an error.
6808: </function>
6809: <function><p><type>int</type>
6810: <funcdef>sk_send</funcdef>
6811: (<type>sock *</type> <param>s</param>, <type>unsigned</type> <param>len</param>) -- send data to a socket
6812:
6813: <funcsect>Arguments
6814: <p><descrip>
6815: <tagp><type>sock *</type> <param>s</param></tagp>
6816: socket
6817: <tagp><type>unsigned</type> <param>len</param></tagp>
6818: number of bytes to send
6819: </descrip>
6820: <funcsect>Description
6821: <p>
6822: This function sends <param/len/ bytes of data prepared in the
6823: transmit buffer of the socket <param/s/ to the network connection.
6824: If the packet can be sent immediately, it does so and returns
6825: 1, else it queues the packet for later processing, returns 0
6826: and calls the <param/tx_hook/ of the socket when the tranmission
6827: takes place.
6828: </function>
6829: <function><p><type>int</type>
6830: <funcdef>sk_send_to</funcdef>
6831: (<type>sock *</type> <param>s</param>, <type>unsigned</type> <param>len</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>port</param>) -- send data to a specific destination
6832:
6833: <funcsect>Arguments
6834: <p><descrip>
6835: <tagp><type>sock *</type> <param>s</param></tagp>
6836: socket
6837: <tagp><type>unsigned</type> <param>len</param></tagp>
6838: number of bytes to send
6839: <tagp><type>ip_addr</type> <param>addr</param></tagp>
6840: IP address to send the packet to
6841: <tagp><type>unsigned</type> <param>port</param></tagp>
6842: port to send the packet to
6843: </descrip>
6844: <funcsect>Description
6845: <p>
6846: This is a <func/sk_send()/ replacement for connection-less packet sockets
6847: which allows destination of the packet to be chosen dynamically.
6848: Raw IP sockets should use 0 for <param/port/.
6849: </function>
6850: <function><p><type>void</type>
6851: <funcdef>io_log_event</funcdef>
6852: (<type>void *</type> <param>hook</param>, <type>void *</type> <param>data</param>) -- mark approaching event into event log
6853:
6854: <funcsect>Arguments
6855: <p><descrip>
6856: <tagp><type>void *</type> <param>hook</param></tagp>
6857: event hook address
6858: <tagp><type>void *</type> <param>data</param></tagp>
6859: event data address
6860: </descrip>
6861: <funcsect>Description
6862: <p>
6863: Store info (hook, data, timestamp) about the following internal event into
6864: a circular event log (<param/event_log/). When latency tracking is enabled, the log
6865: entry is kept open (in <param/event_open/) so the duration can be filled later.
6866: </function>
6867:
6868: </book>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog.sgml CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird2 / doc